@flow-industries/id 0.9.0 → 0.10.0

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

@@ -1,3 +1,5 @@
+import { clearBrowserCookie, cookieNamesFor, JWT_COOKIE_MAX_AGE_S, writeBrowserCookie, } from "../cookies";
+import { isExpiring } from "../token-expiry";
 import { createDialogHost } from "./dialog-host";
 import { idb } from "./idb";
 import { METHODS } from "./methods";
@@ -6,31 +8,6 @@ import { createRoomsApi } from "./rooms";
 import { credentialToAddress, restoreCredential, runLogin, runLogout, } from "./session";
 import { createStore, initialFlowState } from "./store";
 const DEFAULT_HOST = "https://id.flow.industries";
-// Refresh a little before the JWT's `exp` so a token handed out by getToken()
-// is still valid by the time it reaches the relying party, absorbing request
-// latency and minor client/server clock skew.
-const EXPIRY_SKEW_MS = 60_000;
-/** Reads the `exp` (seconds since epoch) from a JWT, or null if unreadable. */
-function jwtExp(token) {
-    const parts = token.split(".");
-    if (parts.length !== 3)
-        return null;
-    try {
-        const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-        const payload = JSON.parse(atob(padded));
-        return typeof payload.exp === "number" ? payload.exp : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** True if the token is missing an exp, already expired, or within the skew. */
-function isExpiring(token) {
-    const exp = jwtExp(token);
-    if (exp === null)
-        return true;
-    return Date.now() >= exp * 1000 - EXPIRY_SKEW_MS;
-}
 /**
  * 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
@@ -89,11 +66,22 @@ export function createFlow(options = {}) {
     // and IDB writes while components/hooks that captured it keep reading
     // 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().");
+    }
     if (currentFlow)
         return currentFlow;
     const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
     const dialogUrl = `${host}/dialog/`;
-    const refreshStore = makeRefreshStore(host);
+    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 chains = options.chains ?? [];
     const getChain = (chainId) => {
         if (chainId == null)
@@ -106,6 +94,37 @@ 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.
+    if (options.initialState) {
+        store.setState({
+            user: options.initialState.user,
+            jwt: options.initialState.jwt,
+            address: options.initialState.address ?? null,
+        });
+    }
     let dialog = null;
     const getDialog = () => {
         if (!dialog)
@@ -262,6 +281,11 @@ export function createFlow(options = {}) {
     }
     void (async () => {
         await restoreCredential(store);
+        // A fresh hydrated JWT means the server already refreshed this request —
+        // running doRefresh() here would rotate a second time for nothing.
+        const hydrated = store.getSnapshot().jwt;
+        if (hydrated && !isExpiring(hydrated))
+            return;
         if (options.autoRestore !== false) {
             const restored = await doRefresh();
             // ensureGuest re-checks (refresh-first) under a cross-tab lock before

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

@@ -1,6 +1,7 @@
-export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowState, FlowUser, LoginOptions, MethodName, MountProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
+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";
 export { METHODS } from "./methods";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
+export { createStaticFlow } from "./static-flow";

package/dist/sdk/client/index.js

@@ -3,3 +3,4 @@ export { createDialogHost } from "./dialog-host";
 export { METHODS } from "./methods";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
+export { createStaticFlow } from "./static-flow";

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

@@ -1,3 +1,4 @@
+import type { RefreshCookieConfig } from "../types";
 /**
  * First-party persistence for the rotating refresh token. It lives in the
  * consumer app's OWN localStorage (origin-scoped), so it survives reloads and
@@ -10,4 +11,12 @@ export interface RefreshStore {
     set(token: string): void;
     clear(): void;
 }
-export declare function makeRefreshStore(host: string): RefreshStore;
+/**
+ * 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,13 +1,30 @@
-export function makeRefreshStore(host) {
+import { clearBrowserCookie, REFRESH_COOKIE_MAX_AGE_S, readBrowserCookie, writeBrowserCookie, } from "../cookies";
+/**
+ * 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}`;
-    return {
+    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
@@ -19,12 +36,31 @@ export function makeRefreshStore(host) {
                 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 });
         },
     };
+    // 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 store;
 }

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

@@ -0,0 +1,14 @@
+import type { Flow, FlowSessionState } from "../types";
+/**
+ * A frozen, per-request Flow for server rendering: hooks and components read
+ * the state `resolveSession()` resolved for THIS request, so the SSR HTML
+ * matches what the hydrated client (seeded via `createFlow({ initialState })`)
+ * renders first. Never touches the module singleton — concurrent requests
+ * must not share auth state.
+ *
+ * Reads work (`user`, `jwt`, `getToken`, `getState`, `rooms` — a plain fetch
+ * API); anything interactive (login, dialog, signing) throws.
+ */
+export declare function createStaticFlow(state: FlowSessionState | null, options?: {
+    host?: string;
+}): Flow;

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

@@ -0,0 +1,65 @@
+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 " +
+        "client from createFlow().");
+}
+/**
+ * A frozen, per-request Flow for server rendering: hooks and components read
+ * the state `resolveSession()` resolved for THIS request, so the SSR HTML
+ * matches what the hydrated client (seeded via `createFlow({ initialState })`)
+ * renders first. Never touches the module singleton — concurrent requests
+ * must not share auth state.
+ *
+ * Reads work (`user`, `jwt`, `getToken`, `getState`, `rooms` — a plain fetch
+ * API); anything interactive (login, dialog, signing) throws.
+ */
+export function createStaticFlow(state, options = {}) {
+    const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+    const snapshot = Object.freeze({
+        user: state?.user ?? null,
+        jwt: state?.jwt ?? null,
+        credential: null,
+        address: state?.address ?? null,
+    });
+    const getToken = async () => snapshot.jwt;
+    return {
+        get user() {
+            return snapshot.user;
+        },
+        get jwt() {
+            return snapshot.jwt;
+        },
+        get credential() {
+            return snapshot.credential;
+        },
+        get address() {
+            return snapshot.address;
+        },
+        get isAuthenticated() {
+            return snapshot.user !== null;
+        },
+        get isGuest() {
+            return snapshot.user?.isGuest === true;
+        },
+        login: () => unavailable("login"),
+        logout: () => unavailable("logout"),
+        restore: async () => false,
+        ensureGuest: () => unavailable("ensureGuest"),
+        refreshJwt: async () => false,
+        getToken,
+        rooms: createRoomsApi(host, getToken),
+        signMessage: () => unavailable("signMessage"),
+        signTypedData: () => unavailable("signTypedData"),
+        sendTransaction: () => unavailable("sendTransaction"),
+        sendCalls: () => unavailable("sendCalls"),
+        walletClient: () => unavailable("walletClient"),
+        subscribe: () => () => { },
+        getState: () => snapshot,
+        get dialog() {
+            return unavailable("dialog");
+        },
+        host,
+    };
+}

