@bajustone/fortress 1.0.0-rc.1

package/docs/hardening.md

@@ -0,0 +1,118 @@
+# Hardening
+
+A focused checklist for operators running Fortress in production. Pair
+with [deployment.md](./deployment.md) (configuration), [security.md](./security.md) (architecture),
+and [threat-model.md](./threat-model.md) (attacker model).
+
+Each item is "what to do" + "why" + "how to verify".
+
+## Identity and credentials
+
+### JWT secret
+
+- **Do:** Generate via `fortress generate-secret` (64 bytes hex, exceeds the 32-byte HS256 minimum). Store in a secret manager. Rotate at least annually and immediately on suspected compromise.
+- **Why:** A leaked HS256 secret lets an attacker forge any access token. Fortress validates secret length at boot — anything shorter throws.
+- **Verify:** `createFortress` accepts an array for rotation (`jwt.key: [new, old]`) — make sure your rotation playbook adds `new` to position 0, redeploys, waits past `accessTokenExpirySeconds`, removes `old`.
+
+### Cookie posture
+
+- **Do:** Keep the `__Host-` prefix defaults. Only set `cookies: { secure: false }` for localhost HTTP dev.
+- **Why:** `__Host-` cookies are scoped to the origin, have no `Domain`, and refuse to be set without HTTPS — the strongest browser-enforced isolation.
+- **Verify:** `curl -I https://your-domain/auth/login` returns `Set-Cookie: __Host-fortress_*` with `Secure; HttpOnly; SameSite=Lax; Path=/`.
+
+### Password policy
+
+- **Do:** Keep the default `passwordPolicy.minLength` of 15 and enable `checkBreached`; choose `breachedFailureMode: 'closed'` when assurance is more important than registration availability.
+- **Why:** Length plus breached-password screening provides useful resistance without brittle composition rules. Every HIBP outage emits `PASSWORD_BREACH_CHECK_DEGRADED` for alerting.
+- **Verify:** Try registering with `"abc"` — it should reject with `BAD_REQUEST`; simulate an HIBP outage and verify your chosen open/closed behavior.
+
+### Refresh-token posture
+
+- **Do:** Keep `refreshTokenExpirySeconds` ≤ 30 days. Enforce per-device refresh family rotation (Fortress default). Treat any `TOKEN_REUSE_DETECTED` event as a paging incident.
+- **Why:** Refresh-token reuse detection turns a stolen refresh token into a same-day revocation event. Without rotation, the attacker has the full token lifetime.
+
+## Authorization
+
+### Default-deny everywhere
+
+- **Do:** Every Fortress-managed route should carry either `.security('none')` (intentional public) or `.permission(resource, action)` (default-deny). The mutual-exclusion check at boot will throw if you mix them.
+- **Why:** The plan's stated goal — operators should never have to remember to add a guard.
+- **Verify:** `fortress check:public-routes` in CI catches a stray `.security('none')`; the bootstrap allow-list covers only Fortress's intentional public surface.
+
+### RBAC drift
+
+- **Do:** Add `fortress manifest:check` to CI; also run `runFortressChecks({ fortress })` in a test that constructs your real `Fortress` instance.
+- **Why:** Manifest drift catches "I added a route and forgot the `.permission` decorator" before it ships.
+
+### Policy as code
+
+- **Do:** Manage roles/groups/service accounts via `fortress.policy.json` instead of imperative `iam.createRole(...)` from production code. Reconcile in CI with `applyPolicyPlan(...)`.
+- **Why:** Reviewable Git history for permission grants; no "who gave Bob role X?" mystery.
+
+## Transport and edge
+
+### HTTPS
+
+- **Do:** Terminate TLS at the edge; redirect HTTP to HTTPS. Set HSTS via your edge (`Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`).
+- **Why:** All security guarantees in this guide assume HTTPS in the browser.
+
+### CSRF
+
+- **Do:** Keep the default pipeline check on for cookie-authenticated browser sessions. Add `csrf: { rejectSameSite: true }` if your app is single-host (`example.com` only). Skip the check for routes that absolutely must accept third-party POSTs (webhooks) and replace it with signature verification per-route.
+- **Why:** Cookies are ambient credentials; without a CSRF check, any malicious page can trigger a state change.
+- **Verify:** A POST from a third-party origin (no `X-Fortress-CSRF` header, `Sec-Fetch-Site: cross-site`) returns 403.
+
+### Rate limiting
+
+- **Do:** Mount the `rate-limit` plugin with `login`, `register`, `refresh`, `oauthToken`, and `apiKeyIssue` blocks. In multi-replica deployments, bring your own `RateLimitStore` (Redis, Memcached) — the in-memory default does not coordinate across replicas.
+- **Why:** Per-IP and per-account limits stop credential-stuffing and account-enumeration before they reach the password hasher.
+
+## Data isolation
+
+### Tenancy
+
+- **Do:** Use the verified `tenantId` JWT claim (set by `enrichTokenClaims`); never an `X-Tenant-Code` header. Use numeric tenant IDs in schema names (`tenant_<id>`). For PostgreSQL, the adapter pins `search_path` per transaction via `set_config('search_path', ?, true)`.
+- **Why:** The hardening plan documented in [docs/plugins/tenancy.md](./plugins/tenancy.md) closes a class of cross-tenant data-leak bugs.
+
+### Multi-tenant scope rules
+
+- **Do:** For row-level isolation across databases (not just PG), use the `data-isolation` plugin with explicit `scopes` per model.
+- **Why:** Tenancy-via-schema only works on PG; everywhere else, scope rules are the safety net.
+
+## Audit and logging
+
+### Audit chain
+
+- **Do:** Mount `auditLog({ hashChain: true })`. Schedule a nightly `verifyChain()` job. Mirror auth events into the audit log via an `addAuthObserver` (see [observability.md §6](./observability.md)).
+- **Why:** Hash-chaining detects after-the-fact deletions; verification turns it into an enforced invariant.
+
+### Structured logging
+
+- **Do:** Pass a structured logger to `FortressConfig.logger` (`pino`, `fastify.log`, etc.). Default is silent — production without a logger means you'll never see token reuse or RBAC denials.
+- **Why:** Security events are useless if no one sees them.
+
+## Cryptographic posture
+
+- **Do:** Stick with Argon2id (the default). Don't downgrade to PBKDF2/bcrypt without a measured reason.
+- **Do:** Use the bundled OAuth signing key rotation (`oauth_signing_key` table); rotate quarterly.
+- **Do:** When using social-login, pin provider issuer URLs to HTTPS; the bundled providers do this.
+
+## Deployment hygiene
+
+- **Do:** Run `bun run lint` + `bun run typecheck` + `bun run test` + `fortress migrate:check` + `fortress manifest:check` + `fortress check:public-routes` on every CI build. The shipped GitHub Actions workflow does all six (see [docs/ci/github-actions.yml](./ci/github-actions.yml)).
+- **Do:** Take a database backup before every deploy that bumps a migration version; test restores quarterly.
+- **Do:** Pin to a minor version (`@bajustone/fortress@~0.1`). Pre-1.0 Fortress reserves the right to ship breaking changes in any minor.
+
+## Release notes discipline
+
+The maintainer commits to:
+
+- Every change that affects a security-relevant code path lands with a `### Security` or `### Changed` entry in the CHANGELOG noting the impact.
+- Migration-bearing changes ship with a `docs/migrations/<version>.md` note (forward, rollback, backfill).
+- Findings from external reviews land in `docs/security-review-<date>.md` with a remediation plan.
+
+If a CHANGELOG entry for a security-affecting change is missing in a release, file an issue — it's a process bug.
+
+## Reporting a vulnerability
+
+See [SECURITY.md](../SECURITY.md). Email `security@bajustone.dev`. Acknowledgement within 48 hours, fix targeted within 7 days for criticals.

