@flow-industries/id 0.23.0 → 0.23.1

package/README.md

@@ -143,3 +143,5 @@ The current OpenAPI artifact describes the service report boundary. The remainin
 account, room management, study, settings, session and passkey HTTP operations
 still need complete request/response descriptions and generated client coverage
 before the full HTTP contract work is complete.
+
+Server deployments may set `FLOW_ID_API_URL` to a trusted internal HTTP(S) origin for API and JWKS requests, or pass `apiUrl` to server session/verification helpers. `issuerUrl` remains the public JWT issuer and browser navigation origin. The transport URL must contain no credentials, path, query, or fragment.

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

@@ -4,5 +4,5 @@ export declare function startBrowserSession(request: Request, audience: string,
     returnTo?: string;
     signUp?: boolean;
     accessKeyHash?: string;
-}): Promise<Response>;
-export declare function finishBrowserSession(request: Request, audience: string, issuerUrl: string): Promise<Response>;
+}, apiUrl?: string): Promise<Response>;
+export declare function finishBrowserSession(request: Request, audience: string, issuerUrl: string, apiUrl?: string): Promise<Response>;

package/dist/sdk/browser-session-route.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { browserSigningSchema } from "./browser-contract";
 import { clearCookieString, cookieNamesFor, parseCookieHeader, serializeCookie, } from "./cookies";
+import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 import { claimsToUser, sessionCookies } from "./session-core";
 import { verifyFlowJWT } from "./verify";
 const opaquePattern = /^[A-Za-z0-9_-]{43}$/;
@@ -60,7 +61,7 @@ export function safeReturnTo(value, audience, sessionPath = "/flow/session") {
         return null;
     }
 }
