Security Model

SAM’s security model separates platform secrets (managed by operators) from user credentials (encrypted per-user in the database).

Credential Types

Platform Secrets

These are Cloudflare Worker secrets set during deployment:

Secret	Purpose
`ENCRYPTION_KEY`	AES-256-GCM key for encrypting user credentials
`JWT_PRIVATE_KEY`	RSA-2048 key for signing workspace and callback tokens
`JWT_PUBLIC_KEY`	RSA-2048 key for token verification (exposed via JWKS)
`CF_API_TOKEN`	Cloudflare deploy, DNS, Origin CA certificate issuance, observability, and AI Gateway operations (requires Account → SSL and Certificates → Edit)

Security keys are automatically generated and persisted by Pulumi on first deployment. Cloudflare secrets remain Worker secrets because they are deployment trust roots. GitHub App/OAuth, GitHub webhook, and Google OAuth credentials can be supplied either as optional environment fallbacks or through the first-run/superadmin platform config UI; runtime values are stored encrypted in D1 and override environment fallbacks. They never appear in source control.

Platform Integration Credentials

Admin-managed integration secrets stored encrypted in D1:

Credential	Purpose	Resolution order
GitHub OAuth client secret	GitHub sign-in and OAuth refresh	Runtime D1 → Worker env → unset
GitHub App private key	Installation tokens for repository access	Runtime D1 → Worker env → unset
GitHub webhook secret	GitHub App webhook HMAC verification	Runtime D1 → Worker env → unset
Google login OAuth client secret	Google sign-in (BetterAuth social login)	Runtime D1 → Worker env (`GOOGLE_LOGIN_CLIENT_SECRET`) → unset
Google infra OAuth client secret	GCP deployment authorization flows (separate client from login)	Worker env (`GOOGLE_CLIENT_SECRET`) → unset

User Credentials

User-provided secrets stored encrypted in D1:

Credential	Purpose	Encryption
Hetzner API token	VM provisioning	AES-256-GCM, per-credential IV
Agent API keys	Claude/OpenAI API access	AES-256-GCM, per-credential IV
Agent OAuth tokens	Claude Pro/Max subscriptions	AES-256-GCM, per-credential IV

User credentials are never stored as environment variables or Worker secrets.

Authentication Flow

SAM uses BetterAuth with GitHub OAuth for user authentication:

User clicks “Sign in with GitHub”
API redirects to GitHub OAuth
GitHub returns authorization code
API exchanges code for access token
API fetches user profile and primary email
BetterAuth creates/updates user record and session
Session cookie set in browser

Token Types

Token	Lifetime	Purpose	Validated By
Session cookie	Hours	Browser authentication	API Worker (BetterAuth)
Workspace JWT	Minutes	Terminal WebSocket auth	VM Agent (via JWKS)
Bootstrap token	5 minutes	One-time VM credential injection	API Worker
Callback token	Minutes	VM Agent → API callbacks	API Worker

Credential Encryption

User credentials are encrypted at rest using AES-256-GCM:

Encrypt: plaintext + ENCRYPTION_KEY → { ciphertext, iv }  (stored in D1)
Decrypt: { ciphertext, iv } + ENCRYPTION_KEY → plaintext   (on-demand)

Each credential gets a random initialization vector (IV), ensuring identical plaintext values produce different ciphertext.

Terminal Authentication

Terminal WebSocket connections use short-lived JWTs:

Browser requests a terminal token: POST /api/terminal/token
API signs a JWT with the workspace ID and user ID
Browser connects: wss://ws-{id}.domain/workspaces/{id}/shell?token=...
Worker proxies the WebSocket to the VM Agent
VM Agent validates the JWT against the API’s JWKS endpoint (/.well-known/jwks.json)

Bootstrap Security

When a new VM starts, it needs credentials (callback URL, node ID) but no secrets are embedded in cloud-init:

API creates a one-time bootstrap token (cryptographically random, 5-minute expiry)
Cloud-init script includes only the token and API URL
VM Agent redeems the token: POST /api/bootstrap/{token}
API returns the full configuration (callback URL, node ID, etc.)
Token is invalidated after use

VM TLS Certificates

New nodes use per-node Origin CA key material rather than a platform-shared private key:

The API Worker passes a node-scoped certificate endpoint into cloud-init (apps/api/src/services/nodes.ts).
Cloud-init generates /etc/sam/tls/origin-ca-key.pem locally on the VM, creates a CSR, and posts only that CSR to POST /api/nodes/:id/origin-ca-certificate with the node callback JWT (packages/cloud-init/src/template.ts).
The API Worker verifies the callback token is node-scoped and matches :id, then signs the CSR through Cloudflare Origin CA using CF_API_TOKEN (apps/api/src/routes/node-lifecycle.ts, apps/api/src/services/origin-ca-certificates.ts).
The VM stores the returned certificate at /etc/sam/tls/origin-ca.pem and starts the VM agent with TLS_CERT_PATH and TLS_KEY_PATH.

The certificate hostnames remain wildcard-scoped (*.BASE_DOMAIN, *.vm.BASE_DOMAIN, and BASE_DOMAIN) so existing ws-* and {node}.vm routing continues to work. The private key is no longer shared across nodes or embedded in static cloud-init user-data. Each node receives a distinct private key and short-lived certificate, with ORIGIN_CA_CERT_VALIDITY_DAYS defaulting to 7 days.

Legacy Origin CA Rotation

Deployments created before the per-node CSR model may have running nodes that still hold a broadly distributed wildcard ORIGIN_CA_KEY. Rotate that legacy material by draining or deleting old nodes, deploying the per-node certificate model, revoking the old wildcard Origin CA certificate in Cloudflare SSL/TLS → Origin Server, and removing any manually configured ORIGIN_CA_CERT/ORIGIN_CA_KEY Worker secrets. New nodes do not require those Worker secrets.

Security Best Practices

Rotate keys quarterly — regenerate JWT and encryption keys
Minimal GitHub App permissions — only Contents (read/write), Metadata (read-only), and Email addresses (read-only)
HTTPS everywhere — all traffic encrypted via Cloudflare
Session isolation — each workspace JWT is scoped to a specific workspace ID
No shared cloud credentials — BYOC model means the platform has no Hetzner access