@flow-industries/id 0.11.0 → 0.13.0

package/dist/sdk/session-route.js

@@ -0,0 +1,127 @@
+/**
+ * The first-party session route every consumer app serves from its own
+ * origin — the only path between a browser and the refresh token. The
+ * rotating refresh token lives in an HttpOnly cookie owned by the app's
+ * server; the browser client calls this route instead of ever holding the
+ * token itself:
+ *
+ *  - `GET`    resolve: fresh JWT from the cookies, rotating server-side when
+ *             the access token is expiring.
+ *  - `POST`   install: one-time handoff of a freshly minted session (refresh
+ *             token + access JWT from the dialog) into the HttpOnly cookies.
+ *             The JWT verifies locally against the issuer's cached JWKS — no
+ *             rotation of a seconds-old token; a bogus refresh token simply
+ *             dies at the first GET, like any planted cookie.
+ *  - `DELETE` sign-out: revoke the token's lineage at the issuer and clear
+ *             the cookies.
+ *
+ * Framework-agnostic (`Request` → `Response`); `flowSessionHandlers` from
+ * `@flow-industries/id/start` adapts it to a TanStack Start route file.
+ */
+import { cookieNamesFor, parseCookieHeader } from "./cookies";
+import { DEFAULT_SESSION_PATH, defaultAudience, resolveIdHost, } from "./id-host";
+import { claimsToUser, clearingCookies, isJwtVerificationFailure, resolveSessionCore, sessionCookies, } from "./session-core";
+import { verifyFlowJWT } from "./verify";
+function json(body, status, setCookies = []) {
+    const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    for (const cookie of setCookies)
+        headers.append("Set-Cookie", cookie);
+    return new Response(JSON.stringify(body), { status, headers });
+}
+/**
+ * Cross-site requests must never reach the session route: the cookies are
+ * SameSite=Lax already, so this is defense in depth. `Sec-Fetch-Site` is
+ * authoritative where present ("none" = direct navigation, harmless); the
+ * Origin header — sent by browsers on every non-GET — must match the app.
+ * Requests carrying neither header (server-to-server tooling) pass.
+ */
+function isCrossSite(request, audience) {
+    const site = request.headers.get("Sec-Fetch-Site");
+    if (site && site !== "same-origin" && site !== "none")
+        return true;
+    const origin = request.headers.get("Origin");
+    if (origin && origin !== audience && origin !== new URL(request.url).origin) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Handles one session-route request (no path check — the caller routed it).
+ * `audience` defaults per `defaultAudience` (`APP_ORIGIN` env, then the
+ * request's own origin); `issuerUrl` per `defaultIdHost`.
+ */
+export async function handleSessionRequest(request, opts = {}) {
+    const audience = opts.audience ?? defaultAudience(new URL(request.url).origin);
+    const issuerUrl = resolveIdHost(opts.issuerUrl, audience);
+    if (isCrossSite(request, audience)) {
+        return json({ state: null }, 403);
+    }
+    switch (request.method) {
+        case "GET": {
+            const { session, setCookies } = await resolveSessionCore(request.headers.get("Cookie"), audience, issuerUrl);
+            return json({ state: session }, 200, setCookies);
+        }
+        case "POST": {
+            const body = (await request.json().catch(() => null));
+            const refreshToken = body?.refreshToken;
+            const jwt = body?.jwt;
+            if (typeof refreshToken !== "string" ||
+                refreshToken.length === 0 ||
+                typeof jwt !== "string" ||
+                jwt.length === 0) {
+                return json({ state: null }, 400);
+            }
+            // The audience check on the verified JWT is what stops a token minted
+            // for another app from being installed here; a failed install must not
+            // clear cookies that may hold a live session.
+            try {
+                const claims = await verifyFlowJWT(jwt, { audience, issuerUrl });
+                return json({ state: { user: claimsToUser(claims), jwt } }, 200, sessionCookies(audience, jwt, refreshToken));
+            }
+            catch (err) {
+                return json({ state: null }, isJwtVerificationFailure(err) ? 401 : 502);
+            }
+        }
+        case "DELETE": {
+            const names = cookieNamesFor(audience);
+            const token = parseCookieHeader(request.headers.get("Cookie"))[names.refresh];
+            // Best-effort: clearing the cookies signs this browser out either way;
+            // an unreachable issuer just leaves the lineage to expire on its own.
+            if (token) {
+                try {
+                    await fetch(`${issuerUrl}/api/session/revoke`, {
+                        method: "POST",
+                        headers: { Authorization: `Bearer ${token}` },
+                    });
+                }
+                catch { }
+            }
+            const headers = new Headers({ "Cache-Control": "no-store" });
+            for (const cookie of clearingCookies(audience)) {
+                headers.append("Set-Cookie", cookie);
+            }
+            return new Response(null, { status: 204, headers });
+        }
+        default:
+            return new Response(null, {
+                status: 405,
+                headers: { Allow: "GET, POST, DELETE" },
+            });
+    }
+}
+/**
+ * Wraps `handleSessionRequest` with a path check for servers that route by
+ * hand (a Bun/Hono server): returns null for requests that aren't for the
+ * session path so the caller can fall through.
+ */
+export function createSessionHandler(opts = {}) {
+    const path = opts.path ?? DEFAULT_SESSION_PATH;
+    return async (request) => {
+        if (new URL(request.url).pathname !== path)
+            return null;
+        return handleSessionRequest(request, opts);
+    };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * TanStack Start integration — the whole Flow ID wiring a Start app needs,
+ * so integrating a new domain is one route file plus one root wrapper:
+ *
+ * ```tsx
+ * // src/routes/flow.session.ts — the first-party session route + SSR fn
+ * import { createServerFn } from "@tanstack/react-start";
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { flowSessionHandlers, resolveFlowSessionRequest } from "@flow-industries/id/start/server";
+ *
+ * export const getFlowSession = createServerFn({ method: "GET" }).handler(resolveFlowSessionRequest);
+ * export const Route = createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } });
+ *
+ * // src/routes/__root.tsx
+ * beforeLoad: () => flowSessionContext(getFlowSession),
+ * // and in the root component:
+ * <FlowRoot session={session}>{children}</FlowRoot>
+ * ```
+ *
+ * The server fn stays in app source because TanStack's compiler splits it
+ * into the server bundle there; everything it does lives here.
+ */
+import { type ReactNode } from "react";
+import type { AdditionalSession, FlowSessionState } from "../types";
+/**
+ * The `beforeLoad` body: during SSR resolve the session server-side (via the
+ * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);
+ * in the browser snapshot the live singleton instead — no network.
+ */
+export declare function flowSessionContext(getSession: () => Promise<FlowSessionState | null>): Promise<{
+    session: FlowSessionState | null;
+}>;
+export type FlowRootProps = {
+    /** The session resolved by `flowSessionContext` in `beforeLoad`. */
+    session: FlowSessionState | null;
+    /** Mint a silent guest for first-time visitors (see `CreateFlowOptions`). */
+    autoGuest?: boolean;
+    /** Override the Flow ID origin; defaults per `defaultIdHost`. */
+    host?: string;
+    /** Extra audiences every mint requests (see `CreateFlowOptions`). */
+    additionalAudiences?: readonly string[];
+    /** One-time delivery of the extra sessions (see `CreateFlowOptions`). */
+    onAdditionalSessions?: (sessions: AdditionalSession[]) => void;
+    children: ReactNode;
+};
+/**
+ * Renders the subtree under a request-scoped static Flow on the server and
+ * the seeded browser singleton on the client, so the first client render
+ * matches the SSR HTML and no bootstrap refresh runs while the hydrated JWT
+ * is fresh.
+ */
+export declare function FlowRoot({ session, autoGuest, host, additionalAudiences, onAdditionalSessions, children, }: FlowRootProps): import("react/jsx-runtime").JSX.Element;

package/dist/sdk/start/index.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * TanStack Start integration — the whole Flow ID wiring a Start app needs,
+ * so integrating a new domain is one route file plus one root wrapper:
+ *
+ * ```tsx
+ * // src/routes/flow.session.ts — the first-party session route + SSR fn
+ * import { createServerFn } from "@tanstack/react-start";
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { flowSessionHandlers, resolveFlowSessionRequest } from "@flow-industries/id/start/server";
+ *
+ * export const getFlowSession = createServerFn({ method: "GET" }).handler(resolveFlowSessionRequest);
+ * export const Route = createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } });
+ *
+ * // src/routes/__root.tsx
+ * beforeLoad: () => flowSessionContext(getFlowSession),
+ * // and in the root component:
+ * <FlowRoot session={session}>{children}</FlowRoot>
+ * ```
+ *
+ * The server fn stays in app source because TanStack's compiler splits it
+ * into the server bundle there; everything it does lives here.
+ */
+import { useMemo } from "react";
+import { createFlow, createStaticFlow, getFlow } from "../client";
+import { FlowIdProvider } from "../react";
+/**
+ * The `beforeLoad` body: during SSR resolve the session server-side (via the
+ * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);
+ * in the browser snapshot the live singleton instead — no network.
+ */
+export async function flowSessionContext(getSession) {
+    if (typeof window === "undefined")
+        return { session: await getSession() };
+    const flow = getFlow();
+    const session = flow?.user && flow.jwt
+        ? { user: flow.user, jwt: flow.jwt, address: flow.address }
+        : null;
+    return { session };
+}
+/**
+ * Renders the subtree under a request-scoped static Flow on the server and
+ * the seeded browser singleton on the client, so the first client render
+ * matches the SSR HTML and no bootstrap refresh runs while the hydrated JWT
+ * is fresh.
+ */
+export function FlowRoot({ session, autoGuest, host, additionalAudiences, onAdditionalSessions, children, }) {
+    const flow = useMemo(() => typeof window === "undefined"
+        ? createStaticFlow(session, { host })
+        : createFlow({
+            initialState: session,
+            autoGuest,
+            host,
+            additionalAudiences,
+            onAdditionalSessions,
+        }), [session, autoGuest, host, additionalAudiences, onAdditionalSessions]);
+    return _jsx(FlowIdProvider, { flow: flow, children: children });
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Server half of the TanStack Start integration: the session-route handlers
+ * and the SSR resolve used by the app's `getFlowSession` server fn. Import
+ * only from app-source files the Start compiler splits server-side (the
+ * session route file) — see `@flow-industries/id/start` for the wiring.
+ */
+import type { FlowSessionState, SessionRouteOptions } from "../types";
+/**
+ * The `getFlowSession` server-fn handler: resolves the visitor's session
+ * from the request cookies during SSR. A server-side refresh rotates the
+ * token, so the rotated Set-Cookie values are appended to the response here
+ * rather than left to callers. The audience is pinned by `APP_ORIGIN`
+ * (mandatory behind a TLS-terminating proxy), falling back to the request
+ * origin in dev.
+ */
+export declare function resolveFlowSessionRequest(): Promise<FlowSessionState | null>;
+/**
+ * Route handlers for the app's session route file:
+ * `createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } })`.
+ * The route path must match the client's `sessionPath` (default
+ * `/flow/session`).
+ */
+export declare function flowSessionHandlers(opts?: SessionRouteOptions): {
+    GET: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+    POST: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+    DELETE: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+};

package/dist/sdk/start/server.js

@@ -0,0 +1,35 @@
+/**
+ * Server half of the TanStack Start integration: the session-route handlers
+ * and the SSR resolve used by the app's `getFlowSession` server fn. Import
+ * only from app-source files the Start compiler splits server-side (the
+ * session route file) — see `@flow-industries/id/start` for the wiring.
+ */
+import { getRequestHeader, getRequestUrl, setResponseHeader, } from "@tanstack/react-start/server";
+import { defaultAudience, defaultIdHost } from "../id-host";
+import { resolveSession } from "../server";
+import { handleSessionRequest } from "../session-route";
+/**
+ * The `getFlowSession` server-fn handler: resolves the visitor's session
+ * from the request cookies during SSR. A server-side refresh rotates the
+ * token, so the rotated Set-Cookie values are appended to the response here
+ * rather than left to callers. The audience is pinned by `APP_ORIGIN`
+ * (mandatory behind a TLS-terminating proxy), falling back to the request
+ * origin in dev.
+ */
+export async function resolveFlowSessionRequest() {
+    const audience = defaultAudience(getRequestUrl().origin);
+    const { state, setCookies } = await resolveSession(getRequestHeader("cookie"), { audience, issuerUrl: defaultIdHost(audience) });
+    if (setCookies.length > 0)
+        setResponseHeader("Set-Cookie", setCookies);
+    return state;
+}
+/**
+ * Route handlers for the app's session route file:
+ * `createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } })`.
+ * The route path must match the client's `sessionPath` (default
+ * `/flow/session`).
+ */
+export function flowSessionHandlers(opts = {}) {
+    const handler = ({ request }) => handleSessionRequest(request, opts);
+    return { GET: handler, POST: handler, DELETE: handler };
+}

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

@@ -14,11 +14,24 @@ export type FlowCredential = {
     id: string;
     publicKey: string;
 };
+/**
+ * A session minted for one of the ADDITIONAL audiences a login requested
+ * (AUTH-39): its own refresh-token lineage and access JWT, both bound to
+ * `audience`. Installed once into that origin's own HttpOnly cookies via its
+ * `/flow/session` route (the embed bootstrap) — never held by page JS beyond
+ * the one-time handoff.
+ */
+export type AdditionalSession = {
+    audience: string;
+    jwt: string;
+    refreshToken: string;
+};
 export type AuthResponse = {
     jwt: string;
     refreshToken: string;
     user: FlowUser;
     credential: FlowCredential;
+    additionalSessions?: AdditionalSession[];
 };
 export type AuthConfig = {
     rpId: string;

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.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 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.audience.minted" | "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

@@ -1,11 +1,11 @@
-export type { AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential, FlowUser, PasskeyPluginOptions, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
+export type { AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential, FlowUser, PasskeyPluginOptions, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
 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, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { CreateRoomInput, MyRooms, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, UpdateRoomInput, VerifyRoomContext, } from "./rooms";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, 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 { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, 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 { ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } 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/protocol.d.ts

@@ -1,4 +1,4 @@
-import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
+import type { AdditionalSession, FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { Address } from "./sdk";
 export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_guest" | "wallet_signout";
 export type ConnectCapabilities = {
@@ -14,6 +14,12 @@ export type ConnectCapabilities = {
      * cookie session; see the register endpoint.
      */
     guestToken?: string;
+    /**
+     * Extra audiences to mint refresh tokens for in the same login (AUTH-39).
+     * The server refuses any entry outside its explicit origin -> audiences
+     * allowlist; allowed entries come back as `additionalSessions`.
+     */
+    additionalAudiences?: readonly string[];
 };
 export type ConnectRequest = [{
     capabilities?: ConnectCapabilities;
@@ -25,6 +31,7 @@ export type ConnectResponse = {
     user: FlowUser;
     credential: FlowCredential;
     webauthn?: WebAuthnSignature;
+    additionalSessions?: AdditionalSession[];
 };
 export type SignMessageRequest = [message: string, address: string];
 export type SignMessageResponse = `0x${string}`;
@@ -74,7 +81,9 @@ export type RestoreResponse = {
     credential: FlowCredential | null;
     address: Address | null;
 };
-export type GuestRequest = [];
+export type GuestRequest = [] | [{
+    additionalAudiences?: readonly string[];
+}];
 /**
  * A guest has no passkey and no derivable wallet address yet, so `credential`
  * and `address` are always null — the shape mirrors RestoreResponse so the SDK
@@ -86,6 +95,7 @@ export type GuestResponse = {
     user: FlowUser;
     credential: null;
     address: null;
+    additionalSessions?: AdditionalSession[];
 };
 export type SignOutRequest = [];
 export type SignOutResponse = {

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { Chain, Hex, PrepareTransactionRequestParameters, SendTransactionParameters, SignTypedDataParameters, Transport, WalletClient } from "viem";
 import type { SendCallsParameters } from "viem/actions";
-import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
+import type { AdditionalSession, FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { ConnectCapabilities, ConnectResponse } from "./protocol";
 import type { RoomsApi } from "./rooms";
 export type Address = `0x${string}`;
@@ -72,14 +72,14 @@ export type CreateFlowOptions = {
      */
     autoGuest?: boolean;
     /**
-     * If true, the session lives in first-party cookies on the app's own
-     * origin: the JWT is mirrored there from memory and the rotating refresh
-     * token is stored there alone (not in localStorage), so the app's server
-     * can resolve and rotate 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.
+     * Path of the app's first-party session route (see
+     * `@flow-industries/id/server`). The refresh token lives in an HttpOnly
+     * cookie owned by the app's server; the client resolves, installs, and
+     * revokes the session exclusively through this same-origin route. Override
+     * only when the app cannot claim the default path — the route registration
+     * must use the same value.
      */
-    cookies?: boolean;
+    sessionPath?: string;
     /**
      * Session state resolved server-side (via `resolveSession`) to seed the
      * store synchronously, so the first client render matches the SSR HTML and
@@ -88,6 +88,22 @@ export type CreateFlowOptions = {
      * bootstrap.
      */
     initialState?: FlowSessionState | null;
+    /**
+     * Extra audiences every dialog mint (login, guest) requests refresh tokens
+     * for, on top of the app's own (AUTH-39). Only audiences the auth server
+     * explicitly allowlists for this origin succeed — anything else fails the
+     * mint. The minted sessions are delivered once via `onAdditionalSessions`
+     * and never stored; the app forwards each to its own origin (e.g. the
+     * same-site chat embed's `/flow/session`) to be sealed HttpOnly.
+     */
+    additionalAudiences?: readonly string[];
+    /**
+     * One-time delivery of the additional-audience sessions minted at login or
+     * guest creation. Fired after the app's own session installs; the receiver
+     * must hand each session to its audience's origin (the embed bootstrap) and
+     * drop it — nothing here is retained by the SDK.
+     */
+    onAdditionalSessions?: (sessions: AdditionalSession[]) => void;
 };
 export type FlowState = {
     user: FlowUser | null;
@@ -115,10 +131,6 @@ export type FlowCookieNames = {
     jwt: string;
     refresh: string;
 };
-export type RefreshCookieConfig = {
-    name: string;
-    secure: boolean;
-};
 export type LoginOptions = {
     mode?: "iframe" | "popup";
     signUp?: boolean;
@@ -301,6 +313,7 @@ export type RunLoginResult = {
     session: Session;
     refreshToken: string;
     webauthn: ConnectResponse["webauthn"];
+    additionalSessions?: AdditionalSession[];
 };
 export type FinalizeAccessKeyParams = {
     address: Address;

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

@@ -1,5 +1,5 @@
-import type { VerifiedFlowJWT } from "./auth";
-import type { FlowSessionState } from "./sdk";
+import type { FlowCredential, FlowUser, VerifiedFlowJWT } from "./auth";
+import type { Address, 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`. */
@@ -26,3 +26,31 @@ export type ResolvedFlowSession = {
     /** Public profile, only when requested via `profile: true` and resolvable. */
     profile?: PublicProfile;
 };
+export type SessionRouteOptions = {
+    /**
+     * The app's public origin, e.g. `https://flow.game` — the JWT audience and
+     * what cookie names derive from. Defaults to the `APP_ORIGIN` env var, then
+     * the request's own origin (fine in dev; behind a TLS-terminating proxy set
+     * `APP_ORIGIN`).
+     */
+    audience?: string;
+    /** Flow ID origin; defaults per `defaultIdHost` (`FLOW_ID_HOST` on servers). */
+    issuerUrl?: string;
+    /** Route path for `createSessionHandler`'s own path check. */
+    path?: string;
+};
+/**
+ * A session as the session route reports it to the browser client.
+ * `credential`/`address` are present only when the token was rotated
+ * server-side — the rotation response is authoritative for signing state,
+ * while the JWT hot path knows neither and the client must keep what it has.
+ */
+export type SessionRouteSession = {
+    user: FlowUser;
+    jwt: string;
+    credential?: FlowCredential | null;
+    address?: Address | null;
+};
+export type SessionRouteResponse = {
+    state: SessionRouteSession | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -33,6 +33,14 @@
     "./server": {
       "types": "./dist/sdk/server.d.ts",
       "import": "./dist/sdk/server.js"
+    },
+    "./start": {
+      "types": "./dist/sdk/start/index.d.ts",
+      "import": "./dist/sdk/start/index.js"
+    },
+    "./start/server": {
+      "types": "./dist/sdk/start/server.d.ts",
+      "import": "./dist/sdk/start/server.js"
     }
   },
   "files": [
@@ -66,7 +74,8 @@
     "viem": ">=2.47.10",
     "ox": ">=0.14.0",
     "react": ">=18",
-    "@wagmi/core": ">=3.0.0"
+    "@wagmi/core": ">=3.0.0",
+    "@tanstack/react-start": ">=1.168.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -74,6 +83,9 @@
     },
     "@wagmi/core": {
       "optional": true
+    },
+    "@tanstack/react-start": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -83,6 +95,7 @@
     "@react-email/ui": "^6.6.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-router-devtools": "^1.160.0",
+    "@tanstack/react-start": "^1.168.28",
     "@tanstack/router-cli": "^1.167.17",
     "@tanstack/router-plugin": "^1.160.0",
     "@types/bun": "latest",

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

@@ -1 +0,0 @@
-export {};