@vellumai/credential-executor 0.4.55 → 0.4.56

package/src/subjects/policy.ts

@@ -0,0 +1,79 @@
+/**
+ * CES credential policy enforcement.
+ *
+ * Enforces credential-level policies (allowedTools, allowedDomains) that were
+ * previously only checked by the pre-CES broker in the assistant daemon.
+ * Without these checks, CES would materialise credentials that the broker
+ * would have rejected — a security regression.
+ *
+ * Policy rules:
+ * - **allowedDomains** — credentials with domain restrictions are scoped to
+ *   browser use on those domains and cannot be used server-side by CES.
+ * - **allowedTools** — if set (even if empty), only the listed tools may
+ *   consume the credential. An empty array means deny-all. CES tool names
+ *   ("make_authenticated_request", "run_authenticated_command") must be in
+ *   the list.
+ */
+
+import type { StaticCredentialRecord } from "@vellumai/credential-storage";
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export interface CredentialPolicyCheckResult {
+  ok: boolean;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Policy check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check credential-level policies before materialisation.
+ *
+ * Returns `{ ok: true }` if the credential may be materialised for the
+ * given CES tool, or `{ ok: false, error }` with a human-readable
+ * rejection message.
+ *
+ * @param metadata  Non-secret metadata record for a local static credential.
+ * @param cesToolName  The CES tool requesting materialisation
+ *   (e.g. "make_authenticated_request" or "run_authenticated_command").
+ */
+export function checkCredentialPolicy(
+  metadata: StaticCredentialRecord,
+  cesToolName: string,
+): CredentialPolicyCheckResult {
+  // -- allowedDomains -------------------------------------------------------
+  // Credentials with domain restrictions are scoped to browser use on those
+  // domains. They cannot be used for server-side operations through CES.
+  if (metadata.allowedDomains && metadata.allowedDomains.length > 0) {
+    return {
+      ok: false,
+      error:
+        `Credential ${metadata.service}/${metadata.field} has domain restrictions ` +
+        `(${metadata.allowedDomains.join(", ")}) and cannot be used for server-side ` +
+        `operations through CES. Remove domain restrictions or use a separate credential.`,
+    };
+  }
+
+  // -- allowedTools ---------------------------------------------------------
+  // If set (even if empty), the CES tool must be in the allowed list.
+  // An empty allowedTools array means no tools are permitted (deny-all).
+  if (metadata.allowedTools) {
+    if (!metadata.allowedTools.includes(cesToolName)) {
+      return {
+        ok: false,
+        error:
+          metadata.allowedTools.length === 0
+            ? `Credential ${metadata.service}/${metadata.field} does not allow any tools.`
+            : `Tool "${cesToolName}" is not allowed to use credential ` +
+              `${metadata.service}/${metadata.field}. ` +
+              `Allowed tools: ${metadata.allowedTools.join(", ")}.`,
+      };
+    }
+  }
+
+  return { ok: true };
+}

package/src/toolstore/publish.ts

@@ -27,8 +27,8 @@
  *    workspace directory or use non-HTTPS schemes are rejected.
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 import { getCesToolStoreDir, type CesMode } from "../paths.js";
 import type { SecureCommandManifest } from "../commands/profiles.js";
@@ -103,16 +103,23 @@ const BUNDLE_FILENAME = "bundle.bin";
  * Return the content-addressed directory path for a given digest.
  *
  * Layout: `<toolstoreDir>/<digest>/`
+ *
+ * @throws {Error} if digest is not a valid SHA-256 hex string.
  */
 export function getBundleDir(
   toolstoreDir: string,
   digest: string,
 ): string {
+  if (!isValidSha256Hex(digest)) {
+    throw new Error(`Invalid digest "${digest}": must be a 64-character lowercase hex SHA-256 digest.`);
+  }
   return join(toolstoreDir, digest);
 }
 
 /**
  * Return the manifest file path for a given digest.
+ *
+ * @throws {Error} if digest is not a valid SHA-256 hex string.
  */
 export function getBundleManifestPath(
   toolstoreDir: string,
@@ -123,6 +130,8 @@ export function getBundleManifestPath(
 
 /**
  * Return the bundle content file path for a given digest.
+ *
+ * @throws {Error} if digest is not a valid SHA-256 hex string.
  */
 export function getBundleContentPath(
   toolstoreDir: string,
@@ -176,15 +185,35 @@ export function publishBundle(request: PublishRequest): PublishResult {
   // -- Reject workspace-origin paths in the URL ---------------------------
   try {
     const parsedUrl = new URL(sourceUrl);
-    if (isWorkspaceOriginPath(parsedUrl.pathname)) {
+    const rawPathname = parsedUrl.pathname;
+
+    // Always check the raw pathname — this must not be skipped.
+    if (isWorkspaceOriginPath(rawPathname)) {
       return {
         success: false,
         deduplicated: false,
         bundlePath: "",
-        error: `Source URL path "${parsedUrl.pathname}" appears to be a workspace-origin path. ` +
+        error: `Source URL path "${rawPathname}" appears to be a workspace-origin path. ` +
           `Workspace-origin binaries are never publishable.`,
       };
     }
+
+    // Also check the decoded pathname for percent-encoded traversals.
+    try {
+      const decodedPathname = decodeURIComponent(rawPathname);
+      if (decodedPathname !== rawPathname && isWorkspaceOriginPath(decodedPathname)) {
+        return {
+          success: false,
+          deduplicated: false,
+          bundlePath: "",
+          error: `Source URL path "${decodedPathname}" (decoded from "${rawPathname}") appears to be a workspace-origin path. ` +
+            `Workspace-origin binaries are never publishable.`,
+        };
+      }
+    } catch {
+      // decodeURIComponent threw URIError on malformed sequences (e.g. %C0%AF).
+      // The raw pathname was already checked above, so we're safe.
+    }
   } catch {
     // URL parsing already validated above
   }
@@ -211,6 +240,32 @@ export function publishBundle(request: PublishRequest): PublishResult {
     };
   }
 
+  // -- Validate manifest metadata matches request -------------------------
+  const metadataMismatches: string[] = [];
+  if (secureCommandManifest.bundleDigest !== expectedDigest) {
+    metadataMismatches.push(
+      `bundleDigest "${secureCommandManifest.bundleDigest}" does not match expectedDigest "${expectedDigest}"`,
+    );
+  }
+  if (secureCommandManifest.bundleId !== bundleId) {
+    metadataMismatches.push(
+      `bundleId "${secureCommandManifest.bundleId}" does not match request bundleId "${bundleId}"`,
+    );
+  }
+  if (secureCommandManifest.version !== version) {
+    metadataMismatches.push(
+      `version "${secureCommandManifest.version}" does not match request version "${version}"`,
+    );
+  }
+  if (metadataMismatches.length > 0) {
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: `Manifest metadata mismatch: ${metadataMismatches.join("; ")}`,
+    };
+  }
+
   // -- Verify bundle digest -----------------------------------------------
   const digestResult = verifyDigest(bundleBytes, expectedDigest);
   if (!digestResult.valid) {
@@ -247,10 +302,85 @@ export function publishBundle(request: PublishRequest): PublishResult {
   mkdirSync(stagingDir, { recursive: true });
 
   try {
-    // Write bundle content
-    const stagingBundlePath = join(stagingDir, BUNDLE_FILENAME);
+    // Write bundle content to a unique staging filename so that if the
+    // archive itself contains a root-level "bundle.bin", extraction won't
+    // collide with the staging archive file.
+    const stagingArchiveName = `.ces-bundle-staging-${Date.now()}.tar.gz`;
+    const stagingBundlePath = join(stagingDir, stagingArchiveName);
     writeFileSync(stagingBundlePath, bundleBytes, { mode: 0o444 });
 
+    // Extract the tar.gz archive into the staging directory.
+    // The archive is expected to contain the runnable bundle contents,
+    // including the entrypoint declared in the manifest.
+    const extractProc = Bun.spawnSync(
+      ["tar", "xzf", stagingBundlePath, "-C", stagingDir],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    if (extractProc.exitCode !== 0) {
+      const stderr = extractProc.stderr
+        ? new TextDecoder().decode(extractProc.stderr).trim()
+        : "unknown error";
+      throw new Error(
+        `Bundle extraction failed (exit code ${extractProc.exitCode}): ${stderr}`,
+      );
+    }
+
+    // Remove the raw archive — the extracted contents replace it
+    try {
+      unlinkSync(stagingBundlePath);
+    } catch {
+      // Best effort — the file may have been overwritten by extraction
+    }
+
+    // Scan for symlinks that escape the bundle directory.
+    // A symlink pointing outside the staging directory could allow the
+    // entrypoint to execute arbitrary binaries on the host.
+    const escapingSymlinks = findEscapingSymlinks(stagingDir);
+    if (escapingSymlinks.length > 0) {
+      throw new Error(
+        `Bundle contains symlinks that point outside the bundle directory: ${escapingSymlinks.join(", ")}. ` +
+        `Symlink escape is not allowed.`,
+      );
+    }
+
+    // Validate that the declared entrypoint resolves inside the staging
+    // directory. A manifest with an absolute or `../`-traversal entrypoint
+    // could make chmod (or later execution) touch files outside the bundle.
+    const realStagingDir = realpathSync(stagingDir);
+    const extractedEntrypoint = resolve(realStagingDir, secureCommandManifest.entrypoint);
+    if (extractedEntrypoint !== realStagingDir && !extractedEntrypoint.startsWith(realStagingDir + "/")) {
+      throw new Error(
+        `Entrypoint "${secureCommandManifest.entrypoint}" resolves outside the bundle directory. ` +
+        `Path traversal in entrypoint values is not allowed.`,
+      );
+    }
+
+    // Check that the entrypoint itself is not a symlink (use lstat to avoid following)
+    try {
+      const entrypointStat = lstatSync(extractedEntrypoint);
+      if (entrypointStat.isSymbolicLink()) {
+        throw new Error(
+          `Entrypoint "${secureCommandManifest.entrypoint}" is a symbolic link. ` +
+          `Symlink entrypoints are not allowed — the entrypoint must be a regular file.`,
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("Symlink entrypoints")) {
+        throw err;
+      }
+      // lstat failed — the file doesn't exist, fall through to existsSync check
+    }
+
+    if (!existsSync(extractedEntrypoint)) {
+      throw new Error(
+        `Entrypoint "${secureCommandManifest.entrypoint}" not found in extracted bundle contents. ` +
+        `The archive must contain the declared entrypoint path.`,
+      );
+    }
+
+    // Make the entrypoint executable
+    chmodSync(extractedEntrypoint, 0o555);
+
     // Build and write toolstore manifest
     const toolstoreManifest: ToolstoreManifest = {
       digest: expectedDigest,
@@ -285,6 +415,14 @@ export function publishBundle(request: PublishRequest): PublishResult {
     } catch {
       // Best effort cleanup
     }
+    // Re-check: another process may have published the same digest concurrently
+    if (existsSync(bundleDir) && existsSync(manifestPath)) {
+      return {
+        success: true,
+        deduplicated: true,
+        bundlePath: bundleDir,
+      };
+    }
     return {
       success: false,
       deduplicated: false,
@@ -307,12 +445,17 @@ export function publishBundle(request: PublishRequest): PublishResult {
 /**
  * Read a published toolstore manifest by digest.
  *
- * Returns null if no bundle with the given digest is published.
+ * Returns null if no bundle with the given digest is published or if the
+ * digest is not a valid SHA-256 hex string.
  */
 export function readPublishedManifest(
   digest: string,
   cesMode?: CesMode,
 ): ToolstoreManifest | null {
+  if (!isValidSha256Hex(digest)) {
+    return null;
+  }
+
   const toolstoreDir = getCesToolStoreDir(cesMode);
   const manifestPath = getBundleManifestPath(toolstoreDir, digest);
 
@@ -328,15 +471,101 @@ export function readPublishedManifest(
   }
 }
 
+/**
+ * Delete a published bundle from the toolstore by digest.
+ *
+ * Removes the entire content-addressed directory for the given digest.
+ * Returns true if the directory existed and was deleted, false if it
+ * did not exist (or the digest was invalid).
+ *
+ * This is used during tool unregistration to ensure that a previously
+ * published bundle cannot be executed after the tool is removed from
+ * the in-memory registry.
+ */
+export function deleteBundleFromToolstore(
+  digest: string,
+  cesMode?: CesMode,
+): boolean {
+  if (!isValidSha256Hex(digest)) {
+    return false;
+  }
+
+  const toolstoreDir = getCesToolStoreDir(cesMode);
+  const bundleDir = getBundleDir(toolstoreDir, digest);
+
+  if (!existsSync(bundleDir)) {
+    return false;
+  }
+
+  rmSync(bundleDir, { recursive: true, force: true });
+  return true;
+}
+
 /**
  * Check if a bundle with the given digest is published in the toolstore.
+ *
+ * Returns false if the digest is not a valid SHA-256 hex string.
  */
 export function isBundlePublished(
   digest: string,
   cesMode?: CesMode,
 ): boolean {
+  if (!isValidSha256Hex(digest)) {
+    return false;
+  }
+
   const toolstoreDir = getCesToolStoreDir(cesMode);
   const bundleDir = getBundleDir(toolstoreDir, digest);
   const manifestPath = getBundleManifestPath(toolstoreDir, digest);
   return existsSync(bundleDir) && existsSync(manifestPath);
 }
+
+// ---------------------------------------------------------------------------
+// Symlink escape detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively scan a directory for symlinks that point outside of it.
+ *
+ * Returns an array of relative paths (from `rootDir`) of symlinks whose
+ * resolved target falls outside `rootDir`.
+ */
+function findEscapingSymlinks(rootDir: string): string[] {
+  const escaping: string[] = [];
+  const realRoot = realpathSync(rootDir);
+
+  function walk(dir: string): void {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      let stat;
+      try {
+        stat = lstatSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isSymbolicLink()) {
+        // Resolve the symlink target relative to its parent directory
+        const linkTarget = readlinkSync(fullPath);
+        const resolvedTarget = resolve(dir, linkTarget);
+        // Check if the resolved target is outside the root directory
+        if (!resolvedTarget.startsWith(realRoot + "/") && resolvedTarget !== realRoot) {
+          const relativePath = fullPath.slice(realRoot.length + 1);
+          escaping.push(relativePath);
+        }
+      } else if (stat.isDirectory()) {
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(realRoot);
+  return escaping;
+}