{"id":50737960,"url":"https://github.com/shizhigu/agent-auth","last_synced_at":"2026-06-10T15:30:25.366Z","repository":{"id":354926720,"uuid":"1225995853","full_name":"shizhigu/agent-auth","owner":"shizhigu","description":"Production-grade auth rail for AI agents. Sits next to your existing human auth — never replaces it.","archived":false,"fork":false,"pushed_at":"2026-05-01T01:16:10.000Z","size":1090,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T01:16:54.034Z","etag":null,"topics":["agent-auth","ai-agents","api-keys","audit-log","authentication","authorization","hmac","kms","libsodium","nodejs","oauth","postgres","rate-limiting","redis","security","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/shizhigu/agent-auth#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shizhigu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"audit/round-1-prompt.md","citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T21:36:06.000Z","updated_at":"2026-05-01T01:16:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shizhigu/agent-auth","commit_stats":null,"previous_names":["shizhigu/agent-auth"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shizhigu/agent-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shizhigu%2Fagent-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shizhigu%2Fagent-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shizhigu%2Fagent-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shizhigu%2Fagent-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shizhigu","download_url":"https://codeload.github.com/shizhigu/agent-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shizhigu%2Fagent-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34159247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-auth","ai-agents","api-keys","audit-log","authentication","authorization","hmac","kms","libsodium","nodejs","oauth","postgres","rate-limiting","redis","security","typescript"],"created_at":"2026-06-10T15:30:24.435Z","updated_at":"2026-06-10T15:30:25.349Z","avatar_url":"https://github.com/shizhigu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/brand/logo-mark-color.svg\" alt=\"\" width=\"64\" height=\"64\"\u003e\n\n# Vouch\n\n**Identity infrastructure for AI agents.**\n**Drop it next to your existing human auth — never replaces it.**\n\n\u003csub\u003eThe open-source engine ships as `@vouch/server` on npm. Hosted Vouch Cloud is on the [roadmap](#roadmap) for v1.0.\u003c/sub\u003e\n\n[![CI](https://github.com/shizhigu/agent-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/shizhigu/agent-auth/actions/workflows/ci.yml)\n[![Security](https://github.com/shizhigu/agent-auth/actions/workflows/security.yml/badge.svg)](https://github.com/shizhigu/agent-auth/actions/workflows/security.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-brightgreen.svg)](https://nodejs.org)\n[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6.svg?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Tests](https://img.shields.io/badge/tests-393%20unit%20%C2%B7%2094%20integration%20%C2%B7%2014%20chaos-success)](#testing)\n\n[Status](#project-status) ·\n[Why](#why-vouch) ·\n[Comparison](#comparison-vs-better-auth--auth0--clerk--nango) ·\n[Quick start](#quick-start) ·\n[How it works](#how-it-works) ·\n[Architecture](#architecture) ·\n[Roadmap](#roadmap)\n\n\u003c/div\u003e\n\n---\n\n## Project status\n\n**Server-side engine: feature-complete (v0.2).** All 8 milestones shipped + DX completeness sweep (factory, Hono, monorepo, CLI, scaffolder, multi-provider, docs site, OTel, brand assets) — `393` unit · `94` integration · `14` chaos tests passing at HEAD. Spec audited across 13 rounds with codex / GPT-5; final grade A (production-ready paying-customer level).\n\n**What is NOT shipped yet** — and why this matters for you:\n\n| | Status | Plan |\n|---|---|---|\n| Published on npm (`@vouch/server`) | **No** — names reserved (`agent-auth` was taken), publish pending user OK | next |\n| Agent-side SDK (`@vouch/client`) | **Dev preview** — lives in [`packages/client/`](packages/client/) (not yet on npm) | v0.2 |\n| CLI scaffolder (`npx create-vouch-app`) | **Yes** — Express SaaS or Node agent in one command, ready to run | shipped |\n| Reference end-to-end demo (SaaS + agent) | **Yes** — runnable in `apps/demo/` (Postgres + Redis via docker compose, no AWS / GitHub OAuth needed) | v0.2 |\n| Docs site | **Yes** — VitePress site under [`apps/docs/`](apps/docs/), 9 pages, `npm run docs:dev` to preview | shipped |\n| Multi-provider identity | **Yes** — `identity.github`, `identity.google`, `identity.oidc` (auto-discovery), or any pre-built `IdentityProvider` via `identity.custom` | shipped |\n| Migration runner (`vouch migrate up`) | **Yes** — `@vouch/cli` ships forward + rollback + status; tracking table auto-created | shipped |\n| Vouch Cloud (hosted + admin dashboard) | **No** — self-host only | v1.0 |\n\nIf you want to **try it today**, see [Quick start](#quick-start). If you want to **build production on top of it**, the realistic ETA is **v0.2 (~4 weeks)** when DX completes — the server-side core is solid, but the rough edges are real.\n\n## Why Vouch\n\nToday's \"agent signup\" stories don't hold up:\n\n- **CAPTCHAs and email verification** block headless flows\n- **Browser automation** (the \"have the agent click around\") is brittle, slow, and a security nightmare\n- **Sharing a human's password** is unauditable, can't be scoped, and can't be instantly revoked\n\nVouch solves this by giving the agent **its own first-class identity** — rooted in a human's existing GitHub login, scoped to a single tenant, with full audit trail and instant revocation. You drop the engine into your SaaS backend; your existing human auth keeps working unchanged.\n\n```ts\n// Existing human auth — UNTOUCHED\napp.use('/api/v1', humanAuth.middleware);    // sets req.user\n\n// New agent auth — lives on req.agent (per SPEC §6.3 confused-deputy prevention)\napp.use('/api/agent/v1', agentAuthMiddleware);\n\napp.get('/api/agent/v1/data', (req, res) =\u003e {\n  req.agent.require_scope('read');                    // throws 403 on miss\n  return queryDb({ tenant_id: req.agent.account_id }); // RT-9 tenant isolation\n});\n```\n\n## Comparison vs Better Auth / Auth0 / Clerk / Nango\n\nVouch is **complementary** to existing auth tools, not a competitor. It plugs a gap none of them cover today.\n\n### Quick map\n\n\u003e - **Better Auth · Auth0 · Clerk · Lucia** → \"humans log into your SaaS\"\n\u003e - **Nango · Arcade · Auth0 for AI Agents** → \"your code calls third-party APIs (Slack, GDrive, …) on behalf of an authenticated human\"\n\u003e - **Vouch (this)** → \"AI agents register accounts on YOUR SaaS and get their own scoped API keys\"\n\u003e\n\u003e If you're building Acme SaaS and want Claude Code / Cursor / Codex to autonomously sign up for an Acme account on a human's behalf and call the Acme API: **Vouch fills that gap**. None of the others do.\n\n### Detailed table\n\n| | **Better Auth · Lucia** | **Auth0 · Clerk** | **Nango · Arcade · Auth0-for-AI-Agents** | **Vouch (this)** |\n|---|---|---|---|---|\n| **Whose identity** | the human | the human | the human (token forwarded to 3rd-party APIs) | the agent itself |\n| **You are the…** | service humans log into | service humans log into | service that calls 3rd-party APIs | service the agent calls |\n| **Hosted option** | Better Auth Cloud | Yes (default) | Yes | Vouch Cloud (v1.0); self-host only today |\n| **DB ownership** | your DB | their DB | your DB | your DB |\n| **Headless agent flow** | n/a | n/a | partial (token broker) | designed for it (PKCE + sealed-box) |\n| **API key issuance** | session cookies primarily | sessions / JWT / API keys | n/a | API keys (scoped, rotatable, instantly revocable) |\n| **Audit chain (cryptographic)** | basic logs | yes (paid) | basic logs | append-only hash chain + WORM mirror |\n| **Multi-tenant by default** | yes | yes | yes | yes (`req.agent.account_id` enforced) |\n| **Self-hostable** | yes | no | yes (some) | yes (only mode at v0.1) |\n| **Supply-chain hardening** | varies | n/a | varies | OIDC publish + Sigstore + SBOM + Scorecard |\n\n### What Vouch is NOT\n\n- Not a replacement for Clerk / Auth0 / Better Auth — those handle **human** auth.\n- Not browser automation — Browserbase / Skyvern occupy that space.\n- Not an agent governance / observability platform.\n- Not a token vault for already-authorized SaaS APIs.\n- Not a marketplace or payment rail for agents.\n\n## Features\n\n- **Drop-in middleware** for Express, Hono, and any framework via the framework-agnostic core. Adapters take 5 lines each.\n- **Two-stage trust** — registration via GitHub OAuth + PKCE; runtime validation via HMAC + KMS-held pepper. No Argon2id at the hot path (3 µs cache hit, 6.5 µs cache miss in benchmarks).\n- **Sealed-box key delivery** (libsodium `crypto_box_seal`) — the agent's pubkey gates the one-shot key drop. Stolen poll tokens cannot extract the key.\n- **Postgres-authoritative** with Redis as 30-second-bounded cache. Worst-case staleness is provable; correctness never depends on Redis alone.\n- **Tier B durability** — high-stakes mutations use `synchronous_commit=remote_apply` + two-phase idempotency. Network blips during commit produce deterministic outcomes (`completed` / `failed` / `unknown`), never silent loss.\n- **Append-only audit chain** — Postgres trigger derives `prev_hash`/`row_hash`; hourly verifier walks the chain; WORM mirror in S3 Object Lock for SOC 2 / GDPR.\n- **Multi-region active-passive** with LSN barrier + timeline-aware revocation. Failover playbook (RB-8) included.\n- **Instant revocation** — Postgres write + Redis epoch bump + pubsub broadcast invalidates every cache in \u003c 30 s.\n- **GCRA rate limiting** at the edge (Lua atomic in Redis) with multi-dimensional per-IP / per-account / per-tenant short-circuits.\n- **44-threat threat model** mapped to controls; 32 with automated tests (unit / integration / chaos / property), 11 explicitly operational, 1 reserved.\n- **9 admin runbooks** (RB-1..RB-9) covering revocation drift, oncall paging, KMS key rotation, cross-region failover, etc.\n\n## Quick start\n\n\u003e **Heads up** — packages aren't on npm yet. Until v0.2 publishes, scaffold from this repo by passing `--template-dir` to `create-vouch-app` or install via `file:` link.\n\n### One command (when published)\n\n```bash\nnpx create-vouch-app my-saas\ncd my-saas\ncp .env.example .env\ndocker compose up -d\nnpx vouch migrate up\nnpm install\nnpm run dev\n```\n\nThat's it — `create-vouch-app` writes a working Express SaaS template, `vouch migrate up` applies the schema, `npm run dev` starts the server with hot reload. See [`packages/create-vouch-app`](packages/create-vouch-app/) for templates (`saas-express`, `agent`).\n\n### Install from source (today, pre-npm-publish)\n\n```bash\ngit clone https://github.com/shizhigu/agent-auth.git\ncd agent-auth\nnpm install \u0026\u0026 npm run build\n# Then in your SaaS project:\nnpm install /path/to/agent-auth\n```\n\n### Apply the database schema\n\n```bash\nnpm install -D @vouch/cli\nDATABASE_URL=postgres://… npx vouch migrate up\n```\n\n`vouch migrate status` shows pending vs applied; `vouch migrate down --steps 1` rolls back. Tracking lives in a `vouch_migrations` table the CLI creates automatically. See [`packages/cli/README.md`](packages/cli/README.md) for the full reference.\n\n### Wire it up (Express)\n\n```ts\nimport express from 'express';\nimport { vouch } from 'agent-auth';\n\ndeclare module 'express-serve-static-core' {\n  interface Request {\n    agent?: import('agent-auth').AgentContext; // NOT req.user — see SPEC §6.3\n  }\n}\n\nconst auth = await vouch({\n  database: { url: process.env.DATABASE_URL! },\n  redis: { url: process.env.REDIS_URL! },\n  kms: {\n    provider: 'aws',\n    region: 'us-east-1',\n    pepper_alias: 'alias/vouch-pepper',\n    device_alias: 'alias/vouch-device-flow',\n    pepperFetcher: async (v) =\u003e /* read pepper bytes from KMS */ Buffer.alloc(32),\n  },\n  identity: {\n    github: {\n      client_id: process.env.GH_CLIENT_ID!,\n      client_secret: process.env.GH_CLIENT_SECRET!,\n      webhook_secret: process.env.GH_WEBHOOK_SECRET!,\n      app_private_key_pem: process.env.GH_APP_PRIVATE_KEY!,\n    },\n  },\n  internal_secret: process.env.AGENT_AUTH_INTERNAL_SECRET!,  // base64\n  base_url: process.env.PUBLIC_BASE_URL!,\n});\n\nconst app = express();\nauth.express.mount(app);                                     // /agent-auth/*\napp.use('/api/agent/v1', auth.express.middleware());         // protect your API\n\napp.get('/api/agent/v1/whoami', (req, res) =\u003e {\n  res.json({ account_id: req.agent!.account_id, scopes: req.agent!.scopes });\n});\n\napp.listen(8080);\n```\n\nThat's it — `vouch()` builds Postgres / Redis / KMS adapters, wires the 12 lifecycle routes (`begin-registration`, `callback`, `registration-status`, `rotate-key`, `revoke`, `recover-account*`, `webhooks/:provider`, `healthz`, `well-known`, `list-keys`), handles raw-body parsing for webhook signature verification, and runs `redis.loadScripts()` + `sealedBoxReady()` for you.\n\n### Identity providers\n\nPick one or more — they're additive:\n\n```ts\nconst auth = await vouch({\n  // ... database / redis / kms / internal_secret as above ...\n  identity: {\n    github: {\n      client_id: process.env.GH_CLIENT_ID!,\n      client_secret: process.env.GH_CLIENT_SECRET!,\n      webhook_secret: process.env.GH_WEBHOOK_SECRET!,\n      app_private_key_pem: process.env.GH_APP_PRIVATE_KEY!,\n    },\n    google: {\n      client_id: process.env.GOOGLE_CLIENT_ID!,\n      client_secret: process.env.GOOGLE_CLIENT_SECRET!,\n      hosted_domain: 'acme.com',  // optional — restrict to one Workspace\n    },\n    oidc: {\n      // Generic OIDC — any standards-compliant IdP via discovery.\n      name: 'okta',\n      issuer_url: 'https://your-tenant.okta.com',\n      client_id: process.env.OKTA_CLIENT_ID!,\n      client_secret: process.env.OKTA_CLIENT_SECRET!,\n    },\n  },\n});\n```\n\nNeed a provider Vouch doesn't ship? Implement `IdentityProvider` and pass it via `identity.custom: [yourProvider]`. Each registration session picks one provider via `request.body.provider` (e.g. `'github_app' | 'google' | 'okta'`).\n\n### Same wiring on Hono\n\nVouch ships a Hono adapter for Bun / Cloudflare Workers / Deno deployments. Same `vouch()` call, then:\n\n```ts\nimport { Hono } from 'hono';\nimport { vouch } from 'agent-auth';\nimport { honoRoutes, honoAppMiddleware } from 'agent-auth/hono';\n\nconst auth = await vouch({ /* same config as above */ });\n\nconst app = new Hono();\napp.route('/agent-auth', honoRoutes(auth));            // lifecycle routes\napp.use('/api/agent/v1/*', honoAppMiddleware(auth));   // protect your API\n\napp.get('/api/agent/v1/whoami', (c) =\u003e {\n  const agent = c.get('agent');\n  return c.json({ account_id: agent.account_id, scopes: agent.scopes });\n});\n```\n\nThe Hono router is built off the same framework-agnostic `auth.lifecycle` that backs Express, so behavior is identical down to the route bodies and error shapes.\n\nFor the **agent side**, use [`@vouch/client`](packages/client/) — 5 lines from `register()` to authenticated `fetch()`:\n\n```ts\nimport { register } from '@vouch/client';\n\nconst vouch = await register({\n  saas_url: 'https://my-saas.com',\n  provider: 'github_app',\n  onChallengeUrl: (url) =\u003e console.log('Authorize at:', url),\n});\n\nconst me = await vouch.fetch('/api/agent/v1/whoami').then((r) =\u003e r.json());\n```\n\nNeed full control over adapters (custom Pool, BYO Redis, audit WORM, etc.)? See [`examples/express-integration.ts`](examples/express-integration.ts) for the manual wiring path. Need to try it locally first? See [`apps/demo/`](apps/demo/) — Postgres + Redis via docker compose, runs end-to-end in 5 minutes.\n\n## How it works\n\nThe registration flow (the part that actually sets agent-auth apart):\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant Agent as AI Agent\n    participant SaaS as SaaS Backend (your app)\n    participant Lib as agent-auth lib\n    participant GH as GitHub OAuth\n    participant Owner as Account Owner (human)\n\n    Agent-\u003e\u003eSaaS: POST /agent-auth/begin (intent=register, client_pubkey)\n    SaaS-\u003e\u003eLib: beginRegistration(...)\n    Lib--\u003e\u003eSaaS: { redirect_url, poll_token }\n    SaaS--\u003e\u003eAgent: { redirect_url, poll_token }\n\n    Agent-\u003e\u003eOwner: open redirect_url in browser\n    Owner-\u003e\u003eGH: authorize via PKCE + state\n    GH-\u003e\u003eSaaS: GET /agent-auth/callback?code=...\u0026state=...\n    SaaS-\u003e\u003eLib: handleCallback(...)\n    Lib-\u003e\u003eLib: verify PKCE + state nonce (single-use)\n    Lib-\u003e\u003eLib: mint scoped API key, HMAC + KMS pepper\n    Lib-\u003e\u003eLib: sealed-box encrypt for client_pubkey\n\n    loop poll\n      Agent-\u003e\u003eSaaS: GET /agent-auth/registration-status (poll_token)\n      SaaS--\u003e\u003eAgent: { status: \"pending\" | \"ready\" }\n    end\n\n    SaaS--\u003e\u003eAgent: { status: \"ready\", encrypted_payload }\n    Agent-\u003e\u003eAgent: sealed-box decrypt → bearer key (pak_...)\n    Agent-\u003e\u003eSaaS: GET /api/... (Authorization: Bearer pak_...)\n    SaaS-\u003e\u003eLib: validateKey(...) → AgentContext (cached, 3 µs hit)\n    SaaS--\u003e\u003eAgent: response\n```\n\nFor revocation, rotation, recovery, and multi-region paths, see the corresponding sections of [`SPEC.md`](SPEC.md).\n\n## Architecture\n\n| Component | Role | Why |\n|---|---|---|\n| **Postgres 16** | authoritative state — accounts, agents, keys, audit chain | Strong consistency, transactional safety. All Tier B writes use `synchronous_commit=remote_apply`. |\n| **Redis 7** | cache (30 s bounded) + pubsub fan-out for revocations | Sub-millisecond hot path. Correctness never depends on Redis alone (RT-3, RT-26). |\n| **AWS KMS** | pepper for HMAC; envelope keys for sealed-box delivery | Pepper rotates weekly; legacy versions accepted within a 7-day dual-window. |\n| **AWS S3 (Object Lock)** | WORM mirror of audit chain | SOC 2 / GDPR — immutable evidence even against an admin-role attacker (RT-12, RT-39). |\n| **GitHub App / OAuth** | identity provider | Default in v0.1; the lib is provider-agnostic — you can implement `IdentityProvider` for SAML / OIDC / etc. |\n\n### Role separation\n\n`agent-auth` ships **four Postgres roles** that the SaaS connects with depending on the operation:\n\n| Role | Used by | Permissions |\n|---|---|---|\n| `agent_auth_migrator` | one-shot DDL on deploy | full DDL, then dropped from the connection pool |\n| `agent_auth_app` | request-path validation + Tier A reads | SELECT + INSERT on most tables; **no UPDATE / DELETE** on `agent_audit_log` |\n| `agent_auth_admin` | admin runbooks (RB-1..RB-9) | privileged writes guarded by JIT-RBAC + two-person approval |\n| `agent_auth_readonly` | reporting / forensics | SELECT only |\n\nPer the threat model (`SPEC.md` Part VI), the app role cannot tamper with audit history even if compromised — append is the only op it has.\n\n### Your responsibility (the SaaS side of the contract)\n\nVouch handles identity attestation, key minting, sealed-box delivery, audit, revocation, and rate limiting. **Three things stay on your side**:\n\n- **Authorize the human** before calling `/begin-registration` with `intent: 'add_key'` or `intent: 'recover'`. Vouch verifies the GitHub / OIDC identity; it does NOT verify \"this human is an admin/owner of the SaaS account `target_account_id`\". That's your role model — wire it up:\n  ```ts\n  app.post('/agent-auth/begin-registration', requireAdmin, async (req, res) =\u003e {\n    // Vouch handler\n  });\n  ```\n- **Tenant-scope every query** by `req.agent.account_id`. Vouch enforces the bearer maps to a single account; it doesn't know your tables.\n- **Configure your OAuth provider's redirect_uri allowlist** at GitHub / Google. Optionally: pass `redirect_uri_allowlist` to `vouch()` for defense-in-depth.\n\n## Documentation\n\n| | |\n|---|---|\n| [`SPEC.md`](SPEC.md) | The comprehensive specification — start here for implementation details, threat model, ADRs, runbooks |\n| [`docs/MIGRATION_GUIDE.md`](docs/MIGRATION_GUIDE.md) | Upgrade walkthrough for SaaS adopters (post-v0.1 sweep) |\n| [`docs/PRE_RELEASE_CHECKLIST.md`](docs/PRE_RELEASE_CHECKLIST.md) | Release gate (mirror of SPEC §12.7) |\n| [`docs/runbooks/INDEX.md`](docs/runbooks/INDEX.md) | RB-1..RB-9 incident playbooks |\n| [`docs/security/OWASP-API-self-review.md`](docs/security/OWASP-API-self-review.md) | OWASP API 2023 mapping |\n| [`audit/`](audit/) | 13 rounds of design-audit history (preserved for rationale) |\n| [`examples/`](examples/) | Express + Hono single-file references; Next.js / SvelteKit / Cloudflare Workers integrations in subdirectories |\n| [`packages/vouch/schema/migrations/`](packages/vouch/schema/migrations/) | Forward + rollback SQL DDL (0001..0006) |\n\n## Testing\n\nFour-tier test pyramid; all four pass at HEAD.\n\n| Tier | Count | Wall | What it covers |\n|---|---|---|---|\n| **Unit** (vitest + fast-check) | 393 / 54 suites | ~1 s | Algorithm shape, error mapping, property invariants (GCRA · audit chain · idempotency state machine · canonical hashing) + factory / Hono / providers / CLI / scaffolder / OTel coverage. |\n| **Integration** (testcontainers Postgres 16 + Redis 7) | 94 / 27 suites | ~95 s | Real DB triggers, cross-region barrier, audit partition manager, RT-* threats end-to-end. |\n| **Chaos** (testcontainers + injected faults) | 14 / 5 suites | ~10 s | RT-15 DoS · RT-18/32/34 multi-region failover · RT-22 KMS unavailable · RT-25 Redis partition · RT-43 fail-closed amplification. |\n| **Bench** (vitest bench) | 2 | ~5 s | `validation_cache_hit` P99 = 3.2 µs (target 50 ms) · `validation_cache_miss + HMAC` P99 = 6.5 µs (target 100 ms). |\n\n```bash\nnpm install\nnpm run lint\nnpm run typecheck\nnpm test                     # unit\nnpm run test:integration     # needs Docker (testcontainers)\nnpm run test:chaos           # needs Docker\nnpm run bench\n```\n\n## Roadmap\n\nThe server-side engine is done; the next milestones are about **developer experience parity with Better Auth / Auth0**.\n\n### v0.2 — DX completeness (mostly shipped)\n\n- [ ] **`agent-auth` published on npm** — currently dev-only\n- [x] **`@vouch/client` dev preview** — agent-side SDK lives in [`packages/client/`](packages/client/); 5-line `register()` happy path; auto-rotation deferred to v0.3\n- [ ] **`@vouch/client` published on npm**\n- [x] **`npx create-vouch-app`** — scaffolder; templates: `saas-express` (default) and `agent`\n- [x] **Reference end-to-end demo** — see [`apps/demo/`](apps/demo/) (SaaS + agent runnable via `docker compose up \u0026\u0026 npm run saas \u0026\u0026 npm run agent`)\n- [x] **Docs site** — VitePress under [`apps/docs/`](apps/docs/); pages: home, getting-started, concepts, providers, CLI, client SDK, Hono guide, demo guide, lifecycle reference, error codes reference, FAQ. Hostable on GitHub Pages or vouch.dev.\n- [x] OTel tracing — opt-in via `tracing: { tracer }`; lib never imports `@opentelemetry/api`. See [`apps/docs/guides/tracing.md`](apps/docs/guides/tracing.md).\n- [ ] Idempotency middleware sugar (wraps `tierBIdempotent` for HTTP routes)\n- [ ] GitHub device-flow as alt registration path\n\n### v0.3 — Multi-provider + tooling\n\n- [x] Generic OIDC provider — works against any standards-compliant IdP via `/.well-known/openid-configuration` discovery\n- [x] Google / Google Workspace provider (with `hosted_domain` restriction)\n- [ ] Microsoft Entra, GitLab, Okta, Auth0 thin presets (use `identity.oidc` directly until then)\n- [x] **`vouch migrate up`** — first-class migration runner (`@vouch/cli`); ships forward + rollback + status, transactional with auto tracking table\n- [ ] Type inference end-to-end (server-defined scopes flow into agent-side `useAgent()` hook)\n\n### v1.0 — Vouch Cloud\n\n- [ ] **Vouch Cloud** — managed control plane (you keep your DB; we run the validation hot path)\n- [ ] **Admin web dashboard** — keys / agents / audit / runbooks UI (today: CLI only)\n- [ ] Customer reference deployment with SOC 2 attestation\n- [ ] 30-day staging replay automated against production-shape data\n\n### v0.1.x — Maintenance\n\n- Bug fixes from real deployments\n- Worker / reaper hardening\n- No new features\n\n## Status\n\n| | |\n|---|---|\n| **Version** | v0.1 (server-side complete) |\n| **DX completeness** | ~85% — factory + monorepo + CLI + scaffolder + multi-provider + docs + OTel all shipped; npm publish + Cloud are the remaining gaps |\n| **Spec audit grade** | A (production-ready paying-customer level, per 13 rounds with codex / GPT-5) |\n| **Threats covered with tests** | 32 of 44 RT-* (11 explicitly operational, 1 reserved) |\n| **OWASP API 2023** | All 10 risks mapped — see `docs/security/OWASP-API-self-review.md` |\n| **Compliance posture** | SOC 2 / GDPR-ready audit trail; deploying SaaS owns the actual audit |\n| **License** | MIT |\n\n## Stack\n\nNode.js 20+ (Bun-compatible) · TypeScript 5.4 strict · libsodium · pg · ioredis · @aws-sdk/client-{kms,s3} · zod · vitest · testcontainers · fast-check.\n\n## Contributing\n\nVouch is **roadmap-driven**. The current focus is v0.2 (DX completeness — see [Roadmap](#roadmap)). Contributors are very welcome:\n\n- **Bug reports and security findings** — open an [Issue](https://github.com/shizhigu/agent-auth/issues), or for vulnerabilities follow [`SECURITY.md`](SECURITY.md) (private advisory).\n- **Bug-fix PRs** — please open an issue first so we can align on the fix shape; PRs with linked issues get fast-tracked.\n- **Feature PRs** — we evaluate against the roadmap. For anything that touches `SPEC.md`, the threat model, or `packages/vouch/src/crypto/` / `packages/vouch/src/middleware/validate-key.ts` / `packages/vouch/src/distributed/`, please open an issue first to discuss the design before writing code. An ADR in Appendix B is required for spec-touching changes (see ADR-001..ADR-014 for the format).\n- **Good first issues** — labeled in the [issue tracker](https://github.com/shizhigu/agent-auth/issues?q=is%3Aopen+label%3A%22good+first+issue%22).\n\nWe aim to respond to issues and PRs within **a few business days**. Auth is supply-chain-sensitive — review depth matters more than throughput, so please be patient if a PR sits in review for a beat.\n\n## License\n\n[MIT](LICENSE) © 2026 Agentic Flow LLC\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003e\u003cb\u003eVouch\u003c/b\u003e is built by \u003ca href=\"https://github.com/shizhigu\"\u003eAgentic Flow LLC\u003c/a\u003e. The open-source engine ships as \u003ccode\u003eagent-auth\u003c/code\u003e on npm (v0.2). Hosted Vouch Cloud is on the \u003ca href=\"#roadmap\"\u003eroadmap\u003c/a\u003e.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshizhigu%2Fagent-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshizhigu%2Fagent-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshizhigu%2Fagent-auth/lists"}