@udibo/oauth2 0.17.1 → 0.18.0

package/dist/client/direct-client.d.ts

@@ -79,21 +79,33 @@ export interface DirectClientOptions extends BaseOptions {
     discoveryCache?: DiscoveryCache;
     /** Access-token storage. Defaults to {@link MemoryTokenStorage}. */
     tokenStorage?: TokenStorage;
-    /** Refresh-token storage. Defaults to {@link MemoryRefreshTokenStorage}. */
-    refreshTokenStorage?: RefreshTokenStorage;
     /**
-     * Auth-request storage.
+     * Refresh-token storage.
      *
-     * Defaults to {@link SessionStorageAuthRequestStorage} in a browser document
-     * and {@link MemoryAuthRequestStorage} everywhere else. The browser default
-     * is what makes the authorize redirect work at all: an in-memory record does
-     * not survive the navigation away and back, so the callback rejects every
-     * `state` as unknown. Servers keep the in-memory default so a per-request
-     * client does not write pending logins into one process-wide store.
+     * In a browser document it defaults to {@link MemoryRefreshTokenStorage},
+     * which the tab loses on reload; pass `IndexedDBRefreshTokenStorage` to keep
+     * it. Outside a browser there is no default: a sign-in or device
+     * authorization that would store a refresh token throws a `TypeError` until
+     * one is passed. Pass storage that outlives the process, such as a database
+     * or the operating system's keychain, or {@link MemoryRefreshTokenStorage}
+     * for a single process, tests and local development. Client-credentials
+     * use needs none.
+     */
+    refreshTokenStorage?: RefreshTokenStorage;
+    /**
+     * Where a pending sign-in (`state` → PKCE verifier, return-to) waits for
+     * its callback.
      *
-     * Override it when the record must live somewhere else — a per-request
-     * cookie store on a server, or a store scoped to something other than the
-     * tab.
+     * In a browser document it defaults to
+     * {@link SessionStorageAuthRequestStorage}, which survives the navigation
+     * to the authorization server and back. Outside a browser there is no
+     * default: {@link DirectClient.login} and
+     * {@link DirectClient.exchangeAuthorizationCode} throw a `TypeError` unless
+     * this or their per-call `authRequestStorage` is given, because the
+     * callback can reach a different instance than the one that started the
+     * sign-in. Pass storage every instance shares, a per-request store on each
+     * call, or {@link MemoryAuthRequestStorage} for a single process, tests and
+     * local development. Client-credentials use needs none.
      */
     authRequestStorage?: AuthRequestStorage;
     /**
@@ -362,6 +374,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * authorize URL, override `redirect_uri`, or bind the pending request to a
      * per-request store.
      * @returns The authorize URL and the `state` the callback will echo back.
+     * @throws {TypeError} outside a browser when neither the client nor this
+     * call has an `authRequestStorage`.
      * @throws {Error} when no authorization endpoint is configured or
      * discoverable.
      *
@@ -395,7 +409,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * `cause` is the transport failure.
      * @throws {OAuth2Error} when the callback carries `?error=…`, or the token
      * exchange fails.
-     * @throws {TypeError} when `code` or `state` is missing.
+     * @throws {TypeError} when `code` or `state` is missing, or outside a
+     * browser when the client has no `authRequestStorage` or no
+     * `refreshTokenStorage`; checked before the pending request is claimed.
      * @throws {InvalidGrantError} when `state` is unknown or expired.
      *
      * @example
@@ -436,6 +452,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * which must match what {@link login} was given.
      * @returns The tokens, the rotated refresh token, and the recorded
      * `returnTo`, plus the raw response.
+     * @throws {TypeError} outside a browser when neither the client nor this
+     * call has an `authRequestStorage`.
      * @throws {InvalidGrantError} when `state` is unknown or older than
      * `authRequestTtlMs`.
      * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
@@ -530,6 +548,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      *
      * @param options `scope` overrides the client's default scope string.
      * @returns The server's device authorization response.
+     * @throws {TypeError} outside a browser when the client has no
+     * `refreshTokenStorage` for the tokens {@link pollDeviceToken} will keep.
      * @throws {Error} when no device authorization endpoint is configured or
      * discoverable.
      * @throws {TemporarilyUnavailableError} when the device authorization
@@ -563,6 +583,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * authorization response so polling respects the server's advertised
      * minimum interval and deadline, and `signal` to cancel.
      * @returns The persisted token bundle.
+     * @throws {TypeError} outside a browser when the client has no
+     * `refreshTokenStorage`.
      * @throws {AccessDeniedError} when `signal` aborts, or the user declines.
      * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
      * server that reports the code expired first throws `ExpiredTokenError`

package/dist/client/direct-client.js

@@ -120,11 +120,11 @@ export class DirectClient extends OAuth2ClientBase {
         this.#endpoints = { ...options.endpoints };
         this.#tokenStorage = options.tokenStorage ?? new MemoryTokenStorage();
         this.#refreshTokenStorage =
-            options.refreshTokenStorage ?? new MemoryRefreshTokenStorage();
+            options.refreshTokenStorage ?? browserRefreshTokenStorage();
         this.#authRequestTtlMs = options.authRequestTtlMs ?? 10 * 60 * 1000;
         this.#authRequestStorage =
             options.authRequestStorage ??
-                defaultAuthRequestStorage(this.#authRequestTtlMs);
+                browserAuthRequestStorage(this.#authRequestTtlMs);
     }
     /** True when the client was given a secret and authenticates via Basic. */
     get isConfidential() {
@@ -322,6 +322,8 @@ export class DirectClient extends OAuth2ClientBase {
      * authorize URL, override `redirect_uri`, or bind the pending request to a
      * per-request store.
      * @returns The authorize URL and the `state` the callback will echo back.
+     * @throws {TypeError} outside a browser when neither the client nor this
+     * call has an `authRequestStorage`.
      * @throws {Error} when no authorization endpoint is configured or
      * discoverable.
      *
@@ -338,6 +340,7 @@ export class DirectClient extends OAuth2ClientBase {
      * ```
      */
     async login(options = {}) {
+        const authRequestStorage = options.authRequestStorage ?? this.#requireAuthRequestStorage();
         const baseAuthEndpoint = await this.#requireEndpoint("authorization");
         const authEndpoint = options.origin
             ? withOrigin(baseAuthEndpoint, options.origin)
@@ -347,7 +350,6 @@ export class DirectClient extends OAuth2ClientBase {
         const codeVerifier = generateCodeVerifier();
         const codeChallenge = await challengeMethods.S256(codeVerifier);
         const scope = options.scope ?? this.#scope;
-        const authRequestStorage = options.authRequestStorage ?? this.#authRequestStorage;
         await authRequestStorage.set(state, {
             codeVerifier,
             returnTo: options.returnTo,
@@ -388,7 +390,9 @@ export class DirectClient extends OAuth2ClientBase {
      * `cause` is the transport failure.
      * @throws {OAuth2Error} when the callback carries `?error=…`, or the token
      * exchange fails.
-     * @throws {TypeError} when `code` or `state` is missing.
+     * @throws {TypeError} when `code` or `state` is missing, or outside a
+     * browser when the client has no `authRequestStorage` or no
+     * `refreshTokenStorage`; checked before the pending request is claimed.
      * @throws {InvalidGrantError} when `state` is unknown or expired.
      *
      * @example
@@ -418,6 +422,13 @@ export class DirectClient extends OAuth2ClientBase {
             this.emit({ type: "error", error: instance });
             return Promise.reject(instance);
         }
+        try {
+            this.#requireAuthRequestStorage();
+            this.#requireRefreshTokenStorage();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
         const code = params.get("code");
         const state = params.get("state");
         if (!code)
@@ -467,6 +478,8 @@ export class DirectClient extends OAuth2ClientBase {
      * which must match what {@link login} was given.
      * @returns The tokens, the rotated refresh token, and the recorded
      * `returnTo`, plus the raw response.
+     * @throws {TypeError} outside a browser when neither the client nor this
+     * call has an `authRequestStorage`.
      * @throws {InvalidGrantError} when `state` is unknown or older than
      * `authRequestTtlMs`.
      * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
@@ -474,7 +487,7 @@ export class DirectClient extends OAuth2ClientBase {
      * `cause` is the transport failure.
      */
     async exchangeAuthorizationCode(code, state, options = {}) {
-        const authRequestStorage = options.authRequestStorage ?? this.#authRequestStorage;
+        const authRequestStorage = options.authRequestStorage ?? this.#requireAuthRequestStorage();
         const record = await claimAuthRequest(authRequestStorage, state);
         if (!record)
             throw new InvalidGrantError("unknown state parameter");
@@ -656,7 +669,7 @@ export class DirectClient extends OAuth2ClientBase {
     }
     async #readRefreshToken(reportTransient) {
         try {
-            return await this.#refreshTokenStorage.get();
+            return (await this.#refreshTokenStorage?.get()) ?? null;
         }
         catch (error) {
             if (reportTransient)
@@ -671,6 +684,8 @@ export class DirectClient extends OAuth2ClientBase {
      *
      * @param options `scope` overrides the client's default scope string.
      * @returns The server's device authorization response.
+     * @throws {TypeError} outside a browser when the client has no
+     * `refreshTokenStorage` for the tokens {@link pollDeviceToken} will keep.
      * @throws {Error} when no device authorization endpoint is configured or
      * discoverable.
      * @throws {TemporarilyUnavailableError} when the device authorization
@@ -692,6 +707,7 @@ export class DirectClient extends OAuth2ClientBase {
      * ```
      */
     async startDeviceAuthorization(options = {}) {
+        this.#requireRefreshTokenStorage();
         const endpoint = await this.#requireEndpoint("deviceAuthorization");
         const body = new URLSearchParams({ client_id: this.#clientId });
         const scope = options.scope ?? this.#scope;
@@ -717,6 +733,8 @@ export class DirectClient extends OAuth2ClientBase {
      * authorization response so polling respects the server's advertised
      * minimum interval and deadline, and `signal` to cancel.
      * @returns The persisted token bundle.
+     * @throws {TypeError} outside a browser when the client has no
+     * `refreshTokenStorage`.
      * @throws {AccessDeniedError} when `signal` aborts, or the user declines.
      * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
      * server that reports the code expired first throws `ExpiredTokenError`
@@ -727,6 +745,7 @@ export class DirectClient extends OAuth2ClientBase {
      * @throws {OAuth2Error} on any other terminal error from the server.
      */
     async pollDeviceToken(deviceCode, options = {}) {
+        this.#requireRefreshTokenStorage();
         const version = ++this.#sessionVersion;
         let interval = Math.max(1, options.interval ?? 5);
         const deadline = options.expiresAt ?? Infinity;
@@ -1038,7 +1057,7 @@ export class DirectClient extends OAuth2ClientBase {
                 ? Math.round((tokens.accessTokenExpiresAt - Date.now()) / 1000)
                 : null;
             if (expiresIn !== null && expiresIn <= 0) {
-                const revivable = await this.#refreshTokenStorage.get();
+                const revivable = await this.#refreshTokenStorage?.get();
                 if (!revivable)
                     return SIGNED_OUT;
             }
@@ -1116,6 +1135,18 @@ export class DirectClient extends OAuth2ClientBase {
         }
         return await this.#sharedRefresh(!quiet);
     }
+    #requireAuthRequestStorage() {
+        if (!this.#authRequestStorage) {
+            throw new TypeError(MISSING_AUTH_REQUEST_STORAGE);
+        }
+        return this.#authRequestStorage;
+    }
+    #requireRefreshTokenStorage() {
+        if (!this.#refreshTokenStorage) {
+            throw new TypeError(MISSING_REFRESH_TOKEN_STORAGE);
+        }
+        return this.#refreshTokenStorage;
+    }
     #basicAuth() {
         return encodeBasicAuth(this.#clientId, this.#clientSecret);
     }
@@ -1154,10 +1185,10 @@ export class DirectClient extends OAuth2ClientBase {
             const bundle = responseToBundle(response);
             await this.#tokenStorage.set(bundle);
             if (response.refresh_token) {
-                await this.#refreshTokenStorage.set(response.refresh_token);
+                await this.#refreshTokenStorage?.set(response.refresh_token);
             }
             else if (!preserveRefreshToken) {
-                await this.#refreshTokenStorage.clear();
+                await this.#refreshTokenStorage?.clear();
             }
             if (version !== this.#sessionVersion) {
                 throw new InvalidGrantError("session changed during token exchange");
@@ -1177,8 +1208,8 @@ export class DirectClient extends OAuth2ClientBase {
         this.#sessionVersion++;
         return this.#mutateSession(async () => {
             await this.#tokenStorage.clear();
-            await this.#refreshTokenStorage.clear();
-            await this.#authRequestStorage.clear();
+            await this.#refreshTokenStorage?.clear();
+            await this.#authRequestStorage?.clear();
         });
     }
 }
@@ -1230,12 +1261,31 @@ function toSearchParams(input) {
         return new URLSearchParams(input.startsWith("?") ? input.slice(1) : input);
     }
 }
-function defaultAuthRequestStorage(ttlMs) {
-    const inBrowserDocument = typeof document !== "undefined" && typeof sessionStorage !== "undefined";
-    return inBrowserDocument
+const MISSING_AUTH_REQUEST_STORAGE = "DirectClient requires options.authRequestStorage outside a browser to " +
+    "start or complete a sign-in. Pass an AuthRequestStorage over storage " +
+    "every instance shares, pass one to login() and " +
+    "exchangeAuthorizationCode() for each call, or pass " +
+    "MemoryAuthRequestStorage for a single process, tests and local " +
+    "development.";
+const MISSING_REFRESH_TOKEN_STORAGE = "DirectClient requires options.refreshTokenStorage outside a browser to " +
+    "keep the refresh token a sign-in returns. Pass a RefreshTokenStorage " +
+    "over storage that outlives the process, such as a database or the " +
+    "operating system's keychain, or MemoryRefreshTokenStorage for a single " +
+    "process, tests and local development. Client-credentials use needs " +
+    "neither.";
+function inBrowserDocument() {
+    return typeof document !== "undefined";
+}
+function browserAuthRequestStorage(ttlMs) {
+    if (!inBrowserDocument())
+        return undefined;
+    return typeof sessionStorage !== "undefined"
         ? new SessionStorageAuthRequestStorage({ ttlMs })
         : new MemoryAuthRequestStorage({ ttlMs });
 }
+function browserRefreshTokenStorage() {
+    return inBrowserDocument() ? new MemoryRefreshTokenStorage() : undefined;
+}
 async function claimAuthRequest(storage, state) {
     if (storage.take)
         return await storage.take(state);

package/dist/client/mod.d.ts

@@ -15,11 +15,13 @@
  * care — the React adapter's `<OAuth2Provider>`, a shared UI helper — should
  * accept.
  *
- * A {@link DirectClient} keeps its token bundle and refresh token in memory
- * by default, so they are lost on reload; a browser app that must survive one
- * passes {@link IndexedDBRefreshTokenStorage}. The pending auth request
- * defaults to {@link SessionStorageAuthRequestStorage} in a browser document
- * and to memory everywhere else.
+ * In a browser document a {@link DirectClient} keeps its token bundle and
+ * refresh token in memory by default, so they are lost on reload; a browser
+ * app that must survive one passes {@link IndexedDBRefreshTokenStorage}. The
+ * pending auth request defaults to {@link SessionStorageAuthRequestStorage}
+ * there. Outside a browser, a sign-in or device flow requires
+ * `authRequestStorage` and `refreshTokenStorage` and throws a `TypeError`
+ * without them; client credentials need neither.
  *
  * @module
  */

package/dist/client/mod.js

@@ -15,11 +15,13 @@
  * care — the React adapter's `<OAuth2Provider>`, a shared UI helper — should
  * accept.
  *
- * A {@link DirectClient} keeps its token bundle and refresh token in memory
- * by default, so they are lost on reload; a browser app that must survive one
- * passes {@link IndexedDBRefreshTokenStorage}. The pending auth request
- * defaults to {@link SessionStorageAuthRequestStorage} in a browser document
- * and to memory everywhere else.
+ * In a browser document a {@link DirectClient} keeps its token bundle and
+ * refresh token in memory by default, so they are lost on reload; a browser
+ * app that must survive one passes {@link IndexedDBRefreshTokenStorage}. The
+ * pending auth request defaults to {@link SessionStorageAuthRequestStorage}
+ * there. Outside a browser, a sign-in or device flow requires
+ * `authRequestStorage` and `refreshTokenStorage` and throws a `TypeError`
+ * without them; client credentials need neither.
  *
  * @module
  */

package/dist/client/storage.d.ts

@@ -10,11 +10,14 @@
  *   used to correlate an authorize redirect with its callback.
  *
  * The implementations here are in-memory and live only for the process / tab
- * lifetime. `DirectClient` uses them by default, except that in a browser
- * document its auth-request storage defaults to `sessionStorage`. A browser
- * app that must stay signed in across reloads passes
- * `IndexedDBRefreshTokenStorage` for the refresh token and keeps the access
- * token in memory.
+ * lifetime. In a browser document `DirectClient` keeps the token bundle and
+ * refresh token in them by default and its auth-request map in
+ * `sessionStorage`. A browser app that must stay signed in across reloads
+ * passes `IndexedDBRefreshTokenStorage` for the refresh token and keeps the
+ * access token in memory. Outside a browser only the token bundle has a
+ * default: a sign-in requires the auth-request and refresh-token storage to be
+ * passed, these memory ones only for a single process, tests and local
+ * development.
  *
  * @module
  */
@@ -116,8 +119,9 @@ export declare class MemoryTokenStorage implements TokenStorage {
     clear(): void;
 }
 /**
- * Default in-memory {@link RefreshTokenStorage}. Data is lost when the
- * process exits.
+ * In-memory {@link RefreshTokenStorage}: `DirectClient`'s default in a browser
+ * document, and an explicit choice elsewhere for a single process, tests and
+ * local development. Data is lost when the process exits.
  */
 export declare class MemoryRefreshTokenStorage implements RefreshTokenStorage {
     #private;
@@ -145,8 +149,9 @@ export interface MemoryAuthRequestStorageOptions {
     maxEntries?: number;
 }
 /**
- * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
- * browser document. Data is lost when the process exits. Every write prunes
+ * In-memory {@link AuthRequestStorage} for a single process, tests and local
+ * development; `DirectClient` falls back to it only in a browser document
+ * without `sessionStorage`. Data is lost when the process exits. Every write prunes
  * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, then
  * evicts the oldest-written records beyond
  * {@link MemoryAuthRequestStorageOptions.maxEntries}, so neither logins that

package/dist/client/storage.js

@@ -10,11 +10,14 @@
  *   used to correlate an authorize redirect with its callback.
  *
  * The implementations here are in-memory and live only for the process / tab
- * lifetime. `DirectClient` uses them by default, except that in a browser
- * document its auth-request storage defaults to `sessionStorage`. A browser
- * app that must stay signed in across reloads passes
- * `IndexedDBRefreshTokenStorage` for the refresh token and keeps the access
- * token in memory.
+ * lifetime. In a browser document `DirectClient` keeps the token bundle and
+ * refresh token in them by default and its auth-request map in
+ * `sessionStorage`. A browser app that must stay signed in across reloads
+ * passes `IndexedDBRefreshTokenStorage` for the refresh token and keeps the
+ * access token in memory. Outside a browser only the token bundle has a
+ * default: a sign-in requires the auth-request and refresh-token storage to be
+ * passed, these memory ones only for a single process, tests and local
+ * development.
  *
  * @module
  */
@@ -35,8 +38,9 @@ export class MemoryTokenStorage {
     }
 }
 /**
- * Default in-memory {@link RefreshTokenStorage}. Data is lost when the
- * process exits.
+ * In-memory {@link RefreshTokenStorage}: `DirectClient`'s default in a browser
+ * document, and an explicit choice elsewhere for a single process, tests and
+ * local development. Data is lost when the process exits.
  */
 export class MemoryRefreshTokenStorage {
     #token = null;
@@ -55,8 +59,9 @@ export class MemoryRefreshTokenStorage {
 }
 const DEFAULT_MAX_AUTH_REQUESTS = 1000;
 /**
- * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
- * browser document. Data is lost when the process exits. Every write prunes
+ * In-memory {@link AuthRequestStorage} for a single process, tests and local
+ * development; `DirectClient` falls back to it only in a browser document
+ * without `sessionStorage`. Data is lost when the process exits. Every write prunes
  * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, then
  * evicts the oldest-written records beyond
  * {@link MemoryAuthRequestStorageOptions.maxEntries}, so neither logins that

package/dist/identity/lockout.d.ts

@@ -4,10 +4,11 @@
  * 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).
+ * a threshold is crossed. Storage is a pluggable {@link LockoutStore} with no
+ * default: back it with storage every instance shares — e.g. columns on your
+ * users table, which also gives admins visibility — or pass the bounded
+ * {@link MemoryLockoutStore} for a single process, tests and local
+ * development.
  *
  * `AccountLockout` only records state: it never decides whether to block.
  * `IdentityService` consults it and applies its `protectionMode`
@@ -25,8 +26,12 @@ export interface LockoutRecord {
 }
 /** 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>;
+    /**
+     * The account's current record, or `undefined` when it has none.
+     * `AccountLockout` passes the clock it was given as `now`, for a store that
+     * expires records; a store that keeps them until cleared can ignore it.
+     */
+    get(userId: string, now?: number): 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
@@ -49,8 +54,18 @@ export interface AccountLockoutOptions {
     maxAttempts?: number;
     /** How long a lock lasts, in ms. Defaults to 15 minutes. */
     lockDurationMs?: number;
-    /** State storage. Defaults to {@link MemoryLockoutStore}. */
-    store?: LockoutStore;
+    /**
+     * Where failure counts and locks live. Required, because a lockout only
+     * holds if every instance that serves sign-in reads the same records:
+     *
+     * - A {@link LockoutStore} over storage every instance shares, such as
+     *   columns on your users table. Its `increment` must be atomic.
+     * - {@link MemoryLockoutStore} for a single process, tests and local
+     *   development. Each instance counts its own failures, so behind a load
+     *   balancer an attacker gets `maxAttempts` guesses per instance and a lock
+     *   on one instance does not stop sign-in on another.
+     */
+    store: LockoutStore;
 }
 /** The outcome of {@link AccountLockout.recordFailure}. */
 export interface LockoutFailureResult {
@@ -123,15 +138,20 @@ export interface AccountLockoutLike {
 }
 /**
  * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
- * lock) — the default {@link AccountLockoutLike}. Wire into
+ * lock) — the shipped {@link AccountLockoutLike}. Wire into
  * {@link IdentityService} via its `lockout` option, which resets it on a
  * successful sign-in, password reset, or {@link IdentityService.unlockAccount};
  * call {@link reset} yourself only from an unlock flow of your own.
  */
 export declare class AccountLockout implements AccountLockoutLike {
     #private;
-    /** Fixes thresholds and the backing store (defaults to {@linkcode MemoryLockoutStore}). */
-    constructor(options?: AccountLockoutOptions);
+    /**
+     * Fixes the thresholds and the backing store.
+     *
+     * @throws {TypeError} When {@linkcode AccountLockoutOptions.store} is
+     * missing.
+     */
+    constructor(options: AccountLockoutOptions);
     /** The account's current lock state. An expired lock reads as not locked. */
     status(userId: string, now?: number): Promise<LockoutStatus>;
     /**
@@ -142,14 +162,64 @@ export declare class AccountLockout implements AccountLockoutLike {
     /** 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. */
+/** Options for {@link MemoryLockoutStore}. */
+export interface MemoryLockoutStoreOptions {
+    /**
+     * How long a record is kept after its last failure, in ms. A record past it
+     * reads as absent, so the next failure starts a fresh count, but a record is
+     * never dropped while its lock is active. Defaults to 24 hours; `Infinity`
+     * keeps records until they are cleared or evicted.
+     */
+    ttlMs?: number;
+    /**
+     * Most records held at once. Defaults to 10,000; `Infinity` never evicts by
+     * count.
+     */
+    maxEntries?: number;
+}
+/**
+ * In-memory {@link LockoutStore} for a single process, tests and local
+ * development. Records live in the process that wrote them, so instances do
+ * not share failures or locks; pass a store over shared storage when more
+ * than one instance serves sign-in.
+ *
+ * Bounded so it cannot grow without limit: a record expires
+ * {@link MemoryLockoutStoreOptions.ttlMs} after its last failure unless its
+ * lock is still active, and a write beyond
+ * {@link MemoryLockoutStoreOptions.maxEntries} first drops expired records,
+ * then evicts one: unlocked records before locked ones, the fewest failures
+ * first, then the longest idle; among locked records, the lock that ends
+ * soonest. The residual is real: failures against more than `maxEntries`
+ * other accounts that each end locked can evict an active lock.
+ */
 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). */
+    /**
+     * Configures the TTL (24 hours by default) and the record cap (10,000 by
+     * default).
+     *
+     * @throws {RangeError} When `ttlMs` is not a positive number or `Infinity`,
+     * or `maxEntries` is neither a positive integer nor `Infinity`.
+     */
+    constructor(options?: MemoryLockoutStoreOptions);
+    /**
+     * How many records are currently retained — never more than `maxEntries`.
+     * Exposed so a test or a dev-time probe can see the bound working; it is not
+     * part of the {@link LockoutStore} contract.
+     */
+    get size(): number;
+    /** The stored record for `userId`, or `undefined` once it has expired. */
+    get(userId: string, now?: number): Promise<LockoutRecord | undefined>;
+    /**
+     * Add one failure synchronously (atomic in a single-process store). May
+     * drop expired records and evict another account's record to stay under
+     * `maxEntries`.
+     */
     increment(userId: string, now: number): Promise<LockoutRecord>;
-    /** Store `record` for `userId`. */
+    /**
+     * Store `record` for `userId`, keeping the time of its last failure; a
+     * record for an account with none is timed from now.
+     */
     set(userId: string, record: LockoutRecord): Promise<void>;
     /** Drop `userId`'s record. */
     clear(userId: string): Promise<void>;

package/dist/identity/lockout.js

@@ -4,10 +4,11 @@
  * 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).
+ * a threshold is crossed. Storage is a pluggable {@link LockoutStore} with no
+ * default: back it with storage every instance shares — e.g. columns on your
+ * users table, which also gives admins visibility — or pass the bounded
+ * {@link MemoryLockoutStore} for a single process, tests and local
+ * development.
  *
  * `AccountLockout` only records state: it never decides whether to block.
  * `IdentityService` consults it and applies its `protectionMode`
@@ -18,9 +19,12 @@
  */
 const DEFAULT_MAX_ATTEMPTS = 10;
 const DEFAULT_LOCK_DURATION_MS = 15 * 60 * 1000;
+const MISSING_LOCKOUT_STORE = "AccountLockout requires options.store. Pass a LockoutStore over storage " +
+    "every instance shares, such as columns on your users table, or " +
+    "MemoryLockoutStore for a single process, tests and local development.";
 /**
  * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
- * lock) — the default {@link AccountLockoutLike}. Wire into
+ * lock) — the shipped {@link AccountLockoutLike}. Wire into
  * {@link IdentityService} via its `lockout` option, which resets it on a
  * successful sign-in, password reset, or {@link IdentityService.unlockAccount};
  * call {@link reset} yourself only from an unlock flow of your own.
@@ -29,15 +33,22 @@ export class AccountLockout {
     #maxAttempts;
     #lockDurationMs;
     #store;
-    /** Fixes thresholds and the backing store (defaults to {@linkcode MemoryLockoutStore}). */
-    constructor(options = {}) {
+    /**
+     * Fixes the thresholds and the backing store.
+     *
+     * @throws {TypeError} When {@linkcode AccountLockoutOptions.store} is
+     * missing.
+     */
+    constructor(options) {
+        if (!options?.store)
+            throw new TypeError(MISSING_LOCKOUT_STORE);
         this.#maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
         this.#lockDurationMs = options.lockDurationMs ?? DEFAULT_LOCK_DURATION_MS;
-        this.#store = options.store ?? new MemoryLockoutStore();
+        this.#store = options.store;
     }
     /** 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);
+        const record = await this.#store.get(userId, now);
         if (!record)
             return { locked: false, failures: 0 };
         const locked = record.lockedUntil !== undefined && record.lockedUntil > now;
@@ -82,16 +93,74 @@ export class AccountLockout {
         return this.#store.clear(userId);
     }
 }
-/** In-memory {@link LockoutStore} for dev / single-process use. */
+const DEFAULT_LOCKOUT_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_LOCKOUT_RECORDS = 10_000;
+const LOCKOUT_SWEEP_INTERVAL = 1_000;
+/**
+ * In-memory {@link LockoutStore} for a single process, tests and local
+ * development. Records live in the process that wrote them, so instances do
+ * not share failures or locks; pass a store over shared storage when more
+ * than one instance serves sign-in.
+ *
+ * Bounded so it cannot grow without limit: a record expires
+ * {@link MemoryLockoutStoreOptions.ttlMs} after its last failure unless its
+ * lock is still active, and a write beyond
+ * {@link MemoryLockoutStoreOptions.maxEntries} first drops expired records,
+ * then evicts one: unlocked records before locked ones, the fewest failures
+ * first, then the longest idle; among locked records, the lock that ends
+ * soonest. The residual is real: failures against more than `maxEntries`
+ * other accounts that each end locked can evict an active lock.
+ */
 export class MemoryLockoutStore {
-    #records = new Map();
-    /** The stored record for `userId`, if any. */
-    get(userId) {
-        return Promise.resolve(this.#records.get(userId));
+    #entries = new Map();
+    #ttlMs;
+    #maxEntries;
+    #writesSinceSweep = 0;
+    /**
+     * Configures the TTL (24 hours by default) and the record cap (10,000 by
+     * default).
+     *
+     * @throws {RangeError} When `ttlMs` is not a positive number or `Infinity`,
+     * or `maxEntries` is neither a positive integer nor `Infinity`.
+     */
+    constructor(options = {}) {
+        this.#ttlMs = options.ttlMs ?? DEFAULT_LOCKOUT_TTL_MS;
+        this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_LOCKOUT_RECORDS;
+        if (!(this.#ttlMs > 0)) {
+            throw new RangeError("MemoryLockoutStore ttlMs must be a positive number or Infinity, " +
+                `got ${this.#ttlMs}.`);
+        }
+        if (this.#maxEntries !== Infinity &&
+            !(Number.isInteger(this.#maxEntries) && this.#maxEntries > 0)) {
+            throw new RangeError("MemoryLockoutStore maxEntries must be a positive integer or " +
+                `Infinity, got ${this.#maxEntries}.`);
+        }
+    }
+    /**
+     * How many records are currently retained — never more than `maxEntries`.
+     * Exposed so a test or a dev-time probe can see the bound working; it is not
+     * part of the {@link LockoutStore} contract.
+     */
+    get size() {
+        return this.#entries.size;
+    }
+    /** The stored record for `userId`, or `undefined` once it has expired. */
+    get(userId, now = Date.now()) {
+        const entry = this.#entries.get(userId);
+        if (entry && this.#expired(entry, now)) {
+            this.#entries.delete(userId);
+            return Promise.resolve(undefined);
+        }
+        return Promise.resolve(entry?.record);
     }
-    /** Add one failure synchronously (atomic in a single-process store). */
+    /**
+     * Add one failure synchronously (atomic in a single-process store). May
+     * drop expired records and evict another account's record to stay under
+     * `maxEntries`.
+     */
     increment(userId, now) {
-        const record = this.#records.get(userId);
+        const entry = this.#entries.get(userId);
+        const record = entry && !this.#expired(entry, now) ? entry.record : undefined;
         const lockExpired = record?.lockedUntil !== undefined && record.lockedUntil <= now;
         const next = record && !lockExpired
             ? {
@@ -101,17 +170,81 @@ export class MemoryLockoutStore {
                     : {}),
             }
             : { failures: 1 };
-        this.#records.set(userId, next);
+        this.#entries.set(userId, { record: next, touchedAt: now });
+        this.#collect(userId, now);
         return Promise.resolve(next);
     }
-    /** Store `record` for `userId`. */
+    /**
+     * Store `record` for `userId`, keeping the time of its last failure; a
+     * record for an account with none is timed from now.
+     */
     set(userId, record) {
-        this.#records.set(userId, record);
+        const touchedAt = this.#entries.get(userId)?.touchedAt ?? Date.now();
+        this.#entries.set(userId, { record, touchedAt });
+        this.#collect(userId, touchedAt);
         return Promise.resolve();
     }
     /** Drop `userId`'s record. */
     clear(userId) {
-        this.#records.delete(userId);
+        this.#entries.delete(userId);
         return Promise.resolve();
     }
+    #expired(entry, now) {
+        const { lockedUntil } = entry.record;
+        if (lockedUntil !== undefined && lockedUntil > now)
+            return false;
+        return now - entry.touchedAt >= this.#ttlMs;
+    }
+    #collect(written, now) {
+        if (++this.#writesSinceSweep >= LOCKOUT_SWEEP_INTERVAL) {
+            this.#dropExpired(now);
+        }
+        if (this.#entries.size <= this.#maxEntries)
+            return;
+        this.#dropExpired(now);
+        while (this.#entries.size > this.#maxEntries) {
+            const victim = this.#evictionCandidate(written, now);
+            if (victim === undefined)
+                return;
+            this.#entries.delete(victim);
+        }
+    }
+    #dropExpired(now) {
+        this.#writesSinceSweep = 0;
+        for (const [userId, entry] of this.#entries) {
+            if (this.#expired(entry, now))
+                this.#entries.delete(userId);
+        }
+    }
+    #evictionCandidate(written, now) {
+        let victim;
+        for (const candidate of this.#entries) {
+            if (candidate[0] === written)
+                continue;
+            if (!victim || evictsBefore(candidate[1], victim[1], now)) {
+                victim = candidate;
+            }
+        }
+        return victim?.[0];
+    }
+}
+function lockEnd(entry, now) {
+    const { lockedUntil } = entry.record;
+    return lockedUntil !== undefined && lockedUntil > now
+        ? lockedUntil
+        : undefined;
+}
+function evictsBefore(a, b, now) {
+    const aLock = lockEnd(a, now);
+    const bLock = lockEnd(b, now);
+    if (aLock === undefined && bLock !== undefined)
+        return true;
+    if (aLock !== undefined && bLock === undefined)
+        return false;
+    if (aLock !== undefined && bLock !== undefined)
+        return aLock < bLock;
+    if (a.record.failures !== b.record.failures) {
+        return a.record.failures < b.record.failures;
+    }
+    return a.touchedAt < b.touchedAt;
 }

package/dist/identity/mod.d.ts

@@ -55,7 +55,7 @@ export { buildResetUrl, buildSignInUrl, buildTokenUrl, buildUnlockUrl, buildVeri
 export { isRecentlyAuthenticated, type ListableSessionService, type RevocableSessionService, type SessionSummary, supportsSessionListing, } from "./session.ts";
 export { type ConsumeSignInLinkResult, type IdentityRateLimiters, IdentityService, type IdentityServiceOptions, type IdentityUser, type IdentityUserStore, type UnlockAccountResult, type VerifyEmailResult, type VerifySignInCodeResult, } from "./service.ts";
 export { EmailOtpService, type EmailOtpServiceOptions, MemoryOtpStore, type OtpRecord, type OtpStore, type RequestedOtp, type RequestOtpOptions, type VerifyOtpOptions, type VerifyOtpResult, } from "./otp.ts";
-export { AccountLockout, type AccountLockoutLike, type AccountLockoutOptions, type LockoutFailureResult, type LockoutRecord, type LockoutStatus, type LockoutStore, MemoryLockoutStore, } from "./lockout.ts";
+export { AccountLockout, type AccountLockoutLike, type AccountLockoutOptions, type LockoutFailureResult, type LockoutRecord, type LockoutStatus, type LockoutStore, MemoryLockoutStore, type MemoryLockoutStoreOptions, } from "./lockout.ts";
 export type { IdentityEvent, IdentityEventHook, SignInCodeFailureReason, SignInFailureReason, } from "./events.ts";
 export { IdentityError, type IdentityErrorCode, type IdentityErrorOptions, type IdentityErrorStatus, identityErrorStatus, isIdentityError, } from "./errors.ts";
 export { MemoryRateLimitStore, RateLimiter, type RateLimiterLike, type RateLimiterOptions, type RateLimitResult, type RateLimitStore, } from "./rate-limit.ts";

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

@@ -1,9 +1,10 @@
 /**
  * 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
+ * is the counter storage {@link RateLimiter} requires (back it with Redis or a
+ * database to share limits across instances, or pass the bounded
+ * {@link MemoryRateLimitStore} for a single process, tests and local
+ * development), 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`).
  *
@@ -90,16 +91,26 @@ export interface RateLimiterOptions {
     limit?: number;
     /** Window length in ms. Defaults to 15 minutes. */
     windowMs?: number;
-    /** Counter storage. Defaults to {@link MemoryRateLimitStore}. */
-    store?: RateLimitStore;
+    /**
+     * Where the counters live. Required, because a limit only holds if every
+     * instance that serves the flow counts in the same place:
+     *
+     * - A {@link RateLimitStore} over Redis or a database every instance
+     *   shares. Its `increment` must be atomic.
+     * - {@link MemoryRateLimitStore} for a single process, tests and local
+     *   development. Each instance keeps its own counters, so behind a load
+     *   balancer a client gets `limit` hits per instance per window.
+     */
+    store: RateLimitStore;
 }
 /**
- * Fixed-window limiter — the default {@link RateLimiterLike}. Swap in your own
+ * Fixed-window limiter — the shipped {@link RateLimiterLike}. Swap in your own
  * `RateLimiterLike` for anything the fixed window cannot express.
  *
  * @example
  * ```ts
- * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000 });
+ * declare const store: RateLimitStore;
+ * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000, store });
  * 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}`);
@@ -107,8 +118,12 @@ export interface RateLimiterOptions {
  */
 export declare class RateLimiter implements RateLimiterLike {
     #private;
-    /** Fixes the `limit`/`windowMs` and the backing store (defaults to {@linkcode MemoryRateLimitStore}). */
-    constructor(options?: RateLimiterOptions);
+    /**
+     * Fixes the `limit`/`windowMs` and the backing store.
+     *
+     * @throws {TypeError} When {@linkcode RateLimiterOptions.store} is missing.
+     */
+    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. */
@@ -152,9 +167,10 @@ export type EnforceRateLimitOptions = {
  */
 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.
+ * In-memory {@link RateLimitStore} for a single process, tests and local
+ * development. Counters are per-process, so replicas do not share limits —
+ * back {@link RateLimiter} with Redis or a database when more than one
+ * instance serves the flow.
  *
  * 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.

package/dist/identity/rate-limit.js

@@ -1,9 +1,10 @@
 /**
  * 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
+ * is the counter storage {@link RateLimiter} requires (back it with Redis or a
+ * database to share limits across instances, or pass the bounded
+ * {@link MemoryRateLimitStore} for a single process, tests and local
+ * development), 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`).
  *
@@ -12,13 +13,17 @@
 import { IdentityError } from "./errors.js";
 const DEFAULT_LIMIT = 10;
 const DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+const MISSING_RATE_LIMIT_STORE = "RateLimiter requires options.store. Pass a RateLimitStore over Redis or " +
+    "a database every instance shares, or MemoryRateLimitStore for a single " +
+    "process, tests and local development.";
 /**
- * Fixed-window limiter — the default {@link RateLimiterLike}. Swap in your own
+ * Fixed-window limiter — the shipped {@link RateLimiterLike}. Swap in your own
  * `RateLimiterLike` for anything the fixed window cannot express.
  *
  * @example
  * ```ts
- * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000 });
+ * declare const store: RateLimitStore;
+ * const limiter = new RateLimiter({ limit: 5, windowMs: 15 * 60_000, store });
  * 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}`);
@@ -28,11 +33,17 @@ export class RateLimiter {
     #limit;
     #windowMs;
     #store;
-    /** Fixes the `limit`/`windowMs` and the backing store (defaults to {@linkcode MemoryRateLimitStore}). */
-    constructor(options = {}) {
+    /**
+     * Fixes the `limit`/`windowMs` and the backing store.
+     *
+     * @throws {TypeError} When {@linkcode RateLimiterOptions.store} is missing.
+     */
+    constructor(options) {
+        if (!options?.store)
+            throw new TypeError(MISSING_RATE_LIMIT_STORE);
         this.#limit = options.limit ?? DEFAULT_LIMIT;
         this.#windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
-        this.#store = options.store ?? new MemoryRateLimitStore();
+        this.#store = options.store;
     }
     /** Record a hit for `key` and report whether it is within the limit. */
     async check(key, now = Date.now()) {
@@ -100,9 +111,10 @@ 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.
+ * In-memory {@link RateLimitStore} for a single process, tests and local
+ * development. Counters are per-process, so replicas do not share limits —
+ * back {@link RateLimiter} with Redis or a database when more than one
+ * instance serves the flow.
  *
  * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "keywords": [
     "authorization-server",