TenantAtlas/specs/402-resource-policy-authorization-proof-matrix/tasks.md

Tasks: Spec 402 - Resource Policy & Authorization Proof Matrix

Input: specs/402-resource-policy-authorization-proof-matrix/spec.md, plan.md, checklists/requirements.md, user-provided Spec 402 draft, Spec 400 and Spec 401 context, Product Surface Contract, and repo truth.

Tests: Required. This spec changes or verifies authorization behavior and must include focused Pest policy/gate/Feature/Filament tests plus focused browser proof for representative high-risk rendered paths.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed authorization behavior.
• New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover resource authorization without pulling in unrelated lane cost.
• The declared surface test profile or standard-native-filament relief is explicit.
• Browser proof covers representative rendered authorization behavior and does not claim full browser audit.
• Human Product Sanity and Product Surface implementation-report close-out are planned.
• Any material budget, baseline, trend, or escalation note is recorded in the implementation report.

Phase 1: Preparation And Dirty-State Baseline

Purpose: Establish safe starting conditions and read all governing context before runtime edits.

• T001 Read specs/402-resource-policy-authorization-proof-matrix/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• T002 Record current branch, HEAD, dirty state, tracked changed files, untracked files, and git diff --check in specs/402-resource-policy-authorization-proof-matrix/implementation-report.md.
• T003 Re-read AGENTS.md, .specify/memory/constitution.md, .specify/README.md, docs/ai-coding-rules.md, docs/security-guidelines.md, docs/testing-guidelines.md, docs/architecture-guidelines.md, docs/filament-guidelines.md, and docs/product/standards/product-surface-contract.md.
• T004 Re-read specs/400-product-contract-spec-completeness-audit/ and specs/401-high-risk-admin-action-proof-pack/implementation-report.md as read-only context; preserve completed-spec history.
• T005 Confirm Spec 401 has no unresolved P0 high-risk action blocker before making Spec 402 runtime changes; record any residual proof debt as input to the matrix.
• T006 Confirm no new roles, new capability vocabulary, new product surfaces, migrations, JSON-to-JSONB work, governance lifecycle work, management PDF behavior, or broad UI redesign will be included.

Phase 2: Baseline Inventory

Purpose: Build repo-truth inventory before adding policies or hardening code.

• T007 Inventory panel provider registration and access middleware in apps/platform/bootstrap/providers.php, apps/platform/app/Providers/Filament/AdminPanelProvider.php, and apps/platform/app/Providers/Filament/SystemPanelProvider.php.
• T008 Inventory admin/system routes with Laravel route tooling or Boost route listing, including /admin, /admin/workspaces/{workspace}/environments/{environment}/..., /system, controller-backed downloads/exports, and signed links.
• T009 Inventory Filament resources under apps/platform/app/Filament/Resources/, including model, pages, global search posture, can* methods, getEloquentQuery(), resolveRecordRouteBinding(), actions, bulk actions, and relation managers.
• T010 Inventory model-backed admin/custom pages under apps/platform/app/Filament/Pages/, including governance, monitoring, evidence, operations, review, onboarding, workspace settings, and context pages.
• T011 Inventory system pages/widgets under apps/platform/app/Filament/System/ and classify read-only diagnostics versus mutation/repair actions.
• T012 Inventory policies under apps/platform/app/Policies/, policy registration in AuthServiceProvider and AppServiceProvider, and any model-backed resource without an explicit policy.
• T013 Inventory gates/capabilities in apps/platform/app/Providers/AuthServiceProvider.php, apps/platform/app/Services/Auth/, apps/platform/app/Support/Auth/, and existing UiEnforcement / WorkspaceUiEnforcement paths.
• T014 Inventory authorization-relevant controllers and middleware under apps/platform/app/Http/, especially review-pack/report downloads, management-report PDF downloads, provider consent/RBAC callbacks, finding-exception queue deep links, workspace/environment switching, and platform capability middleware.
• T015 Inventory existing tests under apps/platform/tests/ for policy, authorization, capability, Filament resource, relation manager, global search, admin/system boundary, backup/restore/provider/evidence/review/report/operation/audit coverage.

Phase 3: Resource Policy & Authorization Matrix

Purpose: Create the matrix first; do not fix runtime behavior until every inspected surface has a classification target.

