@udibo/oauth2 0.1.0

package/esm/identity/password.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Password hashing primitive for the identity self-service layer.
+ *
+ * Promotes the package's internal PBKDF2 helpers (previously reachable only via
+ * a relative import) to a public, documented service so apps stop hand-rolling
+ * password crypto — the single riskiest thing to reinvent. The built-in
+ * algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS} iterations
+ * with a constant-time verify. Want argon2 or scrypt instead? Implement
+ * {@link PasswordHasherLike} with your own dependency and pass it wherever a
+ * hasher is accepted — nothing in the package requires the concrete class.
+ *
+ * **Storage is yours.** Persist the whole {@link PasswordCredential} — including
+ * its `params` — on your user record and pass it back to
+ * {@link PasswordIdentityService.verify}. The package owns the crypto, not the
+ * database (the same thin-seam philosophy as `SessionStore`).
+ *
+ * @module
+ */
+/**
+ * Generates a cryptographically random salt for password hashing.
+ *
+ * @param length The number of bytes of randomness
+ * @returns The hex-encoded salt, twice `length` characters long
+ */
+export declare function generateSalt(length?: number): string;
+/**
+ * The PBKDF2-SHA-256 iteration count new credentials are minted at, matching
+ * current OWASP guidance. Raise it with `new PasswordIdentityService({
+ * iterations })` as hardware improves; stored credentials record what they were
+ * hashed with, so raising it only triggers a rehash on the owner's next sign-in.
+ */
+export declare const DEFAULT_PBKDF2_ITERATIONS = 600000;
+/**
+ * The iteration count a {@link PasswordCredential} with no `params` is assumed
+ * to have been hashed at — the package's original default. Credentials minted
+ * before `params` existed keep verifying against this, and
+ * {@link PasswordIdentityService.needsRehash} reports them as due for an
+ * upgrade.
+ */
+export declare const LEGACY_PBKDF2_ITERATIONS = 100000;
+/** The algorithm identifier {@link PasswordIdentityService} records and accepts. */
+export declare const PBKDF2_SHA256 = "pbkdf2-sha256";
+/**
+ * The work factor a stored credential was produced with, so a credential is
+ * self-describing and a later default change can tell old hashes from new.
+ */
+export interface PasswordHashParams {
+    /** Algorithm identifier; {@link PasswordIdentityService} only mints {@link PBKDF2_SHA256}. */
+    algorithm: string;
+    /** Iteration count the hash was derived with. */
+    iterations: number;
+}
+/**
+ * A stored password credential: the hash, the salt it used, and (for
+ * credentials minted since `params` existed) the work factor behind it.
+ *
+ * Persist all three fields. A credential with no `params` is interpreted as
+ * PBKDF2-SHA-256 at {@link LEGACY_PBKDF2_ITERATIONS}.
+ */
+export interface PasswordCredential {
+    /** Hex-encoded PBKDF2-SHA-256 digest. */
+    hash: string;
+    /** Hex-encoded random salt. */
+    salt: string;
+    /** Algorithm and work factor used; absent means the legacy default. */
+    params?: PasswordHashParams;
+}
+/**
+ * The password-hasher seam. {@link PasswordIdentityService} is the built-in
+ * PBKDF2 implementation; implement this yourself to plug in argon2, scrypt, or
+ * a hardware-backed hasher, and pass it as `IdentityService`'s `passwords`
+ * option.
+ *
+ * Implement the optional `needsRehash` to get rehash-on-successful-sign-in: the
+ * identity flows call it after a password verifies and, when it returns `true`,
+ * re-hash the just-verified password and persist the result.
+ */
+export interface PasswordHasherLike {
+    /** Hashes a new password into a credential to store. */
+    hash(password: string): Promise<PasswordCredential>;
+    /** Constant-time verify of a password against a stored credential. */
+    verify(password: string, credential: PasswordCredential): Promise<boolean>;
+    /**
+     * Whether a stored credential is weaker than what this hasher mints today.
+     * Only consulted for a credential that has just verified. Omit to opt out of
+     * rehash-on-sign-in.
+     */
+    needsRehash?(credential: PasswordCredential): boolean;
+}
+/**
+ * Hashes a password with salt using PBKDF2-SHA-256.
+ *
+ * Pass the same `iterations` to {@link verifyPassword} that you hashed with —
+ * a mismatch simply fails to verify. Prefer {@link PasswordIdentityService},
+ * which records the work factor on the credential so you never have to track it.
+ *
+ * @param password The password to hash
+ * @param salt The salt to use, from {@link generateSalt}
+ * @param iterations PBKDF2 iterations; defaults to {@link DEFAULT_PBKDF2_ITERATIONS}
+ * @returns The hex-encoded 256-bit digest
+ */
+export declare function hashPassword(password: string, salt: string, iterations?: number): Promise<string>;
+/**
+ * Verifies a password against a stored hash in constant time.
+ *
+ * @param password The password to verify
+ * @param salt The salt used for the hash
+ * @param hash The stored hash to compare against
+ * @param iterations The iterations the stored hash was derived with; defaults to {@link DEFAULT_PBKDF2_ITERATIONS}
+ * @returns Whether the password reproduces the stored hash
+ */
+export declare function verifyPassword(password: string, salt: string, hash: string, iterations?: number): Promise<boolean>;
+/** Options for {@link PasswordIdentityService}. */
+export interface PasswordIdentityServiceOptions {
+    /**
+     * PBKDF2 iterations new credentials are minted at. Defaults to
+     * {@link DEFAULT_PBKDF2_ITERATIONS}. Raising it costs login latency (roughly
+     * linear) and makes every older credential report `needsRehash`.
+     */
+    iterations?: number;
+}
+/**
+ * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time verify).
+ * Construct once and reuse.
+ *
+ * Verification reads the work factor off the credential, so credentials minted
+ * under an older default keep verifying; {@link needsRehash} tells you when one
+ * is due for an upgrade (`IdentityService` does this for you on sign-in).
+ *
+ * @example
+ * ```ts
+ * import {
+ *   type IdentityUserStore,
+ *   PasswordIdentityService,
+ * } from "@udibo/oauth2/identity";
+ *
+ * interface User { id: string }
+ *
+ * declare const store: IdentityUserStore<User>;
+ * declare const userId: string;
+ *
+ * const passwords = new PasswordIdentityService();
+ * const credential = await passwords.hash("hunter2");   // { hash, salt, params }
+ * // …store credential on the user…
+ * const ok = await passwords.verify("hunter2", credential);
+ * if (ok && passwords.needsRehash(credential)) {
+ *   await store.setCredential(userId, await passwords.hash("hunter2"));
+ * }
+ * ```
+ */
+export declare class PasswordIdentityService implements PasswordHasherLike {
+    #private;
+    /** Applies the iteration default; construct with no arguments for it. */
+    constructor(options?: PasswordIdentityServiceOptions);
+    /** The PBKDF2 iteration count this instance mints new credentials at. */
+    get iterations(): number;
+    /** Hashes a new password, generating a fresh random salt. */
+    hash(password: string): Promise<PasswordCredential>;
+    /**
+     * Constant-time verify of a password against a stored credential, using the
+     * credential's own recorded work factor. Resolves `false` for a credential
+     * recorded under an algorithm this service does not implement.
+     */
+    verify(password: string, credential: PasswordCredential): Promise<boolean>;
+    /**
+     * Whether the credential was produced with a weaker configuration than this
+     * service mints today — call it after a successful {@link verify} and, when
+     * `true`, re-hash the verified password and persist the new credential.
+     */
+    needsRehash(credential: PasswordCredential): boolean;
+}

