132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
---
|
|
phase: 04-rbac
|
|
plan: 01
|
|
subsystem: rbac
|
|
tags: [rbac, auth, invitations, migration, orm, guards]
|
|
dependency_graph:
|
|
requires: []
|
|
provides:
|
|
- RBAC guard dependencies (require_platform_admin, require_tenant_admin, require_tenant_member)
|
|
- Migration 006 (user_tenant_roles, portal_invitations tables)
|
|
- HMAC invite token generation and validation
|
|
- Invitation CRUD API (create, accept, resend, list)
|
|
- SMTP email utility for invitations
|
|
- auth/verify returning role + tenant_ids (replaces is_admin)
|
|
affects:
|
|
- packages/shared/shared/models/auth.py (PortalUser.is_admin removed)
|
|
- packages/shared/shared/api/portal.py (AuthVerifyResponse shape changed)
|
|
- packages/gateway/gateway/main.py (invitations_router mounted)
|
|
tech_stack:
|
|
added: []
|
|
patterns:
|
|
- TEXT + CHECK constraint for role column (per Phase 1 ADR, avoids sa.Enum DDL issues)
|
|
- HMAC-SHA256 with hmac.compare_digest for timing-safe token verification
|
|
- SHA-256(token) stored in DB — raw token never persisted
|
|
- Celery fire-and-forget via lazy local import in API handler (avoids circular dep)
|
|
- platform_admin bypasses all tenant membership checks (no DB query)
|
|
key_files:
|
|
created:
|
|
- migrations/versions/006_rbac_roles.py
|
|
- packages/shared/shared/api/rbac.py
|
|
- packages/shared/shared/invite_token.py
|
|
- packages/shared/shared/email.py
|
|
- packages/shared/shared/api/invitations.py
|
|
- tests/unit/test_rbac_guards.py
|
|
- tests/unit/test_invitations.py
|
|
- tests/unit/test_portal_auth.py
|
|
modified:
|
|
- packages/shared/shared/models/auth.py
|
|
- packages/shared/shared/api/portal.py
|
|
- packages/shared/shared/api/__init__.py
|
|
- packages/shared/shared/config.py
|
|
- packages/gateway/gateway/main.py
|
|
- packages/orchestrator/orchestrator/tasks.py
|
|
decisions:
|
|
- "Role stored as TEXT + CHECK (not sa.Enum) — per Phase 1 ADR to avoid Alembic DDL conflicts"
|
|
- "SHA-256 hash of raw token stored in DB — token_hash enables O(1) lookup without exposing token"
|
|
- "platform_admin bypasses tenant membership check without DB query — simpler and faster"
|
|
- "Celery task dispatch uses lazy local import in invitations.py — avoids shared->orchestrator circular dep"
|
|
- "portal_url reused for invite link construction — not duplicated as portal_base_url"
|
|
metrics:
|
|
duration: "8 minutes"
|
|
completed: "2026-03-24"
|
|
tasks_completed: 3
|
|
files_created: 8
|
|
files_modified: 6
|
|
---
|
|
|
|
# Phase 4 Plan 01: RBAC Foundation Summary
|
|
|
|
**One-liner:** 3-tier RBAC (platform_admin/customer_admin/customer_operator) with DB migration, FastAPI guard dependencies, HMAC invite tokens, and invite-only onboarding API.
|
|
|
|
## What Was Built
|
|
|
|
### Task 1: DB Migration + ORM Models + Config
|
|
Migration 006 (`migrations/versions/006_rbac_roles.py`) adds the RBAC schema to PostgreSQL:
|
|
- Adds `role TEXT + CHECK` column to `portal_users`, backfills `is_admin` values, drops `is_admin`
|
|
- Creates `user_tenant_roles` table (user_id FK, tenant_id FK, UNIQUE constraint)
|
|
- Creates `portal_invitations` table (token_hash UNIQUE, status, expires_at, all FKs)
|
|
|
|
`packages/shared/shared/models/auth.py` gains:
|
|
- `UserRole` string enum (PLATFORM_ADMIN, CUSTOMER_ADMIN, CUSTOMER_OPERATOR)
|
|
- `UserTenantRole` ORM model with CASCADE deletes
|
|
- `PortalInvitation` ORM model
|
|
- `PortalUser.role` replaces `PortalUser.is_admin`
|
|
|
|
`packages/shared/shared/config.py` gains: `invite_secret`, `smtp_host`, `smtp_port`, `smtp_username`, `smtp_password`, `smtp_from_email`.
|
|
|
|
### Task 2: RBAC Guards + Invite Token + Email + Invitation API
|
|
|
|
**`packages/shared/shared/api/rbac.py`** — FastAPI dependency guards:
|
|
- `PortalCaller` dataclass (user_id, role, tenant_id from request headers)
|
|
- `get_portal_caller` — parses X-Portal-User-Id/Role/Tenant-Id headers, raises 401 on bad UUID
|
|
- `require_platform_admin` — raises 403 for non-platform_admin
|
|
- `require_tenant_admin` — platform_admin bypasses; customer_admin checked against UserTenantRole; operator always 403
|
|
- `require_tenant_member` — platform_admin bypasses; customer_admin/operator checked against UserTenantRole
|
|
|
|
**`packages/shared/shared/invite_token.py`** — HMAC token utilities:
|
|
- `generate_invite_token(invitation_id)` — HMAC-SHA256, base64url-encoded, embeds `{id}:{timestamp}`
|
|
- `validate_invite_token(token)` — timing-safe compare_digest, 48h TTL check, returns invitation_id
|
|
- `token_to_hash(token)` — SHA-256 hex digest for DB storage
|
|
|
|
**`packages/shared/shared/email.py`** — SMTP email sender (sync, for Celery):
|
|
- Sends HTML+text multipart invite email
|
|
- Skips silently if smtp_host is empty (dev-friendly)
|
|
|
|
**`packages/shared/shared/api/invitations.py`** — Invitation CRUD router:
|
|
- `POST /api/portal/invitations` — create invitation (requires tenant admin), returns raw token
|
|
- `POST /api/portal/invitations/accept` — validate token, create PortalUser + UserTenantRole, mark accepted
|
|
- `POST /api/portal/invitations/{id}/resend` — regenerate token, extend expiry
|
|
- `GET /api/portal/invitations` — list pending invitations for caller's tenant
|
|
|
|
**`packages/shared/shared/api/portal.py`** — auth/verify updated:
|
|
- `AuthVerifyResponse` now returns `role`, `tenant_ids`, `active_tenant_id` (replaced `is_admin`)
|
|
- platform_admin returns all tenant IDs; customer roles return their UserTenantRole tenant IDs
|
|
- `/auth/register` gated behind `require_platform_admin` with deprecation comment
|
|
|
|
**`packages/orchestrator/orchestrator/tasks.py`** — added `send_invite_email_task` Celery task.
|
|
|
|
**`packages/gateway/gateway/main.py`** — `invitations_router` mounted.
|
|
|
|
### Task 3: Unit Tests (27 passing)
|
|
|
|
- `tests/unit/test_rbac_guards.py` (11 tests): RBAC guard pass/reject scenarios, platform_admin bypass
|
|
- `tests/unit/test_invitations.py` (11 tests): HMAC token roundtrip, tamper/expiry, invitation CRUD
|
|
- `tests/unit/test_portal_auth.py` (7 tests): auth/verify returns role+tenant_ids+active_tenant_id
|
|
|
|
## Deviations from Plan
|
|
|
|
None — plan executed exactly as written.
|
|
|
|
## Commits
|
|
|
|
| Hash | Description |
|
|
|------|-------------|
|
|
| f710c9c | feat(04-rbac-01): DB migration 006 + RBAC ORM models + config fields |
|
|
| d59f85c | feat(04-rbac-01): RBAC guards + invite token + email + invitation API |
|
|
| 7b0594e | test(04-rbac-01): unit tests for RBAC guards, invitation system, portal auth |
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All files created and verified before this summary was written.
|