@aooth/user 0.1.7 → 0.1.9

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { C as UserServiceConfig, S as UserCredentials, _ as PolicyCheckResult, a as LockStatus, b as TrustedDeviceRecord, c as MfaData, d as PasswordConfig, f as PasswordData, g as PasswordPolicyInstance, h as PasswordPolicyEvalFn, i as DeepPartial, l as MfaMethod, m as PasswordPolicyDef, n as WithCasOptions, o as LockoutConfig, p as PasswordPolicyContext, r as AccountData, s as LoginResult, t as UserStore, u as MfaMethodInfo, v as TotpConfig, w as UserStoreUpdate, x as UserAuthErrorType, y as TransferablePolicy } from "./user-store-BZsKtBHy.cjs";
+import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-CI7Vgllp.cjs";
 
 //#region src/errors.d.ts
 declare class UserAuthError extends Error {
@@ -71,6 +71,15 @@ interface ResolvedConfig {
     secret: string;
   };
 }
+/**
+ * Orchestrates user credentials over a pluggable {@link UserStore}.
+ *
+ * Identity model: the stable surrogate **`id`** is the token subject. `getUser`
+ * and every mutation/admin method are keyed by `id` (the value carried in the
+ * session and returned by `useAuth().getUserId()`); only `login` (and other
+ * handle-driven entry points) take a `username`/`email` login handle, resolved
+ * via `UserStore.findByHandle`.
+ */
 declare class UserService<T extends object = object> {
   protected readonly store: UserStore<T>;
   protected readonly config: ResolvedConfig;
@@ -80,42 +89,59 @@ declare class UserService<T extends object = object> {
    * Creates a user with `account.active: false`. The invite workflow relies
    * on this default (see `InviteWorkflow.acceptInvite` — pending invitees stay
    * inactive until they accept). For setup scripts / seeders / tests that
-   * don't go through invite, follow up with `activateAccount(username)` or
-   * `login()` will throw `UserAuthError("INACTIVE")` — which the login
-   * workflow deliberately re-maps to `"Invalid credentials"` to avoid account
+   * don't go through invite, follow up with `activateAccount(id)` or `login()`
+   * will throw `UserAuthError("INACTIVE")` — which the login workflow
+   * deliberately re-maps to `"Invalid credentials"` to avoid account
    * enumeration, so the failure is silent client-side.
    *
+   * A stable `id` is minted here (server-managed surrogate, also the token
+   * subject) and returned on the record, so callers can `auth.issue(user.id)`
+   * without a re-read. Pass `id` via `extras` to override it.
+   *
    * @param extras Optional partial user fields merged AFTER the base
    *   `UserCredentials` shape, so callers can populate consumer-specific
    *   required fields (e.g. `tenantId`) without subclassing the store.
    *   Because the merge is shallow and extras win, overlapping top-level
-   *   keys (`id`, `account`, `mfa`, ...) replace the defaults entirely —
-   *   pass nested objects with all required sub-fields if you intend to
-   *   override them.
+   *   keys (`id`, `email`, `account`, `mfa`, ...) replace the defaults
+   *   entirely — pass nested objects with all required sub-fields if you
+   *   intend to override them.
    */
   createUser(username: string, password?: string, extras?: Partial<T>): Promise<UserCredentials & T>;
-  getUser(username: string): Promise<UserCredentials & T>;
-  login(username: string, password: string): Promise<LoginResult<T>>;
-  verifyPassword(username: string, password: string): Promise<boolean>;
-  changePassword(username: string, currentPassword: string, newPassword: string, repeatPassword?: string): Promise<void>;
-  setPassword(username: string, newPassword: string): Promise<void>;
+  /** Read by the stable `id` (the token subject). */
+  getUser(id: string): Promise<UserCredentials & T>;
   /**
-   * Hard-delete the user row. Returns nothing on success. Throws
-   * `UserAuthError("NOT_FOUND")` when no row matches `username`. Used by the
-   * invite workflow's `auth/invite/cancel` to revoke a pending invitation.
+   * Deterministic handle resolver — `username` exact, then `email` exact.
+   * Returns `null` when nothing matches. Maps a login/recovery handle to a row;
+   * `login` uses the same resolution.
    */
-  deleteUser(username: string): Promise<void>;
+  findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Permissive lookup — `id`, then `username`, then `email` (ordered, first
+   * match). For internal / admin / recovery callers that may hold either an id
+   * or a handle. NOT for the login path (use {@link login}/{@link findByHandle}).
+   */
+  findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
+  login(handle: string, password: string, lockoutOverride?: Partial<LockoutConfig>): Promise<LoginResult<T>>;
+  verifyPassword(id: string, password: string): Promise<boolean>;
+  changePassword(id: string, currentPassword: string, newPassword: string, repeatPassword?: string): Promise<void>;
+  setPassword(id: string, newPassword: string): Promise<void>;
+  /**
+   * Hard-delete the user row by `id`. Returns nothing on success. Throws
+   * `UserAuthError("NOT_FOUND")` when no row matches. Used by the invite
+   * workflow's `auth/invite/cancel` to revoke a pending invitation.
+   */
+  deleteUser(id: string): Promise<void>;
   /**
    * Deep-merge `patch` into the user record (top-level fields are shallow-
    * merged; `account` / `mfa` / `password` are merged per their
    * `@db.patch.strategy 'merge'` declaration). Returns the patched record.
    * Used by the invite workflow's `applyProfile` default fallback.
    */
-  update(username: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
-  activateAccount(username: string): Promise<void>;
-  deactivateAccount(username: string): Promise<void>;
-  lockAccount(username: string, reason: string, duration?: number): Promise<void>;
-  unlockAccount(username: string): Promise<void>;
+  update(id: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
+  activateAccount(id: string): Promise<void>;
+  deactivateAccount(id: string): Promise<void>;
+  lockAccount(id: string, reason: string, duration?: number): Promise<void>;
+  unlockAccount(id: string): Promise<void>;
   getLockStatus(account: UserCredentials["account"]): LockStatus;
   /**
    * Returns `true` when the user's password is older than
@@ -132,40 +158,19 @@ declare class UserService<T extends object = object> {
   isPasswordExpired(user: UserCredentials & T, now?: number): boolean;
   checkPolicies(password: string, passwordData?: PasswordData): Promise<PolicyCheckResult>;
   getTransferablePolicies(): TransferablePolicy[];
-  addMfaMethod(username: string, method: MfaMethod): Promise<void>;
-  confirmMfaMethod(username: string, name: string): Promise<void>;
-  removeMfaMethod(username: string, name: string): Promise<void>;
-  setDefaultMfaMethod(username: string, name: string): Promise<void>;
-  setMfaAutoSend(username: string, value: boolean): Promise<void>;
+  addMfaMethod(id: string, method: MfaMethod): Promise<void>;
+  confirmMfaMethod(id: string, name: string): Promise<void>;
+  removeMfaMethod(id: string, name: string): Promise<void>;
+  setDefaultMfaMethod(id: string, name: string): Promise<void>;
+  setMfaAutoSend(id: string, value: boolean): Promise<void>;
   getAvailableMfaMethods(mfa: MfaData): MfaMethodInfo[];
-  /**
-   * Generate `count` plaintext backup codes (default 10), persist their
-   * hashes (replacing any existing batch), and return the plaintext codes
-   * once for the caller to deliver to the user. Plaintext is never
-   * recoverable after this call returns.
-   *
-   * Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
-   */
-  generateBackupCodes(username: string, count?: number): Promise<string[]>;
-  /**
-   * Consume a backup code: returns `true` and removes the matching hash
-   * from storage if `code` matches a stored backup code; returns `false`
-   * if no match (without modifying storage). Single-use is enforced by
-   * optimistic-concurrency CAS on the version column — concurrent consumes
-   * of the same code race fairly and only one wins; the loser re-reads,
-   * finds the hash already removed, and returns `false`.
-   *
-   * Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
-   * Throws `UserAuthError("CAS_EXHAUSTED")` if retries are saturated.
-   */
-  consumeBackupCode(username: string, code: string): Promise<boolean>;
   /**
    * Verify a TOTP code against the user's confirmed `totp` MFA method.
    * Failures bump the same `failedLoginAttempts` counter as `login` so an
    * attacker who knows the password but not the TOTP gets `lockout.threshold`
    * total tries across BOTH factors, not `2 * threshold`.
    */
-  verifyMfa(username: string, code: string, config?: TotpConfig): Promise<void>;
+  verifyMfa(id: string, code: string, config?: TotpConfig, lockoutOverride?: Partial<LockoutConfig>): Promise<void>;
   /**
    * Verify a TOTP code against an UNCONFIRMED `totp` MFA method during initial
    * enrollment. Differs from `verifyMfa`:
@@ -177,7 +182,7 @@ declare class UserService<T extends object = object> {
    * Throws: NOT_FOUND if user missing; MFA_NOT_CONFIGURED if no unconfirmed
    * totp method; MFA_INVALID on wrong code.
    */
-  verifyTotpSetupCode(username: string, code: string, config?: TotpConfig): Promise<void>;
+  verifyTotpSetupCode(id: string, code: string, config?: TotpConfig): Promise<void>;
   getPasswordHasher(): PasswordHasher;
   getConfig(): Readonly<ResolvedConfig>;
   /**
@@ -194,19 +199,19 @@ declare class UserService<T extends object = object> {
    * write — the array shape is preserved end-to-end so DB adapters with a
    * merge strategy replace the whole array.
    */
-  addTrustedDevice(username: string, record: TrustedDeviceRecord): Promise<void>;
+  addTrustedDevice(id: string, record: TrustedDeviceRecord): Promise<void>;
   /**
    * Returns true when the supplied token (a) signs against the user+ip with
    * the configured secret, AND (b) matches a persisted record that is still
    * within its expiry window and whose bound IP (if any) matches.
    */
-  verifyTrustedDevice(username: string, token: string, ip?: string): Promise<boolean>;
+  verifyTrustedDevice(userId: string, token: string, ip?: string): Promise<boolean>;
   /**
    * Remove a specific trust record from the user. No-op when the record is
    * absent — mirrors the legacy `DeviceTrustStore.revoke` semantics.
    */
-  revokeTrustedDevice(username: string, token: string): Promise<void>;
-  listTrustedDevices(username: string): Promise<TrustedDeviceRecord[]>;
+  revokeTrustedDevice(id: string, token: string): Promise<void>;
+  listTrustedDevices(id: string): Promise<TrustedDeviceRecord[]>;
   private requireDeviceTrustSecret;
   private applyPasswordChange;
   private hasConfirmedMfaMethods;
@@ -220,20 +225,78 @@ declare class UserService<T extends object = object> {
    * and always throw `errorCode` (with `details.lockEnds` when the lockout
    * just tripped). Used by both `login` and `verifyMfa` so the two factors
    * share one counter.
+   *
+   * `lockoutOverride` lets a caller (e.g. a workflow policy resolver) force a
+   * different posture for THIS lock — notably `{ duration: 0 }` to make the
+   * lock permanent (admin-/recovery-lift only) instead of timed. Unset fields
+   * fall back to `this.config.lockout`.
    */
   private incrementAndMaybeLock;
 }
 //#endregion
 //#region src/store/memory.d.ts
 declare class UserStoreMemory<T extends object = object> extends UserStore<T> {
+  /** Keyed by the stable surrogate `id` (the token subject). */
   private store;
-  constructor(seed?: Record<string, UserCredentials & T>);
-  exists(username: string): Promise<boolean>;
-  findByUsername(username: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Ordered secondary handle fields (e.g. email then phone) resolved from the
+   * model's `@aooth.user.*` annotations by the wiring layer (`handleFields` of
+   * `getAoothUserHandleSpec`). Tried by `findByHandle` after `username`, and
+   * enforced unique by `create`. Empty when no handles are configured (login by
+   * email/phone unavailable).
+   */
+  private readonly handleFields;
+  /**
+   * Optional seed. The map is keyed by each record's `id`; a record missing an
+   * `id` gets one minted (mirrors the DB `@db.default.uuid`). The seed object's
+   * keys are ignored — identity is the record's `id`.
+   *
+   * `opts.handleFields` names the ordered secondary login handles (mirroring
+   * `UsersStoreAtscriptDb`); omit it for username-only resolution.
+   */
+  constructor(seed?: Record<string, UserCredentials & T>, opts?: {
+    handleFields?: string[];
+  });
+  exists(handle: string): Promise<boolean>;
+  findById(id: string): Promise<(UserCredentials & T) | null>;
+  findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
+  findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
   create(data: UserCredentials & T): Promise<void>;
-  update(username: string, update: UserStoreUpdate): Promise<boolean>;
-  delete(username: string): Promise<boolean>;
-  withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+  /**
+   * Throw `ALREADY_EXISTS` if any record other than `excludeId` already holds
+   * one of `rec`'s handle-column values — the in-memory mirror of the
+   * atscript-db store's unique index, so `create` and `update` enforce the same
+   * collision contract (which `promote-to-handle` swallows best-effort). Handle
+   * values are string columns; a non-string is never a collision.
+   */
+  private assertHandlesUnique;
+  update(id: string, update: UserStoreUpdate): Promise<boolean>;
+  delete(id: string): Promise<boolean>;
+  withCas(id: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+}
+//#endregion
+//#region src/store/federated-identity-store-memory.d.ts
+interface FederatedIdentityStoreMemoryOptions {
+  /** Injectable clock for deterministic `linkedAt` / `lastLoginAt`. Defaults to `Date.now`. */
+  clock?: () => number;
+}
+/**
+ * In-memory {@link FederatedIdentityStore} — the offline-testable reference
+ * impl (RFC IDP.md §9). Keyed by the composite `(provider, subject)`;
+ * `structuredClone` on every read/write isolates callers from later mutation
+ * (mirrors `UserStoreMemory`).
+ */
+declare class FederatedIdentityStoreMemory extends FederatedIdentityStore {
+  /** Keyed by `compositeKey(provider, subject)`. */
+  private store;
+  private clock;
+  constructor(opts?: FederatedIdentityStoreMemoryOptions);
+  find(provider: string, subject: string): Promise<FederatedIdentity | null>;
+  listForUser(userId: string): Promise<FederatedIdentity[]>;
+  link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
+  unlink(provider: string, subject: string): Promise<boolean>;
+  touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
+  deleteAllForUser(userId: string): Promise<number>;
 }
 //#endregion
 //#region src/password/policies.d.ts
@@ -274,23 +337,10 @@ declare function hashMfaCode(code: string): string;
  */
 declare function verifyMfaCode(submitted: string, expectedHash: string): boolean;
 //#endregion
-//#region src/mfa/backup-codes.d.ts
-/**
- * Generate `count` cryptographically-random backup codes (default 10).
- *
- * Format: 10 characters from the 31-char safe alphabet (uppercase letters +
- * digits, omitting I/O/L/0/1), grouped as `XXXX-XXXX-XX`.
- *
- * Returns plaintext codes for the caller to deliver to the user — these
- * should be hashed via {@link hashMfaCode} before persistence and never
- * shown to the user again.
- */
-declare function generateBackupCodePlaintext(count?: number): string[];
-//#endregion
 //#region src/utils.d.ts
 declare function maskEmail(email: string): string;
 declare function maskPhone(phone: string): string;
 declare function maskMfaValue(method: MfaMethod): string;
 declare function setAtPath(obj: object, path: string, value: unknown): void;
 //#endregion
-export { type AccountData, type DeepPartial, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as UserServiceConfig, S as UserCredentials, _ as PolicyCheckResult, a as LockStatus, b as TrustedDeviceRecord, c as MfaData, d as PasswordConfig, f as PasswordData, g as PasswordPolicyInstance, h as PasswordPolicyEvalFn, i as DeepPartial, l as MfaMethod, m as PasswordPolicyDef, n as WithCasOptions, o as LockoutConfig, p as PasswordPolicyContext, r as AccountData, s as LoginResult, t as UserStore, u as MfaMethodInfo, v as TotpConfig, w as UserStoreUpdate, x as UserAuthErrorType, y as TransferablePolicy } from "./user-store-62LCSa8q.mjs";
+import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-CI7Vgllp.mjs";
 
 //#region src/errors.d.ts
 declare class UserAuthError extends Error {
@@ -71,6 +71,15 @@ interface ResolvedConfig {
     secret: string;
   };
 }
+/**
+ * Orchestrates user credentials over a pluggable {@link UserStore}.
+ *
+ * Identity model: the stable surrogate **`id`** is the token subject. `getUser`
+ * and every mutation/admin method are keyed by `id` (the value carried in the
+ * session and returned by `useAuth().getUserId()`); only `login` (and other
+ * handle-driven entry points) take a `username`/`email` login handle, resolved
+ * via `UserStore.findByHandle`.
+ */
 declare class UserService<T extends object = object> {
   protected readonly store: UserStore<T>;
   protected readonly config: ResolvedConfig;
@@ -80,42 +89,59 @@ declare class UserService<T extends object = object> {
    * Creates a user with `account.active: false`. The invite workflow relies
    * on this default (see `InviteWorkflow.acceptInvite` — pending invitees stay
    * inactive until they accept). For setup scripts / seeders / tests that
-   * don't go through invite, follow up with `activateAccount(username)` or
-   * `login()` will throw `UserAuthError("INACTIVE")` — which the login
-   * workflow deliberately re-maps to `"Invalid credentials"` to avoid account
+   * don't go through invite, follow up with `activateAccount(id)` or `login()`
+   * will throw `UserAuthError("INACTIVE")` — which the login workflow
+   * deliberately re-maps to `"Invalid credentials"` to avoid account
    * enumeration, so the failure is silent client-side.
    *
+   * A stable `id` is minted here (server-managed surrogate, also the token
+   * subject) and returned on the record, so callers can `auth.issue(user.id)`
+   * without a re-read. Pass `id` via `extras` to override it.
+   *
    * @param extras Optional partial user fields merged AFTER the base
    *   `UserCredentials` shape, so callers can populate consumer-specific
    *   required fields (e.g. `tenantId`) without subclassing the store.
    *   Because the merge is shallow and extras win, overlapping top-level
-   *   keys (`id`, `account`, `mfa`, ...) replace the defaults entirely —
-   *   pass nested objects with all required sub-fields if you intend to
-   *   override them.
+   *   keys (`id`, `email`, `account`, `mfa`, ...) replace the defaults
+   *   entirely — pass nested objects with all required sub-fields if you
+   *   intend to override them.
    */
   createUser(username: string, password?: string, extras?: Partial<T>): Promise<UserCredentials & T>;
-  getUser(username: string): Promise<UserCredentials & T>;
-  login(username: string, password: string): Promise<LoginResult<T>>;
-  verifyPassword(username: string, password: string): Promise<boolean>;
-  changePassword(username: string, currentPassword: string, newPassword: string, repeatPassword?: string): Promise<void>;
-  setPassword(username: string, newPassword: string): Promise<void>;
+  /** Read by the stable `id` (the token subject). */
+  getUser(id: string): Promise<UserCredentials & T>;
   /**
-   * Hard-delete the user row. Returns nothing on success. Throws
-   * `UserAuthError("NOT_FOUND")` when no row matches `username`. Used by the
-   * invite workflow's `auth/invite/cancel` to revoke a pending invitation.
+   * Deterministic handle resolver — `username` exact, then `email` exact.
+   * Returns `null` when nothing matches. Maps a login/recovery handle to a row;
+   * `login` uses the same resolution.
    */
-  deleteUser(username: string): Promise<void>;
+  findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Permissive lookup — `id`, then `username`, then `email` (ordered, first
+   * match). For internal / admin / recovery callers that may hold either an id
+   * or a handle. NOT for the login path (use {@link login}/{@link findByHandle}).
+   */
+  findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
+  login(handle: string, password: string, lockoutOverride?: Partial<LockoutConfig>): Promise<LoginResult<T>>;
+  verifyPassword(id: string, password: string): Promise<boolean>;
+  changePassword(id: string, currentPassword: string, newPassword: string, repeatPassword?: string): Promise<void>;
+  setPassword(id: string, newPassword: string): Promise<void>;
+  /**
+   * Hard-delete the user row by `id`. Returns nothing on success. Throws
+   * `UserAuthError("NOT_FOUND")` when no row matches. Used by the invite
+   * workflow's `auth/invite/cancel` to revoke a pending invitation.
+   */
+  deleteUser(id: string): Promise<void>;
   /**
    * Deep-merge `patch` into the user record (top-level fields are shallow-
    * merged; `account` / `mfa` / `password` are merged per their
    * `@db.patch.strategy 'merge'` declaration). Returns the patched record.
    * Used by the invite workflow's `applyProfile` default fallback.
    */
-  update(username: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
-  activateAccount(username: string): Promise<void>;
-  deactivateAccount(username: string): Promise<void>;
-  lockAccount(username: string, reason: string, duration?: number): Promise<void>;
-  unlockAccount(username: string): Promise<void>;
+  update(id: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
+  activateAccount(id: string): Promise<void>;
+  deactivateAccount(id: string): Promise<void>;
+  lockAccount(id: string, reason: string, duration?: number): Promise<void>;
+  unlockAccount(id: string): Promise<void>;
   getLockStatus(account: UserCredentials["account"]): LockStatus;
   /**
    * Returns `true` when the user's password is older than
@@ -132,40 +158,19 @@ declare class UserService<T extends object = object> {
   isPasswordExpired(user: UserCredentials & T, now?: number): boolean;
   checkPolicies(password: string, passwordData?: PasswordData): Promise<PolicyCheckResult>;
   getTransferablePolicies(): TransferablePolicy[];
-  addMfaMethod(username: string, method: MfaMethod): Promise<void>;
-  confirmMfaMethod(username: string, name: string): Promise<void>;
-  removeMfaMethod(username: string, name: string): Promise<void>;
-  setDefaultMfaMethod(username: string, name: string): Promise<void>;
-  setMfaAutoSend(username: string, value: boolean): Promise<void>;
+  addMfaMethod(id: string, method: MfaMethod): Promise<void>;
+  confirmMfaMethod(id: string, name: string): Promise<void>;
+  removeMfaMethod(id: string, name: string): Promise<void>;
+  setDefaultMfaMethod(id: string, name: string): Promise<void>;
+  setMfaAutoSend(id: string, value: boolean): Promise<void>;
   getAvailableMfaMethods(mfa: MfaData): MfaMethodInfo[];
-  /**
-   * Generate `count` plaintext backup codes (default 10), persist their
-   * hashes (replacing any existing batch), and return the plaintext codes
-   * once for the caller to deliver to the user. Plaintext is never
-   * recoverable after this call returns.
-   *
-   * Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
-   */
-  generateBackupCodes(username: string, count?: number): Promise<string[]>;
-  /**
-   * Consume a backup code: returns `true` and removes the matching hash
-   * from storage if `code` matches a stored backup code; returns `false`
-   * if no match (without modifying storage). Single-use is enforced by
-   * optimistic-concurrency CAS on the version column — concurrent consumes
-   * of the same code race fairly and only one wins; the loser re-reads,
-   * finds the hash already removed, and returns `false`.
-   *
-   * Throws `UserAuthError("NOT_FOUND")` if the user does not exist.
-   * Throws `UserAuthError("CAS_EXHAUSTED")` if retries are saturated.
-   */
-  consumeBackupCode(username: string, code: string): Promise<boolean>;
   /**
    * Verify a TOTP code against the user's confirmed `totp` MFA method.
    * Failures bump the same `failedLoginAttempts` counter as `login` so an
    * attacker who knows the password but not the TOTP gets `lockout.threshold`
    * total tries across BOTH factors, not `2 * threshold`.
    */
-  verifyMfa(username: string, code: string, config?: TotpConfig): Promise<void>;
+  verifyMfa(id: string, code: string, config?: TotpConfig, lockoutOverride?: Partial<LockoutConfig>): Promise<void>;
   /**
    * Verify a TOTP code against an UNCONFIRMED `totp` MFA method during initial
    * enrollment. Differs from `verifyMfa`:
@@ -177,7 +182,7 @@ declare class UserService<T extends object = object> {
    * Throws: NOT_FOUND if user missing; MFA_NOT_CONFIGURED if no unconfirmed
    * totp method; MFA_INVALID on wrong code.
    */
-  verifyTotpSetupCode(username: string, code: string, config?: TotpConfig): Promise<void>;
+  verifyTotpSetupCode(id: string, code: string, config?: TotpConfig): Promise<void>;
   getPasswordHasher(): PasswordHasher;
   getConfig(): Readonly<ResolvedConfig>;
   /**
@@ -194,19 +199,19 @@ declare class UserService<T extends object = object> {
    * write — the array shape is preserved end-to-end so DB adapters with a
    * merge strategy replace the whole array.
    */
-  addTrustedDevice(username: string, record: TrustedDeviceRecord): Promise<void>;
+  addTrustedDevice(id: string, record: TrustedDeviceRecord): Promise<void>;
   /**
    * Returns true when the supplied token (a) signs against the user+ip with
    * the configured secret, AND (b) matches a persisted record that is still
    * within its expiry window and whose bound IP (if any) matches.
    */
-  verifyTrustedDevice(username: string, token: string, ip?: string): Promise<boolean>;
+  verifyTrustedDevice(userId: string, token: string, ip?: string): Promise<boolean>;
   /**
    * Remove a specific trust record from the user. No-op when the record is
    * absent — mirrors the legacy `DeviceTrustStore.revoke` semantics.
    */
-  revokeTrustedDevice(username: string, token: string): Promise<void>;
-  listTrustedDevices(username: string): Promise<TrustedDeviceRecord[]>;
+  revokeTrustedDevice(id: string, token: string): Promise<void>;
+  listTrustedDevices(id: string): Promise<TrustedDeviceRecord[]>;
   private requireDeviceTrustSecret;
   private applyPasswordChange;
   private hasConfirmedMfaMethods;
@@ -220,20 +225,78 @@ declare class UserService<T extends object = object> {
    * and always throw `errorCode` (with `details.lockEnds` when the lockout
    * just tripped). Used by both `login` and `verifyMfa` so the two factors
    * share one counter.
+   *
+   * `lockoutOverride` lets a caller (e.g. a workflow policy resolver) force a
+   * different posture for THIS lock — notably `{ duration: 0 }` to make the
+   * lock permanent (admin-/recovery-lift only) instead of timed. Unset fields
+   * fall back to `this.config.lockout`.
    */
   private incrementAndMaybeLock;
 }
 //#endregion
 //#region src/store/memory.d.ts
 declare class UserStoreMemory<T extends object = object> extends UserStore<T> {
+  /** Keyed by the stable surrogate `id` (the token subject). */
   private store;
-  constructor(seed?: Record<string, UserCredentials & T>);
-  exists(username: string): Promise<boolean>;
-  findByUsername(username: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Ordered secondary handle fields (e.g. email then phone) resolved from the
+   * model's `@aooth.user.*` annotations by the wiring layer (`handleFields` of
+   * `getAoothUserHandleSpec`). Tried by `findByHandle` after `username`, and
+   * enforced unique by `create`. Empty when no handles are configured (login by
+   * email/phone unavailable).
+   */
+  private readonly handleFields;
+  /**
+   * Optional seed. The map is keyed by each record's `id`; a record missing an
+   * `id` gets one minted (mirrors the DB `@db.default.uuid`). The seed object's
+   * keys are ignored — identity is the record's `id`.
+   *
+   * `opts.handleFields` names the ordered secondary login handles (mirroring
+   * `UsersStoreAtscriptDb`); omit it for username-only resolution.
+   */
+  constructor(seed?: Record<string, UserCredentials & T>, opts?: {
+    handleFields?: string[];
+  });
+  exists(handle: string): Promise<boolean>;
+  findById(id: string): Promise<(UserCredentials & T) | null>;
+  findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
+  findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
   create(data: UserCredentials & T): Promise<void>;
-  update(username: string, update: UserStoreUpdate): Promise<boolean>;
-  delete(username: string): Promise<boolean>;
-  withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+  /**
+   * Throw `ALREADY_EXISTS` if any record other than `excludeId` already holds
+   * one of `rec`'s handle-column values — the in-memory mirror of the
+   * atscript-db store's unique index, so `create` and `update` enforce the same
+   * collision contract (which `promote-to-handle` swallows best-effort). Handle
+   * values are string columns; a non-string is never a collision.
+   */
+  private assertHandlesUnique;
+  update(id: string, update: UserStoreUpdate): Promise<boolean>;
+  delete(id: string): Promise<boolean>;
+  withCas(id: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+}
+//#endregion
+//#region src/store/federated-identity-store-memory.d.ts
+interface FederatedIdentityStoreMemoryOptions {
+  /** Injectable clock for deterministic `linkedAt` / `lastLoginAt`. Defaults to `Date.now`. */
+  clock?: () => number;
+}
+/**
+ * In-memory {@link FederatedIdentityStore} — the offline-testable reference
+ * impl (RFC IDP.md §9). Keyed by the composite `(provider, subject)`;
+ * `structuredClone` on every read/write isolates callers from later mutation
+ * (mirrors `UserStoreMemory`).
+ */
+declare class FederatedIdentityStoreMemory extends FederatedIdentityStore {
+  /** Keyed by `compositeKey(provider, subject)`. */
+  private store;
+  private clock;
+  constructor(opts?: FederatedIdentityStoreMemoryOptions);
+  find(provider: string, subject: string): Promise<FederatedIdentity | null>;
+  listForUser(userId: string): Promise<FederatedIdentity[]>;
+  link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
+  unlink(provider: string, subject: string): Promise<boolean>;
+  touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
+  deleteAllForUser(userId: string): Promise<number>;
 }
 //#endregion
 //#region src/password/policies.d.ts
@@ -274,23 +337,10 @@ declare function hashMfaCode(code: string): string;
  */
 declare function verifyMfaCode(submitted: string, expectedHash: string): boolean;
 //#endregion
-//#region src/mfa/backup-codes.d.ts
-/**
- * Generate `count` cryptographically-random backup codes (default 10).
- *
- * Format: 10 characters from the 31-char safe alphabet (uppercase letters +
- * digits, omitting I/O/L/0/1), grouped as `XXXX-XXXX-XX`.
- *
- * Returns plaintext codes for the caller to deliver to the user — these
- * should be hashed via {@link hashMfaCode} before persistence and never
- * shown to the user again.
- */
-declare function generateBackupCodePlaintext(count?: number): string[];
-//#endregion
 //#region src/utils.d.ts
 declare function maskEmail(email: string): string;
 declare function maskPhone(phone: string): string;
 declare function maskMfaValue(method: MfaMethod): string;
 declare function setAtPath(obj: object, path: string, value: unknown): void;
 //#endregion
-export { type AccountData, type DeepPartial, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateBackupCodePlaintext, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };