# Feature Specification: RBAC Role Matrix & Access Boundary Audit **Feature Branch**: `309-rbac-role-matrix-access-boundary-audit` **Created**: 2026-05-15 **Status**: Ready for implementation **Input**: User-provided Spec 309 draft: "RBAC Role Matrix & Access Boundary Audit" ## Spec Candidate Check *(mandatory - SPEC-GATE-001)* - **Problem**: TenantPilot is becoming a governance-of-record platform, but repo analysis shows a possible security-boundary contradiction: the Constitution says Manager must not manage tenant memberships, while the current role capability map appears to grant Manager-level membership-management authority. - **Today's failure**: The product may present deterministic workspace and managed-environment isolation while runtime capability maps, panel access, policies, and direct routes disagree. That can create privilege escalation, workspace/environment leakage, provider credential exposure, or customer-visible review artifact access outside intended scope. - **User-visible improvement**: Operators and reviewers can trust that workspace isolation, managed-environment isolation, capability checks, and panel boundaries agree server-side. Sensitive membership, provider, review, review-pack, accepted-risk, and operation surfaces are proven by direct tests rather than navigation visibility. - **Smallest enterprise-capable version**: Run an audit-first repo verification over the existing capability registry, role maps, panel providers, workspace context, policies, resources, and tests; add focused failing tests for confirmed contradictions; apply only minimal corrections to existing role maps, policies, panel access, or Filament visibility after server-side proof. - **Explicit non-goals**: No new RBAC model, no new role family, no permission UI, no identity federation, no SCIM, no support impersonation redesign, no billing lifecycle work, no navigation cleanup, no route-family redesign, no migrations by default, no customer portal work, and no broad policy framework. - **Permanent complexity imported**: Focused Unit/Feature tests and possibly small edits to existing capability maps, policies, panel access, or visibility helpers. No new table, persisted entity, enum/status family, capability registry architecture, frontend asset, or public abstraction. - **Why now**: The roadmap prioritizes customer-safe review/productization, but RBAC ambiguity is a foundation risk. Spec 309 reduces security and trust risk before additional customer-facing governance surfaces are built on top. - **Why not local**: The suspected contradiction spans `WorkspaceRoleCapabilityMap`, Constitution role semantics, `User::canAccessPanel()`, panel middleware, policies, and existing tests. A local patch to one resource would not prove the boundary. - **Approval class**: Core Enterprise - **Red flags triggered**: Cross-surface authorization audit and broad test matrix. Defense: this is a security-boundary verification pass, not a new framework; all work reuses existing capability/policy/gate infrastructure and fixes only confirmed contradictions. - **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12** - **Decision**: approve ## Spec Scope Fields *(mandatory)* - **Scope**: workspace - **Primary Routes**: - `/admin` - `/admin/login` - workspace and managed-environment admin surfaces under the existing Admin panel - existing environment-scoped resource routes for Provider Connections, Environment Reviews, Review Packs, Evidence, Finding Exceptions, and Operation Runs - `/system` - representative `/system/*` pages and operation-detail routes - **Data Ownership**: - No new persisted data. - `workspace_memberships` remains the workspace role source. - `managed_environment_memberships` remains an access-scope/membership surface as currently implemented; this spec audits whether any remaining role-bearing or owner-only authority contradicts the Constitution. - Provider Connections, Environment Reviews, Review Packs, Evidence, Finding Exceptions, Stored Reports, and tenant-bound OperationRuns must remain workspace + managed-environment scoped. - Workspace-bound OperationRuns may remain workspace-only, but tenant-bound runs must still enforce environment entitlement before capability checks. - **RBAC**: - Workspace membership is the first isolation boundary. - Managed-environment entitlement is the second isolation boundary. - Capability/policy authorization is third. - UI visibility is last and never the security boundary. - Non-member or out-of-scope access must deny as not found (`404`) where repo policy semantics already use boundary hiding. - In-scope members missing a capability must receive `403` where policies define capability denial. This is not a canonical-view spec. No new default filter behavior is introduced. ## Cross-Cutting / Shared Pattern Reuse *(mandatory)* - **Cross-cutting feature?**: yes. - **Interaction class(es)**: RBAC capability resolution, panel access, route authorization, Filament resource/page access, action authorization, global search safety, operation drilldown links, provider credential actions, review/export/download access, and accepted-risk lifecycle actions. - **Systems touched**: - `apps/platform/app/Support/Auth/Capabilities.php` - `apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php` - `apps/platform/app/Services/Auth/RoleCapabilityMap.php` - `apps/platform/app/Providers/AuthServiceProvider.php` - `apps/platform/app/Models/User.php` - `apps/platform/app/Providers/Filament/AdminPanelProvider.php` - `apps/platform/app/Providers/Filament/SystemPanelProvider.php` - `apps/platform/app/Support/Workspaces/WorkspaceContext.php` - `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php` - relevant policies/resources/pages for ProviderConnection, EnvironmentReview, ReviewPack, EvidenceSnapshot, StoredReport, FindingException, and OperationRun. - **Existing pattern(s) to extend**: capability registry constants, `WorkspaceCapabilityResolver`, `CapabilityResolver`, `ManagedEnvironmentAccessScopeResolver`, model policies, Gate definitions, Filament `canAccess()` / `canViewAny()` / policy checks, existing cross-plane middleware, and existing 404/403 semantics. - **Shared contract / presenter / builder / renderer to reuse**: Existing capability/policy/gate infrastructure only. Do not introduce a new RBAC abstraction. - **Why the existing shared path is sufficient or insufficient**: The repo already has a central capability registry and role maps. The issue is whether current mappings, panels, policies, and tests agree with the Constitution, not absence of infrastructure. - **Allowed deviation and why**: None planned. If implementation discovers that a minimal helper is required to remove duplicated direct checks, it must be private, narrow, and justified in close-out. - **Consistency impact**: Role maps, policies, direct URLs, Filament action execution, global search, operation links, and panel guards must all derive the same outcome for the same actor/workspace/environment/capability tuple. - **Review focus**: Block UI-only security, raw role-string checks, direct route bypasses, cross-plane access, Manager/Operator/Readonly owner-only grants, and speculative RBAC redesign. ## OperationRun UX Impact *(mandatory)* - **Touches OperationRun start/completion/link UX?**: yes, authorization only. - **Shared OperationRun UX contract/layer reused**: `OperationRunPolicy`, `OperationRunCapabilityResolver`, `OperationRunLinks`, and existing Monitoring/Operations route helpers. - **Delegated start/completion UX behaviors**: Existing operation start/link/display UX remains unchanged; this spec verifies that run visibility and action capability checks remain scope-safe. - **Local surface-owned behavior that remains**: No new operation UI. Any touched action keeps its existing initiation input and feedback path. - **Queued DB-notification policy**: N/A. - **Terminal notification path**: Existing central lifecycle mechanism. - **Exception required?**: none. ## Provider Boundary / Platform Core Check *(mandatory)* - **Shared provider/platform boundary touched?**: yes, provider credential access is audited. - **Boundary classification**: mixed. ProviderConnection records are platform-core integration records bound to a workspace and managed environment; provider credential operations remain high-privilege provider-owned behavior. - **Seams affected**: ProviderConnection policies/resources/actions, provider management capabilities, dedicated credential actions, verification/start surfaces. - **Neutral platform terms preserved or introduced**: provider connection, provider credential, managed environment, workspace, operation. - **Provider-specific semantics retained and why**: Existing Microsoft/Intune specifics remain inside provider connection and Graph-facing code; this spec does not introduce provider-specific platform terminology. - **Why this does not deepen provider coupling accidentally**: The audit checks access boundaries only and does not add provider contracts, endpoints, or provider taxonomy. - **Follow-up path**: Support Access Governance remains separate; provider capability registry redesign is out of scope. ## UI / Surface Guardrail Impact *(mandatory)* No new operator-facing surface is introduced. UI changes are allowed only after server-side authorization is correct and only to align visibility/disabled state with existing policy outcomes. | Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note | |---|---|---|---|---|---|---| | Admin panel access boundary | no new surface | Existing Filament panel | panel access, workspace context | middleware, panel gate, route | no | direct URL behavior must be tested | | System panel access boundary | no new surface | Existing Filament system panel | cross-plane access | guard, middleware, panel auth | no | ordinary workspace users must not access `/system` | | Existing resource/actions visibility | possible minor alignment only | Native Filament resources/actions | action execution and visibility | action policy, page access | no | visibility follows server-side policy | ## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)* N/A - this spec does not create or materially redesign an operator-facing surface. Existing surfaces remain decision-owned by their current resources/pages. ## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)* N/A - no customer-facing content or disclosure hierarchy changes. Existing raw/support diagnostics must remain capability-gated or hidden according to current policies. ## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)* N/A - no new or redesigned list/detail/workbench surface. Existing Filament v5 action rules still apply to any touched resource/action: destructive actions require `->requiresConfirmation()` and server-side authorization. ## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)* N/A - no new operator surface contract. Direct access/action tests are the proof mechanism for this spec. ## Proportionality Review *(mandatory when structural complexity is introduced)* - **New source of truth?**: no. - **New persisted entity/table/artifact?**: no. - **New abstraction?**: no planned abstraction. - **New enum/state/reason family?**: no. - **New cross-domain UI framework/taxonomy?**: no. - **Current operator problem**: possible mismatch between role/capability truth, Constitution semantics, panel access, and direct route/action authorization. - **Existing structure is insufficient because**: it may contain incorrect grants or missing policy checks; the structure itself is sufficient if corrected and tested. - **Narrowest correct implementation**: inventory, classify, write focused tests, and adjust only existing maps/policies/panel checks where repo truth confirms a bug. - **Ownership cost**: focused RBAC boundary tests and close-out inventory. - **Alternative intentionally rejected**: new permission framework or role model. That would import complexity without being required for this security audit. - **Release truth**: current-release trust and security boundary hardening. ### Compatibility posture The product is pre-production. Compatibility shims, legacy capability aliases, dual-read logic, and data migrations are out of scope unless a repo-verified security blocker cannot be represented by the current role/capability model. ## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* - **Test purpose / classification**: Unit and Feature. Browser is not required unless direct panel/action behavior cannot be proven by Feature/Filament tests. - **Validation lane(s)**: confidence for RBAC/panel/policy tests; optional browser only for unprovable rendered panel interaction. - **Why this classification and these lanes are sufficient**: Static role-map tests prove deterministic grants. Feature tests prove direct URLs, policies, action execution, and cross-scope denial. Browser smoke is unnecessary when Feature/Livewire tests prove direct route/action boundaries. - **New or expanded test families**: `apps/platform/tests/Unit/Auth/WorkspaceRoleCapabilityMapTest.php` and focused `apps/platform/tests/Feature/Rbac/*BoundaryTest.php` files or repo-real equivalents. - **Fixture / helper cost impact**: moderate and feature-local. Tests need users, workspace memberships, managed environments, environment-scope rows, ProviderConnections, ReviewPacks, EnvironmentReviews, FindingExceptions, OperationRuns, and platform users. Shared helper defaults must stay cheap. - **Heavy-family visibility / justification**: none expected. - **Special surface test profile**: standard-native-filament and access-boundary feature tests. - **Standard-native relief or required special coverage**: feature tests are preferred over browser smoke for panel boundaries and policies. - **Reviewer handoff**: Confirm 404 vs 403 semantics, direct route/action proof, no UI-only security, no new RBAC model, no assets, no migrations, and no broadened test defaults. - **Budget / baseline / trend impact**: low to moderate focused confidence-lane growth; no heavy-governance family. - **Escalation needed**: none unless implementation discovers a structural RBAC model gap. - **Active feature PR close-out entry**: RBAC Inventory / Boundary Proof / Remaining Decisions. - **Planned validation commands**: - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceRoleCapabilityMapTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/WorkspaceRoleCapabilityBoundaryTest.php tests/Feature/Rbac/AdminPanelAccessBoundaryTest.php tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/ManagedEnvironmentAccessBoundaryTest.php tests/Feature/Rbac/ProviderConnectionAccessBoundaryTest.php tests/Feature/Rbac/ReviewPackAccessBoundaryTest.php tests/Feature/Rbac/OperationRunAccessBoundaryTest.php tests/Feature/Rbac/FindingExceptionLifecycleAccessBoundaryTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/ReviewPack/ReviewPackRbacTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php` - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - `git diff --check` ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Role Matrix Truth Is Audited (Priority: P1) As a platform maintainer, I need a repo-derived inventory of roles and capabilities so owner-only contradictions can be identified before new customer-facing governance surfaces are built. **Why this priority**: This is the trigger for the spec and the prerequisite for deciding whether runtime behavior should change. **Independent Test**: A focused role-map test can prove whether Owner, Manager, Operator, Readonly, and Platform/System grants match the intended sensitive-boundary matrix. **Acceptance Scenarios**: 1. **Given** the current capability registry and role maps, **When** the implementation inventories all role grants, **Then** the close-out lists each sensitive grant, match/mismatch classification, and action. 2. **Given** the Constitution says Manager must not manage tenant memberships, **When** the role map grants Manager membership-management capability, **Then** the mismatch is either fixed as a confirmed bug or explicitly recorded as product-decision-needed. --- ### User Story 2 - Panel And Scope Boundaries Are Proven Directly (Priority: P1) As a security reviewer, I need direct URL proof for `/admin`, `/system`, workspace isolation, and managed-environment isolation so hidden navigation cannot be mistaken for security. **Why this priority**: Panel and scope bypasses would be security blockers. **Independent Test**: Feature tests can authenticate ordinary workspace users, platform users, non-members, wrong-workspace members, and wrong-environment members, then assert direct URLs/actions return the repo-standard denial. **Acceptance Scenarios**: 1. **Given** an ordinary workspace user, **When** they request `/system`, **Then** the system returns deny-as-not-found and no system content is visible. 2. **Given** a user without valid workspace authority, **When** they request direct `/admin` workspace surfaces, **Then** access is denied by authentication/workspace middleware or policy, not only hidden navigation. 3. **Given** a member of workspace A, **When** they request workspace B review packs, findings, provider connections, or operation runs, **Then** the response denies as not found. 4. **Given** a member scoped to environment A, **When** they request environment B records in the same workspace, **Then** the response denies as not found before capability checks. --- ### User Story 3 - Sensitive Actions Are Server-Side Gated (Priority: P2) As an enterprise operator, I need sensitive membership, provider credential, review/review-pack, accepted-risk, and operation actions to be impossible for unauthorized roles even through direct action execution. **Why this priority**: Mutation boundaries are higher risk than read-only view boundaries, and UI visibility is explicitly not a security boundary. **Independent Test**: Filament/Livewire Feature tests and policy tests can call representative actions directly and assert non-owner or missing-capability actors are denied. **Acceptance Scenarios**: 1. **Given** a Manager/Operator/Readonly actor, **When** they attempt owner-only membership management, **Then** the server denies execution. 2. **Given** a Manager/Operator actor without high-privilege provider authority, **When** they attempt provider credential rotation/delete/dedicated credential management, **Then** the server denies execution. 3. **Given** a Readonly actor, **When** they attempt finding exception approval/rejection, review publication/archive/export mutation, review-pack mutation, or operation action, **Then** the server denies execution. 4. **Given** an Owner or allowed role, **When** they perform existing allowed flows covered by regression tests, **Then** the flow still works. ## Edge Cases - A user has workspace membership but no current workspace context. - A user has workspace membership but a stale remembered managed-environment context. - A user has platform/system authority but no workspace membership. - A user has both web and platform sessions; cross-plane session separation must still hide the other plane. - A record has a workspace_id / managed_environment_id mismatch. - An OperationRun is workspace-bound with no managed_environment_id. - An OperationRun is tenant-bound but its environment is deleted or outside the current workspace. - A Filament URL-only action is navigation-only; confirmation behavior must not be assumed unless the action executes via `->action(...)`. - A resource is globally searchable but lacks an Edit/View page; global search must be disabled or the page must exist. ## Functional Requirements *(mandatory)* - **FR-001 Role Map Inventory**: Implementation MUST produce a repo-derived inventory of all roles and assigned capabilities, including Owner, Manager, Operator, Readonly, Platform/System, and any repo-real special roles. - **FR-002 Constitution Alignment**: Implementation MUST compare Constitution RBAC statements against runtime mappings and classify mismatches as confirmed bug, intentional product decision, docs/constitution drift, unclear/product-decision-needed, or out of scope. - **FR-003 Owner-only Enforcement**: Confirmed owner-only capabilities MUST NOT be granted to Manager, Operator, Readonly, or customer-safe actors. - **FR-004 Admin Panel Boundary Enforcement**: Direct access to `/admin` surfaces MUST be tested. `User::canAccessPanel()` MUST NOT be the only boundary when it is permissive. - **FR-005 System Panel Boundary Enforcement**: Direct access to `/system` MUST be tested. Ordinary workspace users MUST NOT access the System panel through workspace roles. - **FR-006 Workspace Isolation**: Cross-workspace direct access MUST be denied for at least Environment Review, Review Pack, FindingException or decision surface, OperationRun, and ProviderConnection or equivalent sensitive resource. - **FR-007 Managed Environment Isolation**: Same-workspace wrong-environment direct access MUST be denied for at least Review/ReviewPack, Evidence or StoredReport, FindingException, and OperationRun. - **FR-008 Provider Connection Boundary**: ProviderConnection view/manage/verify/update/delete/dedicated-credential capabilities MUST match the target role model and be proven server-side. - **FR-009 Review / Review Pack Boundary**: Customer-safe review and review-pack surfaces MUST preserve existing access rules, redaction, and no hidden environment leakage in summaries, counts, exports, or download URLs. - **FR-010 FindingException / Decision Boundary**: Approval, rejection, renewal, revocation, closure, and accepted-risk lifecycle actions MUST be capability-gated server-side. - **FR-011 OperationRun Boundary**: OperationRun visibility and action permissions MUST be workspace/environment scope-safe; run links MUST NOT grant access to users who cannot view the underlying run. - **FR-012 Service-level Authorization**: Critical mutation paths MUST be checked for policy/gate enforcement beyond hidden UI actions. - **FR-013 No New RBAC System**: Implementation MUST reuse existing capabilities, policies, gates, middleware, and resource checks. - **FR-014 Close-out Inventory Format**: Close-out MUST include `Role -> Capabilities -> Sensitive? -> Matches target? -> Action`. ## Non-Functional Requirements - **NFR-001 Minimality**: Fix only confirmed contradictions and direct boundary bugs. - **NFR-002 Auditability**: Sensitive access decisions must be explainable by role, capability, workspace, environment, and policy. - **NFR-003 Determinism**: Same user, workspace, environment, and capability set must always produce the same authorization outcome. - **NFR-004 Testability**: Each corrected boundary must have focused Unit or Feature coverage. - **NFR-005 No UI-only Security**: Navigation visibility, hidden actions, and disabled actions are insufficient proof. - **NFR-006 No New Assets**: No CSS, JS, Vite, or design-system changes. - **NFR-007 No Migration By Default**: Stop and document if a migration appears necessary. ## Security Requirements - **SEC-001**: Workspace isolation is mandatory for all workspace-owned records. - **SEC-002**: Managed-environment isolation is mandatory for all environment-owned records. - **SEC-003**: Panel access must be enforced server-side. - **SEC-004**: Membership management must be Owner-only unless a repo/product decision explicitly says otherwise. - **SEC-005**: Provider credential-level operations must be high privilege only. - **SEC-006**: Readonly/customer-safe users must not mutate anything. - **SEC-007**: Platform/system users must not implicitly access customer workspace data through system authority. - **SEC-008**: Direct URLs to denied objects must follow repo-standard denial semantics: `404` for non-member/out-of-scope and `403` for in-scope missing capability where existing policies define it. - **SEC-009**: No test may rely only on navigation invisibility. ## Repo Evidence Anchors Initial preparation found these repo-real paths: | Area | Repo-real path | Preparation note | |---|---|---| | Capability registry | `apps/platform/app/Support/Auth/Capabilities.php` | Canonical tenant/workspace capability names | | Workspace role map | `apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php` | User draft said `Support/Auth`; repo path is `Services/Auth` | | Managed-environment role map | `apps/platform/app/Services/Auth/RoleCapabilityMap.php` | Current tenant-role capabilities | | Workspace roles | `apps/platform/app/Support/Auth/WorkspaceRole.php` | Owner, Manager, Operator, Readonly | | Tenant roles | `apps/platform/app/Support/TenantRole.php` | Owner, Manager, Operator, Readonly | | Platform capabilities | `apps/platform/app/Support/Auth/PlatformCapabilities.php` | System panel capabilities | | Auth/provider wiring | `apps/platform/app/Providers/AuthServiceProvider.php` | Gate and policy registration | | User panel access | `apps/platform/app/Models/User.php` | `canAccessPanel()` currently returns true | | Admin panel | `apps/platform/app/Providers/Filament/AdminPanelProvider.php` | `/admin`, web guard, workspace/environment middleware | | System panel | `apps/platform/app/Providers/Filament/SystemPanelProvider.php` | `/system`, platform guard, platform capability middleware | | Provider registration | `apps/platform/bootstrap/providers.php` | Laravel 12 provider registration location | | Workspace context | `apps/platform/app/Support/Workspaces/WorkspaceContext.php` | Workspace session/context enforcement | | Environment routes | `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php` | Managed-environment scoped URL model | | OperationRun policy | `apps/platform/app/Policies/OperationRunPolicy.php` | Workspace/environment/run access | | ProviderConnection policy | `apps/platform/app/Policies/ProviderConnectionPolicy.php` | Provider credential/scope boundary | | Review policy | `apps/platform/app/Policies/EnvironmentReviewPolicy.php` | Review access/mutation | | ReviewPack policy | `apps/platform/app/Policies/ReviewPackPolicy.php` | Review pack access/mutation | | Evidence policy | `apps/platform/app/Policies/EvidenceSnapshotPolicy.php` | Evidence access/mutation | | FindingException policy | `apps/platform/app/Policies/FindingExceptionPolicy.php` | Accepted-risk/decision lifecycle | | Constitution | `.specify/memory/constitution.md` | RBAC-UX owner-only and cross-plane rules | ## Initial Repo-Derived Inventory Snapshot This preparation did not implement changes, but read-only inspection found: - `WorkspaceRoleCapabilityMap` grants Owner `WORKSPACE_MEMBERSHIP_MANAGE` and `TENANT_MEMBERSHIP_MANAGE` through merged tenant-role capabilities. - `WorkspaceRoleCapabilityMap` grants Manager `WORKSPACE_MEMBERSHIP_MANAGE` directly and appends `TENANT_MEMBERSHIP_MANAGE` in `getCapabilities()`. - `RoleCapabilityMap` grants tenant Manager provider manage, review pack manage, environment review manage, evidence manage, and many governance mutation capabilities, while it does not grant `TENANT_ROLE_MAPPING_MANAGE`. - Operator has operational and read scopes but no `TENANT_MEMBERSHIP_MANAGE`, `TENANT_MANAGE`, `PROVIDER_MANAGE`, or `TENANT_BACKUP_SCHEDULES_MANAGE`. - Readonly has view-only provider/review/evidence/audit-style capabilities and no mutation capabilities from the inspected map. - Platform users are separate `PlatformUser` records using the `platform` guard and `PlatformCapabilities`. - Existing system-panel tests already prove several tenant-session-to-`/system` denials, but Spec 309 should add/extend focused boundary tests for the current risk matrix. ## Suspected Contradictions To Verify - Manager membership-management grant appears to contradict the Constitution line: "Manager ... MUST NOT manage tenant memberships (Owner-only)." - `User::canAccessPanel()` returning true may be acceptable only if admin/system middleware, guards, workspace context, and policies definitively enforce access. Implementation must prove this before changing it. - Existing tests currently assert Manager can manage tenant membership in `apps/platform/tests/Unit/Auth/CapabilityResolverTest.php` and `apps/platform/tests/Feature/Rbac/RoleMatrix/ManagerAccessTest.php`; if Owner-only is confirmed, those tests must be updated as failing proof before runtime fix. - Provider manage and credential-level capabilities for Manager may be intentional or too broad; classify before changing. - Review/ReviewPack/Evidence manage capabilities for Manager may be intentional governance workflow authority; classify before changing. - FindingException approval via workspace capability currently grants Owner and Manager from the inspected map; classify whether Manager approval is intended. ## Acceptance Criteria - **AC-001 Role Inventory Produced**: Close-out includes a role/capability inventory for Owner, Manager, Operator, Readonly, Platform/System, and repo-real special roles. - **AC-002 Owner-only Contradictions Resolved Or Classified**: Manager/Operator grants of owner-only membership-management capability are fixed or explicitly classified. - **AC-003 Admin Panel Boundary Tested**: Tests prove users without valid admin/workspace authority cannot access `/admin` surfaces through direct URLs. - **AC-004 System Panel Boundary Tested**: Tests prove ordinary workspace users cannot access `/system`. - **AC-005 Workspace Isolation Tested**: Cross-workspace direct access is denied for EnvironmentReview, ReviewPack, FindingException or decision surface, OperationRun, and ProviderConnection/equivalent. - **AC-006 Managed Environment Isolation Tested**: Same-workspace wrong-environment direct access is denied for Review/ReviewPack, Evidence or StoredReport, FindingException, and OperationRun. - **AC-007 Sensitive Actions Tested**: At least one sensitive action from each group is tested against unauthorized roles: membership management, provider credential management, review/review-pack mutation, accepted-risk lifecycle mutation, and operation action/view. - **AC-008 UI Visibility Is Not The Only Guard**: Every fixed sensitive action has a direct server-side access/action test. - **AC-009 No Broad RBAC Redesign**: No new role model, table, public permission framework, or capability registry redesign is introduced. - **AC-010 Focused Tests Pass**: Focused RBAC/panel/access-boundary tests pass. - **AC-011 Existing Product Flows Still Work**: Existing Review, Review Pack, Findings, and OperationRun scenarios covered by regression tests still pass for Owner and allowed Manager/Operator roles. - **AC-012 Filament v5 Contract Preserved**: Filament remains v5 with Livewire v4; provider registration remains in `apps/platform/bootstrap/providers.php`; no new assets are introduced; deploy continues to include the existing Filament asset publication step where registered assets are used. ## Assumptions - Spec 308 is merged or cleanly separated before implementation. - The product remains pre-production, so removing incorrect capability grants does not require data migration shims. - Existing capability names remain canonical; no new capability strings are introduced unless implementation proves an existing owner-only capability cannot express the boundary. - Browser tests are optional and only needed if Feature/Filament tests cannot prove a panel or action boundary. ## Risks - Removing Manager membership authority may break existing tests and workflows that assumed Manager could manage memberships. - Constitution may be newer than current product intent; unclear cases must be product-decision-needed instead of silently fixed. - Tightening `canAccessPanel()` without understanding workspace-selection flow could block legitimate login/chooser flows. - Provider/manage and review/manage authority may be too broad for this spec if the repo treats them as product decisions. - Adding broad fixtures could worsen test-suite cost; keep RBAC tests focused and helper setup opt-in. ## Open Questions - Can Manager manage workspace membership? Recommended default: no. - Can Manager manage managed-environment membership/access scope? Recommended default: no unless product explicitly approves partial scope management. - Can Manager rotate or delete provider credentials? Recommended default: no. - Can Manager approve accepted risks? Recommended default: existing policy unless unsafe, but classify. - Can Readonly download Review Packs? Recommended default: capability-gated according to existing review-pack policy. - Should `User::canAccessPanel()` be restrictive? Recommended default: restrictive where it does not break workspace selection, with middleware/policies still enforcing fine-grained boundaries. - Can platform/system users access workspace data? Recommended default: no implicit access; support access governance stays separate. ## Candidate Selection Rationale - **Selected candidate**: `309 - RBAC Role Matrix & Access Boundary Audit`. - **Source locations**: - explicit user-provided Spec 309 draft on 2026-05-15 - `.specify/memory/constitution.md` RBAC-UX rules for workspace/tenant isolation, owner-only tenant membership management, cross-plane denial, and server-side authorization - `docs/product/roadmap.md` enterprise access boundary/security hardening context - `docs/product/spec-candidates.md` enterprise access boundary/support access governance context, with support-access implementation kept out of scope - **Why selected**: The repo-read found a high-risk static mismatch between Constitution owner-only membership semantics and the current Manager grants in `WorkspaceRoleCapabilityMap`. This security-boundary warning should be verified before further customer-facing productization. - **Why close alternatives were deferred**: - Customer Review Workspace v1 Completion is deferred until RBAC/access boundaries are verified. - Product Truth / Docs Drift Reconciliation is deferred until Spec 309 distinguishes runtime truth from docs drift. - Support Access Governance v1 is deferred because it is a new support/impersonation product slice, not the minimal role-matrix audit. - **Roadmap relationship**: Foundation hardening before customer-safe governance productization. - **Smallest viable implementation slice**: inventory, classify, focused tests, minimal fixes for confirmed contradictions, and close-out decisions. ## Completed-Spec Guardrail Result Related existing specs are context only and must not be rewritten: - `specs/285-workspace-rbac-environment-access/` has implementation-completed/validated task markers and browser-smoke proof; use only as workspace-first RBAC context. - `specs/276-support-access-governance/` has completed task markers and review outcome; support access remains a follow-up, not part of 309. - `specs/301-admin-inventory-navigation-cutover/`, `specs/302-tenant-owned-surface-route-audit/`, `specs/303-admin-directory-groups-cutover/`, and `specs/304-tenant-panel-dead-code-retirement/` are completed/reviewed context for panel and route behavior. - `specs/307-decision-register-evidence-operationrun-link-polish/` and `specs/308-decision-register-summary-review-pack/` are Decision Register / Review Pack context only. - No existing `specs/309-*` package existed before this preparation. ## Follow-up Candidates - Support Access Governance v1: audited support/impersonation, TTL, reason, approval, banner, and exportable access logs. - Product Truth / Docs Drift Reconciliation: update roadmap/ledger/candidates after repo truth is confirmed. - Commercial Entitlements / Billing-State Enforcement: plan lifecycle and workspace entitlement gates. - Customer Review Workspace v1 Completion: continue customer-facing productization after security boundary verification. - Route / Panel Access Contract Audit: broader route duplication and canonical-route cleanup if 309 uncovers structural route drift. ## Implementation Done Definition Spec 309 is done when the role/capability inventory is documented, owner-only contradictions are fixed or classified, `/admin` and `/system` boundaries are tested, cross-workspace and cross-environment boundaries are tested, sensitive actions are server-side denied for unauthorized roles, no new RBAC architecture is introduced, focused tests pass, Pint dirty passes, `git diff --check` passes, and remaining product decisions are listed as follow-ups.