@udibo/oauth2 0.37.0 → 0.39.0

package/dist/identity/events.d.ts

@@ -118,18 +118,39 @@ export type IdentityEvent = {
 } | {
     type: "password_reset.completed";
     userId: string;
+    /**
+     * Sessions the reset revoked: the sum of what
+     * `IdentityUserStore.resetCredential` and the `sessions` service
+     * reported. Absent when neither ran.
+     */
+    sessionsRevoked?: number;
 } | {
     type: "password_reset.failed";
     /**
      * `"invalid_token"` — the reset link was unknown, expired, or already used.
-     * `"session_revocation_failed"` — the new password was set but the
-     * configured {@link RevocableSessionService} threw before the user's other
-     * sessions could be revoked, so the reset is reported failed (and rethrown)
-     * rather than trusted. The reset token is already spent, so clear the
-     * still-live sessions by calling `revokeAllByUser` again from this event,
-     * or have the user complete a fresh reset link.
+     * Nothing changed.
+     *
+     * The other reasons fire after the link was spent, and the error is
+     * rethrown:
+     *
+     * - `"credential_write_failed"` — hashing or storing the new password
+     *   threw. The old password still works and no session was revoked; the
+     *   user requests a fresh link.
+     * - `"session_revocation_failed"` — the new password was set but the
+     *   configured `RevocableSessionService` threw before the user's other
+     *   sessions could be revoked. Call `revokeAllByUser(userId)` again.
+     * - `"lockout_reset_failed"` — the password changed and the sessions were
+     *   revoked, but clearing the failed-attempt lockout threw. Call
+     *   `reset(userId)` on the lockout, or let the lock lapse.
+     *
+     * A store that implements `IdentityUserStore.resetCredential` writes the
+     * password and revokes the sessions it holds together. A
+     * `"session_revocation_failed"` after that means the stored sessions
+     * were revoked and only the `sessions` service's own state was not.
      */
-    reason: "invalid_token" | "session_revocation_failed";
+    reason: "invalid_token" | "credential_write_failed" | "session_revocation_failed" | "lockout_reset_failed";
+    /** The account the spent link belonged to; absent for `"invalid_token"`. */
+    userId?: string;
 } | {
     type: "credential_mint.failed";
     /**

package/dist/identity/mfa/service.d.ts

@@ -69,7 +69,9 @@ export interface MfaStore {
     getRecoveryHashes(userId: string): Promise<string[]>;
     /**
      * Replace the user's recovery-code hashes with exactly this set — used for
-     * initial issue, regeneration, and disable (`[]`).
+     * initial issue, regeneration, and disable (`[]`). `MfaService` issues codes
+     * only once the TOTP credential is active, so a store may keep recovery
+     * hashes on the credential's record and drop a write for a user without one.
      */
     setRecoveryHashes(userId: string, hashes: string[]): Promise<void>;
     /**
@@ -189,7 +191,9 @@ export type MfaVerification = {
     method: "recovery";
     /**
      * How many unused recovery codes remain — surface it so the UI can
-     * prompt regeneration when low.
+     * prompt regeneration when low. Counted from the set read just before
+     * this code was burned, so a code burned concurrently is not yet
+     * subtracted.
      */
     remainingRecoveryCodes: number;
 };
