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

Tasks: RBAC Role Matrix & Access Boundary Audit

Input: Design documents from /specs/309-rbac-role-matrix-access-boundary-audit/
Prerequisites: spec.md, plan.md, checklists/requirements.md
Tests: Required. Use Pest 4 Unit/Feature tests; Browser only if Feature/Filament tests cannot prove the access boundary.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in Unit/Feature unless a panel interaction cannot be proven otherwise.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the changed boundaries without pulling unrelated lane cost.
• Browser coverage, if any, is explicit and justified.
• Close-out records fixed contradictions, deferred decisions, and validation results.

Phase 1: Read-Only Inventory

Purpose: Verify repo truth before any runtime or test changes.

• T001 Confirm current branch is 309-rbac-role-matrix-access-boundary-audit and working tree state is understood.
• T002 Read .specify/memory/constitution.md RBAC, workspace isolation, tenant isolation, cross-plane, and testing sections.
• T003 [P] Inspect apps/platform/app/Support/Auth/Capabilities.php and apps/platform/app/Support/Auth/PlatformCapabilities.php.
• T004 [P] Inspect apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php and apps/platform/app/Services/Auth/RoleCapabilityMap.php.
• T005 [P] Inspect apps/platform/app/Support/Auth/WorkspaceRole.php and apps/platform/app/Support/TenantRole.php.
• T006 [P] Inspect apps/platform/app/Models/User.php and apps/platform/app/Models/PlatformUser.php.
• T007 [P] Inspect apps/platform/app/Providers/AuthServiceProvider.php and apps/platform/bootstrap/providers.php.
• T008 [P] Inspect apps/platform/app/Providers/Filament/AdminPanelProvider.php and apps/platform/app/Providers/Filament/SystemPanelProvider.php.
• T009 [P] Inspect apps/platform/app/Support/Workspaces/WorkspaceContext.php and apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php.
• T010 [P] Inspect apps/platform/app/Policies/WorkspaceMembershipPolicy.php, apps/platform/app/Policies/WorkspacePolicy.php, and workspace membership Filament relation-manager surfaces.
• T011 [P] Inspect apps/platform/app/Policies/ProviderConnectionPolicy.php and provider connection resources/actions.
• T012 [P] Inspect apps/platform/app/Policies/EnvironmentReviewPolicy.php, apps/platform/app/Policies/ReviewPackPolicy.php, apps/platform/app/Policies/EvidenceSnapshotPolicy.php, and related resources/pages.
• T013 [P] Inspect apps/platform/app/Policies/FindingExceptionPolicy.php and finding exception lifecycle services/actions.
• T014 [P] Inspect apps/platform/app/Policies/OperationRunPolicy.php, apps/platform/app/Support/Operations/OperationRunCapabilityResolver.php, and operation link/view helpers.
• T015 [P] Inspect existing RBAC, panel, provider, review-pack, customer-review, finding-exception, and OperationRun authorization tests under apps/platform/tests/.
• T016 Produce a close-out-ready initial inventory table: Role -> Capabilities -> Sensitive? -> Matches target? -> Action.

Phase 2: Classification

Purpose: Decide what is a confirmed bug versus intentional product behavior or docs drift.

• T017 Classify Manager WORKSPACE_MEMBERSHIP_MANAGE grant in apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php.
• T018 Classify Manager TENANT_MEMBERSHIP_MANAGE grant appended in WorkspaceRoleCapabilityMap::getCapabilities().
• T019 Classify Manager provider manage and dedicated credential boundaries in apps/platform/app/Policies/ProviderConnectionPolicy.php.
• T020 Classify Manager review, review-pack, evidence, and finding-exception approval/manage capabilities.
• T021 Classify apps/platform/app/Models/User.php::canAccessPanel() as safe-by-middleware or a confirmed defense-in-depth gap.
• T022 Classify /system cross-plane behavior using existing system-panel tests and direct route behavior.
• T023 Identify confirmed security blockers that must be fixed in Spec 309.
• T024 Identify product-decision-needed items that must not be fixed blindly.
• T025 Identify docs-only drift and follow-up candidates outside Spec 309.
• T026 Record the minimal runtime fix list before editing application code.

