@vellumai/credential-executor 0.4.55

package/src/http/path-template.ts

@@ -0,0 +1,179 @@
+/**
+ * Deterministic path-template derivation for HTTP grant proposals.
+ *
+ * Normalises URLs and replaces only well-known dynamic segments (numeric IDs,
+ * UUIDs, and long hex strings) with typed placeholders while keeping every
+ * other path segment literal. This ensures that proposals are specific enough
+ * to be meaningful ("allow GET on /repos/{owner}/pulls/{:num}") without
+ * over-expanding to wildcard patterns that would be too permissive.
+ *
+ * Design invariants:
+ * - Query strings and fragments are stripped — only scheme + host + path matter.
+ * - Host is preserved literally (no wildcard expansion).
+ * - Path never collapses to `/*`.
+ * - Trailing slashes are normalised away.
+ */
+
+// ---------------------------------------------------------------------------
+// Segment classification patterns
+// ---------------------------------------------------------------------------
+
+/**
+ * UUID v4 pattern (case-insensitive): 8-4-4-4-12 hex digits with hyphens.
+ */
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Purely numeric segments (e.g. resource IDs like `/users/42`).
+ */
+const NUMERIC_RE = /^[0-9]+$/;
+
+/**
+ * Hex-like strings of 16+ characters — commonly used for opaque identifiers,
+ * commit SHAs, object IDs, etc. Must be at least 16 chars to avoid matching
+ * short, human-meaningful slugs that happen to be hex-only (e.g. "cafe",
+ * "dead", "beef").
+ */
+const HEX_LONG_RE = /^[0-9a-f]{16,}$/i;
+
+// ---------------------------------------------------------------------------
+// Placeholder types
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace a path segment with a typed placeholder if it matches a known
+ * dynamic pattern. Returns the original segment if it does not match.
+ */
+function classifySegment(segment: string): string {
+  if (UUID_RE.test(segment)) return "{:uuid}";
+  if (NUMERIC_RE.test(segment)) return "{:num}";
+  if (HEX_LONG_RE.test(segment)) return "{:hex}";
+  return segment;
+}
+
+// ---------------------------------------------------------------------------
+// Path template derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a deterministic path template from a raw URL.
+ *
+ * 1. Parse the URL to extract scheme, host, and pathname.
+ * 2. Strip query string and fragment.
+ * 3. Split the pathname into segments and classify each one.
+ * 4. Reassemble into `scheme://host/path/with/{placeholders}`.
+ *
+ * Throws if `rawUrl` is not a valid absolute URL.
+ */
+export function derivePathTemplate(rawUrl: string): string {
+  const parsed = new URL(rawUrl);
+
+  // Normalise: strip query and fragment, lowercase the host
+  const scheme = parsed.protocol.replace(/:$/, "");
+  const host = parsed.hostname + (parsed.port ? `:${parsed.port}` : "");
+
+  // Split path into segments, dropping empty segments from leading/trailing slashes
+  const segments = parsed.pathname
+    .split("/")
+    .filter((s) => s.length > 0);
+
+  const templatedSegments = segments.map(classifySegment);
+
+  const path =
+    templatedSegments.length > 0
+      ? "/" + templatedSegments.join("/")
+      : "/";
+
+  return `${scheme}://${host}${path}`;
+}
+
+/**
+ * Derive the allowed URL pattern for an HTTP grant proposal.
+ *
+ * Returns an array with a single pattern string — the path template.
+ * The caller uses this to populate `allowedUrlPatterns` on the proposal.
+ *
+ * This is a thin wrapper around `derivePathTemplate` that returns an array
+ * for direct use in proposal construction.
+ */
+export function deriveAllowedUrlPatterns(rawUrl: string): string[] {
+  return [derivePathTemplate(rawUrl)];
+}
+
+/**
+ * Check whether a concrete URL matches a path template pattern.
+ *
+ * Used during grant evaluation to determine whether a stored
+ * `allowedUrlPatterns` entry covers a requested URL.
+ *
+ * Matching rules:
+ * - Scheme and host must match exactly (case-insensitive).
+ * - Path segments must match positionally.
+ * - A `{:num}` placeholder matches any purely numeric segment.
+ * - A `{:uuid}` placeholder matches any UUID v4 segment.
+ * - A `{:hex}` placeholder matches any 16+-char hex segment.
+ * - Literal segments must match exactly (case-sensitive — URL paths are
+ *   case-sensitive per RFC 3986).
+ */
+export function urlMatchesTemplate(
+  rawUrl: string,
+  template: string,
+): boolean {
+  let parsedUrl: URL;
+  let parsedTemplate: URL;
+
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  try {
+    parsedTemplate = new URL(template);
+  } catch {
+    return false;
+  }
+
+  // Scheme must match
+  if (parsedUrl.protocol !== parsedTemplate.protocol) return false;
+
+  // Host must match (case-insensitive)
+  const urlHost =
+    parsedUrl.hostname.toLowerCase() +
+    (parsedUrl.port ? `:${parsedUrl.port}` : "");
+  const templateHost =
+    parsedTemplate.hostname.toLowerCase() +
+    (parsedTemplate.port ? `:${parsedTemplate.port}` : "");
+  if (urlHost !== templateHost) return false;
+
+  // Split paths and compare segment-by-segment.
+  // decodeURIComponent is needed because the URL constructor percent-encodes
+  // curly braces ({, }) in paths — placeholders like {:num} become %7B:num%7D.
+  const urlSegments = parsedUrl.pathname
+    .split("/")
+    .filter((s) => s.length > 0);
+  const templateSegments = parsedTemplate.pathname
+    .split("/")
+    .filter((s) => s.length > 0)
+    .map((s) => decodeURIComponent(s));
+
+  if (urlSegments.length !== templateSegments.length) return false;
+
+  for (let i = 0; i < templateSegments.length; i++) {
+    const tSeg = templateSegments[i];
+    const uSeg = urlSegments[i];
+
+    if (tSeg === "{:num}") {
+      if (!NUMERIC_RE.test(uSeg)) return false;
+    } else if (tSeg === "{:uuid}") {
+      if (!UUID_RE.test(uSeg)) return false;
+    } else if (tSeg === "{:hex}") {
+      if (!HEX_LONG_RE.test(uSeg)) return false;
+    } else {
+      // Literal match (case-sensitive)
+      if (tSeg !== uSeg) return false;
+    }
+  }
+
+  return true;
+}

