@vellumai/credential-executor 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/audit/store.ts

@@ -1,188 +0,0 @@
-/**
- * CES audit record persistence.
- *
- * Persists token-free audit record summaries to `audit.jsonl` inside
- * the CES-private data root. Each line is a self-contained JSON object
- * conforming to the `AuditRecordSummary` schema from `@vellumai/service-contracts`.
- *
- * Design principles:
- * - **Append-only**: Records are appended one per line. The file is never
- *   rewritten or truncated during normal operation.
- * - **Token-free**: Audit records must never contain raw secrets, auth
- *   tokens, raw headers, or raw response bodies. Only sanitized summaries
- *   (method, URL template, status code, credential handle, grant ID) are
- *   persisted.
- * - **Fail-open for reads**: If the file is corrupt or missing, reads
- *   return an empty array rather than throwing. Writes still throw on I/O
- *   failure so callers know when persistence is broken.
- * - **Bounded reads**: The `list` method supports limit and cursor-based
- *   pagination to avoid reading the entire log into memory.
- */
-
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-
-import type { AuditRecordSummary } from "@vellumai/service-contracts/credential-rpc";
-
-import { getCesAuditDir } from "../paths.js";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const AUDIT_FILENAME = "audit.jsonl";
-
-// ---------------------------------------------------------------------------
-// Store implementation
-// ---------------------------------------------------------------------------
-
-export class AuditStore {
-  private readonly filePath: string;
-
-  constructor(auditDir?: string) {
-    const dir = auditDir ?? getCesAuditDir();
-    this.filePath = join(dir, AUDIT_FILENAME);
-  }
-
-  // -----------------------------------------------------------------------
-  // Public API
-  // -----------------------------------------------------------------------
-
-  /**
-   * Ensure the parent directory exists. Safe to call multiple times.
-   */
-  init(): void {
-    const dir = dirname(this.filePath);
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-    }
-  }
-
-  /**
-   * Append a token-free audit record summary to the log.
-   *
-   * Throws on I/O failure (callers should handle gracefully — audit
-   * persistence failure must not block the execution pipeline).
-   */
-  append(record: AuditRecordSummary): void {
-    const dir = dirname(this.filePath);
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-    }
-
-    const line = JSON.stringify(record) + "\n";
-    appendFileSync(this.filePath, line, { mode: 0o600 });
-  }
-
-  /**
-   * List audit records with optional filtering and pagination.
-   *
-   * Records are returned in reverse-chronological order (newest first).
-   *
-   * @param options.sessionId - Filter by session ID.
-   * @param options.credentialHandle - Filter by credential handle.
-   * @param options.grantId - Filter by grant ID.
-   * @param options.limit - Maximum number of records to return (default: 50).
-   * @param options.cursor - Opaque cursor from a previous response to
-   *   continue pagination. The cursor is the 0-based line offset encoded
-   *   as a string.
-   *
-   * @returns An object with `records` and `nextCursor`. `nextCursor` is
-   *   null when there are no more results.
-   */
-  list(options?: {
-    sessionId?: string;
-    credentialHandle?: string;
-    grantId?: string;
-    limit?: number;
-    cursor?: string;
-  }): { records: AuditRecordSummary[]; nextCursor: string | null } {
-    const limit = options?.limit ?? 50;
-
-    const allRecords = this.readAll();
-
-    // Reverse for newest-first ordering
-    allRecords.reverse();
-
-    // Apply filters
-    let filtered = allRecords;
-    if (options?.sessionId) {
-      filtered = filtered.filter((r) => r.sessionId === options.sessionId);
-    }
-    if (options?.credentialHandle) {
-      filtered = filtered.filter(
-        (r) => r.credentialHandle === options.credentialHandle,
-      );
-    }
-    if (options?.grantId) {
-      filtered = filtered.filter((r) => r.grantId === options.grantId);
-    }
-
-    // Apply cursor-based pagination
-    const offset = options?.cursor ? parseInt(options.cursor, 10) : 0;
-    const startIdx = isNaN(offset) ? 0 : offset;
-
-    const page = filtered.slice(startIdx, startIdx + limit);
-    const hasMore = startIdx + limit < filtered.length;
-    const nextCursor = hasMore ? String(startIdx + limit) : null;
-
-    return { records: page, nextCursor };
-  }
-
-  /**
-   * Return the total number of records in the log.
-   *
-   * Returns 0 if the file does not exist or is unreadable.
-   */
-  count(): number {
-    return this.readAll().length;
-  }
-
-  // -----------------------------------------------------------------------
-  // Internals
-  // -----------------------------------------------------------------------
-
-  /**
-   * Read all records from the JSONL file, skipping malformed lines.
-   *
-   * Returns an empty array if the file is missing or unreadable.
-   */
-  private readAll(): AuditRecordSummary[] {
-    if (!existsSync(this.filePath)) return [];
-
-    let raw: string;
-    try {
-      raw = readFileSync(this.filePath, "utf-8");
-    } catch {
-      return [];
-    }
-
-    const records: AuditRecordSummary[] = [];
-    const lines = raw.split("\n");
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (trimmed.length === 0) continue;
-
-      try {
-        const parsed = JSON.parse(trimmed) as AuditRecordSummary;
-        // Minimal validation — must have auditId and timestamp
-        if (
-          typeof parsed.auditId === "string" &&
-          typeof parsed.timestamp === "string"
-        ) {
-          records.push(parsed);
-        }
-      } catch {
-        // Skip malformed lines
-      }
-    }
-
-    return records;
-  }
-}

