KytheraDB -- Governance
Enterprise governance model for KytheraDB, covering roles, teams, permissions, audit, and session management.
Table of Contents
- Role Hierarchy
- Team Management
- Project Permissions
- Audit Trail
- Session Management
- User Blocking
- Project Access Control
Role Hierarchy
KytheraDB defines five roles in ascending order of privilege:
viewer < qa < dev < admin < super_admin
Role Definitions
| Role | Description | Scope |
|---|---|---|
viewer | Read-only access to project data and schemas | Project |
qa | Viewer access plus seeding and QA template execution | Project |
dev | QA access plus SQL write, patches, imports, bridge, preflight | Project |
admin | Full project access, connection management, team management, user admin | Organization |
super_admin | Governance-only role: DSI dashboard, cross-organization visibility | Platform |
Role Capabilities
| Capability | viewer | qa | dev | admin | super_admin |
|---|---|---|---|---|---|
| View schemas and data | Yes | Yes | Yes | Yes | -- |
| Export data | Yes | Yes | Yes | Yes | -- |
| Run seeds | -- | Yes | Yes | Yes | -- |
| Run QA templates | -- | Yes | Yes | Yes | -- |
| Write SQL | -- | -- | Yes | Yes | -- |
| Create/execute patches | -- | -- | Yes | Yes | -- |
| Import data | -- | -- | Yes | Yes | -- |
| Bridge transfers | -- | -- | Yes | Yes | -- |
| Preflight analysis | -- | -- | Yes | Yes | -- |
| Performance monitoring | -- | -- | Yes | Yes | -- |
| Manage connections | -- | -- | -- | Yes | -- |
| Manage anonymization | -- | -- | -- | Yes | -- |
| GDPR/compliance scanning | -- | -- | -- | Yes | -- |
| Project configuration | -- | -- | -- | Yes | -- |
| Team management | -- | -- | -- | Yes | -- |
| User management | -- | -- | -- | Yes | -- |
| Governance dashboard | -- | -- | -- | -- | Yes |
| Block/unblock users | -- | -- | -- | -- | Yes |
| Force logout | -- | -- | -- | -- | Yes |
| Cross-project audit | -- | -- | -- | -- | Yes |
| Manage project permissions | -- | -- | -- | -- | Yes |
super_admin Restrictions
The super_admin role is designed exclusively for governance and oversight. It cannot:
- Access project data directly
- Execute SQL queries
- Create or modify records
- Navigate to project routes
This separation ensures that governance users operate at the organizational level without touching production data.
Team Management
Teams group users for project access control.
Team Structure
Team
├── name: string
├── description: string
├── created_at: timestamp
└── members: TeamMember[]
├── user_id: UUID
├── role: string (admin, dev, qa, viewer)
└── joined_at: timestamp
Team Operations
| Operation | Required Role | Endpoint |
|---|---|---|
| Create team | admin | POST /teams/ |
| List teams | admin | GET /teams/ |
| View team details | admin | GET /teams/{team_id} |
| Update team | admin | PATCH /teams/{team_id} |
| Delete team | admin | DELETE /teams/{team_id} |
| Add member | admin | POST /teams/{team_id}/members |
| Remove member | admin | DELETE /teams/{team_id}/members/{user_id} |
| Update member role | admin | PATCH /teams/{team_id}/members/{user_id} |
| List team projects | admin | GET /teams/{team_id}/projects |
| Create team project | admin | POST /teams/{team_id}/projects |
Governance Team Operations
Super admins can manage teams through the governance API:
| Operation | Endpoint |
|---|---|
| List all teams | GET /governance/teams |
| Create team | POST /governance/teams |
| View team details | GET /governance/teams/{team_id} |
| Delete team | DELETE /governance/teams/{team_id} |
Project Permissions
Fine-grained, per-user access grants on individual projects.
Permission Types
| Permission | Description |
|---|---|
READ | View project schemas, data, and configurations |
WRITE | Modify data through CRUD operations |
EXECUTE | Execute SQL queries and run seeds |
PATCH | Create and execute mass patches |
ADMIN | Full project control including configuration changes |
Access Resolution
When a user attempts to access a project, the system checks in order:
- No team assigned to project: Any authenticated user has access (backward compatibility for projects created before team management).
- Team membership: If the project has a
team_id, the user must be a member of that team. - Direct permission: If the user is not a team member, check for a
ProjectPermissionrecord granting them access.
If none of these conditions are met, access is denied with HTTP 403.
Permission Management
Only super_admin users can manage project permissions through the governance API:
| Operation | Endpoint |
|---|---|
| Grant permission | POST /governance/projects/{project_id}/permissions |
| List permissions | GET /governance/projects/{project_id}/permissions |
| Revoke permission | DELETE /governance/projects/{project_id}/permissions/{user_id} |
Permission Data Model
ProjectPermission
├── id: UUID
├── project_id: UUID (FK → projects)
├── user_id: UUID (FK → app_users)
├── permissions: string[] (e.g., ["READ", "WRITE", "EXECUTE"])
├── granted_by: UUID (FK → app_users)
├── granted_at: timestamp
Audit Trail
Every significant action in the platform is recorded in the audit log.
Audit Log Entry
AuditLog
├── id: UUID
├── project_id: UUID (nullable for platform-level actions)
├── user_id: UUID (who performed the action)
├── action: string (e.g., "seed_insert", "patch_execute", "bridge_transfer")
├── details: JSON (action-specific metadata)
├── is_deleted_project: boolean (true if the project has been deleted)
├── created_at: timestamp
Audit Access
| Scope | Endpoint | Role |
|---|---|---|
| Project activity | GET /projects/{id}/activity | Any member |
| Platform activity | GET /auth/activity | admin |
| Governance audit | GET /governance/audit | super_admin |
| Export audit (CSV) | GET /governance/audit/export | super_admin |
Governance Audit Features
The governance audit endpoint supports:
- Pagination: Page-based navigation for large audit logs
- Filtering: By user, action type, date range, project
- Search: Text search across action details
- Export: Download the filtered audit trail as a CSV file
Session Management
Enterprise super admins can monitor and control active user sessions.
Session Operations
| Operation | Endpoint | Description |
|---|---|---|
| List sessions | GET /governance/sessions | View all active user sessions |
| Revoke session | POST /governance/sessions/{user_id}/revoke | Force-logout a specific user |
| Force logout | POST /governance/users/{user_id}/force-logout | Invalidate all sessions for a user |
Session Data
Sessions are tracked through JWT token issuance. Revoking a session invalidates the user's token, requiring them to re-authenticate.
User Blocking
Super admins can block users to prevent all platform access.
Block Operations
| Operation | Endpoint | Description |
|---|---|---|
| Block user | POST /governance/users/{user_id}/block | Block user with required reason |
| Unblock | POST /governance/users/{user_id}/unblock | Restore user access |
Block Data Model
User
├── is_active: boolean (false when blocked)
├── block_reason: string (required when blocking)
Blocked users receive HTTP 401 on all authenticated requests. The block reason is recorded for compliance and audit purposes.
Project Access Control
Access Flow Diagram
User requests project resource
│
├─ Is user authenticated?
│ No → 401 Unauthorized
│
├─ Is user super_admin?
│ Yes → 403 (governance only, no project access)
│
├─ Does project have a team_id?
│ No → Allow (backward compatibility)
│
├─ Is user a member of the project's team?
│ Yes → Allow
│
├─ Does user have a direct ProjectPermission?
│ Yes → Allow
│
└─ 403 Forbidden
Connection-Level Environment Awareness
Each connection has an environment_tag (e.g., dev, staging, production). This tag affects:
- Preflight Guard: Stricter risk thresholds for production connections
- Guard Rails: Policies can be configured per environment
- Validation Rules: Rules can be scoped to specific environments via
environment_tags - UI Indicators: The sidebar displays the active connection's environment tag
Governance Dashboard
The governance dashboard (GET /governance/dashboard) provides:
- Total user count, active count, blocked count
- Total team count and member distribution
- Total project count with connection counts
- Recent activity across all projects
- Alert detection for anomalous activity patterns
- Deleted project tracking