@bajustone/fortress 1.0.0-rc.1

package/docs/plugins/api-key.md

@@ -0,0 +1,327 @@
+# API Key Plugin
+
+## Overview
+
+The `api-key` plugin adds scoped API key management to Fortress. It is designed for service accounts, CI/CD pipelines, mobile devices, and any scenario where long-lived bearer tokens are preferable to short-lived JWTs.
+
+Keys are generated with a configurable prefix, hashed with SHA-256 before storage, and can be scoped to limit what actions a key is allowed to perform.
+
+**Polymorphic ownership.** Keys are owned by a `Subject` — either a `USER` or a `SERVICE_ACCOUNT`. The api-key schema stores `(subject_type, subject_id)` instead of a hard FK to `users.id`, mirroring `role_binding` and `direct_permission_binding`. Authentication flows support both subject types transparently.
+
+**Automatic request principal resolution.** The plugin implements Fortress's `resolvePrincipal` capability: when a request arrives with an `Authorization: ApiKey <key>` or `X-API-Key: <key>` header, the plugin resolves the key to its owning subject and that subject becomes the request principal for RBAC. No middleware setup required — just register the plugin.
+
+## Installation
+
+Import the `apiKey` factory and pass it in the `plugins` array when creating a Fortress instance:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { apiKey } from '@bajustone/fortress/plugins/api-key';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    apiKey({
+      prefix: 'myapp',
+      defaultExpirySeconds: 90 * 24 * 60 * 60, // 90 days
+      maxKeysPerSubject: 5,
+    }),
+  ],
+});
+```
+
+Once registered, methods are available at `fortress.plugins['api-key']` with full type safety.
+
+## Configuration
+
+All fields on `ApiKeyConfig` are optional:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `prefix` | `string` | `'fortress'` | Prefix prepended to generated keys. Keys are formatted as `{prefix}_sk_{hex}`. |
+| `defaultExpirySeconds` | `number \| null` | `null` | Default time-to-live for new keys, in seconds. `null` means keys never expire unless an explicit `expiresAt` is provided at creation time. |
+| `maxKeysPerSubject` | `number` | `10` | Maximum number of active (non-revoked) keys a single subject (user or service account) can hold. Revoked keys do not count toward this limit. |
+| `routes` | `boolean` | `false` | Mount self-service HTTP routes under `/api-key/keys/*`. The programmatic methods on `fortress.plugins['api-key']` are always available regardless of this flag. |
+
+## Usage
+
+### Creating a key
+
+```ts
+// For a user
+const { key, id } = await fortress.plugins['api-key'].createKey({
+  subject: { type: 'USER', id: userId },
+  name: 'CI deploy token',
+});
+
+// For a service account (see IAM docs for createServiceAccount)
+const { key: saKey } = await fortress.plugins['api-key'].createKey({
+  subject: { type: 'SERVICE_ACCOUNT', id: serviceAccountId },
+  name: 'ci-deploy-key',
+});
+
+// key = "myapp_sk_a1b2c3d4..." (the raw secret -- only returned once)
+// id  = 42 (database record ID)
+```
+
+Store or display the raw `key` immediately. Fortress stores only the SHA-256 hash; the plaintext cannot be retrieved later.
+
+You can set an explicit expiry:
+
+```ts
+const { key } = await fortress.plugins['api-key'].createKey({
+  subject: { type: 'USER', id: userId },
+  name: 'Temp key',
+  expiresAt: new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now
+});
+```
+
+If neither `expiresAt` nor `defaultExpirySeconds` is set, the key never expires.
+
+### Listing keys
+
+```ts
+const keys = await fortress.plugins['api-key'].listKeys({
+  subject: { type: 'USER', id: userId },
+});
+
+for (const k of keys) {
+  console.log(k.id, k.name, k.keyPrefix, k.scopes, k.expiresAt, k.lastUsedAt);
+}
+```
+
+Returns only active (non-revoked) keys scoped to the given subject. Each entry includes a short `keyPrefix` (first 12 characters) for identification but never exposes the full key or its hash.
+
+### Revoking a key
+
+```ts
+await fortress.plugins['api-key'].revokeKey({
+  subject: { type: 'USER', id: userId },
+  id: keyId,
+});
+```
+
+Marks the key as revoked. Revoked keys cannot be resolved and do not count toward the per-subject limit. The `subject` parameter is checked against the key's owner — attempting to revoke a key that belongs to a different subject throws a `NotFound` error.
+
+### Rotating a key
+
+```ts
+const { key: newKey, id: newId } = await fortress.plugins['api-key'].rotateKey({
+  subject: { type: 'USER', id: userId },
+  id: keyId,
+});
+```
+
+Rotation is a single atomic operation that:
+
+1. Revokes the existing key.
+2. Creates a new key with the same `name`, `scopes`, and `expiresAt` as the original.
+
+The old key stops working immediately. The new raw key is returned and must be stored by the caller.
+
+### Resolving a key for authentication
+
+```ts
+const result = await fortress.plugins['api-key'].resolveKey(rawKey);
+
+if (!result) {
+  // Key is invalid, revoked, expired, or owned by a disabled service account.
+  throw new Error('Unauthorized');
+}
+
+console.log(result.subject); // { type: 'USER' | 'SERVICE_ACCOUNT', id: string }
+console.log(result.scopes);  // string[] | null
+```
+
+`resolveKey` hashes the provided raw key and looks it up in the database. It returns `null` when the key is unknown, revoked, past its `expiresAt`, or owned by a service account with `isActive: false`. On success it also updates the key's `lastUsedAt` timestamp.
+
+### Authenticating incoming requests
+
+You don't need to call `resolveKey` yourself — the api-key plugin implements Fortress's `resolvePrincipal` capability, so both `fortress.handleRequest` *and* the Hono / Express / SvelteKit user-route auth middleware automatically resolve requests bearing an api-key header into a subject principal. Two header formats are accepted:
+
+```
+Authorization: ApiKey myapp_sk_a1b2c3d4...
+X-API-Key: myapp_sk_a1b2c3d4...
+```
+
+If neither header is present, the pipeline falls back to the JWT path. If both a JWT and an api-key are present, the api-key wins (resolvers run before the JWT fallback).
+
+> Note: api-key authentication works uniformly on Fortress-owned routes (`/auth/*`, `/iam/*`, plugin routes) *and* your own custom routes — any route protected by the adapter's auth middleware goes through `fortress.resolvePrincipal`, which tries the plugin chain before the JWT fallback. The resolved principal is available as `fortressSubject` on the adapter request context (Hono `c.get('fortressSubject')` / Express `req.fortressSubject` / SvelteKit `event.locals.fortress.subject`).
+
+Once resolved, the principal flows through the same RBAC machinery as a JWT-authenticated request:
+
+```ts
+// Inside a fortress-managed route or an adapter middleware RBAC check
+await fortress.iam.checkPermission(
+  ctx.subject,  // { type: 'USER' | 'SERVICE_ACCOUNT', id }
+  'deploy',
+  'run',
+);
+```
+
+### Scoped keys
+
+Scopes let you restrict what an API key is allowed to do. Pass a `scopes` array at creation time:
+
+```ts
+const { key } = await fortress.plugins['api-key'].createKey({
+  subject: { type: 'USER', id: userId },
+  name: 'Read-only analytics',
+  scopes: ['analytics:read', 'reports:list'],
+});
+```
+
+When the key is resolved, the scopes are returned so your application can enforce them:
+
+```ts
+const result = await fortress.plugins['api-key'].resolveKey(rawKey);
+
+if (result && result.scopes && !result.scopes.includes('analytics:read')) {
+  throw new Error('Forbidden: insufficient scope');
+}
+```
+
+If no scopes are provided, `resolveKey` returns `scopes: null`, which you can treat as "unrestricted" or reject based on your security policy.
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `createKey` | `(input: { subject?: Subject; name: string; scopes?: string[]; expiresAt?: Date }, routeCtx?: PluginRouteContext)` | `Promise<{ key: string; id: string }>` |
+| `listKeys` | `(input: { subject?: Subject }, routeCtx?: PluginRouteContext)` | `Promise<ApiKeyInfo[]>` |
+| `revokeKey` | `(input: { subject?: Subject; id: string \| string }, routeCtx?: PluginRouteContext)` | `Promise<{ ok: true }>` |
+| `rotateKey` | `(input: { subject?: Subject; id: string \| string }, routeCtx?: PluginRouteContext)` | `Promise<{ key: string; id: string }>` |
+| `resolveKey` | `(rawKey: string)` | `Promise<{ subject: Subject; scopes: string[] \| null } \| null>` |
+
+**Dual-mode `subject`.** When called from an HTTP route handler with a `routeCtx`, the plugin uses `routeCtx.subject` and ignores any `subject` supplied in `input` — clients can't pick which subject a key is created for. When called programmatically (no `routeCtx`), the plugin uses `input.subject`; programmatic callers are trusted.
+
+The `ApiKeyInfo` type returned by `listKeys`:
+
+```ts
+interface ApiKeyInfo {
+  id: string;
+  name: string;
+  keyPrefix: string;        // first 12 characters of the raw key
+  scopes: string[] | null;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+}
+```
+
+## Service account flow (end-to-end)
+
+A complete walkthrough of setting up a CI deploy bot as a service account, granting it permissions, and authenticating its requests. Service accounts are first-class IAM principals — see the [README IAM section](../../README.md#use-service-accounts) for the conceptual overview.
+
+### 1. Create the service account
+
+```ts
+const ci = await fortress.iam.createServiceAccount({
+  name: 'ci-deploy',                       // machine identifier, immutable
+  displayName: 'CI Deploy',
+  description: 'Runs production deploys from GitHub Actions',
+});
+```
+
+### 2. Grant it permissions
+
+Either bind a role or a direct permission. Both work exactly as they do for users:
+
+```ts
+const deployer = await fortress.iam.createRole('deployer', [
+  { resource: 'deploy', action: 'run' },
+  { resource: 'deploy', action: 'rollback' },
+]);
+await fortress.iam.bindRoleToServiceAccount(ci.id, deployer.id);
+```
+
+### 3. Mint an API key for the service account
+
+Programmatically:
+
+```ts
+const { key } = await fortress.plugins['api-key'].createKey({
+  subject: { type: 'SERVICE_ACCOUNT', id: ci.id },
+  name: 'ci-deploy-github-actions',
+});
+// store `key` in your CI secrets store NOW — it is never returned again
+```
+
+Or via HTTP, using the admin plugin's mint endpoint — the only supported HTTP path for bootstrapping a service account's first credential (a fresh SA has no login flow, so it can't self-mint via the `/api-key/keys` self-service route):
+
+```bash
+curl -X POST http://localhost:3000/admin/service-accounts/$SA_ID/api-keys \
+  -H "Authorization: Bearer $ADMIN_JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"ci-deploy-github-actions"}'
+```
+
+This requires `admin({ apiKeyRoutes: true })` registered alongside `apiKey()`, and the caller must hold the `apiKey:manage` permission (auto-registered by bootstrap). See [docs/plugins/admin.md — API key management](./admin.md#api-key-management) for the full admin surface.
+
+### 4. Authenticate requests using the key
+
+The client sends the key in either header. Fortress's `resolvePrincipal` plugin hook — which `api-key` implements — inspects each incoming request and turns the header into a subject principal *before* RBAC runs:
+
+```
+POST /deploy/run HTTP/1.1
+Authorization: ApiKey fortress_sk_a1b2c3d4...
+```
+
+or
+
+```
+POST /deploy/run HTTP/1.1
+X-API-Key: fortress_sk_a1b2c3d4...
+```
+
+Inside your route, the authenticated principal is the service account:
+
+```ts
+// On a fortress-managed route, routeCtx.subject is populated
+async handler(input, routeCtx) {
+  // routeCtx.subject is { type: 'SERVICE_ACCOUNT', id: ci.id }
+  const allowed = await fortress.iam.checkPermission(
+    routeCtx.subject!,
+    'deploy',
+    'run',
+  );
+  if (!allowed) throw Errors.forbidden();
+  // ... run the deploy
+}
+```
+
+Fortress-managed routes (like the `/iam/service-accounts/*` admin endpoints) automatically enforce the subject's permissions via `enforceFortressPermission`.
+
+### 5. Kill-switch: deactivate when compromised
+
+If a key leaks, you have two layers of defense. Revoke the individual key, or deactivate the entire service account — the latter instantly stops every key the account owns from resolving, and drives `checkPermission` to return `false` for that subject:
+
+```ts
+// Option A: revoke just this key
+await fortress.plugins['api-key'].revokeKey({
+  subject: { type: 'SERVICE_ACCOUNT', id: ci.id },
+  id: keyId,
+});
+
+// Option B: kill-switch the whole service account
+await fortress.iam.updateServiceAccount(ci.id, { isActive: false });
+```
+
+### 6. Decommission: delete the service account
+
+`deleteServiceAccount` is a hard delete with cascade — the account row, all role bindings, all direct permission bindings, and every API key owned by the account are removed in one operation.
+
+```ts
+await fortress.iam.deleteServiceAccount(ci.id);
+```
+
+---
+
+## How It Works
+
+1. **Key generation** -- `crypto.getRandomValues` produces 32 random bytes, hex-encoded and prepended with `{prefix}_sk_` to form the raw key.
+2. **Hashed storage** -- The raw key is hashed with SHA-256 (via the same `hashToken` used for refresh tokens). Only the hash is persisted; the plaintext is returned once at creation time.
+3. **Prefix-based identification** -- The first 12 characters of the raw key are stored as `keyPrefix`, allowing users and admins to identify keys in listings without exposing the secret.
+4. **Resolution** -- `resolveKey` hashes the incoming raw key and performs a database lookup on `keyHash`. It rejects revoked and expired keys, and updates `lastUsedAt` on success.
+5. **Scopes** -- Stored as a JSON-serialized string array in the database and parsed back to `string[]` on read. Scope enforcement is left to the application layer.

package/docs/plugins/audit-log.md

@@ -0,0 +1,261 @@
+# Audit Log Plugin
+
+## Overview
+
+The audit-log plugin provides a hash-chain integrity trail for authentication events. Every login, logout, registration, token refresh, and failed login attempt is recorded with actor, timestamp, IP address, and user-agent metadata.
+
+An optional SHA-256 hash chain links each entry to its predecessor, making retroactive tampering detectable. This is designed for organizations that need to demonstrate compliance with SOC 2, HIPAA, PCI-DSS, or similar frameworks that require immutable, verifiable logs of access events.
+
+## Installation
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { auditLog } from '@bajustone/fortress/plugins/audit-log';
+
+const fortress = createFortress({
+  jwt: { key: process.env.JWT_SECRET! },
+  database: adapter,
+  plugins: [auditLog()],
+});
+```
+
+The bundled Fortress migrations create `fortress_audit_log`; run `fortress.migrate()` before enabling the plugin.
+
+## Configuration
+
+Pass an `AuditLogConfig` object to the `auditLog()` factory:
+
+```ts
+auditLog({
+  events: ['LOGIN_SUCCESS', 'LOGIN_FAILURE', 'LOGOUT'],
+  hashChain: true,
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `events` | `AuditEventType[]` | `undefined` (all events) | Restrict which events are captured. When omitted, all event types are logged. |
+| `hashChain` | `boolean` | `false` | Enable SHA-256 hash chain linking each entry to its predecessor for tamper detection. |
+
+### Event Types
+
+| Event | Trigger | Actor |
+|---|---|---|
+| `LOGIN_SUCCESS` | Successful `auth.login()` call | The authenticated user |
+| `LOGIN_FAILURE` | Failed `auth.login()` call (wrong password, unknown user) | Anonymous (actorId is null) |
+| `LOGOUT` | `auth.logout()` call | User (resolved from token context) |
+| `REGISTER` | `auth.createUser()` call | The newly created user |
+| `TOKEN_REFRESH` | `auth.refresh()` call | User (from refresh token context) |
+| `TOKEN_REUSE` | Refresh token replay detected | Reserved for future hook support |
+
+## Usage
+
+### Automatic Event Capture
+
+Once the plugin is registered, events are captured automatically through Fortress lifecycle hooks. No additional code is needed for logging -- every `auth.login()`, `auth.createUser()`, `auth.logout()`, and `auth.refresh()` call writes an audit entry.
+
+```ts
+// These calls automatically produce audit log entries:
+const user = await fortress.auth.createUser({
+  email: 'alice@example.com',
+  name: 'Alice',
+  password: 'secure-password-123',
+});
+// -> REGISTER entry logged
+
+const { accessToken, refreshToken } = await fortress.auth.login(
+  'alice@example.com',
+  'secure-password-123',
+);
+// -> LOGIN_SUCCESS entry logged
+
+await fortress.auth.refresh(refreshToken);
+// -> TOKEN_REFRESH entry logged
+
+await fortress.auth.logout(refreshToken);
+// -> LOGOUT entry logged
+```
+
+Failed logins are also captured. The entry includes the attempted identifier and error message in the `metadata` field as JSON:
+
+```ts
+await fortress.auth.login('alice@example.com', 'wrong-password').catch(() => {});
+// -> LOGIN_FAILURE entry logged with metadata: {"identifier":"alice@example.com","error":"..."}
+```
+
+### Passing Request Metadata
+
+To capture IP address and user-agent in audit entries, pass `RequestMeta` through the auth methods that support it. If you are using the Hono adapter, this is handled automatically. Otherwise, pass `meta` through your hook context.
+
+### Querying the Audit Log
+
+Use the type-safe plugin access to retrieve entries:
+
+```ts
+const entries = await fortress.plugins['audit-log'].getAuditLog();
+```
+
+The `getAuditLog` method accepts an `AuditLogQueryOptions` object for filtering and pagination:
+
+```ts
+// All login failures in the last 24 hours
+const failures = await fortress.plugins['audit-log'].getAuditLog({
+  eventType: 'LOGIN_FAILURE',
+  from: new Date(Date.now() - 24 * 60 * 60 * 1000),
+});
+
+// All events for a specific user, paginated
+const userHistory = await fortress.plugins['audit-log'].getAuditLog({
+  userId: '42',
+  limit: 50,
+  offset: 0,
+});
+
+// Events within a date range
+const report = await fortress.plugins['audit-log'].getAuditLog({
+  from: new Date('2026-01-01'),
+  to: new Date('2026-03-31'),
+  limit: 1000,
+});
+```
+
+Results are returned in reverse chronological order (`timestamp DESC`).
+
+#### Query Options
+
+| Option | Type | Description |
+|---|---|---|
+| `userId` | `string` | Filter by `actorId` |
+| `eventType` | `AuditEventType` | Filter by event type |
+| `from` | `Date` | Entries on or after this timestamp |
+| `to` | `Date` | Entries on or before this timestamp |
+| `limit` | `number` | Maximum entries to return |
+| `offset` | `number` | Number of entries to skip (for pagination) |
+
+### Hash Chain for Tamper Detection
+
+When `hashChain: true` is set, each audit entry includes a `previousHash` field containing the SHA-256 hash of the preceding entry. The digest uses an unambiguous serialization of all 13 stored fields, including the predecessor's own `previousHash`, so changes to actor, target, request, outcome, metadata, or timestamp fields break verification. This is an unkeyed integrity check, not proof against an attacker who can rewrite the complete database: such an attacker can recompute the chain and reset its in-database anchor. Use external attestation or a keyed/external anchor when database-write attackers are in scope.
+
+The first entry has `previousHash: null`. Every subsequent entry references the one before it. A permanent singleton `fortress_audit_chain_state` anchor starts at `{ lastHash: null, entryCount: 0 }` and stores the expected terminal hash/count after each append, making deletion or mutation of the final row—or deletion of the entire chain—detectable as well. Each append reads this anchor, inserts the new row using `anchor.lastHash`, and advances the anchor in the same serialized transaction, so append work remains constant as the log grows. A zero anchor performs one bounded (`LIMIT 1`) existence probe to reject an untransformed legacy log safely; no history is hashed or traversed. SQLite transactions are queued per adapter instance to accommodate synchronous drivers; PostgreSQL uses a transaction-scoped advisory lock across application instances and is not placed on an in-process/global queue. `verifyChain()` performs the separate full historical scan.
+
+```ts
+const fortress = createFortress({
+  jwt: { key: process.env.JWT_SECRET! },
+  database: adapter,
+  plugins: [auditLog({ hashChain: true })],
+});
+
+// After several auth events...
+const entries = await fortress.plugins['audit-log'].getAuditLog();
+
+// Verify chain integrity without relying on identifier ordering
+const verification = await fortress.plugins['audit-log'].verifyChain();
+if (!verification.valid)
+  throw new Error(`Broken audit chain: ${JSON.stringify(verification.brokenLinks)}`);
+```
+
+If a row is deleted or altered, either an internal link or the persisted terminal anchor breaks. Auditors can verify both the chain graph and its expected terminal state through `verifyChain()`. Appends intentionally do not rescan history; schedule `verifyChain()` independently and alert on an invalid result.
+
+### Enabling hash chaining on an existing log
+
+A non-empty log written with `hashChain: false` must be explicitly transitioned before normal auth traffic starts using `hashChain: true`. Archive and externally attest the legacy rows first: rebaselining links the stored rows from that point forward but cannot prove that their earlier history was untampered.
+
+```ts
+const audit = fortress.plugins['audit-log'];
+const result = await audit.rebaselineChain();
+if (!result.valid)
+  throw new Error('Audit rebaseline failed');
+```
+
+`rebaselineChain()` runs under the same transaction/advisory lock as append, accepts only the migration-seeded zero anchor plus rows whose `previousHash` values are all null, orders those rows by `createdAt` and then string `id`, rewrites their links, advances the anchor, and verifies the result before commit. It rejects an already or partially chained log, so it cannot be used as a general-purpose way to erase evidence of detected tampering. Run it once during a maintenance window after migrations, before exposing login/register/refresh/logout traffic on the hash-chain-enabled instance.
+
+Automatic audit hook writes are best-effort after auth state changes: an audit storage/anchor failure is sent to the configured logger and does not turn a committed login, registration, refresh, or logout into a reported auth failure. Direct `logCustomEvent()` and maintenance methods still reject on errors, allowing operators to monitor and fail their own workflows explicitly.
+
+**Performance note:** Chain-enabled append is O(1) with respect to historical row count. `verifyChain()` and the one-time `rebaselineChain()` are O(n) maintenance operations and hold the chain lock while they run.
+
+### Exporting for compliance
+
+`exportEntries` serializes audit entries to a string for retention,
+hand-off to a SIEM, or a compliance request. It accepts the same
+`AuditLogQueryOptions` as `getAuditLog`, so you can scope the export by
+user, event type, or time window.
+
+```ts
+const audit = fortress.plugins['audit-log'];
+
+// Full JSON export (default format)
+const json = await audit.exportEntries();
+
+// CSV export of one user's last quarter, for a data-subject request
+const csv = await audit.exportEntries('csv', {
+  userId: '42',
+  from: new Date('2026-01-01'),
+  to: new Date('2026-03-31'),
+});
+```
+
+The CSV output is RFC 4180-compliant: a fixed header row, one row per
+entry, with cells containing commas, quotes, or newlines quoted and their
+embedded quotes doubled. Cells beginning with `=`, `+`, `-`, `@`, tab, or
+carriage return are prefixed with an apostrophe to prevent spreadsheet-formula
+injection. `Date` columns are emitted as ISO 8601 strings.
+Both formats stream the rows in the same order as `getAuditLog` (newest
+first).
+
+## API Reference
+
+### Factory
+
+| Function | Signature | Description |
+|---|---|---|
+| `auditLog` | `(config?: AuditLogConfig) => FortressPlugin` | Creates the audit-log plugin instance |
+
+### Methods (via `fortress.plugins['audit-log']`)
+
+| Method | Signature | Description |
+|---|---|---|
+| `getAuditLog` | `(options?: AuditLogQueryOptions) => Promise<AuditLogEntry[]>` | Query audit log entries with optional filters |
+| `logCustomEvent` | `(event: CustomAuditEvent) => Promise<void>` | Append an application-defined event |
+| `verifyChain` | `() => Promise<ChainVerificationResult>` | Walk the hash chain and report broken links |
+| `rebaselineChain` | `() => Promise<ChainVerificationResult>` | One-time transactional conversion of an unchained legacy log |
+| `exportEntries` | `(format?: 'json' \| 'csv', options?: AuditLogQueryOptions) => Promise<string>` | Serialize entries for compliance export (defaults to `json`) |
+
+### Types
+
+**`AuditLogEntry`** -- a single audit log record:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Adapter-generated entry ID |
+| `timestamp` | `Date` | Event timestamp |
+| `eventType` | `AuditEventType` | One of the six event types |
+| `actorId` | `string \| null` | User ID of the actor, or null for anonymous events |
+| `actorType` | `string` | `"user"` or `"anonymous"` |
+| `targetId` | `string \| null` | ID of the affected resource (e.g., the new user on REGISTER) |
+| `targetType` | `string \| null` | Type of the affected resource (e.g., `"user"`) |
+| `ipAddress` | `string \| null` | Client IP if available via `RequestMeta` |
+| `userAgent` | `string \| null` | Client user-agent if available via `RequestMeta` |
+| `outcome` | `string` | `"success"` or `"failure"` |
+| `metadata` | `string \| null` | JSON string with event-specific details (e.g., error message on failure) |
+| `previousHash` | `string \| null` | SHA-256 hash of the preceding entry (only when `hashChain` is enabled) |
+| `createdAt` | `Date` | Creation timestamp |
+
+## How It Works
+
+The plugin uses Fortress's hook system to intercept auth lifecycle events without modifying core code.
+
+**Hooks registered:**
+
+| Hook | Event Logged |
+|---|---|
+| `afterLogin` | `LOGIN_SUCCESS` |
+| `onLoginFailure` | `LOGIN_FAILURE` |
+| `beforeLogout` | `LOGOUT` |
+| `afterRegister` | `REGISTER` |
+| `afterTokenRefresh` | `TOKEN_REFRESH` |
+
+Each hook writes a row to the `audit_log` model via the database adapter. When hash chaining is enabled, Fortress reads the persisted terminal anchor, stores its `lastHash` as the new entry's `previousHash`, hashes the inserted entry, and advances the anchor in the same serialized transaction. Full graph traversal and all-field digest verification are reserved for `verifyChain()`.
+
+The `getAuditLog` method builds `WhereClause` filters from the query options and delegates to `db.findMany`, keeping the plugin fully database-agnostic.
+
+All hooks run inline with the auth flow. Audit-plugin write failures are logged and contained so they cannot report a committed auth state change as failed. Failures from other plugins are unaffected, and explicit audit method calls continue to reject on storage or chain-maintenance errors.