@flow-industries/id 0.10.0 → 0.12.0

package/dist/sdk/server.js

@@ -1,68 +1,7 @@
-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";
+import { resolveIdHost } from "./id-host";
+import { resolveSessionCore } from "./session-core";
+export { createSessionHandler, handleSessionRequest } from "./session-route";
 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`, {
@@ -80,121 +19,26 @@ async function fetchProfile(issuerUrl, jwt, audience) {
     }
 }
 /**
- * Resolves the visitor's Flow session from the request's Cookie header — the
- * server-side counterpart of `createFlow({ cookies: true })`, for rendering
- * auth-aware UI without a client round-trip.
- *
- * Resolution order:
- *  1. A still-fresh JWT cookie verifies locally against the issuer's JWKS
- *     (cached per process) — the hot path, no auth-server call, no cookies
- *     to set.
- *  2. Otherwise a refresh cookie is presented to `/api/session/refresh`,
- *     which ROTATES it — append every entry of `setCookies` to the response
- *     or the client is left holding a dead predecessor. A definitive
- *     rejection (401/403) yields clearing cookies instead; a network failure
- *     leaves the cookies alone so a later request can retry.
- *  3. Neither cookie → signed-out `state: null`.
- *
- * Feed `state` into the SSR payload and `createFlow({ initialState })` so the
- * hydrated client renders it without a second refresh.
+ * Resolves the visitor's Flow session from the request's Cookie header for
+ * SSR: render auth-aware UI without a client round-trip, then feed `state`
+ * into the SSR payload and `createFlow({ initialState })` so the hydrated
+ * client renders it without a second refresh. Append every entry of
+ * `setCookies` to the response or the client is left holding a dead
+ * predecessor (a server-side refresh ROTATES the token).
  */
 export 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)
+    const issuerUrl = resolveIdHost(opts.issuerUrl, opts.audience);
+    const { session, claims, setCookies } = await resolveSessionCore(cookieHeader, opts.audience, issuerUrl);
+    const state = session
+        ? { user: session.user, jwt: session.jwt, address: session.address ?? null }
+        : null;
+    const profile = state && opts.profile
+        ? await fetchProfile(issuerUrl, state.jwt, opts.audience)
         : undefined;
     return {
         state,
         claims,
-        setCookies: successorCookies,
+        setCookies,
         ...(profile ? { profile } : {}),
     };
 }

package/dist/sdk/session-core.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Internal session-resolution core shared by `resolveSession` (SSR) and the
+ * session route. Not part of the published API surface — `server.ts` and
+ * `session-route.ts` compose it into the public entry points.
+ */
+import type { FlowUser, SessionRouteSession, VerifiedFlowJWT } from "./types";
+export declare function claimsToUser(claims: VerifiedFlowJWT): FlowUser;
+export declare function isJwtVerificationFailure(err: unknown): boolean;
+/** The Set-Cookie pair carrying a session (1h JWT + 30-day refresh token). */
+export declare function sessionCookies(audience: string, jwt: string, refreshToken: string): string[];
+/** The Set-Cookie pair deleting both session cookies. */
+export declare function clearingCookies(audience: string): string[];
+/**
+ * The resolution result shared by `resolveSession` (SSR) and the session
+ * route. On the refresh path `session` carries the authoritative signing
+ * state (`credential`/`address`) from the rotation response; on the JWT hot
+ * path both keys are absent — the claims carry neither, and the consumer
+ * must not overwrite signing state it already holds.
+ */
+export type ResolvedSessionCore = {
+    session: SessionRouteSession | null;
+    claims: VerifiedFlowJWT | null;
+    setCookies: string[];
+};
+/**
+ * Rotates a refresh token through the issuer and re-verifies the minted JWT.
+ * 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 ⇒ clearing cookies; a transient
+ * JWKS failure still hands the successor over (the rotation already
+ * happened) but resolves signed-out rather than trusting it. Returns "dead"
+ * for a definitive rejection and null for a transient network failure.
+ */
+export declare function refreshSessionCore(issuerUrl: string, audience: string, refreshToken: string): Promise<ResolvedSessionCore | "dead" | null>;
+/**
+ * Resolves a session from a request's Cookie header.
+ *
+ * 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 — the returned `setCookies` must reach the response.
+ *     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 `session: null`.
+ */
+export declare function resolveSessionCore(cookieHeader: string | null | undefined, audience: string, issuerUrl: string): Promise<ResolvedSessionCore>;

package/dist/sdk/session-core.js

@@ -0,0 +1,176 @@
+/**
+ * Internal session-resolution core shared by `resolveSession` (SSR) and the
+ * session route. Not part of the published API surface — `server.ts` and
+ * `session-route.ts` compose it into the public entry points.
+ */
+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 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 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.
+export 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");
+}
+/** The Set-Cookie pair carrying a session (1h JWT + 30-day refresh token). */
+export function sessionCookies(audience, jwt, refreshToken) {
+    const names = cookieNamesFor(audience);
+    const secure = audience.startsWith("https:");
+    return [
+        serializeCookie(names.jwt, jwt, { maxAge: JWT_COOKIE_MAX_AGE_S, secure }),
+        serializeCookie(names.refresh, refreshToken, {
+            maxAge: REFRESH_COOKIE_MAX_AGE_S,
+            secure,
+        }),
+    ];
+}
+/** The Set-Cookie pair deleting both session cookies. */
+export function clearingCookies(audience) {
+    const names = cookieNamesFor(audience);
+    const secure = audience.startsWith("https:");
+    return [
+        clearCookieString(names.jwt, { secure }),
+        clearCookieString(names.refresh, { secure }),
+    ];
+}
+/**
+ * Rotates a refresh token through the issuer and re-verifies the minted JWT.
+ * 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 ⇒ clearing cookies; a transient
+ * JWKS failure still hands the successor over (the rotation already
+ * happened) but resolves signed-out rather than trusting it. Returns "dead"
+ * for a definitive rejection and null for a transient network failure.
+ */
+export async function refreshSessionCore(issuerUrl, audience, refreshToken) {
+    const result = await refreshOnce(issuerUrl, refreshToken);
+    if (result === "dead" || !result)
+        return result;
+    const successorCookies = sessionCookies(audience, result.jwt, result.refreshToken);
+    let claims;
+    try {
+        claims = await verifyFlowJWT(result.jwt, { audience, issuerUrl });
+    }
+    catch (err) {
+        if (isJwtVerificationFailure(err)) {
+            return {
+                session: null,
+                claims: null,
+                setCookies: clearingCookies(audience),
+            };
+        }
+        return { session: null, claims: null, setCookies: successorCookies };
+    }
+    return {
+        session: {
+            user: result.user,
+            jwt: result.jwt,
+            credential: result.credential,
+            address: result.address,
+        },
+        claims,
+        setCookies: successorCookies,
+    };
+}
+/**
+ * Resolves a session from a request's Cookie header.
+ *
+ * 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 — the returned `setCookies` must reach the response.
+ *     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 `session: null`.
+ */
+export async function resolveSessionCore(cookieHeader, audience, issuerUrl) {
+    const names = cookieNamesFor(audience);
+    const cookies = parseCookieHeader(cookieHeader);
+    const jwt = cookies[names.jwt];
+    if (jwt && !isExpiring(jwt)) {
+        try {
+            const claims = await verifyFlowJWT(jwt, { audience, issuerUrl });
+            return {
+                session: { user: claimsToUser(claims), jwt },
+                claims,
+                setCookies: [],
+            };
+        }
+        catch (err) {
+            if (!isJwtVerificationFailure(err)) {
+                return { session: null, claims: null, setCookies: [] };
+            }
+        }
+    }
+    const refreshToken = cookies[names.refresh];
+    if (!refreshToken)
+        return { session: null, claims: null, setCookies: [] };
+    const refreshed = await refreshSessionCore(issuerUrl, audience, refreshToken);
+    if (refreshed === "dead") {
+        return {
+            session: null,
+            claims: null,
+            setCookies: clearingCookies(audience),
+        };
+    }
+    if (!refreshed)
+        return { session: null, claims: null, setCookies: [] };
+    return refreshed;
+}

package/dist/sdk/session-route.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 type { SessionRouteOptions } from "./types";
+/**
+ * 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 declare function handleSessionRequest(request: Request, opts?: SessionRouteOptions): Promise<Response>;
+/**
+ * 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 declare function createSessionHandler(opts?: SessionRouteOptions): (request: Request) => Promise<Response | null>;

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,48 @@
+/**
+ * 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 { 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;
+    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, children, }: FlowRootProps): import("react/jsx-runtime").JSX.Element;