Runbook

Operations

Use this page as the deployment and production-readiness checklist for the service.

Configuration

Setting Purpose
AUTH_JWT_AUDIENCE Audience claim expected by downstream services.
AUTH_JWT_KEY_ID JWT key identifier exposed as kid in tokens and JWKS.
AUTH_JWT_PRIVATE_KEY_PATH Path to the RSA private key used for signing tokens.
AUTH_JWT_PUBLIC_KEY_PATH Path to the RSA public key exposed through JWKS.
AUTH_SMTP_* SMTP host, TLS mode, credentials, sender address, and sender name.

Deployment Checklist

  • Serve the service only behind TLS.
  • Keep JWT private keys, SMTP credentials, and database passwords in a secret store.
  • Use a migration runner for schema changes.
  • Disable test-only handlers and fake congestion-control settings in production configs.
  • Configure reverse proxy request-size limits and rate limits for auth endpoints.
  • Keep access logs free of passwords, refresh tokens, verification codes, and raw cookies.
  • Monitor sign-in failures, refresh-token reuse events, SMTP failures, and outbox dead jobs.

Security Controls

Edge

Apply IP and path rate limits at the proxy. Treat proxy headers as trusted only when they come from controlled infrastructure.

Application

Add account-aware limits for username, email, phone, user id, and verification target when the backing store is available.

Tokens

Rotate refresh tokens, revoke token families on reuse, and rotate JWT signing keys through JWKS with overlapping validity windows.

GitHub Pages

The repository includes a Pages workflow that publishes the static docs site. It copies docs/ and the current openapi/auth-v0.yaml into the Pages artifact.

  1. Commit docs/, openapi/auth-v0.yaml, and the Pages workflow.
  2. In repository settings, enable GitHub Pages with GitHub Actions as the source.
  3. Push to master or run the workflow manually.

Release Gate

cmake --build cmake-build-debug -j$(nproc) --target smirkly-auth smirkly-auth_unittest
ctest --test-dir cmake-build-debug --output-on-failure
ruby -e "require 'yaml'; YAML.load_file('openapi/auth-v0.yaml')"