package/src/commands/auth-adapters.ts

@@ -1,169 +0,0 @@
-/**
- * CES auth adapter definitions for secure command profiles.
- *
- * Auth adapters describe how credentials are materialised into a command's
- * execution environment. Each adapter type has different security properties
- * and cleanup requirements.
- *
- * v1 adapter set:
- *
- * - `env_var`            — Inject credential as an environment variable.
- *                          Lifetime: process scope. Cleaned up on exit.
- * - `temp_file`          — Write credential to a temporary file and pass
- *                          the path via an env var. File is deleted after
- *                          command exits.
- * - `credential_process` — Spawn a helper process that prints the credential
- *                          to stdout (AWS credential_process pattern). The
- *                          helper runs inside CES and is never exposed to the
- *                          subprocess directly.
- */
-
-// ---------------------------------------------------------------------------
-// Auth adapter type discriminator
-// ---------------------------------------------------------------------------
-
-export const AuthAdapterType = {
-  /** Inject credential value as an environment variable. */
-  EnvVar: "env_var",
-  /** Write credential to a temp file and set a path env var. */
-  TempFile: "temp_file",
-  /**
-   * Spawn a credential helper process (AWS credential_process-style).
-   * The helper stdout is captured and injected as an env var.
-   */
-  CredentialProcess: "credential_process",
-} as const;
-
-export type AuthAdapterType =
-  (typeof AuthAdapterType)[keyof typeof AuthAdapterType];
-
-/** All valid auth adapter type strings. */
-export const AUTH_ADAPTER_TYPES: readonly AuthAdapterType[] = Object.values(
-  AuthAdapterType,
-) as AuthAdapterType[];
-
-// ---------------------------------------------------------------------------
-// Auth adapter config shapes
-// ---------------------------------------------------------------------------
-
-/**
- * Inject a credential directly as an environment variable.
- *
- * Example: `GH_TOKEN=<secret>` with `envVarName: "GH_TOKEN"`.
- */
-export interface EnvVarAdapterConfig {
-  type: typeof AuthAdapterType.EnvVar;
-  /** Environment variable name where the credential value is injected. */
-  envVarName: string;
-  /**
-   * Optional prefix prepended to the raw credential value before injection
-   * (e.g. "Bearer " for OAuth tokens).
-   */
-  valuePrefix?: string;
-}
-
-/**
- * Write the credential to a temporary file and set an env var to the path.
- *
- * Example: `GOOGLE_APPLICATION_CREDENTIALS=/tmp/ces-xxx/svc.json`.
- * The temp file is created in a CES-managed ephemeral directory and deleted
- * after the command exits.
- */
-export interface TempFileAdapterConfig {
-  type: typeof AuthAdapterType.TempFile;
-  /** Environment variable name pointing to the temp file path. */
-  envVarName: string;
-  /** File extension for the temp file (e.g. ".json", ".pem"). */
-  fileExtension?: string;
-  /**
-   * File mode (octal) for the temp file. Defaults to 0o600 (owner-only
-   * read/write). Must be <= 0o600.
-   */
-  fileMode?: number;
-}
-
-/**
- * Spawn a credential helper process, capture its stdout, and inject the
- * result as an env var.
- *
- * Example: AWS `credential_process` that emits JSON with temporary keys.
- * The helper command runs inside the CES process and is never exposed to
- * the child command.
- */
-export interface CredentialProcessAdapterConfig {
-  type: typeof AuthAdapterType.CredentialProcess;
-  /** The helper command to run (e.g. "aws-vault exec <profile> --json"). */
-  helperCommand: string;
-  /** Environment variable name where the helper's stdout is injected. */
-  envVarName: string;
-  /** Timeout in milliseconds for the helper process. Defaults to 10000. */
-  timeoutMs?: number;
-}
-
-/**
- * Discriminated union of all auth adapter configurations.
- */
-export type AuthAdapterConfig =
-  | EnvVarAdapterConfig
-  | TempFileAdapterConfig
-  | CredentialProcessAdapterConfig;
-
-// ---------------------------------------------------------------------------
-// Validation helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Returns true if the given string is a valid auth adapter type.
- */
-export function isValidAuthAdapterType(value: string): value is AuthAdapterType {
-  return (AUTH_ADAPTER_TYPES as readonly string[]).includes(value);
-}
-
-/**
- * Validate an auth adapter config shape. Returns a list of error messages
- * (empty array = valid).
- */
-export function validateAuthAdapterConfig(
-  config: AuthAdapterConfig,
-): string[] {
-  const errors: string[] = [];
-
-  if (!isValidAuthAdapterType(config.type)) {
-    errors.push(
-      `Unknown auth adapter type "${config.type}". Valid types: ${AUTH_ADAPTER_TYPES.join(", ")}`,
-    );
-    return errors;
-  }
-
-  if (!config.envVarName || config.envVarName.trim().length === 0) {
-    errors.push(`Auth adapter "${config.type}" requires a non-empty envVarName`);
-  }
-
-  switch (config.type) {
-    case AuthAdapterType.TempFile:
-      if (
-        config.fileMode !== undefined &&
-        (config.fileMode > 0o600 || (config.fileMode & 0o077) !== 0)
-      ) {
-        errors.push(
-          `temp_file adapter fileMode must be <= 0600 (owner-only) with no group/other bits, got ${config.fileMode.toString(8)}`,
-        );
-      }
-      break;
-
-    case AuthAdapterType.CredentialProcess:
-      if (!config.helperCommand || config.helperCommand.trim().length === 0) {
-        errors.push(
-          `credential_process adapter requires a non-empty helperCommand`,
-        );
-      }
-      if (config.timeoutMs !== undefined && config.timeoutMs <= 0) {
-        errors.push(
-          `credential_process adapter timeoutMs must be positive, got ${config.timeoutMs}`,
-        );
-      }
-      break;
-  }
-
-  return errors;
-}

