pi-freeflow 1.5.0 → 1.7.0

package/src/config.ts

@@ -17,7 +17,6 @@ export const OPENCODE_API_URL = `${UPSTREAM_OPENCODE}/v1`;
 export const DEFAULT_PORT = 28180;
 export const LEGACY_PORT = 18080;
 export const HOST = "127.0.0.1";
-export const DEFAULT_HOST = "127.0.0.1";
 
 export function resolvePort(): number {
 	const envPort = process.env.FREEFLOW_PORT;
@@ -49,7 +48,6 @@ export function opencodeHeaders(): Record<string, string> {
 }
 
 // ── Relay and Deployment constants ──────────────────────────────────
-export const DEFAULT_RELAY_URL = "";
 export const VERCEL_API = "https://api.vercel.com";
 
 // ── Catalog & Logging constants ─────────────────────────────────────
@@ -151,9 +149,33 @@ export function resolveUpdateCachePath(): string {
 	}
 }
 
+export function resolveOnboardedFlagPath(): string {
+	try {
+		return path.join(homedir(), ".pi", "agent", "pi-freeflow-onboarded");
+	} catch {
+		return path.join(
+			path.dirname(fileURLToPath(import.meta.url)),
+			"..",
+			".onboarded",
+		);
+	}
+}
+
 export const RELAY_STATE_FILE = resolveRelayStatePath();
 export const LOG_FILE = resolveLogFilePath();
 export const CATALOG_CACHE_FILE = resolveCatalogCachePath();
 export const DEBUG_STATE_FILE = resolveDebugStatePath();
 export const UPDATE_CACHE_FILE = resolveUpdateCachePath();
+export const ONBOARDED_FLAG_FILE = resolveOnboardedFlagPath();
 export const UPDATE_CHECK_TTL_MS = 86_400_000;
+// ── Security & Relay Validation ─────────────────────────────────────
+/** Opt-out for tests/dev: when set to "1", relay URLs on http:// and private hosts are allowed. */
+export const ALLOW_UNSAFE_RELAY_ENV = "PI_FREEFLOW_ALLOW_UNSAFE_RELAY";
+/** Max request body the proxy buffers before responding 413. */
+export const MAX_BODY_BYTES = 32 * 1024 * 1024;
+/** Default timeout for upstream headers while proxying a request. */
+export const UPSTREAM_HEADER_TIMEOUT_MS = 300_000;
+/** Timeout for refreshing the catalog (host fetchDynamicModels). */
+export const CATALOG_REFRESH_TIMEOUT_MS = 10_000;
+/** Timeout for probing a relay with a light /v1/models request. */
+export const PROBE_TIMEOUT_MS = 5_000;

package/src/deploy.ts

@@ -7,13 +7,22 @@
 
 import { VERCEL_API } from "./config.ts";
 import { log, logError } from "./logger.ts";
+import { randomBytes } from "node:crypto";
 
 /**
- * Hardened Edge Worker code deployed to Vercel.
- * Strictly whitelists OpenCode Zen and KiloCode Gateway endpoints to prevent open proxy abuse.
+ * Canonical guarded request pipeline shared by every platform relay template.
+ * The platform wrappers below only adapt the entry point (Vercel fetch
+ * handler / Cloudflare module worker / Deno.serve) around this core, so the
+ * whitelist, SSRF guard, path resolver, header denylist, auth gate and
+ * streaming forward live exactly once.
+ *
+ * @param relayAuth Per-deployment shared secret. Empty string disables the
+ *   auth gate (legacy/manual deploys); built-in deploys always embed one.
  */
-export const VERCEL_RELAY_WORKER = `// Only the 2 upstreams pi-freeflow talks to. Anything else = open proxy abuse.
+function buildRelayWorkerCore(relayAuth: string): string {
+	return `// Only the 2 upstreams pi-freeflow talks to. Anything else = open proxy abuse.
 const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+const RELAY_AUTH = ${JSON.stringify(relayAuth)};
 const resolveRelayTarget = function(target, relayPath) {
   let targetUrl;
   try { targetUrl = new URL(target); } catch { return { ok: false, status: 400, reason: "invalid x-relay-target" }; }
@@ -27,35 +36,50 @@ const resolveRelayTarget = function(target, relayPath) {
   }
   return { ok: true, url: finalUrl.toString() };
 };
