@vellumai/credential-executor 0.6.6 → 0.7.1

package/src/migrations/002-api-keys-to-credentials.ts

@@ -0,0 +1,60 @@
+import type { CesMigration } from "./types.js";
+
+/**
+ * Providers whose bare API-key entries (e.g. `anthropic`) must be moved to
+ * the canonical `credential/{provider}/api_key` namespace.
+ *
+ * Note: `elevenlabs` is intentionally omitted — it was already migrated by
+ * `migrateElevenLabsToCredential()` in the Swift layer before CES migrations
+ * were introduced.
+ */
+const PROVIDERS_TO_MIGRATE = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "ollama",
+  "fireworks",
+  "openrouter",
+  "brave",
+  "perplexity",
+  "deepgram",
+  "xai",
+] as const;
+
+export const apiKeyToCredentialsMigration: CesMigration = {
+  id: "002-api-keys-to-credentials",
+  description:
+    "Rekey bare provider API keys to credential/{provider}/api_key namespace",
+
+  async run(backend): Promise<void> {
+    for (const provider of PROVIDERS_TO_MIGRATE) {
+      const bareValue = await backend.get(provider);
+      if (bareValue === undefined) continue; // nothing to migrate for this provider
+
+      const credKey = `credential/${provider}/api_key`;
+      const existingCred = await backend.get(credKey);
+      if (existingCred === undefined) {
+        // Write new key first — safe to re-run if we crash after this.
+        // Skip delete if the write fails so the bare key is preserved for retry.
+        const ok = await backend.set(credKey, bareValue);
+        if (!ok) continue;
+      }
+      // Always delete old bare key (idempotent: harmless if already absent)
+      await backend.delete(provider);
+    }
+  },
+
+  async down(backend): Promise<void> {
+    for (const provider of PROVIDERS_TO_MIGRATE) {
+      const credKey = `credential/${provider}/api_key`;
+      const credValue = await backend.get(credKey);
+      if (credValue === undefined) continue;
+
+      const existingBare = await backend.get(provider);
+      if (existingBare === undefined) {
+        await backend.set(provider, credValue);
+      }
+      await backend.delete(credKey);
+    }
+  },
+};

package/src/migrations/registry.ts

@@ -0,0 +1,15 @@
+import { apiKeyToCredentialsMigration } from "./002-api-keys-to-credentials.js";
+import { noOpMigration } from "./001-no-op.js";
+import type { CesMigration } from "./types.js";
+
+/**
+ * Ordered list of all CES data migrations.
+ *
+ * New migrations are appended to the end. Never reorder or remove entries —
+ * the runner uses array position for ordering and the `id` field for
+ * checkpoint tracking.
+ */
+export const CES_MIGRATIONS: CesMigration[] = [
+  noOpMigration,
+  apiKeyToCredentialsMigration,
+];

