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

package/src/subjects/managed.ts

@@ -1,311 +0,0 @@
-/**
- * Managed subject resolution for platform OAuth handles.
- *
- * Resolves `platform_oauth:<connection_id>` handles into a normalized
- * subject shape that the rest of CES can treat uniformly alongside local
- * subjects. Managed subjects never carry raw tokens — they carry only
- * the metadata needed to call the platform's token-materialization
- * endpoint at execution time.
- *
- * Subject resolution is the first phase of a two-phase credential flow:
- *   1. **Resolution** (this module) — parse the handle, validate the
- *      connection exists in the platform catalog, and return a subject
- *      descriptor with provider metadata.
- *   2. **Materialization** (`materializers/managed-platform.ts`) — use
- *      the resolved subject to request a short-lived access token from
- *      the platform and inject it into the execution environment.
- *
- * The subject shape is intentionally slim and secret-free so it can be
- * logged, cached in memory, and passed across internal boundaries without
- * risk of leaking credentials.
- */
-
-import {
-  HandleType,
-  parseHandle,
-  type PlatformOAuthHandle,
-} from "@vellumai/service-contracts/credential-rpc";
-
-// ---------------------------------------------------------------------------
-// Common subject interface
-// ---------------------------------------------------------------------------
-
-/**
- * Source discriminator shared by all subject types.
- *
- * - `"local"` — credential lives in the local secure-key backend.
- * - `"managed"` — credential is managed by the platform; tokens are
- *   obtained via the platform's CES token-materialization endpoint.
- */
-export type SubjectSource = "local" | "managed";
-
-/**
- * Common shape that all resolved subjects expose. CES execution paths
- * (HTTP materializer, command materializer) can branch on `source`
- * without knowing the full subject type.
- */
-export interface ResolvedSubject {
-  /** Source of the credential. */
-  source: SubjectSource;
-  /** The raw handle string that was resolved. */
-  handle: string;
-  /** Provider identifier (e.g. "google", "slack", "github"). */
-  provider: string;
-  /** Connection identifier on the platform (managed) or locally. */
-  connectionId: string;
-}
-
-// ---------------------------------------------------------------------------
-// Managed subject shape
-// ---------------------------------------------------------------------------
-
-/**
- * A resolved managed subject — the output of resolving a
- * `platform_oauth:<connection_id>` handle against the platform catalog.
- *
- * This shape carries zero secret material. It is safe to log, serialize,
- * and pass across internal boundaries.
- */
-export interface ManagedSubject extends ResolvedSubject {
-  source: "managed";
-  /** Account info as reported by the platform catalog (e.g. email). */
-  accountInfo: string | null;
-  /** Granted OAuth scopes as reported by the platform catalog. */
-  grantedScopes: string[];
-  /** Connection status from the platform catalog (e.g. "active", "expired"). */
-  status: string;
-}
-
-// ---------------------------------------------------------------------------
-// Platform catalog entry (non-secret subset from the platform response)
-// ---------------------------------------------------------------------------
-
-/**
- * Shape of a single connection entry in the platform catalog response.
- * Only non-secret fields are parsed; token values are never included.
- *
- * Field names match the platform's ManagedConnectionCatalogEntrySerializer:
- *   handle, connection_id, provider, account_label, scopes_granted, status
- */
-export interface PlatformCatalogEntry {
-  handle: string;
-  connection_id: string;
-  provider: string;
-  account_label?: string | null;
-  scopes_granted?: string[];
-  status?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Resolution errors
-// ---------------------------------------------------------------------------
-
-export class SubjectResolutionError extends Error {
-  readonly code: string;
-
-  constructor(code: string, message: string) {
-    super(message);
-    this.name = "SubjectResolutionError";
-    this.code = code;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Resolution options
-// ---------------------------------------------------------------------------
-
-export interface ManagedSubjectResolverOptions {
-  /**
-   * Platform base URL (without trailing slash).
-   * e.g. "https://api.vellum.ai"
-   */
-  platformBaseUrl: string;
-  /**
-   * Assistant API key for authenticating with the platform.
-   */
-  assistantApiKey: string;
-  /**
-   * Platform-assigned assistant UUID. Required for building the
-   * platform catalog URL: /v1/assistants/<id>/oauth/managed/catalog/
-   */
-  assistantId: string;
-  /**
-   * Optional custom fetch implementation (for testing).
-   */
-  fetch?: typeof globalThis.fetch;
-}
-
-// ---------------------------------------------------------------------------
-// Resolution result
-// ---------------------------------------------------------------------------
-
-export type ResolveResult =
-  | { ok: true; subject: ManagedSubject }
-  | { ok: false; error: SubjectResolutionError };
-
-// ---------------------------------------------------------------------------
-// Resolver implementation
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a `platform_oauth:<connection_id>` handle into a managed subject
- * by looking up the connection in the platform's CES catalog.
- *
- * Fail-closed: if the platform cannot be reached, returns an error rather
- * than proceeding without credential validation.
- */
-export async function resolveManagedSubject(
-  handle: string,
-  options: ManagedSubjectResolverOptions,
-): Promise<ResolveResult> {
-  // -- Parse handle ---------------------------------------------------------
-  const parsed = parseHandle(handle);
-  if (!parsed.ok) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError("INVALID_HANDLE", parsed.error),
-    };
-  }
-
-  if (parsed.handle.type !== HandleType.PlatformOAuth) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "WRONG_HANDLE_TYPE",
-        `Expected platform_oauth handle, got ${parsed.handle.type}`,
-      ),
-    };
-  }
-
-  const platformHandle = parsed.handle as PlatformOAuthHandle;
-
-  // -- Validate prerequisites -----------------------------------------------
-  if (!options.platformBaseUrl) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "MISSING_PLATFORM_URL",
-        "Platform base URL is required for managed subject resolution",
-      ),
-    };
-  }
-
-  if (!options.assistantApiKey) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "MISSING_API_KEY",
-        "Assistant API key is required for managed subject resolution",
-      ),
-    };
-  }
-
-  if (!options.assistantId) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "MISSING_ASSISTANT_ID",
-        "Assistant ID is required for managed subject resolution",
-      ),
-    };
-  }
-
-  // -- Fetch catalog entry --------------------------------------------------
-  const fetchFn = options.fetch ?? globalThis.fetch;
-  const catalogUrl = `${options.platformBaseUrl}/v1/assistants/${encodeURIComponent(options.assistantId)}/oauth/managed/catalog/`;
-
-  let response: Response;
-  try {
-    response = await fetchFn(catalogUrl, {
-      method: "GET",
-      headers: {
-        Authorization: `Api-Key ${options.assistantApiKey}`,
-        Accept: "application/json",
-      },
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "PLATFORM_UNREACHABLE",
-        `Failed to reach platform CES catalog: ${sanitizeError(message)}`,
-      ),
-    };
-  }
-
-  if (!response.ok) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        `PLATFORM_HTTP_${response.status}`,
-        `Platform CES catalog returned HTTP ${response.status}`,
-      ),
-    };
-  }
-
-  // -- Parse response -------------------------------------------------------
-  // The platform returns a flat JSON array of catalog entries
-  // (serialized with many=True), not a wrapper object.
-  let entries: PlatformCatalogEntry[];
-  try {
-    entries = (await response.json()) as PlatformCatalogEntry[];
-  } catch {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "INVALID_CATALOG_RESPONSE",
-        "Platform CES catalog returned invalid JSON",
-      ),
-    };
-  }
-
-  if (!Array.isArray(entries)) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "INVALID_CATALOG_RESPONSE",
-        "Platform CES catalog returned unexpected response format",
-      ),
-    };
-  }
-
-  // -- Find matching connection ---------------------------------------------
-  const entry = entries.find(
-    (c) => c.connection_id === platformHandle.connectionId,
-  );
-
-  if (!entry) {
-    return {
-      ok: false,
-      error: new SubjectResolutionError(
-        "CONNECTION_NOT_FOUND",
-        `Connection ${platformHandle.connectionId} not found in platform catalog`,
-      ),
-    };
-  }
-
-  // -- Build managed subject ------------------------------------------------
-  const subject: ManagedSubject = {
-    source: "managed",
-    handle,
-    provider: entry.provider,
-    connectionId: entry.connection_id,
-    accountInfo: entry.account_label ?? null,
-    grantedScopes: entry.scopes_granted ?? [],
-    status: entry.status ?? "unknown",
-  };
-
-  return { ok: true, subject };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Sanitize error messages to avoid leaking secrets (defensive).
- */
-function sanitizeError(message: string): string {
-  return message.replace(/Api-Key\s+\S+/gi, "Api-Key [REDACTED]");
-}

