@vellumai/credential-executor 0.7.0 → 0.7.1

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");
 }
 
 // ---------------------------------------------------------------------------