@@ -285,7 +289,9 @@ export declare class MfaService {
      * accepted TOTP code advances the stored last step through
      * {@link MfaStore.advanceLastStep}, so the same code is rejected on replay;
      * an accepted recovery code is burned through
-     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. Both hold under
+     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. The remaining
+     * codes are read before the burn, so a store failure never spends a code
+     * without signing the user in. Both hold under
      * concurrent submission only if the store implements those methods
      * atomically. Without an
      * active credential every code is rejected — recovery codes are a fallback

package/dist/identity/mfa/service.js

@@ -153,7 +153,9 @@ export class MfaService {
      * accepted TOTP code advances the stored last step through
      * {@link MfaStore.advanceLastStep}, so the same code is rejected on replay;
      * an accepted recovery code is burned through
-     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. Both hold under
+     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. The remaining
+     * codes are read before the burn, so a store failure never spends a code
+     * without signing the user in. Both hold under
      * concurrent submission only if the store implements those methods
      * atomically. Without an
      * active credential every code is rejected — recovery codes are a fallback
@@ -255,11 +257,12 @@ export class MfaService {
         if (normalizeRecoveryCode(code).length !== RECOVERY_CODE_LENGTH) {
             return undefined;
         }
-        const consumed = await this.#store.consumeRecoveryHash(userId, await hashRecoveryCode(code));
-        if (!consumed)
+        const hash = await hashRecoveryCode(code);
+        const stored = await this.#store.getRecoveryHashes(userId);
+        if (!(await this.#store.consumeRecoveryHash(userId, hash))) {
             return undefined;
-        const remainingRecoveryCodes = (await this.#store.getRecoveryHashes(userId))
-            .length;
+        }
+        const remainingRecoveryCodes = stored.filter((candidate) => candidate !== hash).length;
         await this.#resetThrottle(userId);
         await this.#emit({
             type: "mfa.verify.succeeded",

package/dist/identity/service.d.ts

@@ -60,6 +60,22 @@ export interface IdentityUserStore<User extends IdentityUser> {
     getCredential(userId: string): Promise<PasswordCredential | undefined>;
     /** Replace the user's password credential (reset / change). */
     setCredential(userId: string, credential: PasswordCredential): Promise<void>;
+    /**
+     * Complete a password reset in one transaction: replace the credential,
+     * drop any imported hash, and revoke **every** session of the user. Return
+     * the number of sessions revoked. On a throw, none of the three may have
+     * happened.
+     *
+     * Optional. Implement it when the credential and the sessions share a
+     * database, so a session-store outage cannot leave a reset with the new
+     * password set and the old sessions live. When present,
+     * {@link IdentityService.resetPassword} calls it instead of
+     * {@link setCredential} and {@link clearLegacyCredential}. The reset link is
+     * still spent first. A configured `sessions` service is still called after
+     * this commits, for session state outside the transaction, such as a cache.
+     * Its `revokeAllByUser` then finds nothing left in the shared database.
+     */
+    resetCredential?(userId: string, credential: PasswordCredential): Promise<number>;
     /**
      * Atomically replace the credential only if it still equals `expected`.
      * `undefined` expects no native credential, for an imported-password upgrade.
@@ -188,7 +204,13 @@ export interface IdentityServiceOptions<User extends IdentityUser> {
      * Successful sign-ins are never delayed.
      */
     failedSignInFloorMs?: number;
-    /** Session revocation, called on a successful password reset. Optional. */
+    /**
+     * Session revocation, called on a successful password reset. Optional. When
+     * the user store implements {@link IdentityUserStore.resetCredential}, the
+     * reset still calls `revokeAllByUser` after that transaction commits, so
+     * session state the transaction cannot reach is revoked too. Omit it when
+     * the store's transaction already covers every place a session lives.
+     */
     sessions?: RevocableSessionService;
     /** Delivery transports for the emailed links and sign-in codes. Optional. */
     delivery?: DeliveryHooks;
@@ -468,19 +490,27 @@ export declare class IdentityService<User extends IdentityUser> {
      * redeemable until they expire) and, when an `otp` service is configured, the
      * pending sign-in code. Neither can fail the reset: a store that throws is
      * logged and the reset still completes, since the password has already
-     * changed by then.
+     * changed by then. Each is voided independently, so one store failing does
+     * not keep the other credential alive.
      *
      * 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. 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.
+     * nothing. Any failure after that point is reported, never swallowed: a
+     * `password_reset.failed` event carrying the `userId` and a reason
+     * (`credential_write_failed`, `session_revocation_failed` or
+     * `lockout_reset_failed`) fires, no `password_reset.completed` fires, and the
+     * error rethrows. Each reason names what already changed and how to finish
+     * the reset; see the event's documentation.
+     *
+     * Without {@link IdentityUserStore.resetCredential}, sessions are revoked
+     * **after** the password is changed, in a separate call, so a session-store
+     * outage leaves the new password set and the old sessions live. A store
+     * that implements it makes the password write and the revocation one
+     * transaction; a configured `sessions` service then runs after the commit
+     * and can still report `session_revocation_failed` for the state outside
+     * it. `password_reset.completed` carries `sessionsRevoked`, the sum of the
+     * counts the store and the `sessions` service reported.
      *
      * @throws {IdentityError} `weak_password` when `password` fails the password
      * policy — including the 8–256 character defaults that apply when
@@ -602,7 +632,9 @@ export declare class IdentityService<User extends IdentityUser> {
      * 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.
+     * does treating a since-deleted/disabled user as a failed sign-in. A
+     * throttle reset that throws is logged and the result is still `success`,
+     * since the code is already spent.
      */
     verifySignInCode(input: {
         email: string;

package/dist/identity/service.js

@@ -258,19 +258,27 @@ export class IdentityService {
      * redeemable until they expire) and, when an `otp` service is configured, the
      * pending sign-in code. Neither can fail the reset: a store that throws is
      * logged and the reset still completes, since the password has already
-     * changed by then.
+     * changed by then. Each is voided independently, so one store failing does
+     * not keep the other credential alive.
      *
      * 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. 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.
+     * nothing. Any failure after that point is reported, never swallowed: a
+     * `password_reset.failed` event carrying the `userId` and a reason
+     * (`credential_write_failed`, `session_revocation_failed` or
+     * `lockout_reset_failed`) fires, no `password_reset.completed` fires, and the
+     * error rethrows. Each reason names what already changed and how to finish
+     * the reset; see the event's documentation.
+     *
+     * Without {@link IdentityUserStore.resetCredential}, sessions are revoked
+     * **after** the password is changed, in a separate call, so a session-store
+     * outage leaves the new password set and the old sessions live. A store
+     * that implements it makes the password write and the revocation one
+     * transaction; a configured `sessions` service then runs after the commit
+     * and can still report `session_revocation_failed` for the state outside
+     * it. `password_reset.completed` carries `sessionsRevoked`, the sum of the
+     * counts the store and the `sessions` service reported.
      *
      * @throws {IdentityError} `weak_password` when `password` fails the password
      * policy — including the 8–256 character defaults that apply when
@@ -293,33 +301,55 @@ export class IdentityService {
         });
         if (consumed.status !== "success")
             return null;
-        const { resolved } = consumed;
-        await this.#users.setCredential(resolved.subject, await this.#passwords.hash(input.password));
-        try {
-            await this.#users.clearLegacyCredential?.(resolved.subject);
-        }
-        catch (error) {
-            console.error("[@udibo/oauth2] resetPassword legacy-credential clear failed:", error instanceof Error ? error.message : error);
-        }
-        await this.#voidPasswordlessCredentials(tokens, resolved.subject, emailFromData(resolved.data));
-        if (this.#sessions) {
-            try {
-                await this.#sessions.revokeAllByUser(resolved.subject);
+        const userId = consumed.resolved.subject;
+        const resetCredential = this.#users.resetCredential;
+        let sessionsRevoked;
+        await this.#failResetOnThrow(userId, "credential_write_failed", async () => {
+            const credential = await this.#passwords.hash(input.password);
+            if (resetCredential) {
+                sessionsRevoked = await resetCredential.call(this.#users, userId, credential);
             }
-            catch (error) {
-                await this.#emit({
-                    type: "password_reset.failed",
-                    reason: "session_revocation_failed",
-                });
-                throw error;
+            else {
+                await this.#users.setCredential(userId, credential);
             }
+        });
+        if (!resetCredential)
+            await this.#clearLegacyAfterReset(userId);
+        await this.#voidPasswordlessCredentials(tokens, userId, emailFromData(consumed.resolved.data));
+        const sessions = this.#sessions;
+        if (sessions) {
+            await this.#failResetOnThrow(userId, "session_revocation_failed", async () => {
+                sessionsRevoked =
+                    (sessionsRevoked ?? 0) + (await sessions.revokeAllByUser(userId));
+            });
+        }
+        const lockout = this.#lockout;
+        if (lockout) {
+            await this.#failResetOnThrow(userId, "lockout_reset_failed", () => lockout.reset(userId));
         }
-        await this.#lockout?.reset(resolved.subject);
         await this.#emit({
             type: "password_reset.completed",
-            userId: resolved.subject,
+            userId,
+            ...(sessionsRevoked === undefined ? {} : { sessionsRevoked }),
         });
-        return { userId: resolved.subject };
+        return { userId };
+    }
+    async #failResetOnThrow(userId, reason, step) {
+        try {
+            await step();
+        }
+        catch (error) {
+            await this.#emit({ type: "password_reset.failed", reason, userId });
+            throw error;
+        }
+    }
+    async #clearLegacyAfterReset(userId) {
+        try {
+            await this.#users.clearLegacyCredential?.(userId);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] resetPassword legacy-credential clear failed:", error instanceof Error ? error.message : error);
+        }
     }
     /**
      * Mint + deliver an email-verification link for a user. Typically called
@@ -565,7 +595,9 @@ export class IdentityService {
      * 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.
+     * does treating a since-deleted/disabled user as a failed sign-in. A
+     * throttle reset that throws is logged and the result is still `success`,
+     * since the code is already spent.
      */
     async verifySignInCode(input) {
         const otp = this.#requireOtp("verifySignInCode");
@@ -593,7 +625,12 @@ export class IdentityService {
             });
             return { status: "invalid" };
         }
