TenantAtlas/specs/276-support-access-governance/plan.md

# Implementation Plan: Enterprise Access Boundary & Support Access Governance v1

**Branch**: `276-support-access-governance` | **Date**: 2026-05-05 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `specs/276-support-access-governance/spec.md`

## Summary

Prepare one bounded support-access governance slice on top of the repo’s current system support and recovery seams. The narrow implementation path is to introduce one workspace-owned support-access grant history with exactly two scopes, reuse the current system workspace detail page as the request and active-state surface, reuse workspace settings as the owner-approval surface, extend existing system and admin audit views for support-access history, and harden the existing owner-repair utility so it requires both active break-glass and an active recovery-scoped support grant.

This slice stays explicitly narrow. Filament remains v5 on Livewire v4, panel-provider registration stays in `apps/platform/bootstrap/providers.php`, no new globally searchable resource is introduced, and no asset registration change is expected. The plan does not create impersonation, a delegated admin browsing bridge, SCIM, or a second support console.

## Inherited Baseline / Explicit Delta

### Inherited baseline

- `BreakGlassSession`, the system dashboard break-glass actions, and the current system break-glass banner already provide a global emergency recovery control with TTL and audit.
- `RepairWorkspaceOwners` already exposes the current owner-repair utility and audit behavior, but today it only requires platform capability plus active break-glass.
- `ViewWorkspace` already acts as the system-plane workspace detail surface and already owns bounded workspace-scoped admin actions.
- `WorkspaceSettings` already acts as the admin-plane workspace singleton page and already supports workspace-owner-only actions.
- `AuditLog` already acts as the admin-plane customer-visible history surface.
- `AccessLogs` already acts as the system security history surface for platform auth and break-glass events.

### Explicit delta in this plan

- Add one workspace-owned support-access grant history with bounded lifecycle and expiry.
- Add one support-scope catalog with exactly `audit_view` and `workspace_recovery`.
- Add one shared `SupportAccessGrantResolver` or manager so current detail, settings, recovery, and history surfaces consume the same support-access truth.
- Add a request and end flow on `ViewWorkspace`.
- Add owner approval or denial for `workspace_recovery` on `WorkspaceSettings`.
- Extend `AuditLog` with a support-access filter and export path.
- Extend `AccessLogs` with support-access lifecycle events.
- Refactor `RepairWorkspaceOwners` so owner repair requires both active break-glass and an active recovery-scoped support grant for the chosen workspace.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12  
**Primary Dependencies**: Filament v5, Livewire v4, Pest v4, existing `BreakGlassSession`, existing audit infrastructure, existing workspace settings and system workspace detail surfaces  
**Storage**: PostgreSQL via a new workspace-owned `support_access_grants` table plus existing `audit_logs` and current session-backed break-glass state  
**Testing**: Pest v4 `Unit` plus focused `Feature` coverage  
**Validation Lanes**: fast-feedback, confidence
**Target Platform**: Laravel monolith in `apps/platform`, reusing existing admin and system Filament pages  
**Project Type**: Web application (Laravel monolith with Filament panels)  
**Performance Goals**: no new queue family, no Graph calls, and DB-only support-access resolution on current detail, settings, and history surfaces  
**Constraints**: no impersonation, no delegated admin browsing bridge, no SCIM, no new support console, no new global-search resource, and no asset registration changes  
**Scale/Scope**: 1 new workspace-owned entity, 1 bounded resolver or manager, 4 existing page families, and focused extensions to existing auth or audit tests

## Likely Affected Repo Surfaces

- `apps/platform/app/Models/SupportAccessGrant.php` as the new workspace-owned grant model.
- `apps/platform/database/migrations/*_create_support_access_grants_table.php` for new persistence.
- `apps/platform/database/factories/SupportAccessGrantFactory.php` for bounded test setup.
- `apps/platform/app/Services/Auth/SupportAccessGrantResolver.php` and `SupportAccessGrantManager.php` as the shared lifecycle and mutation layer.
- `apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php` for request, end, and active-state summary.
- `apps/platform/app/Filament/System/Pages/RepairWorkspaceOwners.php` for the combined support-access plus break-glass recovery boundary.
- `apps/platform/app/Filament/System/Pages/Security/AccessLogs.php` for system-side support-access history.
- `apps/platform/app/Filament/Pages/Settings/WorkspaceSettings.php` for owner approval or denial and a current support-access summary.
- `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php` for the support-access filter and export path.
- `apps/platform/app/Support/Auth/PlatformCapabilities.php` for new bounded platform-side support-access manage capability.
- `apps/platform/app/Support/Audit/AuditActionId.php`, `WorkspaceAuditLogger`, and `SystemConsoleAuditLogger` for stable support-access audit action IDs and structured metadata.
- `apps/platform/tests/Unit/System/SupportAccessGrantResolverTest.php` plus focused system, auth, settings, monitoring, and access-log feature tests.

