@flow-industries/id 0.4.0 → 0.7.0

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

@@ -1,6 +1,7 @@
 import { createDialogHost } from "./dialog-host";
 import { idb } from "./idb";
 import { METHODS } from "./methods";
+import { makeRefreshStore } from "./refresh-store";
 import { credentialToAddress, restoreCredential, runLogin, runLogout, } from "./session";
 import { createStore, initialFlowState } from "./store";
 const DEFAULT_HOST = "https://id.flow.industries";
@@ -91,6 +92,7 @@ export function createFlow(options = {}) {
         return currentFlow;
     const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
     const dialogUrl = `${host}/dialog/`;
+    const refreshStore = makeRefreshStore(host);
     const chains = options.chains ?? [];
     const getChain = (chainId) => {
         if (chainId == null)
@@ -120,19 +122,39 @@ export function createFlow(options = {}) {
      * user has no active session (in which case the caller should fall back to
      * `flow.login()`). Never throws — restore failures are treated as "no session".
      */
-    async function restore() {
-        const dialogHost = getDialog();
+    /**
+     * Mints a fresh session from the first-party refresh token: POSTs it as a
+     * bearer to /api/session/refresh (no cookie, so iOS ITP can't block it),
+     * commits the returned session, and persists the rotated token. Returns false
+     * (never throws) when there's no token or the server rejects it — the caller
+     * then falls back to ensureGuest()/login(). A 401 means the token is dead
+     * (expired, revoked, or reuse-detected), so it's dropped.
+     */
+    async function refreshViaToken() {
+        const token = refreshStore.get();
+        if (!token)
+            return false;
         try {
-            const result = await dialogHost.requestSilent(METHODS.restore, []);
+            const res = await fetch(`${host}/api/session/refresh`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) {
+                if (res.status === 401)
+                    refreshStore.clear();
+                return false;
+            }
+            const result = (await res.json());
+            refreshStore.set(result.refreshToken);
             store.setState({
                 user: result.user,
                 jwt: result.jwt,
                 credential: result.credential,
                 address: result.address,
             });
-            // A guest restore returns a null credential; never persist that — the IDB
-            // store is reserved for a real passkey credential and writing null would
-            // erase a previously stored one.
+            // A guest carries a null credential; never persist that — the IDB store is
+            // reserved for a real passkey credential and writing null would erase a
+            // previously stored one.
             if (result.credential) {
                 await idb.set("flow.activeCredential", result.credential);
             }
@@ -142,10 +164,11 @@ export function createFlow(options = {}) {
             return false;
         }
     }
-    // refreshJwt is semantically the same as restore — both mint a fresh JWT
-    // from the cookie session. We expose two names because consumers reach for
-    // one or the other based on intent (page-load vs near-expiry).
-    const refreshJwt = restore;
+    // Rotation is cross-tab-safe: the lock serializes refreshes across tabs of the
+    // same origin, and refreshViaToken reads the token fresh from storage inside
+    // the lock, so a second tab uses the already-rotated token (never a stale one
+    // that would trip server-side reuse detection).
+    const refreshJwt = () => withGuestLock(`flow.id.refresh:${host}`, refreshViaToken);
     // Dedupe concurrent refreshes: a burst of getToken() calls that all find the
     // cached token expired should trigger one mint, not one per call.
     let refreshInFlight = null;
@@ -192,17 +215,18 @@ export function createFlow(options = {}) {
             return true;
         if (!guestInFlight) {
             guestInFlight = withGuestLock(`flow.id.guest:${host}`, async () => {
-                // Re-check under the lock: another tab may have minted the guest (and
-                // set the shared id.flow.industries cookie) while we waited, so
-                // restore-first collapses concurrent first-visits onto one row.
+                // Re-check under the lock: another tab may have minted the guest while
+                // we waited. Refresh-first (from this origin's stored token) recovers an
+                // existing session instead of minting a duplicate guest.
                 if (store.getSnapshot().user)
                     return true;
-                if (await restore())
+                if (await refreshViaToken())
                     return true;
                 try {
                     const result = await getDialog().requestSilent(METHODS.guest, []);
                     if (!result.user)
                         return false;
+                    refreshStore.set(result.refreshToken);
                     store.setState({
                         user: result.user,
                         jwt: result.jwt,
@@ -225,10 +249,10 @@ export function createFlow(options = {}) {
     void (async () => {
         await restoreCredential(store);
         if (options.autoRestore !== false) {
-            const restored = await restore();
-            // ensureGuest re-checks under a cross-tab lock (restore-first) before
-            // minting, so calling it after a failed restore can't fork a visitor into
-            // duplicate guests across tabs — the extra restore is the dedup.
+            const restored = await refreshViaToken();
+            // ensureGuest re-checks (refresh-first) under a cross-tab lock before
+            // minting, so calling it after a failed refresh can't fork a visitor into
+            // duplicate guests across tabs — the extra refresh is the dedup.
             if (!restored && options.autoGuest)
                 await ensureGuest();
         }
@@ -270,12 +294,13 @@ export function createFlow(options = {}) {
             accessKeyPrep = await accessKeyModule.prepareAccessKey(accessKeyOptions, chain.id);
             extraCapabilities = { accessKeyHash: accessKeyPrep.accessKeyHash };
         }
-        const { session, webauthn } = await runLogin({
+        const { session, webauthn, refreshToken } = await runLogin({
             dialog: dialogHost,
             store,
             options: loginOpts,
             ...(extraCapabilities ? { extraCapabilities } : {}),
         });
+        refreshStore.set(refreshToken);
         if (accessKeyModule && accessKeyPrep && webauthn) {
             await accessKeyModule.finalizeAccessKey({
                 address: session.address,
@@ -310,7 +335,13 @@ export function createFlow(options = {}) {
             // Server-side sign-out failed (offline?) — still clear local state.
         }
         await runLogout(store);
+        refreshStore.clear();
         dialog?.close();
+        // An autoGuest app is never truly "signed out" — it always wants at least a
+        // guest session. Re-mint one so the UI (e.g. the profile widget pill) keeps
+        // working after logout instead of vanishing until the next page load.
+        if (options.autoGuest)
+            await ensureGuest();
     }
     const flow = {
         get user() {
@@ -333,7 +364,7 @@ export function createFlow(options = {}) {
         },
         login,
         logout,
-        restore,
+        restore: refreshJwt,
         ensureGuest,
         refreshJwt,
         getToken,
@@ -362,6 +393,7 @@ export function createFlow(options = {}) {
         get dialog() {
             return getDialog();
         },
+        host,
     };
     currentFlow = flow;
     return flow;

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

@@ -1,4 +1,5 @@
 import * as Messenger from "../dialog/remote/Messenger";
+import { bridgeToWindow, makeIframe } from "./iframe-host";
 const HIDDEN_STYLE = {
     position: "fixed",
     inset: "0",
@@ -38,25 +39,20 @@ export function createDialogHost(options) {
     const pending = new Map();
     /**
      * Mounts the iframe and wires up the postMessage bridge. Idempotent — safe
-     * to call before every request. The `allow` attribute grants WebAuthn and
-     * clipboard permissions to the dialog (required for passkey ceremonies).
+     * to call before every request.
      */
     function ensureFrame() {
         if (iframe)
             return;
-        iframe = document.createElement("iframe");
-        iframe.src = `${host}`;
+        iframe = makeIframe(`${host}`);
         iframe.dataset.flowId = "";
-        iframe.allow =
-            "publickey-credentials-create; publickey-credentials-get; clipboard-write";
         Object.assign(iframe.style, HIDDEN_STYLE);
-        iframe.style.colorScheme = "normal";
         container.appendChild(iframe);
-        messenger = Messenger.bridge({
-            from: Messenger.fromWindow(window),
-            to: Messenger.fromWindow(iframe.contentWindow),
-            waitForReady: true,
-        });
+        // Bind the bridge to this iframe's own window — a page may host more than
+        // one same-origin Flow iframe (e.g. the profile widget), and origin
+        // filtering can't tell them apart, so without the source filter their
+        // `ready`/`close` would cross-fire onto this dialog's bridge.
+        messenger = bridgeToWindow(iframe.contentWindow);
         messenger.on("rpc-response", (payload) => {
             const id = payload?.id;
             const handler = pending.get(id);
@@ -90,11 +86,7 @@ export function createDialogHost(options) {
             return;
         if (messenger)
             messenger.destroy();
-        messenger = Messenger.bridge({
-            from: Messenger.fromWindow(window),
-            to: Messenger.fromWindow(popup),
-            waitForReady: true,
-        });
+        messenger = bridgeToWindow(popup);
     }
     let initSent = false;
     /**
@@ -117,11 +109,20 @@ export function createDialogHost(options) {
         if (!iframe)
             return;
         Object.assign(iframe.style, VISIBLE_STYLE);
+        // The dialog owns its open/close animation and mounts the overlay (playing
+        // the enter animation) on this signal — same mechanism as the profile
+        // widget, so every dialog appears and disappears identically.
+        void messenger?.send("__internal", { type: "dialog-shown" });
     }
     function hide() {
         if (!iframe)
             return;
-        Object.assign(iframe.style, { display: "none", pointerEvents: "none" });
+        // Keep the iframe rendered and only drop hit-testing, so the dialog can play
+        // its exit animation. display:none would pause the iframe's
+        // requestAnimationFrame, making the close (and the next open) skip straight
+        // to the end. While hidden the overlay is transparent and click-through.
+        iframe.style.pointerEvents = "none";
+        void messenger?.send("__internal", { type: "dialog-hidden" });
     }
     function open(opts) {
         if (opts?.mode === "popup") {
@@ -129,8 +130,11 @@ export function createDialogHost(options) {
             return;
         }
         ensureFrame();
-        show();
+        // Init before show so the dialog is initialized/navigated by the time it
+        // mounts the overlay on the show signal — the card enters with its content
+        // ready rather than flashing the pre-init spinner.
         sendInit(opts);
+        show();
     }
     function close() {
         hide();
@@ -177,6 +181,7 @@ export function createDialogHost(options) {
     async function requestSilent(method, params) {
         ensureFrame();
         sendInit();
+        await messenger.waitForReady();
         return dispatchRequest(method, params);
     }
     return {

package/dist/sdk/client/iframe-host.d.ts

@@ -0,0 +1,23 @@
+import * as Messenger from "../dialog/remote/Messenger";
+/**
+ * Permissions the dialog iframe needs to run WebAuthn passkey ceremonies and
+ * copy recovery values. Shared by every Flow iframe host (the dialog host and
+ * the profile widget).
+ */
+export declare const IFRAME_ALLOW = "publickey-credentials-create; publickey-credentials-get; clipboard-write";
+/**
+ * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
+ * `color-scheme: normal` so the iframe itself stays transparent (the rendered
+ * theme is applied to nested card wrappers, not the iframe). The caller owns
+ * positioning/visibility and any `data-*` marker.
+ */
+export declare function makeIframe(src: string): HTMLIFrameElement;
+/**
+ * Builds a postMessage bridge to a child window (iframe `contentWindow` or
+ * popup). Inbound is filtered by `source` so multiple same-origin Flow frames
+ * on one page can't cross-fire their `ready`/`close` handshakes; `targetOrigin`
+ * pins outbound sends to the host origin when given (omit for "*").
+ */
+export declare function bridgeToWindow(target: Window, options?: {
+    targetOrigin?: string;
+}): Messenger.Bridge;

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

@@ -0,0 +1,34 @@
+import * as Messenger from "../dialog/remote/Messenger";
+/**
+ * Permissions the dialog iframe needs to run WebAuthn passkey ceremonies and
+ * copy recovery values. Shared by every Flow iframe host (the dialog host and
+ * the profile widget).
+ */
+export const IFRAME_ALLOW = "publickey-credentials-create; publickey-credentials-get; clipboard-write";
+/**
+ * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
+ * `color-scheme: normal` so the iframe itself stays transparent (the rendered
+ * theme is applied to nested card wrappers, not the iframe). The caller owns
+ * positioning/visibility and any `data-*` marker.
+ */
+export function makeIframe(src) {
+    const frame = document.createElement("iframe");
+    frame.src = src;
+    frame.allow = IFRAME_ALLOW;
+    frame.style.border = "none";
+    frame.style.colorScheme = "normal";
+    return frame;
+}
+/**
+ * Builds a postMessage bridge to a child window (iframe `contentWindow` or
+ * popup). Inbound is filtered by `source` so multiple same-origin Flow frames
+ * on one page can't cross-fire their `ready`/`close` handshakes; `targetOrigin`
+ * pins outbound sends to the host origin when given (omit for "*").
+ */
+export function bridgeToWindow(target, options = {}) {
+    return Messenger.bridge({
+        from: Messenger.fromWindow(window, { source: target }),
+        to: Messenger.fromWindow(target, options.targetOrigin ? { targetOrigin: options.targetOrigin } : undefined),
+        waitForReady: true,
+    });
+}

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

@@ -1,4 +1,5 @@
-export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowState, FlowUser, LoginOptions, MethodName, Session, } from "../types";
+export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, 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";

package/dist/sdk/client/index.js

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

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

@@ -4,7 +4,6 @@ export declare const METHODS: {
     readonly signTypedData: "eth_signTypedData";
     readonly sendTransaction: "eth_sendTransaction";
     readonly sendCalls: "wallet_sendCalls";
-    readonly restore: "wallet_restore";
     readonly guest: "wallet_guest";
     readonly signOut: "wallet_signout";
 };

package/dist/sdk/client/methods.js

@@ -4,7 +4,6 @@ export const METHODS = {
     signTypedData: "eth_signTypedData",
     sendTransaction: "eth_sendTransaction",
     sendCalls: "wallet_sendCalls",
-    restore: "wallet_restore",
     guest: "wallet_guest",
     signOut: "wallet_signout",
 };

package/dist/sdk/client/profile-button.d.ts

@@ -0,0 +1,15 @@
+import type { MountProfileOptions, ProfileButtonHandle } from "../types";
+/**
+ * Mounts the universal Flow ID "profile button" — a persistent inline iframe
+ * showing the signed-in user's avatar + username (the collapsed pill). Clicking
+ * it opens the profile dialog in a SEPARATE fullscreen overlay iframe, so the
+ * pill stays in place behind the dialog's dimmed backdrop rather than morphing
+ * into it. Both iframes ride the dialog SPA at `${host}/dialog/` (routes
+ * `/dialog/profile-pill` and `/dialog/profile`) so the chrome matches the auth
+ * dialog and the widget is first-party to Flow ID (reads `/api/me`, uploads
+ * avatars with the cookie session).
+ *
+ * Resolves the Flow singleton automatically (createFlow() must have run), so
+ * callers don't thread the instance through. No-op under SSR.
+ */
+export declare function createProfileButton(options: MountProfileOptions): ProfileButtonHandle;

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

@@ -0,0 +1,189 @@
+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";
+const POSITION_STYLE = {
+    "top-right": { top: "0", right: "0" },
+    "top-left": { top: "0", left: "0" },
+    "bottom-right": { bottom: "0", right: "0" },
+    "bottom-left": { bottom: "0", left: "0" },
+};
+const OVERLAY_STYLE = {
+    position: "fixed",
+    inset: "0",
+    width: "100%",
+    height: "100%",
+    zIndex: "2147483647",
+};
+/**
+ * Mounts the universal Flow ID "profile button" — a persistent inline iframe
+ * showing the signed-in user's avatar + username (the collapsed pill). Clicking
+ * it opens the profile dialog in a SEPARATE fullscreen overlay iframe, so the
+ * pill stays in place behind the dialog's dimmed backdrop rather than morphing
+ * into it. Both iframes ride the dialog SPA at `${host}/dialog/` (routes
+ * `/dialog/profile-pill` and `/dialog/profile`) so the chrome matches the auth
+ * dialog and the widget is first-party to Flow ID (reads `/api/me`, uploads
+ * avatars with the cookie session).
+ *
+ * Resolves the Flow singleton automatically (createFlow() must have run), so
+ * callers don't thread the instance through. No-op under SSR.
+ */
+export function createProfileButton(options) {
+    if (typeof document === "undefined")
+        return { destroy() { } };
+    const flow = options.flow ?? getFlow() ?? requireFlow();
+    const host = (options.host ?? flow.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+    const hostOrigin = new URL(host).origin;
+    const theme = options.theme ?? "light dark";
+    let createdContainer = null;
+    let container = options.container ?? null;
+    if (!container) {
+        const el = document.createElement("div");
+        Object.assign(el.style, {
+            position: "fixed",
+            zIndex: "2147483000",
+            // Never steal input from the host (e.g. the Godot canvas) — only the
+            // iframe re-enables pointer events for itself.
+            pointerEvents: "none",
+            padding: options.padding ?? "1.5rem",
+            ...POSITION_STYLE[options.position ?? "top-right"],
+        });
+        document.body.appendChild(el);
+        createdContainer = el;
+        container = el;
+    }
+    function makeFrame() {
+        const frame = makeIframe(`${host}/dialog/`);
+        frame.dataset.flowProfile = "";
+        frame.style.display = "block";
+        return frame;
+    }
+    // A page may host several same-origin Flow iframes (this pill, this dialog,
+    // the auth login dialog). Origin filtering can't tell them apart, so each
+    // bridge is bound to its own iframe window — otherwise their `ready`/`close`
+    // handshakes would cross-fire. Identity is pinned to the host origin so the
+    // username is never broadcast with "*".
+    function makeBridge(frame, route) {
+        const bridge = bridgeToWindow(frame.contentWindow, {
+            targetOrigin: hostOrigin,
+        });
+        bridge.send("__internal", {
+            type: "init",
+            mode: "iframe",
+            referrer: { title: document.title },
+            theme: { colorScheme: theme },
+            route,
+        });
+        return bridge;
+    }
+    function currentIdentity() {
+        const user = flow.getState().user;
+        return user
+            ? { username: user.username, isGuest: user.isGuest === true }
+            : null;
+    }
+    // ----- the persistent pill (stays mounted; sizes to its own content) -----
+    const pill = makeFrame();
+    let pillWidth = 0;
+    let pillHeight = 0;
+    function applyPillSize() {
+        Object.assign(pill.style, {
+            position: "static",
+            width: `${pillWidth}px`,
+            height: `${pillHeight}px`,
+            pointerEvents: pillWidth > 0 ? "auto" : "none",
+        });
+    }
+    applyPillSize();
+    container.appendChild(pill);
+    const pillBridge = makeBridge(pill, "/dialog/profile-pill");
+    pillBridge.on("__internal", (payload) => {
+        if (payload.type === "profile-resize") {
+            pillWidth = payload.width;
+            pillHeight = payload.height;
+            applyPillSize();
+        }
+        else if (payload.type === "profile-expand") {
+            showDialog();
+        }
+    });
+    // ----- the dialog overlay (lazy; a separate fullscreen iframe layered ABOVE
+    // the pill, so the pill shows through its dimmed backdrop) -----
+    let dialog = null;
+    let dialogBridge = null;
+    function ensureDialog() {
+        if (dialog)
+            return;
+        dialog = makeFrame();
+        Object.assign(dialog.style, OVERLAY_STYLE, {
+            pointerEvents: "none",
+        });
+        document.body.appendChild(dialog);
+        dialogBridge = makeBridge(dialog, "/dialog/profile");
+        dialogBridge.on("close", () => hideDialog());
+        dialogBridge.on("__internal", (payload) => {
+            if (payload.type === "profile-login") {
+                hideDialog();
+                void flow
+                    .login(payload.mode === "signup" ? { signUp: true } : { signIn: true })
+                    .catch(() => { });
+            }
+            else if (payload.type === "profile-logout") {
+                hideDialog();
+                void flow.logout().catch(() => { });
+            }
+        });
+        void dialogBridge.send("__internal", {
+            type: "profile-identity",
+            identity: currentIdentity(),
+        });
+    }
+    // The dialog owns its open/close animation entirely; the host only signals
+    // visibility and toggles hit-testing. The overlay iframe is NEVER set to
+    // display:none — that pauses the iframe's requestAnimationFrame, so motion's
+    // engine is asleep when the next open fires and the animation jumps straight
+    // to its end (instant). Keeping it always-rendered, transparent and
+    // click-through while hidden keeps every open/close animation reliable.
+    function showDialog() {
+        ensureDialog();
+        if (!dialog)
+            return;
+        dialog.style.pointerEvents = "auto";
+        void dialogBridge?.send("__internal", { type: "dialog-shown" });
+    }
+    function hideDialog() {
+        if (!dialog)
+            return;
+        dialog.style.pointerEvents = "none";
+        void dialogBridge?.send("__internal", { type: "dialog-hidden" });
+    }
+    // ----- keep both iframes' identity in sync with the Flow session -----
+    // flow.subscribe fires on any store change (jwt/credential/address too), so
+    // skip re-sending an identical identity (e.g. on every silent JWT refresh).
+    let lastIdentityKey;
+    function pushIdentity() {
+        const identity = currentIdentity();
+        const key = identity ? `${identity.username}|${identity.isGuest}` : "none";
+        if (key === lastIdentityKey)
+            return;
+        lastIdentityKey = key;
+        void pillBridge.send("__internal", { type: "profile-identity", identity });
+        if (dialogBridge)
+            void dialogBridge.send("__internal", {
+                type: "profile-identity",
+                identity,
+            });
+    }
+    pushIdentity();
+    const unsubscribe = flow.subscribe(pushIdentity);
+    return {
+        destroy() {
+            unsubscribe();
+            pillBridge.destroy();
+            dialogBridge?.destroy();
+            pill.remove();
+            dialog?.remove();
+            createdContainer?.remove();
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+/**
+ * First-party persistence for the rotating refresh token. It lives in the
+ * consumer app's OWN localStorage (origin-scoped), so it survives reloads and
+ * navigations and — unlike the old id.flow.industries cookie — is never a
+ * third-party cookie, so iOS ITP can't block it. Keyed by `host` so pointing
+ * the SDK at a different Flow ID origin (dev vs prod) doesn't collide.
+ */
+export interface RefreshStore {
+    get(): string | null;
+    set(token: string): void;
+    clear(): void;
+}
+export declare function makeRefreshStore(host: string): RefreshStore;

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

@@ -0,0 +1,25 @@
+export function makeRefreshStore(host) {
+    const key = `flow.id.refresh:${host}`;
+    return {
+        get() {
+            try {
+                return localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(token) {
+            try {
+                localStorage.setItem(key, token);
+            }
+            catch { }
+        },
+        clear() {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch { }
+        },
+    };
+}

package/dist/sdk/client/session.js

@@ -40,12 +40,13 @@ export async function runLogin(params) {
     const result = (await dialog.request(METHODS.connect, [
         { capabilities },
     ]));
-    const { jwt, user, credential, webauthn } = result;
+    const { jwt, refreshToken, user, credential, webauthn } = result;
     const address = credentialToAddress(credential);
     await idb.set(CREDENTIAL_KEY, credential);
     store.setState({ user, jwt, credential, address });
     return {
         session: { user, jwt, credential, address },
+        refreshToken,
         webauthn,
     };
 }

package/dist/sdk/dialog/remote/Messenger.js

@@ -38,7 +38,7 @@ export function from(messenger) {
  * isolation that prevents arbitrary pages from injecting messages.
  */
 export function fromWindow(w, options = {}) {
-    const { targetOrigin } = options;
+    const { targetOrigin, source } = options;
     const listeners = new Map();
     return from({
         destroy() {
@@ -54,6 +54,8 @@ export function fromWindow(w, options = {}) {
                     return;
                 if (targetOrigin && event.origin !== targetOrigin)
                     return;
+                if (source && event.source !== source)
+                    return;
                 listener(event.data.payload, event);
             }
             w.addEventListener("message", handler);

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

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

package/dist/sdk/react/index.js

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

package/dist/sdk/react/profile-button.d.ts

@@ -0,0 +1,9 @@
+import type { ProfileButtonProps } from "../types";
+/**
+ * Drops the universal Flow ID profile button into a React tree. Renders a host
+ * element (style it via `className` for placement/padding — e.g. top-right) that
+ * the pill iframe mounts into; the iframe itself is sized to its content and
+ * expands to the profile dialog on click. Resolves the Flow instance from a
+ * `<FlowIdProvider>` or the createFlow() singleton.
+ */
+export declare function ProfileButton({ className, host, theme }: ProfileButtonProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { createProfileButton } from "../client/profile-button";
+import { useFlow } from "./hooks";
+/**
+ * Drops the universal Flow ID profile button into a React tree. Renders a host
+ * element (style it via `className` for placement/padding — e.g. top-right) that
+ * the pill iframe mounts into; the iframe itself is sized to its content and
+ * expands to the profile dialog on click. Resolves the Flow instance from a
+ * `<FlowIdProvider>` or the createFlow() singleton.
+ */
+export function ProfileButton({ className, host, theme }) {
+    const flow = useFlow();
+    const ref = useRef(null);
+    useEffect(() => {
+        const container = ref.current;
+        if (!container)
+            return;
+        const handle = createProfileButton({
+            container,
+            flow,
+            ...(host ? { host } : {}),
+            ...(theme ? { theme } : {}),
+        });
+        return () => handle.destroy();
+    }, [flow, host, theme]);
+    return _jsx("div", { ref: ref, className: className });
+}

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

@@ -16,6 +16,7 @@ export type FlowCredential = {
 };
 export type AuthResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
     credential: FlowCredential;
 };

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

@@ -37,6 +37,27 @@ export type DialogCustomLabels = {
     switchAccount?: string;
     signUpLink?: string;
 };
+/**
+ * The profile fields the widget renders, read from `/api/me` (the cookie
+ * session's `session.user`). `image`/`createdAt` are not on the SDK's
+ * `FlowUser`, so they only come from this authenticated fetch.
+ */
+export type ProfileData = {
+    username: string;
+    image?: string | null;
+    createdAt?: string;
+    isGuest?: boolean;
+};
+/**
+ * Identity the embedding host pushes into the widget over postMessage. Lets the
+ * pill render the username immediately (and reactively on login/logout) without
+ * waiting on `/api/me` — the fast path that also works where third-party cookies
+ * are blocked (Safari/Firefox).
+ */
+export type ProfileIdentity = {
+    username: string;
+    isGuest: boolean;
+};
 export type DialogState = {
     mode: string;
     display: "floating" | "drawer" | "full";
@@ -50,6 +71,7 @@ export type DialogState = {
         username?: string;
         email?: string;
     }>;
+    shown: boolean;
     customFeatures?: DialogCustomFeatures;
     customLabels?: DialogCustomLabels;
 };

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

@@ -8,8 +8,8 @@ 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.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "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" | "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" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "internal_error";
+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 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 {
     service: "auth";

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

@@ -1,8 +1,9 @@
 export type { AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential, FlowUser, PasskeyPluginOptions, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
-export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, } from "./dialog";
+export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, ProfileData, ProfileIdentity, } from "./dialog";
 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, RestoreRequest, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
+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, PrepareArgsWithAuth, PrepareTransactionRequestPhase, 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, 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 { 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/messenger.d.ts

@@ -65,6 +65,7 @@ export type Schema = [
             };
             features?: Record<string, boolean>;
             labels?: Record<string, string>;
+            route?: string;
         } | {
             type: "switch";
             mode: "iframe" | "popup" | "popup-standalone" | "page";
@@ -77,6 +78,27 @@ export type Schema = [
             theme: {
                 colorScheme?: string;
             };
+        } | {
+            type: "profile-resize";
+            width: number;
+            height: number;
+        } | {
+            type: "profile-expand";
+        } | {
+            type: "profile-identity";
+            identity: {
+                username: string;
+                isGuest: boolean;
+            } | null;
+        } | {
+            type: "profile-login";
+            mode: "signin" | "signup";
+        } | {
+            type: "profile-logout";
+        } | {
+            type: "dialog-shown";
+        } | {
+            type: "dialog-hidden";
         };
         response: undefined;
     }
@@ -106,6 +128,14 @@ export type Bridge = WithReady & {
 };
 export type FromWindowOptions = {
     targetOrigin?: string;
+    /**
+     * When set, inbound messages are only accepted from this exact window
+     * (`event.source`). Required when more than one same-origin iframe posts to
+     * the same host window (e.g. the auth dialog and the profile widget) —
+     * origin filtering alone can't tell same-origin frames apart, so without this
+     * one frame's `ready` handshake would resolve the other bridge's gate.
+     */
+    source?: MessageEventSource | null;
 };
 export type BridgeParameters = {
     from: Messenger;

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

@@ -1,6 +1,6 @@
 import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { Address } from "./sdk";
-export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_restore" | "wallet_guest" | "wallet_signout";
+export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_guest" | "wallet_signout";
 export type ConnectCapabilities = {
     createAccount?: boolean;
     signIn?: boolean;
@@ -13,6 +13,8 @@ export type ConnectRequest = [{
 }];
 export type ConnectResponse = {
     jwt: string;
+    /** First-party rotating refresh token; the SDK persists it in the app origin. */
+    refreshToken: string;
     user: FlowUser;
     credential: FlowCredential;
     webauthn?: WebAuthnSignature;
@@ -58,12 +60,12 @@ export type SendCallsRequest = [
 export type SendCallsResponse = {
     id: string;
 };
-export type RestoreRequest = [];
 export type RestoreResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
-    credential: FlowCredential;
-    address: Address;
+    credential: FlowCredential | null;
+    address: Address | null;
 };
 export type GuestRequest = [];
 /**
@@ -73,6 +75,7 @@ export type GuestRequest = [];
  */
 export type GuestResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
     credential: null;
     address: null;
@@ -87,7 +90,6 @@ export type MethodParams = {
     eth_signTypedData: SignTypedDataRequest;
     eth_sendTransaction: SendTransactionRequest;
     wallet_sendCalls: SendCallsRequest;
-    wallet_restore: RestoreRequest;
     wallet_guest: GuestRequest;
     wallet_signout: SignOutRequest;
 };
@@ -97,7 +99,6 @@ export type MethodResult = {
     eth_signTypedData: SignTypedDataResponse;
     eth_sendTransaction: SendTransactionResponse;
     wallet_sendCalls: SendCallsResponse;
-    wallet_restore: RestoreResponse;
     wallet_guest: GuestResponse;
     wallet_signout: SignOutResponse;
 };

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

@@ -129,6 +129,36 @@ export type DialogOpenOptions = {
         icon?: string;
     };
 };
+/** Anchor for an auto-created (host-less) profile widget container. */
+export type ProfilePosition = "top-right" | "top-left" | "bottom-right" | "bottom-left";
+export type MountProfileOptions = {
+    /**
+     * Element to mount the pill iframe into. When omitted, a fixed-position
+     * container is created and anchored via `position` — the path of least
+     * resistance for non-DOM hosts (the Godot canvas overlay).
+     */
+    container?: HTMLElement;
+    /** Anchor used only when `container` is omitted. Defaults to "top-right". */
+    position?: ProfilePosition;
+    /** CSS padding for the auto-created container. Defaults to a responsive inset. */
+    padding?: string;
+    /**
+     * The Flow ID origin serving the widget (e.g. https://id.flow.industries).
+     * Defaults to the resolved Flow instance's `host`, then the SDK default.
+     */
+    host?: string;
+    /**
+     * Color scheme for the widget chrome. Set this to match the host (the dark
+     * game UI passes "dark"). Defaults to "light dark" (follows the OS).
+     */
+    theme?: "light" | "dark" | "light dark";
+    /** Explicit Flow instance. Defaults to the createFlow() singleton. */
+    flow?: Flow;
+};
+export type ProfileButtonHandle = {
+    /** Tears down the iframe, listeners, and any auto-created container. */
+    destroy: () => void;
+};
 export type DialogHost = {
     open: (options?: DialogOpenOptions) => void;
     close: () => void;
@@ -178,6 +208,13 @@ export type Flow = {
     subscribe(listener: Listener<FlowState>): () => void;
     getState(): FlowState;
     dialog: DialogHost;
+    /**
+     * The resolved Flow ID origin this instance talks to (no trailing slash),
+     * e.g. `https://id.flow.industries`. Exposed so widgets like the profile
+     * button build their iframe URL from the single host configured on createFlow
+     * instead of re-resolving it.
+     */
+    readonly host: string;
 };
 export type FlowConnectorParameters = Omit<CreateFlowOptions, "chains" | "transports"> & {
     /**
@@ -202,6 +239,14 @@ export type FlowIdProviderProps = {
     flow?: Flow;
     children: ReactNode;
 };
+export type ProfileButtonProps = {
+    /** Class applied to the host element the pill iframe mounts into. */
+    className?: string;
+    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
+    host?: string;
+    /** Color scheme for the widget chrome; defaults to "light dark" (the OS). */
+    theme?: "light" | "dark" | "light dark";
+};
 export type RunLoginParams = {
     dialog: DialogHost;
     store: Store<FlowState>;
@@ -210,6 +255,7 @@ export type RunLoginParams = {
 };
 export type RunLoginResult = {
     session: Session;
+    refreshToken: string;
     webauthn: ConnectResponse["webauthn"];
 };
 export type FinalizeAccessKeyParams = {

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

@@ -0,0 +1,72 @@
+/** XP / leveling shapes that cross the server/dialog boundary. */
+export interface LevelProgress {
+    /** Level within the current tier, 1..100 — it resets to 1 on each tier-up. */
+    level: number;
+    /** Prestige tier, 1..5. Reaching level 100 rolls into the next tier. */
+    tier: number;
+    /** XP earned since reaching the current level. */
+    xpIntoLevel: number;
+    /** XP between the current level's floor and the next level's floor. */
+    xpForNextLevel: number;
+}
+/** One recent ledger grant. Carries only the static source id — the display
+ * label resolves client-side from the registry, so renames never touch stored
+ * rows or the wire shape. */
+export interface XpRecentGrant {
+    source: string;
+    amount: number;
+    /** ISO timestamp of the grant, for newer-than-last-seen diffing. */
+    at: string;
+}
+/** Response shape of GET /api/xp/me. */
+export interface XpSummary extends LevelProgress {
+    totalXp: number;
+    flowScore: number;
+    /** Last few positive grants, newest first. Optional so client-synthesized
+     * summaries (the widget's per-frame lerp) stay valid without it. */
+    recentGrants?: XpRecentGrant[];
+}
+/** Outcome of one grant attempt. `granted: false` covers idempotent replays,
+ * sub-minimum durations and exhausted daily caps — all non-errors. Carries the
+ * post-grant standing so reporters (the game server) can refresh a player's
+ * nametag level without a second request. */
+export interface XpGrantResult extends LevelProgress {
+    granted: boolean;
+    amount: number;
+    totalXp: number;
+    flowScore: number;
+}
+/** Response of GET /api/xp/day/:source — what the in-game action timer needs to
+ * estimate a live session's XP: today's prior minutes for the source (so the
+ * day-cumulative curve starts from the right point) and the flow multiplier. */
+export interface ActionDayContext {
+    priorMinutes: number;
+    flowScore: number;
+}
+/** Lifecycle state of a durable action session. `abandoned` is set by the
+ * orphan reaper when the game server stops heartbeating a still-active
+ * session (e.g. a server crash). */
+export type ActionSessionState = "active" | "finished" | "abandoned";
+/** An action-session transition kind, appended to the action_event log.
+ * `focus_lost`/`focus_gained` mark the tab going background/foreground — accrual
+ * never stops (they only split focused vs unfocused time for stats). */
+export type ActionEventKind = "start" | "focus_lost" | "focus_gained" | "finish" | "abandon";
+/** Response of GET /api/actions/active — the caller's current in-progress
+ * action (or null when idle), plus the day context so the timer can render the
+ * live XP estimate from the server-authoritative accrued duration. (Always an
+ * `active` session by definition, so the lifecycle state isn't carried.) */
+export interface ActiveActionResponse extends ActionDayContext {
+    source: string;
+    label: string | null;
+    accruedSeconds: number;
+}
+/** Non-sensitive profile facts any player may see about another — nested into
+ * the /api/session/verify payload beside `appearance` so game servers can
+ * broadcast them (avatar + level badge on nametags) without extra fetches.
+ * snake_case keys to match the appearance object in the same payload; the
+ * Godot consumer parses both symmetrically. */
+export interface PublicProfile {
+    avatar_url: string | null;
+    tier: number;
+    level: number;
+}

package/dist/sdk/types/xp.js

@@ -0,0 +1 @@
+/** XP / leveling shapes that cross the server/dialog boundary. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -53,6 +53,7 @@
     "db:push": "bunx drizzle-kit push",
     "db:studio": "bunx drizzle-kit studio",
     "lint": "biome check",
+    "test": "bun test src",
     "format": "biome format --write",
     "check": "biome check --write",
     "typecheck": "tsr generate && tsc --noEmit"
@@ -93,6 +94,7 @@
     "vite": "^7.3.1"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1073.0",
     "@flow-industries/ui": "^0.15.3",
     "@hono/otel": "^1.1.2",
     "@openobserve/browser-logs": "^0.3.1",
@@ -121,6 +123,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-intersection-observer": "^10.0.2",
+    "sharp": "^0.35.2",
     "tempo.ts": "^0.14.2",
     "viem": "2.47.10",
     "wagmi": "^3.4.2",