@udibo/oauth2 0.34.0 → 0.36.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-rotation.js

@@ -235,6 +235,19 @@ export function runTokenRotationContractTests(options) {
                 "successor that rotation commits afterwards stays live in a " +
                 "family the server revoked").toStrictEqual([]);
         });
+        it("leaves no live member when the code that issued the family is replayed while a rotation is in flight", async () => {
+            const code = "replayed-while-rotating";
+            const parent = { ...(await member(family)), code };
+            await tokenService.save(parent);
+            const next = await member(family);
+            const [rotated, revoked] = await whileRotating(parent, next, () => tokenService.revokeCode(code, client));
+            assert(revoked.status === "fulfilled");
+            assert(rotated.status === "fulfilled");
+            expect([undefined, next.refreshToken]).toContain(rotated.value?.refreshToken);
+            expect(await live([parent, next]), "revokeCode must revoke the code's families as revokeFamily does, " +
+                "waiting for a rotation holding one, or the successor that " +
+                "rotation commits afterwards stays live after the code's replay").toStrictEqual([]);
+        });
         it("revokes the successor of a rotation that committed before the family was revoked", async () => {
             const parent = await savedMember(family);
             const next = await member(family);

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;
@@ -51,6 +52,41 @@ export function runTokenServiceContractTests(options) {
             await options.addUser(userService, user, "pw");
             await options.addClient(clientService, client);
         });
+        async function familyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
+            const accessToken = await tokenService.generateAccessToken(client, user);
+            const refreshToken = (await tokenService.generateRefreshToken(client, user));
+            return {
+                accessToken,
+                accessTokenExpiresAt: new Date(Date.now() + 60_000),
+                refreshToken,
+                refreshTokenExpiresAt,
+                familyId,
+                familyCreatedAt: new Date(Date.now() - 60_000),
+                client,
+                user,
+            };
+        }
+        async function saveFamilyMember(familyId, refreshTokenExpiresAt) {
+            const token = await familyMember(familyId, refreshTokenExpiresAt);
+            await tokenService.save(token);
+            return token;
+        }
+        async function isLive(token) {
+            return ((await tokenService.getRefreshToken(token.refreshToken)) !==
+                undefined ||
+                (await tokenService.getToken(token.accessToken)) !== undefined);
+        }
+        async function rotateTo(current, next) {
+            if (tokenService.rotate) {
+                assert(await tokenService.rotate(current, next));
+                return;
+            }
+            const claimed = tokenService.revokeRotated
+                ? await tokenService.revokeRotated(current)
+                : await tokenService.revoke(current);
+            assert(claimed);
+            await tokenService.save(next);
+        }
         describe("generateAccessToken / generateRefreshToken", () => {
             it("produces unique access tokens", async () => {
                 const a = await tokenService.generateAccessToken(client, user);
@@ -214,6 +250,48 @@ 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);
+                });
+                it("revokes nothing in a rotated family 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 family = makeFamilyId();
+                    const issued = {
+                        ...(await familyMember(family)),
+                        code: "rotated-replayed-code",
+                    };
+                    await tokenService.save(issued);
+                    const rotated = await familyMember(family);
+                    await rotateTo(issued, rotated);
+                    expect(await tokenService.revokeCode("rotated-replayed-code", other)).toBe(false);
+                    expect(await isLive(rotated), "the client check comes before any family is revoked — a " +
+                        "client that could never have redeemed the code must not end " +
+                        "the session rotated from it").toBe(true);
+                });
+            }
+            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", () => {
@@ -223,25 +301,6 @@ export function runTokenServiceContractTests(options) {
                     family = makeFamilyId();
                     otherFamily = makeFamilyId();
                 });
