@udibo/oauth2 0.30.0 → 0.32.0

package/dist/adapters/hono/bff/bff.d.ts

@@ -526,7 +526,20 @@ export interface HonoBffOptions {
      * `auth_time` but no particular age. A token response without an ID token
      * is not checked, unless {@link HonoBffOptions.forwardedParams} names
      * `scope`: the browser could then leave out `openid` to skip the check, so
-     * a missing ID token fails with `login_required` too. A pinned `scope` is
+     * a missing ID token fails with `login_required` too.
+     *
+     * Both rules follow the sign-in, not the instance that finishes it.
+     * `/auth/login` records the `max_age` it sent, and whether it forwarded
+     * `scope`, on the pending authorization request
+     * ({@link AuthRequestRecord.maxAge}). `/auth/callback` checks against that
+     * record, so a login-only instance that pins `max_age` for a step-up route
+     * is enforced by a callback another instance serves. An instance that pins
+     * `max_age` does not check a sign-in that carried none. A record without
+     * the field, written by an earlier release or kept by an
+     * {@link HonoBffOptions.authRequestStorage} that drops fields it does not
+     * know, is checked against the callback instance's own options instead.
+     *
+     * A pinned `scope` is
      * accepted only when
      * {@link scope} is unset; setting both would leave which one applies
      * ambiguous. Either configuration supplies the scope the login flow records

package/dist/adapters/hono/bff/bff.js

@@ -168,6 +168,30 @@ function pinnedMaxAge(fixed) {
     }
     return strictest;
 }
+function recordingAuthenticationControls(storage, controls) {
+    return {
+        get: storage.get.bind(storage),
+        set: (state, value) => storage.set(state, { ...value, ...controls }),
+        delete: storage.delete.bind(storage),
+        clear: storage.clear.bind(storage),
+    };
+}
+function recordedAuthenticationControls(recorded) {
+    const { maxAge } = recorded;
+    const scopeForwarded = recorded.scopeForwarded !== false;
+    if (maxAge === null)
+        return { maxAge: undefined, scopeForwarded };
+    if (typeof maxAge === "number" &&
+        Number.isSafeInteger(maxAge) &&
+        maxAge >= 0) {
+        return { maxAge, scopeForwarded };
+    }
+    throw new CallbackRefusal({
+        error: "login_required",
+        error_description: "the pending authorization request recorded a max_age that is not a " +
+            "non-negative integer, so the ID token's auth_time could not be checked",
+    });
+}
 class CallbackRefusal extends Error {
     refusal;
     constructor(refusal) {
@@ -724,7 +748,10 @@ export class HonoBff {
                 prompt: requested.prompt,
                 extraParams: requested.extraParams,
                 redirectUri: this.#derivedRedirectUri(c, origin),
-                authRequestStorage: this.#authRequestStorage(c),
+                authRequestStorage: recordingAuthenticationControls(this.#authRequestStorage(c), {
+                    maxAge: this.#extraAuthorizeParams.maxAge ?? null,
+                    scopeForwarded: this.#extraAuthorizeParams.scopeForwarded,
+                }),
             });
             this.#writeLoginStateHashes(c, [
                 ...this.#loginStateHashes(c),
@@ -776,15 +803,18 @@ export class HonoBff {
             this.#writeLoginStateHashes(c, pendingStates.filter((_, index) => index !== matched));
             try {
                 const origin = this.#options.resolveOrigin?.(c);
-                const { tokens, refreshToken, returnTo, raw } = await this.#client.exchangeAuthorizationCode(code, state, {
+                const exchanged = await this.#client.exchangeAuthorizationCode(code, state, {
                     origin,
                     redirectUri: this.#derivedRedirectUri(c, origin),
                     authRequestStorage: this.#authRequestStorage(c),
                 });
+                const { tokens, refreshToken, returnTo, raw } = exchanged;
                 let user = null;
                 let sid;
                 const idToken = raw.id_token;
