@udibo/oauth2 0.33.0 → 0.35.0

package/dist/testing/contract/code-exchange.js

@@ -0,0 +1,309 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface.exchangeCode} and its
+ * linearizability with {@link TokenServiceInterface.revokeCode}.
+ *
+ * `runTokenServiceContractTests` checks `revokeCode` for one caller. This
+ * suite checks the atomic code exchange under concurrent callers: two
+ * exchanges of one code, a replay of the code racing its exchange through
+ * the authorization code grant, an exchange of an unrelated code, and an
+ * exchange whose insert fails. Each case asserts the store's end state, the
+ * live tokens and whether the code can still be claimed, not only the value
+ * each call resolved.
+ *
+ * The store under test awaits {@link CodeExchangeBarriers.afterClaim} inside
+ * `exchangeCode`, between its claim and its insert, so the suite can hold an
+ * exchange there and race the other call against it; a store that never
+ * reaches the barrier fails every held case. Only a store whose
+ * `exchangeCode` never awaits between its claim and its insert, such as
+ * `MemoryTokenService` paired with its code store, opts out with
+ * `exchangeAwaitsBarrier: false`; the suite then runs those schedules as
+ * overlapping calls.
+ *
+ * @module
+ */
+import { assert, beforeEach, describe, expect, it } from "vitest";
+import { InvalidGrantError } from "../../errors.js";
+import { AuthorizationCodeGrant, } from "../../server/grants/authorization-code.js";
+import { race } from "./_race.js";
+const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
+const defaultMakeClient = (seq) => ({
+    id: `client-${seq}`,
+    grants: ["authorization_code", "refresh_token"],
+});
+async function settledWithin(promise, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([
+            promise.then(() => true, () => true),
+            timeout,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs the code exchange contract suite: concurrent schedules of
+ * {@linkcode TokenServiceInterface.exchangeCode} against itself, and against
+ * a replay of the code through the authorization code grant, which calls
+ * {@linkcode TokenServiceInterface.revokeCode}. The service must implement
+ * `exchangeCode`.
+ */
+export function runCodeExchangeContractTests(options) {
+    const makeUser = options.makeUser ?? defaultMakeUser;
+    const makeClient = options.makeClient ?? defaultMakeClient;
+    const pausable = options.exchangeAwaitsBarrier ?? true;
+    const blockedAfterMs = options.blockedAfterMs ?? 100;
+    describe(options.describeName ?? "TokenServiceInterface.exchangeCode contract", () => {
+        let services;
+        let codeService;
+        let tokenService;
+        let user;
+        let client;
+        let armed;
+        const barriers = {
+            async afterClaim() {
+                const hold = armed;
+                if (!hold)
+                    return;
+                armed = undefined;
+                hold.reached.resolve();
+                await hold.release.promise;
+            },
+        };
+        beforeEach(async () => {
+            armed = undefined;
+            services = await options.makeServices(barriers);
+            codeService = services.authorizationCodeService;
+            tokenService = services.tokenService;
+            user = makeUser(1);
+            client = makeClient(1);
+            await options.addUser(services.userService, user, "pw");
+            await options.addClient(services.clientService, client);
+        });
+        function exchangeCode(authorizationCode, token) {
+            assert(typeof tokenService.exchangeCode === "function", "runCodeExchangeContractTests needs a token service that implements exchangeCode");
+            return tokenService.exchangeCode(authorizationCode, token);
+        }
+        async function savedCode() {
+            const authorizationCode = {
+                code: await codeService.generateCode(client, user),
+                expiresAt: await codeService.expiresAt(client, user),
+                client,
+                user,
+            };
+            await codeService.save(authorizationCode);
+            return authorizationCode;
+        }
+        async function tokenFor(authorizationCode) {
+            return {
+                accessToken: await tokenService.generateAccessToken(client, user),
+                accessTokenExpiresAt: new Date(Date.now() + 60_000),
+                client,
+                user,
+                code: authorizationCode.code,
+            };
+        }
+        async function live(tokens) {
+            const found = [];
+            for (const token of tokens) {
+                if (await tokenService.getToken(token.accessToken)) {
+                    found.push(token.accessToken);
+                }
+            }
+            return found;
+        }
+        async function claimable(authorizationCode) {
+            return (await codeService.get(authorizationCode.code)) !== undefined;
+        }
+        function arm() {
+            const hold = {
+                reached: Promise.withResolvers(),
+                release: Promise.withResolvers(),
+            };
+            armed = hold;
+            return hold;
+        }
+        async function untilHeld(hold, exchange) {
+            const outcome = await Promise.race([
+                hold.reached.promise.then(() => "held"),
+                exchange.then(() => "settled", () => "settled"),
+            ]);
+            assert(outcome === "held", "exchangeCode settled without awaiting barriers.afterClaim; wire " +
+                "the barrier into exchangeCode between its claim and its " +
+                "insert, or, only if exchangeCode never awaits between them, " +
+                "set exchangeAwaitsBarrier: false");
+        }
+        function codeGrant(reuseEvents) {
+            return new AuthorizationCodeGrant({
+                resolve: () => ({
+                    clientService: services.clientService,
+                    authorizationCodeService: codeService,
+                    tokenService,
+                }),
+                requirePKCE: false,
+                onCodeReuse: (event) => {
+                    reuseEvents.push(event);
+                },
+            });
+        }
+        function redeem(grant, authorizationCode) {
+            const body = new FormData();
+            body.set("grant_type", "authorization_code");
+            body.set("code", authorizationCode.code);
+            return grant.token(new Request("https://as.test/token", { method: "POST" }), client, body);
+        }
+        it("implements exchangeCode", () => {
+            assert(typeof tokenService.exchangeCode === "function", "the code exchange contract covers exchangeCode");
+        });
+        it("claims the code and saves its token in one call, findable by the code", async () => {
+            const authorizationCode = await savedCode();
+            const token = await tokenFor(authorizationCode);
+            const saved = await exchangeCode(authorizationCode, token);
+            expect(saved?.accessToken).toBe(token.accessToken);
+            expect(await claimable(authorizationCode), "an exchanged code must be spent").toBe(false);
+            expect(await codeService.revoke(authorizationCode.code)).toBe(false);
+            expect(await live([token])).toStrictEqual([token.accessToken]);
+            expect(await tokenService.revokeCode(authorizationCode.code, client), "revokeCode must find the token exchangeCode saved by its code").toBe(true);
+            expect(await live([token])).toStrictEqual([]);
+        });
+        it("refuses a code that was already claimed or never stored, persisting nothing", async () => {
+            const claimed = await savedCode();
+            await codeService.revoke(claimed.code);
+            const afterClaim = await tokenFor(claimed);
+            const unknown = {
+                ...claimed,
+                code: await codeService.generateCode(client, user),
+            };
+            const forUnknown = await tokenFor(unknown);
+            expect(await exchangeCode(claimed, afterClaim)).toBe(undefined);
+            expect(await exchangeCode(unknown, forUnknown)).toBe(undefined);
+            expect(await live([afterClaim, forUnknown])).toStrictEqual([]);
+        });
+        it("gives concurrent exchanges of one code exactly one token", async () => {
+            const authorizationCode = await savedCode();
+            const tokens = await race(() => tokenFor(authorizationCode));
+            const results = await race((caller) => exchangeCode(authorizationCode, tokens[caller]));
+            expect(results.filter((result) => result !== undefined).length, "exchangeCode must claim its code once, however many callers race").toBe(1);
+            expect(await live(tokens)).toHaveLength(1);
+        });
+        it("revokes the exchanged token when the code's own client replays it through the grant", async () => {
+            const authorizationCode = await savedCode();
+            const reuseEvents = [];
+            const grant = codeGrant(reuseEvents);
+            const issued = await redeem(grant, authorizationCode);
+            const replay = await Promise.allSettled([
+                redeem(grant, authorizationCode),
+            ]);
+            assert(replay[0].status === "rejected");
+            expect(replay[0].reason).toBeInstanceOf(InvalidGrantError);
+            expect(await live([issued])).toStrictEqual([]);
+            expect(reuseEvents).toHaveLength(1);
+        });
+        it("leaves no live token when the code is replayed through the grant while its exchange is in flight", async () => {
+            const authorizationCode = await savedCode();
+            const reuseEvents = [];
+            const grant = codeGrant(reuseEvents);
+            let outcomes;
+            if (pausable) {
+                const hold = arm();
+                const first = redeem(grant, authorizationCode);
+                await untilHeld(hold, first);
+                const replay = redeem(grant, authorizationCode);
+                await settledWithin(replay, blockedAfterMs);
+                hold.release.resolve();
+                outcomes = await Promise.allSettled([first, replay]);
+            }
+            else {
+                outcomes = await Promise.allSettled([
+                    redeem(grant, authorizationCode),
+                    redeem(grant, authorizationCode),
+                ]);
+            }
+            const issued = outcomes.flatMap((outcome) => outcome.status === "fulfilled" ? [outcome.value] : []);
+            const refused = outcomes.flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason] : []);
+            expect(issued).toHaveLength(1);
+            expect(refused).toHaveLength(1);
+            expect(refused[0]).toBeInstanceOf(InvalidGrantError);
+            expect(await live(issued), "a replay that lands while the exchange is between its claim and " +
+                "its insert must still leave no live token issued from the code: " +
+                "revokeCode has to see the token, or the replay has to wait for " +
+                "the exchange and lose the claim").toStrictEqual([]);
+            expect(reuseEvents).toHaveLength(1);
+        });
+        it("refuses a second exchange that starts while the first is held after its claim", async ({ skip, }) => {
+            skip(!pausable, "exchangeCode cannot be held (exchangeAwaitsBarrier: false)");
+            const authorizationCode = await savedCode();
+            const first = await tokenFor(authorizationCode);
+            const second = await tokenFor(authorizationCode);
+            const hold = arm();
+            const held = exchangeCode(authorizationCode, first);
+            await untilHeld(hold, held);
+            const racing = exchangeCode(authorizationCode, second);
+            await settledWithin(racing, blockedAfterMs);
+            hold.release.resolve();
+            expect((await held)?.accessToken).toBe(first.accessToken);
+            expect(await racing).toBe(undefined);
+            expect(await live([first, second])).toStrictEqual([first.accessToken]);
+        });
+        it("does not hold an exchange of another code behind a held one", async ({ skip, }) => {
+            skip(!pausable, "exchangeCode cannot be held (exchangeAwaitsBarrier: false)");
+            const authorizationCode = await savedCode();
+            const token = await tokenFor(authorizationCode);
+            const otherCode = await savedCode();
+            const otherToken = await tokenFor(otherCode);
+            const hold = arm();
+            const exchange = exchangeCode(authorizationCode, token);
+            await untilHeld(hold, exchange);
+            const other = exchangeCode(otherCode, otherToken);
+            const settled = await settledWithin(other, 5_000);
+            hold.release.resolve();
+            expect(settled, "the code lock must be keyed by code, so one login's exchange " +
+                "never waits on another's").toBe(true);
+            expect((await other)?.accessToken).toBe(otherToken.accessToken);
+            expect((await exchange)?.accessToken).toBe(token.accessToken);
+        });
+        it("leaves the code claimable and persists nothing when the token cannot be persisted", async () => {
+            const authorizationCode = await savedCode();
+            const unpersistable = await tokenFor(authorizationCode);
+            const accessToken = unpersistable.accessToken;
+            Object.defineProperty(unpersistable, "accessToken", {
+                enumerable: true,
+                get() {
+                    throw new Error("forced persistence failure");
+                },
+            });
+            const outcome = await Promise.allSettled([
+                exchangeCode(authorizationCode, unpersistable),
+            ]);
+            if (outcome[0].status === "fulfilled") {
+                expect(outcome[0].value).toBe(undefined);
+            }
+            expect(await claimable(authorizationCode), "a failed exchange must not spend its code").toBe(true);
+            expect(await tokenService.getToken(accessToken)).toBe(undefined);
+            const retry = await tokenFor(authorizationCode);
+            expect((await exchangeCode(authorizationCode, retry))?.accessToken).toBe(retry.accessToken);
+        });
+        it("rolls the claim back when the insert fails after it", async ({ skip, }) => {
+            skip(!pausable, "exchangeCode cannot be held (exchangeAwaitsBarrier: false)");
+            const authorizationCode = await savedCode();
+            const token = await tokenFor(authorizationCode);
+            const hold = arm();
+            const exchange = exchangeCode(authorizationCode, token);
+            await untilHeld(hold, exchange);
+            hold.release.reject(new Error("forced insert failure"));
+            const outcome = await Promise.allSettled([exchange]);
+            if (outcome[0].status === "fulfilled") {
+                expect(outcome[0].value).toBe(undefined);
+            }
+            expect(await claimable(authorizationCode), "the claim and the insert are one step: a failed insert must " +
+                "leave the code claimable").toBe(true);
+            expect(await live([token])).toStrictEqual([]);
+            const retry = await tokenFor(authorizationCode);
+            expect((await exchangeCode(authorizationCode, retry))?.accessToken, "a failed exchange must release the code").toBe(retry.accessToken);
+        });
+    });
+}

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

@@ -30,6 +30,11 @@
  * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
  * suite can hold a rotation there.
  *
+ * `TokenServiceInterface.exchangeCode` has one too: two exchanges of one
+ * code, a replay racing an exchange through the authorization code grant,
+ * and an exchange whose insert fails. A store that awaits between its claim
+ * and its insert wires `CodeExchangeBarriers` into `exchangeCode`.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -40,6 +45,7 @@ export { runUserServiceContractTests, type UserServiceContractOptions, } from ".
 export { type ClientServiceContractOptions, runClientServiceContractTests, } from "./client.ts";
 export { runTokenServiceContractTests, type TokenServiceContractOptions, } from "./token.ts";
 export { runTokenRotationContractTests, type TokenRotationBarriers, type TokenRotationContractOptions, type TokenRotationContractServices, } from "./token-rotation.ts";
+export { type CodeExchangeBarriers, type CodeExchangeContractOptions, type CodeExchangeContractServices, runCodeExchangeContractTests, } from "./code-exchange.ts";
 export { runTokenReaderContractTests, type TokenReaderContractFixture, type TokenReaderContractOptions, } from "./token-reader.ts";
 export { type AuthorizationCodeServiceContractOptions, runAuthorizationCodeServiceContractTests, } from "./authorization-code.ts";
 export { type DeviceAuthorizationServiceContractOptions, runDeviceAuthorizationServiceContractTests, } from "./device-authorization.ts";

package/dist/testing/contract/mod.js

@@ -30,6 +30,11 @@
  * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
  * suite can hold a rotation there.
  *
+ * `TokenServiceInterface.exchangeCode` has one too: two exchanges of one
+ * code, a replay racing an exchange through the authorization code grant,
+ * and an exchange whose insert fails. A store that awaits between its claim
+ * and its insert wires `CodeExchangeBarriers` into `exchangeCode`.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -40,6 +45,7 @@ export { runUserServiceContractTests, } from "./user.js";
 export { runClientServiceContractTests, } from "./client.js";
 export { runTokenServiceContractTests, } from "./token.js";
 export { runTokenRotationContractTests, } from "./token-rotation.js";
+export { runCodeExchangeContractTests, } from "./code-exchange.js";
 export { runTokenReaderContractTests, } from "./token-reader.js";
 export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
 export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";

package/dist/testing/contract/token.d.ts

@@ -78,6 +78,14 @@ export interface TokenServiceContractOptions<C extends ClientInterface, U extend
      * loudly rather than losing reuse detection quietly.
      */
     refreshTokenReuseDetection?: boolean;
+    /**
+     * Set to `false` when the service's `revokeCode` deliberately ignores its
+     * `client` argument. The suite then registers an ignored case naming what is
+     * not covered — any client that presents a spent code revokes the tokens
+     * issued from it, so a client that sees a leaked code can end the session it
+     * started — instead of passing in silence. Defaults to `true`.
+     */
+    revokeCodeChecksClient?: boolean;
     /** Overrides the name passed to the outer `describe` block. */
     describeName?: string;
 }

