Better Auth session, social login, magic-link, password, and OIDC flows.
/api/auth/*, /auth/*, and authentication discovery endpoints.
Auth-owned Redis configuration, transactional email, and auth telemetry.
Calling the resource API over the deployment's private network before deleting business data.

Code layout

The runtime is intentionally flat. Its main boundaries are:

auth.ts: Better Auth configuration and identity lifecycle hooks.
routes.ts: the complete public Auth HTTP surface and request authentication.
server.ts: dependency composition, health checks, and process lifecycle.
resource-api.ts: the single private Auth-to-resource-API boundary.
rate-limit.ts and otel.ts: cross-route operational policies.
email.ts and oidc-jwt-bearer.ts: substantial external integration modules.

Small shared contracts stay beside those boundaries (db.ts, env.ts, error.ts, and origin.ts). Tests are collected under src/tests; Better Auth schema-generation wiring is isolated under src/tooling.

Run locally

pnpm -F @proj-airi/auth-server dev

The service reads .env.local from this directory. PUBLIC_URL is the public issuer origin presented through Caddy; RESOURCE_SERVER_URL is the private resource API used for internal calls.

To run PostgreSQL, Redis, the resource API, and Auth together from the repository root:

pnpm dev:backend

server/docker-compose.yaml exposes only the local Caddy gateway on http://localhost:6112; API and Auth stay on its private network. The internal /internal/* boundary has no application token, and Caddy rejects that path at the public edge.

Railway

Deploy this as the Auth Railway service with Config File Path /server/apps/auth/railway.toml; keep the service Root Directory at the repository root because the Dockerfile copies workspace manifests and server/packages/auth-shared. The config owns its Dockerfile, start command, /readyz healthcheck, and the watch patterns for each copied build input.

Set PUBLIC_URL to this service's canonical public issuer URL, and make the Resource API's AUTH_SERVER_URL exactly the same value. Set RESOURCE_SERVER_URL from the Resource API's Railway private domain; do not run shared database migrations from Auth. See server/README.md for the complete service contract.

Do not use it for

Product APIs, billing, model routing, chat, or WebSocket business state.
Importing modules from server/apps/api.
Running the shared database migration history during normal process startup.

Auth tables and principal contracts live in @proj-airi/auth-shared. The existing @proj-airi/drizzle-migration build remains the migration owner while both applications share one PostgreSQL database.