@instafy/cli 0.2.3 → 0.3.0

package/dist/bind/src/net.mjs

@@ -0,0 +1,281 @@
+// SSRF guard: URL params and handler fetches go only to public http(s) addresses unless --allow-local.
+import dns from "node:dns";
+import net from "node:net";
+import http from "node:http";
+import https from "node:https";
+
+function ipv4ToInt(ip) {
+  return ip.split(".").reduce((acc, part) => (acc << 8) + Number(part), 0) >>> 0;
+}
+
+const V4_BLOCKS = [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16],
+  ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15],
+  ["198.51.100.0", 24], ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+].map(([base, bits]) => [ipv4ToInt(base), bits]);
+
+function isPrivateV4(ip) {
+  const value = ipv4ToInt(ip);
+  return V4_BLOCKS.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+    return (value & mask) === (base & mask);
+  });
+}
+
+function expandV6(ip) {
+  let address = ip.toLowerCase().replace(/%.*$/, "");
+  let tail = [];
+  const v4 = address.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4) {
+    const n = ipv4ToInt(v4[1]);
+    tail = [(n >>> 16).toString(16), (n & 0xffff).toString(16)];
+    address = address.slice(0, -v4[1].length).replace(/:$/, "") || ":";
+    if (address === ":") address = "::";
+  }
+  const [head, rest] = address.split("::");
+  const left = head ? head.split(":").filter(Boolean) : [];
+  const right = rest !== undefined ? (rest ? rest.split(":").filter(Boolean) : []) : null;
+  const known = left.length + (right ? right.length : 0) + tail.length;
+  const middle = right === null ? [] : Array(Math.max(0, 8 - known)).fill("0");
+  return [...left, ...middle, ...(right || []), ...tail].map((h) => parseInt(h, 16) || 0);
+}
+
+function isPrivateV6(ip) {
+  const g = expandV6(ip);
+  if (g.length !== 8) return true;
+  const allZeroUpTo = (n) => g.slice(0, n).every((x) => x === 0);
+  if (allZeroUpTo(8)) return true; // ::
+  if (allZeroUpTo(7) && g[7] === 1) return true; // ::1
+  const embedded = () => `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+  if (allZeroUpTo(5) && g[5] === 0xffff) return isPrivateV4(embedded()); // ::ffff:a.b.c.d
+  if (allZeroUpTo(6)) return true; // ::a.b.c.d (deprecated compatible)
+  if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((x) => x === 0)) return isPrivateV4(embedded()); // NAT64
+  if ((g[0] & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local
+  if ((g[0] & 0xffc0) === 0xfe80) return true; // fe80::/10 link local
+  if ((g[0] & 0xffc0) === 0xfec0) return true; // fec0::/10 site local
+  if ((g[0] & 0xff00) === 0xff00) return true; // multicast
+  if (g[0] === 0x2001 && g[1] === 0x0db8) return true; // documentation
+  if (g[0] === 0x2001 && g[1] === 0x0000) return true; // 2001::/32 Teredo (tunnels to arbitrary IPv4)
+  if (g[0] === 0x2002) return isPrivateV4(`${g[1] >> 8}.${g[1] & 255}.${g[2] >> 8}.${g[2] & 255}`); // 2002::/16 6to4
+  return false;
+}
+
+/** True for loopback, private, link-local, CGNAT, multicast, reserved and documentation addresses. */
+export function isPrivateAddress(ip) {
+  const family = net.isIP(ip);
+  if (family === 4) return isPrivateV4(ip);
+  if (family === 6) return isPrivateV6(ip);
+  return true;
+}
+
+const LOCAL_NAME_RE = /(^|\.)(localhost|local|internal|lan|home|intranet|localdomain)$/i;
+
+/**
+ * Check that a URL points at a public http(s) host. Resolves DNS names.
+ * Returns {ok: true, addresses} or {ok: false, reason}.
+ */
+export async function checkPublicUrl(raw, { allowLocal = false, lookup = dns.promises.lookup } = {}) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: "not a valid URL" };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return { ok: false, reason: "only http(s) URLs are allowed" };
+  if (url.username || url.password) return { ok: false, reason: "URLs with credentials are not allowed" };
+  if (allowLocal) return { ok: true, addresses: [] };
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (net.isIP(host)) {
+    return isPrivateAddress(host) ? { ok: false, reason: `${host} is a private or local address` } : { ok: true, addresses: [host] };
+  }
+  if (LOCAL_NAME_RE.test(host) || !host.includes(".")) return { ok: false, reason: `${host} is a local host name` };
+  let addresses;
+  try {
+    addresses = (await lookup(host, { all: true, verbatim: true })).map((entry) => entry.address);
+  } catch (error) {
+    return { ok: false, reason: `${host} does not resolve (${error.code || error.message})` };
+  }
+  const blocked = addresses.find(isPrivateAddress);
+  if (blocked) return { ok: false, reason: `${host} resolves to a private address` };
+  return { ok: true, addresses };
+}
+
+/**
+ * Every string in `value` that its schema marks format: uri, walking properties, additionalProperties,
+ * items and oneOf/anyOf/allOf branches. Returns [{path, value}].
+ */
+export function uriParams(schema, value, at = "") {
+  const out = [];
+  if (!schema || typeof schema !== "object") return out;
+  const branches = [...(schema.oneOf || []), ...(schema.anyOf || []), ...(schema.allOf || [])];
+  if (typeof value === "string" && (schema.format === "uri" || branches.some((b) => b?.format === "uri"))) {
+    out.push({ path: at || "$", value });
+    return out;
+  }
+  if (Array.isArray(value)) {
+    const items = schema.items && typeof schema.items === "object" ? schema.items : null;
+    if (items) value.forEach((entry, i) => out.push(...uriParams(items, entry, `${at}[${i}]`)));
+  } else if (value && typeof value === "object") {
+    const props = schema.properties || {};
+    for (const [key, entry] of Object.entries(value)) {
+      const sub = Object.prototype.hasOwnProperty.call(props, key) ? props[key] : typeof schema.additionalProperties === "object" ? schema.additionalProperties : null;
+      if (sub) out.push(...uriParams(sub, entry, at ? `${at}.${key}` : key));
+    }
+  }
+  for (const branch of branches) if (typeof value !== "string") out.push(...uriParams(branch, value, at));
+  return out;
+}
+
+/**
+ * Check every param the schema marks format: uri (nested ones too): public http(s) only, and inside
+ * `allowedOrigins` when that list is given. Returns null or a reason.
+ */
+export async function checkUriParams(paramsSchema, params, { allowedOrigins = null, ...options } = {}) {
+  const seen = new Set();
+  for (const { path: at, value } of uriParams(paramsSchema, params)) {
+    if (seen.has(at)) continue;
+    seen.add(at);
+    if (allowedOrigins && allowedOrigins.length && !originAllowed(value, allowedOrigins)) {
+      let origin = value;
+      try {
+        origin = new URL(value).origin;
+      } catch {
+        // reported as is
+      }
+      return `${at}: ${String(origin).slice(0, 80)} is not in allowed_origins`;
+    }
+    const result = await checkPublicUrl(value, options);
+    if (!result.ok) return `${at}: ${result.reason}`;
+  }
+  return null;
+}
+
+/** The origins of an intent's URL params, as allowed_origins patterns (used when an agent intent declares none). */
+export function uriParamOrigins(paramsSchema, params) {
+  const origins = new Set();
+  for (const { value } of uriParams(paramsSchema, params)) {
+    try {
+      const url = new URL(value);
+      if (url.protocol === "https:" || url.protocol === "http:") origins.add(url.origin);
+    } catch {
+      // not a URL
+    }
+  }
+  return [...origins];
+}
+
+/** A dns.lookup wrapper that refuses private addresses at connect time (covers DNS rebinding). */
+function guardedLookup(allowLocal) {
+  return (hostname, options, callback) => {
+    dns.lookup(hostname, { ...options, all: true }, (error, addresses) => {
+      if (error) return callback(error);
+      const list = Array.isArray(addresses) ? addresses : [{ address: addresses, family: options.family || 4 }];
+      if (!allowLocal) {
+        const blocked = list.find((entry) => isPrivateAddress(entry.address));
+        if (blocked) {
+          const refusal = new Error(`refusing to connect to private address for ${hostname}`);
+          refusal.code = "EPRIVATE";
+          return callback(refusal);
+        }
+      }
+      if (options.all) return callback(null, list);
+      return callback(null, list[0].address, list[0].family);
+    });
+  };
+}
+
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/** Response headers up to this size are read (Node's default, 16 KB, is less than some shops send). */
+export const MAX_HEADER_BYTES = 128 * 1024;
+
+/**
+ * Fetch a public URL for script handlers. Redirects are followed manually and re-checked (and passed to `checkHop`);
+ * credential headers are dropped when a redirect changes origin.
+ * Resolves {ok, status, url, headers, body: Buffer, text(): Promise<string>, json(): Promise<any>}.
+ */
+export async function safeFetch(raw, { allowLocal = false, method = "GET", headers: initialHeaders = {}, maxBytes = 5 * 1024 * 1024, timeoutMs = 20_000, maxRedirects = 5, followRedirects = true, checkHop = null } = {}) {
+  let current = raw;
+  let headers = { ...initialHeaders };
+  let firstOrigin = null;
+  for (let hop = 0; hop <= maxRedirects; hop += 1) {
+    const check = await checkPublicUrl(current, { allowLocal });
+    if (!check.ok) throw Object.assign(new Error(`blocked: ${check.reason}`), { code: "policy" });
+    // A caller's own rule for every URL it would read, the first one and each redirect target (kit.fetch: robots.txt).
+    // It throws to refuse.
+    if (checkHop) await checkHop(current, hop);
+    const url = new URL(current);
+    firstOrigin ??= url.origin;
+    if (url.origin !== firstOrigin) {
+      headers = Object.fromEntries(Object.entries(headers).filter(([name]) => !CREDENTIAL_HEADERS.includes(name.toLowerCase())));
+    }
+    const response = await new Promise((resolve, reject) => {
+      const lib = url.protocol === "https:" ? https : http;
+      const request = lib.request(url, {
+        method,
+        headers: { "user-agent": "instafy-bind/0.1", ...headers },
+        lookup: net.isIP(url.hostname.replace(/^\[|\]$/g, "")) ? undefined : guardedLookup(allowLocal),
+        timeout: timeoutMs,
+        maxHeaderSize: MAX_HEADER_BYTES,
+      }, (res) => {
+        const chunks = [];
+        let size = 0;
+        res.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > maxBytes) {
+            request.destroy(Object.assign(new Error(`response larger than ${maxBytes} bytes`), { code: "upstream" }));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on("end", () => resolve({ status: res.statusCode, headers: res.headers, body: Buffer.concat(chunks) }));
+        res.on("error", reject);
+      });
+      request.on("timeout", () => request.destroy(Object.assign(new Error("request timed out"), { code: "timeout" })));
+      request.on("error", (error) => {
+        // Say which site failed; a handler that does not catch it still reports something readable.
+        if (error.code === "upstream" || error.code === "timeout" || error.code === "EPRIVATE") return reject(error);
+        reject(Object.assign(new Error(`could not read ${url.hostname}: ${error.reason || error.message}`), { code: "upstream", cause: error }));
+      });
+      request.end();
+    });
+    if (followRedirects && [301, 302, 303, 307, 308].includes(response.status) && response.headers.location) {
+      current = new URL(response.headers.location, url).toString();
+      continue;
+    }
+    return {
+      ok: response.status >= 200 && response.status < 300,
+      status: response.status,
+      url: url.toString(),
+      headers: response.headers,
+      body: response.body,
+      text: async () => response.body.toString("utf8"),
+      json: async () => JSON.parse(response.body.toString("utf8")),
+    };
+  }
+  throw Object.assign(new Error("too many redirects"), { code: "upstream" });
+}
+
+/** Match an origin against bound.json allowed_origins patterns like "https://*" or "https://*.example.com". */
+export function originAllowed(raw, patterns) {
+  if (!patterns || patterns.length === 0) return true;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  return patterns.some((pattern) => {
+    const match = pattern.match(/^(https?):\/\/([^:/]+)(?::(\d+))?$/);
+    if (!match) return false;
+    const [, scheme, hostPattern, port] = match;
+    if (`${scheme}:` !== url.protocol) return false;
+    const actualPort = url.port || (scheme === "https" ? "443" : "80");
+    if (actualPort !== (port || (scheme === "https" ? "443" : "80"))) return false;
+    if (hostPattern === "*") return true;
+    if (hostPattern.startsWith("*.")) {
+      const suffix = hostPattern.slice(1).toLowerCase();
+      return url.hostname.toLowerCase().endsWith(suffix);
+    }
+    return url.hostname.toLowerCase() === hostPattern.toLowerCase();
+  });
+}

package/dist/bind/src/page-fetch.mjs

@@ -0,0 +1,43 @@
+// Page reads for script handlers (kit.fetch) and for the robots.txt check: one SSRF-guarded GET (net.mjs). A site
+// that does not answer (refused, reset, timed out, not resolvable) or answers 5xx is "unavailable" (error code
+// "unavailable"): not a missing page, so a handler can say it could not be checked right now. 404/410 and every other
+// answer are returned to the caller.
+// SPDX-License-Identifier: AGPL-3.0-only
+import { safeFetch } from "./net.mjs";
+
+const UNAVAILABLE_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "EHOSTUNREACH", "ENETUNREACH", "EAI_AGAIN", "ENOTFOUND", "EPIPE", "timeout", "unavailable"]);
+
+/** Did this error mean the site did not answer (as opposed to a refusal, a bad URL or a bug)? */
+export function isUnavailable(error) {
+  if (!error || error.code === "policy" || error.code === "invalid") return false;
+  if (error.code === "unavailable") return true;
+  const code = error.code === "upstream" ? error.cause?.code : error.code;
+  return Boolean(code && UNAVAILABLE_CODES.has(code));
+}
+
+const unavailable = (message, extra = {}) => Object.assign(new Error(message), { code: "unavailable", ...extra });
+
+/**
+ * safeFetch's signature and answer. Throws code "unavailable" when the site did not answer or answered 5xx
+ * (`answerAnyStatus` keeps a 5xx as an answer: robots.txt reads 5xx as "do not crawl"); "policy" refusals as before.
+ */
+export async function pageFetch(url, options = {}) {
+  const { answerAnyStatus = false, ...rest } = options;
+  let host = "the page";
+  try {
+    host = new URL(url).host.toLowerCase();
+  } catch {
+    // safeFetch reports the bad URL
+  }
+  let response;
+  try {
+    response = await safeFetch(url, rest);
+  } catch (error) {
+    if (!isUnavailable(error)) throw error;
+    throw unavailable(`${host} did not answer (${String(error.message).slice(0, 160)}): unavailable right now, not a missing page`, { cause: error });
+  }
+  if (!answerAnyStatus && response.status >= 500) {
+    throw unavailable(`${host} answered HTTP ${response.status}: unavailable right now, not a missing page`, { httpStatus: response.status });
+  }
+  return response;
+}

package/dist/bind/src/preview-host.mjs

@@ -0,0 +1,114 @@
+// Preview mode (`serve --preview`): serve a bound site inside Studio's preview card without a viewer token.
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// Why this is safe. `instafy preview open --port N` connects a private tunnel to 127.0.0.1:N. The tunnel broker's
+// Traefik only routes that tunnel through a capability host `p-<26 base32 label>--<32 hex tunnel id>.<preview
+// domain>`, behind the broker's forwardAuth, which lets through only space members holding a live per-Open session
+// (tunnel-broker ingress.rs; runtime-controller previews/sessions.rs). Traefik keeps the Host header and the rathole
+// hop is plain TCP, so the binder sees that capability host. The site backend holds no credential (see
+// SITE-BACKEND-CONTRACT.md): forwardAuth on the capability host is the auth, so the binder needs no token of its own.
+//
+// What the binder still checks, because without a token anything that reaches the port could act:
+// - it listens on loopback only (enforced by createBinder), so only this runtime's own processes and its tunnels
+//   reach it;
+// - the Host header is a loopback name at the binder's port, or a capability host `p-<label>--<id>.<suffix>` where
+//   <id> is a preview `instafy preview open` recorded for this port (~/.instafy/cli-preview-state.json) AND <suffix>
+//   is exactly the preview domain (and port) the controller told the CLI that preview is viewed under (`hostSuffix`).
+//   The tunnel id alone is not a secret: every member's frame address carries it and it leaks as a Referer, so a
+//   DNS-rebinding page named `p-<any label>--<id>.attacker.example` could otherwise pose as the preview host. The
+//   attacker cannot serve a page from the real preview domain, so pinning the domain is what stops rebinding. A state
+//   entry without a hostSuffix (an older CLI) is never accepted. A public tunnel (`instafy tunnel`, Host
+//   `<uuid>.<tunnel domain>`) or any other name gets 421;
+// - intents still need Origin == Host (same origin) and a JSON body (CORS preflight), as with a token;
+// - frame messages (Ask Octo, location, follow mode) are taken only from the Studio origin `instafy preview open`
+//   recorded for that preview (`studioOrigin`, from the controller): the capability host sends
+//   `frame-ancestors 'self' <studio origin>` and the bind client trusts no other parent. The label is a bearer that
+//   also leaks in Origin headers, so without this any page that framed the preview URL could act as its host. A
+//   preview without a recorded Studio origin is still shown, but its page takes no host messages at all.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The capability host the broker routes private previews by (Traefik HostRegexp), plus an optional port. */
+export const PREVIEW_HOST_RE = /^p-[a-z2-7]{26}--([0-9a-f]{32})\.([a-z0-9-]+(?:\.[a-z0-9-]+)*(?::\d{1,5})?)$/;
+
+/** Where the Instafy CLI records the previews it opened (instafy-cli src/preview.ts previewStateFile). */
+export function defaultPreviewStateFile() {
+  return path.join(os.homedir(), ".instafy", "cli-preview-state.json");
+}
+
+/** The tunnel id (32 lowercase hex) of a capability Host header, or null. */
+export function previewTunnelOf(hostHeader) {
+  return previewHostParts(hostHeader)?.tunnel ?? null;
+}
+
+/** `{ tunnel, suffix }` of a capability Host header (suffix = the domain and any port after the first label), or null. */
+export function previewHostParts(hostHeader) {
+  const match = PREVIEW_HOST_RE.exec(String(hostHeader || "").trim().toLowerCase());
+  return match ? { tunnel: match[1], suffix: match[2] } : null;
+}
+
+const normalizeSuffix = (raw) => {
+  const suffix = String(raw || "").trim().toLowerCase().replace(/^\.+/, "");
+  return /^[a-z0-9-]+(?:\.[a-z0-9-]+)*(?::\d{1,5})?$/.test(suffix) ? suffix : null;
+};
+
+const normalizeTunnelId = (raw) => {
+  const hex = String(raw || "").trim().toLowerCase().replace(/-/g, "");
+  return /^[0-9a-f]{32}$/.test(hex) ? hex : null;
+};
+
+const normalizeOrigin = (raw) => {
+  if (typeof raw !== "string") return null;
+  try {
+    const url = new URL(raw.trim());
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    if (url.username || url.password || url.search || url.hash || (url.pathname !== "/" && url.pathname !== "")) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The previews opened for a local port, read from the CLI's state file: a Map of tunnel id → Map of the host suffixes
+ * it is viewed under → the Studio origins that frame it (empty when unknown). Entries without a hostSuffix are left out. The file is small and is written by `instafy preview open`
+ * after the binder starts, so it is read on use (cached until it changes).
+ */
+export function previewTunnelReader(file = defaultPreviewStateFile()) {
+  let cacheKey = null;
+  let cached = [];
+  return function tunnelsForPort(port) {
+    let stat;
+    try {
+      stat = fs.statSync(file);
+    } catch {
+      cacheKey = null;
+      cached = [];
+      return new Map();
+    }
+    const key = `${stat.mtimeMs}:${stat.size}`;
+    if (key !== cacheKey) {
+      cacheKey = key;
+      try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        cached = Array.isArray(parsed?.previews) ? parsed.previews.filter((p) => p && typeof p === "object") : [];
+      } catch {
+        cached = [];
+      }
+    }
+    const previews = new Map();
+    for (const entry of cached) {
+      if (Number(entry.localPort) !== Number(port)) continue;
+      const id = normalizeTunnelId(entry.previewId);
+      const suffix = normalizeSuffix(entry.hostSuffix);
+      if (!id || !suffix) continue;
+      if (!previews.has(id)) previews.set(id, new Map());
+      const suffixes = previews.get(id);
+      if (!suffixes.has(suffix)) suffixes.set(suffix, new Set());
+      const studio = normalizeOrigin(entry.studioOrigin);
+      if (studio) suffixes.get(suffix).add(studio);
+    }
+    return previews;
+  };
+}

package/dist/bind/src/protocol.mjs

@@ -0,0 +1,103 @@
+// Message shapes shared by the binder and the bind client.
+import { randomBytes } from "node:crypto";
+
+export const PROTOCOL_VERSION = 2;
+export const HOST_SOURCE = "instafy-host";
+export const INTENT_SOURCES = ["instafy-site"];
+export const HOST_TYPES = ["hello", "ack", "progress", "results", "done", "error", "command"];
+export const ACK_STATUSES = ["queued", "needs_confirm", "rejected", "running"];
+export const ERROR_CODES = ["not_found", "timeout", "policy", "upstream", "unavailable", "invalid", "cancelled", "dry_run", "internal"];
+export const COMMAND_NAMES = ["select", "highlight", "toast", "reload"];
+export const RESERVED_INTENTS = ["cancel"];
+
+export const INTENT_ID_RE = /^int_[a-z0-9]{1,12}_[a-z0-9]{2,8}$/;
+export const INTENT_NAME_RE = /^[a-z][a-z0-9_]{0,47}$/;
+/** The records-schema ref shape without whitespace or other free text: "<collection>:<id>". */
+export const ENVELOPE_REF_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,47}:[A-Za-z0-9_.:-]{1,120}$/;
+/** ui and attr hints from the page: short tokens only (they reach logs, prompts and other viewers). */
+export const ENVELOPE_TOKEN_RE = /^[A-Za-z0-9_.:-]{1,60}$/;
+/** Cancel keys returned to the submitting viewer only. */
+export const CANCEL_KEY_RE = /^[A-Za-z0-9_-]{16,64}$/;
+/** The whole POST body. */
+export const MAX_INTENT_BYTES = 8 * 1024;
+/** Serialised params. */
+export const MAX_PARAMS_BYTES = 4 * 1024;
+export const MAX_COMMAND_BYTES = 4 * 1024;
+
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+/** n uniform base36 characters (rejection sampling: bytes 252-255 are dropped, so no character is likelier). */
+const base36 = (n) => {
+  let out = "";
+  while (out.length < n) {
+    for (const b of randomBytes(n * 2)) {
+      if (b < 252 && out.length < n) out += ALPHABET[b % 36];
+    }
+  }
+  return out;
+};
+
+/** "int_" + base36(now) + "_" + 4 random base36 characters. */
+export function newIntentId(now = Date.now()) {
+  return `int_${now.toString(36)}_${base36(4)}`;
+}
+
+export function newJobId(now = Date.now()) {
+  return `job_${now.toString(36)}_${base36(6)}`;
+}
+
+/** Host -> site message with the protocol envelope. */
+export function hostMessage(type, fields = {}) {
+  return { source: HOST_SOURCE, v: PROTOCOL_VERSION, type, ...fields, at: new Date().toISOString() };
+}
+
+/** Clip text for progress/error messages (140 characters). */
+export function clip(text, max = 140) {
+  const value = String(text ?? "").replace(/\s+/g, " ").trim();
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+/**
+ * Structural check of an intent message before the per-intent params check.
+ * Returns null when the envelope is fine, else a short reason.
+ */
+export function checkIntentEnvelope(msg) {
+  if (!msg || typeof msg !== "object" || Array.isArray(msg)) return "body must be a JSON object";
+  if (!INTENT_SOURCES.includes(msg.source)) return `source must be one of ${INTENT_SOURCES.join(", ")}`;
+  if (msg.v !== PROTOCOL_VERSION) return `v must be ${PROTOCOL_VERSION}`;
+  if (msg.type !== "intent") return 'type must be "intent"';
+  if (typeof msg.id !== "string" || !INTENT_ID_RE.test(msg.id)) return "id must look like int_<base36>_<rand>";
+  if (typeof msg.name !== "string" || !INTENT_NAME_RE.test(msg.name)) return "name must match ^[a-z][a-z0-9_]{0,47}$";
+  if (!msg.params || typeof msg.params !== "object" || Array.isArray(msg.params)) return "params must be an object";
+  if (msg.ref !== undefined && msg.ref !== null && (typeof msg.ref !== "string" || !ENVELOPE_REF_RE.test(msg.ref))) {
+    return "ref must look like <collection>:<id> (letters, digits, _ . : -)";
+  }
+  for (const key of ["ui", "attr"]) {
+    const value = msg[key];
+    if (value !== undefined && value !== null && (typeof value !== "string" || !ENVELOPE_TOKEN_RE.test(value))) {
+      return `${key} must be a short token (letters, digits, _ . : -)`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Make text safe for a terminal or a log line: C0/C1 control characters (escape sequences included) become "?",
+ * newlines stay only when `multiline` is set.
+ */
+export function safeText(text, { multiline = false } = {}) {
+  const value = String(text ?? "");
+  const cleaned = value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "?");
+  return multiline ? cleaned : cleaned.replace(/\n/g, "\\n");
+}
+
+/** Deterministic JSON for coalescing keys (sorted object keys). */
+export function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}