adelorenzo/konstruct
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(04-rbac): revise plans based on checker feedback

Browse Source
This commit is contained in:
Adolfo Delorenzo
2026-03-24 13:46:03 -06:00
parent bf4adf0b21
commit 2aecc5c787
3 changed files with 60 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
.planning/phases/04-rbac/04-01-PLAN.md
View File

@@ -16,6 +16,7 @@ files_modified:
- migrations/versions/006_rbac_roles.py
- tests/unit/test_rbac_guards.py
- tests/unit/test_invitations.py
- tests/unit/test_portal_auth.py
autonomous: true
requirements:
- RBAC-01
@@ -54,6 +55,9 @@ must_haves:
- path: "tests/unit/test_invitations.py"
provides: "Unit tests for HMAC token and invitation flow"
min_lines: 40
- path: "tests/unit/test_portal_auth.py"
provides: "Unit tests for auth/verify endpoint returning role + tenant_ids claims"
min_lines: 30
key_links:
- from: "packages/shared/shared/api/rbac.py"
to: "packages/shared/shared/models/auth.py"
@@ -266,10 +270,11 @@ class AuditEvent(Base): # Reuse for impersonation logging in Plan 03
</task>
<task type="auto" tdd="true">
<name>Task 3: Unit tests for RBAC guards and invitation system</name>
<name>Task 3: Unit tests for RBAC guards, invitation system, and portal auth</name>
<files>
tests/unit/test_rbac_guards.py,
tests/unit/test_invitations.py
tests/unit/test_invitations.py,
tests/unit/test_portal_auth.py
</files>
<behavior>
- test_platform_admin_passes: platform_admin caller gets through require_platform_admin
@@ -285,6 +290,9 @@ class AuditEvent(Base): # Reuse for impersonation logging in Plan 03
- test_invite_accept_creates_user: accepting invite creates PortalUser + UserTenantRole
- test_invite_accept_rejects_expired: expired invitation returns error
- test_invite_resend_updates_token: resend generates new token_hash and extends expires_at
- test_auth_verify_returns_role: auth/verify response contains role field (not is_admin)
- test_auth_verify_returns_tenant_ids: auth/verify response contains tenant_ids list
- test_auth_verify_returns_active_tenant: auth/verify response contains active_tenant_id
</behavior>
<action>
Create `tests/unit/test_rbac_guards.py`:
@@ -309,18 +317,27 @@ class AuditEvent(Base): # Reuse for impersonation logging in Plan 03
- Test invitation acceptance via POST /api/portal/invitations/accept (mock DB session with pending invitation)
- Test resend updates token_hash and extends expires_at
Create `tests/unit/test_portal_auth.py`:
- Test the updated auth/verify endpoint returns role (not is_admin) in the response
- Test auth/verify returns tenant_ids as a list of UUID strings for a user with UserTenantRole memberships
- Test auth/verify returns active_tenant_id as the first tenant ID (or None for users with no memberships)
- Test auth/verify for platform_admin returns all tenant IDs from the tenants table
- Test auth/verify for customer_admin returns only tenant IDs from their UserTenantRole rows
- Mock the DB session with appropriate PortalUser (role field) and UserTenantRole rows
- Use httpx.AsyncClient with the app, following existing test patterns (make_app(session) factory)
Follow existing test patterns: use `make_app(session)` factory from tests/ or direct httpx.AsyncClient with app.
</action>
<verify>
<automated>cd /home/adelorenzo/repos/konstruct && pytest tests/unit/test_rbac_guards.py tests/unit/test_invitations.py -x -v</automated>
<automated>cd /home/adelorenzo/repos/konstruct && pytest tests/unit/test_rbac_guards.py tests/unit/test_invitations.py tests/unit/test_portal_auth.py -x -v</automated>
</verify>
<done>All RBAC guard unit tests pass. All invitation token and API unit tests pass. Coverage includes platform_admin bypass, tenant membership checks, token tampering, and expiry validation.</done>
<done>All RBAC guard unit tests pass. All invitation token and API unit tests pass. All portal auth unit tests pass verifying role + tenant_ids claims. Coverage includes platform_admin bypass, tenant membership checks, token tampering, expiry validation, and auth/verify response shape.</done>
</task>
</tasks>
<verification>
- `pytest tests/unit/test_rbac_guards.py tests/unit/test_invitations.py -x -v` — all pass
- `pytest tests/unit/test_rbac_guards.py tests/unit/test_invitations.py tests/unit/test_portal_auth.py -x -v` — all pass
- `python -c "from shared.models.auth import UserRole; assert len(UserRole) == 3"` — enum has 3 values
- `python -c "from shared.api.rbac import require_platform_admin"` — guard imports clean
- `python -c "from shared.invite_token import generate_invite_token, validate_invite_token"` — token utils import clean
@@ -335,7 +352,7 @@ class AuditEvent(Base): # Reuse for impersonation logging in Plan 03
- HMAC invite tokens generate and validate with 48h TTL
- SMTP email utility exists (sync, for Celery)
- Auth/verify returns role + tenant_ids
- All unit tests pass
- All unit tests pass (including test_portal_auth.py for JWT callback claims)
</success_criteria>
<output>

