@udibo/oauth2 0.24.0 → 0.26.0

package/dist/server/authorization-server.js

@@ -134,6 +134,11 @@ export const ENDPOINT_PATHS = Object.fromEntries(ENDPOINT_ENTRIES.map(([key, { p
  * ```
  */
 export const ENDPOINT_METHODS = Object.fromEntries(ENDPOINT_ENTRIES.map(([key, { methods }]) => [key, methods]));
+function authorizationResponseRedirect(target) {
+    if (target.issuer)
+        target.url.searchParams.set("iss", target.issuer);
+    return Response.redirect(target.url.toString(), 302);
+}
 function isAuthorizationCodeGrant(grant) {
     return grant instanceof AuthorizationCodeGrant;
 }
@@ -742,6 +747,11 @@ export class AuthorizationServer extends ResourceServer {
      * responses from this endpoint, since there is no verified place to send the
      * user back to.
      *
+     * Every redirect to the client, the code and the error alike, carries `iss`
+     * set to the request's resolved issuer (RFC 9207), replacing any `iss` the
+     * registered `redirect_uri` itself carries. A request that resolves no
+     * `issuer` sends none.
+     *
      * Requires a grant extending {@linkcode AuthorizationCodeGrant} registered
      * under `authorization_code`; without one the endpoint answers 500
      * `server_error` (or rethrows, with `throwOnError`).
@@ -757,16 +767,17 @@ export class AuthorizationServer extends ResourceServer {
             return await this.#authorize(request, target, authenticateUser, handleConsent);
         }
         catch (error) {
-            return this.#authorizeErrorResponse(error, target.url);
+            return this.#authorizeErrorResponse(error, target);
         }
     }
     async #authorize(request, target, authenticateUser, handleConsent) {
         const params = this.parseAuthorizeParameters(request);
         const grant = this.#authorizationCodeGrant();
-        const { services } = await this.authorizationContext(request);
+        const { services, issuer } = await this.authorizationContext(request);
         const client = await this.#resolveAuthorizeClient(grant, params.clientId, services);
         const redirectUrl = this.#resolveRedirectTarget(client, params.redirectUri);
         target.url = redirectUrl;
+        target.issuer = issuer;
         if (!params.state) {
             throw new InvalidRequestError("state required");
         }
@@ -807,9 +818,10 @@ export class AuthorizationServer extends ResourceServer {
             authenticationContext,
         }, request);
         redirectUrl.searchParams.set("code", authorizationCode.code);
-        return Response.redirect(redirectUrl.toString(), 302);
+        return authorizationResponseRedirect({ url: redirectUrl, issuer });
     }
-    #authorizeErrorResponse(error, redirectUrl) {
+    #authorizeErrorResponse(error, target) {
+        const redirectUrl = target.url;
         if (!redirectUrl || !(error instanceof Error) || !isOAuth2Error(error)) {
             return this.#handleEndpointError(error);
         }
@@ -824,7 +836,10 @@ export class AuthorizationServer extends ResourceServer {
         if (errorUri) {
             searchParams.set("error_uri", errorUri);
         }
-        return Response.redirect(redirectUrl.toString(), 302);
+        return authorizationResponseRedirect({
+            url: redirectUrl,
+            issuer: target.issuer,
+        });
     }
     #authorizationCodeGrant() {
         const grant = this.grants[AUTHORIZATION_CODE_GRANT_TYPE];
@@ -1136,7 +1151,9 @@ export class AuthorizationServer extends ResourceServer {
      * authorization code grant's own `challengeMethods`, so a server that
      * registers an extra method (or drops `S256`) advertises what it will
      * actually accept. It is omitted entirely when no authorization code grant
-     * is registered, since PKCE has nothing to apply to.
+     * is registered, since PKCE has nothing to apply to. The same condition
+     * governs `authorization_response_iss_parameter_supported: true`
+     * (RFC 9207 §3): the authorization endpoint's redirects carry `iss`.
      *
      * `token_endpoint_auth_methods_supported` always includes `none`, the
      * RFC 7591 method for a client with no secret. The token endpoint accepts it
@@ -1178,6 +1195,9 @@ export class AuthorizationServer extends ResourceServer {
             metadata.code_challenge_methods_supported = challengeMethods;
         }
         metadata.response_types_supported = hasAuthCodeGrant ? ["code"] : [];
+        if (hasAuthCodeGrant) {
+            metadata.authorization_response_iss_parameter_supported = true;
+        }
         const scopesSupported = context.scopesSupported ?? this.scopesSupported;
         if (scopesSupported) {
             metadata.scopes_supported = scopesSupported;

package/dist/server/grants/refresh-token.d.ts

@@ -86,10 +86,14 @@ export declare class RefreshTokenGrant<Client extends ClientInterface, User, S e
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements

package/dist/server/grants/refresh-token.js

@@ -32,10 +32,14 @@ export class RefreshTokenGrant extends AbstractGrant {
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements
@@ -122,6 +126,13 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (familyExpiresAt) {
             this.capAtFamilyExpiry(nextRefreshToken, familyExpiresAt);
         }
+        if (tokenService.rotate) {
+            const rotated = await tokenService.rotate(currentToken, nextRefreshToken);
+            if (!rotated) {
+                throw new InvalidGrantError("refresh_token was already consumed");
+            }
+            return rotated;
+        }
         const claimed = tokenService.revokeRotated
             ? await tokenService.revokeRotated(currentToken)
             : await tokenService.revoke(currentToken);

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

@@ -129,6 +129,32 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * it, so a sign-out racing a refresh still ends the successor.
      */
     revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Rotates a refresh token in one atomic step: claims `current` and persists
+     * `next`, its successor in the same family, or does neither. Resolves the
+     * saved successor, or `undefined` with nothing persisted when `current` was
+     * already claimed or revoked, or its family has been revoked. Concurrent
+     * calls for one `current` produce exactly one successor.
+     *
+     * When implemented, the refresh grant calls it instead of
+     * {@linkcode revokeRotated} (or {@linkcode revoke}) followed by
+     * {@linkcode save}. Without it, the grant claims and saves in two calls,
+     * and a request that presents `current` between them finds it revoked with
+     * no live successor: reuse detection revokes the family and fires
+     * `onTokenReuse`, so a benign concurrent refresh signs the person out, and a
+     * store whose `revokeFamily` does not keep the family revoked leaves the
+     * successor live.
+     *
+     * Treat the claim as a rotation, never an end of grant: stamp the
+     * rotated-out record with {@linkcode RefreshToken.rotatedAt} exactly as
+     * {@linkcode revokeRotated} does, keep it findable through
+     * {@linkcode getRevokedRefreshToken}, and revoke its access token as
+     * `revokeRotated` would. Make it linearizable with
+     * {@linkcode revokeFamily}, as that method requires.
+     * `runTokenRotationContractTests` checks it under concurrent callers, with
+     * the store's barrier wired between its claim and its insert.
+     */
+    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).
@@ -164,9 +190,17 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * `/revoke` ends the family without firing `onTokenReuse`, so any audit
      * trail for that case has to come from this method.
      *
-     * Keep the family revoked: a successor that a concurrent rotation saves
-     * after this call must be stored already revoked, as
-     * `MemoryTokenService` does.
+     * Without {@linkcode rotate}, keep the family revoked: a successor that a
+     * concurrent rotation saves after this call must be stored already revoked,
+     * as `MemoryTokenService` does. A store that implements `rotate` meets this
+     * through the linearizability below, since the refresh grant then never
+     * saves a rotation's successor separately.
+     *
+     * With {@linkcode rotate}, make the two linearizable: once this resolves,
+     * the family has no live member and no later `rotate` of a member
+     * succeeds, and a `rotate` that committed before this began has its
+     * successor revoked. A store whose `rotate` can be paused between its claim
+     * and its insert meets this by taking one per-family lock in both methods.
      */
     revokeFamily?(familyId: string): Promise<boolean>;
     /**

package/dist/testing/contract/mod.d.ts

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * 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.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, type UserServiceContractOptions, } from "./user.ts";
 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 { 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

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * 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.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, } from "./user.js";
 export { runClientServiceContractTests, } from "./client.js";
 export { runTokenServiceContractTests, } from "./token.js";
+export { runTokenRotationContractTests, } from "./token-rotation.js";
 export { runTokenReaderContractTests, } from "./token-reader.js";
 export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
 export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";

package/dist/testing/contract/token-rotation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface.rotate} and its
+ * linearizability with {@link TokenServiceInterface.revokeFamily}.
+ *
+ * `runTokenServiceContractTests` checks what one caller sees. This suite
+ * checks what concurrent callers see: two rotations of one refresh token, a
+ * family revocation racing a rotation, a replay racing a refresh through the
+ * refresh grant, a rotation in an unrelated family, and a rotation whose
+ * insert fails. Each case asserts the store's end state, the live tokens of
+ * the family, not only the value each call resolved.
+ *
+ * The store under test awaits {@link TokenRotationBarriers.afterClaim} inside
+ * `rotate`, between its claim and its insert, so the suite can hold a rotation
+ * there and race the other call against it; a store that never reaches the
+ * barrier fails every held case. Only a store whose `rotate` never awaits
+ * between its claim and its insert, such as `MemoryTokenService`, opts out with
+ * `rotateAwaitsBarrier: 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 { 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.rotate} at which
+ * {@link runTokenRotationContractTests} holds a rotation. Wire it into a test
+ * build of the store.
+ */
+export interface TokenRotationBarriers {
+    /**
+     * Await this inside `rotate` after claiming `current` and before persisting
+     * `next`, still inside the atomic step: within the transaction and holding
+     * the family's lock. When it rejects, fail the rotation as a failed insert
+     * would: leave `current` live, persist nothing, and reject or resolve
+     * `undefined`.
+     */
+    afterClaim(): Promise<void>;
+}
+/** Services built for each case of {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractServices<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /** The user service the token service hydrates users from. */
+    userService: UserServiceInterface<U>;
+    /** The client service the token service hydrates clients from. */
+    clientService: ClientServiceInterface<C, U>;
+    /** The token service under test. It must implement `rotate`. */
+    tokenService: TokenServiceInterface<C, U, S>;
+}
+/** Options for {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /**
+     * Returns fresh services for each case, with `rotate` awaiting
+     * `barriers.afterClaim()` between its claim and its insert. A store that
+     * sets `rotateAwaitsBarrier: false` ignores `barriers`.
+     */
+    makeServices(barriers: TokenRotationBarriers): Promise<TokenRotationContractServices<C, U, S>> | TokenRotationContractServices<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 `rotate` awaits `barriers.afterClaim()`. Defaults to `true`: the
+     * suite holds a rotation between its claim and its insert while it runs a
+     * family revocation, a second rotation, a replayed refresh, or a rotation in
+     * another family, and fails the insert there. Set `false` only when
+     * `rotate` 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 `rotate`.
+     */
+    rotateAwaitsBarrier?: boolean;
+    /**
+     * Milliseconds the suite lets a call run against a held rotation before it
+     * releases the rotation; 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 rotation contract suite: concurrent schedules of
+ * {@linkcode TokenServiceInterface.rotate} against itself, against
+ * {@linkcode TokenServiceInterface.revokeFamily}, and through the refresh
+ * grant. The service must implement `rotate`, `revokeFamily` and
+ * `getRevokedRefreshToken`.
+ */
+export declare function runTokenRotationContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: TokenRotationContractOptions<C, U, S>): void;