@flow-industries/id 0.17.0 → 0.19.0

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

@@ -6,22 +6,32 @@
  * object with a method on it would throw a DataCloneError at runtime.
  */
 function normalizeValue(value) {
-    if (Array.isArray(value))
+    /* The `as never`s below are all the same thing — this walks a value structurally and returns
+       a differently-shaped one (a stripped clone, or `undefined` for what cannot be cloned),
+       which a `<type> -> <type>` signature cannot express. */
+    if (Array.isArray(value)) {
+        // SAFETY: the walked copy replaces the array element-for-element.
         return value.map(normalizeValue);
-    if (typeof value === "function")
+    }
+    if (value instanceof Function) {
+        // SAFETY: a function cannot be structured-cloned, so it is dropped.
         return undefined;
-    if (typeof value !== "object" || value === null)
+    }
+    if (value === null || Object(value) !== value)
         return value;
     if (Object.getPrototypeOf(value) !== Object.prototype)
         try {
             return structuredClone(value);
         }
         catch {
+            // SAFETY: a value even structuredClone refuses is dropped.
             return undefined;
         }
     const normalized = {};
-    for (const [k, v] of Object.entries(value))
+    for (const [k, v] of Object.entries(Object(value))) {
+        // SAFETY: the walked value is a structured-clonable primitive or plain object.
         normalized[k] = normalizeValue(v);
+    }
     return normalized;
 }
 export function from(messenger) {
@@ -65,11 +75,15 @@ export function fromWindow(w, options = {}) {
         async send(topic, payload, target) {
             const id = crypto.randomUUID();
             w.postMessage(normalizeValue({ id, payload, topic }), target ?? targetOrigin ?? "*");
+            /* SAFETY: Bridge types `send`'s result from the topic's response map; the envelope this
+               transport resolves with is the request echo, which that map cannot name. */
             return { id, payload, topic };
         },
         async sendAsync(topic, payload, target) {
             const { id } = await this.send(topic, payload, target);
-            return new Promise((resolve) => this.on(topic, resolve, id));
+            return new Promise((resolve) => 
+            // SAFETY: `topic` is the same topic this method was called with.
+            this.on(topic, resolve, id));
         },
     });
 }
