create-safest-tools 0.2.0

package/template/src/connection-egress.ts

@@ -0,0 +1,430 @@
+import { canonicalJson } from "./audit";
+import { resolveOAuthAccessToken } from "./connection-oauth";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import { assertSafeConnectionDestination } from "./platform-registry-validation";
+
+interface ConnectionExecutionRow {
+  id: string;
+  connectionId: string;
+  definitionStatus: string;
+  baseUrl: string | null;
+  serviceBindingName: string | null;
+  allowedHostsJson: string;
+  allowedMethodsJson: string;
+  allowedPathPrefixesJson: string;
+  requestLimitBytes: number;
+  responseLimitBytes: number;
+  responseContentTypesJson: string;
+  timeoutMs: number;
+  concurrencyLimit: number;
+  requestsPerWindow: number;
+  windowSeconds: number;
+  credentialStrategy: string;
+  secretReference: string | null;
+  signingStrategyJson: string;
+  healthState: string | null;
+}
+
+export interface ConnectionExecutionInput {
+  connectionVersionId: string;
+  componentRunId?: string;
+  actionProposalId?: string;
+  operationId: string;
+  attemptNumber: number;
+  method: string;
+  path: string;
+  body: unknown;
+  headers?: Record<string, string>;
+  allowPaused?: boolean;
+}
+
+export interface ConnectionExecutionResult {
+  status: number;
+  data: Record<string, unknown>;
+  responseDigest: string;
+  connectionAttemptId: string;
+}
+
+export class ConnectionExecutionError extends Error {
+  constructor(
+    readonly code: string,
+    readonly retryable: boolean,
+    readonly delaySeconds = 5,
+  ) {
+    super(code);
+    this.name = "ConnectionExecutionError";
+  }
+}
+
+function parsedJson<T>(value: string, fallback: T): T {
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function secretValue(env: Env, reference: string | null): string | null {
+  if (!reference || !/^(?:CONNECTION|OAUTH|ACTION|NOTIFICATION|EMAIL|AI)_[A-Z0-9_]{2,96}$/u.test(reference)) return null;
+  const value = (env as unknown as Record<string, unknown>)[reference];
+  return typeof value === "string" && value.length >= 16 ? value : null;
+}
+
+async function hmac(secret: string, value: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const digest = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value)));
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function boundedBody(response: Response, maximum: number): Promise<Uint8Array> {
+  const contentLength = Number.parseInt(response.headers.get("content-length") ?? "", 10);
+  if (Number.isFinite(contentLength) && contentLength > maximum) throw new ConnectionExecutionError("connection_response_too_large", false);
+  if (!response.body) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maximum) {
+        await reader.cancel("response limit exceeded");
+        throw new ConnectionExecutionError("connection_response_too_large", false);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const result = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+async function recordAttempt(
+  db: D1Database,
+  input: {
+    id: string;
+    connection: ConnectionExecutionRow;
+    execution: ConnectionExecutionInput;
+    destinationOrigin: string;
+    destinationPath: string;
+    requestDigest: string;
+    responseStatus: number | null;
+    responseDigest: string | null;
+    responseClass: "success" | "retryable" | "permanent" | "timeout" | "circuit_open" | "denied" | "invalid";
+    errorCode: string | null;
+    startedAt: string;
+    finishedAt: string;
+  },
+): Promise<void> {
+  const succeeded = input.responseClass === "success";
+  const affectsHealth = ["success", "retryable", "timeout"].includes(input.responseClass);
+  await db.batch([
+    db.prepare(`
+      INSERT INTO connection_attempts (
+        id, installation_id, connection_version_id, component_run_id,
+        action_proposal_id, operation_id, attempt_number, method,
+        destination_origin, destination_path_hash, request_digest,
+        response_status, response_digest, response_class, error_code,
+        started_at, finished_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16)
+      ON CONFLICT(operation_id, attempt_number) DO NOTHING
+    `).bind(
+      input.id, input.connection.id, input.execution.componentRunId ?? null,
+      input.execution.actionProposalId ?? null, input.execution.operationId,
+      input.execution.attemptNumber, input.execution.method, input.destinationOrigin,
+      `sha256:${await sha256(input.destinationPath)}`, input.requestDigest,
+      input.responseStatus, input.responseDigest, input.responseClass,
+      input.errorCode, input.startedAt, input.finishedAt,
+    ),
+    db.prepare(`
+      UPDATE connection_health SET
+        state = CASE
+          WHEN ?6 = 0 THEN state
+          WHEN ?2 = 1 THEN 'healthy'
+          WHEN consecutive_failures + 1 >= 5 THEN 'open_circuit'
+          ELSE 'degraded'
+        END,
+        consecutive_failures = CASE WHEN ?6 = 0 THEN consecutive_failures WHEN ?2 = 1 THEN 0 ELSE consecutive_failures + 1 END,
+        opened_at = CASE WHEN ?6 = 0 THEN opened_at WHEN ?2 = 0 AND consecutive_failures + 1 >= 5 THEN COALESCE(opened_at, ?3) ELSE NULL END,
+        next_probe_at = CASE WHEN ?6 = 0 THEN next_probe_at WHEN ?2 = 0 AND consecutive_failures + 1 >= 5 THEN ?4 ELSE NULL END,
+        last_success_at = CASE WHEN ?6 = 1 AND ?2 = 1 THEN ?3 ELSE last_success_at END,
+        last_error_code = CASE WHEN ?6 = 0 THEN last_error_code WHEN ?2 = 1 THEN NULL ELSE ?5 END,
+        revision = revision + 1, updated_at = ?3
+      WHERE connection_version_id = ?1
+    `).bind(
+      input.connection.id, succeeded ? 1 : 0, input.finishedAt,
+      new Date(Date.now() + 60_000).toISOString(), input.errorCode, affectsHealth ? 1 : 0,
+    ),
+  ]);
+}
+
+async function acquireExecutionLease(
+  db: D1Database,
+  connection: ConnectionExecutionRow,
+  input: ConnectionExecutionInput,
+  startedAt: string,
+): Promise<string> {
+  const leaseId = crypto.randomUUID();
+  const expiresAt = new Date(Date.now() + connection.timeoutMs + 10_000).toISOString();
+  const windowStart = new Date(Date.now() - connection.windowSeconds * 1_000).toISOString();
+  await db.prepare(`DELETE FROM connection_execution_leases WHERE expires_at <= ?1`).bind(startedAt).run();
+  const inserted = await db.prepare(`
+    INSERT INTO connection_execution_leases (
+      id, connection_version_id, operation_id, attempt_number, expires_at, created_at
+    )
+    SELECT ?1, ?2, ?3, ?4, ?5, ?6
+    WHERE (SELECT COUNT(*) FROM connection_execution_leases
+      WHERE connection_version_id = ?2 AND expires_at > ?6) < ?7
+      AND (SELECT COUNT(*) FROM connection_attempts
+        WHERE connection_version_id = ?2 AND started_at >= ?8) < ?9
+    ON CONFLICT(operation_id, attempt_number) DO NOTHING
+  `).bind(
+    leaseId, connection.id, input.operationId, input.attemptNumber,
+    expiresAt, startedAt, connection.concurrencyLimit, windowStart,
+    connection.requestsPerWindow,
+  ).run();
+  if (inserted.meta.changes === 1) return leaseId;
+  const existing = await db.prepare(`
+    SELECT id FROM connection_execution_leases
+    WHERE operation_id = ?1 AND attempt_number = ?2 AND expires_at > ?3 LIMIT 1
+  `).bind(input.operationId, input.attemptNumber, startedAt).first<{ id: string }>();
+  if (existing) throw new ConnectionExecutionError("connection_attempt_in_progress", true, 2);
+  const active = await db.prepare(`
+    SELECT COUNT(*) AS count FROM connection_execution_leases
+    WHERE connection_version_id = ?1 AND expires_at > ?2
+  `).bind(connection.id, startedAt).first<{ count: number }>();
+  if (Number(active?.count ?? 0) >= connection.concurrencyLimit) {
+    throw new ConnectionExecutionError("connection_concurrency_exhausted", true, 5);
+  }
+  throw new ConnectionExecutionError("connection_rate_limited", true, Math.max(1, connection.windowSeconds));
+}
+
+async function loadConnection(db: D1Database, id: string, allowPaused = false): Promise<ConnectionExecutionRow> {
+  const row = await db.prepare(`
+    SELECT v.id, v.connection_id AS connectionId, d.status AS definitionStatus,
+      v.base_url AS baseUrl, v.service_binding_name AS serviceBindingName,
+      v.allowed_hosts_json AS allowedHostsJson,
+      v.allowed_methods_json AS allowedMethodsJson,
+      v.allowed_path_prefixes_json AS allowedPathPrefixesJson,
+      v.request_limit_bytes AS requestLimitBytes,
+      v.response_limit_bytes AS responseLimitBytes,
+      v.response_content_types_json AS responseContentTypesJson,
+      v.timeout_ms AS timeoutMs, v.concurrency_limit AS concurrencyLimit,
+      v.requests_per_window AS requestsPerWindow, v.window_seconds AS windowSeconds,
+      v.credential_strategy AS credentialStrategy,
+      v.secret_reference AS secretReference, v.signing_strategy_json AS signingStrategyJson,
+      h.state AS healthState
+    FROM connection_versions v JOIN connection_definitions d ON d.id = v.connection_id
+    LEFT JOIN connection_health h ON h.connection_version_id = v.id
+    WHERE v.id = ?1 AND v.retired_at IS NULL LIMIT 1
+  `).bind(id).first<ConnectionExecutionRow>();
+  if (!row || (row.definitionStatus !== "active" && !(allowPaused && row.definitionStatus === "paused"))) throw new ConnectionExecutionError("connection_unavailable", false);
+  if (row.healthState === "paused" && !allowPaused) throw new ConnectionExecutionError("connection_paused", false);
+  if (row.healthState === "open_circuit") throw new ConnectionExecutionError("connection_circuit_open", true, 60);
+  return row;
+}
+
+export async function executeConnectionJson(
+  env: Env,
+  input: ConnectionExecutionInput,
+): Promise<ConnectionExecutionResult> {
+  const connection = await loadConnection(env.DB, input.connectionVersionId, input.allowPaused === true);
+  const method = input.method.toUpperCase();
+  const allowedMethods = parsedJson<string[]>(connection.allowedMethodsJson, []);
+  if (!allowedMethods.includes(method)) throw new ConnectionExecutionError("connection_method_denied", false);
+  if (!input.path.startsWith("/") || input.path.includes("..") || input.path.includes("#")) throw new ConnectionExecutionError("connection_path_denied", false);
+  const body = canonicalJson(input.body);
+  const bodyBytes = new TextEncoder().encode(body);
+  if (bodyBytes.byteLength > connection.requestLimitBytes) throw new ConnectionExecutionError("connection_request_too_large", false);
+  const requestDigest = `sha256:${await sha256(body)}`;
+  const attemptId = crypto.randomUUID();
+  const startedAt = new Date().toISOString();
+  let destinationOrigin: string;
+  let destinationPath: string;
+  let requestUrl: string;
+  let fetcher: Pick<Fetcher, "fetch"> = globalThis;
+  if (connection.baseUrl) {
+    const url = new URL(`${connection.baseUrl.replace(/\/$/u, "")}/${input.path.replace(/^\//u, "")}`);
+    try {
+      assertSafeConnectionDestination(
+        url,
+        parsedJson(connection.allowedHostsJson, []),
+        parsedJson(connection.allowedPathPrefixesJson, []),
+      );
+    } catch {
+      throw new ConnectionExecutionError("connection_destination_denied", false);
+    }
+    destinationOrigin = url.origin;
+    destinationPath = url.pathname;
+    requestUrl = url.href;
+  } else if (connection.serviceBindingName) {
+    if (!/^[A-Z][A-Z0-9_]{1,99}$/u.test(connection.serviceBindingName)) throw new ConnectionExecutionError("connection_service_binding_invalid", false);
+    const candidate = (env as unknown as Record<string, unknown>)[connection.serviceBindingName];
+    if (!candidate || typeof candidate !== "object" || !("fetch" in candidate) || typeof candidate.fetch !== "function") throw new ConnectionExecutionError("connection_service_binding_missing", false);
+    fetcher = candidate as Pick<Fetcher, "fetch">;
+    destinationOrigin = `service://${connection.serviceBindingName}`;
+    destinationPath = input.path;
+    requestUrl = `https://service.invalid${input.path}`;
+  } else {
+    throw new ConnectionExecutionError("connection_destination_missing", false);
+  }
+  const headers = new Headers({ "content-type": "application/json", "accept": "application/json" });
+  for (const [name, value] of Object.entries(input.headers ?? {})) {
+    const lower = name.toLowerCase();
+    if (!["accept", "content-type", "x-safest-purpose"].includes(lower) || /[\r\n]/u.test(value)) throw new ConnectionExecutionError("connection_header_denied", false);
+    headers.set(name, value);
+  }
+  const secret = secretValue(env, connection.secretReference);
+  const timestamp = new Date().toISOString();
+  const nonce = crypto.randomUUID();
+  if (connection.credentialStrategy === "bearer") {
+    if (!secret) throw new ConnectionExecutionError("connection_auth_required", false);
+    headers.set("authorization", `Bearer ${secret}`);
+  } else if (connection.credentialStrategy === "static_header") {
+    if (!secret) throw new ConnectionExecutionError("connection_auth_required", false);
+    const strategy = parsedJson<Record<string, unknown>>(connection.signingStrategyJson, {});
+    const headerName = typeof strategy.header_name === "string" ? strategy.header_name : "x-api-key";
+    if (!/^[A-Za-z][A-Za-z0-9-]{0,63}$/u.test(headerName)) throw new ConnectionExecutionError("connection_auth_configuration_invalid", false);
+    headers.set(headerName, secret);
+  } else if (connection.credentialStrategy === "hmac") {
+    if (!secret) throw new ConnectionExecutionError("connection_auth_required", false);
+    headers.set("safest-timestamp", timestamp);
+    headers.set("safest-nonce", nonce);
+    headers.set("safest-operation-id", input.operationId);
+    headers.set("safest-signature", await hmac(secret, `${method}\n${destinationPath}\n${timestamp}\n${nonce}\n${requestDigest}`));
+  } else if (connection.credentialStrategy === "oauth2_authorization_code") {
+    try {
+      const credential = await resolveOAuthAccessToken(env, connection.id);
+      headers.set("authorization", `${credential.tokenType} ${credential.token}`);
+    } catch (error) {
+      if (error instanceof ApiError) {
+        const retryable = ["oauth_provider_unavailable", "oauth_token_exchange_failed"].includes(error.code);
+        throw new ConnectionExecutionError(error.code, retryable, retryable ? 30 : 5);
+      }
+      throw error;
+    }
+  } else if (["oauth2_client_credentials", "mutual_tls"].includes(connection.credentialStrategy)) {
+    throw new ConnectionExecutionError("connection_auth_required", false);
+  }
+  let leaseId: string;
+  try {
+    leaseId = await acquireExecutionLease(env.DB, connection, input, startedAt);
+  } catch (error) {
+    if (error instanceof ConnectionExecutionError) {
+      await recordAttempt(env.DB, {
+        id: attemptId,
+        connection,
+        execution: input,
+        destinationOrigin,
+        destinationPath,
+        requestDigest,
+        responseStatus: null,
+        responseDigest: null,
+        responseClass: "denied",
+        errorCode: error.code,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+      });
+    }
+    throw error;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort("connection timeout"), connection.timeoutMs);
+  let attemptRecorded = false;
+  try {
+    const response = await fetcher.fetch(requestUrl, {
+      method,
+      headers,
+      body: ["GET", "HEAD"].includes(method) ? undefined : body,
+      redirect: "manual",
+      signal: controller.signal,
+    });
+    if (response.status >= 300 && response.status < 400) throw new ConnectionExecutionError("connection_redirect_denied", false);
+    const contentType = (response.headers.get("content-type") ?? "").split(";", 1)[0]!.trim().toLowerCase();
+    const allowedContentTypes = parsedJson<string[]>(connection.responseContentTypesJson, []);
+    if (!allowedContentTypes.includes(contentType)) throw new ConnectionExecutionError("connection_content_type_invalid", false);
+    const bytes = await boundedBody(response, connection.responseLimitBytes);
+    const responseText = new TextDecoder().decode(bytes);
+    const responseDigest = `sha256:${await sha256(responseText)}`;
+    let data: unknown;
+    try {
+      data = responseText ? JSON.parse(responseText) : {};
+    } catch {
+      throw new ConnectionExecutionError("connection_json_invalid", false);
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data)) throw new ConnectionExecutionError("connection_json_invalid", false);
+    const responseClass = response.ok ? "success" : [408, 425, 429].includes(response.status) || response.status >= 500 ? "retryable" : "permanent";
+    const finishedAt = new Date().toISOString();
+    await recordAttempt(env.DB, {
+      id: attemptId,
+      connection,
+      execution: input,
+      destinationOrigin,
+      destinationPath,
+      requestDigest,
+      responseStatus: response.status,
+      responseDigest,
+      responseClass,
+      errorCode: response.ok ? null : `http_${response.status}`,
+      startedAt,
+      finishedAt,
+    });
+    attemptRecorded = true;
+    if (!response.ok) throw new ConnectionExecutionError(`connection_http_${response.status}`, responseClass === "retryable", response.status === 429 ? 30 : 5);
+    return { status: response.status, data: data as Record<string, unknown>, responseDigest, connectionAttemptId: attemptId };
+  } catch (error) {
+    if (error instanceof ConnectionExecutionError) {
+      if (!attemptRecorded) {
+        await recordAttempt(env.DB, {
+          id: attemptId,
+          connection,
+          execution: input,
+          destinationOrigin,
+          destinationPath,
+          requestDigest,
+          responseStatus: null,
+          responseDigest: null,
+          responseClass: error.code === "connection_circuit_open" ? "circuit_open" : error.retryable ? "retryable" : "invalid",
+          errorCode: error.code,
+          startedAt,
+          finishedAt: new Date().toISOString(),
+        });
+      }
+      throw error;
+    }
+    const timedOut = controller.signal.aborted;
+    const code = timedOut ? "connection_timeout" : "connection_transport_error";
+    await recordAttempt(env.DB, {
+      id: attemptId,
+      connection,
+      execution: input,
+      destinationOrigin,
+      destinationPath,
+      requestDigest,
+      responseStatus: null,
+      responseDigest: null,
+      responseClass: timedOut ? "timeout" : "retryable",
+      errorCode: code,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+    });
+    throw new ConnectionExecutionError(code, true, 5);
+  } finally {
+    clearTimeout(timeout);
+    await env.DB.prepare(`DELETE FROM connection_execution_leases WHERE id = ?1`).bind(leaseId).run();
+  }
+}