-const isPrivateHostname = function(h) {
-  if (!h) return true
-  let host = String(h).trim().toLowerCase().replace(/^\[|\]$/g, "")
-  if (host.length > 1 && host.endsWith(".")) host = host.slice(0, -1)
-  if (!host) return true
-  if (host === "localhost" || host === "0.0.0.0" || host === "127.0.0.1" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true
-  if (host.startsWith("::")) return true
-  const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
-  if (v4) {
-    const a = Number(v4[1])
-    const b = Number(v4[2])
-    if (a === 0 || a === 10 || a === 127) return true
-    if (a === 169 && b === 254) return true
-    if (a === 192 && b === 168) return true
-    if (a === 172 && b >= 16 && b <= 31) return true
-    if (a === 100 && b >= 64 && b <= 127) return true
-    return false
-  }
-  if (host.includes(":")) {
-    if (host.startsWith("fc") || host.startsWith("fd")) return true
-    if (/^fe[89ab]/.test(host)) return true
-    return false
-  }
-  return false
+const isPrivateHostname = function(h) {
+  if (!h) return true
+  let host = String(h).trim().toLowerCase().replace(/^\[|\]$/g, "")
+  if (host.length > 1 && host.endsWith(".")) host = host.slice(0, -1)
+  if (!host) return true
+  if (host === "localhost" || host === "0.0.0.0" || host === "127.0.0.1" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true
+  if (host.startsWith("::")) return true
+  const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+  if (v4) {
+    const a = Number(v4[1])
+    const b = Number(v4[2])
+    if (a === 0 || a === 10 || a === 127) return true
+    if (a === 169 && b === 254) return true
+    if (a === 192 && b === 168) return true
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 100 && b >= 64 && b <= 127) return true
+    return false
+  }
+  if (host.includes(":")) {
+    if (host.startsWith("fc") || host.startsWith("fd")) return true
+    if (/^fe[89ab]/.test(host)) return true
+    return false
+  }
+  return false
 };
-export const config = { runtime: "edge" };
-export default async function handler(req) {
+// Constant-time string comparison (no timingSafeEqual in every edge runtime).
+const timingSafeEqualStr = function(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  let diff = a.length ^ b.length;
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+};
+// x-relay-auth is read by the handler below, so it is stripped explicitly
+// (never forwarded upstream) instead of living in the denylist.
+const DENY_HEADERS = ["host", "connection", "content-length", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization", "transfer-encoding", "te", "trailer", "upgrade", "x-relay-target", "x-relay-path"];
+async function relayHandler(req) {
   const target = req.headers.get("x-relay-target");
   if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400, headers: { "content-type": "application/json" } });
+  if (RELAY_AUTH && !timingSafeEqualStr(req.headers.get("x-relay-auth") || "", RELAY_AUTH)) {
+    return new Response(JSON.stringify({ error: "unauthorized" }), { status: 401, headers: { "content-type": "application/json" } });
+  }
   let targetUrl;
   try { targetUrl = new URL(target); } catch { return new Response(JSON.stringify({ error: "invalid x-relay-target" }), { status: 400, headers: { "content-type": "application/json" } }); }
   if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") return new Response(JSON.stringify({ error: "forbidden x-relay-target protocol" }), { status: 403, headers: { "content-type": "application/json" } });
@@ -67,10 +91,60 @@ export default async function handler(req) {
   const resolved = resolveRelayTarget(target, relayPath);
   if (!resolved.ok) return new Response(JSON.stringify({ error: resolved.reason }), { status: resolved.status, headers: { "content-type": "application/json" } });
   const headers = new Headers(req.headers);
-  ["host", "connection", "content-length", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization", "transfer-encoding", "te", "trailer", "upgrade", "x-relay-target", "x-relay-path", "x-relay-auth"].forEach((h) => headers.delete(h));
-  const response = await fetch(resolved.url, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined, duplex: "half" });
-  return new Response(response.body, { status: response.status, headers: response.headers });
+  DENY_HEADERS.forEach((h) => headers.delete(h));
+  headers.delete("x-relay-auth");
+  try {
+    const init = { method: req.method, headers };
+    if (req.method !== "GET" && req.method !== "HEAD") { init.body = req.body; init.duplex = "half"; }
+    const response = await fetch(resolved.url, init);
+    return new Response(response.body, { status: response.status, headers: response.headers });
+  } catch (error) {
+    return new Response(JSON.stringify({ error: String(error) }), { status: 502, headers: { "content-type": "application/json" } });
+  }
+}`;
+}
+
+/**
+ * Vercel Edge Function relay template: canonical core wrapped in the edge-runtime module handler.
+ */
+export function buildVercelRelayWorker(relayAuth: string): string {
+	return `${buildRelayWorkerCore(relayAuth)}
+export const config = { runtime: "edge" };
+export default async function handler(req) {
+  return relayHandler(req);
 }`;
+}
+
+/**
+ * Cloudflare Workers module relay template: canonical core wrapped in the module fetch handler.
+ */
+export function buildCloudflareRelayWorker(relayAuth: string): string {
+	return `${buildRelayWorkerCore(relayAuth)}
+export default {
+  async fetch(request) {
+    return relayHandler(request);
+  },
+};`;
+}
+
+/**
+ * Deno Deploy relay script template: canonical core wrapped in Deno.serve.
+ */
+export function buildDenoRelayScript(relayAuth: string): string {
+	return `${buildRelayWorkerCore(relayAuth)}
+Deno.serve(async (request) => {
+  return relayHandler(request);
+});`;
+}
+
+/**
+ * Public template constants (tests/README): the canonical core without a
+ * secret, so the auth gate is disabled. Deployed relays always embed their
+ * own per-deployment secret.
+ */
+export const VERCEL_RELAY_WORKER = buildVercelRelayWorker("");
+export const CLOUDFLARE_RELAY_WORKER = buildCloudflareRelayWorker("");
+export const DENO_RELAY_SCRIPT = buildDenoRelayScript("");
 
 /**
  * Deploy a fresh Vercel Edge Relay project in-memory.
@@ -78,13 +152,13 @@ export default async function handler(req) {
  * @param token Vercel personal access token (used in-memory only)
  * @param name Unique project/deployment name (e.g. pi-freeflow-relay-abc123)
  * @param onProgress Optional callback for user-facing progress updates
- * @returns Deployed HTTPS relay URL
+ * @returns Deployed { url, auth } — url is the public relay URL, auth the embedded shared secret
  */
 export async function deployVercelRelay(
 	token: string,
 	name: string,
 	onProgress?: (msg: string) => void,
-): Promise<string> {
+): Promise<{ url: string; auth: string }> {
 	const auth = {
 		Authorization: `Bearer ${token}`,
 		"Content-Type": "application/json",
@@ -93,6 +167,9 @@ export async function deployVercelRelay(
 	// 1. Create deployment (3 inline files, no git repository required)
 	onProgress?.("Uploading relay files to Vercel…");
 	log("info", `Starting Vercel deployment: ${name}`);
+	// Per-deployment shared secret: embedded in the worker, persisted on the
+	// relay-state entry by the caller, and required via x-relay-auth.
+	const relayAuth = randomBytes(24).toString("base64url");
 
 	const dep = await fetch(`${VERCEL_API}/v13/deployments`, {
 		method: "POST",
@@ -100,7 +177,7 @@ export async function deployVercelRelay(
 		body: JSON.stringify({
 			name,
 			files: [
-				{ file: "api/relay.js", data: VERCEL_RELAY_WORKER },
+				{ file: "api/relay.js", data: buildVercelRelayWorker(relayAuth) },
 				{
 					file: "package.json",
 					data: JSON.stringify({ name, version: "1.0.0" }),
@@ -160,7 +237,7 @@ export async function deployVercelRelay(
 			if (j.readyState === "READY" && j.url) {
 				const deployedUrl = `https://${j.url}`;
 				log("info", `Vercel relay successfully deployed: ${deployedUrl}`);
-				return deployedUrl;
+				return { url: deployedUrl, auth: relayAuth };
 			}
 			if (j.readyState === "ERROR" || j.readyState === "CANCELED") {
 				const err = `Deployment failed with state: ${j.readyState}`;
@@ -183,146 +260,6 @@ const DENO_API = "https://api.deno.com/v2";
 
 export type DeployPlatform = "vercel" | "cloudflare" | "deno";
 
-/**
- * Module Worker relay deployed to Cloudflare Workers.
- * Same whitelist contract as the Vercel Edge relay, with SSRF guard, relay-path resolver, and streaming duplex.
- */
-export const CLOUDFLARE_RELAY_WORKER = `// Only the 2 upstreams this relay talks to. Anything else = open proxy abuse.
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
-const resolveRelayTarget = function(target, relayPath) {
-  let targetUrl;
-  try { targetUrl = new URL(target); } catch { return { ok: false, status: 400, reason: "invalid x-relay-target" }; }
-  if (typeof relayPath !== "string" || relayPath.indexOf("@") !== -1 || relayPath.indexOf("\\") !== -1 || relayPath.charAt(0) !== "/") {
-    return { ok: false, status: 403, reason: "forbidden x-relay-path" };
-  }
-  let finalUrl;
-  try { finalUrl = new URL(relayPath, targetUrl); } catch { return { ok: false, status: 403, reason: "forbidden x-relay-path" }; }
-  if (finalUrl.hostname !== targetUrl.hostname || finalUrl.protocol !== targetUrl.protocol || finalUrl.port !== targetUrl.port || finalUrl.username || finalUrl.password) {
-    return { ok: false, status: 403, reason: "forbidden x-relay-path (host mismatch)" };
-  }
-  return { ok: true, url: finalUrl.toString() };
-};
-const isPrivateHostname = function(h) {
-  if (!h) return true
-  let host = String(h).trim().toLowerCase().replace(/^\[|\]$/g, "")
-  if (host.length > 1 && host.endsWith(".")) host = host.slice(0, -1)
-  if (!host) return true
-  if (host === "localhost" || host === "0.0.0.0" || host === "127.0.0.1" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true
-  if (host.startsWith("::")) return true
-  const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
-  if (v4) {
-    const a = Number(v4[1])
-    const b = Number(v4[2])
-    if (a === 0 || a === 10 || a === 127) return true
-    if (a === 169 && b === 254) return true
-    if (a === 192 && b === 168) return true
-    if (a === 172 && b >= 16 && b <= 31) return true
-    if (a === 100 && b >= 64 && b <= 127) return true
-    return false
-  }
-  if (host.includes(":")) {
-    if (host.startsWith("fc") || host.startsWith("fd")) return true
-    if (/^fe[89ab]/.test(host)) return true
-    return false
-  }
-  return false
-};
-export default {
-  async fetch(request) {
-    const target = request.headers.get("x-relay-target");
-    if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400, headers: { "content-type": "application/json" } });
-    let targetUrl;
-    try { targetUrl = new URL(target); } catch { return new Response(JSON.stringify({ error: "invalid x-relay-target" }), { status: 400, headers: { "content-type": "application/json" } }); }
-    if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") return new Response(JSON.stringify({ error: "forbidden x-relay-target protocol" }), { status: 403, headers: { "content-type": "application/json" } });
-    if (targetUrl.username || targetUrl.password) return new Response(JSON.stringify({ error: "forbidden x-relay-target (embedded credentials)" }), { status: 403, headers: { "content-type": "application/json" } });
-    if (isPrivateHostname(targetUrl.hostname)) return new Response(JSON.stringify({ error: "forbidden x-relay-target (private/loopback host)" }), { status: 403, headers: { "content-type": "application/json" } });
-    const cleanTarget = target.replace(/\/$/, "");
-    if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403, headers: { "content-type": "application/json" } });
-    const relayPath = request.headers.get("x-relay-path") || "/";
-    const resolved = resolveRelayTarget(target, relayPath);
-    if (!resolved.ok) return new Response(JSON.stringify({ error: resolved.reason }), { status: resolved.status, headers: { "content-type": "application/json" } });
-    const headers = new Headers(request.headers);
-    ["host", "connection", "content-length", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization", "transfer-encoding", "te", "trailer", "upgrade", "x-relay-target", "x-relay-path", "x-relay-auth"].forEach((h) => headers.delete(h));
-    try {
-      const init = { method: request.method, headers };
-      if (request.method !== "GET" && request.method !== "HEAD") { init.body = request.body; init.duplex = "half"; }
-      const response = await fetch(resolved.url, init);
-      return new Response(response.body, { status: response.status, headers: response.headers });
-    } catch (error) {
-      return new Response(JSON.stringify({ error: String(error) }), { status: 502, headers: { "content-type": "application/json" } });
-    }
-  },
-};`;
-
-/**
- * Relay script deployed to Deno Deploy (Deno.serve variant).
- * Same whitelist contract as the Vercel Edge relay, with SSRF guard and relay-path resolver.
- */
-export const DENO_RELAY_SCRIPT = `// Only the 2 upstreams this relay talks to. Anything else = open proxy abuse.
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
-const resolveRelayTarget = function(target, relayPath) {
-  let targetUrl;
-  try { targetUrl = new URL(target); } catch { return { ok: false, status: 400, reason: "invalid x-relay-target" }; }
-  if (typeof relayPath !== "string" || relayPath.indexOf("@") !== -1 || relayPath.indexOf("\\") !== -1 || relayPath.charAt(0) !== "/") {
-    return { ok: false, status: 403, reason: "forbidden x-relay-path" };
-  }
-  let finalUrl;
-  try { finalUrl = new URL(relayPath, targetUrl); } catch { return { ok: false, status: 403, reason: "forbidden x-relay-path" }; }
-  if (finalUrl.hostname !== targetUrl.hostname || finalUrl.protocol !== targetUrl.protocol || finalUrl.port !== targetUrl.port || finalUrl.username || finalUrl.password) {
-    return { ok: false, status: 403, reason: "forbidden x-relay-path (host mismatch)" };
-  }
-  return { ok: true, url: finalUrl.toString() };
-};
-const isPrivateHostname = function(h) {
-  if (!h) return true
-  let host = String(h).trim().toLowerCase().replace(/^\[|\]$/g, "")
-  if (host.length > 1 && host.endsWith(".")) host = host.slice(0, -1)
-  if (!host) return true
-  if (host === "localhost" || host === "0.0.0.0" || host === "127.0.0.1" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true
-  if (host.startsWith("::")) return true
-  const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
-  if (v4) {
-    const a = Number(v4[1])
-    const b = Number(v4[2])
-    if (a === 0 || a === 10 || a === 127) return true
-    if (a === 169 && b === 254) return true
-    if (a === 192 && b === 168) return true
-    if (a === 172 && b >= 16 && b <= 31) return true
-    if (a === 100 && b >= 64 && b <= 127) return true
-    return false
-  }
-  if (host.includes(":")) {
-    if (host.startsWith("fc") || host.startsWith("fd")) return true
-    if (/^fe[89ab]/.test(host)) return true
-    return false
-  }
-  return false
-};
-Deno.serve(async (request) => {
-  const target = request.headers.get("x-relay-target");
-  if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400, headers: { "content-type": "application/json" } });
-  let targetUrl;
-  try { targetUrl = new URL(target); } catch { return new Response(JSON.stringify({ error: "invalid x-relay-target" }), { status: 400, headers: { "content-type": "application/json" } }); }
-  if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") return new Response(JSON.stringify({ error: "forbidden x-relay-target protocol" }), { status: 403, headers: { "content-type": "application/json" } });
-  if (targetUrl.username || targetUrl.password) return new Response(JSON.stringify({ error: "forbidden x-relay-target (embedded credentials)" }), { status: 403, headers: { "content-type": "application/json" } });
-  if (isPrivateHostname(targetUrl.hostname)) return new Response(JSON.stringify({ error: "forbidden x-relay-target (private/loopback host)" }), { status: 403, headers: { "content-type": "application/json" } });
-  const cleanTarget = target.replace(/\/$/, "");
-  if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403, headers: { "content-type": "application/json" } });
-  const relayPath = request.headers.get("x-relay-path") || "/";
-  const resolved = resolveRelayTarget(target, relayPath);
-  if (!resolved.ok) return new Response(JSON.stringify({ error: resolved.reason }), { status: resolved.status, headers: { "content-type": "application/json" } });
-  const headers = new Headers(request.headers);
-  ["host", "connection", "content-length", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization", "transfer-encoding", "te", "trailer", "upgrade", "x-relay-target", "x-relay-path", "x-relay-auth"].forEach((h) => headers.delete(h));
-  try {
-    const init = { method: request.method, headers };
-    if (request.method !== "GET" && request.method !== "HEAD") { init.body = request.body; init.duplex = "half"; }
-    const response = await fetch(resolved.url, init);
-    return new Response(response.body, { status: response.status, headers: response.headers });
-  } catch (error) {
-    return new Response(JSON.stringify({ error: String(error) }), { status: 502, headers: { "content-type": "application/json" } });
-  }
-});`;
-
 function baseRelayName(name: string): string {
 	return name
 		.toLowerCase()
@@ -394,13 +331,13 @@ async function denoError(action: string, res: Response, override?: string): Prom
  * @param token Cloudflare API token (used in-memory only)
  * @param name Unique worker/script name (sanitized to [a-z0-9-])
  * @param onProgress Optional callback for user-facing progress updates
- * @returns Public *.workers.dev relay URL
+ * @returns Public { url, auth } — relay URL plus the embedded shared secret
  */
 export async function deployCloudflareWorker(
 	token: string,
 	name: string,
 	onProgress?: (msg: string) => void,
-): Promise<string> {
+): Promise<{ url: string; auth: string }> {
 	const auth = { Authorization: `Bearer ${token}` };
 	const scriptName = cloudflareScriptName(name);
 
@@ -419,10 +356,13 @@ export async function deployCloudflareWorker(
 
 	// 2. Upload the module worker script (multipart: main module + metadata)
 	onProgress?.("Uploading relay worker to Cloudflare…");
+	// Per-deployment shared secret: embedded in the worker, persisted on the
+	// relay-state entry by the caller, and required via x-relay-auth.
+	const relayAuth = randomBytes(24).toString("base64url");
 	const formData = new FormData();
 	formData.append(
 		"index.js",
-		new Blob([CLOUDFLARE_RELAY_WORKER], { type: "application/javascript+module" }),
+		new Blob([buildCloudflareRelayWorker(relayAuth)], { type: "application/javascript+module" }),
 		"index.js",
 	);
 	formData.append(
@@ -467,7 +407,7 @@ export async function deployCloudflareWorker(
 	}
 	const url = `https://${scriptName}.${subdomain}.workers.dev`;
 	log("info", `Cloudflare relay successfully deployed: ${url}`);
-	return url;
+	return { url, auth: relayAuth };
 }
 
 type DenoRevision = {
@@ -504,13 +444,13 @@ async function firstManagedDenoDomain(token: string): Promise<string | null> {
  * @param token Deno Deploy organization access token (used in-memory only)
  * @param name Unique app/project name (sanitized to a valid slug)
  * @param onProgress Optional callback for user-facing progress updates
- * @returns Public *.deno.dev-style (*.deno.net) relay URL
+ * @returns Public { url, auth } — relay URL plus the embedded shared secret
  */
 export async function deployDenoRelay(
 	token: string,
 	name: string,
 	onProgress?: (msg: string) => void,
-): Promise<string> {
+): Promise<{ url: string; auth: string }> {
 	const auth = { Authorization: `Bearer ${token}` };
 	const jsonHeaders = { ...auth, "Content-Type": "application/json" };
 	const slug = denoProjectName(name);
@@ -553,12 +493,15 @@ export async function deployDenoRelay(
 
 	// 2. Push the relay source as a single-file revision
 	onProgress?.("Uploading relay script to Deno Deploy…");
+	// Per-deployment shared secret: embedded in the worker, persisted on the
+	// relay-state entry by the caller, and required via x-relay-auth.
+	const relayAuth = randomBytes(24).toString("base64url");
 	const deployRes = await fetch(`${DENO_API}/apps/${appId}/deploy`, {
 		method: "POST",
 		headers: jsonHeaders,
 		body: JSON.stringify({
 			assets: {
-				"main.ts": { kind: "file", content: DENO_RELAY_SCRIPT, encoding: "utf-8" },
+				"main.ts": { kind: "file", content: buildDenoRelayScript(relayAuth), encoding: "utf-8" },
 			},
 		}),
 	});
@@ -616,7 +559,7 @@ export async function deployDenoRelay(
 	if (routed) {
 		const url = `https://${routed}`;
 		log("info", `Deno Deploy relay successfully deployed: ${url}`);
-		return url;
+		return { url, auth: relayAuth };
 	}
 	const managed = await firstManagedDenoDomain(token);
 	if (!managed) {
@@ -626,5 +569,5 @@ export async function deployDenoRelay(
 	}
 	const url = `https://${slug}.${managed}`;
 	log("info", `Deno Deploy relay successfully deployed: ${url}`);
-	return url;
+	return { url, auth: relayAuth };
 }

package/src/health.ts

@@ -7,6 +7,7 @@ import type * as http from "node:http";
 import { ALL_MODELS } from "./models.ts";
 import { getActiveRelayState, getRelayHealth, isRelayHealthy } from "./relay-state.ts";
 import { PORT } from "./config.ts";
+import { getClientIP } from "./proxy.ts";
 
 export interface HealthRelayInfo {
 	url: string;
@@ -58,12 +59,6 @@ function isLoopbackIP(ip: string): boolean {
 	return clean === "127.0.0.1" || clean === "::1" || clean === "localhost";
 }
 
-function getClientIPFromReq(req: http.IncomingMessage): string {
-	const addr = (req.socket as unknown as { remoteAddress?: string })?.remoteAddress;
-	if (!addr) return "unknown";
-	return addr.startsWith("::ffff:") ? addr.slice(7) : addr;
-}
-
 /**
  * Handle loopback health requests.
  * Returns true if request was a health endpoint (handled, response already sent).
@@ -87,7 +82,7 @@ export function handleHealthRequest(
 		return false;
 	}
 
-	const clientIP = getClientIPFromReq(req);
+	const clientIP = getClientIP(req);
 	if (!isLoopbackIP(clientIP)) {
 		const body = JSON.stringify({ error: "forbidden" });
 		res.writeHead(403, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });

package/src/index.ts

@@ -1,13 +1,14 @@
 /**
  * pi-freeflow — Modular, high-resiliency LLM extension for Pi & Oh My Pi (OMP)
  *
- * Provides access to 21 free models (7 OpenCode Zen + 14 KiloCode Gateway) with:
+ * Provides access to 25 free models (7 OpenCode Zen + 18 KiloCode Gateway) with:
  * - Single-port daemon reuse on 28180 across concurrent subagents
  * - Multi-cloud rolling egress relays (Vercel Edge, Cloudflare, Deno)
  * - 0ms instant startup with verified static catalog and background live health checks
  * - Per-model thinking/reasoning translation and streaming SSE pass-through
  */
-
+import fs from "node:fs";
+import path from "node:path";
 import type * as http from "node:http";
 import {
 	getAliveCatalog,
@@ -17,9 +18,9 @@ import {
 	setAliveCatalog,
 } from "./catalog.ts";
 import { createCommandSpec, updateStatusBar } from "./commands.ts";
-import { DEFAULT_HOST, HOST, LEGACY_PORT, PORT } from "./config.ts";
+import { HOST, LEGACY_PORT, ONBOARDED_FLAG_FILE, PORT } from "./config.ts";
 import { log, logInfo, logWarn } from "./logger.ts";
-import { ALL_MODELS, KILO_MODEL_IDS, MODEL_MAP, getAllRegisteredModels, resolveCanonicalModelId } from "./models.ts";
+import { ALL_MODELS, KILO_MODEL_IDS, MODEL_MAP, resolveCanonicalModelId } from "./models.ts";
 import { isProxyAlive, startProxy } from "./proxy.ts";
 import { resetRateLimits } from "./rate-limiter.ts";
 import { checkForUpdateInBackground } from "./update-checker.ts";
@@ -298,6 +299,23 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		setStatusUi(ctx.ui);
 		try { bindWidgetClick(ctx.ui); } catch {}
 
+		// First-run onboarding: write the flag before notifying so a crash can
+		// never re-fire the message; never block session start.
+		try {
+			if (!fs.existsSync(ONBOARDED_FLAG_FILE)) {
+				fs.mkdirSync(path.dirname(ONBOARDED_FLAG_FILE), { recursive: true });
+				fs.writeFileSync(ONBOARDED_FLAG_FILE, "1", "utf8");
+				const hint =
+					freshRelayState.relays.length > 0
+						? `Relay pool ready: ${freshRelayState.relays.length} relay(s). Run /freeflow for pool management.`
+						: "Relay pool empty — direct mode. Run /freeflow deploy to add your own egress.";
+				ctx.ui?.notify?.(
+					`freeflow ready: 25 free models via local proxy 127.0.0.1:28180. ${hint}`,
+					"info",
+				);
+			}
+		} catch {}
+
 		let provider: string | undefined;
 		let modelId: string | undefined;
 		if (ctx && typeof ctx === "object" && "model" in ctx && ctx.model && typeof ctx.model === "object") {