@vellumai/credential-executor 0.4.55 → 0.4.56

package/src/materializers/managed-platform.ts

@@ -70,6 +70,9 @@ export class MaterializationError extends Error {
 /**
  * Shape of the platform's CES token-materialization response.
  *
+ * Field names match the platform's ManagedTokenMaterializeResponseSerializer:
+ *   access_token, token_type, expires_at, provider, handle
+ *
  * The platform issues a short-lived access token for the specified
  * connection. The token is pre-authorized for the scopes granted on
  * the connection.
@@ -77,8 +80,10 @@ export class MaterializationError extends Error {
 interface PlatformTokenResponse {
   access_token: string;
   token_type?: string;
-  /** Seconds until the token expires. */
-  expires_in?: number | null;
+  /** ISO-8601 datetime when the token expires (null if no expiry). */
+  expires_at?: string | null;
+  provider?: string;
+  handle?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -94,6 +99,11 @@ export interface ManagedMaterializerOptions {
    * Assistant API key for authenticating with the platform.
    */
   assistantApiKey: string;
+  /**
+   * Platform-assigned assistant UUID. Required for building the
+   * platform materialize URL: /v1/assistants/<id>/oauth/managed/materialize/
+   */
+  assistantId: string;
   /**
    * Optional custom fetch implementation (for testing).
    */
@@ -109,7 +119,9 @@ export interface ManagedMaterializerOptions {
  * by calling the platform's token-materialization endpoint.
  *
  * The endpoint is:
- *   POST {platformBaseUrl}/v1/ces/connections/{connectionId}/materialize
+ *   POST {platformBaseUrl}/v1/assistants/{assistantId}/oauth/managed/materialize/
+ *
+ * The request body contains `{ connection_id: <uuid> }`.
  *
  * The platform validates the assistant API key, checks that the connection
  * is active, and returns a fresh access token (refreshing upstream if
@@ -120,7 +132,7 @@ export interface ManagedMaterializerOptions {
  */
 export async function materializeManagedToken(
   subject: ManagedSubject,
-  options: ManagedMaterializerOptions,
+  options: ManagedMaterializerOptions
 ): Promise<MaterializeResult> {
   // -- Validate prerequisites -----------------------------------------------
   if (!options.platformBaseUrl) {
@@ -128,7 +140,7 @@ export async function materializeManagedToken(
       ok: false,
       error: new MaterializationError(
         "MISSING_PLATFORM_URL",
-        "Platform base URL is required for managed token materialization",
+        "Platform base URL is required for managed token materialization"
       ),
     };
   }
@@ -138,15 +150,28 @@ export async function materializeManagedToken(
       ok: false,
       error: new MaterializationError(
         "MISSING_API_KEY",
-        "Assistant API key is required for managed token materialization",
+        "Assistant API key is required for managed token materialization"
+      ),
+    };
+  }
+
+  if (!options.assistantId) {
+    return {
+      ok: false,
+      error: new MaterializationError(
+        "MISSING_ASSISTANT_ID",
+        "Assistant ID 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`;
+  const materializeUrl = `${
+    options.platformBaseUrl
+  }/v1/assistants/${encodeURIComponent(
+    options.assistantId
+  )}/oauth/managed/materialize/`;
 
   let response: Response;
   try {
@@ -157,7 +182,7 @@ export async function materializeManagedToken(
         Accept: "application/json",
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({}),
+      body: JSON.stringify({ connection_id: subject.connectionId }),
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -165,7 +190,7 @@ export async function materializeManagedToken(
       ok: false,
       error: new MaterializationError(
         "PLATFORM_UNREACHABLE",
-        `Failed to reach platform token endpoint: ${sanitizeError(message)}`,
+        `Failed to reach platform token endpoint: ${sanitizeError(message)}`
       ),
     };
   }
@@ -187,7 +212,7 @@ export async function materializeManagedToken(
       ok: false,
       error: new MaterializationError(
         "INVALID_TOKEN_RESPONSE",
-        "Platform token endpoint returned invalid JSON",
+        "Platform token endpoint returned invalid JSON"
       ),
     };
   }
@@ -197,13 +222,13 @@ export async function materializeManagedToken(
       ok: false,
       error: new MaterializationError(
         "INVALID_TOKEN_RESPONSE",
-        "Platform token response missing access_token",
+        "Platform token response missing access_token"
       ),
     };
   }
 
   // -- Build materialized token ---------------------------------------------
-  const expiresAt = computeExpiresAt(body.expires_in);
+  const expiresAt = parseExpiresAt(body.expires_at);
 
   const token: MaterializedToken = {
     accessToken: body.access_token,
@@ -225,41 +250,41 @@ export async function materializeManagedToken(
  */
 function mapPlatformError(
   status: number,
-  connectionId: string,
+  connectionId: string
 ): MaterializationError {
   switch (status) {
     case 401:
       return new MaterializationError(
         "PLATFORM_AUTH_FAILED",
-        "Assistant API key is invalid or expired (HTTP 401)",
+        "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)",
+        "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)`,
+        `Connection ${connectionId} not found on the platform (HTTP 404)`
       );
     default:
       return new MaterializationError(
         `PLATFORM_HTTP_${status}`,
-        `Platform token endpoint returned 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.
+ * Parse an ISO-8601 `expires_at` datetime string into epoch milliseconds.
+ * Returns null if the value is missing or invalid.
  */
-function computeExpiresAt(
-  expiresIn: number | null | undefined,
-): number | null {
-  if (expiresIn == null || expiresIn <= 0) return null;
-  return Date.now() + expiresIn * 1000;
+function parseExpiresAt(expiresAt: string | null | undefined): number | null {
+  if (expiresAt == null) return null;
+  const ts = new Date(expiresAt).getTime();
+  if (Number.isNaN(ts)) return null;
+  return ts;
 }
 
 /**

package/src/paths.ts

@@ -11,9 +11,9 @@
  * - **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.
+ * - **Managed**: CES private state lives at `/ces-data` by default
+ *   (overridable via `CES_DATA_DIR` env var). The assistant container never
+ *   sees this path.
  *
  * The assistant-visible data root (where workspace, embeddings, etc. live)
  * is a separate path and must never be used for CES-private writes.
@@ -51,19 +51,27 @@ function getVellumRootDir(): string {
   return join(baseDataDir || homedir(), ".vellum");
 }
 
-/** Well-known managed CES data root (dedicated volume mount). */
-const MANAGED_CES_DATA_ROOT = "/ces-data";
+/**
+ * Default managed CES data root.
+ *
+ * Defaults to `/ces-data` — the platform template provisions this path
+ * via the `CES_DATA_DIR` env var and a dedicated PVC.
+ */
+const DEFAULT_MANAGED_CES_DATA_ROOT = "/ces-data";
 
 /**
  * Return the CES-private data root.
  *
  * - Local: `<vellumRoot>/protected/credential-executor/`
- * - Managed: `/ces-data`
+ * - Managed: `CES_DATA_DIR` env var, or `/ces-data` by default
  */
 export function getCesDataRoot(mode?: CesMode): string {
   const resolvedMode = mode ?? getCesMode();
   if (resolvedMode === "managed") {
-    return MANAGED_CES_DATA_ROOT;
+    return (
+      process.env["CES_DATA_DIR"] ??
+      DEFAULT_MANAGED_CES_DATA_ROOT
+    );
   }
   return join(getVellumRootDir(), "protected", "credential-executor");
 }
@@ -92,7 +100,7 @@ export function getCesToolStoreDir(mode?: CesMode): string {
 // ---------------------------------------------------------------------------
 
 /** Default directory for the bootstrap Unix socket shared volume. */
-const BOOTSTRAP_SOCKET_DIR = "/run/ces";
+const BOOTSTRAP_SOCKET_DIR = "/run/ces-bootstrap";
 
 /** Default bootstrap socket filename. */
 const BOOTSTRAP_SOCKET_NAME = "ces.sock";
@@ -104,9 +112,19 @@ const BOOTSTRAP_SOCKET_NAME = "ces.sock";
  * 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.
+ * Priority:
+ * 1. `CES_BOOTSTRAP_SOCKET_DIR` env var (directory) — appends `ces.sock`
+ * 2. `CES_BOOTSTRAP_SOCKET` env var (full file path override)
+ * 3. Hardcoded default: `/run/ces-bootstrap/ces.sock`
+ *
+ * The pod template exports `CES_BOOTSTRAP_SOCKET_DIR`; the full-path
+ * override is kept for local testing convenience.
  */
 export function getBootstrapSocketPath(): string {
+  const dir = process.env["CES_BOOTSTRAP_SOCKET_DIR"];
+  if (dir) {
+    return join(dir, BOOTSTRAP_SOCKET_NAME);
+  }
   return (
     process.env["CES_BOOTSTRAP_SOCKET"] ??
     join(BOOTSTRAP_SOCKET_DIR, BOOTSTRAP_SOCKET_NAME)
@@ -118,7 +136,7 @@ export function getBootstrapSocketPath(): string {
 // ---------------------------------------------------------------------------
 
 /** Default health probe port for managed CES. */
-const DEFAULT_HEALTH_PORT = 7841;
+const DEFAULT_HEALTH_PORT = 8090;
 
 /**
  * Return the health probe port for managed mode.

package/src/server.ts

@@ -20,6 +20,8 @@ import {
   CES_PROTOCOL_VERSION,
   CesRpcMethod,
   CesRpcSchemas,
+  hashProposal,
+  type CommandGrantProposal,
   type HandshakeAck,
   type HandshakeRequest,
   type MakeAuthenticatedRequest,
@@ -32,12 +34,16 @@ import {
   TransportMessageSchema,
 } from "@vellumai/ces-contracts";
 
+import { resolve } from "node:path";
+
 import {
   executeAuthenticatedCommand,
   type CommandExecutorDeps,
   type ExecuteCommandRequest,
 } from "./commands/executor.js";
 
+import { validateContainedPath } from "./commands/workspace.js";
+
 import {
   executeAuthenticatedHttpRequest,
   type HttpExecutorDeps,
@@ -47,6 +53,15 @@ import {
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * Mutable reference to the current session ID. Allows handlers that are
+ * registered before the RPC handshake to read the actual handshake session
+ * ID at call time (after the handshake completes and sets `.current`).
+ */
+export interface SessionIdRef {
+  current: string;
+}
+
 /**
  * Handler function for a single RPC method. Receives the validated
  * request payload and returns the response payload (or throws).
@@ -73,6 +88,10 @@ export interface CesServerOptions {
   logger?: Pick<Console, "log" | "warn" | "error">;
   /** Optional abort signal to shut down the server. */
   signal?: AbortSignal;
+  /** Callback invoked when the handshake completes with the negotiated session ID and optional API key. */
+  onHandshakeComplete?: (sessionId: string, assistantApiKey?: string) => void;
+  /** Callback invoked when the assistant pushes an updated API key after hatch. */
+  onApiKeyUpdate?: (assistantApiKey: string) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -85,6 +104,7 @@ export class CesRpcServer {
   private readonly handlers: RpcHandlerRegistry;
   private readonly logger: Pick<Console, "log" | "warn" | "error">;
   private readonly signal?: AbortSignal;
+  private readonly onHandshakeComplete?: (sessionId: string, assistantApiKey?: string) => void;
 
   private handshakeComplete = false;
   private sessionId: string | null = null;
@@ -97,6 +117,17 @@ export class CesRpcServer {
     this.handlers = options.handlers;
     this.logger = options.logger ?? console;
     this.signal = options.signal;
+    this.onHandshakeComplete = options.onHandshakeComplete;
+
+    // Auto-register the update_managed_credential handler if a callback is provided.
+    if (options.onApiKeyUpdate) {
+      const onUpdate = options.onApiKeyUpdate;
+      this.handlers[CesRpcMethod.UpdateManagedCredential] = (request: unknown) => {
+        const { assistantApiKey } = request as { assistantApiKey: string };
+        onUpdate(assistantApiKey);
+        return { updated: true };
+      };
+    }
   }
 
   /**
@@ -154,9 +185,14 @@ export class CesRpcServer {
     return this.sessionId;
   }
 
-  /** Shut down the server gracefully. */
+  /** Shut down the server gracefully, destroying transport streams. */
   close(): void {
+    if (this.closed) return;
     this.closed = true;
+    this.input.destroy();
+    if (typeof (this.output as any).destroy === "function") {
+      this.output.destroy();
+    }
   }
 
   // -----------------------------------------------------------------------
@@ -195,9 +231,23 @@ export class CesRpcServer {
     const msg = msgResult.data as TransportMessage;
 
     if (msg.type === "handshake_request") {
+      if (this.handshakeComplete) {
+        this.logger.warn("[ces-server] Duplicate handshake_request after session established; rejecting");
+        const ack: HandshakeAck = {
+          type: "handshake_ack",
+          protocolVersion: CES_PROTOCOL_VERSION,
+          sessionId: (msg as HandshakeRequest).sessionId,
+          accepted: false,
+          reason: "Session already established",
+        };
+        this.sendMessage(ack);
+        return;
+      }
       this.handleHandshake(msg as HandshakeRequest);
     } else if (msg.type === "rpc") {
-      this.handleRpcEnvelope(msg as unknown as RpcEnvelope);
+      this.handleRpcEnvelope(msg as unknown as RpcEnvelope).catch((err) => {
+        this.logger.error(`[ces-server] Unhandled error in RPC handler: ${err}`);
+      });
     } else {
       this.logger.warn("[ces-server] Unexpected message type:", msg.type);
     }
@@ -217,6 +267,7 @@ export class CesRpcServer {
       this.handshakeComplete = true;
       this.sessionId = req.sessionId;
       this.logger.log(`[ces-server] Handshake accepted for session ${req.sessionId}`);
+      this.onHandshakeComplete?.(req.sessionId, req.assistantApiKey);
     } else {
       this.logger.warn(
         `[ces-server] Handshake rejected: version mismatch (got ${req.protocolVersion}, expected ${CES_PROTOCOL_VERSION})`,
@@ -406,14 +457,46 @@ export function createRunAuthenticatedCommandHandler(
       };
     }
 
+    // Validate cwd when inputs or outputs are present — the workspace
+    // staging/copyback pipeline resolves paths relative to workspaceDir,
+    // so an unvalidated cwd could let a caller read/write outside the
+    // assistant workspace.
+    const workspaceDir = request.cwd ?? options.defaultWorkspaceDir;
+    const hasWorkspaceIO =
+      (request.inputs && request.inputs.length > 0) ||
+      (request.outputs && request.outputs.length > 0);
+
+    if (hasWorkspaceIO && request.cwd) {
+      const resolvedCwd = resolve(request.cwd);
+      const cwdError = validateContainedPath(
+        resolvedCwd,
+        options.defaultWorkspaceDir,
+        "Command cwd",
+      );
+      if (cwdError) {
+        return {
+          success: false,
+          error: {
+            code: "INVALID_CWD",
+            message:
+              `cwd cannot be used with inputs/outputs when it resolves outside ` +
+              `the workspace directory: ${cwdError}`,
+          },
+        };
+      }
+    }
+
     const execRequest: ExecuteCommandRequest = {
       bundleDigest: parseResult.bundleDigest,
       profileName: parseResult.profileName,
       credentialHandle: request.credentialHandle,
       argv: parseResult.argv,
-      workspaceDir: request.cwd ?? options.defaultWorkspaceDir,
+      workspaceDir,
+      inputs: request.inputs,
+      outputs: request.outputs,
       purpose: request.purpose,
       grantId: request.grantId,
+      conversationId: request.conversationId,
     };
 
     const result = await executeAuthenticatedCommand(
@@ -421,6 +504,35 @@ export function createRunAuthenticatedCommandHandler(
       options.executorDeps,
     );
 
+    // If the failure was due to a missing grant, return a structured
+    // APPROVAL_REQUIRED response with the proposal so the approval
+    // bridge can activate.
+    if (!result.success && result.approvalRequired) {
+      const { credentialHandle, bundleDigest, profileName, command, purpose } =
+        result.approvalRequired;
+
+      const proposal: CommandGrantProposal = {
+        type: "command",
+        credentialHandle,
+        command,
+        purpose,
+        allowedCommandPatterns: [`${credentialHandle}:${bundleDigest}:${profileName}`],
+      };
+
+      return {
+        success: false,
+        error: {
+          code: "APPROVAL_REQUIRED",
+          message: `No active grant covers this command. Approval is required.`,
+          details: {
+            proposal,
+            proposalHash: hashProposal(proposal),
+          },
+        },
+        auditId: result.auditId,
+      };
+    }
+
     return {
       success: result.success,
       exitCode: result.exitCode,
@@ -561,6 +673,8 @@ export function createManageSecureCommandToolHandler(
     if (!request.sourceUrl) missing.push("sourceUrl");
     if (!request.sha256) missing.push("sha256");
     if (!request.credentialHandle) missing.push("credentialHandle");
+    if (!request.description) missing.push("description");
+    if (!request.secureCommandManifest) missing.push("secureCommandManifest");
     if (missing.length > 0) {
       return {
         success: false,
@@ -571,6 +685,29 @@ export function createManageSecureCommandToolHandler(
       };
     }
 
+    // Validate HTTPS before downloading — CES is the security boundary
+    // and must not rely on the caller for URL scheme validation.
+    try {
+      const parsed = new URL(request.sourceUrl!);
+      if (parsed.protocol !== "https:") {
+        return {
+          success: false,
+          error: {
+            code: "INVALID_SOURCE_URL",
+            message: "sourceUrl must use HTTPS for secure bundle downloads.",
+          },
+        };
+      }
+    } catch {
+      return {
+        success: false,
+        error: {
+          code: "INVALID_SOURCE_URL",
+          message: "sourceUrl is not a valid URL.",
+        },
+      };
+    }
+
     // Download the bundle
     let bundleBytes: Buffer | Uint8Array;
     try {
@@ -585,6 +722,11 @@ export function createManageSecureCommandToolHandler(
       };
     }
 
+    // The caller provides the full secure command manifest via the RPC
+    // payload. Cast to the internal type — publishBundle() validates it.
+    const secureCommandManifest =
+      request.secureCommandManifest as unknown as import("./commands/profiles.js").SecureCommandManifest;
+
     // Publish into the immutable toolstore (includes digest verification)
     const publishResult = deps.publishBundle({
       bundleBytes,
@@ -592,13 +734,7 @@ export function createManageSecureCommandToolHandler(
       bundleId: request.bundleId!,
       version: request.version!,
       sourceUrl: request.sourceUrl!,
-      // The secure command manifest is embedded in the bundle; for now
-      // pass a minimal manifest with declared profiles.
-      secureCommandManifest: {
-        commandProfiles: Object.fromEntries(
-          (request.profiles ?? []).map((p) => [p, { command: request.toolName }]),
-        ),
-      } as unknown as import("./commands/profiles.js").SecureCommandManifest,
+      secureCommandManifest,
     });
 
     if (!publishResult.success) {
@@ -615,7 +751,7 @@ export function createManageSecureCommandToolHandler(
     deps.registerTool({
       toolName: request.toolName,
       credentialHandle: request.credentialHandle!,
-      description: request.description ?? "",
+      description: request.description!,
       bundleDigest: request.sha256!,
     });
 

package/src/subjects/managed.ts

@@ -83,12 +83,16 @@ export interface ManagedSubject extends ResolvedSubject {
 /**
  * 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 {
-  id: string;
+  handle: string;
+  connection_id: string;
   provider: string;
-  account_info?: string | null;
-  granted_scopes?: string[];
+  account_label?: string | null;
+  scopes_granted?: string[];
   status?: string;
 }
 
@@ -120,6 +124,11 @@ export interface ManagedSubjectResolverOptions {
    * 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).
    */
@@ -191,9 +200,19 @@ export async function resolveManagedSubject(
     };
   }
 
+  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/ces/catalog`;
+  const catalogUrl = `${options.platformBaseUrl}/v1/assistants/${encodeURIComponent(options.assistantId)}/oauth/managed/catalog/`;
 
   let response: Response;
   try {
@@ -226,9 +245,11 @@ export async function resolveManagedSubject(
   }
 
   // -- Parse response -------------------------------------------------------
-  let body: { connections?: PlatformCatalogEntry[] };
+  // The platform returns a flat JSON array of catalog entries
+  // (serialized with many=True), not a wrapper object.
+  let entries: PlatformCatalogEntry[];
   try {
-    body = (await response.json()) as { connections?: PlatformCatalogEntry[] };
+    entries = (await response.json()) as PlatformCatalogEntry[];
   } catch {
     return {
       ok: false,
@@ -239,7 +260,7 @@ export async function resolveManagedSubject(
     };
   }
 
-  if (!body.connections || !Array.isArray(body.connections)) {
+  if (!Array.isArray(entries)) {
     return {
       ok: false,
       error: new SubjectResolutionError(
@@ -250,8 +271,8 @@ export async function resolveManagedSubject(
   }
 
   // -- Find matching connection ---------------------------------------------
-  const entry = body.connections.find(
-    (c) => c.id === platformHandle.connectionId,
+  const entry = entries.find(
+    (c) => c.connection_id === platformHandle.connectionId,
   );
 
   if (!entry) {
@@ -269,9 +290,9 @@ export async function resolveManagedSubject(
     source: "managed",
     handle,
     provider: entry.provider,
-    connectionId: entry.id,
-    accountInfo: entry.account_info ?? null,
-    grantedScopes: entry.granted_scopes ?? [],
+    connectionId: entry.connection_id,
+    accountInfo: entry.account_label ?? null,
+    grantedScopes: entry.scopes_granted ?? [],
     status: entry.status ?? "unknown",
   };