package/dist/sdk/cookies.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import type { FlowCookieNames } from "./types";
+export declare const JWT_COOKIE_MAX_AGE_S: number;
+export declare const REFRESH_COOKIE_MAX_AGE_S: number;
+/**
+ * Cookie names for an app origin. On https the `__Host-` prefix makes the
+ * browser enforce Secure + Path=/ + host-only, so no sibling subdomain can
+ * plant a shadowing cookie with `Domain=` (session fixation). On localhost
+ * (plain http, where `__Host-` is unavailable) the port is folded into the
+ * name instead — cookie jars ignore ports, so without the suffix parallel
+ * dev stacks on different ports would overwrite each other's sessions.
+ */
+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.
+ */
+export declare function serializeCookie(name: string, value: string, opts: {
+    maxAge: number;
+    secure: boolean;
+}): string;
+/** Builds a Set-Cookie value that deletes the cookie. */
+export declare function clearCookieString(name: string, opts: {
+    secure: boolean;
+}): 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

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+export const JWT_COOKIE_MAX_AGE_S = 60 * 60;
+export const REFRESH_COOKIE_MAX_AGE_S = 30 * 24 * 60 * 60;
+/**
+ * Cookie names for an app origin. On https the `__Host-` prefix makes the
+ * browser enforce Secure + Path=/ + host-only, so no sibling subdomain can
+ * plant a shadowing cookie with `Domain=` (session fixation). On localhost
+ * (plain http, where `__Host-` is unavailable) the port is folded into the
+ * name instead — cookie jars ignore ports, so without the suffix parallel
+ * dev stacks on different ports would overwrite each other's sessions.
+ */
+export function cookieNamesFor(origin) {
+    let prefix = "";
+    let suffix = "";
+    try {
+        const url = new URL(origin);
+        if (url.protocol === "https:")
+            prefix = "__Host-";
+        const local = url.hostname === "localhost" ||
+            url.hostname === "127.0.0.1" ||
+            url.hostname === "[::1]";
+        if (local && url.port)
+            suffix = `_p${url.port}`;
+    }
+    catch { }
+    return {
+        jwt: `${prefix}flow_id.jwt${suffix}`,
+        refresh: `${prefix}flow_id.refresh${suffix}`,
+    };
+}
+/**
+ * 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.
+ */
+export function serializeCookie(name, value, opts) {
+    const secure = opts.secure ? "; Secure" : "";
+    return `${name}=${value}; Path=/; SameSite=Lax; Max-Age=${opts.maxAge}${secure}`;
+}
+/** Builds a Set-Cookie value that deletes the cookie. */
+export function clearCookieString(name, opts) {
+    return serializeCookie(name, "", { maxAge: 0, secure: opts.secure });
+}
+/** Parses a Cookie request header into name → value; first occurrence wins (RFC 6265 practice). */
+export function parseCookieHeader(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name || name in out)
+            continue;
+        out[name] = part.slice(eq + 1).trim();
+    }
+    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/server.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedFlowSession, ResolveSessionOptions } from "./types";
+export type { FlowSessionState, ResolvedFlowSession, ResolveSessionOptions, } 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.
+ */
+export declare function resolveSession(cookieHeader: string | null | undefined, opts: ResolveSessionOptions): Promise<ResolvedFlowSession>;

