@udibo/oauth2 0.33.0 → 0.35.0

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;