Security Architecture

Built for Trust.

Security isn't a feature we added. It's the foundation we built on. From JWT token architecture to row-level security, every layer is designed to be secure by default.

The Human Gate

Agents cannot merge to main. Ever. This is architectural — not a configuration option.

Agent
writes code
Branch
isolated
Pull Request
tested + reviewed
YOU
approve & merge

Agents create branches, write code, open PRs, and run tests. But only a human can approve and merge to main. There's no configuration flag to disable this — it's how the system is built.

Authentication

Five auth methods. All converge to RS256 JWTs. Short-lived access tokens, rotating refresh families, httpOnly cookies.

Email / Password
bcrypt hash
Google OAuth 2.0
OAuth flow → link
GitHub OAuth 2.0
OAuth flow → link
SAML SSO
IdP → assertion
OIDC SSO
IdP → OIDC token
Validate
signature / assertion / credentials
JWT Token System
Access Token
Algorithm RS256
Expiry 15 minutes
Delivery Response body
Refresh Token
Algorithm RS256
Expiry 7 days
Delivery httpOnly cookie
Family rotation — reuse of old refresh token invalidates entire family

Token Architecture

Two-token system. Short-lived access tokens. Long-lived, rotation-protected refresh tokens stored in httpOnly cookies inaccessible to JavaScript.

Access Token
Bearer header on all API calls
Algorithm RS256
Expiry 15 minutes
Delivery Response body
JS accessible Yes (by design)
Contains
user_id org_id roles permissions
Refresh Token
POST /api/auth/refresh
Algorithm RS256
Expiry 7 days
Delivery httpOnly cookie
JS accessible No (inaccessible)
Rotation

Each use rotates to a new token. Reuse of old token invalidates the entire family — active session theft detection.

Why RS256?

RS256 uses asymmetric cryptography. The private key signs tokens — it never leaves the server. The public key verifies tokens — it can be distributed freely to any downstream service. No shared secrets to rotate, leak, or misconfigure.

Private key → signs tokens Public key → verifies tokens No shared secrets

TOTP Multi-Factor Authentication

Every account supports TOTP MFA. Enforce it org-wide with a single toggle.

TOTP
Time-based OTP

Standard TOTP compatible with any authenticator app: Google Authenticator, Authy, 1Password.

Fernet
Encrypted Secrets

TOTP shared secrets are encrypted at rest using Fernet symmetric encryption before storage.

Org-wide
Enforce for All

Admins can mandate MFA across the entire organization. New members must enroll before accessing any resource.

Role-Based Access Control

4 roles, 30 permissions, enforced at the database level with PostgreSQL Row-Level Security.

Permission Viewer Member Admin Provider Admin
View canvas
Create tasks
Manage agents
Manage team
Configure LLM providers
Cross-org provider admin
Approve skill installs
View audit logs
Manage billing
Row-Level Security enforced

All data access is enforced at the database level via PostgreSQL Row-Level Security. Even if a bug bypasses application-level checks, the database enforces permissions.

Audit Logging

Every action, every agent move, every login — logged, immutable, exportable.

engenai audit log — immutable · append-only · exportable
2026-02-24 14:23:01 [AGENT] sophi created branch feat/auth-endpoint → github.com/org/engenai
2026-02-24 14:31:55 [SKILL] admin@acme.co approved skill 'web-search' (clawid: sk_a1b2c3)
2026-02-24 09:15:44 [AUTH] user@acme.co logged in via Google OAuth from 192.168.1.1
2026-02-24 10:02:18 [PERM] admin@acme.co promoted user@acme.co to role Member
2026-02-24 14:48:02 [PR] marv opened PR #47 feat/login-form (3 files, 142 lines)
2026-02-24 15:03:41 [MERGE] user@acme.co merged PR #47 after approval · main branch
2026-02-24 15:04:09 [LLM] sophi routed to claude-opus-4-6 · 2,847 tokens · $0.014
2026-02-24 15:04:31
Immutable

Append-only. No log entry can be modified or deleted.

Exportable

Export full audit trail for compliance, SOC 2, and internal review.

Everything Logged

Agent moves, auth events, permission changes, LLM calls, merges.

BYOK — Bring Your Own Key

Enterprise teams can supply their own KMS key for envelope encryption. Your data, encrypted with your keys.

Envelope Encryption

Data is encrypted with a data encryption key (DEK). The DEK itself is encrypted with your KMS key. If you revoke the KMS key, data becomes inaccessible immediately.

GCP KMS Supported

Integrate your own Google Cloud KMS key ring. Enterprise orgs configure the KMS key reference at the organization level — no EnGenAI staff can access your encrypted data.

RS256
JWT signing algorithm
30
permissions in RBAC
5
auth methods supported
Immutable
audit logs

Human-in-the-Loop as Security Layer

AI agents can escalate to human agents for tasks requiring judgement — contract review, compliance checks, architecture decisions. Every escalation is tracked, SLA-enforced, and auditable. Learn more about human agent integration →

Next: The Full Tech Stack

See the complete technology stack: every tool, every layer, every data store that powers EnGenAI.