TenantAtlas/specs/309-rbac-role-matrix-access-boundary-audit/spec.md

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.