17
.planning/phases/04-rbac/04-02-PLAN.md
View File

@@ -11,7 +11,7 @@ files_modified:
- packages/portal/components/nav.tsx
- packages/portal/components/tenant-switcher.tsx
- packages/portal/components/impersonation-banner.tsx
- packages/portal/app/(dashboard)/invite/[token]/page.tsx
- packages/portal/app/invite/[token]/page.tsx
- packages/portal/app/(dashboard)/users/page.tsx
- packages/portal/app/(dashboard)/admin/users/page.tsx
- packages/portal/app/(dashboard)/layout.tsx
@@ -52,8 +52,8 @@ must_haves:
- path: "packages/portal/components/impersonation-banner.tsx"
provides: "Impersonation indicator banner"
min_lines: 15
- path: "packages/portal/app/(dashboard)/invite/[token]/page.tsx"
provides: "Invite acceptance page with password form"
- path: "packages/portal/app/invite/[token]/page.tsx"
provides: "Invite acceptance page with password form (outside dashboard layout — no auth required)"
min_lines: 40
- path: "packages/portal/app/(dashboard)/users/page.tsx"
provides: "Per-tenant user management page"
@@ -253,13 +253,13 @@ const navItems = [ /* dashboard, tenants, agents, usage, billing, api-keys */ ];
<task type="auto">
<name>Task 3: Invite acceptance page + user management pages</name>
<files>
packages/portal/app/(dashboard)/invite/[token]/page.tsx,
packages/portal/app/invite/[token]/page.tsx,
packages/portal/app/(dashboard)/users/page.tsx,
packages/portal/app/(dashboard)/admin/users/page.tsx
</files>
<action>
Create `packages/portal/app/(dashboard)/invite/[token]/page.tsx`:
- NOTE: This page must be accessible WITHOUT authentication. If the (dashboard) layout requires auth, create this at `packages/portal/app/invite/[token]/page.tsx` instead (outside the dashboard layout group). Check existing route structure.
Create `packages/portal/app/invite/[token]/page.tsx`:
- IMPORTANT: This page is created OUTSIDE the (dashboard) route group because the (dashboard) layout enforces authentication. Invite acceptance must be accessible to unauthenticated users who are creating their account.
- Reads `token` from URL params
- On load, validates token client-side by calling a GET endpoint or just displays the form (server validates on submit)
- Form fields: Password (min 8 chars), Confirm Password
@@ -289,7 +289,7 @@ const navItems = [ /* dashboard, tenants, agents, usage, billing, api-keys */ ];
<verify>
<automated>cd /home/adelorenzo/repos/konstruct/packages/portal && npx tsc --noEmit 2>&1 | head -30</automated>
</verify>
<done>Invite acceptance page renders password form and submits to accept endpoint. Per-tenant users page lists users with invite/resend capability. Platform admin users page shows cross-tenant user list with filters. All pages compile without TypeScript errors.</done>
<done>Invite acceptance page renders password form and submits to accept endpoint. Page is outside (dashboard) group so unauthenticated users can access it. Per-tenant users page lists users with invite/resend capability. Platform admin users page shows cross-tenant user list with filters. All pages compile without TypeScript errors.</done>
</task>
</tasks>
@@ -299,6 +299,7 @@ const navItems = [ /* dashboard, tenants, agents, usage, billing, api-keys */ ];
- `cd packages/portal && npx next build` — build succeeds
- Login as platform_admin: JWT contains role="platform_admin", sees all nav items
- Login as customer_operator: does not see Billing/API Keys/Users in nav, /billing redirects to /agents
- Visit /invite/{token} while logged out: page renders without auth redirect
</verification>
<success_criteria>
@@ -307,7 +308,7 @@ const navItems = [ /* dashboard, tenants, agents, usage, billing, api-keys */ ];
- Nav hides restricted items based on role
- Tenant switcher works for multi-tenant users (no page reload)
- Impersonation banner renders when impersonating
- Invite acceptance page accepts token and creates account
- Invite acceptance page at /invite/[token] (outside dashboard layout) accepts token and creates account without requiring auth
- User management pages exist for tenant admin and platform admin
- Portal builds and TypeScript compiles clean
</success_criteria>

