TenantAtlas/specs/152-livewire-context-locking/quickstart.md

Quickstart: Livewire Context Locking and Trusted-State Reduction

Goal

Harden tier-1 Livewire and Filament surfaces so that public component state supports continuity and UX, but never becomes authority for protected actions.

Implementation Order

1. Inventory the first-slice component fields and classify them as presentation, locked identity, or server-derived authority.
2. Replace ownership-relevant public model objects on the onboarding wizard with locked scalar IDs or resolver-backed access.
3. Normalize onboarding action methods so each protected action re-resolves draft, tenant, workspace, and selected provider connection before use.
4. Tighten the tenant required permissions page so route-derived tenant scope remains authoritative and filter state remains presentation-only.
5. Tighten the system runbooks page so selected tenant IDs remain validated proposals and cannot bypass AllowedTenantUniverse.
6. Extend existing forged-state and resolver guard tests instead of introducing a parallel guard suite.
7. Add or update one lightweight architectural guard for covered public authority fields, implementation markers, and first-slice action-surface status.
8. Add automated non-regression assertions for onboarding continuity and runbook selector query boundaries.
9. Run focused Pest coverage and format changed files with Pint.

Suggested Code Touches

app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
app/Filament/Pages/TenantRequiredPermissions.php
app/Filament/System/Pages/Ops/Runbooks.php
app/Filament/Concerns/ResolvesPanelTenantContext.php
app/Support/Workspaces/WorkspaceContext.php
app/Services/Onboarding/*
tests/Feature/Onboarding/*
tests/Feature/Guards/*
tests/Feature/Rbac/*

Validation Flow

Run the minimum focused suites first:

vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/LivewireTrustedStateGuardTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/AdminTenantResolverGuardTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/NoAdHocFilamentAuthPatternsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillPreflightTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillStartTest.php
vendor/bin/sail bin pint --dirty --format agent

The focused onboarding and runbook suites should include automated assertions that trusted-state hardening does not add broad resolver-query fan-out or break legitimate render and continuity paths.

If the first slice touches additional guard files, run those focused tests before expanding coverage.

Manual Smoke Checklist

1. Open /admin/onboarding/{onboardingDraft} for a valid draft and verify normal resume behavior still works.
2. Change provider connection through the intended UI and confirm verification still uses the selected in-scope connection.
3. Attempt a forged or stale target in a Livewire test or browser devtools scenario and confirm the request fails closed.
4. Open /admin/tenants/{tenant}/required-permissions and confirm filters remain usable while tenant scope stays fixed.
5. Open /system/ops/runbooks, switch between all-tenant and single-tenant scope, and confirm unauthorized tenant selections are rejected.
6. Re-run the trusted-state and guard suites after any future component adopts this pattern, and update the first-slice policy inventory before expanding exemptions.

Exit Criteria

1. Tier-1 components no longer depend on mutable public authority state for protected actions.
2. Forged-state regression coverage exists for onboarding, tenant-context, and system-page slices.
3. Existing operator UX and legitimate refresh or resume behavior remain intact.
4. Automated non-regression assertions cover onboarding continuity and runbook selector query boundaries.
5. No new panel, route, asset, or Graph contract change was introduced.