• T016 Create specs/402-resource-policy-authorization-proof-matrix/implementation-report.md with the required report headings A through M from spec.md.
• T017 Add the matrix table with columns: Resource / Surface, Panel, Model, Category, Workspace/Environment/System Scope, Policy, Gate/Capability, List, View, Create, Update, Delete, Custom Actions, Bulk Actions, Relations, Global Search, Query Scope Proof, Direct Access Proof, Tests, Decision.
• T018 Classify each admin Filament resource as category A/B/C/D/E and record workspace/environment/system scope, model, pages, global search posture, and authorization mechanism.
• T019 Classify each system page/action as category D or E and record platform capability path, read-only versus mutation/repair decision, and system/admin boundary proof.
• T020 Classify controller-backed downloads/exports/deep links and signed routes by underlying model/resource, scope, capability path, and customer/internal boundary.
• T021 Classify every relation manager by owner record, related model, parent scope, allowed actions, and direct invocation proof need.
• T022 Classify every bulk action discovered in resources by action name, affected model(s), per-record authorization posture, confirmation posture, and tests.
• T023 Classify global search for every resource as authorized/scoped, disabled by design, system-only, unsafe/missing proof, or not applicable.
• T024 Record existing tests proving each matrix decision; mark missing proof as P1 until proven or explicitly deferred.

Phase 4: Gap Classification

Purpose: Decide whether a gap is missing proof, missing policy, unsafe access, or product-decision debt.

• T025 Classify missing proof only gaps where implementation looks safe but direct/negative tests do not exist.
• T026 Classify missing policy but sufficient gate/capability paths where existing resolvers are authoritative and tested.
• T027 Classify missing policy and insufficient authorization paths where no explicit server-side check is proven.
• T028 Classify UI visibility versus execution inconsistencies, especially static Filament can* methods, hidden actions, disabled actions, and direct Livewire action calls.
• T029 Classify workspace/environment scope risks for list, view, action, relation manager, export/download, and global search paths.
• T030 Classify system/admin boundary risks for /system access, system pages/actions, platform capabilities, and workspace-admin denial.
• T031 Classify customer/reviewer/internal boundary risks where customer-safe review/report/evidence surfaces are represented.
• T032 Classify relation manager, bulk action, and global search risks separately rather than folding them into page-level authorization.
• T033 Mark product-ambiguous authorization decisions as DEFERRED: product decision required instead of inventing roles or capabilities.

Phase 5: Tests Before Hardening

Purpose: Add focused negative tests for high-risk proof gaps before runtime changes where feasible.

• T034 Add or update policy/gate tests proving allowed and denied decisions for every new or modified policy in apps/platform/tests/Feature/....
• T035 Add or update direct route/resource access tests proving authorized users can list/view authorized workspace/environment records and unauthorized users cannot access guessed record URLs.
• T036 Add or update cross-workspace denial tests for at least one high-risk admin resource and every fixed cross-workspace gap.
• T037 Add or update system/admin separation tests proving workspace admins cannot access /system resources and platform users require appropriate PlatformCapabilities.
• T038 Add or update Filament action tests proving unauthorized actors cannot execute hidden/disabled high-impact actions directly and no unauthorized mutation/audit/evidence/operation side effect occurs; provider check/sync/snapshot disabled direct calls are covered by ProviderConnectionsUiEnforcementTest.
• T039 Add or update bulk action tests proving disabled/authorized/per-record behavior for any fixed or high-risk bulk actions.
• T040 Add or update relation manager tests proving parent and related records stay scoped and relation actions cannot affect unrelated records.
• T041 Add or update global search tests proving sensitive resources are disabled or scoped and unauthorized/cross-workspace/system-only records do not appear.
• T042 Add or update controller/download/export tests proving actor authorization to underlying workspace/environment/customer-safe artifacts before serving output.
• T043 Add or update customer/reviewer boundary tests where existing customer-safe surfaces are in matrix scope.

Phase 6: Minimal Hardening

Purpose: Fix only confirmed unsafe or unproven authorization gaps using existing architecture.

• T044 Add a policy class only when the model is user-accessible, no sufficient explicit authorization path exists, behavior is derivable from existing product contracts, and tests can prove it.
• T045 Register any newly required policy according to current repository convention without duplicating existing capability semantics.
• T046 Update existing policies only when they lack required list/view/create/update/delete/custom action decisions or wrong-scope denial semantics.
• T047 Update static Filament can* methods only when they do not delegate to explicit policies/gates/capabilities or contradict direct execution behavior.
• T048 Add missing action-level server authorization checks for high-impact or destructive actions while preserving ->action(...), ->requiresConfirmation(), audit behavior, and notifications where applicable.
• T049 Disable or restrict unsafe global search rather than enabling search for completeness.
• T050 Restrict unsafe bulk actions or add per-record authorization checks where bulk operations could bypass record authorization.
• T051 Scope relation manager queries/actions to the owner workspace/environment and block unrelated related records.
• T052 Harden controller-backed downloads/exports/deep links to authorize the underlying resource before output.
• T053 Document any low-risk/read-only/internal exception in the matrix instead of adding cosmetic policies.
• T054 Stop and update spec/plan before introducing any new authorization helper, new abstraction, new capability, or broader RBAC model.