## Support Access Fit

- Treat support access as a workspace-owned governance truth, not as an extension of `BreakGlassSession`.
- Keep exactly two scopes in v1 so the slice stays on current repo-real support work:
  - `audit_view`
  - `workspace_recovery`
- Keep support-access lifecycle distinct from break-glass lifecycle.
- Keep owner repair as the one high-risk mutation that requires both active break-glass and active recovery-scoped support access.
- Keep admin history export on the current audit surface rather than adding a second support-history page.

## UI / Filament & Livewire Fit

- Existing operator-facing surfaces remain native Filament surfaces under Livewire v4.
- No new Filament resource or globally searchable resource is required; current pages are sufficient.
- `ViewWorkspace` keeps one dominant support-access action family: request or end support access.
- `WorkspaceSettings` keeps approval scoped to pending `workspace_recovery` requests and must not become a second platform-control plane.
- `AuditLog` and `AccessLogs` stay read-only history surfaces and only expand their filter or event scope.
- Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`, and no new asset strategy is planned. If a later shared asset becomes necessary, deployment remains the standard `cd apps/platform && php artisan filament:assets` path.

## RBAC / Policy Fit

- Workspace and tenant membership remain the primary admin-plane isolation boundaries. Wrong-plane or non-member requests stay `404`; in-scope actors missing capability stay `403`.
- Platform-side request and end actions should use one new bounded `PlatformCapabilities::SUPPORT_ACCESS_MANAGE` capability instead of reusing broad console visibility alone.
- Workspace-owner approval should remain on `WorkspaceSettings` and should reuse existing owner-level manage semantics rather than adding a separate customer support role.
- `AuditLog` export remains tied to the current admin-plane audit view capability.
- Business-state blocking on the recovery page must remain distinguishable from authorization failure.

## Audit / Logging Fit

- Every support-access request, approval, denial, activation, expiry, end, and ownerless waiver must write a stable audit action ID with structured metadata.
- `AuditLog` remains the customer-visible history substrate.
- `AccessLogs` remains the system-side security history substrate and expands to include support-access events.
- No second audit subsystem is needed.

## Data & Query Fit

- `support_access_grants.workspace_id` must be NOT NULL and indexed.
- Prevent overlapping `requested` or `active` grants for the same workspace, platform actor, and scope.
- Keep the v1 table bounded to the fields in `data-model.md`; do not add broad ticketing, provider, or impersonation fields.
- `SupportAccessGrantResolver` should expose a single current summary for the active workspace plus current page context.
- `RepairWorkspaceOwners` should query only the targeted workspace’s active recovery grant, not scan across workspaces.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament
- **Shared-family relevance**: system detail summaries, workspace settings approvals, audit-history filters, system security history, and recovery state messaging
- **State layers in scope**: page, detail
- **Audience modes in scope**: operator-MSP, support-platform
- **Decision/diagnostic/raw hierarchy plan**: decision-first, diagnostics-second, support-raw-third
- **Raw/support gating plan**: raw audit detail remains on existing history surfaces; default-visible content stays on current support posture and approval need
- **One-primary-action / duplicate-truth control**: `ViewWorkspace` remains the one place to start or end support access; `WorkspaceSettings` remains the one place to approve or deny risky recovery; history pages explain rather than re-decide
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory now; future hard-stop candidate if a second support console or impersonation bridge appears inside this slice
- **Special surface test profiles**: standard-native-filament, shared-detail-family, monitoring-state-page, exception-coded-surface
- **Required tests or manual smoke**: functional-core, state-contract, exception-fallback
- **Exception path and spread control**: the recovery page remains the named separately governed exception and must not spread its combined prerequisite logic to unrelated surfaces
- **Active feature PR close-out entry**: Guardrail

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: `ViewWorkspace`, `WorkspaceSettings`, `AuditLog`, `AccessLogs`, `RepairWorkspaceOwners`, `BreakGlassSession`, audit action IDs, and current audit loggers
- **Shared abstractions reused**: current system detail pattern, current singleton settings pattern, current admin audit history, current system access logs, and current audit infrastructure
- **New abstraction introduced? why?**: one bounded `SupportAccessGrantResolver` or manager, because current repo truth has no support-access lifecycle abstraction and several surfaces need the same grant state and dedupe rules
- **Why the existing abstraction was sufficient or insufficient**: current break-glass and audit abstractions are sufficient for emergency recovery and history rendering, but insufficient for one workspace-scoped ordinary support-access lifecycle with approval and expiry
- **Bounded deviation / spread control**: no local page-specific support-access helper is allowed outside the shared resolver or manager path

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no
- **Central contract reused**: `N/A`
- **Delegated UX behaviors**: `N/A`
- **Surface-owned behavior kept local**: request or approval inputs only
- **Queued DB-notification policy**: `N/A`
- **Terminal notification path**: `N/A`
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no
- **Provider-owned seams**: none in this slice
- **Platform-core seams**: support-access grant truth, approval flow, break-glass separation, and workspace-scoped history
- **Neutral platform terms / contracts preserved**: `support access`, `break-glass`, `workspace recovery`, `audit trail review`
- **Retained provider-specific semantics and why**: none
- **Bounded extraction or follow-up path**: future delegated support or impersonation only if promoted by a separate spec

## Constitution Check

*GATE: Must pass before implementation begins and again before merge.*

- Inventory-first / snapshot truth: PASS. This slice does not change tenant inventory or snapshot semantics.
- Read/write separation: PASS. Every mutation is bounded, confirmation-protected where high risk, and audit-backed.
- Graph contract path: PASS. No Graph or provider calls are introduced.
- Deterministic capabilities: PASS. Existing canonical capability registries remain authoritative.
- Workspace and tenant isolation: PASS. Workspace context and wrong-plane `404` remain unchanged.
- RBAC-UX plane separation: PASS. `/system` handles request or end; `/admin` handles approval or history.
- Destructive action discipline: PASS. High-risk approval and recovery remain confirmation-aware.
- Global search safety: PASS. No new searchable resource is added.
- OperationRun / Ops-UX: PASS. No new run family or `OperationRun` start surface is introduced.
- Data minimization: PASS. The new entity stores bounded support-access truth only.
- Test governance: PASS. Proof remains in one new unit family plus focused feature families.
- Proportionality / no premature abstraction: PASS. One new entity and one bounded resolver or manager are the narrowest viable path.
- Persisted truth: PASS. The new table represents independent product truth with its own lifecycle and audit need.
- Behavioral state: PASS. Grant status and approval mode change recovery behavior, expiry, and audit outcomes.
- Shared pattern first / UI semantics / Filament-native UI: PASS. Existing detail, settings, recovery, and history surfaces remain authoritative.
- Provider boundary: PASS. No provider-specific vocabulary or dependency is added.
- Filament / Laravel planning contract: PASS. Filament stays v5 on Livewire v4, provider registration remains in `apps/platform/bootstrap/providers.php`, no globally searchable resource is added, and no asset registration change is planned.

**Gate evaluation**: PASS.

**Post-design re-check**: PASS. `research.md`, `data-model.md`, `quickstart.md`, `contracts/workspace-support-access-governance.logical.openapi.yaml`, `checklists/requirements.md`, and `tasks.md` are present and aligned with the package.

## Test Governance Check

- **Test purpose / classification by changed surface**: `Unit` for grant lifecycle, expiry, and dedupe rules; `Feature` for system detail request flow, owner approval, recovery boundary, and history surfaces
- **Affected validation lanes**: fast-feedback, confidence
- **Why this lane mix is the narrowest sufficient proof**: the slice reuses native Filament and current audit surfaces, so focused unit and feature tests can prove the new truth without browser automation
- **Narrowest proving command(s)**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/System/SupportAccessGrantResolverTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/SupportAccessRequestFlowTest.php tests/Feature/System/SupportAccessRecoveryBoundaryTest.php tests/Feature/Auth/BreakGlassModeTest.php tests/Feature/Auth/BreakGlassWorkspaceOwnerRecoveryTest.php tests/Feature/System/Spec114/AccessLogsTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Settings/WorkspaceSupportAccessApprovalTest.php tests/Feature/Monitoring/AuditLogSupportAccessHistoryTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- **Fixture / helper / factory / seed / context cost risks**: moderate but contained; one new factory is needed, but existing platform user, workspace, membership, and audit fixtures can be reused
- **Expensive defaults or shared helper growth introduced?**: no
- **Heavy-family additions, promotions, or visibility changes**: none planned
- **Surface-class relief / special coverage rule**: standard-native-filament relief for detail, settings, and history surfaces; exception-coded coverage for the recovery boundary
- **Closing validation and reviewer handoff**: reviewers should rely on the exact commands above, confirm that no impersonation bridge or second console appears, verify that recovery still needs active break-glass plus active recovery support access, and verify that support history export remains workspace-safe
- **Budget / baseline / trend follow-up**: none expected beyond a small feature-local increase
- **Review-stop questions**: did the slice add more than two support scopes, did it bypass break-glass on recovery, did it create a second history surface, and did it let admin history leak outside the workspace scope
- **Escalation path**: `document-in-feature` for contained naming drift; `reject-or-split` if the slice widens into impersonation, SCIM, or a second support console
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: routine support-access upkeep should stay inside this feature unless future delegated support or impersonation is explicitly promoted as a separate slice
- **Test-governance outcome**: keep

## Review Checklist Status

- **Review checklist artifact**: `checklists/requirements.md`
- **Review outcome class**: `acceptable-special-case`
- **Workflow outcome**: `keep`
- **Test-governance outcome**: `keep`
- **Escalation rule**: if implementation adds admin-plane browsing, impersonation, SCIM, or a second support console, flip the workflow outcome to `split` before continuing

## Rollout Considerations

- Land persistence and shared resolver or manager first.
- Add workspace detail request or end flow next.
- Add workspace-owner approval next.
- Harden recovery enforcement only after support-access truth exists.
- Add history filter and export last so the customer-visible trail reflects the final lifecycle semantics.
- Keep Filament v5 on Livewire v4, provider registration in `apps/platform/bootstrap/providers.php`, global search unchanged, and assets unchanged.

## Risk Controls

- Reject any implementation that adds impersonation or delegated admin browsing.
- Reject any implementation that lets `workspace_recovery` proceed without active break-glass.
- Reject any implementation that adds more than the two scoped support capabilities in this slice.
- Reject any implementation that creates a second support history or approval surface outside the current detail, settings, and audit pages.
- Reject browser-heavy proof as the default validation lane.

## Research & Design Outputs

- `research.md` resolves the key design choices: workspace-scoped grants, two-scope catalog, recovery plus break-glass coupling, existing-surface reuse, and admin history export.
- `data-model.md` records the new grant entity, state and approval semantics, dedupe rule, and derived summary shape.
- `quickstart.md` provides the bounded reviewer flow, explicit approval and waiver expectations, and focused validation commands.
- `contracts/workspace-support-access-governance.logical.openapi.yaml` captures the logical route and action boundaries for request, approval, end, history, export, and recovery gating.
- `checklists/requirements.md` records the prep-time review outcome, workflow outcome, and test-governance outcome.
- `tasks.md` keeps implementation bounded to current support and recovery surfaces.

## Project Structure

### Documentation (this feature)

```text
specs/276-support-access-governance/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── workspace-support-access-governance.logical.openapi.yaml
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── tasks.md
```

### Source Code (expected implementation surfaces)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── Monitoring/
│   │   │   │   └── AuditLog.php
│   │   │   └── Settings/
│   │   │       └── WorkspaceSettings.php
│   │   └── System/Pages/
│   │       ├── Directory/
│   │       │   └── ViewWorkspace.php
│   │       ├── RepairWorkspaceOwners.php
│   │       └── Security/
│   │           └── AccessLogs.php
│   ├── Models/
│   │   └── SupportAccessGrant.php
│   ├── Services/
│   │   ├── Audit/
│   │   │   └── WorkspaceAuditLogger.php
│   │   ├── Auth/
│   │   │   ├── BreakGlassSession.php
│   │   │   ├── SupportAccessGrantManager.php
│   │   │   └── SupportAccessGrantResolver.php
│   │   └── SystemConsole/
│   │       └── SystemConsoleAuditLogger.php
│   └── Support/
│       ├── Audit/
│       │   └── AuditActionId.php
│       └── Auth/
│           └── PlatformCapabilities.php
├── database/
│   ├── factories/
│   │   └── SupportAccessGrantFactory.php
│   └── migrations/
│       └── *_create_support_access_grants_table.php
└── tests/
    ├── Feature/
    │   ├── Auth/
    │   │   ├── BreakGlassModeTest.php
    │   │   └── BreakGlassWorkspaceOwnerRecoveryTest.php
    │   ├── Filament/Settings/
    │   │   └── WorkspaceSupportAccessApprovalTest.php
    │   ├── Monitoring/
    │   │   └── AuditLogSupportAccessHistoryTest.php
    │   └── System/
    │       ├── Spec114/AccessLogsTest.php
    │       ├── SupportAccessRecoveryBoundaryTest.php
    │       └── SupportAccessRequestFlowTest.php
    └── Unit/
        └── System/
            └── SupportAccessGrantResolverTest.php
```

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| New persisted support-access entity | Support access now needs its own lifecycle, expiry, and approval lineage | Session-only or audit-log-only approaches could not gate recovery and customer-visible approval safely |

## Proportionality Review

- **Current operator problem**: current support and recovery seams lack one bounded workspace-scoped support lifecycle that is both customer-visible and strong enough to gate recovery
- **Existing structure is insufficient because**: `BreakGlassSession` is global and current pages can only infer support state indirectly through scattered audit events
- **Narrowest correct implementation**: one grant history table plus one shared resolver or manager, added to the current system detail, settings, history, and recovery pages only
- **Ownership cost**: one new entity, one new resolver or manager, one new factory, one migration, and focused tests
- **Alternative intentionally rejected**: break-glass-only governance and broad impersonation bridge
- **Release truth**: current-release truth with bounded future preparation only