@flow-industries/id 0.11.0 → 0.12.0

package/dist/sdk/client/create-flow.d.ts

@@ -10,9 +10,9 @@ import { credentialToAddress } from "./session";
  *
  * On construction it kicks off two async tasks: rehydrating the credential
  * from IndexedDB (so signing works even before the JWT is refreshed) and,
- * unless `autoRestore: false`, attempting a silent JWT refresh through the
- * hidden dialog iframe. Both run in the background; consumers can subscribe
- * to state changes via `flow.subscribe`.
+ * unless `autoRestore: false`, a silent session resolve through the app's
+ * first-party session route. Both run in the background; consumers can
+ * subscribe to state changes via `flow.subscribe`.
  *
  * Most signing methods dynamically import their implementation modules so
  * apps that only use identity (no chain ops) don't pay for the viem/tempo

package/dist/sdk/client/create-flow.js

@@ -1,20 +1,19 @@
-import { clearBrowserCookie, cookieNamesFor, JWT_COOKIE_MAX_AGE_S, writeBrowserCookie, } from "../cookies";
+import { DEFAULT_SESSION_PATH, isLocalHostname, resolveIdHost, } from "../id-host";
 import { isExpiring } from "../token-expiry";
 import { createDialogHost } from "./dialog-host";
 import { idb } from "./idb";
 import { METHODS } from "./methods";
-import { makeRefreshStore } from "./refresh-store";
 import { createRoomsApi } from "./rooms";
 import { credentialToAddress, restoreCredential, runLogin, runLogout, } from "./session";
 import { createStore, initialFlowState } from "./store";
-const DEFAULT_HOST = "https://id.flow.industries";
 /**
- * Runs `fn` while holding a cross-tab lock (Web Locks API) so concurrent tabs
- * of the same origin serialize guest creation: the first tab mints and sets the
- * shared cookie, later tabs then restore it instead of minting a duplicate
- * guest. Falls back to running `fn` directly where Web Locks is unavailable.
+ * Runs `fn` while holding a cross-tab lock (Web Locks API — origin-scoped by
+ * design, matching the origin-scoped session cookies) so concurrent tabs
+ * serialize session work: the first tab refreshes or mints, later tabs then
+ * see the result instead of racing it. Falls back to running `fn` directly
+ * where Web Locks is unavailable.
  */