package/docs/host-owned-routes.md

@@ -0,0 +1,154 @@
+# Host-owned routes
+
+Fortress has two HTTP surfaces:
+
+1. **Fortress-managed routes** — endpoints registered in `fortress.endpoints` and served through `fortress.handleRequest()` by `mountFortress()` / `createSvelteKitHandle()`.
+2. **Host-owned routes** — routes your app registers in Hono, Express, SvelteKit, `Bun.serve`, etc. These often call `fortress.auth.*`, `fortress.iam.*`, or plugin methods directly.
+
+Use `protect()` / `protectedRoute()` when a host-owned route should receive the same security controls as a Fortress-managed route.
+
+## What `protect()` runs
+
+Given an endpoint definition (or handler name) present in the route manifest, Fortress applies:
+
+- plugin middleware: `before-auth`, `after-auth`, `after-rbac`;
+- pipeline CSRF protection for unsafe cookie-authenticated requests;
+- principal resolution via plugin credentials first, then Fortress JWT bearer/cookie;
+- default-deny RBAC from `endpoint.meta.permission`;
+- request validation from endpoint body/query/params schemas;
+- auth-cookie attachment when the handler returns `{ accessToken, refreshToken? }`.
+
+The route's endpoint metadata remains the source of truth. Do not duplicate permissions in a separate route map unless you intentionally want a different policy.
+
+## Core API
+
+```ts
+import { protect } from '@bajustone/fortress';
+
+const handler = protect(fortress, endpointDefinition, async (ctx) => {
+  // ctx.subject, ctx.userId, ctx.input, ctx.params, ctx.query, ctx.body
+  return { ok: true };
+});
+
+const response = await handler(request);
+```
+
+`target` may be an `EndpointDefinition` or a unique endpoint `handler` name. If a handler name maps to multiple routes, pass the definition directly or set `method`.
+
+### Typed input inference
+
+`protect()` is generic over the endpoint you pass it. When `target` is the value returned by `endpoint(...).build()`, its phantom `<TBody, TQuery, TParams, TResponses>` generics flow into the `ProtectedRouteContext`:
+
+```ts
+const createThing = endpoint('POST', '/things/:id')
+  .summary('Create thing')
+  .security('bearer')
+  .permission('thing', 'write')
+  .body(obj({ name: str() }, 'name'))
+  .params(obj({ id: int() }, 'id'))
+  .response(201, 'Created', obj({ ok: str() }, 'ok'))
+  .handler('createThing')
+  .build();
+
+const handler = protect(fortress, createThing, async (ctx) => {
+  // ctx.body is { name: string } — non-optional, because a body schema is
+  // declared and validation already ran before the handler executes.
+  // ctx.params is { id: string }
+  // ctx.input is { name: string; id: string }
+  return { ok: ctx.body.name };
+});
+```
+
+When the endpoint declares a body schema, `ctx.body` is narrowed to a non-optional `T` — use it directly, no `!` and no detour through `ctx.input`. Endpoints with no declared body schema keep the loose `unknown` body.
+
+Passing a string handler name keeps the looser `Record<string, unknown>` / `unknown` typing (no inference source available). Runtime validation and coercion are identical in both cases — this is purely a typing improvement.
+
+### Typed status returns with `ctx.respond`
+
+For non-2xx returns, use `ctx.respond(status, body)` instead of hand-rolling a `Response`. When the target is a typed endpoint, both arguments narrow against the response declarations:
+
+```ts
+const getThing = endpoint('GET', '/things/:id')
+  .summary('Get thing')
+  .security('bearer')
+  .params(obj({ id: int() }, 'id'))
+  .response(200, 'OK', obj({ data: str() }, 'data'))
+  .errorResponse(404, 'Not found')
+  .handler('getThing')
+  .build();
+
+const handler = protect(fortress, getThing, async (ctx) => {
+  const thing = await load(ctx.params.id);
+  if (!thing)
+    return ctx.respond(404, { code: 'NOT_FOUND', message: 'no such thing', statusCode: 404 });
+  //                  ^^^                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  //          must be a declared status          typed against responses[404].schema (ErrorEnvelope)
+  return { data: thing };
+});
+```
+
+String-target endpoints fall back to `(status: number, body: unknown) => Response` — same ergonomics as before, no narrowing.
+
+## Hono
+
+```ts
+import { endpoint, obj, str } from '@bajustone/fortress';
+import { protectedRoute } from '@bajustone/fortress/hono';
+
+const statsEndpoint = endpoint('GET', '/api/stats')
+  .summary('Stats')
+  .security('bearer')
+  .permission('stats', 'read')
+  .response(200, 'OK', obj({ ok: str() }, 'ok'))
+  .handler('stats')
+  .build();
+
+// Include the endpoint so it appears in
+// fortress.endpoints / fortress.manifest / OpenAPI. Either pass it via the
+// top-level `routes` shorthand (preferred) or as a one-field plugin.
+const fortress = createFortress({
+  // ...
+  routes: { stats: statsEndpoint },
+});
+
+// Equivalent long-form (use this if you want to colocate host endpoints with
+// other plugin metadata in the same record):
+// plugins: [{ name: 'host-routes', routes: { stats: statsEndpoint } }],
+
+app.get('/api/stats', protectedRoute(fortress, statsEndpoint, async (_c, ctx) => {
+  return { ok: ctx.subject?.type ?? 'unknown' };
+}));
+```
+
+Register the Hono route before `mountFortress(app, fortress)` so the host handler wins over the manifest-owned fallback route.
+
+## Express
+
+```ts
+import { protectedRoute } from '@bajustone/fortress/express';
+
+app.get('/api/stats', protectedRoute(fortress, statsEndpoint, async (_req, _res, ctx) => {
+  return { ok: ctx.subject?.type ?? 'unknown' };
+}));
+```
+
+## SvelteKit
+
+```ts
+import { protectedRoute } from '@bajustone/fortress/sveltekit';
+
+const GET = protectedRoute(fortress, statsEndpoint, async (_event, ctx) => {
+  return new Response(JSON.stringify({ ok: ctx.subject?.type }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+
+export { GET };
+```
+
+## Boundary checklist
+
+- `fortress.handleRequest()` remains responsible for Fortress-managed routes.
+- `protectedRoute()` is responsible for host-owned routes that opt in.
+- Public host routes can remain unwrapped.
+- If a host route is mounted at a different path than its endpoint metadata, pass `options.path` / `options.params` so plugin middleware and validation use the intended canonical route.

