Authorization and RBAC (future)

Status: target, not shipped

The shipped authorization model — dual-check, hierarchy-aware, with @TargetOrgId() binding — is described in Current state → Multi-tenant hierarchy. This page covers planned evolutions.

Cross-hierarchy permission cascade

Today: A Portfolio or Partner owner can act on their descendant Brands via hierarchy membership. The cascade is single-hop and explicit per endpoint.

Target: A multi-hop cascade allows a Portfolio owner to manage Products across all descendant Brands through a single set of endpoints, with permissions enforced via hierarchy traversal.

Open:

• Hierarchy-aware permission resolution that walks the full ancestry chain, not just the immediate parent
• Dual-check evaluation that combines base permission + hierarchy-scoped permission
• UI affordances that surface descendant-scoped actions

Tracking: OpenSpec deferral D5 in openspec/current-decisions-for-future-tracking.md. No assigned ticket — revisit when a real customer workflow needs the multi-hop cascade.

OAuth2 two-step connect flow

Today: The only integration is ServiceTitan with API-key auth. Credentials are written atomically on the connect endpoint.

Target: OAuth2 vendors (Google, Salesforce, Intuit, etc.) connect via a two-step flow:

1. Initiate connect → create IntegrationInstance in PENDING state, redirect user to vendor OAuth consent
2. Complete connect → receive callback, exchange code for tokens, transition instance to CONNECTED

Open:

• A finite TTL on the intermediate PENDING state (abandoned consent flows become orphans)
• An orphan-cleanup cron — see Future state → Catalog and enablement → Orphan cleanup cron
• A vendor-specific strategy in the credential factory (the existing strategy pattern accommodates this — see Current state → Catalog and enablement → Strategy pattern)

Tracking: OpenSpec deferral D3 in openspec/current-decisions-for-future-tracking.md. Triggered when a second integration with OAuth2 is added.

Catalog admin CRUD endpoints

Today: ProductDefinition and IntegrationDefinition are seed-driven. Adding a product or integration requires a migration.

Target: Admin endpoints for catalog CRUD, gated on PLATFORM identity authority. The catalog stops being immutable-at-runtime.

Open: This evolution implicates cache invalidation and runtime availability checks as well as authorization — tracked end-to-end on Future state → Catalog and enablement → Runtime catalog.

Tracking: OpenSpec deferral D1.

Related

• Current state → Multi-tenant hierarchy — shipped authorization model
• OpenSpec deferred decisions: openspec/current-decisions-for-future-tracking.md