@vellumai/credential-executor 0.4.55

package/src/materializers/local.ts

@@ -0,0 +1,300 @@
+/**
+ * CES local credential materialisation.
+ *
+ * Materialises credential values from local storage into per-operation
+ * results that the CES execution layer can inject into authenticated
+ * requests or commands. Materialised values never persist to assistant-
+ * visible state — they exist only for the duration of the execution.
+ *
+ * Supports two credential types:
+ *
+ * - **Static secrets** — Retrieved from the secure-key backend using the
+ *   storage key from the resolved subject. Fails if the key is missing.
+ *
+ * - **OAuth tokens** — Retrieved from the secure-key backend using the
+ *   connection's access token path. Automatically refreshes expired tokens
+ *   using the shared `@vellumai/credential-storage` refresh primitives.
+ *   Fails if no access token exists (disconnected connection) or if
+ *   refresh fails.
+ *
+ * Materialisation is fail-closed: missing keys, disconnected connections,
+ * and refresh failures all return errors before any outbound work starts.
+ */
+
+import {
+  type SecureKeyBackend,
+  type TokenRefreshResult,
+  getStoredAccessToken,
+  getStoredRefreshToken,
+  isTokenExpired,
+  RefreshCircuitBreaker,
+  RefreshDeduplicator,
+  persistRefreshedTokens,
+} from "@vellumai/credential-storage";
+import { HandleType } from "@vellumai/ces-contracts";
+
+import type {
+  ResolvedLocalSubject,
+  ResolvedOAuthSubject,
+  ResolvedStaticSubject,
+} from "../subjects/local.js";
+
+// ---------------------------------------------------------------------------
+// Materialisation result
+// ---------------------------------------------------------------------------
+
+/**
+ * A materialised credential value ready for injection into an execution
+ * environment. The value is ephemeral and must not be persisted to any
+ * assistant-visible store.
+ */
+export interface MaterialisedCredential {
+  /** The credential value (secret, token, etc.). */
+  value: string;
+  /** The handle type that produced this value. */
+  handleType: HandleType;
+  /** For OAuth: the token expiry timestamp (null if unknown). */
+  expiresAt?: number | null;
+}
+
+export type MaterialisationResult =
+  | { ok: true; credential: MaterialisedCredential }
+  | { ok: false; error: string };
+
+// ---------------------------------------------------------------------------
+// Token refresh callback
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback for performing the actual OAuth token refresh network call.
+ *
+ * CES delegates the refresh network call to callers so it remains
+ * transport-agnostic. The callback receives the connection ID and
+ * refresh token, and returns a `TokenRefreshResult` from the shared
+ * credential-storage primitives.
+ */
+export type TokenRefreshFn = (
+  connectionId: string,
+  refreshToken: string,
+) => Promise<TokenRefreshResult>;
+
+// ---------------------------------------------------------------------------
+// Local materialiser
+// ---------------------------------------------------------------------------
+
+export interface LocalMaterialiserDeps {
+  /** Secure-key backend for retrieving secret values. */
+  secureKeyBackend: SecureKeyBackend;
+  /** Optional token refresh callback for OAuth tokens. */
+  tokenRefreshFn?: TokenRefreshFn;
+}
+
+/**
+ * Local credential materialiser.
+ *
+ * Stateful: maintains a per-connection circuit breaker and refresh
+ * deduplicator for OAuth token refresh. Create one instance per CES
+ * process lifetime.
+ */
+export class LocalMaterialiser {
+  private readonly backend: SecureKeyBackend;
+  private readonly tokenRefreshFn?: TokenRefreshFn;
+  private readonly circuitBreaker = new RefreshCircuitBreaker();
+  private readonly deduplicator = new RefreshDeduplicator();
+
+  constructor(deps: LocalMaterialiserDeps) {
+    this.backend = deps.secureKeyBackend;
+    this.tokenRefreshFn = deps.tokenRefreshFn;
+  }
+
+  /**
+   * Materialise a resolved local subject into a credential value.
+   *
+   * Dispatches to the appropriate handler based on the subject type.
+   * Returns a discriminated result — never throws for expected failure
+   * modes (missing keys, disconnected connections, expired tokens).
+   */
+  async materialise(
+    subject: ResolvedLocalSubject,
+  ): Promise<MaterialisationResult> {
+    switch (subject.type) {
+      case HandleType.LocalStatic:
+        return this.materialiseStatic(subject);
+      case HandleType.LocalOAuth:
+        return this.materialiseOAuth(subject);
+      default:
+        return {
+          ok: false,
+          error: `Unsupported subject type for local materialisation`,
+        };
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Static secret materialisation
+  // -----------------------------------------------------------------------
+
+  private async materialiseStatic(
+    subject: ResolvedStaticSubject,
+  ): Promise<MaterialisationResult> {
+    const secretValue = await this.backend.get(subject.storageKey);
+    if (secretValue === undefined) {
+      return {
+        ok: false,
+        error: `Secure key "${subject.storageKey}" not found in local credential store. ` +
+          `The credential for service="${subject.metadata.service}", field="${subject.metadata.field}" ` +
+          `has metadata but no secret value stored.`,
+      };
+    }
+
+    return {
+      ok: true,
+      credential: {
+        value: secretValue,
+        handleType: HandleType.LocalStatic,
+      },
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // OAuth token materialisation
+  // -----------------------------------------------------------------------
+
+  private async materialiseOAuth(
+    subject: ResolvedOAuthSubject,
+  ): Promise<MaterialisationResult> {
+    const { connection } = subject;
+    const connectionId = connection.id;
+
+    // 1. Get the stored access token
+    const accessToken = await getStoredAccessToken(
+      this.backend,
+      connectionId,
+    );
+
+    if (!accessToken) {
+      return {
+        ok: false,
+        error: `No access token found for OAuth connection "${connectionId}" ` +
+          `(provider="${connection.providerKey}"). The connection is disconnected.`,
+      };
+    }
+
+    // 2. Check if the token is expired and needs refresh
+    if (
+      isTokenExpired(connection.expiresAt) &&
+      connection.hasRefreshToken
+    ) {
+      return this.refreshAndMaterialise(subject, connectionId);
+    }
+
+    // 3. Token is valid — return it
+    return {
+      ok: true,
+      credential: {
+        value: accessToken,
+        handleType: HandleType.LocalOAuth,
+        expiresAt: connection.expiresAt,
+      },
+    };
+  }
+
+  /**
+   * Refresh an expired OAuth token and return the materialised result.
+   *
+   * Uses the circuit breaker to prevent retry storms and the deduplicator
+   * to coalesce concurrent refresh attempts for the same connection.
+   */
+  private async refreshAndMaterialise(
+    subject: ResolvedOAuthSubject,
+    connectionId: string,
+  ): Promise<MaterialisationResult> {
+    // Check circuit breaker
+    if (this.circuitBreaker.isOpen(connectionId)) {
+      return {
+        ok: false,
+        error: `Token refresh circuit breaker is open for connection "${connectionId}". ` +
+          `Too many consecutive refresh failures. Re-authorization may be required.`,
+      };
+    }
+
+    if (!this.tokenRefreshFn) {
+      return {
+        ok: false,
+        error: `Token for OAuth connection "${connectionId}" is expired but no refresh ` +
+          `function is configured. Re-authorization required.`,
+      };
+    }
+
+    // Get the refresh token
+    const refreshToken = await getStoredRefreshToken(
+      this.backend,
+      connectionId,
+    );
+    if (!refreshToken) {
+      return {
+        ok: false,
+        error: `Token for OAuth connection "${connectionId}" is expired and no refresh ` +
+          `token is available. Re-authorization required.`,
+      };
+    }
+
+    try {
+      // Use deduplicator to prevent concurrent refresh attempts
+      const tokenRefreshFn = this.tokenRefreshFn;
+      const backend = this.backend;
+      const circuitBreaker = this.circuitBreaker;
+
+      const newAccessToken = await this.deduplicator.deduplicate(
+        connectionId,
+        async () => {
+          const result = await tokenRefreshFn(connectionId, refreshToken);
+          if (!result.success) {
+            circuitBreaker.recordFailure(connectionId);
+            throw new Error(result.error);
+          }
+
+          circuitBreaker.recordSuccess(connectionId);
+
+          // Persist the refreshed tokens to the secure-key backend
+          // (but NOT to any assistant-visible state)
+          const persisted = await persistRefreshedTokens(
+            backend,
+            connectionId,
+            {
+              accessToken: result.accessToken,
+              expiresIn: result.expiresAt
+                ? Math.floor((result.expiresAt - Date.now()) / 1000)
+                : null,
+            },
+          );
+
+          return persisted.accessToken;
+        },
+      );
+
+      return {
+        ok: true,
+        credential: {
+          value: newAccessToken,
+          handleType: HandleType.LocalOAuth,
+          expiresAt: null, // Refresh result expiry is tracked internally
+        },
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        error: `Failed to refresh token for OAuth connection "${connectionId}": ${message}`,
+      };
+    }
+  }
+
+  /**
+   * Reset circuit breaker and deduplicator state (primarily for testing).
+   */
+  reset(): void {
+    this.circuitBreaker.clear();
+    this.deduplicator.clear();
+  }
+}

package/src/materializers/managed-platform.ts

@@ -0,0 +1,270 @@
+/**
+ * Managed platform OAuth materializer.
+ *
+ * Materializes a `platform_oauth` handle into a short-lived access token
+ * by calling the platform's CES token-materialization endpoint. The
+ * materialized token is returned to the caller for immediate use (e.g.
+ * injection into an HTTP request or command environment) but is **never**
+ * persisted to any local storage — it exists only in memory for the
+ * duration of the execution.
+ *
+ * Security invariants:
+ * - Materialized tokens are never written to disk.
+ * - Materialized tokens are never logged (not even partially).
+ * - Platform errors are surfaced as structured errors without leaking secrets.
+ * - If the platform cannot be reached, materialization fails closed.
+ *
+ * The materializer expects a resolved `ManagedSubject` from
+ * `subjects/managed.ts`. It does not perform handle parsing or catalog
+ * lookup — that is the resolver's responsibility.
+ */
+
+import type { ManagedSubject } from "../subjects/managed.js";
+
+// ---------------------------------------------------------------------------
+// Materialization result
+// ---------------------------------------------------------------------------
+
+/**
+ * Successful materialization result.
+ *
+ * The `accessToken` field contains the short-lived token obtained from
+ * the platform. Callers MUST NOT persist this value — it should be used
+ * immediately for request injection and then discarded.
+ */
+export interface MaterializedToken {
+  /** The short-lived access token. */
+  accessToken: string;
+  /** Token type (typically "Bearer"). */
+  tokenType: string;
+  /** Epoch ms when the token expires (null if the platform didn't report expiry). */
+  expiresAt: number | null;
+  /** Provider key (mirrored from the subject for convenience). */
+  provider: string;
+  /** Connection ID (mirrored from the subject for convenience). */
+  connectionId: string;
+}
+
+export type MaterializeResult =
+  | { ok: true; token: MaterializedToken }
+  | { ok: false; error: MaterializationError };
+
+// ---------------------------------------------------------------------------
+// Materialization errors
+// ---------------------------------------------------------------------------
+
+export class MaterializationError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "MaterializationError";
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Platform token response shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of the platform's CES token-materialization response.
+ *
+ * The platform issues a short-lived access token for the specified
+ * connection. The token is pre-authorized for the scopes granted on
+ * the connection.
+ */
+interface PlatformTokenResponse {
+  access_token: string;
+  token_type?: string;
+  /** Seconds until the token expires. */
+  expires_in?: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Materializer options
+// ---------------------------------------------------------------------------
+
+export interface ManagedMaterializerOptions {
+  /**
+   * Platform base URL (without trailing slash).
+   */
+  platformBaseUrl: string;
+  /**
+   * Assistant API key for authenticating with the platform.
+   */
+  assistantApiKey: string;
+  /**
+   * Optional custom fetch implementation (for testing).
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
+// ---------------------------------------------------------------------------
+// Materializer implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Materialize a managed OAuth subject into a short-lived access token
+ * by calling the platform's token-materialization endpoint.
+ *
+ * The endpoint is:
+ *   POST {platformBaseUrl}/v1/ces/connections/{connectionId}/materialize
+ *
+ * The platform validates the assistant API key, checks that the connection
+ * is active, and returns a fresh access token (refreshing upstream if
+ * needed).
+ *
+ * Fail-closed: any error results in a structured `MaterializationError`
+ * rather than a partial or fallback result.
+ */
+export async function materializeManagedToken(
+  subject: ManagedSubject,
+  options: ManagedMaterializerOptions,
+): Promise<MaterializeResult> {
+  // -- Validate prerequisites -----------------------------------------------
+  if (!options.platformBaseUrl) {
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "MISSING_PLATFORM_URL",
+        "Platform base URL is required for managed token materialization",
+      ),
+    };
+  }
+
+  if (!options.assistantApiKey) {
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "MISSING_API_KEY",
+        "Assistant API key is required for managed token materialization",
+      ),
+    };
+  }
+
+  // -- Call platform token endpoint -----------------------------------------
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const materializeUrl =
+    `${options.platformBaseUrl}/v1/ces/connections/${subject.connectionId}/materialize`;
+
+  let response: Response;
+  try {
+    response = await fetchFn(materializeUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Api-Key ${options.assistantApiKey}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({}),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "PLATFORM_UNREACHABLE",
+        `Failed to reach platform token endpoint: ${sanitizeError(message)}`,
+      ),
+    };
+  }
+
+  // -- Handle error responses -----------------------------------------------
+  if (!response.ok) {
+    return {
+      ok: false,
+      error: mapPlatformError(response.status, subject.connectionId),
+    };
+  }
+
+  // -- Parse token response -------------------------------------------------
+  let body: PlatformTokenResponse;
+  try {
+    body = (await response.json()) as PlatformTokenResponse;
+  } catch {
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "INVALID_TOKEN_RESPONSE",
+        "Platform token endpoint returned invalid JSON",
+      ),
+    };
+  }
+
+  if (!body.access_token || typeof body.access_token !== "string") {
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "INVALID_TOKEN_RESPONSE",
+        "Platform token response missing access_token",
+      ),
+    };
+  }
+
+  // -- Build materialized token ---------------------------------------------
+  const expiresAt = computeExpiresAt(body.expires_in);
+
+  const token: MaterializedToken = {
+    accessToken: body.access_token,
+    tokenType: body.token_type ?? "Bearer",
+    expiresAt,
+    provider: subject.provider,
+    connectionId: subject.connectionId,
+  };
+
+  return { ok: true, token };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a platform HTTP error status to a structured MaterializationError.
+ */
+function mapPlatformError(
+  status: number,
+  connectionId: string,
+): MaterializationError {
+  switch (status) {
+    case 401:
+      return new MaterializationError(
+        "PLATFORM_AUTH_FAILED",
+        "Assistant API key is invalid or expired (HTTP 401)",
+      );
+    case 403:
+      return new MaterializationError(
+        "PLATFORM_FORBIDDEN",
+        "Assistant is not authorized to materialize this connection (HTTP 403)",
+      );
+    case 404:
+      return new MaterializationError(
+        "CONNECTION_NOT_FOUND",
+        `Connection ${connectionId} not found on the platform (HTTP 404)`,
+      );
+    default:
+      return new MaterializationError(
+        `PLATFORM_HTTP_${status}`,
+        `Platform token endpoint returned HTTP ${status}`,
+      );
+  }
+}
+
+/**
+ * Compute the absolute expiry timestamp from an `expires_in` seconds value.
+ * Returns null if the value is missing or zero.
+ */
+function computeExpiresAt(
+  expiresIn: number | null | undefined,
+): number | null {
+  if (expiresIn == null || expiresIn <= 0) return null;
+  return Date.now() + expiresIn * 1000;
+}
+
+/**
+ * Sanitize error messages to avoid leaking secrets.
+ */
+function sanitizeError(message: string): string {
+  return message.replace(/Api-Key\s+\S+/gi, "Api-Key [REDACTED]");
+}

