@bajustone/fortress 1.0.0-rc.1

package/docs/plugins/webauthn.md

@@ -0,0 +1,188 @@
+# WebAuthn Plugin
+
+## Overview
+
+The `webauthn` plugin adds passkey and WebAuthn support to Fortress, enabling passwordless authentication using platform authenticators (Touch ID, Face ID, Windows Hello) and security keys. It is built on [@simplewebauthn/server](https://simplewebauthn.dev/).
+
+The plugin supports both registration (adding a passkey to an existing account) and authentication (signing in with a passkey). In passwordless mode, successful authentication returns JWT tokens directly.
+
+## Installation
+
+Import the `webauthn` factory and pass it in the `plugins` array when creating a Fortress instance:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { webauthn } from '@bajustone/fortress/plugins/webauthn';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    webauthn({
+      rpName: 'My App',
+      rpID: 'example.com',
+      origin: 'https://example.com',
+    }),
+  ],
+});
+```
+
+Once registered, methods are available at `fortress.plugins['webauthn']` with full type safety.
+
+## Configuration
+
+| Option | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `rpName` | `string` | -- | Yes | Human-readable relying party name shown to users (e.g., "My App"). |
+| `rpID` | `string` | -- | Yes | Relying party identifier, typically the domain (e.g., "example.com"). |
+| `origin` | `string \| string[]` | -- | Yes | Expected origin(s) for credentials (e.g., "https://example.com"). |
+| `attestation` | `'none' \| 'indirect' \| 'direct' \| 'enterprise'` | `'none'` | No | Attestation preference. |
+| `authenticatorSelection.authenticatorAttachment` | `'platform' \| 'cross-platform'` | -- | No | Restrict to platform or roaming authenticators. |
+| `authenticatorSelection.residentKey` | `'discouraged' \| 'preferred' \| 'required'` | `'preferred'` | No | Resident key (discoverable credential) preference. |
+| `authenticatorSelection.userVerification` | `'discouraged' \| 'preferred' \| 'required'` | `'preferred'` | No | User verification preference. |
+| `timeout` | `number` | `60000` (60s) | No | Timeout for WebAuthn ceremonies in milliseconds. |
+| `challengeTTLSeconds` | `number` | `300` (5 min) | No | How long a challenge remains valid, in seconds. |
+| `supportPasswordless` | `boolean` | `true` | No | When `true`, `verifyAuthentication` returns `AuthResult` for direct passwordless login. When `false`, the plugin registers a pre-token `postAuthGate` and challenges password logins. |
+
+## HTTP Routes
+
+The plugin defines four routes that are auto-mounted via `mountFortress`:
+
+| Method | Path | Auth Required | Description |
+|---|---|---|---|
+| POST | `/webauthn/register/options` | Yes (bearer) | Generate registration options for a new passkey against the authenticated caller. Body: `{}`. |
+| POST | `/webauthn/register/verify` | Yes (bearer) | Verify the registration response and store the credential for the authenticated caller. Body: `{ response }`. |
+| POST | `/webauthn/authenticate/options` | No | Generate authentication options. Optionally pass `userId` for non-discoverable flow. |
+| POST | `/webauthn/authenticate/verify` | No | Verify the authentication assertion and return tokens (if passwordless). |
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `generateRegistrationOptions` | `(input: Record<string, unknown>, ctx: PluginRouteContext)` | `Promise<{ options: PublicKeyCredentialCreationOptionsJSON }>` |
+| `verifyRegistration` | `(input: { response: RegistrationResponseJSON }, ctx: PluginRouteContext)` | `Promise<{ verified, credentialId, credentialDeviceType, credentialBackedUp }>` |
+| `generateAuthenticationOptions` | `(input: { userId?: string })` | `Promise<{ options: PublicKeyCredentialRequestOptionsJSON }>` |
+| `completeAuthentication` | `(continuationToken, response, meta?)` | `Promise<AuthResult>` |
+| `verifyAuthentication` | `(input: { response: AuthenticationResponseJSON }, meta?)` | `Promise<AuthResult>` |
+
+> **Registration methods require `PluginRouteContext`.** The target user is always the verified caller (`ctx.userId`) — there is no body-supplied `userId` field. When a browser hits `POST /webauthn/register/options` or `/webauthn/register/verify`, `fortress.handleRequest` constructs the `ctx` automatically from the bearer token. Programmatic callers must build one by hand (see below).
+
+### generateRegistrationOptions
+
+Generates options for `navigator.credentials.create()`. Existing credentials for the authenticated caller are included in `excludeCredentials` to prevent duplicate registration:
+
+```ts
+// Programmatic (server-side, no HTTP request)
+const { options } = await fortress.plugins['webauthn'].generateRegistrationOptions(
+  {},
+  { userId, request: new Request('http://localhost') },
+);
+// Pass options to the browser: navigator.credentials.create({ publicKey: options })
+```
+
+Throws `Unauthorized` if `ctx.userId` is missing, or `NotFound` if the user does not exist.
+
+### verifyRegistration
+
+Verifies the authenticator's response and stores the new credential against the authenticated caller:
+
+```ts
+const result = await fortress.plugins['webauthn'].verifyRegistration(
+  { response: registrationResponseFromBrowser },
+  { userId, request: new Request('http://localhost') },
+);
+// result.verified, result.credentialId, result.credentialDeviceType, result.credentialBackedUp
+```
+
+Throws:
+- `Unauthorized` -- `ctx.userId` is missing.
+- `BadRequest` -- No pending challenge, challenge expired, or verification failed.
+
+### generateAuthenticationOptions
+
+Generates options for `navigator.credentials.get()`. Pass `userId` to restrict to that user's credentials, or omit for discoverable credential (passkey) flow:
+
+```ts
+// Discoverable flow (user selects passkey)
+const { options } = await fortress.plugins['webauthn'].generateAuthenticationOptions({});
+
+// User-specific flow
+const { options } = await fortress.plugins['webauthn'].generateAuthenticationOptions({ userId });
+```
+
+### verifyAuthentication
+
+Verifies the authentication assertion. In passwordless mode, returns the unified auth result and issues a full session:
+
+```ts
+const result = await fortress.plugins['webauthn'].verifyAuthentication({
+  response: authenticationResponseFromBrowser,
+});
+if (result.status === 'success') {
+  // result.user, result.method === 'webauthn', result.accessToken, result.refreshToken
+}
+```
+
+For second-factor mode, pass the pending login's continuation token and browser assertion to `completeAuthentication(continuationToken, response, meta)`. Both paths validate the authenticator counter to detect credential cloning (skipped for synced passkeys where both counters are 0), and both rerun remaining gates before token issuance.
+
+Throws:
+- `Unauthorized` -- Unknown credential or verification failed.
+- `BadRequest` -- No pending challenge or challenge expired.
+
+## Example
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { webauthn } from '@bajustone/fortress/plugins/webauthn';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    webauthn({
+      rpName: 'My App',
+      rpID: 'myapp.com',
+      origin: 'https://myapp.com',
+      supportPasswordless: true,
+    }),
+  ],
+});
+
+// --- Registration (browser + server) ---
+// Most apps let the browser hit POST /webauthn/register/options and
+// /webauthn/register/verify directly — the dispatcher constructs the
+// PluginRouteContext from the bearer token so the passkey is always
+// registered against the verified caller.
+//
+// Calling programmatically (e.g. from a custom Hono route or CLI tool)
+// requires building a PluginRouteContext by hand:
+
+// Server: generate options
+const { options } = await fortress.plugins['webauthn'].generateRegistrationOptions(
+  {},
+  { userId, request: new Request('http://localhost') },
+);
+
+// Browser: create credential
+// const credential = await navigator.credentials.create({ publicKey: options });
+
+// Server: verify and store
+const result = await fortress.plugins['webauthn'].verifyRegistration(
+  { response: credentialResponseFromBrowser },
+  { userId, request: new Request('http://localhost') },
+);
+
+// --- Authentication (browser + server) ---
+
+// Server: generate options
+const { options: authOptions } = await fortress.plugins['webauthn'].generateAuthenticationOptions({});
+
+// Browser: get assertion
+// const assertion = await navigator.credentials.get({ publicKey: authOptions });
+
+// Server: verify and get tokens
+const authResult = await fortress.plugins['webauthn'].verifyAuthentication({
+  response: assertionFromBrowser,
+});
+// authResult.accessToken -- use this to authenticate the user
+```

