@udibo/oauth2 0.1.0

package/esm/identity/external/provider.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The contract between {@link ExternalAuthFlow} and a concrete external
+ * provider connector ({@link oidcProvider}, {@link googleProvider},
+ * {@link githubProvider}, or your own).
+ *
+ * A provider's job ends at returning a verified, normalized
+ * {@link ExternalProfile}. What the app does with it — create a user, link an
+ * account, reject — is app code; the library deliberately stores nothing.
+ *
+ * @module
+ */
+/**
+ * A verified, normalized profile returned by an external provider after a
+ * successful sign-in. This is the connector layer's entire output — account
+ * creation/linking is the app's job.
+ */
+export interface ExternalProfile {
+    /** The provider id the profile came from (e.g. `"google"`). */
+    provider: string;
+    /**
+     * The provider's stable unique id for the user (OIDC `sub`, GitHub user
+     * id). Key identities by `(provider, subject)` — never by email, which can
+     * change or be reassigned.
+     */
+    subject: string;
+    /** The user's email address, when the provider shared one. */
+    email?: string;
+    /**
+     * `true` only when the provider positively asserted the email is verified
+     * (OIDC `email_verified: true`, GitHub verified primary email). Defaults to
+     * `false` — treat unverified emails as attacker-controllable input and do
+     * not auto-link accounts on them.
+     */
+    emailVerified: boolean;
+    /** Display name, when shared. */
+    name?: string;
+    /** Given (first) name, when shared. */
+    givenName?: string;
+    /** Family (last) name, when shared. */
+    familyName?: string;
+    /** Avatar/profile picture URL, when shared. */
+    picture?: string;
+    /**
+     * The provider's raw claims/profile payload, for app-specific fields the
+     * normalized shape omits (e.g. Google's `hd`, GitHub's `login`).
+     */
+    raw: Record<string, unknown>;
+}
+/**
+ * The per-authorization transient state {@link ExternalAuthFlow.start}
+ * returns. JSON-serializable by construction — put it in a sealed cookie or
+ * your session store and hand it back to {@link ExternalAuthFlow.finish} on
+ * the callback. It is the only state the flow needs; the library stores
+ * nothing.
+ */
+export interface ExternalAuthTransient {
+    /** CSRF token echoed back by the provider as the callback `state` param. */
+    state: string;
+    /** PKCE code verifier, present when the provider uses PKCE. */
+    codeVerifier?: string;
+    /** OIDC replay-protection nonce, present when the provider uses one. */
+    nonce?: string;
+    /** The id of the provider the attempt was started with. */
+    provider: string;
+    /** The redirect URI the authorization request was built with. */
+    redirectUri: string;
+    /** Unix ms when the attempt started; bounds the callback window. */
+    createdAt: number;
+}
+/** Input to {@link ExternalProvider.buildAuthorizationUrl}. */
+export interface ExternalAuthorizationUrlInput {
+    /** The callback URL registered with the provider for this app. */
+    redirectUri: string;
+    /** CSRF token to send as the `state` parameter. */
+    state: string;
+    /** PKCE code verifier to derive the S256 challenge from, when PKCE is on. */
+    codeVerifier?: string;
+    /** OIDC nonce to bind into the id_token, when the provider uses one. */
+    nonce?: string;
+    /** Scopes to request (already defaulted by the flow). */
+    scopes: string[];
+    /** OIDC `prompt` parameter (e.g. `"select_account"`), when requested. */
+    prompt?: string;
+}
+/** Input to {@link ExternalProvider.fetchProfile}. */
+export interface ExternalProfileInput {
+    /** The authorization code from the callback. */
+    code: string;
+    /** The redirect URI the flow was started with (must match the exchange). */
+    redirectUri: string;
+    /** The PKCE code verifier from the transient, when PKCE was used. */
+    codeVerifier?: string;
+    /** The expected id_token `nonce` from the transient, when one was sent. */
+    nonce?: string;
+}
+/**
+ * What a connector must provide for {@link ExternalAuthFlow} to drive it.
+ *
+ * The flow owns the cross-provider policy (state generation and timing-safe
+ * verification, transient expiry, callback error surfacing); the provider
+ * owns the wire protocol (authorize URL shape, code exchange, id_token nonce
+ * validation, profile normalization). Implement this only for providers the
+ * built-in {@link oidcProvider} / {@link githubProvider} cannot cover.
+ */
+export interface ExternalProvider {
+    /** Stable id used in {@link ExternalProfile.provider} and error messages. */
+    readonly id: string;
+    /** Human-readable name for buttons and logs (e.g. `"Google"`). */
+    readonly displayName: string;
+    /** Scopes requested when the caller passes none. */
+    readonly defaultScopes: string[];
+    /** Whether the flow should generate a PKCE code verifier for this provider. */
+    readonly usesPkce: boolean;
+    /** Whether the flow should generate an OIDC nonce for this provider. */
+    readonly usesNonce: boolean;
+    /**
+     * Builds the provider's authorization URL for the given per-attempt values.
+     *
+     * @throws {ExternalAuthError} `configuration` when the provider cannot
+     *   resolve its authorization endpoint (e.g. OIDC discovery failed).
+     */
+    buildAuthorizationUrl(input: ExternalAuthorizationUrlInput): Promise<string>;
+    /**
+     * Exchanges the authorization code and returns the verified, normalized
+     * profile. Implementations must validate the id_token `nonce` against
+     * `input.nonce` when one was sent.
+     *
+     * @throws {ExternalAuthError} `provider_error` when the exchange or profile
+     *   fetch fails, `nonce_mismatch` when the id_token nonce does not match.
+     */
+    fetchProfile(input: ExternalProfileInput): Promise<ExternalProfile>;
+}