package/src/subjects/policy.ts

@@ -1,79 +0,0 @@
-/**
- * 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/integrity.ts

@@ -1,94 +0,0 @@
-/**
- * Bundle integrity verification.
- *
- * Provides SHA-256 digest computation and verification for secure command
- * bundles. Digests are computed over the raw bundle bytes and compared
- * against the expected digest declared in the toolstore manifest.
- *
- * All digests are lowercase hex-encoded SHA-256 hashes (64 characters).
- */
-
-import { createHash, timingSafeEqual } from "node:crypto";
-
-// ---------------------------------------------------------------------------
-// Digest computation
-// ---------------------------------------------------------------------------
-
-/**
- * Compute the SHA-256 hex digest of arbitrary bytes.
- *
- * Returns a lowercase 64-character hex string.
- */
-export function computeDigest(data: Buffer | Uint8Array): string {
-  return createHash("sha256").update(data).digest("hex");
-}
-
-// ---------------------------------------------------------------------------
-// Digest verification
-// ---------------------------------------------------------------------------
-
-export interface DigestVerificationResult {
-  /** Whether the computed digest matches the expected digest. */
-  valid: boolean;
-  /** The computed digest (always present). */
-  computedDigest: string;
-  /** The expected digest (always present). */
-  expectedDigest: string;
-  /** Human-readable error message when invalid (undefined when valid). */
-  error?: string;
-}
-
-/**
- * Verify that the SHA-256 digest of `data` matches `expectedDigest`.
- *
- * Uses constant-time comparison via `timingSafeEqual` to prevent
- * timing side-channel attacks on digest values.
- */
-export function verifyDigest(
-  data: Buffer | Uint8Array,
-  expectedDigest: string,
-): DigestVerificationResult {
-  const computedDigest = computeDigest(data);
-
-  // Use timing-safe comparison to prevent timing attacks
-  const computedBuf = Buffer.from(computedDigest, "hex");
-  const expectedBuf = Buffer.from(expectedDigest, "hex");
-
-  // If the expected digest is not valid hex (wrong length), fail
-  if (computedBuf.length !== expectedBuf.length || expectedBuf.length !== 32) {
-    return {
-      valid: false,
-      computedDigest,
-      expectedDigest,
-      error: `Digest mismatch: expected "${expectedDigest}" but computed "${computedDigest}". ` +
-        `The bundle contents do not match the declared digest.`,
-    };
-  }
-
-  const match = safeTimingEqual(computedBuf, expectedBuf);
-
-  if (!match) {
-    return {
-      valid: false,
-      computedDigest,
-      expectedDigest,
-      error: `Digest mismatch: expected "${expectedDigest}" but computed "${computedDigest}". ` +
-        `The bundle contents do not match the declared digest.`,
-    };
-  }
-
-  return {
-    valid: true,
-    computedDigest,
-    expectedDigest,
-  };
-}
-
-/**
- * Constant-time buffer comparison. Wraps `crypto.timingSafeEqual`
- * with a length guard (timingSafeEqual throws on length mismatch).
- */
-function safeTimingEqual(a: Buffer, b: Buffer): boolean {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(a, b);
-}

package/src/toolstore/manifest.ts

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