package/dist/sdk/server.js

@@ -0,0 +1,200 @@
+import { clearCookieString, cookieNamesFor, JWT_COOKIE_MAX_AGE_S, parseCookieHeader, REFRESH_COOKIE_MAX_AGE_S, serializeCookie, } from "./cookies";
+import { isExpiring } from "./token-expiry";
+import { verifyFlowJWT } from "./verify";
+export { verifyFlowJWT } from "./verify";
+const DEFAULT_ISSUER_URL = "https://id.flow.industries";
+function claimsToUser(claims) {
+    return {
+        id: claims.sub,
+        username: typeof claims.username === "string" ? claims.username : "",
+        // Fail-safe: only an explicit `false` marks a full account; a missing or
+        // mangled claim must never grant full privileges.
+        isGuest: claims.guest !== false,
+    };
+}
+async function refreshSession(issuerUrl, token) {
+    try {
+        const res = await fetch(`${issuerUrl}/api/session/refresh`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (res.status === 401 || res.status === 403)
+            return "dead";
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+// Dedupe a same-instance SSR fan-out (parallel requests carrying the same
+// cookie) into one rotation. Settled results are retained briefly so a
+// request that lands after the rotation but before the browser applied the
+// Set-Cookie is served the same successor instead of re-presenting a dead
+// token; the auth server's grace window covers presenters this map can't see
+// (other replicas, other machines).
+const REFRESH_RESULT_TTL_MS = 30_000;
+const refreshInFlight = new Map();
+function refreshOnce(issuerUrl, token) {
+    const key = `${issuerUrl}\n${token}`;
+    let flight = refreshInFlight.get(key);
+    if (!flight) {
+        flight = refreshSession(issuerUrl, token);
+        refreshInFlight.set(key, flight);
+        void flight.finally(() => {
+            const timer = setTimeout(() => refreshInFlight.delete(key), REFRESH_RESULT_TTL_MS);
+            timer.unref?.();
+        });
+    }
+    return flight;
+}
+// jose verification-class failures (bad signature, expired, wrong audience,
+// unknown key) mean the token itself is unacceptable; anything else — JWKS
+// fetch failure, timeouts — is transient infrastructure trouble, and falling
+// through to a rotation there would turn a JWKS outage into a rotation storm
+// against the same struggling server.
+function isJwtVerificationFailure(err) {
+    const code = err?.code;
+    if (typeof code !== "string")
+        return false;
+    return (code.startsWith("ERR_JWT") ||
+        code.startsWith("ERR_JWS") ||
+        code === "ERR_JWKS_NO_MATCHING_KEY" ||
+        code === "ERR_JWKS_MULTIPLE_MATCHING_KEYS");
+}
+async function fetchProfile(issuerUrl, jwt, audience) {
+    try {
+        const res = await fetch(`${issuerUrl}/api/session/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token: jwt, audience }),
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        return data.payload?.profile ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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.
+ */
+export async function resolveSession(cookieHeader, opts) {
+    const issuerUrl = (opts.issuerUrl ?? DEFAULT_ISSUER_URL).replace(/\/+$/, "");
+    const names = cookieNamesFor(opts.audience);
+    const secure = opts.audience.startsWith("https:");
+    const cookies = parseCookieHeader(cookieHeader);
+    const jwt = cookies[names.jwt];
+    if (jwt && !isExpiring(jwt)) {
+        try {
+            const claims = await verifyFlowJWT(jwt, {
+                audience: opts.audience,
+                issuerUrl,
+            });
+            const state = {
+                user: claimsToUser(claims),
+                jwt,
+                address: null,
+            };
+            const profile = opts.profile
+                ? await fetchProfile(issuerUrl, jwt, opts.audience)
+                : undefined;
+            return {
+                state,
+                claims,
+                setCookies: [],
+                ...(profile ? { profile } : {}),
+            };
+        }
+        catch (err) {
+            if (!isJwtVerificationFailure(err)) {
+                return { state: null, claims: null, setCookies: [] };
+            }
+        }
+    }
+    const refreshToken = cookies[names.refresh];
+    if (!refreshToken)
+        return { state: null, claims: null, setCookies: [] };
+    const result = await refreshOnce(issuerUrl, refreshToken);
+    if (result === "dead") {
+        return {
+            state: null,
+            claims: null,
+            setCookies: [
+                clearCookieString(names.jwt, { secure }),
+                clearCookieString(names.refresh, { secure }),
+            ],
+        };
+    }
+    if (!result)
+        return { state: null, claims: null, setCookies: [] };
+    const successorCookies = [
+        serializeCookie(names.jwt, result.jwt, {
+            maxAge: JWT_COOKIE_MAX_AGE_S,
+            secure,
+        }),
+        serializeCookie(names.refresh, result.refreshToken, {
+            maxAge: REFRESH_COOKIE_MAX_AGE_S,
+            secure,
+        }),
+    ];
+    // Never trust a minted session unverified: the refresh endpoint binds the
+    // JWT to the token ROW's audience, so a cookie planted by a sibling
+    // subdomain (or a misconfigured audience) would otherwise resolve into a
+    // wrong-app session. Verification failure ⇒ clear the cookies; a transient
+    // JWKS failure still hands the successor over (the rotation already
+    // happened) but renders signed-out rather than trusting it.
+    let claims;
+    try {
+        claims = await verifyFlowJWT(result.jwt, {
+            audience: opts.audience,
+            issuerUrl,
+        });
+    }
+    catch (err) {
+        if (isJwtVerificationFailure(err)) {
+            return {
+                state: null,
+                claims: null,
+                setCookies: [
+                    clearCookieString(names.jwt, { secure }),
+                    clearCookieString(names.refresh, { secure }),
+                ],
+            };
+        }
+        return { state: null, claims: null, setCookies: successorCookies };
+    }
+    const state = {
+        user: result.user,
+        jwt: result.jwt,
+        address: result.address,
+    };
+    const profile = opts.profile
+        ? await fetchProfile(issuerUrl, result.jwt, opts.audience)
+        : undefined;
+    return {
+        state,
+        claims,
+        setCookies: successorCookies,
+        ...(profile ? { profile } : {}),
+    };
+}

package/dist/sdk/token-expiry.d.ts

@@ -0,0 +1,5 @@
+export declare const EXPIRY_SKEW_MS = 60000;
+/** Reads the `exp` (seconds since epoch) from a JWT, or null if unreadable. */
+export declare function jwtExp(token: string): number | null;
+/** True if the token is missing an exp, already expired, or within the skew. */
+export declare function isExpiring(token: string): boolean;

package/dist/sdk/token-expiry.js

@@ -0,0 +1,25 @@
+// Refresh a little before the JWT's `exp` so a token handed out to a caller
+// is still valid by the time it reaches the relying party, absorbing request
+// latency and minor client/server clock skew.
+export const EXPIRY_SKEW_MS = 60_000;
+/** Reads the `exp` (seconds since epoch) from a JWT, or null if unreadable. */
+export function jwtExp(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const padded = (parts[1] ?? "").replace(/-/g, "+").replace(/_/g, "/");
+        const payload = JSON.parse(atob(padded));
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if the token is missing an exp, already expired, or within the skew. */
+export function isExpiring(token) {
+    const exp = jwtExp(token);
+    if (exp === null)
+        return true;
+    return Date.now() >= exp * 1000 - EXPIRY_SKEW_MS;
+}

package/dist/sdk/types/events.d.ts

@@ -8,7 +8,7 @@ export type AuthOutcome = "success" | "failure" | "info";
 export type AuthMode = "sign-up" | "sign-in";
 /** Client-only funnel steps reported via the `/api/events` beacon. */
 export type FunnelStep = "mode_selected" | "email_entered" | "ceremony_started" | "done_shown";
-export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.audience.rejected" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.done_shown";
+export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.refresh.grace" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.audience.rejected" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.done_shown";
 export type AuthErrorCode = "username_taken" | "credential_taken" | "email_taken" | "email_not_verified" | "no_email" | "image_upload_forbidden" | "image_upload_rate_limited" | "invalid_image_type" | "image_too_large" | "image_upload_failed" | "otp_invalid" | "otp_expired" | "otp_attempts_exceeded" | "otp_resend_cooldown" | "otp_resend_limit" | "otp_global_limit" | "otp_send_failed" | "challenge_expired" | "unknown_credential" | "invalid_assertion_type" | "invalid_assertion_origin" | "user_verification_required" | "invalid_signature" | "user_not_found" | "missing_audience" | "audience_not_allowed" | "audience_mismatch" | "no_session" | "no_passkey" | "refresh_token_invalid" | "refresh_token_expired" | "refresh_reuse_detected" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "internal_error";
 /** One flat record per event = one row in the `auth_events` stream. */
 export interface AuthEventRecord {

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

@@ -5,6 +5,7 @@ export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfi
 export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { CreateRoomInput, MyRooms, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, UpdateRoomInput, VerifyRoomContext, } from "./rooms";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowIdProviderProps, FlowState, Listener, LoginOptions, MountProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
+export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, Listener, LoginOptions, MountProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, RefreshCookieConfig, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
+export type { ResolvedFlowSession, ResolveSessionOptions } from "./server";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
 export type { ActionDayContext, ActionEventKind, ActionSessionState, ActiveActionResponse, LevelProgress, PublicProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/sdk.d.ts

@@ -71,6 +71,22 @@ export type CreateFlowOptions = {
      * data keyed on the Flow user id survives. See `ensureGuest`.
      */
     autoGuest?: boolean;
+    /**
+     * If true, the JWT and the rotating refresh token are mirrored into
+     * first-party cookies on the app's own origin so the app's server can
+     * resolve the session per-request (see `@flow-industries/id/server`).
+     * Off by default — a backend that never reads them shouldn't start
+     * receiving refresh tokens on every request.
+     */
+    cookies?: boolean;
+    /**
+     * Session state resolved server-side (via `resolveSession`) to seed the
+     * store synchronously, so the first client render matches the SSR HTML and
+     * no bootstrap refresh runs while the hydrated JWT is still fresh. Pass
+     * `null` for a known signed-out visitor; omit for the default client-only
+     * bootstrap.
+     */
+    initialState?: FlowSessionState | null;
 };
 export type FlowState = {
     user: FlowUser | null;
@@ -78,6 +94,30 @@ export type FlowState = {
     credential: FlowCredential | null;
     address: Address | null;
 };
+/**
+ * The auth state a server can resolve per-request from the first-party
+ * cookies: identity + access token, but never the credential (passkeys live
+ * in the browser's IndexedDB only).
+ */
+export type FlowSessionState = {
+    user: FlowUser;
+    jwt: string;
+    /**
+     * Null whenever the session came from a locally-verified JWT — the common
+     * SSR hot path — because the claim set carries no address. The client
+     * restores it from the stored passkey credential after hydration; never
+     * server-render wallet UI from this field.
+     */
+    address: Address | null;
+};
+export type FlowCookieNames = {
+    jwt: string;
+    refresh: string;
+};
+export type RefreshCookieConfig = {
+    name: string;
+    secure: boolean;
+};
 export type LoginOptions = {
     mode?: "iframe" | "popup";
     signUp?: boolean;

package/dist/sdk/types/server.d.ts

@@ -0,0 +1,28 @@
+import type { VerifiedFlowJWT } from "./auth";
+import type { FlowSessionState } from "./sdk";
+import type { PublicProfile } from "./xp";
+export type ResolveSessionOptions = {
+    /** The calling app's origin, e.g. `https://flow.game` — must match the JWT `aud`. */
+    audience: string;
+    /** Flow ID origin; defaults to `https://id.flow.industries`. */
+    issuerUrl?: string;
+    /**
+     * Also fetch the public profile (avatar, tier, level) for a resolved
+     * session via `/api/session/verify` — one extra round-trip; off by default.
+     */
+    profile?: boolean;
+};
+export type ResolvedFlowSession = {
+    /** Resolved session, or null for a signed-out visitor. */
+    state: FlowSessionState | null;
+    /** Verified JWT claims when the session came from a locally-verified JWT. */
+    claims: VerifiedFlowJWT | null;
+    /**
+     * Set-Cookie values to append to the response: rotation successors after a
+     * server-side refresh, or expired-cookie clears after a dead token. Empty on
+     * the JWT-valid hot path.
+     */
+    setCookies: string[];
+    /** Public profile, only when requested via `profile: true` and resolvable. */
+    profile?: PublicProfile;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -29,6 +29,10 @@
     "./verify": {
       "types": "./dist/sdk/verify.d.ts",
       "import": "./dist/sdk/verify.js"
+    },
+    "./server": {
+      "types": "./dist/sdk/server.d.ts",
+      "import": "./dist/sdk/server.js"
     }
   },
   "files": [