@flow-industries/id 0.8.1 → 0.10.0

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

@@ -1,35 +1,13 @@
+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";
 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";
-// 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
@@ -88,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)
@@ -105,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)
@@ -261,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
@@ -309,14 +334,16 @@ export function createFlow(options = {}) {
         }
         // When the current session is a guest, forward its access token so a
         // sign-up upgrades that guest in place even where the guest cookie is
-        // unreadable (the iOS top-level sign-up popup). The server verifies it
-        // before honoring it, so an app that never becomes a guest sends nothing.
-        const snapshot = store.getSnapshot();
-        if (snapshot.user?.isGuest && snapshot.jwt) {
-            extraCapabilities = {
-                ...(extraCapabilities ?? {}),
-                guestToken: snapshot.jwt,
-            };
+        // unreadable (the iOS top-level sign-up popup). Mint via getToken() rather
+        // than reading store.jwt directly: the cached JWT can be up to an hour stale
+        // on a long-idle tab, and an expired token fails server verification — the
+        // guest would then be registered as a fresh account instead of upgraded.
+        // An app that never becomes a guest forwards nothing.
+        if (store.getSnapshot().user?.isGuest) {
+            const guestToken = await getToken();
+            if (guestToken) {
+                extraCapabilities = { ...(extraCapabilities ?? {}), guestToken };
+            }
         }
         const { session, webauthn, refreshToken } = await runLogin({
             dialog: dialogHost,
@@ -392,6 +419,7 @@ export function createFlow(options = {}) {
         ensureGuest,
         refreshJwt,
         getToken,
+        rooms: createRoomsApi(host, getToken),
         signMessage: async (args) => {
             const mod = await import("./signing");
             return mod.signMessage(buildSigningContext(), args);

package/dist/sdk/client/dialog-host.js

@@ -1,4 +1,3 @@
-import * as Messenger from "../dialog/remote/Messenger";
 import { bridgeToWindow, makeIframe } from "./iframe-host";
 const HIDDEN_STYLE = {
     position: "fixed",

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

@@ -1,5 +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

@@ -2,3 +2,5 @@ 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/profile-button.js

@@ -1,4 +1,3 @@
-import * as Messenger from "../dialog/remote/Messenger";
 import { getFlow, requireFlow } from "./create-flow";
 import { bridgeToWindow, makeIframe } from "./iframe-host";
 const DEFAULT_HOST = "https://id.flow.industries";

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/rooms.d.ts

@@ -0,0 +1,14 @@
+import type { RoomsApi } from "../types";
+/** Thrown on any non-2xx rooms response; `reason` carries the machine-readable
+ * cause when the API provides one (e.g. "banned", "private"). */
+export declare class RoomsRequestError extends Error {
+    readonly status: number;
+    readonly reason?: string | undefined;
+    constructor(status: number, message: string, reason?: string | undefined);
+}
+/**
+ * Thin typed client for the room registry, bound to a host and the Flow
+ * token supplier. Public reads work signed-out; mutations attach the caller's
+ * bearer and fail fast with a 401-shaped error when no session exists.
+ */
+export declare function createRoomsApi(host: string, getToken: () => Promise<string | null>): RoomsApi;

package/dist/sdk/client/rooms.js

@@ -0,0 +1,86 @@
+/** Thrown on any non-2xx rooms response; `reason` carries the machine-readable
+ * cause when the API provides one (e.g. "banned", "private"). */
+export class RoomsRequestError extends Error {
+    status;
+    reason;
+    constructor(status, message, reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = "RoomsRequestError";
+    }
+}
+/**
+ * Thin typed client for the room registry, bound to a host and the Flow
+ * token supplier. Public reads work signed-out; mutations attach the caller's
+ * bearer and fail fast with a 401-shaped error when no session exists.
+ */
+export function createRoomsApi(host, getToken) {
+    async function request(path, options = {}) {
+        const headers = {};
+        const token = await getToken();
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        else if (options.authRequired) {
+            throw new RoomsRequestError(401, "Sign in first");
+        }
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await fetch(`${host}/api/rooms${path}`, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        const payload = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            throw new RoomsRequestError(res.status, typeof payload.error === "string"
+                ? payload.error
+                : `Rooms request failed (${res.status})`, typeof payload.reason === "string" ? payload.reason : undefined);
+        }
+        return payload;
+    }
+    const slugPath = (slug) => `/${encodeURIComponent(slug)}`;
+    const act = (slug, action, body) => request(`${slugPath(slug)}/${action}`, {
+        method: "POST",
+        body,
+        authRequired: true,
+    }).then(() => undefined);
+    return {
+        list(options) {
+            const params = new URLSearchParams();
+            if (options?.cursor)
+                params.set("cursor", options.cursor);
+            if (options?.limit)
+                params.set("limit", String(options.limit));
+            const query = params.size ? `?${params}` : "";
+            return request(query);
+        },
+        get: (slug) => request(slugPath(slug)),
+        mine: () => request("/mine", { authRequired: true }),
+        create: (input) => request("", {
+            method: "POST",
+            body: input,
+            authRequired: true,
+        }),
+        update: (slug, patch) => request(`${slugPath(slug)}/update`, {
+            method: "POST",
+            body: patch,
+            authRequired: true,
+        }),
+        remove: (slug) => act(slug, "delete", {}),
+        join: (slug) => act(slug, "join", {}),
+        leave: (slug) => act(slug, "leave", {}),
+        members: (slug) => request(`${slugPath(slug)}/members`, { authRequired: true }),
+        presence: (slug) => request(`${slugPath(slug)}/presence`),
+        settings: (slug, surface) => request(`${slugPath(slug)}/settings/${encodeURIComponent(surface)}`),
+        saveSettings: (slug, surface, settings) => request(`${slugPath(slug)}/settings/${encodeURIComponent(surface)}`, { method: "POST", body: { settings }, authRequired: true }),
+        transfer: (slug, userId) => act(slug, "transfer", { userId }),
+        claim: (slug) => act(slug, "claim", {}),
+        setRole: (slug, userId, role) => act(slug, "role", { userId, role }),
+        kick: (slug, userId) => act(slug, "kick", { userId }),
+        ban: (slug, userId, options) => act(slug, "ban", { userId, ...options }),
+        unban: (slug, userId) => act(slug, "unban", { userId }),
+        mute: (slug, userId, options) => act(slug, "mute", { userId, ...options }),
+        unmute: (slug, userId) => act(slug, "unmute", { userId }),
+    };
+}

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/react/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { Flow, FlowState } from "../types";
+import type { Flow, FlowState, RoomDetail, RoomPresenceSnapshot, RoomSummary } from "../types";
 /**
  * Returns the Flow instance to use. Resolution order:
  *  1. The instance from a `<FlowIdProvider>` ancestor (if any)
@@ -35,3 +35,28 @@ export declare function useFlowId(): {
     refreshJwt: () => Promise<boolean>;
     getToken: () => Promise<string | null>;
 };
+/**
+ * Fetches the public room list once (call `reload` to refresh). Pagination
+ * stays manual: pass the returned `nextCursor` back through `flow.rooms.list`.
+ */
+export declare function useRooms(): {
+    rooms: RoomSummary[];
+    nextCursor: string | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => void;
+};
+/**
+ * Fetches one room's detail, and optionally polls its live presence when
+ * `presencePollMs` is set (polling until the presence store grows a push
+ * channel). Re-fetches when the slug changes; call `reload` to refresh.
+ */
+export declare function useRoom(slug: string, options?: {
+    presencePollMs?: number;
+}): {
+    room: RoomDetail | null;
+    presence: RoomPresenceSnapshot | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => void;
+};

package/dist/sdk/react/hooks.js

@@ -1,6 +1,7 @@
-import { useContext, useSyncExternalStore } from "react";
+import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from "react";
 import { getFlow as getSingletonFlow } from "../client/create-flow";
 import { FlowContext } from "./provider";
+const asError = (e) => e instanceof Error ? e : new Error(String(e));
 /**
  * Returns the Flow instance to use. Resolution order:
  *  1. The instance from a `<FlowIdProvider>` ancestor (if any)
@@ -53,3 +54,79 @@ export function useFlowId() {
         getToken: flow.getToken,
     };
 }
+/**
+ * Fetches the public room list once (call `reload` to refresh). Pagination
+ * stays manual: pass the returned `nextCursor` back through `flow.rooms.list`.
+ */
+export function useRooms() {
+    const flow = useFlow();
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    const load = useCallback(() => {
+        flow.rooms
+            .list()
+            .then((list) => {
+            setResult(list);
+            setError(null);
+        })
+            .catch((err) => setError(asError(err)));
+    }, [flow]);
+    useEffect(load, [load]);
+    return {
+        rooms: result?.rooms ?? [],
+        nextCursor: result?.nextCursor ?? null,
+        loading: result === null && error === null,
+        error,
+        reload: load,
+    };
+}
+/**
+ * Fetches one room's detail, and optionally polls its live presence when
+ * `presencePollMs` is set (polling until the presence store grows a push
+ * channel). Re-fetches when the slug changes; call `reload` to refresh.
+ */
+export function useRoom(slug, options) {
+    const flow = useFlow();
+    const pollMs = options?.presencePollMs ?? 0;
+    const [room, setRoom] = useState(null);
+    const [presence, setPresence] = useState(null);
+    const [error, setError] = useState(null);
+    const loadRoom = useCallback(() => {
+        flow.rooms
+            .get(slug)
+            .then((detail) => {
+            setRoom(detail);
+            setError(null);
+        })
+            .catch((err) => setError(asError(err)));
+    }, [flow, slug]);
+    const loadPresence = useCallback(() => {
+        flow.rooms
+            .presence(slug)
+            .then(setPresence)
+            .catch(() => { });
+    }, [flow, slug]);
+    useEffect(() => {
+        setRoom(null);
+        setError(null);
+        loadRoom();
+    }, [loadRoom]);
+    useEffect(() => {
+        loadPresence();
+        if (pollMs <= 0)
+            return;
+        const timer = setInterval(loadPresence, pollMs);
+        return () => clearInterval(timer);
+    }, [loadPresence, pollMs]);
+    const reload = useCallback(() => {
+        loadRoom();
+        loadPresence();
+    }, [loadRoom, loadPresence]);
+    return {
+        room,
+        presence,
+        loading: room === null && error === null,
+        error,
+        reload,
+    };
+}

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

@@ -1,4 +1,4 @@
 export type { FlowIdProviderProps, ProfileButtonProps } from "../types";
-export { useFlow, useFlowId, useFlowState } from "./hooks";
+export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

package/dist/sdk/react/index.js

@@ -1,3 +1,3 @@
-export { useFlow, useFlowId, useFlowState } from "./hooks";
+export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

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

@@ -3,7 +3,9 @@ export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogErr
 export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutcome, BeaconBody, FunnelStep, } from "./events";
 export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
 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 { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
-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 { 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, 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/index.js

@@ -1 +1 @@
-export { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
+export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";

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

@@ -131,6 +131,12 @@ export type SendCallsParams = {
     chainId?: string;
     capabilities?: Record<string, unknown>;
 };
+/**
+ * Unwraps the connect capabilities from a wallet_connect RPC request (they ride
+ * as the first param), or undefined. Several dialog surfaces read them (mode,
+ * accessKeyHash, guestToken), so the cast lives here rather than being repeated.
+ */
+export declare function getConnectCapabilities(request: RpcRequest | undefined): ConnectCapabilities | undefined;
 export declare function isPersonalSignParams(params: readonly unknown[] | undefined): params is readonly [string, string];
 export declare function isSendTransactionParams(params: readonly unknown[] | undefined): params is readonly [SendTransactionParams];
 export declare function isSendCallsParams(params: readonly unknown[] | undefined): params is readonly [SendCallsParams];

package/dist/sdk/types/protocol.js

@@ -1,3 +1,11 @@
+/**
+ * Unwraps the connect capabilities from a wallet_connect RPC request (they ride
+ * as the first param), or undefined. Several dialog surfaces read them (mode,
+ * accessKeyHash, guestToken), so the cast lives here rather than being repeated.
+ */
+export function getConnectCapabilities(request) {
+    return request?.params?.[0]?.capabilities;
+}
 export function isPersonalSignParams(params) {
     if (!params || params.length < 2)
         return false;

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

@@ -0,0 +1,129 @@
+/** Room registry types shared by the server routes and the client SDK. */
+export type RoomVisibility = "public" | "unlisted" | "private";
+/**
+ * Owner is not a member-row role: `room.ownerId` is the single authority.
+ * Member rows carry moderator|member.
+ */
+export type RoomRole = "owner" | "moderator" | "member";
+export type RoomChannel = "game" | "voice" | "text";
+export type RoomRestrictionKind = "ban" | "mute";
+export interface RoomOwner {
+    id: string;
+    username: string;
+}
+/** Live occupant counts per channel, staleness-filtered at read time. */
+export interface RoomOccupancy {
+    game: number;
+    voice: number;
+    text: number;
+}
+export interface RoomSummary {
+    id: string;
+    slug: string;
+    displayName: string;
+    description: string | null;
+    owner: RoomOwner | null;
+    visibility: RoomVisibility;
+    isSystem: boolean;
+    occupancy: RoomOccupancy;
+    createdAt: string;
+}
+export interface RoomDetail extends RoomSummary {
+    /** The caller's role in this room, when the request carried a valid bearer. */
+    viewerRole: RoomRole | null;
+    memberCount: number;
+}
+export interface RoomMemberEntry {
+    userId: string;
+    username: string;
+    role: RoomRole;
+    joinedAt: string;
+}
+export interface RoomMembers {
+    owner: RoomOwner | null;
+    members: RoomMemberEntry[];
+}
+export interface CreateRoomInput {
+    slug: string;
+    displayName?: string;
+    description?: string;
+    visibility?: RoomVisibility;
+}
+export interface UpdateRoomInput {
+    slug?: string;
+    displayName?: string;
+    description?: string;
+    visibility?: RoomVisibility;
+}
+export interface MyRooms {
+    owned: RoomSummary[];
+    member: RoomSummary[];
+}
+export interface RoomList {
+    rooms: RoomSummary[];
+    nextCursor: string | null;
+}
+export interface RoomPresenceEntry {
+    userId: string;
+    username: string;
+    joinedAt: string;
+}
+export interface RoomPresenceSnapshot {
+    roomId: string;
+    slug: string;
+    channels: Record<RoomChannel, RoomPresenceEntry[]>;
+}
+/**
+ * Room admission context returned by POST /api/session/verify when the caller
+ * passes a `room` slug: whether the verified subject may enter, and with which
+ * role and per-room game settings. `settings` is delivered only through this
+ * server-to-server path — surface blobs may hold secret-ish values.
+ */
+export interface VerifyRoomContext {
+    ok: boolean;
+    reason?: "not_found" | "banned" | "private_not_member";
+    id: string | null;
+    slug: string;
+    visibility: RoomVisibility | null;
+    role: RoomRole | null;
+    muted: boolean;
+    settings: Record<string, number | boolean | string>;
+}
+export interface RoomSurfaceSettings {
+    surface: string;
+    version: number;
+    settings: Record<string, number | boolean | string>;
+}
+/** The room-registry client exposed as `flow.rooms`. Public reads work
+ * signed-out; everything else attaches the caller's bearer token. */
+export interface RoomsApi {
+    list(options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<RoomList>;
+    get(slug: string): Promise<RoomDetail>;
+    mine(): Promise<MyRooms>;
+    create(input: CreateRoomInput): Promise<RoomDetail>;
+    update(slug: string, patch: UpdateRoomInput): Promise<RoomDetail>;
+    remove(slug: string): Promise<void>;
+    join(slug: string): Promise<void>;
+    leave(slug: string): Promise<void>;
+    members(slug: string): Promise<RoomMembers>;
+    presence(slug: string): Promise<RoomPresenceSnapshot>;
+    settings(slug: string, surface: string): Promise<RoomSurfaceSettings>;
+    saveSettings(slug: string, surface: string, settings: Record<string, unknown>): Promise<RoomSurfaceSettings>;
+    transfer(slug: string, userId: string): Promise<void>;
+    claim(slug: string): Promise<void>;
+    setRole(slug: string, userId: string, role: "moderator" | "member"): Promise<void>;
+    kick(slug: string, userId: string): Promise<void>;
+    ban(slug: string, userId: string, options?: {
+        reason?: string;
+        expiresInSeconds?: number;
+    }): Promise<void>;
+    unban(slug: string, userId: string): Promise<void>;
+    mute(slug: string, userId: string, options?: {
+        reason?: string;
+        expiresInSeconds?: number;
+    }): Promise<void>;
+    unmute(slug: string, userId: string): Promise<void>;
+}

package/dist/sdk/types/rooms.js

@@ -0,0 +1 @@
+/** Room registry types shared by the server routes and the client SDK. */

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

@@ -3,6 +3,7 @@ import type { Chain, Hex, PrepareTransactionRequestParameters, SendTransactionPa
 import type { SendCallsParameters } from "viem/actions";
 import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { ConnectCapabilities, ConnectResponse } from "./protocol";
+import type { RoomsApi } from "./rooms";
 export type Address = `0x${string}`;
 /**
  * Phases viem invokes a chain's `prepareTransactionRequest` hook at. Inlined
@@ -70,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;
@@ -77,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;
@@ -205,6 +246,8 @@ export type Flow = {
     walletClient(args?: {
         chainId?: number;
     }): Promise<WalletClient>;
+    /** Typed client for the room registry (browse, membership, settings, moderation). */
+    rooms: RoomsApi;
     subscribe(listener: Listener<FlowState>): () => void;
     getState(): FlowState;
     dialog: DialogHost;

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.8.1",
+  "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": [