@udibo/oauth2 0.38.0 → 0.40.0

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>;
     /**

package/dist/identity/otp.d.ts

@@ -67,8 +67,10 @@ export interface OtpStore {
     /** Persist a new active record. */
     create(record: OtpRecord): Promise<void>;
     /**
-     * The most recently created active record for `(email, purpose)`, or `null`.
-     * Must still return an expired record — the service reports expiry itself.
+     * The active record with the greatest `createdAt` for `(email, purpose)`, or
+     * `null` — ordered by `createdAt`, never by insertion, since `consume`
+     * retires records by the same field. Must still return an expired record —
+     * the service reports expiry itself.
      */
     findActive(email: string, purpose: string): Promise<OtpRecord | null>;
     /**
@@ -84,6 +86,13 @@ export interface OtpStore {
      * Atomically consume an active code. Return `true` only to the caller that
      * removed it from the active set; concurrent or repeated claims return
      * `false`. Use a conditional delete/update with RETURNING in persistent stores.
+     *
+     * A successful claim also deactivates every other active record for the same
+     * `(email, purpose)` created no later than the claimed one, in the same
+     * atomic operation, so a sign-in with the newest code leaves no older code
+     * redeemable. Records created after it, other pairs, and — when the claim
+     * fails — every record stay active. A store that keeps one active code per
+     * pair already satisfies this.
      */
     consume(id: string): Promise<boolean>;
     /**
@@ -91,7 +100,8 @@ export interface OtpStore {
      * the send carrying it failed. Separate from {@link OtpStore.consume} so a
      * store that records *why* a code left the active set can tell a redeemed
      * code from a discarded one, and from {@link OtpStore.invalidate} so a
-     * concurrent request's newer code survives. A no-op for an unknown id.
+     * concurrent request's code survives, older or newer. Unlike `consume`, it
+     * deactivates no other record. A no-op for an unknown id.
      */
     invalidateById(id: string): Promise<void>;
     /** Deactivate every active record for `(email, purpose)`. */
@@ -237,7 +247,9 @@ export declare class EmailOtpService {
      * value — **before** the compare, so concurrent verifies of one live code
      * can't each test a guess against a stale pre-increment count: at most
      * `maxAttempts` guesses ever reach the comparison. Spending the budget
-     * invalidates the code (`locked`); success consumes it (single-use).
+     * invalidates the code (`locked`); success consumes it (single-use) and,
+     * through {@link OtpStore.consume}, retires any older code for the pair that
+     * overlapping requests left active.
      */
     verify(options: VerifyOtpOptions): Promise<VerifyOtpResult>;
 }
