​
Authentication

Diminuendo supports two authentication methods:

​
Auth0 JWT

Production authentication via Auth0:
  1. Client authenticates with Auth0 and receives a JWT
  2. JWT is sent in the Authorization: Bearer <token> header or as WebSocket subprotocol
  3. Gateway verifies JWT signature using Auth0 JWKS endpoint (cached with LRU)
  4. User identity and tenant are extracted from JWT claims

​
Dev Mode

When DEV_MODE=true, authentication is bypassed:
  • All requests are auto-authenticated as developer@example.com
  • Useful for local development without Auth0 setup

​
RBAC

​
Roles

RoleLevelDescription
owner5Full access + billing + tenant deletion
admin4Full access except billing
developer3CRUD threads/projects, deploy agents
viewer2Read-only access
guest1Limited thread access

​
Permissions

PermissionRequired RoleDescription
threads.createdeveloperCreate new threads
threads.readviewerRead thread history
threads.writedeveloperSend messages, steer, approve
threads.deleteadminDelete threads
projects.createdeveloperCreate projects
projects.manageadminManage project settings
members.manageadminAdd/remove members, change roles
integrations.manageadminConfigure chat integrations
config.manageadminUpdate tenant settings
deployments.manageadminDeploy agents
audit.readadminRead audit logs
billing.manageownerManage billing

​
Permission Check

requirePermission(identity, 'threads.create');
// Throws 403 if identity.role lacks the required permission

​
Security Features

​
CSRF Protection

Non-GET requests require a CSRF token (except webhooks and dev mode):
  • Token generated per session
  • Validated on every mutating request

​
Rate Limiting

HTTP rate limiting per API key/user:
  • Configurable per-endpoint limits
  • 429 response with Retry-After header

​
Security Headers

All responses include security headers:
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Strict-Transport-Security (production)
  • Content-Security-Policy

​
SSRF Guard

File operations and webhook URLs are validated against SSRF:
  • Private IP ranges blocked
  • DNS rebinding protection
  • Allowlisted domains only

​
Error Sanitization

Production error responses never leak internal details:
  • Stack traces stripped
  • Database errors replaced with generic messages
  • Request IDs included for correlation