@udibo/oauth2 0.31.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.31.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",