package/docs/plugins/webhook.md

@@ -0,0 +1,242 @@
+# Webhook Plugin
+
+## Overview
+
+The `webhook` plugin delivers events to consumer-registered HTTPS endpoints following the [Standard Webhooks](https://www.standardwebhooks.com) specification (HMAC-SHA256 signing, `webhook-id`/`webhook-timestamp`/`webhook-signature` headers).
+
+Highlights:
+
+- **Custom events** — declare and `emit()` your own events through the same path the built-in auth events use.
+- **Bring-Your-Own-Queue (BYOQ)** — delivery is always queued; plug in any backend (in-memory, database, BullMQ, SQS, Cloudflare Queues, …) via a small interface. Defaults to a dev-only in-memory queue.
+- **SSRF-safe delivery** — webhook URLs are consumer-supplied, so delivery resolves + validates the target, blocks private/loopback/link-local/CGNAT/NAT64 addresses, and **pins the connection to the resolved IP** (closing the DNS-rebinding window).
+- **Resilience** — failure classification, jittered exponential backoff, a per-endpoint circuit breaker, and DLQ/alert callbacks.
+- **Per-delivery idempotency** — a stable `webhook-id` so receivers can dedup retries, plus an `idempotencyKey` so `emit()` is safe to call more than once.
+
+Built-in auth events are dispatched automatically via lifecycle hooks; custom events you `emit()` yourself.
+
+## Installation
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { webhook } from '@bajustone/fortress/plugins/webhook';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [webhook()], // defaults: all built-in events, in-memory queue
+});
+```
+
+Methods are available at `fortress.plugins.webhook`. The plugin is method-only — it ships **no** HTTP routes (mount your own management endpoints, as the example app does).
+
+## Events
+
+Built-in and custom events share one declaration shape (`WebhookEventDeclaration`) and one emit path. The built-ins:
+
+| Event | Source hook |
+|---|---|
+| `auth.login.success` | `afterLogin` |
+| `auth.login.failure` | `onLoginFailure` |
+| `auth.logout` | `beforeLogout` |
+| `auth.user.registered` | `afterRegister` |
+| `auth.token.refreshed` | `afterTokenRefresh` |
+
+Pass `events` to declare custom events (and optionally exclude built-ins). Each event may carry a Standard Schema validator (`schema`) — the payload is validated at `emit()` time.
+
+```ts
+import { builtinEvents, webhook } from '@bajustone/fortress/plugins/webhook';
+import { obj, str } from '@bajustone/fortress';
+
+webhook({
+  events: [
+    ...builtinEvents({ exclude: ['auth.logout'] }), // keep the built-ins you want
+    { name: 'order.paid', schema: obj({ orderId: str(), amount: str() }, 'orderId', 'amount') },
+    { name: 'order.refunded' },
+  ],
+});
+```
+
+Emit a custom event from your code:
+
+```ts
+await fortress.plugins.webhook.emit('order.paid', { orderId: 'o_123', amount: '49.00' });
+```
+
+`emit()` throws a `WebhookEmitError` (with `code: 'unknown_event' | 'invalid_payload' | 'payload_too_large'`) so you can branch on the failure.
+
+## Queue (Bring-Your-Own-Queue)
+
+Delivery is always queued. Bundled queues (zero extra deps):
+
+- **`inMemoryQueue()`** — the **default**. `setTimeout`-driven, single process. **Dev-only**: scheduled retries live in in-process timers, so a restart loses every pending retry until the next process runs its startup recovery sweep. Jobs are processed sequentially.
+- **`databaseQueue({ pollMs })`** — the crash-safe bundled option. Polls `webhook_delivery` for due rows; the table itself is the transactional outbox, so it survives restarts. Single-worker (run one poller per deployment, or use a real broker for multi-worker).
+
+```ts
+import { databaseQueue, webhook } from '@bajustone/fortress/plugins/webhook';
+
+webhook({ queue: databaseQueue({ pollMs: 10_000 }) });
+```
+
+Implement `WebhookQueue` to use any external broker. Set `handlesRetries: true` and `delivery.retry: 'queue'` to let the broker own retries (the plugin re-throws on failure so the broker re-delivers).
+
+The queue worker starts automatically the first time the plugin methods are accessed; call `await fortress.plugins.webhook.stop()` on shutdown to tear down timers/pollers.
+
+## Configuration
+
+All fields on `WebhookConfig` are optional:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `events` | `WebhookEventDeclaration[]` | `builtinEvents()` | The event registry (built-in + custom). |
+| `queue` | `WebhookQueue` | `inMemoryQueue()` | Delivery queue backend. |
+| `maxRetries` | `number` | `5` | Attempts before a delivery is marked `failed`. |
+| `maxPayloadBytes` | `number` | `262144` (256 KB) | `emit()` rejects larger payloads. |
+| `delivery.timeoutMs` | `number` | `10000` | Per-attempt request timeout. |
+| `delivery.retry` | `'pluginScheduled' \| 'inProcess' \| 'queue'` | `'pluginScheduled'` | Who owns retries (see below). |
+| `delivery.permanentStatuses` | `number[]` | `[404, 410, 421]` | Statuses that permanently deactivate an endpoint. |
+| `delivery.maxConsecutiveFailures` | `number` | `15` | Circuit breaker — deactivate after this many consecutive failures. |
+| `delivery.onDeliveryFailed` | `(d: WebhookDelivery) => void \| Promise<void>` | — | Terminal-failure hook (the DLQ/alert seam). |
+| `delivery.onEndpointDeactivated` | `(e: WebhookEndpoint, reason: WebhookDeactivatedReason) => void \| Promise<void>` | — | Fired on auto-deactivation. |
+| `delivery.fetch` | `FetchFn` | `ssrfSafeFetch()` | Override the transport (custom transport or tests). **Bypasses the SSRF guard** — only override when you control the targets. |
+
+### Retry modes
+
+| Mode | Behavior |
+|---|---|
+| `'pluginScheduled'` (default) | One attempt per job. On a retriable failure the plugin schedules `nextRetryAt` with jittered backoff and re-enqueues. Works with any queue. |
+| `'inProcess'` | The fetcher transport retries within a single attempt (POST opted in). The queue sees one job per logical delivery. |
+| `'queue'` | The plugin re-throws on a retriable failure so the queue re-delivers. Requires a queue with `handlesRetries: true`. |
+
+### Failure classification (plugin-scheduled)
+
+| Result | Action |
+|---|---|
+| 2xx | success (resets the failure counter) |
+| `404 / 410 / 421` | `failed` + **deactivate** the endpoint (`permanent_<status>`) |
+| `408 / 425 / 429` | retry (transient) |
+| other `4xx` | `failed`, **no retry** (permanent client error) |
+| `5xx` / network / timeout | retry with jittered exponential backoff |
+
+Backoff ladder (jittered ±25%): **5s → 5min → 30min → 2h → 5h**. Independently, the circuit breaker deactivates an endpoint after `maxConsecutiveFailures` consecutive failures (`reason: 'too_many_failures'`).
+
+## Endpoint management
+
+| Method | Signature |
+|---|---|
+| `emit` | `(name: string, payload: object, opts?: { idempotencyKey?: string }) => Promise<void>` |
+| `registerEndpoint` | `(url: string, events: string[], opts?: { secret?: string }) => Promise<WebhookEndpoint>` |
+| `updateEndpoint` | `(id: string, patch: { url?, events?, isActive? }) => Promise<RedactedWebhookEndpoint \| null>` |
+| `rotateSecret` | `(id: string) => Promise<{ id: string; secret: string }>` |
+| `listEndpoints` | `() => Promise<RedactedWebhookEndpoint[]>` |
+| `removeEndpoint` | `(id: string) => Promise<void>` |
+| `listEventTypes` | `() => { name: string; description?: string }[]` |
+| `stop` | `() => Promise<void>` |
+
+```ts
+const wh = fortress.plugins.webhook;
+
+// A CSPRNG secret is generated when omitted — returned ONCE on the result.
+const endpoint = await wh.registerEndpoint('https://hooks.myapp.com/auth', ['auth.login.success', 'order.paid']);
+console.log(endpoint.secret); // whsec_… — store it now; it is never returned again
+
+await wh.updateEndpoint(endpoint.id, { events: ['order.paid'], isActive: true });
+const { secret } = await wh.rotateSecret(endpoint.id); // new secret, returned once
+
+const endpoints = await wh.listEndpoints(); // secret REDACTED
+await wh.removeEndpoint(endpoint.id);
+```
+
+> **Secrets are returned only at `registerEndpoint` and `rotateSecret`.** `listEndpoints()` and `updateEndpoint()` omit the `secret` field.
+
+## Signing
+
+Each attempt sends:
+
+```
+webhook-id: msg_<deliveryId>          # STABLE across retries — use it as your idempotency key
+webhook-timestamp: 1234567890         # changes per attempt
+webhook-signature: v1,<base64-hmac-sha256>
+```
+
+The signature is `HMAC-SHA256(secret, "{webhook-id}.{webhook-timestamp}.{body}")`. Because `webhook-id` is stable per delivery, a receiver that dedups on it ignores retries automatically.
+
+## Idempotency
+
+Pass `emit(name, payload, { idempotencyKey })` to make a logical event safe to emit more than once: a second `emit` with the same `(endpoint, idempotencyKey)` is a no-op, enforced by a unique index on `webhook_delivery (endpoint_id, idempotency_key)` (so it holds even under concurrent emits).
+
+## Types
+
+```ts
+type WebhookDeactivatedReason = `permanent_${number}` | 'too_many_failures';
+type WebhookErrorKind = 'http' | 'network';
+
+interface WebhookEndpoint {
+  id: string;
+  url: string;
+  events: string;              // JSON array of event names
+  secret: string;              // redacted in listEndpoints()/updateEndpoint()
+  isActive: boolean;
+  deactivatedReason: WebhookDeactivatedReason | null;
+  consecutiveFailures: number;
+  createdAt: Date;
+}
+
+interface WebhookDelivery {
+  id: string;
+  endpointId: string;
+  eventType: string;
+  payload: string;             // JSON
+  status: 'pending' | 'success' | 'failed';
+  attempts: number;
+  idempotencyKey: string | null;
+  lastAttemptAt: Date | null;
+  nextRetryAt: Date | null;
+  responseStatus: number | null;
+  responseBody: string | null; // first ~2 KB, for debugging
+  errorKind: WebhookErrorKind | null;
+  createdAt: Date;
+}
+```
+
+## Security
+
+- **SSRF.** Built-in delivery resolves the host, rejects non-https and private/loopback/link-local/CGNAT targets (IPv4, IPv6, `::ffff:`-mapped, and `64:ff9b::/96` NAT64 forms), and pins the connection to the validated IP. Overriding `delivery.fetch` bypasses this guard — only do so for targets you control. `assertSafeWebhookUrl(url)` is exported if a custom transport wants to reuse the guard.
+- **Secrets.** Generated with a CSPRNG, returned only at creation/rotation, and redacted from list/update. Rotate with `rotateSecret`.
+- **Payloads.** Signed but **not encrypted** — never put secrets/PII in a webhook payload you wouldn't want a receiver (or a misconfigured endpoint) to see.
+
+## Example
+
+```ts
+import { createFortress, obj, str } from '@bajustone/fortress';
+import { builtinEvents, databaseQueue, webhook } from '@bajustone/fortress/plugins/webhook';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    webhook({
+      events: [
+        ...builtinEvents(),
+        { name: 'order.paid', schema: obj({ orderId: str() }, 'orderId') },
+      ],
+      queue: databaseQueue({ pollMs: 10_000 }), // crash-safe
+      delivery: {
+        maxConsecutiveFailures: 10,
+        onEndpointDeactivated: (e, reason) => log.warn('webhook endpoint disabled', { id: e.id, reason }),
+        onDeliveryFailed: d => deadLetter.push(d),
+      },
+    }),
+  ],
+});
+
+const wh = fortress.plugins.webhook;
+
+// Built-in auth events deliver automatically on login/register/etc.
+await wh.registerEndpoint('https://hooks.myapp.com/auth', ['auth.login.success', 'order.paid']);
+
+// Emit a custom event
+await fortress.plugins.webhook.emit('order.paid', { orderId: 'o_123' }, { idempotencyKey: 'o_123' });
+
+// On shutdown
+await wh.stop();
+```

package/docs/policy-as-code.md

@@ -0,0 +1,156 @@
+# Policy as code
+
+Declare roles, permissions, groups, and service accounts in JSON, then reconcile the file against the database with `diffPolicy()` and `applyPolicyPlan()`.
+
+## File format
+
+Default file: `fortress.policy.json` in the working directory.
+Environment-specific override:
+`fortress.policy.<env>.json`, picked when `FORTRESS_ENV` is set (the env
+file fully **replaces** the base — no implicit merging).
+
+See [`examples/policy/fortress.policy.json`](../examples/policy/fortress.policy.json)
+for a complete example. Minimum shape:
+
+```jsonc
+{
+  "resources": [
+    { "name": "article", "actions": ["create", "read", "update", "delete"] }
+  ],
+  "roles": [
+    {
+      "name": "editor",
+      "description": "Authors and edits articles",
+      "permissions": [
+        { "resource": "article", "action": "create" },
+        { "resource": "article", "action": "update" }
+      ]
+    }
+  ],
+  "groups": [
+    { "name": "engineering", "description": "Engineering team" }
+  ],
+  "serviceAccounts": [
+    { "name": "ci-bot", "displayName": "CI", "isActive": true, "roles": ["editor"] }
+  ]
+}
+```
+
+### What's covered
+
+| Entity | Declared keys | Reconciled by `applyPolicyPlan` |
+|---|---|---|
+| Resources | `name`, `actions[]`, `description` | Creates missing resources; adds missing actions to existing resources |
+| Roles | `name`, `description`, `permissions[]` | Creates missing roles; updates description; adds + removes permissions |
+| Groups | `name`, `description` | Creates missing groups; updates description |
+| Service accounts | `name`, `displayName`, `description`, `isActive`, `roles[]` | Creates missing SAs; updates fields; binds + unbinds roles |
+
+### What's intentionally NOT covered
+
+- **OAuth clients.** They have secrets — manage via the admin endpoints.
+- **User accounts / user → group memberships.** User data, not policy.
+  Provision users via signup or admin endpoints; manage memberships via
+  `fortress.iam.addUserToGroup(...)`.
+- **Per-tenant role bindings.** Manage via the admin endpoints; the
+  global policy file is the wrong fit for per-tenant scale.
+- **Resource deletions / action removals.** Dropping a resource cascades
+  to permissions and role bindings; require explicit operator action.
+
+## Diff + apply workflow
+
+The same three-step loop you'd use for migrations or manifests:
+
+```ts
+import { createFortress, loadPolicy, diffPolicy, applyPolicyPlan } from '@bajustone/fortress';
+import config from './fortress.config';
+
+const fortress = createFortress(config);
+const { policy } = await loadPolicy();        // reads fortress.policy.json (or env override)
+const plan = await diffPolicy(policy, fortress.iam);
+if (!plan.inSync) {
+  console.log('Plan:');
+  for (const op of plan.ops) console.log(' -', op.description);
+
+  const result = await applyPolicyPlan(plan, fortress.iam);
+  if (result.errors.length) {
+    console.error('Some ops failed:', result.errors);
+    process.exit(1);
+  }
+}
+```
+
+### Pruning (deletes)
+
+`diffPolicy(policy, iam, { prune: true })` emits `delete-role`,
+`delete-group`, `delete-service-account`, and `unbind-service-account-role`
+ops for entities present in the database but absent from the policy
+file. System roles (`isSystem === true`) are never deleted.
+
+Run the un-pruned diff first to review, then add `prune: true` when
+the diff matches your intent. An empty policy is rejected under prune by default because it would delete all managed IAM state; the destructive operation requires explicit `{ prune: true, allowEmptyPrune: true }` acknowledgement.
+
+### Resource ops apply without filesystem access
+
+`applyPolicyPlan` reconciles resources/actions, roles, groups, service accounts, and their global role bindings directly through `IamService`. It never writes a temporary file, so it works in workerd/Deno-no-fs runtimes. The compatibility `applyResourceOps(plan, iam, legacyFilePath)` helper now ignores the retained path argument and applies only resource operations through the same in-memory database path.
+
+## CLI
+
+The CLI exposes one offline command (no DB required) plus three
+how-to printers because the diff/apply/check commands need your
+configured `Fortress` instance:
+
+```sh
+fortress policy:summary [--file <path>] [--env <name>]   # offline; prints declared counts
+fortress policy:diff                                     # prints code snippet for in-app usage
+fortress policy:apply                                    # prints code snippet
+fortress policy:check                                    # prints code snippet
+```
+
+`fortress policy:summary` is useful in CI to assert the file parses
+and to print a quick inventory; the actual diff/apply runs from a
+small script in your repo that knows your DB connection.
+
+## CI gate
+
+Add a `policy:check` step to your CI workflow that runs against an
+ephemeral DB seeded from production policy:
+
+```ts
+// scripts/policy-check.ts
+import { createFortress, loadPolicy, diffPolicy } from '@bajustone/fortress';
+import { createTestAdapter } from '@bajustone/fortress/testing';
+import { applyPolicyPlan } from '@bajustone/fortress';
+
+const fortress = createFortress({
+  database: createTestAdapter(),
+  jwt: { key: process.env.FORTRESS_JWT_SECRET! },
+});
+
+const { policy } = await loadPolicy();
+// Bootstrap from the policy itself so the diff result reflects only the
+// drift between two consecutive policy revisions.
+await applyPolicyPlan(await diffPolicy(policy, fortress.iam), fortress.iam);
+
+const after = await diffPolicy(policy, fortress.iam);
+if (!after.inSync) {
+  console.error('Policy reconciliation is not converging:', after.ops);
+  process.exit(1);
+}
+console.log(`Policy in sync (${policy.roles?.length ?? 0} role(s), ${policy.serviceAccounts?.length ?? 0} service account(s)).`);
+```
+
+Run it as a step in `.github/workflows/fortress-ci.yml` alongside
+`fortress manifest:check` and `fortress migrate:check`.
+
+## API reference
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `loadPolicy(options?)` | async function | Read, validate, and parse the policy file (env-aware) |
+| `resolvePolicyPath(options?)` | async function | Resolve the file path that `loadPolicy` would use |
+| `diffPolicy(policy, iam, options?)` | function | Compute the plan to reconcile live IAM with `policy` |
+| `applyPolicyPlan(plan, iam)` | function | Apply every op in the plan; returns `applied` / `errors` |
+| `applyResourceOps(plan, iam, legacyFilePath)` | function | Compatibility helper; applies resource-only ops directly without file I/O |
+| `PolicyDocument`, `PolicyRole`, ... | types | Type-only exports for callers that read the file themselves |
+
+All exported from the package root.

package/docs/route-manifest.md

@@ -0,0 +1,46 @@
+# Route security manifest
+
+Fortress builds a canonical route-security manifest from endpoint metadata. The manifest is derived from the same `EndpointDefinition` records used by `fortress.handleRequest()`, adapter mounting, and OpenAPI generation.
+
+## Runtime API
+
+```ts
+const manifest = fortress.manifest;
+```
+
+Each entry contains:
+
+- `method`, `path`, `handler` — the HTTP route and dispatcher handler.
+- `plugin` — `auth`, `iam`, a registered plugin name, or `null` when the origin cannot be inferred.
+- `classification` — one of:
+  - `public` — `meta.security` includes `none`.
+  - `authenticated` — bearer/basic/API-key route without an IAM permission.
+  - `rbac` — route has `meta.permission` and requires IAM authorization.
+  - `oauth-protocol` — route has `meta.bearerKind: 'oauth'` and self-authenticates as an OAuth protocol endpoint.
+  - `default-deny` — no usable security metadata; the request pipeline denies it.
+- `permission`, `security`, `bearerKind` — direct endpoint security metadata.
+- `csrfApplicable` — unsafe method and not skipped by `config.csrf`.
+- `rateLimited` — route matches plugin rate-limit middleware, or a rate-limit hook protects the auth gate.
+- `mounted` — `true` for routes present in the active `fortress.endpoints` union.
+
+## CLI
+
+```sh
+fortress manifest --out route-manifest.json
+fortress manifest:check
+```
+
+The CLI currently emits/checks the core auth + IAM manifest. For app/plugin-aware checks, call the programmatic API against your configured `fortress` instance:
+
+```ts
+import { detectRouteManifestDrift, hasRouteManifestDrift } from '@bajustone/fortress';
+
+const drift = detectRouteManifestDrift(fortress, { openapi: yourGeneratedOpenApiSpec });
+if (hasRouteManifestDrift(drift)) {
+  throw new Error(JSON.stringify(drift, null, 2));
+}
+```
+
+## Adapter behavior
+
+Hono, Express, and SvelteKit adapters use `fortress.manifest` to decide which paths are Fortress-managed before delegating to `fortress.handleRequest()`. This keeps route interception, OpenAPI, and security drift checks aligned with the same endpoint metadata.