105 lines
5.2 KiB
Markdown
105 lines
5.2 KiB
Markdown
# Implementation Plan: Tenant RBAC v1
|
|
|
|
**Branch**: `065-tenant-rbac-v1` | **Date**: 2026-01-27 | **Spec**: [spec.md](spec.md)
|
|
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.
|
|
|
|
## Summary
|
|
|
|
This plan outlines the implementation of a capabilities-first Tenant RBAC system within the existing Laravel and Filament application. The primary requirement is to introduce granular, server-side enforced permissions for tenant users, managed through a new "Members" UI.
|
|
|
|
The technical approach involves:
|
|
1. Creating a `tenant_memberships` table to store user roles within each tenant.
|
|
2. Defining a central capability registry and mapping roles (`Owner`, `Manager`, `Operator`, `Readonly`) to specific capabilities.
|
|
3. Using Laravel Gates and Policies to enforce these capabilities throughout the application.
|
|
4. Building a Filament Relation Manager (`MembersRelationManager`) to provide a UI for Owners to manage tenant memberships.
|
|
5. Adding comprehensive feature and unit tests with Pest to ensure the RBAC system is secure and correct.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4+
|
|
**Primary Dependencies**: Laravel 12, Filament 5, Livewire 4, Pest 4
|
|
**Storage**: PostgreSQL
|
|
**Testing**: Pest
|
|
**Target Platform**: Web (Laravel application)
|
|
**Project Type**: Web application
|
|
**Performance Goals**: Membership/capability evaluation MUST be O(1) per request after initial load (NFR-001).
|
|
**Constraints**: RBAC UI surfaces MUST be DB-only at render time (NFR-003).
|
|
**Scale/Scope**: The system should be designed to handle a moderate number of tenants and users, with the potential to scale. Initial design should not be a bottleneck for future growth.
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- [X] **Inventory-first**: N/A for this feature.
|
|
- [X] **Read/write separation**: All membership changes (write operations) are specified to require Owner-level privileges and will be implemented with confirmations and audit logs.
|
|
- [X] **Graph contract path**: N/A. The spec explicitly states no Graph calls for RBAC UI.
|
|
- [X] **Deterministic capabilities**: The role-to-capability mapping is deterministic and defined in a central place.
|
|
- [X] **RBAC Standard**: This feature implements the RBAC standard. It establishes the two-plane separation, capabilities-first authorization, and least-privilege roles.
|
|
- [X] **Tenant isolation**: All queries and actions are tenant-scoped through the `tenant_memberships` table.
|
|
- [X] **Run observability**: N/A for the core RBAC logic, as it's synchronous. Any long-running operations triggered by authorized users will follow this principle.
|
|
- [X] **Automation**: N/A for this feature.
|
|
- [X] **Data minimization**: The `tenant_memberships` table stores only essential information (IDs and role).
|
|
- [X] **Badge semantics (BADGE-001)**: The role badge in the members list will use the `BadgeCatalog`.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/065-tenant-rbac-v1/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/
|
|
│ └── capabilities.md # Phase 1 output
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
The project follows a standard Laravel structure. Key files for this feature will be located in:
|
|
|
|
```text
|
|
app/
|
|
├── Models/
|
|
│ ├── TenantMembership.php # New Eloquent model
|
|
│ └── User.php # Add relationship to TenantMembership
|
|
│ └── Tenant.php # Add relationship to TenantMembership
|
|
├── Policies/
|
|
│ └── TenantMembershipPolicy.php # New policy for managing memberships
|
|
├── Providers/
|
|
│ └── AuthServiceProvider.php # Register gates and policies
|
|
└── Filament/
|
|
└── Resources/
|
|
└── TenantResource/
|
|
└── RelationManagers/
|
|
└── MembersRelationManager.php # New Filament relation manager
|
|
|
|
database/
|
|
├── factories/
|
|
│ └── TenantMembershipFactory.php # New model factory
|
|
└── migrations/
|
|
└── [timestamp]_create_tenant_memberships_table.php # New migration
|
|
|
|
tests/
|
|
├── Feature/
|
|
│ └── Filament/
|
|
│ └── TenantMembersTest.php # New feature test for RBAC UI
|
|
└── Unit/
|
|
└── TenantRBACTest.php # New unit test for role-capability mapping
|
|
```
|
|
|
|
**Structure Decision**: The implementation will use the existing Laravel project structure. New classes and files will be created in their conventional locations. The primary UI for membership management will be a Filament Relation Manager on the `TenantResource`.
|
|
|
|
## Complexity Tracking
|
|
|
|
> **Fill ONLY if Constitution Check has violations that must be justified**
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
|
|
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
|