@udibo/oauth2 0.1.0

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

@@ -0,0 +1,154 @@
+/**
+ * Stateless {@link AuthRequestStorage} 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`.
+ *
+ * {@link EncryptedCookieAuthRequestStorage} carries the record in an encrypted
+ * cookie instead (AES-GCM under a server-held secret, the same construction
+ * {@link EncryptedCookieSessionStore} uses), so no server-side storage is
+ * involved and any instance can complete the flow. Apps that already have a
+ * database can implement {@link AuthRequestStorage} against it instead.
+ *
+ * **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
+ * 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
+ * configured. Choose here on whether every instance can read the record back.
+ *
+ * @module
+ */
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
+const BASE_NAME = "oauth2_auth_request";
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_PENDING = 3;
+function cookieAttributes(options, maxAgeSeconds) {
+    const { secure, path, domain } = resolvePrefixConstrainedAttributes(options);
+    return {
+        path,
+        secure,
+        httpOnly: true,
+        sameSite: options?.sameSite ?? "Lax",
+        ...(domain ? { domain } : {}),
+        ...(maxAgeSeconds === undefined ? {} : { maxAge: maxAgeSeconds }),
+    };
+}
+/**
+ * Stateless {@link AuthRequestStorage}: the pending authorization requests live
+ * in an AES-GCM cookie under a server-held secret, so `/auth/login` and
+ * `/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
+ * `unknown state parameter`. The AES key is derived on first use and shared by
+ * every later request.
+ *
+ * @example
+ * ```ts
+ * const bff = new HonoBff({
+ *   client,
+ *   sessionStore: new EncryptedCookieSessionStore({ secret }),
+ *   authRequestStorage: new EncryptedCookieAuthRequestStorage({ secret }),
+ * });
+ * ```
+ */
+export class EncryptedCookieAuthRequestStorage {
+    #cookie;
+    #secret;
+    #name;
+    #ttlMs;
+    #maxPending;
+    #keyPromise;
+    /**
+     * Resolves and validates the cookie name up front; the AES key is derived
+     * lazily on the first request that touches the cookie.
+     *
+     * @throws {Error} When an explicit {@link AuthRequestCookieOptions.name}
+     * carries a `__Host-`/`__Secure-` prefix the other cookie options contradict,
+     * or when {@link AuthRequestCookieOptions.sameSite} is `"None"` without
+     * {@link AuthRequestCookieOptions.secure}.
+     */
+    constructor(options) {
+        this.#cookie = options.cookie;
+        this.#secret = options.secret;
+        this.#name = resolveCookieName({
+            name: options.cookie?.name,
+            base: BASE_NAME,
+            attributes: resolvePrefixConstrainedAttributes(options.cookie),
+            consequence: "the pending request would be lost and every callback would fail " +
+                "with an unknown state parameter",
+        });
+        this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.#maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+    }
+    #key() {
+        return this.#keyPromise ??= deriveAesKey(this.#secret);
+    }
+    async #read(c) {
+        const cookieValue = getCookie(c, this.#name);
+        if (!cookieValue)
+            return {};
+        const pending = await unsealJson(await this.#key(), cookieValue);
+        if (!pending)
+            return {};
+        const cutoff = Date.now() - this.#ttlMs;
+        return Object.fromEntries(Object.entries(pending).filter(([, record]) => record.createdAt > cutoff));
+    }
+    async #write(c, pending) {
+        const entries = Object.entries(pending)
+            .sort(([, a], [, b]) => 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)));
+    }
+    #clear(c) {
+        deleteCookie(c, this.#name, cookieAttributes(this.#cookie));
+    }
+    /** Returns the storage bound to `c`, for the duration of that request. */
+    forRequest(c) {
+        return {
+            get: async (state) => (await this.#read(c))[state] ?? null,
+            set: async (state, value) => {
+                const pending = await this.#read(c);
+                pending[state] = value;
+                await this.#write(c, pending);
+            },
+            delete: async (state) => {
+                const pending = await this.#read(c);
+                delete pending[state];
+                await this.#write(c, pending);
+            },
+            clear: () => this.#clear(c),
+        };
+    }
+}
+/**
+ * Convenience factory for {@link EncryptedCookieAuthRequestStorage} — the same
+ * as `new EncryptedCookieAuthRequestStorage(options)`, for call sites that
+ * prefer a function to a constructor.
+ *
+ * @example
+ * ```ts
+ * import { encryptedCookieAuthRequestStorage } from "@udibo/oauth2/hono/bff";
+ *
+ * const authRequestStorage = encryptedCookieAuthRequestStorage({
+ *   secret: Deno.env.get("SESSION_SECRET")!,
+ * });
+ * ```
+ */
+export function encryptedCookieAuthRequestStorage(options) {
+    return new EncryptedCookieAuthRequestStorage(options);
+}