Phase 7: Focused Browser Proof

Purpose: Verify representative rendered authorization behavior without turning Spec 402 into a full browser audit.

• T055 Add or update a focused browser smoke test such as apps/platform/tests/Browser/Spec402ResourcePolicyAuthorizationSmokeTest.php if browser support is available.
• T056 Browser-proof one authorized admin workspace-scoped resource allowed path.
• T057 Browser-proof one admin cross-workspace denied resource path.
• T058 Browser-proof one system-only resource/page denied to a workspace admin.
• T059 Browser-proof one high-impact action hidden for an unauthorized actor with no operation side effect; provider disabled-action UX is browser-tested, and direct disabled provider operation execution is feature-tested.
• T060 Feature-proof one sensitive global-search disabled/scoped posture; browser global-search UI proof is intentionally not claimed by the focused smoke.
• T061 Record route/surface, actor, panel, workspace/environment, expected result, observed result, and console/runtime errors in the implementation report.
• T062 If browser tests are unavailable, record the exact blocker and do not claim browser proof.

Phase 8: Implementation Report And Final Validation

Purpose: Close the proof loop with explicit results, residual severity, and next-step recommendation.

• T063 Complete implementation report section A with Candidate Gate Result: PASS, PASS WITH CONDITIONS, or FAIL.
• T064 Complete section B with included and explicitly not included scope.
• T065 Complete section C with dirty state before/after, tracked files changed, and untracked files.
• T066 Complete section D with the Resource Policy & Authorization Matrix.
• T067 Complete section E with runtime changes made, why needed, and scope risk.
• T068 Complete section F with policies/gates/capabilities added, updated, and documented exceptions.
• T069 Complete section G with tests added/updated, positive/negative classification, and result.
• T070 Complete section H with direct access, UI visibility, action execution, workspace/environment isolation, system/admin separation, customer/internal boundary, global search, relation manager, and bulk-action proof summary.
• T071 Complete section I with focused browser proof or exact no-browser limitation.
• T072 Complete section J with remaining findings by P0/P1/P2/P3.
• T073 Complete section K with deferred items: evidence currentness closure, management PDF staging validation, governance lifecycle, JSONB migration, full browser audit, and other items.
• T074 Complete section L with validation commands and exact results.
• T075 Complete section M with recommended next action: Spec 403 only if no P0 remains and P1 conditions are bounded.
• T076 Run git diff --check after implementation and record result.
• T077 If PHP runtime or test files changed, run the project formatter for changed PHP files according to repository convention and record the result.
• T078 Verify changed reports, tests, logs, and fixtures do not include secrets, tokens, raw credential payloads, or sensitive raw provider payloads.
• T079 Run targeted Pest validation commands from plan.md and record pass/fail/output summary.
• T080 Run focused browser validation command if available and record pass/fail/output summary.
• T081 Run final dirty-state commands and confirm no unrelated dirty files were reset, deleted, or cleaned.

Non-Goals Checklist

• NT001 Do not add new product roles, role hierarchy, permission model, or capability vocabulary unless an existing contract already requires it.
• NT002 Do not add new admin, system, customer, navigation, onboarding, evidence/reporting, backup, restore, provider, or governance lifecycle surfaces.
• NT003 Do not add migrations, JSON-to-JSONB changes, new persisted truth, new status family, or new taxonomy.
• NT004 Do not perform broad service/model/Filament refactors.
• NT005 Do not rewrite completed specs or remove historical close-out, validation, smoke, browser, or task history.
• NT006 Do not claim UI visibility is authorization proof.
• NT007 Do not enable global search merely to satisfy matrix completeness.
• NT008 Do not claim full browser/UX/runtime audit completion.

Dependencies And Execution Order

• Phase 1 must complete before runtime edits.
• Phase 2 inventory must complete before Phase 3 matrix decisions.
• Phase 3 matrix must exist before Phase 4 gap classification.
• Phase 4 must classify gaps before tests/hardening.
• Phase 5 negative tests should precede Phase 6 hardening wherever feasible.
• Phase 6 fixes must stay bounded to confirmed authorization gaps.
• Phase 7 browser proof follows focused hardening and tests.
• Phase 8 closes with report, validation, dirty state, and recommended next step.

Recommended Implementation Strategy

Treat implementation as an authorization proof loop, not a policy-generation pass. Prefer existing policies, gates, capabilities, scoped queries, and UI enforcement helpers. Add policy classes only when they improve safety and can be derived from current contracts. Every fixed authorization gap needs a negative test, and any ambiguous product decision must be deferred instead of invented.