@udibo/oauth2 0.35.0 → 0.37.0

package/README.md

@@ -1,6 +1,6 @@
 # @udibo/oauth2
 
-[![npm version](https://img.shields.io/npm/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![JSR version](https://jsr.io/badges/@udibo/oauth2)](https://jsr.io/@udibo/oauth2) [![JSR score](https://jsr.io/badges/@udibo/oauth2/score)](https://jsr.io/@udibo/oauth2/score) [![CI](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml/badge.svg?branch=main)](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/npm/l/@udibo/oauth2)](LICENSE) [![npm downloads](https://img.shields.io/npm/dw/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![Node.js version](https://img.shields.io/node/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2)
+[![npm version](https://img.shields.io/npm/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![JSR version](https://jsr.io/badges/@udibo/oauth2)](https://jsr.io/@udibo/oauth2) [![CI](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml/badge.svg?branch=main)](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml?query=branch%3Amain) [![Coverage](https://codecov.io/gh/udibo/oauth2/branch/main/graph/badge.svg)](https://codecov.io/gh/udibo/oauth2) [![License: MIT](https://img.shields.io/npm/l/@udibo/oauth2)](LICENSE) [![npm downloads](https://img.shields.io/npm/dw/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![Node.js version](https://img.shields.io/node/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2)
 
 OAuth2 and OpenID Connect tools for TypeScript applications: clients,
 authorization and resource servers, Hono middleware, React bindings, and

package/dist/models/token.d.ts

@@ -30,6 +30,14 @@ export interface Token<Client extends ClientInterface, User, Scope extends Abstr
     claims?: Record<string, unknown>;
     /** The authorization code used to generate this token, for replay detection per RFC 6819. */
     code?: string;
+    /**
+     * The SHA-256 digest, as lowercase hex, of the PKCE `code_verifier` that
+     * redeemed {@linkcode Token.code}. The authorization code grant sets it on a
+     * code redeemed with PKCE. A token service persists it with the code, so
+     * `revokeCode` can tell a replay that presents that verifier from one that
+     * only names the client.
+     */
+    codeVerifierHash?: string;
     /**
      * OIDC nonce carried transiently from the authorization code so the token
      * endpoint can echo it in the id_token. Not persisted by token stores.

package/dist/server/grants/authorization-code.d.ts

@@ -33,8 +33,10 @@ export interface CodeReuseEvent<Client extends ClientInterface> {
      * The client that presented the code. It is the code's own client only when
      * the token service's `revokeCode` honors its `client` argument. A public
      * client, or any client the grant looks up by id because
-     * `requireClientAuthentication` is `false`, is named by `client_id` alone,
-     * so whoever holds the spent code can present it as that client.
+     * `requireClientAuthentication` is `false`, is named by `client_id` alone;
+     * its replay revokes, and so reaches this event, only when it presented the
+     * `code_verifier` that redeemed the code and `revokeCode` honors its
+     * `codeVerifierHash` argument.
      */
     client: Client;
 }
@@ -90,7 +92,9 @@ export interface AuthorizationCodeGrantOptions<Client extends ClientInterface, U
      * token service's `revokeCode` revoked those tokens — record it as a
      * security event. A `revokeCode` that honors its `client` argument revokes
      * nothing, and so does not fire this, for a client other than the code's
-     * own; {@linkcode CodeReuseEvent.client} says who that excludes.
+     * own; {@linkcode CodeReuseEvent.client} says who that excludes. A client
+     * that did not authenticate with its secret fires it only by presenting the
+     * `code_verifier` that redeemed the code.
      *
      * Trigger point `code-reuse` (see `docs/trigger-points.md`).
      * Fire-and-forget: it is awaited, but a throw is caught and logged, never
@@ -225,7 +229,14 @@ export declare class AuthorizationCodeGrant<Client extends ClientInterface, User
      * then fails its checks, asks
      * `tokenService.revokeCode` to revoke the tokens issued from it on behalf of
      * the presenting client, fires `onCodeReuse` when it did, and fails with
-     * `invalid_grant` (RFC 6819 §4.4.1.1).
+     * `invalid_grant` (RFC 6819 §4.4.1.1). The replay must prove it could have
+     * redeemed the code: a client that authenticated with a `client_secret` in
+     * `request` asks with the client alone, and any other client asks with the
+     * SHA-256 hex digest of the `code_verifier` it presented, which `revokeCode`
+     * matches against {@linkcode Token.codeVerifierHash}. Without a verifier,
+     * such a client's replay revokes nothing. Pass the `client` that
+     * {@linkcode getAuthenticatedClient} resolved from this same `request`.
+     * A code redeemed with PKCE issues its token with `codeVerifierHash` set.
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.
      * @throws {InvalidGrantError} When the code is unknown, expired, already claimed, or its verifier or `redirect_uri` does not match.

package/dist/server/grants/authorization-code.js

@@ -188,7 +188,14 @@ export class AuthorizationCodeGrant extends AbstractGrant {
      * then fails its checks, asks
      * `tokenService.revokeCode` to revoke the tokens issued from it on behalf of
      * the presenting client, fires `onCodeReuse` when it did, and fails with
-     * `invalid_grant` (RFC 6819 §4.4.1.1).
+     * `invalid_grant` (RFC 6819 §4.4.1.1). The replay must prove it could have
+     * redeemed the code: a client that authenticated with a `client_secret` in
+     * `request` asks with the client alone, and any other client asks with the
+     * SHA-256 hex digest of the `code_verifier` it presented, which `revokeCode`
+     * matches against {@linkcode Token.codeVerifierHash}. Without a verifier,
+     * such a client's replay revokes nothing. Pass the `client` that
+     * {@linkcode getAuthenticatedClient} resolved from this same `request`.
+     * A code redeemed with PKCE issues its token with `codeVerifierHash` set.
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.
      * @throws {InvalidGrantError} When the code is unknown, expired, already claimed, or its verifier or `redirect_uri` does not match.
@@ -202,9 +209,10 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         if (typeof code !== "string") {
             throw new InvalidRequestError("code parameter required");
         }
+        const replay = { code, client, request, body };
         const authorizationCode = await authorizationCodeService.get(code);
         if (!authorizationCode) {
-            throw await this.#refuseClaimedCode(tokenService, code, client, "invalid code");
+            throw await this.#refuseClaimedCode(tokenService, replay, "invalid code");
         }
         if (authorizationCode.expiresAt < new Date()) {
             throw new InvalidGrantError("invalid code");
@@ -212,7 +220,7 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         const exchangeCode = tokenService.exchangeCode?.bind(tokenService);
         if (!exchangeCode &&
             !(await authorizationCodeService.revoke(authorizationCode))) {
-            throw await this.#refuseClaimedCode(tokenService, code, client);
+            throw await this.#refuseClaimedCode(tokenService, replay);
         }
         let token;
         try {
@@ -221,11 +229,15 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         }
         catch (error) {
             if (exchangeCode) {
-                await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client);
+                await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, replay);
             }
             throw error;
         }
         token.code = code;
+        const codeVerifier = body.get("code_verifier");
+        if (typeof codeVerifier === "string") {
+            token.codeVerifierHash = await sha256Hash(codeVerifier);
+        }
         let saved;
         if (exchangeCode) {
             try {
@@ -233,7 +245,7 @@ export class AuthorizationCodeGrant extends AbstractGrant {
             }
             catch (error) {
                 if (isOAuth2Error(error)) {
-                    await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client);
+                    await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, replay);
                 }
                 throw error;
             }
@@ -242,7 +254,7 @@ export class AuthorizationCodeGrant extends AbstractGrant {
             saved = await tokenService.save(token);
         }
         if (!saved) {
-            throw await this.#refuseClaimedCode(tokenService, code, client);
+            throw await this.#refuseClaimedCode(tokenService, replay);
         }
         if (authorizationCode.nonce)
             saved.nonce = authorizationCode.nonce;
@@ -281,23 +293,38 @@ export class AuthorizationCodeGrant extends AbstractGrant {
             throw new InvalidGrantError("did not expect redirect_uri parameter");
         }
     }
-    async #consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client) {
+    async #consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, replay) {
         try {
             if (!(await authorizationCodeService.revoke(authorizationCode))) {
-                await this.#refuseClaimedCode(tokenService, authorizationCode.code, client);
+                await this.#refuseClaimedCode(tokenService, replay);
             }
         }
         catch (error) {
             console.error("[@udibo/oauth2] could not consume the code of a failed exchange:", error instanceof Error ? error.message : error);
         }
     }
-    async #refuseClaimedCode(tokenService, code, client, unrevokedMessage = "code already used") {
-        if (!(await tokenService.revokeCode(code, client))) {
-            return new InvalidGrantError(unrevokedMessage);
+    async #refuseClaimedCode(tokenService, { code, client, request, body }, unrevokedMessage = "code already used") {
+        const codeVerifier = body.get("code_verifier");
+        let revoked = false;
+        if (this.#authenticatedBySecret(request, body)) {
+            revoked = await tokenService.revokeCode(code, client);
+        }
+        else if (typeof codeVerifier === "string") {
+            revoked = await tokenService.revokeCode(code, client, await sha256Hash(codeVerifier));
         }
+        if (!revoked)
+            return new InvalidGrantError(unrevokedMessage);
         await this.#notifyCodeReuse({ codeHash: await sha256Hash(code), client });
         return new InvalidGrantError("code already used");
     }
+    #authenticatedBySecret(request, body) {
+        try {
+            return !!this.getClientCredentials(request, body).clientSecret;
+        }
+        catch {
+            return false;
+        }
+    }
     async #notifyCodeReuse(event) {
         if (!this.#onCodeReuse)
             return;

package/dist/server/services/token.d.ts

@@ -162,17 +162,28 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * Returns true if any tokens were revoked, which the grant reports as a code
      * replay (RFC 6819 §4.4.1.1).
      *
+     * After the client check below passes, revoke every live member of the
+     * rotation families of those tokens too, as {@linkcode revokeFamily} does,
+     * keeping them revoked against a rotation in flight. A refresh token rotated
+     * from the code's token carries no `code`, so revoking only the tokens saved
+     * with the code leaves the stolen code's session refreshing once it has
+     * rotated.
+     *
      * `client` is the client that presented the code. Revoke only when it is the
      * client the code's tokens were issued to; for any other client revoke
      * nothing and resolve `false`. A different confidential client could never
      * have redeemed the code, since that needs the code's own client's
-     * credentials, so its replay says nothing about theft. The gate names a
-     * public client, or any client when the grant's
-     * `requireClientAuthentication` is `false`, by `client_id` alone, so anyone
-     * holding such a client's spent code can still present it as that client
-     * and revoke. A store that ignores `client` revokes on any client's replay,
-     * which lets a client that sees a leaked, spent code end the session it
-     * started.
+     * credentials, so its replay says nothing about theft. A store that ignores
+     * `client` revokes on any client's replay, which lets a client that sees a
+     * leaked, spent code end the session it started.
+     *
+     * `codeVerifierHash`, the SHA-256 hex digest of the `code_verifier` the
+     * replay presented, is passed for a client that did not authenticate with a
+     * secret. When it is given, also revoke only when it equals the
+     * {@linkcode Token.codeVerifierHash} persisted with the code's tokens;
+     * tokens saved without one never match. Omitted, the client check alone
+     * applies. A store that ignores it lets anyone holding a public client's
+     * spent code end the session it started.
      *
      * With {@linkcode exchangeCode}, make the two linearizable: a call that
      * begins once `exchangeCode` has claimed the code must find and revoke the
@@ -181,7 +192,7 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      *
      * @see https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.1.1
      */
-    revokeCode(code: string, client?: Client): Promise<boolean>;
+    revokeCode(code: string, client?: Client, codeVerifierHash?: string): Promise<boolean>;
     /**
      * Exchanges an authorization code in one atomic step: claims
      * `authorizationCode` as `AuthorizationCodeServiceInterface.revoke`
@@ -200,8 +211,9 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      *
      * After a successful call the code service's `get` must resolve `undefined`
      * for the code, as after `revoke`. A failed insert must leave the code
-     * claimable. Store the token so `revokeCode` finds it by the code, and make
-     * the two linearizable, as `revokeCode` requires.
+     * claimable. Store the token so `revokeCode` finds it by the code, with its
+     * {@linkcode Token.codeVerifierHash}, and make the two linearizable, as
+     * `revokeCode` requires.
      * `runCodeExchangeContractTests` checks it under concurrent callers, with
      * the store's barrier wired between its claim and its insert.
      */
@@ -365,8 +377,9 @@ export declare abstract class AbstractTokenService<Client extends ClientInterfac
     /**
      * Revokes every token issued from the given authorization code, returning
      * true if any were revoked (signaling code replay per RFC 6819 §4.4.1.1).
-     * Revoke nothing when `client` is not the client the tokens were issued to
-     * ({@linkcode TokenServiceInterface.revokeCode} explains why).
+     * Revoke nothing when `client` is not the client the tokens were issued to,
+     * or when `codeVerifierHash` is given and is not the one they were saved
+     * with ({@linkcode TokenServiceInterface.revokeCode} explains why).
      */
-    abstract revokeCode(code: string, client?: Client): Promise<boolean>;
+    abstract revokeCode(code: string, client?: Client, codeVerifierHash?: string): Promise<boolean>;
 }