-                const { maxAge, scopeForwarded } = this.#extraAuthorizeParams;
+                const { maxAge, scopeForwarded } = exchanged.maxAge === undefined
+                    ? this.#extraAuthorizeParams
+                    : recordedAuthenticationControls(exchanged);
                 if (maxAge !== undefined && (idToken || scopeForwarded)) {
                     let claims;
                     try {

package/dist/client/direct-client.d.ts

@@ -210,6 +210,16 @@ export interface ExchangeResult {
     refreshToken?: string;
     /** `returnTo` recorded at authorize time, for the code exchange. */
     returnTo?: string;
+    /**
+     * {@link AuthRequestRecord.maxAge} as recorded at authorize time, for the
+     * code exchange. Absent when the record carries none.
+     */
+    maxAge?: number | null;
+    /**
+     * {@link AuthRequestRecord.scopeForwarded} as recorded at authorize time,
+     * for the code exchange. Absent when the record carries none.
+     */
+    scopeForwarded?: boolean;
     /** The raw token-endpoint response. */
     raw: TokenResponse;
 }

package/dist/client/direct-client.js

@@ -565,6 +565,10 @@ export class DirectClient extends OAuth2ClientBase {
             tokens: responseToBundle(raw),
             refreshToken: raw.refresh_token,
             returnTo: record.returnTo,
+            ...(record.maxAge === undefined ? {} : { maxAge: record.maxAge }),
+            ...(record.scopeForwarded === undefined
+                ? {}
+                : { scopeForwarded: record.scopeForwarded }),
             raw,
         };
     }

package/dist/client/storage.d.ts

@@ -64,6 +64,25 @@ export interface AuthRequestRecord {
     returnTo?: string;
     /** Scope requested for this authorization, space-delimited. */
     scope?: string;
+    /**
+     * The `max_age` the authorize request carried, in seconds, or `null` when
+     * it carried none. `HonoBff` records it at `/auth/login` and checks the ID
+     * token's `auth_time` against it at `/auth/callback`, whichever instance
+     * serves either one. Absent on a record from a release that did not record
+     * it; the callback then falls back to its own pinned `max_age`. A storage
+     * must return `null` as `null`, not as an absent field, and a number as a
+     * number: the callback refuses any other value with `login_required`.
+     */
+    maxAge?: number | null;
+    /**
+     * Whether the browser chose this request's `scope` (`HonoBff`'s
+     * `forwardedParams` names `scope`). When it did and {@link maxAge} is set,
+     * the callback refuses a token response without an ID token, because a
+     * scope without `openid` would otherwise skip the `auth_time` check.
+     * Recorded alongside {@link maxAge}; the callback reads any value other than
+     * `false` as `true`.
+     */
+    scopeForwarded?: boolean;
     /** When the request was created (epoch ms), used for TTL expiry. */
     createdAt: number;
 }

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

@@ -64,7 +64,13 @@ export interface RefreshTokenGrantOptions<Client extends ClientInterface, User,
      *
      * Needs a token service that sets {@linkcode RefreshToken.rotatedAt} in
      * `revokeRotated` and implements `hasLiveRefreshToken`; with any other
-     * service the grace never applies.
+     * service the grace never applies. The window is measured by the token
+     * service's `isWithinReplayGrace` when it implements one, on the store's
+     * clock, and otherwise by comparing `rotatedAt` with this process's clock.
+     * The store's answer is honored only while `rotatedAt` is no more than five
+     * minutes ahead of this process's clock and no more than the grace plus
+     * five minutes behind it, so a faulty store check cannot excuse replays
+     * indefinitely.
      */
     replayGraceSeconds?: number;
 }

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

@@ -5,6 +5,7 @@
  */
 import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, } from "../../errors.js";
 import { AbstractGrant, } from "./grant.js";
+const REPLAY_GRACE_CLOCK_TOLERANCE_SECONDS = 300;
 /**
  * The refresh token grant type.
  * https://datatracker.ietf.org/doc/html/rfc6749.html#section-6
@@ -16,7 +17,7 @@ export class RefreshTokenGrant extends AbstractGrant {
     /** The OAuth2 grant type: `refresh_token`. */
     grantType = "refresh_token";
     #onTokenReuse;