package/src/http/policy.ts

@@ -0,0 +1,256 @@
+/**
+ * HTTP policy evaluation for the Credential Execution Service.
+ *
+ * Evaluates incoming HTTP requests against the CES grant stores before any
+ * outbound network call is made. If no active grant covers the request, the
+ * policy engine blocks the call and returns an `approval_required` result
+ * containing the minimal reusable HTTP capability proposal.
+ *
+ * Security invariants:
+ * - **Off-grant requests are blocked before any network call.** The CES must
+ *   never make an authenticated outbound HTTP request without a matching grant.
+ * - **Proposal derivation never auto-expands.** Proposals use the concrete
+ *   path template (with typed placeholders for dynamic segments), never host
+ *   wildcards or `/*`.
+ * - **Caller-supplied auth headers are rejected.** The untrusted agent must
+ *   not be able to smuggle raw `Authorization`, `Cookie`, or other auth
+ *   headers in the request — CES injects those from the materialised
+ *   credential.
+ */
+
+import { createHash } from "node:crypto";
+
+import type { HttpGrantProposal } from "@vellumai/ces-contracts";
+
+import type { PersistentGrant, PersistentGrantStore } from "../grants/persistent-store.js";
+import type { TemporaryGrantStore } from "../grants/temporary-store.js";
+import {
+  deriveAllowedUrlPatterns,
+  derivePathTemplate,
+  urlMatchesTemplate,
+} from "./path-template.js";
+
+// ---------------------------------------------------------------------------
+// Auth header rejection
+// ---------------------------------------------------------------------------
+
+/**
+ * Headers that the untrusted agent is forbidden from setting on credentialed
+ * requests. CES injects authentication; the caller must not override it.
+ */
+const FORBIDDEN_CALLER_HEADERS = new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+  "x-api-key",
+  "x-auth-token",
+]);
+
+/**
+ * Returns the list of forbidden header names present in the caller-supplied
+ * headers, or an empty array if none are present.
+ */
+export function detectForbiddenHeaders(
+  headers: Record<string, string> | undefined,
+): string[] {
+  if (!headers) return [];
+  const forbidden: string[] = [];
+  for (const key of Object.keys(headers)) {
+    if (FORBIDDEN_CALLER_HEADERS.has(key.toLowerCase())) {
+      forbidden.push(key);
+    }
+  }
+  return forbidden;
+}
+
+// ---------------------------------------------------------------------------
+// Policy evaluation result
+// ---------------------------------------------------------------------------
+
+export type PolicyResult =
+  | { allowed: true; grantId: string; grantSource: "persistent" | "temporary" }
+  | { allowed: false; reason: "forbidden_headers"; forbiddenHeaders: string[] }
+  | {
+      allowed: false;
+      reason: "approval_required";
+      proposal: HttpGrantProposal;
+    };
+
+// ---------------------------------------------------------------------------
+// Policy evaluation request
+// ---------------------------------------------------------------------------
+
+export interface HttpPolicyRequest {
+  /** CES credential handle identifying which credential to use. */
+  credentialHandle: string;
+  /** HTTP method (e.g. "GET", "POST"). */
+  method: string;
+  /** Target URL. */
+  url: string;
+  /** Caller-supplied headers (before credential injection). */
+  headers?: Record<string, string>;
+  /** Human-readable purpose for the audit trail. */
+  purpose: string;
+  /** Explicit grant ID the caller claims to hold. */
+  grantId?: string;
+  /** Conversation ID for thread-scoped temporary grants. */
+  conversationId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Policy evaluator
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate whether an HTTP request is covered by an existing grant.
+ *
+ * Evaluation order:
+ * 1. Reject forbidden caller-supplied auth headers.
+ * 2. If an explicit `grantId` is provided, look it up in the persistent store.
+ * 3. Check the persistent grant store for a matching active grant.
+ * 4. Check the temporary grant store for a matching temporary grant.
+ * 5. If no grant matches, derive a minimal proposal and return `approval_required`.
+ */
+export function evaluateHttpPolicy(
+  request: HttpPolicyRequest,
+  persistentStore: PersistentGrantStore,
+  temporaryStore: TemporaryGrantStore,
+): PolicyResult {
+  // 1. Reject forbidden caller-supplied auth headers
+  const forbidden = detectForbiddenHeaders(request.headers);
+  if (forbidden.length > 0) {
+    return {
+      allowed: false,
+      reason: "forbidden_headers",
+      forbiddenHeaders: forbidden,
+    };
+  }
+
+  // 2. Check explicit grantId in persistent store
+  if (request.grantId) {
+    const grant = persistentStore.getById(request.grantId);
+    if (grant) {
+      return { allowed: true, grantId: grant.id, grantSource: "persistent" };
+    }
+    // Explicit grant not found — fall through to pattern matching
+  }
+
+  // 3. Check persistent grants for pattern match
+  const pathTemplate = derivePathTemplate(request.url);
+  const allGrants = persistentStore.getAll();
+  for (const grant of allGrants) {
+    if (
+      grant.tool === "http" &&
+      grantCoversRequest(grant, request.credentialHandle, request.method, request.url, pathTemplate)
+    ) {
+      return { allowed: true, grantId: grant.id, grantSource: "persistent" };
+    }
+  }
+
+  // 4. Check temporary grants
+  // Build a proposal hash key from the canonical request shape
+  const proposal = buildProposal(request, pathTemplate);
+  const proposalHash = hashProposalForLookup(proposal);
+
+  const tempKind = temporaryStore.checkAny(
+    proposalHash,
+    request.conversationId,
+  );
+  if (tempKind) {
+    return {
+      allowed: true,
+      grantId: `temp:${tempKind}:${proposalHash}`,
+      grantSource: "temporary",
+    };
+  }
+
+  // 5. No grant matches — derive proposal
+  return {
+    allowed: false,
+    reason: "approval_required",
+    proposal,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Grant matching helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a persistent grant covers a specific HTTP request.
+ *
+ * A grant covers a request when:
+ * - The grant's `pattern` field contains an `allowedUrlPatterns`-style
+ *   entry that matches the request URL's path template.
+ * - The grant's `scope` field matches the credential handle.
+ * - The grant is for the `http` tool type.
+ */
+function grantCoversRequest(
+  grant: PersistentGrant,
+  credentialHandle: string,
+  method: string,
+  rawUrl: string,
+  _pathTemplate: string,
+): boolean {
+  // Scope must match the credential handle
+  if (grant.scope !== credentialHandle) return false;
+
+  // The pattern field encodes "METHOD pattern", e.g. "GET https://api.github.com/repos/{:uuid}/pulls"
+  // Parse out the method and URL pattern
+  const spaceIdx = grant.pattern.indexOf(" ");
+  if (spaceIdx === -1) {
+    // Pattern without method — match URL only
+    return urlMatchesTemplate(rawUrl, grant.pattern);
+  }
+
+  const grantMethod = grant.pattern.slice(0, spaceIdx).toUpperCase();
+  const grantUrlPattern = grant.pattern.slice(spaceIdx + 1);
+
+  if (grantMethod !== method.toUpperCase()) return false;
+  return urlMatchesTemplate(rawUrl, grantUrlPattern);
+}
+
+// ---------------------------------------------------------------------------
+// Proposal construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the minimal HTTP grant proposal for an unapproved request.
+ *
+ * The proposal uses the derived path template as the `allowedUrlPatterns`
+ * entry — never `/*` or host-level wildcards.
+ */
+function buildProposal(
+  request: HttpPolicyRequest,
+  _pathTemplate: string,
+): HttpGrantProposal {
+  return {
+    type: "http",
+    credentialHandle: request.credentialHandle,
+    method: request.method.toUpperCase(),
+    url: request.url,
+    purpose: request.purpose,
+    allowedUrlPatterns: deriveAllowedUrlPatterns(request.url),
+  };
+}
+
+/**
+ * Compute a deterministic hash key for temporary grant lookup.
+ *
+ * Uses the same canonical JSON → SHA-256 approach as the contracts package
+ * `hashProposal`, but we use a simplified inline version here to avoid
+ * importing the full contracts rendering module into the policy hot path.
+ */
+function hashProposalForLookup(proposal: HttpGrantProposal): string {
+  // Build a canonical key from the proposal's stable fields:
+  // type + credentialHandle + method + allowedUrlPatterns (sorted)
+  const parts = [
+    proposal.type,
+    proposal.credentialHandle,
+    proposal.method.toUpperCase(),
+    ...(proposal.allowedUrlPatterns ?? []).slice().sort(),
+  ];
+  const canonical = JSON.stringify(parts);
+
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}

package/src/http/response-filter.ts

@@ -0,0 +1,233 @@
+/**
+ * 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,
+  };
+}