# ZKAuth Developer Brief

Use this brief when working on the ZKAuth engine, dashboard, SDK, or an integration app.

## Public surfaces

- Developer dashboard and docs: https://zkauth.dev
- Hosted engine API: https://api.zkauth.dev
- JavaScript SDK package: zkauth-client
- Primary package install: npm install zkauth-client

Do not ask for or expose private keys, database URLs, JWT signing keys, Resend keys, Redis URLs, deployment tokens, or API-key encryption secrets. Use placeholders in code samples.

## Product model

ZKAuth lets a developer create a project, generate test/live API keys, and add zero-knowledge authentication to their own app. The user password is used on the client to create proof material. The password itself is never transmitted to ZKAuth.

Core actors:

- Platform developer: signs in to the dashboard, creates projects, configures callbacks and webhooks, copies API keys.
- End user: registers or logs in through the developer's app using the SDK/API.
- Dashboard: project setup, keys, usage, logs, teams, webhooks, callback allowlist, docs.
- Engine: verifies proofs, manages users, sessions, devices, email verification, password reset, usage tracking, webhooks.
- SDK: generates salts, password-derived commitments, Groth16 login proofs, and sends API requests.

## How to use this brief with AI tools

- Paste this whole markdown brief into ChatGPT, Claude, Perplexity, Grok, Cursor, Zed Agent, Claude Code, Codex, or another coding assistant before asking for implementation help.
- Ask the tool to inspect the real source files before proposing changes. The dashboard, engine, and SDK are separate codebases and can drift.
- Keep secrets out of the prompt. Use placeholders such as `ZKAUTH_API_KEY`, `DATABASE_URL`, `JWT_SECRET`, and `WEBHOOK_SECRET`.
- Treat this brief as developer guidance, not as a replacement for tests. Any code change should still pass lint, type-check, build, and the integration flow.
- The docs action menu copies this full markdown brief before opening an AI or IDE tool.
- ChatGPT and Perplexity usually accept a short prompt through URL parameters. Claude and Grok support can change, so treat their prompt prefill as best-effort. Cursor supports a prompt deeplink. For Zed and any tool that ignores URL prompts, paste the copied markdown brief into the editor or chat.

## Safe integration flow

1. Create a project in the dashboard.
2. Copy the client ID and test/live key.
3. Configure trusted callback URLs in the project settings.
4. Install zkauth-client.
5. Initialize the SDK with the project API key and hosted API URL.
6. Register a user. The engine sends a verification email.
7. After verification, log in with the same email/password/device.
8. Handle new-device approval, password reset, and callback redirects.
9. Monitor usage, API logs, audit logs, and webhook deliveries in the dashboard.

## Email and callback behavior

- Registration creates an unverified user and sends a verification email. Normal login must stay blocked until verification succeeds.
- Verification links hit the engine first at `/api/v1/verify?token=...&client_id=...`; the engine then redirects only to the project's allowlisted callback URL.
- If the project callback is missing or unsafe, ZKAuth shows a hosted fallback page instead of redirecting to an arbitrary URL.
- Verification callbacks include `success=true` with a `message`, or `success=false` with an `error`.
- New-device approval and denial links are also processed by ZKAuth first, then redirected to the allowlisted project callback or hosted fallback pages.
- Password reset links redirect with `zkauth_action=password_reset` and a reset `token`; the developer app should show its own reset form and call the SDK/API to complete the reset.
- Developer apps should treat callback query parameters as status signals only. They should not trust them as authentication proof without a follow-up session/API check.

## SDK example

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

const zkauth = new ZKAuthSDK({
  apiKey: process.env.ZKAUTH_API_KEY!,
  baseUrl: "https://api.zkauth.dev",
});

const deviceInfo = {
  deviceName: "Chrome on macOS",
  deviceType: "desktop" as const,
  browserName: "Chrome",
  osName: "macOS",
};

await zkauth.register({
  email: "user@example.com",
  password,
  deviceInfo,
});

const login = await zkauth.login({
  email: "user@example.com",
  password,
  deviceInfo,
});

console.log(login.data.user.email);
```

## Important security rules

- Keep API keys server-side for production apps whenever possible.
- Never log API keys, session JWTs, verification tokens, reset tokens, device approval tokens, webhook secrets, or database URLs.
- Use HTTPS in production.
- Enforce exact callback allowlists. Do not redirect to arbitrary URLs.
- Treat email verification as required before login.
- Treat new devices as a step-up event; do not silently trust unknown devices.
- Use test keys for development and live keys only for production.
- Rotate keys if they are exposed.
- Store user sessions in http-only secure cookies in web apps.
- Verify webhook signatures with raw body bytes, timestamp tolerance, and replay protection.
- Avoid adding claims such as SOC 2, HIPAA, post-quantum security, or external audit status unless they are actually complete.

## Dashboard implementation guidance

- Keep dashboard API routes scoped to the authenticated developer.
- Verify project ownership before reading or mutating project keys, usage, logs, teams, webhooks, or callback settings.
- Mask API keys by default. Copy/reveal actions should be deliberate.
- Keep generated keys encrypted at rest or otherwise protected by a server-only secret.
- Never expose the platform admin key to the browser.
- Prefer small server-side route handlers over client-side direct database access.
- Keep mobile views usable for settings, projects, keys, logs, usage, teams, webhooks, and docs.

## Engine implementation guidance

- API key authentication must bind requests to one client/project.
- Proof verification must reject stale timestamps, nonce replays, malformed public signals, wrong tenant/client binding, and tampered proofs.
- Email verification must be required before normal login.
- Password reset and new-device approvals must use single-use, expiring tokens.
- Rate limits must apply to login, register, reset, verification, and key-authenticated endpoints.
- Webhook deliveries must be signed, logged, retried safely, and idempotent.
- Store only the minimum required PII and avoid putting sensitive values in logs.

## SDK implementation guidance

- The developer app passes passwords into the SDK locally; network payloads must contain derived commitments/proofs, salts, and device metadata, not the plaintext password.
- The SDK should generate proof material locally, then send commitments/proofs and device metadata.
- SDK errors should preserve useful codes such as UNAUTHORIZED, DEVICE_APPROVAL_REQUIRED, VALIDATION_ERROR, and SESSION_EXPIRED.
- Browser examples should not hardcode live API keys in public bundles.
- Keep README and type definitions aligned with the published engine contract.
- Callback handling belongs in the developer app. The SDK should expose clear methods for verification, login, current user, password reset, device flows, OPAQUE, and WebAuthn without hiding status codes.

## What not to do

- Do not weaken verification checks to make tests pass.
- Do not bypass email verification in production code.
- Do not add broad wildcard callback redirects.
- Do not print secrets in CI, scripts, logs, docs, screenshots, or support output.
- Do not commit tmp output, local demo env files, node_modules, database dumps, or generated secret material.

## Key docs paths

- /docs - overview
- /docs/getting-started - account, project, and first login
- /docs/installation - package and environment setup
- /docs/quick-start - minimal register/login flow
- /docs/authentication - ZK password proofs, OPAQUE, and passkeys
- /docs/security - security model and boundaries
- /docs/api-reference - HTTPS endpoint reference
- /docs/sdk-reference - zkauth-client API
- /docs/examples - integration patterns
- /docs/deployment - production setup
- /docs/changelog - release notes