-export async function startBrowserSession(request, audience, issuerUrl, body) {
+export async function startBrowserSession(request, audience, issuerUrl, body, apiUrl = resolveIssuerApiUrl(issuerUrl)) {
     const cookies = parseCookieHeader(request.headers.get("Cookie"));
     const refresh = cookies[cookieNamesFor(audience).refresh];
     const headers = new Headers({ "Content-Type": "application/json" });
@@ -74,7 +75,7 @@ export async function startBrowserSession(request, audience, issuerUrl, body) {
     if (body.action === "account") {
         if (!refresh)
             return reply({ error: "signed_out" }, 401);
-        const response = await fetch(`${issuerUrl}/api/auth/browser/account-handoff`, { method: "POST", headers, body: JSON.stringify({ audience }) });
+        const response = await fetchIssuerApi(`${apiUrl}/api/auth/browser/account-handoff`, { method: "POST", headers, body: JSON.stringify({ audience }) });
         if (!response.ok)
             return reply({ error: "account_unavailable" }, response.status);
         const { handoff } = z
@@ -88,7 +89,7 @@ export async function startBrowserSession(request, audience, issuerUrl, body) {
     const state = secret();
     const verifier = secret();
     const callback = `${audience}${new URL(request.url).pathname}`;
-    const response = await fetch(`${issuerUrl}/api/auth/browser/transaction`, {
+    const response = await fetchIssuerApi(`${apiUrl}/api/auth/browser/transaction`, {
         method: "POST",
         headers,
         body: JSON.stringify({
@@ -121,7 +122,7 @@ export async function startBrowserSession(request, audience, issuerUrl, body) {
         }),
     ]);
 }
-export async function finishBrowserSession(request, audience, issuerUrl) {
+export async function finishBrowserSession(request, audience, issuerUrl, apiUrl = resolveIssuerApiUrl(issuerUrl)) {
     const url = new URL(request.url);
     const state = url.searchParams.get("flow_state") ?? "";
     if (!opaquePattern.test(state))
@@ -154,7 +155,7 @@ export async function finishBrowserSession(request, audience, issuerUrl) {
     if (!opaquePattern.test(code))
         return reply({ error: "invalid_login_code" }, 400);
     try {
-        const result = await fetch(`${issuerUrl}/api/auth/browser/token`, {
+        const result = await fetchIssuerApi(`${apiUrl}/api/auth/browser/token`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -170,7 +171,11 @@ export async function finishBrowserSession(request, audience, issuerUrl) {
                 message: "Return to your app and start sign-in again.",
             }, 400, [clear]);
         const session = exchangeSchema.parse(await result.json());
-        const claims = await verifyFlowJWT(session.jwt, { audience, issuerUrl });
+        const claims = await verifyFlowJWT(session.jwt, {
+            audience,
+            issuerUrl,
+            apiUrl,
+        });
         if (!claimsToUser(claims).id)
             throw new Error("Invalid session");
         for (const value of sessionCookies(audience, session.jwt, session.refreshToken))

package/dist/sdk/issuer-api.d.ts

@@ -0,0 +1,3 @@
+/** Resolve a trusted server transport without changing the public JWT issuer. */
+export declare function resolveIssuerApiUrl(issuerUrl: string, override?: string): string;
+export declare function fetchIssuerApi(url: string, init?: RequestInit): Promise<Response>;

package/dist/sdk/issuer-api.js

@@ -0,0 +1,28 @@
+/** Resolve a trusted server transport without changing the public JWT issuer. */
+export function resolveIssuerApiUrl(issuerUrl, override) {
+    const configured = override ??
+        (globalThis.process !== undefined
+            ? process.env.FLOW_ID_API_URL
+            : undefined);
+    const url = new URL(configured ?? issuerUrl);
+    if (!["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/") {
+        throw new Error("Flow ID API URL must be an HTTP(S) origin without credentials, path, query, or fragment");
+    }
+    return url.origin;
+}
+export async function fetchIssuerApi(url, init) {
+    const response = await fetch(url, { ...init, redirect: "error" });
+    if (!response.ok) {
+        console.warn("Flow ID API request failed", {
+            path: new URL(url).pathname,
+            status: response.status,
+            contentType: response.headers.get("content-type")?.split(";")[0] ?? null,
+        });
+    }
+    return response;
+}

package/dist/sdk/server.js

@@ -1,10 +1,11 @@
 import { resolveIdHost } from "./id-host";
+import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 import { resolveSessionCore } from "./session-core";
 export { createSessionHandler, handleSessionRequest } from "./session-route";
 export { verifyFlowJWT } from "./verify";
-async function fetchProfile(issuerUrl, jwt, audience) {
+async function fetchProfile(apiUrl, jwt, audience) {
     try {
-        const res = await fetch(`${issuerUrl}/api/session/verify`, {
+        const res = await fetchIssuerApi(`${apiUrl}/api/session/verify`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ token: jwt, audience }),
@@ -29,12 +30,13 @@ async function fetchProfile(issuerUrl, jwt, audience) {
  */
 export async function resolveSession(cookieHeader, opts) {
     const issuerUrl = resolveIdHost(opts.issuerUrl, opts.audience);
-    const { session, claims, setCookies } = await resolveSessionCore(cookieHeader, opts.audience, issuerUrl);
+    const apiUrl = resolveIssuerApiUrl(issuerUrl, opts.apiUrl);
+    const { session, claims, setCookies } = await resolveSessionCore(cookieHeader, opts.audience, issuerUrl, apiUrl);
     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)
+        ? await fetchProfile(apiUrl, state.jwt, opts.audience)
         : undefined;
     return {
         state,

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

@@ -27,7 +27,7 @@ export type ResolvedSessionCore = {
  * 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>;
+export declare function refreshSessionCore(issuerUrl: string, audience: string, refreshToken: string, apiUrl?: string): Promise<ResolvedSessionCore | "dead" | null>;
 /**
  * Resolves a session from a request's Cookie header.
  *
@@ -41,4 +41,4 @@ export declare function refreshSessionCore(issuerUrl: string, audience: string,
  *     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>;
+export declare function resolveSessionCore(cookieHeader: string | null | undefined, audience: string, issuerUrl: string, apiUrl?: string): Promise<ResolvedSessionCore>;

package/dist/sdk/session-core.js

@@ -5,6 +5,7 @@ import { errField } from "./driver-error";
  * `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 { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 import { isExpiring } from "./token-expiry";
 import { verifyFlowJWT } from "./verify";
 export function claimsToUser(claims) {
@@ -16,9 +17,9 @@ export function claimsToUser(claims) {
         isGuest: claims.guest !== false,
     };
 }
-async function refreshSession(issuerUrl, token) {
+async function refreshSession(token, apiUrl) {
     try {
-        const res = await fetch(`${issuerUrl}/api/session/refresh`, {
+        const res = await fetchIssuerApi(`${apiUrl}/api/session/refresh`, {
             method: "POST",
             headers: { Authorization: `Bearer ${token}` },
         });
@@ -42,11 +43,11 @@ async function refreshSession(issuerUrl, token) {
 // other machines).
 const REFRESH_RESULT_TTL_MS = 30_000;
 const refreshInFlight = new Map();
-function refreshOnce(issuerUrl, token) {
-    const key = `${issuerUrl}\n${token}`;
+function refreshOnce(issuerUrl, token, apiUrl) {
+    const key = `${issuerUrl}\n${apiUrl}\n${token}`;
     let flight = refreshInFlight.get(key);
     if (!flight) {
-        flight = refreshSession(issuerUrl, token);
+        flight = refreshSession(token, apiUrl);
         refreshInFlight.set(key, flight);
         void flight.finally(() => {
             const timer = setTimeout(() => refreshInFlight.delete(key), REFRESH_RESULT_TTL_MS);
@@ -100,14 +101,14 @@ export function clearingCookies(audience) {
  * 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);
+export async function refreshSessionCore(issuerUrl, audience, refreshToken, apiUrl = resolveIssuerApiUrl(issuerUrl)) {
+    const result = await refreshOnce(issuerUrl, refreshToken, apiUrl);
     if (result === "dead" || !result)
         return result;
     const successorCookies = sessionCookies(audience, result.jwt, result.refreshToken);
     let claims;
     try {
-        claims = await verifyFlowJWT(result.jwt, { audience, issuerUrl });
+        claims = await verifyFlowJWT(result.jwt, { audience, issuerUrl, apiUrl });
     }
     catch (err) {
         if (isJwtVerificationFailure(err)) {
@@ -143,13 +144,13 @@ export async function refreshSessionCore(issuerUrl, audience, refreshToken) {
  *     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) {
+export async function resolveSessionCore(cookieHeader, audience, issuerUrl, apiUrl = resolveIssuerApiUrl(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 });
+            const claims = await verifyFlowJWT(jwt, { audience, issuerUrl, apiUrl });
             return {
                 session: { user: claimsToUser(claims), jwt },
                 claims,
@@ -165,7 +166,7 @@ export async function resolveSessionCore(cookieHeader, audience, issuerUrl) {
     const refreshToken = cookies[names.refresh];
     if (!refreshToken)
         return { session: null, claims: null, setCookies: [] };
-    const refreshed = await refreshSessionCore(issuerUrl, audience, refreshToken);
+    const refreshed = await refreshSessionCore(issuerUrl, audience, refreshToken, apiUrl);
     if (refreshed === "dead") {
         return {
             session: null,

package/dist/sdk/session-route.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { browserCompletionSchema } from "./browser-contract";
 import { finishBrowserSession, startBrowserSession, } from "./browser-session-route";
 import { clearCookieString } from "./cookies";
+import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 /**
  * The first-party session route every consumer app serves from its own
  * origin — the only path between a browser and the refresh token. The
@@ -82,9 +83,10 @@ function isCrossSite(request, audience) {
 export async function handleSessionRequest(request, opts = {}) {
     const audience = opts.audience ?? defaultAudience(new URL(request.url).origin);
     const issuerUrl = resolveIdHost(opts.issuerUrl, audience);
+    const apiUrl = resolveIssuerApiUrl(issuerUrl, opts.apiUrl);
     const callback = new URL(request.url);
     if (request.method === "GET" && callback.searchParams.has("flow_state")) {
-        return finishBrowserSession(request, audience, issuerUrl);
+        return finishBrowserSession(request, audience, issuerUrl, apiUrl);
     }
     if (isCrossSite(request, audience)) {
         return json({ state: null }, 403);
@@ -95,14 +97,14 @@ export async function handleSessionRequest(request, opts = {}) {
                 const token = parseCookieHeader(request.headers.get("Cookie"))[cookieNamesFor(audience).refresh];
                 if (!token)
                     return json({ state: null }, 200);
-                const result = await refreshSessionCore(issuerUrl, audience, token);
+                const result = await refreshSessionCore(issuerUrl, audience, token, apiUrl);
                 if (result === "dead")
                     return json({ state: null }, 200, clearingCookies(audience));
                 if (!result)
                     return json({ state: null }, 502);
                 return json({ state: result.session }, 200, result.setCookies);
             }
-            const { session, setCookies } = await resolveSessionCore(request.headers.get("Cookie"), audience, issuerUrl);
+            const { session, setCookies } = await resolveSessionCore(request.headers.get("Cookie"), audience, issuerUrl, apiUrl);
             const completionName = `${cookieNamesFor(audience).refresh}.completion`;
             const raw = parseCookieHeader(request.headers.get("Cookie"))[completionName];
             let loginCompletion;
@@ -129,14 +131,14 @@ export async function handleSessionRequest(request, opts = {}) {
                     return await startBrowserSession(request, audience, issuerUrl, {
                         ...body,
                         action: body.action,
-                    });
+                    }, apiUrl);
                 }
                 catch {
                     return json({ state: null }, 502);
                 }
             }
             if (body?.action === "guest") {
-                const existing = await resolveSessionCore(request.headers.get("Cookie"), audience, issuerUrl);
+                const existing = await resolveSessionCore(request.headers.get("Cookie"), audience, issuerUrl, apiUrl);
                 if (existing.session)
                     return json({ state: existing.session }, 200, existing.setCookies);
                 const previousRefresh = parseCookieHeader(request.headers.get("Cookie"))[cookieNamesFor(audience).refresh];
@@ -153,7 +155,7 @@ export async function handleSessionRequest(request, opts = {}) {
                         if (value)
                             headers.set(name, value);
                     }
-                    const result = await fetch(`${issuerUrl}/api/auth/passkey/guest`, {
+                    const result = await fetchIssuerApi(`${apiUrl}/api/auth/passkey/guest`, {
                         method: "POST",
                         headers,
                         body: JSON.stringify({ audience }),
@@ -162,7 +164,11 @@ export async function handleSessionRequest(request, opts = {}) {
                         return json({ state: null }, result.status);
                     // SAFETY: the configured issuer returns this session token pair, verified below.
                     const data = (await result.json());
-                    const claims = await verifyFlowJWT(data.jwt, { audience, issuerUrl });
+                    const claims = await verifyFlowJWT(data.jwt, {
+                        audience,
+                        issuerUrl,
+                        apiUrl,
+                    });
                     return json({
                         state: {
                             user: claimsToUser(claims),
@@ -188,7 +194,7 @@ export async function handleSessionRequest(request, opts = {}) {
                 let additionalSessions = [];
                 if (token && audiences.length > 0) {
                     try {
-                        const res = await fetch(`${issuerUrl}/api/session/additional`, {
+                        const res = await fetchIssuerApi(`${apiUrl}/api/session/additional`, {
                             method: "POST",
                             headers: {
                                 "Content-Type": "application/json",
@@ -216,7 +222,11 @@ export async function handleSessionRequest(request, opts = {}) {
             // 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 });
+                const claims = await verifyFlowJWT(jwt, {
+                    audience,
+                    issuerUrl,
+                    apiUrl,
+                });
                 return json({ state: { user: claimsToUser(claims), jwt } }, 200, sessionCookies(audience, jwt, refreshToken));
             }
             catch (err) {
@@ -230,7 +240,7 @@ export async function handleSessionRequest(request, opts = {}) {
             // an unreachable issuer just leaves the lineage to expire on its own.
             if (token) {
                 try {
-                    const response = await fetch(`${issuerUrl}/api/session/revoke`, {
+                    const response = await fetchIssuerApi(`${apiUrl}/api/session/revoke`, {
                         method: "POST",
                         headers: { Authorization: `Bearer ${token}` },
                     });

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

@@ -99,6 +99,8 @@ export type PasskeyPluginOptions = {
 export type VerifyOptions = {
     audience: string;
     issuerUrl?: string;
+    /** Trusted server API origin; defaults to FLOW_ID_API_URL, then the public issuer. */
+    apiUrl?: string;
 };
 /**
  * One entry in the signed-in user's session list (`GET /api/account/sessions`).

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

@@ -6,6 +6,8 @@ export type ResolveSessionOptions = {
     audience: string;
     /** Flow ID origin; defaults to `https://id.flow.industries`. */
     issuerUrl?: string;
+    /** Trusted server API origin; defaults to FLOW_ID_API_URL, then the public issuer. */
+    apiUrl?: string;
     /**
      * Also fetch the public profile (avatar, tier, level) for a resolved
      * session via `/api/session/verify` — one extra round-trip; off by default.
@@ -36,6 +38,8 @@ export type SessionRouteOptions = {
     audience?: string;
     /** Flow ID origin; defaults per `defaultIdHost` (`FLOW_ID_HOST` on servers). */
     issuerUrl?: string;
+    /** Trusted server API origin; defaults to FLOW_ID_API_URL, then the public issuer. */
+    apiUrl?: string;
     /** Route path for `createSessionHandler`'s own path check. */
     path?: string;
 };

package/dist/sdk/verify.js

@@ -1,4 +1,5 @@
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
+import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 const jwksCache = new Map();
 const DEFAULT_ISSUER_URL = "https://id.flow.industries";
 /**
@@ -22,10 +23,14 @@ const DEFAULT_ISSUER_URL = "https://id.flow.industries";
  */
 export async function verifyFlowJWT(token, opts) {
     const issuerUrl = opts.issuerUrl ?? DEFAULT_ISSUER_URL;
-    let jwks = jwksCache.get(issuerUrl);
+    const apiUrl = resolveIssuerApiUrl(issuerUrl, opts.apiUrl);
+    const cacheKey = `${issuerUrl}\n${apiUrl}`;
+    let jwks = jwksCache.get(cacheKey);
     if (!jwks) {
-        jwks = createRemoteJWKSet(new URL(`${issuerUrl}/api/auth/jwks`));
-        jwksCache.set(issuerUrl, jwks);
+        jwks = createRemoteJWKSet(new URL(`${apiUrl}/api/auth/jwks`), {
+            [customFetch]: fetchIssuerApi,
+        });
+        jwksCache.set(cacheKey, jwks);
     }
     const { payload } = await jwtVerify(token, jwks, {
         issuer: issuerUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "license": "MIT",
   "repository": {
     "type": "git",