@vellumai/assistant 0.4.22 → 0.4.25

package/src/tools/network/script-proxy/logging.ts

@@ -1,196 +1,12 @@
-/**
- * Safe diagnostic logging helpers for the proxy subsystem.
- *
- * All sanitizers and trace builders are designed to NEVER include secret
- * values by construction — sanitizers redact sensitive header/query values,
- * and trace builders only reference host patterns, decision kinds, and
- * candidate counts.
- */
-
-const REDACTED = '[REDACTED]';
-
-/**
- * Replace values of sensitive header keys with a redaction placeholder.
- *
- * Matching is case-insensitive — "Authorization" and "authorization"
- * are both caught. The caller supplies the set of sensitive key names
- * (lowercased) because different credential templates inject into
- * different headers.
- */
-export function sanitizeHeaders(
-  headers: Record<string, string>,
-  sensitiveKeys: string[],
-): Record<string, string> {
-  const lower = new Set(sensitiveKeys.map((k) => k.toLowerCase()));
-  const out: Record<string, string> = {};
-
-  for (const [key, value] of Object.entries(headers)) {
-    out[key] = lower.has(key.toLowerCase()) ? REDACTED : value;
-  }
-
-  return out;
-}
-
-/**
- * Redact query-parameter values for sensitive param names.
- *
- * Returns a URL string where the values of `sensitiveParams` are
- * replaced with the redaction placeholder. Non-sensitive params and
- * the rest of the URL are preserved verbatim.
- */
-export function sanitizeUrl(
-  url: string,
-  sensitiveParams: string[],
-): string {
-  if (sensitiveParams.length === 0) return url;
-
-  // Guard against malformed input — return the URL unchanged if it
-  // doesn't contain a query string at all.
-  const qIdx = url.indexOf('?');
-  if (qIdx === -1) return url;
-
-  try {
-    // Build a full URL if given an absolute path, otherwise parse as-is
-    const parseable = url.startsWith('/') ? `http://placeholder${url}` : url;
-    const parsed = new URL(parseable);
-    const lower = new Set(sensitiveParams.map((p) => p.toLowerCase()));
-
-    for (const key of Array.from(parsed.searchParams.keys())) {
-      if (lower.has(key.toLowerCase())) {
-        parsed.searchParams.set(key, REDACTED);
-      }
-    }
-
-    // Reconstruct the original shape: if the input was a path we strip
-    // the placeholder origin so the caller gets back a relative path.
-    if (url.startsWith('/')) {
-      return parsed.pathname + parsed.search;
-    }
-    return parsed.toString();
-  } catch {
-    // Fail closed: if we can't parse the URL, strip the query string
-    // entirely rather than risk leaking secrets in log output.
-    return url.slice(0, qIdx);
-  }
-}
-
-/**
- * Build a log-safe snapshot of an outbound proxy request.
- *
- * `sensitiveKeys` should include header names and query param names
- * that carry credential values (e.g. "Authorization", "api_key").
- */
-export function createSafeLogEntry(
-  req: { method: string; url: string; headers: Record<string, string> },
-  sensitiveKeys: string[],
-): { method: string; url: string; headers: Record<string, string> } {
-  return {
-    method: req.method,
-    url: sanitizeUrl(req.url, sensitiveKeys),
-    headers: sanitizeHeaders(req.headers, sensitiveKeys),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Policy/rewrite decision trace
-// ---------------------------------------------------------------------------
-
-import type { PolicyDecision } from './types.js';
-
-export interface ProxyDecisionTrace {
-  /** Target hostname. */
-  host: string;
-  /** Target port (null = default for scheme). */
-  port: number | null;
-  /** Request path. */
-  path: string;
-  /** Protocol scheme. */
-  scheme: 'http' | 'https';
-  /** The decision kind emitted by the policy engine. */
-  decisionKind: PolicyDecision['kind'];
-  /** Number of candidate templates that matched before disambiguation. */
-  candidateCount: number;
-  /** The host pattern of the selected template, if any. */
-  selectedPattern: string | null;
-  /** The credential ID of the selected credential, if any. */
-  selectedCredentialId: string | null;
-}
-
-/**
- * Strip the query string from a URL path so that secrets passed as
- * query parameters (API keys, tokens) are never recorded in traces.
- */
-export function stripQueryString(p: string): string {
-  const idx = p.indexOf('?');
-  return idx === -1 ? p : p.slice(0, idx);
-}
-
-/**
- * Build a structured trace record from a policy decision.
- *
- * Intentionally excludes all secret-bearing fields (header values,
- * storage keys, injected tokens) — only patterns, counts, and
- * decision metadata are included. Query parameters are stripped from
- * the path to prevent leaking secrets (API keys, tokens) into logs.
- */
-export function buildDecisionTrace(
-  host: string,
-  port: number | null,
-  path: string,
-  scheme: 'http' | 'https',
-  decision: PolicyDecision,
-): ProxyDecisionTrace {
-  let candidateCount = 0;
-  let selectedPattern: string | null = null;
-  let selectedCredentialId: string | null = null;
-
-  switch (decision.kind) {
-    case 'matched':
-      candidateCount = 1;
-      selectedPattern = decision.template.hostPattern;
-      selectedCredentialId = decision.credentialId;
-      break;
-    case 'ambiguous':
-      candidateCount = decision.candidates.length;
-      break;
-    case 'ask_missing_credential':
-      candidateCount = decision.matchingPatterns.length;
-      break;
-    // 'missing', 'unauthenticated', 'ask_unauthenticated' — no candidates
-  }
-
-  return {
-    host,
-    port,
-    path: stripQueryString(path),
-    scheme,
-    decisionKind: decision.kind,
-    candidateCount,
-    selectedPattern,
-    selectedCredentialId,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Credential ref resolution trace
-// ---------------------------------------------------------------------------
-
-export interface CredentialRefTrace {
-  /** The raw refs provided by the caller. */
-  rawRefs: string[];
-  /** The resolved canonical UUIDs. */
-  resolvedIds: string[];
-  /** Any refs that could not be resolved. */
-  unresolvedRefs: string[];
-}
-
-/**
- * Build a credential ref resolution trace for diagnostic logging.
- */
-export function buildCredentialRefTrace(
-  rawRefs: string[],
-  resolvedIds: string[],
-  unresolvedRefs: string[],
-): CredentialRefTrace {
-  return { rawRefs, resolvedIds, unresolvedRefs };
-}
+export type {
+  CredentialRefTrace,
+  ProxyDecisionTrace,
+} from "@vellumai/proxy-sidecar";
+export {
+  buildCredentialRefTrace,
+  buildDecisionTrace,
+  createSafeLogEntry,
+  sanitizeHeaders,
+  sanitizeUrl,
+  stripQueryString,
+} from "@vellumai/proxy-sidecar";

package/src/tools/network/script-proxy/mitm-handler.ts

@@ -1,270 +1,2 @@
-/**
- * MITM handler — intercepts HTTPS CONNECT requests by terminating TLS
- * with a dynamically-issued leaf certificate, allowing the proxy to
- * read and rewrite the decrypted HTTP request before forwarding it
- * upstream over a fresh TLS connection.
- *
- * Uses a loopback TLS server on an ephemeral port with manual data
- * forwarding because Bun does not support in-process TLS termination
- * via `new TLSSocket(socket, { isServer })` or `tlsServer.emit('connection')`.
- * Additionally, pipe() has timing issues in Bun for this use case,
- * so we use explicit data event forwarding instead.
- */
-
-import { connect as netConnect, type Socket } from 'node:net';
-import {
-  connect as tlsConnect,
-  type ConnectionOptions,
-  createServer as createTlsServer,
-  type TLSSocket,
-} from 'node:tls';
-
-import { issueLeafCert } from './certs.js';
-
-/**
- * Hop-by-hop headers stripped during forwarding.
- * transfer-encoding is intentionally preserved: we forward body bytes raw,
- * so stripping it would cause upstream to misparse chunked bodies.
- */
-const HOP_BY_HOP = new Set([
-  'connection',
-  'keep-alive',
-  'proxy-authenticate',
-  'proxy-authorization',
-  'proxy-connection',
-  'te',
-  'trailer',
-  'upgrade',
-]);
-
-/**
- * Callback that receives the parsed request and returns headers to merge.
- * Return null to reject the request with 403.
- */
-export type RewriteCallback = (req: {
-  method: string;
-  path: string;
-  headers: Record<string, string>;
-  hostname: string;
-  port: number;
-}) => Promise<Record<string, string> | null>;
-
-interface ParsedRequest {
-  method: string;
-  path: string;
-  httpVersion: string;
-  headers: Record<string, string>;
-  bodyPrefix: Buffer;
-}
-
-function parseHttpRequest(buf: Buffer): ParsedRequest | null {
-  const headerEnd = buf.indexOf('\r\n\r\n');
-  if (headerEnd === -1) return null;
-
-  const headerBlock = buf.subarray(0, headerEnd).toString('utf-8');
-  const lines = headerBlock.split('\r\n');
-  const [method, path, httpVersion] = lines[0].split(' ', 3);
-
-  const headers: Record<string, string> = {};
-  for (let i = 1; i < lines.length; i++) {
-    const colonIdx = lines[i].indexOf(':');
-    if (colonIdx === -1) continue;
-    const key = lines[i].slice(0, colonIdx).trim().toLowerCase();
-    const value = lines[i].slice(colonIdx + 1).trim();
-    headers[key] = value;
-  }
-
-  return { method, path, httpVersion, headers, bodyPrefix: buf.subarray(headerEnd + 4) };
-}
-
-function serializeRequestHead(
-  method: string,
-  path: string,
-  httpVersion: string,
-  headers: Record<string, string>,
-): Buffer {
-  let head = `${method} ${path} ${httpVersion}\r\n`;
-  for (const [key, value] of Object.entries(headers)) {
-    head += `${key}: ${value}\r\n`;
-  }
-  head += '\r\n';
-  return Buffer.from(head);
-}
-
-function filterHeaders(raw: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [key, value] of Object.entries(raw)) {
-    if (!HOP_BY_HOP.has(key.toLowerCase())) {
-      out[key] = value;
-    }
-  }
-  // Prevent request-smuggling: when Transfer-Encoding is present,
-  // Content-Length creates ambiguous framing. Drop it per RFC 7230 §3.3.3.
-  if (out['transfer-encoding']) {
-    delete out['content-length'];
-  }
-  return out;
-}
-
-/**
- * Handle a CONNECT request via MITM TLS interception.
- */
-export async function handleMitm(
-  clientSocket: Socket,
-  head: Buffer,
-  hostname: string,
-  port: number,
-  caDir: string,
-  rewriteCallback: RewriteCallback,
-  upstreamTlsOptions?: Pick<ConnectionOptions, 'ca' | 'rejectUnauthorized'>,
-): Promise<void> {
-  const { cert, key } = await issueLeafCert(caDir, hostname);
-
-  clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
-
-  const tlsServer = createTlsServer({ cert, key }, (tlsSocket: TLSSocket) => {
-    tlsServer.close();
-    handleDecryptedConnection(tlsSocket, hostname, port, rewriteCallback, upstreamTlsOptions);
-  });
-
-  await new Promise<void>((resolve, reject) => {
-    tlsServer.listen(0, '127.0.0.1', () => resolve());
-    tlsServer.on('error', reject);
-  });
-
-  const addr = tlsServer.address();
-  if (!addr || typeof addr === 'string') {
-    clientSocket.destroy();
-    tlsServer.close();
-    return;
-  }
-
-  const bridge = netConnect(addr.port, '127.0.0.1', () => {
-    if (head.length > 0) {
-      bridge.write(head);
-    }
-  });
-
-  // Manual bidirectional forwarding — pipe() has timing issues in Bun
-  clientSocket.on('data', (chunk) => bridge.write(chunk));
-  bridge.on('data', (chunk) => clientSocket.write(chunk));
-
-  bridge.on('end', () => clientSocket.end());
-  clientSocket.on('end', () => bridge.end());
-
-  bridge.on('error', () => { clientSocket.destroy(); tlsServer.close(); });
-  clientSocket.on('error', () => {
-    bridge.destroy();
-    tlsServer.close();
-  });
-}
-
-function handleDecryptedConnection(
-  tlsSocket: TLSSocket,
-  hostname: string,
-  port: number,
-  rewriteCallback: RewriteCallback,
-  upstreamTlsOptions?: Pick<ConnectionOptions, 'ca' | 'rejectUnauthorized'>,
-): void {
-  const chunks: Buffer[] = [];
-
-  const onData = (chunk: Buffer) => {
-    chunks.push(chunk);
-    const combined = Buffer.concat(chunks);
-    const parsed = parseHttpRequest(combined);
-    if (!parsed) return;
-
-    tlsSocket.removeListener('data', onData);
-    tlsSocket.pause();
-    processRequest(tlsSocket, parsed, hostname, port, rewriteCallback, upstreamTlsOptions);
-  };
-
-  tlsSocket.on('data', onData);
-  tlsSocket.on('error', () => tlsSocket.destroy());
-}
-
-async function processRequest(
-  tlsSocket: TLSSocket,
-  parsed: ParsedRequest,
-  hostname: string,
-  port: number,
-  rewriteCallback: RewriteCallback,
-  upstreamTlsOptions?: Pick<ConnectionOptions, 'ca' | 'rejectUnauthorized'>,
-): Promise<void> {
-  try {
-    const filteredHeaders = filterHeaders(parsed.headers);
-    const rewriteResult = await rewriteCallback({
-      method: parsed.method,
-      path: parsed.path,
-      headers: { ...filteredHeaders },
-      hostname,
-      port,
-    });
-
-    if (rewriteResult == null) {
-      const body = 'Forbidden';
-      tlsSocket.write(
-        `HTTP/1.1 403 Forbidden\r\nContent-Length: ${body.length}\r\nContent-Type: text/plain\r\n\r\n${body}`,
-      );
-      tlsSocket.end();
-      return;
-    }
-
-    const finalHeaders = { ...filteredHeaders, ...rewriteResult };
-    if (!finalHeaders['host']) {
-      finalHeaders['host'] = port === 443 ? hostname : `${hostname}:${port}`;
-    }
-    // Force close so each request gets a fresh MITM cycle with rewrite
-    finalHeaders['connection'] = 'close';
-
-    const upstream = tlsConnect(
-      {
-        host: hostname,
-        port,
-        servername: hostname,
-        ...upstreamTlsOptions,
-      },
-      () => {
-        const headBuf = serializeRequestHead(
-          parsed.method,
-          parsed.path,
-          parsed.httpVersion,
-          finalHeaders,
-        );
-        upstream.write(headBuf);
-
-        if (parsed.bodyPrefix.length > 0) {
-          upstream.write(parsed.bodyPrefix);
-        }
-
-        // Manual forwarding — no pipe()
-        tlsSocket.on('data', (chunk) => upstream.write(chunk));
-        tlsSocket.resume();
-        upstream.on('data', (chunk) => tlsSocket.write(chunk));
-
-        upstream.on('end', () => tlsSocket.end());
-        tlsSocket.on('end', () => upstream.end());
-      },
-    );
-
-    upstream.on('error', () => {
-      if (tlsSocket.writable) {
-        const body = 'Bad Gateway';
-        tlsSocket.write(
-          `HTTP/1.1 502 Bad Gateway\r\nContent-Length: ${body.length}\r\nContent-Type: text/plain\r\n\r\n${body}`,
-        );
-      }
-      tlsSocket.end();
-    });
-
-    tlsSocket.on('error', () => upstream.destroy());
-  } catch {
-    if (tlsSocket.writable) {
-      const body = 'Internal Server Error';
-      tlsSocket.write(
-        `HTTP/1.1 500 Internal Server Error\r\nContent-Length: ${body.length}\r\nContent-Type: text/plain\r\n\r\n${body}`,
-      );
-    }
-    tlsSocket.end();
-  }
-}
+export type { RewriteCallback } from "@vellumai/proxy-sidecar";
+export { handleMitm } from "@vellumai/proxy-sidecar";

package/src/tools/network/script-proxy/policy.ts

@@ -1,152 +1,4 @@
-/**
- * Proxy policy engine — matches outbound request targets to credential
- * injection templates and emits deterministic policy decisions.
- */
-
-import { compareMatchSpecificity, type HostMatchKind,matchHostPattern } from '../../credentials/host-pattern-match.js';
-import type { CredentialInjectionTemplate } from '../../credentials/policy-types.js';
-import type { PolicyDecision, RequestTargetContext } from './types.js';
-
-interface MatchCandidate {
-  credentialId: string;
-  template: CredentialInjectionTemplate;
-}
-
-/**
- * Evaluate an outbound request against credential injection templates.
- *
- * @param hostname  Target hostname (e.g. "api.fal.ai")
- * @param _path     Request path — reserved for future path-level matching
- * @param credentialIds  Credential IDs the session is authorized to use
- * @param templates  Map from credentialId → injection templates
- */
-export function evaluateRequest(
-  hostname: string,
-  _path: string,
-  credentialIds: string[],
-  templates: Map<string, CredentialInjectionTemplate[]>,
-): PolicyDecision {
-  if (credentialIds.length === 0) {
-    return { kind: 'unauthenticated' };
-  }
-
-  // For each credential, find the best matching header template by specificity.
-  // Query templates are excluded — they're handled via URL rewriting in the
-  // MITM path and can't be injected by the HTTP forwarder.
-  const perCredentialBest: MatchCandidate[] = [];
-
-  for (const id of credentialIds) {
-    const tpls = templates.get(id);
-    if (!tpls) continue;
-
-    let bestMatch: HostMatchKind = 'none';
-    let bestCandidates: CredentialInjectionTemplate[] = [];
-
-    for (const tpl of tpls) {
-      if (tpl.injectionType === 'query') continue;
-      const match = matchHostPattern(hostname, tpl.hostPattern, { includeApexForWildcard: true });
-      if (match === 'none') continue;
-
-      const cmp = compareMatchSpecificity(match, bestMatch);
-      if (cmp < 0) {
-        // Strictly more specific — replace
-        bestMatch = match;
-        bestCandidates = [tpl];
-      } else if (cmp === 0) {
-        // Same specificity — accumulate (potential intra-credential tie)
-        bestCandidates.push(tpl);
-      }
-      // cmp > 0 means less specific — skip
-    }
-
-    if (bestCandidates.length === 1) {
-      perCredentialBest.push({ credentialId: id, template: bestCandidates[0] });
-    } else if (bestCandidates.length > 1) {
-      // Same credential has multiple templates at the same specificity — ambiguous
-      return {
-        kind: 'ambiguous',
-        candidates: bestCandidates.map((tpl) => ({ credentialId: id, template: tpl })),
-      };
-    }
-  }
-
-  if (perCredentialBest.length === 0) {
-    return { kind: 'missing' };
-  }
-
-  if (perCredentialBest.length === 1) {
-    return {
-      kind: 'matched',
-      credentialId: perCredentialBest[0].credentialId,
-      template: perCredentialBest[0].template,
-    };
-  }
-
-  // Multiple credentials match — cross-credential ambiguity
-  return { kind: 'ambiguous', candidates: perCredentialBest };
-}
-
-/**
- * Evaluate an outbound request with approval-hook awareness.
- *
- * This wraps `evaluateRequest` and, when the base decision is `missing` or
- * `unauthenticated`, consults the full credential template registry to
- * determine whether an approval prompt should be surfaced:
- *
- * - `ask_missing_credential` — the target host matches at least one known
- *   template pattern in the registry, but the session has no credential
- *   bound for it.
- * - `ask_unauthenticated` — the request doesn't match any known template
- *   in the full registry and the session has no credentials.
- *
- * For `matched` and `ambiguous` decisions the result passes through unchanged.
- *
- * @param hostname       Target hostname
- * @param port           Target port (null when the default for the scheme)
- * @param path           Request path
- * @param credentialIds  Credential IDs the session is authorized to use
- * @param sessionTemplates  Templates for the session's credential IDs
- * @param allKnownTemplates All credential injection templates across every
- *                          credential in the system — used to detect whether
- *                          the target host is "known" even if the session
- *                          doesn't have the right credential bound.
- */
-export function evaluateRequestWithApproval(
-  hostname: string,
-  port: number | null,
-  path: string,
-  credentialIds: string[],
-  sessionTemplates: Map<string, CredentialInjectionTemplate[]>,
-  allKnownTemplates: CredentialInjectionTemplate[],
-  scheme: 'http' | 'https' = 'https',
-): PolicyDecision {
-  const base = evaluateRequest(hostname, path, credentialIds, sessionTemplates);
-
-  if (base.kind !== 'missing' && base.kind !== 'unauthenticated') {
-    return base;
-  }
-
-  const target: RequestTargetContext = { hostname, port, path, scheme };
-
-  // Check whether any non-query template in the full registry covers this
-  // host. Query templates are excluded for consistency with evaluateRequest
-  // — they're handled via URL rewriting in the MITM path and shouldn't
-  // cause a false ask_missing_credential on the HTTP forwarder path.
-  const matchingPatterns: string[] = [];
-  for (const tpl of allKnownTemplates) {
-    if (tpl.injectionType === 'query') continue;
-    if (matchHostPattern(hostname, tpl.hostPattern, { includeApexForWildcard: true }) !== 'none') {
-      matchingPatterns.push(tpl.hostPattern);
-    }
-  }
-  // Deduplicate — multiple credentials may share the same host pattern.
-  const uniquePatterns = [...new Set(matchingPatterns)];
-
-  if (uniquePatterns.length > 0) {
-    // A known host pattern exists but no credential is bound to this session.
-    return { kind: 'ask_missing_credential', target, matchingPatterns: uniquePatterns };
-  }
-
-  // Completely unknown host — prompt for unauthenticated access.
-  return { kind: 'ask_unauthenticated', target };
-}
+export {
+  evaluateRequest,
+  evaluateRequestWithApproval,
+} from "@vellumai/proxy-sidecar";

package/src/tools/network/script-proxy/router.ts

@@ -1,60 +1,2 @@
-/**
- * Hybrid proxy router — decides per-CONNECT request whether to MITM-intercept
- * (for credential injection) or use a plain CONNECT tunnel (no rewrite needed).
- *
- * The router checks whether any credential injection template matches the
- * target hostname. Only when a credential rewrite is required does the proxy
- * pay the cost of TLS termination, cert issuance, and request rewriting.
- */
-
-import { matchHostPattern } from '../../credentials/host-pattern-match.js';
-import type { CredentialInjectionTemplate } from '../../credentials/policy-types.js';
-
-// ---- Public types ----------------------------------------------------------
-
-/** Deterministic reason codes for auditing and testing. */
-export type RouteReason =
-  | 'mitm:credential_injection'
-  | 'tunnel:no_rewrite'
-  | 'tunnel:no_credentials';
-
-export interface RouteDecision {
-  action: 'mitm' | 'tunnel';
-  reason: RouteReason;
-}
-
-// ---- Router ----------------------------------------------------------------
-
-/**
- * Decide whether a CONNECT target requires MITM interception.
- *
- * @param hostname       Target hostname (e.g. "api.fal.ai")
- * @param _port          Target port — reserved for future port-level rules
- * @param credentialIds  Credential IDs the session is authorized to use
- * @param templates      Map from credentialId to injection templates
- */
-export function routeConnection(
-  hostname: string,
-  _port: number,
-  credentialIds: string[],
-  templates: ReadonlyMap<string, readonly CredentialInjectionTemplate[]>,
-): RouteDecision {
-  // No credentials configured — nothing to inject, tunnel through.
-  if (credentialIds.length === 0) {
-    return { action: 'tunnel', reason: 'tunnel:no_credentials' };
-  }
-
-  for (const id of credentialIds) {
-    const tpls = templates.get(id);
-    if (!tpls) continue;
-
-    for (const tpl of tpls) {
-      if (matchHostPattern(hostname, tpl.hostPattern, { includeApexForWildcard: true }) !== 'none') {
-        return { action: 'mitm', reason: 'mitm:credential_injection' };
-      }
-    }
-  }
-
-  // Credentials exist but none match this host — no rewrite needed.
-  return { action: 'tunnel', reason: 'tunnel:no_rewrite' };
-}
+export type { RouteDecision, RouteReason } from "@vellumai/proxy-sidecar";
+export { routeConnection } from "@vellumai/proxy-sidecar";