@udibo/oauth2 0.31.0 → 0.32.1

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/react/_logout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Not part of the public API. Lets `useOAuth2().logout()` tell
+ * `<RequireAuth>` that a sign-out is under way, so the `logged_out` event the
+ * client emits before the browser leaves does not start a login over the
+ * logout navigation.
+ *
+ * @module
+ */
+import { type Context } from "react";
+/** The provider's view of `useOAuth2().logout()` calls. */
+export interface LogoutTracker {
+    /**
+     * True from the start of a logout until it settles without navigating. A
+     * logout that navigates away stays in flight until the page is restored
+     * from the back-forward cache.
+     */
+    inFlight: boolean;
+    /** Marks a logout as started. Call before `client.logout()`. */
+    start(): void;
+    /** Marks a started logout as finished without leaving the page. */
+    settle(): void;
+}
+/** Supplied by `<OAuth2Provider>`; `null` under any other provider. */
+export declare const LogoutTrackerContext: Context<LogoutTracker | null>;

package/dist/react/_logout.js

@@ -0,0 +1,11 @@
+/**
+ * Not part of the public API. Lets `useOAuth2().logout()` tell
+ * `<RequireAuth>` that a sign-out is under way, so the `logged_out` event the
+ * client emits before the browser leaves does not start a login over the
+ * logout navigation.
+ *
+ * @module
+ */
+import { createContext } from "react";
+/** Supplied by `<OAuth2Provider>`; `null` under any other provider. */
+export const LogoutTrackerContext = createContext(null);

package/dist/react/provider.d.ts