package/esm/identity/external/provider.js

@@ -0,0 +1,12 @@
+/**
+ * The contract between {@link ExternalAuthFlow} and a concrete external
+ * provider connector ({@link oidcProvider}, {@link googleProvider},
+ * {@link githubProvider}, or your own).
+ *
+ * A provider's job ends at returning a verified, normalized
+ * {@link ExternalProfile}. What the app does with it — create a user, link an
+ * account, reject — is app code; the library deliberately stores nothing.
+ *
+ * @module
+ */
+export {};

package/esm/identity/hibp.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Breached-password rejection via the Have I Been Pwned range API — the
+ * privacy-preserving k-anonymity model: only the first five characters of the
+ * password's SHA-1 hash ever leave the process; the full password and full
+ * hash never do.
+ *
+ * {@link breachedPasswordValidator} returns an async validator for
+ * {@link PasswordPolicy.validators}, so a policy rejects known-breached
+ * passwords at sign-up and password reset. **Fail-open by default**: if the
+ * range API is unreachable, the password is allowed —
+ * availability of your sign-up flow shouldn't hinge on a third party. Set
+ * `failOpen: false` to invert that.
+ *
+ * Pass `onEvent` so those fail-opens reach your audit store as
+ * `password_policy.check_unavailable` events; an egress rule that blocks
+ * `api.pwnedpasswords.com` disables this control silently otherwise.
+ *
+ * @module
+ */
+import { type IdentityEventHook } from "./events.js";
+/** Options for {@link breachedPasswordValidator}. */
+export interface BreachedPasswordOptions {
+    /**
+     * Reject when the password appears in at least this many breaches.
+     * Defaults to 1.
+     */
+    threshold?: number;
+    /**
+     * Allow the password when the range API can't be reached (default `true`).
+     * `false` rejects with a retry message instead.
+     */
+    failOpen?: boolean;
+    /** Abort the range request after this many ms. Defaults to 3000. */
+    timeoutMs?: number;
+    /** Fetch implementation — inject for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Range API base URL. Defaults to `https://api.pwnedpasswords.com/range/`. */
+    baseUrl?: string;
+    /**
+     * Receives a `password_policy.check_unavailable` {@link IdentityEvent} every
+     * time the range lookup fails, so a fail-open is answerable from the same
+     * audit store as every other identity outcome ("was this check actually
+     * running last month?"). Pass the hook you gave `IdentityService`'s
+     * `onEvent`.
+     *
+     * Without it the failure is only a `console.warn` — greppable in container
+     * logs, invisible to an audit query. The hook follows the
+     * {@link IdentityEventHook} contract: awaited, and a rejection is logged
+     * rather than rethrown, so the sign-up it observes still completes.
+     */
+    onEvent?: IdentityEventHook;
+}
+/** Uppercase hex SHA-1, the digest format the HIBP range API keys on. */
+export declare function sha1Hex(input: string): Promise<string>;
+/**
+ * Build a {@link PasswordPolicy} validator that rejects passwords found in the
+ * HIBP breach corpus.
+ *
+ * @example
+ * ```ts
+ * const policy: PasswordPolicy = {
+ *   minLength: 8,
+ *   validators: [breachedPasswordValidator({ onEvent })],
+ * };
+ * ```
+ */
+export declare function breachedPasswordValidator(options?: BreachedPasswordOptions): (password: string) => Promise<string | undefined>;

