@bajustone/fortress 1.0.0-rc.1

package/docs/plugins/social-login.md

@@ -0,0 +1,337 @@
+# Social Login Plugin
+
+## Overview
+
+The `social-login` plugin is an OAuth/OIDC consumer that lets users sign in with external identity providers. It handles the full OAuth 2.0 authorization code flow with PKCE, profile normalization, JIT (just-in-time) user provisioning, and account linking.
+
+Built-in providers: **Google**, **GitHub**, **Microsoft**, **Apple**, **Discord**.
+Any OIDC-compliant provider can be added via the `issuer` option.
+
+## Installation
+
+```typescript
+import { createFortress } from '@bajustone/fortress';
+import { socialLogin } from '@bajustone/fortress/plugins/social-login';
+
+const fortress = createFortress({
+  database: adapter,
+  jwt: { key: process.env.JWT_SECRET!, issuer: 'my-app' },
+  plugins: [
+    socialLogin({
+      providers: [
+        {
+          name: 'google',
+          clientId: process.env.GOOGLE_CLIENT_ID!,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+        },
+        {
+          name: 'github',
+          clientId: process.env.GITHUB_CLIENT_ID!,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+        },
+      ],
+    }),
+  ],
+});
+```
+
+The plugin registers a `social_account` table that links provider identities to Fortress users. Your database adapter must support this model (the Drizzle adapter handles it automatically).
+
+## Configuration
+
+`socialLogin(config)` accepts a `SocialLoginConfig` object:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `providers` | `ProviderConfig[]` | (required) | List of configured providers. |
+| `autoRegister` | `boolean` | `true` | Create a new Fortress user on first social login (JIT provisioning). |
+| `linkAccounts` | `boolean` | `true` | When a provider-verified social login email matches an active existing user, link the social identity to that user instead of creating a duplicate. |
+| `persistTokens` | `boolean` | `false` | Persist encrypted provider access/refresh tokens. **Off by default** — set to `true` only if you need server-side access to provider tokens (e.g. to call the provider's API after sign-in); requires `tokenEncryptionKey`. |
+| `tokenEncryptionKey` | `string` | required when `persistTokens` | 32-byte AES-256-GCM key (base64/base64url/hex/raw UTF-8) for provider token encryption. Hard requirement — the plugin throws at construction if `persistTokens` is enabled without one. |
+
+To call `getProviderTokens`, enable persistence explicitly:
+
+```typescript
+socialLogin({
+  persistTokens: true,
+  tokenEncryptionKey: process.env.FORTRESS_SOCIAL_TOKEN_KEY!,
+  providers: [/* ... */],
+})
+```
+| `mapProfile` | `(provider, profile) => { email, name }` | `undefined` | Custom mapping from provider profile to Fortress user fields during JIT provisioning. |
+| `onFirstLogin` | `(user, provider, profile) => Promise<void>` | `undefined` | Callback invoked once when a user is created via social login. Useful for assigning default roles, sending welcome emails, etc. |
+
+### ProviderConfig
+
+Each entry in `providers` has these fields:
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | Yes | Provider identifier. Use a built-in name (`google`, `github`, `microsoft`, `apple`, `discord`) or any string for custom OIDC. |
+| `clientId` | `string` | Yes | OAuth client ID from the provider. |
+| `clientSecret` | `string` | Yes | OAuth client secret from the provider. |
+| `scopes` | `string[]` | No | Override the default scopes for this provider. |
+| `tenant` | `string` | No | Microsoft only. Azure AD tenant: a tenant ID, `'common'`, or `'organizations'`. Defaults to `'common'`. |
+| `allowedDomains` | `string[]` | No | Restrict sign-in to specific email domains (e.g., `['acme.com']`). |
+| `issuer` | `string` | No | OIDC issuer URL for custom providers. Enables discovery of authorization, token, userinfo, and JWKS endpoints. |
+| `authorizationUrl` / `tokenUrl` / `userInfoUrl` / `jwksUri` | `string` | No | Endpoint overrides for custom OIDC providers. |
+| `teamId` / `keyId` / `privateKey` | `string` | Apple only | Apple ES256 client-secret JWT inputs. |
+
+## Usage
+
+### Setting Up Providers
+
+**Built-in providers** require only `name`, `clientId`, and `clientSecret`:
+
+```typescript
+socialLogin({
+  providers: [
+    { name: 'google', clientId: '...', clientSecret: '...' },
+    { name: 'github', clientId: '...', clientSecret: '...' },
+    { name: 'apple', clientId: '...', clientSecret: '...' },
+    { name: 'discord', clientId: '...', clientSecret: '...' },
+  ],
+})
+```
+
+**Custom OIDC providers** use the `issuer` field. Fortress constructs the standard OIDC endpoints from the issuer URL:
+
+```typescript
+socialLogin({
+  providers: [
+    {
+      name: 'okta',
+      clientId: '...',
+      clientSecret: '...',
+      issuer: 'https://dev-123456.okta.com',
+    },
+    {
+      name: 'keycloak',
+      clientId: '...',
+      clientSecret: '...',
+      issuer: 'https://auth.example.com/realms/my-realm',
+    },
+  ],
+})
+```
+
+### Authorization URL Generation
+
+Redirect the user to the provider's authorization page. The plugin generates a PKCE challenge, OAuth CSRF state, and OIDC nonce automatically.
+
+```typescript
+const { url, state, codeVerifier, nonce } = await fortress.plugins['social-login'].getAuthorizationUrl(
+  'google',
+  'https://myapp.com/auth/google/callback',
+);
+
+// Store these in the user's session (needed for callback verification)
+session.set('oauth_state', state);
+session.set('oauth_code_verifier', codeVerifier);
+session.set('oidc_nonce', nonce);
+
+// Redirect the user
+return redirect(url);
+```
+
+The returned values are:
+- `state` -- random OAuth CSRF token
+- `codeVerifier` -- PKCE code verifier (required for the callback)
+- `nonce` -- separate OIDC nonce verified against the provider ID token
+
+### Handling the Callback
+
+When the provider redirects back to your app, exchange the authorization code for tokens and resolve the user:
+
+```typescript
+app.get('/auth/google/callback', async (c) => {
+  const code = c.req.query('code');
+  const returnedState = c.req.query('state');
+  const storedState = session.get('oauth_state');
+  const codeVerifier = session.get('oauth_code_verifier');
+  const nonce = session.get('oidc_nonce');
+
+  const { user, profile, isNewUser } = await fortress.plugins['social-login'].handleCallback(
+    'google',
+    code,
+    'https://myapp.com/auth/google/callback', // must match the redirect URI used above
+    codeVerifier,
+    returnedState,
+    storedState,
+    nonce,
+  );
+
+  // Issue a Fortress session (JWT) for the user
+  const tokens = await fortress.auth.login({ email: user.email });
+
+  if (isNewUser) {
+    // First-time social login -- maybe redirect to onboarding
+  }
+
+  return c.json({ accessToken: tokens.accessToken, user });
+});
+```
+
+`handleCallback` returns:
+- `user` -- the Fortress user (existing or newly created)
+- `profile` -- normalized provider profile (`id`, `email`, `emailVerified`, `name`, `avatar`, `raw`)
+- `isNewUser` -- `true` if the user was created during this call (JIT provisioning)
+
+> The OIDC discovery, token-exchange, and userinfo calls run through a shared `@bajustone/fetcher` client with a request timeout (10 s; HIBP breach checks use 6 s), so a hung provider cannot stall the callback. Token responses are rejected if `access_token` is missing; discovery/userinfo responses must be JSON objects. Discovery falls back to the static provider definition on timeout/error.
+
+### JIT User Provisioning
+
+When `autoRegister` is `true` (the default) and no existing Fortress user matches the social identity, the plugin creates a new user automatically. The new user has `passwordHash: null`, marking them as a social-only account.
+
+To customize the user record created during provisioning, use `mapProfile`:
+
+```typescript
+socialLogin({
+  autoRegister: true,
+  mapProfile: (provider, profile) => ({
+    email: profile.email,
+    name: profile.displayName ?? profile.name ?? profile.email,
+  }),
+  providers: [/* ... */],
+})
+```
+
+To run logic after user creation (assign roles, send a welcome email), use `onFirstLogin`:
+
+```typescript
+socialLogin({
+  onFirstLogin: async (user, provider, profile) => {
+    await fortress.iam.assignRole(user.id, 'member');
+    await sendWelcomeEmail(profile.email, profile.name);
+  },
+  providers: [/* ... */],
+})
+```
+
+Set `autoRegister: false` to require users to exist before they can sign in via social login. The plugin will throw an `unauthorized` error if no matching user is found.
+
+### Account Linking
+
+When `linkAccounts` is `true` (the default) and a provider-verified social login email matches an active existing Fortress user, the social identity is linked to that user rather than creating a duplicate.
+
+This means a user who first registered with email/password and later signs in with Google (using the same verified email) will have their Google identity attached to their existing account. Unverified provider emails never trigger by-email linking.
+
+### Domain Restrictions
+
+Restrict sign-in to specific email domains per provider using `allowedDomains`. This is useful for corporate SSO where only company emails should be accepted:
+
+```typescript
+socialLogin({
+  providers: [
+    {
+      name: 'google',
+      clientId: '...',
+      clientSecret: '...',
+      allowedDomains: ['acme.com', 'acme.io'],
+    },
+  ],
+})
+```
+
+If a user attempts to sign in with an email outside the allowed domains, `handleCallback` throws an `unauthorized` error with the message `"Email domain 'gmail.com' is not allowed for google"`.
+
+### Managing Linked Accounts
+
+List all social identities linked to a user:
+
+```typescript
+const accounts = await fortress.plugins['social-login'].getLinkedAccounts(userId);
+// [
+//   { provider: 'google', providerAccountId: '1234567890', email: 'alice@acme.com' },
+//   { provider: 'github', providerAccountId: '987654', email: 'alice@acme.com' },
+// ]
+```
+
+Unlink a social identity from a user:
+
+```typescript
+await fortress.plugins['social-login'].unlinkAccount(userId, 'github');
+```
+
+List all configured providers:
+
+```typescript
+const providers = fortress.plugins['social-login'].getProviders();
+// ['google', 'github']
+```
+
+## Provider-Specific Notes
+
+### Google
+
+- Uses OpenID Connect. Default scopes: `openid`, `profile`, `email`.
+- Create credentials at [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
+- Profile fields: `sub` (id), `email`, `name`, `picture`.
+
+### GitHub
+
+- Uses custom OAuth 2.0 (not OIDC -- no discovery URL). Default scopes: `read:user`, `user:email`.
+- Create an OAuth App at [GitHub Developer Settings](https://github.com/settings/developers).
+- Profile fields: `id`, `email`, `name`/`login`, `avatar_url`.
+
+### Microsoft
+
+- Uses OpenID Connect via Azure AD. Default scopes: `openid`, `profile`, `email`, `User.Read`.
+- The `tenant` option controls which Azure AD tenant is used:
+  - `'common'` (default) -- any Microsoft account (personal + work/school).
+  - `'organizations'` -- work/school accounts only.
+  - A specific tenant ID -- restricts to a single Azure AD directory.
+
+```typescript
+{
+  name: 'microsoft',
+  clientId: '...',
+  clientSecret: '...',
+  tenant: 'your-azure-tenant-id',
+}
+```
+
+- Register your app at [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps).
+- Profile is fetched from Microsoft Graph (`/v1.0/me`). Avatar requires a separate Graph API call and is not included.
+
+### Apple
+
+- Uses OpenID Connect, but profile data comes from the ID token only (no userinfo endpoint).
+- Apple sends the user's name only on the **first** authorization. Subsequent logins provide only `sub` and `email`.
+- Default scopes: `name`, `email`.
+- Create a Service ID at [Apple Developer](https://developer.apple.com/account/resources/identifiers/list/serviceId).
+
+### Discord
+
+- Uses custom OAuth 2.0. Default scopes: `identify`, `email`.
+- Create an application at [Discord Developer Portal](https://discord.com/developers/applications).
+- Profile fields: `id`, `email`, `username`, `global_name`, `avatar`.
+
+## API Reference
+
+All methods are accessed via `fortress.plugins['social-login']`.
+
+| Method | Signature | Description |
+|---|---|---|
+| `getAuthorizationUrl` | `(providerName: string, redirectUri: string) => Promise<{ url: string; state: string; codeVerifier: string; nonce: string }>` | Generate the OAuth authorization URL. Store `state`, `codeVerifier`, and `nonce` in the user's session. |
+| `handleCallback` | `(providerName: string, code: string, redirectUri: string, codeVerifier: string, returnedState: string, storedState: string, storedNonce: string) => Promise<{ user: FortressUser; profile: ProviderProfile; isNewUser: boolean }>` | Timing-safe-verify OAuth state, verify OIDC ID-token signature/issuer/audience/expiry/nonce, fetch the profile, and resolve or create the Fortress user. |
+| `getLinkedAccounts` | `(userId: string) => Promise<{ provider: string; providerAccountId: string; email: string \| null }[]>` | List social identities linked to a user. |
+| `getProviderTokens` | `(userId: string, provider: string) => Promise<{ accessToken: string \| null; refreshToken: string \| null; tokenExpiresAt: Date \| null }>` | Return decrypted provider tokens for a linked account. |
+| `unlinkAccount` | `(userId: string, provider: string) => Promise<void>` | Remove a social identity from a user. |
+| `getProviders` | `() => string[]` | List the names of all configured providers. |
+
+### ProviderProfile
+
+The normalized profile returned by `handleCallback`:
+
+```typescript
+interface ProviderProfile {
+  id: string;             // Provider's unique user ID
+  email: string;
+  emailVerified: boolean;
+  name?: string;
+  displayName?: string;
+  avatar?: string;
+  raw: Record<string, unknown>; // Full raw response from the provider
+}
+```

package/docs/plugins/tenancy.md

@@ -0,0 +1,122 @@
+# Tenancy Plugin
+
+## Overview
+
+The `tenancy` plugin adds schema-per-tenant isolation for PostgreSQL. Each tenant gets its own schema named from its numeric database id (by default `tenant_<id>`), and request-scoped database operations run with that tenant schema on PostgreSQL's `search_path`.
+
+Tenant selection is derived from the verified JWT claim produced by `enrichTokenClaims`: `claims.customClaims.tenantId`. It is never read from client-supplied tenant context. A caller can therefore only get a tenant claim after being a member of that tenant via `tenant_user`.
+
+Isolation is transaction-pinned and fail-closed: each wrapped operation starts a transaction, calls `set_config('search_path', ?, true)` with a bound parameter on the pinned connection, then runs the operation. If there is no verified tenant claim, or the adapter is not PostgreSQL, the adapter is returned unchanged. Business tables should live only in tenant schemas, so missing tenant context fails by not finding those tables rather than silently reading another tenant.
+
+This plugin is PostgreSQL-specific. For database-agnostic row-level isolation, see [Data Isolation](./data-isolation.md).
+
+## Service accounts and tenancy
+
+Service accounts have no `tenant_user` membership, so `enrichTokenClaims` does not add a tenant claim for them and the tenancy adapter wrapper does not switch schemas. That is intentional fail-closed behavior.
+
+Tenant-scoped *permissions* for service accounts are unaffected. IAM still resolves grants through `role_binding.tenantId` when you pass an explicit `tenantId` to `fortress.iam.checkPermission(...)`; this is separate from schema switching and does not rely on any tenant header.
+
+## Installation
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { tenancy } from '@bajustone/fortress/plugins/tenancy';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    tenancy({
+      schemaPrefix: 'tenant_',
+      routes: false,
+      onSchemaCreated: async (schemaName, rawQuery) => {
+        await rawQuery(`CREATE TABLE IF NOT EXISTS ${schemaName}.widgets (id SERIAL PRIMARY KEY)`);
+      },
+      dropSchemaOnDelete: false,
+    }),
+  ],
+});
+```
+
+Programmatic methods are always available at `fortress.plugins.tenancy`. HTTP routes are mounted only when `routes: true`.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `schemaPrefix` | `string` | `'tenant_'` | Prefix for tenant schemas. Must match `^[a-z_][a-z0-9_]*$`. Full schema name is `${schemaPrefix}${tenant.id}`. |
+| `routes` | `boolean` | `false` | Mount opt-in HTTP routes under `/tenancy/*`. |
+| `onSchemaCreated` | `(schemaName, rawQuery) => Promise<void>` | `undefined` | Runs inside the `createTenant` transaction after `CREATE SCHEMA`. Use for per-tenant DDL/migrations. |
+| `dropSchemaOnDelete` | `boolean` | `false` | When `true`, `deleteTenant` drops the tenant schema with `CASCADE`. |
+
+## HTTP Routes
+
+Enable with `tenancy({ routes: true })`.
+
+| Method | Path | Handler | Auth |
+|---|---|---|---|
+| `POST` | `/tenancy/tenants` | `createTenant` | Bearer + `fortress:manageTenants` |
+| `DELETE` | `/tenancy/tenants/:id` | `deleteTenant` | Bearer + `fortress:manageTenants` |
+| `GET` | `/tenancy/tenants/mine` | `getMyTenants` | Bearer; caller derived from token |
+| `POST` | `/tenancy/switch` | `switchTenant` | Bearer; caller derived from token |
+
+Self-service routes ignore any `userId` in the body when a route context is present.
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `createTenant` | `({ name, taxId, description? })` | `Promise<TenantRecord>` |
+| `deleteTenant` | `({ id })` | `Promise<{ ok: true }>` |
+| `addUserToTenant` | `(userId, tenantId)` | `Promise<void>` |
+| `getUserTenants` | `(userId)` | `Promise<TenantRecord[]>` |
+| `getMyTenants` | `({ userId? }, routeCtx?)` | `Promise<{ tenants: TenantRecord[] }>` |
+| `switchTenant` | `({ taxId, userId? }, routeCtx?)` | `Promise<{ ok: true }>` |
+
+### createTenant
+
+Creates the tenant row and, on PostgreSQL, schema `tenant_<id>` (or your configured prefix) in one transaction:
+
+```ts
+const tenant = await fortress.plugins.tenancy.createTenant({
+  name: 'Acme Corp',
+  taxId: 'acme-corp', // unique external code; not used in schema names
+});
+```
+
+### deleteTenant
+
+Removes tenant memberships and the tenant row. The schema is only dropped when `dropSchemaOnDelete: true`.
+
+```ts
+await fortress.plugins.tenancy.deleteTenant({ id: tenant.id });
+```
+
+### switchTenant
+
+Sets the user's default tenant after verifying membership. The flip is serialized and performed as a two-phase update inside one transaction (clear, then set), while a partial unique index enforces at most one default membership per user. The new tenant takes effect on the next login/token refresh because tenant data is stored in JWT custom claims.
+
+```ts
+await fortress.plugins.tenancy.switchTenant({ taxId: 'acme-corp', userId });
+```
+
+## Migration notes for pre-hardening schemas
+
+Older experimental builds derived schema names from tenant codes/tax IDs (for example `tenant_acme-001`) and trusted `X-Tenant-Code` as request context. Hardened Fortress no longer reads that header and no longer uses tax IDs in SQL identifiers.
+
+For existing deployments:
+
+1. For every row in `fortress_tenant`, compute the hardened schema name as `${schemaPrefix}${tenant.id}` (default: `tenant_<numeric id>`).
+2. Rename each old tenant schema to the hardened name, or recreate it and copy data:
+   ```sql
+   ALTER SCHEMA old_schema_name RENAME TO tenant_123;
+   ```
+3. Ensure all tenant business tables live only in tenant schemas, not `public`, so missing tenant context fails closed.
+4. Remove any app code that forwards or depends on `X-Tenant-Code`.
+5. Have users log in or refresh tokens after `switchTenant`; the active tenant comes from `claims.customClaims.tenantId`.
+
+No Fortress-owned table shape changes are required beyond the normal migration catalog/version checks.
+
+## JWT staleness tradeoff
+
+Tenant access is encoded in short-lived JWT access tokens. If a user is removed from a tenant, an already-issued token can retain its old `tenantId` claim until it expires or is refreshed. Keep access-token lifetimes short and force session/token revocation for immediate removal.

package/docs/plugins/two-factor.md

@@ -0,0 +1,191 @@
+# Two-Factor Authentication Plugin
+
+TOTP-based two-factor authentication with backup codes and trusted devices.
+
+## Installation
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { twoFactor } from '@bajustone/fortress/plugins/two-factor';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes-long' },
+  database: yourAdapter,
+  plugins: [
+    twoFactor({
+      secretEncryptionKey: process.env.FORTRESS_TOTP_ENCRYPTION_KEY!,
+      totp: { issuer: 'MyApp' },
+    }),
+  ],
+} as const);
+```
+
+The plugin registers three database models automatically: `two_factor_secret`, `backup_code`, and `trusted_device`.
+
+## Configuration
+
+Pass a `TwoFactorConfig` object to `twoFactor()`. `secretEncryptionKey` is required; all other options are optional.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `secretEncryptionKey` | `string` | required | Exactly 32 bytes (raw UTF-8, hex, base64, or base64url) used for AES-256-GCM encryption of TOTP seeds |
+| `totp.issuer` | `string` | `'Fortress'` | Issuer name displayed in authenticator apps (Google Authenticator, Authy, etc.) |
+| `totp.period` | `number` | `30` | TOTP time step in seconds |
+| `totp.digits` | `number` | `6` | Number of digits in the TOTP code |
+| `backupCodes.count` | `number` | `10` | Number of backup codes generated on enable |
+| `trustedDeviceDays` | `number` | `30` | Days a device stays trusted after successful 2FA verification |
+
+```ts
+twoFactor({
+  secretEncryptionKey: process.env.FORTRESS_TOTP_ENCRYPTION_KEY!,
+  totp: {
+    issuer: 'MyApp',
+    period: 30,
+    digits: 6,
+  },
+  backupCodes: { count: 10 },
+  trustedDeviceDays: 30,
+})
+```
+
+## Usage
+
+Access the plugin methods via the type-safe `fortress.plugins['two-factor']` accessor.
+
+```ts
+const tf = fortress.plugins['two-factor'];
+```
+
+### Enable 2FA
+
+Call `enable` to generate a TOTP secret and backup codes. The user must verify a code before 2FA is activated. Only an AES-256-GCM ciphertext is stored; `isEnabled` stays `false` until the first successful `verify`.
+
+Keep the encryption key in a secrets manager, separate from the database, and back it up. Losing or changing it makes existing seeds undecryptable and requires re-enrolment. Migration `0009_encrypt_totp_secrets` deletes legacy plaintext enrolments and associated recovery/trusted-device records so an upgrade cannot leave usable plaintext seeds behind.
+
+```ts
+const setup = await fortress.plugins['two-factor'].enable(userId);
+
+// setup.secret     — base32-encoded TOTP secret (store nowhere; show once)
+// setup.otpauthUrl — otpauth:// URI for QR code generation
+// setup.backupCodes — array of one-time backup codes (show once, user saves them)
+```
+
+Show the QR code to the user using any QR library:
+
+```ts
+import QRCode from 'qrcode';
+
+const qrDataUrl = await QRCode.toDataURL(setup.otpauthUrl);
+// Render qrDataUrl as an <img> for the user to scan with their authenticator app
+```
+
+Display the backup codes and instruct the user to store them securely. These are the only time the raw codes are available.
+
+### Confirm setup and complete challenges
+
+After `enable`, activate the secret with `confirmSetup(userId, code)`. This setup-only method returns `{ verified: true, trustedDeviceToken? }` and does not issue a session. Device enrollment is explicit:
+
+```ts
+const confirmation = await fortress.plugins['two-factor'].confirmSetup(
+  userId,
+  '123456',
+  { rememberDevice: true },
+);
+// If present, put confirmation.trustedDeviceToken in a host-managed
+// Secure, HttpOnly, SameSite cookie. Fortress stores only its hash.
+```
+
+During login, call `verify` with the pending continuation token and a TOTP or backup code. It returns the unified `AuthResult` and issues tokens only when every configured gate is complete.
+
+```ts
+const result = await fortress.plugins['two-factor'].verify(
+  loginResult.pending.continuationToken,
+  code,
+  { rememberDevice: true },
+);
+```
+
+The equivalent HTTP endpoint is `POST /auth/2fa/verify` with `{ continuationToken, code, rememberDevice?: boolean }`. A successful opted-in response carries the raw token once in `pluginData.trustedDeviceToken`.
+
+### Disable 2FA
+
+Removes the TOTP secret, all backup codes, and all trusted devices for the user.
+
+```ts
+await fortress.plugins['two-factor'].disable(userId);
+```
+
+After disabling, the user can call `enable` again to set up fresh 2FA.
+
+### Login flow with the post-auth gate
+
+When a user with enabled 2FA logs in, Fortress checks trusted-device state before token issuance. An untrusted login returns an `AuthPending` with a required challenge and **no token fields**.
+
+```ts
+const loginResult = await fortress.auth.login(email, password, {
+  trustedDeviceToken: readTrustedDeviceCookie(request),
+});
+
+if (loginResult.status === 'pending' && loginResult.pending.reason === 'two-factor') {
+  const completed = await fortress.plugins['two-factor'].verify(
+    loginResult.pending.continuationToken,
+    codeFromUser,
+    { rememberDevice: shouldRememberDevice },
+  );
+
+  if (completed.status === 'success') {
+    // completed.accessToken and completed.refreshToken are the issued session.
+  }
+}
+```
+
+### Trusted Devices
+
+Trusted-device enrollment occurs only when `rememberDevice: true` is supplied to `confirmSetup` or `verify`. Fortress generates a high-entropy opaque token, returns it once, and stores only its SHA-256 hash. User-Agent is metadata only and is never a trust credential.
+
+The host must store the raw token in a `Secure`, `HttpOnly`, appropriately scoped `SameSite` cookie and pass it as `RequestMeta.trustedDeviceToken` on later programmatic logins. The HTTP login endpoint accepts the same opaque value as optional `trustedDeviceToken`; the host adapter is responsible for copying its cookie into that field.
+
+- Trust expires after `trustedDeviceDays` (default 30).
+- `lastUsedAt` is updated whenever a valid token is recognized.
+- Calling `disable` removes all trusted devices for the user.
+- Never expose the token to JavaScript-readable storage.
+
+## API Reference
+
+All methods are accessed via `fortress.plugins['two-factor']`.
+
+| Method | Signature | Description |
+|---|---|---|
+| `enable` | `(userId: string) => Promise<{ secret: string; otpauthUrl: string; backupCodes: string[] }>` | Generate an unconfirmed TOTP secret and backup codes. Throws if 2FA is already enabled. |
+| `confirmSetup` | `(userId: string, code: string, meta?: RequestMeta) => Promise<{ verified: true; trustedDeviceToken?: string }>` | Verify the first TOTP code, activate setup, and optionally enroll a trusted device. |
+| `verify` | `(continuationToken: string, code: string, meta?: RequestMeta) => Promise<AuthResult>` | Complete a pending login with TOTP or a single-use backup code, rerun remaining gates, and issue the session on success. |
+| `disable` | `(userId: string) => Promise<void>` | Remove all 2FA data (secret, backup codes, trusted devices) for the user. |
+
+The plugin also installs a `postAuthGate` hook. This is not called directly -- it runs automatically on every `fortress.auth.login()` call.
+
+## How It Works
+
+### TOTP (RFC 6238)
+
+The implementation follows RFC 6238 (TOTP) built on RFC 4226 (HOTP):
+
+1. A 20-byte random secret is generated and base32-encoded.
+2. The current Unix timestamp is divided by the `period` (default 30s) to produce a counter.
+3. The counter is HMAC-SHA1 signed with the secret.
+4. Dynamic truncation extracts a 6-digit code from the HMAC result.
+5. Verification checks the current time window plus one window before and after (+-30s) to tolerate clock drift.
+
+The `otpauthUrl` is a standard `otpauth://totp/` URI that authenticator apps (Google Authenticator, Authy, 1Password, etc.) can scan via QR code.
+
+### Backup Codes
+
+- Generated as 8-character hex strings (4 random bytes each).
+- Only SHA-256 hashes are stored in the database; raw codes are returned once from `enable`.
+- Each backup code can be used exactly once. After use, the record is marked `isUsed: true`.
+- All backup codes are deleted when 2FA is disabled.
+
+### Trusted Device Hashing
+
+- The device fingerprint is `SHA-256(userId + ":" + userAgent)`.
+- This is a convenience mechanism, not a strong device binding. User-Agent strings can be spoofed.
+- Expired trusted device records are not automatically cleaned up. They are simply ignored when their `expiresAt` is in the past.