Security model

Threat model

This model defines what ZKAuth is trying to protect, which attackers are in scope, and which risks remain outside the current system boundary.

Assets

• Password-derived secrets
• User salts and commitments
• Groth16 proof public signals
• Project API keys
• Scoped end-user API keys
• Session JWTs and refresh state
• Email verification tokens
• Password reset tokens
• Device approval and denial tokens
• Hosted session handoff codes
• Organization memberships, roles, invitations, verified domains, and audit events
• Webhook signing secrets
• Usage, quota, and rate-limit counters
• Dashboard re-authentication state for high-risk actions
• Opaque credentials and OPAQUE login sessions
• WebAuthn challenges and passkey credential metadata

Attackers in scope

• Malicious tenant attempting cross-project access
• Malicious user attempting replay or tampered proof login
• Attacker with a stolen project API key
• Attacker with a stolen scoped user API key
• Attacker with a stolen session token
• Attacker with a leaked organization invitation token
• Malicious organization member attempting privilege escalation
• Compromised email inbox during verification or reset
• Network attacker blocked by TLS assumptions
• Open-redirect attacker controlling callback parameters
• Webhook receiver attempting replay or malformed delivery handling
• Rogue dashboard operator or compromised dashboard session

Trust assumptions

• Groth16 proof soundness for the selected circuit and verification key
• Correct client-side password derivation and proof generation
• TLS for dashboard, engine, and developer application traffic
• Redis availability for production replay protection where configured
• Server-only storage for project API keys, JWT secrets, and webhook secrets
• Email provider availability and verified sending domain configuration
• Exact callback allowlists for verification, device approval, and reset flows
• Dashboard and engine database targets remain separated by purpose and credentials
• High-risk dashboard operations require recent re-authentication

Non-goals

• Malware or keylogger on the user's device
• A fully compromised tenant application backend
• A malicious browser extension with page access
• No post-quantum security for the current Groth16/BN128 login proof
• Full formal verification of the deployed implementation
• No universal hardware authenticator compatibility
• Certified enterprise SSO or SCIM provider parity before live-provider runs and compatibility notes are complete
• Billing, seat enforcement, or enterprise compliance evidence before those programs are complete

Required invariants

• API-key tenant context must be established before handlers run.
• Tenant IDs from requests must not override authenticated context.
• Proof public signals must bind tenant/client and email hashes.
• Replay protection must fail closed in production.
• Verification, reset, device, OPAQUE, and WebAuthn challenge state must be single-use.
• Hosted handoff codes must be short-lived, single-use, project-bound, and redeemed only from trusted server code.
• User API keys must remain scoped to one project and one user; they must not be accepted as project API keys or browser-safe credentials.
• Organization roles, invitations, verified domains, teams, and audit events must stay project-bound and cannot cross tenants.
• Device approval and denial must be separate tenant-bound decisions; the first valid decision wins.
• Callback redirects must match exact project allowlists.
• High-risk actions such as key rotation, destructive user operations, organization mutation, and sensitive account changes must create audit events.
• Secrets must not appear in logs, docs, diagnostics, or UI output.

For evidence linked to these properties, see Evidence. For product boundaries, see Limitations.