package/docs/migrations/0001-schema-version.md

@@ -0,0 +1,54 @@
+# Migration 0001 — Schema version tracking
+
+Introduced: 2026-06-08
+
+## Summary
+
+Adds the `fortress_schema_version` singleton table. Fortress migration tooling uses this table to compare a live database against bundled migrations.
+
+## Forward
+
+SQLite:
+
+```sql
+CREATE TABLE IF NOT EXISTS fortress_schema_version (
+  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+  version INTEGER NOT NULL,
+  applied_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+```
+
+PostgreSQL:
+
+```sql
+CREATE TABLE IF NOT EXISTS fortress_schema_version (
+  id integer PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+  version integer NOT NULL,
+  applied_at timestamp NOT NULL DEFAULT now()
+);
+```
+
+The singleton version row (`id = 1`) is **not** written by this SQL — the
+migration runner (`migrateUp`) stamps it after each migration applies, so
+version tracking has a single source of truth. Applying the raw SQL by
+hand creates the table at version 0; run `migrateUp` (or the CLI) to stamp
+the current version.
+
+## Rollback
+
+```sql
+DROP TABLE IF EXISTS fortress_schema_version;
+```
+
+## Backfill / cleanup
+
+No data backfill is required. Existing Fortress tables are not modified by this migration.
+
+## Validation
+
+```ts
+import { getMigrationStatus } from '@bajustone/fortress';
+
+const status = await getMigrationStatus(fortress.config.database);
+console.log(status.currentVersion, status.latestVersion);
+```

