@vellumai/credential-executor 0.4.55

package/src/subjects/local.ts

@@ -0,0 +1,177 @@
+/**
+ * CES local subject resolution.
+ *
+ * Resolves CES credential handles to their underlying storage subjects
+ * using the shared `@vellumai/credential-storage` primitives. This module
+ * is the CES-side counterpart to the assistant's credential resolver, but
+ * operates independently — it never imports from the assistant daemon.
+ *
+ * Subject resolution is the first phase of credential materialisation:
+ * 1. Parse the handle (via `@vellumai/ces-contracts`)
+ * 2. Look up the metadata/connection record in local storage
+ * 3. Return a resolved subject that the materialiser can consume
+ *
+ * Both `local_static` and `local_oauth` handle types are supported.
+ * Unknown or disconnected handles fail before any outbound work starts.
+ */
+
+import {
+  credentialKey,
+  type OAuthConnectionRecord,
+  type StaticCredentialRecord,
+  StaticCredentialMetadataStore,
+} from "@vellumai/credential-storage";
+import {
+  HandleType,
+  parseHandle,
+  type LocalOAuthHandle,
+  type LocalStaticHandle,
+} from "@vellumai/ces-contracts";
+
+// ---------------------------------------------------------------------------
+// Resolved subject types
+// ---------------------------------------------------------------------------
+
+/**
+ * A resolved local static credential subject. Contains the metadata record
+ * and the secure-key storage key needed to materialise the secret value.
+ */
+export interface ResolvedStaticSubject {
+  type: typeof HandleType.LocalStatic;
+  /** The parsed handle. */
+  handle: LocalStaticHandle;
+  /** Non-secret metadata record from the credential store. */
+  metadata: StaticCredentialRecord;
+  /** Secure-key path where the secret value is stored. */
+  storageKey: string;
+}
+
+/**
+ * A resolved local OAuth credential subject. Contains the connection record
+ * and the connection ID needed to materialise the access token.
+ */
+export interface ResolvedOAuthSubject {
+  type: typeof HandleType.LocalOAuth;
+  /** The parsed handle. */
+  handle: LocalOAuthHandle;
+  /** OAuth connection record from local persistence. */
+  connection: OAuthConnectionRecord;
+}
+
+export type ResolvedLocalSubject =
+  | ResolvedStaticSubject
+  | ResolvedOAuthSubject;
+
+// ---------------------------------------------------------------------------
+// Resolution result
+// ---------------------------------------------------------------------------
+
+export type SubjectResolutionResult =
+  | { ok: true; subject: ResolvedLocalSubject }
+  | { ok: false; error: string };
+
+// ---------------------------------------------------------------------------
+// OAuth connection lookup abstraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Abstraction for looking up local OAuth connection records.
+ *
+ * CES does not import the assistant's SQLite-backed oauth-store. Instead,
+ * callers provide a lightweight lookup interface that can be backed by
+ * any persistence mechanism (JSON file, SQLite, in-memory map).
+ */
+export interface OAuthConnectionLookup {
+  /** Look up a connection by its ID. Returns undefined if not found. */
+  getById(connectionId: string): OAuthConnectionRecord | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Local subject resolver
+// ---------------------------------------------------------------------------
+
+export interface LocalSubjectResolverDeps {
+  /** Metadata store for local static credentials. */
+  metadataStore: StaticCredentialMetadataStore;
+  /** Lookup for local OAuth connections. */
+  oauthConnections: OAuthConnectionLookup;
+}
+
+/**
+ * Resolve a CES credential handle to a local subject.
+ *
+ * Supports `local_static` and `local_oauth` handle types. Returns a
+ * discriminated result so callers can inspect errors without catching
+ * exceptions.
+ *
+ * Resolution is fail-closed: unknown handle types, missing metadata,
+ * and disconnected OAuth connections all return errors before any
+ * outbound work starts.
+ */
+export function resolveLocalSubject(
+  rawHandle: string,
+  deps: LocalSubjectResolverDeps,
+): SubjectResolutionResult {
+  const parseResult = parseHandle(rawHandle);
+  if (!parseResult.ok) {
+    return { ok: false, error: parseResult.error };
+  }
+
+  const parsed = parseResult.handle;
+
+  switch (parsed.type) {
+    case HandleType.LocalStatic: {
+      const metadata = deps.metadataStore.getByServiceField(
+        parsed.service,
+        parsed.field,
+      );
+      if (!metadata) {
+        return {
+          ok: false,
+          error: `No local static credential found for service="${parsed.service}", field="${parsed.field}"`,
+        };
+      }
+      const storageKey = credentialKey(parsed.service, parsed.field);
+      return {
+        ok: true,
+        subject: {
+          type: HandleType.LocalStatic,
+          handle: parsed,
+          metadata,
+          storageKey,
+        },
+      };
+    }
+
+    case HandleType.LocalOAuth: {
+      const connection = deps.oauthConnections.getById(parsed.connectionId);
+      if (!connection) {
+        return {
+          ok: false,
+          error: `No local OAuth connection found for connectionId="${parsed.connectionId}"`,
+        };
+      }
+      // Verify the provider key matches the connection's provider
+      if (connection.providerKey !== parsed.providerKey) {
+        return {
+          ok: false,
+          error: `OAuth connection "${parsed.connectionId}" has providerKey="${connection.providerKey}" but handle specifies "${parsed.providerKey}"`,
+        };
+      }
+      return {
+        ok: true,
+        subject: {
+          type: HandleType.LocalOAuth,
+          handle: parsed,
+          connection,
+        },
+      };
+    }
+
+    default:
+      return {
+        ok: false,
+        error: `Handle type "${parsed.type}" is not a local handle and cannot be resolved by the local subject resolver`,
+      };
+  }
+}

package/src/subjects/managed.ts

@@ -0,0 +1,290 @@
+/**
+ * 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/ces-contracts";
+
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export interface PlatformCatalogEntry {
+  id: string;
+  provider: string;
+  account_info?: string | null;
+  granted_scopes?: 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;
+  /**
+   * 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",
+      ),
+    };
+  }
+
+  // -- Fetch catalog entry --------------------------------------------------
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const catalogUrl = `${options.platformBaseUrl}/v1/ces/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 -------------------------------------------------------
+  let body: { connections?: PlatformCatalogEntry[] };
+  try {
+    body = (await response.json()) as { connections?: PlatformCatalogEntry[] };
+  } catch {
+    return {
+      ok: false,
+      error: new SubjectResolutionError(
+        "INVALID_CATALOG_RESPONSE",
+        "Platform CES catalog returned invalid JSON",
+      ),
+    };
+  }
+
+  if (!body.connections || !Array.isArray(body.connections)) {
+    return {
+      ok: false,
+      error: new SubjectResolutionError(
+        "INVALID_CATALOG_RESPONSE",
+        "Platform CES catalog returned unexpected response format",
+      ),
+    };
+  }
+
+  // -- Find matching connection ---------------------------------------------
+  const entry = body.connections.find(
+    (c) => c.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.id,
+    accountInfo: entry.account_info ?? null,
+    grantedScopes: entry.granted_scopes ?? [],
+    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/toolstore/integrity.ts

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