-        await this.#resetThrottle("signInCode", email);
+        try {
+            await this.#resetThrottle("signInCode", email);
+        }
+        catch (error) {
+            this.#logPersistFailure("sign-in code throttle reset", error);
+        }
         await this.#emit({ type: "signin_code.verified", userId: user.id });
         return { status: "success", userId: user.id };
     }
@@ -719,14 +756,10 @@ export class IdentityService {
         });
     }
     async #voidPasswordlessCredentials(tokens, subject, email) {
-        try {
-            await tokens.invalidate(TokenPurpose.SignIn, subject);
-            if (email)
-                await this.#otp?.invalidate(email, TokenPurpose.SignIn);
-        }
-        catch (error) {
-            console.error("[@udibo/oauth2] resetPassword could not void the outstanding " +
-                "passwordless credentials; they stay usable until they expire:", error instanceof Error ? error.message : error);
+        await logVoidFailure("sign-in links", () => tokens.invalidate(TokenPurpose.SignIn, subject));
+        const otp = this.#otp;
+        if (email && otp) {
+            await logVoidFailure("sign-in code", () => otp.invalidate(email, TokenPurpose.SignIn));
         }
     }
     async #trapMintFailure(flow, mint) {
@@ -854,6 +887,15 @@ const DELIVERY_PURPOSES = {
     sendEmailVerification: TokenPurpose.EmailVerification,
     sendSignInLink: TokenPurpose.SignIn,
 };
