@udibo/oauth2 0.5.1 → 0.7.0

package/esm/server/authorization-server.js

@@ -29,6 +29,7 @@ import { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
 import { ResourceServer, } from "./resource-server.js";
 import { defaultSubjectOf, signJwt, verifyJwt, } from "./signing-keys.js";
 import { validateCodeChallenge } from "../utils/pkce.js";
+import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../utils/_body.js";
 const ENDPOINTS = {
     authorization: {
         option: "authorizationEndpoint",
@@ -186,6 +187,7 @@ export class AuthorizationServer extends ResourceServer {
     signingKeys;
     #endSession;
     #isPublicSuffix;
+    #maxBodyBytes;
     #subjectOf;
     #userClaims;
     #introspectionClaims;
@@ -197,6 +199,7 @@ export class AuthorizationServer extends ResourceServer {
      *
      * @throws {Error} If any grant's map key does not equal its `grantType`.
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
+     * @throws {RangeError} If `maxBodyBytes` is not a positive integer.
      */
     constructor(options) {
         super({
@@ -227,6 +230,8 @@ export class AuthorizationServer extends ResourceServer {
                 "plain OAuth2.");
         }
         this.#isPublicSuffix = options.isPublicSuffix;
+        this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        assertMaxBodyBytes(this.#maxBodyBytes, "maxBodyBytes");
         this.#subjectOf = options.subjectOf ?? defaultSubjectOf;
         this.#userClaims = options.userClaims;
         this.#introspectionClaims = options.introspectionClaims;
@@ -343,6 +348,18 @@ export class AuthorizationServer extends ResourceServer {
         }
         return grant;
     }
+    async #readBody(request, options = {}) {
+        const bytes = await readBoundedBody(request, this.#maxBodyBytes, options)
+            .catch((cause) => {
+            throw new InvalidRequestError("request body could not be read", {
+                cause,
+            });
+        });
+        if (!bytes) {
+            throw new InvalidRequestError(413, `request body exceeds ${this.#maxBodyBytes} bytes`);
+        }
+        return bytes;
+    }
     async #beginClientAuthenticatedRequest(request, options = {}) {
         if (request.method !== "POST") {
             throw new InvalidRequestError("method must be POST");
@@ -351,10 +368,13 @@ export class AuthorizationServer extends ResourceServer {
         if (!contentType?.includes("application/x-www-form-urlencoded")) {
             throw new InvalidRequestError("content-type header must be application/x-www-form-urlencoded");
         }
-        const context = await this.authorizationContext(request);
-        const body = await request.clone().formData().catch(() => {
+        const bytes = await this.#readBody(request, { keepReadable: true });
+        const body = await new Response(bytes, {
+            headers: { "content-type": contentType },
+        }).formData().catch(() => {
             throw new InvalidRequestError("body must be application/x-www-form-urlencoded");
         });
+        const context = await this.authorizationContext(request);
         const grant = options.grantFromBody?.(body);
         const client = grant
             ? await grant.getAuthenticatedClient(request, body)
@@ -372,7 +392,9 @@ export class AuthorizationServer extends ResourceServer {
      * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
      * `invalid_request`. A `grant_type` with no registered grant is
      * `unsupported_grant_type`, checked before client authentication; a client
-     * not registered for the grant is `unauthorized_client`.
+     * not registered for the grant is `unauthorized_client`. A body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before the request context is resolved.
      */
     async handleTokenRequest(request) {
         try {
@@ -523,7 +545,9 @@ export class AuthorizationServer extends ResourceServer {
      * when sent, names the client ahead of the hint's audience, and when both
      * are sent `client_id` must be one of the hint's audiences — a mismatch is
      * a 400 `invalid_request` (OIDC RP-Initiated Logout 1.0 §2). `state` rides
-     * along only to a URI that passed authorization.
+     * along only to a URI that passed authorization. A POST body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before `endSession` runs.
      *
      * Wire the app's session teardown through the `endSession` **constructor
      * option**; this method answers 404 without it, and the discovery document
@@ -572,7 +596,7 @@ export class AuthorizationServer extends ResourceServer {
     async #endSessionParameters(request) {
         const url = new URL(request.url);
         const params = request.method === "POST"
-            ? new URLSearchParams(await request.text())
+            ? new URLSearchParams(new TextDecoder().decode(await this.#readBody(request)))
             : url.searchParams;
         const idTokenHint = params.get("id_token_hint");
         const hint = idTokenHint ? await this.#readIdTokenHint(idTokenHint) : null;

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,85 @@
+/**
+ * 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,
+ * });
+ * ```
+ *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
+ * @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;
+    /**
+     * What the store's {@link AuthRequestStorage.clear} removes. Defaults to
+     * `"all"`: every record, as a store private to one browser or session
+     * does. Pass `"scoped"` for a store shared between users whose `clear()`
+     * deliberately removes less — only expired records, say — because a
+     * `DirectClient` clears it on every sign-out, and removing everything would
+     * cancel other users' sign-ins still in progress. The suite then drops the
+     * clear-everything case and instead requires that `clear()` leaves every
+     * record still inside its lifetime readable and redeemable, and removes a
+     * record created at the epoch (`createdAt: 0`), which is past any lifetime.
+     */
+    clear?: "all" | "scoped";
+    /**
+     * 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,170 @@
+/**
+ * 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,
+ * });
+ * ```
+ *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
+ * @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;
+    const clearScope = options.clear ?? "all";
+    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");
+            });
+            if (clearScope === "all") {
+                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);
+                });
+            }
+            else {
+                it('leaves every in-progress record in place (clear: "scoped")', async () => {
+                    const first = record({ codeVerifier: "verifier-1" });
+                    const second = record({ codeVerifier: "verifier-2" });
+                    await store.set("state-1", first);
+                    await store.set("state-2", second);
+                    await store.clear();
+                    const message = "clear() on a shared store must not cancel another user's sign-in " +
+                        "that is still in progress";
+                    assertEquals(await store.get("state-2"), second, message);
+                    assertEquals(expectTake
+                        ? await store.take("state-1")
+                        : await store.get("state-1"), first, message);
+                });
+                it('removes a record past any lifetime (clear: "scoped")', async () => {
+                    await store.set("expired", record({ createdAt: 0 }));
+                    await store.clear();
+                    assertStrictEquals(await store.get("expired"), null, "a scoped clear() must still remove expired records");
+                });
+            }
+        });
+        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/esm/utils/_body.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal bounded request-body reader for the endpoints that parse a body
+ * before they have authenticated the caller.
+ *
+ * @module
+ */
+/**
+ * The default cap on those bodies: 64 KiB. The largest legitimate field is a
+ * JWT (`id_token_hint`, `logout_token`, an introspected access token), and a
+ * token that also travels in an `Authorization` header already has to fit
+ * the 8–16 KiB header limits common to servers and proxies.
+ */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * Throws a `RangeError` naming `option` unless `maxBodyBytes` is a positive
+ * safe integer.
+ */
+export declare function assertMaxBodyBytes(maxBodyBytes: number, option: string): void;
+/**
+ * Reads `request`'s body, counting bytes as they arrive, and returns `null`
+ * once it exceeds `maxBytes` — cancelling the stream rather than draining it.
+ * A `Content-Length` over the cap is refused without reading; one under it is
+ * not trusted. Consumes the body unless `keepReadable` is set, which reads a
+ * clone and leaves the original readable (a refusal cancels both). Rejects if
+ * the stream errors or was already read.
+ */
+export declare function readBoundedBody(request: Request, maxBytes: number, options?: {
+    keepReadable?: boolean;
+}): Promise<Uint8Array<ArrayBuffer> | null>;