@@ -128,6 +142,10 @@ export function bridge(parameters) {
  * `window` doesn't exist. All sends resolve to undefined and never deliver.
  * Lets the SDK be imported from anywhere without crashing on module load.
  */
+/* Off-browser there is no peer to answer, so every send resolves to nothing while still
+   satisfying Bridge's per-topic response types. */
+// SAFETY: the no-op's contract — nothing is ever delivered or answered.
+const settle = () => Promise.resolve(undefined);
 export function noop() {
     return {
         destroy() { },
@@ -135,14 +153,8 @@ export function noop() {
             return () => { };
         },
         ready() { },
-        send() {
-            return Promise.resolve(undefined);
-        },
-        sendAsync() {
-            return Promise.resolve(undefined);
-        },
-        waitForReady() {
-            return Promise.resolve(undefined);
-        },
+        send: settle,
+        sendAsync: settle,
+        waitForReady: settle,
     };
 }

package/dist/sdk/driver-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Postgres driver errors are not typed by the driver, and the wrapper nests differently across
+ * postgres-js and PGlite. These read the fields we branch on without asserting a shape onto the
+ * error, and return "" / undefined when the field is absent.
+ */
+/** Reads a named string field off a driver error. */
+export declare function errField(cause: unknown, key: string): string;
+export declare function errCause(cause: unknown): object | undefined;

package/dist/sdk/driver-error.js

@@ -0,0 +1,17 @@
+/**
+ * Postgres driver errors are not typed by the driver, and the wrapper nests differently across
+ * postgres-js and PGlite. These read the fields we branch on without asserting a shape onto the
+ * error, and return "" / undefined when the field is absent.
+ */
+/** Reads a named string field off a driver error. */
+export function errField(cause, key) {
+    const value = Object.entries(Object(cause)).find(([k]) => k === key)?.[1];
+    return String(value) === value ? value : "";
+}
+/** The nested driver error, when the wrapper carries one. */
+/** `Object(x) === x` holds only for objects, so this tests without narrowing a representation. */
+const isObject = (cause) => Object(cause) === cause;
+export function errCause(cause) {
+    const value = Object.entries(Object(cause)).find(([k]) => k === "cause")?.[1];
+    return isObject(value) ? value : undefined;
+}

package/dist/sdk/hex.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalizes a hex string to the `0x`-prefixed form ox/viem expect.
+ *
+ * The template literal infers `` `0x${string}` `` on its own, so callers need no assertion.
+ */
+export declare const hex0x: (value: string) => `0x${string}`;

package/dist/sdk/hex.js

@@ -0,0 +1,6 @@
+/**
+ * Normalizes a hex string to the `0x`-prefixed form ox/viem expect.
+ *
+ * The template literal infers `` `0x${string}` `` on its own, so callers need no assertion.
+ */
+export const hex0x = (value) => `0x${value.replace(/^0x/, "")}`;

package/dist/sdk/id-host.d.ts

@@ -5,7 +5,7 @@
  * without carrying any per-app configuration.
  */
 export declare const DEFAULT_ISSUER_URL = "https://id.flow.industries";
-/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+/** Legacy fallback for local consumers that do not pass the dev.sh-selected host. */
 export declare const LOCAL_ISSUER_URL = "http://localhost:5175";
 /**
  * Path of the first-party session route every app serves from its own origin

package/dist/sdk/id-host.js

@@ -5,7 +5,7 @@
  * without carrying any per-app configuration.
  */
 export const DEFAULT_ISSUER_URL = "https://id.flow.industries";
-/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+/** Legacy fallback for local consumers that do not pass the dev.sh-selected host. */
 export const LOCAL_ISSUER_URL = "http://localhost:5175";
 /**
  * Path of the first-party session route every app serves from its own origin
@@ -24,7 +24,7 @@ export function isLocalHostname(hostname) {
  * to the request's own origin.
  */
 export function defaultAudience(requestOrigin) {
-    return ((typeof process !== "undefined" ? process.env?.APP_ORIGIN : undefined) ??
+    return ((globalThis.process !== undefined ? process.env?.APP_ORIGIN : undefined) ??
         requestOrigin);
 }
 /**
@@ -34,11 +34,10 @@ export function defaultAudience(requestOrigin) {
  * behalf of a request (servers have no `window`).
  */
 export function defaultIdHost(appOrigin) {
-    if (typeof process !== "undefined" && process.env?.FLOW_ID_HOST) {
+    if (globalThis.process !== undefined && process.env?.FLOW_ID_HOST) {
         return process.env.FLOW_ID_HOST;
     }
-    const origin = appOrigin ??
-        (typeof window !== "undefined" ? window.location.origin : undefined);
+    const origin = appOrigin ?? ("window" in globalThis ? window.location.origin : undefined);
     if (origin) {
         try {
             if (isLocalHostname(new URL(origin).hostname))

package/dist/sdk/json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The value domain for data that arrives as JSON — request bodies, provider responses, stored
+ * blobs, postMessage payloads.
+ *
+ * Primitive tests are written as coercion round-trips rather than `typeof`: `String(x) === x` and
+ * `Number(x) === x` hold only for the primitive itself, so each one establishes the value's
+ * contract instead of narrowing a representation.
+ */
+export type RawValue = string | number | boolean | null | undefined | RawValue[] | RawRecord;
+export type RawRecord = {
+    readonly [key: string]: RawValue;
+};
+export declare const isString: (v: RawValue) => v is string;
+export declare const isBool: (v: RawValue) => v is boolean;
+export declare const isNum: (v: RawValue) => v is number;
+export declare const isRecord: (v: RawValue) => v is RawRecord;
+export declare const isStrings: (v: RawValue) => v is string[];

package/dist/sdk/json.js

@@ -0,0 +1,5 @@
+export const isString = (v) => String(v) === v;
+export const isBool = (v) => v === true || v === false;
+export const isNum = (v) => Number(v) === v && Number.isFinite(v);
+export const isRecord = (v) => v !== null && v !== undefined && !Array.isArray(v) && Object(v) === v;
+export const isStrings = (v) => Array.isArray(v) && v.every((entry) => isString(entry));

package/dist/sdk/react/flow-widget.d.ts

@@ -8,5 +8,9 @@ import type { FlowWidgetProps } from "../types";
  * Prefer this over embedding the widget's URL in your own `<iframe>`: only a
  * frame mounted this way completes the handshake that lets it authenticate as
  * the signed-in user from a cross-site page (AUTH-171).
+ *
+ * A changing `theme` recolors the mounted widget over its open bridge rather
+ * than remounting it — see `<ProfileButton>` for why the frame must survive a
+ * light/dark toggle.
  */
 export declare function FlowWidget({ widget, className, host, theme, }: FlowWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist/sdk/react/flow-widget.js

@@ -11,10 +11,16 @@ import { useFlow } from "./hooks";
  * Prefer this over embedding the widget's URL in your own `<iframe>`: only a
  * frame mounted this way completes the handshake that lets it authenticate as
  * the signed-in user from a cross-site page (AUTH-171).
+ *
+ * A changing `theme` recolors the mounted widget over its open bridge rather
+ * than remounting it — see `<ProfileButton>` for why the frame must survive a
+ * light/dark toggle.
  */
 export function FlowWidget({ widget, className, host, theme, }) {
     const flow = useFlow();
     const ref = useRef(null);
+    const handleRef = useRef(null);
+    const themeRef = useRef(theme);
     useEffect(() => {
         const container = ref.current;
         if (!container)
@@ -23,15 +29,24 @@ export function FlowWidget({ widget, className, host, theme, }) {
             widget,
             container,
             flow,
-            ...(host ? { host } : {}),
-            ...(theme ? { theme } : {}),
+            host: host ? host : undefined,
+            theme: themeRef.current ? themeRef.current : undefined,
         });
+        handleRef.current = handle;
         if (handle.frame) {
             handle.frame.style.width = "100%";
             handle.frame.style.height = "100%";
             handle.frame.style.display = "block";
         }
-        return () => handle.destroy();
-    }, [widget, flow, host, theme]);
+        return () => {
+            handleRef.current = null;
+            handle.destroy();
+        };
+    }, [widget, flow, host]);
+    useEffect(() => {
+        themeRef.current = theme;
+        if (theme)
+            handleRef.current?.setTheme(theme);
+    }, [theme]);
     return _jsx("div", { ref: ref, className: className });
 }

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

@@ -39,24 +39,28 @@ export declare function useFlowId(): {
  * Fetches the public room list once (call `reload` to refresh). Pagination
  * stays manual: pass the returned `nextCursor` back through `flow.rooms.list`.
  */
-export declare function useRooms(): {
+/** What {@link useRooms} returns. */
+export type RoomsState = {
     rooms: RoomSummary[];
     nextCursor: string | null;
     loading: boolean;
     error: Error | null;
     reload: () => void;
 };
+export declare function useRooms(): RoomsState;
 /**
  * Fetches one room's detail, and optionally polls its live presence when
  * `presencePollMs` is set (polling until the presence store grows a push
  * channel). Re-fetches when the slug changes; call `reload` to refresh.
  */
-export declare function useRoom(slug: string, options?: {
-    presencePollMs?: number;
-}): {
+/** What {@link useRoom} returns. */
+export type RoomState = {
     room: RoomDetail | null;
     presence: RoomPresenceSnapshot | null;
     loading: boolean;
     error: Error | null;
     reload: () => void;
 };
+export declare function useRoom(slug: string, options?: {
+    presencePollMs?: number;
+}): RoomState;

package/dist/sdk/react/hooks.js

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

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

@@ -5,5 +5,10 @@ import type { ProfileButtonProps } from "../types";
  * 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.
+ *
+ * A changing `theme` recolors the mounted pill over its open bridge rather than
+ * remounting it: `theme` is deliberately absent from the mount effect's deps,
+ * because tearing the iframe down on a light/dark toggle reloads the widget and
+ * drops the pill out of the host's layout mid-toggle.
  */
 export declare function ProfileButton({ className, host, theme }: ProfileButtonProps): import("react/jsx-runtime").JSX.Element;

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

@@ -8,10 +8,17 @@ import { useFlow } from "./hooks";
  * 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.
+ *
+ * A changing `theme` recolors the mounted pill over its open bridge rather than
+ * remounting it: `theme` is deliberately absent from the mount effect's deps,
+ * because tearing the iframe down on a light/dark toggle reloads the widget and
+ * drops the pill out of the host's layout mid-toggle.
  */
 export function ProfileButton({ className, host, theme }) {
     const flow = useFlow();
     const ref = useRef(null);
+    const handleRef = useRef(null);
+    const themeRef = useRef(theme);
     useEffect(() => {
         const container = ref.current;
         if (!container)
@@ -19,10 +26,19 @@ export function ProfileButton({ className, host, theme }) {
         const handle = createProfileButton({
             container,
             flow,
-            ...(host ? { host } : {}),
-            ...(theme ? { theme } : {}),
+            host: host ? host : undefined,
+            theme: themeRef.current ? themeRef.current : undefined,
         });
-        return () => handle.destroy();
-    }, [flow, host, theme]);
+        handleRef.current = handle;
+        return () => {
+            handleRef.current = null;
+            handle.destroy();
+        };
+    }, [flow, host]);
+    useEffect(() => {
+        themeRef.current = theme;
+        if (theme)
+            handleRef.current?.setTheme(theme);
+    }, [theme]);
     return _jsx("div", { ref: ref, className: className });
 }

package/dist/sdk/server.js

@@ -11,6 +11,7 @@ async function fetchProfile(issuerUrl, jwt, audience) {
         });
         if (!res.ok)
             return undefined;
+        /* SAFETY: this server's own /session/verify endpoint, called over the loopback. */
         const data = (await res.json());
         return data.payload?.profile ?? undefined;
     }
@@ -39,6 +40,6 @@ export async function resolveSession(cookieHeader, opts) {
         state,
         claims,
         setCookies,
-        ...(profile ? { profile } : {}),
+        profile: profile ? profile : undefined,
     };
 }

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

@@ -1,11 +1,6 @@
-/**
- * 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;
+export declare function isJwtVerificationFailure(cause: 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. */

package/dist/sdk/session-core.js

@@ -1,3 +1,4 @@
+import { errField } from "./driver-error";
 /**
  * Internal session-resolution core shared by `resolveSession` (SSR) and the
  * session route. Not part of the published API surface — `server.ts` and
@@ -9,7 +10,7 @@ import { verifyFlowJWT } from "./verify";
 export function claimsToUser(claims) {
     return {
         id: claims.sub,
-        username: typeof claims.username === "string" ? claims.username : "",
+        username: String(claims.username) === claims.username ? 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,
@@ -25,6 +26,8 @@ async function refreshSession(issuerUrl, token) {
             return "dead";
         if (!res.ok)
             return null;
+        /* SAFETY: the response is this issuer's own /session/restore payload; a non-ok status has
+         already thrown above. */
         return (await res.json());
     }
     catch {
@@ -57,9 +60,9 @@ function refreshOnce(issuerUrl, token) {
 // 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")
+export function isJwtVerificationFailure(cause) {
+    const code = errField(cause, "code");
+    if (!code)
         return false;
     return (code.startsWith("ERR_JWT") ||
         code.startsWith("ERR_JWS") ||

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

@@ -1,23 +1,3 @@
-/**
- * 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).

package/dist/sdk/session-route.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /**
  * The first-party session route every consumer app serves from its own
  * origin — the only path between a browser and the refresh token. The
@@ -22,6 +23,21 @@ 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";
+/** The body the browser SDK posts to its own app's session route. */
+const installBodySchema = z.object({
+    refreshToken: z.string().min(1).optional(),
+    jwt: z.string().min(1).optional(),
+    mint: z.array(z.string()).optional(),
+});
+const additionalBodySchema = z.object({
+    additionalSessions: z
+        .array(z.object({
+        audience: z.string(),
+        jwt: z.string(),
+        refreshToken: z.string(),
+    }))
+        .optional(),
+});
 function json(body, status, setCookies = []) {
     const headers = new Headers({
         "Content-Type": "application/json",
@@ -65,14 +81,15 @@ export async function handleSessionRequest(request, opts = {}) {
             return json({ state: session }, 200, setCookies);
         }
         case "POST": {
-            const body = (await request.json().catch(() => null));
+            const parsed = installBodySchema.safeParse(await request.json().catch(() => null));
+            const body = parsed.success ? parsed.data : null;
             // Reconcile mint: the browser asks its own server to obtain additional-
             // audience sessions (e.g. talk.flow.game) authorized by the PRIMARY
             // refresh cookie, for an embed that booted with no session of its own.
             // The refresh token never touches page JS — it's read from the HttpOnly
             // cookie here and presented to the issuer as a bearer.
-            if (Array.isArray(body?.mint)) {
-                const audiences = body.mint.filter((a) => typeof a === "string");
+            if (body?.mint) {
+                const audiences = body.mint;
                 const names = cookieNamesFor(audience);
                 const token = parseCookieHeader(request.headers.get("Cookie"))[names.refresh];
                 let additionalSessions = [];
@@ -87,8 +104,10 @@ export async function handleSessionRequest(request, opts = {}) {
                             body: JSON.stringify({ audiences }),
                         });
                         if (res.ok) {
-                            const data = (await res.json());
-                            additionalSessions = data.additionalSessions ?? [];
+                            const data = additionalBodySchema.safeParse(await res.json());
+                            additionalSessions = data.success
+                                ? (data.data.additionalSessions ?? [])
+                                : [];
                         }
                     }
                     catch { }
@@ -97,10 +116,7 @@ export async function handleSessionRequest(request, opts = {}) {
             }
             const refreshToken = body?.refreshToken;
             const jwt = body?.jwt;
-            if (typeof refreshToken !== "string" ||
-                refreshToken.length === 0 ||
-                typeof jwt !== "string" ||
-                jwt.length === 0) {
+            if (!refreshToken || !jwt) {
                 return json({ state: null }, 400);
             }
             // The audience check on the verified JWT is what stops a token minted

package/dist/sdk/start/graceful-shutdown.d.ts

@@ -0,0 +1,8 @@
+import type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer } from "../types";
+export declare const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 20000;
+/**
+ * Install one process-wide graceful-shutdown handler for a Bun-compatible
+ * server. The first signal stops new accepts, drains active HTTP and consumer
+ * cleanup together, force-closes at the deadline, and exits successfully.
+ */
+export declare function installGracefulShutdown(server: GracefulShutdownServer | null | undefined, options?: GracefulShutdownOptions): GracefulShutdownCleanup;

package/dist/sdk/start/graceful-shutdown.js

@@ -0,0 +1,81 @@
+export const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 20_000;
+let installation;
+function timeoutMs(options) {
+    const configured = options.timeoutMs;
+    if (configured === undefined)
+        return DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS;
+    if (!Number.isFinite(configured) || configured < 0) {
+        return DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS;
+    }
+    return configured;
+}
+function deadline(ms) {
+    let timer;
+    return {
+        promise: new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), ms);
+        }),
+        cancel: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}
+async function shutdown(current, signal) {
+    let gracefulStop;
+    try {
+        gracefulStop = Promise.resolve(current.server.stop(false));
+    }
+    catch (error) {
+        gracefulStop = Promise.reject(error);
+    }
+    const consumerDrain = Promise.resolve().then(() => current.options.onShutdown?.(signal));
+    const drained = Promise.allSettled([gracefulStop, consumerDrain]).then(() => true);
+    const timeout = deadline(timeoutMs(current.options));
+    const completed = await Promise.race([drained, timeout.promise]);
+    timeout.cancel();
+    if (!completed) {
+        try {
+            void current.server.stop(true);
+        }
+        catch {
+            // The configured deadline is authoritative even if forced close fails.
+        }
+    }
+    process.exit(0);
+}
+function handleSignal(signal) {
+    const current = installation;
+    if (!current || current.shuttingDown)
+        return;
+    current.shuttingDown = true;
+    void shutdown(current, signal);
+}
+function handleSigterm() {
+    handleSignal("SIGTERM");
+}
+function handleSigint() {
+    handleSignal("SIGINT");
+}
+/**
+ * Install one process-wide graceful-shutdown handler for a Bun-compatible
+ * server. The first signal stops new accepts, drains active HTTP and consumer
+ * cleanup together, force-closes at the deadline, and exits successfully.
+ */
+export function installGracefulShutdown(server, options = {}) {
+    if (!server)
+        return () => undefined;
+    if (installation)
+        return installation.cleanup;
+    const cleanup = () => {
+        if (!installation || installation.cleanup !== cleanup)
+            return;
+        process.off("SIGTERM", handleSigterm);
+        process.off("SIGINT", handleSigint);
+        installation = undefined;
+    };
+    installation = { cleanup, options, server, shuttingDown: false };
+    process.on("SIGTERM", handleSigterm);
+    process.on("SIGINT", handleSigint);
+    return cleanup;
+}

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

@@ -22,6 +22,8 @@
  */
 import { type ReactNode } from "react";
 import type { AdditionalSession, FlowSessionState } from "../types";
+export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, } from "../types";
+export { DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS, installGracefulShutdown, } from "./graceful-shutdown";
 /**
  * The `beforeLoad` body: during SSR resolve the session server-side (via the
  * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);