@udibo/oauth2 0.5.1 → 0.6.0

package/esm/client/_http.d.ts

@@ -48,6 +48,8 @@ export declare function sendGuarded(fetchImpl: typeof fetch, url: string, init:
  * @param res The response from {@link sendGuarded}.
  * @param what The endpoint's name, for error messages.
  * @returns The parsed JSON object.
+ * @throws {TemporarilyUnavailableError} on a `2xx` whose body stops arriving
+ * within the size cap — the deadline fires or the connection drops mid-body.
  * @throws {OAuth2Error} on a non-OK status, an oversized body, a body that is
  * not valid JSON, or JSON that is not an object.
  */

package/esm/client/_http.js

@@ -81,6 +81,8 @@ export async function sendGuarded(fetchImpl, url, init, what, options = {}) {
  * @param res The response from {@link sendGuarded}.
  * @param what The endpoint's name, for error messages.
  * @returns The parsed JSON object.
+ * @throws {TemporarilyUnavailableError} on a `2xx` whose body stops arriving
+ * within the size cap — the deadline fires or the connection drops mid-body.
  * @throws {OAuth2Error} on a non-OK status, an oversized body, a body that is
  * not valid JSON, or JSON that is not an object.
  */
@@ -92,6 +94,10 @@ export async function receiveJson(res, what) {
         throw new ServerError(`the ${what} response exceeded ${MAX_RESPONSE_BYTES} bytes — refusing ` +
             `to parse a response this large`);
     }
+    if (body.interrupted) {
+        throw new TemporarilyUnavailableError(`the ${what} response body did not arrive in full ` +
+            `(${describeError(body.interrupted.cause)})`, { cause: body.interrupted.cause });
+    }
     let parsed;
     try {
         parsed = JSON.parse(body.text);
@@ -184,8 +190,8 @@ async function readBounded(res) {
             size += value.byteLength;
         }
     }
-    catch {
-        return { text: decode(chunks, size), truncated: true };
+    catch (cause) {
+        return { text: decode(chunks, size), truncated, interrupted: { cause } };
     }
     finally {
         await reader.cancel().catch(() => { });

package/esm/client/check.d.ts

@@ -96,9 +96,10 @@ export interface CheckPermissionsResult {
  * deleted after the signature, so catch it on that path rather than reading a
  * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
  * JSON object or exceeds the response-size cap, also throws
- * {@linkcode ServerError}, and a request whose response headers do not
- * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
- * The body's shape is not validated beyond being a JSON object.
+ * {@linkcode ServerError}. A response that does not arrive in full before the
+ * deadline — whether its headers or its body stall — or whose connection
+ * drops mid-body throws {@linkcode TemporarilyUnavailableError}. The body's
+ * shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts

package/esm/client/check.js

@@ -50,9 +50,10 @@ const CHECK_ENDPOINT = "check endpoint";
  * deleted after the signature, so catch it on that path rather than reading a
  * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
  * JSON object or exceeds the response-size cap, also throws
- * {@linkcode ServerError}, and a request whose response headers do not
- * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
- * The body's shape is not validated beyond being a JSON object.
+ * {@linkcode ServerError}. A response that does not arrive in full before the
+ * deadline — whether its headers or its body stall — or whose connection
+ * drops mid-body throws {@linkcode TemporarilyUnavailableError}. The body's
+ * shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts

package/esm/client/storage.d.ts

@@ -89,7 +89,8 @@ export interface AuthRequestStorage {
      * before the token call but lets concurrent callers that both read it
      * before either deletes it redeem it twice. Implement it with the backing
      * store's own atomic primitive (`GETDEL`, `DELETE … RETURNING`) whenever
-     * the store is shared between processes or requests.
+     * the store is shared between processes or requests, and check it with
+     * `runAuthRequestStorageContractTests` from `@udibo/oauth2/testing/contract`.
      */
     take?(state: string): Promise<AuthRequestRecord | null> | AuthRequestRecord | null;
     /** Removes one entry — a claimed or stale one. */

package/esm/testing/contract/_race.d.ts

@@ -0,0 +1,2 @@
+export declare const CONCURRENT_CALLERS = 8;
+export declare function race<T>(call: (caller: number) => Promise<T> | T): Promise<Awaited<T>[]>;

package/esm/testing/contract/_race.js

@@ -0,0 +1,4 @@
+export const CONCURRENT_CALLERS = 8;
+export function race(call) {
+    return Promise.all(Array.from({ length: CONCURRENT_CALLERS }, (_, caller) => call(caller)));
+}

package/esm/testing/contract/auth-request-storage.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Contract test suite for {@link AuthRequestStorage} implementations — the
+ * short-lived map from an authorization request's `state` to the PKCE verifier
+ * it was built with.
+ *
+ * The load-bearing method is the optional `take`: `DirectClient` claims the
+ * record with it before calling the token endpoint, so of two callbacks racing
+ * on one `state` only one reaches it. Only an atomic read-and-remove survives
+ * concurrent callers taking one record. This suite races eight of them on one
+ * record.
+ *
+ * @example Verify a Redis-backed store
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "RedisAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshAuthRequestStorage,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { AuthRequestStorage } from "../../client/storage.js";
+/** Options for {@link runAuthRequestStorageContractTests}. */
+export interface AuthRequestStorageContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — a
+     * record surviving into the next test makes the single-use checks
+     * meaningless.
+     */
+    makeStore(): Promise<AuthRequestStorage> | AuthRequestStorage;
+    /**
+     * Set to `false` when the store deliberately omits the optional
+     * {@link AuthRequestStorage.take}. The suite then registers an ignored case
+     * naming what is not covered — two callbacks racing on one `state` can both
+     * redeem it — instead of passing in silence. Defaults to `true`, so a store
+     * that meant to implement it and does not fails loudly.
+     */
+    take?: boolean;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"AuthRequestStorage contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link AuthRequestStorage} contract suite. Call it from your own
+ * test file — it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The concurrency cases take one `state` from eight callers at once. A store
+ * whose `take` reads, awaits, then deletes hands the record to more than one
+ * of them and fails in practice — a race is probabilistic, so a lucky
+ * interleaving can still pass a single run.
+ */
+export declare function runAuthRequestStorageContractTests(options: AuthRequestStorageContractOptions): void;

package/esm/testing/contract/auth-request-storage.js

@@ -0,0 +1,133 @@
+/**
+ * Contract test suite for {@link AuthRequestStorage} implementations — the
+ * short-lived map from an authorization request's `state` to the PKCE verifier
+ * it was built with.
+ *
+ * The load-bearing method is the optional `take`: `DirectClient` claims the
+ * record with it before calling the token endpoint, so of two callbacks racing
+ * on one `state` only one reaches it. Only an atomic read-and-remove survives
+ * concurrent callers taking one record. This suite races eight of them on one
+ * record.
+ *
+ * @example Verify a Redis-backed store
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "RedisAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshAuthRequestStorage,
+ * });
+ * ```
+ *
+ * @module
+ */
+import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+import { CONCURRENT_CALLERS, race } from "./_race.js";
+function record(overrides = {}) {
+    return {
+        codeVerifier: "verifier-1",
+        returnTo: "/dashboard",
+        scope: "openid profile",
+        createdAt: Date.now(),
+        ...overrides,
+    };
+}
+/**
+ * Runs the {@link AuthRequestStorage} contract suite. Call it from your own
+ * test file — it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The concurrency cases take one `state` from eight callers at once. A store
+ * whose `take` reads, awaits, then deletes hands the record to more than one
+ * of them and fails in practice — a race is probabilistic, so a lucky
+ * interleaving can still pass a single run.
+ */
+export function runAuthRequestStorageContractTests(options) {
+    const expectTake = options.take ?? true;
+    describe(options.describeName ?? "AuthRequestStorage contract", () => {
+        let store;
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        describe("set / get / delete / clear", () => {
+            it("returns null for an unknown state", async () => {
+                assertStrictEquals(await store.get("no-such-state"), null);
+            });
+            it("round-trips every field of a stored record", async () => {
+                const stored = record();
+                await store.set("state-1", stored);
+                assertEquals(await store.get("state-1"), stored);
+            });
+            it("keeps records under different states independent", async () => {
+                await store.set("state-1", record({ codeVerifier: "verifier-1" }));
+                await store.set("state-2", record({ codeVerifier: "verifier-2" }));
+                assertStrictEquals((await store.get("state-1"))?.codeVerifier, "verifier-1");
+                assertStrictEquals((await store.get("state-2"))?.codeVerifier, "verifier-2");
+            });
+            it("deletes one record and leaves the others", async () => {
+                await store.set("state-1", record());
+                await store.set("state-2", record());
+                await store.delete("state-1");
+                assertStrictEquals(await store.get("state-1"), null);
+                assert(await store.get("state-2") !== null, "delete must remove only the named state");
+            });
+            it("clears every record", async () => {
+                await store.set("state-1", record());
+                await store.set("state-2", record());
+                await store.clear();
+                assertStrictEquals(await store.get("state-1"), null);
+                assertStrictEquals(await store.get("state-2"), null);
+            });
+        });
+        if (expectTake) {
+            describe("take", () => {
+                it("is implemented", () => {
+                    assert(typeof store.take === "function", "take is optional, but without it DirectClient falls back to " +
+                        "get then delete, and two callbacks racing on one state can " +
+                        "both redeem it. Implement it, or pass `take: false` to record " +
+                        "the gap.");
+                });
+                it("returns the record and removes it", async () => {
+                    const stored = record();
+                    await store.set("state-1", stored);
+                    assertEquals(await store.take("state-1"), stored);
+                    assertStrictEquals(await store.get("state-1"), null, "a taken record must not be readable again");
+                    assertStrictEquals(await store.take("state-1"), null);
+                });
+                it("returns null for an unknown state", async () => {
+                    assertStrictEquals(await store.take("no-such-state"), null);
+                });
+                it(`hands one record to exactly one of ${CONCURRENT_CALLERS} concurrent takes`, async () => {
+                    const stored = record();
+                    await store.set("state-1", stored);
+                    const results = await race(() => store.take("state-1"));
+                    const winners = results.filter((result) => result !== null);
+                    assertStrictEquals(winners.length, 1, "a state is single-use — callbacks racing on it must not each " +
+                        "receive the PKCE verifier");
+                    assertEquals(winners[0], stored);
+                    assertStrictEquals(await store.get("state-1"), null);
+                });
+                it("hands each record to its own taker when two states are taken concurrently", async () => {
+                    await store.set("state-1", record({ codeVerifier: "verifier-1" }));
+                    await store.set("state-2", record({ codeVerifier: "verifier-2" }));
+                    const [first, second] = await Promise.all([
+                        store.take("state-1"),
+                        store.take("state-2"),
+                    ]);
+                    assertStrictEquals(first?.codeVerifier, "verifier-1");
+                    assertStrictEquals(second?.codeVerifier, "verifier-2");
+                });
+            });
+        }
+        else {
+            it({
+                name: "take is not implemented — two callbacks racing on one state can both redeem it (take: false)",
+                ignore: true,
+                fn: () => { },
+            });
+        }
+    });
+}

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

@@ -42,9 +42,10 @@ export interface MfaStoreContractOptions {
  * Runs the {@link MfaStore} contract suite. Call it from your own test file —
  * it registers `describe` / `it` blocks the test runner picks up.
  *
- * The atomicity cases issue two or more overlapping calls and assert the
- * outcome a conditional write produces. An implementation that reads, then
- * awaits, then writes fails them, which is the point: the same store passes
- * every sequential check.
+ * The atomicity cases issue overlapping calls — eight on one key where only one
+ * may win — and assert the outcome a conditional write produces. An
+ * implementation that reads, then awaits, then writes fails them in practice,
+ * which is the point: the same store passes every sequential check. A race is
+ * probabilistic, so a lucky interleaving can still pass a single run.
  */
 export declare function runMfaStoreContractTests(options: MfaStoreContractOptions): void;

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

@@ -25,6 +25,7 @@
  */
 import { assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
 import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+import { CONCURRENT_CALLERS, race } from "./_race.js";
 const USER = "user-1";
 const OTHER_USER = "user-2";
 const SECRET_A = "AAAAAAAAAAAAAAAA";
@@ -36,10 +37,11 @@ function countTrue(results) {
  * Runs the {@link MfaStore} contract suite. Call it from your own test file —
  * it registers `describe` / `it` blocks the test runner picks up.
  *
- * The atomicity cases issue two or more overlapping calls and assert the
- * outcome a conditional write produces. An implementation that reads, then
- * awaits, then writes fails them, which is the point: the same store passes
- * every sequential check.
+ * The atomicity cases issue overlapping calls — eight on one key where only one
+ * may win — and assert the outcome a conditional write produces. An
+ * implementation that reads, then awaits, then writes fails them in practice,
+ * which is the point: the same store passes every sequential check. A race is
+ * probabilistic, so a lucky interleaving can still pass a single run.
  */
 export function runMfaStoreContractTests(options) {
     describe(options.describeName ?? "MfaStore contract", () => {
@@ -98,12 +100,9 @@ export function runMfaStoreContractTests(options) {
                 assertStrictEquals(record?.secretBase32, undefined);
                 assertEquals(record?.pendingSecretBase32, SECRET_B);
             });
-            it("activates for exactly one of two concurrent confirmations", async () => {
+            it(`activates for exactly one of ${CONCURRENT_CALLERS} concurrent confirmations`, async () => {
                 await store.setPendingTotp(USER, SECRET_A);
-                const results = await Promise.all([
-                    store.activateTotp(USER, SECRET_A, 10),
-                    store.activateTotp(USER, SECRET_A, 20),
-                ]);
+                const results = await race((caller) => store.activateTotp(USER, SECRET_A, 10 + caller));
                 assertStrictEquals(countTrue(results), 1, "the pending secret must be claimable once — a second concurrent " +
                     "confirmation finds it already spent");
                 const record = await store.getTotp(USER);
@@ -154,11 +153,8 @@ export function runMfaStoreContractTests(options) {
             it("refuses for a user with no record", async () => {
                 assertStrictEquals(await store.advanceLastStep(OTHER_USER, 1), false);
             });
-            it("admits exactly one of two concurrent claims on the same step", async () => {
-                const results = await Promise.all([
-                    store.advanceLastStep(USER, 101),
-                    store.advanceLastStep(USER, 101),
-                ]);
+            it(`admits exactly one of ${CONCURRENT_CALLERS} concurrent claims on the same step`, async () => {
+                const results = await race(() => store.advanceLastStep(USER, 101));
                 assertStrictEquals(countTrue(results), 1, "a time step is spendable once — the loser must read as a replay");
                 assertEquals((await store.getTotp(USER))?.lastStep, 101);
             });
@@ -202,14 +198,11 @@ export function runMfaStoreContractTests(options) {
                 assertStrictEquals(await store.consumeRecoveryHash(USER, "nope"), false);
                 assertEquals(await store.getRecoveryHashes(USER), ["h1"]);
             });
-            it("burns a code for exactly one of two concurrent redemptions", async () => {
+            it(`burns a code for exactly one of ${CONCURRENT_CALLERS} concurrent redemptions`, async () => {
                 await store.setRecoveryHashes(USER, ["h1", "h2"]);
-                const results = await Promise.all([
-                    store.consumeRecoveryHash(USER, "h1"),
-                    store.consumeRecoveryHash(USER, "h1"),
-                ]);
-                assertStrictEquals(countTrue(results), 1, "a recovery code is single-use — two requests racing one code must " +
-                    "not both be told they redeemed it");
+                const results = await race(() => store.consumeRecoveryHash(USER, "h1"));
+                assertStrictEquals(countTrue(results), 1, "a recovery code is single-use — requests racing one code must " +
+                    "not each be told they redeemed it");
                 assertEquals(await store.getRecoveryHashes(USER), ["h2"]);
             });
             it("burns both codes when two different ones are redeemed concurrently", async () => {

package/esm/testing/contract/mod.d.ts

@@ -11,11 +11,12 @@
  * library are tested by the exact same checks.
  *
  * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
- * `OtpStore`, `RateLimitStore`, `LockoutStore` — have runners of their
- * own. Those interfaces document methods that **must be atomic**
- * (single-use recovery codes, single-use links, the TOTP replay guard,
- * the guess and failure budgets), and each suite checks that claim with
- * overlapping calls: a read-modify-write implementation passes every
+ * `OtpStore`, `RateLimitStore`, `LockoutStore` — and the client's
+ * `AuthRequestStorage` have runners of their own. Those interfaces document
+ * methods that **must be atomic** (single-use recovery codes, single-use
+ * links, the TOTP replay guard, the guess and failure budgets, the
+ * single-use claim of a login's `state`), and each suite checks that claim
+ * with overlapping calls: a read-modify-write implementation passes every
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
@@ -37,4 +38,5 @@ export { runTokenFlowStoreContractTests, type TokenFlowStoreContractOptions, } f
 export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-store.js";
 export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { type LockoutStoreContractOptions, runLockoutStoreContractTests, } from "./lockout-store.js";
+export { type AuthRequestStorageContractOptions, runAuthRequestStorageContractTests, } from "./auth-request-storage.js";
 export { runTenantContractTests, type TenantContractFixture, type TenantContractOptions, type TenantContractTokens, } from "./tenant.js";

package/esm/testing/contract/mod.js

@@ -11,11 +11,12 @@
  * library are tested by the exact same checks.
  *
  * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
- * `OtpStore`, `RateLimitStore`, `LockoutStore` — have runners of their
- * own. Those interfaces document methods that **must be atomic**
- * (single-use recovery codes, single-use links, the TOTP replay guard,
- * the guess and failure budgets), and each suite checks that claim with
- * overlapping calls: a read-modify-write implementation passes every
+ * `OtpStore`, `RateLimitStore`, `LockoutStore` — and the client's
+ * `AuthRequestStorage` have runners of their own. Those interfaces document
+ * methods that **must be atomic** (single-use recovery codes, single-use
+ * links, the TOTP replay guard, the guess and failure budgets, the
+ * single-use claim of a login's `state`), and each suite checks that claim
+ * with overlapping calls: a read-modify-write implementation passes every
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
@@ -37,4 +38,5 @@ export { runTokenFlowStoreContractTests, } from "./token-flow-store.js";
 export { runOtpStoreContractTests, } from "./otp-store.js";
 export { runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { runLockoutStoreContractTests, } from "./lockout-store.js";
+export { runAuthRequestStorageContractTests, } from "./auth-request-storage.js";
 export { runTenantContractTests, } from "./tenant.js";

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

@@ -24,6 +24,7 @@
  */
 import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
 import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+import { CONCURRENT_CALLERS, race } from "./_race.js";
 const EMAIL = "user@example.com";
 const OTHER_EMAIL = "other@example.com";
 const PURPOSE = "signin";
@@ -94,14 +95,12 @@ export function runOtpStoreContractTests(options) {
             });
         });
         describe("consume", () => {
-            it("claims an active code only once under concurrency", async () => {
+            it(`claims an active code for exactly one of ${CONCURRENT_CALLERS} concurrent consumers`, async () => {
                 const created = record();
                 await store.create(created);
-                const results = await Promise.all([
-                    store.consume(created.id),
-                    store.consume(created.id),
-                ]);
-                assertEquals(results.sort(), [false, true]);
+                const results = await race(() => store.consume(created.id));
+                assertStrictEquals(results.filter((claimed) => claimed).length, 1, "a code is single-use — consumers racing one code must not each " +
+                    "be told they claimed it");
                 assertStrictEquals(await store.consume("missing-code"), false);
             });
             it("takes the record out of the active set", async () => {

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

@@ -3,8 +3,8 @@
  * behind verification links, password-reset links, and magic links.
  *
  * The load-bearing method is `markConsumed`: it is what makes a link
- * single-use, and only a conditional write survives two requests redeeming one
- * link at the same time. This suite issues those two requests.
+ * single-use, and only a conditional write survives concurrent requests
+ * redeeming one link. This suite races eight of them on one link.
  *
  * @example Verify a database-backed store
  * ```ts
@@ -48,7 +48,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.
  *
- * The concurrency cases redeem one token from two callers at once; a store that
- * reads, awaits, then writes hands the token to both and fails them.
+ * 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
+ * still pass a single run.
  */
 export declare function runTokenFlowStoreContractTests(options: TokenFlowStoreContractOptions): void;

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

@@ -3,8 +3,8 @@
  * behind verification links, password-reset links, and magic links.
  *
  * The load-bearing method is `markConsumed`: it is what makes a link
- * single-use, and only a conditional write survives two requests redeeming one
- * link at the same time. This suite issues those two requests.
+ * single-use, and only a conditional write survives concurrent requests
+ * redeeming one link. This suite races eight of them on one link.
  *
  * @example Verify a database-backed store
  * ```ts
@@ -23,6 +23,7 @@
  */
 import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
 import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+import { CONCURRENT_CALLERS, race } from "./_race.js";
 const PURPOSE = "password-reset";
 const OTHER_PURPOSE = "email-verification";
 const SUBJECT = "user-1";
@@ -44,8 +45,10 @@ function record(overrides) {
  * Runs the {@link TokenFlowStore} contract suite. Call it from your own test
  * file — it registers `describe` / `it` blocks the test runner picks up.
  *
- * The concurrency cases redeem one token from two callers at once; a store that
- * reads, awaits, then writes hands the token to both and fails them.
+ * 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
+ * still pass a single run.
  */
 export function runTokenFlowStoreContractTests(options) {
     const expectDeleteBySubject = options.deleteBySubject ?? true;
@@ -103,15 +106,12 @@ export function runTokenFlowStoreContractTests(options) {
             it("refuses an unknown token hash", async () => {
                 assertStrictEquals(await store.markConsumed("no-such-hash", Date.now()), false);
             });
-            it("claims a token for exactly one of two concurrent redemptions", async () => {
+            it(`claims a token for exactly one of ${CONCURRENT_CALLERS} concurrent redemptions`, async () => {
                 await store.save(record({ tokenHash: "hash-1" }));
                 const now = Date.now();
-                const results = await Promise.all([
-                    store.markConsumed("hash-1", now),
-                    store.markConsumed("hash-1", now + 1),
-                ]);
-                assertStrictEquals(countTrue(results), 1, "a link is single-use — two requests racing one link must not both " +
-                    "be told they claimed it");
+                const results = await race((caller) => store.markConsumed("hash-1", now + caller));
+                assertStrictEquals(countTrue(results), 1, "a link is single-use — requests racing one link must not each be " +
+                    "told they claimed it");
             });
             it("claims both tokens when two different ones are redeemed concurrently", async () => {
                 await store.save(record({ tokenHash: "hash-1" }));

package/package.json

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