@udibo/oauth2 0.33.0 → 0.35.0

package/dist/adapters/hono/bff/_cookie-keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The AES-256-GCM keys the BFF's encrypted-cookie stores seal under.
+ *
+ * @module
+ */
+/** HKDF `info` label for `EncryptedCookieSessionStore`'s key. */
+export declare const SESSION_COOKIE_KEY_INFO = "udibo:oauth2:bff:session-cookie:v1";
+/** HKDF `info` label for `EncryptedCookieAuthRequestStorage`'s key. */
+export declare const AUTH_REQUEST_COOKIE_KEY_INFO = "udibo:oauth2:bff:auth-request-cookie:v1";
+/**
+ * Derives a cookie store's key from its configured secret with HKDF-SHA-256
+ * under the store's own `info` label, so one secret given to two stores yields
+ * independent keys.
+ *
+ * @throws {Error} When the secret is shorter than 16 bytes.
+ */
+export declare function deriveCookieKey(secret: string | Uint8Array, info: string): Promise<CryptoKey>;

package/dist/adapters/hono/bff/_cookie-keys.js

@@ -0,0 +1,25 @@
+/**
+ * The AES-256-GCM keys the BFF's encrypted-cookie stores seal under.
+ *
+ * @module
+ */
+import { deriveSealKey } from "../../../utils/crypto.js";
+/** HKDF `info` label for `EncryptedCookieSessionStore`'s key. */
+export const SESSION_COOKIE_KEY_INFO = "udibo:oauth2:bff:session-cookie:v1";
+/** HKDF `info` label for `EncryptedCookieAuthRequestStorage`'s key. */
+export const AUTH_REQUEST_COOKIE_KEY_INFO = "udibo:oauth2:bff:auth-request-cookie:v1";
+const MIN_SECRET_BYTES = 16;
+/**
+ * Derives a cookie store's key from its configured secret with HKDF-SHA-256
+ * under the store's own `info` label, so one secret given to two stores yields
+ * independent keys.
+ *
+ * @throws {Error} When the secret is shorter than 16 bytes.
+ */
+export async function deriveCookieKey(secret, info) {
+    const bytes = typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+    if (bytes.byteLength < MIN_SECRET_BYTES) {
+        throw new Error("secret must be at least 16 bytes; 32+ bytes of entropy is recommended.");
+    }
+    return await deriveSealKey(bytes, info);
+}

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

@@ -11,10 +11,10 @@
  * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