package/dist/testing/contract/token.js

@@ -35,6 +35,7 @@ export function runTokenServiceContractTests(options) {
     const supportedScope = options.supportedScope ?? "read";
     const makeFamilyId = options.makeFamilyId ?? defaultMakeFamilyId;
     const expectReuseDetection = options.refreshTokenReuseDetection ?? true;
+    const expectCodeClientCheck = options.revokeCodeChecksClient ?? true;
     describe(options.describeName ?? "TokenServiceInterface contract", () => {
         let userService;
         let clientService;
@@ -214,6 +215,32 @@ export function runTokenServiceContractTests(options) {
             it("returns false when no tokens were issued for the code", async () => {
                 expect(await tokenService.revokeCode("never-used")).toBe(false);
             });
+            if (expectCodeClientCheck) {
+                async function issueFromCode(code) {
+                    const accessToken = await tokenService.generateAccessToken(client, user);
+                    await tokenService.save({ accessToken, code, client, user });
+                    return accessToken;
+                }
+                it("revokes nothing for a client other than the one the code's tokens were issued to", async () => {
+                    const other = makeClient(2);
+                    await options.addClient(clientService, other);
+                    const accessToken = await issueFromCode("replayed-code");
+                    expect(await tokenService.revokeCode("replayed-code", other), "a client that could never have redeemed the code must not " +
+                        "revoke what it issued").toBe(false);
+                    expect(await tokenService.getToken(accessToken)).not.toBe(undefined);
+                });
+                it("revokes for the client the code's tokens were issued to, after another client was refused", async () => {
+                    const other = makeClient(2);
+                    await options.addClient(clientService, other);
+                    const accessToken = await issueFromCode("replayed-code");
+                    await tokenService.revokeCode("replayed-code", other);
+                    expect(await tokenService.revokeCode("replayed-code", client)).toBe(true);
+                    expect(await tokenService.getToken(accessToken)).toBe(undefined);
+                });
+            }
+            else {
+                it.skip("revokeCode ignores the presenting client — any client that presents a spent code revokes its tokens (revokeCodeChecksClient: false)", () => { });
+            }
         });
         if (expectReuseDetection) {
             describe("refresh-token rotation family", () => {

package/dist/testing/server.js

@@ -78,13 +78,14 @@ export async function createMemoryAuthorizationServer(options = {}) {
     const enabledGrants = { ...DEFAULT_GRANTS, ...options.grants };
     const userService = new MemoryUserService();
     const clientService = new MemoryClientService(userService);
-    const tokenService = new MemoryTokenService({
+    const authorizationCodeService = new MemoryAuthorizationCodeService({
         clientService,
         userService,
     });
-    const authorizationCodeService = new MemoryAuthorizationCodeService({
+    const tokenService = new MemoryTokenService({
         clientService,
         userService,
+        authorizationCodeService,
     });
     const deviceAuthorizationService = new MemoryDeviceAuthorizationService({ clientService, userService });
     const grants = {};

package/dist/testing/services.d.ts

@@ -135,7 +135,7 @@ export declare class MemoryClientService<C extends ClientInterface, U> implement
     getUser(client: C | string): Promise<U | undefined>;
 }
 /** Options for {@link MemoryTokenService}. */
-export interface MemoryTokenServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {
+export interface MemoryTokenServiceOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
     /** Resolves clients when hydrating stored tokens back into full records. */
     clientService: ClientServiceInterface<C, U>;
     /** Resolves users when hydrating stored tokens back into full records. */
@@ -149,6 +149,14 @@ export interface MemoryTokenServiceOptions<C extends ClientInterface, U extends
      * leave rotation uncapped.
      */
     refreshTokenMaxLifetime?: number;
+    /**
+     * The code store the authorization code grant claims codes from. Pass it to
+     * give the token service {@linkcode MemoryTokenService.exchangeCode}, so the
+     * grant claims a code and saves its token in one step; without it the grant
+     * claims and saves in two. `exchangeCode` claims from the code store's own
+     * map, so a subclass that overrides the code store's `revoke` is bypassed.
+     */
+    authorizationCodeService?: MemoryAuthorizationCodeService<C, U, S>;
 }
 /**
  * In-memory `TokenServiceInterface` implementation. Tokens are hashed on
@@ -171,13 +179,21 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
      * client sets none. Undefined leaves families uncapped.
      */
     refreshTokenMaxLifetime?: number;
+    /**
+     * Claims a code from the paired `authorizationCodeService` and saves the
+     * token issued from it in one step, or does neither, resolving `undefined`
+     * when the code was already claimed. Present only when the service was
+     * constructed with `authorizationCodeService`, so the grant falls back to
+     * two calls for a token service that has no code store to claim from.
+     */
+    readonly exchangeCode?: (authorizationCode: AuthorizationCode<C, U, S>, token: Token<C, U, S>) => Promise<Token<C, U, S> | undefined>;
     /**
      * Creates an empty token store.
      *
-     * @param options Backing client/user services and optional default token
-     * lifetimes.
+     * @param options Backing client/user services, optional default token
+     * lifetimes, and the code store that enables `exchangeCode`.
      */
-    constructor(options: MemoryTokenServiceOptions<C, U>);
+    constructor(options: MemoryTokenServiceOptions<C, U, S>);
     /**
      * Accepts the requested scope verbatim; the stub performs no scope
      * narrowing. Return `false` from a subclass to reject a request.
@@ -279,8 +295,10 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
     /**
      * Removes every token issued from the given authorization code, used when a
      * code is replayed. Resolves `true` when at least one token was removed.
+     * Removes nothing and resolves `false` when `client` is given and is not the
+     * client the code's tokens were issued to.
      */
-    revokeCode(code: string): Promise<boolean>;
+    revokeCode(code: string, client?: C): Promise<boolean>;
 }
 /** Options for {@link MemoryAuthorizationCodeService}. */
 export interface MemoryAuthorizationCodeServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {

package/dist/testing/services.js

@@ -208,11 +208,19 @@ export class MemoryTokenService {
     #tokensByCodeHash = new Map();
     #revokedByRefreshHash = new Map();
     #revokedFamilies = new Set();
+    /**
+     * Claims a code from the paired `authorizationCodeService` and saves the
+     * token issued from it in one step, or does neither, resolving `undefined`
+     * when the code was already claimed. Present only when the service was
+     * constructed with `authorizationCodeService`, so the grant falls back to
+     * two calls for a token service that has no code store to claim from.
+     */
+    exchangeCode;
     /**
      * Creates an empty token store.
      *
-     * @param options Backing client/user services and optional default token
-     * lifetimes.
+     * @param options Backing client/user services, optional default token
+     * lifetimes, and the code store that enables `exchangeCode`.
      */
     constructor(options) {
         this.#clientService = options.clientService;
@@ -221,6 +229,21 @@ export class MemoryTokenService {
         this.refreshTokenLifetime =
             options.refreshTokenLifetime ?? 14 * 24 * 60 * 60;
         this.refreshTokenMaxLifetime = options.refreshTokenMaxLifetime;
+        const codes = options.authorizationCodeService;
+        if (codes) {
+            this.exchangeCode = (authorizationCode, token) => this.#exchangeCode(codes, authorizationCode, token);
+        }
+    }
+    async #exchangeCode(codes, authorizationCode, token) {
+        const codeHash = await sha256Hash(authorizationCode.code);
+        const stored = await this.#prepare({
+            ...token,
+            code: authorizationCode.code,
+        });
+        if (!claimStoredCode(codes, codeHash))
+            return undefined;
+        this.#store(stored);
+        return token;
     }
     /**
      * Accepts the requested scope verbatim; the stub performs no scope
@@ -344,10 +367,10 @@ export class MemoryTokenService {
         if (stored.codeHash) {
             let bucket = this.#tokensByCodeHash.get(stored.codeHash);
             if (!bucket) {
-                bucket = new Set();
+                bucket = { clientId: stored.clientId, accessTokenHashes: new Set() };
                 this.#tokensByCodeHash.set(stored.codeHash, bucket);
             }
-            bucket.add(stored.accessTokenHash);
+            bucket.accessTokenHashes.add(stored.accessTokenHash);
         }
         if (stored.refreshTokenHash) {
             if (stored.familyId && this.#revokedFamilies.has(stored.familyId)) {
@@ -481,13 +504,18 @@ export class MemoryTokenService {
     /**
      * Removes every token issued from the given authorization code, used when a
      * code is replayed. Resolves `true` when at least one token was removed.
+     * Removes nothing and resolves `false` when `client` is given and is not the
+     * client the code's tokens were issued to.
      */
-    async revokeCode(code) {
+    async revokeCode(code, client) {
         const codeHash = await sha256Hash(code);
-        const tokenHashes = this.#tokensByCodeHash.get(codeHash);
-        if (!tokenHashes || tokenHashes.size === 0)
+        const bucket = this.#tokensByCodeHash.get(codeHash);
+        if (!bucket || bucket.accessTokenHashes.size === 0)
+            return false;
+        if (client && client.id.toString() !== bucket.clientId.toString()) {
             return false;
-        for (const accessTokenHash of tokenHashes) {
+        }
+        for (const accessTokenHash of bucket.accessTokenHashes) {
             const stored = this.#tokensByAccessHash.get(accessTokenHash);
             if (stored) {
                 this.#tokensByAccessHash.delete(accessTokenHash);
@@ -500,6 +528,7 @@ export class MemoryTokenService {
         return true;
     }
 }
+let claimStoredCode;
 /** In-memory `AuthorizationCodeServiceInterface` implementation. */
 export class MemoryAuthorizationCodeService {
     /** Authorization-code lifetime in seconds applied by {@linkcode expiresAt}. */
@@ -507,6 +536,9 @@ export class MemoryAuthorizationCodeService {
     #clientService;
     #userService;
     #codes = new Map();
+    static {
+        claimStoredCode = (service, codeHash) => service.#codes.delete(codeHash);
+    }
     /**
      * Creates an empty authorization-code store.
      *

package/dist/utils/crypto.d.ts

@@ -2,20 +2,14 @@
  * Authenticated-encryption (AES-256-GCM) and key-derivation helpers for sealing
  * session and token data at rest or in a cookie.
  *
- * Two key-derivation paths, for two different threat models:
- *
- * - {@link deriveAesKey} hashes a single **server-held** secret (SHA-256) into
- *   an AES-256-GCM key. Use this for a stateless cookie sealed under one
- *   configured secret (see `EncryptedCookieSessionStore`), where the secret is
- *   never persisted.
- *
- * - {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so
- *   a high-entropy *per-session* secret yields an encryption key that is
- *   independent of any other value derived from the same secret. This is what
- *   makes "the cookie value is both the lookup credential **and** the decryption
- *   key" safe: a database can store `sha256(secret)` as a lookup hash while the
- *   sealing key is `HKDF(secret, info)`, and knowing the stored hash never
- *   reveals the key. Always pass a distinct `info` per purpose.
+ * {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so a
+ * high-entropy secret yields an encryption key that is independent of any other
+ * value derived from the same secret. This is what makes "the cookie value is
+ * both the lookup credential **and** the decryption key" safe: a database can
+ * store `sha256(secret)` as a lookup hash while the sealing key is
+ * `HKDF(secret, info)`, and knowing the stored hash never reveals the key. It is
+ * also what lets one secret seal two kinds of value without either opening as
+ * the other. Always pass a distinct `info` per purpose.
  *
  * {@link seal}/{@link unseal} use AES-256-GCM (an AEAD), so tampered ciphertext
  * fails to unseal (returns `null`) rather than decrypting to garbage.
@@ -61,18 +55,6 @@ export declare function base64urlDecode(value: string): Uint8Array;
  * ```
  */
 export declare function randomToken(bytes?: number): string;
-/**
- * Derive an AES-256-GCM key from a single server-held secret via SHA-256.
- *
- * Suitable when the secret is a long-lived configuration value that is never
- * stored alongside the ciphertext. Do **not** use this when a hash of the same
- * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
- * sealing key is independent of that stored hash.
- *
- * @throws {Error} if the secret is shorter than 16 bytes. Length is all that is
- * checked; supply 32+ bytes of real entropy.
- */
-export declare function deriveAesKey(secret: string | Uint8Array): Promise<CryptoKey>;
 /**
  * Derive an AES-256-GCM sealing key from a high-entropy secret via HKDF-SHA-256
  * with a domain-separating `info` label.