@udibo/oauth2 0.4.1 → 0.5.0

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

@@ -94,8 +94,7 @@ export interface RateLimiterOptions {
     store?: RateLimitStore;
 }
 /**
- * Fixed-window limiter — the default {@link RateLimiterLike}, deliberately
- * feature-frozen as a floor rather than a product. Swap in your own
+ * Fixed-window limiter — the default {@link RateLimiterLike}. Swap in your own
  * `RateLimiterLike` for anything the fixed window cannot express.
  *
  * @example
@@ -115,11 +114,6 @@ export declare class RateLimiter implements RateLimiterLike {
     /** 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;

package/esm/identity/rate-limit.js

@@ -13,8 +13,7 @@ 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
+ * Fixed-window limiter — the default {@link RateLimiterLike}. Swap in your own
  * `RateLimiterLike` for anything the fixed window cannot express.
  *
  * @example

package/esm/identity/service.d.ts

@@ -13,7 +13,7 @@
  * Storage-agnostic by design: every flow addresses users by opaque id and the
  * {@link IdentityUserStore} is yours — back it with whatever database, ORM, and
  * schema your app already uses. The library composes the flows; it never owns
- * your tables. It stays below the turnkey-identity-service line.
+ * your tables.
  *
  * @module
  */
@@ -134,7 +134,10 @@ export interface IdentityRateLimiters {
 export interface IdentityServiceOptions<User extends IdentityUser> {
     /** App-owned user storage. */
     users: IdentityUserStore<User>;
-    /** Token flow for verify/reset links. Required for those flows. */
+    /**
+     * Token flow for the emailed links (verification, reset, unlock, sign-in).
+     * The methods that mint or consume them throw an `Error` without it.
+     */
     tokens?: TokenFlowService;
     /**
      * Password hasher. Defaults to a new {@link PasswordIdentityService}
@@ -150,10 +153,14 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
      * When set, {@link IdentityService.signIn} — for a user with no native
      * credential yet — reads the imported hash via
      * {@link IdentityUserStore.getLegacyCredential} and verifies it with the first
-     * verifier whose `canVerify` accepts it. On a match it rehashes the password
-     * into the native format ({@link IdentityUserStore.replaceCredential}), clears the
-     * imported hash ({@link IdentityUserStore.clearLegacyCredential}), emits a
-     * `password.upgraded` event, and signs the user in. The package ships
+     * verifier whose `canVerify` accepts it. On a match it signs the user in.
+     * When the store implements {@link IdentityUserStore.replaceCredential}, it
+     * first rehashes the password into the native format; on success it clears
+     * the imported hash ({@link IdentityUserStore.clearLegacyCredential}) and
+     * emits a `password.upgraded` event. If that write reports the credential
+     * already replaced, the password must verify against the new credential or
+     * sign-in fails; if the write throws, the user is signed in without the
+     * upgrade. The package ships
      * {@link pbkdf2Verifier} built-in; bcrypt/argon2/scrypt are bring-your-own via
      * the {@link LegacyPasswordVerifier} seam (no dep-free implementation exists).
      */
@@ -162,8 +169,9 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
      * Minimum wall-clock duration of a **failed** {@link IdentityService.signIn},
      * in ms. Defaults to `250`. Every rejection — unknown identifier, locked
      * account, no password set, wrong native password, wrong imported password —
-     * is held to the same deadline measured from the call's first statement, so
-     * the response time reveals nothing about which branch ran.
+     * is held to the same minimum duration, measured from the call's first
+     * statement, so branches that finish under it are indistinguishable by
+     * response time.
      *
      * Set it above the cost of your slowest configured
      * {@link IdentityServiceOptions.legacyVerifiers} plus one password hash —
@@ -182,7 +190,7 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
     failedSignInFloorMs?: number;
     /** Session revocation, called on a successful password reset. Optional. */
     sessions?: RevocableSessionService;
-    /** Delivery transports for verify/reset links. Optional. */
+    /** Delivery transports for the emailed links and sign-in codes. Optional. */
     delivery?: DeliveryHooks;
     /**
      * Base URL (origin, or origin + prefix) used to build the action links
@@ -191,10 +199,11 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
     baseUrl?: string;
     /**
      * Token lifetimes in ms. Defaults: password reset 1h, email verification 24h,
-     * account unlock 1h, sign-in link 15m. A per-call `ttlMs` — currently only
-     * {@link IdentityService.requestSignInLink} takes one — overrides the
-     * configured default for that request. One-time sign-in **codes** are not
-     * tokens; their lifetime is {@link IdentityServiceOptions.otp}'s `ttlMs`.
+     * account unlock 1h, sign-in link 15m.
+     * {@link IdentityService.requestSignInLink} also takes a per-call `ttlMs`
+     * that overrides the sign-in link default for that request. One-time sign-in
+     * **codes** are not tokens; their lifetime is
+     * {@link IdentityServiceOptions.otp}'s `ttlMs`.
      */
     ttl?: {
         passwordReset?: number;
@@ -259,9 +268,9 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
     /**
      * Per-flow limiter overrides. Set one when a single threshold cannot serve
      * every flow — a limit tuned as a sign-in floor is usually far too permissive
-     * for the four flows that make the server **send an email to a
+     * for the five flows that make the server **send an email to a
      * caller-supplied address** (`passwordReset`, `emailVerification`,
-     * `accountUnlock`, `signInLink`, plus `signInCode`), which typically want a
+     * `accountUnlock`, `signInLink`, and `signInCode`), which typically want a
      * handful of requests per hour rather than per 15 minutes.
      *
      * Each entry is a whole {@link RateLimiterLike} — build one
@@ -391,8 +400,9 @@ export declare class IdentityService<User extends IdentityUser> {
         profile: Record<string, unknown>;
     }): Promise<User>;
     /**
-     * Verify credentials; returns the user, or `null` for an unknown identifier or
-     * wrong password (don't reveal which). Establishing a session is your app's
+     * Verify credentials; returns the user, or `null` for an unknown identifier,
+     * an account with no password, a wrong password, or (under `"enforce"`) a
+     * locked account — don't reveal which. Establishing a session is your app's
      * job — do it on a non-null result.
      *
      * The throttle window is keyed on the identifier as submitted (trimmed, not
@@ -401,12 +411,13 @@ export declare class IdentityService<User extends IdentityUser> {
      * the identifiers you later hand {@link IdentityService.resetSignInThrottle}
      * won't match the ones that filled it.
      *
-     * Every rejection is held to
+     * Every rejection is held to at least
      * {@link IdentityServiceOptions.failedSignInFloorMs} (250 ms by default),
      * measured from entry, so an unknown identifier, a locked account, a wrong
-     * native password, and a wrong password against an imported hash all take the
-     * same time — the branch that runs a foreign KDF is not visible from
-     * outside. A success returns as soon as it is done.
+     * native password, and a wrong password against an imported hash take the
+     * same time as long as each finishes under the floor — a branch that runs
+     * longer (typically a foreign KDF) stays visible by its excess. A success
+     * returns as soon as it is done.
      *
      * @throws {IdentityError} `rate_limited` (with `retryAfterMs`) when a
      * `rateLimiter` is configured, the identifier's limit is hit, and
@@ -427,11 +438,18 @@ export declare class IdentityService<User extends IdentityUser> {
      */
     resetSignInThrottle(identifier: string): Promise<void>;
     /**
-     * Enumeration-safe: always resolves or throws identically whether or not the
-     * email maps to a user. If it does, mints a single-use reset token and calls
-     * `delivery.sendPasswordReset`. With a `rateLimiter`, requests throttle per
-     * target email, case-folded so casing variants share one window — the check
-     * runs before the lookup, so a 429 reveals nothing —
+     * Resolves with the same `void` whether or not the email maps to a user. If
+     * it does, mints a single-use reset token (voiding outstanding ones when the
+     * token store implements `deleteBySubject`) and calls
+     * `delivery.sendPasswordReset`. Only that branch awaits minting and delivery,
+     * so it is not timing-uniform — send from a background queue and throttle by
+     * IP at the route, as for {@link IdentityService.requestSignInLink}. A
+     * token store that throws while minting is trapped like a throwing delivery
+     * hook: the call still resolves `void`, a `credential_mint.failed` event is
+     * emitted, and nothing is sent — so a store outage is not an enumeration
+     * oracle through the error either. With a `rateLimiter`,
+     * requests throttle per target email, case-folded so casing variants share
+     * one window — the check runs before the lookup, so a 429 reveals nothing —
      * and throw {@link IdentityError} `rate_limited` when exceeded; catch it and
      * return your uniform success response. Give it a tighter threshold than
      * sign-in via `rateLimiters.passwordReset`.
@@ -439,10 +457,10 @@ export declare class IdentityService<User extends IdentityUser> {
     requestPasswordReset(email: string): Promise<void>;
     /**
      * Consume a reset token, set the new password, and (if a `sessions` service
-     * was configured) revoke the user's other sessions. Clears any failed-attempt
-     * lockout — the emailed token proves the same account ownership the unlock
-     * flow does. Returns `{ userId }`, or `null` for an invalid/expired/used
-     * token.
+     * was configured) revoke **all** of the user's sessions via
+     * `revokeAllByUser`. Clears any failed-attempt lockout — the emailed token
+     * proves the same account ownership the unlock flow does. Returns
+     * `{ userId }`, or `null` for an invalid/expired/used token.
      *
      * A reset is the user's "lock everyone else out" action, so the outstanding
      * passwordless credentials for the same account are voided too: sign-in links
@@ -452,11 +470,17 @@ export declare class IdentityService<User extends IdentityUser> {
      * logged and the reset still completes, since the password has already
      * changed by then.
      *
-     * Sessions are revoked **after** the password is changed. If that revocation
-     * throws, the reset is reported failed — a `password_reset.failed`
+     * The token is consumed **first**, before the password is written, so two
+     * concurrent submissions of one link resolve to exactly one `{ userId }` and
+     * only that call's password is set — the loser gets `null` and writes
+     * nothing. Sessions are revoked **after** the password is changed. If that
+     * revocation throws, the reset is reported failed — a `password_reset.failed`
      * (`session_revocation_failed`) event fires, no `password_reset.completed`
-     * fires, and the error rethrows — rather than silently returning success with
-     * the user's old sessions still live. Retry the reset to clear them.
+     * fires, and the error rethrows — rather than silently returning success
+     * with the user's old sessions still live. The token is already spent and
+     * the new password already set by then, so the operator clears the still-live
+     * sessions by calling `revokeAllByUser` again (subscribe to the event), or
+     * the user completes a fresh reset link.
      *
      * @throws {IdentityError} `weak_password` when `password` fails the password
      * policy — including the 8–256 character defaults that apply when
@@ -519,13 +543,18 @@ export declare class IdentityService<User extends IdentityUser> {
     unlockAccount(token: string): Promise<UnlockAccountResult>;
     /**
      * Passwordless request: always resolves with the same `void` result. If the
-     * email maps to a user, mints a single-use sign-in token (invalidating any
-     * outstanding one) and calls `delivery.sendSignInLink`; an unknown email does
-     * neither, so the **return value** never reveals whether an account exists.
+     * email maps to a user, mints a single-use sign-in token (voiding outstanding
+     * ones when the token store implements `deleteBySubject`) and calls
+     * `delivery.sendSignInLink`; an unknown email does neither, so the **return
+     * value** never reveals whether an account exists.
      * The synchronous path is not fully timing-uniform, though — only the
      * known-email branch awaits token minting and delivery — so send email from a
      * background queue and apply IP-level throttling at the route to close the
-     * residual latency/side-channel oracle. Throttled per email (case-folded,
+     * residual latency/side-channel oracle. A token store that throws while
+     * minting is trapped: the call still resolves `void` and a
+     * `credential_mint.failed` event is the only signal, so neither a store nor
+     * a mailer outage surfaces as an error on the known branch alone.
+     * Throttled per email (case-folded,
      * key `pwless:<email>`) when a `rateLimiter` — or a tighter
      * `rateLimiters.signInLink` — is configured; throws {@link IdentityError}
      * `rate_limited` in enforce mode. Default link lifetime is 15 minutes.
@@ -560,17 +589,20 @@ export declare class IdentityService<User extends IdentityUser> {
      * {@link DeliveryHooks}): that exact code is invalidated — never a newer one a
      * retry may have delivered meanwhile — a `delivery.failed` event is emitted,
      * and the call still resolves `void`, so a mailer outage is not an enumeration
-     * oracle either.
+     * oracle either. Nor is an OTP store outage: a throw while minting the code
+     * is trapped the same way, with a `credential_mint.failed` event as the only
+     * signal.
      */
     requestSignInCode(email: string): Promise<void>;
     /**
      * Verify a one-time sign-in code. An unknown email performs the same hash
      * work as a known one and reports plain `invalid` — the result is not an
-     * enumeration oracle. Wrong tries spend the code's attempt budget (`locked`
-     * once it runs out); success consumes the code (single-use), resets the
-     * flow's throttle window, and carries the `userId` to sign in — session
-     * creation and your MFA gate stay your app's job, as does treating a
-     * since-deleted/disabled user as a failed sign-in.
+     * enumeration oracle. Wrong tries spend the code's attempt budget and the
+     * code is invalidated once it runs out — the result still reads `invalid`;
+     * the `signin_code.failed` event carries `locked`. Success consumes the code
+     * (single-use), resets the flow's throttle window, and carries the `userId`
+     * to sign in — session creation and your MFA gate stay your app's job, as
+     * does treating a since-deleted/disabled user as a failed sign-in.
      */
     verifySignInCode(input: {
         email: string;

package/esm/identity/service.js

@@ -13,7 +13,7 @@
  * Storage-agnostic by design: every flow addresses users by opaque id and the
  * {@link IdentityUserStore} is yours — back it with whatever database, ORM, and
  * schema your app already uses. The library composes the flows; it never owns
- * your tables. It stays below the turnkey-identity-service line.
+ * your tables.
  *
  * @module
  */
@@ -22,6 +22,7 @@ import { buildResetUrl, buildSignInUrl, buildUnlockUrl, buildVerificationUrl, }
 import { PasswordIdentityService, } from "./password.js";
 import { TokenPurpose, } from "./token-flow.js";
 import { assertPasswordPolicy, } from "./password-policy.js";
+import { IdentityError } from "./errors.js";
 import { enforceRateLimit } from "./rate-limit.js";
 import { EmailOtpService, otpRateKey } from "./otp.js";
 import { dispatchIdentityEvent, } from "./events.js";
@@ -34,21 +35,6 @@ const DEFAULT_FAILED_SIGN_IN_FLOOR_MS = 250;
 function foldEmail(email) {
     return email.trim().toLowerCase();
 }
-/**
- * The rate-limit key for each throttled flow, one entry per
- * {@link IdentityRateLimiters} key. Every check and every reset derives its key
- * here, so the window a flow fills is always the window its reset clears.
- *
- * Case-folding is a decision per key type. Email-addressed keys fold, so casing
- * variants of one mailbox share a window instead of each earning a fresh send
- * budget (`signInCode` folds inside {@link otpRateKey}, so the window it fills
- * is the one a standalone {@link EmailOtpService} would). Opaque user ids pass
- * through untouched — only the app knows whether they are case-sensitive.
- * `signin:` is trimmed but not folded: an identifier
- * may be a username or phone whose equality only the app's `findByIdentifier`
- * defines, and folding would merge two distinct accounts (`Bob`, `bob`) into
- * one window, letting failures against either deny sign-in to the other.
- */
 const RATE_KEYS = {
     signIn: (identifier) => `signin:${identifier.trim()}`,
     passwordReset: (email) => `pwreset:${foldEmail(email)}`,
@@ -138,8 +124,9 @@ export class IdentityService {
         return user;
     }
     /**
-     * Verify credentials; returns the user, or `null` for an unknown identifier or
-     * wrong password (don't reveal which). Establishing a session is your app's
+     * Verify credentials; returns the user, or `null` for an unknown identifier,
+     * an account with no password, a wrong password, or (under `"enforce"`) a
+     * locked account — don't reveal which. Establishing a session is your app's
      * job — do it on a non-null result.
      *
      * The throttle window is keyed on the identifier as submitted (trimmed, not
@@ -148,12 +135,13 @@ export class IdentityService {
      * the identifiers you later hand {@link IdentityService.resetSignInThrottle}
      * won't match the ones that filled it.
      *
-     * Every rejection is held to
+     * Every rejection is held to at least
      * {@link IdentityServiceOptions.failedSignInFloorMs} (250 ms by default),
      * measured from entry, so an unknown identifier, a locked account, a wrong
-     * native password, and a wrong password against an imported hash all take the
-     * same time — the branch that runs a foreign KDF is not visible from
-     * outside. A success returns as soon as it is done.
+     * native password, and a wrong password against an imported hash take the
+     * same time as long as each finishes under the floor — a branch that runs
+     * longer (typically a foreign KDF) stays visible by its excess. A success
+     * returns as soon as it is done.
      *
      * @throws {IdentityError} `rate_limited` (with `retryAfterMs`) when a
      * `rateLimiter` is configured, the identifier's limit is hit, and
@@ -217,11 +205,18 @@ export class IdentityService {
         await this.#resetThrottle("signIn", identifier);
     }
     /**
-     * Enumeration-safe: always resolves or throws identically whether or not the
-     * email maps to a user. If it does, mints a single-use reset token and calls
-     * `delivery.sendPasswordReset`. With a `rateLimiter`, requests throttle per
-     * target email, case-folded so casing variants share one window — the check
-     * runs before the lookup, so a 429 reveals nothing —
+     * Resolves with the same `void` whether or not the email maps to a user. If
+     * it does, mints a single-use reset token (voiding outstanding ones when the
+     * token store implements `deleteBySubject`) and calls
+     * `delivery.sendPasswordReset`. Only that branch awaits minting and delivery,
+     * so it is not timing-uniform — send from a background queue and throttle by
+     * IP at the route, as for {@link IdentityService.requestSignInLink}. A
+     * token store that throws while minting is trapped like a throwing delivery
+     * hook: the call still resolves `void`, a `credential_mint.failed` event is
+     * emitted, and nothing is sent — so a store outage is not an enumeration
+     * oracle through the error either. With a `rateLimiter`,
+     * requests throttle per target email, case-folded so casing variants share
+     * one window — the check runs before the lookup, so a 429 reveals nothing —
      * and throw {@link IdentityError} `rate_limited` when exceeded; catch it and
      * return your uniform success response. Give it a tighter threshold than
      * sign-in via `rateLimiters.passwordReset`.
@@ -238,7 +233,7 @@ export class IdentityService {
             });
             return;
         }
-        await this.#issueAndDeliver(tokens, {
+        await this.#trapMintFailure("password_reset", () => this.#issueAndDeliver(tokens, {
             hook: "sendPasswordReset",
             to: normalized,
             subject: user.id,
@@ -249,14 +244,14 @@ export class IdentityService {
                 email: normalized,
                 userId: user.id,
             },
-        });
+        }));
     }
     /**
      * Consume a reset token, set the new password, and (if a `sessions` service
-     * was configured) revoke the user's other sessions. Clears any failed-attempt
-     * lockout — the emailed token proves the same account ownership the unlock
-     * flow does. Returns `{ userId }`, or `null` for an invalid/expired/used
-     * token.
+     * was configured) revoke **all** of the user's sessions via
+     * `revokeAllByUser`. Clears any failed-attempt lockout — the emailed token
+     * proves the same account ownership the unlock flow does. Returns
+     * `{ userId }`, or `null` for an invalid/expired/used token.
      *
      * A reset is the user's "lock everyone else out" action, so the outstanding
      * passwordless credentials for the same account are voided too: sign-in links
@@ -266,11 +261,17 @@ export class IdentityService {
      * logged and the reset still completes, since the password has already
      * changed by then.
      *
-     * Sessions are revoked **after** the password is changed. If that revocation
-     * throws, the reset is reported failed — a `password_reset.failed`
+     * The token is consumed **first**, before the password is written, so two
+     * concurrent submissions of one link resolve to exactly one `{ userId }` and
+     * only that call's password is set — the loser gets `null` and writes
+     * nothing. Sessions are revoked **after** the password is changed. If that
+     * revocation throws, the reset is reported failed — a `password_reset.failed`
      * (`session_revocation_failed`) event fires, no `password_reset.completed`
-     * fires, and the error rethrows — rather than silently returning success with
-     * the user's old sessions still live. Retry the reset to clear them.
+     * fires, and the error rethrows — rather than silently returning success
+     * with the user's old sessions still live. The token is already spent and
+     * the new password already set by then, so the operator clears the still-live
+     * sessions by calling `revokeAllByUser` again (subscribe to the event), or
+     * the user completes a fresh reset link.
      *
      * @throws {IdentityError} `weak_password` when `password` fails the password
      * policy — including the 8–256 character defaults that apply when
@@ -299,8 +300,6 @@ export class IdentityService {
             await this.#users.clearLegacyCredential?.(resolved.subject);
         }
         catch (error) {
-            // A throwing hook must not skip session revocation after the password
-            // already changed.
             console.error("[@udibo/oauth2] resetPassword legacy-credential clear failed:", error instanceof Error ? error.message : error);
         }
         await this.#voidPasswordlessCredentials(tokens, resolved.subject, emailFromData(resolved.data));
@@ -456,13 +455,18 @@ export class IdentityService {
     }
     /**
      * Passwordless request: always resolves with the same `void` result. If the
-     * email maps to a user, mints a single-use sign-in token (invalidating any
-     * outstanding one) and calls `delivery.sendSignInLink`; an unknown email does
-     * neither, so the **return value** never reveals whether an account exists.
+     * email maps to a user, mints a single-use sign-in token (voiding outstanding
+     * ones when the token store implements `deleteBySubject`) and calls
+     * `delivery.sendSignInLink`; an unknown email does neither, so the **return
+     * value** never reveals whether an account exists.
      * The synchronous path is not fully timing-uniform, though — only the
      * known-email branch awaits token minting and delivery — so send email from a
      * background queue and apply IP-level throttling at the route to close the
-     * residual latency/side-channel oracle. Throttled per email (case-folded,
+     * residual latency/side-channel oracle. A token store that throws while
+     * minting is trapped: the call still resolves `void` and a
+     * `credential_mint.failed` event is the only signal, so neither a store nor
+     * a mailer outage surfaces as an error on the known branch alone.
+     * Throttled per email (case-folded,
      * key `pwless:<email>`) when a `rateLimiter` — or a tighter
      * `rateLimiters.signInLink` — is configured; throws {@link IdentityError}
      * `rate_limited` in enforce mode. Default link lifetime is 15 minutes.
@@ -476,7 +480,7 @@ export class IdentityService {
             await this.#emit({ type: "signin_link.requested", email: normalized });
             return;
         }
-        await this.#issueAndDeliver(tokens, {
+        await this.#trapMintFailure("signin_link", () => this.#issueAndDeliver(tokens, {
             hook: "sendSignInLink",
             to: normalized,
             subject: user.id,
@@ -486,7 +490,7 @@ export class IdentityService {
                 email: normalized,
                 userId: user.id,
             },
-        });
+        }));
     }
     /**
      * Consume a sign-in link token (single-use). `success` carries the `userId`
@@ -528,7 +532,9 @@ export class IdentityService {
      * {@link DeliveryHooks}): that exact code is invalidated — never a newer one a
      * retry may have delivered meanwhile — a `delivery.failed` event is emitted,
      * and the call still resolves `void`, so a mailer outage is not an enumeration
-     * oracle either.
+     * oracle either. Nor is an OTP store outage: a throw while minting the code
+     * is trapped the same way, with a `credential_mint.failed` event as the only
+     * signal.
      */
     async requestSignInCode(email) {
         const otp = this.#requireOtp("requestSignInCode");
@@ -539,25 +545,28 @@ export class IdentityService {
             await this.#emit({ type: "signin_code.requested", email: normalized });
             return;
         }
-        await otp.request({
-            email: normalized,
-            purpose: TokenPurpose.SignIn,
-            onDeliver: (code, expiresAt, codeId) => this.#deliverCode(normalized, code, user.id, expiresAt, codeId),
-        });
-        await this.#emit({
-            type: "signin_code.requested",
-            email: normalized,
-            userId: user.id,
+        await this.#trapMintFailure("signin_code", async () => {
+            await otp.request({
+                email: normalized,
+                purpose: TokenPurpose.SignIn,
+                onDeliver: (code, expiresAt, codeId) => this.#deliverCode(normalized, code, user.id, expiresAt, codeId),
+            });
+            await this.#emit({
+                type: "signin_code.requested",
+                email: normalized,
+                userId: user.id,
+            });
         });
     }
     /**
      * Verify a one-time sign-in code. An unknown email performs the same hash
      * work as a known one and reports plain `invalid` — the result is not an
-     * enumeration oracle. Wrong tries spend the code's attempt budget (`locked`
-     * once it runs out); success consumes the code (single-use), resets the
-     * flow's throttle window, and carries the `userId` to sign in — session
-     * creation and your MFA gate stay your app's job, as does treating a
-     * since-deleted/disabled user as a failed sign-in.
+     * enumeration oracle. Wrong tries spend the code's attempt budget and the
+     * code is invalidated once it runs out — the result still reads `invalid`;
+     * the `signin_code.failed` event carries `locked`. Success consumes the code
+     * (single-use), resets the flow's throttle window, and carries the `userId`
+     * to sign in — session creation and your MFA gate stay your app's job, as
+     * does treating a since-deleted/disabled user as a failed sign-in.
      */
     async verifySignInCode(input) {
         const otp = this.#requireOtp("verifySignInCode");
@@ -721,6 +730,23 @@ export class IdentityService {
                 "passwordless credentials; they stay usable until they expire:", error instanceof Error ? error.message : error);
         }
     }
+    async #trapMintFailure(flow, mint) {
+        try {
+            await mint();
+        }
+        catch (error) {
+            if (error instanceof IdentityError)
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[@udibo/oauth2] ${flow} request could not mint its credential; ` +
+                `nothing was sent:`, message);
+            await this.#emit({
+                type: "credential_mint.failed",
+                flow,
+                error: message,
+            });
+        }
+    }
     async #issueAndDeliver(tokens, request) {
         const { token, expiresAt } = await tokens.create({
             purpose: DELIVERY_PURPOSES[request.hook],

package/esm/identity/session.d.ts

@@ -2,13 +2,13 @@
  * Session revocation + step-up contracts for the identity layer.
  *
  * Three security primitives the own-auth flows need, kept as **contracts + a
- * pure helper** — storage stays app-owned (the `SessionStore` philosophy, and
- * the Lucia-deprecation lesson: don't ship a DB-adapter zoo):
+ * pure helper** — storage stays app-owned (the `SessionStore` philosophy):
  *
  * - {@link RevocableSessionService} — revoke a user's sessions on a credential
  *   change. After a password reset the app must end the *other* sessions, or a
- *   compromised account's other devices stay logged in. The reset flow calls
- *   this; your app implements it over its session store.
+ *   compromised account's other devices stay logged in.
+ *   `IdentityService.resetPassword` calls its `revokeAllByUser`; your app
+ *   implements it over its session store.
  * - {@link ListableSessionService} — the revocation seam's optional listing
  *   half: a user's live sessions as {@link SessionSummary} display rows, so a
  *   "where you're signed in" screen has one typed shape to render and wire the
@@ -107,6 +107,7 @@ export declare function supportsSessionListing(service: RevocableSessionService)
 /**
  * Whether a session authenticated within `maxAgeMs` — a recent-auth ("step-up")
  * check to gate sensitive actions. Re-prompt for credentials when this is false.
+ * An `authenticatedAt` of `0` or less (unknown) is never recent.
  *
  * @param authenticatedAt When the session last actively authenticated (epoch ms).
  * @param maxAgeMs How recent counts as "fresh" (e.g. 5 minutes).

package/esm/identity/session.js

@@ -2,13 +2,13 @@
  * Session revocation + step-up contracts for the identity layer.
  *
  * Three security primitives the own-auth flows need, kept as **contracts + a
- * pure helper** — storage stays app-owned (the `SessionStore` philosophy, and
- * the Lucia-deprecation lesson: don't ship a DB-adapter zoo):
+ * pure helper** — storage stays app-owned (the `SessionStore` philosophy):
  *
  * - {@link RevocableSessionService} — revoke a user's sessions on a credential
  *   change. After a password reset the app must end the *other* sessions, or a
- *   compromised account's other devices stay logged in. The reset flow calls
- *   this; your app implements it over its session store.
+ *   compromised account's other devices stay logged in.
+ *   `IdentityService.resetPassword` calls its `revokeAllByUser`; your app
+ *   implements it over its session store.
  * - {@link ListableSessionService} — the revocation seam's optional listing
  *   half: a user's live sessions as {@link SessionSummary} display rows, so a
  *   "where you're signed in" screen has one typed shape to render and wire the
@@ -31,6 +31,7 @@ export function supportsSessionListing(service) {
 /**
  * Whether a session authenticated within `maxAgeMs` — a recent-auth ("step-up")
  * check to gate sensitive actions. Re-prompt for credentials when this is false.
+ * An `authenticatedAt` of `0` or less (unknown) is never recent.
  *
  * @param authenticatedAt When the session last actively authenticated (epoch ms).
  * @param maxAgeMs How recent counts as "fresh" (e.g. 5 minutes).

package/esm/identity/token-flow.d.ts

@@ -1,12 +1,11 @@
 /**
  * One token-flow primitive for the single-use, expiring links an identity layer
- * needs — **email verification** and **password reset** are the same mechanics:
- * mint a high-entropy token, store only its hash, hand the raw token to the app
- * to deliver, then validate / single-use-consume it later.
+ * needs — email verification, password reset, account unlock, and sign-in
+ * links share the same mechanics: mint a 32-byte random token, store only its
+ * SHA-256 hash, hand the raw token to the app to deliver, then validate /
+ * single-use-consume it later.
  *
- * The app reimplements this once per flow today (random bytes → sha256 → store
- * with expiry → consume). This collapses it into one tested, enumeration-safe
- * building block. Storage is an app-owned {@link TokenFlowStore} (a
+ * Storage is an app-owned {@link TokenFlowStore} (a
  * {@link MemoryTokenFlowStore} ships for dev/tests); the package owns the
  * lifecycle, not the database.
  *
@@ -91,8 +90,9 @@ export interface CreateTokenOptions {
     /** Lifetime in milliseconds. */
     ttlMs: number;
     /**
-     * Invalidate any existing pending tokens for this `(purpose, subject)` first
-     * (requires {@link TokenFlowStore.deleteBySubject}). Defaults to `false`.
+     * Invalidate any existing pending tokens for this `(purpose, subject)` first.
+     * Silently skipped when the store lacks
+     * {@link TokenFlowStore.deleteBySubject}. Defaults to `false`.
      */
     invalidateExisting?: boolean;
 }

package/esm/identity/token-flow.js

@@ -1,12 +1,11 @@
 /**
  * One token-flow primitive for the single-use, expiring links an identity layer
- * needs — **email verification** and **password reset** are the same mechanics:
- * mint a high-entropy token, store only its hash, hand the raw token to the app
- * to deliver, then validate / single-use-consume it later.
+ * needs — email verification, password reset, account unlock, and sign-in
+ * links share the same mechanics: mint a 32-byte random token, store only its
+ * SHA-256 hash, hand the raw token to the app to deliver, then validate /
+ * single-use-consume it later.
  *
- * The app reimplements this once per flow today (random bytes → sha256 → store
- * with expiry → consume). This collapses it into one tested, enumeration-safe
- * building block. Storage is an app-owned {@link TokenFlowStore} (a
+ * Storage is an app-owned {@link TokenFlowStore} (a
  * {@link MemoryTokenFlowStore} ships for dev/tests); the package owns the
  * lifecycle, not the database.
  *