bauth

Headless authentication server: apps draw their own screens and call bauth's API.

Warning

This project is written with AI assistance and its human review is still in progress. It has not been audited; known issues are listed under "Audit findings" in CLAUDE.md. Use it at your own risk: it comes with no warranty of any kind (see the license).

• Registration with email verification, password login, magic links (+ 6-digit code, passwordless sign-up), password reset
• OAuth 2.1 authorization code flow with PKCE; EdDSA access tokens (JWT) published in a JWKS
• Refresh token rotation with reuse detection, revocation, /me (profile, password, email, sessions, account deletion, confirmed by password or by an emailed code for passwordless accounts)
• Rate limits per IP and per email address

Crates

Crate	Role
bauth_server	The server (axum, sqlx, Postgres)
bauth_client	Verifies bauth access tokens in an API (JWKS cache)
bauth_core	Types shared by both

The TypeScript SDK for apps is @wadjetz/bauth-client on npm.

Development

cp .env.example .env            # then set BAUTH_MASTER_KEY: openssl rand -base64 32
podman compose up -d           # dev Postgres :5441, emails on http://localhost:8026, test Postgres :5440
cd bauth_server && sqlx migrate run && cd ..
cargo run -p bauth_server

Clients are declared in bauth.toml. Example requests live in bruno/.

After changing a SQL query, refresh the offline query cache used by CI and Docker:

cd bauth_server && cargo sqlx prepare

After changing a route, a request or response type, or a #[utoipa::path] doc, regenerate bauth_server/openapi.json (otherwise its test fails), then the SDK types generated from it:

UPDATE_OPENAPI=1 SQLX_OFFLINE=true cargo test -p bauth_server openapi
cd bauth_sdk && npm run generate && npm test

Releasing the SDK

@wadjetz/bauth-client is published by hand. Release it together with any server change to the API (its types come from openapi.json), with a version telling how compatible it is: patch for fixes, minor for additions — and, while in 0.x, for breaking changes too.

npm login                               # sessions expire: check with `npm whoami`
cd bauth_sdk
npm run generate && npm test            # types match openapi.json, tests pass
npm version minor --no-git-tag-version  # bumps package.json and package-lock.json
npm publish                             # `prepack` rebuilds dist/

Then commit the version bump.

Docker

podman run -p 8401:8401 \
  -v ./bauth.toml:/etc/bauth/bauth.toml:ro \
  -e BAUTH_DATABASE_URL=postgres://… \
  -e BAUTH_MASTER_KEY=… \
  -e BAUTH_ISSUER=https://auth.example.com \
  -e BAUTH_SMTP_URL=smtps://… \
  ghcr.io/wadjetz/bauth:latest

Migrations run at startup. See .env.example for every setting.

License

MIT