@udibo/oauth2 0.34.0 → 0.36.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,62 @@ 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.
+     * 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.
+     *
+     * 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 +235,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 +372,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;