41
.planning/phases/04-rbac/04-03-PLAN.md
View File

@@ -28,6 +28,7 @@ must_haves:
- "Every tenant-scoped endpoint returns 403 for customer_admin accessing a different tenant"
- "Platform admin gets 200 on any tenant's endpoints regardless of membership"
- "Customer operator gets 200 on read-only endpoints (GET agents, GET usage) for their tenant"
- "Customer operator can POST a test message to an agent (POST /tenants/{tid}/agents/{aid}/test) and get 200"
- "Impersonation actions are logged in audit_events with platform admin user_id"
- "Full invite flow works end-to-end: create invitation -> accept -> login -> correct role"
artifacts:
@@ -40,8 +41,8 @@ must_haves:
key_links:
- from: "packages/shared/shared/api/portal.py"
to: "packages/shared/shared/api/rbac.py"
via: "Depends(require_tenant_admin) on mutating endpoints"
pattern: "Depends\\(require_tenant_admin\\)|Depends\\(require_platform_admin\\)"
via: "Depends(require_tenant_admin) on mutating endpoints, Depends(require_tenant_member) on test-message endpoint"
pattern: "Depends\\(require_tenant_admin\\)|Depends\\(require_platform_admin\\)|Depends\\(require_tenant_member\\)"
- from: "packages/shared/shared/api/billing.py"
to: "packages/shared/shared/api/rbac.py"
via: "Depends(require_tenant_admin) on billing endpoints"
@@ -53,10 +54,10 @@ must_haves:
---
<objective>
Wire RBAC guards to ALL existing portal API endpoints, add impersonation audit logging, add user listing endpoints, and create comprehensive integration tests proving every endpoint enforces role-based authorization.
Wire RBAC guards to ALL existing portal API endpoints, add test-message endpoint for operators, add impersonation audit logging, add user listing endpoints, and create comprehensive integration tests proving every endpoint enforces role-based authorization.
Purpose: Defense in depth — the UI hides things, but the API MUST enforce authorization. This plan completes the server-side enforcement layer and validates the entire RBAC system end-to-end.
Output: All portal endpoints guarded, impersonation logged, integration tests for RBAC + invite flow.
Output: All portal endpoints guarded, test-message endpoint for operators, impersonation logged, integration tests for RBAC + invite flow.
</objective>
<execution_context>
@@ -104,6 +105,9 @@ POST /api/portal/tenants/{tid}/agents # require_tenant_admin
GET /api/portal/tenants/{tid}/agents/{aid} # require_tenant_member
PUT /api/portal/tenants/{tid}/agents/{aid} # require_tenant_admin
DELETE /api/portal/tenants/{tid}/agents/{aid} # require_tenant_admin
# NEW — Test message (per locked decision: operators can send test messages)
POST /api/portal/tenants/{tid}/agents/{aid}/test # require_tenant_member (operators included)
```
From packages/shared/shared/api/billing.py, channels.py, llm_keys.py, usage.py:
@@ -126,7 +130,7 @@ class AuditEvent(Base):
<tasks>
<task type="auto">
<name>Task 1: Wire RBAC guards to all existing API endpoints + impersonation + user listing</name>
<name>Task 1: Wire RBAC guards to all existing API endpoints + test-message endpoint + impersonation + user listing</name>
<files>
packages/shared/shared/api/portal.py,
packages/shared/shared/api/billing.py,
@@ -149,6 +153,7 @@ class AuditEvent(Base):
- `GET /tenants/{tenant_id}/agents/{agent_id}` — add `Depends(require_tenant_member)`.
- `PUT /tenants/{tenant_id}/agents/{agent_id}` — add `Depends(require_tenant_admin)`.
- `DELETE /tenants/{tenant_id}/agents/{agent_id}` — add `Depends(require_tenant_admin)`.
- ADD new endpoint: `POST /tenants/{tenant_id}/agents/{agent_id}/test` — requires `Depends(require_tenant_member)` (NOT require_tenant_admin). This is the test-message endpoint per locked decision: "operators can send test messages to agents." Accepts `{message: str}` body. Dispatches the message through the agent orchestrator pipeline (or a lightweight test handler) for the specified agent, returns the agent's response. This allows operators to QA agent behavior without agent CRUD access.
- ADD new endpoint: `GET /tenants/{tenant_id}/users` — requires require_tenant_admin. Queries UserTenantRole JOIN PortalUser WHERE tenant_id matches. Returns list of {id, name, email, role, created_at}. Also queries PortalInvitation WHERE tenant_id AND status='pending' to include pending invites.
- ADD new endpoint: `GET /admin/users` — requires require_platform_admin. Queries ALL PortalUser with their UserTenantRole associations. Supports optional query params: tenant_id filter, role filter. Returns list with tenant membership info.
@@ -189,8 +194,11 @@ from shared.api.billing import billing_router
from shared.api.channels import channels_router
routes = [r.path for r in portal_router.routes]
print(f'Portal routes: {len(routes)}')
# Verify test-message endpoint exists
test_routes = [r.path for r in portal_router.routes if 'test' in r.path]
assert test_routes, 'Missing /test endpoint for agent test messages'
print(f'Test-message route: {test_routes}')
# Verify at least one route has dependencies
import inspect
for r in portal_router.routes:
if hasattr(r, 'dependant') and r.dependant.dependencies:
print(f' {r.path} has {len(r.dependant.dependencies)} dependencies')
@@ -199,7 +207,7 @@ else:
print('WARNING: No routes have dependencies')
"</automated>
</verify>
<done>Every portal API endpoint has an RBAC guard. Mutating endpoints require tenant_admin or platform_admin. Read-only tenant endpoints allow tenant_member. Global endpoints require platform_admin. Impersonation endpoint logs to audit trail. User listing endpoints exist for both per-tenant and global views.</done>
<done>Every portal API endpoint has an RBAC guard. Mutating endpoints require tenant_admin or platform_admin. Read-only tenant endpoints allow tenant_member. Test-message endpoint (POST /tenants/{tid}/agents/{aid}/test) allows tenant_member including operators. Global endpoints require platform_admin. Impersonation endpoint logs to audit trail. User listing endpoints exist for both per-tenant and global views.</done>
</task>
<task type="auto" tdd="true">
@@ -212,6 +220,7 @@ else:
- Platform admin with correct headers gets 200 on all endpoints
- Customer admin gets 200 on own-tenant endpoints, 403 on other tenants
- Customer operator gets 200 on GET endpoints, 403 on POST/PUT/DELETE
- Customer operator gets 200 on POST /tenants/{tid}/agents/{aid}/test (test message — exception to POST restriction)
- Missing role headers return 401/422 (FastAPI Header() validation)
- Impersonation endpoint logs AuditEvent row
- Full invite flow: admin creates invite -> token generated -> accept with password -> new user can login -> new user has correct role and tenant membership
@@ -237,6 +246,7 @@ else:
| POST /tenants/{tid}/agents | 201 | 201 | 403 | 403 |
| PUT /tenants/{tid}/agents/{aid} | 200 | 200 | 403 | 403 |
| DELETE /tenants/{tid}/agents/{aid} | 204 | 204 | 403 | 403 |
| POST /tenants/{tid}/agents/{aid}/test | 200 | 200 | 403 | 200 |
| GET /tenants/{tid}/users | 200 | 200 | 403 | 403 |
| GET /admin/users | 200 | 403 | 403 | 403 |
@@ -244,6 +254,7 @@ else:
- Request with NO role headers -> 422 (missing required header)
- Impersonation endpoint creates AuditEvent row
- Billing, channels, llm_keys, usage endpoints follow same pattern (at least one representative test per router)
- Specific test: customer_operator can POST to /test endpoint but NOT to agent CRUD POST
Create `tests/integration/test_invite_flow.py`:
- Set up: create a tenant, create a customer_admin user with membership
@@ -263,7 +274,7 @@ else:
<verify>
<automated>cd /home/adelorenzo/repos/konstruct && pytest tests/integration/test_portal_rbac.py tests/integration/test_invite_flow.py -x -v</automated>
</verify>
<done>All RBAC integration tests pass — every endpoint returns correct status code for each role. Full invite flow works end-to-end. Expired invites are rejected. Resend works. Double-accept prevented.</done>
<done>All RBAC integration tests pass — every endpoint returns correct status code for each role. Operator test-message endpoint returns 200. Full invite flow works end-to-end. Expired invites are rejected. Resend works. Double-accept prevented.</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
@@ -279,8 +290,9 @@ else:
- Verify: can access /admin/users (global user management)
- Verify: can impersonate a tenant (banner appears, can exit)
4. Create a customer_admin invite from the Users page
5. Open the invite link in an incognito window
- Verify: activation page shows, can set password
5. Open the invite link in an incognito window (URL will be /invite/{token} — NOT inside dashboard)
- Verify: activation page shows without requiring login
- Verify: can set password and complete account creation
- Verify: after activation, redirected to login
6. Login as the new customer admin:
- Verify: sees Dashboard, Employees, Usage, Billing, API Keys, Users (no Tenants, no Platform)
@@ -290,11 +302,12 @@ else:
- Verify: sees only Employees and Usage in nav
- Verify: navigating to /billing redirects to /agents
- Verify: cannot see Billing, API Keys, Users in sidebar
- Verify: can click "Test" on an agent to send a test message (per locked decision)
9. If user has multiple tenants, verify tenant switcher appears and switches context
10. Run: `pytest tests/ -x` — all tests pass
</action>
<verify>Human confirms all verification steps pass or reports issues</verify>
<done>All three roles behave correctly in portal UI and API. Invitation flow works end-to-end. Full test suite green.</done>
<done>All three roles behave correctly in portal UI and API. Operators can send test messages but not edit agents. Invitation flow works end-to-end. Full test suite green.</done>
</task>
</tasks>
@@ -305,16 +318,18 @@ else:
- `pytest tests/ -x` — entire test suite green (no regressions)
- Every mutating endpoint returns 403 without proper role headers
- Platform admin bypasses all tenant membership checks
- Operator gets 200 on POST /tenants/{tid}/agents/{aid}/test
</verification>
<success_criteria>
- All portal API endpoints enforce role-based authorization via Depends() guards
- Customer operators cannot mutate any data via API (403 on POST/PUT/DELETE)
- Customer operators cannot mutate any data via API (403 on POST/PUT/DELETE) EXCEPT test-message endpoint
- Customer operators CAN send test messages to agents (POST /tenants/{tid}/agents/{aid}/test returns 200)
- Customer admins can only access their own tenant's data (403 on other tenants)
- Platform admin has unrestricted access to all endpoints
- Impersonation actions logged in audit_events table
- User listing endpoints exist for per-tenant and global views
- Integration tests comprehensively cover the RBAC matrix
- Integration tests comprehensively cover the RBAC matrix including test-message operator access
- Full invite flow works end-to-end in integration tests
- Human verification confirms visual role-based behavior in portal
</success_criteria>