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

# 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.