vellum 0.0.16 → 0.2.0

package/src/tools/memory/register.ts

@@ -0,0 +1,66 @@
+import { RiskLevel } from '../../permissions/types.js';
+import { getConfig } from '../../config/loader.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { memorySearchDefinition, memorySaveDefinition, memoryUpdateDefinition } from './definitions.js';
+import { handleMemorySearch, handleMemorySave, handleMemoryUpdate } from './handlers.js';
+
+// ── memory_search ────────────────────────────────────────────────────
+
+class MemorySearchTool implements Tool {
+  name = 'memory_search';
+  description = memorySearchDefinition.description;
+  category = 'memory';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return memorySearchDefinition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const config = getConfig();
+    return handleMemorySearch(input, config, context.memoryScopeId);
+  }
+}
+
+// ── memory_save ──────────────────────────────────────────────────────
+
+class MemorySaveTool implements Tool {
+  name = 'memory_save';
+  description = memorySaveDefinition.description;
+  category = 'memory';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return memorySaveDefinition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const config = getConfig();
+    return handleMemorySave(input, config, context.conversationId, context.requestId, context.memoryScopeId);
+  }
+}
+
+// ── memory_update ────────────────────────────────────────────────────
+
+class MemoryUpdateTool implements Tool {
+  name = 'memory_update';
+  description = memoryUpdateDefinition.description;
+  category = 'memory';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return memoryUpdateDefinition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const config = getConfig();
+    return handleMemoryUpdate(input, config, context.memoryScopeId);
+  }
+}
+
+// ── Exported tool instances ──────────────────────────────────────────
+
+export const memorySearchTool = new MemorySearchTool();
+export const memorySaveTool = new MemorySaveTool();
+export const memoryUpdateTool = new MemoryUpdateTool();

package/src/tools/network/domain-normalize.ts

@@ -0,0 +1,85 @@
+/**
+ * Registrable domain normalization utility.
+ *
+ * Wraps `tldts` to provide deterministic domain parsing used by
+ * credential domain policy enforcement.
+ */
+
+import { parse } from 'tldts';
+
+export interface DomainInfo {
+  /** Original hostname, lowercased and stripped of trailing dot. */
+  hostname: string;
+  /** Registrable domain (eTLD+1), e.g. "example.co.uk" for "foo.bar.example.co.uk". */
+  registrableDomain: string | null;
+}
+
+/**
+ * Parse and normalize a hostname or URL into its domain components.
+ *
+ * Handles:
+ * - Full URLs (extracts hostname)
+ * - Bare hostnames
+ * - Trailing dots
+ * - Mixed case
+ * - Punycode/IDN domains
+ *
+ * Returns `null` for inputs that cannot be parsed into a valid hostname
+ * (e.g. IP addresses, localhost, empty strings).
+ */
+export function normalizeDomain(input: string): DomainInfo | null {
+  if (!input || typeof input !== 'string') return null;
+
+  let hostname: string;
+
+  // If input looks like a URL, extract the hostname
+  try {
+    if (input.includes('://')) {
+      const url = new URL(input);
+      hostname = url.hostname;
+    } else {
+      hostname = input;
+    }
+  } catch {
+    hostname = input;
+  }
+
+  // Strip trailing port from bare hostnames (no scheme).
+  // Without this, "example.com:8080" is misidentified as IPv6 by isIPAddress.
+  if (!input.includes('://')) {
+    hostname = hostname.replace(/:\d+$/, '');
+  }
+
+  // Normalize: lowercase, strip trailing dot
+  hostname = hostname.toLowerCase().replace(/\.$/, '');
+
+  if (!hostname) return null;
+
+  // Reject IP addresses and localhost — they don't have registrable domains
+  if (isIPAddress(hostname) || hostname === 'localhost') {
+    return null;
+  }
+
+  // Reject malformed hostnames. Each DNS label must start and end with an
+  // alphanumeric and contain only alphanumerics/hyphens — no consecutive dots,
+  // no labels starting or ending with hyphens.
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/.test(hostname)) {
+    return null;
+  }
+
+  const result = parse(hostname);
+  const registrableDomain = result.domain || null;
+
+  return {
+    hostname,
+    registrableDomain,
+  };
+}
+
+function isIPAddress(hostname: string): boolean {
+  // IPv4
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) return true;
+  // IPv6 (bracketed or bare)
+  if (hostname.startsWith('[') || hostname.includes(':')) return true;
+  return false;
+}

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

