TenantAtlas/specs/285-workspace-rbac-environment-access/quickstart.md

Quickstart: Workspace-first RBAC & Environment Access Scoping

Purpose

Use this guide to review or implement Feature 285 once the prerequisite specs are present on the working branch.

Preconditions

• Spec 280 is present on the branch and provides the workspace-first route or shell baseline.
• Spec 281 is present on the branch and provides provider-neutral target-scope baselines.
• Spec 283 is present on the branch and provides downstream provider capability context.
• The branch does not attempt to absorb Spec 284, 286, or 287 work.
• The implementation keeps Filament v5 on Livewire v4 and provider registration in apps/platform/bootstrap/providers.php.

If any of the first three prerequisites is missing, stop and land those dependencies first.

Read order

1. spec.md
2. plan.md
3. research.md
4. data-model.md
5. contracts/workspace-rbac-environment-access.logical.openapi.yaml
6. tasks.md
7. checklists/requirements.md

Implementation intent

• keep WorkspaceMembership as the sole role-bearing truth
• reinterpret or replace the current managed-environment membership semantics as a narrow access-scope overlay only
• retarget CapabilityResolver, User, WorkspaceContext, and the key environment-owned policies to one workspace-first access contract
• split operator-facing membership surfaces into workspace role management and managed-environment access-scope management
• preserve 404 for non-members or out-of-scope actors and 403 for in-scope members missing capability
• keep touched searchable-resource results and denied-access diagnostics aligned with the same shared access contract

Review scenarios

Scenario 1: Workspace role alone is sufficient when no explicit environment scope exists

• create a workspace with at least two managed environments
• add a user through workspace membership only
• confirm the user can open the allowed environment-owned resources that match their workspace role

Scenario 2: Explicit environment scope narrows visibility without changing role

• keep the same workspace role
• add explicit access scope to only one managed environment
• confirm the allowed environment remains visible and a sibling environment becomes not found

Scenario 3: Membership management surfaces no longer expose duplicate roles

• open the workspace membership surface and confirm role editing happens there
• open the retargeted managed-environment access-scope surface and confirm it manages visibility only

Scenario 4: OperationRun access follows the same workspace-first rule

• confirm a workspace-bound run is viewable from workspace membership plus required capability
• confirm an environment-bound run is additionally narrowed by explicit environment scope when present

Scenario 5: Search safety and denied-access diagnostics stay aligned

• confirm any touched searchable resource does not hint inaccessible managed environments to non-members or out-of-scope actors
• confirm denied-access logs explain the failed boundary without exposing raw provider data

Scenario 6: Representative list and bulk preflight stay query-bounded

• confirm a representative environment-owned list, run list, and bulk-authorization preflight use the shared access contract without introducing avoidable N+1 membership or scope lookups

Planned validation commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceFirstCapabilityResolverTest.php tests/Unit/Auth/ManagedEnvironmentAccessScopeResolverTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Rbac/OperationRunWorkspaceFirstAuthorizationTest.php tests/Feature/Rbac/GovernanceArtifactsWorkspaceFirstAuthorizationTest.php tests/Feature/Filament/WorkspaceMembershipRoleManagementTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)

Expected implementation boundaries

• no new role family
• no dual-write or compatibility fallback
• no new provider-boundary contract work
• no copy/localization sweep
• no cutover-wide guardrail enforcement bundle