ahmido e1a7752f40 chore: finalize high risk admin action proof pack (#472 )

Automated PR created by Codex automation.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #472

2026-06-23 00:24:08 +00:00

27 KiB

Raw Permalink Blame History

Implementation Plan: Spec 401 - High-risk Admin Action Proof Pack

Branch: 401-high-risk-admin-action-proof-pack | Date: 2026-06-22 | Spec: specs/401-high-risk-admin-action-proof-pack/spec.md Input: Feature specification from specs/401-high-risk-admin-action-proof-pack/spec.md

Summary

Prepare a targeted proof and minimal-hardening implementation package over existing restore, backup, and provider setup/detail admin flows. The implementation must first inventory current actions and tests, then build a proof map, add focused tests and browser proof for missing coverage, apply only minimal in-scope hardening defects, and close out with evidence that no new surfaces, concepts, persisted truth, or completed-spec rewrites were introduced.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4. Primary Dependencies: Laravel, Filament v5, Livewire v4, Pest 4, PostgreSQL via Sail, existing Spec Kit artifacts, Product Surface Contract, existing OperationRun/audit/evidence/provider/restore/backup support classes. Storage: No new database table, migration, persisted product truth, or storage disk expected. Existing tables inspected or touched by tests include restore_runs, backup_sets, backup_items, backup_schedules, provider_connections, managed_environment_permissions, operation_runs, audit_logs, and evidence_snapshots. Testing: Pest Feature/Filament/Livewire tests, Unit tests only where derived state helpers need proof, and one focused Pest Browser smoke. Validation Lanes: confidence + browser; fast-feedback for pure unit/helper tests; PostgreSQL only if implementation unexpectedly touches PostgreSQL-specific behavior; no heavy-governance lane unless proof map reveals a structural guard need and spec is updated. Target Platform: TenantPilot Laravel monolith under apps/platform; Spec Kit package under specs/401-high-risk-admin-action-proof-pack/. Project Type: Laravel web application with Filament admin UI. Performance Goals: No material query or browser-suite expansion. Focused tests should prove high-risk behavior without becoming a broad audit. Constraints: Existing surfaces only; no new routes/pages/navigation/panels/product concepts/status families/persistence/frameworks; no completed-spec rewrites; no external Graph calls in tests/browser proof. Scale/Scope: Three high-risk domains: restore preview/readiness/execution, backup schedules/sets/runs, provider setup/detail/readiness/permissions.

Candidate Selection And Gate Result

Candidate source: direct user-provided Spec 401 draft.
Auto queue status: docs/product/spec-candidates.md reports no safe automatic next-best-prep target; this is a manually supplied candidate.
Completed-spec guardrail: PASS. No 401-* package existed before preparation. Related Specs 333, 335, 364, 390, 394, and 395-400 are read-only context.
Smallest slice: proof map + focused tests + minimal hardening for existing high-risk actions only.
Close alternatives deferred: management-report PDF runtime validation, governance artifact lifecycle, provider onboarding redesign, cross-domain indicator follow-through, and reopening recent completed specs.

Repository Surfaces Likely Affected

Restore:

apps/platform/app/Filament/Resources/RestoreRunResource.php
apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php
apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php
apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php
apps/platform/resources/views/filament/forms/components/restore-run-*.blade.php
apps/platform/resources/views/filament/infolists/entries/restore-*.blade.php
apps/platform/app/Jobs/ExecuteRestoreRunJob.php
apps/platform/app/Support/Operations/Reconciliation/RestoreExecuteReconciliationAdapter.php
apps/platform/app/Services/Intune/RestoreService.php
apps/platform/app/Services/Intune/RestoreRiskChecker.php
apps/platform/app/Services/AssignmentRestoreService.php

Backup:

apps/platform/app/Filament/Resources/BackupScheduleResource.php
apps/platform/app/Filament/Resources/BackupScheduleResource/Pages/*
apps/platform/app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleOperationRunsRelationManager.php
apps/platform/app/Filament/Resources/BackupSetResource.php
apps/platform/app/Filament/Resources/BackupSetResource/Pages/*
apps/platform/app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php
apps/platform/app/Jobs/RunBackupScheduleJob.php
apps/platform/app/Jobs/AddPoliciesToBackupSetJob.php
apps/platform/app/Jobs/RemovePoliciesFromBackupSetJob.php
apps/platform/app/Services/BackupScheduling/*
apps/platform/app/Services/AssignmentBackupService.php
apps/platform/app/Support/BackupHealth/*
apps/platform/app/Support/BackupQuality/*

Provider:

apps/platform/app/Filament/Resources/ProviderConnectionResource.php
apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/*
apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php
apps/platform/resources/views/filament/infolists/entries/provider-*.blade.php
apps/platform/resources/views/filament/widgets/provider-connections/provider-readiness-guidance.blade.php
apps/platform/app/Services/Providers/*
apps/platform/app/Support/Providers/*
apps/platform/app/Services/Intune/ManagedEnvironmentPermissionService.php
apps/platform/app/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php
apps/platform/app/Jobs/ProviderConnectionHealthCheckJob.php

Shared proof and safety:

apps/platform/app/Filament/Pages/Monitoring/Operations.php
apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
apps/platform/app/Filament/Pages/Monitoring/AuditLog.php
apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
apps/platform/app/Support/OpsUx/*
apps/platform/app/Support/OperationRunLinks.php
apps/platform/app/Services/OperationRunService.php
apps/platform/app/Services/Audit/*
apps/platform/app/Models/OperationRun.php
apps/platform/app/Models/AuditLog.php

Likely test surfaces:

apps/platform/tests/Feature/Filament/Spec401HighRiskAdminActionProofPackTest.php
apps/platform/tests/Feature/Operations/Spec401HighRiskAdminActionProofPackTest.php
apps/platform/tests/Feature/ProviderConnections/Spec401HighRiskAdminActionProofPackTest.php
apps/platform/tests/Feature/BackupScheduling/Spec401HighRiskAdminActionProofPackTest.php
apps/platform/tests/Browser/Spec401HighRiskAdminActionProofPackSmokeTest.php
specs/401-high-risk-admin-action-proof-pack/implementation-report.md

Exact test-file split may be adjusted during implementation to fit existing test organization, but every task must keep the Spec 401 prefix or report mapping.

Implementation Method

Phase 1 - Read-only inventory

Record current branch, HEAD, dirty state, related routes, Filament resources/pages/actions, Livewire/Blade components, models, policies/gates/capabilities, migrations/schema, existing tests, and recent spec evidence. Do not edit runtime files before the proof map exists.

Phase 2 - Proof gap mapping

Create a Spec 401 proof map in implementation-report.md or a spec-local proof-map.md if the map is too large. Each row must include:

Flow
State
Existing proof
Missing proof
Fix needed?
Test needed?
Browser proof needed?
Out of scope?
Classification

Phase 3 - Tests first

Add or update tests in this preferred order:

Authorization/direct-invocation tests.
State semantics tests.
Confirmation/cancel tests.
Audit/evidence side-effect tests.
Browser smoke proof.

Phase 4 - Minimal hardening

Fix only confirmed in-scope defects required by existing product contracts. Acceptable fixes include missing confirmation, missing server-side authorization, stale action execution guard, wrong partial/failed/blocking display, false audit/evidence creation, or raw detail exposure on default product paths. Stop and update spec/plan if a fix requires new surfaces, new persistence, new status vocabulary, broad resource decomposition, or a new architecture layer.

Phase 5 - Browser proof and close-out

Run focused browser proof for restore, backup, provider, and one unauthorized/blocked path. Complete implementation report with files changed, tests, browser proof, states proven/deferred, Product Surface fields, deployment impact, no completed-spec rewrite assertion, and visible complexity outcome.

UI / Surface Guardrail Plan

Guardrail scope: existing high-risk operator-facing surfaces may be minimally hardened.
Affected routes/pages/actions/states/navigation/panel/provider surfaces: RestoreRun create/view/list, BackupSchedule list/create/edit/run, BackupSet list/create/view/items, ProviderConnection list/create/view/edit, EnvironmentRequiredPermissions, OperationRun/audit/evidence links where already exposed.
No-impact class: N/A.
Native vs custom classification summary: mixed. Prefer native Filament actions/resources and shared primitives; existing custom Blade/presenter fragments may be touched only when proof gaps require it.
Shared-family relevance: destructive/high-impact actions, OperationRun links/start UX, provider readiness, restore readiness, backup quality, audit/evidence links, status messaging.
State layers in scope: page, detail, modal/action, table/relation manager, and route/query context. Shell/navigation/panel state is out of scope unless implementation finds a direct high-risk action leak.
Audience modes in scope: operator-MSP and support-platform. No new customer-facing surface.
Decision/diagnostic/raw hierarchy plan: decision-first default; diagnostics and raw/support proof hidden, demoted, or capability-gated.
Raw/support gating plan: keep raw provider payloads, credentials, source keys, raw evidence, raw backup payloads, and technical logs out of default product surfaces.
One-primary-action / duplicate-truth control: each changed surface keeps one dominant next safe action and avoids duplicate readiness/status summaries.
Handling modes by drift class or surface: in-scope proof gaps are fixed if safe and bounded; missing product contracts become document-in-feature or follow-up-spec; broad architecture becomes stop condition.
Repository-signal treatment: review-mandatory for high-risk actions; exception-required for any Product Surface budget or action-contract deviation.
Special surface test profiles: dangerous-workflow wizard, shared-detail-family, monitoring-state-page, standard-native-filament where applicable.
Required tests or manual smoke: Feature/Filament tests plus focused browser smoke.
Exception path and spread control: none planned. Exceptions must be named in the implementation report.
Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
UI/Productization coverage decision: existing coverage remains valid by default; update coverage artifacts only if implementation materially changes surface classification or finds registry drift.
Coverage artifacts to update: none planned.
No-impact rationale: N/A.
Screenshot or page-report need: focused browser proof required; full page reports not required by default.

Product Surface Contract Plan

Product Surface Contract reference: docs/product/standards/product-surface-contract.md.
No-legacy posture: clean canonical behavior; no compatibility shims or legacy fixtures by default.
Page archetype and surface budget plan: keep existing archetypes; document any materially touched surface as Wizard, Receipt, Search/Index, Settings, Decision sub-surface, or Technical Annex; expect pass.
Technical Annex and deep-link demotion plan: OperationRun/raw evidence/raw IDs/source keys/fingerprints/payloads/logs remain secondary, internal, or gated.
Canonical status vocabulary plan: visible product statuses map to existing Product Surface vocabulary. No new status family.
Product Surface exceptions: none planned.
Browser verification plan: focused Spec 401 browser smoke over restore, backup, provider, and one unauthorized/blocked path.
Human Product Sanity plan: complete in implementation report.
Visible complexity outcome target: neutral or decreased.
Implementation report target: specs/401-high-risk-admin-action-proof-pack/implementation-report.md unless final response carries the full report and the operator accepts no file output.

Filament / Livewire / Deployment Posture

Livewire v4 compliance: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire v3 APIs allowed.
Panel provider registration location: apps/platform/bootstrap/providers.php; no panel provider change expected.
Global search posture: no global search change expected. Any touched globally searchable resource must have View/Edit plus $recordTitleAttribute, or global search disabled.
Destructive/high-impact action posture:
- Touched destructive/high-impact actions must execute through Action::make(...)->action(...).
- Touched destructive/high-impact actions must include ->requiresConfirmation().
- Backup action proof must classify each touched backup action by existing contract source before asserting whether confirmation is required.
- URL-only actions remain navigation-only and are not confirmation-protected.
- Server-side Gate/Policy authorization and audit/proof side effects must be tested.
Asset strategy: no new assets. No FilamentAsset registration and no filament:assets deployment change expected.
Testing plan: Feature/Filament action tests, direct authorization/action execution tests, audit/evidence side-effect tests, state semantics tests, focused browser smoke.
Deployment impact: none expected for env vars, migrations, queues, scheduler, storage, assets, provider scopes, or Dokploy. If an existing job/action path is touched, document queue impact but do not add new workers.

Shared Pattern & System Fit

Cross-cutting feature marker: yes.
Systems touched: existing Filament action APIs, UiEnforcement / WorkspaceUiEnforcement, policies/gates, OperationRun UX, provider readiness, restore readiness, backup quality/health, audit/evidence links.
Shared abstractions reused: existing helpers/services/presenters should be reused before adding local logic.
New abstraction introduced? why?: none planned. A small local test helper is allowed only if it reduces duplicated test setup and stays explicit.
Why existing abstractions are sufficient or insufficient: existing action, authorization, OperationRun, provider, restore, backup, and audit paths cover the proof categories. The gap is evidence coverage, not a missing runtime framework.
Bounded deviation / spread control: any local deviation must be documented in the implementation report and must not create a parallel operator-facing language.

OperationRun UX Impact

Touches OperationRun start/completion/link UX?: yes where existing restore/backup/provider actions create, queue, block, complete, reconcile, or link runs.
Central contract reused: existing OperationRun Start UX Contract, OperationUxPresenter, OperationRunLinks, OperationRunService, OperationRunCompleted.
Delegated UX behaviors: queued toast, run link, artifact link, browser event, dedupe/blocked/start-failure messaging, tenant/workspace-safe URL resolution, terminal notification.
Surface-owned behavior kept local: domain input collection, confirmation copy, and proof display.
Queued DB-notification policy: unchanged; no new queued DB notification.
Terminal notification path: central lifecycle mechanism.
Exception path: none planned.

Provider Boundary & Portability Fit

Shared provider/platform boundary touched?: yes.
Provider-owned seams: Microsoft/Intune/Entra connection details, provider verification reports, required Graph permission evidence, provider errors, provider credentials/consent.
Platform-core seams: workspace, managed environment, provider connection reference, operation, evidence, audit, readiness, blocked/failed/expired state display, action authorization.
Neutral platform terms / contracts preserved: workspace, managed environment, provider, connection, operation, evidence, audit trail, backup, restore, readiness.
Retained provider-specific semantics and why: current runtime is Microsoft-backed; provider-specific details stay in technical/provider-owned layers.
Bounded extraction or follow-up path: follow-up-spec only if proof uncovers structural provider coupling beyond this minimal hardening slice.

Domain / Model Implications

No new model, migration, enum, table, persisted artifact, provider integration, Graph contract, operation type, queue, scheduler, or customer-output artifact is expected.

Existing model relationships and policies must be inspected before tests/hardening. If a required test cannot be written because ownership or scope is ambiguous, record product-decision debt.

RBAC / Security / Audit Implications

Non-members and wrong-scope actors remain 404.
Members missing capability remain 403 or disabled/hidden per current UI enforcement.
Direct action invocation must be tested; hidden buttons are not proof.
Mutating actions must write audit entries where existing contracts require audit.
Cancelled and forbidden actions must not write successful audit/evidence/OperationRun proof.
Provider credentials, raw tokens, raw provider payloads, raw tenant data, and secrets must never appear in tests, logs, screenshots, or implementation reports.

OperationRun / Evidence / Result Truth Implications

The implementation must distinguish:

Execution truth: OperationRun status/outcome/summary/failure/audit trail.
Artifact truth: evidence snapshots, stored report/review artifacts where already linked.
Backup/snapshot truth: backup sets/items/schedules and immutable captured payload truth.
Recovery/evidence truth: restore preview/readiness/result, stale/failed/partial proof, provider prerequisites.
Operator next action: the single safe action or blocked/deferred state shown to the operator.

No product surface may collapse these truths into one false success state.

Constitution Check

Inventory-first: PASS. Existing inventory/backup/provider/restore truth remains authoritative.
Read/write separation: PASS planned. Restore/backup/provider mutations require preview/dry-run where existing, confirmation, audit, and tests.
Graph contract path: PASS planned. No new Graph calls; existing calls remain behind current abstractions.
Deterministic capabilities: PASS planned. Use existing capability registry/policies; no raw role checks.
RBAC-UX: PASS planned. Direct invocation tests cover 404/403 boundaries and server-side authorization.
Workspace isolation: PASS planned. Tests must prove workspace/environment scope.
Tenant isolation: PASS planned. No cross-tenant leakage or ID shortcuts.
Run observability: PASS planned. Existing long-running/high-impact operations use/reuse OperationRun; no new local run UX.
OperationRun start UX: PASS planned. Existing shared paths reused.
Ops-UX 3-surface feedback: PASS planned. No new queued DB notification or local terminal notification.
Data minimization: PASS planned. No secrets/raw provider payloads in output.
Test governance: PASS planned. Confidence + browser lanes are explicit and bounded.
Proportionality: PASS. Proof map/tests/minimal hardening are narrower than a framework.
No premature abstraction: PASS. No new runtime abstraction planned.
Persisted truth: PASS. No new persistence planned.
Behavioral state: PASS. Existing states/vocabulary only.
UI semantics: PASS. Use Product Surface vocabulary and existing shared badge/status paths.
Shared pattern first: PASS. Existing shared paths are named and preferred.
Provider boundary: PASS. Provider-specific semantics remain provider-owned.
V1 explicitness / few layers: PASS. Direct tests and local hardening only.
Spec discipline / bloat check: PASS. One coherent proof-pack spec instead of many micro-specs.
Filament-native UI: PASS planned. Native Filament/shared primitives first.
UI/Productization coverage: PASS planned. Existing surfaces only; coverage updates only if material classification drift appears.
Product Surface Contract Gate: PASS planned. Spec/plan/tasks name surfaces, browser proof, human sanity, destructive/high-impact actions, deployment impact, and no completed-spec rewrite assertion.

Test Governance Check

Test purpose / classification by changed surface: Feature/Filament for action/authorization/state/audit proof; Browser for focused rendered workflow proof; Unit only for derived state helpers if touched.
Affected validation lanes: confidence + browser; fast-feedback for unit-only changes; PostgreSQL only if database-specific behavior changes unexpectedly.
Why this lane mix is the narrowest sufficient proof: Direct action behavior and side effects require Feature/Filament tests. Rendered confirmation/status behavior needs focused Browser smoke. Broad heavy-governance is not needed for a bounded proof pack.
Narrowest proving command(s):
- cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/Operations/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/ProviderConnections/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/BackupScheduling/Spec401HighRiskAdminActionProofPackTest.php --compact
- cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec401HighRiskAdminActionProofPackSmokeTest.php --compact
- cd apps/platform && ./vendor/bin/sail pint --dirty
- git diff --check
Fixture / helper / factory / seed / context cost risks: use existing explicit workspace/environment/provider/backup/restore fixtures; do not widen default setup.
Expensive defaults or shared helper growth introduced?: no planned; any helper must be opt-in.
Heavy-family additions, promotions, or visibility changes: one named focused browser smoke only.
Surface-class relief / special coverage rule: dangerous-workflow wizard and shared-detail-family for restore; standard-native-filament for ordinary lists/actions; monitoring-state-page where OperationRun proof is touched.
Closing validation and reviewer handoff: reviewers verify proof map completeness, task coverage, test commands/results, browser proof, no secrets/screenshots leak, Product Surface close-out, and no completed-spec rewrites.
Budget / baseline / trend follow-up: none expected; document-in-feature if browser fixture cost grows.
Review-stop questions: Did implementation add a new surface/status/persistence? Did cancelled/forbidden actions avoid success artifacts? Did direct invocation get tested? Did browser proof stay focused? Did raw detail remain demoted?
Escalation path: document-in-feature for contained proof gaps; follow-up-spec for structural missing product contracts; reject-or-split for broad redesign.
Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
Why no dedicated follow-up spec is needed now: this spec is the bounded proof pack. Follow-ups are created only for confirmed out-of-scope defects or product-decision gaps.

Project Structure

Spec Package

specs/401-high-risk-admin-action-proof-pack/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── implementation-report.md   # created during implementation close-out if file output is used

Source Code

apps/platform/app/
├── Filament/
├── Jobs/
├── Models/
├── Policies/
├── Services/
└── Support/

apps/platform/resources/views/
└── filament/

apps/platform/tests/
├── Feature/
├── Unit/
└── Browser/

Structure Decision: Use existing Laravel/Filament monolith structure. Do not create new base folders. New tests should live in existing test families with Spec 401 naming.

Complexity Tracking

No constitution violation is planned.

Potential Complexity	Decision	Simpler Alternative
Cross-domain proof map	Allowed as spec-local review evidence	One-off local notes would not cover all high-risk domains consistently
Focused browser smoke	Allowed because rendered high-risk flows are in scope	Feature tests alone cannot prove browser/Livewire/Filament runtime behavior
Minimal runtime hardening	Allowed only after failing/missing proof confirms an in-scope defect	Broad refactor or framework explicitly rejected

Implementation Phases

Safety, inventory, and proof map.
Restore tests and minimal hardening.
Backup tests and minimal hardening.
Provider tests and minimal hardening.
Cross-domain browser proof.
Implementation report and validation.

Stop Conditions

Stop and update spec/plan before continuing if:

implementation requires a new persisted entity/table/artifact;
implementation requires a new enum/status/reason family;
implementation requires a new route/page/navigation group/panel;
implementation requires a broad restore, backup, provider, OperationRun, or Product Surface framework;
a required state lacks a product contract and cannot be safely derived from repo truth;
unrelated dirty state appears;
browser/test fixture work expands into a broad audit;
any completed spec would need to be rewritten to make the proof pass.

Rollout / Deployment Considerations

Staging: run focused tests and browser smoke before staging validation if runtime code changes.
Production: no special production rollout expected. If existing high-impact action behavior changes, release notes should call out safer confirmation/authorization/state handling.
Migrations: none expected.
Env vars: none expected.
Queues: existing queue workers only; no new queue class expected unless minimal hardening touches existing jobs.
Scheduler: no change expected.
Storage: no change expected.
Assets: no new assets; filament:assets unchanged.

Risk Controls

Tests before fixes wherever feasible.
Direct invocation tests, not only hidden/disabled UI assertions.
Separate execution truth from backup/artifact/evidence truth.
Treat missing product contract as finding, not implementation invitation.
Keep browser proof focused and evidence-backed.
Preserve historical spec close-out and validation history.

27 KiB Raw Permalink Blame History