TenantAtlas/specs/066-rbac-ui-enforcement-helper/quickstart.md

Quickstart: RBAC UI Enforcement Helper v2

Branch: 066-rbac-ui-enforcement-helper-v2
Date: 2026-01-30
Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas-066-rbac-ui-enforcement-helper-v2/specs/066-rbac-ui-enforcement-helper/spec.md

Local setup

1. Start the app stack:
   • ./vendor/bin/sail up -d
2. Install dependencies (if needed):
   • ./vendor/bin/sail composer install

Recipes (once implemented)

Scope: Tenant plane only (/admin/t/{tenant}). Platform plane (/system) is out of scope.

Tenant-scoped action (default tenant from Filament)

• Use UiEnforcement with the required Capabilities::* constant.
• Non-members should never see the action (routing already denies them).
• Members without capability see a disabled action + standard tooltip.

Mixed visibility (business visibility + RBAC)

• If the surface already has business visibility rules, use composition:
  • Tenant-scoped: you may use preserveVisibility() to keep existing visibility closures unchanged.
  • Record-scoped / cross-tenant lists: do not use preserveVisibility(); instead use andVisibleWhen(...) / andHiddenWhen(...) so non-members cannot discover actions.

Record-scoped tenant (record == tenant)

• Configure enforcement with tenantFromRecord() so membership/capability checks are evaluated per row/record tenant.
• Non-members must be deny-as-not-found (404) on direct access/execution attempts.

Bulk actions (authorization-only all-or-nothing)

• Use bulk preflight to disable the action if any selected record is unauthorized.
• Keep business eligibility separate (e.g., skip inactive/archived records with deterministic feedback).

Notes on Filament execution semantics

• Hidden actions do not execute (silent no-op). This is acceptable for the non-member contract.
• Disabled actions do not execute (silent no-op). This is acceptable for member-without-capability.
• Server-side authorization remains required (UI is not security). Where reachable:
  • Non-member: deny-as-not-found (404)
  • Member without capability: 403

Manual QA checklist (once implemented)

• Log in as a tenant member without the capability:
  • Action visible but disabled, with tooltip “Insufficient permission — ask a tenant Owner.”
  • Clicking does not execute.
• Remove membership:
  • Action hidden; direct access returns 404.
• Bulk selection with mixed authorization:
  • Bulk action is disabled; no partial execution.

Test run (once implemented)

• ./vendor/bin/sail bin pint --dirty
• ./vendor/bin/sail artisan test tests/Feature/Guards --compact
• ./vendor/bin/sail artisan test tests/Feature/Filament --compact
• ./vendor/bin/sail artisan test tests/Feature/Rbac --compact