@bajustone/fortress 1.0.0-rc.1

package/docs/ci/github-actions.yml

@@ -0,0 +1,59 @@
+# Drop-in GitHub Actions workflow that runs the Fortress CI checks.
+#
+# Save as `.github/workflows/fortress-ci.yml` in your repo. Adapt:
+#   - Node/Bun version if you pin a different one.
+#   - The path to your fortress instance (the example assumes
+#     `src/lib/fortress.ts` exports a configured `fortress`).
+#   - Install command (`bun install` / `pnpm i` / `npm ci`).
+#
+# What it runs:
+#   - `fortress manifest:check`     → route-security manifest drift
+#   - `fortress check:public-routes` → catches `.security('none')` on routes
+#     that shouldn't be public (against the bundled Fortress allow-list)
+#   - `fortress migrate:check`      → bundled migration catalog consistency
+#   - `bun run test`                → your suite, which should include
+#     `runFortressChecks()` against your real fortress instance with the
+#     test adapter (see docs/ci.md for a sample test file).
+
+name: fortress-ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  fortress-checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Fortress route-manifest drift
+        run: bunx fortress manifest:check
+
+      - name: Fortress public-route allow-list
+        run: bunx fortress check:public-routes
+
+      - name: Fortress migration catalog
+        run: bunx fortress migrate:check
+
+      - name: Unit tests
+        run: bun run test
+
+      # Optional: build artifact for verifying types compile cleanly
+      - name: Library build (publish dry-run)
+        run: bunx tsup

package/docs/ci.md

