@udibo/oauth2 0.16.0 → 0.17.1

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

@@ -1,13 +1,14 @@
 /**
- * Stateless {@link AuthRequestStorage} for {@link HonoBff}.
+ * {@link AuthRequestStorageFactory} implementations for {@link HonoBff}.
  *
  * The pending authorization request — the `state`, its PKCE code verifier, and
  * where to return afterwards — has to survive the round trip to the identity
- * provider. The client's default {@link MemoryAuthRequestStorage} keeps it in
- * the process that started the flow, which breaks on any platform that spreads
- * requests across isolates or instances: `/auth/login` stores the record on one
- * and `/auth/callback` looks for it on another, so sign-in fails intermittently
- * with `unknown state parameter`.
+ * provider. {@link MemoryAuthRequestStorageFactory} keeps it in the process
+ * that started the flow, which breaks on any platform that spreads requests
+ * across isolates or instances: `/auth/login` stores the record on one and
+ * `/auth/callback` looks for it on another, so sign-in fails intermittently
+ * with `unknown state parameter`. `HonoBff` therefore has no default; the
+ * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
  * cookie instead (AES-GCM under a server-held secret, the same construction
@@ -18,7 +19,7 @@
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
  * that *this* browser is the one that started it, so a process-wide store like
- * the memory default would otherwise let anyone's browser complete anyone
+ * {@link MemoryAuthRequestStorageFactory} would otherwise let anyone's browser complete anyone
  * else's pending sign-in (login CSRF). {@link HonoBff} closes that separately
  * and unconditionally: `/auth/login` also binds the `state` to the browser in
  * a short-lived cookie that `/auth/callback` requires, whichever storage is
@@ -27,7 +28,7 @@
  * @module
  */
 import type { Context } from "hono";