package/src/migrations/runner.ts

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { SecureKeyBackend } from "@vellumai/credential-storage";
+
+import { getLogger } from "../logger.js";
+import type { CesMigration, CesMigrationStatus } from "./types.js";
+
+const log = getLogger("ces-migrations");
+
+// ---------------------------------------------------------------------------
+// Checkpoint file
+// ---------------------------------------------------------------------------
+
+type CheckpointFile = {
+  applied: Record<string, { appliedAt: string; status?: CesMigrationStatus }>;
+};
+
+function getCheckpointPath(cesDataRoot: string): string {
+  return join(cesDataRoot, ".ces-migrations.json");
+}
+
+function loadCheckpoints(cesDataRoot: string): CheckpointFile {
+  const path = getCheckpointPath(cesDataRoot);
+  if (!existsSync(path)) {
+    return { applied: {} };
+  }
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const data = JSON.parse(raw);
+    if (
+      typeof data === "object" &&
+      data != null &&
+      typeof data.applied === "object" &&
+      data.applied != null
+    ) {
+      return data as CheckpointFile;
+    }
+    log.warn(
+      "CES migration checkpoint file has unexpected structure; treating as fresh state",
+    );
+  } catch {
+    log.warn(
+      "CES migration checkpoint file is malformed; treating as fresh state",
+    );
+  }
+  return { applied: {} };
+}
+
+function saveCheckpoints(
+  cesDataRoot: string,
+  checkpoints: CheckpointFile,
+): void {
+  const path = getCheckpointPath(cesDataRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = path + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(checkpoints, null, 2) + "\n", "utf-8");
+  renameSync(tmpPath, path);
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all pending CES migrations in registry order.
+ *
+ * - Skips migrations that already have a checkpoint entry (`"completed"` or
+ *   `"failed"`). Only `"started"` and `"rolling_back"` entries are cleared
+ *   and re-run on the next startup (crash recovery — migrations must be
+ *   idempotent).
+ * - Marks failed migrations as `"failed"` and continues startup; a failed
+ *   migration does not block the RPC server from starting.
+ *
+ * @param cesDataRoot  The CES-private data root (from `getCesDataRoot(mode)`).
+ *   The checkpoint file is stored here as `.ces-migrations.json`.
+ * @param backend  The active `SecureKeyBackend` instance, passed directly to
+ *   each migration's `run()` function.
+ * @param migrations  Ordered list of migrations from the registry.
+ */
+export async function runCesMigrations(
+  cesDataRoot: string,
+  backend: SecureKeyBackend,
+  migrations: CesMigration[],
+): Promise<void> {
+  // Validate uniqueness.
+  const seen = new Set<string>();
+  for (const m of migrations) {
+    if (seen.has(m.id)) {
+      throw new Error(`Duplicate CES migration id: "${m.id}"`);
+    }
+    seen.add(m.id);
+  }
+
+  const checkpoints = loadCheckpoints(cesDataRoot);
+
+  // Clear any interrupted checkpoints so they re-run.
+  for (const [id, entry] of Object.entries(checkpoints.applied)) {
+    if (entry.status === "started" || entry.status === "rolling_back") {
+      log.warn(
+        `CES migration "${id}" was interrupted during a previous run; will re-run`,
+      );
+      delete checkpoints.applied[id];
+    }
+  }
+
+  for (const migration of migrations) {
+    if (checkpoints.applied[migration.id]) {
+      continue;
+    }
+
+    log.info(
+      `Running CES migration: ${migration.id} — ${migration.description}`,
+    );
+
+    // Mark as started before executing (crash recovery observability).
+    checkpoints.applied[migration.id] = {
+      appliedAt: new Date().toISOString(),
+      status: "started",
+    };
+    saveCheckpoints(cesDataRoot, checkpoints);
+
+    try {
+      await migration.run(backend);
+    } catch (error) {
+      log.error(
+        { migrationId: migration.id, error },
+        `CES migration failed: ${migration.id} — marking as failed and continuing`,
+      );
+      checkpoints.applied[migration.id] = {
+        appliedAt: new Date().toISOString(),
+        status: "failed",
+      };
+      saveCheckpoints(cesDataRoot, checkpoints);
+      continue;
+    }
+
+    checkpoints.applied[migration.id] = {
+      appliedAt: new Date().toISOString(),
+      status: "completed",
+    };
+    saveCheckpoints(cesDataRoot, checkpoints);
+
+    log.info(`CES migration completed: ${migration.id}`);
+  }
+}

package/src/migrations/types.ts

@@ -0,0 +1,54 @@
+import type { SecureKeyBackend } from "@vellumai/credential-storage";
+
+/**
+ * A single CES data migration.
+ *
+ * Migrations run at CES startup — once per installation, tracked via a
+ * checkpoint file in the CES-private data root. They are the right place
+ * for one-time transformations of the credential store (key renames,
+ * format changes, etc.) that must happen before the RPC server accepts
+ * connections.
+ *
+ * **Idempotency**: `run` and `down` must both be safe to re-run. The
+ * runner re-executes any migration whose checkpoint was left in `"started"`
+ * state (i.e. the process crashed mid-migration).
+ *
+ * **Ordering**: Migrations are executed in registry order. Never reorder
+ * or remove an entry from the registry once it has been released.
+ */
+export interface CesMigration {
+  /**
+   * Unique identifier used as the checkpoint key.
+   * Convention: `"NNN-short-description"`, e.g. `"001-no-op"`.
+   * Must be unique across all registered migrations.
+   */
+  id: string;
+
+  /** Human-readable description logged when the migration runs. */
+  description: string;
+
+  /**
+   * Apply the migration.
+   *
+   * Receives the active `SecureKeyBackend` so the migration can read,
+   * write, and delete credential store entries without re-opening the
+   * encrypted store.
+   */
+  run(backend: SecureKeyBackend): void | Promise<void>;
+
+  /**
+   * Reverse the migration (best-effort).
+   *
+   * Some migrations are forward-only (e.g. dropping a key that is no
+   * longer used). In those cases, implement `down` as a no-op and document
+   * why reversal is not meaningful.
+   */
+  down(backend: SecureKeyBackend): void | Promise<void>;
+}
+
+/** Checkpoint status values written to `.ces-migrations.json`. */
+export type CesMigrationStatus =
+  | "started"
+  | "completed"
+  | "rolling_back"
+  | "failed";

package/src/paths.ts

@@ -43,12 +43,19 @@ export function getCesMode(): CesMode {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the Vellum root directory, respecting `BASE_DATA_DIR` for
- * multi-instance deployments. Mirrors the logic in `assistant/src/util/platform.ts`.
+ * Resolve the CES security directory.
+ *
+ * Priority:
+ * 1. `CREDENTIAL_SECURITY_DIR` env var (set by the platform template for the
+ *    CES container — `/ces-security` in managed mode)
+ * 2. Default: `~/.vellum/protected` (local mode shares the filesystem with
+ *    the gateway)
  */
-function getVellumRootDir(): string {
-  const baseDataDir = process.env["BASE_DATA_DIR"]?.trim();
-  return join(baseDataDir || homedir(), ".vellum");
+export function getSecurityDir(): string {
+  return (
+    process.env["CREDENTIAL_SECURITY_DIR"]?.trim() ||
+    join(homedir(), ".vellum", "protected")
+  );
 }
 
 /**
@@ -62,18 +69,15 @@ const DEFAULT_MANAGED_CES_DATA_ROOT = "/ces-data";
 /**
  * Return the CES-private data root.
  *
- * - Local: `<vellumRoot>/protected/credential-executor/`
+ * - Local: `<securityDir>/credential-executor/`
  * - 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 (
-      process.env["CES_DATA_DIR"] ??
-      DEFAULT_MANAGED_CES_DATA_ROOT
-    );
+    return process.env["CES_DATA_DIR"] ?? DEFAULT_MANAGED_CES_DATA_ROOT;
   }
-  return join(getVellumRootDir(), "protected", "credential-executor");
+  return join(getSecurityDir(), "credential-executor");
 }
 
 // ---------------------------------------------------------------------------

package/src/server.ts

@@ -2,7 +2,7 @@
  * CES RPC server.
  *
  * Implements the server-side of the CES wire protocol defined in
- * `@vellumai/ces-contracts`. The server reads newline-delimited JSON
+ * `@vellumai/service-contracts`. The server reads newline-delimited JSON
  * messages from a readable stream, dispatches them through the RPC
  * contract, and writes responses back to a writable stream.
  *
@@ -32,7 +32,7 @@ import {
   type RunAuthenticatedCommandResponse,
   type TransportMessage,
   TransportMessageSchema,
-} from "@vellumai/ces-contracts";
+} from "@vellumai/service-contracts/credential-rpc";
 
 import { resolve } from "node:path";
 

package/src/subjects/local.ts

@@ -7,7 +7,7 @@
  * 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`)
+ * 1. Parse the handle (via `@vellumai/service-contracts`)
  * 2. Look up the metadata/connection record in local storage
  * 3. Return a resolved subject that the materialiser can consume
  *
@@ -26,7 +26,7 @@ import {
   parseHandle,
   type LocalOAuthHandle,
   type LocalStaticHandle,
-} from "@vellumai/ces-contracts";
+} from "@vellumai/service-contracts/credential-rpc";
 
 // ---------------------------------------------------------------------------
 // Resolved subject types

package/src/subjects/managed.ts

@@ -24,7 +24,7 @@ import {
   HandleType,
   parseHandle,
   type PlatformOAuthHandle,
-} from "@vellumai/ces-contracts";
+} from "@vellumai/service-contracts/credential-rpc";
 
 // ---------------------------------------------------------------------------
 // Common subject interface