@@ -249,11 +261,18 @@ export declare class MemoryOtpStore implements OtpStore {
     #private;
     /** Persist a record and mark it active. */
     create(record: OtpRecord): Promise<void>;
-    /** The newest active record for `(email, purpose)`, expired or not; else `null`. */
+    /**
+     * The active record with the greatest `createdAt` for `(email, purpose)`,
+     * expired or not; else `null`.
+     */
     findActive(email: string, purpose: string): Promise<OtpRecord | null>;
     /** Bump a record's attempt count; returns the new count, or 0 if unknown. */
     recordAttempt(id: string): Promise<number>;
-    /** Atomically deactivate one active record; return whether it was claimed. */
+    /**
+     * Atomically deactivate one active record and, when it was claimed, the
+     * older active records for its `(email, purpose)`; return whether it was
+     * claimed.
+     */
     consume(id: string): Promise<boolean>;
     /** Deactivate one undelivered record; a no-op if the id is unknown. */
     invalidateById(id: string): Promise<void>;

package/dist/identity/otp.js

@@ -160,7 +160,9 @@ export class EmailOtpService {
      * value — **before** the compare, so concurrent verifies of one live code
      * can't each test a guess against a stale pre-increment count: at most
      * `maxAttempts` guesses ever reach the comparison. Spending the budget
-     * invalidates the code (`locked`); success consumes it (single-use).
+     * invalidates the code (`locked`); success consumes it (single-use) and,
+     * through {@link OtpStore.consume}, retires any older code for the pair that
+     * overlapping requests left active.
      */
     async verify(options) {
         const { purpose } = options;
@@ -204,7 +206,10 @@ export class MemoryOtpStore {
         this.#active.add(record.id);
         return Promise.resolve();
     }
-    /** The newest active record for `(email, purpose)`, expired or not; else `null`. */
+    /**
+     * The active record with the greatest `createdAt` for `(email, purpose)`,
+     * expired or not; else `null`.
+     */
     findActive(email, purpose) {
         let latest = null;
         for (const id of this.#active) {
@@ -226,9 +231,25 @@ export class MemoryOtpStore {
         record.attempts++;
         return Promise.resolve(record.attempts);
     }
-    /** Atomically deactivate one active record; return whether it was claimed. */
+    /**
+     * Atomically deactivate one active record and, when it was claimed, the
+     * older active records for its `(email, purpose)`; return whether it was
+     * claimed.
+     */
     consume(id) {
-        return Promise.resolve(this.#active.delete(id));
+        const claimed = this.#records.get(id);
+        if (!claimed || !this.#active.delete(id))
+            return Promise.resolve(false);
+        for (const activeId of [...this.#active]) {
+            const record = this.#records.get(activeId);
+            if (record &&
+                record.email === claimed.email &&
+                record.purpose === claimed.purpose &&
+                record.createdAt <= claimed.createdAt) {
+                this.#active.delete(activeId);
+            }
+        }
+        return Promise.resolve(true);
     }
     /** Deactivate one undelivered record; a no-op if the id is unknown. */
     invalidateById(id) {

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

@@ -5,7 +5,9 @@
  * A six-digit code is guessable online, so the attempt budget is the only thing
  * standing between an attacker and a one-in-a-million draw. `recordAttempt` is
  * what enforces it, and it only enforces it when concurrent guesses cannot
- * share a count — which is what this suite checks.
+ * share a count — which is what this suite checks. It also checks that a
+ * successful `consume` retires the pair's older codes, so a sign-in with the
+ * newest code leaves no earlier one redeemable.
  *
  * @example Verify a database-backed store
  * ```ts
@@ -22,7 +24,7 @@
  *
  * @module
  */
-import type { OtpStore } from "../../identity/otp.ts";
+import { type OtpStore } from "../../identity/otp.ts";
 /** Options for {@link runOtpStoreContractTests}. */
 export interface OtpStoreContractOptions {
     /**
@@ -31,6 +33,19 @@ export interface OtpStoreContractOptions {
      * meaningless.
      */
     makeStore(): Promise<OtpStore> | OtpStore;
+    /**
+     * Set to `true` for a store that keeps at most one active code per
+     * `(email, purpose)`, where `create` replaces the pair's code — for example
+     * an upsert on a unique `(email, purpose)` index. Such a store conforms: the
+     * suite then requires `create` to replace the code, so the replaced code's
+     * id no longer consumes, and drops the cases that need two codes active at
+     * once. The trade-off is availability: when overlapping requests each send a
+     * code and the later send fails, discarding the later code leaves no code
+     * the user can enter, where a store keeping several codes leaves the one
+     * already delivered. Defaults to `false`; a store that keeps several codes
+     * and sets it fails the replacement case.
+     */
+    oneActiveCode?: boolean;
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"OtpStore contract"`.
@@ -41,8 +56,15 @@ 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.
+ * the same count to every guess and fails it. The `consume` cases require a
+ * successful claim to retire every older active code for the pair, and to
+ * leave newer codes, other pairs and — when the claim fails — everything else
+ * active. Register a store that keeps one code per pair with
+ * `oneActiveCode: true`.
  */
 export declare function runOtpStoreContractTests(options: OtpStoreContractOptions): void;

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

@@ -5,7 +5,9 @@
  * A six-digit code is guessable online, so the attempt budget is the only thing
  * standing between an attacker and a one-in-a-million draw. `recordAttempt` is
  * what enforces it, and it only enforces it when concurrent guesses cannot
- * share a count — which is what this suite checks.
+ * share a count — which is what this suite checks. It also checks that a
+ * successful `consume` retires the pair's older codes, so a sign-in with the
+ * newest code leaves no earlier one redeemable.
  *
  * @example Verify a database-backed store
  * ```ts
@@ -23,16 +25,16 @@
  * @module
  */
 import { assert, beforeEach, describe, expect, it } from "vitest";
+import { EmailOtpService, } from "../../identity/otp.js";
 import { CONCURRENT_CALLERS, race } from "./_race.js";
 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,11 +49,20 @@ 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.
+ * the same count to every guess and fails it. The `consume` cases require a
+ * successful claim to retire every older active code for the pair, and to
+ * leave newer codes, other pairs and — when the claim fails — everything else
+ * active. Register a store that keeps one code per pair with
+ * `oneActiveCode: true`.
  */
 export function runOtpStoreContractTests(options) {
+    const oneActiveCode = options.oneActiveCode ?? false;
+    const manyActiveCodes = !oneActiveCode;
     describe(options.describeName ?? "OtpStore contract", () => {
         let store;
         beforeEach(async () => {
@@ -82,6 +93,31 @@ export function runOtpStoreContractTests(options) {
                 await store.create(newer);
                 expect((await store.findActive(EMAIL, PURPOSE))?.id, "a re-send supersedes the code before it").toBe(newer.id);
             });
+            if (oneActiveCode) {
+                it("replaces the pair's active code (oneActiveCode)", async () => {
+                    const now = Date.now();
+                    const older = record({ createdAt: now - 1000, codeHash: "old" });
+                    const newer = record({ createdAt: now, codeHash: "new" });
+                    await store.create(older);
+                    await store.create(newer);
+                    expect(await store.consume(older.id), "`oneActiveCode: true` declares that a new code replaces the " +
+                        "pair's code; this store kept the older one active").toBe(false);
+                    expect((await store.findActive(EMAIL, PURPOSE))?.id).toBe(newer.id);
+                });
+                it.skip("a store keeping one code per pair returns the code created last, whatever its createdAt — there is no other code to order it against (oneActiveCode: true)", () => { });
+            }
+            else {
+                it("returns the greatest createdAt, not the last inserted", async () => {
+                    const now = Date.now();
+                    const higher = record({ createdAt: now });
+                    const lower = record({ createdAt: now - 1000 });
+                    await store.create(higher);
+                    await store.create(lower);
+                    expect((await store.findActive(EMAIL, PURPOSE))?.id, "verify consumes the record findActive returns and consume " +
+                        "retires records created no later than it; ordering by " +
+                        "insertion under clock drift leaves the other code redeemable").toBe(higher.id);
+                });
+            }
             it("returns an expired record rather than hiding it", async () => {
                 await store.create(record({ expiresAt: Date.now() - 1000 }));
                 assert((await store.findActive(EMAIL, PURPOSE)) !== null, "expiry is the service's call — it reports `expired` distinctly " +
@@ -100,7 +136,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();
@@ -108,37 +144,94 @@ export function runOtpStoreContractTests(options) {
                 await store.consume(created.id);
                 expect(await store.findActive(EMAIL, PURPOSE)).toBe(null);
             });
-            it("leaves an older active code findable", async () => {
+            it("retires every older active code for the pair", async () => {
                 const now = Date.now();
+                const oldest = record({ createdAt: now - 2000 });
                 const older = record({ createdAt: now - 1000 });
-                const newer = record({ createdAt: now });
+                const newest = record({ createdAt: now });
+                await store.create(oldest);
                 await store.create(older);
-                await store.create(newer);
-                await store.consume(newer.id);
-                expect((await store.findActive(EMAIL, PURPOSE))?.id).toBe(older.id);
+                await store.create(newest);
+                expect(await store.consume(newest.id)).toBe(true);
+                expect(await store.findActive(EMAIL, PURPOSE), "a sign-in with the newest code must end the older codes' window; " +
+                    "otherwise each stays redeemable until it expires").toBe(null);
+                expect(await store.consume(older.id)).toBe(false);
+                expect(await store.consume(oldest.id)).toBe(false);
+            });
+            if (manyActiveCodes) {
+                it("leaves a code newer than the claimed one active", async () => {
+                    const now = Date.now();
+                    const claimed = record({ createdAt: now - 1000 });
+                    const newer = record({ createdAt: now });
+                    await store.create(claimed);
+                    await store.create(newer);
+                    expect(await store.consume(claimed.id)).toBe(true);
+                    expect((await store.findActive(EMAIL, PURPOSE))?.id, "a code a concurrent request minted after the claimed one " +
+                        "is not older than it and must survive").toBe(newer.id);
+                });
+                it("retires nothing when the claim fails", async () => {
+                    const now = Date.now();
+                    const older = record({ createdAt: now - 1000 });
+                    const discarded = record({ createdAt: now });
+                    await store.create(older);
+                    await store.create(discarded);
+                    await store.invalidateById(discarded.id);
+                    expect(await store.consume(discarded.id)).toBe(false);
+                    expect((await store.findActive(EMAIL, PURPOSE))?.id, "only a successful claim retires older codes; a stale or " +
+                        "repeated consume must leave the delivered code usable").toBe(older.id);
+                });
+            }
+            else {
+                it.skip("a store keeping one code per pair has no newer or older code beside the claimed one — a re-send replaces the code a sign-in is verifying, so that sign-in reports invalid and the user enters the new code (oneActiveCode: true)", () => { });
+            }
+            it("leaves other emails and other purposes active", async () => {
+                const claimed = record();
+                const otherEmail = record({ email: OTHER_EMAIL });
+                const otherPurpose = record({ purpose: OTHER_PURPOSE });
+                await store.create(claimed);
+                await store.create(otherEmail);
+                await store.create(otherPurpose);
+                expect(await store.consume(claimed.id)).toBe(true);
+                expect((await store.findActive(OTHER_EMAIL, PURPOSE))?.id).toBe(otherEmail.id);
+                expect((await store.findActive(EMAIL, OTHER_PURPOSE))?.id).toBe(otherPurpose.id);
             });
             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);
             });
         });
         describe("invalidateById", () => {
-            it("deactivates only the named record", async () => {
+            if (manyActiveCodes) {
+                it("deactivates only the named record", async () => {
+                    const now = Date.now();
+                    const undelivered = record({ createdAt: now });
+                    const previous = record({ createdAt: now - 1000 });
+                    await store.create(previous);
+                    await store.create(undelivered);
+                    await store.invalidateById(undelivered.id);
+                    expect((await store.findActive(EMAIL, PURPOSE))?.id, "discarding an undeliverable code must not take a concurrent " +
+                        "request's code with it").toBe(previous.id);
+                });
+            }
+            else {
+                it.skip("a store keeping one code per pair has no older code to keep — when overlapping requests each send a code and the later send fails, discarding it leaves no code the user can enter (oneActiveCode: true)", () => { });
+            }
+            it("leaves a newer code active", async () => {
                 const now = Date.now();
-                const undelivered = record({ createdAt: now });
-                const previous = record({ createdAt: now - 1000 });
-                await store.create(previous);
-                await store.create(undelivered);
-                await store.invalidateById(undelivered.id);
-                expect((await store.findActive(EMAIL, PURPOSE))?.id, "discarding an undeliverable code must not take a concurrent " +
-                    "request's code with it").toBe(previous.id);
+                const older = record({ createdAt: now - 1000 });
+                const newer = record({ createdAt: now });
+                await store.create(older);
+                await store.create(newer);
+                await store.invalidateById(older.id);
+                expect((await store.findActive(EMAIL, PURPOSE))?.id, "a slow failed send discards its own code, never the code a " +
+                    "retry has since delivered").toBe(newer.id);
             });
             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 +264,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();
@@ -191,5 +284,46 @@ export function runOtpStoreContractTests(options) {
                     "rest through").toStrictEqual([1, 2, 3, 4, 5]);
             });
         });
+        describe("EmailOtpService over the store", () => {
+            it("leaves no older code redeemable after a successful verify", async () => {
+                const overlapping = new EmailOtpService({
+                    store: {
+                        create: (created) => store.create(created),
+                        findActive: (email, purpose) => store.findActive(email, purpose),
+                        recordAttempt: (id) => store.recordAttempt(id),
+                        consume: (id) => store.consume(id),
+                        invalidateById: (id) => store.invalidateById(id),
+                        invalidate: () => Promise.resolve(),
+                    },
+                });
+                const codes = new Map();
+                for (let i = 0; i < 2; i++) {
+                    await overlapping.request({
+                        email: EMAIL,
+                        purpose: PURPOSE,
+                        onDeliver: (code, _expiresAt, codeId) => {
+                            codes.set(codeId, code);
+                        },
+                    });
+                }
+                const newest = await store.findActive(EMAIL, PURPOSE);
+                assert(newest !== null, "a requested code must be findable");
+                const newestCode = codes.get(newest.id);
+                const olderCode = [...codes].find(([id]) => id !== newest.id)?.[1];
+                assert(newestCode !== undefined && olderCode !== undefined);
+                const service = new EmailOtpService({ store });
+                expect(await service.verify({
+                    email: EMAIL,
+                    purpose: PURPOSE,
+                    code: newestCode,
+                })).toStrictEqual({ status: "success" });
+                expect(await service.verify({
+                    email: EMAIL,
+                    purpose: PURPOSE,
+                    code: olderCode,
+                }), "two overlapping requests left two codes; signing in with the " +
+                    "newest must not leave the older one redeemable").toStrictEqual({ status: "invalid" });
+            });
+        });
     });
 }

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.38.0",
+  "version": "0.40.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",