-import type { AuthRequestStorage } from "../../../client/mod.ts";
+import { type AuthRequestStorage, type MemoryAuthRequestStorageOptions } from "../../../client/mod.ts";
 /**
  * Cookie attributes for the pending-authorization cookie.
  *
@@ -110,8 +111,10 @@ export interface EncryptedCookieAuthRequestStorageOptions {
  * {@link HonoBffOptions.authRequestStorage} takes one of these rather than a
  * bare storage because a cookie-backed store can only read and write through
  * the request's {@link Context}. Pass an
- * {@link EncryptedCookieAuthRequestStorage}, or implement `forRequest` over
- * storage of your own.
+ * {@link EncryptedCookieAuthRequestStorage}, a
+ * {@link MemoryAuthRequestStorageFactory} for a single process, or implement
+ * `forRequest` over storage every instance shares. A storage that needs no
+ * request context is wrapped as `{ forRequest: () => storage }`.
  */
 export interface AuthRequestStorageFactory {
     /** Returns the storage bound to `c`, for the duration of that request. */
@@ -123,7 +126,7 @@ export interface AuthRequestStorageFactory {
  * `/auth/callback` need not be served by the same instance.
  *
  * Reach for it whenever the BFF runs on more than one isolate or instance —
- * the client's default in-memory storage fails those deployments with
+ * {@link MemoryAuthRequestStorageFactory} fails those deployments with
  * `unknown state parameter`. The AES key is derived on first use and shared by
  * every later request.
  *
@@ -173,3 +176,46 @@ export declare class EncryptedCookieAuthRequestStorage implements AuthRequestSto
  * ```
  */
 export declare function encryptedCookieAuthRequestStorage(options: EncryptedCookieAuthRequestStorageOptions): EncryptedCookieAuthRequestStorage;
+/**
+ * In-process {@link AuthRequestStorageFactory}: every request shares one
+ * {@link MemoryAuthRequestStorage}, so a sign-in completes only on the process
+ * that started it.
+ *
+ * Pass it explicitly for a single long-lived process, tests and local
+ * development. A deployment that can serve `/auth/login` and `/auth/callback`
+ * from different instances or isolates fails sign-in with it, intermittently,
+ * with an unknown `state`; use {@link EncryptedCookieAuthRequestStorage} or a
+ * factory over shared storage there. The options are
+ * {@link MemoryAuthRequestStorage}'s: records older than `ttlMs` (10 minutes
+ * by default) are pruned and at most `maxEntries` (1000 by default) are held.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   HonoBff,
+ *   MemoryAuthRequestStorageFactory,
+ *   MemorySessionStore,
+ * } from "@udibo/oauth2/hono/bff";
+ * import { DirectClient } from "@udibo/oauth2/client";
+ *
+ * const bff = new HonoBff({
+ *   client: new DirectClient({
+ *     clientId: "local-app",
+ *     clientSecret: "dev-secret",
+ *     issuer: "http://localhost:8000",
+ *   }),
+ *   sessionStore: new MemorySessionStore(),
+ *   authRequestStorage: new MemoryAuthRequestStorageFactory(),
+ * });
+ * ```
+ */
+export declare class MemoryAuthRequestStorageFactory implements AuthRequestStorageFactory {
+    #private;
+    /**
+     * @throws {RangeError} When `maxEntries` is neither a positive integer nor
+     * `Infinity`.
+     */
+    constructor(options?: MemoryAuthRequestStorageOptions);
+    /** Returns the process-wide storage; `c` is not consulted. */
+    forRequest(_c: Context): AuthRequestStorage;
+}

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

@@ -1,13 +1,14 @@
 /**
- * Stateless {@link AuthRequestStorage} for {@link HonoBff}.
+ * {@link AuthRequestStorageFactory} implementations for {@link HonoBff}.
  *
  * The pending authorization request — the `state`, its PKCE code verifier, and
  * where to return afterwards — has to survive the round trip to the identity
- * provider. The client's default {@link MemoryAuthRequestStorage} keeps it in
- * the process that started the flow, which breaks on any platform that spreads
- * requests across isolates or instances: `/auth/login` stores the record on one
- * and `/auth/callback` looks for it on another, so sign-in fails intermittently
- * with `unknown state parameter`.
+ * provider. {@link MemoryAuthRequestStorageFactory} keeps it in the process
+ * that started the flow, which breaks on any platform that spreads requests
+ * across isolates or instances: `/auth/login` stores the record on one and
+ * `/auth/callback` looks for it on another, so sign-in fails intermittently
+ * with `unknown state parameter`. `HonoBff` therefore has no default; the
+ * caller chooses.
  *
  * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
  * cookie instead (AES-GCM under a server-held secret, the same construction
@@ -18,7 +19,7 @@
  * **Which storage you pick is a reliability decision, not a security one.**
  * Server-side storage on its own says a `state` is pending somewhere — never
  * that *this* browser is the one that started it, so a process-wide store like
- * the memory default would otherwise let anyone's browser complete anyone
+ * {@link MemoryAuthRequestStorageFactory} would otherwise let anyone's browser complete anyone
  * else's pending sign-in (login CSRF). {@link HonoBff} closes that separately
  * and unconditionally: `/auth/login` also binds the `state` to the browser in
  * a short-lived cookie that `/auth/callback` requires, whichever storage is
@@ -27,6 +28,7 @@
  * @module
  */
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { MemoryAuthRequestStorage, } from "../../../client/mod.js";
 import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 const BASE_NAME = "oauth2_auth_request";
@@ -51,7 +53,7 @@ function cookieAttributes(options, maxAgeSeconds) {
  * `/auth/callback` need not be served by the same instance.
  *
  * Reach for it whenever the BFF runs on more than one isolate or instance —
- * the client's default in-memory storage fails those deployments with
+ * {@link MemoryAuthRequestStorageFactory} fails those deployments with
  * `unknown state parameter`. The AES key is derived on first use and shared by
  * every later request.
  *
@@ -173,3 +175,50 @@ export class EncryptedCookieAuthRequestStorage {
 export function encryptedCookieAuthRequestStorage(options) {
     return new EncryptedCookieAuthRequestStorage(options);
 }
+/**
+ * In-process {@link AuthRequestStorageFactory}: every request shares one
+ * {@link MemoryAuthRequestStorage}, so a sign-in completes only on the process
+ * that started it.
+ *
+ * Pass it explicitly for a single long-lived process, tests and local
+ * development. A deployment that can serve `/auth/login` and `/auth/callback`
+ * from different instances or isolates fails sign-in with it, intermittently,
+ * with an unknown `state`; use {@link EncryptedCookieAuthRequestStorage} or a
+ * factory over shared storage there. The options are
+ * {@link MemoryAuthRequestStorage}'s: records older than `ttlMs` (10 minutes
+ * by default) are pruned and at most `maxEntries` (1000 by default) are held.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   HonoBff,
+ *   MemoryAuthRequestStorageFactory,
+ *   MemorySessionStore,
+ * } from "@udibo/oauth2/hono/bff";
+ * import { DirectClient } from "@udibo/oauth2/client";
+ *
+ * const bff = new HonoBff({
+ *   client: new DirectClient({
+ *     clientId: "local-app",
+ *     clientSecret: "dev-secret",
+ *     issuer: "http://localhost:8000",
+ *   }),
+ *   sessionStore: new MemorySessionStore(),
+ *   authRequestStorage: new MemoryAuthRequestStorageFactory(),
+ * });
+ * ```
+ */
+export class MemoryAuthRequestStorageFactory {
+    #storage;
+    /**
+     * @throws {RangeError} When `maxEntries` is neither a positive integer nor
+     * `Infinity`.
+     */
+    constructor(options = {}) {
+        this.#storage = new MemoryAuthRequestStorage(options);
+    }
+    /** Returns the process-wide storage; `c` is not consulted. */
+    forRequest(_c) {
+        return this.#storage;
+    }
+}

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

@@ -311,10 +311,23 @@ export interface HonoBffOptions {
      */
     client: DirectClient;
     /**
-     * Where session data lives. Defaults to {@link MemorySessionStore},
-     * which is fine for dev and tests but must be replaced for production.
-     */
-    sessionStore?: SessionStore;
+     * Where session data lives. Required, because the right store depends on
+     * how many instances serve the app:
+     *
+     * - {@link EncryptedCookieSessionStore} keeps the session in an encrypted
+     *   cookie, so every instance that shares its secret can read it and no
+     *   server-side store is needed. It cannot list sessions, so it does not
+     *   support {@link HonoBffOptions.backchannelLogout}, and sign-out cannot
+     *   invalidate a copied cookie: it stays valid until its `maxAgeMs`. Use a
+     *   shared {@link SessionStore} when you need revocation.
+     * - A {@link SessionStore} over a database or cache every instance shares,
+     *   for server-side revocation and back-channel logout. Check it with
+     *   `runSessionStoreContractTests`.
+     * - {@link MemorySessionStore} for a single process, tests and local
+     *   development. A session it holds is unknown to every other instance, so
+     *   behind a load balancer the user appears signed out.
+     */
+    sessionStore: SessionStore;
     /**
      * How long a BFF session is meant to live, in milliseconds. Defaults to 14
      * days ({@link DEFAULT_SESSION_MAX_AGE_MS}). Milliseconds match the store's
@@ -346,19 +359,25 @@ export interface HonoBffOptions {
     sessionMaxAgeMs?: number;
     /**
      * Where the pending authorization request (`state` → PKCE verifier,
-     * return-to) lives, resolved per request. Defaults to the client's
-     * configured `authRequestStorage`, which is in-memory unless the client was
-     * given something else — fine for a single long-lived process, wrong for any
-     * platform that can serve `/auth/login` and `/auth/callback` from different
-     * isolates. Pass an {@link EncryptedCookieAuthRequestStorage} to carry the
-     * record in an encrypted cookie instead, or implement
-     * {@link AuthRequestStorageFactory} over storage of your own.
+     * return-to) lives, resolved per request. Required, because `/auth/login`
+     * and `/auth/callback` can be served by different instances or isolates.
+     * The BFF always uses this, never the client's own `authRequestStorage`.
+     *
+     * - {@link EncryptedCookieAuthRequestStorage} carries the record in an
+     *   encrypted cookie, so any instance sharing its secret completes the
+     *   sign-in with no server-side store.
+     * - An {@link AuthRequestStorageFactory} over storage every instance shares;
+     *   wrap a context-free `AuthRequestStorage` as
+     *   `{ forRequest: () => storage }`.
+     * - {@link MemoryAuthRequestStorageFactory} for a single process, tests and
+     *   local development. A callback that reaches another instance fails with
+     *   an unknown `state`.
      *
      * Whatever this resolves to, the pending request is **also** bound to the
      * browser that started it by the login-state cookie, which no option turns
      * off. See {@link loginStateTtlMs}.
      */
-    authRequestStorage?: AuthRequestStorageFactory;
+    authRequestStorage: AuthRequestStorageFactory;
     /**
      * How long, in ms, the browser keeps the login-state cookie `/auth/login`
      * sets and `/auth/callback` requires — the `Max-Age` on that cookie, and so
@@ -492,8 +511,16 @@ export interface HonoBffOptions {
      * @example Pin every sign-in to one organization
      * ```ts
      * declare const client: DirectClient;
-     *
-     * const bff = new HonoBff({ client, extraParams: { organization: "acme" } });
+     * declare const stores: Pick<
+     *   HonoBffOptions,
+     *   "sessionStore" | "authRequestStorage"
+     * >;
+     *
+     * const bff = new HonoBff({
+     *   client,
+     *   ...stores,
+     *   extraParams: { organization: "acme" },
+     * });
      * ```
      */
     extraParams?: Record<string, string>;
@@ -559,8 +586,16 @@ export interface HonoBffOptions {
      * @example Let a sign-in link choose the organization
      * ```ts
      * declare const client: DirectClient;
-     *
-     * const bff = new HonoBff({ client, forwardedParams: ["organization"] });
+     * declare const stores: Pick<
+     *   HonoBffOptions,
+     *   "sessionStore" | "authRequestStorage"
+     * >;
+     *
+     * const bff = new HonoBff({
+     *   client,
+     *   ...stores,
+     *   forwardedParams: ["organization"],
+     * });
      * ```
      *
      * A link to `/auth/login?organization=acme&return_to=/dashboard` then
@@ -641,9 +676,12 @@ export interface HonoBffOptions {
 export declare class HonoBff {
     #private;
     /**
-     * Defaults are applied for the session store ({@linkcode MemorySessionStore}),
-     * session mode (`"own"`), cookie name, and CSRF.
+     * Defaults are applied for session mode (`"own"`), cookie name, and CSRF.
+     * The session store and auth-request storage have no default.
      *
+     * @throws {TypeError} When {@linkcode HonoBffOptions.sessionStore} or
+     * {@linkcode HonoBffOptions.authRequestStorage} is missing, or when
+     * `authRequestStorage` has no `forRequest` method.
      * @throws {Error} When {@linkcode HonoBffOptions.backchannelLogout} is
      * configured against a store that cannot enumerate sessions (e.g.
      * {@linkcode EncryptedCookieSessionStore}), when an explicit

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

@@ -58,7 +58,7 @@ import { sha256Hash } from "../../../server/utils/hash.js";
 import { OAUTH2_CONTEXT_KEY } from "../_common.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 { DEFAULT_SESSION_MAX_AGE_MS, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.js";
 import { buildDownstreamHeaders, buildUpstreamHeaders, isInvalidTokenChallenge, resolveForwardHeaders, resolveProxyUrl, } from "./proxy.js";
 function isRevokedGrant(error) {
     if (!isOAuth2Error(error))
@@ -268,6 +268,30 @@ function loginStateCookieOpts(opts, maxAgeSeconds) {
         ...(maxAgeSeconds === undefined ? {} : { maxAge: maxAgeSeconds }),
     };
 }
+const MISSING_SESSION_STORE = "HonoBff requires options.sessionStore. Pass EncryptedCookieSessionStore " +
+    "to keep sessions in an encrypted cookie any instance can read (sign-out " +
+    "cannot revoke a copied cookie), a " +
+    "SessionStore over a database or cache every instance shares, or " +
+    "MemorySessionStore for a single process, tests and local development.";
+const MISSING_AUTH_REQUEST_STORAGE = "HonoBff requires options.authRequestStorage. Pass " +
+    "EncryptedCookieAuthRequestStorage to keep pending sign-ins in an " +
+    "encrypted cookie any instance can read, an AuthRequestStorageFactory " +
+    "over storage every instance shares, or MemoryAuthRequestStorageFactory " +
+    "for a single process, tests and local development.";
+function assertStoresConfigured(options) {
+    const missing = [
+        ...(options.sessionStore ? [] : [MISSING_SESSION_STORE]),
+        ...(options.authRequestStorage ? [] : [MISSING_AUTH_REQUEST_STORAGE]),
+    ];
+    if (missing.length > 0)
+        throw new TypeError(missing.join(" "));
+    if (typeof options.authRequestStorage?.forRequest !== "function") {
+        throw new TypeError("HonoBff options.authRequestStorage must be an " +
+            "AuthRequestStorageFactory, an object whose forRequest(c) returns the " +
+            "storage for that request. Wrap an AuthRequestStorage that needs no " +
+            "request context as { forRequest: () => storage }.");
+    }
+}
 /**
  * Backend-for-Frontend adapter for Hono. Construct once per app, mount
  * `routes()` under `/auth`, and use `attachToken()` as middleware on
@@ -292,9 +316,12 @@ export class HonoBff {
     #maxReturnToLength;
     #refreshes = new Map();
     /**
-     * Defaults are applied for the session store ({@linkcode MemorySessionStore}),
-     * session mode (`"own"`), cookie name, and CSRF.
+     * Defaults are applied for session mode (`"own"`), cookie name, and CSRF.
+     * The session store and auth-request storage have no default.
      *
+     * @throws {TypeError} When {@linkcode HonoBffOptions.sessionStore} or
+     * {@linkcode HonoBffOptions.authRequestStorage} is missing, or when
+     * `authRequestStorage` has no `forRequest` method.
      * @throws {Error} When {@linkcode HonoBffOptions.backchannelLogout} is
      * configured against a store that cannot enumerate sessions (e.g.
      * {@linkcode EncryptedCookieSessionStore}), when an explicit
@@ -320,9 +347,10 @@ export class HonoBff {
      * {@linkcode HonoBffOptions.scope} is also set.
      */
     constructor(options) {
+        assertStoresConfigured(options);
         this.#options = options;
         this.#client = options.client;
-        this.#store = options.sessionStore ?? new MemorySessionStore();
+        this.#store = options.sessionStore;
         this.#paths = resolvePaths(options.paths, {
             backchannelMounted: options.backchannelLogout !== undefined,
         });
@@ -447,6 +475,13 @@ export class HonoBff {
         deleteCookie(c, this.#cookieName, this.#cookieOptions());
         return null;
     }
+    #authRequestStorage(c) {
+        const storage = this.#options.authRequestStorage.forRequest(c);
+        if (!storage) {
+            throw new TypeError("HonoBff options.authRequestStorage.forRequest(c) returned no storage.");
+        }
+        return storage;
+    }
     #noStore(c) {
         c.header("Cache-Control", "no-store");
         c.header("Vary", "Cookie");
@@ -618,7 +653,7 @@ export class HonoBff {
                 prompt: requested.prompt,
                 extraParams: requested.extraParams,
                 redirectUri: this.#derivedRedirectUri(c, origin),
-                authRequestStorage: this.#options.authRequestStorage?.forRequest(c),
+                authRequestStorage: this.#authRequestStorage(c),
             });
             this.#writeLoginStateHashes(c, [
                 ...this.#loginStateHashes(c),
@@ -669,7 +704,7 @@ export class HonoBff {
                 const { tokens, refreshToken, returnTo, raw } = await this.#client.exchangeAuthorizationCode(code, state, {
                     origin,
                     redirectUri: this.#derivedRedirectUri(c, origin),
-                    authRequestStorage: this.#options.authRequestStorage?.forRequest(c),
+                    authRequestStorage: this.#authRequestStorage(c),
                 });
                 let user = null;
                 let sid;

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

@@ -4,7 +4,12 @@
  * Exposes a {@link HonoBff} class that wraps an
  * `DirectClient` constructed with a client secret, plus the
  * {@link SessionStore} contract and two ready-to-use implementations
- * ({@link MemorySessionStore}, {@link EncryptedCookieSessionStore}).
+ * ({@link MemorySessionStore}, {@link EncryptedCookieSessionStore}), and the
+ * {@link AuthRequestStorageFactory} contract with two of its own
+ * ({@link MemoryAuthRequestStorageFactory},
+ * {@link EncryptedCookieAuthRequestStorage}). `HonoBff` requires one of each:
+ * the encrypted-cookie pair works across instances with no shared server, and
+ * the memory pair serves a single process, tests and local development.
  *
  * Need a server-side store (Postgres, Redis, …)? Implement the
  * {@link SessionStore} interface and verify it with
@@ -13,6 +18,6 @@
  * @module
  */
 export { type BackchannelLogoutSubject, type BffCallbackError, HonoBff, type HonoBffBackchannelOptions, type HonoBffCookieOptions, type HonoBffCsrfOptions, type HonoBffOptions, type HonoBffPaths, type HonoBffResourceServer, } from "./bff.ts";
-export { type AuthRequestCookieOptions, type AuthRequestStorageFactory, EncryptedCookieAuthRequestStorage, encryptedCookieAuthRequestStorage, type EncryptedCookieAuthRequestStorageOptions, } from "./auth-request-store.ts";
+export { type AuthRequestCookieOptions, type AuthRequestStorageFactory, EncryptedCookieAuthRequestStorage, encryptedCookieAuthRequestStorage, type EncryptedCookieAuthRequestStorageOptions, MemoryAuthRequestStorageFactory, } from "./auth-request-store.ts";
 export { DEFAULT_PROXY_FORWARD_HEADERS, type HonoBffProxyOptions, } from "./proxy.ts";
 export { type BackchannelLogoutStore, type BoundedSessionStore, DEFAULT_SESSION_MAX_AGE_MS, EncryptedCookieSessionStore, type EncryptedCookieSessionStoreOptions, MemorySessionStore, type SessionData, type SessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.ts";

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

@@ -4,7 +4,12 @@
  * Exposes a {@link HonoBff} class that wraps an
  * `DirectClient` constructed with a client secret, plus the
  * {@link SessionStore} contract and two ready-to-use implementations
- * ({@link MemorySessionStore}, {@link EncryptedCookieSessionStore}).
+ * ({@link MemorySessionStore}, {@link EncryptedCookieSessionStore}), and the
+ * {@link AuthRequestStorageFactory} contract with two of its own
+ * ({@link MemoryAuthRequestStorageFactory},
+ * {@link EncryptedCookieAuthRequestStorage}). `HonoBff` requires one of each:
+ * the encrypted-cookie pair works across instances with no shared server, and
+ * the memory pair serves a single process, tests and local development.
  *
  * Need a server-side store (Postgres, Redis, …)? Implement the
  * {@link SessionStore} interface and verify it with
@@ -13,6 +18,6 @@
  * @module
  */
 export { HonoBff, } from "./bff.js";
-export { EncryptedCookieAuthRequestStorage, encryptedCookieAuthRequestStorage, } from "./auth-request-store.js";
+export { EncryptedCookieAuthRequestStorage, encryptedCookieAuthRequestStorage, MemoryAuthRequestStorageFactory, } from "./auth-request-store.js";
 export { DEFAULT_PROXY_FORWARD_HEADERS, } from "./proxy.js";
 export { DEFAULT_SESSION_MAX_AGE_MS, EncryptedCookieSessionStore, MemorySessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.js";

package/dist/server/signing-keys.d.ts

@@ -117,8 +117,9 @@ export declare function exportSigningKeyJwk(key: SigningKey): Promise<JsonWebKey
 }>;
 /**
  * Import a signing key previously exported with {@link exportSigningKeyJwk}.
- * A JWK without a `kid` is given a random one, so every instance importing it
- * would publish and stamp a different `kid` — persist the exported `kid`.
+ * A JWK that sets a `kid` keeps it. One without a `kid` gets its RFC 7638 JWK
+ * thumbprint (base64url SHA-256 of the public key), so every instance
+ * importing the same key publishes and stamps the same `kid`.
  */
 export declare function importSigningKeyJwk(jwk: JsonWebKey & {
     kid?: string;

package/dist/server/signing-keys.js

@@ -13,6 +13,7 @@
  */
 import { base64urlDecode, base64urlEncode } from "../utils/crypto.js";
 import { snapshotAuthenticationContext } from "../utils/authentication-context.js";
+import { jwkThumbprint } from "../utils/_jwk-thumbprint.js";
 /** A {@link SigningKeyProvider} over one fixed key. */
 export class StaticSigningKeyProvider {
     #key;
@@ -130,12 +131,13 @@ export async function exportSigningKeyJwk(key) {
 }
 /**
  * Import a signing key previously exported with {@link exportSigningKeyJwk}.
- * A JWK without a `kid` is given a random one, so every instance importing it
- * would publish and stamp a different `kid` — persist the exported `kid`.
+ * A JWK that sets a `kid` keeps it. One without a `kid` gets its RFC 7638 JWK
+ * thumbprint (base64url SHA-256 of the public key), so every instance
+ * importing the same key publishes and stamps the same `kid`.
  */
 export async function importSigningKeyJwk(jwk) {
     const privateKey = await crypto.subtle.importKey("jwk", jwk, ES256_PARAMS, true, ["sign"]);
-    const kid = jwk.kid ?? crypto.randomUUID();
+    const kid = jwk.kid ?? (await jwkThumbprint(jwk));
     return {
         kid,
         alg: "ES256",

package/dist/utils/_jwk-thumbprint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * RFC 7638 JWK thumbprints.
+ *
+ * @module
+ */
+/**
+ * The RFC 7638 SHA-256 thumbprint of a JWK, base64url-encoded. Only the key
+ * type's required public members are hashed, so a private JWK and its public
+ * half share a thumbprint. Rejects with a `TypeError` for a key type other
+ * than `EC`, `OKP` or `RSA`, or when a required member is missing.
+ */
+export declare function jwkThumbprint(jwk: JsonWebKey): Promise<string>;

package/dist/utils/_jwk-thumbprint.js

@@ -0,0 +1,34 @@
+/**
+ * RFC 7638 JWK thumbprints.
+ *
+ * @module
+ */
+import { encodeBase64Url } from "./_encoding.js";
+const REQUIRED_MEMBERS = {
+    EC: ["crv", "kty", "x", "y"],
+    OKP: ["crv", "kty", "x"],
+    RSA: ["e", "kty", "n"],
+};
+/**
+ * The RFC 7638 SHA-256 thumbprint of a JWK, base64url-encoded. Only the key
+ * type's required public members are hashed, so a private JWK and its public
+ * half share a thumbprint. Rejects with a `TypeError` for a key type other
+ * than `EC`, `OKP` or `RSA`, or when a required member is missing.
+ */
+export async function jwkThumbprint(jwk) {
+    const members = jwk.kty === undefined ? undefined : REQUIRED_MEMBERS[jwk.kty];
+    if (!members) {
+        throw new TypeError(`Cannot compute a JWK thumbprint for key type ${JSON.stringify(jwk.kty)}`);
+    }
+    const fields = jwk;
+    const canonical = {};
+    for (const member of members) {
+        const value = fields[member];
+        if (typeof value !== "string") {
+            throw new TypeError(`Cannot compute a JWK thumbprint without the "${member}" member`);
+        }
+        canonical[member] = value;
+    }
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(canonical)));
+    return encodeBase64Url(new Uint8Array(digest));
+}

package/package.json

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