package/src/commands/egress-hooks.ts

@@ -1,203 +0,0 @@
-/**
- * CES egress proxy hooks.
- *
- * Provides a lightweight `SessionStartHooks` implementation for the
- * credential execution service. Unlike the assistant's session-manager
- * (which wires credential resolution, MITM interception, and policy
- * decisions), CES only needs to enforce the manifest's
- * `allowedNetworkTargets` allowlist. No credential injection or CA
- * setup happens at the proxy layer — CES injects credentials through
- * auth adapters in the command environment.
- *
- * The proxy server is a plain HTTP CONNECT proxy that:
- * - Allows connections matching the session's `allowedTargets` (host, port, protocol)
- * - Blocks all other outbound connections
- */
-
-import { request as httpRequest, createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { request as httpsRequest } from "node:https";
-import { connect, type Socket } from "node:net";
-
-import type { AllowedTarget, ManagedSession, SessionStartHooks } from "@vellumai/egress-proxy";
-
-// ---------------------------------------------------------------------------
-// Host-pattern matching
-// ---------------------------------------------------------------------------
-
-/**
- * Match a hostname against a glob pattern.
- *
- * Supported patterns:
- * - Exact match: `"api.github.com"` matches `"api.github.com"`
- * - Wildcard subdomain: `"*.github.com"` matches `"api.github.com"`,
- *   `"foo.bar.github.com"`, and also `"github.com"` (apex)
- *
- * Note: `"*"` (match-everything) is intentionally NOT supported. The
- * manifest validator rejects overbroad patterns at registration time.
- */
-function matchesHostPattern(hostname: string, pattern: string): boolean {
-  if (pattern === hostname) return true;
-  if (pattern.startsWith("*.")) {
-    const suffix = pattern.slice(1); // e.g. ".github.com"
-    const apex = pattern.slice(2);   // e.g. "github.com"
-    return hostname.endsWith(suffix) || hostname === apex;
-  }
-  return false;
-}
-
-/**
- * Check if a request target is allowed by any of the provided allowed targets.
- *
- * Validates host, port, and protocol against each allowed target entry.
- * - Host must match the glob pattern.
- * - If the target specifies `ports`, the request port must be in the list.
- * - If the target specifies `protocols`, the request protocol must be in the list.
- */
-function isTargetAllowed(
-  hostname: string,
-  port: number,
-  protocol: "http" | "https",
-  allowedTargets: AllowedTarget[],
-): boolean {
-  for (const target of allowedTargets) {
-    if (!matchesHostPattern(hostname, target.host)) continue;
-    if (target.ports && target.ports.length > 0 && !target.ports.includes(port)) continue;
-    if (target.protocols && target.protocols.length > 0 && !target.protocols.includes(protocol)) continue;
-    return true;
-  }
-  return false;
-}
-
-// ---------------------------------------------------------------------------
-// CONNECT tunnel handler
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a CONNECT target of the form `host:port`.
- */
-function parseConnectTarget(
-  url: string | undefined,
-): { host: string; port: number } | null {
-  if (!url) return null;
-  const colonIdx = url.lastIndexOf(":");
-  if (colonIdx <= 0) return null;
-  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;
-  if (host.startsWith("[") && host.endsWith("]")) {
-    host = host.slice(1, -1);
-    if (!host) return null;
-  }
-  return { host, port };
-}
-
-// ---------------------------------------------------------------------------
-// Hooks factory
-// ---------------------------------------------------------------------------
-
-/**
- * Build `SessionStartHooks` for CES egress enforcement.
- *
- * The created proxy server enforces the `allowedTargets` from the
- * session's config. If no `allowedTargets` are configured, all
- * connections are blocked (fail-closed).
- */
-export function buildCesEgressHooks(): SessionStartHooks {
-  return {
-    // No CA setup needed — CES does not do MITM interception
-    createServer: async (managed: ManagedSession) => {
-      const allowedTargets = managed.config.allowedTargets ?? [];
-
-      const server = createServer((req: IncomingMessage, res: ServerResponse) => {
-        // Plain HTTP proxy requests — parse the absolute URL and check host/port/protocol
-        if (req.url && req.method) {
-          try {
-            const target = new URL(req.url);
-            const protocol = target.protocol === "https:" ? "https" : "http" as const;
-            const port = target.port
-              ? Number(target.port)
-              : protocol === "https" ? 443 : 80;
-            if (!isTargetAllowed(target.hostname, port, protocol, allowedTargets)) {
-              res.writeHead(403, { "Content-Type": "text/plain" });
-              res.end(`Blocked by CES egress policy: ${target.hostname}:${port} (${protocol}) is not in the allowed targets list`);
-              return;
-            }
-
-            // Forward the request using the appropriate protocol
-            const doRequest = target.protocol === "https:" ? httpsRequest : httpRequest;
-            const proxyReq = doRequest(
-              req.url,
-              {
-                method: req.method,
-                headers: { ...req.headers, host: target.host },
-              },
-              (proxyRes) => {
-                res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
-                proxyRes.pipe(res);
-              },
-            );
-
-            proxyReq.on("error", () => {
-              if (!res.headersSent) {
-                res.writeHead(502, { "Content-Type": "text/plain" });
-              }
-              res.end("Proxy connection error");
-            });
-
-            req.pipe(proxyReq);
-          } catch {
-            res.writeHead(400, { "Content-Type": "text/plain" });
-            res.end("Bad request");
-          }
-          return;
-        }
-
-        res.writeHead(400, { "Content-Type": "text/plain" });
-        res.end("Bad request");
-      });
-
-      // Handle CONNECT for HTTPS tunnelling
-      server.on("connect", (req: IncomingMessage, clientSocket: Socket, head: Buffer) => {
-        const target = parseConnectTarget(req.url);
-        if (!target) {
-          clientSocket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
-          clientSocket.destroy();
-          return;
-        }
-
-        // CONNECT is used for HTTPS tunnelling — assume "https" protocol
-        if (!isTargetAllowed(target.host, target.port, "https", allowedTargets)) {
-          clientSocket.write(
-            "HTTP/1.1 403 Forbidden\r\n" +
-            "Content-Type: text/plain\r\n\r\n" +
-            `Blocked by CES egress policy: ${target.host}:${target.port} (https) is not in the allowed targets list`,
-          );
-          clientSocket.destroy();
-          return;
-        }
-
-        // Tunnel to the allowed target
-        const upstream = connect(target.port, target.host, () => {
-          clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
-          if (head.length > 0) {
-            upstream.write(head);
-          }
-          upstream.pipe(clientSocket);
-          clientSocket.pipe(upstream);
-        });
-
-        upstream.on("error", () => {
-          clientSocket.destroy();
-        });
-
-        clientSocket.on("error", () => {
-          upstream.destroy();
-        });
-      });
-
-      return server;
-    },
-  };
-}