package/dist/testing/contract/code-exchange.d.ts

@@ -87,6 +87,15 @@ export interface CodeExchangeContractOptions<C extends ClientInterface, U extend
      * longer to reach the lock they wait on.
      */
     blockedAfterMs?: number;
+    /**
+     * Set to `false` when the service's `revokeCode` deliberately ignores its
+     * `codeVerifierHash` argument, as `runTokenServiceContractTests` allows. The
+     * suite still checks that a token `exchangeCode` saved revokes for its own
+     * verifier, and registers an ignored case naming what is not covered — a
+     * replay that names a public client, with any verifier, revokes the token
+     * `exchangeCode` saved. Defaults to `true`.
+     */
+    revokeCodeChecksVerifier?: boolean;
     /** Overrides the name passed to the outer `describe` block. */
     describeName?: string;
 }

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

@@ -24,6 +24,8 @@
 import { assert, beforeEach, describe, expect, it } from "vitest";
 import { InvalidGrantError } from "../../errors.js";
 import { AuthorizationCodeGrant, } from "../../server/grants/authorization-code.js";
+import { sha256Hash } from "../../server/utils/hash.js";
+import { generateCodeChallenge, generateCodeVerifier, } from "../../utils/pkce.js";
 import { race } from "./_race.js";
 const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
 const defaultMakeClient = (seq) => ({
@@ -57,6 +59,7 @@ export function runCodeExchangeContractTests(options) {
     const makeClient = options.makeClient ?? defaultMakeClient;
     const pausable = options.exchangeAwaitsBarrier ?? true;
     const blockedAfterMs = options.blockedAfterMs ?? 100;
+    const expectCodeVerifierCheck = options.revokeCodeChecksVerifier ?? true;
     describe(options.describeName ?? "TokenServiceInterface.exchangeCode contract", () => {
         let services;
         let codeService;
@@ -64,6 +67,7 @@ export function runCodeExchangeContractTests(options) {
         let user;
         let client;
         let armed;
+        let verifiers;
         const barriers = {
             async afterClaim() {
                 const hold = armed;
@@ -76,6 +80,7 @@ export function runCodeExchangeContractTests(options) {
         };
         beforeEach(async () => {
             armed = undefined;
+            verifiers = new Map();
             services = await options.makeServices(barriers);
             codeService = services.authorizationCodeService;
             tokenService = services.tokenService;
@@ -88,24 +93,37 @@ export function runCodeExchangeContractTests(options) {
             assert(typeof tokenService.exchangeCode === "function", "runCodeExchangeContractTests needs a token service that implements exchangeCode");
             return tokenService.exchangeCode(authorizationCode, token);
         }
+        function verifierOf(authorizationCode) {
+            const verifier = verifiers.get(authorizationCode.code);
+            assert(verifier, "the suite saved no verifier for this code");
+            return verifier;
+        }
         async function savedCode() {
+            const verifier = generateCodeVerifier();
             const authorizationCode = {
                 code: await codeService.generateCode(client, user),
                 expiresAt: await codeService.expiresAt(client, user),
                 client,
                 user,
+                challenge: await generateCodeChallenge(verifier),
+                challengeMethod: "S256",
             };
+            verifiers.set(authorizationCode.code, verifier);
             await codeService.save(authorizationCode);
             return authorizationCode;
         }
         async function tokenFor(authorizationCode) {
-            return {
+            const token = {
                 accessToken: await tokenService.generateAccessToken(client, user),
                 accessTokenExpiresAt: new Date(Date.now() + 60_000),
                 client,
                 user,
                 code: authorizationCode.code,
             };
+            const verifier = verifiers.get(authorizationCode.code);
+            if (verifier)
+                token.codeVerifierHash = await sha256Hash(verifier);
+            return token;
         }
         async function live(tokens) {
             const found = [];
@@ -154,6 +172,8 @@ export function runCodeExchangeContractTests(options) {
             const body = new FormData();
             body.set("grant_type", "authorization_code");
             body.set("code", authorizationCode.code);
+            body.set("client_id", client.id.toString());
+            body.set("code_verifier", verifierOf(authorizationCode));
             return grant.token(new Request("https://as.test/token", { method: "POST" }), client, body);
         }
         it("implements exchangeCode", () => {
@@ -170,6 +190,30 @@ export function runCodeExchangeContractTests(options) {
             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("revokes the token it saved for the codeVerifierHash it was saved with", async () => {
+            const authorizationCode = await savedCode();
+            const token = await tokenFor(authorizationCode);
+            await exchangeCode(authorizationCode, token);
+            expect(await tokenService.revokeCode(authorizationCode.code, client, token.codeVerifierHash), "exchangeCode must persist codeVerifierHash with the token, or a " +
+                "replay with the redeeming verifier cannot revoke it").toBe(true);
+            expect(await live([token])).toStrictEqual([]);
+        });
+        if (expectCodeVerifierCheck) {
+            it("keeps the token's codeVerifierHash, so revokeCode refuses another verifier and revokes for its own", async () => {
+                const authorizationCode = await savedCode();
+                const token = await tokenFor(authorizationCode);
+                await exchangeCode(authorizationCode, token);
+                expect(await tokenService.revokeCode(authorizationCode.code, client, await sha256Hash(generateCodeVerifier())), "a replay that does not present the redeeming verifier must " +
+                    "revoke nothing").toBe(false);
+                expect(await live([token])).toStrictEqual([token.accessToken]);
+                expect(await tokenService.revokeCode(authorizationCode.code, client, token.codeVerifierHash), "exchangeCode must persist codeVerifierHash with the token, or a " +
+                    "replay with the redeeming verifier cannot revoke it").toBe(true);
+                expect(await live([token])).toStrictEqual([]);
+            });
+        }
+        else {
+            it.skip("revokeCode ignores the presented verifier — a replay that names a public client, with any verifier, revokes the token exchangeCode saved (revokeCodeChecksVerifier: false)", () => { });
+        }
         it("refuses a code that was already claimed or never stored, persisting nothing", async () => {
             const claimed = await savedCode();
             await codeService.revoke(claimed.code);

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

@@ -86,6 +86,15 @@ export interface TokenServiceContractOptions<C extends ClientInterface, U extend
      * started — instead of passing in silence. Defaults to `true`.
      */
     revokeCodeChecksClient?: boolean;
+    /**
+     * Set to `false` when the service's `revokeCode` deliberately ignores its
+     * `codeVerifierHash` argument. The suite then registers an ignored case
+     * naming what is not covered — a replay that names a public client by
+     * `client_id`, with any verifier, revokes the tokens issued from its spent
+     * code, so anyone who holds a leaked code can end the session it started —
+     * instead of passing in silence. Defaults to `true`.
+     */
+    revokeCodeChecksVerifier?: boolean;
     /** Overrides the name passed to the outer `describe` block. */
     describeName?: string;
 }

package/dist/testing/contract/token.js

@@ -27,6 +27,7 @@ const defaultMakeClient = (seq) => ({
 });
 const defaultMakeScope = (value) => new BasicScope(value);
 const defaultMakeFamilyId = () => crypto.randomUUID();
+const randomVerifierHash = () => Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, "0")).join("");
 /** Runs the {@link TokenServiceInterface} contract suite. */
 export function runTokenServiceContractTests(options) {
     const makeUser = options.makeUser ?? defaultMakeUser;
@@ -36,6 +37,7 @@ export function runTokenServiceContractTests(options) {
     const makeFamilyId = options.makeFamilyId ?? defaultMakeFamilyId;
     const expectReuseDetection = options.refreshTokenReuseDetection ?? true;
     const expectCodeClientCheck = options.revokeCodeChecksClient ?? true;
+    const expectCodeVerifierCheck = options.revokeCodeChecksVerifier ?? true;
     describe(options.describeName ?? "TokenServiceInterface contract", () => {
         let userService;
         let clientService;
@@ -52,6 +54,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);
@@ -237,10 +274,92 @@ export function runTokenServiceContractTests(options) {
                     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 (expectCodeVerifierCheck) {
+                async function issueBoundCode(code, codeVerifierHash) {
+                    const accessToken = await tokenService.generateAccessToken(client, user);
+                    await tokenService.save({
+                        accessToken,
+                        code,
+                        codeVerifierHash,
+                        client,
+                        user,
+                    });
+                    return accessToken;
+                }
+                it("revokes nothing for a codeVerifierHash other than the one the code's tokens were saved with", async () => {
+                    const accessToken = await issueBoundCode("bound-code", randomVerifierHash());
+                    expect(await tokenService.revokeCode("bound-code", client, randomVerifierHash()), "a replay without the verifier that redeemed the code proves " +
+                        "nothing, so it must not revoke what the code issued").toBe(false);
+                    expect(await tokenService.getToken(accessToken)).not.toBe(undefined);
+                });
+                it("revokes for the codeVerifierHash the code's tokens were saved with, after another was refused", async () => {
+                    const codeVerifierHash = randomVerifierHash();
+                    const accessToken = await issueBoundCode("bound-code", codeVerifierHash);
+                    await tokenService.revokeCode("bound-code", client, randomVerifierHash());
+                    expect(await tokenService.revokeCode("bound-code", client, codeVerifierHash)).toBe(true);
+                    expect(await tokenService.getToken(accessToken)).toBe(undefined);
+                });
+                if (expectCodeClientCheck) {
+                    it("revokes nothing for another client that presents the codeVerifierHash the code's tokens were saved with", async () => {
+                        const other = makeClient(2);
+                        await options.addClient(clientService, other);
+                        const codeVerifierHash = randomVerifierHash();
+                        const accessToken = await issueBoundCode("bound-code", codeVerifierHash);
+                        expect(await tokenService.revokeCode("bound-code", other, codeVerifierHash), "a matching verifier does not lift the client check").toBe(false);
+                        expect(await tokenService.getToken(accessToken)).not.toBe(undefined);
+                    });
+                }
+                it("revokes nothing for a codeVerifierHash when the code's tokens were saved without one", async () => {
+                    const accessToken = await issueBoundCode("unbound-code");
+                    expect(await tokenService.revokeCode("unbound-code", client, randomVerifierHash()), "a code redeemed without PKCE binds no verifier, so no verifier " +
+                        "a replay presents can match it").toBe(false);
+                    expect(await tokenService.getToken(accessToken)).not.toBe(undefined);
+                });
+                it("revokes a code saved with a codeVerifierHash when none is passed, for a client that authenticated", async () => {
+                    const accessToken = await issueBoundCode("bound-code", randomVerifierHash());
+                    expect(await tokenService.revokeCode("bound-code", client), "the grant omits codeVerifierHash for a client that " +
+                        "authenticated with its secret, where the client check suffices").toBe(true);
+                    expect(await tokenService.getToken(accessToken)).toBe(undefined);
+                });
+                it("revokes nothing in a rotated family for a codeVerifierHash other than the one the code's tokens were saved with", async () => {
+                    const family = makeFamilyId();
+                    const issued = {
+                        ...(await familyMember(family)),
+                        code: "rotated-bound-code",
+                        codeVerifierHash: randomVerifierHash(),
+                    };
+                    await tokenService.save(issued);
+                    const rotated = await familyMember(family);
+                    await rotateTo(issued, rotated);
+                    expect(await tokenService.revokeCode("rotated-bound-code", client, randomVerifierHash())).toBe(false);
+                    expect(await isLive(rotated), "the verifier check comes before any family is revoked — a " +
+                        "replay without the redeeming verifier must not end the " +
+                        "session rotated from the code").toBe(true);
+                });
+            }
+            else {
+                it.skip("revokeCode ignores the presented verifier — a replay that names a public client, with any verifier, revokes its spent code's tokens (revokeCodeChecksVerifier: false)", () => { });
+            }
         });
         if (expectReuseDetection) {
             describe("refresh-token rotation family", () => {
@@ -250,25 +369,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 " +
@@ -404,6 +504,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/services.d.ts

@@ -294,11 +294,14 @@ 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.
+     * client the code's tokens were issued to, or when `codeVerifierHash` is
+     * given and is not the one they were saved with.
      */
-    revokeCode(code: string, client?: C): Promise<boolean>;
+    revokeCode(code: string, client?: C, codeVerifierHash?: string): Promise<boolean>;
 }
 /** Options for {@link MemoryAuthorizationCodeService}. */
 export interface MemoryAuthorizationCodeServiceOptions<C extends ClientInterface, U extends MemoryUserShape> {

package/dist/testing/services.js

@@ -354,6 +354,9 @@ export class MemoryTokenService {
         };
         if (token.code)
             stored.codeHash = await sha256Hash(token.code);
+        if (token.codeVerifierHash) {
+            stored.codeVerifierHash = token.codeVerifierHash;
+        }
         if ("refreshToken" in token) {
             const rt = token;
             stored.refreshTokenHash = await sha256Hash(rt.refreshToken);
@@ -367,10 +370,17 @@ export class MemoryTokenService {
         if (stored.codeHash) {
             let bucket = this.#tokensByCodeHash.get(stored.codeHash);
             if (!bucket) {
-                bucket = { clientId: stored.clientId, accessTokenHashes: new Set() };
+                bucket = {
+                    clientId: stored.clientId,
+                    codeVerifierHash: stored.codeVerifierHash,
+                    accessTokenHashes: new Set(),
+                    familyIds: new Set(),
+                };
                 this.#tokensByCodeHash.set(stored.codeHash, bucket);
             }
             bucket.accessTokenHashes.add(stored.accessTokenHash);
+            if (stored.familyId)
+                bucket.familyIds.add(stored.familyId);
         }
         if (stored.refreshTokenHash) {
             if (stored.familyId && this.#revokedFamilies.has(stored.familyId)) {
@@ -483,6 +493,9 @@ export class MemoryTokenService {
      * live token was removed.
      */
     revokeFamily(familyId) {
+        return Promise.resolve(this.#revokeFamily(familyId));
+    }
+    #revokeFamily(familyId) {
         this.#revokedFamilies.add(familyId);
         let revoked = false;
         for (const [hash, stored] of this.#tokensByRefreshHash) {
@@ -499,15 +512,18 @@ export class MemoryTokenService {
                 revoked = true;
             }
         }
-        return Promise.resolve(revoked);
+        return revoked;
     }
     /**
      * 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.
+     * client the code's tokens were issued to, or when `codeVerifierHash` is
+     * given and is not the one they were saved with.
      */
-    async revokeCode(code, client) {
+    async revokeCode(code, client, codeVerifierHash) {
         const codeHash = await sha256Hash(code);
         const bucket = this.#tokensByCodeHash.get(codeHash);
         if (!bucket || bucket.accessTokenHashes.size === 0)
@@ -515,6 +531,12 @@ export class MemoryTokenService {
         if (client && client.id.toString() !== bucket.clientId.toString()) {
             return false;
         }
+        if (codeVerifierHash !== undefined &&
+            codeVerifierHash !== bucket.codeVerifierHash) {
+            return false;
+        }
+        for (const familyId of bucket.familyIds)
+            this.#revokeFamily(familyId);
         for (const accessTokenHash of bucket.accessTokenHashes) {
             const stored = this.#tokensByAccessHash.get(accessTokenHash);
             if (stored) {

package/package.json

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