# Feature Specification: Spec 402 - Resource Policy & Authorization Proof Matrix **Feature Branch**: `402-resource-policy-authorization-proof-matrix` **Created**: 2026-06-23 **Status**: Draft / Ready for implementation preparation review **Type**: Targeted authorization hardening / proof / policy matrix spec **Runtime posture**: Existing authorization proof and minimal hardening only. No new product surfaces, no new product concepts, no broad RBAC redesign. **Input**: User-provided Spec 402 draft, current repo truth, Product Surface Contract, Spec 400 product-contract audit context, Spec 401 high-risk action proof context, roadmap/spec-candidate queue, and admin/system Filament authorization surfaces. ## Candidate Selection Context - **Selected candidate**: Resource Policy & Authorization Proof Matrix. - **Source location**: Direct user-provided Spec 402 draft in the 2026-06-23 request, promoted from the Spec 400 P1 resource-policy matrix condition. - **Why selected**: `docs/product/spec-candidates.md` currently reports no safe automatic next-best-prep target, but the operator supplied a direct manual candidate. The candidate closes an explicit Spec 400 risk: several resource-backed models and surfaces rely on a mix of policies, gates, capabilities, Filament static authorization, route middleware, and scoped queries, but the proof is not organized as an auditable resource matrix. - **Roadmap relationship**: Supports the current governance and architecture hardening lane by proving RBAC, workspace/environment isolation, system/admin separation, global search posture, relation-manager scoping, and direct invocation denial before Evidence Anchor & Currentness Runtime Closure or broader browser/runtime audit work proceeds. - **Close alternatives deferred**: - Spec 403 - Evidence Anchor & Currentness Runtime Closure is deferred until Spec 402 reaches at least `PASS WITH CONDITIONS` with no P0 authorization findings. - Management Report PDF staging validation remains manual follow-through for Specs 378-380 and is unrelated to resource authorization proof. - Governance artifact lifecycle/retention runtime is broader product runtime work and must not be hidden inside this authorization proof. - Provider readiness onboarding productization is optional productization work; this spec proves existing authorization posture first. - Full browser/UX/runtime audit is deferred while resource authorization proof remains incomplete. - **Completed-spec guardrail result**: - No `specs/402-resource-policy-authorization-proof-matrix/` package existed before this preparation. - A local and remote branch named `402-screwfast-website-rebuild` existed before preparation, but no TenantPilot `specs/402-*` package existed. The operator explicitly requested Spec ID 402, so this package uses the requested number and records the branch-prefix collision as preparation context. - Specs 400 and 401 are related context only. Their close-out notes, validation results, completed task markers, browser proof, smoke history, and implementation reports must not be rewritten, normalized, unchecked, or removed. - Spec 401 implementation-report evidence shows no unresolved P0 high-risk action blocker in the selected backup-schedule hardening slice. It records an independently reproducible provider UI enforcement residual; Spec 402 must inventory that as proof debt if still present, not silently treat it as solved. - **Smallest viable implementation slice**: Build the Resource Policy & Authorization Matrix first; classify gaps; add targeted tests and only minimal runtime hardening for confirmed unsafe or unproven high-risk resource authorization paths; record any policy/gate/capability exceptions in the implementation report. - **Feature description for Spec Kit**: Prove and minimally harden existing resource-backed authorization across TenantPilot admin and system panels by inventorying every relevant Filament resource/page/action/relation/search path, documenting policy/gate/capability decisions, adding focused tests for direct access, workspace/environment isolation, system/admin separation, global search, relation managers, and high-risk action execution, and applying only bounded fixes required to make the authorization posture evidence-backed. ## Spec Candidate Check *(mandatory - SPEC-GATE-001)* - **Problem**: TenantPilot has many resource-backed admin and system surfaces, but authorization proof is fragmented across policies, gates, capability checks, static Filament `can*` methods, route middleware, scoped queries, UI visibility callbacks, and tests. Future agents can mistake hidden UI buttons or resource-level helpers for complete authorization. - **Today's failure**: A reviewer cannot quickly prove which actor may list, view, create, update, delete, search, bulk-act, or trigger custom actions for every resource-backed surface. Missing policies may be safe because a capability path exists, or unsafe because direct record/action access is untested. Both cases currently look too similar. - **User-visible improvement**: Operators and reviewers get evidence-backed confidence that admin/system resources enforce workspace/environment scope, system/admin separation, customer/internal boundaries, direct invocation denial, global search posture, relation-manager scoping, and action authorization. - **Smallest enterprise-capable version**: One implementation report with a matrix over existing admin/system resources, focused negative tests for high-risk resource paths, minimal hardening only where proof reveals an unsafe or unproven authorization path, and documented exceptions where an existing gate/capability service is intentionally sufficient. - **Explicit non-goals**: No new roles, no new role hierarchy, no new permission product model, no new capability vocabulary unless an existing contract already requires it, no new admin/system/customer surfaces, no navigation changes, no onboarding or evidence/reporting behavior, no management PDF behavior, no JSON-to-JSONB migration, no governance lifecycle/retention work, no broad UI redesign, no completed-spec rewrite. - **Permanent complexity imported**: A spec-local implementation report/matrix, focused policy/feature/Filament/browser tests, and possibly a small number of targeted policy classes or authorization checks if existing proof is insufficient. No new persisted truth, table, enum/status family, cross-domain framework, or broad RBAC model is expected. - **Why now**: Spec 400 recorded resource policy coverage as a P1 condition, and Spec 401 proved selected high-risk action behavior. Before proceeding to evidence/currentness or broader runtime audit, TenantPilot needs the authorization map that proves resource-backed surfaces are not relying on UI visibility or assumptions. - **Why not local**: A local policy fix for one model would not answer cross-panel ownership, direct route access, global search, relation managers, bulk actions, system/admin boundary, or existing gate/capability exceptions. The proof must be matrix-first so fixes are targeted rather than cosmetic. - **Approval class**: Core Enterprise. - **Red flags triggered**: Matrix/proof artifact and many surfaces. Defense: the matrix is spec-local evidence, not a runtime registry or framework; scope is existing authorization only; no new roles, concepts, persisted truth, or surfaces are introduced. - **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12** - **Decision**: approve as a bounded authorization proof and hardening package. ## Problem Statement Spec 400 concluded that TenantPilot passes product-contract review with conditions, including a P1 need for a resource-policy matrix. Several resource-backed models do not have obvious explicit policy classes, while many paths use gates, capabilities, Filament authorization methods, or scoped query constraints. This spec answers: ```text Can TenantPilot prove that every resource-backed admin/system surface has an explicit, consistent, and tested authorization contract? ``` A surface is authorization-safe only when the implementation can prove who may access it, in which panel, under which workspace/environment/system scope, through which policy/gate/capability path, with which list/view/create/update/delete/custom/bulk/search/relation decisions, and with which tests proving unauthorized direct access is blocked. ## Product / Business Value Authorization proof is a trust feature for an Intune management product. It prevents false confidence in UI-hidden controls, reduces cross-workspace leakage risk, clarifies system/admin separation, and gives future agents a concrete map instead of implicit assumptions. ## Primary Users / Operators - Workspace owners/managers who expect workspace and managed-environment isolation. - Tenant/MSP operators who use admin resources but must be blocked from system-only functions. - Readonly/customer/reviewer actors where tests or surfaces represent customer-safe access. - Platform/system operators who use `/system` without leaking cross-workspace views into `/admin`. - Engineering reviewers and future implementation agents validating authorization safety. ## Spec Scope Fields *(mandatory)* - **Scope**: Admin panel resources/pages/actions, system panel pages/actions, relation managers, table/header/record/bulk actions, global search posture, resource-backed routes/controllers, and workspace/environment/system scoped model access. - **Primary Routes / Surfaces**: - Admin panel `/admin`, discovered resources under `apps/platform/app/Filament/Resources`. - System panel `/system`, discovered pages under `apps/platform/app/Filament/System/Pages`. - Resource-backed admin routes under `/admin/workspaces/{workspace}/environments/{environment}/...`. - Workspace resource routes under `/admin/workspaces/...`. - System directory and operations routes under `/system/directory/...`, `/system/ops/...`, `/system/security/access-logs`, and `/system/repair-workspace-owners`. - Controller-backed admin routes for review-pack downloads/rendered reports, management-report PDF downloads, provider consent/RBAC callbacks, finding-exception queue deep links, workspace switching, and environment selection where they touch resource authorization. - **Required domains**: - Workspace and workspace membership. - ManagedEnvironment and environment memberships/access scopes. - Provider connections, provider credentials/readiness/freshness/permissions. - Backup schedules, backup sets, backup items, backup runs, restore runs. - Evidence snapshots/items, evidence anchors where repo-real, findings, finding exceptions/decisions/evidence references. - Environment reviews, review publication resolution, review packs, stored reports/exports. - Operation runs, audit logs, governance inbox/register pages, operational controls, system operations, system directory, user/team/access management surfaces. - **Data Ownership**: - Workspace-owned records remain workspace scoped. - ManagedEnvironment-owned records remain workspace plus managed-environment scoped. - OperationRun may be workspace-scoped or managed-environment scoped depending on run type, but detail links must enforce entitlement before revealing tenant-bound records. - System-only records and system pages remain platform-plane scoped. - No new persisted entity/table/artifact is allowed by default. - **RBAC**: - Admin plane (`/admin`) uses authenticated `User` plus workspace/environment membership and capability gates. - System plane (`/system`) uses authenticated `PlatformUser` plus `PlatformCapabilities`. - Non-member or wrong workspace/environment scope remains deny-as-not-found. - Member missing capability remains forbidden at execution level. - Cross-plane access remains denied and non-enumerable. - UI visibility is never sufficient authorization proof. For canonical-view or mixed-scope specs: - **Default filter behavior when environment-context is active**: Existing route-owned workspace/environment context must remain authoritative. Missing or stale session context must not expose records. - **Explicit entitlement checks preventing cross-tenant leakage**: List queries, record resolution, action execution, relation managers, exports/downloads, global search, and system cross-workspace views must each prove scope and capability checks. ## No Legacy / No Backward Compatibility Constraint *(mandatory)* TenantPilot is pre-production for this authorization contract. - **Compatibility posture**: canonical authorization proof and hardening over current behavior. - **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no new compatibility path is allowed. - **Why clean replacement is safe now**: Authorization gaps must be fixed or explicitly documented as product-decision debt. Pre-production status means unsafe or ambiguous authorization paths should not be preserved for historical compatibility. ## UI Surface Impact *(mandatory - UI-COV-001)* Does this spec add, remove, rename, or materially change any reachable UI surface? - [ ] No UI surface impact - [x] Existing page changed - [ ] New page/route added - [ ] Navigation changed - [ ] Filament panel/provider surface changed - [ ] New modal/drawer/wizard/action added - [ ] New table/form/state added - [ ] Customer-facing surface changed - [x] Dangerous action changed - [ ] Status/evidence/review presentation changed - [ ] Workspace/environment context presentation changed Rationale: Spec 402 does not add surfaces or redesign presentation, but implementation may harden visibility, disabled state, global search posture, direct action execution, relation-manager access, or high-impact action authorization on existing rendered pages. Treat these as existing-surface authorization changes requiring focused browser proof. ## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact")* - **Route/page/surface**: Existing admin/system resources and pages listed in the authorization matrix; exact touched surfaces must be named in `implementation-report.md`. - **Current or new page archetype**: Existing Search/Index, Settings, Decision, Receipt, Technical Annex, and System Admin pages only. No new archetype may be introduced. - **Design depth**: Domain Pattern Surface / System Admin / Technical Annex depending on existing surface. This spec is authorization proof, not a product redesign. - **Repo-truth level**: repo-verified existing surfaces. - **Existing pattern reused**: native Filament resource/page/action authorization, policies, gates, `UiEnforcement`, `WorkspaceUiEnforcement`, scoped queries, platform capability middleware, and existing browser fixture patterns. - **New pattern required**: none by default. If implementation finds a recurring structural authorization defect, stop and update spec/plan before introducing any shared helper or abstraction. - **Screenshot required**: no full screenshot set by default. Focused browser proof is required for representative high-risk paths. - **Page audit required**: no broad page audit. Matrix and focused proof only. - **Customer-safe review required**: required only where existing customer/reviewer tests or customer-safe surfaces are included in the matrix. - **Dangerous-action review required**: yes for existing destructive/high-impact actions touched or classified. - **Coverage files updated or explicitly not needed**: - [ ] `docs/ui-ux-enterprise-audit/route-inventory.md` - [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` - [ ] `docs/ui-ux-enterprise-audit/page-reports/...` - [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md` - [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md` - [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md` - [x] `N/A - no new reachable UI surface; existing-surface authorization hardening only` - **No-impact rationale when applicable**: N/A because existing rendered authorization behavior may change. ## Product Surface Impact *(mandatory for UI-affecting specs)* Reference: `docs/product/standards/product-surface-contract.md`. - **Product Surface Contract applies?**: yes. Existing actions, global search, route access, downloads/exports, and system/admin boundaries can affect rendered product access. - **Page archetype**: existing archetypes only; exact touched pages recorded in implementation report. - **Primary user question**: "Am I allowed to see or perform this action for this workspace/environment/system scope?" - **Primary action**: no new primary action. Existing primary actions must remain authorization-correct. - **Surface budget result**: neutral by default; any UI complexity increase requires an implementation-report exception. - **Technical Annex / deep-link demotion**: unchanged. OperationRun, raw evidence, IDs, payloads, source keys, detectors, fingerprints, and technical logs must not become more visible. - **Canonical status vocabulary**: unchanged. No new status vocabulary is allowed. - **Visible complexity impact**: neutral or decreased. Hidden/disabled actions may become more accurate; no new UI layers. - **Product Surface exceptions**: none planned. ## Browser Verification Plan *(mandatory)* - **Browser proof required?**: yes for representative high-risk authorization surfaces. - **No-browser rationale**: N/A. - **Focused path when required**: 1. One authorized admin workspace-scoped resource allowed path. 2. One admin cross-workspace denied resource path. 3. One `/system` resource/page denied to a normal workspace admin. 4. One high-impact action hidden, disabled, or execution-blocked for unauthorized actor. 5. One globally unsearchable or scoped-search sensitive resource posture by the narrowest honest proof path; use feature-level proof when the focused browser smoke does not exercise the global-search UI. - **Primary interaction to execute**: route navigation, table/resource action visibility, direct denied URL, one high-impact action proof, and global search only when the focused browser path is available without turning the smoke into a broad UI audit. - **Console, Livewire, Filament, network, and 500-error checks**: planned. - **Full-suite failure triage**: unrelated browser failures are documented separately; do not claim full browser audit. ## Human Product Sanity Check *(mandatory)* - **Required?**: yes, as a focused authorization sanity check for changed rendered behavior. - **No-human-sanity rationale**: N/A. - **Reviewer questions**: Are allowed/denied states understandable? Does forbidden access avoid leaking record existence? Are high-impact actions separated and confirmation-protected? Is the system/admin boundary clear? Did visible complexity stay neutral or decrease? - **Planned result location**: `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`. ## Product Surface Merge Gate Checklist *(mandatory)* - [x] No-legacy posture or approved exception recorded. - [x] Product Surface Impact is completed for existing-surface authorization hardening. - [x] Browser proof is required for representative authorization surfaces during implementation. - [x] Human Product Sanity is required for changed rendered behavior. - [x] Product Surface exceptions are documented as `none planned`. - [x] Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion. ## Cross-Cutting / Shared Pattern Reuse - **Cross-cutting feature?**: yes. - **Interaction class(es)**: authorization, action visibility/disabled state, global search, relation managers, downloads/exports, system access. - **Systems touched**: policies, gates, capability resolvers, `UiEnforcement`, `WorkspaceUiEnforcement`, scoped resource queries, platform capability middleware, Filament resources/pages/relation managers, controller-backed downloads/deep links. - **Existing pattern(s) to extend**: existing policies/gates/capabilities and UI enforcement paths. - **Shared contract / presenter / builder / renderer to reuse**: existing authorization services and UI enforcement helpers; no new shared pattern by default. - **Why the existing shared path is sufficient or insufficient**: sufficient until the matrix proves a concrete gap. Any new helper requires spec/plan update and proportionality review. - **Allowed deviation and why**: documented policy/gate/capability exception only when it is safer and clearer than adding a cosmetic policy. - **Consistency impact**: direct execution, UI visibility, scoped queries, search, relations, and bulk actions must agree. - **Review focus**: no hidden UI-only authorization, no duplicate role logic, no raw role strings in new code, no unscoped relation/search/export path, no completed-spec rewrite. ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: possibly, only as authorization proof for existing OperationRun-linked resources/actions. - **Shared OperationRun UX contract/layer reused**: existing OperationRun policies, links, and start UX paths only. - **Delegated start/completion UX behaviors**: unchanged. - **Local surface-owned behavior that remains**: existing initiation inputs only. - **Queued DB-notification policy**: unchanged. - **Terminal notification path**: unchanged. - **Exception required?**: none planned. ## Provider Boundary / Platform Core Check - **Shared provider/platform boundary touched?**: yes, by inspection of provider connections/readiness/permissions and provider-backed resources. - **Boundary classification**: mixed; provider connection details are provider-owned, while workspace/environment authorization, capability gates, operations, evidence, and audit are platform-core. - **Seams affected**: provider connections, provider credentials, managed-environment permissions, provider readiness/freshness actions, OperationRun proof links. - **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, operation, evidence, audit, capability. - **Provider-specific semantics retained and why**: Microsoft/Graph/Entra terms remain only where existing provider-owned surfaces require them. - **Why this does not deepen provider coupling accidentally**: the spec changes authorization proof only and does not create provider taxonomy or new provider-facing product concepts. - **Follow-up path**: provider productization remains outside scope. ## UI / Surface Guardrail Impact | Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note | |---|---|---|---|---|---|---| | Admin Filament resources and relation managers | yes, if hardening changes visible authorization | Native Filament + existing helpers | authorization, actions, search, relations | page, table, relation, modal/action, route/query | none planned | Existing-surface authorization only | | System Filament pages | yes, if capability access changes | Native Filament pages/widgets | platform capabilities | page, route | none planned | System/admin boundary proof | | Controller-backed downloads/deep links | no rendered surface change unless link visibility changes | Laravel controllers + existing links | downloads/exports | route/action | none planned | Direct authorization proof | ## Decision-First Surface Role | Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction | |---|---|---|---|---|---|---|---| | Existing admin resource index/detail pages | Primary or secondary depending on existing page | Decide whether actor can inspect or act on scoped resource | Allowed actions and denied/disabled state | Audit/OperationRun/evidence links where already present | Not changed by this spec | Existing workflows only | Prevents false clickable affordances | | Existing system pages | System Admin | Platform operator decides or inspects system state | System-only access and capability-gated actions | System diagnostics and access logs | System plane only | Existing `/system` workflows | Blocks workspace-admin confusion | ## Audience-Aware Disclosure | Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention | |---|---|---|---|---|---|---|---| | Admin resources | operator-MSP, readonly/customer where already represented | Safe action availability and scoped records | Existing audit/evidence/run links | Capability-gated only | Existing primary action | Unauthorized records and raw internals | Matrix records one authorization decision per action | | System pages | support-platform | System capability access | System diagnostics | Platform capability-gated | Existing system action | Workspace-admin access | Separate admin/system decisions | ## UI/UX Surface Classification | Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification | |---|---|---|---|---|---|---|---|---|---|---|---|---|---| | Admin resources | Existing list/detail/action classes | CRUD / Registry / Technical Annex / Decision as already defined | Inspect, manage, restore, export, run, verify, or resolve according to existing resource | Existing resource route | Existing behavior | Existing More/detail placement | Confirmation-protected, server-authorized | Existing `/admin/...` routes | Existing detail routes | Workspace/environment | Existing nouns | Authorized action state | none planned | | System pages | System Admin | System operations/directory/security | Inspect or operate platform controls | Existing page route | Existing behavior | Existing page actions | Capability-gated | `/system/...` | `/system/...` | Platform/system | Existing nouns | Platform access state | none planned | ## Operator Surface Contract | Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions | |---|---|---|---|---|---|---|---|---|---|---| | Existing admin resources | Workspace operator | Access scoped records and execute allowed actions | Existing | Can I access or act on this scoped record? | Allowed records/actions | Raw proof, payloads, audit internals where existing | Existing | TenantPilot / provider / simulation as existing | Existing | Must be confirmed and execution-authorized | | Existing system pages | Platform operator | Inspect or operate platform/system state | System Admin | Can I access or act on this system resource? | System capability-allowed surfaces | System diagnostics | Existing | Platform/system | Existing | Must be platform-capability gated | ## Proportionality Review *(mandatory when structural complexity is introduced)* - **New source of truth?**: no runtime source of truth. The implementation report matrix is review evidence only. - **New persisted entity/table/artifact?**: no. - **New abstraction?**: no by default. Any proposed helper/policy abstraction requires updated proportionality review before implementation continues. - **New enum/state/reason family?**: no. - **New cross-domain UI framework/taxonomy?**: no. - **Current operator problem**: authorization posture is too implicit to audit consistently across admin/system resources. - **Existing structure is insufficient because**: scattered proof makes it hard to distinguish safe gate/capability exceptions from missing policy coverage or direct-access gaps. - **Narrowest correct implementation**: matrix-first proof, targeted tests, minimal hardening only when evidence shows a gap. - **Ownership cost**: one implementation report/matrix plus focused tests and any targeted policies/checks added. - **Alternative intentionally rejected**: blindly generating policies for every model or creating a new authorization framework. - **Release truth**: current-release trust and safety requirement. ### Compatibility posture This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by an existing product contract. ## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* - **Test purpose / classification**: Feature, Filament/Livewire, policy/gate, Heavy-Governance for matrix/proof if grouped, Browser for representative authorization smoke. - **Validation lane(s)**: confidence plus focused browser; fast-feedback for small policy/gate tests where possible. - **Why this classification and these lanes are sufficient**: authorization behavior spans HTTP routes, Filament resources/actions/relation managers, policy/gate decisions, and rendered browser visibility; no full browser audit is needed. - **New or expanded test families**: `Spec402` focused authorization tests only. - **Fixture / helper cost impact**: use existing factories/helpers; any new helper must stay cheap and explicit. - **Heavy-family visibility / justification**: matrix-style discovery may be heavy-governance if implemented as broad guard; keep it explicit and not in narrow lanes accidentally. - **Special surface test profile**: global-context-shell for workspace/environment scope; standard-native-filament for ordinary resources; system-admin for `/system`; browser for representative proof. - **Standard-native relief or required special coverage**: standard resources need focused direct/access/action tests; high-risk actions and system boundary require browser proof. - **Reviewer handoff**: reviewers verify lane fit, fixture cost, negative tests for every fixed gap, and no broad helper drift. - **Budget / baseline / trend impact**: none expected; document if test runtime materially increases. - **Escalation needed**: document-in-feature by default; follow-up-spec if a structural authorization framework decision is required. - **Active feature PR close-out entry**: `Guardrail / Exception / Smoke Coverage`. - **Planned validation commands**: - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Policy` - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Authorization` - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Capability` - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Filament` - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Resource` - `cd apps/platform && ./vendor/bin/sail artisan test --filter=System` - targeted Spec 402 test files created during implementation - focused browser command for the Spec 402 browser smoke if available - `git diff --check` ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Build the resource authorization matrix (Priority: P1) As an engineering reviewer, I want a complete matrix of admin/system resource-backed surfaces, authorization mechanisms, scope decisions, search posture, relation/bulk posture, and tests, so I can tell which resources are explicitly safe, fixed, deferred, or failed. **Independent Test**: Inspect the implementation report. Every inspected resource has a decision of `OK: explicit policy`, `OK: explicit gate/capability`, `OK: documented exception`, `FIXED: policy added`, `FIXED: authorization hardened`, `DEFERRED: product decision required`, or `FAIL: unsafe or unproven`. ### User Story 2 - Prove admin workspace/environment isolation (Priority: P1) As a workspace operator, I want admin resources to show and mutate only records in my authorized workspace/environment, so direct URLs, action calls, relation managers, exports, and global search cannot leak another workspace's data. **Independent Test**: Focused tests prove allowed user can list/view an authorized record, cross-workspace user receives deny-as-not-found on guessed URLs and action targets, relation managers do not expose unrelated records, and sensitive global search is disabled or scoped. ### User Story 3 - Prove system/admin separation (Priority: P1) As a platform operator, I want `/system` to stay separate from `/admin`, so normal workspace admins cannot access system-only directory, operations, repair, or access-log surfaces, while authorized platform users can access intended system pages. **Independent Test**: Focused tests prove workspace admins are denied system pages/actions, platform users with required capabilities can access intended system surfaces, and mutation/repair actions require stronger platform capabilities than read-only diagnostics. ### User Story 4 - Harden only confirmed authorization gaps (Priority: P1) As a maintainer, I want minimal fixes for confirmed unsafe or unproven high-risk paths, so authorization becomes safer without inventing a new RBAC model or adding cosmetic policies that duplicate existing capability logic. **Independent Test**: Every fixed gap has at least one negative test proving unauthorized direct access/action/search/relation/bulk path is blocked and no unauthorized mutation/audit/evidence side effect occurs. ### User Story 5 - Record implementation proof and residual findings (Priority: P1) As a future agent, I want the final report to record dirty state, matrix decisions, changes, tests, browser proof, P0/P1/P2/P3 residuals, and next-step recommendation, so later specs do not assume UI visibility equals authorization. **Independent Test**: The implementation report follows the required Spec 402 structure and classifies remaining findings; `PASS` is used only when no P0/P1 high-risk proof gaps remain. ## Functional Requirements - **FR-402-001**: Implementation MUST record dirty state before and after work, including branch, tracked changes, untracked files, and `git diff --check`. - **FR-402-002**: Implementation MUST inventory existing admin panel resources, system panel pages, model-backed Filament pages, relation managers, controller-backed admin/system routes, policies, gates, capability checks, route middleware, scoped query helpers, global search posture, and relevant tests. - **FR-402-003**: The authorization matrix MUST include columns for 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, and decision. - **FR-402-004**: Every inspected resource-backed surface MUST receive exactly one explicit decision: `OK: explicit policy`, `OK: explicit gate/capability`, `OK: documented exception`, `FIXED: policy added`, `FIXED: authorization hardened`, `DEFERRED: product decision required`, or `FAIL: unsafe or unproven`. - **FR-402-005**: High-impact operational resources MUST have policy/gate/capability proof and direct unauthorized execution tests. - **FR-402-006**: Sensitive workspace/environment data resources MUST have workspace/environment scoping proof and customer/internal boundary proof where applicable. - **FR-402-007**: Governance/audit/proof resources MUST separately prove read access and action access. - **FR-402-008**: System-only resources MUST deny normal workspace admins and explicitly authorize platform users. - **FR-402-009**: Low-risk/read-only/internal resources MAY use documented exceptions only when no unsafe access path exists. - **FR-402-010**: For Eloquent model-backed resources, policies are preferred unless an existing central gate/capability/scoped-query contract is explicitly documented and tested as sufficient. - **FR-402-011**: New policies MUST delegate to existing capability/scope services where those services already define product authorization semantics. - **FR-402-012**: Implementation MUST NOT invent new product roles, permission hierarchy, capability vocabulary, or independent role-string logic. - **FR-402-013**: Static Filament `can*` methods MAY remain only if they delegate to explicit gates/capabilities/policies or are documented as an exception and direct execution remains blocked. - **FR-402-014**: Route middleware alone MUST NOT count as record-level proof unless scoped record resolution, actor entitlement, capability, and action checks are also proven. - **FR-402-015**: Every resource with global search enabled or potentially enabled MUST be classified as globally searchable and authorized, not globally searchable by design, system-only searchable, scoped-search only, or unsafe/missing proof. - **FR-402-016**: Bulk actions MUST be disabled, authorized, or documented with tests proving they cannot bypass per-record authorization. - **FR-402-017**: Relation managers MUST prove parent and related record scoping and must not expose or mutate unrelated records. - **FR-402-018**: Controller-backed downloads, exports, rendered reports, and signed links MUST prove actor authorization to the underlying workspace/environment/customer-safe artifact. - **FR-402-019**: Every fixed authorization gap MUST include a negative test. - **FR-402-020**: Focused browser proof MUST cover representative allowed admin access, cross-workspace denial, system-only denial to workspace admin, one high-impact action hidden/blocked for unauthorized actor, and one global-search posture check where applicable. - **FR-402-021**: Implementation MUST produce the required Spec 402 implementation report with matrix, runtime changes, tests, browser proof, findings, deferred items, validation commands, and recommended next step. ## Non-Functional Requirements - **NFR-402-001**: Keep changes narrowly scoped to authorization proof and minimal hardening. - **NFR-402-002**: Do not introduce schema changes, migrations, new persistent entities, or new product surfaces. - **NFR-402-003**: Preserve completed-spec history and validation artifacts. - **NFR-402-004**: Use existing Laravel 12, Filament v5, Livewire v4, and Pest 4 conventions. - **NFR-402-005**: Avoid broad test-suite expansion; keep heavy-governance/browser cost explicit. - **NFR-402-006**: No secrets, tokens, raw credential payloads, or sensitive raw provider payloads may be logged or added to reports. ## Out of Scope - New roles, new role hierarchy, new permission product model, or new customer-visible permission UX. - Broad RBAC redesign. - New admin, system, customer, or navigation surfaces. - New restore/backup/provider feature behavior beyond authorization hardening. - Evidence anchor/currentness runtime closure. - Management Report PDF staging validation. - Governance artifact lifecycle/retention. - UI audit registry reconciliation. - JSON-to-JSONB data-layer hardening. - Full browser/UX/runtime audit. - Broad service/model/Filament refactor. - Rewriting historical completed specs. ## Acceptance Criteria - Existing admin and system resource-backed surfaces are inventoried. - A Resource Policy & Authorization Matrix is produced. - Every inspected resource has an explicit authorization decision. - Missing policy classes are either added or justified with documented exception. - Existing gates/capabilities are proven where used instead of policies. - Workspace/environment isolation is tested for high-risk resources. - System/admin separation is tested. - Direct unauthorized access is tested for high-risk resources. - Custom actions are execution-authorized and tested where relevant. - Bulk actions are disabled, authorized, or explicitly documented. - Relation manager scoping is tested where relevant. - Global search posture is disabled, scoped, or tested where relevant. - No new product roles/surfaces/concepts are introduced. - Remaining findings are classified P0/P1/P2/P3. - Validation commands and results are included. ## Candidate Gate Rules - **PASS**: no P0 findings remain; no P1 authorization proof gaps remain for high-risk resources; every inspected resource has an explicit matrix decision; targeted tests pass; focused browser proof passes or is not applicable with reason; no new product/authorization model drift is introduced. - **PASS WITH CONDITIONS**: no P0 findings remain; remaining P1 gaps are explicitly bounded and safely deferred; critical high-risk resource authorization is proven; exceptions are documented; remaining work belongs to later specs or lower-risk productization. - **FAIL**: any P0 remains; unsafe cross-workspace access exists; unauthorized high-impact action execution is possible; system-only resources are accessible to workspace admins; customer/reviewer can access internal-only resources; global search leaks sensitive records; authorization behavior requires unresolved product decisions; fixes exceed bounded scope. ## Required Final Implementation Report Structure The future implementation report must use this top-level structure: ```markdown # Spec 402 Implementation Report - Resource Policy & Authorization Proof Matrix ## A. Candidate Gate Result ## B. Scope Confirmation ## C. Dirty State ## D. Resource Policy & Authorization Matrix ## E. Runtime Changes Made ## F. Policies / Gates / Capabilities ## G. Tests Added or Updated ## H. Authorization Proof Summary ## I. Browser Proof ## J. Remaining Findings ## K. Deferred Items ## L. Validation Commands ## M. Recommended Next Step ``` ## Success Criteria - **SC-402-001**: 100% of inspected resource-backed surfaces have a matrix row and decision. - **SC-402-002**: 100% of fixed authorization gaps include a negative test. - **SC-402-003**: High-impact resources prove direct access/action denial. - **SC-402-004**: Cross-workspace, system/admin, and global search boundaries are proven for representative high-risk surfaces. - **SC-402-005**: The final report can recommend Spec 403 only when no P0 remains and any P1 conditions are bounded. - **SC-402-006**: No runtime code outside authorization proof/hardening scope is changed. ## Assumptions - The operator-provided Spec 402 draft is an explicit manual promotion despite the automatic candidate queue being empty. - The existing branch prefix collision with `402-screwfast-website-rebuild` is unrelated to TenantPilot spec artifacts; this package uses the requested Spec ID 402. - `ManagedEnvironment` is the current repo model for managed tenant/environment context; existing tests and some route/copy names may still use tenant terminology. - Spec 401 has no unresolved P0 blocker in its implementation report, but its provider UI residual must be treated as related proof context. - Implementation may create or update `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`. ## Risks - The matrix scope is broad; implementation must avoid turning the work into a full RBAC redesign or broad browser audit. - Existing gate/capability paths may be safe but under-documented; the report must distinguish missing proof from unsafe behavior. - Adding policies without understanding existing capability services could create contradictory authorization logic. - Focused browser proof may require fixtures; any fixture expansion must be explicit and bounded. - Product decisions may be required for genuinely ambiguous system/admin/customer boundaries; those must be deferred rather than invented. ## Open Questions None blocking preparation. During implementation, if a resource's intended authorization decision cannot be derived from existing contracts, record `DEFERRED: product decision required` and stop before inventing semantics. ## Follow-Up Spec Candidates - Spec 403 - Evidence Anchor & Currentness Runtime Closure, only after Spec 402 reaches at least `PASS WITH CONDITIONS` without P0. - Provider readiness/onboarding productization if provider proof reveals UX friction but no authorization defect. - Dedicated authorization remediation spec if Spec 402 returns `FAIL` or leaves P0/P1 blockers too large for bounded fixes.