@runuai/host 0.9.171 → 0.9.172

package/lib/custom-connection-capture.ts

@@ -0,0 +1,395 @@
+/** ADR-164 sign-in-box discovery and protocol admission. Provider response
+ * bodies and error text never leave this module. All production I/O goes
+ * through the DNS-pinned safeRequest transport. */
+import {
+  customConnectionEnabled,
+  validConnectionModels,
+  parseCustomConnectionMaterial,
+  parseEngineConnectCustomDiscoverFrame,
+  parseEngineConnectCustomSaveFrame,
+  parseEngineConnectCustomManualSaveFrame,
+  type EngineConnectCustomManualSaveFrame,
+  type CustomConnectionAuthMode,
+  type CustomConnectionDiscoverResult,
+  type CustomConnectionMaterial,
+  type CustomConnectionReason,
+  type CustomConnectionSaveResult,
+  type EngineConnectCustomDiscoverFrame,
+  type EngineConnectCustomSaveFrame,
+} from "../src/custom-connections";
+import { buildEngineCapture, parseCaptureFlow, writeCapture } from "./capture-flow";
+import type { CredentialStore } from "./credential-store";
+import { readOpenRouterBudget } from "./openrouter-budget";
+import { readSafeBody, safeRequest, SafeHttpRefusal, type SafeHttpRequest, type SafeHttpResponse } from "./safe-http";
+
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_BYTES = 1024 * 1024;
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_PAGES = 5;
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_MODELS = 2000;
+export const CUSTOM_CONNECTION_ATTEMPT_MS = 20_000;
+const PROBE_MAX_BYTES = 1024 * 1024;
+
+export interface CustomConnectionCaptureOptions {
+  /** Tests may replace the transport. Production always defaults safeRequest. */
+  request?: typeof safeRequest;
+  signal?: AbortSignal;
+  now?: () => number;
+}
+
+class ConnectionFailure extends Error {
+  constructor(readonly reason: CustomConnectionReason, readonly retryable = reason === "timeout") {
+    super(reason);
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function failure(error: unknown, signal?: AbortSignal): ConnectionFailure {
+  if (error instanceof ConnectionFailure) return error;
+  if (signal?.aborted || (error instanceof SafeHttpRefusal && error.reason === "timeout")) return new ConnectionFailure("timeout", true);
+  if (error instanceof SafeHttpRefusal) {
+    if (error.reason === "non_public_address") return new ConnectionFailure("private-address");
+    if (["url", "request_too_large", "response_too_large"].includes(error.reason)) return new ConnectionFailure("wrong-protocol");
+  }
+  return new ConnectionFailure("unreachable");
+}
+
+function statusFailure(status: number): ConnectionFailure {
+  if (status === 401) return new ConnectionFailure("unauthorized");
+  if (status === 403) return new ConnectionFailure("forbidden");
+  if (status === 404) return new ConnectionFailure("model-not-found");
+  if (status === 429) return new ConnectionFailure("rate-limited");
+  if (status >= 500 && status <= 599) return new ConnectionFailure("upstream-error", true);
+  return new ConnectionFailure("wrong-protocol");
+}
+
+function headers(settings: CustomConnectionMaterial, auth: CustomConnectionAuthMode = settings.authMode): Record<string, string> {
+  return {
+    ...(auth === "bearer" ? { authorization: `Bearer ${settings.apiKey}` } : { "x-api-key": settings.apiKey }),
+    ...(settings.engine === "claude" && settings.providerType !== "bedrock" ? { "anthropic-version": "2023-06-01" } : {}),
+  };
+}
+
+function deadline(options: CustomConnectionCaptureOptions): AbortSignal {
+  const timeout = AbortSignal.timeout(CUSTOM_CONNECTION_ATTEMPT_MS);
+  return options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+}
+
+async function exchange(request: SafeHttpRequest, options: CustomConnectionCaptureOptions, signal: AbortSignal): Promise<SafeHttpResponse> {
+  try {
+    return await (options.request ?? safeRequest)({ ...request, signal }, {
+      connectMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      headersMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      idleMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      maxRequestBodyBytes: 16 * 1024,
+    });
+  } catch (error) {
+    throw failure(error, signal);
+  }
+}
+
+async function body(response: SafeHttpResponse, maxBytes: number, signal: AbortSignal): Promise<Buffer> {
+  try { return await readSafeBody(response, maxBytes); } catch (error) { throw failure(error, signal); }
+}
+
+function decodeJson(raw: Buffer): unknown {
+  try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw)); } catch { throw new ConnectionFailure("wrong-protocol"); }
+}
+
+async function json(request: SafeHttpRequest, options: CustomConnectionCaptureOptions, signal: AbortSignal, maxBytes: number): Promise<{ value: Record<string, unknown>; bytes: number }> {
+  const response = await exchange(request, options, signal);
+  if (response.status !== 200) {
+    response.body.destroy();
+    throw statusFailure(response.status);
+  }
+  const raw = await body(response, maxBytes, signal);
+  const value = object(decodeJson(raw));
+  if (!value) throw new ConnectionFailure("wrong-protocol");
+  return { value, bytes: raw.byteLength };
+}
+
+function validated(settings: CustomConnectionMaterial, enabled: EngineConnectCustomDiscoverFrame["enabled"], now: number): CustomConnectionMaterial {
+  const parsed = parseCustomConnectionMaterial(settings);
+  if (!parsed || !customConnectionEnabled(parsed, enabled)) throw new ConnectionFailure("unsupported");
+  if (parsed.expiresAt !== undefined && parsed.expiresAt !== null && parsed.expiresAt <= now) throw new ConnectionFailure("expired");
+  return parsed;
+}
+
+function modelId(value: unknown, key: string): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 200 && !/[\s\u0000-\u001f\u007f]/.test(value) && !value.includes(key);
+}
+
+/** Pagination never changes the destination or resource carrying the key. */
+function nextPage(value: Record<string, unknown>, current: URL, initial: URL): URL | null {
+  if (value.has_more === true) {
+    if (typeof value.last_id !== "string" || !value.last_id || value.last_id.length > 512) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(current);
+    next.searchParams.set("after_id", value.last_id);
+    return next;
+  }
+  if (typeof value.nextToken === "string" && value.nextToken) {
+    if (value.nextToken.length > 4096) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(current);
+    next.searchParams.set("nextToken", value.nextToken);
+    return next;
+  }
+  const links = object(value.links);
+  if (links?.next !== undefined && links.next !== null) {
+    if (typeof links.next !== "string" || links.next.length > 4096) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(links.next, initial);
+    if (next.origin !== initial.origin || next.pathname !== initial.pathname || next.username || next.password || next.hash) throw new ConnectionFailure("wrong-protocol");
+    return next;
+  }
+  return null;
+}
+
+/** Discover without writing a capture. A denied listing is a non-fatal UI
+ * outcome: the owner can enter model IDs and test them directly. */
+export async function discoverCustomConnection(frame: EngineConnectCustomDiscoverFrame, options: CustomConnectionCaptureOptions = {}): Promise<CustomConnectionDiscoverResult> {
+  const signal = deadline(options);
+  try {
+    const parsedFrame = parseEngineConnectCustomDiscoverFrame(frame);
+    if (!parsedFrame || parsedFrame.settings.internal === true) throw new ConnectionFailure("unsupported");
+    const settings = validated(parsedFrame.settings, parsedFrame.enabled, (options.now ?? Date.now)());
+    if (settings.providerType === "bedrock" && settings.engine === "codex" && settings.transport === "runtime") return { ok: false, reason: "unsupported" };
+    const models = new Set<string>();
+    const streamingFoundationIds = new Set<string>();
+    let bytes = 0;
+    let pages = 0;
+    const bedrockClaude = settings.providerType === "bedrock" && settings.engine === "claude";
+    const roots = bedrockClaude
+      ? [`https://bedrock.${settings.region}.amazonaws.com/foundation-models`, `https://bedrock.${settings.region}.amazonaws.com/inference-profiles`]
+      : [settings.providerType === "bedrock" ? `https://bedrock-mantle.${settings.region}.api.aws/v1/models` : `${settings.baseUrl}${settings.engine === "claude" ? "/v1" : ""}/models`];
+    let truncated = false;
+    discovery: for (const root of roots) {
+      const initial = new URL(root);
+      if (settings.engine === "claude" && settings.providerType !== "bedrock") initial.searchParams.set("limit", "1000");
+      let url: URL | null = initial;
+      const seen = new Set<string>();
+      while (url !== null) {
+        if (pages >= CUSTOM_CONNECTION_DISCOVERY_MAX_PAGES) { truncated = true; break discovery; }
+        if (seen.has(url.href)) throw new ConnectionFailure("wrong-protocol");
+        seen.add(url.href);
+        pages++;
+        const result = await json({ url: url.href, headers: headers(settings) }, options, signal, CUSTOM_CONNECTION_DISCOVERY_MAX_BYTES - bytes);
+        bytes += result.bytes;
+        const list = bedrockClaude ? result.value[root.endsWith("foundation-models") ? "modelSummaries" : "inferenceProfileSummaries"] : result.value.data;
+        if (!Array.isArray(list)) throw new ConnectionFailure("wrong-protocol");
+        for (const entry of list) {
+          const row = object(entry);
+          if (!row) throw new ConnectionFailure("wrong-protocol");
+          const id = bedrockClaude ? row.modelId ?? row.inferenceProfileId : row.id;
+          if (!modelId(id, settings.apiKey)) throw new ConnectionFailure("invalid-models");
+          if (bedrockClaude) {
+            if (root.endsWith("foundation-models")) {
+              if (row.providerName !== "Anthropic" || row.responseStreamingSupported !== true) continue;
+              streamingFoundationIds.add(id);
+            } else {
+              if (!Array.isArray(row.models) || !row.models.length || !row.models.every(value => {
+                const arn = object(value)?.modelArn;
+                return typeof arn === "string" && streamingFoundationIds.has(arn.slice(arn.lastIndexOf("/") + 1));
+              })) continue;
+              if (row.status !== undefined && row.status !== "ACTIVE") continue;
+            }
+          } else if (settings.providerType === "bedrock") {
+            // Mantle lists several incompatible route families. Names alone
+            // are not proof that a model serves the /openai/v1 transport.
+            const paths = row.supported_api_paths ?? row.supportedApiPaths;
+            if (row.api_path !== "/openai/v1" && row.apiPath !== "/openai/v1" && !(Array.isArray(paths) && paths.includes("/openai/v1"))) continue;
+          }
+          if (!models.has(id) && models.size >= CUSTOM_CONNECTION_DISCOVERY_MAX_MODELS) {
+            truncated = true;
+            break discovery;
+          }
+          models.add(id);
+        }
+        url = nextPage(result.value, url, initial);
+      }
+    }
+    if (settings.providerType === "bedrock" && settings.transport === "mantle" && models.size === 0) return { ok: false, reason: "unsupported" };
+    return { ok: true, models: [...models], ...(truncated ? { truncated: true } : {}) };
+  } catch (error) {
+    return { ok: false, reason: failure(error, signal).reason };
+  }
+}
+
+function validMessages(value: unknown): boolean {
+  const message = object(value);
+  const usage = object(message?.usage);
+  return Boolean(message && message.type === "message" && message.role === "assistant" && typeof message.id === "string" && message.id.length > 0 && typeof message.model === "string" && Array.isArray(message.content) && usage && [usage.input_tokens, usage.output_tokens].every(n => Number.isSafeInteger(n) && (n as number) >= 0));
+}
+
+/** Responses terminals are protocol outcomes, not merely successful HTTP. */
+export function validateResponsesProbe(raw: Buffer): void {
+  let text: string;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(raw).replace(/\r\n/g, "\n"); } catch { throw new ConnectionFailure("wrong-protocol"); }
+  const chunks = text.split("\n\n");
+  const tail = chunks.pop();
+  if (tail?.trim()) throw new ConnectionFailure("wrong-protocol");
+  let terminal = false;
+  for (const chunk of chunks) {
+    let event: string | undefined;
+    const data: string[] = [];
+    for (const line of chunk.split("\n")) {
+      if (line.startsWith(":")) continue;
+      if (line.startsWith("event:")) event = line.slice(6).trim();
+      else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+      else if (line && !line.startsWith("id:") && !line.startsWith("retry:")) throw new ConnectionFailure("wrong-protocol");
+    }
+    if (!data.length) continue;
+    if (data.join("\n") === "[DONE]") {
+      if (!terminal) throw new ConnectionFailure("wrong-protocol");
+      continue;
+    }
+    if (terminal) throw new ConnectionFailure("wrong-protocol");
+    const value = object(decodeJson(Buffer.from(data.join("\n"))));
+    if (!value || typeof value.type !== "string" || (event !== undefined && event !== value.type)) throw new ConnectionFailure("wrong-protocol");
+    if (value.type === "error" || value.type === "response.failed") throw new ConnectionFailure("upstream-error");
+    if (value.type === "response.completed") {
+      if (object(value.response)?.status !== "completed") throw new ConnectionFailure("wrong-protocol");
+      terminal = true;
+    } else if (value.type === "response.incomplete") {
+      const response = object(value.response);
+      if (response?.status !== "incomplete" || object(response.incomplete_details)?.reason !== "max_output_tokens") throw new ConnectionFailure("wrong-protocol");
+      terminal = true;
+    }
+  }
+  if (!terminal) throw new ConnectionFailure("wrong-protocol");
+}
+
+/** AWS EventStream has two CRC32 checks: prelude and the complete message. */
+export function eventStreamCrc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let i = 0; i < 8; i++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function validateBedrockProbe(raw: Buffer): void {
+  let offset = 0;
+  let started = false;
+  let finishedMessage = false;
+  let stopped = false;
+  while (offset < raw.length) {
+    if (raw.length - offset < 16) throw new ConnectionFailure("wrong-protocol");
+    const length = raw.readUInt32BE(offset);
+    const headersLength = raw.readUInt32BE(offset + 4);
+    if (length < 16 || length > PROBE_MAX_BYTES || headersLength > length - 16 || offset + length > raw.length || raw.readUInt32BE(offset + 8) !== eventStreamCrc32(raw.subarray(offset, offset + 8)) || raw.readUInt32BE(offset + length - 4) !== eventStreamCrc32(raw.subarray(offset, offset + length - 4))) throw new ConnectionFailure("wrong-protocol");
+    const headerEnd = offset + 12 + headersLength;
+    let cursor = offset + 12;
+    const parsedHeaders = new Map<string, string>();
+    while (cursor < headerEnd) {
+      const nameLength = raw[cursor++]!;
+      if (!nameLength || cursor + nameLength + 3 > headerEnd) throw new ConnectionFailure("wrong-protocol");
+      const name = raw.subarray(cursor, cursor + nameLength).toString("utf8");
+      cursor += nameLength;
+      if (raw[cursor++] !== 7) throw new ConnectionFailure("wrong-protocol");
+      const valueLength = raw.readUInt16BE(cursor);
+      cursor += 2;
+      if (cursor + valueLength > headerEnd || parsedHeaders.has(name)) throw new ConnectionFailure("wrong-protocol");
+      parsedHeaders.set(name, raw.subarray(cursor, cursor + valueLength).toString("utf8"));
+      cursor += valueLength;
+    }
+    if (parsedHeaders.get(":message-type") !== "event" || parsedHeaders.get(":event-type") !== "chunk") {
+      const type = parsedHeaders.get(":event-type") ?? parsedHeaders.get(":exception-type") ?? "";
+      throw new ConnectionFailure(/throttl/i.test(type) ? "rate-limited" : /timeout/i.test(type) ? "timeout" : "upstream-error");
+    }
+    const payload = object(decodeJson(raw.subarray(headerEnd, offset + length - 4)));
+    if (!payload || typeof payload.bytes !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(payload.bytes)) throw new ConnectionFailure("wrong-protocol");
+    const event = object(decodeJson(Buffer.from(payload.bytes, "base64")));
+    if (!event || typeof event.type !== "string" || stopped) throw new ConnectionFailure("wrong-protocol");
+    if (event.type === "error") throw new ConnectionFailure("upstream-error");
+    if (event.type === "message_start") {
+      if (started || !validMessages(event.message)) throw new ConnectionFailure("wrong-protocol");
+      started = true;
+    } else if (event.type === "message_stop") {
+      if (!started || !finishedMessage) throw new ConnectionFailure("wrong-protocol");
+      stopped = true;
+    } else if (event.type === "message_delta") {
+      if (!started || typeof object(event.delta)?.stop_reason !== "string" || !Number.isSafeInteger(object(event.usage)?.output_tokens)) throw new ConnectionFailure("wrong-protocol");
+      finishedMessage = true;
+    } else if (!started || !["content_block_start", "content_block_delta", "content_block_stop", "ping"].includes(event.type)) throw new ConnectionFailure("wrong-protocol");
+    offset += length;
+  }
+  if (!started || !stopped) throw new ConnectionFailure("wrong-protocol");
+}
+
+async function probe(settings: CustomConnectionMaterial, model: string, auth: CustomConnectionAuthMode, options: CustomConnectionCaptureOptions, allowFallback: boolean): Promise<CustomConnectionAuthMode> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const signal = deadline(options);
+    try {
+      const bedrock = settings.providerType === "bedrock" && settings.engine === "claude";
+      const request: SafeHttpRequest = {
+        url: bedrock ? `${settings.baseUrl}/model/${encodeURIComponent(model)}/invoke-with-response-stream` : `${settings.baseUrl}${settings.engine === "claude" ? "/v1/messages" : "/responses"}`,
+        method: "POST",
+        headers: { ...headers(settings, auth), "content-type": "application/json", accept: bedrock ? "application/vnd.amazon.eventstream" : settings.engine === "codex" ? "text/event-stream" : "application/json" },
+        body: JSON.stringify(settings.engine === "codex" ? { model, input: "Hi", store: false, stream: true, max_output_tokens: 16 } : { ...(bedrock ? { anthropic_version: "bedrock-2023-05-31" } : { model }), messages: [{ role: "user", content: "Hi" }], max_tokens: 1 }),
+      };
+      let response = await exchange(request, options, signal);
+      let usedAuth = auth;
+      if (response.status === 401 && allowFallback && settings.providerType === "custom" && settings.engine === "claude" && auth === "bearer") {
+        response.body.destroy();
+        response = await exchange({ ...request, headers: { ...headers(settings, "x-api-key"), "content-type": "application/json", accept: "application/json" } }, options, signal);
+        usedAuth = "x-api-key";
+      }
+      if (response.status !== 200) { response.body.destroy(); throw statusFailure(response.status); }
+      const raw = await body(response, PROBE_MAX_BYTES, signal);
+      if (bedrock) validateBedrockProbe(raw);
+      else if (settings.engine === "codex") validateResponsesProbe(raw);
+      else if (!validMessages(decodeJson(raw))) throw new ConnectionFailure("wrong-protocol");
+      return usedAuth;
+    } catch (error) {
+      const refused = failure(error, signal);
+      if (attempt === 0 && refused.retryable && !options.signal?.aborted) continue;
+      throw refused;
+    }
+  }
+  throw new ConnectionFailure("upstream-error");
+}
+
+/** All selected models are probed before the single immutable write. */
+export async function saveCustomConnection(frame: EngineConnectCustomSaveFrame, store: CredentialStore | null, options: CustomConnectionCaptureOptions = {}): Promise<CustomConnectionSaveResult> {
+  try {
+    if (!parseCustomConnectionMaterial(frame?.settings) || frame.settings.internal === true) throw new ConnectionFailure("unsupported");
+    const parsed = parseEngineConnectCustomSaveFrame(frame);
+    if (!parsed || !validConnectionModels(parsed.models, parsed.defaultModel, parsed.backgroundModel, parsed.settings.engine, parsed.settings.apiKey)) throw new ConnectionFailure("invalid-models");
+    const settings = validated(parsed.settings, parsed.enabled, (options.now ?? Date.now)());
+    const flow = parseCaptureFlow(parsed.flow);
+    if (!flow || !store?.putImmutable) throw new ConnectionFailure("unsupported");
+    // Refuse an envelope that will never fit before spending any inference
+    // tokens. The successful auth mode is checked again before persistence.
+    try { buildEngineCapture(flow, { authKind: "custom-connection", connection: settings }); } catch { throw new ConnectionFailure("unsupported"); }
+    const authMode = await probe(settings, parsed.defaultModel, "bearer", options, true);
+    if (parsed.backgroundModel && parsed.backgroundModel !== parsed.defaultModel) await probe(settings, parsed.backgroundModel, authMode, options, false);
+    const connection = { ...settings, authMode };
+    const budget = connection.providerType === "openrouter" ? await readOpenRouterBudget(connection.apiKey, options) : undefined;
+    validated(connection, parsed.enabled, (options.now ?? Date.now)());
+    let built;
+    try { built = buildEngineCapture(flow, { authKind: "custom-connection", connection }); } catch { throw new ConnectionFailure("unsupported"); }
+    if ("error" in built) throw new ConnectionFailure("unsupported");
+    const capture = await writeCapture(store, flow, built, { signal: options.signal });
+    return { ok: true, capture, authMode, ...(budget ? { budget } : {}) };
+  } catch (error) {
+    return { ok: false, reason: failure(error, options.signal).reason };
+  }
+}
+
+/** Internal saves deliberately have no transport or resolver path. The person
+ * selects Claude's header; the fenced write records exactly that choice. */
+export async function saveCustomConnectionManual(frame: EngineConnectCustomManualSaveFrame, store: CredentialStore | null, options: Pick<CustomConnectionCaptureOptions, "signal" | "now"> = {}): Promise<CustomConnectionSaveResult> {
+  try {
+    const parsed = parseEngineConnectCustomManualSaveFrame(frame);
+    if (!parsed) throw new ConnectionFailure("unsupported");
+    if (!validConnectionModels(parsed.models, parsed.defaultModel, parsed.backgroundModel, parsed.settings.engine, parsed.settings.apiKey)) throw new ConnectionFailure("invalid-models");
+    const connection = validated(parsed.settings, parsed.enabled, (options.now ?? Date.now)());
+    const flow = parseCaptureFlow(parsed.flow);
+    if (!flow || !store?.putImmutable) throw new ConnectionFailure("unsupported");
+    const built = buildEngineCapture(flow, { authKind: "custom-connection", connection });
+    if ("error" in built) throw new ConnectionFailure("unsupported");
+    const capture = await writeCapture(store, flow, built, { signal: options.signal });
+    return { ok: true, capture, authMode: connection.authMode };
+  } catch (error) { return { ok: false, reason: failure(error, options.signal).reason }; }
+}