Phase 3: Tests First - Role And Panel Boundaries

Purpose: Add failing or tightening proof before runtime fixes.

• T027 [P] Add or update apps/platform/tests/Unit/Auth/WorkspaceRoleCapabilityMapTest.php to assert known capabilities, unknown capability rejection, and Owner-only membership-management expectations once confirmed.
• T028 [P] Update apps/platform/tests/Unit/Auth/CapabilityResolverTest.php if Manager tenant-membership management is confirmed incorrect.
• T029 [P] Update apps/platform/tests/Feature/Rbac/RoleMatrix/ManagerAccessTest.php if Manager tenant-membership management is confirmed incorrect.
• T030 [P] Add or update apps/platform/tests/Feature/Rbac/WorkspaceRoleCapabilityBoundaryTest.php for Manager/Operator/Readonly owner-only membership denial and Owner positive coverage.
• T031 [P] Add or update apps/platform/tests/Feature/Rbac/AdminPanelAccessBoundaryTest.php to prove direct /admin workspace surfaces deny unauthenticated users, users without valid workspace authority, and wrong-plane actors.
• T032 [P] Add or update apps/platform/tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php or extend existing system tests to prove ordinary workspace users cannot access /system or representative /system/* routes.

Phase 4: Tests First - Workspace And Environment Isolation

Purpose: Prove direct object access boundaries for representative high-risk resources.

• T033 [P] Add or update apps/platform/tests/Feature/Rbac/ManagedEnvironmentAccessBoundaryTest.php for same-workspace wrong-environment denial.
• T034 [P] Add or update EnvironmentReview direct access coverage in apps/platform/tests/Feature/Rbac/ManagedEnvironmentAccessBoundaryTest.php or an existing EnvironmentReview authorization test.
• T035 [P] Add or update ReviewPack cross-workspace and wrong-environment coverage in apps/platform/tests/Feature/Rbac/ReviewPackAccessBoundaryTest.php or existing ReviewPack authorization tests.
• T036 [P] Add or update EvidenceSnapshot or StoredReport wrong-environment coverage using repo-real policies/resources.
• T037 [P] Add or update FindingException cross-workspace and wrong-environment coverage in apps/platform/tests/Feature/Rbac/FindingExceptionLifecycleAccessBoundaryTest.php or existing finding exception authorization tests.
• T038 [P] Add or update OperationRun workspace-bound and environment-bound access coverage in apps/platform/tests/Feature/Rbac/OperationRunAccessBoundaryTest.php or existing OperationRun authorization tests.
• T039 [P] Add or update ProviderConnection cross-workspace and wrong-environment coverage in apps/platform/tests/Feature/Rbac/ProviderConnectionAccessBoundaryTest.php or existing ProviderConnection authorization tests.

Phase 5: Tests First - Sensitive Actions

Purpose: Prove server-side authorization for mutation/action execution, not only navigation visibility.

• T040 Add membership-management direct action or policy tests proving non-Owner denial and last-owner guard preservation.
• T041 Add ProviderConnection credential-level denial tests for Manager/Operator/Readonly where high-privilege-only classification is confirmed.
• T042 Add Review/ReviewPack mutation denial tests for Readonly and any non-owner role classified as unauthorized.
• T043 Add FindingException approval/rejection/renew/revoke lifecycle denial tests for unauthorized roles.
• T044 Add OperationRun view/start/cancel/retry/action denial tests for unauthorized or out-of-scope roles using existing operation action surfaces.
• T045 Ensure each destructive action changed by this spec is tested for server-side authorization and existing ->requiresConfirmation() posture.

Phase 6: Minimal Runtime Fixes

Purpose: Fix only confirmed contradictions and direct boundary bugs.

• T046 Remove or adjust Manager WORKSPACE_MEMBERSHIP_MANAGE in apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php if Owner-only is confirmed.
• T047 Remove or adjust Manager-specific TENANT_MEMBERSHIP_MANAGE append in WorkspaceRoleCapabilityMap::getCapabilities() if Owner-only is confirmed.
• T048 Update apps/platform/app/Models/User.php::canAccessPanel() only if direct tests prove current permissive behavior is unsafe or can be tightened without breaking login/workspace selection.
• T049 Add missing Gate::authorize(...) or policy checks in confirmed service/action mutation paths only. No missing mutation path was confirmed beyond the fixed role-map grants.
• T050 Fix missing policy logic in ProviderConnection, ReviewPack, EnvironmentReview, EvidenceSnapshot, FindingException, or OperationRun policies only for confirmed direct-access bypasses. No direct-access policy bypass was confirmed.
• T051 Align Filament action visibility/disabled state with server-side policy only after the policy/gate behavior is correct.
• T052 Ensure any changed destructive Filament execution action still uses ->action(...), ->requiresConfirmation(), and server-side authorization. No destructive action implementation changed.
• T053 Do not introduce new roles, tables, migrations, capability aliases, broad resolvers, or UI redesigns.

Phase 7: Focused Validation

Purpose: Run the smallest honest lanes for changed behavior.

• T054 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceRoleCapabilityMapTest.php.
• T055 Run focused RBAC boundary tests under apps/platform/tests/Feature/Rbac/ that were added or updated for Spec 309.
• T056 Run existing panel cross-plane tests if panel access changed: apps/platform/tests/Feature/Auth/CrossScopeAccessTest.php, apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php, and apps/platform/tests/Feature/System/Spec114/SystemConsoleAccessSemanticsTest.php.
• T057 Run review/customer workspace regressions: apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php, apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackRbacTest.php, and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php.
• T058 Run provider connection authorization regressions if provider boundaries changed.
• T059 Run OperationRun authorization/link regressions if OperationRun policy or links changed. No OperationRun policy/link code changed; existing OperationRun RBAC regression was still run.
• T060 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T061 Run git diff --check.
• T062 Run browser smoke only if Feature/Filament tests cannot prove a changed panel/action boundary; otherwise document why browser was not needed.

Phase 8: Close-Out

Purpose: Leave implementation reviewers with exact security and product-truth decisions.

• T063 Record final role/capability inventory in close-out notes.
• T064 Record confirmed contradictions fixed.
• T065 Record product decisions deferred.
• T066 Record docs-only drift and follow-up candidates.
• T067 Record tests run, tests not run, and why.
• T068 Confirm no new RBAC model/table/capability framework/migration was introduced.
• T069 Confirm Filament v5 / Livewire v4 compliance, provider registration location, global-search resource posture, destructive-action confirmation/authorization, no new asset strategy, and testing plan coverage.
• T070 Confirm remaining risks and recommended next spec after 309.

Dependencies & Execution Order

• Phase 1 blocks all later phases.
• Phase 2 blocks test writing and runtime edits.
• Phases 3, 4, and 5 can run partly in parallel once classification is complete, but each worker must own disjoint test files.
• Phase 6 starts only after tests for confirmed contradictions exist.
• Phase 7 starts after runtime fixes.
• Phase 8 closes after validation.

Parallel Execution Examples

• T003-T015 can run in parallel as read-only inspection.
• T027-T032 can run in parallel with disjoint test files.
• T033-T039 can run in parallel with disjoint test files.
• T041-T044 can run in parallel when each action group owns separate policies/tests.
• T054-T059 can run in parallel if the Sail environment supports concurrent lanes; otherwise run serially.

Implementation Strategy

1. MVP = role-map contradiction proof + /admin and /system direct boundary tests.
2. Add workspace/environment isolation proof for the representative resource set.
3. Add sensitive-action tests for the confirmed bug set.
4. Apply minimal fixes.
5. Validate focused lanes and close out with inventory and decisions.

Deferred Follow-Ups / Non-Goals

• Support Access Governance v1.
• Product Truth / Docs Drift Reconciliation.
• Customer Review Workspace v1 Completion.
• Route / Panel Access Contract Audit beyond confirmed 309 bugs.
• Commercial entitlements or billing state.
• New RBAC management UI or permission matrix.

Implementation Close-Out Notes

RBAC Inventory

Role	Capabilities	Sensitive?	Matches target?	Action
Workspace Owner	Workspace membership manage, tenant membership manage, provider manage + dedicated credential manage, review/review-pack/evidence manage, finding exception approve, OperationRun view by capability	Yes	Yes	Kept. Owner positive tests added.
Workspace Manager	Workspace membership view, provider manage/run, review/review-pack/evidence manage, finding exception approve, workspace settings/manage, alerts/baselines/audit	Yes	Partially	Fixed confirmed membership-management contradiction. Provider/review/evidence/finding manage remains product-decision-needed because existing runtime and tests treat it as intended.
Workspace Operator	Workspace membership view, provider view/run, review/evidence view, findings triage, audit, allowed operation visibility	Medium/High	Yes	Kept and covered by boundary tests.
Workspace Readonly	Workspace/settings/alerts/baselines/audit view plus customer-safe tenant/review/evidence/provider/review-pack view where scoped	Medium	Yes	Kept and mutation denials covered.
Platform/System	Separate platform guard + PlatformCapabilities; no implicit admin/workspace access	Critical	Yes	Kept; /system direct tests added and cross-plane regressions passed.

Confirmed Contradictions Fixed

• Manager no longer receives Capabilities::WORKSPACE_MEMBERSHIP_MANAGE from WorkspaceRoleCapabilityMap.
• Manager no longer receives the Manager-only appended Capabilities::TENANT_MEMBERSHIP_MANAGE from WorkspaceRoleCapabilityMap::getCapabilities().
• User::canAccessPanel() is now restricted to the admin panel; ordinary web users no longer advertise access to the system panel.

Product Decisions Deferred

• Manager PROVIDER_MANAGE, REVIEW_PACK_MANAGE, ENVIRONMENT_REVIEW_MANAGE, EVIDENCE_MANAGE, and FINDING_EXCEPTION_APPROVE remain unchanged because repo-real policies and existing regressions treat them as current product behavior.
• Provider dedicated credential management remains high-privilege only through PROVIDER_MANAGE_DEDICATED; tests prove Manager/Operator/Readonly denial and Owner allowance.
• Support access governance, commercial lifecycle enforcement, and broader route/panel contract cleanup remain follow-up candidates.

Validation Results

• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceRoleCapabilityMapTest.php tests/Unit/Auth/CapabilityResolverTest.php tests/Feature/Rbac/RoleMatrix/ManagerAccessTest.php tests/Feature/Rbac/WorkspaceRoleCapabilityBoundaryTest.php tests/Feature/Rbac/AdminPanelAccessBoundaryTest.php tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php — 17 passed.
• 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 — 12 passed.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/WorkspaceMembershipsRelationManagerUiEnforcementTest.php tests/Feature/Auth/CrossScopeAccessTest.php tests/Feature/Auth/SystemPanelAuthTest.php — 14 passed.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/System/Spec114/SystemConsoleAccessSemanticsTest.php — 22 passed.
• 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 — 30 passed.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Rbac/OperationRunWorkspaceFirstAuthorizationTest.php tests/Feature/ProviderConnections/ManageCapabilityEnforcementTest.php tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php — 13 passed.
• cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent — passed.
• git diff --check — passed.

Browser smoke was not run because the changed behavior is backend authorization, role maps, panel contract checks, and Filament/Livewire action enforcement proven by Feature/Livewire tests. No frontend assets, layouts, forms, or navigation redesign were introduced.

Filament / Runtime Compliance

• Filament v5 remains on Livewire v4.1.4.
• Panel providers remain registered through apps/platform/bootstrap/providers.php.
• New/changed resources are not introduced; existing touched resources keep their current global-search posture.
• No destructive action implementation changed. Existing workspace membership destructive removal still uses an execution action with confirmation and the server-side workspace capability guard.
• No assets were added or changed; no filament:assets deploy impact.
• No new RBAC model, role, table, migration, capability alias, public permission framework, or UI redesign was introduced.