@@ -0,0 +1,237 @@
+import { mkdir, stat, readFile, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { X509Certificate } from 'node:crypto';
+
+const CA_CERT_FILENAME = 'ca.pem';
+const CA_KEY_FILENAME = 'ca-key.pem';
+const COMBINED_CA_FILENAME = 'combined-ca-bundle.pem';
+const ISSUED_DIR = 'issued';
+
+/** Well-known system CA bundle paths by platform. */
+const SYSTEM_CA_PATHS = [
+  '/etc/ssl/cert.pem',                       // macOS
+  '/etc/ssl/certs/ca-certificates.crt',      // Debian/Ubuntu
+  '/etc/pki/tls/certs/ca-bundle.crt',        // RHEL/CentOS/Fedora
+  '/etc/ssl/ca-bundle.pem',                  // openSUSE
+];
+
+// Only allow valid hostname characters: alphanumeric, hyphens, dots, and wildcards
+const HOSTNAME_RE = /^[a-zA-Z0-9.*-]+$/;
+
+/**
+ * Ensure a self-signed CA cert+key exists in `{dataDir}/proxy-ca/`.
+ * Idempotent: skips generation if both files already exist.
+ */
+export async function ensureLocalCA(dataDir: string): Promise<void> {
+  const caDir = join(dataDir, 'proxy-ca');
+  const certPath = join(caDir, CA_CERT_FILENAME);
+  const keyPath = join(caDir, CA_KEY_FILENAME);
+
+  // Check if both files already exist
+  const [certExists, keyExists] = await Promise.all([
+    stat(certPath).then(() => true, () => false),
+    stat(keyPath).then(() => true, () => false),
+  ]);
+
+  if (certExists && keyExists) return;
+
+  await mkdir(caDir, { recursive: true });
+
+  // Generate CA key
+  const keyProc = Bun.spawn([
+    'openssl', 'genrsa', '-out', keyPath, '2048',
+  ], { stdout: 'pipe', stderr: 'pipe' });
+  const keyExit = await keyProc.exited;
+  if (keyExit !== 0) {
+    const stderr = await new Response(keyProc.stderr).text();
+    throw new Error(`Failed to generate CA key: ${stderr}`);
+  }
+
+  // Generate self-signed CA cert (valid 10 years)
+  const certProc = Bun.spawn([
+    'openssl', 'req', '-new', '-x509',
+    '-key', keyPath,
+    '-out', certPath,
+    '-days', '3650',
+    '-subj', '/CN=Vellum Local Proxy CA',
+    '-addext', 'basicConstraints=critical,CA:TRUE',
+    '-addext', 'keyUsage=critical,keyCertSign,cRLSign',
+  ], { stdout: 'pipe', stderr: 'pipe' });
+  const certExit = await certProc.exited;
+  if (certExit !== 0) {
+    const stderr = await new Response(certProc.stderr).text();
+    throw new Error(`Failed to generate CA cert: ${stderr}`);
+  }
+
+  // Set strict permissions
+  await Promise.all([
+    chmod(keyPath, 0o600),
+    chmod(certPath, 0o644),
+  ]);
+}
+
+/**
+ * Issue a leaf certificate signed by the local CA for the given hostname.
+ * Caches issued certs in `{caDir}/issued/{hostname}.pem`.
+ * Returns PEM strings for the cert and key.
+ */
+export async function issueLeafCert(
+  caDir: string,
+  hostname: string,
+): Promise<{ cert: string; key: string }> {
+  if (!HOSTNAME_RE.test(hostname)) {
+    throw new Error(`Invalid hostname: ${hostname}`);
+  }
+
+  const issuedDir = join(caDir, ISSUED_DIR);
+  const leafCertPath = join(issuedDir, `${hostname}.pem`);
+  const leafKeyPath = join(issuedDir, `${hostname}-key.pem`);
+
+  // Return cached cert if it exists and is signed by the current CA
+  const [certExists, keyExists] = await Promise.all([
+    stat(leafCertPath).then(() => true, () => false),
+    stat(leafKeyPath).then(() => true, () => false),
+  ]);
+
+  if (certExists && keyExists) {
+    const [cert, key, caCert] = await Promise.all([
+      readFile(leafCertPath, 'utf-8'),
+      readFile(leafKeyPath, 'utf-8'),
+      readFile(join(caDir, CA_CERT_FILENAME), 'utf-8'),
+    ]);
+
+    // Verify cached cert was signed by the current CA, not a previous one
+    try {
+      const leaf = new X509Certificate(cert);
+      const ca = new X509Certificate(caCert);
+      if (leaf.checkIssued(ca)) {
+        return { cert, key };
+      }
+    } catch {
+      // Cert parsing failed — fall through to re-issue
+    }
+  }
+
+  await mkdir(issuedDir, { recursive: true });
+
+  const caCertPath = join(caDir, CA_CERT_FILENAME);
+  const caKeyPath = join(caDir, CA_KEY_FILENAME);
+
+  // Generate leaf key
+  const keyProc = Bun.spawn([
+    'openssl', 'genrsa', '-out', leafKeyPath, '2048',
+  ], { stdout: 'pipe', stderr: 'pipe' });
+  const keyExit = await keyProc.exited;
+  if (keyExit !== 0) {
+    const stderr = await new Response(keyProc.stderr).text();
+    throw new Error(`Failed to generate leaf key for ${hostname}: ${stderr}`);
+  }
+
+  // Generate CSR
+  const csrPath = join(issuedDir, `${hostname}.csr`);
+  const csrProc = Bun.spawn([
+    'openssl', 'req', '-new',
+    '-key', leafKeyPath,
+    '-out', csrPath,
+    '-subj', `/CN=${hostname}`,
+  ], { stdout: 'pipe', stderr: 'pipe' });
+  const csrExit = await csrProc.exited;
+  if (csrExit !== 0) {
+    const stderr = await new Response(csrProc.stderr).text();
+    throw new Error(`Failed to generate CSR for ${hostname}: ${stderr}`);
+  }
+
+  // Write SAN extension config to a temp file
+  const extPath = join(issuedDir, `${hostname}-ext.cnf`);
+  await writeFile(extPath, `subjectAltName=DNS:${hostname}\n`);
+
+  // Sign with CA (valid 1 year)
+  const signProc = Bun.spawn([
+    'openssl', 'x509', '-req',
+    '-in', csrPath,
+    '-CA', caCertPath,
+    '-CAkey', caKeyPath,
+    '-CAcreateserial',
+    '-out', leafCertPath,
+    '-days', '365',
+    '-extfile', extPath,
+  ], { stdout: 'pipe', stderr: 'pipe' });
+  const signExit = await signProc.exited;
+  if (signExit !== 0) {
+    const stderr = await new Response(signProc.stderr).text();
+    throw new Error(`Failed to sign leaf cert for ${hostname}: ${stderr}`);
+  }
+
+  const [cert, key] = await Promise.all([
+    readFile(leafCertPath, 'utf-8'),
+    readFile(leafKeyPath, 'utf-8'),
+  ]);
+  return { cert, key };
+}
+
+/**
+ * Create a combined CA bundle that includes both system root CAs and the
+ * proxy CA cert. This is needed for non-Node clients (curl, Python, Go)
+ * that don't honor NODE_EXTRA_CA_CERTS — they use SSL_CERT_FILE instead,
+ * which replaces (rather than supplements) the default CA bundle.
+ *
+ * Idempotent: skips regeneration if the combined bundle is newer than
+ * both the system bundle and the proxy CA cert.
+ */
+export async function ensureCombinedCABundle(dataDir: string): Promise<string | null> {
+  const caDir = join(dataDir, 'proxy-ca');
+  const caCertPath = join(caDir, CA_CERT_FILENAME);
+  const combinedPath = join(caDir, COMBINED_CA_FILENAME);
+
+  // Find the system CA bundle
+  let systemBundlePath: string | null = null;
+  for (const p of SYSTEM_CA_PATHS) {
+    try {
+      await stat(p);
+      systemBundlePath = p;
+      break;
+    } catch {
+      // not found, try next
+    }
+  }
+  if (!systemBundlePath) return null;
+
+  // Check if combined bundle already exists and is newer than both sources
+  try {
+    const [combinedSt, caSt, systemSt] = await Promise.all([
+      stat(combinedPath),
+      stat(caCertPath),
+      stat(systemBundlePath),
+    ]);
+    if (combinedSt.mtimeMs > caSt.mtimeMs && combinedSt.mtimeMs > systemSt.mtimeMs) {
+      return combinedPath;
+    }
+  } catch {
+    // One or more files missing — fall through to create
+  }
+
+  try {
+    const [systemCAs, proxyCACert] = await Promise.all([
+      readFile(systemBundlePath, 'utf-8'),
+      readFile(caCertPath, 'utf-8'),
+    ]);
+    await writeFile(combinedPath, systemCAs + '\n' + proxyCACert);
+    return combinedPath;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the path to the combined CA bundle for use as SSL_CERT_FILE.
+ */
+export function getCombinedCAPath(dataDir: string): string {
+  return join(dataDir, 'proxy-ca', COMBINED_CA_FILENAME);
+}
+
+/**
+ * Return the path to the local CA cert for use as NODE_EXTRA_CA_CERTS.
+ */
+export function getCAPath(dataDir: string): string {
+  return join(dataDir, 'proxy-ca', CA_CERT_FILENAME);
+}

package/src/tools/network/script-proxy/connect-tunnel.ts

@@ -0,0 +1,82 @@
+/**
+ * CONNECT tunnel handler — establishes a raw TCP tunnel between the
+ * client and a remote host for HTTPS pass-through (no MITM).
+ */
+
+import { connect, type Socket } from 'node:net';
+import type { IncomingMessage } from 'node:http';
+
+/**
+ * Parse and validate a CONNECT target of the form `host:port`.
+ * Returns null if the target is malformed.
+ * Strips brackets from IPv6 literals (e.g. `[::1]:443` -> `::1`).
+ */
+function parseTarget(url: string | undefined): { host: string; port: number } | null {
+  if (!url) return null;
+
+  const colonIdx = url.lastIndexOf(':');
+  if (colonIdx <= 0) return null; // no port separator, or leading colon only
+
+  let host = url.slice(0, colonIdx);
+  const portStr = url.slice(colonIdx + 1);
+
+  if (!host || !portStr) return null;
+
+  const port = Number(portStr);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+
+  // Strip brackets from IPv6 literals — net.connect expects the raw address
+  if (host.startsWith('[') && host.endsWith(']')) {
+    host = host.slice(1, -1);
+    if (!host) return null;
+  }
+
+  return { host, port };
+}
+
+/**
+ * Handle an HTTP CONNECT request by establishing a bidirectional TCP
+ * tunnel to the requested target.
+ */
+export function handleConnect(
+  req: IncomingMessage,
+  clientSocket: Socket,
+  head: Buffer,
+): void {
+  const target = parseTarget(req.url);
+
+  if (!target) {
+    clientSocket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+    clientSocket.destroy();
+    return;
+  }
+
+  let tunnelEstablished = false;
+
+  const upstream = connect(target.port, target.host, () => {
+    tunnelEstablished = true;
+    clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+
+    // Forward any data already buffered by the HTTP parser
+    if (head.length > 0) {
+      upstream.write(head);
+    }
+
+    // Bidirectional piping
+    upstream.pipe(clientSocket);
+    clientSocket.pipe(upstream);
+  });
+
+  upstream.on('error', () => {
+    // Only send HTTP error if the tunnel hasn't been established yet;
+    // once established the client expects raw TLS, not HTTP framing
+    if (!tunnelEstablished && clientSocket.writable) {
+      clientSocket.write('HTTP/1.1 502 Bad Gateway\r\n\r\n');
+    }
+    clientSocket.destroy();
+  });
+
+  clientSocket.on('error', () => {
+    upstream.destroy();
+  });
+}

package/src/tools/network/script-proxy/http-forwarder.ts

@@ -0,0 +1,151 @@
+/**
+ * HTTP proxy forwarder — parses absolute-URL proxy requests and forwards
+ * them to the upstream server with full body streaming.
+ */
+
+import { request as httpRequest, type IncomingMessage, type ServerResponse } from 'node:http';
+import { URL } from 'node:url';
+
+/** Hop-by-hop headers that MUST NOT be forwarded between proxy hops. */
+const HOP_BY_HOP = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+/**
+ * Optional callback for credential injection or policy gating.
+ * Called before the upstream request is sent. Returns extra headers
+ * to merge, or null to reject the request.
+ */
+export type PolicyCallback = (
+  hostname: string,
+  port: number | null,
+  path: string,
+  scheme: 'http' | 'https',
+) => Promise<Record<string, string> | null>;
+
+/**
+ * Strip hop-by-hop headers and Connection-token headers (RFC 7230 s6.1)
+ * from an incoming header set, preserving multi-value arrays.
+ */
+function filterHeaders(raw: IncomingMessage['headers']): Record<string, string | string[]> {
+  // Collect extra headers listed in the Connection header (RFC 7230 s6.1)
+  const connectionTokens = new Set<string>();
+  const connValue = raw['connection'];
+  if (connValue) {
+    const values = Array.isArray(connValue) ? connValue : [connValue];
+    for (const v of values) {
+      for (const token of v.split(',')) {
+        connectionTokens.add(token.trim().toLowerCase());
+      }
+    }
+  }
+
+  const out: Record<string, string | string[]> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const lower = key.toLowerCase();
+    if (HOP_BY_HOP.has(lower)) continue;
+    if (connectionTokens.has(lower)) continue;
+    if (value === undefined) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Forward a plain HTTP proxy request (absolute-URL form) to the upstream
+ * server and stream the response back to the client.
+ */
+export function forwardHttpRequest(
+  clientReq: IncomingMessage,
+  clientRes: ServerResponse,
+  policyCallback?: PolicyCallback,
+): void {
+  const urlStr = clientReq.url;
+  if (!urlStr) {
+    clientRes.writeHead(400, { 'Content-Type': 'text/plain' });
+    clientRes.end('Bad Request');
+    return;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(urlStr);
+  } catch {
+    clientRes.writeHead(400, { 'Content-Type': 'text/plain' });
+    clientRes.end('Bad Request');
+    return;
+  }
+
+  if (parsed.protocol !== 'http:') {
+    clientRes.writeHead(400, { 'Content-Type': 'text/plain' });
+    clientRes.end('Only HTTP is supported for non-CONNECT proxy requests');
+    return;
+  }
+
+  const hostname = parsed.hostname;
+  const port = parsed.port ? Number(parsed.port) : 80;
+  const path = parsed.pathname + parsed.search;
+
+  const doForward = (extraHeaders: Record<string, string> = {}) => {
+    const headers = { ...filterHeaders(clientReq.headers), ...extraHeaders };
+    // Ensure Host header matches the upstream target
+    headers['host'] = parsed.host;
+
+    const upstreamReq = httpRequest(
+      {
+        hostname,
+        port,
+        path,
+        method: clientReq.method,
+        headers,
+      },
+      (upstreamRes: IncomingMessage) => {
+        const responseHeaders = filterHeaders(upstreamRes.headers);
+        clientRes.writeHead(upstreamRes.statusCode ?? 502, responseHeaders);
+        upstreamRes.on('error', () => {
+          clientRes.destroy();
+        });
+        upstreamRes.pipe(clientRes);
+      },
+    );
+
+    upstreamReq.on('error', () => {
+      // Don't leak internal error details — generic 502
+      if (!clientRes.headersSent) {
+        clientRes.writeHead(502, { 'Content-Type': 'text/plain' });
+      }
+      clientRes.end('Bad Gateway');
+    });
+
+    // Stream client body to upstream
+    clientReq.pipe(upstreamReq);
+  };
+
+  if (policyCallback) {
+    policyCallback(hostname, parsed.port ? Number(parsed.port) : null, path, 'http')
+      .then((extraHeaders) => {
+        if (extraHeaders === null) {
+          clientRes.writeHead(403, { 'Content-Type': 'text/plain' });
+          clientRes.end('Forbidden');
+          return;
+        }
+        doForward(extraHeaders);
+      })
+      .catch(() => {
+        if (!clientRes.headersSent) {
+          clientRes.writeHead(502, { 'Content-Type': 'text/plain' });
+        }
+        clientRes.end('Bad Gateway');
+      });
+  } else {
+    doForward();
+  }
+}

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

@@ -0,0 +1,28 @@
+export type {
+  ProxySessionId,
+  ProxySession,
+  ProxySessionConfig,
+  ProxySessionStatus,
+  ProxyEnvVars,
+  ProxyApprovalRequest,
+  ProxyApprovalCallback,
+} from './types.js';
+
+export {
+  createSession,
+  startSession,
+  stopSession,
+  getSessionEnv,
+  getActiveSession,
+  getOrStartSession,
+  getSessionsForConversation,
+  stopAllSessions,
+} from './session-manager.js';
+
+export {
+  ensureLocalCA,
+  ensureCombinedCABundle,
+  issueLeafCert,
+  getCAPath,
+  getCombinedCAPath,
+} from './certs.js';