-                async function familyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
-                    const accessToken = await tokenService.generateAccessToken(client, user);
-                    const refreshToken = (await tokenService.generateRefreshToken(client, user));
-                    return {
-                        accessToken,
-                        accessTokenExpiresAt: new Date(Date.now() + 60_000),
-                        refreshToken,
-                        refreshTokenExpiresAt,
-                        familyId,
-                        familyCreatedAt: new Date(Date.now() - 60_000),
-                        client,
-                        user,
-                    };
-                }
-                async function saveFamilyMember(familyId, refreshTokenExpiresAt) {
-                    const token = await familyMember(familyId, refreshTokenExpiresAt);
-                    await tokenService.save(token);
-                    return token;
-                }
                 it("implements both halves of reuse detection", () => {
                     assert(typeof tokenService.getRevokedRefreshToken === "function" &&
                         typeof tokenService.revokeFamily === "function", "getRevokedRefreshToken and revokeFamily are optional, but " +
@@ -377,6 +436,49 @@ export function runTokenServiceContractTests(options) {
                     assert((await tokenService.getRefreshToken(unrelated.refreshToken)) !==
                         undefined);
                 });
+                it("revokes the rotated successors of a replayed code's tokens, leaving other families live", async () => {
+                    const code = "rotated-code";
+                    const issued = { ...(await familyMember(family)), code };
+                    await tokenService.save(issued);
+                    const rotated = await familyMember(family);
+                    await rotateTo(issued, rotated);
+                    const latest = await familyMember(family);
+                    await rotateTo(rotated, latest);
+                    const unrelated = await saveFamilyMember(otherFamily);
+                    expect(await isLive(latest)).toBe(true);
+                    expect(await tokenService.revokeCode(code, client), "the replay ended a live token, so the grant must report it").toBe(true);
+                    expect(await tokenService.getRefreshToken(latest.refreshToken), "a rotated successor carries no code, so revoking only the " +
+                        "rows issued with the code leaves the stolen code's session " +
+                        "refreshing — revoke every live member of their families").toBe(undefined);
+                    expect(await tokenService.getToken(latest.accessToken), "the successor's access token ends with its family").toBe(undefined);
+                    if (tokenService.hasLiveRefreshToken) {
+                        expect(await tokenService.hasLiveRefreshToken(family)).toBe(false);
+                    }
+                    assert((await tokenService.getRefreshToken(unrelated.refreshToken)) !==
+                        undefined, "a replayed code must not end families it did not issue");
+                });
+                it("keeps a replayed code's family revoked: a successor saved after revokeCode is not live", async ({ skip, }) => {
+                    skip(typeof tokenService.rotate === "function", "the service implements rotate, so the refresh grant never saves " +
+                        "a successor separately; runTokenRotationContractTests checks " +
+                        "revokeCode against rotate");
+                    const code = "claimed-code";
+                    const issued = { ...(await familyMember(family)), code };
+                    await tokenService.save(issued);
+                    const next = await familyMember(family);
+                    const claimed = tokenService.revokeRotated
+                        ? await tokenService.revokeRotated(issued)
+                        : await tokenService.revoke(issued);
+                    expect(claimed).toBe(true);
+                    await tokenService.revokeCode(code, client);
+                    await tokenService.save(next);
+                    expect(await isLive(next), "a successor saved after its code was replayed must be stored " +
+                        "already revoked: the refresh grant claims a token and saves " +
+                        "its successor in two calls, and a replay that lands between " +
+                        "them otherwise leaves the successor live").toBe(false);
+                    if (tokenService.hasLiveRefreshToken) {
+                        expect(await tokenService.hasLiveRefreshToken(family)).toBe(false);
+                    }
+                });
                 it("leaves rotatedAt unset on a token revoked other than by rotation", async () => {
                     const token = await saveFamilyMember(family);
                     await tokenService.revoke(token.refreshToken, "refresh_token");

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.
@@ -278,9 +294,13 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
     revokeFamily(familyId: string): Promise<boolean>;
     /**
      * Removes every token issued from the given authorization code, used when a
-     * code is replayed. Resolves `true` when at least one token was removed.
+     * code is replayed, and revokes the rotation families of those tokens as
+     * {@linkcode revokeFamily} does, so their rotated successors end with them.
+     * Resolves `true` when tokens were issued from the code.
+     * 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> {