docs/team-rbac

Team RBAC & Access Control

Manage team access across four role tiers with Supabase JWT authentication and SQLite action audit logging.

Security by construction: Every API endpoint on Server B verifies the caller’s role level against the required permission hierarchy before performing sensitive operations.

The 4-Tier Role Hierarchy

Owner (Level 4)

Full workspace administrative control. Delete projects, manage subscription tier, invite admins, and modify role hierarchy.

Admin (Level 3)

Member (Level 2)

Review Gate 1 raw events, edit issue draft Markdown, approve Gate 2 publication to GitHub, and trigger replays.

Viewer (Level 1)

Read-only telemetry access. Inspect runs, view diffs, examine metrics, and audit team action logs.

RBAC & Action Audit Trail

1	# Role hierarchy & permissions
2	VALID_ROLES = {"owner", "admin", "member", "viewer"}
3	ROLE_HIERARCHY = {"owner": 4, "admin": 3, "member": 2, "viewer": 1}
4
5	# Check permission level
6	can_approve_gate2 = has_permission(user_role="member", required_role="member") # True
7	can_rotate_keys = has_permission(user_role="member", required_role="admin") # False
8
9	# Action audit trail automatically recorded in SQLite audit log
10	log_team_action(project_id, actor_id, action="rotate_key", details="key rotated")

Supabase JWT Verification Middleware

Server B verifies incoming Authorization: Bearer <token> headers using PyJWT with HS256 algorithm verification against your SUPABASE_JWT_SECRET. Invalid, forged, or expired tokens are rejected with HTTP 401 before touching route logic.

Team Action Audit Trail

All critical team operations — including member additions, role promotions, member removals, and key rotations — are recorded in the team_audit_log SQLite table with actor ID, target user ID, timestamp, and metadata details.