package/docs/migrations/0002-initial-schema.md

@@ -0,0 +1,84 @@
+# Migration 0002 — Initial Fortress schema
+
+Introduced: 2026-06-08
+
+## Summary
+
+Creates every Fortress-owned table, index, and constraint — everything
+except the `fortress_schema_version` checkpoint installed by `0001`. This
+is the baseline that lets `migrateUp` provision a brand-new database
+(SQLite or PostgreSQL) end-to-end through the adapter's `rawQuery`, with
+no Drizzle or `drizzle-kit` dependency at runtime.
+
+The migration is the SQL-first source of truth for the schema:
+
+- `src/testing/index.ts` builds the in-memory test adapter from this DDL.
+- The column-drift checker (`detectMigrationDrift`) parses expected
+  columns out of this DDL.
+
+So the test adapter and a production `migrateUp` cannot drift.
+
+## Forward
+
+Run via the migration runner (recommended — it also stamps the version
+row):
+
+```ts
+import { migrateUp } from '@bajustone/fortress';
+
+await migrateUp(adapter); // applies 0001 + 0002, stamps version 2
+```
+
+Or apply the bundled SQL directly:
+
+- SQLite: `migrations/sqlite/0002_initial_schema.sql`
+- PostgreSQL: `migrations/pg/0002_initial_schema.sql`
+
+All statements are `CREATE TABLE IF NOT EXISTS` / `CREATE [UNIQUE] INDEX
+IF NOT EXISTS`, so applying it to a database that already has the Fortress
+tables (e.g. provisioned from the Drizzle schema) is a no-op.
+
+## Rollback
+
+```ts
+import { migrateDown } from '@bajustone/fortress';
+
+await migrateDown(adapter, undefined, 1); // roll back to version 1
+```
+
+Or apply `migrations/{sqlite,pg}/0002_initial_schema.down.sql`.
+
+> **Destructive.** The down step drops every Fortress table (PostgreSQL
+> uses `CASCADE`). It deletes all users, tokens, roles, and audit history.
+> Back up first and only do this on a database you intend to re-provision.
+
+## Backfill / cleanup
+
+None. On a fresh database this is the initial install. On a database whose
+tables were already provisioned from the Drizzle schema, the forward step
+is a no-op and only the version row changes.
+
+## Migrating from a pre-0002 database
+
+If you deployed an earlier Fortress version and provisioned tables from
+the Drizzle schema (the previous documented path):
+
+1. Pull this version.
+2. Run `migrateUp(adapter)`. The `IF NOT EXISTS` guards mean existing
+   tables are left untouched; the version row advances to 2.
+3. Run `detectMigrationDrift(adapter)` and confirm both `missingTables`
+   and `missingColumns` are empty. If `missingColumns` is non-empty, your
+   tables predate a column added in a later schema change — apply the
+   listed columns (the bundled DDL is the reference) and re-check.
+
+## Validation
+
+```ts
+import { detectMigrationDrift, getMigrationStatus, hasMigrationDrift } from '@bajustone/fortress';
+
+const status = await getMigrationStatus(adapter);
+console.log(status.currentVersion, status.latestVersion); // 2 2
+
+const drift = await detectMigrationDrift(adapter);
+console.log(hasMigrationDrift(drift)); // false
+```

