@udibo/oauth2 0.15.2 → 0.16.0

package/dist/adapters/hono/bff/auth-request-store.d.ts

@@ -96,7 +96,11 @@ export interface EncryptedCookieAuthRequestStorageOptions {
     /**
      * How many pending requests the cookie carries at once. A second sign-in
      * started in another tab would otherwise evict the first, so its callback
-     * would fail. Defaults to 3; the oldest is dropped beyond that.
+     * would fail. Defaults to 3; the oldest is dropped beyond that, and also
+     * whenever keeping it would push the sealed cookie past what every browser
+     * stores (about 4 KB), since a browser silently drops an oversized cookie
+     * and every pending sign-in in it with it. The sign-in being started is
+     * never the one dropped. Must be a positive integer.
      */
     maxPending?: number;
 }
@@ -146,6 +150,9 @@ export declare class EncryptedCookieAuthRequestStorage implements AuthRequestSto
      * carries a `__Host-`/`__Secure-` prefix the other cookie options contradict,
      * or when {@link AuthRequestCookieOptions.sameSite} is `"None"` without
      * {@link AuthRequestCookieOptions.secure}.
+     * @throws {RangeError} When
+     * {@link EncryptedCookieAuthRequestStorageOptions.maxPending} is not a
+     * positive integer.
      */
     constructor(options: EncryptedCookieAuthRequestStorageOptions);
     /** Returns the storage bound to `c`, for the duration of that request. */

package/dist/adapters/hono/bff/auth-request-store.js

