qauth-labs/qauth

QAuth is an open-source OAuth 2.1 and OpenID Connect 1.0 server. You run it yourself. Your apps, MCP servers and AI agents get standard access tokens and ID tokens from it.

It is built for three jobs:

• Agents. An AI agent acts for a user with narrower rights than the user, and every step is audited (ADR-007).
• Federation. Identity sources plug in behind one interface. Apps integrate once, whatever the user signs in with (ADR-003).
• Post-quantum. Signing sits behind algorithm-agnostic interfaces. A hybrid ML-DSA-65 + Ed25519 mode already ships (ADR-005).

Status

QAuth is pre-1.0. Releases are 0.x, and main runs ahead of the latest one. The changelog lists every change.

The road to 1.0 runs through 0.x betas, one area at a time: the core and its UIs, then the Authority Tree, then federation. ADR-018 sets what 1.0 covers and what it promises. An independent security audit and OpenID Foundation certification come before 1.0.

The status page tracks each feature. The milestones hold the open work.

What works today

OAuth 2.1 and OpenID Connect

• Authorization code flow with mandatory PKCE (S256), for confidential and public clients.
• client_credentials and refresh_token grants. Refresh tokens rotate, and a replayed one revokes its whole family.
• Discovery, JWKS, ID tokens, userinfo, introspection (RFC 7662) and revocation (RFC 7009).
• Resource indicators (RFC 8707): each token is bound to its audience.
• Client registration by Client ID Metadata Document (CIMD). RFC 7591 dynamic registration remains as a fallback.

MCP servers and AI agents

• The MCP authorization profile, revision 2026-07-28: protected-resource metadata (RFC 9728), audience binding and step-up challenges. @qauth-labs/resource-guard handles the resource-server side.
• An agent client type. An agent acts for a user through token exchange (RFC 8693), and the act claim names it.
• Scope modes (read-only, admin, exec), step-up before dangerous operations, and an audit trail per agent.
• A policy per environment (development, staging, production). It sets token lifetimes, PKCE, redirects, rate limits and step-up (ADR-008).

Accounts and operations

• Email and password sign-up with account verification. Passwords are hashed with Argon2id. Repeated failed logins lock the account.
• Realms: separate tenants, each with its own issuer and hosts.
• A developer portal for OAuth clients and API keys.
• Security headers, CSRF protection and __Host- cookies.
• Structured logs, liveness and readiness probes (/health, /ready), and Prometheus metrics on an internal listener. Events can also go out as OpenTelemetry logs, once OTEL_EVENTS_ENABLED is set.
• Signing keys stored encrypted under a key-encryption key (KEK).

Behind switches that are off by default

Switch	What it turns on
WALLET_FEDERATION_ENABLED	Linking a wallet to an account and signing in with it, over OID4VP 1.0 with SD-JWT VC. Tested against a mock wallet so far; the pass against a real wallet is still open.
HYBRID_SIGNING_ENABLED	Hybrid ML-DSA-65 + Ed25519 token signatures and a mixed JWKS. See the verifier guide.
ID_JAG_ENABLED	Enterprise-managed authorization: accepting and minting ID-JAG assertions (ADR-011).
DPOP_ENABLED	DPoP-bound tokens (RFC 9449): the token endpoint binds tokens to the client's key, and userinfo accepts them.

Quick start

You need Docker 23 or later with Compose 2, and OpenSSL.

git clone https://github.com/qauth-labs/qauth.git
cd qauth
cp .env.docker.example .env

Fill in these values in .env:

Variable	How to make it
JWT_PRIVATE_KEY, JWT_PUBLIC_KEY	openssl genpkey -algorithm Ed25519 -out private.pem, then openssl pkey -in private.pem -pubout -out public.pem. Paste both files, BEGIN and END lines included.
KEK	openssl rand -base64 32. Keep a copy with your backups: without it, the stored keys cannot be read.
DB_PASSWORD	Any strong password.

Then start the stack and check it:

docker compose up -d
curl http://localhost:3000/ready

Compose builds the images from source and runs the database migrations. It then starts the auth server on port 3000 and the developer portal on port 3001, with PostgreSQL 18 and Redis 7. The interactive API docs at /docs are off in production; ENABLE_SWAGGER=true turns them on.

The Docker guide covers the development setup and troubleshooting.

Documentation

Guides and reference live at docs.qauth.dev:

Section	Start with
Integrate	MCP quickstart · OAuth 2.1 flow · Agent authorization · API reference
Operate	Docker · Topology · Configuration · Keys · Reverse proxy · Upgrades
Extend	Architecture · Repository map · Adding a credential provider · Testing
Reference	Status · Events · API conventions · Experimental features · Design records

In this repository:

• docs/adr/: the architecture decision records.
• docs/security/threat-model.md: what QAuth promises and how findings are rated.
• docs/: the other engineering records, such as the spec pin log and the conformance matrix.
• Each library documents itself in its own README.md under libs/.

Repository layout

Path	What it holds
apps/auth-server	The OAuth 2.1 and OpenID Connect server
apps/developer-portal	The developer portal
apps/migration-runner	Applies the database migrations
apps/docs-site	The documentation site, docs.qauth.dev
apps/wire-suite, apps/upgrade-test	Black-box HTTP tests and upgrade tests against a running server
libs/	Server, Fastify plugin, database, crypto, SDK, shared and UI code
docs/	Design records and other engineering records

The stack is TypeScript on Node.js 26: Fastify, Drizzle ORM, PostgreSQL 18 and Redis 7 on the server; React 19 and TanStack Start for the UIs. The monorepo runs on Nx and pnpm.

Contributing

CONTRIBUTING.md covers setup, conventions and the pull request checklist. Everyone who takes part follows the Code of Conduct.

Security

Report a vulnerability privately, as SECURITY.md describes. Please do not open a public issue for it.

License

Apache License 2.0. See LICENSE.

Copyright © 2025–2026 QAuth Labs

Acknowledgments

QAuth learns from the open-source identity servers that came before it. It builds on the open standards of the IETF, the OpenID Foundation, the W3C and NIST.

Website · Documentation · Foundation