package/docs/migrations/upgrade-guide.md

@@ -0,0 +1,160 @@
+# Fortress migration upgrade guide
+
+This guide is the operational counterpart to the per-release notes under
+`docs/migrations/<version>.md`. It describes how to run, verify, and roll
+back Fortress migrations across releases.
+
+## Migration sources of truth
+
+- **Bundled migrations:** `migrations/{sqlite,pg}/<version>_<name>.sql`
+  and `<version>_<name>.down.sql`. Committed to the repo for review and
+  auditability. Mirrored as string constants in
+  `src/core/migrations/migrations.ts` so the runtime works without disk
+  access (serverless, bundled CLIs).
+- **Expected table list:** `FORTRESS_TABLES` in
+  `src/core/migrations/migrations.ts`. Drives the live-DB drift checker.
+  Kept in sync with `src/drizzle/schema.ts`, `src/drizzle/pg/schema.ts`,
+  and `src/testing/index.ts`; the engine test fails if the test adapter
+  ever stops creating one of these tables.
+- **Schema-version table:** `fortress_schema_version` (single row,
+  `id = 1`). The applied baseline is whatever `version` holds; missing
+  table means version 0.
+
+## Runtime API
+
+```ts
+import {
+  detectMigrationDrift,
+  getMigrationStatus,
+  hasMigrationDrift,
+  migrateDown,
+  migrateUp,
+} from '@bajustone/fortress';
+
+const status = await getMigrationStatus(adapter);
+//   { dialect, currentVersion, latestVersion, pending, applied, upToDate, hasVersionTable }
+
+const up = await migrateUp(adapter);
+//   { fromVersion, toVersion, applied: FortressMigration[] }
+
+const down = await migrateDown(adapter, 'sqlite', 0);
+//   rolls back to version 0
+
+const drift = await detectMigrationDrift(adapter);
+//   { currentVersion, latestVersion, missingVersionTable, unknownFutureVersion,
+//     pendingVersions, missingTables, missingColumns, missingIndexes }
+if (hasMigrationDrift(drift)) throw new Error('Schema drift detected');
+```
+
+Pass an explicit `dialect` when the adapter does not advertise one (most
+non-Drizzle adapters). Both `migrateUp` and `migrateDown` are idempotent and safe to run on every
+deploy. Mutation runs acquire a database-backed lock, re-read the checkpoint
+only after locking, and execute transactionally. The engine maintains
+`fortress_migration_journal` with one SHA-256 checksum per applied migration;
+legacy checkpoints are backfilled once, while later missing or changed rows
+fail closed before any schema mutation.
+
+## CLI
+
+```sh
+fortress migrate:status
+fortress migrate:down
+fortress migrate:diff
+fortress migrate:check     # exits non-zero on drift; suitable for CI
+```
+
+The CLI commands operate on the bundled migration catalog and do **not**
+connect to a database. Migration v6 includes a Unicode-aware data step, so
+`fortress migrate:up` intentionally refuses to emit SQL-only output that would
+skip cleanup. Run the runtime API against your live database from application
+code; it executes data steps and constraints atomically using the configured
+adapter.
+
+## Drift signals (`detectMigrationDrift`)
+
+| Field | Meaning | Recommended action |
+|---|---|---|
+| `missingVersionTable` | `fortress_schema_version` does not exist | Run `migrateUp` |
+| `pendingVersions` | Migrations the runtime has but the DB has not applied | Run `migrateUp` |
+| `unknownFutureVersion` | DB is at a higher version than the bundled migrations | Upgrade the Fortress version before deploying |
+| `missingTables` | Any `FORTRESS_TABLES` entry not present in the DB | Run `migrateUp`, or finish the interrupted migration run |
+| `missingColumns` | A table that exists but is missing a column the bundled DDL defines | Apply the migration that adds the column (or recreate the table from the bundled DDL) |
+| `missingIndexes` | A required hot-path index is absent | Apply the owning migration or restore the named index |
+
+`missingTables`, `missingColumns`, and `missingIndexes` are the deep checks — they catch the
+case where the version table claims everything is applied but the schema
+is genuinely incomplete (manual DROP, partial restore, a table created
+from an older schema dump). Expected columns are parsed straight out of
+the bundled migration DDL, so the check works for any adapter — not just
+Drizzle. Wire `hasMigrationDrift()` into your deploy preflight and your CI
+smoke tests.
+
+## Current migration catalog
+
+Ten migrations ship today:
+
+- **`0001_schema_version`** — installs the schema checkpoint.
+- **`0002_initial_schema`** — creates the original Fortress schema.
+- **`0003_auth_continuation`** — adds pending-auth/session metadata.
+- **`0004_tenant_default_unique`** — enforces one default tenant membership.
+- **`0005_hot_indexes_timestamptz`** — adds hot indexes and UTC-safe PostgreSQL timestamps.
+- **`0006_canonical_email`** — performs runtime Unicode email cleanup and installs case-insensitive uniqueness.
+- **`0007_audit_chain_anchor`** — installs the permanent zero-entry sentinel and persists the terminal audit hash/count so tail or full-chain deletion is detectable.
+- **`0008_two_factor_hardening`** — adds durable continuation failure counters, invalidation/cooldown metadata, and the indexed per-account failure lookup used by MFA throttling.
+- **`0009_encrypt_totp_secrets`** — removes legacy plaintext TOTP enrolments, backup codes, and trusted devices. SQL cannot encrypt legacy seeds with the application-held key, so affected users must re-enrol; new seeds are stored as AES-256-GCM envelopes.
+- **`0010_bigint_append_only_ids`** — widens PostgreSQL identifiers and sequences on unbounded/churn-heavy token, audit, webhook-delivery, and WebAuthn-challenge tables to bigint. SQLite identifiers are already signed 64-bit. Narrowing rollback is intentionally unsupported.
+
+If `fortress_audit_log` already contains rows written without hash chaining, migration 0007 intentionally leaves the anchor at zero; SQL cannot establish a trustworthy cryptographic history. Before serving auth traffic with `auditLog({ hashChain: true })`, archive and externally attest those rows, create the hash-chain-enabled Fortress instance during a maintenance window, and call `await fortress.plugins['audit-log'].rebaselineChain()`. The method transactionally accepts only an uninitialized zero anchor and fully unchained rows, links them deterministically, advances the anchor, and verifies the result. See [Audit Log Plugin](../plugins/audit-log.md#enabling-hash-chaining-on-an-existing-log).
+
+The migrations are the SQL-first source of truth: `src/testing/index.ts`
+derives the test adapter's schema from them, and the column-drift checker
+parses expected columns from them, so the test adapter and a production
+`migrateUp` cannot diverge.
+
+### Provisioning a new database
+
+1. Point Fortress at an empty database (any adapter with `rawQuery`).
+2. Call `migrateUp(adapter)` — this creates the checkpoint table, all
+   Fortress tables, and stamps `fortress_schema_version` at the latest
+   version.
+3. Call `detectMigrationDrift(adapter)` to confirm `missingTables` and
+   `missingColumns` are empty.
+
+> Drizzle users may still provision tables directly from
+> `src/drizzle/{,pg/}schema.ts` if they prefer to own schema management;
+> `migrateUp` is idempotent (`CREATE TABLE IF NOT EXISTS`) and will simply
+> stamp the version row in that case.
+
+### Upgrading an existing database
+
+1. Pull the new Fortress version.
+2. Read the version-specific notes in `docs/migrations/<version>.md` for
+   forward/rollback/backfill steps.
+3. Call `migrateUp(adapter)` on application start (or in a one-shot
+   deploy job).
+4. Confirm via `migrate:check` / `hasMigrationDrift()` that the
+   database is at the expected version with no missing tables.
+
+## Rollback
+
+`migrateDown(adapter, dialect, targetVersion)` rolls the schema back to
+the supplied version (default `0`). Each migration's `.down.sql` is
+applied in reverse order. The version row is updated last, so a failed
+rollback leaves the previous version recorded — re-run after fixing the
+underlying issue.
+
+Always take a backup before rolling back across an irreversible change
+(table drops, column drops, type narrowing). The `0001_schema_version`
+down step only removes the checkpoint table. **`0002_initial_schema`'s
+down step drops every Fortress table** (PostgreSQL uses `CASCADE`), so
+rolling back below version 2 is destructive — it deletes all users,
+tokens, roles, and audit history. Only do this against a database you
+intend to re-provision, and back up first.
+
+## Custom / additional migrations
+
+The bundled catalog covers Fortress-owned tables. Application-owned
+tables (e.g. tenant-specific business tables, audit-log partitions) are
+out of scope — keep them in your own migration tool of choice. The
+adapter's `rawQuery` is available if you need to call into the same DB
+connection from your own scripts.