@vellumai/credential-executor 0.4.55

package/src/toolstore/manifest.ts

@@ -0,0 +1,154 @@
+/**
+ * Toolstore manifest type definitions.
+ *
+ * Describes an approved secure command bundle that CES can publish into
+ * its private immutable toolstore. Each manifest records:
+ *
+ * - **sourceUrl**        — The canonical URL the bundle was fetched from.
+ * - **expectedDigest**   — SHA-256 hex digest that the downloaded bytes
+ *                          must match before publication.
+ * - **bundleId**         — Unique identifier for the command bundle
+ *                          (e.g. "gh-cli", "aws-cli").
+ * - **version**          — Semantic version of the bundle.
+ * - **commandProfiles**  — Profile names from the secure command manifest
+ *                          that this bundle declares.
+ *
+ * ## Publishing rules
+ *
+ * 1. **Only CES can write** — bundles are published into the CES-private
+ *    data root, which the assistant process cannot reach.
+ * 2. **Immutable once published** — a bundle directory keyed by its digest
+ *    is never overwritten. Re-publishing the same digest is a no-op.
+ * 3. **Workspace-origin binaries are never publishable** — bundles must
+ *    come from a known source URL; arbitrary assistant-provided bytes are
+ *    rejected.
+ * 4. **Publication does not grant credentials** — writing a bundle into
+ *    the toolstore is purely a content operation. Credential-use grants
+ *    are managed by a separate subsystem.
+ */
+
+import type { SecureCommandManifest } from "../commands/profiles.js";
+
+// ---------------------------------------------------------------------------
+// Bundle origin
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes the provenance of a bundle.
+ *
+ * `sourceUrl` must be an HTTPS URL. Workspace paths, file:// URLs, and
+ * data: URLs are structurally rejected.
+ */
+export interface BundleOrigin {
+  /** HTTPS URL from which the bundle was fetched. */
+  sourceUrl: string;
+  /** ISO-8601 timestamp of when the bundle was fetched. */
+  fetchedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Toolstore manifest
+// ---------------------------------------------------------------------------
+
+/**
+ * A toolstore manifest describes a single approved secure command bundle.
+ *
+ * This is the metadata stored alongside the bundle contents in the
+ * content-addressed toolstore directory.
+ */
+export interface ToolstoreManifest {
+  /** SHA-256 hex digest of the bundle contents. Content-address key. */
+  digest: string;
+
+  /** Unique identifier for the command bundle. */
+  bundleId: string;
+
+  /** Semantic version of the bundle. */
+  version: string;
+
+  /** Provenance information — where the bundle came from. */
+  origin: BundleOrigin;
+
+  /** Profile names declared in the secure command manifest. */
+  declaredProfiles: string[];
+
+  /**
+   * The full secure command manifest embedded in the toolstore manifest.
+   * Used for runtime validation without needing to re-parse the bundle.
+   */
+  secureCommandManifest: SecureCommandManifest;
+
+  /** ISO-8601 timestamp of when the bundle was published to the toolstore. */
+  publishedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/** Regex for a valid SHA-256 hex digest. */
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+
+/**
+ * Returns true if the given string is a valid SHA-256 hex digest.
+ */
+export function isValidSha256Hex(digest: string): boolean {
+  return SHA256_HEX_PATTERN.test(digest);
+}
+
+/**
+ * Schemes that are structurally rejected as bundle source URLs.
+ * Only HTTPS sources are accepted.
+ */
+const REJECTED_URL_SCHEMES = ["file:", "data:", "blob:", "javascript:"];
+
+/**
+ * Validate a source URL for bundle origin.
+ *
+ * Accepted: HTTPS URLs only.
+ * Rejected: file://, data://, workspace paths, non-URL strings.
+ *
+ * Returns an error message if invalid, or null if valid.
+ */
+export function validateSourceUrl(sourceUrl: string): string | null {
+  if (!sourceUrl || sourceUrl.trim().length === 0) {
+    return "sourceUrl is required and must be non-empty.";
+  }
+
+  // Must be a valid URL
+  let parsed: URL;
+  try {
+    parsed = new URL(sourceUrl);
+  } catch {
+    return `sourceUrl "${sourceUrl}" is not a valid URL. Only HTTPS URLs are accepted.`;
+  }
+
+  // Must be HTTPS
+  if (parsed.protocol !== "https:") {
+    if (REJECTED_URL_SCHEMES.includes(parsed.protocol)) {
+      return `sourceUrl scheme "${parsed.protocol}" is not allowed. Only HTTPS URLs are accepted as bundle sources.`;
+    }
+    return `sourceUrl scheme "${parsed.protocol}" is not allowed. Only HTTPS URLs are accepted.`;
+  }
+
+  return null;
+}
+
+/**
+ * Workspace-origin path patterns that are never publishable as bundle
+ * sources. These catch attempts to publish assistant-provided bytes
+ * directly from the workspace directory.
+ */
+const WORKSPACE_PATH_PATTERNS = [
+  /^~?\/?\.vellum\//,
+  /\/\.vellum\//,
+  /\/workspace\//i,
+] as const;
+
+/**
+ * Returns true if the given path looks like a workspace-origin path
+ * that should never be accepted as a bundle source.
+ */
+export function isWorkspaceOriginPath(path: string): boolean {
+  return WORKSPACE_PATH_PATTERNS.some((pattern) => pattern.test(path));
+}

package/src/toolstore/publish.ts

@@ -0,0 +1,342 @@
+/**
+ * Immutable toolstore publisher.
+ *
+ * Downloads (or re-fetches) secure command bundles inside CES, verifies
+ * their digest against the declared expected value, and writes them into
+ * content-addressed directories within the CES-private data root.
+ *
+ * ## Invariants
+ *
+ * 1. **CES-only writes** — All bundle content is written to the CES
+ *    toolstore directory, which lives under the CES-private data root.
+ *    The assistant process cannot read or write this path.
+ *
+ * 2. **Immutable publications** — Once a digest directory exists, it is
+ *    never overwritten. Re-publishing the same digest is a deduplicated
+ *    no-op that returns success.
+ *
+ * 3. **Digest verification before write** — Downloaded bytes are verified
+ *    against the expected digest before any file is created. A mismatch
+ *    is a hard error; no partial writes occur.
+ *
+ * 4. **No credential grants** — Publishing a bundle into the toolstore
+ *    is a pure content operation. It does not create, modify, or imply
+ *    any credential-use grant.
+ *
+ * 5. **No workspace-origin bundles** — Source URLs that point to the
+ *    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 { getCesToolStoreDir, type CesMode } from "../paths.js";
+import type { SecureCommandManifest } from "../commands/profiles.js";
+import { validateManifest } from "../commands/validator.js";
+import { verifyDigest } from "./integrity.js";
+import {
+  isValidSha256Hex,
+  isWorkspaceOriginPath,
+  validateSourceUrl,
+  type ToolstoreManifest,
+} from "./manifest.js";
+
+// ---------------------------------------------------------------------------
+// Publication result
+// ---------------------------------------------------------------------------
+
+export interface PublishResult {
+  /** Whether the publication succeeded. */
+  success: boolean;
+
+  /**
+   * Whether this was a deduplicated no-op (the digest directory already
+   * existed from a previous publication).
+   */
+  deduplicated: boolean;
+
+  /** The content-addressed directory path where the bundle is stored. */
+  bundlePath: string;
+
+  /** Error message if publication failed (undefined on success). */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Publish request
+// ---------------------------------------------------------------------------
+
+export interface PublishRequest {
+  /** Raw bundle bytes to publish. */
+  bundleBytes: Buffer | Uint8Array;
+
+  /** Expected SHA-256 hex digest of the bundle bytes. */
+  expectedDigest: string;
+
+  /** Unique identifier for the command bundle. */
+  bundleId: string;
+
+  /** Semantic version of the bundle. */
+  version: string;
+
+  /** HTTPS URL from which the bundle was fetched. */
+  sourceUrl: string;
+
+  /** The secure command manifest for this bundle. */
+  secureCommandManifest: SecureCommandManifest;
+
+  /** CES mode override (defaults to auto-detection). */
+  cesMode?: CesMode;
+}
+
+// ---------------------------------------------------------------------------
+// Content-addressed path helpers
+// ---------------------------------------------------------------------------
+
+/** Manifest filename within a content-addressed bundle directory. */
+const MANIFEST_FILENAME = "toolstore-manifest.json";
+
+/** Bundle content filename within a content-addressed bundle directory. */
+const BUNDLE_FILENAME = "bundle.bin";
+
+/**
+ * Return the content-addressed directory path for a given digest.
+ *
+ * Layout: `<toolstoreDir>/<digest>/`
+ */
+export function getBundleDir(
+  toolstoreDir: string,
+  digest: string,
+): string {
+  return join(toolstoreDir, digest);
+}
+
+/**
+ * Return the manifest file path for a given digest.
+ */
+export function getBundleManifestPath(
+  toolstoreDir: string,
+  digest: string,
+): string {
+  return join(getBundleDir(toolstoreDir, digest), MANIFEST_FILENAME);
+}
+
+/**
+ * Return the bundle content file path for a given digest.
+ */
+export function getBundleContentPath(
+  toolstoreDir: string,
+  digest: string,
+): string {
+  return join(getBundleDir(toolstoreDir, digest), BUNDLE_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Publisher
+// ---------------------------------------------------------------------------
+
+/**
+ * Publish a secure command bundle into the CES-private immutable
+ * toolstore.
+ *
+ * This function:
+ * 1. Validates the source URL (HTTPS only, no workspace origins).
+ * 2. Validates the expected digest format.
+ * 3. Validates the secure command manifest.
+ * 4. Verifies the bundle bytes match the expected digest.
+ * 5. Checks for deduplication (returns early if already published).
+ * 6. Writes bundle contents and manifest atomically.
+ *
+ * Returns a {@link PublishResult} describing the outcome.
+ */
+export function publishBundle(request: PublishRequest): PublishResult {
+  const {
+    bundleBytes,
+    expectedDigest,
+    bundleId,
+    version,
+    sourceUrl,
+    secureCommandManifest,
+    cesMode,
+  } = request;
+
+  const toolstoreDir = getCesToolStoreDir(cesMode);
+
+  // -- Validate source URL ------------------------------------------------
+  const urlError = validateSourceUrl(sourceUrl);
+  if (urlError) {
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: `Invalid source URL: ${urlError}`,
+    };
+  }
+
+  // -- Reject workspace-origin paths in the URL ---------------------------
+  try {
+    const parsedUrl = new URL(sourceUrl);
+    if (isWorkspaceOriginPath(parsedUrl.pathname)) {
+      return {
+        success: false,
+        deduplicated: false,
+        bundlePath: "",
+        error: `Source URL path "${parsedUrl.pathname}" appears to be a workspace-origin path. ` +
+          `Workspace-origin binaries are never publishable.`,
+      };
+    }
+  } catch {
+    // URL parsing already validated above
+  }
+
+  // -- Validate digest format ---------------------------------------------
+  if (!isValidSha256Hex(expectedDigest)) {
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: `Invalid expectedDigest "${expectedDigest}". ` +
+        `Must be a 64-character lowercase hex SHA-256 digest.`,
+    };
+  }
+
+  // -- Validate secure command manifest -----------------------------------
+  const manifestValidation = validateManifest(secureCommandManifest);
+  if (!manifestValidation.valid) {
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: `Invalid secure command manifest: ${manifestValidation.errors.join("; ")}`,
+    };
+  }
+
+  // -- Verify bundle digest -----------------------------------------------
+  const digestResult = verifyDigest(bundleBytes, expectedDigest);
+  if (!digestResult.valid) {
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: digestResult.error!,
+    };
+  }
+
+  // -- Deduplication check ------------------------------------------------
+  const bundleDir = getBundleDir(toolstoreDir, expectedDigest);
+  const manifestPath = getBundleManifestPath(toolstoreDir, expectedDigest);
+
+  if (existsSync(bundleDir) && existsSync(manifestPath)) {
+    // Already published — deduplicated no-op
+    return {
+      success: true,
+      deduplicated: true,
+      bundlePath: bundleDir,
+    };
+  }
+
+  // -- Ensure toolstore directory exists -----------------------------------
+  mkdirSync(toolstoreDir, { recursive: true });
+
+  // -- Write bundle atomically --------------------------------------------
+  //
+  // Write to a staging directory first, then rename to the final
+  // content-addressed path. This prevents partial writes from being
+  // visible to readers.
+  const stagingDir = join(toolstoreDir, `.staging-${expectedDigest}-${Date.now()}`);
+  mkdirSync(stagingDir, { recursive: true });
+
+  try {
+    // Write bundle content
+    const stagingBundlePath = join(stagingDir, BUNDLE_FILENAME);
+    writeFileSync(stagingBundlePath, bundleBytes, { mode: 0o444 });
+
+    // Build and write toolstore manifest
+    const toolstoreManifest: ToolstoreManifest = {
+      digest: expectedDigest,
+      bundleId,
+      version,
+      origin: {
+        sourceUrl,
+        fetchedAt: new Date().toISOString(),
+      },
+      declaredProfiles: Object.keys(secureCommandManifest.commandProfiles),
+      secureCommandManifest,
+      publishedAt: new Date().toISOString(),
+    };
+
+    const stagingManifestPath = join(stagingDir, MANIFEST_FILENAME);
+    writeFileSync(
+      stagingManifestPath,
+      JSON.stringify(toolstoreManifest, null, 2) + "\n",
+      { mode: 0o444 },
+    );
+
+    // Rename staging directory to final content-addressed path
+    //
+    // On POSIX, rename() is atomic within a filesystem. Since the
+    // staging dir is in the same parent as the final dir, this is
+    // a same-filesystem rename.
+    renameSync(stagingDir, bundleDir);
+  } catch (err) {
+    // Clean up staging directory on failure
+    try {
+      rmSync(stagingDir, { recursive: true, force: true });
+    } catch {
+      // Best effort cleanup
+    }
+    return {
+      success: false,
+      deduplicated: false,
+      bundlePath: "",
+      error: `Failed to write bundle to toolstore: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  return {
+    success: true,
+    deduplicated: false,
+    bundlePath: bundleDir,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Reader helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a published toolstore manifest by digest.
+ *
+ * Returns null if no bundle with the given digest is published.
+ */
+export function readPublishedManifest(
+  digest: string,
+  cesMode?: CesMode,
+): ToolstoreManifest | null {
+  const toolstoreDir = getCesToolStoreDir(cesMode);
+  const manifestPath = getBundleManifestPath(toolstoreDir, digest);
+
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(manifestPath, "utf-8");
+    return JSON.parse(raw) as ToolstoreManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a bundle with the given digest is published in the toolstore.
+ */
+export function isBundlePublished(
+  digest: string,
+  cesMode?: CesMode,
+): boolean {
+  const toolstoreDir = getCesToolStoreDir(cesMode);
+  const bundleDir = getBundleDir(toolstoreDir, digest);
+  const manifestPath = getBundleManifestPath(toolstoreDir, digest);
+  return existsSync(bundleDir) && existsSync(manifestPath);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}