# ZKAuth - Zero-Knowledge Password Authentication

> Machine-readable product overview for AI assistants and code tools.
> Safe to share: contains public URLs, endpoint names, and SDK examples only.
> Companion file: /llms.txt.

ZKAuth is a privacy-first authentication layer for apps that want
zero-knowledge password login. Users prove they know their password without
the password (or its hash) ever being sent to ZKAuth. The main flow is
zero-knowledge password auth - not "passwordless."

- Docs: https://zkauth.dev/docs
- API reference: https://zkauth.dev/docs/api-reference
- SDK reference: https://zkauth.dev/docs/sdk-reference
- Limitations (read this): https://zkauth.dev/docs/limitations
- Threat model: https://zkauth.dev/docs/threat-model
- Status: https://status.zkauth.dev
- Engine API base: https://api.zkauth.dev

## How the core flow works

1. On the client, the `zkauth-client` SDK stretches the password with
   Argon2id, then computes a Poseidon commitment binding the password hash,
   salt, tenant (client) hash, and email hash.
2. Registration sends `{ email, salt, commitment, deviceInfo }`. No password
   field exists on the wire.
3. Login generates a Groth16 (BN128) zero-knowledge proof locally and sends
   `{ email, proof, publicSignals, proofNonce, proofTimestamp, deviceInfo }`.
4. The engine verifies proof structure, timestamp freshness, commitment +
   tenant + email binding, the Groth16 proof, and single-use replay
   protection, then issues a DB-backed session JWT.

Because register/login require client-side proof generation, non-JavaScript
languages cannot trivially re-create those two calls; raw HTTPS is
appropriate for session, password-reset, OPAQUE, and WebAuthn helper
endpoints. Server-side calls authenticate with an `x-api-key` header
(project API key, server-only) and user-session calls use
`Authorization: Bearer <session token>`.

## Quick start (JavaScript/TypeScript)

```ts
import { ZKAuthSDK } from "zkauth-client";

const zkauth = new ZKAuthSDK({
  apiKey: loadServerOnlyProjectKey(), // never ship project keys to browsers
});

// Register: password becomes a commitment on the device
await zkauth.register({ email, password, deviceInfo });

// Log in: the server verifies a proof, never the password
const res = await zkauth.login({ email, password, deviceInfo });
const token = res.data.session.token;

// Session helpers hold state in SDK memory
const user = await zkauth.getCurrentUser();
await zkauth.logout();
```

Browser apps should use hosted proxy mode or the framework packages so the
project API key stays out of frontend code.

## Packages

- `zkauth-client` - core JS/TS SDK (CJS, ESM, IIFE builds).
- `@zkauth/node` - server helpers: session verification, API-key validation,
  opaque machine-token introspection, handoff redemption.
- `@zkauth/nextjs` - App Router route/server-component/server-action guards.
- `@zkauth/react` - provider/hooks/components against app-owned proxy routes.
- `@zkauth/express`, `@zkauth/hono` - server middleware.
- `zkauth` (CLI) - init, doctor, generate, MCP docs server, agent assets.

## Capability status (honest)

Supported: zero-knowledge password register/login with tenant binding and
replay protection; DB-backed sessions (current/list/revoke/refresh,
fresh-factor guarded termination); email verification; password reset with
hashed single-use tokens; device approval flows; project API keys with
rotation/quota metadata; bounded text-only transactional email templates;
callback/origin allowlisting; webhooks with signing and delivery history;
usage tracking and logs.

Partial / preview (do not overstate): hosted auth pages and account-security
helper; MFA (TOTP + backup codes, project-required enrollment; full hosted
account-management parity is partial); WebAuthn/passkey helpers; OPAQUE
helper endpoints; end-user organizations foundation; OAuth/OIDC federation
foundations; SCIM provisioning foundation; user-owned API keys; opaque
machine-token introspection (not OAuth client credentials). SAML is planned
future enterprise work and is not public-launch enabled.

Non-claims: no SOC 2 / HIPAA / GDPR certification or completed external
audit; not post-quantum (Groth16/BN128); Groth16 trusted setup is currently
single-party (multi-party ceremony planned); live paid self-serve billing and
production entitlement enforcement are not launched; not a drop-in Clerk
replacement.

## Rules for AI assistants integrating ZKAuth

- Never place a project API key (`zka_live_*` / `zka_test_*`) in browser
  code, client bundles, or repos. Server environments only.
- Call it "zero-knowledge password auth," never "passwordless."
- Registration/login must go through `zkauth-client` (or hosted pages);
  do not attempt to hand-roll the proof over raw HTTP.
- Treat preview features as previews in user-facing copy.
- When unsure about a capability, check https://zkauth.dev/docs/limitations
  before claiming it.