@flow-industries/id 0.10.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/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 mirrors 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 mirrors 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);
-}

package/dist/sdk/id-host.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared defaults for the first-party session plumbing. The browser client,
+ * the SSR resolver, and the session route all resolve the Flow ID origin and
+ * the app-local session path from here, so consumer apps agree on both
+ * without carrying any per-app configuration.
+ */
+export declare const DEFAULT_ISSUER_URL = "https://id.flow.industries";
+/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+export declare const LOCAL_ISSUER_URL = "http://localhost:5175";
+/**
+ * Path of the first-party session route every app serves from its own origin
+ * (GET resolve, POST install, DELETE sign-out). The browser client and the
+ * route registration must agree on it; override via `createFlow({ sessionPath })`
+ * plus the route's `path` option only when an app cannot claim this path.
+ */
+export declare const DEFAULT_SESSION_PATH = "/flow/session";
+export declare function isLocalHostname(hostname: string): boolean;
+/**
+ * The app's public origin — the JWT audience and what cookie names derive
+ * from. The `APP_ORIGIN` env var wins (mandatory behind a TLS-terminating
+ * proxy, where the request origin is the internal http one); dev falls back
+ * to the request's own origin.
+ */
+export declare function defaultAudience(requestOrigin: string): string;
+/**
+ * Resolves the Flow ID origin for the current runtime: the `FLOW_ID_HOST`
+ * env var wins on servers, a localhost app talks to the local auth stack,
+ * everything else uses production. Pass the app origin when resolving on
+ * behalf of a request (servers have no `window`).
+ */
+export declare function defaultIdHost(appOrigin?: string): string;
+/**
+ * An explicit host override or the runtime default, normalized (no trailing
+ * slash) so callers can append paths without producing `//api/...` URLs.
+ */
+export declare function resolveIdHost(override?: string | null, appOrigin?: string): string;

package/dist/sdk/id-host.js

@@ -0,0 +1,57 @@
+/**
+ * Shared defaults for the first-party session plumbing. The browser client,
+ * the SSR resolver, and the session route all resolve the Flow ID origin and
+ * the app-local session path from here, so consumer apps agree on both
+ * without carrying any per-app configuration.
+ */
+export const DEFAULT_ISSUER_URL = "https://id.flow.industries";
+/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+export const LOCAL_ISSUER_URL = "http://localhost:5175";
+/**
+ * Path of the first-party session route every app serves from its own origin
+ * (GET resolve, POST install, DELETE sign-out). The browser client and the
+ * route registration must agree on it; override via `createFlow({ sessionPath })`
+ * plus the route's `path` option only when an app cannot claim this path.
+ */
+export const DEFAULT_SESSION_PATH = "/flow/session";
+export function isLocalHostname(hostname) {
+    return (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]");
+}
+/**
+ * The app's public origin — the JWT audience and what cookie names derive
+ * from. The `APP_ORIGIN` env var wins (mandatory behind a TLS-terminating
+ * proxy, where the request origin is the internal http one); dev falls back
+ * to the request's own origin.
+ */
+export function defaultAudience(requestOrigin) {
+    return ((typeof process !== "undefined" ? process.env?.APP_ORIGIN : undefined) ??
+        requestOrigin);
+}
+/**
+ * Resolves the Flow ID origin for the current runtime: the `FLOW_ID_HOST`
+ * env var wins on servers, a localhost app talks to the local auth stack,
+ * everything else uses production. Pass the app origin when resolving on
+ * behalf of a request (servers have no `window`).
+ */
+export function defaultIdHost(appOrigin) {
+    if (typeof process !== "undefined" && process.env?.FLOW_ID_HOST) {
+        return process.env.FLOW_ID_HOST;
+    }
+    const origin = appOrigin ??
+        (typeof window !== "undefined" ? window.location.origin : undefined);
+    if (origin) {
+        try {
+            if (isLocalHostname(new URL(origin).hostname))
+                return LOCAL_ISSUER_URL;
+        }
+        catch { }
+    }
+    return DEFAULT_ISSUER_URL;
+}
+/**
+ * An explicit host override or the runtime default, normalized (no trailing
+ * slash) so callers can append paths without producing `//api/...` URLs.
+ */
+export function resolveIdHost(override, appOrigin) {
+    return (override ?? defaultIdHost(appOrigin)).replace(/\/+$/, "");
+}

package/dist/sdk/server.d.ts

@@ -1,23 +1,13 @@
 import type { ResolvedFlowSession, ResolveSessionOptions } from "./types";
-export type { FlowSessionState, ResolvedFlowSession, ResolveSessionOptions, } from "./types";
+export { createSessionHandler, handleSessionRequest } from "./session-route";
+export type { FlowSessionState, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./types";
 export { verifyFlowJWT } from "./verify";
 /**
- * Resolves the visitor's Flow session from the request's Cookie header — the
- * server-side counterpart of `createFlow({ cookies: true })`, for rendering
- * auth-aware UI without a client round-trip.
- *
- * Resolution order:
- *  1. A still-fresh JWT cookie verifies locally against the issuer's JWKS
- *     (cached per process) — the hot path, no auth-server call, no cookies
- *     to set.
- *  2. Otherwise a refresh cookie is presented to `/api/session/refresh`,
- *     which ROTATES it — append every entry of `setCookies` to the response
- *     or the client is left holding a dead predecessor. A definitive
- *     rejection (401/403) yields clearing cookies instead; a network failure
- *     leaves the cookies alone so a later request can retry.
- *  3. Neither cookie → signed-out `state: null`.
- *
- * Feed `state` into the SSR payload and `createFlow({ initialState })` so the
- * hydrated client renders it without a second refresh.
+ * Resolves the visitor's Flow session from the request's Cookie header for
+ * SSR: render auth-aware UI without a client round-trip, then feed `state`
+ * into the SSR payload and `createFlow({ initialState })` so the hydrated
+ * client renders it without a second refresh. Append every entry of
+ * `setCookies` to the response or the client is left holding a dead
+ * predecessor (a server-side refresh ROTATES the token).
  */
 export declare function resolveSession(cookieHeader: string | null | undefined, opts: ResolveSessionOptions): Promise<ResolvedFlowSession>;