package/src/paths.ts

@@ -0,0 +1,137 @@
+/**
+ * CES private data-root layout.
+ *
+ * Defines the directory structure for CES-private durable state (grants,
+ * audit logs, tool store). This state is never stored on the assistant-visible
+ * workspace/data root — it lives in a CES-only path that the assistant process
+ * cannot read or write.
+ *
+ * Two modes:
+ *
+ * - **Local**: CES private state lives under the Vellum root's `protected/`
+ *   directory at `<rootDir>/protected/credential-executor/`.
+ *
+ * - **Managed**: CES private state lives at `/ces-data`, a dedicated volume
+ *   mounted only into the CES container. The assistant container never sees
+ *   this volume.
+ *
+ * The assistant-visible data root (where workspace, embeddings, etc. live)
+ * is a separate path and must never be used for CES-private writes.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Mode detection
+// ---------------------------------------------------------------------------
+
+export type CesMode = "local" | "managed";
+
+/**
+ * Determine the CES operating mode from the environment.
+ *
+ * `CES_MODE=managed` is set explicitly in managed container entrypoints.
+ * Everything else defaults to local.
+ */
+export function getCesMode(): CesMode {
+  return process.env["CES_MODE"] === "managed" ? "managed" : "local";
+}
+
+// ---------------------------------------------------------------------------
+// Root directory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Vellum root directory, respecting `BASE_DATA_DIR` for
+ * multi-instance deployments. Mirrors the logic in `assistant/src/util/platform.ts`.
+ */
+function getVellumRootDir(): string {
+  const baseDataDir = process.env["BASE_DATA_DIR"]?.trim();
+  return join(baseDataDir || homedir(), ".vellum");
+}
+
+/** Well-known managed CES data root (dedicated volume mount). */
+const MANAGED_CES_DATA_ROOT = "/ces-data";
+
+/**
+ * Return the CES-private data root.
+ *
+ * - Local: `<vellumRoot>/protected/credential-executor/`
+ * - Managed: `/ces-data`
+ */
+export function getCesDataRoot(mode?: CesMode): string {
+  const resolvedMode = mode ?? getCesMode();
+  if (resolvedMode === "managed") {
+    return MANAGED_CES_DATA_ROOT;
+  }
+  return join(getVellumRootDir(), "protected", "credential-executor");
+}
+
+// ---------------------------------------------------------------------------
+// Subdirectory layout
+// ---------------------------------------------------------------------------
+
+/** Directory for CES grant persistence. */
+export function getCesGrantsDir(mode?: CesMode): string {
+  return join(getCesDataRoot(mode), "grants");
+}
+
+/** Directory for CES audit log persistence. */
+export function getCesAuditDir(mode?: CesMode): string {
+  return join(getCesDataRoot(mode), "audit");
+}
+
+/** Directory for CES secure tool store (registered secure command tools). */
+export function getCesToolStoreDir(mode?: CesMode): string {
+  return join(getCesDataRoot(mode), "toolstore");
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap socket path (managed mode only)
+// ---------------------------------------------------------------------------
+
+/** Default directory for the bootstrap Unix socket shared volume. */
+const BOOTSTRAP_SOCKET_DIR = "/run/ces";
+
+/** Default bootstrap socket filename. */
+const BOOTSTRAP_SOCKET_NAME = "ces.sock";
+
+/**
+ * Return the path to the bootstrap Unix socket.
+ *
+ * In managed mode, CES listens on this socket for exactly one assistant
+ * connection, then unlinks it. The path is on a shared `emptyDir` volume
+ * visible to both containers.
+ *
+ * Can be overridden via `CES_BOOTSTRAP_SOCKET` env var.
+ */
+export function getBootstrapSocketPath(): string {
+  return (
+    process.env["CES_BOOTSTRAP_SOCKET"] ??
+    join(BOOTSTRAP_SOCKET_DIR, BOOTSTRAP_SOCKET_NAME)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Health port (managed mode only)
+// ---------------------------------------------------------------------------
+
+/** Default health probe port for managed CES. */
+const DEFAULT_HEALTH_PORT = 7841;
+
+/**
+ * Return the health probe port for managed mode.
+ *
+ * Health probes are served on a dedicated HTTP port, separate from the
+ * Unix socket command transport. This ensures liveness/readiness probes
+ * work without a Unix socket client.
+ */
+export function getHealthPort(): number {
+  const envPort = process.env["CES_HEALTH_PORT"];
+  if (envPort) {
+    const parsed = parseInt(envPort, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_HEALTH_PORT;
+}