@vellumai/credential-executor 0.4.55 → 0.4.56

package/src/commands/profiles.ts

@@ -247,6 +247,10 @@ export const DENIED_BINARIES: ReadonlySet<string> = new Set([
   "lua",
   "php",
 
+  // Multi-call umbrella binaries (contain wget, sh, etc. as subcommands)
+  "busybox",
+  "toybox",
+
   // Shell trampolines
   "bash",
   "sh",

package/src/commands/validator.ts

@@ -23,11 +23,13 @@
 
 import {
   validateAuthAdapterConfig,
+  AuthAdapterType,
 } from "./auth-adapters.js";
 import {
   type SecureCommandManifest,
   type CommandProfile,
   type AllowedArgvPattern,
+  type AllowedNetworkTarget,
   MANIFEST_SCHEMA_VERSION,
   EGRESS_MODES,
   EgressMode,
@@ -116,6 +118,50 @@ export function validateManifest(
     for (const e of adapterErrors) {
       errors.push(`authAdapter: ${e}`);
     }
+
+    // -- credential_process helperCommand denied binary check
+    if (manifest.authAdapter.type === AuthAdapterType.CredentialProcess) {
+      const helper = manifest.authAdapter.helperCommand;
+      if (helper && helper.trim().length > 0) {
+        // Reject shell metacharacters that could chain a denied binary
+        // after an allowed one (e.g. "aws-vault exec ; curl ...").
+        // Since helperCommand is executed via `sh -c`, these operators
+        // allow arbitrary command chaining that bypasses the denylist.
+        if (containsShellMetacharacters(helper)) {
+          errors.push(
+            `authAdapter: credential_process helperCommand contains shell metacharacters. ` +
+              `Command chaining operators (;, &&, ||, |) and subshell expansion ($()) ` +
+              `are not allowed in helperCommand because they can bypass the denied binary check.`,
+          );
+        }
+
+        const firstWord = extractShellBinary(helper);
+        const basename = pathBasename(firstWord);
+        if (isDeniedBinary(firstWord)) {
+          errors.push(
+            `authAdapter: credential_process helperCommand starts with denied binary "${basename}". ` +
+              `Generic HTTP clients, interpreters, and shell trampolines cannot be used as credential helpers.`,
+          );
+        }
+      }
+    }
+  }
+
+  // -- cleanConfigDirs key validation (defense-in-depth against path traversal)
+  if (manifest.cleanConfigDirs) {
+    for (const key of Object.keys(manifest.cleanConfigDirs)) {
+      if (key.includes("..")) {
+        errors.push(
+          `cleanConfigDirs key "${key}" contains path traversal sequence "..". ` +
+            `This is not allowed.`,
+        );
+      }
+      if (key.trim().length === 0) {
+        errors.push(
+          `cleanConfigDirs contains an empty key.`,
+        );
+      }
+    }
   }
 
   // -- Command profiles (must have at least one)
@@ -179,8 +225,13 @@ function validateProfile(
     }
   }
 
-  // -- Denied subcommands (optional but must be an array)
-  if (profile.deniedSubcommands) {
+  // -- Denied subcommands (required — runtime iterates unconditionally)
+  if (!profile.deniedSubcommands || !Array.isArray(profile.deniedSubcommands)) {
+    errors.push(
+      `${prefix}: deniedSubcommands is required and must be an array. ` +
+        "Use an empty array if no subcommands need to be denied.",
+    );
+  } else {
     for (const sub of profile.deniedSubcommands) {
       if (!sub || sub.trim().length === 0) {
         errors.push(
@@ -215,6 +266,15 @@ function validateProfile(
         `${prefix}: egressMode is "proxy_required" but no allowedNetworkTargets are declared. ` +
           "Commands with network egress must declare their allowed network targets.",
       );
+    } else {
+      for (let i = 0; i < profile.allowedNetworkTargets.length; i++) {
+        const target = profile.allowedNetworkTargets[i]!;
+        const targetErrors = validateNetworkTarget(
+          `${prefix}: allowedNetworkTargets[${i}]`,
+          target,
+        );
+        errors.push(...targetErrors);
+      }
     }
   }
 
@@ -233,6 +293,100 @@ function validateProfile(
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Network target validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Overbroad host patterns that effectively match everything.
+ * These defeat the purpose of declaring allowed network targets.
+ */
+const OVERBROAD_HOST_PATTERNS: ReadonlySet<string> = new Set([
+  "*",
+  "*.*",
+  "*.*.*",
+  "*.*.*.*",
+]);
+
+/**
+ * Validate a single {@link AllowedNetworkTarget} entry.
+ *
+ * Returns an array of error messages (empty if valid). Checks:
+ * - `hostPattern` is non-empty
+ * - `hostPattern` is not overbroad (e.g. `"*"`, `"*.*"`)
+ * - `hostPattern` is either an exact hostname or a wildcard-subdomain pattern (`*.domain.tld`)
+ * - `ports` (if specified) are valid (1–65535)
+ * - `protocols` (if specified) are `"http"` or `"https"` only
+ */
+function validateNetworkTarget(
+  prefix: string,
+  target: AllowedNetworkTarget,
+): string[] {
+  const errors: string[] = [];
+
+  // -- hostPattern must be non-empty
+  if (!target.hostPattern || target.hostPattern.trim().length === 0) {
+    errors.push(`${prefix}: hostPattern is required and must be non-empty.`);
+    return errors; // Can't validate further without a pattern
+  }
+
+  const pattern = target.hostPattern;
+
+  // -- Reject overbroad patterns
+  if (OVERBROAD_HOST_PATTERNS.has(pattern)) {
+    errors.push(
+      `${prefix}: hostPattern "${pattern}" is overbroad and matches effectively any host. ` +
+        "Use exact hostnames (e.g. \"api.github.com\") or wildcard-subdomain patterns (e.g. \"*.github.com\").",
+    );
+    return errors;
+  }
+
+  // -- Validate pattern shape: exact hostname or *.domain.tld
+  if (pattern.includes("*")) {
+    // Only *.domain.tld form is allowed
+    if (!pattern.startsWith("*.") || pattern.indexOf("*", 1) !== -1) {
+      errors.push(
+        `${prefix}: hostPattern "${pattern}" uses an unsupported wildcard format. ` +
+          "Only wildcard-subdomain patterns (\"*.domain.tld\") are allowed. " +
+          "Wildcards in the middle or end of a hostname are not supported.",
+      );
+    } else {
+      // Ensure the domain part after *. is non-empty and looks like a domain
+      const domain = pattern.slice(2);
+      if (!domain || domain.trim().length === 0) {
+        errors.push(
+          `${prefix}: hostPattern "${pattern}" has an empty domain after the wildcard prefix.`,
+        );
+      }
+    }
+  }
+
+  // -- Validate ports
+  if (target.ports) {
+    for (const port of target.ports) {
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        errors.push(
+          `${prefix}: port ${port} is invalid. Ports must be integers between 1 and 65535.`,
+        );
+      }
+    }
+  }
+
+  // -- Validate protocols
+  if (target.protocols) {
+    const validProtocols = new Set(["http", "https"]);
+    for (const proto of target.protocols) {
+      if (!validProtocols.has(proto)) {
+        errors.push(
+          `${prefix}: protocol "${proto}" is invalid. Only "http" and "https" are allowed.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
 // ---------------------------------------------------------------------------
 // Argv pattern validation
 // ---------------------------------------------------------------------------
@@ -279,9 +433,108 @@ function validateArgvPattern(
     }
   }
 
+  // Only check denied binaries in executable positions — the first token
+  // (index 0) is the subcommand position for multi-call umbrella binaries
+  // (e.g. busybox wget). Tokens at other positions are argument values and
+  // may legitimately use names that overlap with denied binaries (e.g.
+  // "--scheme https" where "https" is an httpie alias in DENIED_BINARIES).
+  const firstToken = pattern.tokens[0];
+  if (firstToken && !isPlaceholder(firstToken) && !isRestPlaceholder(firstToken) && isDeniedBinary(firstToken)) {
+    errors.push(
+      `${profilePrefix}: argv pattern "${pattern.name}" token "${firstToken}" matches a denied binary. ` +
+        `Multi-call umbrella binaries and shell trampolines cannot appear in executable argv positions.`,
+    );
+  }
+
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Shell metacharacter detection (for helperCommand safety)
+// ---------------------------------------------------------------------------
+
+/**
+ * Shell metacharacters that enable command chaining or subshell expansion.
+ * Since helperCommand is executed via `sh -c`, these operators allow an
+ * attacker to chain a denied binary after an allowed one, bypassing the
+ * denylist check on the first token.
+ *
+ * Detected patterns:
+ * - `;`  — command separator
+ * - `&&` — logical AND
+ * - `||` — logical OR
+ * - `|`  — pipe (but not `||`)
+ * - `$(`  — command substitution
+ * - `` ` `` — backtick command substitution
+ * - `\n` — newline (POSIX command separator, equivalent to `;`)
+ * - `\r` — carriage return
+ */
+const SHELL_METACHAR_RE = /;|&&|\|\||(?<!\|)\|(?!\|)|\$\(|`|\n|\r/;
+
+/**
+ * Returns true if the command string contains shell metacharacters that
+ * could be used for command chaining or subshell expansion.
+ */
+export function containsShellMetacharacters(command: string): boolean {
+  return SHELL_METACHAR_RE.test(command);
+}
+
+// ---------------------------------------------------------------------------
+// Shell binary extraction (for helperCommand denylist checks)
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex matching shell variable assignments (KEY=VALUE) at the start of a
+ * command. These are environment overrides and not the binary. Handles
+ * bare values, single-quoted values, and double-quoted values.
+ */
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|(?:\\.|[^\s])*)\s+/;
+
+/**
+ * Extract the actual binary name from a shell command string, accounting for
+ * leading env-var assignments (KEY=VALUE prefixes) and shell quoting around
+ * the binary token. This is necessary because helperCommand is executed via
+ * `sh -c`, so the shell resolves assignments and quotes before execution.
+ *
+ * Examples:
+ *   "curl https://..."                → "curl"
+ *   "'curl' https://..."              → "curl"
+ *   "AWS_PROFILE=x curl ..."          → "curl"
+ *   "AWS_PROFILE=x FOO=bar curl ..." → "curl"
+ *   "/usr/bin/python3 script.py"      → "/usr/bin/python3"
+ */
+export function extractShellBinary(command: string): string {
+  let remaining = command.trim();
+
+  // Strip leading KEY=VALUE assignments
+  let match: RegExpExecArray | null;
+  while ((match = ENV_ASSIGNMENT_RE.exec(remaining)) !== null) {
+    remaining = remaining.slice(match[0].length);
+  }
+
+  // Extract the first whitespace-delimited token
+  const firstToken = remaining.split(/\s+/)[0] ?? remaining;
+
+  // Strip surrounding quotes (single or double)
+  return stripShellQuotes(firstToken);
+}
+
+/**
+ * Remove surrounding single or double quotes from a token.
+ * Only strips matching pairs at the boundaries (e.g., `'curl'` → `curl`).
+ */
+function stripShellQuotes(token: string): string {
+  if (token.length >= 2) {
+    if (
+      (token.startsWith("'") && token.endsWith("'")) ||
+      (token.startsWith('"') && token.endsWith('"'))
+    ) {
+      return token.slice(1, -1);
+    }
+  }
+  return token;
+}
+
 // ---------------------------------------------------------------------------
 // Argv matching (used by the runtime to check commands against profiles)
 // ---------------------------------------------------------------------------
@@ -405,7 +658,7 @@ export function validateCommand(
     }
   }
 
-  // Check denied flags
+  // Check denied flags — also handle --flag=value combined tokens
   for (const arg of argv) {
     if (allDeniedFlags.has(arg)) {
       return {
@@ -413,6 +666,17 @@ export function validateCommand(
         reason: `Flag "${arg}" is explicitly denied.`,
       };
     }
+
+    // Handle --flag=value form: extract the flag prefix before '='
+    if (arg.startsWith("-") && arg.includes("=")) {
+      const flagPrefix = arg.slice(0, arg.indexOf("="));
+      if (allDeniedFlags.has(flagPrefix)) {
+        return {
+          allowed: false,
+          reason: `Flag "${flagPrefix}" is explicitly denied (via "${arg}").`,
+        };
+      }
+    }
   }
 
   // Try to match against allowed argv patterns in each profile

package/src/commands/workspace.ts

@@ -31,7 +31,6 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
-  readlinkSync,
   realpathSync,
   rmSync,
 } from "node:fs";
@@ -163,27 +162,70 @@ export function validateRelativePath(
 
 /**
  * Verify that a resolved path is contained within the expected root
- * directory. Returns an error string if the path escapes.
+ * directory. When the path exists on disk, symlinks are fully resolved
+ * via `realpathSync` so that symlinked segments cannot escape the root.
+ * When the path doesn't exist yet, its closest existing ancestor is
+ * resolved via `realpathSync` to ensure consistent symlink handling
+ * (e.g. `/tmp` → `/private/tmp` on macOS).
  */
 export function validateContainedPath(
   resolvedPath: string,
   rootDir: string,
   label: string,
 ): string | undefined {
-  const normalizedRoot = resolve(rootDir) + "/";
-  const normalizedPath = resolve(resolvedPath);
+  // Resolve symlinks when path exists; fall back to lexical resolve
+  let normalizedRoot: string;
+  let normalizedPath: string = resolve(resolvedPath);
+  try {
+    normalizedRoot = realpathSync(rootDir);
+  } catch {
+    normalizedRoot = resolve(rootDir);
+  }
+  try {
+    normalizedPath = realpathSync(resolvedPath);
+  } catch {
+    // Path doesn't exist yet — walk up to the nearest existing ancestor and
+    // resolve it via realpathSync so that symlinks in parent dirs (e.g.
+    // /tmp → /private/tmp on macOS) are resolved consistently with the root
+    // directory. A single dirname call isn't enough for multi-level
+    // non-existent paths like "reports/output.json" where "reports/" also
+    // doesn't exist.
+    let current = resolvedPath;
+    let resolved = false;
+    while (!resolved) {
+      const ancestor = dirname(current);
+      const tail = resolvedPath.slice(ancestor.length);
+      try {
+        normalizedPath = realpathSync(ancestor) + tail;
+        resolved = true;
+      } catch {
+        if (ancestor === current) {
+          // Reached filesystem root without finding an existing ancestor
+          normalizedPath = resolve(resolvedPath);
+          resolved = true;
+        }
+        current = ancestor;
+      }
+    }
+  }
+
+  const rootPrefix = normalizedRoot + "/";
 
   // The path must start with the root directory prefix
   // (or be the root directory itself, though that's unusual for files)
-  if (!normalizedPath.startsWith(normalizedRoot) && normalizedPath !== resolve(rootDir)) {
-    return `${label}: resolved path "${normalizedPath}" escapes the root directory "${resolve(rootDir)}".`;
+  if (!normalizedPath.startsWith(rootPrefix) && normalizedPath !== normalizedRoot) {
+    return `${label}: resolved path "${normalizedPath}" escapes the root directory "${normalizedRoot}".`;
   }
   return undefined;
 }
 
 /**
- * Check if a path is a symlink that points outside the given root.
- * Returns an error string if it's an escaping symlink, undefined if safe.
+ * Check if a path (or any of its parent components) involves symlinks
+ * that resolve outside the given root directory.
+ *
+ * Uses `realpathSync` to fully resolve all symlink chains (including
+ * chained symlinks and symlinked parent directories) and then validates
+ * that the fully-resolved path is still within the root.
  */
 export function checkSymlinkEscape(
   filePath: string,
@@ -191,24 +233,20 @@ export function checkSymlinkEscape(
   label: string,
 ): string | undefined {
   try {
-    const stat = lstatSync(filePath);
-    if (!stat.isSymbolicLink()) {
-      return undefined; // Not a symlink — safe
-    }
-
-    // Resolve the symlink target
-    const target = readlinkSync(filePath);
-    const resolvedTarget = resolve(dirname(filePath), target);
-    const normalizedRoot = resolve(rootDir) + "/";
+    // Fully resolve all symlinks (handles chained symlinks and
+    // symlinked parent directories in a single call)
+    const resolvedTarget = realpathSync(filePath);
+    const resolvedRoot = realpathSync(rootDir);
+    const rootPrefix = resolvedRoot + "/";
 
     if (
-      !resolvedTarget.startsWith(normalizedRoot) &&
-      resolvedTarget !== resolve(rootDir)
+      !resolvedTarget.startsWith(rootPrefix) &&
+      resolvedTarget !== resolvedRoot
     ) {
-      return `${label}: symlink "${filePath}" points to "${resolvedTarget}" which is outside the scratch directory "${resolve(rootDir)}".`;
+      return `${label}: path "${filePath}" resolves to "${resolvedTarget}" which is outside the scratch directory "${resolvedRoot}".`;
     }
   } catch {
-    // If we can't stat the file, it doesn't exist yet or is inaccessible.
+    // If we can't resolve the file, it doesn't exist yet or is inaccessible.
     // This will be caught later during the actual copy.
     return undefined;
   }

package/src/grants/index.ts

@@ -7,7 +7,7 @@
  * - **Persistent store**: Durable grants (e.g. `always_allow`) persisted
  *   to `grants.json` inside the CES-private data root. Survives restarts.
  * - **Temporary store**: Ephemeral grants (`allow_once`, `allow_10m`,
- *   `allow_thread`) held in memory. Never survives a process restart.
+ *   `allow_conversation`) held in memory. Never survives a process restart.
  */
 
 export { PersistentGrantStore } from "./persistent-store.js";

package/src/grants/persistent-store.ts

@@ -11,7 +11,8 @@
  *   to a permissive default when the persistent state is corrupt.
  * - **Atomic writes**: Uses rename-over-tmp to prevent partial writes.
  * - **Deduplication**: Grants are keyed by a canonical hash (the `id`
- *   field) — adding a grant with an existing ID is a no-op.
+ *   field) — adding an active grant with an existing ID is a no-op.
+ *   Revoked grants with the same ID are reactivated (upsert).
  */
 
 import {
@@ -43,6 +44,12 @@ export interface PersistentGrant {
   scope: string;
   /** When the grant was created (epoch ms). */
   createdAt: number;
+  /** The agent session that created this grant. Backfilled to "unknown" on legacy grants. */
+  sessionId: string;
+  /** When the grant was revoked (epoch ms), or undefined if active. */
+  revokedAt?: number;
+  /** Human-readable reason for revocation. */
+  revokedReason?: string;
 }
 
 /** On-disk format for the grants file. */
@@ -60,7 +67,6 @@ const GRANTS_FILENAME = "grants.json";
 
 export class PersistentGrantStore {
   private readonly filePath: string;
-  private cache: PersistentGrant[] | null = null;
   /** Set to true when the store detects corruption; blocks all operations. */
   private corrupt = false;
 
@@ -94,43 +100,81 @@ export class PersistentGrantStore {
 
     // Validate the existing file is readable and well-formed.
     // If it isn't, mark corrupt and throw (fail closed).
-    this.loadFromDisk();
+    const grants = this.loadFromDisk();
+
+    // Migration: backfill sessionId on legacy grants that pre-date the field.
+    let migrated = false;
+    for (const grant of grants) {
+      if (grant.sessionId == null) {
+        (grant as { sessionId: string }).sessionId = "unknown";
+        migrated = true;
+      }
+    }
+    if (migrated) {
+      this.writeToDisk(grants);
+    }
   }
 
   /**
-   * Return all persisted grants.
+   * Return all persisted grants that are not revoked.
    *
    * Returns an empty array if the store has never been initialised
    * (no file on disk). Throws if the store is corrupt.
    */
   getAll(): PersistentGrant[] {
+    return this.getAllIncludingRevoked().filter((g) => g.revokedAt == null);
+  }
+
+  /**
+   * Return all persisted grants including revoked ones.
+   *
+   * Used by the listing handler to expose the full audit trail.
+   */
+  getAllIncludingRevoked(): PersistentGrant[] {
     this.assertNotCorrupt();
-    if (this.cache !== null) return [...this.cache];
     if (!existsSync(this.filePath)) return [];
     return [...this.loadFromDisk()];
   }
 
   /**
-   * Look up a grant by its canonical ID.
+   * Look up a grant by its canonical ID (active grants only).
    *
-   * Returns `undefined` if not found. Throws if the store is corrupt.
+   * Returns `undefined` if not found or revoked. Throws if the store is corrupt.
    */
   getById(id: string): PersistentGrant | undefined {
     return this.getAll().find((g) => g.id === id);
   }
 
   /**
-   * Add a grant. If a grant with the same `id` already exists, this is
-   * a no-op (idempotent deduplication by canonical hash).
+   * Add a grant. If an active grant with the same `id` already exists,
+   * this is a no-op (idempotent deduplication by canonical hash).
+   *
+   * If a revoked grant with the same `id` exists, it is reactivated
+   * with the new grant's fields — this supports the revoke-then-re-approve
+   * workflow where the same proposal hash is re-granted.
    *
-   * Returns `true` if the grant was newly added, `false` if it was a
-   * duplicate.
+   * Returns `true` if the grant was newly added or reactivated, `false`
+   * if it was a duplicate of an already-active grant.
    */
   add(grant: PersistentGrant): boolean {
     this.assertNotCorrupt();
     const grants = this.loadFromDisk();
-    if (grants.some((g) => g.id === grant.id)) {
-      return false;
+    const existing = grants.find((g) => g.id === grant.id);
+    if (existing) {
+      // Already active — deduplicate as before.
+      if (existing.revokedAt == null) {
+        return false;
+      }
+      // Revoked — reactivate with fresh fields.
+      existing.tool = grant.tool;
+      existing.pattern = grant.pattern;
+      existing.scope = grant.scope;
+      existing.createdAt = grant.createdAt;
+      existing.sessionId = grant.sessionId;
+      existing.revokedAt = undefined;
+      existing.revokedReason = undefined;
+      this.writeToDisk(grants);
+      return true;
     }
     grants.push(grant);
     this.writeToDisk(grants);
@@ -138,9 +182,11 @@ export class PersistentGrantStore {
   }
 
   /**
-   * Remove a grant by its canonical ID.
+   * Remove a grant by its canonical ID (hard delete).
    *
    * Returns `true` if the grant was found and removed, `false` otherwise.
+   *
+   * Prefer `markRevoked()` for audit-preserving revocation.
    */
   remove(id: string): boolean {
     this.assertNotCorrupt();
@@ -152,6 +198,25 @@ export class PersistentGrantStore {
     return true;
   }
 
+  /**
+   * Mark a grant as revoked by its canonical ID. The grant remains
+   * on disk for audit purposes but is excluded from `getAll()` and
+   * `getById()` lookups.
+   *
+   * Returns `true` if the grant was found and marked revoked,
+   * `false` if the grant does not exist or is already revoked.
+   */
+  markRevoked(id: string, reason?: string): boolean {
+    this.assertNotCorrupt();
+    const grants = this.loadFromDisk();
+    const grant = grants.find((g) => g.id === id);
+    if (!grant || grant.revokedAt != null) return false;
+    grant.revokedAt = Date.now();
+    grant.revokedReason = reason;
+    this.writeToDisk(grants);
+    return true;
+  }
+
   /**
    * Check whether a grant with the given ID exists.
    */
@@ -210,7 +275,6 @@ export class PersistentGrantStore {
         throw new Error("CES grants file is malformed: grants is not an array");
       }
 
-      this.cache = file.grants;
       return [...file.grants];
     } catch (err) {
       if (this.corrupt) throw err;
@@ -241,7 +305,5 @@ export class PersistentGrantStore {
     // Enforce owner-only permissions even if the file already existed
     // with wider permissions.
     chmodSync(this.filePath, 0o600);
-
-    this.cache = grants;
   }
 }