- * cookie instead (AES-GCM under a server-held secret, the same construction
- * {@link EncryptedCookieSessionStore} uses), so no server-side storage is
- * involved and any instance can complete the flow. Apps that already have a
- * database can implement {@link AuthRequestStorage} against it instead.
+ * cookie instead (AES-GCM under a key derived from a server-held secret), so no
+ * server-side storage is involved and any instance can complete the flow. Apps
+ * that already have a database can implement {@link AuthRequestStorage} against
+ * it instead.
  *
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
@@ -84,6 +84,13 @@ export interface EncryptedCookieAuthRequestStorageOptions {
     /**
      * Secret the AES-256 key is derived from; at least 32 bytes. Reuse the
      * secret across instances so any of them can unseal a cookie another sealed.
+     *
+     * Give each store instance and each app a secret of its own. Nothing in a
+     * sealed cookie binds it to the app or store instance that sealed it, so two
+     * apps that share a secret can open each other's pending sign-ins. Sharing
+     * one with {@link EncryptedCookieSessionStore} does not let either store open
+     * the other's cookies: each derives its key with HKDF-SHA-256 under its own
+     * label.
      */
     secret: string;
     /** Cookie attribute overrides. */
@@ -132,14 +139,21 @@ 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
  * const bff = new HonoBff({
  *   client,
- *   sessionStore: new EncryptedCookieSessionStore({ secret }),
- *   authRequestStorage: new EncryptedCookieAuthRequestStorage({ secret }),
+ *   sessionStore: new EncryptedCookieSessionStore({
+ *     secret: process.env.SESSION_SECRET!,
+ *   }),
+ *   authRequestStorage: new EncryptedCookieAuthRequestStorage({
+ *     secret: process.env.AUTH_REQUEST_SECRET!,
+ *   }),
  * });
  * ```
  */
@@ -171,7 +185,7 @@ export declare class EncryptedCookieAuthRequestStorage implements AuthRequestSto
  * import { encryptedCookieAuthRequestStorage } from "@udibo/oauth2/hono/bff";
  *
  * const authRequestStorage = encryptedCookieAuthRequestStorage({
- *   secret: process.env.SESSION_SECRET!,
+ *   secret: process.env.AUTH_REQUEST_SECRET!,
  * });
  * ```
  */

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

@@ -11,10 +11,10 @@
  * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
- * cookie instead (AES-GCM under a server-held secret, the same construction
- * {@link EncryptedCookieSessionStore} uses), so no server-side storage is
- * involved and any instance can complete the flow. Apps that already have a
- * database can implement {@link AuthRequestStorage} against it instead.
+ * cookie instead (AES-GCM under a key derived from a server-held secret), so no
+ * server-side storage is involved and any instance can complete the flow. Apps
+ * that already have a database can implement {@link AuthRequestStorage} against
+ * it instead.
  *
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
@@ -29,13 +29,17 @@
  */
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { MemoryAuthRequestStorage, } from "../../../client/mod.js";
-import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+import { sealJson, unsealJson } from "../../../utils/crypto.js";
+import { AUTH_REQUEST_COOKIE_KEY_INFO, deriveCookieKey, } from "./_cookie-keys.js";
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 const BASE_NAME = "oauth2_auth_request";
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_PENDING = 3;
 // RFC 6265 §6.1 only guarantees 4096 bytes per cookie, attributes included.
 const MAX_COOKIE_NAME_VALUE_BYTES = 3900;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function cookieAttributes(options, maxAgeSeconds) {
     const { secure, path, domain } = resolvePrefixConstrainedAttributes(options);
     return {
@@ -59,14 +63,21 @@ 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
  * const bff = new HonoBff({
  *   client,
- *   sessionStore: new EncryptedCookieSessionStore({ secret }),
- *   authRequestStorage: new EncryptedCookieAuthRequestStorage({ secret }),
+ *   sessionStore: new EncryptedCookieSessionStore({
+ *     secret: process.env.SESSION_SECRET!,
+ *   }),
+ *   authRequestStorage: new EncryptedCookieAuthRequestStorage({
+ *     secret: process.env.AUTH_REQUEST_SECRET!,
+ *   }),
  * });
  * ```
  */
@@ -107,17 +118,19 @@ export class EncryptedCookieAuthRequestStorage {
         }
     }
     #key() {
-        return (this.#keyPromise ??= deriveAesKey(this.#secret));
+        return (this.#keyPromise ??= deriveCookieKey(this.#secret, AUTH_REQUEST_COOKIE_KEY_INFO));
     }
     async #read(c) {
         const cookieValue = getCookie(c, this.#name);
         if (!cookieValue)
             return {};
         const pending = await unsealJson(await this.#key(), cookieValue);
-        if (!pending)
+        if (!isObject(pending))
             return {};
         const cutoff = Date.now() - this.#ttlMs;
-        return Object.fromEntries(Object.entries(pending).filter(([, record]) => record.createdAt > cutoff));
+        return Object.fromEntries(Object.entries(pending).filter((entry) => isObject(entry[1]) &&
+            typeof entry[1].createdAt === "number" &&
+            entry[1].createdAt > cutoff));
     }
     async #write(c, pending, keep) {
         const entries = Object.entries(pending)
@@ -143,7 +156,10 @@ export class EncryptedCookieAuthRequestStorage {
     /** Returns the storage bound to `c`, for the duration of that request. */
     forRequest(c) {
         return {
-            get: async (state) => (await this.#read(c))[state] ?? null,
+            get: async (state) => {
+                const pending = await this.#read(c);
+                return Object.hasOwn(pending, state) ? pending[state] : null;
+            },
             set: async (state, value) => {
                 const pending = await this.#read(c);
                 pending[state] = value;
@@ -168,7 +184,7 @@ export class EncryptedCookieAuthRequestStorage {
  * import { encryptedCookieAuthRequestStorage } from "@udibo/oauth2/hono/bff";
  *
  * const authRequestStorage = encryptedCookieAuthRequestStorage({
- *   secret: process.env.SESSION_SECRET!,
+ *   secret: process.env.AUTH_REQUEST_SECRET!,
  * });
  * ```
  */

package/dist/adapters/hono/bff/session-store.d.ts

@@ -283,6 +283,13 @@ export interface EncryptedCookieSessionStoreOptions {
      * Server-held secret(s) used to derive the AES-256 key(s). Each must have at
      * least 32 bytes of entropy; pass a base64 / hex string or raw bytes.
      *
+     * Give each store instance and each app a secret of its own. Nothing in a
+     * sealed cookie binds it to the app or store instance that sealed it, so two
+     * apps that share a secret can open each other's session cookies. Sharing one
+     * with `EncryptedCookieAuthRequestStorage` does not let either store open the
+     * other's cookies: each derives its key with HKDF-SHA-256 under its own
+     * label.
+     *
      * Pass an **ordered list** to rotate the secret without signing everyone out:
      * the **first** entry is current — every cookie is sealed under it — and
      * `read` tries each entry in turn, so a cookie sealed under a still-listed
@@ -308,10 +315,6 @@ export interface EncryptedCookieSessionStoreOptions {
      * `update` re-seals with a fresh stamp, so this is an **inactivity** window
      * for a session the BFF keeps refreshing. Must be a positive number of
      * milliseconds.
-     *
-     * The store stamps each cookie with a seal time at `create`/`update`; a
-     * cookie without that stamp is aged from its `updatedAt` instead, so it is
-     * bounded too.
      */
     maxAgeMs?: number;
 }
@@ -322,6 +325,11 @@ export interface EncryptedCookieSessionStoreOptions {
  * Security notes:
  * - Each secret must have at least 256 bits of entropy. A weak secret defeats
  *   the confidentiality of the cookie.
+ * - The key is derived from the secret with HKDF-SHA-256 under a label of this
+ *   store's own, so a cookie sealed by another store under the same secret
+ *   does not open here.
+ * - `read` accepts only what `create` sealed: a cookie that is malformed,
+ *   foreign, or the wrong shape reads as `null`.
  * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
  *   (returns `null`).
  * - `destroy` is a no-op on the server — the cookie must be cleared in the
@@ -366,8 +374,8 @@ export declare class EncryptedCookieSessionStore implements SessionStore, Bounde
     create(data: SessionData): Promise<string>;
     /**
      * Decrypts the cookie value, trying each configured secret in turn. Returns
-     * `null` if it is tampered, malformed, sealed with an unknown secret, or
-     * sealed longer ago than
+     * `null` if it is tampered, malformed, sealed with an unknown secret or by
+     * another store, not in the shape `create` seals, or sealed longer ago than
      * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
      */
     read(cookieValue: string): Promise<SessionData | null>;

package/dist/adapters/hono/bff/session-store.js

@@ -24,7 +24,8 @@
  * @module
  */
 import { InvalidGrantError } from "../../../errors.js";
-import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+import { sealJson, unsealJson } from "../../../utils/crypto.js";
+import { deriveCookieKey, SESSION_COOKIE_KEY_INFO } from "./_cookie-keys.js";
 /** Whether a store implements the {@link BackchannelLogoutStore} capability. */
 export function supportsBackchannelLogout(store) {
     return (typeof store.destroyByLogout ===
@@ -233,6 +234,11 @@ function isSealedSession(value) {
  * Security notes:
  * - Each secret must have at least 256 bits of entropy. A weak secret defeats
  *   the confidentiality of the cookie.
+ * - The key is derived from the secret with HKDF-SHA-256 under a label of this
+ *   store's own, so a cookie sealed by another store under the same secret
+ *   does not open here.
+ * - `read` accepts only what `create` sealed: a cookie that is malformed,
+ *   foreign, or the wrong shape reads as `null`.
  * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
  *   (returns `null`).
  * - `destroy` is a no-op on the server — the cookie must be cleared in the
@@ -294,7 +300,7 @@ export class EncryptedCookieSessionStore {
         return this.#maxAgeMs;
     }
     #key(index) {
-        return (this.#keyPromises[index] ??= deriveAesKey(this.#secrets[index]));
+        return (this.#keyPromises[index] ??= deriveCookieKey(this.#secrets[index], SESSION_COOKIE_KEY_INFO));
     }
     /** Encrypts the session into the cookie value under the current secret; there is no server-side record. */
     async create(data) {
@@ -303,8 +309,8 @@ export class EncryptedCookieSessionStore {
     }
     /**
      * Decrypts the cookie value, trying each configured secret in turn. Returns
-     * `null` if it is tampered, malformed, sealed with an unknown secret, or
-     * sealed longer ago than
+     * `null` if it is tampered, malformed, sealed with an unknown secret or by
+     * another store, not in the shape `create` seals, or sealed longer ago than
      * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
      */
     async read(cookieValue) {
@@ -312,13 +318,9 @@ export class EncryptedCookieSessionStore {
             const unsealed = await unsealJson(await this.#key(index), cookieValue);
             if (unsealed === null)
                 continue;
-            if (isSealedSession(unsealed)) {
-                return this.#isExpired(unsealed.issuedAt) ? null : unsealed.data;
-            }
-            const legacy = unsealed;
-            return this.#isExpired(legacy.updatedAt ?? legacy.createdAt)
-                ? null
-                : legacy;
+            if (!isSealedSession(unsealed))
+                return null;
+            return this.#isExpired(unsealed.issuedAt) ? null : unsealed.data;
         }
         return null;
     }

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.