package/esm/identity/password.js

@@ -0,0 +1,160 @@
+/**
+ * Password hashing primitive for the identity self-service layer.
+ *
+ * Promotes the package's internal PBKDF2 helpers (previously reachable only via
+ * a relative import) to a public, documented service so apps stop hand-rolling
+ * password crypto — the single riskiest thing to reinvent. The built-in
+ * algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS} iterations
+ * with a constant-time verify. Want argon2 or scrypt instead? Implement
+ * {@link PasswordHasherLike} with your own dependency and pass it wherever a
+ * hasher is accepted — nothing in the package requires the concrete class.
+ *
+ * **Storage is yours.** Persist the whole {@link PasswordCredential} — including
+ * its `params` — on your user record and pass it back to
+ * {@link PasswordIdentityService.verify}. The package owns the crypto, not the
+ * database (the same thin-seam philosophy as `SessionStore`).
+ *
+ * @module
+ */
+import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.11/mod.js";
+import { timingSafeEqual } from "../deps/jsr.io/@std/crypto/1.1.0/timing_safe_equal.js";
+/**
+ * Generates a cryptographically random salt for password hashing.
+ *
+ * @param length The number of bytes of randomness
+ * @returns The hex-encoded salt, twice `length` characters long
+ */
+export function generateSalt(length = 16) {
+    const salt = new Uint8Array(length);
+    crypto.getRandomValues(salt);
+    return encodeHex(salt);
+}
+const encoder = new TextEncoder();
+/**
+ * The PBKDF2-SHA-256 iteration count new credentials are minted at, matching
+ * current OWASP guidance. Raise it with `new PasswordIdentityService({
+ * iterations })` as hardware improves; stored credentials record what they were
+ * hashed with, so raising it only triggers a rehash on the owner's next sign-in.
+ */
+export const DEFAULT_PBKDF2_ITERATIONS = 600_000;
+/**
+ * The iteration count a {@link PasswordCredential} with no `params` is assumed
+ * to have been hashed at — the package's original default. Credentials minted
+ * before `params` existed keep verifying against this, and
+ * {@link PasswordIdentityService.needsRehash} reports them as due for an
+ * upgrade.
+ */
+export const LEGACY_PBKDF2_ITERATIONS = 100_000;
+/** The algorithm identifier {@link PasswordIdentityService} records and accepts. */
+export const PBKDF2_SHA256 = "pbkdf2-sha256";
+/**
+ * Hashes a password with salt using PBKDF2-SHA-256.
+ *
+ * Pass the same `iterations` to {@link verifyPassword} that you hashed with —
+ * a mismatch simply fails to verify. Prefer {@link PasswordIdentityService},
+ * which records the work factor on the credential so you never have to track it.
+ *
+ * @param password The password to hash
+ * @param salt The salt to use, from {@link generateSalt}
+ * @param iterations PBKDF2 iterations; defaults to {@link DEFAULT_PBKDF2_ITERATIONS}
+ * @returns The hex-encoded 256-bit digest
+ */
+export async function hashPassword(password, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
+    const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits", "deriveKey"]);
+    const derivedBits = await crypto.subtle.deriveBits({
+        name: "PBKDF2",
+        salt: encoder.encode(salt),
+        iterations,
+        hash: "SHA-256",
+    }, keyMaterial, 256);
+    return encodeHex(new Uint8Array(derivedBits, 0, 32));
+}
+/**
+ * Verifies a password against a stored hash in constant time.
+ *
+ * @param password The password to verify
+ * @param salt The salt used for the hash
+ * @param hash The stored hash to compare against
+ * @param iterations The iterations the stored hash was derived with; defaults to {@link DEFAULT_PBKDF2_ITERATIONS}
+ * @returns Whether the password reproduces the stored hash
+ */
+export async function verifyPassword(password, salt, hash, iterations = DEFAULT_PBKDF2_ITERATIONS) {
+    const computedHash = await hashPassword(password, salt, iterations);
+    // Both are fixed-width hex digests, so length carries no secret.
+    if (computedHash.length !== hash.length)
+        return false;
+    return timingSafeEqual(encoder.encode(computedHash), encoder.encode(hash));
+}
+/**
+ * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time verify).
+ * Construct once and reuse.
+ *
+ * Verification reads the work factor off the credential, so credentials minted
+ * under an older default keep verifying; {@link needsRehash} tells you when one
+ * is due for an upgrade (`IdentityService` does this for you on sign-in).
+ *
+ * @example
+ * ```ts
+ * import {
+ *   type IdentityUserStore,
+ *   PasswordIdentityService,
+ * } from "@udibo/oauth2/identity";
+ *
+ * interface User { id: string }
+ *
+ * declare const store: IdentityUserStore<User>;
+ * declare const userId: string;
+ *
+ * const passwords = new PasswordIdentityService();
+ * const credential = await passwords.hash("hunter2");   // { hash, salt, params }
+ * // …store credential on the user…
+ * const ok = await passwords.verify("hunter2", credential);
+ * if (ok && passwords.needsRehash(credential)) {
+ *   await store.setCredential(userId, await passwords.hash("hunter2"));
+ * }
+ * ```
+ */
+export class PasswordIdentityService {
+    #iterations;
+    /** Applies the iteration default; construct with no arguments for it. */
+    constructor(options = {}) {
+        this.#iterations = options.iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+    }
+    /** The PBKDF2 iteration count this instance mints new credentials at. */
+    get iterations() {
+        return this.#iterations;
+    }
+    /** Hashes a new password, generating a fresh random salt. */
+    async hash(password) {
+        const salt = generateSalt();
+        return {
+            salt,
+            hash: await hashPassword(password, salt, this.#iterations),
+            params: { algorithm: PBKDF2_SHA256, iterations: this.#iterations },
+        };
+    }
+    /**
+     * Constant-time verify of a password against a stored credential, using the
+     * credential's own recorded work factor. Resolves `false` for a credential
+     * recorded under an algorithm this service does not implement.
+     */
+    verify(password, credential) {
+        const params = credential.params;
+        if (params && params.algorithm !== PBKDF2_SHA256) {
+            return Promise.resolve(false);
+        }
+        return verifyPassword(password, credential.salt, credential.hash, params?.iterations ?? LEGACY_PBKDF2_ITERATIONS);
+    }
+    /**
+     * Whether the credential was produced with a weaker configuration than this
+     * service mints today — call it after a successful {@link verify} and, when
+     * `true`, re-hash the verified password and persist the new credential.
+     */
+    needsRehash(credential) {
+        const params = credential.params;
+        if (!params)
+            return LEGACY_PBKDF2_ITERATIONS < this.#iterations;
+        return params.algorithm !== PBKDF2_SHA256 ||
+            params.iterations < this.#iterations;
+    }
+}

package/esm/identity/rate-limit.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Fixed-window rate limiting for auth endpoints — throttle sign-in attempts,
+ * forgot-password requests, etc. Two seams sit here: {@link RateLimitStore}
+ * swaps the counter storage (a {@link MemoryRateLimitStore} ships for
+ * dev/single-process; back it with Redis/DB to share limits across instances),
+ * and {@link RateLimiterLike} swaps the limiter itself when a fixed window is
+ * not the algorithm you want. Tenant-agnostic: scope by keying on whatever you
+ * like (IP, identifier, `tenant:ip`).
+ *
+ * @module
+ */
+import type { IdentityEvent, RateLimitedEventInit } from "./events.js";
+/** Pluggable counter store for {@link RateLimiter}. */
+export interface RateLimitStore {
+    /**
+     * Increment `key`'s counter within its current window, returning the new
+     * count and when the window resets. Implementations start a fresh window
+     * (count 1, `resetAt = now + windowMs`) when none is active, and report the
+     * same `resetAt` for every hit inside one window — a window that slides
+     * forward on each hit never resets under sustained traffic. Must be atomic
+     * (a single statement / compare-and-set in shared stores) — a
+     * read-modify-write here lets concurrent attempts lose counts and slip past
+     * the threshold, which is exactly the burst the limiter exists to catch.
+     *
+     * Key cardinality is caller-controlled and often derived from
+     * unauthenticated request input, so bound what you keep: a TTL per key on
+     * Redis, a scheduled delete past `resetAt` on SQL.
+     */
+    increment(key: string, windowMs: number, now: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Clear `key`'s counter (e.g. on a successful sign-in). */
+    reset(key: string): Promise<void>;
+}
+/** The outcome of a {@link RateLimiter.check}. */
+export interface RateLimitResult {
+    /** Whether this hit is within the limit. */
+    allowed: boolean;
+    /** Hits remaining in the current window (0 when blocked). */
+    remaining: number;
+    /** When the window resets, epoch ms. */
+    resetAt: number;
+    /** ms until the caller may retry (0 when allowed). */
+    retryAfterMs: number;
+}
+/**
+ * The limiter contract every identity flow accepts — the bring-your-own-limiter
+ * seam. {@link RateLimiter} is the shipped fixed-window implementation and
+ * satisfies it; implement this directly to run a sliding window, a token
+ * bucket, IP reputation, or a limiter you already operate. Everything but the
+ * {@link RateLimitResult} is yours: the window arithmetic and the allow/deny
+ * decision never leave your implementation.
+ *
+ * Prefer {@link RateLimitStore} when you only need the built-in fixed window to
+ * be shared across instances — that seam swaps storage, not the algorithm.
+ *
+ * @example
+ * ```ts
+ * import type { RateLimiterLike } from "@udibo/oauth2/identity";
+ *
+ * declare const myLimiter: {
+ *   consume(key: string): Promise<{ ok: boolean; msBeforeNext: number }>;
+ *   delete(key: string): Promise<void>;
+ * };
+ *
+ * const rateLimiter: RateLimiterLike = {
+ *   async check(key, now = Date.now()) {
+ *     const { ok, msBeforeNext } = await myLimiter.consume(key);
+ *     return {
+ *       allowed: ok,
+ *       remaining: 0,
+ *       resetAt: now + msBeforeNext,
+ *       retryAfterMs: ok ? 0 : msBeforeNext,
+ *     };
+ *   },
+ *   reset: (key) => myLimiter.delete(key),
+ * };
+ * ```
+ */
+export interface RateLimiterLike {
+    /** Record a hit for `key` and report whether it is within the limit. */
+    check(key: string, now?: number): Promise<RateLimitResult>;
+    /** Clear `key`'s counter (e.g. on a successful sign-in). */
+    reset(key: string): Promise<void>;
+}
+/** Options for {@link RateLimiter}. */
+export interface RateLimiterOptions {
+    /** Max hits per window. Defaults to 10 — a sane sign-in floor. */
+    limit?: number;
+    /** Window length in ms. Defaults to 15 minutes. */
+    windowMs?: number;
+    /** Counter storage. Defaults to {@link MemoryRateLimitStore}. */
+    store?: RateLimitStore;
+}
+/**
+ * Fixed-window limiter — the default {@link RateLimiterLike}, deliberately
+ * feature-frozen as a floor rather than a product. Swap in your own
+ * `RateLimiterLike` for anything the fixed window cannot express.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000 });
+ * const r = await limiter.check(`signin:${ip}`);
+ * if (!r.allowed) throw new IdentityError("rate_limited", undefined, { retryAfterMs: r.retryAfterMs });
+ * // …on success: await limiter.reset(`signin:${ip}`);
+ * ```
+ */
+export declare class RateLimiter implements RateLimiterLike {
+    #private;
+    /** Fixes the `limit`/`windowMs` and the backing store (defaults to {@linkcode MemoryRateLimitStore}). */
+    constructor(options?: RateLimiterOptions);
+    /** Record a hit for `key` and report whether it is within the limit. */
+    check(key: string, now?: number): Promise<RateLimitResult>;
+    /** Clear `key`'s counter. */
+    reset(key: string): Promise<void>;
+}
+/**
+ * How a throttled flow reports hitting its limit. Both halves travel together
+ * or neither does — supplying one without the other would type-check into a
+ * silently dropped audit event.
+ */
+type RateLimitReport = {
+    /** The flow's `*.rate_limited` event, minus the fields filled in here. */
+    event: RateLimitedEventInit;
+    /** The service's event emitter (already hook-safe, never throws). */
+    emit: (event: IdentityEvent) => Promise<void>;
+} | {
+    /** Omitted in a flow whose service exposes no event seam. */
+    event?: never;
+    emit?: never;
+};
+/** Options for {@link enforceRateLimit}. */
+export type EnforceRateLimitOptions = {
+    /** The limiter to check; `undefined` disables throttling entirely. */
+    rateLimiter: RateLimiterLike | undefined;
+    /** The limiter key (e.g. `signin:${identifier}`, `mfa:verify:${userId}`). */
+    key: string;
+    /** The `IdentityError` message when the limit is hit under enforcement. */
+    message: string;
+    /** `false` (log-only mode) emits the event but lets the attempt through. */
+    enforce: boolean;
+} & RateLimitReport;
+/**
+ * The shared throttle sequence every identity-layer flow uses: check the
+ * limiter, and when the limit is hit emit the flow's `*.rate_limited` event
+ * (when the caller supplies `event` + `emit`) and — under enforcement — throw.
+ * No-op without a limiter.
+ *
+ * A BYO {@link RateLimiterLike.check} that **throws** is trapped: under
+ * enforcement it surfaces as the same `rate_limited` error (fail closed, so a
+ * broken limiter denies rather than leaking a raw error), and in log-only mode
+ * it is logged and lets the attempt through (the mode's promise never to
+ * block). A limiter that itself throws an {@link IdentityError} is preserved.
+ *
+ * @throws {IdentityError} `rate_limited` (with `retryAfterMs`) when the limit
+ * is hit and `enforce` is `true`.
+ */
+export declare function enforceRateLimit(options: EnforceRateLimitOptions): Promise<void>;
+/**
+ * In-memory {@link RateLimitStore} for dev / single-process use. Counters are
+ * per-process, so replicas do not share limits — back {@link RateLimiter} with
+ * Redis or a database in production.
+ *
+ * Bounded on purpose: limiter keys are built from unauthenticated request
+ * input, so the store is capped at 10,000 buckets and evicts to stay under it.
+ * Eviction takes lapsed buckets first, then the buckets with the fewest hits,
+ * so a unique-key flood discards its own counters rather than one that is
+ * close to blocking. The residual is real: an attacker able to push ~10,000
+ * keys above a live counter's hit count can still displace it.
+ */
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    #private;
+    /**
+     * How many buckets are currently retained — never more than the 10,000-bucket
+     * cap. Exposed so a test or a dev-time probe can see the guardrail working;
+     * it is not part of the {@link RateLimitStore} contract.
+     */
+    get size(): number;
+    /**
+     * Bump `key`'s counter, opening a fresh window when the current one has
+     * lapsed. Atomic by virtue of being synchronous in a single process. May
+     * evict other keys' buckets to stay under the store's capacity.
+     */
+    increment(key: string, windowMs: number, now: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Forget `key`'s bucket so its next hit starts a new window. */
+    reset(key: string): Promise<void>;
+}
+export {};

package/esm/identity/rate-limit.js

@@ -0,0 +1,168 @@
+/**
+ * Fixed-window rate limiting for auth endpoints — throttle sign-in attempts,
+ * forgot-password requests, etc. Two seams sit here: {@link RateLimitStore}
+ * swaps the counter storage (a {@link MemoryRateLimitStore} ships for
+ * dev/single-process; back it with Redis/DB to share limits across instances),
+ * and {@link RateLimiterLike} swaps the limiter itself when a fixed window is
+ * not the algorithm you want. Tenant-agnostic: scope by keying on whatever you
+ * like (IP, identifier, `tenant:ip`).
+ *
+ * @module
+ */
+import { IdentityError } from "./errors.js";
+const DEFAULT_LIMIT = 10;
+const DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+/**
+ * Fixed-window limiter — the default {@link RateLimiterLike}, deliberately
+ * feature-frozen as a floor rather than a product. Swap in your own
+ * `RateLimiterLike` for anything the fixed window cannot express.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000 });
+ * const r = await limiter.check(`signin:${ip}`);
+ * if (!r.allowed) throw new IdentityError("rate_limited", undefined, { retryAfterMs: r.retryAfterMs });
+ * // …on success: await limiter.reset(`signin:${ip}`);
+ * ```
+ */
+export class RateLimiter {
+    #limit;
+    #windowMs;
+    #store;
+    /** Fixes the `limit`/`windowMs` and the backing store (defaults to {@linkcode MemoryRateLimitStore}). */
+    constructor(options = {}) {
+        this.#limit = options.limit ?? DEFAULT_LIMIT;
+        this.#windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+        this.#store = options.store ?? new MemoryRateLimitStore();
+    }
+    /** Record a hit for `key` and report whether it is within the limit. */
+    async check(key, now = Date.now()) {
+        const { count, resetAt } = await this.#store.increment(key, this.#windowMs, now);
+        const allowed = count <= this.#limit;
+        return {
+            allowed,
+            remaining: Math.max(0, this.#limit - count),
+            resetAt,
+            retryAfterMs: allowed ? 0 : Math.max(0, resetAt - now),
+        };
+    }
+    /** Clear `key`'s counter. */
+    reset(key) {
+        return this.#store.reset(key);
+    }
+}
+/**
+ * The shared throttle sequence every identity-layer flow uses: check the
+ * limiter, and when the limit is hit emit the flow's `*.rate_limited` event
+ * (when the caller supplies `event` + `emit`) and — under enforcement — throw.
+ * No-op without a limiter.
+ *
+ * A BYO {@link RateLimiterLike.check} that **throws** is trapped: under
+ * enforcement it surfaces as the same `rate_limited` error (fail closed, so a
+ * broken limiter denies rather than leaking a raw error), and in log-only mode
+ * it is logged and lets the attempt through (the mode's promise never to
+ * block). A limiter that itself throws an {@link IdentityError} is preserved.
+ *
+ * @throws {IdentityError} `rate_limited` (with `retryAfterMs`) when the limit
+ * is hit and `enforce` is `true`.
+ */
+export async function enforceRateLimit(options) {
+    if (!options.rateLimiter)
+        return;
+    let result;
+    try {
+        result = await options.rateLimiter.check(options.key);
+    }
+    catch (error) {
+        if (error instanceof IdentityError)
+            throw error;
+        if (!options.enforce) {
+            console.error("[@udibo/oauth2] rate limiter check failed (log-only, allowing):", error instanceof Error ? error.message : error);
+            return;
+        }
+        throw new IdentityError("rate_limited", options.message, { cause: error });
+    }
+    if (result.allowed)
+        return;
+    if (options.event && options.emit) {
+        await options.emit({
+            ...options.event,
+            retryAfterMs: result.retryAfterMs,
+            enforced: options.enforce,
+        });
+    }
+    if (options.enforce) {
+        throw new IdentityError("rate_limited", options.message, {
+            retryAfterMs: result.retryAfterMs,
+        });
+    }
+}
+const MAX_BUCKETS = 10_000;
+const SWEEP_INTERVAL = 1_000;
+const EVICTION_TARGET = 9_000;
+/**
+ * In-memory {@link RateLimitStore} for dev / single-process use. Counters are
+ * per-process, so replicas do not share limits — back {@link RateLimiter} with
+ * Redis or a database in production.
+ *
+ * Bounded on purpose: limiter keys are built from unauthenticated request
+ * input, so the store is capped at 10,000 buckets and evicts to stay under it.
+ * Eviction takes lapsed buckets first, then the buckets with the fewest hits,
+ * so a unique-key flood discards its own counters rather than one that is
+ * close to blocking. The residual is real: an attacker able to push ~10,000
+ * keys above a live counter's hit count can still displace it.
+ */
+export class MemoryRateLimitStore {
+    #buckets = new Map();
+    #writesSinceSweep = 0;
+    /**
+     * How many buckets are currently retained — never more than the 10,000-bucket
+     * cap. Exposed so a test or a dev-time probe can see the guardrail working;
+     * it is not part of the {@link RateLimitStore} contract.
+     */
+    get size() {
+        return this.#buckets.size;
+    }
+    /**
+     * Bump `key`'s counter, opening a fresh window when the current one has
+     * lapsed. Atomic by virtue of being synchronous in a single process. May
+     * evict other keys' buckets to stay under the store's capacity.
+     */
+    increment(key, windowMs, now) {
+        let bucket = this.#buckets.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { count: 0, resetAt: now + windowMs };
+            this.#buckets.set(key, bucket);
+        }
+        bucket.count++;
+        this.#collect(now);
+        return Promise.resolve({ count: bucket.count, resetAt: bucket.resetAt });
+    }
+    /** Forget `key`'s bucket so its next hit starts a new window. */
+    reset(key) {
+        this.#buckets.delete(key);
+        return Promise.resolve();
+    }
+    #collect(now) {
+        if (++this.#writesSinceSweep >= SWEEP_INTERVAL)
+            this.#dropLapsed(now);
+        if (this.#buckets.size <= MAX_BUCKETS)
+            return;
+        this.#dropLapsed(now);
+        if (this.#buckets.size <= MAX_BUCKETS)
+            return;
+        this.#dropColdest(this.#buckets.size - EVICTION_TARGET);
+    }
+    #dropLapsed(now) {
+        this.#writesSinceSweep = 0;
+        for (const [key, bucket] of this.#buckets) {
+            if (bucket.resetAt <= now)
+                this.#buckets.delete(key);
+        }
+    }
+    #dropColdest(count) {
+        const ordered = [...this.#buckets].sort((a, b) => a[1].count - b[1].count || a[1].resetAt - b[1].resetAt);
+        for (const [key] of ordered.slice(0, count))
+            this.#buckets.delete(key);
+    }
+}