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

package/src/http/response-filter.ts

@@ -1,233 +0,0 @@
-/**
- * HTTP response filtering for the Credential Execution Service.
- *
- * Sanitises raw HTTP responses before returning them to the untrusted
- * assistant runtime. The assistant must never receive:
- * - Raw auth-bearing response headers (e.g. `set-cookie`, `www-authenticate`)
- * - Echoed secret values in response bodies (defense-in-depth scrubbing)
- * - Unbounded response bodies that could exhaust memory
- *
- * The filter also produces a token-free audit summary of every HTTP
- * interaction for the CES audit log.
- */
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
-
-/**
- * Maximum response body size returned to the assistant (256 KB).
- *
- * Responses larger than this are truncated with a suffix indicating
- * the original size. The full body is never stored — this is a hard
- * clamp, not a soft limit.
- */
-const MAX_BODY_BYTES = 256 * 1024;
-
-/**
- * Response headers that are safe to pass through to the assistant.
- *
- * Only these headers are included in the sanitised response.
- * Everything else is stripped — especially `set-cookie`,
- * `www-authenticate`, and any custom auth headers.
- */
-const ALLOWED_RESPONSE_HEADERS = new Set([
-  "content-type",
-  "content-length",
-  "content-encoding",
-  "content-language",
-  "content-disposition",
-  "cache-control",
-  "etag",
-  "last-modified",
-  "date",
-  "x-request-id",
-  "x-ratelimit-limit",
-  "x-ratelimit-remaining",
-  "x-ratelimit-reset",
-  "retry-after",
-  "link",
-  "location",
-  "vary",
-  "accept-ranges",
-  "access-control-allow-origin",
-  "access-control-allow-methods",
-  "access-control-allow-headers",
-  "access-control-expose-headers",
-]);
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Raw HTTP response from the outbound call. */
-export interface RawHttpResponse {
-  /** HTTP status code. */
-  statusCode: number;
-  /** Raw response headers (key-value pairs, header names may be mixed case). */
-  headers: Record<string, string>;
-  /** Response body as a string. */
-  body: string;
-}
-
-/** Sanitised HTTP response safe for the assistant runtime. */
-export interface SanitisedHttpResponse {
-  /** HTTP status code (passed through). */
-  statusCode: number;
-  /** Whitelisted response headers (lowercased keys). */
-  headers: Record<string, string>;
-  /** Body clamped to MAX_BODY_BYTES with secrets scrubbed. */
-  body: string;
-  /** Whether the body was truncated. */
-  truncated: boolean;
-  /** Original body size in bytes (before truncation). */
-  originalBodyBytes: number;
-}
-
-// ---------------------------------------------------------------------------
-// Header filtering
-// ---------------------------------------------------------------------------
-
-/**
- * Filter response headers to only include whitelisted safe headers.
- *
- * All header names are lowercased for consistent comparison.
- */
-export function filterResponseHeaders(
-  headers: Record<string, string>,
-): Record<string, string> {
-  const filtered: Record<string, string> = {};
-  for (const [key, value] of Object.entries(headers)) {
-    if (ALLOWED_RESPONSE_HEADERS.has(key.toLowerCase())) {
-      filtered[key.toLowerCase()] = value;
-    }
-  }
-  return filtered;
-}
-
-// ---------------------------------------------------------------------------
-// Body clamping
-// ---------------------------------------------------------------------------
-
-/**
- * Clamp the response body to the maximum allowed size.
- *
- * Returns the (possibly truncated) body and metadata about truncation.
- */
-export function clampBody(body: string): {
-  clampedBody: string;
-  truncated: boolean;
-  originalBytes: number;
-} {
-  const bodyBytes = Buffer.byteLength(body, "utf-8");
-
-  if (bodyBytes <= MAX_BODY_BYTES) {
-    return {
-      clampedBody: body,
-      truncated: false,
-      originalBytes: bodyBytes,
-    };
-  }
-
-  // Truncate to MAX_BODY_BYTES. We use Buffer to handle multi-byte characters
-  // correctly — slice at byte boundaries and convert back to string.
-  const buf = Buffer.from(body, "utf-8");
-  const truncatedBuf = buf.subarray(0, MAX_BODY_BYTES);
-
-  // Decode back to string; incomplete multi-byte sequences at the end are
-  // replaced with the Unicode replacement character, which is acceptable
-  // for a truncated preview.
-  const truncatedBody = truncatedBuf.toString("utf-8");
-
-  return {
-    clampedBody:
-      truncatedBody +
-      `\n\n[CES: Response truncated from ${bodyBytes} bytes to ${MAX_BODY_BYTES} bytes]`,
-    truncated: true,
-    originalBytes: bodyBytes,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Secret scrubbing (defense-in-depth)
-// ---------------------------------------------------------------------------
-
-/**
- * Scrub exact occurrences of known secret values from a response body.
- *
- * This is a defense-in-depth measure for APIs that echo back auth tokens
- * or API keys in their response bodies. The scrubbing replaces exact
- * matches of the secret with a redacted placeholder.
- *
- * Limitations:
- * - Only scrubs exact matches (no partial or encoded variants).
- * - Short secrets (< 8 characters) are skipped to avoid false positives.
- * - This is NOT a primary security control — the grant system and
- *   credential isolation are the real boundaries.
- */
-export function scrubSecrets(body: string, secrets: string[]): string {
-  let result = body;
-  for (const secret of secrets) {
-    // Skip short secrets to avoid false positives with common substrings
-    if (secret.length < 8) continue;
-    // Use a simple global replace — secrets are treated as literal strings
-    result = replaceAll(result, secret, "[CES:REDACTED]");
-  }
-  return result;
-}
-
-/**
- * Replace all occurrences of `search` in `str` with `replacement`.
- *
- * Uses a simple loop to avoid regex special-character escaping issues
- * with secret values that may contain regex metacharacters.
- */
-function replaceAll(str: string, search: string, replacement: string): string {
-  if (search.length === 0) return str;
-
-  let result = "";
-  let idx = 0;
-  while (idx < str.length) {
-    const foundAt = str.indexOf(search, idx);
-    if (foundAt === -1) {
-      result += str.slice(idx);
-      break;
-    }
-    result += str.slice(idx, foundAt) + replacement;
-    idx = foundAt + search.length;
-  }
-  return result;
-}
-
-// ---------------------------------------------------------------------------
-// Full response filter
-// ---------------------------------------------------------------------------
-
-/**
- * Apply the full sanitisation pipeline to a raw HTTP response.
- *
- * Pipeline:
- * 1. Filter response headers to the whitelist.
- * 2. Clamp the body to MAX_BODY_BYTES.
- * 3. Scrub known secrets from the (already clamped) body.
- *
- * @param raw - The raw HTTP response from the outbound call.
- * @param secrets - Known secret values to scrub from the body.
- * @returns Sanitised response safe for the assistant runtime.
- */
-export function filterHttpResponse(
-  raw: RawHttpResponse,
-  secrets: string[] = [],
-): SanitisedHttpResponse {
-  const filteredHeaders = filterResponseHeaders(raw.headers);
-  const { clampedBody, truncated, originalBytes } = clampBody(raw.body);
-  const scrubbedBody = scrubSecrets(clampedBody, secrets);
-
-  return {
-    statusCode: raw.statusCode,
-    headers: filteredHeaders,
-    body: scrubbedBody,
-    truncated,
-    originalBodyBytes: originalBytes,
-  };
-}

package/src/managed-errors.ts

@@ -1,9 +0,0 @@
-/**
- * Error message constants for managed-mode CES.
- *
- * Re-exported from @vellumai/service-contracts so both the assistant and
- * credential-executor can share the constant via the approved shared-code
- * path without violating the hard process-boundary isolation.
- */
-
-export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "@vellumai/service-contracts/credential-rpc";

package/src/managed-lazy-getters.ts

@@ -1,106 +0,0 @@
-/**
- * Lazy getter pattern for managed CES API key propagation.
- *
- * In managed mode the assistant API key may arrive after CES handlers are
- * registered (via the handshake callback or a later RPC update). The
- * `ApiKeyRef` + `buildLazyGetters` pattern allows handlers to resolve
- * the key at call time rather than at registration time.
- *
- * Extracted from `managed-main.ts` so the behavioral contract can be
- * tested directly without exercising the full managed bootstrap lifecycle.
- */
-
-import type { ManagedSubjectResolverOptions } from "./subjects/managed.js";
-import type { ManagedMaterializerOptions } from "./materializers/managed-platform.js";
-
-/**
- * Mutable reference to the assistant API key. Allows the handshake callback
- * to inject the key provisioned at runtime (which arrives after handlers are
- * built). Handlers read `.current` at call time, not at registration time.
- */
-export interface ApiKeyRef {
-  current: string;
-}
-
-/**
- * Mutable reference to the platform assistant ID. The assistant ID is not
- * available at CES startup (warm-pool pods); the assistant forwards it via
- * the handshake or update_managed_credential RPC after provisioning, and
- * `.current` is updated so lazy getters pick it up.
- */
-export interface AssistantIdRef {
-  current: string;
-}
-
-/**
- * Overwrite the session-scoped managed credential refs.
- *
- * The managed handler registry is long-lived — it persists across assistant
- * reconnects — so every handshake and every `update_managed_credential` must
- * fully overwrite these refs, including clearing them when a value is absent.
- * Otherwise a new or reprovisioned session could keep materializing platform
- * credentials with the previous session's API key or assistant ID. Absent
- * values fall back to "" (fail closed): the lazy getters then return no
- * materialization options, and `getAssistantApiKey` falls back to the env key.
- */
-export function applyManagedCredentialRefs(
-  apiKeyRef: ApiKeyRef,
-  assistantIdRef: AssistantIdRef,
-  apiKey: string | undefined,
-  assistantId: string | undefined,
-): void {
-  apiKeyRef.current = apiKey ?? "";
-  assistantIdRef.current = assistantId ?? "";
-}
-
-export interface LazyGetterOptions {
-  platformBaseUrl: string;
-  assistantIdRef: AssistantIdRef;
-  apiKeyRef: ApiKeyRef;
-  envApiKey?: string;
-}
-
-export interface LazyGetters {
-  getAssistantApiKey: () => string;
-  getManagedSubjectOptions: () => ManagedSubjectResolverOptions | undefined;
-  getManagedMaterializerOptions: () => ManagedMaterializerOptions | undefined;
-}
-
-/**
- * Build lazy getter functions that resolve the API key at call time.
- *
- * Prefers the handshake-provided key (via `apiKeyRef.current`) over the
- * env-var fallback, since in managed mode the env var may not be set
- * (chicken-and-egg: key is provisioned after hatch).
- */
-export function buildLazyGetters(opts: LazyGetterOptions): LazyGetters {
-  const { platformBaseUrl, assistantIdRef, apiKeyRef, envApiKey } = opts;
-
-  const getAssistantApiKey = (): string => apiKeyRef.current || envApiKey || "";
-
-  const getManagedSubjectOptions = ():
-    | ManagedSubjectResolverOptions
-    | undefined => {
-    const key = getAssistantApiKey();
-    const id = assistantIdRef.current;
-    return platformBaseUrl && key && id
-      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
-      : undefined;
-  };
-
-  const getManagedMaterializerOptions = ():
-    | ManagedMaterializerOptions
-    | undefined => {
-    const key = getAssistantApiKey();
-    const id = assistantIdRef.current;
-    return platformBaseUrl && key && id
-      ? { platformBaseUrl, assistantApiKey: key, assistantId: id }
-      : undefined;
-  };
-
-  return {
-    getAssistantApiKey,
-    getManagedSubjectOptions,
-    getManagedMaterializerOptions,
-  };
-}