@@ -0,0 +1,109 @@
+# CI checks
+
+Fortress ships a bundle of reusable CI checks under
+`@bajustone/fortress/testing` plus a `fortress check:*` CLI namespace.
+The same drift detectors Fortress uses internally to keep its own
+routes/migrations/RBAC mappings honest are exposed to consumer apps so
+you can gate deploys on them.
+
+## What's covered
+
+| Check | API | CLI | Catches |
+|---|---|---|---|
+| Route-manifest drift | `checkRouteManifestDrift(fortress)` | `fortress manifest:check` / `fortress check:routes` | Mounted routes not in the manifest, manifest routes not mounted, RBAC permission/OpenAPI mismatches |
+| Public-route allow-list | `checkPublicRoutes(fortress, { allow })` | `fortress check:public-routes` | A new route marked `.security('none')` or `bearerKind:'oauth'` that wasn't reviewed |
+| Migration drift | `checkMigrationDrift(adapter)` | `fortress migrate:check` / `fortress check:migrations` | Missing version table, pending migrations, missing Fortress tables, DB ahead of bundled catalog |
+| Auth smoke test | `smokeTestAuth(fortress)` | _(run from a test file)_ | User creation/login/access-token verification/refresh/logout regression |
+| Aggregator | `runFortressChecks({ fortress })` | _(run from a test file)_ | All of the above with a single ok/messages roll-up |
+
+`runFortressChecks` is the convenience entry point — wire it into a
+single vitest test or a deploy preflight script. Under Node, install
+`better-sqlite3` as a development dependency for `createTestAdapter()`;
+Bun uses `bun:sqlite` without an extra driver.
+
+## In a vitest test
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { createFortress } from '@bajustone/fortress';
+import { createTestAdapter, runFortressChecks } from '@bajustone/fortress/testing';
+import { config } from '../src/lib/fortress-config';
+
+describe('fortress CI checks', () => {
+  it('passes every Fortress drift checker', async () => {
+    // Build the fortress instance with your real plugin set against an
+    // in-memory adapter so smokeTestAuth has somewhere to write.
+    const fortress = createFortress({ ...config, database: createTestAdapter() });
+    const result = await runFortressChecks({ fortress });
+    if (!result.ok)
+      console.error(result.messages.join('\n'));
+    expect(result.ok).toBe(true);
+  });
+});
+```
+
+This single test catches:
+
+- A new plugin route that's accidentally `.security('none')`.
+- A migration that was added without bumping `fortress_schema_version`.
+- A manifest entry that no longer corresponds to a mounted route.
+- A regression in the auth pipeline (create user/login/token verification/refresh/logout).
+
+## As a CLI
+
+```sh
+fortress manifest:check         # route-security drift (also: check:routes)
+fortress check:public-routes    # public-route allow-list (core surface)
+fortress migrate:check          # migration catalog (also: check:migrations)
+```
+
+The CLI runs against Fortress's **core auth + IAM** route surface, so it
+catches drift in Fortress itself but doesn't see your plugins. For
+app-level checks (plugin routes + your real config), use the API from a
+vitest test as shown above.
+
+## GitHub Actions snippet
+
+A drop-in workflow is committed at
+[`docs/ci/github-actions.yml`](./ci/github-actions.yml). Save it as
+`.github/workflows/fortress-ci.yml` in your repo. It runs:
+
+1. `bun run lint`
+2. `bun run typecheck`
+3. `bun run typecheck:examples`
+4. `bunx fortress manifest:check`
+5. `bunx fortress check:public-routes`
+6. `bunx fortress migrate:check`
+7. `bun run test` (which should include `runFortressChecks(...)` from
+   the snippet above)
+8. `bun run test:integration` for PostgreSQL-backed projects
+9. `bun run build` (verifies distributable output)
+
+Adjust `oven-sh/setup-bun` to your preferred Node/PNPM/NPM setup; every
+step is plain shell.
+
+## Customising the public-route allow-list
+
+The default allow-list covers Fortress's intentional public surface
+(auth open routes + OAuth protocol endpoints). Add your own public
+routes via the `allow` option:
+
+```ts
+checkPublicRoutes(fortress, {
+  allow: [
+    'GET /health',
+    'GET /robots.txt',
+    'POST /webhooks/incoming',
+  ],
+});
+```
+
+CLI usage repeats `--allow`:
+
+```sh
+fortress check:public-routes --allow 'GET /health' --allow 'GET /robots.txt'
+```
+
+If you want a stricter posture (e.g. fail on `oauth-protocol` routes
+that appeared without review), restrict `classifications` to just
+`['public']`.

package/docs/compatibility.md

@@ -0,0 +1,115 @@
+# Compatibility
+
+The Fortress test matrix that the maintainer runs locally and via CI.
+Numbers are "tested, working" — Fortress is framework-agnostic by
+construction so versions outside the matrix will usually work, just
+without an explicit test guarantee.
+
+## Runtime
+
+| Runtime | Minimum | Tested |
+|---|---|---|
+| **Bun** | 1.0 | latest |
+| **Node.js** | 20.19 | 20, 22, 24 |
+| **Deno** | 1.40 | latest |
+| **Cloudflare Workers (workerd)** | wrangler 3 | latest |
+| Browsers | n/a | server-only |
+
+Bun is the maintainer's primary runtime (test adapter prefers
+`bun:sqlite`; the `bin/fortress.ts` CLI shebang targets Bun). The
+package ships a Node-compatible CJS build via `tsup` so the same module
+works under Node 20.19+ unchanged. Deno + workerd can import and use the runtime-neutral core because Node filesystem/path modules are dynamically loaded only when file-oriented policy/resource helpers are invoked. The Bun-targeted CLI and file helpers require a Node-compatible filesystem runtime.
+
+## Frameworks
+
+| Adapter | Package | Tested versions |
+|---|---|---|
+| Hono | `@bajustone/fortress/hono` | `hono@^4.12` |
+| Express | `@bajustone/fortress/express` | `express@^4` and `^5` (duck-typed; no `@types/express` dep) |
+| SvelteKit | `@bajustone/fortress/sveltekit` | `@sveltejs/kit@^2` |
+
+The Express adapter uses minimal duck-typed interfaces (`ExpressRequest`,
+`ExpressResponse`, `ExpressMiddleware`) so consumers bring their own
+Express version. The SvelteKit subpath uses the optional `@sveltejs/kit@^2`
+peer directly for its strict public `Handle`/`Action` types and runtime
+`redirect()`/`fail()` primitives; install that peer when using the adapter.
+
+## Databases
+
+| Driver | Adapter | Tested |
+|---|---|---|
+| PostgreSQL via `drizzle-orm/postgres-js` | `@bajustone/fortress/drizzle` (`dialect: 'pg'`) | `postgres@^3.4` |
+| PostgreSQL via `drizzle-orm/node-postgres` | same | `pg@^8` |
+| SQLite via `drizzle-orm/bun-sqlite` | same (`dialect: 'sqlite'`) | bundled with Bun |
+| SQLite via `drizzle-orm/better-sqlite3` | same | `better-sqlite3@^12.8` |
+
+Drizzle minimum: `drizzle-orm@^0.45`. Earlier versions are missing
+features Fortress relies on (`$dynamic()`, `getTableColumns`,
+`getSetCookie` polyfill).
+
+The `@bajustone/fortress/testing` subpath uses `bun:sqlite` under Bun and the optional `better-sqlite3@^12.8` peer under Node. Install that peer in Node test projects.
+
+Custom adapters: implement the `DatabaseAdapter` interface in
+`src/adapters/database/index.ts` to back Fortress with any datastore.
+The IAM service uses a small set of generic operations
+(`create`/`findOne`/`findMany`/`update`/`delete`/`count`/`transaction`,
+optional `rawQuery`) so even non-SQL stores are workable.
+
+## Optional integrations
+
+| Capability | Peer | Tested |
+|---|---|---|
+| OpenTelemetry metrics + traces | `@opentelemetry/api@^1.9` | latest with `@opentelemetry/sdk-node` |
+| Argon2id password hashing (native) | `argon2@^0.31` | optional; Fortress ships a `hash-wasm` fallback |
+| WebAuthn server | `@simplewebauthn/server@^13.1` | bundled dependency |
+| OAuth signing (RS256 id_token) | `jose@^6.2` | bundled dependency |
+
+## What the CI matrix runs today
+
+The repository workflow ([`.github/workflows/ci.yml`](../.github/workflows/ci.yml))
+executes:
+
+- **`lint`** — eslint + `tsc --noEmit` (Bun, ubuntu-latest).
+- **`unit`** — the full SQLite test suite across a runtime matrix:
+  **Bun**, **Node 20**, and **Node 22**. Bun runs `bun:sqlite`; the Node
+  jobs run the same vitest suite under `better-sqlite3`, keeping the
+  Node-compatible build honest.
+- **`integration`** — the PostgreSQL suite via testcontainers
+  (`bun run test:integration`), covering the `pg` dialect, the tenancy
+  connection-pinning / `search_path` isolation, the migration upgrade
+  fixture, and the framework adapters end-to-end. This is the heavier job,
+  so it runs on pull requests, pushes to `main`, and a **nightly cron**
+  rather than every branch push.
+- **`jsr-check`** — `deno publish --dry-run` to guard JSR publishability.
+
+The consumer-facing drop-in workflow
+([`docs/ci/github-actions.yml`](./ci/github-actions.yml)) is a separate
+template that gates *your* deploys on Fortress's drift checkers
+(`runFortressChecks`); it is not the library's own matrix.
+
+> Deno and Cloudflare Workers remain smoke-tested locally rather than in
+> the public matrix (no first-class GitHub runner for the workerd DB
+> story). MySQL is not currently supported — `DrizzleDialect` is
+> `'sqlite' | 'pg'`; it may be re-added once there is a real consumer and
+> a CI lane to keep it honest.
+
+## What's intentionally out of scope
+
+- **Bun's web runtime APIs** beyond `Request`/`Response`/`crypto`/`fetch`.
+  Fortress sticks to the web platform standard so any modern runtime
+  works.
+- **ESM-only consumers without an interop layer.** The dual `esm`+`cjs`
+  build is shipped; if a consumer's bundler refuses CJS, use the
+  `import` map entry.
+- **Cloudflare Workers without external DB.** Workers cannot use
+  `bun:sqlite` or `better-sqlite3`. Use the Postgres adapter (or a
+  remote DB over HTTP) when targeting workerd.
+
+## Reporting a compatibility issue
+
+If a combination listed here breaks, open an issue with:
+
+1. Runtime + version (`bun --version`, `node --version`, `deno --version`).
+2. Driver + version (`drizzle-orm`, `postgres`, `better-sqlite3`).
+3. The minimal reproduction \u2014 ideally a failing test using
+   `createTestAdapter()`.

package/docs/deployment.md

@@ -0,0 +1,305 @@
+# Fortress production deployment guide
+
+This guide covers what changes between local dev and production for a
+Fortress-backed service. Treat each section as a checklist — every
+production deployment should explicitly answer or skip each item.
+
+## 1. JWT secret
+
+The JWT signing secret (`FortressConfig.jwt.key`) must be **at least
+32 bytes** of cryptographically random material. Anything shorter throws
+at `createFortress` startup.
+
+Generate one with the bundled CLI:
+
+```sh
+fortress generate-secret
+# 64-byte hex string (128 chars); paste into your secret manager
+```
+
+Recommendations:
+
+- Store the secret in your platform's secret manager (AWS Secrets
+  Manager, GCP Secret Manager, Vault, Doppler, Fly secrets, etc.).
+  Never commit it.
+- Rotate the secret periodically. Fortress supports an array of secrets
+  on `jwt.key` — the first entry is used for **signing**, all entries
+  are accepted for **verification**. Add the new secret to position 0,
+  redeploy, wait until every issued token has expired (typically the
+  access-token lifetime + grace), then remove the old one.
+- For multi-region deployments, replicate the same secret across regions
+  so tokens issued in one region verify in another.
+
+## 2. Cookies behind reverse proxies
+
+Fortress defaults to `__Host-fortress_access` / `__Host-fortress_refresh`
+cookies with `HttpOnly; Secure; SameSite=Lax; Path=/`. The `__Host-`
+prefix is the strongest browser-enforced isolation: the cookie is bound
+to the exact origin, has no `Domain` attribute, and **must** be sent
+over HTTPS.
+
+When deploying behind a reverse proxy (nginx, Caddy, ELB, Fly, Cloud
+Run, fly-replay):
+
+- **Terminate TLS at the proxy.** Set `X-Forwarded-Proto: https` so the
+  app sees the original scheme. Fortress only relies on this for IP /
+  user-agent metadata, but most frameworks (Hono, Express, SvelteKit)
+  use it to construct absolute URLs and cookie attributes.
+- **Forward the original host.** Set `Host` to the client-facing
+  hostname — `__Host-` cookies are pinned to it.
+- **Forward `X-Forwarded-For`.** Fortress reads `X-Forwarded-For` then
+  `X-Real-IP` for rate-limit keys and refresh-token metadata. Strip any
+  client-supplied values at the edge; only trust hops you control.
+- **Do not strip cookies.** Some CDN configurations drop `Set-Cookie`
+  by default on cacheable responses. Whitelist
+  `set-cookie: __Host-fortress_*` (or your renamed prefix) on every
+  Fortress-served path.
+
+To opt into a custom cookie name / scope, set
+`FortressConfig.cookies` — for example a top-level apex domain:
+
+```ts
+createFortress({
+  // ...
+  cookies: {
+    accessName: 'app_access',
+    refreshName: 'app_refresh',
+    domain: 'example.com',
+    secure: true,
+    sameSite: 'lax',
+    path: '/',
+  },
+});
+```
+
+Setting a `domain` removes the `__Host-` prefix automatically because
+the prefix forbids cross-subdomain cookies.
+
+## 3. CSRF: opt-out rules and recipes
+
+Pipeline CSRF is on by default for unsafe methods (POST/PUT/PATCH/DELETE)
+on Fortress-managed routes when the request carries a Fortress auth
+cookie. Bearer-only and API-key requests are immune by construction and
+are skipped.
+
+Common production tweaks:
+
+- **Pure API backends (no browser cookies):** set `csrf: { enabled: false }`.
+  Every request authenticates via bearer/API-key; there is no ambient
+  credential to protect.
+- **SPA on the same origin:** keep the default. The SPA sends a custom
+  header (`X-Fortress-CSRF: 1` by default — value is not validated, the
+  *presence* is what matters because cross-site code cannot set custom
+  headers without a CORS preflight you've allowed).
+- **SPA on a sibling subdomain** (`app.example.com` calling
+  `api.example.com`): keep the default `rejectSameSite: false`; the
+  legitimate `Sec-Fetch-Site: same-site` traffic must pass.
+- **Single-host browser app, no cross-subdomain calls:** set
+  `csrf: { rejectSameSite: true }` to also reject same-site requests,
+  closing the residual risk of a malicious subdomain.
+
+Skip specific paths if a third party must call them without a custom
+header (webhooks, OAuth `/oauth/token`, etc.):
+
+```ts
+csrf: {
+  enabled: true,
+  skipPaths: ['/oauth/token', '/oauth/revoke', '/webhooks/incoming'],
+}
+```
+
+`/oauth/*` protocol endpoints are already classified as
+`oauth-protocol` in the route manifest and self-authenticate via
+bearer tokens; they don't need a CSRF skip unless you've put them
+behind cookie auth somehow.
+
+## 4. CORS
+
+Fortress does not ship a CORS middleware — each adapter delegates to its
+host framework. Mount your framework's CORS middleware **before**
+`mountFortress`, and:
+
+- Set `Access-Control-Allow-Credentials: true` if your SPA sends
+  cookies.
+- Set `Access-Control-Allow-Origin` to the explicit SPA origin (never
+  `*`) when credentials are allowed.
+- Include `X-Fortress-CSRF` (and any custom header you renamed it to)
+  in `Access-Control-Allow-Headers`.
+- Include `Authorization` and `X-API-Key` if you authenticate via
+  bearer/API-key from the browser.
+
+Example (Hono):
+
+```ts
+import { cors } from 'hono/cors';
+
+app.use('*', cors({
+  origin: 'https://app.example.com',
+  credentials: true,
+  allowHeaders: ['Content-Type', 'Authorization', 'X-API-Key', 'X-Fortress-CSRF'],
+  exposeHeaders: ['Retry-After'],
+}));
+mountFortress(app, fortress);
+```
+
+## 5. HTTPS requirements
+
+- The OAuth plugin **refuses to start** in production
+  (`NODE_ENV=production`) unless `issuerUrl` is HTTPS. Loopback URLs are
+  exempt for dev.
+- `__Host-` cookies require HTTPS at the browser. If you do not run
+  HTTPS in production, set `cookies: { secure: false }` — but you are
+  giving up the strongest cookie isolation and exposing tokens to any
+  on-path attacker.
+- Every external dependency Fortress speaks to (social-login providers,
+  webhook destinations, OIDC discovery URLs) should use HTTPS. The
+  social-login plugin assumes provider URLs are HTTPS; provider configs
+  with `http://` URLs are accepted but should be flagged in code review.
+
+## 6. PostgreSQL vs SQLite guarantees
+
+| Concern | PostgreSQL | SQLite (`bun:sqlite`, `better-sqlite3`) |
+|---|---|---|
+| Concurrent writers | Yes, MVCC | One writer at a time (serialized in the adapter via `BEGIN IMMEDIATE`) |
+| Tenancy `search_path` switching | Supported (transaction-pinned `set_config`) | Not supported — tenancy plugin is pass-through |
+| Recommended for production | ✅ | Single-node deployments only (Fly Volumes, edge SQLite) |
+| Migrations against a live DB | Standard | Use a small migration window; SQLite serializes writers |
+| Drift checker `missingTables` | Reads `information_schema` | Reads `sqlite_master` |
+| OAuth `oauth_signing_key` | Persisted; rotation safe | Persisted; rotation safe |
+
+SQLite is perfectly fine for small to medium services that don't need
+horizontal write scaling. Use Postgres when you need multi-region, true
+tenancy schema isolation, or when an external tool needs to read the
+schema (BI, replication).
+
+## 7. OAuth / OIDC RP setup
+
+The OAuth plugin acts as an **authorization server**. To enable it:
+
+```ts
+oauth({
+  issuerUrl: 'https://auth.example.com',           // HTTPS mandatory in prod
+  loginUrl: 'https://app.example.com/signin',      // your SPA login page
+  consentUrl: 'https://app.example.com/oauth/consent', // your SPA consent page
+  // Optional: per-deployment OIDC userinfo claim shaping
+  userinfoClaims: async (user, scope) => ({ /* ... */ }),
+})
+```
+
+Key production knobs:
+
+- **`issuerUrl`** is signed into every id_token (`iss` claim) and is the
+  base of every discovery URL. Setting it wrong locks every client out
+  — pick once, document, treat as part of your stable public API.
+- **Discovery** is served from
+  `${issuerUrl}/oauth/.well-known/openid-configuration`. Cache for
+  minutes, not hours; the JWKS rotation cadence depends on your
+  `oauth_signing_key` rotation policy.
+- **JWKS** is served from `${issuerUrl}/oauth/.well-known/jwks.json`.
+  RPs typically cache it for 5–15 minutes; signing-key rotations are
+  picked up next cache refresh.
+- **Refresh tokens** are rotated by default; reuse triggers a
+  family-wide revocation per RFC 9700 §2.2.2. Configure
+  `refreshTokenExpirySeconds` to match your session policy (0 disables
+  refresh entirely).
+- **Public clients** (SPAs, native apps) must register with
+  `tokenEndpointAuthMethod: 'none'` and use PKCE. Confidential clients
+  default to `client_secret_basic`; opt into `'client_secret_post'` per
+  client if needed.
+- **Per-client `allowedScopes`** narrows what each RP can request.
+  Leave blank for legacy clients with broad scopes; set explicitly for
+  any new integration.
+
+## 8. API-key and service-account operations
+
+- API-key plugin endpoints are opt-in (`apiKey({ routes: true })`). In
+  production, decide:
+  - User self-service rotation: mount `routes: true` and put rate-limit
+    on `/api-key/keys`.
+  - Admin-only rotation: leave `routes: false` and rotate via the
+    admin plugin's `/admin/users/:userId/api-keys` endpoints (requires
+    `apiKey:manage` permission).
+- Service accounts have no sessions and no group memberships. Provision
+  them via `/iam/service-accounts` (admin plugin) or
+  `fortress.iam.createServiceAccount(...)`. Mint API keys against them
+  via `/admin/service-accounts/:id/api-keys`.
+- Hash storage: API keys are stored as SHA-256 of the prefix + secret
+  with the plaintext returned only on issuance. If a key leaks, revoke
+  it via `DELETE /api-key/keys/:id` (or admin route); rotation via
+  `POST /api-key/keys/:id/rotate` keeps the same `name` and revokes the
+  predecessor in a single transaction.
+- Rate-limit API-key issuance separately from user logins:
+  `rateLimit({ apiKeyIssue: { maxPerIp: 5, maxPerUser: 5, windowSeconds: 3600 } })`.
+
+## 9. Migration runbook
+
+1. **Pre-deploy:** run `fortress migrate:check` in CI; non-zero exit
+   blocks the deploy. This catches "developer added a new bundled
+   migration but forgot to commit the SQL" before it reaches prod.
+2. **Deploy:** on application start, call
+   `migrateUp(adapter)` from your boot script. Both `migrateUp` and
+   `migrateDown` are idempotent.
+3. **Post-deploy:** in your healthcheck, call
+   `detectMigrationDrift(adapter)` and fail the healthcheck on
+   `missingTables` / `missingVersionTable`. The load balancer pulls the
+   instance out of rotation until drift is fixed.
+
+For irreversible migrations (column drops, type narrowing), keep the
+old code shape supported for at least one release before removing it,
+and take a database snapshot immediately before applying. See
+[docs/migrations/upgrade-guide.md](./migrations/upgrade-guide.md) for
+the runtime API and CLI reference.
+
+## 10. Observability
+
+- Pass a structured logger (`pino`, `bunyan`, framework-provided) to
+  `FortressConfig.logger` so security-critical events (token reuse,
+  account lockout, OAuth errors) are searchable.
+- Wire OpenTelemetry via `@bajustone/fortress/otel`'s
+  `createOtelTelemetry()`. Fortress emits stable
+  `db.client.operation.duration`,
+  `fortress.auth.events.total`, IAM permission-check histograms, and
+  a deny-only span (`fortress.iam.permission_check.deny`).
+- High-cardinality data (user IDs, emails, tenant IDs) is deliberately
+  kept off metric attributes — it lives on spans and structured logs.
+
+## 11. Backups & disaster recovery
+
+- Back up the database before every deploy that ships a migration.
+  Test restores quarterly.
+- The `oauth_signing_key` row is **the** RSA signing material for every
+  OIDC id_token. Losing it invalidates every outstanding id_token (RPs
+  re-authenticate). Treat it like a JWT secret — back it up with the
+  database, never export it.
+- Audit-log rows are append-only and hash-chained when
+  `auditLog({ hashChain: true })` is enabled. Restoring from backup
+  preserves the chain; appending out-of-order rows breaks it. If you
+  restore, run a chain verification job before resuming writes.
+- Rate-limit counter store (the in-memory default) is **not** durable.
+  In production with multiple instances, bring your own store
+  (Redis, Memcached) so limits apply across replicas.
+
+## 12. Checklist
+
+Use this before promoting a release to production:
+
+- [ ] JWT secret is ≥ 32 bytes, stored in a secret manager, rotated on a
+      schedule.
+- [ ] HTTPS terminated end-to-end; `X-Forwarded-Proto`, `Host`, and
+      `X-Forwarded-For` set by the proxy.
+- [ ] Cookies: `__Host-` prefix or explicit `domain` + `secure: true`.
+- [ ] CSRF policy chosen explicitly (default, `rejectSameSite`, or
+      disabled) and documented in code review.
+- [ ] CORS allow-list pins exact SPA origin and exposes the CSRF
+      header.
+- [ ] OAuth `issuerUrl` is HTTPS in production; discovery and JWKS
+      endpoints reachable from RPs.
+- [ ] Rate-limit plugin mounted with `login`/`register`/`refresh`
+      defaults; named rules cover `/api/*`.
+- [ ] Audit-log plugin mounted with `hashChain: true` for any flow
+      that ships compliance evidence.
+- [ ] `fortress migrate:check` in CI; `migrateUp` + drift check in the
+      app's boot/healthcheck path.
+- [ ] OpenTelemetry exporter or structured logger wired so security
+      events leave the box.
+- [ ] Backup + restore tested for the database; signing keys included.