@@ -32,6 +32,8 @@ import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie
 const BASE_NAME = "oauth2_auth_request";
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_PENDING = 3;
+// RFC 6265 §6.1 only guarantees 4096 bytes per cookie, attributes included.
+const MAX_COOKIE_NAME_VALUE_BYTES = 3900;
 function cookieAttributes(options, maxAgeSeconds) {
     const { secure, path, domain } = resolvePrefixConstrainedAttributes(options);
     return {
@@ -81,6 +83,9 @@ export class EncryptedCookieAuthRequestStorage {
      * carries a `__Host-`/`__Secure-` prefix the other cookie options contradict,
      * or when {@link AuthRequestCookieOptions.sameSite} is `"None"` without
      * {@link AuthRequestCookieOptions.secure}.
+     * @throws {RangeError} When
+     * {@link EncryptedCookieAuthRequestStorageOptions.maxPending} is not a
+     * positive integer.
      */
     constructor(options) {
         this.#cookie = options.cookie;
@@ -94,6 +99,10 @@ export class EncryptedCookieAuthRequestStorage {
         });
         this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
         this.#maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+        if (!(Number.isInteger(this.#maxPending) && this.#maxPending > 0)) {
+            throw new RangeError("EncryptedCookieAuthRequestStorage maxPending must be a positive " +
+                `integer, got ${this.#maxPending}.`);
+        }
     }
     #key() {
         return (this.#keyPromise ??= deriveAesKey(this.#secret));
@@ -108,15 +117,23 @@ export class EncryptedCookieAuthRequestStorage {
         const cutoff = Date.now() - this.#ttlMs;
         return Object.fromEntries(Object.entries(pending).filter(([, record]) => record.createdAt > cutoff));
     }
-    async #write(c, pending) {
+    async #write(c, pending, keep) {
         const entries = Object.entries(pending)
-            .sort(([, a], [, b]) => b.createdAt - a.createdAt)
+            .sort(([stateA, a], [stateB, b]) => Number(stateB === keep) - Number(stateA === keep) ||
+            b.createdAt - a.createdAt)
             .slice(0, this.#maxPending);
         if (entries.length === 0) {
             this.#clear(c);
             return;
         }
-        setCookie(c, this.#name, await sealJson(await this.#key(), Object.fromEntries(entries)), cookieAttributes(this.#cookie, Math.ceil(this.#ttlMs / 1000)));
+        const key = await this.#key();
+        let sealed = await sealJson(key, Object.fromEntries(entries));
+        while (entries.length > 1 &&
+            this.#name.length + 1 + sealed.length > MAX_COOKIE_NAME_VALUE_BYTES) {
+            entries.pop();
+            sealed = await sealJson(key, Object.fromEntries(entries));
+        }
+        setCookie(c, this.#name, sealed, cookieAttributes(this.#cookie, Math.ceil(this.#ttlMs / 1000)));
     }
     #clear(c) {
         deleteCookie(c, this.#name, cookieAttributes(this.#cookie));
@@ -128,7 +145,7 @@ export class EncryptedCookieAuthRequestStorage {
             set: async (state, value) => {
                 const pending = await this.#read(c);
                 pending[state] = value;
-                await this.#write(c, pending);
+                await this.#write(c, pending, state);
             },
             delete: async (state) => {
                 const pending = await this.#read(c);

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

@@ -162,6 +162,9 @@ export interface HonoBffCookieOptions {
  * header, so it is guarded instead by a same-origin check that reads
  * `Sec-Fetch-Site` (accepting only `same-origin` and `none`) and falls back to
  * comparing `Origin`, else `Referer`, for clients that send no fetch metadata.
+ * That comparison accepts the request's own origin and the application's
+ * (see {@link HonoBffOptions.rpInitiatedLogout}), so the fallback still passes
+ * behind a TLS-terminating proxy that hands the BFF a plain-HTTP request.
  * `same-site` is rejected along with `cross-site`, so a `GET` logout link
  * followed from a sibling subdomain does not pass. That check **fails closed**:
  * a request carrying none of the three signals is rejected. Two residuals come
@@ -425,10 +428,18 @@ export interface HonoBffOptions {
      * `/auth/logout` — after destroying the local session — additionally
      * redirects the browser to the OP's `end_session_endpoint` with
      * `id_token_hint` (the session's id_token, if any), `client_id`, and a
-     * `post_logout_redirect_uri` built from the resolved origin + the
+     * `post_logout_redirect_uri` built from the application's origin + the
      * open-redirect-guarded `return_to`. This ends the upstream IDP SSO session,
      * not just the local BFF session.
      *
+     * The application's origin is {@link resolveOrigin}'s, else the configured
+     * client `redirectUri`'s, else the request's — the last only when no
+     * `redirectUri` is configured or {@link deriveRedirectUri} is on, matching
+     * the origin sign-in sends. Behind a TLS-terminating proxy the request
+     * reports `http:`, so a deployment that derives its redirect URI there sets
+     * {@link resolveOrigin}; otherwise the URI would miss the registered
+     * `https:` one.
+     *
      * Defaults to `false` (local logout only): not every IDP supports it, and it
      * adds a redirect hop. When enabled but no end-session endpoint is known,
      * logout falls back to the plain local redirect and warns once via
@@ -558,6 +569,14 @@ export interface HonoBffOptions {
     forwardedParams?: readonly string[];
     /** Default `return_to` applied when the browser doesn't pass one. */
     defaultReturnTo?: string;
+    /**
+     * Longest `return_to` accepted, in characters. `/auth/login` stores the
+     * value with the pending sign-in before any authentication, so a longer one
+     * is replaced by {@link defaultReturnTo} rather than kept — at login,
+     * callback, logout and in {@link HonoBff.loginContinuation}. Defaults to
+     * 2048; `Infinity` accepts any length.
+     */
+    maxReturnToLength?: number;
     /**
      * Optional hook run after the authorization code is exchanged. Lets
      * apps enrich the session with database-backed user info before the
@@ -638,7 +657,9 @@ export declare class HonoBff {
      * {@linkcode HonoBffOptions.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
      * numeric `cookie.maxAge` is not positive or exceeds 400 days, when
      * {@linkcode HonoBffBackchannelOptions.maxBodyBytes} is not a positive
-     * integer (a `RangeError`), or when
+     * integer (a `RangeError`), when
+     * {@linkcode HonoBffOptions.maxReturnToLength} is neither a positive
+     * integer nor `Infinity` (a `RangeError`), or when
      * {@linkcode HonoBffOptions.extraParams} or
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed

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

@@ -56,7 +56,7 @@ import { inboundRequestWithHeaders } from "../../../utils/_inbound-request.js";
 import { timingSafeMatchIndex } from "../../../utils/_timing-safe.js";
 import { sha256Hash } from "../../../server/utils/hash.js";
 import { OAUTH2_CONTEXT_KEY } from "../_common.js";
-import { loginContinuation as computeLoginContinuation, safeReturnTo, } from "../../../utils/url.js";
+import { DEFAULT_MAX_RETURN_TO_LENGTH, loginContinuation as computeLoginContinuation, safeReturnTo, } from "../../../utils/url.js";
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 import { DEFAULT_SESSION_MAX_AGE_MS, MemorySessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.js";
 import { buildDownstreamHeaders, buildUpstreamHeaders, isInvalidTokenChallenge, resolveForwardHeaders, resolveProxyUrl, } from "./proxy.js";
@@ -289,6 +289,7 @@ export class HonoBff {
     #sessionMode;
     #csrf;
     #extraAuthorizeParams;
+    #maxReturnToLength;
     #refreshes = new Map();
     /**
      * Defaults are applied for the session store ({@linkcode MemorySessionStore}),
@@ -307,7 +308,9 @@ export class HonoBff {
      * {@linkcode HonoBffOptions.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
      * numeric `cookie.maxAge` is not positive or exceeds 400 days, when
      * {@linkcode HonoBffBackchannelOptions.maxBodyBytes} is not a positive
-     * integer (a `RangeError`), or when
+     * integer (a `RangeError`), when
+     * {@linkcode HonoBffOptions.maxReturnToLength} is neither a positive
+     * integer nor `Infinity` (a `RangeError`), or when
      * {@linkcode HonoBffOptions.extraParams} or
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed
@@ -330,6 +333,13 @@ export class HonoBff {
         this.#sessionMode = options.sessionMode ?? "own";
         this.#csrf = resolveCsrf(options.csrf);
         this.#extraAuthorizeParams = resolveExtraAuthorizeParams(options);
+        this.#maxReturnToLength =
+            options.maxReturnToLength ?? DEFAULT_MAX_RETURN_TO_LENGTH;
+        if (this.#maxReturnToLength !== Infinity &&
+            !(Number.isInteger(this.#maxReturnToLength) && this.#maxReturnToLength > 0)) {
+            throw new RangeError("HonoBff maxReturnToLength must be a positive integer or Infinity, " +
+                `got ${this.#maxReturnToLength}.`);
+        }
         const sessionMaxAgeMs = positiveMs(options.sessionMaxAgeMs ?? DEFAULT_SESSION_MAX_AGE_MS, "sessionMaxAgeMs");
         this.#sessionMaxAgeMs = sessionMaxAgeMs;
         if (this.#sessionMode === "shared") {
@@ -454,6 +464,20 @@ export class HonoBff {
         }
         setCookie(c, this.#loginStateCookieName, hashes.slice(-MAX_PENDING_LOGIN_STATES).join(LOGIN_STATE_SEPARATOR), loginStateCookieOpts(this.#options.cookie, Math.ceil(this.#loginStateTtlMs / 1000)));
     }
+    #safeReturnTo(value) {
+        return safeReturnTo(value, this.#options.defaultReturnTo ?? "/", {
+            maxLength: this.#maxReturnToLength,
+        });
+    }
+    #appOrigin(c) {
+        const resolved = this.#options.resolveOrigin?.(c);
+        if (resolved !== undefined)
+            return resolved;
+        const configured = this.#options.deriveRedirectUri
+            ? undefined
+            : this.#client.redirectUri;
+        return new URL(configured ?? c.req.url).origin;
+    }
     #derivedRedirectUri(c, origin) {
         if (!this.#options.deriveRedirectUri)
             return undefined;
@@ -473,12 +497,12 @@ export class HonoBff {
         const fetchSite = c.req.header("sec-fetch-site");
         if (fetchSite)
             return fetchSite === "same-origin" || fetchSite === "none";
-        const target = new URL(c.req.url).origin;
+        const targets = [new URL(c.req.url).origin, this.#appOrigin(c)];
         const check = (val) => {
             if (!val)
                 return undefined;
             try {
-                return new URL(val).origin === target;
+                return targets.includes(new URL(val).origin);
             }
             catch {
                 return false;
@@ -555,6 +579,7 @@ export class HonoBff {
             authorizeEndpoint: this.#client.authorizationEndpoint,
             loginPath: this.#paths.login,
             defaultReturnTo: this.#options.defaultReturnTo,
+            maxReturnToLength: this.#maxReturnToLength,
         });
     }
     #pathsRelative() {
@@ -583,7 +608,7 @@ export class HonoBff {
     loginHandler() {
         return async (c) => {
             this.#noStore(c);
-            const returnTo = safeReturnTo(c.req.query("return_to"), this.#options.defaultReturnTo ?? "/");
+            const returnTo = this.#safeReturnTo(c.req.query("return_to"));
             const origin = this.#options.resolveOrigin?.(c);
             const requested = authorizeParamsForRequest(this.#extraAuthorizeParams, new URL(c.req.url).searchParams);
             const { url, state } = await this.#client.login({
@@ -683,7 +708,7 @@ export class HonoBff {
                 if (cookieValue !== existing) {
                     setCookie(c, this.#cookieName, cookieValue, this.#cookieOptions());
                 }
-                return c.redirect(safeReturnTo(returnTo, this.#options.defaultReturnTo ?? "/"));
+                return c.redirect(this.#safeReturnTo(returnTo));
             }
             catch (cause) {
                 return await fail({
@@ -723,11 +748,11 @@ export class HonoBff {
                 await this.#store.destroy(cookieValue);
                 deleteCookie(c, this.#cookieName, this.#cookieOptions());
             }
-            const returnTo = safeReturnTo(c.req.query("return_to"), this.#options.defaultReturnTo ?? "/");
+            const returnTo = this.#safeReturnTo(c.req.query("return_to"));
             if (this.#options.rpInitiatedLogout) {
                 const endSession = this.#client.endSessionEndpoint;
                 if (endSession) {
-                    const origin = this.#options.resolveOrigin?.(c) ?? new URL(c.req.url).origin;
+                    const origin = this.#appOrigin(c);
                     const url = new URL(endSession, origin);
                     if (idToken)
                         url.searchParams.set("id_token_hint", idToken);

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

@@ -342,6 +342,15 @@ export declare class DirectClient extends OAuth2ClientBase {
      * available. It is a public identifier, never a credential.
      */
     get clientId(): string;
+    /**
+     * The configured `redirect_uri`, or `undefined` when none was given.
+     *
+     * Exposed so a Backend-for-Frontend behind a TLS-terminating proxy can
+     * take the application's public origin from configuration rather than from
+     * a request URL that reports the proxy's plain-HTTP hop. See
+     * `HonoBffOptions.rpInitiatedLogout`.
+     */
+    get redirectUri(): string | undefined;
     /**
      * Builds the PKCE-protected authorize URL and persists the verifier under
      * the returned `state`. Navigate the browser to `url`; the callback route

package/dist/client/direct-client.js

@@ -280,6 +280,17 @@ export class DirectClient extends OAuth2ClientBase {
     get clientId() {
         return this.#clientId;
     }
+    /**
+     * The configured `redirect_uri`, or `undefined` when none was given.
+     *
+     * Exposed so a Backend-for-Frontend behind a TLS-terminating proxy can
+     * take the application's public origin from configuration rather than from
+     * a request URL that reports the proxy's plain-HTTP hop. See
+     * `HonoBffOptions.rpInitiatedLogout`.
+     */
+    get redirectUri() {
+        return this.#redirectUri;
+    }
     async #endpoint(key) {
         if (this.#issuer && !this.#hasFreshMetadata())
             await this.discover();

package/dist/client/storage.d.ts

@@ -135,17 +135,35 @@ export interface MemoryAuthRequestStorageOptions {
      * in ms. Defaults to 10 minutes; `Infinity` never prunes.
      */
     ttlMs?: number;
+    /**
+     * Most records held at once. A write beyond it evicts the oldest-written
+     * record, so a flood of sign-in starts that never reach the callback cannot
+     * grow the process without bound — at the cost of failing each evicted
+     * sign-in with an unknown `state`. Defaults to 1000; `Infinity` never
+     * evicts by count.
+     */
+    maxEntries?: number;
 }
 /**
  * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
  * browser document. Data is lost when the process exits. Every write prunes
- * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, so logins
- * that never return to the callback do not accumulate in a long-running
- * server.
+ * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, then
+ * evicts the oldest-written records beyond
+ * {@link MemoryAuthRequestStorageOptions.maxEntries}, so neither logins that
+ * never return to the callback nor an anonymous burst of sign-in starts can
+ * grow a long-running server without bound. A deployment with more than one
+ * instance, or more pending sign-ins than the cap, needs storage every
+ * instance shares instead.
  */
 export declare class MemoryAuthRequestStorage implements AuthRequestStorage {
     #private;
-    /** Configures the pruning TTL, 10 minutes by default. */
+    /**
+     * Configures the pruning TTL (10 minutes by default) and the record cap
+     * (1000 by default).
+     *
+     * @throws {RangeError} When `maxEntries` is neither a positive integer nor
+     * `Infinity`.
+     */
     constructor(options?: MemoryAuthRequestStorageOptions);
     /** Returns the record for {@linkcode state}, or `null` if none is stored. */
     get(state: string): AuthRequestRecord | null;
@@ -153,7 +171,8 @@ export declare class MemoryAuthRequestStorage implements AuthRequestStorage {
     take(state: string): AuthRequestRecord | null;
     /**
      * Stores {@linkcode value} under {@linkcode state}, first pruning records
-     * past the TTL. Pruning walks records oldest-write-first and stops at the
+     * past the TTL, then evicting the oldest-written records beyond
+     * `maxEntries`. Pruning walks records oldest-write-first and stops at the
      * first one inside the TTL, so it assumes each `createdAt` is the time of
      * its write, as `DirectClient.login` sets it.
      */

package/dist/client/storage.js

@@ -53,19 +53,37 @@ export class MemoryRefreshTokenStorage {
         this.#token = null;
     }
 }
+const DEFAULT_MAX_AUTH_REQUESTS = 1000;
 /**
  * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
  * browser document. Data is lost when the process exits. Every write prunes
- * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, so logins
- * that never return to the callback do not accumulate in a long-running
- * server.
+ * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, then
+ * evicts the oldest-written records beyond
+ * {@link MemoryAuthRequestStorageOptions.maxEntries}, so neither logins that
+ * never return to the callback nor an anonymous burst of sign-in starts can
+ * grow a long-running server without bound. A deployment with more than one
+ * instance, or more pending sign-ins than the cap, needs storage every
+ * instance shares instead.
  */
 export class MemoryAuthRequestStorage {
     #records = new Map();
     #ttlMs;
-    /** Configures the pruning TTL, 10 minutes by default. */
+    #maxEntries;
+    /**
+     * Configures the pruning TTL (10 minutes by default) and the record cap
+     * (1000 by default).
+     *
+     * @throws {RangeError} When `maxEntries` is neither a positive integer nor
+     * `Infinity`.
+     */
     constructor(options = {}) {
         this.#ttlMs = options.ttlMs ?? 10 * 60 * 1000;
+        this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_AUTH_REQUESTS;
+        if (this.#maxEntries !== Infinity &&
+            !(Number.isInteger(this.#maxEntries) && this.#maxEntries > 0)) {
+            throw new RangeError("MemoryAuthRequestStorage maxEntries must be a positive integer or " +
+                `Infinity, got ${this.#maxEntries}.`);
+        }
     }
     /** Returns the record for {@linkcode state}, or `null` if none is stored. */
     get(state) {
@@ -79,7 +97,8 @@ export class MemoryAuthRequestStorage {
     }
     /**
      * Stores {@linkcode value} under {@linkcode state}, first pruning records
-     * past the TTL. Pruning walks records oldest-write-first and stops at the
+     * past the TTL, then evicting the oldest-written records beyond
+     * `maxEntries`. Pruning walks records oldest-write-first and stops at the
      * first one inside the TTL, so it assumes each `createdAt` is the time of
      * its write, as `DirectClient.login` sets it.
      */
@@ -87,6 +106,7 @@ export class MemoryAuthRequestStorage {
         this.#pruneExpired();
         this.#records.delete(state);
         this.#records.set(state, value);
+        this.#evictOverflow();
     }
     /** Removes the record for {@linkcode state}. */
     delete(state) {
@@ -96,6 +116,13 @@ export class MemoryAuthRequestStorage {
     clear() {
         this.#records.clear();
     }
+    #evictOverflow() {
+        for (const state of this.#records.keys()) {
+            if (this.#records.size <= this.#maxEntries)
+                return;
+            this.#records.delete(state);
+        }
+    }
     #pruneExpired() {
         if (this.#ttlMs === Infinity)
             return;

package/dist/utils/url.d.ts

@@ -3,6 +3,17 @@
  *
  * @module
  */
+/** {@link SafeReturnToOptions.maxLength}'s default, in UTF-16 code units. */
+export declare const DEFAULT_MAX_RETURN_TO_LENGTH = 2048;
+/** Options for {@link safeReturnTo}. */
+export interface SafeReturnToOptions {
+    /**
+     * Longest value accepted, in UTF-16 code units (`String.length`), not
+     * bytes; a longer one collapses to the fallback. Defaults to {@link DEFAULT_MAX_RETURN_TO_LENGTH} (2048).
+     * `Infinity` accepts any length.
+     */
+    maxLength?: number;
+}
 /**
  * Open-redirect guard for a `return_to` / redirect target.
  *
@@ -19,6 +30,11 @@
  * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
  * browser does not decode them before parsing, so they stay on the origin.
  *
+ * A value longer than {@link SafeReturnToOptions.maxLength} (2048 characters
+ * by default) also collapses to `fallback`, so a caller that stores the
+ * result — a pending sign-in, a session — cannot be made to hold an
+ * arbitrarily large string per anonymous request.
+ *
  * Use this anywhere a user-influenced value — a `return_to` / `redirect` query
  * param or form field — is fed into a redirect `Location`, so a crafted
  * absolute target can't turn the (often post-authentication) redirect into an
@@ -32,9 +48,10 @@
  * safeReturnTo("/\\evil.com");       // → "/"
  * safeReturnTo("/\t/evil.com");      // → "/"
  * safeReturnTo(undefined, "/home");  // → "/home"
+ * safeReturnTo("/a-long-path", "/", { maxLength: 8 }); // → "/"
  * ```
  */
-export declare function safeReturnTo(value: string | null | undefined, fallback?: string): string;
+export declare function safeReturnTo(value: string | null | undefined, fallback?: string, options?: SafeReturnToOptions): string;
 /** Trusted application configuration for {@link loginContinuation}. */
 export interface LoginContinuationOptions {
     /**
@@ -47,6 +64,11 @@ export interface LoginContinuationOptions {
     loginPath?: string;
     /** Trusted fallback for missing/unsafe `returnTo`. Defaults to `"/"`. */
     defaultReturnTo?: string;
+    /**
+     * Longest `returnTo` accepted, in characters; a longer one falls back to
+     * {@link defaultReturnTo}. Defaults to 2048 ({@link safeReturnTo}'s cap).
+     */
+    maxReturnToLength?: number;
 }
 /**
  * The URL that (re)starts sign-in toward `returnTo`, for an app that owns its

package/dist/utils/url.js

@@ -4,6 +4,8 @@
  * @module
  */
 const RESOLUTION_ORIGIN = "http://safe-return-to.invalid";
+/** {@link SafeReturnToOptions.maxLength}'s default, in UTF-16 code units. */
+export const DEFAULT_MAX_RETURN_TO_LENGTH = 2048;
 function hasControlCharacter(value) {
     for (let index = 0; index < value.length; index++) {
         const code = value.charCodeAt(index);
@@ -28,6 +30,11 @@ function hasControlCharacter(value) {
  * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
  * browser does not decode them before parsing, so they stay on the origin.
  *
+ * A value longer than {@link SafeReturnToOptions.maxLength} (2048 characters
+ * by default) also collapses to `fallback`, so a caller that stores the
+ * result — a pending sign-in, a session — cannot be made to hold an
+ * arbitrarily large string per anonymous request.
+ *
  * Use this anywhere a user-influenced value — a `return_to` / `redirect` query
  * param or form field — is fed into a redirect `Location`, so a crafted
  * absolute target can't turn the (often post-authentication) redirect into an
@@ -41,11 +48,15 @@ function hasControlCharacter(value) {
  * safeReturnTo("/\\evil.com");       // → "/"
  * safeReturnTo("/\t/evil.com");      // → "/"
  * safeReturnTo(undefined, "/home");  // → "/home"
+ * safeReturnTo("/a-long-path", "/", { maxLength: 8 }); // → "/"
  * ```
  */
-export function safeReturnTo(value, fallback = "/") {
+export function safeReturnTo(value, fallback = "/", options = {}) {
     if (!value || !value.startsWith("/"))
         return fallback;
+    if (value.length > (options.maxLength ?? DEFAULT_MAX_RETURN_TO_LENGTH)) {
+        return fallback;
+    }
     if (hasControlCharacter(value))
         return fallback;
     let resolved;
@@ -79,7 +90,9 @@ export function safeReturnTo(value, fallback = "/") {
  * endpoint and login path are trusted application configuration.
  */
 export function loginContinuation(returnTo, options = {}) {
-    const safe = safeReturnTo(returnTo, options.defaultReturnTo ?? "/");
+    const safe = safeReturnTo(returnTo, options.defaultReturnTo ?? "/", {
+        maxLength: options.maxReturnToLength,
+    });
     if (options.authorizeEndpoint) {
         const base = "http://login.continuation.local";
         const authorizePath = new URL(options.authorizeEndpoint, base).pathname;

package/package.json

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