@vsaas/loopback 12.1.1 → 12.2.0

package/docs/two-factor-authentication.md

@@ -0,0 +1,611 @@
+# Two-factor authentication
+
+LoopBack can add TOTP and single-use recovery-code authentication to a concrete `User` model. The implementation protects enrollment, login challenges, recovery codes, token issuance, and authentication-specific rate limits with durable private state.
+
+Two-factor authentication is opt-in per concrete `User` model. Existing models keep their legacy login behavior until a `twoFactor` setting is present.
+
+## Required models and initialization
+
+Attach the following private models to a durable datasource:
+
+- `TwoFactorCredential`
+- `TwoFactorChallenge`
+- `TwoFactorRecoveryCode`
+- `RateLimitState` when `authenticationRateLimit.enabled` is `true`
+
+Do not expose these models through REST. The credential store requires a physical unique constraint over `principalType`, `principalId`, and `provider`; model metadata alone does not replace the database constraint.
+
+After all models and datasources have been attached, initialize authentication security before accepting traffic:
+
+```js
+await app.initializeAuthenticationSecurity();
+```
+
+The initializer validates every concrete `User` model, registers its private stores and keyrings, initializes general rate limiting, checks model capabilities, and installs the authentication hooks. It supports promises and callbacks and is idempotent.
+
+LoopBack also calls `initializeAuthenticationSecurity()` automatically once the application emits `booted`; an initialization failure is reported through the `authenticationSecurityError` application event and does not crash the server. The explicit call above is for custom boot flows that must await readiness before listening, and for tests.
+
+The current state is exposed as `app.authenticationSecurityReadiness` (`{ ready, error }`). Custom endpoints that depend on two-factor state can guard themselves with `app.assertAuthenticationSecurityReady(UserModel)`, which throws `AUTHENTICATION_SECURITY_UNAVAILABLE` when the model requires security that has not finished initializing.
+
+Do not call `initializeRateLimiting()` first when authentication security is configured. `initializeAuthenticationSecurity()` owns the complete startup sequence. Configured authentication endpoints fail closed with `AUTHENTICATION_SECURITY_UNAVAILABLE` until initialization succeeds.
+
+## Basic configuration
+
+Settings belong to the concrete model:
+
+```js
+SecureUser.settings.twoFactor = {
+  mode: 'enroll-and-verify',
+  issuer: 'Xompass',
+  challengeTtl: 300,
+  verificationLeaseTtl: 30,
+  enrollmentTtl: 600,
+  maxAttempts: 5,
+  maxClockSkewSteps: 1,
+  totp: {
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secretBytes: 20,
+  },
+  recoveryCodeCount: 10,
+  recoveryCodeBytes: 16,
+  loginContextMaxBytes: 8192,
+  sessions: {
+    onEnable: 'revoke-others',
+    onDisable: 'revoke-all',
+    onRecoveryCodesRegenerated: 'revoke-others',
+  },
+  encryption: {
+    currentKeyId: '2026-01',
+    keys: {
+      '2026-01': process.env.TWO_FACTOR_ENCRYPTION_KEY,
+    },
+  },
+  recoveryCodeHmac: {
+    currentKeyId: '2026-01',
+    keys: {
+      '2026-01': process.env.TWO_FACTOR_RECOVERY_HMAC_KEY,
+    },
+  },
+  principalBindingHmac: {
+    currentKeyId: '2026-01',
+    keys: {
+      '2026-01': process.env.TWO_FACTOR_BINDING_HMAC_KEY,
+    },
+  },
+};
+```
+
+Load key material through the application's normal configuration and secret-management layer. Do not commit it to model files.
+
+## Operating modes
+
+| Mode                | Login behavior                                                                                  | Management behavior                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `disabled`          | Does not require a second factor. Startup fails if enabled credentials already exist.           | Enrollment and credential-management operations are unavailable.                              |
+| `verify-only`       | Existing enabled credentials are enforced.                                                      | New enrollment is disabled; verification and existing-credential operations remain available. |
+| `enroll-and-verify` | Existing enabled credentials are enforced. Users without an enabled credential log in normally. | Full enrollment and credential management are available.                                      |
+
+If the complete `twoFactor` setting is absent, the model retains legacy behavior and its two-factor remote methods are disabled.
+
+Use `verify-only` as the rollback mode when verification must remain enforced but new enrollment should stop. Do not switch to `disabled` while enabled credentials exist.
+
+In `disabled` mode, the remaining two-factor options are not used or validated. This makes it suitable for installing schemas and code before provisioning production keyrings, but not for bypassing credentials that have already been enabled.
+
+## Two-factor options
+
+All public duration values in `twoFactor` are in **seconds**.
+
+### General and lifecycle options
+
+| Option                 |    Default | Valid values                                   | Description                                                                                                          |
+| ---------------------- | ---------: | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `mode`                 | `disabled` | `disabled`, `verify-only`, `enroll-and-verify` | Enables verification and/or enrollment for the model.                                                                |
+| `issuer`               |          — | Non-empty string                               | Issuer included in the TOTP URI and authenticator label. Required in active modes.                                   |
+| `challengeTtl`         |      `300` | `60`–`600`                                     | Lifetime of an external login challenge.                                                                             |
+| `verificationLeaseTtl` |       `30` | `1` to `challengeTtl - 1`                      | Short lease used while one worker verifies and consumes a challenge.                                                 |
+| `enrollmentTtl`        |      `600` | `60`–`3600`                                    | Lifetime of an unconfirmed enrollment.                                                                               |
+| `maxAttempts`          |        `5` | `1`–`10`                                       | Maximum invalid-code attempts for an external login challenge.                                                       |
+| `maxClockSkewSteps`    |        `1` | `0`–`2`                                        | Number of adjacent TOTP time steps accepted on each side of the current step.                                        |
+| `recoveryCodeCount`    |       `10` | `1`–`32`                                       | Number of recovery codes issued on enable or regeneration.                                                           |
+| `recoveryCodeBytes`    |       `16` | `10`–`32`                                      | Random bytes used to generate each recovery code. This controls entropy, not the displayed character count directly. |
+| `loginContextMaxBytes` |     `8192` | `256`–`65536`                                  | Maximum serialized encrypted login context stored with a challenge.                                                  |
+
+Increasing clock skew improves tolerance of incorrectly synchronized devices but expands the code-validity window. Keep server clocks synchronized and use the smallest value compatible with clients.
+
+### TOTP options
+
+| Option             | Default | Valid values       | Description                                                                                                              |
+| ------------------ | ------: | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `totp.algorithm`   |  `SHA1` | `SHA1`, `SHA256`   | HMAC algorithm advertised in the TOTP URI and used for verification. Confirm client-app support before choosing SHA-256. |
+| `totp.digits`      |     `6` | `6`, `8`           | Number of digits in each TOTP code.                                                                                      |
+| `totp.period`      |    `30` | `15`–`120` seconds | Duration of each TOTP step.                                                                                              |
+| `totp.secretBytes` |    `20` | `20`–`64`          | Entropy used for a new TOTP secret.                                                                                      |
+
+Changing TOTP algorithm, digits, or period does not transparently migrate already enrolled authenticators. Plan re-enrollment before changing these options for existing users.
+
+### Session-revocation options
+
+```js
+sessions: {
+  onEnable: 'revoke-others',
+  onDisable: 'revoke-all',
+  onRecoveryCodesRegenerated: 'revoke-others',
+}
+```
+
+Each option accepts `revoke-all` or `revoke-others`.
+
+| Option                                | Default         | Description                                                       |
+| ------------------------------------- | --------------- | ----------------------------------------------------------------- |
+| `sessions.onEnable`                   | `revoke-others` | Token-revocation policy after enabling two-factor authentication. |
+| `sessions.onDisable`                  | `revoke-all`    | Token-revocation policy after disabling it.                       |
+| `sessions.onRecoveryCodesRegenerated` | `revoke-others` | Token-revocation policy after replacing recovery codes.           |
+
+`revoke-others` preserves the authenticated token used for the management operation when that token is available. `revoke-all` also revokes the current token.
+
+### Cryptographic keyrings
+
+Three independent keyrings protect different data:
+
+| Keyring                | Key requirement           | Purpose                                                                                     |
+| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
+| `encryption`           | Exactly 32 decoded bytes  | AES-256-GCM encryption for TOTP secrets and protected challenge context.                    |
+| `recoveryCodeHmac`     | At least 32 decoded bytes | One-way identifiers for recovery codes. Plain recovery codes are returned only when issued. |
+| `principalBindingHmac` | At least 32 decoded bytes | Binds a login challenge to the principal's current authentication material.                 |
+
+Each keyring has:
+
+| Option         | Description                                                                          |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `currentKeyId` | Key used for newly created state. It must exist in `keys`.                           |
+| `keys.<keyId>` | Base64-encoded secret. Retained keys can read or verify older state during rotation. |
+
+Key IDs may contain letters, digits, `.`, `_`, and `-`, up to 64 characters. Recovery-code and principal-binding keys must be cryptographically distinct. Use independent random keys in every environment.
+
+By default, principal binding uses the user's password hash. A password change therefore invalidates outstanding two-factor login challenges.
+
+## Login behavior
+
+A user without an enabled two-factor credential receives the normal access token after valid primary credentials.
+
+A user with an enabled credential has two supported flows.
+
+### Inline verification
+
+Include the method and code with normal login credentials:
+
+```json
+{
+  "email": "user@example.com",
+  "password": "correct horse battery staple",
+  "twoFactorMethod": "totp",
+  "twoFactorCode": "123456"
+}
+```
+
+`twoFactorMethod` accepts `totp` or `recovery`; when omitted it defaults to `totp`. A valid code completes login and returns the access token in the normal response. TOTP verification records the last used time-step counter per credential with a compare-and-swap update, so replaying a captured code is rejected even while the code is still within its validity window.
+
+### External challenge
+
+When valid primary credentials are submitted without a second-factor code, login responds with:
+
+```json
+{
+  "error": {
+    "statusCode": 403,
+    "code": "TWO_FACTOR_REQUIRED",
+    "details": {
+      "challengeId": "...",
+      "methods": ["totp", "recovery"],
+      "expiresIn": 300
+    }
+  }
+}
+```
+
+Complete the challenge through `POST /Users/two-factor/verify`:
+
+```json
+{
+  "challengeId": "...",
+  "method": "totp",
+  "code": "123456"
+}
+```
+
+`methods` reflects the second factors currently available to the user: only
+`["totp"]` while no recovery-code set is active, and `["totp", "recovery"]`
+otherwise. Clients should render the offered methods from this field instead
+of assuming both are always present.
+
+The challenge stores a bounded encrypted login context so successful verification can issue the same kind of token the original login requested. Challenge consumption and recovery-code consumption use compare-and-swap state transitions to prevent replay under concurrency.
+
+The `User.createAccessToken` override supports both `(ttl, callback)` and `(ttl, options, callback)`. Existing login options such as relation inclusion are preserved through the two-factor flow.
+
+### Challenge lifecycle
+
+Every challenge moves through a small durable state machine. The states are useful for monitoring queries and support investigations; the service enforces the transitions with compare-and-swap updates so concurrent verifications cannot double-consume a challenge.
+
+| Status                    | Terminal | Meaning                                                                                              |
+| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `pending`                 | No       | Created after valid primary credentials; awaiting second-factor verification.                         |
+| `verifying`               | No       | A worker holds the short verification lease while it validates the code.                              |
+| `consuming`               | No       | The code was accepted; token issuance and revocation of prior sessions are in progress.               |
+| `consumed`                | Yes      | Verification completed and the access token was issued.                                              |
+| `expired`                 | Yes      | `challengeTtl` elapsed without successful verification.                                               |
+| `locked`                  | Yes      | `maxAttempts` invalid codes were submitted.                                                           |
+| `reconciling_no_token`    | No       | A verification lease expired mid-verification; cleanup releases reservations and re-arms or expires the challenge. |
+| `token_revocation_pending`| Yes      | Consumption was interrupted before token revocation could be confirmed; cleanup quarantines these.   |
+| `token_failed`            | Yes      | A quarantined token was confirmed revoked by cleanup; operator reconciliation is complete.           |
+
+The non-terminal states are transient and self-healing. Alert on challenges that remain in `token_revocation_pending`, since those require operator reconciliation (see [Audit and monitoring](#audit-and-monitoring) and the cleanup section below).
+
+## Enrollment and management
+
+Management endpoints require an authenticated access token, and the service verifies that the token belongs to the target principal. Setup, recovery-code regeneration, and disablement additionally require the current password for reauthentication. Confirmation is the exception: it relies on possession of the pending `enrollmentId` together with a valid authenticator code inside the enrollment lifetime, because proving control of the authenticator at this step is itself the strongest signal.
+
+### Start enrollment
+
+`POST /Users/two-factor/setup`
+
+```json
+{
+  "currentPassword": "correct horse battery staple"
+}
+```
+
+The response contains `enrollmentId`, `secret`, `keyUri`, and `expiresIn`. The plaintext secret is returned only here.
+
+### Confirm enrollment
+
+`POST /Users/two-factor/confirm`
+
+```json
+{
+  "enrollmentId": "...",
+  "code": "123456"
+}
+```
+
+Successful confirmation enables the credential and returns the initial recovery-code set once. Store or display those codes securely; the server cannot recover their plaintext later.
+
+### Regenerate recovery codes
+
+`POST /Users/two-factor/recovery-codes`
+
+```json
+{
+  "currentPassword": "correct horse battery staple",
+  "method": "totp",
+  "code": "123456"
+}
+```
+
+This invalidates the previous set and returns the replacement codes once.
+
+### Disable two-factor authentication
+
+`POST /Users/two-factor/disable`
+
+```json
+{
+  "currentPassword": "correct horse battery staple",
+  "method": "totp",
+  "code": "123456"
+}
+```
+
+The session policy in `sessions.onDisable` is applied after the credential is disabled.
+
+Sensitive success and error responses use `Cache-Control: no-store`.
+
+## Authentication rate limiting
+
+Authentication rate limiting is independent of two-factor mode and is configured per concrete `User` model:
+
+```js
+SecureUser.settings.authenticationRateLimit = {
+  enabled: true,
+  store: 'authentication',
+  subjectHash: {
+    currentKeyId: '2026-01',
+    keys: {
+      '2026-01': process.env.AUTH_RATE_LIMIT_SUBJECT_KEY,
+    },
+  },
+  retryAfterGranularity: 30,
+  stateTtl: 604800,
+  policies: {
+    password: {
+      policyId: 'authentication-password',
+      policyVersion: '1',
+      maxFailedAttempts: 5,
+      observationWindow: 900,
+      blockDuration: 60,
+      strategy: 'exponential',
+      multiplier: 2,
+      maxBlockDuration: 3600,
+      backoffResetAfter: 86400,
+    },
+    secondFactor: {
+      maxFailedAttempts: 5,
+      observationWindow: 300,
+      blockDuration: 30,
+      strategy: 'exponential',
+      multiplier: 2,
+      maxBlockDuration: 900,
+      backoffResetAfter: 86400,
+    },
+    management: {
+      maxFailedAttempts: 3,
+      observationWindow: 600,
+      blockDuration: 300,
+      strategy: 'fixed',
+      maxBlockDuration: 300,
+      backoffResetAfter: 86400,
+    },
+    challengeIssuance: {
+      maxAttempts: 10,
+      observationWindow: 300,
+      blockDuration: 300,
+    },
+  },
+  source: {
+    enabled: true,
+    login: {
+      maxAttempts: 100,
+      observationWindow: 60,
+      blockDuration: 60,
+    },
+    secondFactor: {
+      maxAttempts: 60,
+      observationWindow: 60,
+      blockDuration: 60,
+    },
+  },
+};
+```
+
+All durations in `authenticationRateLimit` are in **seconds**.
+
+### Top-level authentication options
+
+| Option                  |         Default | Description                                                                                                               |
+| ----------------------- | --------------: | ------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`               |         `false` | Only the literal value `true` enables authentication rate limiting.                                                       |
+| `store`                 |               — | Name of an application `rateLimit.stores` entry, or an inline store definition. The resolved store must have a namespace. |
+| `subjectHash`           |               — | HMAC keyring used to pseudonymize users, unknown identifiers, and sources. Keys require at least 32 decoded bytes.        |
+| `retryAfterGranularity` |            `30` | `Retry-After` rounding granularity, from 1 to 3600 seconds.                                                               |
+| `stateTtl`              |        `604800` | Default state TTL, from 1 second to 365 days. It must cover every observation, maximum block, and backoff-reset duration. |
+| `policies`              | Built-in values | Per-bucket policy overrides.                                                                                              |
+| `source`                |         Enabled | Source-volume policies that complement per-principal or per-identifier policies.                                          |
+
+An inline store accepts the same persisted-model provider options documented in [Rate limiting](./rate-limiting.md#stores). A named store reuses the application-level provider and namespace. Use a named store for the optional [Redis component](https://github.com/vsaas/loopback-monorepo/tree/main/loopback-component-rate-limit-redis#two-factor-authentication); inline authentication stores support only the built-in `persisted-model` provider.
+
+```js
+store: {
+  provider: 'persisted-model',
+  model: 'RateLimitState',
+  namespace: 'cloud-api-production-authentication',
+  maxRetries: 20,
+}
+```
+
+Startup fails if the resolved store model uses the built-in memory connector
+and the definition does not set `allowMemory: true`. Like every memory-backed
+rate-limit store, that opt-in is intended for tests and single-instance
+development; authentication lockout state must be shared across instances.
+
+The bucket determines the algorithm. `password`, `secondFactor`, and `management` are failure lockouts; `challengeIssuance` is a fixed-window volume limit. Do not add an `algorithm` option to these policy objects.
+
+### Failure-lockout policy options
+
+| Option              | Description                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| `policyId`          | Stable policy identity. A bucket-specific default is provided. |
+| `policyVersion`     | Policy revision, default `1`. Change it with semantic changes. |
+| `maxFailedAttempts` | Failure capacity, from 1 to 100.                               |
+| `observationWindow` | Failure observation window in seconds.                         |
+| `blockDuration`     | Initial block duration in seconds.                             |
+| `strategy`          | `fixed` or `exponential`.                                      |
+| `multiplier`        | Exponential multiplier, from 1 to 10.                          |
+| `maxBlockDuration`  | Maximum block duration in seconds.                             |
+| `backoffResetAfter` | Quiet or success period that resets escalation, in seconds.    |
+| `stateTtl`          | Optional per-policy TTL override.                              |
+
+Defaults:
+
+| Bucket         | Attempts | Observation | Initial block | Strategy       | Maximum block | Reset after |
+| -------------- | -------: | ----------: | ------------: | -------------- | ------------: | ----------: |
+| `password`     |      `5` |       `900` |          `60` | exponential ×2 |        `3600` |     `86400` |
+| `secondFactor` |      `5` |       `300` |          `30` | exponential ×2 |         `900` |     `86400` |
+| `management`   |      `3` |       `600` |         `300` | fixed          |         `300` |     `86400` |
+
+Password failures for a known user consume the principal bucket. Unknown usernames or email addresses consume a pseudonymized identifier bucket so account enumeration does not create state keyed by plaintext identifiers. A successful login resets only the failure state it safely observed; a concurrent newer failure is not erased.
+
+### Fixed-window policy options
+
+`challengeIssuance` and source-volume policies accept:
+
+| Option              | Description                       |
+| ------------------- | --------------------------------- |
+| `policyId`          | Stable policy identity.           |
+| `policyVersion`     | Revision, default `1`.            |
+| `maxAttempts`       | Capacity, from 1 to 100000.       |
+| `observationWindow` | Window duration in seconds.       |
+| `blockDuration`     | Block duration in seconds.        |
+| `stateTtl`          | Optional per-policy TTL override. |
+
+The default challenge-issuance policy allows 10 challenges per 300 seconds and blocks for 300 seconds.
+
+### Source policies
+
+Source limits provide an additional volume boundary across many user identifiers:
+
+| Option                | Default                                    | Description                                     |
+| --------------------- | ------------------------------------------ | ----------------------------------------------- |
+| `source.enabled`      | `true`                                     | Enables source buckets.                         |
+| `source.login`        | 100 attempts / 60 seconds, 60-second block | Applies to primary login activity.              |
+| `source.secondFactor` | 60 attempts / 60 seconds, 60-second block  | Applies to second-factor verification activity. |
+
+The default source resolver uses `options.authenticationSource`, then the request IP or remote socket address. If it returns `null`, no source bucket is applied. Ensure the application derives client addresses only from trusted proxy configuration; otherwise a caller may spoof the source or all callers may collapse into a proxy address.
+
+Authentication rate-limit store failures always return `AUTHENTICATION_RATE_LIMIT_UNAVAILABLE`; credentials are not evaluated without the required state.
+
+## Model hooks
+
+Applications can customize identity and login integration through these hooks. Each supports callbacks or promises.
+
+### `getTwoFactorPrincipalBindingMaterial(user, options, callback)`
+
+Returns the authentication material used to bind challenges to the principal. The default is the current password hash. Override it when primary authentication is external or passwordless.
+
+The returned material must change when primary credentials are revoked or replaced.
+
+### `validateTwoFactorLoginPrincipal(user, options, callback)`
+
+Performs application-specific checks after the user is resolved and before a challenge or token is issued. The default allows the principal. Override it to reject disabled, locked, deleted, or otherwise ineligible accounts.
+
+### `buildTwoFactorLoginContext(credentials, options, callback)`
+
+Builds the serializable context stored with an external challenge. The default preserves supported token-creation options. Keep custom context minimal, free of secrets, and within `loginContextMaxBytes`; it is encrypted but still security-sensitive persisted state.
+
+### `resolveAuthenticationRateLimitSource(options, callback)`
+
+Returns the canonical source used by source-volume limits. Override it when the deployment uses a trusted gateway, device identity, or another application-specific source signal.
+
+## Errors
+
+| Code                                    | HTTP status | Meaning                                                                              |
+| --------------------------------------- | ----------: | ------------------------------------------------------------------------------------ |
+| `TWO_FACTOR_REQUIRED`                   |       `403` | Primary credentials are valid and a second factor is required.                       |
+| `INVALID_TWO_FACTOR_CHALLENGE`          |       `401` | Challenge is invalid, expired, consumed, or no longer bound to the principal.        |
+| `INVALID_TWO_FACTOR_CODE`               |       `401` | TOTP or recovery code is invalid.                                                    |
+| `AUTHENTICATION_RATE_LIMITED`           |       `429` | An authentication bucket is blocked.                                                 |
+| `AUTHENTICATION_RATE_LIMIT_UNAVAILABLE` |       `503` | Required authentication rate-limit state is unavailable.                             |
+| `AUTHENTICATION_SECURITY_UNAVAILABLE`   |       `503` | Authentication security did not initialize or required durable state is unavailable. |
+| `TWO_FACTOR_NOT_CONFIGURED`             |       `404` | The concrete model has no two-factor configuration.                                  |
+| `TWO_FACTOR_ENROLLMENT_DISABLED`        |       `403` | Current mode does not permit enrollment.                                             |
+| `TWO_FACTOR_ALREADY_ENABLED`            |       `409` | The principal already has an enabled credential.                                     |
+| `TWO_FACTOR_ENROLLMENT_EXPIRED`         |       `410` | Enrollment was not confirmed before expiry, or the identifier does not match the pending enrollment. |
+| `TWO_FACTOR_NOT_ENABLED`                |       `409` | The principal has no enabled credential for the requested operation.                 |
+| `AUTHORIZATION_REQUIRED`                |       `401` | An authenticated management token is required.                                       |
+
+Responses with status `429` include a `Retry-After` header, rounded up to the configured `retryAfterGranularity`. Login requests can also fail with ordinary credential errors that keep their usual meanings: `LOGIN_FAILED`, `LOGIN_FAILED_EMAIL_NOT_VERIFIED`, and the request-validation codes `USERNAME_EMAIL_REQUIRED`, `REALM_REQUIRED`, `INVALID_REALM`, `INVALID_USERNAME`, and `INVALID_EMAIL`. These are produced by the shared login validation path before two-factor handling begins.
+
+Clients should handle codes, not error-message text. Do not disclose whether a login identifier exists through different public responses.
+
+## Cleanup and recovery
+
+Run cleanup as a recurring maintenance job:
+
+```js
+const result = await app.cleanupAuthenticationSecurity({
+  now: new Date(),
+  terminalRetentionMs: 7 * 24 * 60 * 60 * 1000,
+  disabledCredentialRetentionMs: 30 * 24 * 60 * 60 * 1000,
+  consumingTimeoutMs: 10 * 60 * 1000,
+});
+```
+
+Cleanup options use **milliseconds**, unlike public model configuration.
+
+| Option                          |      Default | Description                                                                                  |
+| ------------------------------- | -----------: | -------------------------------------------------------------------------------------------- |
+| `now`                           | Current time | Reference `Date` for the cleanup pass.                                                       |
+| `terminalRetentionMs`           |       7 days | Retention for terminal challenges and enrollment operations.                                 |
+| `disabledCredentialRetentionMs` |      30 days | Retention for disabled credential records.                                                   |
+| `consumingTimeoutMs`            |   10 minutes | Age after which an abandoned in-progress consumption can be recovered or quarantined safely. |
+
+The result reports what the pass did through named counters — `expiredChallenges`, `recoveredVerifications`, `quarantinedConsumptions`, `reconciledTokens`, `releasedReservations`, `finalizedReservations`, `removedChallenges`, `expiredEnrollments`, `removedCredentials`, and `removedRecoveryCodes` — so schedules can alert on unexpected movement. Expired enrollments are not deleted immediately: they become disabled with their secrets cleared, and physical removal happens once `disabledCredentialRetentionMs` has passed. Cleanup is safe to schedule on more than one application instance because state transitions use compare-and-swap checks, although one designated worker reduces unnecessary load.
+
+User deletion also removes associated private authentication state. If authentication security is configured but unavailable, deletion fails rather than leaving orphaned security state silently.
+
+## Audit and monitoring
+
+The service emits these lifecycle audit events:
+
+| Event                                 | Meaning                                                                                                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `twoFactorChallengeCreated`           | An external login challenge was created.                                                                                                       |
+| `twoFactorEnrollmentStarted`          | A pending credential and enrollment secret were created.                                                                                       |
+| `twoFactorEnabled`                    | Enrollment was confirmed and the credential became active.                                                                                     |
+| `twoFactorRecoveryCodesRegenerated`   | The active recovery-code set was replaced.                                                                                                     |
+| `twoFactorDisabled`                   | The credential was disabled.                                                                                                                   |
+| `twoFactorTokenRevocationPending`     | A token was issued but the operation could not safely complete or revoke it; operator reconciliation is required.                              |
+| `twoFactorEncryptionRotated`          | A model completed one re-encryption pass and reports migrated, conflicting, and remaining records.                                             |
+| `twoFactorChallengeInvalidationError` | Password change committed, but physical challenge expiration failed. Binding still rejects old challenges; operators must investigate cleanup. |
+
+Monitor `authenticationSecurityError` during boot and `authenticationSecurityCleanupError` during maintenance.
+
+At minimum, alert on:
+
+- repeated `AUTHENTICATION_SECURITY_UNAVAILABLE` or `AUTHENTICATION_RATE_LIMIT_UNAVAILABLE`;
+- unusual enrollment, disablement, or recovery-code regeneration volume;
+- sustained source-level blocking;
+- pending or failed token revocation;
+- cleanup backlog and expired in-progress operations;
+- uniqueness-constraint or compare-and-swap failures.
+
+Avoid logging TOTP secrets, recovery codes, submitted codes, password material, encrypted context, or raw rate-limit subjects.
+
+## Key rotation
+
+### Encryption keys
+
+Deploy the new key to every instance, then make it current. Re-encrypt
+credentials and live challenges with the framework migration:
+
+```js
+const result = await app.rotateAuthenticationSecurityEncryption({
+  batchSize: 100,
+  maxBatches: 10_000,
+});
+
+for (const [modelName, modelResult] of Object.entries(result)) {
+  if (modelResult.remainingCredentials || modelResult.remainingChallenges) {
+    throw new Error(`Encryption rotation is incomplete for ${modelName}`);
+  }
+}
+```
+
+`batchSize` accepts 1–1000 records per pass (default `100`), and `maxBatches`
+caps how many batches one invocation processes (default and maximum `10_000`).
+Each phase stops early when a full batch makes no progress, so rerunning the
+operation converges even under concurrent credential changes. The operation
+uses compare-and-set against the original encrypted envelope and
+key ID. It is safe to rerun and reports conflicts instead of overwriting a
+concurrent credential or challenge transition. It covers enabled credentials
+and live challenges; terminal challenges are never re-encrypted. Keep every old key until all
+instances use the new configuration, the result reports zero remaining
+records, and expired terminal challenges have passed their retention period.
+Never remove an old key merely because `currentKeyId` changed.
+
+### Recovery-code HMAC keys
+
+Existing recovery codes reference the key that created their HMAC identifier. Keep the old key until affected users regenerate their recovery codes, then verify no live records reference it before removal.
+
+### Principal-binding HMAC keys
+
+Retain old keys for at least the maximum challenge lifetime, verification lease, deployment skew, and cleanup margin. Removing them early invalidates outstanding challenges.
+
+Deploy key additions everywhere before switching the current ID, and remove old keys only after all instances and persisted state are safe.
+
+For users who have neither their authenticator nor a recovery code, follow the
+[lost-authenticator recovery runbook](./two-factor-authenticator-loss-runbook.md).
+Password reset intentionally does not disable two-factor authentication.
+
+## Deployment checklist
+
+- Create private durable models and physical uniqueness constraints.
+- Apply required schema migrations before enabling the feature.
+- Load three independent random keyrings from a secret manager.
+- Configure the concrete `User` model and initialize before listening.
+- Start with `enroll-and-verify` only when enrollment endpoints and client UX are ready.
+- Confirm token revocation works for every configured session policy.
+- Configure trusted proxy handling or override the authentication-source resolver.
+- Schedule cleanup and monitor security and audit events.
+- Test TOTP and recovery login, challenge expiry, replay, concurrent verification, password changes, disabled users, rate-limit boundaries, datastore failures, token revocation, and key rotation.
+- Use `verify-only`, not `disabled`, for a rollback that must continue enforcing existing credentials.