package/esm/identity/hibp.js

@@ -0,0 +1,87 @@
+/**
+ * Breached-password rejection via the Have I Been Pwned range API — the
+ * privacy-preserving k-anonymity model: only the first five characters of the
+ * password's SHA-1 hash ever leave the process; the full password and full
+ * hash never do.
+ *
+ * {@link breachedPasswordValidator} returns an async validator for
+ * {@link PasswordPolicy.validators}, so a policy rejects known-breached
+ * passwords at sign-up and password reset. **Fail-open by default**: if the
+ * range API is unreachable, the password is allowed —
+ * availability of your sign-up flow shouldn't hinge on a third party. Set
+ * `failOpen: false` to invert that.
+ *
+ * Pass `onEvent` so those fail-opens reach your audit store as
+ * `password_policy.check_unavailable` events; an egress rule that blocks
+ * `api.pwnedpasswords.com` disables this control silently otherwise.
+ *
+ * @module
+ */
+import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.11/hex.js";
+import { dispatchIdentityEvent } from "./events.js";
+const DEFAULT_BASE_URL = "https://api.pwnedpasswords.com/range/";
+const VALIDATOR_NAME = "breached_password";
+const BREACHED_MESSAGE = "This password has appeared in a data breach; choose a different one.";
+const UNAVAILABLE_MESSAGE = "The password couldn't be checked against known breaches; try again.";
+/** Uppercase hex SHA-1, the digest format the HIBP range API keys on. */
+export async function sha1Hex(input) {
+    const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(input));
+    return encodeHex(digest).toUpperCase();
+}
+/**
+ * Build a {@link PasswordPolicy} validator that rejects passwords found in the
+ * HIBP breach corpus.
+ *
+ * @example
+ * ```ts
+ * const policy: PasswordPolicy = {
+ *   minLength: 8,
+ *   validators: [breachedPasswordValidator({ onEvent })],
+ * };
+ * ```
+ */
+export function breachedPasswordValidator(options = {}) {
+    const threshold = options.threshold ?? 1;
+    const failOpen = options.failOpen ?? true;
+    const timeoutMs = options.timeoutMs ?? 3000;
+    const fetchImpl = options.fetch ?? fetch;
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const onEvent = options.onEvent;
+    return async (password) => {
+        try {
+            const hash = await sha1Hex(password);
+            const prefix = hash.slice(0, 5);
+            const suffix = hash.slice(5);
+            const response = await fetchImpl(`${baseUrl}${prefix}`, {
+                headers: { "Add-Padding": "true" },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new Error(`range API responded ${response.status}`);
+            }
+            const body = await response.text();
+            for (const line of body.split("\n")) {
+                const [lineSuffix, countText] = line.trim().split(":");
+                if (lineSuffix === suffix && Number(countText) >= threshold) {
+                    return BREACHED_MESSAGE;
+                }
+            }
+            return undefined;
+        }
+        catch (error) {
+            if (onEvent) {
+                await dispatchIdentityEvent(onEvent, "breachedPasswordValidator", {
+                    type: "password_policy.check_unavailable",
+                    validator: VALIDATOR_NAME,
+                    failedOpen: failOpen,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            else {
+                console.warn("[@udibo/oauth2] breached-password check failed:", error);
+            }
+            return failOpen ? undefined : UNAVAILABLE_MESSAGE;
+        }
+    };
+}

package/esm/identity/identifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Sign-in identifier classification + resolution.
+ *
+ * A sign-in form usually accepts "email or username" (sometimes phone), and
+ * every app hand-rolls the `identifier.includes("@")` branch to decide which
+ * lookup to run. This makes that a configured concern instead.
+ *
+ * @module
+ */
+/** How a sign-in identifier was classified. */
+export type IdentifierKind = "email" | "username" | "phone";
+/**
+ * Classify a sign-in identifier as an email, phone number, or username.
+ *
+ * Heuristic: an `@` → `email`; otherwise a value made only of phone characters
+ * (`+`, digits, spaces, `-`, `()`, `.`) with at least 7 digits → `phone`;
+ * everything else → `username`. The value is trimmed first.
+ */
+export declare function classifyIdentifier(identifier: string): IdentifierKind;
+/** Per-kind user lookups supplied by the app. Omit a kind to disallow it. */
+export interface IdentifierLookups<User> {
+    /** Resolve a user by email; omit to disallow signing in with an email. */
+    email?: (email: string) => Promise<User | undefined> | User | undefined;
+    /** Resolve a user by username; omit to disallow signing in with a username. */
+    username?: (username: string) => Promise<User | undefined> | User | undefined;
+    /** Resolve a user by phone number; omit to disallow signing in with a phone. */
+    phone?: (phone: string) => Promise<User | undefined> | User | undefined;
+}
+/**
+ * Build a resolver that classifies an identifier ({@link classifyIdentifier})
+ * and dispatches to the matching app-supplied lookup. Returns `undefined` when
+ * no lookup is configured for the classified kind, or the user isn't found —
+ * callers should treat both as "invalid credentials" without revealing which.
+ *
+ * @example
+ * ```ts
+ * const resolve = createIdentifierResolver({
+ *   email: (e) => userService.getByEmail(e),
+ *   username: (u) => userService.getByUsername(u),
+ * });
+ * const user = await resolve(form.get("identifier"));
+ * ```
+ */
+export declare function createIdentifierResolver<User>(lookups: IdentifierLookups<User>): (identifier: string) => Promise<User | undefined>;

package/esm/identity/identifier.js

@@ -0,0 +1,47 @@
+/**
+ * Sign-in identifier classification + resolution.
+ *
+ * A sign-in form usually accepts "email or username" (sometimes phone), and
+ * every app hand-rolls the `identifier.includes("@")` branch to decide which
+ * lookup to run. This makes that a configured concern instead.
+ *
+ * @module
+ */
+/**
+ * Classify a sign-in identifier as an email, phone number, or username.
+ *
+ * Heuristic: an `@` → `email`; otherwise a value made only of phone characters
+ * (`+`, digits, spaces, `-`, `()`, `.`) with at least 7 digits → `phone`;
+ * everything else → `username`. The value is trimmed first.
+ */
+export function classifyIdentifier(identifier) {
+    const value = identifier.trim();
+    if (value.includes("@"))
+        return "email";
+    const digitCount = (value.match(/\d/g) ?? []).length;
+    if (digitCount >= 7 && /^\+?[\d\s\-().]+$/.test(value))
+        return "phone";
+    return "username";
+}
+/**
+ * Build a resolver that classifies an identifier ({@link classifyIdentifier})
+ * and dispatches to the matching app-supplied lookup. Returns `undefined` when
+ * no lookup is configured for the classified kind, or the user isn't found —
+ * callers should treat both as "invalid credentials" without revealing which.
+ *
+ * @example
+ * ```ts
+ * const resolve = createIdentifierResolver({
+ *   email: (e) => userService.getByEmail(e),
+ *   username: (u) => userService.getByUsername(u),
+ * });
+ * const user = await resolve(form.get("identifier"));
+ * ```
+ */
+export function createIdentifierResolver(lookups) {
+    return async (identifier) => {
+        const value = identifier.trim();
+        const lookup = lookups[classifyIdentifier(value)];
+        return lookup ? await lookup(value) : undefined;
+    };
+}

package/esm/identity/lockout.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Failed-attempt account lockout — the brute-force floor for sign-in.
+ *
+ * Distinct from rate limiting: the {@link RateLimiter} throttles *attempts per
+ * window* keyed however you like (identifier, IP), while lockout tracks
+ * *consecutive failures per account* and locks the account for a cooldown once
+ * a threshold is crossed. Storage is a pluggable {@link LockoutStore}
+ * (a {@link MemoryLockoutStore} ships for dev/single-process; back it with your
+ * database to share state across instances — e.g. columns on your users table,
+ * which also gives admins visibility).
+ *
+ * `AccountLockout` is a pure state machine: it never decides whether to block.
+ * `IdentityService` consults it and applies its `protectionMode`
+ * (enforce vs log-only), so adopters can observe lockout behavior before
+ * turning it on.
+ *
+ * @module
+ */
+/** Per-account lockout state. */
+export interface LockoutRecord {
+    /** Consecutive failed sign-in attempts since the last success/unlock. */
+    failures: number;
+    /** When the active lock expires (epoch ms); absent when not locked. */
+    lockedUntil?: number;
+}
+/** Pluggable per-account state store for {@link AccountLockout}. */
+export interface LockoutStore {
+    /** The account's current record, or `undefined` when it has none. */
+    get(userId: string): Promise<LockoutRecord | undefined>;
+    /**
+     * Add one failure and return the new record: an expired lock resets the
+     * count to 1 and drops the lock; otherwise `failures + 1` with any active
+     * lock kept. Must be atomic (a single statement / compare-and-set in shared
+     * stores) — a read-modify-write here lets concurrent failed attempts lose
+     * counts and undershoot the lockout threshold.
+     */
+    increment(userId: string, now: number): Promise<LockoutRecord>;
+    /**
+     * Persist the account's record, replacing any existing one rather than
+     * merging: a record with no `lockedUntil` leaves the account unlocked.
+     */
+    set(userId: string, record: LockoutRecord): Promise<void>;
+    /** Clear the account's record (successful sign-in or unlock). */
+    clear(userId: string): Promise<void>;
+}
+/** Options for {@link AccountLockout}. */
+export interface AccountLockoutOptions {
+    /** Consecutive failures that trigger a lock. Defaults to 10. */
+    maxAttempts?: number;
+    /** How long a lock lasts, in ms. Defaults to 15 minutes. */
+    lockDurationMs?: number;
+    /** State storage. Defaults to {@link MemoryLockoutStore}. */
+    store?: LockoutStore;
+}
+/** The outcome of {@link AccountLockout.recordFailure}. */
+export interface LockoutFailureResult {
+    /** Consecutive failures after this one. */
+    failures: number;
+    /** Whether the account is now locked. */
+    locked: boolean;
+    /** Whether THIS failure crossed the threshold and created the lock. */
+    justLocked: boolean;
+    /** When the lock expires (epoch ms); absent when not locked. */
+    lockedUntil?: number;
+}
+/** The outcome of {@link AccountLockout.status}. */
+export interface LockoutStatus {
+    /** Whether an unexpired lock is active. */
+    locked: boolean;
+    /** Consecutive failures recorded so far. */
+    failures: number;
+    /** When the active lock expires (epoch ms); absent when not locked. */
+    lockedUntil?: number;
+}
+/**
+ * The lockout contract {@link IdentityService} accepts — the
+ * bring-your-own-policy seam, symmetric with `RateLimiterLike`.
+ * {@link AccountLockout} is the shipped consecutive-failure implementation and
+ * satisfies it; implement this directly for a different policy (exponential
+ * backoff, per-IP lockout, a lockout your admin tooling already owns).
+ *
+ * Prefer {@link LockoutStore} when you only need the built-in policy to be
+ * shared across instances — that seam swaps storage, not the state machine.
+ * Like the class, an implementation decides state only: whether a locked
+ * account is refused is `IdentityService`'s `protectionMode`, never yours.
+ *
+ * @example
+ * ```ts
+ * import type { AccountLockoutLike } from "@udibo/oauth2/identity";
+ *
+ * declare const backoff: {
+ *   read(userId: string): Promise<{ failures: number; until?: number }>;
+ *   bump(userId: string): Promise<{ failures: number; until?: number }>;
+ *   clear(userId: string): Promise<void>;
+ * };
+ *
+ * const lockout: AccountLockoutLike = {
+ *   async status(userId, now = Date.now()) {
+ *     const { failures, until } = await backoff.read(userId);
+ *     const locked = until !== undefined && until > now;
+ *     return { locked, failures, lockedUntil: locked ? until : undefined };
+ *   },
+ *   async recordFailure(userId, now = Date.now()) {
+ *     const { failures, until } = await backoff.bump(userId);
+ *     const locked = until !== undefined && until > now;
+ *     return { failures, locked, justLocked: locked, lockedUntil: until };
+ *   },
+ *   reset: (userId) => backoff.clear(userId),
+ * };
+ * ```
+ */
+export interface AccountLockoutLike {
+    /** The account's current lock state. An expired lock must read as unlocked. */
+    status(userId: string, now?: number): Promise<LockoutStatus>;
+    /**
+     * Record one failed attempt and report the resulting state. `justLocked` must
+     * be true for exactly one attempt per lock — `IdentityService` fires the
+     * lockout event and any unlock email off it.
+     */
+    recordFailure(userId: string, now?: number): Promise<LockoutFailureResult>;
+    /** Clear the account's failures and any lock (successful sign-in, unlock). */
+    reset(userId: string): Promise<void>;
+}
+/**
+ * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
+ * lock) — the default {@link AccountLockoutLike}. Wire into
+ * {@link IdentityService} via its `lockout` option; call {@link reset} from
+ * your unlock flow.
+ */
+export declare class AccountLockout implements AccountLockoutLike {
+    #private;
+    /** Fixes thresholds and the backing store (defaults to {@linkcode MemoryLockoutStore}). */
+    constructor(options?: AccountLockoutOptions);
+    /** The account's current lock state. An expired lock reads as not locked. */
+    status(userId: string, now?: number): Promise<LockoutStatus>;
+    /**
+     * Record one failed attempt, locking the account when the consecutive-failure
+     * threshold is crossed. An attempt after a lock expired starts a fresh count.
+     */
+    recordFailure(userId: string, now?: number): Promise<LockoutFailureResult>;
+    /** Clear the account's failures and any lock (successful sign-in, unlock). */
+    reset(userId: string): Promise<void>;
+}
+/** In-memory {@link LockoutStore} for dev / single-process use. */
+export declare class MemoryLockoutStore implements LockoutStore {
+    #private;
+    /** The stored record for `userId`, if any. */
+    get(userId: string): Promise<LockoutRecord | undefined>;
+    /** Add one failure synchronously (atomic in a single-process store). */
+    increment(userId: string, now: number): Promise<LockoutRecord>;
+    /** Store `record` for `userId`. */
+    set(userId: string, record: LockoutRecord): Promise<void>;
+    /** Drop `userId`'s record. */
+    clear(userId: string): Promise<void>;
+}

package/esm/identity/lockout.js

@@ -0,0 +1,117 @@
+/**
+ * Failed-attempt account lockout — the brute-force floor for sign-in.
+ *
+ * Distinct from rate limiting: the {@link RateLimiter} throttles *attempts per
+ * window* keyed however you like (identifier, IP), while lockout tracks
+ * *consecutive failures per account* and locks the account for a cooldown once
+ * a threshold is crossed. Storage is a pluggable {@link LockoutStore}
+ * (a {@link MemoryLockoutStore} ships for dev/single-process; back it with your
+ * database to share state across instances — e.g. columns on your users table,
+ * which also gives admins visibility).
+ *
+ * `AccountLockout` is a pure state machine: it never decides whether to block.
+ * `IdentityService` consults it and applies its `protectionMode`
+ * (enforce vs log-only), so adopters can observe lockout behavior before
+ * turning it on.
+ *
+ * @module
+ */
+const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_LOCK_DURATION_MS = 15 * 60 * 1000;
+/**
+ * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
+ * lock) — the default {@link AccountLockoutLike}. Wire into
+ * {@link IdentityService} via its `lockout` option; call {@link reset} from
+ * your unlock flow.
+ */
+export class AccountLockout {
+    #maxAttempts;
+    #lockDurationMs;
+    #store;
+    /** Fixes thresholds and the backing store (defaults to {@linkcode MemoryLockoutStore}). */
+    constructor(options = {}) {
+        this.#maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.#lockDurationMs = options.lockDurationMs ?? DEFAULT_LOCK_DURATION_MS;
+        this.#store = options.store ?? new MemoryLockoutStore();
+    }
+    /** The account's current lock state. An expired lock reads as not locked. */
+    async status(userId, now = Date.now()) {
+        const record = await this.#store.get(userId);
+        if (!record)
+            return { locked: false, failures: 0 };
+        const locked = record.lockedUntil !== undefined && record.lockedUntil > now;
+        return {
+            locked,
+            failures: record.failures,
+            lockedUntil: locked ? record.lockedUntil : undefined,
+        };
+    }
+    /**
+     * Record one failed attempt, locking the account when the consecutive-failure
+     * threshold is crossed. An attempt after a lock expired starts a fresh count.
+     */
+    async recordFailure(userId, now = Date.now()) {
+        const record = await this.#store.increment(userId, now);
+        const { failures } = record;
+        if (record.lockedUntil !== undefined && record.lockedUntil > now) {
+            return {
+                failures,
+                locked: true,
+                justLocked: false,
+                lockedUntil: record.lockedUntil,
+            };
+        }
+        if (failures >= this.#maxAttempts) {
+            const lockedUntil = now + this.#lockDurationMs;
+            await this.#store.set(userId, { failures, lockedUntil });
+            // Concurrent attempts can overshoot the threshold before the lock lands;
+            // only the attempt that hits it exactly reports justLocked, so the
+            // lockout event (and any unlock email) fires once.
+            return {
+                failures,
+                locked: true,
+                justLocked: failures === this.#maxAttempts,
+                lockedUntil,
+            };
+        }
+        return { failures, locked: false, justLocked: false };
+    }
+    /** Clear the account's failures and any lock (successful sign-in, unlock). */
+    reset(userId) {
+        return this.#store.clear(userId);
+    }
+}
+/** In-memory {@link LockoutStore} for dev / single-process use. */
+export class MemoryLockoutStore {
+    #records = new Map();
+    /** The stored record for `userId`, if any. */
+    get(userId) {
+        return Promise.resolve(this.#records.get(userId));
+    }
+    /** Add one failure synchronously (atomic in a single-process store). */
+    increment(userId, now) {
+        const record = this.#records.get(userId);
+        const lockExpired = record?.lockedUntil !== undefined &&
+            record.lockedUntil <= now;
+        const next = record && !lockExpired
+            ? {
+                failures: record.failures + 1,
+                ...(record.lockedUntil !== undefined
+                    ? { lockedUntil: record.lockedUntil }
+                    : {}),
+            }
+            : { failures: 1 };
+        this.#records.set(userId, next);
+        return Promise.resolve(next);
+    }
+    /** Store `record` for `userId`. */
+    set(userId, record) {
+        this.#records.set(userId, record);
+        return Promise.resolve();
+    }
+    /** Drop `userId`'s record. */
+    clear(userId) {
+        this.#records.delete(userId);
+        return Promise.resolve();
+    }
+}