@aooth/user 0.1.6 → 0.1.8

package/dist/federated-identity-store-DEEed8lA.d.cts

@@ -0,0 +1,378 @@
+//#region src/types.d.ts
+interface UserCredentials {
+  id: string;
+  username: string;
+  /**
+   * Unique login/contact handle. Indexed `@db.index.unique 'email_idx'` on the
+   * `AoothUserCredentials` model so it is independently unique from `username`
+   * and resolvable via `UserStore.findByHandle` / `findByIdentifier`. Optional
+   * because not every deployment populates it (and the invite flow sets
+   * `username := email`).
+   */
+  email?: string;
+  /**
+   * Server-managed optimistic-concurrency counter. Bumped by `UserStore.update`
+   * on every successful write; checked against `UserStoreUpdate.expectedVersion`
+   * for CAS. Callers MUST NOT write it directly — atscript-db rejects direct
+   * writes with `DbError("VERSION_COLUMN_WRITE")`. Optional in TS so pre-OCC
+   * fixtures keep compiling; the store seeds `0` on insert.
+   */
+  version?: number;
+  password: PasswordData;
+  account: AccountData;
+  mfa: MfaData;
+  /**
+   * Persisted device-trust records ("remember this device, skip MFA next
+   * time"). Managed by `UserService.{issue,add,verify,revoke,list}TrustedDevice`.
+   * Absent when the user has never opted in.
+   */
+  trustedDevices?: TrustedDeviceRecord[];
+}
+interface TrustedDeviceRecord {
+  /** `<raw>.<sig>` — what we hand back to the consumer and what they round-trip. */
+  token: string;
+  /** Bound IP — set when `deviceTrust.bindsTo === 'cookie+ip'`. */
+  ip?: string;
+  issuedAt: number;
+  expiresAt: number;
+  /** Optional human-readable label (e.g. user-agent summary). */
+  name?: string;
+}
+interface PasswordData {
+  /** Self-describing scrypt hash: $scrypt$N=...,r=...,p=...,l=...$salt$hash */
+  hash: string;
+  /** Previous password hashes (self-describing strings) */
+  history: string[];
+  lastChanged: number;
+  /** True when password was system-generated and user hasn't set their own */
+  isInitial: boolean;
+}
+interface AccountData {
+  active: boolean;
+  locked: boolean;
+  lockReason: string;
+  /** 0 = permanent lock, >0 = timestamp (ms) when lock expires */
+  lockEnds: number;
+  failedLoginAttempts: number;
+  lastLogin: number;
+  /**
+   * True while the user record exists from an admin-issued invite but the
+   * invitee has not yet accepted (set password + activate). Used by
+   * `InviteWorkflow` to gate the accept tail, reject duplicate invites, and
+   * power `auth/invite/resend` / `auth/invite/cancel`. Absent / `false` once
+   * the invite has been accepted.
+   */
+  pendingInvitation?: boolean;
+}
+interface MfaData {
+  /** Registered MFA methods */
+  methods: MfaMethod[];
+  /** Name of the default MFA method */
+  defaultMethod: string;
+  /** Auto-send MFA challenge on login */
+  autoSend: boolean;
+}
+interface MfaMethod {
+  /** Method name: 'email', 'sms', 'totp' */
+  name: string;
+  /** Whether this method has been verified/confirmed */
+  confirmed: boolean;
+  /** The method's value: email address, phone number, or TOTP secret */
+  value: string;
+  /**
+   * Last HOTP counter accepted for this method (TOTP only). Server-managed
+   * replay guard — `verifyMfa` rejects any code whose matched counter is
+   * `<= lastUsedWindow`. Never written from user-facing input.
+   */
+  lastUsedWindow?: number;
+}
+interface UserServiceConfig {
+  password?: PasswordConfig;
+  lockout?: LockoutConfig;
+  /** Injectable clock for testability. Defaults to Date.now */
+  clock?: () => number;
+  /**
+   * Device-trust config. Required (with a non-empty `secret`) when any
+   * `issueTrustedDevice` / `verifyTrustedDevice` API is called; the methods
+   * throw clearly when invoked without it.
+   */
+  deviceTrust?: {
+    /** HMAC-SHA256 signing secret for trust-device tokens. */secret: string;
+  };
+}
+interface PasswordConfig {
+  /** Pepper string prepended to password before hashing */
+  pepper?: string;
+  /** Number of historical hashes to retain (0 = disabled) */
+  historyLength?: number;
+  /** scrypt cost parameter N (default 16384) */
+  scryptN?: number;
+  /** scrypt block size r (default 8) */
+  scryptR?: number;
+  /** scrypt parallelism p (default 1) */
+  scryptP?: number;
+  /** Hash output length in bytes (default 64) */
+  keyLength?: number;
+  /** Password policy rules */
+  policies?: (PasswordPolicyDef | PasswordPolicyInstance)[];
+  /**
+   * Force re-set of an existing password after this many ms since
+   * `password.lastChanged`. `0` / undefined disables expiry. Read by
+   * `UserService.isPasswordExpired()`; consulted by `@aooth/auth-moost`
+   * `LoginWorkflow`'s forced-change branch when `guards.passwordExpiry`
+   * is true (the default).
+   */
+  maxAgeMs?: number;
+}
+interface LockoutConfig {
+  /** Lock after this many failed attempts (0 = disabled) */
+  threshold?: number;
+  /** Lock duration in ms (0 = permanent) */
+  duration?: number;
+}
+interface PasswordPolicyDef {
+  /**
+   * Backend evaluator. Function only — executed directly with no sandbox.
+   * String rules were removed: `@prostojs/ftring`'s sandbox does NOT block
+   * prototype-chain escapes (`constructor.constructor("return process")()`,
+   * `__proto__.x = ...`), so accepting strings was an RCE vector. Authors
+   * use `definePasswordPolicy({ rule, args })` to get both this fn AND the
+   * serialized form for free.
+   */
+  rule: PasswordPolicyEvalFn;
+  /**
+   * Pre-baked function-literal text shipped to clients for cross-tier
+   * validation via `getTransferablePolicies()`. Authored as
+   * `(v) => (${ruleSource})(v, ${args.map(JSON.stringify).join(', ')})` by
+   * `definePasswordPolicy`. Absent → the policy is backend-only (frontend
+   * skips it; server-side check remains authoritative).
+   */
+  serialized?: string;
+  description?: string;
+  errorMessage?: string;
+}
+type PasswordPolicyEvalFn = (password: string, context?: PasswordPolicyContext) => boolean | Promise<boolean>;
+interface PasswordPolicyContext {
+  passwordData?: PasswordData;
+  passwordConfig?: PasswordConfig;
+}
+/** Interface satisfied by the PasswordPolicy class (avoids circular import) */
+interface PasswordPolicyInstance extends PasswordPolicyDef {
+  evaluate(password: string, context?: PasswordPolicyContext): boolean | Promise<boolean>;
+  transferable: boolean;
+}
+type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
+interface UserStoreUpdate {
+  /** Partial object with fields to set (deep-merged) */
+  set?: DeepPartial<UserCredentials>;
+  /** Dot-paths to atomically increment: e.g. {'account.failedLoginAttempts': 1} */
+  inc?: Record<string, number>;
+  /**
+   * Optimistic concurrency control: when supplied, the store applies the
+   * update iff the row's current `version` equals this value. On mismatch
+   * the store returns `false` (same shape as "not found") and does NOT
+   * mutate. Service callers treat both states as "stale read, retry".
+   */
+  expectedVersion?: number;
+}
+type UserAuthErrorType = "NOT_FOUND" | "ALREADY_EXISTS" | "LOCKED" | "INACTIVE" | "INVALID_CREDENTIALS" | "POLICY_VIOLATION" | "PASSWORDS_MISMATCH" | "PASSWORD_IN_HISTORY" | "MFA_REQUIRED" | "MFA_INVALID" | "MFA_NOT_CONFIGURED" | "CAS_EXHAUSTED";
+interface LoginResult<T extends object = object> {
+  user: UserCredentials & T;
+  /** Whether MFA verification is required before granting full access */
+  mfaRequired: boolean;
+}
+interface LockStatus {
+  locked: boolean;
+  /** True when lock has a non-zero lockEnds that is in the past */
+  expired: boolean;
+  reason: string;
+  lockEnds: number;
+}
+interface PolicyCheckResult {
+  passed: boolean;
+  policies: {
+    description: string;
+    passed: boolean;
+  }[];
+  errors: string[];
+}
+interface TransferablePolicy {
+  rule: string;
+  description?: string;
+  errorMessage?: string;
+}
+interface MfaMethodInfo {
+  name: string;
+  isDefault: boolean;
+  masked: string;
+}
+interface TotpConfig {
+  /** Time step in seconds (default 30) */
+  period?: number;
+  /** Number of digits in the code (default 6) */
+  digits?: number;
+  /** Verification window — number of steps to check on each side (default 1) */
+  window?: number;
+  /** Injectable clock for testability */
+  clock?: () => number;
+}
+//#endregion
+//#region src/store/user-store.d.ts
+interface WithCasOptions {
+  /**
+   * Total attempts (1 initial + retries). Default `2` = one retry. Each
+   * attempt re-reads the row so the mutator runs against fresh state — that
+   * is the whole point of retry under OCC. Bump for high-contention writers
+   * (bulk admin scripts); leave at default for normal per-user request flow.
+   */
+  maxAttempts?: number;
+}
+/**
+ * Storage seam for user credentials, keyed by the stable surrogate **`id`**
+ * (the token subject). Reads come in three flavours:
+ *
+ * - `findById` — strict, by the surrogate id; the canonical identity read used
+ *   by authenticated flows that resolve the session subject (`getUserId()`).
+ * - `findByHandle` — deterministic LOGIN resolver (`username` then `email`).
+ * - `findByIdentifier` — permissive internal/admin/recovery lookup (`id`, then
+ *   `username`, then `email`).
+ *
+ * Writes (`update`/`delete`/`withCas`) all key on the surrogate `id`.
+ */
+declare abstract class UserStore<T extends object = object> {
+  /** True when a user with this login handle (`username`) exists. */
+  abstract exists(handle: string): Promise<boolean>;
+  /**
+   * Strict read by the stable surrogate `id` — the token subject. Authenticated
+   * flows resolve the session subject (`useAuth().getUserId()`) through this.
+   */
+  abstract findById(id: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Deterministic LOGIN resolver: matches `username` exactly, then `email`
+   * exactly (in that order). Intentionally NOT a permissive `$or` — `id`,
+   * `username`, and `email` are all strings, so a permissive match could
+   * silently resolve a value that is one user's username and another's email
+   * to an arbitrary account.
+   */
+  abstract findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
+  /**
+   * Permissive lookup for internal / admin / recovery callers: `id`, then
+   * `username`, then `email` (ordered, first match). NOT for the login path —
+   * use `findByHandle` there.
+   */
+  abstract findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
+  abstract create(data: UserCredentials & T): Promise<void>;
+  /** Apply a patch to the row identified by the stable `id`. */
+  abstract update(id: string, update: UserStoreUpdate): Promise<boolean>;
+  /**
+   * Hard-delete the row by `id`. Returns `true` when a row was removed, `false`
+   * when the id was not found.
+   */
+  abstract delete(id: string): Promise<boolean>;
+  /**
+   * Run a read-modify-write cycle under optimistic concurrency, keyed by `id`.
+   * Each attempt re-reads (via `findById`), calls `mutator`, and applies the
+   * returned patch under CAS (`expectedVersion = current.version`). On CAS miss
+   * the cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null`
+   * to exit early without writing (race-loser "nothing left to do").
+   *
+   * Throws `UserAuthError("NOT_FOUND")` when no row matches `id`, or
+   * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors thrown
+   * from inside `mutator` propagate immediately without retry.
+   */
+  abstract withCas(id: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+}
+//#endregion
+//#region src/store/federated-identity-store.d.ts
+/**
+ * Display fields snapshotted from an IdP profile onto a federated-identity row.
+ * Refreshed on each login via {@link FederatedIdentityStore.touchLogin}; never
+ * a join key (the stable join is `(provider, subject)`). Phase-2's
+ * `NormalizedProfile` (in `@aooth/idp`) is a structural superset of this — it
+ * is declared HERE rather than imported so `@aooth/user` keeps no dependency on
+ * the layer above it.
+ */
+interface FederatedProfileSnapshot {
+  email?: string;
+  emailVerified?: boolean;
+  displayName?: string;
+  avatarUrl?: string;
+}
+/**
+ * Copy only the DEFINED display fields — so a `touchLogin` / `link` with a
+ * partial profile (e.g. Apple omitting the email on a repeat login) never
+ * overwrites a stored value with `undefined`. Shared by every
+ * {@link FederatedIdentityStore} impl.
+ */
+declare function pickDefinedProfile(src: FederatedProfileSnapshot): FederatedProfileSnapshot;
+/**
+ * A persisted federated-identity row: one external-provider account
+ * (`provider` + the IdP's stable `subject`) linked to exactly one aooth user
+ * (`userId` = the user's surrogate `id`). Mirrors the shipped
+ * `AoothFederatedIdentity` `.as` model by construction.
+ */
+interface FederatedIdentity extends FederatedProfileSnapshot {
+  /** Surrogate PK. Server-assigned (`@db.default.uuid` / `randomUUID`). */
+  id: string;
+  provider: string;
+  subject: string;
+  /** Owner — the user's stable surrogate `id`. */
+  userId: string;
+  /** When the link was first created. */
+  linkedAt: number;
+  /** Last federated login through this identity; absent until first `touchLogin`. */
+  lastLoginAt?: number;
+}
+/**
+ * Input to {@link FederatedIdentityStore.link} — the identity keys + owner plus
+ * an optional first-login profile snapshot. `id` and `linkedAt` are assigned by
+ * the store.
+ */
+interface NewFederatedIdentity extends FederatedProfileSnapshot {
+  provider: string;
+  subject: string;
+  userId: string;
+}
+/**
+ * Storage seam for the account-linking table (RFC IDP.md §3.3). The stable
+ * lookup key is the composite `(provider, subject)`; a user may own many rows
+ * (one per linked provider account), so `userId` reads return a list.
+ *
+ * In-memory + atscript-db implementations ship alongside; the abstract surface
+ * keeps the federated-login core (`@aooth/idp`, phase 2) storage-agnostic.
+ */
+declare abstract class FederatedIdentityStore {
+  /** Resolve a provider account to its linked row, or `null`. The federated-login hot path. */
+  abstract find(provider: string, subject: string): Promise<FederatedIdentity | null>;
+  /** All identities linked to a user — the "connected accounts" view. */
+  abstract listForUser(userId: string): Promise<FederatedIdentity[]>;
+  /**
+   * Link a provider account to a user. Throws `UserAuthError("ALREADY_EXISTS")`
+   * when `(provider, subject)` is already linked — to ANY user — which is the
+   * DB-enforced guarantee that one provider account maps to one aooth user.
+   */
+  abstract link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
+  /**
+   * Remove a single provider link. Returns `true` when a row was removed,
+   * `false` when `(provider, subject)` was not linked. (The "don't strand the
+   * user without a usable credential" guard lives in the service layer, not
+   * here — this is the raw delete.)
+   */
+  abstract unlink(provider: string, subject: string): Promise<boolean>;
+  /**
+   * Stamp `lastLoginAt = now` and merge any DEFINED `profile` fields onto the
+   * row. Profile is optional and merged field-by-field, so a provider that
+   * omits the email on a repeat login (e.g. Apple after the first auth) never
+   * nulls the stored snapshot. No-op when `(provider, subject)` is not linked.
+   */
+  abstract touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
+  /**
+   * Remove every identity linked to a user — GDPR hard-delete / "disconnect
+   * everything". Returns the number of rows removed. The app-level complement
+   * to a DB `onDelete cascade` (which this design deliberately does not use —
+   * `userId` is a plain column, not an FK).
+   */
+  abstract deleteAllForUser(userId: string): Promise<number>;
+}
+//#endregion
+export { TotpConfig as C, UserCredentials as D, UserAuthErrorType as E, UserServiceConfig as O, PolicyCheckResult as S, TrustedDeviceRecord as T, PasswordData as _, pickDefinedProfile as a, PasswordPolicyEvalFn as b, AccountData as c, LockoutConfig as d, LoginResult as f, PasswordConfig as g, MfaMethodInfo as h, NewFederatedIdentity as i, UserStoreUpdate as k, DeepPartial as l, MfaMethod as m, FederatedIdentityStore as n, UserStore as o, MfaData as p, FederatedProfileSnapshot as r, WithCasOptions as s, FederatedIdentity as t, LockStatus as u, PasswordPolicyContext as v, TransferablePolicy as w, PasswordPolicyInstance as x, PasswordPolicyDef as y };