ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
eaf28229e0
TenantAtlas/specs/402-resource-policy-authorization-proof-matrix/spec.md
Ahmed Darrazi eaf28229e0
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m7s
Details
feat: add resource policy authorization proof matrix
2026-06-23 09:44:21 +02:00

44 KiB
Raw Blame History

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:

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
  • 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
  • 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
    • 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)

  • No-legacy posture or approved exception recorded.
  • Product Surface Impact is completed for existing-surface authorization hardening.
  • Browser proof is required for representative authorization surfaces during implementation.
  • Human Product Sanity is required for changed rendered behavior.
  • Product Surface exceptions are documented as none planned.
  • 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:

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