@@ -32,7 +32,12 @@ export interface OAuth2ProviderProps {
  * state via `useOAuth2()`.
  *
  * While authenticated it renews the session on a timer shortly before the
- * access token expires, re-arming after each renew. Renewal is per tab and
+ * access token expires (at least 5 seconds apart), re-arming after each
+ * renew. A renew that fails, or reports no later expiry than the one before,
+ * as a `BffClient` session does (`sessionExpiresIn: 0`) until a proxied call
+ * refreshes the token, backs off instead: the wait doubles after each one, up
+ * to one renew every 5 minutes. A renew or client event that reports a later
+ * expiry returns it to the pre-expiry schedule. Renewal is per tab and
  * uncoordinated: a `DirectClient` given a refresh-token storage shared across
  * tabs (e.g. `IndexedDBRefreshTokenStorage`) against a server that
  * rotates refresh tokens can still have two tabs redeem the same token, which

package/dist/react/provider.js

@@ -6,8 +6,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * @module
  */
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { toOAuth2Error } from "../errors.js";
+import { LogoutTrackerContext } from "./_logout.js";
 import { OAuth2Context, } from "./context.js";
 const DEFAULT_STATE = {
     isAuthenticated: false,
@@ -19,10 +20,25 @@ const DEFAULT_STATE = {
 };
 const RENEW_SKEW_SECONDS = 30;
 const MIN_RENEW_MS = 5_000;
+const MAX_RENEW_BACKOFF_MS = 300_000;
 const RENEW_JITTER = 0.1;
 const isBrowser = () => typeof window !== "undefined";
-function renewDelayMs(expiresIn) {
-    const base = Math.max(MIN_RENEW_MS, (expiresIn - RENEW_SKEW_SECONDS) * 1000);
+const EXPIRY_ROUNDING_MS = 1_000;
+function reportExpiry(expiresIn) {
+    return expiresIn == null ? null : { expiresIn, at: Date.now() };
+}
+function isLaterExpiry(next, prev) {
+    if (next == null || next.expiresIn <= 0)
+        return false;
+    if (prev == null)
+        return true;
+    return (next.at + next.expiresIn * 1000 >
+        prev.at + prev.expiresIn * 1000 + EXPIRY_ROUNDING_MS);
+}
+function renewDelayMs(expiresIn, staleRenewals) {
+    const base = staleRenewals === 0
+        ? Math.max(MIN_RENEW_MS, (expiresIn - RENEW_SKEW_SECONDS) * 1000)
+        : Math.min(MAX_RENEW_BACKOFF_MS, MIN_RENEW_MS * 2 ** staleRenewals);
     return base * (1 - RENEW_JITTER * Math.random());
 }
 function expiresInFrom(tokens) {
@@ -35,7 +51,12 @@ function expiresInFrom(tokens) {
  * state via `useOAuth2()`.
  *
  * While authenticated it renews the session on a timer shortly before the
- * access token expires, re-arming after each renew. Renewal is per tab and
+ * access token expires (at least 5 seconds apart), re-arming after each
+ * renew. A renew that fails, or reports no later expiry than the one before,
+ * as a `BffClient` session does (`sessionExpiresIn: 0`) until a proxied call
+ * refreshes the token, backs off instead: the wait doubles after each one, up
+ * to one renew every 5 minutes. A renew or client event that reports a later
+ * expiry returns it to the pre-expiry schedule. Renewal is per tab and
  * uncoordinated: a `DirectClient` given a refresh-token storage shared across
  * tabs (e.g. `IndexedDBRefreshTokenStorage`) against a server that
  * rotates refresh tokens can still have two tabs redeem the same token, which
@@ -49,6 +70,9 @@ export function OAuth2Provider(props) {
         ...initialState,
     }));
     const [renewCount, setRenewCount] = useState(0);
+    const staleRenewals = useRef(0);
+    const reportedExpiry = useRef(null);
+    const [logoutsInFlight, setLogoutsInFlight] = useState(0);
     useEffect(() => {
         let cancelled = false;
         const handle = (event) => {
@@ -114,23 +138,40 @@ export function OAuth2Provider(props) {
     useEffect(() => {
         if (!isBrowser())
             return;
-        if (!state.isAuthenticated)
+        if (!state.isAuthenticated) {
+            staleRenewals.current = 0;
+            reportedExpiry.current = null;
             return;
+        }
         const expiresIn = state.sessionExpiresIn;
         if (expiresIn == null || !Number.isFinite(expiresIn) || expiresIn < 0) {
             return;
         }
+        if (reportedExpiry.current?.expiresIn !== expiresIn) {
+            const reported = reportExpiry(expiresIn);
+            if (isLaterExpiry(reported, reportedExpiry.current)) {
+                staleRenewals.current = 0;
+            }
+            reportedExpiry.current = reported;
+        }
         let cancelled = false;
-        const delayMs = renewDelayMs(expiresIn);
+        const delayMs = renewDelayMs(expiresIn, staleRenewals.current);
         const timer = setTimeout(() => {
             client.renewSession().then((session) => {
                 if (cancelled)
                     return;
+                const reported = reportExpiry(session.sessionExpiresIn);
+                staleRenewals.current = isLaterExpiry(reported, reportedExpiry.current)
+                    ? 0
+                    : staleRenewals.current + 1;
+                reportedExpiry.current = reported;
                 setState((prev) => ({ ...prev, ...session }));
                 setRenewCount((count) => count + 1);
             }, () => {
-                if (!cancelled)
-                    setRenewCount((count) => count + 1);
+                if (cancelled)
+                    return;
+                staleRenewals.current += 1;
+                setRenewCount((count) => count + 1);
             });
         }, delayMs);
         return () => {
@@ -138,11 +179,28 @@ export function OAuth2Provider(props) {
             clearTimeout(timer);
         };
     }, [client, state.isAuthenticated, state.sessionExpiresIn, renewCount]);
+    useEffect(() => {
+        if (!isBrowser())
+            return;
+        const onPageShow = (event) => {
+            if (event.persisted)
+                setLogoutsInFlight(0);
+        };
+        window.addEventListener("pageshow", onPageShow);
+        return () => window.removeEventListener("pageshow", onPageShow);
+    }, []);
     const value = useMemo(() => ({
         client,
         ...state,
     }), [client, state]);
-    return (_jsx(OAuth2Context.Provider, { value: value, children: children }));
+    const startLogout = useCallback(() => setLogoutsInFlight((count) => count + 1), []);
+    const settleLogout = useCallback(() => setLogoutsInFlight((count) => Math.max(0, count - 1)), []);
+    const logoutTracker = useMemo(() => ({
+        inFlight: logoutsInFlight > 0,
+        start: startLogout,
+        settle: settleLogout,
+    }), [logoutsInFlight, startLogout, settleLogout]);
+    return (_jsx(OAuth2Context.Provider, { value: value, children: _jsx(LogoutTrackerContext.Provider, { value: logoutTracker, children: children }) }));
 }
 function reduce(prev, event) {
     switch (event.type) {

package/dist/react/require-auth.d.ts

@@ -5,6 +5,12 @@
  * `returnTo` set to the current path, and renders a configurable
  * `fallback` while the redirect is in flight.
  *
+ * It starts no login while a `logout()` from {@link useOAuth2} is running or
+ * navigating away, so signing out from a protected page ends at the logout
+ * destination rather than the login page. A logout that returns no URL (a
+ * `DirectClient` whose server has no end-session endpoint) leaves the page
+ * signed out, and the gate then starts a login as usual.
+ *
  * @module
  */
 import { type ReactNode } from "react";
@@ -23,6 +29,9 @@ export interface RequireAuthProps {
 /**
  * Render `children` only when authenticated. Otherwise call
  * `login({ returnTo })` once and render `fallback` while the redirect
- * is in flight.
+ * is in flight. While a `useOAuth2().logout()` is running or navigating away,
+ * no new login starts; what renders still follows `isLoading` and
+ * `isAuthenticated`, so the page shows `fallback` once the logout has signed
+ * it out.
  */
 export declare function RequireAuth(props: RequireAuthProps): ReactNode;

package/dist/react/require-auth.js

@@ -5,27 +5,38 @@
  * `returnTo` set to the current path, and renders a configurable
  * `fallback` while the redirect is in flight.
  *
+ * It starts no login while a `logout()` from {@link useOAuth2} is running or
+ * navigating away, so signing out from a protected page ends at the logout
+ * destination rather than the login page. A logout that returns no URL (a
+ * `DirectClient` whose server has no end-session endpoint) leaves the page
+ * signed out, and the gate then starts a login as usual.
+ *
  * @module
  */
-import { useEffect } from "react";
+import { useContext, useEffect } from "react";
+import { LogoutTrackerContext } from "./_logout.js";
 import { useOAuth2 } from "./use-oauth2.js";
 const isBrowser = () => typeof window !== "undefined";
 /**
  * Render `children` only when authenticated. Otherwise call
  * `login({ returnTo })` once and render `fallback` while the redirect
- * is in flight.
+ * is in flight. While a `useOAuth2().logout()` is running or navigating away,
+ * no new login starts; what renders still follows `isLoading` and
+ * `isAuthenticated`, so the page shows `fallback` once the logout has signed
+ * it out.
  */
 export function RequireAuth(props) {
     const { children, fallback = null, returnTo } = props;
     const { isAuthenticated, isLoading, login } = useOAuth2();
+    const logoutInFlight = useContext(LogoutTrackerContext)?.inFlight ?? false;
     useEffect(() => {
-        if (isLoading || isAuthenticated)
+        if (isLoading || isAuthenticated || logoutInFlight)
             return;
         if (!isBrowser())
             return;
         const target = returnTo ?? `${window.location.pathname}${window.location.search}`;
         login({ returnTo: target }).catch(() => { });
-    }, [isLoading, isAuthenticated, login, returnTo]);
+    }, [isLoading, isAuthenticated, logoutInFlight, login, returnTo]);
     if (isLoading || !isAuthenticated)
         return fallback;
     return children;

package/dist/react/use-oauth2.d.ts

@@ -42,6 +42,11 @@ export interface UseOAuth2Result {
      * navigates to the returned URL if the flow needs a redirect (the BFF
      * logout endpoint, or the IDP end-session URL). Returns `{ url }` for
      * SSR callers.
+     *
+     * Under an `<OAuth2Provider>`, a mounted {@link RequireAuth} starts no
+     * login while this runs or navigates, so signing out from a protected page
+     * ends at the logout destination. Calling `client.logout()` directly skips
+     * that guard.
      */
     logout(opts?: LogoutOptions): Promise<{
         url?: string;

package/dist/react/use-oauth2.js

@@ -7,6 +7,7 @@
  */
 import { useCallback, useContext } from "react";
 import { BffClient, DirectClient, } from "../client/mod.js";
+import { LogoutTrackerContext } from "./_logout.js";
 import { OAuth2Context } from "./context.js";
 function useOAuth2Context() {
     const context = useContext(OAuth2Context);
@@ -46,13 +47,27 @@ export function useOAuth2() {
         }
         return result;
     }, [client]);
+    const logoutTracker = useContext(LogoutTrackerContext);
+    const startLogout = logoutTracker?.start;
+    const settleLogout = logoutTracker?.settle;
     const logout = useCallback(async (opts) => {
-        const result = await client.logout(opts);
+        startLogout?.();
+        let result;
+        try {
+            result = await client.logout(opts);
+        }
+        catch (error) {
+            settleLogout?.();
+            throw error;
+        }
         if (result.url && typeof window !== "undefined") {
             window.location.assign(result.url);
         }
+        else {
+            settleLogout?.();
+        }
         return result;
-    }, [client]);
+    }, [client, startLogout, settleLogout]);
     const boundFetch = useCallback((input, init) => client.fetch(input, init), [client]);
     return {
         isAuthenticated: context.isAuthenticated,

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.1",
   "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",