@udibo/oauth2 0.34.0 → 0.35.0

package/dist/adapters/hono/bff/auth-request-store.d.ts

@@ -139,7 +139,10 @@ export interface AuthRequestStorageFactory {
  *
  * It has no `take`: the record travels with the browser and cannot be claimed
  * atomically, so a replayed callback is bounded by the authorization server's
- * single-use code and PKCE.
+ * single-use code and PKCE. Two concurrent callbacks for one sign-in both reach
+ * the token endpoint, and an authorization server that revokes on code replay,
+ * as `@udibo/oauth2`'s does, revokes the tokens the winner received, so the
+ * user is signed out and has to sign in again.
  *
  * @example
  * ```ts

package/dist/adapters/hono/bff/auth-request-store.js

@@ -63,7 +63,10 @@ function cookieAttributes(options, maxAgeSeconds) {
  *
  * It has no `take`: the record travels with the browser and cannot be claimed
  * atomically, so a replayed callback is bounded by the authorization server's
- * single-use code and PKCE.
+ * single-use code and PKCE. Two concurrent callbacks for one sign-in both reach
+ * the token endpoint, and an authorization server that revokes on code replay,
+ * as `@udibo/oauth2`'s does, revokes the tokens the winner received, so the
+ * user is signed out and has to sign in again.
  *
  * @example
  * ```ts

package/dist/cli/idp/server.js

@@ -55,12 +55,13 @@ function newSession(userId, signedInFor) {
 async function createState(config, signingKey, issuer) {
     const userService = new MemoryUserService();
     const clientService = new MemoryClientService(userService);
+    const authorizationCodeService = new MemoryAuthorizationCodeService({ clientService, userService });
     const tokenService = new MemoryTokenService({
         clientService,
         userService,
         accessTokenLifetime: config.accessTokenLifetime,
+        authorizationCodeService,
     });
-    const authorizationCodeService = new MemoryAuthorizationCodeService({ clientService, userService });
     const grants = {};
     if (config.grants.authorization_code) {
         grants.authorization_code = new AuthorizationCodeGrant({

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

@@ -314,6 +314,35 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      *   contains a space or non-ASCII character.
      */
     acrValuesSupported?: readonly string[];
+    /**
+     * Called when the revocation endpoint revokes the rotation family of a
+     * refresh token that rotation already replaced — the client presented a
+     * token that is no longer live, so record it alongside your reuse events.
+     * It fires once per such request, after `revokeFamily`, only for a token
+     * issued to the authenticated client. It never fires `onTokenReuse`: a
+     * sign-out racing the client's own refresh presents the same token, so this
+     * is not by itself evidence of theft.
+     *
+     * Trigger point `rotated-out-revocation` (see `docs/trigger-points.md`).
+     * Fire-and-forget: it is awaited, but a throw is caught and logged, never
+     * rethrown, so a failing hook cannot change the `200` the endpoint answers.
+     */
+    onRotatedOutRevocation?: (event: RotatedOutRevocationEvent<Client, User>) => void | Promise<void>;
+}
+/**
+ * What the revocation endpoint observed when it revoked the rotation family of
+ * a refresh token that rotation already replaced. Passed to
+ * {@link AuthorizationServerOptions.onRotatedOutRevocation}.
+ */
+export interface RotatedOutRevocationEvent<Client extends ClientInterface, User> {
+    /** The rotation family the presented token belonged to. */
+    familyId: string;
+    /** The client the presented token was issued to, which authenticated. */
+    client: Client;
+    /** The user the presented token was issued for, if any. */
+    user?: User;
+    /** Whether {@linkcode TokenServiceInterface.revokeFamily} revoked anything. */
+    familyRevoked: boolean;
 }
 /**
  * Function to authenticate the user during authorization.
@@ -707,7 +736,8 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * revoked other than by rotation, a token with no family, and a service
      * without `getRevokedRefreshToken` and `revokeFamily` revoke nothing more.
      * The refresh grant's `replayGraceSeconds` does not apply here, and
-     * `onTokenReuse` does not fire.
+     * `onTokenReuse` does not fire; the server reports the revocation to
+     * {@linkcode AuthorizationServerOptions.onRotatedOutRevocation} instead.
      *
      * Always returns 200 OK, even if the token was invalid, already revoked, or
      * issued to another client: RFC 7009 Section 2.2 requires that answer so the
@@ -860,7 +890,7 @@ export { AbstractGrant } from "./grants/grant.ts";
 export type { DispatchableGrant, GrantOptions, GrantServices, } from "./grants/grant.ts";
 export { AuthorizationCodeGrant } from "./grants/authorization-code.ts";
 export type { PKCEClientCredentials } from "./grants/authorization-code.ts";
-export type { AuthorizationCodeGrantOptions, AuthorizationCodeGrantServices, GenerateAuthorizationCodeOptions, } from "./grants/authorization-code.ts";
+export type { AuthorizationCodeGrantOptions, AuthorizationCodeGrantServices, CodeReuseEvent, GenerateAuthorizationCodeOptions, } from "./grants/authorization-code.ts";
 export { ClientCredentialsGrant } from "./grants/client-credentials.ts";
 export type { ClientCredentialsGrantOptions, ClientCredentialsGrantServices, } from "./grants/client-credentials.ts";
 export { createJwtAccessTokenGenerator, exportSigningKeyJwk, generateSigningKey, importSigningKeyJwk, RotatingSigningKeyProvider, type RotatingSigningKeyProviderOptions, type SigningKey, type SigningKeyProvider, signJwt, StaticSigningKeyProvider, verifyJwt, type VerifyJwtOptions, } from "./signing-keys.ts";

package/dist/server/authorization-server.js

@@ -200,6 +200,7 @@ export class AuthorizationServer extends ResourceServer {
     #subjectOf;
     #userClaims;
     #introspectionClaims;
+    #onRotatedOutRevocation;
     #canIntrospectToken;
     #resolve;
     /**
@@ -254,6 +255,7 @@ export class AuthorizationServer extends ResourceServer {
         this.#userClaims = options.userClaims;
         this.#introspectionClaims = options.introspectionClaims;
         this.#canIntrospectToken = options.canIntrospectToken;
+        this.#onRotatedOutRevocation = options.onRotatedOutRevocation;
     }
     #handleEndpointError(error, prepare) {
         const oauth2Error = toOAuth2Error(error);
@@ -1001,7 +1003,8 @@ export class AuthorizationServer extends ResourceServer {
      * revoked other than by rotation, a token with no family, and a service
      * without `getRevokedRefreshToken` and `revokeFamily` revoke nothing more.
      * The refresh grant's `replayGraceSeconds` does not apply here, and
-     * `onTokenReuse` does not fire.
+     * `onTokenReuse` does not fire; the server reports the revocation to
+     * {@linkcode AuthorizationServerOptions.onRotatedOutRevocation} instead.
      *
      * Always returns 200 OK, even if the token was invalid, already revoked, or
      * issued to another client: RFC 7009 Section 2.2 requires that answer so the
@@ -1050,7 +1053,23 @@ export class AuthorizationServer extends ResourceServer {
         if (rotatedOut?.rotatedAt &&
             rotatedOut.familyId &&
             rotatedOut.client.id.toString() === client.id.toString()) {
-            await tokenService.revokeFamily(rotatedOut.familyId);
+            const familyRevoked = await tokenService.revokeFamily(rotatedOut.familyId);
+            await this.#notifyRotatedOutRevocation({
+                familyId: rotatedOut.familyId,
+                client: rotatedOut.client,
+                user: rotatedOut.user,
+                familyRevoked,
+            });
+        }
+    }
+    async #notifyRotatedOutRevocation(event) {
+        if (!this.#onRotatedOutRevocation)
+            return;
+        try {
+            await this.#onRotatedOutRevocation(event);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] onRotatedOutRevocation hook failed:", error instanceof Error ? error.message : error);
         }
     }
     async #resolveToken(tokenService, value, hint) {

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

@@ -17,6 +17,27 @@ export interface AuthorizationCodeGrantServices<Client extends ClientInterface,
     /** Generates, stores, and looks up authorization codes for the exchange. */
     authorizationCodeService: AuthorizationCodeServiceInterface<Client, User, S>;
 }
+/**
+ * What the authorization code grant observed when a code that already issued
+ * tokens was presented again. Passed to
+ * {@link AuthorizationCodeGrantOptions.onCodeReuse}.
+ */
+export interface CodeReuseEvent<Client extends ClientInterface> {
+    /**
+     * The SHA-256 digest of the replayed code, as lowercase hex — the value a
+     * store that hashes codes keys them on, so it correlates without recording
+     * the code itself.
+     */
+    codeHash: string;
+    /**
+     * 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.
+     */
+    client: Client;
+}
 /**
  * Options for configuring the authorization code grant.
  *
@@ -64,6 +85,19 @@ export interface AuthorizationCodeGrantOptions<Client extends ClientInterface, U
      * @see https://datatracker.ietf.org/doc/html/rfc9700#section-2.1.1
      */
     requireClientAuthentication?: boolean;
+    /**
+     * Called when a code that already issued tokens is presented again and the
+     * 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.
+     *
+     * Trigger point `code-reuse` (see `docs/trigger-points.md`).
+     * Fire-and-forget: it is awaited, but a throw is caught and logged, never
+     * rethrown, so a failing security-logging hook cannot change the
+     * client-facing `invalid_grant` a replayed code always yields.
+     */
+    onCodeReuse?: (event: CodeReuseEvent<Client>) => void | Promise<void>;
 }
 /** Client credentials extended with optional PKCE code_verifier. */
 export interface PKCEClientCredentials extends ClientCredentials {
@@ -103,6 +137,7 @@ export interface GenerateAuthorizationCodeOptions<Client extends ClientInterface
  * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.1.1
  */
 export declare class AuthorizationCodeGrant<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> extends AbstractGrant<Client, User, S, AuthorizationCodeGrantServices<Client, User, S>> {
+    #private;
     /** The OAuth2 grant type: `authorization_code`. */
     readonly grantType = "authorization_code";
     /** The PKCE challenge methods this grant accepts. Defaults to `S256` only. */
@@ -169,11 +204,27 @@ export declare class AuthorizationCodeGrant<Client extends ClientInterface, User
      * Exchanges an authorization code for an access token. If PKCE was used
      * during authorization, the code_verifier must be provided.
      *
-     * The code is claimed by revoking it before the client-match, verifier, and
-     * `redirect_uri` checks, so a failed exchange still consumes the code. Only
-     * the caller whose revoke wins receives a token, given an atomic
-     * `authorizationCodeService.revoke`. Presenting a code that already minted
-     * tokens asks `tokenService.revokeCode` to revoke those tokens and fails with
+     * A failed exchange still consumes the code: one that fails the
+     * client-match, verifier or `redirect_uri` check, whose token cannot be
+     * generated, or that `exchangeCode` refuses with an OAuth2 error, is claimed
+     * before the error is thrown. Any other error from `exchangeCode`, such as a
+     * lost database connection, leaves the code claimable. Only the caller whose
+     * claim wins receives a token, given an atomic
+     * `authorizationCodeService.revoke`.
+     *
+     * When the token service implements
+     * {@linkcode TokenServiceInterface.exchangeCode}, the grant claims the code
+     * and saves the token in that one call. Otherwise it claims the code with
+     * `authorizationCodeService.revoke` before its checks and saves the token
+     * with `tokenService.save` after them; a replay that lands between those
+     * two calls finds no token to revoke, so the token saved afterwards stays
+     * live.
+     *
+     * A code presented after it was claimed, whether it was gone when the
+     * request read it or a concurrent exchange won the claim, even one that
+     * 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).
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.

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

@@ -4,9 +4,10 @@
  * @module
  */
 import { snapshotAuthenticationContext } from "../../utils/authentication-context.js";
-import { InvalidClientError, InvalidGrantError, InvalidRequestError, ServerError, } from "../../errors.js";
+import { InvalidClientError, InvalidGrantError, InvalidRequestError, isOAuth2Error, ServerError, } from "../../errors.js";
 import { challengeMethods as defaultChallengeMethods, getChallengeMethod, validateCodeVerifier, } from "../../utils/pkce.js";
 import { authenticateClientCredentials } from "../client-authentication.js";
+import { sha256Hash } from "../utils/hash.js";
 import { AbstractGrant, } from "./grant.js";
 /**
  * The authorization code grant type.
@@ -37,6 +38,7 @@ export class AuthorizationCodeGrant extends AbstractGrant {
      * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.5
      */
     requireClientAuthentication;
+    #onCodeReuse;
     /** Creates the grant from its {@linkcode AuthorizationCodeGrantOptions}. */
     constructor(options) {
         super({
@@ -47,6 +49,7 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         this.requirePKCE = options.requirePKCE ?? true;
         this.requireClientAuthentication =
             options.requireClientAuthentication ?? true;
+        this.#onCodeReuse = options.onCodeReuse;
     }
     /**
      * Extracts client credentials from a request, carrying the PKCE
@@ -164,11 +167,27 @@ export class AuthorizationCodeGrant extends AbstractGrant {
      * Exchanges an authorization code for an access token. If PKCE was used
      * during authorization, the code_verifier must be provided.
      *
-     * The code is claimed by revoking it before the client-match, verifier, and
-     * `redirect_uri` checks, so a failed exchange still consumes the code. Only
-     * the caller whose revoke wins receives a token, given an atomic
-     * `authorizationCodeService.revoke`. Presenting a code that already minted
-     * tokens asks `tokenService.revokeCode` to revoke those tokens and fails with
+     * A failed exchange still consumes the code: one that fails the
+     * client-match, verifier or `redirect_uri` check, whose token cannot be
+     * generated, or that `exchangeCode` refuses with an OAuth2 error, is claimed
+     * before the error is thrown. Any other error from `exchangeCode`, such as a
+     * lost database connection, leaves the code claimable. Only the caller whose
+     * claim wins receives a token, given an atomic
+     * `authorizationCodeService.revoke`.
+     *
+     * When the token service implements
+     * {@linkcode TokenServiceInterface.exchangeCode}, the grant claims the code
+     * and saves the token in that one call. Otherwise it claims the code with
+     * `authorizationCodeService.revoke` before its checks and saves the token
+     * with `tokenService.save` after them; a replay that lands between those
+     * two calls finds no token to revoke, so the token saved afterwards stays
+     * live.
+     *
+     * A code presented after it was claimed, whether it was gone when the
+     * request read it or a concurrent exchange won the claim, even one that
+     * 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).
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.
@@ -183,17 +202,53 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         if (typeof code !== "string") {
             throw new InvalidRequestError("code parameter required");
         }
-        // RFC 6819 §4.4.1.1: code replay revokes already-issued tokens and rejects.
-        if (await tokenService.revokeCode(code)) {
-            throw new InvalidGrantError("code already used");
-        }
         const authorizationCode = await authorizationCodeService.get(code);
-        if (!authorizationCode || authorizationCode.expiresAt < new Date()) {
+        if (!authorizationCode) {
+            throw await this.#refuseClaimedCode(tokenService, code, client, "invalid code");
+        }
+        if (authorizationCode.expiresAt < new Date()) {
             throw new InvalidGrantError("invalid code");
         }
-        if (!(await authorizationCodeService.revoke(authorizationCode))) {
-            throw new InvalidGrantError("code already used");
+        const exchangeCode = tokenService.exchangeCode?.bind(tokenService);
+        if (!exchangeCode &&
+            !(await authorizationCodeService.revoke(authorizationCode))) {
+            throw await this.#refuseClaimedCode(tokenService, code, client);
+        }
+        let token;
+        try {
+            await this.#checkExchange(authorizationCode, client, body);
+            token = await this.generateToken(client, authorizationCode.user, authorizationCode.scope, tokenService, authorizationCode.authenticationContext);
+        }
+        catch (error) {
+            if (exchangeCode) {
+                await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client);
+            }
+            throw error;
+        }
+        token.code = code;
+        let saved;
+        if (exchangeCode) {
+            try {
+                saved = await exchangeCode(authorizationCode, token);
+            }
+            catch (error) {
+                if (isOAuth2Error(error)) {
+                    await this.#consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client);
+                }
+                throw error;
+            }
+        }
+        else {
+            saved = await tokenService.save(token);
+        }
+        if (!saved) {
+            throw await this.#refuseClaimedCode(tokenService, code, client);
         }
+        if (authorizationCode.nonce)
+            saved.nonce = authorizationCode.nonce;
+        return saved;
+    }
+    async #checkExchange(authorizationCode, client, body) {
         const codeVerifier = body.get("code_verifier");
         if (typeof codeVerifier === "string") {
             if (!validateCodeVerifier(codeVerifier)) {
@@ -209,11 +264,11 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         else if (this.requirePKCE) {
             throw new InvalidRequestError("PKCE is required for this grant");
         }
-        const { client: codeClient, user, scope, redirectUri: expectedRedirectUri, } = authorizationCode;
-        if (client.id.toString() !== codeClient.id.toString()) {
+        if (client.id.toString() !== authorizationCode.client.id.toString()) {
             throw new InvalidClientError("code was issued to another client");
         }
         const redirectUri = body.get("redirect_uri");
+        const expectedRedirectUri = authorizationCode.redirectUri;
         if (expectedRedirectUri) {
             if (typeof redirectUri !== "string") {
                 throw new InvalidGrantError("redirect_uri parameter required");
@@ -225,11 +280,32 @@ export class AuthorizationCodeGrant extends AbstractGrant {
         else if (redirectUri) {
             throw new InvalidGrantError("did not expect redirect_uri parameter");
         }
-        const token = await this.generateToken(client, user, scope, tokenService, authorizationCode.authenticationContext);
-        token.code = code;
-        const saved = await tokenService.save(token);
-        if (authorizationCode.nonce)
-            saved.nonce = authorizationCode.nonce;
-        return saved;
+    }
+    async #consumeFailedExchange(authorizationCodeService, tokenService, authorizationCode, client) {
+        try {
+            if (!(await authorizationCodeService.revoke(authorizationCode))) {
+                await this.#refuseClaimedCode(tokenService, authorizationCode.code, client);
+            }
+        }
+        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);
+        }
+        await this.#notifyCodeReuse({ codeHash: await sha256Hash(code), client });
+        return new InvalidGrantError("code already used");
+    }
+    async #notifyCodeReuse(event) {
+        if (!this.#onCodeReuse)
+            return;
+        try {
+            await this.#onCodeReuse(event);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] onCodeReuse hook failed:", error instanceof Error ? error.message : error);
+        }
     }
 }

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

@@ -1,5 +1,6 @@
 import type { ClientInterface } from "../../models/client.ts";
 import type { AuthenticationContext } from "../../models/authentication.ts";
+import type { AuthorizationCode } from "../../models/authorization-code.ts";
 import type { RefreshToken, Token } from "../../models/token.ts";
 import type { AbstractScope, BasicScope } from "../../models/scope.ts";
 import type { ClientServiceInterface } from "./client.ts";
@@ -156,16 +157,55 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      */
     rotate?(current: RefreshToken<Client, User, Scope>, next: RefreshToken<Client, User, Scope>): Promise<RefreshToken<Client, User, Scope> | undefined>;
     /**
-     * Revokes all tokens issued with the given authorization code.
-     * Returns true if any tokens were revoked (indicating code replay).
+     * Revokes all tokens issued with the given authorization code, called by the
+     * authorization code grant when a code is presented after it was claimed.
+     * Returns true if any tokens were revoked, which the grant reports as a code
+     * replay (RFC 6819 §4.4.1.1).
      *
-     * Per RFC 6819 Section 4.4.1.1, if an authorization code is used more
-     * than once, the authorization server MUST revoke all tokens previously
-     * issued based on that authorization code.
+     * `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.
+     *
+     * With {@linkcode exchangeCode}, make the two linearizable: a call that
+     * begins once `exchangeCode` has claimed the code must find and revoke the
+     * token it saved. Committing the claim and the insert together, as one
+     * database transaction does, meets this.
      *
      * @see https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.1.1
      */
-    revokeCode(code: string): Promise<boolean>;
+    revokeCode(code: string, client?: Client): Promise<boolean>;
+    /**
+     * Exchanges an authorization code in one atomic step: claims
+     * `authorizationCode` as `AuthorizationCodeServiceInterface.revoke`
+     * would, and persists `token`, the token issued from it, or does neither.
+     * Resolves the saved token, or `undefined` with nothing persisted when the
+     * code was already claimed or never stored. Concurrent calls for one code
+     * persist exactly one token. `token.code` is already set to the code.
+     *
+     * When implemented, the authorization code grant calls it instead of
+     * claiming the code through the authorization code service and saving the
+     * token with {@linkcode save}. Without it, the grant claims and saves in two
+     * calls, and a replay that arrives between them finds the code claimed but
+     * no token to revoke: the replay is refused, and the token the first
+     * exchange saves next stays live. With it, a replay finds the token
+     * {@linkcode revokeCode} can revoke.
+     *
+     * 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.
+     * `runCodeExchangeContractTests` checks it under concurrent callers, with
+     * the store's barrier wired between its claim and its insert.
+     */
+    exchangeCode?(authorizationCode: AuthorizationCode<Client, User, Scope>, token: Token<Client, User, Scope>): Promise<Token<Client, User, Scope> | undefined>;
     /**
      * Looks up a refresh token that has already been revoked/rotated out. The
      * refresh grant's reuse detection reads it, and so does the revocation
@@ -188,8 +228,8 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * given a token whose tombstone carries {@linkcode RefreshToken.rotatedAt}.
      * Returns true if anything was revoked.
      *
-     * `/revoke` ends the family without firing `onTokenReuse`, so any audit
-     * trail for that case has to come from this method.
+     * `/revoke` ends the family without firing `onTokenReuse`; it reports the
+     * revocation to `AuthorizationServerOptions.onRotatedOutRevocation` instead.
      *
      * Without {@linkcode rotate}, keep the family revoked: a successor that a
      * concurrent rotation saves after this call must be stored already revoked,
@@ -325,6 +365,8 @@ 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).
      */
-    abstract revokeCode(code: string): Promise<boolean>;
+    abstract revokeCode(code: string, client?: Client): Promise<boolean>;
 }

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

@@ -0,0 +1,100 @@
+/**
+ * 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 type { ClientInterface } from "../../models/client.ts";
+import type { AbstractScope, BasicScope } from "../../models/scope.ts";
+import type { AuthorizationCodeServiceInterface } from "../../server/services/authorization-code.ts";
+import type { ClientServiceInterface } from "../../server/services/client.ts";
+import type { TokenServiceInterface } from "../../server/services/token.ts";
+import type { UserServiceInterface } from "../../server/services/user.ts";
+import type { MemoryUserShape } from "../services.ts";
+/**
+ * The point inside a store's {@linkcode TokenServiceInterface.exchangeCode}
+ * at which {@link runCodeExchangeContractTests} holds an exchange. Wire it
+ * into a test build of the store.
+ */
+export interface CodeExchangeBarriers {
+    /**
+     * Await this inside `exchangeCode` after claiming the code and before
+     * persisting the token, still inside the atomic step: within the
+     * transaction and holding the code's lock. When it rejects, fail the
+     * exchange as a failed insert would: leave the code claimable, persist
+     * nothing, and reject or resolve `undefined`.
+     */
+    afterClaim(): Promise<void>;
+}
+/** Services built for each case of {@link runCodeExchangeContractTests}. */
+export interface CodeExchangeContractServices<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /** The user service both stores hydrate users from. */
+    userService: UserServiceInterface<U>;
+    /** The client service both stores hydrate clients from. */
+    clientService: ClientServiceInterface<C, U>;
+    /** The code store `exchangeCode` claims codes from. */
+    authorizationCodeService: AuthorizationCodeServiceInterface<C, U, S>;
+    /** The token service under test. It must implement `exchangeCode`. */
+    tokenService: TokenServiceInterface<C, U, S>;
+}
+/** Options for {@link runCodeExchangeContractTests}. */
+export interface CodeExchangeContractOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /**
+     * Returns fresh services for each case, with `exchangeCode` awaiting
+     * `barriers.afterClaim()` between its claim and its insert. A store that
+     * sets `exchangeAwaitsBarrier: false` ignores `barriers`.
+     */
+    makeServices(barriers: CodeExchangeBarriers): Promise<CodeExchangeContractServices<C, U, S>> | CodeExchangeContractServices<C, U, S>;
+    /** Persists a user with the given password into the user service under test. */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /** Persists a client into the client service under test. */
+    addClient(service: ClientServiceInterface<C, U>, client: C): Promise<void>;
+    /** Builds a distinct user fixture for the given sequence number. Defaults to a minimal `{ id, username }` shape. */
+    makeUser?(seq: number): U;
+    /** Builds a distinct client fixture for the given sequence number. Defaults to a client granting `authorization_code` and `refresh_token`. */
+    makeClient?(seq: number): C;
+    /**
+     * Whether `exchangeCode` awaits `barriers.afterClaim()`. Defaults to
+     * `true`: the suite holds an exchange between its claim and its insert
+     * while it runs a second exchange, a replay through the grant, or an
+     * exchange of another code, and fails the insert there. Set `false` only
+     * when `exchangeCode` never awaits between its claim and its insert, as in
+     * `MemoryTokenService`; the suite then runs those schedules as overlapping
+     * calls, which cannot reach a gap inside `exchangeCode`.
+     */
+    exchangeAwaitsBarrier?: boolean;
+    /**
+     * Milliseconds the suite lets a call run against a held exchange before it
+     * releases the exchange; a call that has not settled by then is taken to be
+     * waiting on it. Defaults to 100. Raise it for a store whose calls take
+     * longer to reach the lock they wait on.
+     */
+    blockedAfterMs?: number;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/**
+ * 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 declare function runCodeExchangeContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: CodeExchangeContractOptions<C, U, S>): void;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.34.0",
+  "version": "0.35.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",