211 lines
16 KiB
Markdown
211 lines
16 KiB
Markdown
# Tasks: Livewire Context Locking and Trusted-State Reduction
|
|
|
|
**Input**: Design documents from `/specs/152-livewire-context-locking/`
|
|
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md
|
|
|
|
**Tests**: Tests are REQUIRED for this feature because it changes runtime authorization, Livewire trusted-state handling, tenant and workspace isolation, and forged-state fail-closed behavior in a Laravel/Pest codebase.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Establish the shared trusted-state scaffolding and guard baseline used by all stories.
|
|
|
|
- [x] T001 Create the first-slice trusted-state file skeleton and initial policy inventory stubs in `app/Support/Livewire/TrustedState/TrustedStateClass.php`, `app/Support/Livewire/TrustedState/TrustedStatePolicy.php`, and `app/Support/Livewire/TrustedState/TrustedStateResolver.php`
|
|
- [x] T002 [P] Create the Livewire trusted-state architectural guard test harness and first-slice fixture list in `tests/Feature/Guards/LivewireTrustedStateGuardTest.php`
|
|
- [x] T003 [P] Add shared Pest helpers `mutateTrustedStatePayload()` and `assertScopedSelectorRejected()` in `tests/Pest.php` for reuse by onboarding, tenant required permissions, and runbook selector suites
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Put the reusable trusted-state and resolver rules in place before component-specific work starts.
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
|
|
|
|
- [x] T004 Implement the shared trusted-state lane and resolver contract in `app/Support/Livewire/TrustedState/TrustedStateClass.php`, `app/Support/Livewire/TrustedState/TrustedStatePolicy.php`, and `app/Support/Livewire/TrustedState/TrustedStateResolver.php`
|
|
- [x] T005 [P] Wire shared workspace, tenant, and onboarding authority re-resolution into `app/Support/Workspaces/WorkspaceContext.php`, `app/Filament/Concerns/ResolvesPanelTenantContext.php`, `app/Services/Onboarding/OnboardingDraftResolver.php`, and `app/Services/Onboarding/OnboardingDraftMutationService.php`
|
|
- [x] T006 [P] Wire shared platform selector validation into `app/Services/System/AllowedTenantUniverse.php` and `app/Filament/System/Pages/Ops/Runbooks.php`
|
|
- [x] T007 Update the architectural guard allowlists for the first-slice surfaces in `tests/Feature/Guards/AdminTenantResolverGuardTest.php` and `tests/Feature/Guards/NoAdHocFilamentAuthPatternsTest.php`
|
|
|
|
**Checkpoint**: The trusted-state contract, canonical resolver seams, and guard baseline exist, so user story work can proceed in parallel.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Trust ownership-sensitive wizard actions (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Ensure onboarding wizard actions derive draft, workspace, tenant, and provider truth from locked or server-resolved state instead of mutable public Livewire authority.
|
|
|
|
**Independent Test**: A user can resume and operate a valid onboarding draft normally, while forged or stale draft, workspace, tenant, or provider values fail closed and execute no protected action.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [x] T008 [P] [US1] Extend forged-draft and stale-workspace coverage in `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`, `tests/Feature/Onboarding/OnboardingDraftAccessTest.php`, and `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
|
|
- [x] T009 [P] [US1] Extend forged provider-selection and stale-target coverage in `tests/Feature/Onboarding/OnboardingProviderConnectionTest.php`, `tests/Feature/Onboarding/OnboardingActivationTest.php`, and `tests/Feature/Onboarding/OnboardingVerificationTest.php`
|
|
- [x] T010 [P] [US1] Extend onboarding 404 versus 403 parity coverage for trusted-state failures in `tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php` and `tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
|
|
- [x] T011 [P] [US1] Preserve onboarding audit-log and operation-history coverage during trusted-state hardening in `tests/Feature/Onboarding/OnboardingActivationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationAssistTest.php`, and `tests/Feature/Onboarding/OnboardingVerificationTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [x] T012 [US1] Replace ownership-relevant public model authority in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` with locked scalar identity or resolver-backed access while preserving wizard continuity
|
|
- [x] T013 [US1] Rework protected onboarding actions in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingDraftMutationService.php` to re-resolve draft, workspace, and tenant truth before verify, bootstrap, cancel, delete, and activate paths
|
|
- [x] T014 [US1] Re-scope mutable provider selection through canonical draft and tenant validation in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingDraftResolver.php`
|
|
- [x] T015 [US1] Preserve resume and display behavior through computed or resolver-backed model access in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `resources/views/filament/pages/workspaces/managed-tenant-onboarding-wizard.blade.php`
|
|
|
|
**Checkpoint**: The onboarding wizard is independently safe against forged state and remains fully usable as the MVP slice.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Keep non-wizard stateful pages safe under forged state (Priority: P1)
|
|
|
|
**Goal**: Ensure tenant-context and system pages treat public selectors and filters as untrusted input while keeping legitimate UX intact.
|
|
|
|
**Independent Test**: A route-bound tenant page and a system runbook page continue to work with normal filters and selectors, but forged tenant-like or runbook target state cannot redefine authority or execute against unauthorized targets.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [x] T016 [P] [US2] Add tenant-context trusted-state coverage in `tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php` and `tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php`
|
|
- [x] T017 [P] [US2] Extend system runbook selector forged-state coverage in `tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillPreflightTest.php`, `tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillStartTest.php`, and `tests/Feature/System/Spec113/AllowedTenantUniverseTest.php`
|
|
- [x] T018 [P] [US2] Add explicit positive-path continuity coverage for normal tenant filters and allowed runbook selections in `tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php` and `tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillPreflightTest.php`
|
|
- [x] T019 [P] [US2] Extend cross-plane and capability-parity coverage for covered non-wizard surfaces in `tests/Feature/System/Spec113/AuthorizationSemanticsTest.php` and `tests/Feature/System/Spec113/TenantPlaneCannotAccessSystemTest.php`
|
|
- [x] T020 [P] [US2] Preserve system runbook audit-log and operation-history coverage during trusted-state hardening in `tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillStartTest.php` and `tests/Feature/System/OpsRunbooks/OpsUxStartSurfaceContractTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [x] T021 [US2] Convert tenant authority on `app/Filament/Pages/TenantRequiredPermissions.php` to route- or resolver-derived scope while keeping `status`, `type`, `features`, and `search` presentation-only
|
|
- [x] T022 [US2] Re-validate runbook tenant selectors against the platform operator universe on every protected path in `app/Filament/System/Pages/Ops/Runbooks.php` and `app/Services/System/AllowedTenantUniverse.php`
|
|
- [x] T023 [US2] Normalize deny-as-not-found versus forbidden semantics for covered non-wizard stateful flows in `app/Filament/Pages/TenantRequiredPermissions.php`, `app/Filament/System/Pages/Ops/Runbooks.php`, and `app/Services/Runbooks/FindingsLifecycleBackfillRunbookService.php`
|
|
|
|
**Checkpoint**: Covered tenant-context and system pages are independently safe against forged selector state without relying on the onboarding wizard changes.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Apply one reusable trusted-state standard to future components (Priority: P2)
|
|
|
|
**Goal**: Make the trusted-state model reusable and enforceable so future Livewire components do not reintroduce mutable authority by convention.
|
|
|
|
**Independent Test**: The repo contains a reusable guard and first-slice field inventory that fail when ownership-relevant public model state or mutable foreign identifiers reappear on covered surfaces without the approved pattern.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [x] T024 [P] [US3] Implement the trusted-state architectural guard assertions in `tests/Feature/Guards/LivewireTrustedStateGuardTest.php`
|
|
- [x] T025 [P] [US3] Extend existing resolver and action-surface guard coverage for the first-slice surfaces in `tests/Feature/Guards/AdminTenantResolverGuardTest.php`, `tests/Feature/Guards/NoAdHocFilamentAuthPatternsTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [x] T026 [US3] Finalize the reusable first-slice field inventory and trusted-state policy map in `app/Support/Livewire/TrustedState/TrustedStatePolicy.php` and `specs/152-livewire-context-locking/data-model.md`
|
|
- [x] T027 [US3] Encode reusable locked-versus-derived helper usage in `app/Support/Livewire/TrustedState/TrustedStateResolver.php`, `app/Support/Livewire/TrustedState/TrustedStateClass.php`, and `specs/152-livewire-context-locking/research.md`
|
|
- [x] T028 [US3] Align the logical contract and rollout checklist with the implemented patterns in `specs/152-livewire-context-locking/contracts/trusted-state-logical.openapi.yaml`, `specs/152-livewire-context-locking/contracts/trusted-state-guard.schema.json`, and `specs/152-livewire-context-locking/quickstart.md`
|
|
|
|
**Checkpoint**: The trusted-state pattern is reusable, documented, and guarded in CI for future component work.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Validate the rollout, keep the branch releasable, and confirm the spec's manual verification paths.
|
|
|
|
- [x] T029 [P] Run the focused Pest validation suite from `specs/152-livewire-context-locking/quickstart.md`
|
|
- [x] T030 [P] Add automated non-regression assertions for first-slice render continuity and canonical resolver-query boundaries in `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php` and `tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillPreflightTest.php`
|
|
- [x] T031 Run formatting with `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [x] T032 [P] Validate the manual smoke checklist in `specs/152-livewire-context-locking/quickstart.md` against `/admin/onboarding/{onboardingDraft}`, `/admin/tenants/{tenant}/required-permissions`, and `/system/ops/runbooks`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies, can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Starts after Foundational completion.
|
|
- **User Story 2 (Phase 4)**: Starts after Foundational completion and can proceed in parallel with US1.
|
|
- **User Story 3 (Phase 5)**: Starts after Foundational completion and should land after at least one first-slice surface has adopted the pattern.
|
|
- **Polish (Phase 6)**: Runs after the desired user stories are complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: No dependency on other stories. This is the recommended MVP slice.
|
|
- **US2**: Depends only on the foundational trusted-state and resolver layer, not on US1 completion.
|
|
- **US3**: Depends on the foundational layer and benefits from US1 and US2 landing first so the guard inventory reflects real adoption.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests MUST be written and fail before implementation.
|
|
- Shared resolver and trusted-state seams must exist before surface-specific rewrites begin.
|
|
- Protected action re-resolution must land before cleanup of public model authority is considered complete.
|
|
- Guard updates should happen after at least one representative implementation proves the pattern.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- T002 and T003 can run in parallel.
|
|
- T005 and T006 can run in parallel.
|
|
- US1 test tasks T008, T009, T010, and T011 can run in parallel.
|
|
- US2 test tasks T016, T017, T018, T019, and T020 can run in parallel.
|
|
- US3 test tasks T024 and T025 can run in parallel.
|
|
- Polish tasks T029, T030, and T032 can run in parallel after implementation is complete.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch the onboarding forged-state regressions together:
|
|
Task: "Extend forged-draft and stale-workspace coverage in tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php, tests/Feature/Onboarding/OnboardingDraftAccessTest.php, and tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php"
|
|
Task: "Extend forged provider-selection and stale-target coverage in tests/Feature/Onboarding/OnboardingProviderConnectionTest.php, tests/Feature/Onboarding/OnboardingActivationTest.php, and tests/Feature/Onboarding/OnboardingVerificationTest.php"
|
|
Task: "Extend onboarding 404 versus 403 parity coverage for trusted-state failures in tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php and tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php"
|
|
|
|
# Then land the wizard implementation in sequence:
|
|
Task: "Replace ownership-relevant public model authority in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php with locked scalar identity or resolver-backed access while preserving wizard continuity"
|
|
Task: "Rework protected onboarding actions in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Services/Onboarding/OnboardingDraftMutationService.php to re-resolve draft, workspace, and tenant truth before verify, bootstrap, cancel, delete, and activate paths"
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch the tenant-context and system-page regressions together:
|
|
Task: "Add tenant-context trusted-state coverage in tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php and tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php"
|
|
Task: "Extend system runbook selector forged-state coverage in tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillPreflightTest.php, tests/Feature/System/OpsRunbooks/FindingsLifecycleBackfillStartTest.php, and tests/Feature/System/Spec113/AllowedTenantUniverseTest.php"
|
|
Task: "Extend cross-plane and capability-parity coverage for covered non-wizard surfaces in tests/Feature/System/Spec113/AuthorizationSemanticsTest.php and tests/Feature/System/Spec113/TenantPlaneCannotAccessSystemTest.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch the reusable guard work together:
|
|
Task: "Implement the trusted-state architectural guard in tests/Feature/Guards/LivewireTrustedStateGuardTest.php"
|
|
Task: "Extend existing resolver and action-surface guard coverage for the first-slice surfaces in tests/Feature/Guards/AdminTenantResolverGuardTest.php, tests/Feature/Guards/NoAdHocFilamentAuthPatternsTest.php, and tests/Feature/Guards/ActionSurfaceContractTest.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Validate onboarding resume, verification, bootstrap, and activation behavior against forged-state regressions.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Land the shared trusted-state and resolver layer.
|
|
2. Harden onboarding as the MVP trust surface.
|
|
3. Add tenant-context and system-page selector hardening.
|
|
4. Finish with the reusable guard and contract alignment so future components inherit the pattern.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One developer lands the foundational trusted-state scaffolding.
|
|
2. A second developer can harden the onboarding wizard while another works on tenant-context and system-page regressions.
|
|
3. A final pass lands the reusable guard and rollout-inventory alignment after the first-slice surfaces are proven.
|
|
|
|
## Notes
|
|
|
|
- [P] tasks are limited to work on different files with no incomplete dependency overlap.
|
|
- US1 is the recommended MVP because it closes the highest-risk Livewire trust boundary first.
|
|
- US2 proves the pattern is not wizard-specific by covering both admin tenant-context and system platform surfaces.
|
|
- US3 turns the first-slice implementation into a reusable, CI-enforced repository standard. |