+async function logVoidFailure(credential, invalidate) {
+    try {
+        await invalidate();
+    }
+    catch (error) {
+        console.error(`[@udibo/oauth2] resetPassword could not void the outstanding ` +
+            `${credential}, usable until expiry:`, error instanceof Error ? error.message : error);
+    }
+}
 function emailFromData(data) {
     const email = data?.email;
     return typeof email === "string" ? email : undefined;

package/dist/testing/contract/identity-user-store.d.ts

@@ -30,6 +30,18 @@ export interface IdentityUserStoreContractFixture<User extends IdentityUser> {
     isEmailVerified?(userId: string): Promise<boolean>;
     /** Seed an imported hash. Required for legacyCredentials. */
     setLegacyCredential?(userId: string, hash: string): Promise<void>;
+    /** Start a live session for the user and return its id. Required for resetCredential. */
+    startSession?(userId: string): Promise<string>;
+    /** Whether the application would still accept the session. Required for resetCredential. */
+    isSessionLive?(sessionId: string): Promise<boolean>;
+    /**
+     * Make the next resetCredential call throw at `step`, after the other
+     * writes have had their chance to run inside the transaction. Required for
+     * resetCredential: the suite calls it once for each step (`"legacy"` only
+     * with legacyCredentials) to prove that no write survives another failing,
+     * whichever order your transaction runs them in.
+     */
+    failNextReset?(step: "credential" | "legacy" | "sessions"): Promise<void> | void;
     /** Release resources and remove this test's records after all calls finish. */
     dispose?(): Promise<void> | void;
 }
@@ -45,6 +57,12 @@ export interface IdentityUserStoreContractOptions<User extends IdentityUser> {
     emailVerification?: boolean;
     /** Require imported credential lookup and clearing, plus its setup helper. */
     legacyCredentials?: boolean;
+    /**
+     * Require the transactional password-reset capability and its session and
+     * fault-injection helpers. With legacyCredentials, also checks that the
+     * reset drops the imported hash.
+     */
+    resetCredential?: boolean;
 }
 /**
  * Register the IdentityUserStore suite in a Vitest test file. Credential fixtures

package/dist/testing/contract/identity-user-store.js

@@ -137,6 +137,60 @@ export function runIdentityUserStoreContractTests(options) {
                 expect(await store.getCredential(other.id)).toStrictEqual(ORIGINAL);
             });
         }
+        if (options.resetCredential) {
+            async function resetSetup() {
+                assert.exists(store.resetCredential, "resetCredential capability is required");
+                assert.exists(fixture.startSession, "startSession setup helper is required");
+                assert.exists(fixture.isSessionLive, "isSessionLive setup helper is required");
+                const user = await create();
+                const other = await create(2);
+                if (options.legacyCredentials) {
+                    assert.exists(fixture.setLegacyCredential);
+                    await fixture.setLegacyCredential(user.id, "imported-hash-one");
+                }
+                return {
+                    user,
+                    other,
+                    sessions: [
+                        await fixture.startSession(user.id),
+                        await fixture.startSession(user.id),
+                    ],
+                    otherSession: await fixture.startSession(other.id),
+                };
+            }
+            async function liveness(ids) {
+                return await Promise.all(ids.map((id) => fixture.isSessionLive(id)));
+            }
+            it("resets the credential and revokes every session of the user, and only that user", async () => {
+                const { user, other, sessions, otherSession } = await resetSetup();
+                expect(await store.resetCredential(user.id, structuredClone(REPLACEMENT)), "resetCredential must report the sessions it revoked").toStrictEqual(2);
+                expect(await store.getCredential(user.id)).toStrictEqual(REPLACEMENT);
+                expect(await liveness(sessions), "resetCredential revokes every session of the user").toStrictEqual([false, false]);
+                if (options.legacyCredentials) {
+                    expect(await store.getLegacyCredential(user.id), "resetCredential drops the imported hash").toBe(null);
+                }
+                expect(await store.getCredential(other.id)).toStrictEqual(ORIGINAL);
+                expect(await fixture.isSessionLive(otherSession), "resetCredential must not revoke another user's sessions").toBe(true);
+                expect(await store.resetCredential(user.id, structuredClone(REPLACEMENT))).toStrictEqual(0);
+            });
+            const steps = options.legacyCredentials
+                ? ["credential", "legacy", "sessions"]
+                : ["credential", "sessions"];
+            for (const step of steps) {
+                it(`changes nothing when the reset fails at the ${step} step`, async () => {
+                    const { user, sessions } = await resetSetup();
+                    assert.exists(fixture.failNextReset, "failNextReset fault-injection helper is required");
+                    await fixture.failNextReset(step);
+                    const outcome = await store.resetCredential(user.id, structuredClone(REPLACEMENT)).then(() => "resolved", () => "rejected");
+                    expect(outcome, "resetCredential must reject when failNextReset injected a failure").toStrictEqual("rejected");
+                    expect(await store.getCredential(user.id), "a failed reset must leave the credential unchanged").toStrictEqual(ORIGINAL);
+                    expect(await liveness(sessions), "a failed reset must leave the sessions live").toStrictEqual([true, true]);
+                    if (options.legacyCredentials) {
+                        expect(await store.getLegacyCredential(user.id), "a failed reset must leave the imported hash in place").toStrictEqual("imported-hash-one");
+                    }
+                });
+            }
+        }
         if (options.emailVerification) {
             it("verifies only the issued-for email and is idempotent", async () => {
                 const user = await create();

package/dist/testing/contract/lockout-store.d.ts

@@ -31,6 +31,17 @@ export interface LockoutStoreContractOptions {
      * asserts.
      */
     makeStore(): Promise<LockoutStore> | LockoutStore;
+    /**
+     * The account the cases act on, in your application's id format. A store
+     * that keeps the count on the user's own row needs it to name a user that
+     * exists. Defaults to `"user-1"`.
+     */
+    userId?: string;
+    /**
+     * A second account, distinct from {@link LockoutStoreContractOptions.userId},
+     * whose count must stay apart from the first. Defaults to `"user-2"`.
+     */
+    otherUserId?: string;
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"LockoutStore contract"`.

package/dist/testing/contract/lockout-store.js

@@ -23,8 +23,6 @@
  * @module
  */
 import { beforeEach, describe, expect, it } from "vitest";
-const USER = "user-1";
-const OTHER_USER = "user-2";
 /**
  * Runs the {@link LockoutStore} contract suite. Call it from your own test
  * file — it registers `describe` / `it` blocks the test runner picks up.
@@ -33,6 +31,8 @@ const OTHER_USER = "user-2";
  * clock-free and never need a timer.
  */
 export function runLockoutStoreContractTests(options) {
+    const USER = options.userId ?? "user-1";
+    const OTHER_USER = options.otherUserId ?? "user-2";
     describe(options.describeName ?? "LockoutStore contract", () => {
         let store;
         let now;

package/dist/testing/contract/mfa-store.d.ts

@@ -32,6 +32,17 @@ export interface MfaStoreContractOptions {
      * meaningless.
      */
     makeStore(): Promise<MfaStore> | MfaStore;
+    /**
+     * The user the cases act on, in your application's id format. A store whose
+     * rows reference a users table needs it to name a user that exists. Defaults
+     * to `"user-1"`.
+     */
+    userId?: string;
+    /**
+     * A second user, distinct from {@link MfaStoreContractOptions.userId}, whose
+     * records must stay apart from the first. Defaults to `"user-2"`.
+     */
+    otherUserId?: string;
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"MfaStore contract"`.

package/dist/testing/contract/mfa-store.js

@@ -25,8 +25,6 @@
  */
 import { beforeEach, describe, expect, it } from "vitest";
 import { CONCURRENT_CALLERS, race } from "./_race.js";
-const USER = "user-1";
-const OTHER_USER = "user-2";
 const SECRET_A = "AAAAAAAAAAAAAAAA";
 const SECRET_B = "BBBBBBBBBBBBBBBB";
 function countTrue(results) {
@@ -43,6 +41,8 @@ function countTrue(results) {
  * probabilistic, so a lucky interleaving can still pass a single run.
  */
 export function runMfaStoreContractTests(options) {
+    const USER = options.userId ?? "user-1";
+    const OTHER_USER = options.otherUserId ?? "user-2";
     describe(options.describeName ?? "MfaStore contract", () => {
         let store;
         beforeEach(async () => {
@@ -165,7 +165,19 @@ export function runMfaStoreContractTests(options) {
                 expect((await store.getTotp(USER))?.lastStep, "the highest accepted step must survive a concurrent lower one").toStrictEqual(105);
             });
         });
+        describe("recovery hashes for a user without a credential", () => {
+            it("reads none and redeems none", async () => {
+                expect(await store.getRecoveryHashes(OTHER_USER)).toStrictEqual([]);
+                expect(await store.consumeRecoveryHash(OTHER_USER, "h1")).toBe(false);
+            });
+        });
         describe("recovery hashes", () => {
+            beforeEach(async () => {
+                for (const user of [USER, OTHER_USER]) {
+                    await store.setPendingTotp(user, SECRET_A);
+                    await store.activateTotp(user, SECRET_A, 1);
+                }
+            });
             it("returns an empty list for a user with none", async () => {
                 expect(await store.getRecoveryHashes(USER)).toStrictEqual([]);
             });

package/dist/testing/contract/otp-store.d.ts

@@ -41,6 +41,9 @@ export interface OtpStoreContractOptions {
  * Runs the {@link OtpStore} contract suite. Call it from your own test file —
  * it registers `describe` / `it` blocks the test runner picks up.
  *
+ * Record ids, known and unknown alike, are UUIDs — the ids `EmailOtpService`
+ * issues — so a store with a `uuid` id column accepts every one.
+ *
  * The concurrency case fires overlapping `recordAttempt` calls and requires
  * each to see a distinct count; a store that reads, awaits, then writes hands
  * the same count to every guess and fails it.

package/dist/testing/contract/otp-store.js

@@ -28,11 +28,10 @@ const EMAIL = "user@example.com";
 const OTHER_EMAIL = "other@example.com";
 const PURPOSE = "signin";
 const OTHER_PURPOSE = "step-up";
-let sequence = 0;
 function record(overrides = {}) {
     const now = Date.now();
     return {
-        id: `otp-${++sequence}`,
+        id: crypto.randomUUID(),
         email: EMAIL,
         purpose: PURPOSE,
         codeHash: "hash",
@@ -47,6 +46,9 @@ function record(overrides = {}) {
  * Runs the {@link OtpStore} contract suite. Call it from your own test file —
  * it registers `describe` / `it` blocks the test runner picks up.
  *
+ * Record ids, known and unknown alike, are UUIDs — the ids `EmailOtpService`
+ * issues — so a store with a `uuid` id column accepts every one.
+ *
  * The concurrency case fires overlapping `recordAttempt` calls and requires
  * each to see a distinct count; a store that reads, awaits, then writes hands
  * the same count to every guess and fails it.
@@ -100,7 +102,7 @@ export function runOtpStoreContractTests(options) {
                 const results = await race(() => store.consume(created.id));
                 expect(results.filter((claimed) => claimed).length, "a code is single-use — consumers racing one code must not each " +
                     "be told they claimed it").toBe(1);
-                expect(await store.consume("missing-code")).toBe(false);
+                expect(await store.consume(crypto.randomUUID())).toBe(false);
             });
             it("takes the record out of the active set", async () => {
                 const created = record();
@@ -120,7 +122,7 @@ export function runOtpStoreContractTests(options) {
             it("is a no-op for an unknown id", async () => {
                 const created = record();
                 await store.create(created);
-                await store.consume("no-such-id");
+                await store.consume(crypto.randomUUID());
                 expect((await store.findActive(EMAIL, PURPOSE))?.id).toBe(created.id);
             });
         });
@@ -138,7 +140,7 @@ export function runOtpStoreContractTests(options) {
             it("is a no-op for an unknown id", async () => {
                 const created = record();
                 await store.create(created);
-                await store.invalidateById("no-such-id");
+                await store.invalidateById(crypto.randomUUID());
                 expect((await store.findActive(EMAIL, PURPOSE))?.id).toBe(created.id);
             });
         });
@@ -171,7 +173,7 @@ export function runOtpStoreContractTests(options) {
                 expect(await store.recordAttempt(created.id)).toBe(3);
             });
             it("returns 0 for an unknown id", async () => {
-                expect(await store.recordAttempt("no-such-id")).toBe(0);
+                expect(await store.recordAttempt(crypto.randomUUID())).toBe(0);
             });
             it("counts each record separately", async () => {
                 const mine = record();

package/dist/testing/contract/token-flow-store.d.ts

@@ -38,6 +38,18 @@ export interface TokenFlowStoreContractOptions {
      * that meant to implement it and does not fails loudly.
      */
     deleteBySubject?: boolean;
+    /**
+     * The subject the cases issue tokens for, in your application's id format. A
+     * store whose rows reference a users table needs it to name a user that
+     * exists. Defaults to `"user-1"`.
+     */
+    subject?: string;
+    /**
+     * A second subject, distinct from
+     * {@link TokenFlowStoreContractOptions.subject}, whose tokens must survive
+     * operations on the first. Defaults to `"user-2"`.
+     */
+    otherSubject?: string;
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"TokenFlowStore contract"`.
@@ -48,6 +60,9 @@ export interface TokenFlowStoreContractOptions {
  * Runs the {@link TokenFlowStore} contract suite. Call it from your own test
  * file — it registers `describe` / `it` blocks the test runner picks up.
  *
+ * Token hashes are unique to each test, so a store whose hash column is unique
+ * across tenants or test files never collides with an earlier run's rows.
+ *
  * The concurrency cases redeem one token from eight callers at once. A store
  * that reads, awaits, then writes hands the token to more than one of them and
  * fails in practice — a race is probabilistic, so a lucky interleaving can

package/dist/testing/contract/token-flow-store.js

@@ -25,25 +25,16 @@ import { assert, beforeEach, describe, expect, it } from "vitest";
 import { CONCURRENT_CALLERS, race } from "./_race.js";
 const PURPOSE = "password-reset";
 const OTHER_PURPOSE = "email-verification";
-const SUBJECT = "user-1";
-const OTHER_SUBJECT = "user-2";
 function countTrue(results) {
     return results.filter((result) => result).length;
 }
-function record(overrides) {
-    const now = Date.now();
-    return {
-        purpose: PURPOSE,
-        subject: SUBJECT,
-        expiresAt: now + 60_000,
-        createdAt: now,
-        ...overrides,
-    };
-}
 /**
  * Runs the {@link TokenFlowStore} contract suite. Call it from your own test
  * file — it registers `describe` / `it` blocks the test runner picks up.
  *
+ * Token hashes are unique to each test, so a store whose hash column is unique
+ * across tenants or test files never collides with an earlier run's rows.
+ *
  * The concurrency cases redeem one token from eight callers at once. A store
  * that reads, awaits, then writes hands the token to more than one of them and
  * fails in practice — a race is probabilistic, so a lucky interleaving can
@@ -51,22 +42,39 @@ function record(overrides) {
  */
 export function runTokenFlowStoreContractTests(options) {
     const expectDeleteBySubject = options.deleteBySubject ?? true;
+    const SUBJECT = options.subject ?? "user-1";
+    const OTHER_SUBJECT = options.otherSubject ?? "user-2";
     describe(options.describeName ?? "TokenFlowStore contract", () => {
         let store;
+        let testId;
+        function hash(name) {
+            return `hash-${name}-${testId}`;
+        }
+        function record(overrides) {
+            const now = Date.now();
+            return {
+                purpose: PURPOSE,
+                subject: SUBJECT,
+                expiresAt: now + 60_000,
+                createdAt: now,
+                ...overrides,
+            };
+        }
         beforeEach(async () => {
+            testId = crypto.randomUUID();
             store = await options.makeStore();
         });
         describe("save / get", () => {
             it("returns null for an unknown token hash", async () => {
-                expect(await store.get("no-such-hash")).toBe(null);
+                expect(await store.get(hash("unknown"))).toBe(null);
             });
             it("round-trips every field of a saved record", async () => {
                 const saved = record({
-                    tokenHash: "hash-1",
+                    tokenHash: hash("1"),
                     data: { email: "user@example.com" },
                 });
                 await store.save(saved);
-                const fetched = await store.get("hash-1");
+                const fetched = await store.get(hash("1"));
                 assert(fetched !== null, "a saved record must be readable back");
                 expect(fetched.purpose).toStrictEqual(saved.purpose);
                 expect(fetched.subject).toStrictEqual(saved.subject);
@@ -76,53 +84,53 @@ export function runTokenFlowStoreContractTests(options) {
                 expect(fetched.consumedAt).toBe(undefined);
             });
             it("returns an expired record rather than hiding it", async () => {
-                await store.save(record({ tokenHash: "hash-expired", expiresAt: Date.now() - 1000 }));
-                const fetched = await store.get("hash-expired");
+                await store.save(record({ tokenHash: hash("expired"), expiresAt: Date.now() - 1000 }));
+                const fetched = await store.get(hash("expired"));
                 assert(fetched !== null, "expiry is the service's call — it reports `expired` distinctly " +
                     "from `invalid`, which it cannot do if the store swallows the row");
             });
             it("keeps records with different hashes independent", async () => {
-                await store.save(record({ tokenHash: "hash-1" }));
-                await store.save(record({ tokenHash: "hash-2" }));
-                expect((await store.get("hash-1"))?.tokenHash).toBe("hash-1");
-                expect((await store.get("hash-2"))?.tokenHash).toBe("hash-2");
+                await store.save(record({ tokenHash: hash("1") }));
+                await store.save(record({ tokenHash: hash("2") }));
+                expect((await store.get(hash("1")))?.tokenHash).toBe(hash("1"));
+                expect((await store.get(hash("2")))?.tokenHash).toBe(hash("2"));
             });
         });
         describe("markConsumed", () => {
             it("claims a live record and stamps it", async () => {
-                await store.save(record({ tokenHash: "hash-1" }));
+                await store.save(record({ tokenHash: hash("1") }));
                 const consumedAt = Date.now();
-                expect(await store.markConsumed("hash-1", consumedAt)).toBe(true);
-                expect((await store.get("hash-1"))?.consumedAt).toBe(consumedAt);
+                expect(await store.markConsumed(hash("1"), consumedAt)).toBe(true);
+                expect((await store.get(hash("1")))?.consumedAt).toBe(consumedAt);
             });
             it("refuses a record already consumed, keeping the first stamp", async () => {
-                await store.save(record({ tokenHash: "hash-1" }));
+                await store.save(record({ tokenHash: hash("1") }));
                 const first = Date.now();
-                await store.markConsumed("hash-1", first);
-                expect(await store.markConsumed("hash-1", first + 5_000)).toBe(false);
-                expect((await store.get("hash-1"))?.consumedAt, "a losing claim must not overwrite the winner's record").toBe(first);
+                await store.markConsumed(hash("1"), first);
+                expect(await store.markConsumed(hash("1"), first + 5_000)).toBe(false);
+                expect((await store.get(hash("1")))?.consumedAt, "a losing claim must not overwrite the winner's record").toBe(first);
             });
             it("refuses an unknown token hash", async () => {
-                expect(await store.markConsumed("no-such-hash", Date.now())).toBe(false);
+                expect(await store.markConsumed(hash("unknown"), Date.now())).toBe(false);
             });
             it(`claims a token for exactly one of ${CONCURRENT_CALLERS} concurrent redemptions`, async () => {
-                await store.save(record({ tokenHash: "hash-1" }));
+                await store.save(record({ tokenHash: hash("1") }));
                 const now = Date.now();
-                const results = await race((caller) => store.markConsumed("hash-1", now + caller));
+                const results = await race((caller) => store.markConsumed(hash("1"), now + caller));
                 expect(countTrue(results), "a link is single-use — requests racing one link must not each be " +
                     "told they claimed it").toBe(1);
             });
             it("claims both tokens when two different ones are redeemed concurrently", async () => {
-                await store.save(record({ tokenHash: "hash-1" }));
-                await store.save(record({ tokenHash: "hash-2" }));
+                await store.save(record({ tokenHash: hash("1") }));
+                await store.save(record({ tokenHash: hash("2") }));
                 const now = Date.now();
                 const results = await Promise.all([
-                    store.markConsumed("hash-1", now),
-                    store.markConsumed("hash-2", now),
+                    store.markConsumed(hash("1"), now),
+                    store.markConsumed(hash("2"), now),
                 ]);
                 expect(countTrue(results)).toBe(2);
-                assert((await store.get("hash-1"))?.consumedAt !== undefined &&
-                    (await store.get("hash-2"))?.consumedAt !== undefined, "neither stamp may be lost to the other's stale read");
+                assert((await store.get(hash("1")))?.consumedAt !== undefined &&
+                    (await store.get(hash("2")))?.consumedAt !== undefined, "neither stamp may be lost to the other's stale read");
             });
         });
         if (expectDeleteBySubject) {
@@ -134,33 +142,39 @@ export function runTokenFlowStoreContractTests(options) {
                         "`deleteBySubject: false` to record the gap.");
                 });
                 it("drops the pending tokens for one (purpose, subject)", async () => {
-                    await store.save(record({ tokenHash: "hash-1" }));
-                    await store.save(record({ tokenHash: "hash-2" }));
+                    await store.save(record({ tokenHash: hash("1") }));
+                    await store.save(record({ tokenHash: hash("2") }));
                     await store.deleteBySubject(PURPOSE, SUBJECT);
-                    expect(await store.get("hash-1")).toBe(null);
-                    expect(await store.get("hash-2")).toBe(null);
+                    expect(await store.get(hash("1"))).toBe(null);
+                    expect(await store.get(hash("2"))).toBe(null);
                 });
                 it("leaves other subjects and other purposes alone", async () => {
-                    await store.save(record({ tokenHash: "hash-mine" }));
-                    await store.save(record({ tokenHash: "hash-other-subject", subject: OTHER_SUBJECT }));
-                    await store.save(record({ tokenHash: "hash-other-purpose", purpose: OTHER_PURPOSE }));
+                    await store.save(record({ tokenHash: hash("mine") }));
+                    await store.save(record({
+                        tokenHash: hash("other-subject"),
+                        subject: OTHER_SUBJECT,
+                    }));
+                    await store.save(record({
+                        tokenHash: hash("other-purpose"),
+                        purpose: OTHER_PURPOSE,
+                    }));
                     await store.deleteBySubject(PURPOSE, SUBJECT);
-                    expect(await store.get("hash-mine")).toBe(null);
-                    assert((await store.get("hash-other-subject")) !== null, "another subject's token must survive");
-                    assert((await store.get("hash-other-purpose")) !== null, "the same subject's token for another purpose must survive");
+                    expect(await store.get(hash("mine"))).toBe(null);
+                    assert((await store.get(hash("other-subject"))) !== null, "another subject's token must survive");
+                    assert((await store.get(hash("other-purpose"))) !== null, "the same subject's token for another purpose must survive");
                 });
                 it("is a no-op when the pair has no tokens", async () => {
-                    await store.save(record({ tokenHash: "hash-1" }));
+                    await store.save(record({ tokenHash: hash("1") }));
                     await store.deleteBySubject(PURPOSE, OTHER_SUBJECT);
-                    assert((await store.get("hash-1")) !== null);
+                    assert((await store.get(hash("1"))) !== null);
                 });
                 it("keeps an already-consumed record so it still reads as consumed", async () => {
-                    await store.save(record({ tokenHash: "hash-used" }));
-                    await store.save(record({ tokenHash: "hash-pending" }));
-                    expect(await store.markConsumed("hash-used", Date.now())).toBe(true);
+                    await store.save(record({ tokenHash: hash("used") }));
+                    await store.save(record({ tokenHash: hash("pending") }));
+                    expect(await store.markConsumed(hash("used"), Date.now())).toBe(true);
                     await store.deleteBySubject(PURPOSE, SUBJECT);
-                    expect(await store.get("hash-pending"), "the pending token must be dropped").toBe(null);
-                    const used = await store.get("hash-used");
+                    expect(await store.get(hash("pending")), "the pending token must be dropped").toBe(null);
+                    const used = await store.get(hash("used"));
                     assert(used !== null, "a consumed record must survive so inspect() can answer " +
                         "`consumed` rather than the generic `invalid`");
                     assert(used.consumedAt !== undefined, "the surviving record must still carry its consumedAt stamp");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.37.0",
+  "version": "0.39.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",