-    #replayGraceMs;
+    #replayGraceSeconds;
     /** Creates the grant from its {@linkcode RefreshTokenGrantOptions}. */
     constructor(options) {
         super({ ...options, allowRefreshToken: true });
@@ -25,7 +26,7 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (!Number.isFinite(graceSeconds) || graceSeconds < 0) {
             throw new RangeError(`replayGraceSeconds must be a non-negative number of seconds, got ${graceSeconds}`);
         }
-        this.#replayGraceMs = graceSeconds * 1000;
+        this.#replayGraceSeconds = graceSeconds;
     }
     /**
      * Handles a token request for the refresh token grant. Issues a new access
@@ -143,12 +144,23 @@ export class RefreshTokenGrant extends AbstractGrant {
     }
     async #withinReplayGrace(tokenService, replayed) {
         const { rotatedAt, familyId } = replayed;
-        if (this.#replayGraceMs === 0 || !rotatedAt || !familyId)
+        if (this.#replayGraceSeconds === 0 || !rotatedAt || !familyId) {
             return false;
-        if (Date.now() - rotatedAt.getTime() > this.#replayGraceMs)
+        }
+        const elapsedMs = Date.now() - rotatedAt.getTime();
+        const withinWindow = tokenService.isWithinReplayGrace
+            ? this.#withinClockTolerance(elapsedMs) &&
+                (await tokenService.isWithinReplayGrace(replayed, this.#replayGraceSeconds))
+            : elapsedMs <= this.#replayGraceSeconds * 1000;
+        if (!withinWindow)
             return false;
         return (await tokenService.hasLiveRefreshToken?.(familyId)) ?? false;
     }
+    #withinClockTolerance(elapsedMs) {
+        const toleranceMs = REPLAY_GRACE_CLOCK_TOLERANCE_SECONDS * 1000;
+        return (elapsedMs >= -toleranceMs &&
+            elapsedMs <= this.#replayGraceSeconds * 1000 + toleranceMs);
+    }
     async #notifyTokenReuse(event) {
         if (!this.#onTokenReuse)
             return;

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

@@ -175,9 +175,10 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * is silently disabled and `/revoke` cannot reach a successor.
      *
      * Return the tombstone unconditionally. Apply any replay grace through
-     * `RefreshTokenGrantOptions.replayGraceSeconds`, never by hiding recent
-     * tombstones here: a hidden tombstone also hides the family from a sign-out
-     * racing the refresh, which then leaves the successor live.
+     * `RefreshTokenGrantOptions.replayGraceSeconds`, judged on the store's clock
+     * by {@linkcode isWithinReplayGrace} when it needs one, never by hiding
+     * recent tombstones here: a hidden tombstone also hides the family from a
+     * sign-out racing the refresh, which then leaves the successor live.
      */
     getRevokedRefreshToken?(refreshToken: string): Promise<RefreshToken<Client, User, Scope> | undefined>;
     /**
@@ -209,6 +210,25 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * never applies and every replay is treated as reuse.
      */
     hasLiveRefreshToken?(familyId: string): Promise<boolean>;
+    /**
+     * Whether `tombstone`, a record {@linkcode getRevokedRefreshToken} just
+     * returned, was rotated out no more than `graceSeconds` ago, measured on the
+     * clock that stamped its rotation. Implement it when that clock is the
+     * store's own, such as a database's, so instances whose clocks drift
+     * apart agree on the refresh grant's `replayGraceSeconds` window. Without
+     * it, the grant compares {@linkcode RefreshToken.rotatedAt} with its own
+     * `Date.now()`.
+     *
+     * The grant calls it only when `replayGraceSeconds` is above zero and the
+     * tombstone carries `rotatedAt` and a `familyId`; `graceSeconds` may be
+     * fractional. The window still needs {@linkcode hasLiveRefreshToken}.
+     * The grant treats the replay as outside the window, whatever this
+     * resolves, once `rotatedAt` is more than five minutes ahead of the
+     * grant's clock or more than `graceSeconds` plus five minutes behind it.
+     * Implementing this never licenses hiding a tombstone from
+     * `getRevokedRefreshToken`.
+     */
+    isWithinReplayGrace?(tombstone: RefreshToken<Client, User, Scope>, graceSeconds: number): Promise<boolean>;
 }
 /** Options for configuring an abstract token service. */
 export interface AbstractTokenServiceOptions<Client extends ClientInterface, User> {

package/dist/testing/contract/auth-request-storage.d.ts

@@ -9,6 +9,11 @@
  * concurrent callers taking one record. This suite races eight of them on one
  * record.
  *
+ * Every field of a record must come back as it was stored, `maxAge: null`
+ * included: a store that keeps only the fields it knows makes `HonoBff` check
+ * a sign-in against the callback instance's options instead of the
+ * `max_age` the sign-in was started with.
+ *
  * @example Verify a Redis-backed store
  * ```ts
  * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";

package/dist/testing/contract/auth-request-storage.js

@@ -9,6 +9,11 @@
  * concurrent callers taking one record. This suite races eight of them on one
  * record.
  *
+ * Every field of a record must come back as it was stored, `maxAge: null`
+ * included: a store that keeps only the fields it knows makes `HonoBff` check
+ * a sign-in against the callback instance's options instead of the
+ * `max_age` the sign-in was started with.
+ *
  * @example Verify a Redis-backed store
  * ```ts
  * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
@@ -45,6 +50,8 @@ function record(overrides = {}) {
         codeVerifier: "verifier-1",
         returnTo: "/dashboard",
         scope: "openid profile",
+        maxAge: 300,
+        scopeForwarded: true,
         createdAt: Date.now(),
         ...overrides,
     };
@@ -75,6 +82,12 @@ export function runAuthRequestStorageContractTests(options) {
                 await store.set("state-1", stored);
                 expect(await store.get("state-1")).toStrictEqual(stored);
             });
