@flow-industries/id 0.11.0 → 0.12.0

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

@@ -0,0 +1,36 @@
+/**
+ * Shared defaults for the first-party session plumbing. The browser client,
+ * the SSR resolver, and the session route all resolve the Flow ID origin and
+ * the app-local session path from here, so consumer apps agree on both
+ * 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). */
+export declare const LOCAL_ISSUER_URL = "http://localhost:5175";
+/**
+ * Path of the first-party session route every app serves from its own origin
+ * (GET resolve, POST install, DELETE sign-out). The browser client and the
+ * route registration must agree on it; override via `createFlow({ sessionPath })`
+ * plus the route's `path` option only when an app cannot claim this path.
+ */
+export declare const DEFAULT_SESSION_PATH = "/flow/session";
+export declare function isLocalHostname(hostname: string): boolean;
+/**
+ * The app's public origin — the JWT audience and what cookie names derive
+ * from. The `APP_ORIGIN` env var wins (mandatory behind a TLS-terminating
+ * proxy, where the request origin is the internal http one); dev falls back
+ * to the request's own origin.
+ */
+export declare function defaultAudience(requestOrigin: string): string;
+/**
+ * Resolves the Flow ID origin for the current runtime: the `FLOW_ID_HOST`
+ * env var wins on servers, a localhost app talks to the local auth stack,
+ * everything else uses production. Pass the app origin when resolving on
+ * behalf of a request (servers have no `window`).
+ */
+export declare function defaultIdHost(appOrigin?: string): string;
+/**
+ * An explicit host override or the runtime default, normalized (no trailing
+ * slash) so callers can append paths without producing `//api/...` URLs.
+ */
+export declare function resolveIdHost(override?: string | null, appOrigin?: string): string;

package/dist/sdk/id-host.js

@@ -0,0 +1,57 @@
+/**
+ * Shared defaults for the first-party session plumbing. The browser client,
+ * the SSR resolver, and the session route all resolve the Flow ID origin and
+ * the app-local session path from here, so consumer apps agree on both
+ * 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). */
+export const LOCAL_ISSUER_URL = "http://localhost:5175";
+/**
+ * Path of the first-party session route every app serves from its own origin
+ * (GET resolve, POST install, DELETE sign-out). The browser client and the
+ * route registration must agree on it; override via `createFlow({ sessionPath })`
+ * plus the route's `path` option only when an app cannot claim this path.
+ */
+export const DEFAULT_SESSION_PATH = "/flow/session";
+export function isLocalHostname(hostname) {
+    return (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]");
+}
+/**
+ * The app's public origin — the JWT audience and what cookie names derive
+ * from. The `APP_ORIGIN` env var wins (mandatory behind a TLS-terminating
+ * proxy, where the request origin is the internal http one); dev falls back
+ * to the request's own origin.
+ */
+export function defaultAudience(requestOrigin) {
+    return ((typeof process !== "undefined" ? process.env?.APP_ORIGIN : undefined) ??
+        requestOrigin);
+}
+/**
+ * Resolves the Flow ID origin for the current runtime: the `FLOW_ID_HOST`
+ * env var wins on servers, a localhost app talks to the local auth stack,
+ * everything else uses production. Pass the app origin when resolving on
+ * behalf of a request (servers have no `window`).
+ */
+export function defaultIdHost(appOrigin) {
+    if (typeof process !== "undefined" && process.env?.FLOW_ID_HOST) {
+        return process.env.FLOW_ID_HOST;
+    }
+    const origin = appOrigin ??
+        (typeof window !== "undefined" ? window.location.origin : undefined);
+    if (origin) {
+        try {
+            if (isLocalHostname(new URL(origin).hostname))
+                return LOCAL_ISSUER_URL;
+        }
+        catch { }
+    }
+    return DEFAULT_ISSUER_URL;
+}
+/**
+ * An explicit host override or the runtime default, normalized (no trailing
+ * slash) so callers can append paths without producing `//api/...` URLs.
+ */
+export function resolveIdHost(override, appOrigin) {
+    return (override ?? defaultIdHost(appOrigin)).replace(/\/+$/, "");
+}

package/dist/sdk/server.d.ts

@@ -1,23 +1,13 @@
 import type { ResolvedFlowSession, ResolveSessionOptions } from "./types";
-export type { FlowSessionState, ResolvedFlowSession, ResolveSessionOptions, } from "./types";
+export { createSessionHandler, handleSessionRequest } from "./session-route";
+export type { FlowSessionState, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./types";
 export { verifyFlowJWT } from "./verify";
 /**
- * Resolves the visitor's Flow session from the request's Cookie header — the
- * server-side counterpart of `createFlow({ cookies: true })`, for rendering
- * auth-aware UI without a client round-trip.
- *
- * Resolution order:
- *  1. A still-fresh JWT cookie verifies locally against the issuer's JWKS
- *     (cached per process) — the hot path, no auth-server call, no cookies
- *     to set.
- *  2. Otherwise a refresh cookie is presented to `/api/session/refresh`,
- *     which ROTATES it — append every entry of `setCookies` to the response
- *     or the client is left holding a dead predecessor. A definitive
- *     rejection (401/403) yields clearing cookies instead; a network failure
- *     leaves the cookies alone so a later request can retry.
- *  3. Neither cookie → signed-out `state: null`.
- *
- * Feed `state` into the SSR payload and `createFlow({ initialState })` so the
- * hydrated client renders it without a second refresh.
+ * 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 declare function resolveSession(cookieHeader: string | null | undefined, opts: ResolveSessionOptions): Promise<ResolvedFlowSession>;

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>;