-function withGuestLock(name, fn) {
+function withOriginLock(name, fn) {
     const locks = globalThis.navigator?.locks;
     if (locks?.request)
         return locks.request(name, fn);
@@ -50,9 +49,9 @@ function resolveAccessKey(input) {
  *
  * On construction it kicks off two async tasks: rehydrating the credential
  * from IndexedDB (so signing works even before the JWT is refreshed) and,
- * unless `autoRestore: false`, attempting a silent JWT refresh through the
- * hidden dialog iframe. Both run in the background; consumers can subscribe
- * to state changes via `flow.subscribe`.
+ * unless `autoRestore: false`, a silent session resolve through the app's
+ * first-party session route. Both run in the background; consumers can
+ * subscribe to state changes via `flow.subscribe`.
  *
  * Most signing methods dynamically import their implementation modules so
  * apps that only use identity (no chain ops) don't pay for the viem/tempo
@@ -67,21 +66,17 @@ export function createFlow(options = {}) {
     // stale state. For genuine multi-instance scenarios (tests), call
     // resetFlow() first or pass explicit Flow instances.
     if (typeof window === "undefined") {
-        throw new Error("createFlow() is browser-only (localStorage, IndexedDB, iframes). " +
-            "For server rendering, resolve state with resolveSession() from " +
-            "@flow-industries/id/server and render with createStaticFlow().");
+        throw new Error("createFlow() is browser-only (IndexedDB, iframes, fetch with " +
+            "cookies). For server rendering, resolve state with resolveSession() " +
+            "from @flow-industries/id/server and render with createStaticFlow().");
     }
     if (currentFlow)
         return currentFlow;
-    const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+    const host = resolveIdHost(options.host);
     const dialogUrl = `${host}/dialog/`;
-    const cookieNames = options.cookies
-        ? cookieNamesFor(window.location.origin)
-        : null;
-    const cookiesSecure = window.location.protocol === "https:";
-    const refreshStore = makeRefreshStore(host, cookieNames
-        ? { name: cookieNames.refresh, secure: cookiesSecure }
-        : undefined);
+    const sessionPath = options.sessionPath ?? DEFAULT_SESSION_PATH;
+    const rpId = options.rpId ??
+        (isLocalHostname(window.location.hostname) ? "localhost" : undefined);
     const chains = options.chains ?? [];
     const getChain = (chainId) => {
         if (chainId == null)
@@ -94,27 +89,6 @@ export function createFlow(options = {}) {
     };
     const accessKeyOptions = resolveAccessKey(options.accessKey);
     const store = createStore({ ...initialFlowState });
-    // One subscription mirrors the JWT into its first-party cookie on every
-    // commit path — refresh, guest mint, login, hydration — and clears it when
-    // logout resets the store. Keeping the mirror here (not in each path) means
-    // no mint site can forget it.
-    if (cookieNames) {
-        let mirroredJwt = null;
-        store.subscribe((s) => {
-            if (s.jwt === mirroredJwt)
-                return;
-            mirroredJwt = s.jwt;
-            if (s.jwt) {
-                writeBrowserCookie(cookieNames.jwt, s.jwt, {
-                    maxAge: JWT_COOKIE_MAX_AGE_S,
-                    secure: cookiesSecure,
-                });
-            }
-            else {
-                clearBrowserCookie(cookieNames.jwt, { secure: cookiesSecure });
-            }
-        });
-    }
     // Seed synchronously so the first client render matches the SSR HTML —
     // hooks read the hydrated user instead of flashing signed-out while a
     // bootstrap refresh runs.
@@ -132,73 +106,90 @@ export function createFlow(options = {}) {
         return dialog;
     };
     /**
-     * Mints a fresh JWT from the user's existing cookie session via the hidden
-     * dialog iframe. The iframe is first-party to id.flow.industries so the
-     * `flow_id.session_token` cookie is sent automatically — this is the only
-     * way to read the session from a third-party app (browsers block reading
-     * cross-origin cookies).
-     *
-     * Returns true if a session was found and state was populated, false if the
-     * user has no active session (in which case the caller should fall back to
-     * `flow.login()`). Never throws — restore failures are treated as "no session".
+     * Commits a session reported by the app's session route. `credential` and
+     * `address` keys are present only when the route rotated the token — the
+     * rotation response is authoritative for signing state; the JWT hot path
+     * knows neither, and overwriting would erase state restored from IDB.
      */
+    function commitSession(session) {
+        store.setState({
+            user: session.user,
+            jwt: session.jwt,
+            ...(session.credential !== undefined
+                ? { credential: session.credential, address: session.address ?? null }
+                : {}),
+        });
+        // A guest carries a null credential; never persist that — the IDB store is
+        // reserved for a real passkey credential and writing null would erase a
+        // previously stored one.
+        if (session.credential) {
+            void idb.set("flow.activeCredential", session.credential);
+        }
+    }
     /**
-     * Mints a fresh session from the first-party refresh token: POSTs it as a
-     * bearer to /api/session/refresh (no cookie, so iOS ITP can't block it),
-     * commits the returned session, and persists the rotated token. Returns false
-     * (never throws) when there's no token or the server rejects it — the caller
-     * then falls back to ensureGuest()/login(). A 401 means the token is dead
-     * (expired, revoked, or reuse-detected), so it's dropped.
+     * Resolves a fresh session from the app's own session route. The refresh
+     * token lives in an HttpOnly cookie only that route's server can read, so
+     * this is the sole silent-session path: the server rotates the token when
+     * the access JWT is expiring and answers with the minted session. Returns
+     * false (never throws) when the visitor is signed out or the route is
+     * unreachable — the caller then falls back to ensureGuest()/login().
      */
-    async function refreshViaToken() {
-        const token = refreshStore.get();
-        if (!token)
+    async function refreshViaSession() {
+        try {
+            const res = await fetch(sessionPath, {
+                headers: { Accept: "application/json" },
+            });
+            if (!res.ok)
+                return false;
+            const { state } = (await res.json());
+            if (!state)
+                return false;
+            commitSession(state);
+            return true;
+        }
+        catch {
             return false;
+        }
+    }
+    /**
+     * One-time handoff of a freshly minted session (dialog login or guest
+     * mint) to the app's server, which verifies the JWT against the issuer's
+     * JWKS and sets the HttpOnly cookies — the refresh token is never stored
+     * where page JavaScript could read it back. Best-effort: without a
+     * reachable session route the in-memory session still works, it just
+     * can't survive a reload.
+     */
+    async function installSession(refreshToken, jwt) {
+        if (!refreshToken || !jwt)
+            return;
         try {
-            const res = await fetch(`${host}/api/session/refresh`, {
+            const res = await fetch(sessionPath, {
                 method: "POST",
-                headers: { Authorization: `Bearer ${token}` },
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ refreshToken, jwt }),
             });
             if (!res.ok) {
-                if (res.status === 401)
-                    refreshStore.clear();
-                return false;
-            }
-            const result = (await res.json());
-            refreshStore.set(result.refreshToken);
-            store.setState({
-                user: result.user,
-                jwt: result.jwt,
-                credential: result.credential,
-                address: result.address,
-            });
-            // A guest carries a null credential; never persist that — the IDB store is
-            // reserved for a real passkey credential and writing null would erase a
-            // previously stored one.
-            if (result.credential) {
-                await idb.set("flow.activeCredential", result.credential);
+                console.warn(`Flow ID: session route ${sessionPath} answered ${res.status}; ` +
+                    "the session will not survive a reload");
             }
-            return true;
         }
         catch {
-            return false;
+            console.warn(`Flow ID: no session route at ${sessionPath}; ` +
+                "the session will not survive a reload");
         }
     }
-    // Every refresh-token POST — boot, ensureGuest, and getToken — funnels through
-    // this one lock so two callers can't present the same stored token at once.
-    // Rotation is single-use: a token replayed after it rotated looks like theft,
-    // tripping server-side reuse detection and revoking the whole lineage (which
-    // would then 401 → clear → re-guest). The lock serializes refreshes across
-    // tabs of the same origin, and the guard short-circuits a caller that arrives
-    // after a concurrent holder already minted a fresh JWT, so no one re-presents
-    // an already-rotated token. refreshViaToken re-reads the token fresh from
-    // storage inside the lock, so a genuinely-second refresh uses the rotated one.
+    // Every session-route call — boot, ensureGuest, and getToken — funnels
+    // through this one lock so concurrent tabs don't fan out parallel
+    // rotations. The server dedupes and the auth server's grace window absorbs
+    // stragglers, but serializing here means the common case is one rotation,
+    // and the guard short-circuits a caller that arrives after a concurrent
+    // holder already minted a fresh JWT.
     async function doRefresh() {
-        return withGuestLock(`flow.id.refresh:${host}`, async () => {
+        return withOriginLock("flow.id.refresh", async () => {
             const current = store.getSnapshot().jwt;
             if (current && !isExpiring(current))
                 return true;
-            return refreshViaToken();
+            return refreshViaSession();
         });
     }
     const refreshJwt = doRefresh;
@@ -247,10 +238,10 @@ export function createFlow(options = {}) {
         if (store.getSnapshot().user)
             return true;
         if (!guestInFlight) {
-            guestInFlight = withGuestLock(`flow.id.guest:${host}`, async () => {
+            guestInFlight = withOriginLock("flow.id.guest", async () => {
                 // Re-check under the lock: another tab may have minted the guest while
-                // we waited. Refresh-first (from this origin's stored token) recovers an
-                // existing session instead of minting a duplicate guest.
+                // we waited. Refresh-first (from this origin's session cookie)
+                // recovers an existing session instead of minting a duplicate guest.
                 if (store.getSnapshot().user)
                     return true;
                 if (await doRefresh())
@@ -259,7 +250,6 @@ export function createFlow(options = {}) {
                     const result = await getDialog().requestSilent(METHODS.guest, []);
                     if (!result.user)
                         return false;
-                    refreshStore.set(result.refreshToken);
                     store.setState({
                         user: result.user,
                         jwt: result.jwt,
@@ -268,6 +258,7 @@ export function createFlow(options = {}) {
                         // address already in state rather than stripping signing.
                         ...(result.user.isGuest ? { credential: null, address: null } : {}),
                     });
+                    await installSession(result.refreshToken, result.jwt);
                     return true;
                 }
                 catch {
@@ -303,7 +294,7 @@ export function createFlow(options = {}) {
             getState: () => store.getSnapshot(),
             getChain,
             getTransport,
-            ...(options.rpId ? { rpId: options.rpId } : {}),
+            ...(rpId ? { rpId } : {}),
             ...(accessKeyOptions?.strict ? { strict: accessKeyOptions.strict } : {}),
         };
     }
@@ -351,7 +342,7 @@ export function createFlow(options = {}) {
             options: loginOpts,
             ...(extraCapabilities ? { extraCapabilities } : {}),
         });
-        refreshStore.set(refreshToken);
+        await installSession(refreshToken, session.jwt);
         if (accessKeyModule && accessKeyPrep && webauthn) {
             await accessKeyModule.finalizeAccessKey({
                 address: session.address,
@@ -369,24 +360,24 @@ export function createFlow(options = {}) {
         return session;
     }
     /**
-     * Performs a full sign-out: tells the server to invalidate the cookie session
-     * (so other Flow apps can't silently restore it), clears local credential and
-     * access-key state, and resets the in-memory store.
+     * Performs a full sign-out: tells the id.flow.industries dialog to
+     * invalidate its cookie session (so other Flow apps can't silently restore
+     * it), tells the app's session route to revoke the refresh lineage and
+     * clear the HttpOnly cookies, then clears local credential and access-key
+     * state and resets the in-memory store.
      *
-     * Server-side sign-out is best-effort — if the network call fails (e.g.,
+     * Both server-side steps are best-effort — if a network call fails (e.g.,
      * offline) we still clear local state so the UI reflects "signed out". The
-     * cookie will eventually expire on its own.
+     * cookies and tokens eventually expire on their own.
      */
     async function logout() {
-        const dialogHost = getDialog();
-        try {
-            await dialogHost.requestSilent(METHODS.signOut, []);
-        }
-        catch {
-            // Server-side sign-out failed (offline?) — still clear local state.
-        }
+        // Both server-side sign-outs are independent and best-effort — if either
+        // fails (offline?) local state still clears so the UI reads "signed out".
+        await Promise.allSettled([
+            getDialog().requestSilent(METHODS.signOut, []),
+            fetch(sessionPath, { method: "DELETE" }),
+        ]);
         await runLogout(store);
-        refreshStore.clear();
         dialog?.close();
         // An autoGuest app is never truly "signed out" — it always wants at least a
         // guest session. Re-mint one so the UI (e.g. the profile widget pill) keeps

package/dist/sdk/client/index.d.ts

@@ -1,3 +1,4 @@
+export { defaultIdHost, isLocalHostname } from "../id-host";
 export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, LoginOptions, MethodName, MountProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";

package/dist/sdk/client/index.js

@@ -1,3 +1,4 @@
+export { defaultIdHost, isLocalHostname } from "../id-host";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { METHODS } from "./methods";

package/dist/sdk/client/profile-button.js

@@ -1,6 +1,6 @@
+import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
 import { bridgeToWindow, makeIframe } from "./iframe-host";
-const DEFAULT_HOST = "https://id.flow.industries";
 const POSITION_STYLE = {
     "top-right": { top: "0", right: "0" },
     "top-left": { top: "0", left: "0" },
@@ -31,7 +31,7 @@ export function createProfileButton(options) {
     if (typeof document === "undefined")
         return { destroy() { } };
     const flow = options.flow ?? getFlow() ?? requireFlow();
-    const host = (options.host ?? flow.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+    const host = resolveIdHost(options.host ?? flow.host);
     const hostOrigin = new URL(host).origin;
     const theme = options.theme ?? "light dark";
     let createdContainer = null;

package/dist/sdk/client/refresh-store.d.ts

@@ -1,23 +1,22 @@
 import type { RefreshCookieConfig } from "../types";
 /**
- * First-party persistence for the rotating refresh token, keyed by `host` so
- * pointing the SDK at a different Flow ID origin (dev vs prod) doesn't
- * collide. Two modes:
- *
- * - With a cookie config (`createFlow({ cookies: true })`) the first-party
- *   cookie is the sole store. The app's own server reads and rotates it
- *   during SSR, so any second copy only drifts behind on each rotation —
- *   and presenting a superseded token looks like theft to the server's
- *   reuse detection, which revokes the whole lineage (self-logout).
- *
- * - Without one (a consumer with no server to share the token with), it
- *   lives in the app's own localStorage: origin-scoped, survives reloads,
- *   and — unlike the old id.flow.industries cookie — never third-party, so
- *   iOS ITP can't block it.
+ * First-party persistence for the rotating refresh token. It lives in the
+ * consumer app's OWN localStorage (origin-scoped), so it survives reloads and
+ * navigations and — unlike the old id.flow.industries cookie — is never a
+ * third-party cookie, so iOS ITP can't block it. Keyed by `host` so pointing
+ * the SDK at a different Flow ID origin (dev vs prod) doesn't collide.
  */
 export interface RefreshStore {
     get(): string | null;
     set(token: string): void;
     clear(): void;
 }
+/**
+ * With a cookie config (`createFlow({ cookies: true })`) the token is
+ * additionally mirrored into a first-party cookie so the app's own server can
+ * refresh the session during SSR. Reads prefer the cookie: the only writer
+ * that updates one side without the other is that server (Set-Cookie only),
+ * and its value is always a successor of whatever localStorage still holds;
+ * every client-side write hits both in the same call.
+ */
 export declare function makeRefreshStore(host: string, cookie?: RefreshCookieConfig): RefreshStore;

package/dist/sdk/client/refresh-store.js

@@ -1,76 +1,66 @@
 import { clearBrowserCookie, REFRESH_COOKIE_MAX_AGE_S, readBrowserCookie, writeBrowserCookie, } from "../cookies";
-function localStorageStore(key) {
-    return {
+/**
+ * With a cookie config (`createFlow({ cookies: true })`) the token is
+ * additionally mirrored into a first-party cookie so the app's own server can
+ * refresh the session during SSR. Reads prefer the cookie: the only writer
+ * that updates one side without the other is that server (Set-Cookie only),
+ * and its value is always a successor of whatever localStorage still holds;
+ * every client-side write hits both in the same call.
+ */
+export function makeRefreshStore(host, cookie) {
+    const key = `flow.id.refresh:${host}`;
+    const readLocal = () => {
+        try {
+            return localStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    };
+    const readCookie = () => {
+        if (!cookie || typeof document === "undefined")
+            return null;
+        return readBrowserCookie(document.cookie, cookie.name);
+    };
+    const store = {
         get() {
-            try {
-                return localStorage.getItem(key);
-            }
-            catch {
-                return null;
-            }
+            return readCookie() ?? readLocal();
         },
         set(token) {
+            // Never persist a missing token: localStorage.setItem coerces undefined
+            // to the literal "undefined", which later reads back as a bogus bearer
+            // and 401s as refresh_token_invalid. Fail safe by ignoring it instead.
+            if (!token)
+                return;
             try {
                 localStorage.setItem(key, token);
             }
             catch { }
+            if (cookie) {
+                writeBrowserCookie(cookie.name, token, {
+                    maxAge: REFRESH_COOKIE_MAX_AGE_S,
+                    secure: cookie.secure,
+                });
+            }
         },
         clear() {
             try {
                 localStorage.removeItem(key);
             }
             catch { }
+            if (cookie)
+                clearBrowserCookie(cookie.name, { secure: cookie.secure });
         },
     };
-}
-function cookieStore(cookie) {
-    return {
-        get() {
-            return readBrowserCookie(document.cookie, cookie.name);
-        },
-        set(token) {
-            writeBrowserCookie(cookie.name, token, {
-                maxAge: REFRESH_COOKIE_MAX_AGE_S,
-                secure: cookie.secure,
-            });
-        },
-        clear() {
-            clearBrowserCookie(cookie.name, { secure: cookie.secure });
-        },
-    };
-}
-/**
- * Never persist a missing token: both backends coerce undefined to the
- * literal "undefined", which later reads back as a bogus bearer and 401s as
- * refresh_token_invalid. Fail safe by ignoring it instead.
- */
-function withMissingTokenGuard(store) {
-    return {
-        ...store,
-        set(token) {
-            if (!token)
-                return;
-            store.set(token);
-        },
-    };
-}
-export function makeRefreshStore(host, cookie) {
-    const legacy = localStorageStore(`flow.id.refresh:${host}`);
-    if (!cookie)
-        return withMissingTokenGuard(legacy);
-    const store = cookieStore(cookie);
-    // One-time takeover from the dual-write SDK (<= 0.10.0), which kept a
-    // localStorage copy: promote it when no cookie exists yet (a session
-    // predating the app's cookie mode), then drop the key — a leftover copy
-    // goes stale on the next SSR rotation and replaying it trips lineage
-    // revocation. Remove this block once every legacy token has rotated or
-    // expired (REFRESH_COOKIE_MAX_AGE_S after 0.11.0 reaches all cookie-mode
-    // apps).
-    const legacyToken = legacy.get();
-    if (legacyToken) {
-        if (!store.get())
-            store.set(legacyToken);
-        legacy.clear();
+    // One-time reconcile so exactly one canonical value exists before the first
+    // refresh: an SSR rotation updates only the cookie, leaving localStorage one
+    // generation behind — presenting that stale token would look like reuse.
+    const fromCookie = readCookie();
+    if (fromCookie && fromCookie !== readLocal()) {
+        try {
+            localStorage.setItem(key, fromCookie);
+        }
+        catch { }
     }
-    return withMissingTokenGuard(store);
+    return store;
 }

package/dist/sdk/client/static-flow.js

@@ -1,5 +1,5 @@
+import { resolveIdHost } from "../id-host";
 import { createRoomsApi } from "./rooms";
-const DEFAULT_HOST = "https://id.flow.industries";
 function unavailable(method) {
     throw new Error(`flow.${method} is not available on a static Flow — it renders ` +
         "server-resolved state only. Interactive methods need the browser " +
@@ -16,7 +16,7 @@ function unavailable(method) {
  * API); anything interactive (login, dialog, signing) throws.
  */
 export function createStaticFlow(state, options = {}) {
-    const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+    const host = resolveIdHost(options.host);
     const snapshot = Object.freeze({
         user: state?.user ?? null,
         jwt: state?.jwt ?? null,

package/dist/sdk/cookies.d.ts

@@ -1,8 +1,8 @@
 /**
- * First-party cookie names and (de)serialization shared by the browser SDK
- * (which persists the session into cookies) and the server helper (which reads
- * them per-request to render auth-aware UI without a client round-trip).
- * Isomorphic: no browser globals at import time.
+ * First-party session cookie names and (de)serialization. Cookies are owned
+ * exclusively by the app's server (the SSR resolver and the session route) —
+ * page JavaScript never reads or writes them, which is what lets them be
+ * HttpOnly. Isomorphic module: no browser globals at import time.
  */
 import type { FlowCookieNames } from "./types";
 export declare const JWT_COOKIE_MAX_AGE_S: number;
@@ -17,10 +17,10 @@ export declare const REFRESH_COOKIE_MAX_AGE_S: number;
  */
 export declare function cookieNamesFor(origin: string): FlowCookieNames;
 /**
- * Builds a Set-Cookie value. Host-only (no Domain), `SameSite=Lax`, `Path=/`;
- * `Secure` everywhere except plain-http localhost (Safari drops Secure
- * cookies set over http). Never HttpOnly — the browser SDK reads and writes
- * these same cookies.
+ * Builds a Set-Cookie value. Host-only (no Domain), `SameSite=Lax`, `Path=/`,
+ * always `HttpOnly` (only the app's server touches these cookies — an XSS
+ * payload can never read the refresh token); `Secure` everywhere except
+ * plain-http localhost (Safari drops Secure cookies set over http).
  */
 export declare function serializeCookie(name: string, value: string, opts: {
     maxAge: number;
@@ -32,14 +32,3 @@ export declare function clearCookieString(name: string, opts: {
 }): string;
 /** Parses a Cookie request header into name → value; first occurrence wins (RFC 6265 practice). */
 export declare function parseCookieHeader(header: string | null | undefined): Record<string, string>;
-/** Reads one cookie from a `document.cookie` string. */
-export declare function readBrowserCookie(cookieString: string, name: string): string | null;
-/** Writes a cookie in the browser; no-op outside it. */
-export declare function writeBrowserCookie(name: string, value: string, opts: {
-    maxAge: number;
-    secure: boolean;
-}): void;
-/** Deletes a cookie in the browser; no-op outside it. */
-export declare function clearBrowserCookie(name: string, opts: {
-    secure: boolean;
-}): void;

package/dist/sdk/cookies.js

@@ -1,8 +1,8 @@
 /**
- * First-party cookie names and (de)serialization shared by the browser SDK
- * (which persists the session into cookies) and the server helper (which reads
- * them per-request to render auth-aware UI without a client round-trip).
- * Isomorphic: no browser globals at import time.
+ * First-party session cookie names and (de)serialization. Cookies are owned
+ * exclusively by the app's server (the SSR resolver and the session route) —
+ * page JavaScript never reads or writes them, which is what lets them be
+ * HttpOnly. Isomorphic module: no browser globals at import time.
  */
 export const JWT_COOKIE_MAX_AGE_S = 60 * 60;
 export const REFRESH_COOKIE_MAX_AGE_S = 30 * 24 * 60 * 60;
@@ -34,14 +34,14 @@ export function cookieNamesFor(origin) {
     };
 }
 /**
- * Builds a Set-Cookie value. Host-only (no Domain), `SameSite=Lax`, `Path=/`;
- * `Secure` everywhere except plain-http localhost (Safari drops Secure
- * cookies set over http). Never HttpOnly — the browser SDK reads and writes
- * these same cookies.
+ * Builds a Set-Cookie value. Host-only (no Domain), `SameSite=Lax`, `Path=/`,
+ * always `HttpOnly` (only the app's server touches these cookies — an XSS
+ * payload can never read the refresh token); `Secure` everywhere except
+ * plain-http localhost (Safari drops Secure cookies set over http).
  */
 export function serializeCookie(name, value, opts) {
     const secure = opts.secure ? "; Secure" : "";
-    return `${name}=${value}; Path=/; SameSite=Lax; Max-Age=${opts.maxAge}${secure}`;
+    return `${name}=${value}; Path=/; SameSite=Lax; Max-Age=${opts.maxAge}; HttpOnly${secure}`;
 }
 /** Builds a Set-Cookie value that deletes the cookie. */
 export function clearCookieString(name, opts) {
@@ -63,19 +63,3 @@ export function parseCookieHeader(header) {
     }
     return out;
 }
-/** Reads one cookie from a `document.cookie` string. */
-export function readBrowserCookie(cookieString, name) {
-    return parseCookieHeader(cookieString)[name] ?? null;
-}
-/** Writes a cookie in the browser; no-op outside it. */
-export function writeBrowserCookie(name, value, opts) {
-    if (typeof document === "undefined")
-        return;
-    document.cookie = serializeCookie(name, value, opts);
-}
-/** Deletes a cookie in the browser; no-op outside it. */
-export function clearBrowserCookie(name, opts) {
-    if (typeof document === "undefined")
-        return;
-    document.cookie = clearCookieString(name, opts);
-}