+            it("returns a recorded maxAge of null as null, not as an absent field", async () => {
+                const stored = record({ maxAge: null, scopeForwarded: false });
+                await store.set("state-1", stored);
+                expect(await store.get("state-1"), "null records a sign-in that carried no max_age; an absent field " +
+                    "makes the callback fall back to its own pinned max_age").toStrictEqual(stored);
+            });
             it("keeps records under different states independent", async () => {
                 await store.set("state-1", record({ codeVerifier: "verifier-1" }));
                 await store.set("state-2", record({ codeVerifier: "verifier-2" }));

package/dist/testing/contract/token.js

@@ -17,6 +17,7 @@
  *
  * @module
  */
+import { setTimeout as delay } from "node:timers/promises";
 import { assert, beforeEach, describe, expect, it } from "vitest";
 import { BasicScope } from "../../models/scope.js";
 const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
@@ -368,6 +369,41 @@ export function runTokenServiceContractTests(options) {
                     expect(await tokenService.hasLiveRefreshToken(FAMILY), "an expired successor cannot be used, so a replay of its " +
                         "predecessor must not be excused as a straggler").toBe(false);
                 });
+                async function rotateOut(skip) {
+                    skip(typeof tokenService.isWithinReplayGrace !== "function", "the service does not implement isWithinReplayGrace");
+                    skip(typeof tokenService.rotate !== "function" &&
+                        typeof tokenService.revokeRotated !== "function", "the service implements neither rotate nor revokeRotated");
+                    const parent = await saveFamilyMember(FAMILY);
+                    const successor = await familyMember(FAMILY);
+                    if (tokenService.rotate) {
+                        assert(await tokenService.rotate(parent, successor));
+                    }
+                    else {
+                        assert(await tokenService.revokeRotated(parent));
+                        await tokenService.save(successor);
+                    }
+                    const tombstone = await tokenService.getRevokedRefreshToken(parent.refreshToken);
+                    assert(tombstone?.familyId === FAMILY && tombstone.rotatedAt, "a store that judges the replay grace must still return every " +
+                        "rotated-out tombstone, with its family and rotatedAt; hiding " +
+                        "one inside the window hides the family from a sign-out " +
+                        "racing the refresh, which then leaves the successor live");
+                    return { tombstone, successor };
+                }
+                it("returns the tombstone of a token inside its replay grace, so revoking it ends the successor", async ({ skip, }) => {
+                    const { tombstone, successor } = await rotateOut(skip);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 60), "a token rotated out a moment ago is inside a 60-second grace").toBe(true);
+                    expect(await tokenService.revokeFamily(tombstone.familyId)).toBe(true);
+                    expect(await tokenService.getRefreshToken(successor.refreshToken)).toBe(undefined);
+                });
+                it("judges a rotated-out token inside a one-second grace, then outside it once the second has passed", async ({ skip, }) => {
+                    const { tombstone } = await rotateOut(skip);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 1), "a token rotated out a moment ago is inside a one-second grace").toBe(true);
+                    await delay(1_200);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 1), "a grace that answers true regardless of elapsed time excuses " +
+                        "every replay while the family is live, which turns reuse " +
+                        "detection off").toBe(false);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 3600)).toBe(true);
+                });
             });
         }
         else {

package/dist/testing/services.d.ts

@@ -256,6 +256,13 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
     rotate(current: RefreshToken<C, U, S>, next: RefreshToken<C, U, S>): Promise<RefreshToken<C, U, S> | undefined>;
     /** Whether the family has a live refresh token that has not expired. */
     hasLiveRefreshToken(familyId: string): Promise<boolean>;
+    /**
+     * Whether the tombstone was rotated out no more than `graceSeconds` ago,
+     * judged from the rotation time this store recorded rather than the one on
+     * the record passed in. Resolves `false` for a token it holds no rotated-out
+     * tombstone for.
+     */
+    isWithinReplayGrace(tombstone: RefreshToken<C, U, S>, graceSeconds: number): Promise<boolean>;
     /**
      * Looks up a revoked/rotated-out refresh token for the refresh grant's
      * reuse detection: revoked refresh records are kept as tombstones instead

package/dist/testing/services.js

@@ -427,6 +427,18 @@ export class MemoryTokenService {
         }
         return Promise.resolve(false);
     }
+    /**
+     * Whether the tombstone was rotated out no more than `graceSeconds` ago,
+     * judged from the rotation time this store recorded rather than the one on
+     * the record passed in. Resolves `false` for a token it holds no rotated-out
+     * tombstone for.
+     */
+    async isWithinReplayGrace(tombstone, graceSeconds) {
+        const rotatedAt = this.#revokedByRefreshHash.get(await sha256Hash(tombstone.refreshToken))?.rotatedAt;
+        if (!rotatedAt)
+            return false;
+        return Date.now() - rotatedAt.getTime() <= graceSeconds * 1000;
+    }
     #tombstone(refreshTokenHash, stored) {
         this.#revokedByRefreshHash.set(refreshTokenHash, stored);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "keywords": [
     "authorization-server",