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

package/src/http/path-template.ts

@@ -1,245 +0,0 @@
-/**
- * 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.
- */
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Safely decode a percent-encoded path segment. Returns `null` when it
- * contains malformed escapes (e.g. bare `%` or `%zz`) so that callers
- * can fail closed — malformed segments never match anything.
- */
-function safeDecodeSegment(segment: string): string | null {
-  try {
-    return decodeURIComponent(segment);
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-
-// ---------------------------------------------------------------------------
-// Spoofed placeholder detection
-// ---------------------------------------------------------------------------
-
-/**
- * Literal strings that, if present in a decoded URL segment, indicate an
- * attempt to inject a wildcard placeholder via percent-encoding.
- *
- * Legitimate URLs never contain these exact strings as path segments.
- * Rejecting them prevents an attacker from crafting a URL like
- * `https://api.example.com/%7B:num%7D/resource` that would be stored as
- * a literal during grant approval but decoded to a wildcard during matching.
- */
-const PLACEHOLDER_LITERALS = new Set(["{:num}", "{:uuid}", "{:hex}"]);
-
-// ---------------------------------------------------------------------------
-// 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 rawSegments = parsed.pathname
-    .split("/")
-    .filter((s) => s.length > 0);
-
-  // Decode each segment for classification and placeholder detection, but
-  // preserve the raw (encoded) form for literal segments in the rebuilt
-  // template. This prevents encoded delimiters like %2F from being decoded
-  // into real path separators, which would change URL structure.
-  const decodedSegments = rawSegments.map((seg) => {
-    const decoded = safeDecodeSegment(seg);
-    // If decoding fails, keep the raw segment — it will be stored as a
-    // literal and can never match anything meaningful (fail closed).
-    return decoded ?? seg;
-  });
-
-  // Guard: reject URLs whose decoded segments match known placeholder
-  // patterns. Legitimate URLs never contain literal "{:num}" etc. as path
-  // segments; their presence indicates an attempt to inject wildcards via
-  // percent-encoding (e.g. %7B:num%7D).
-  for (const seg of decodedSegments) {
-    if (PLACEHOLDER_LITERALS.has(seg)) {
-      throw new Error(
-        `Refusing to derive path template: segment "${seg}" is a reserved placeholder literal`,
-      );
-    }
-  }
-
-  const templatedSegments = decodedSegments.map((decoded, i) => {
-    const classified = classifySegment(decoded);
-    // If the segment was replaced with a placeholder, use the placeholder.
-    // Otherwise, use the raw (encoded) segment to preserve URL structure.
-    return classified !== decoded ? classified : rawSegments[i]!;
-  });
-
-  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.
-  // safeDecodeSegment is applied to both sides so that percent-encoded bytes
-  // (e.g. %20, %7B) are compared consistently and so that the URL constructor's
-  // encoding of curly braces ({, }) in template placeholders is reversed.
-  // A null return means a malformed escape — fail closed immediately.
-  const urlSegments = parsedUrl.pathname
-    .split("/")
-    .filter((s) => s.length > 0)
-    .map(safeDecodeSegment);
-  const templateSegments = parsedTemplate.pathname
-    .split("/")
-    .filter((s) => s.length > 0)
-    .map(safeDecodeSegment);
-
-  if (urlSegments.some((s) => s === null)) return false;
-  if (templateSegments.some((s) => s === null)) return false;
-
-  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

@@ -1,238 +0,0 @@
-/**
- * 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 { hashProposal, type HttpGrantProposal } from "@vellumai/service-contracts/credential-rpc";
-
-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 conversation-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 &&
-      grant.tool === "http" &&
-      grantCoversRequest(grant, request.credentialHandle, request.method, request.url, "")
-    ) {
-      return { allowed: true, grantId: grant.id, grantSource: "persistent" };
-    }
-    // Explicit grant not found or does not cover this request — 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 = hashProposal(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),
-  };
-}
-