Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/procella-dev/procella/blob/main/README.md) - [AGENTS.md](https://github.com/procella-dev/procella/blob/main/AGENTS.md) - [packages/auth/src/auth.test.ts](https://github.com/procella-dev/procella/blob/main/packages/auth/src/auth.test.ts) - [apps/server/src/middleware/middleware.test.ts](https://github.com/procella-dev/procella/blob/main/apps/server/src/middleware/middleware.test.ts) - [apps/server/src/routes/index.ts](https://github.com/procella-dev/procella/blob/main/apps/server/src/routes/index.ts) - [infra/descope.ts](https://github.com/procella-dev/procella/blob/main/infra/descope.ts) - [e2e/descope-auth.test.ts](https://github.com/procella-dev/procella/blob/main/e2e/descope-auth.test.ts)

# Authentication & RBAC Procella implements a multi-tenant authentication system designed to facilitate both local development and production-grade security. The system supports two primary modes: a `dev` mode utilizing static tokens and a `descope` mode leveraging [Descope](https://www.descope.com/) for JWT-based authentication, SSO, and tenant management. The architecture enforces Role-Based Access Control (RBAC) at the organization level, ensuring that users possess the necessary permissions (Viewer, Member, or Admin) before performing operations on Pulumi stacks or organizational settings. Sources: [README.md:12-13](), [AGENTS.md:144-150](), [infra/descope.ts:80-108]() ## Auth Modes and Services Procella abstracts authentication logic through an `AuthService` interface, allowing the system to switch between providers based on configuration. ### Dev Mode (`dev`) In development, Procella uses a static token defined by the `PROCELLA_DEV_AUTH_TOKEN` environment variable. Any request providing this token via the `Authorization` header is granted administrative access under a default development user and organization. Sources: [README.md:112-115](), [packages/auth/src/auth.test.ts:51-60]() ### Descope Mode (`descope`) For production, Procella integrates with Descope to handle complex identity flows. This includes: * **JWT Validation**: Authenticating users via session JWTs. * **Access Keys**: Long-lived keys for CLI use, which are exchanged for session tokens. * **Tenant Mapping**: Automatically mapping Descope tenants to Procella organizations. Sources: [AGENTS.md:154-160](), [infra/descope.ts:60-78](), [e2e/descope-auth.test.ts:88-112]() | Feature | Dev Mode | Descope Mode | | :--- | :--- | :--- | | **Token Type** | Static String | JWT / Access Key | | **Identity Provider** | Internal (Static) | Descope | | **RBAC Enforcement** | Hardcoded (Admin) | Per-Tenant Roles | | **Browser Login** | Not Applicable | Supported via Descope Flows | Sources: [README.md:112-120](), [packages/auth/src/auth.test.ts:40-100]() ## Authentication Flow Procella handles authentication through specialized middleware in the Hono server. The system distinguishes between standard API/Dashboard access and the specific "update-token" lease system used by the Pulumi CLI during active updates. ```mermaid flowchart TD Req[Incoming Request] --> Filter{Route Path} Filter -- "/trpc/*" --> TRPC[tRPC Auth] Filter -- "/api/*" --> API[API Auth Middleware] API --> Header{Auth Header Type} Header -- "token " --> KeyAuth[Access Key/Static Token] Header -- "Bearer " --> JWTAuth[JWT Validation] Header -- "update-token " --> LeaseAuth[Lease Validation] KeyAuth --> Principal[Identify Caller] JWTAuth --> Principal LeaseAuth --> UpdateCtx[Identify Update Context] Principal --> RBAC{Check Roles} RBAC -- Fail --> 403[Forbidden] RBAC -- Pass --> Handler[Process Request] ``` The diagram above illustrates how requests are routed and validated based on the authorization header and target endpoint. Sources: [apps/server/src/routes/index.ts:143-160](), [apps/server/src/middleware/middleware.test.ts:40-80](), [AGENTS.md:95-108]() ### CLI Update Leases During a `pulumi up` operation, the CLI uses a unique 4-part update token. This token format (`update:::`) allows the server to verify that the CLI has a valid lease for the specific stack it is modifying. Sources: [packages/auth/src/auth.test.ts:85-95](), [apps/server/src/middleware/middleware.test.ts:94-110]() ## Role-Based Access Control (RBAC) Procella enforces three standard roles per organization. These roles are mapped to specific HTTP methods and internal permissions. ### Roles and Permissions | Role | Description | Method Mapping | | :--- | :--- | :--- | | **viewer** | Read-only access to stacks and history. | `GET`, `HEAD` | | **member** | Can create stacks and run updates. | `POST`, `PUT`, `PATCH` | | **admin** | Full access, including member and webhook management. | `DELETE` + All others | Sources: [infra/descope.ts:98-108](), [packages/auth/src/auth.test.ts:255-275]() ### Role Enforcement Logic The `requireRole` utility compares the caller's assigned roles against the required level. Admin status is hierarchical; an `admin` automatically satisfies `member` and `viewer` requirements. ```mermaid classDiagram class Caller { +string tenantId +string orgSlug +string userId +string login +string[] roles +string principalType } class Role { <> viewer member admin } Caller --> Role : assigned ``` Procella uses a structured `Caller` object to track identity and permissions throughout the request lifecycle. Sources: [packages/auth/src/auth.test.ts:220-235](), [apps/server/src/middleware/middleware.test.ts:18-25]() ## Infrastructure Configuration In production, Descope is configured via Pulumi to provide the necessary JWT templates and authorization schemas that Procella expects. ### JWT Templates Descope must emit specific claims in the JWT for Procella to function: * **dct**: Automatic tenant claim used for multi-tenancy. * **roles**: User roles within the tenant. * **tenant_name**: Human-friendly name used to derive the organizational slug. Sources: [infra/descope.ts:25-50](), [packages/auth/src/auth.test.ts:315-340]() ### Implementation Example: Role Checking ```typescript export function requireRole(caller: Caller, required: Role) { if (caller.roles.includes("admin")) return; if (required === "member" && caller.roles.includes("member")) return; if (required === "viewer" && (caller.roles.includes("member") || caller.roles.includes("viewer"))) return; throw new ForbiddenError(`Required role ${required} not met`); } ``` Sources: [packages/auth/src/auth.test.ts:220-250]() (Logic derived from test assertions). ## Summary The Authentication and RBAC system in Procella provides a secure foundation for self-hosting Pulumi state. By supporting both a simplified development mode and a robust OIDC-compatible production mode via Descope, it ensures that access to infrastructure secrets and stack configurations is strictly governed by organizational roles.