@vellumai/credential-executor 0.6.6 → 0.7.1

package/src/http/credential-routes.ts

@@ -21,6 +21,49 @@ import { timingSafeEqual } from "node:crypto";
 
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
 
+// ---------------------------------------------------------------------------
+// Account key normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Known internal key prefixes. Keys in the encrypted store use slash-separated
+ * paths (e.g. `credential/vellum/platform_organization_id`), but callers
+ * (especially manual `curl` invocations) often use the colon-separated format
+ * visible in the CLI (e.g. `vellum:platform_organization_id`).
+ *
+ * This normalizer transparently converts colon-separated credential names
+ * to the internal format so writes land under the correct key. Without this,
+ * a credential stored as `vellum:platform_organization_id` would silently
+ * succeed but be invisible to the gateway and assistant, which look up
+ * `credential/vellum/platform_organization_id`.
+ */
+const CREDENTIAL_PREFIX = "credential/";
+
+function normalizeAccountKey(account: string): string {
+  // Already in internal format — pass through
+  if (account.startsWith(CREDENTIAL_PREFIX)) {
+    return account;
+  }
+
+  // Other known internal prefixes — pass through as-is
+  if (account.startsWith("oauth/")) {
+    return account;
+  }
+
+  // Convert "service:field" → "credential/service/field"
+  // Use lastIndexOf to match the canonical split in secret-routes.ts
+  // (e.g. "integration:google:access_token" → service="integration:google", field="access_token")
+  const colonIdx = account.lastIndexOf(":");
+  if (colonIdx > 0 && colonIdx < account.length - 1) {
+    const service = account.slice(0, colonIdx);
+    const field = account.slice(colonIdx + 1);
+    return `${CREDENTIAL_PREFIX}${service}/${field}`;
+  }
+
+  // Unrecognized format — return as-is (will likely fail lookup, which is fine)
+  return account;
+}
+
 // ---------------------------------------------------------------------------
 // Auth
 // ---------------------------------------------------------------------------
@@ -136,8 +179,9 @@ export async function handleCredentialRoute(
 
     const results: Array<{ account: string; ok: boolean }> = [];
     for (const entry of body.credentials as Array<{ account: string; value: string }>) {
-      const ok = await backend.set(entry.account, entry.value);
-      results.push({ account: entry.account, ok: !!ok });
+      const normalized = normalizeAccountKey(entry.account);
+      const ok = await backend.set(normalized, entry.value);
+      results.push({ account: normalized, ok: !!ok });
     }
 
     return new Response(
@@ -167,15 +211,17 @@ export async function handleCredentialRoute(
     return null; // Not a credential route
   }
 
-  const account = decodeURIComponent(accountSegment.slice(1));
-  if (!account) {
+  const rawAccount = decodeURIComponent(accountSegment.slice(1));
+  if (!rawAccount) {
     return new Response(
       JSON.stringify({ error: "Account name is required" }),
       { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
+      );
+    }
+
+    const account = normalizeAccountKey(rawAccount);
 
-  switch (req.method) {
+    switch (req.method) {
     // GET /v1/credentials/:account — get credential value
     case "GET": {
       const value = await backend.get(account);

package/src/http/executor.ts

@@ -26,8 +26,8 @@
 import type {
   MakeAuthenticatedRequest,
   MakeAuthenticatedRequestResponse,
-} from "@vellumai/ces-contracts";
-import { HandleType, parseHandle, hashProposal } from "@vellumai/ces-contracts";
+} from "@vellumai/service-contracts/credential-rpc";
+import { HandleType, parseHandle, hashProposal } from "@vellumai/service-contracts/credential-rpc";
 import type { InjectionTemplate } from "@vellumai/credential-storage";
 
 import { evaluateHttpPolicy, type PolicyResult } from "./policy.js";

package/src/http/policy.ts

@@ -18,7 +18,7 @@
  *   credential.
  */
 
-import { hashProposal, type HttpGrantProposal } from "@vellumai/ces-contracts";
+import { hashProposal, type HttpGrantProposal } from "@vellumai/service-contracts/credential-rpc";
 
 import type { PersistentGrant, PersistentGrantStore } from "../grants/persistent-store.js";
 import type { TemporaryGrantStore } from "../grants/temporary-store.js";

package/src/main.ts

@@ -21,9 +21,12 @@
 
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
-import { CES_PROTOCOL_VERSION, CesRpcMethod } from "@vellumai/ces-contracts";
+import {
+  CES_PROTOCOL_VERSION,
+  CesRpcMethod,
+} from "@vellumai/service-contracts/credential-rpc";
 import { StaticCredentialMetadataStore } from "@vellumai/credential-storage";
 
 import { AuditStore } from "./audit/store.js";
@@ -36,6 +39,7 @@ import {
 } from "./grants/rpc-handlers.js";
 import { TemporaryGrantStore } from "./grants/temporary-store.js";
 import { LocalMaterialiser } from "./materializers/local.js";
+import type { SecureKeyBackend } from "@vellumai/credential-storage";
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
 import { createLocalOAuthLookup } from "./materializers/local-oauth-lookup.js";
 import { createLocalTokenRefreshFn } from "./materializers/local-token-refresh.js";
@@ -57,9 +61,14 @@ import {
   type RpcHandlerRegistry,
   type SessionIdRef,
 } from "./server.js";
-import { deleteBundleFromToolstore, publishBundle } from "./toolstore/publish.js";
+import {
+  deleteBundleFromToolstore,
+  publishBundle,
+} from "./toolstore/publish.js";
 import { validateSourceUrl } from "./toolstore/manifest.js";
 import { buildCesEgressHooks } from "./commands/egress-hooks.js";
+import { CES_MIGRATIONS } from "./migrations/registry.js";
+import { runCesMigrations } from "./migrations/runner.js";
 
 // ---------------------------------------------------------------------------
 // Data directory bootstrap
@@ -78,19 +87,46 @@ function ensureDataDirs(): void {
 }
 
 // ---------------------------------------------------------------------------
-// Vellum root resolution (mirrors assistant/src/util/platform.ts)
+// Path resolution
 // ---------------------------------------------------------------------------
 
-function getVellumRootDir(): string {
-  const baseDataDir = process.env["BASE_DATA_DIR"]?.trim();
-  return join(baseDataDir || homedir(), ".vellum");
+/**
+ * Resolve the workspace directory.
+ *
+ * Priority:
+ * 1. `VELLUM_WORKSPACE_DIR` env var (set by the platform template)
+ * 2. Default: `~/.vellum/workspace`
+ */
+function getWorkspaceDir(): string {
+  return (
+    process.env["VELLUM_WORKSPACE_DIR"]?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+/**
+ * Resolve the CES security directory (contains key stores, encryption data).
+ *
+ * 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)
+ */
+function getSecurityDir(): string {
+  return (
+    process.env["CREDENTIAL_SECURITY_DIR"]?.trim() ||
+    join(homedir(), ".vellum", "protected")
+  );
 }
 
 // ---------------------------------------------------------------------------
 // Build RPC handler registry
 // ---------------------------------------------------------------------------
 
-function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
+function buildHandlers(
+  sessionIdRef: SessionIdRef,
+  secureKeyBackend: SecureKeyBackend,
+): RpcHandlerRegistry {
   // -- Grant stores ----------------------------------------------------------
   const persistentGrantStore = new PersistentGrantStore(
     getCesGrantsDir("local"),
@@ -106,10 +142,9 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
   // -- Credential backend (local) --------------------------------------------
   // In local mode CES shares the filesystem with the assistant and can access
   // the same credential metadata and secure-key stores.
-  const vellumRoot = getVellumRootDir();
+  const workspaceDir = getWorkspaceDir();
   const credentialMetadataPath = join(
-    vellumRoot,
-    "workspace",
+    workspaceDir,
     "data",
     "credentials",
     "metadata.json",
@@ -120,33 +155,27 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
 
   // Read-only OAuth connection lookup backed by the assistant's SQLite
   // database. CES opens the database in read-only mode.
-  const oauthConnections = createLocalOAuthLookup(vellumRoot);
-
-  // CES-native SecureKeyBackend that reads from the assistant's encrypted
-  // key store file. Read-only — CES never writes or deletes keys.
-  const secureKeyBackend = createLocalSecureKeyBackend(vellumRoot);
+  const oauthConnections = createLocalOAuthLookup(workspaceDir);
 
   const localMaterialiser = new LocalMaterialiser({
     secureKeyBackend,
-    tokenRefreshFn: createLocalTokenRefreshFn(vellumRoot, secureKeyBackend),
+    tokenRefreshFn: createLocalTokenRefreshFn(workspaceDir, secureKeyBackend),
   });
 
   // -- Build handler registry ------------------------------------------------
 
   // Start with the HTTP handler (make_authenticated_request)
-  const handlers = buildHandlersWithHttp(
-    {
-      persistentGrantStore,
-      temporaryGrantStore,
-      localMaterialiser,
-      localSubjectDeps: {
-        metadataStore,
-        oauthConnections,
-      },
-      auditStore,
-      sessionId: sessionIdRef,
+  const handlers = buildHandlersWithHttp({
+    persistentGrantStore,
+    temporaryGrantStore,
+    localMaterialiser,
+    localSubjectDeps: {
+      metadataStore,
+      oauthConnections,
     },
-  );
+    auditStore,
+    sessionId: sessionIdRef,
+  });
 
   // Register run_authenticated_command handler
   registerCommandExecutionHandler(handlers, {
@@ -174,7 +203,9 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
           }
         }
 
-        const matResult = await localMaterialiser.materialise(subjectResult.subject);
+        const matResult = await localMaterialiser.materialise(
+          subjectResult.subject,
+        );
         if (!matResult.ok) {
           return { ok: false as const, error: matResult.error };
         }
@@ -189,11 +220,19 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
       cesMode: "local",
       egressHooks: buildCesEgressHooks(),
     },
-    defaultWorkspaceDir: join(vellumRoot, "workspace"),
+    defaultWorkspaceDir: workspaceDir,
   });
 
   // Register manage_secure_command_tool handler
-  const toolRegistry = new Map<string, { toolName: string; credentialHandle: string; description: string; bundleDigest: string }>();
+  const toolRegistry = new Map<
+    string,
+    {
+      toolName: string;
+      credentialHandle: string;
+      description: string;
+      bundleDigest: string;
+    }
+  >();
 
   registerManageSecureCommandToolHandler(handlers, {
     downloadBundle: async (sourceUrl: string) => {
@@ -202,13 +241,17 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
         throw new Error(urlError);
       }
       const MAX_BUNDLE_SIZE = 100 * 1024 * 1024; // 100 MB
-      const resp = await fetch(sourceUrl, { signal: AbortSignal.timeout(60_000) });
+      const resp = await fetch(sourceUrl, {
+        signal: AbortSignal.timeout(60_000),
+      });
       if (!resp.ok) {
         throw new Error(`HTTP ${resp.status}: ${resp.statusText}`);
       }
       const contentLength = resp.headers.get("content-length");
       if (contentLength && parseInt(contentLength, 10) > MAX_BUNDLE_SIZE) {
-        throw new Error(`Bundle too large: ${contentLength} bytes (max ${MAX_BUNDLE_SIZE})`);
+        throw new Error(
+          `Bundle too large: ${contentLength} bytes (max ${MAX_BUNDLE_SIZE})`,
+        );
       }
       // Stream the body and enforce the size limit on actual bytes received,
       // since Content-Length can be absent (chunked encoding) or lie.
@@ -221,7 +264,9 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
       for await (const chunk of body) {
         totalBytes += chunk.byteLength;
         if (totalBytes > MAX_BUNDLE_SIZE) {
-          throw new Error(`Bundle too large: received >${MAX_BUNDLE_SIZE} bytes (max ${MAX_BUNDLE_SIZE})`);
+          throw new Error(
+            `Bundle too large: received >${MAX_BUNDLE_SIZE} bytes (max ${MAX_BUNDLE_SIZE})`,
+          );
         }
         chunks.push(chunk);
       }
@@ -232,7 +277,9 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
       const entry = toolRegistry.get(toolName);
       const removed = toolRegistry.delete(toolName);
       if (removed && entry?.bundleDigest) {
-        const stillInUse = Array.from(toolRegistry.values()).some(t => t.bundleDigest === entry.bundleDigest);
+        const stillInUse = Array.from(toolRegistry.values()).some(
+          (t) => t.bundleDigest === entry.bundleDigest,
+        );
         if (!stillInUse) {
           deleteBundleFromToolstore(entry.bundleDigest, "local");
         }
@@ -248,50 +295,57 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
   handlers[CesRpcMethod.RecordGrant] = createRecordGrantHandler({
     persistentGrantStore,
     temporaryGrantStore,
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   handlers[CesRpcMethod.ListGrants] = createListGrantsHandler({
     persistentGrantStore,
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   handlers[CesRpcMethod.RevokeGrant] = createRevokeGrantHandler({
     persistentGrantStore,
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   // Register audit record handler
   handlers[CesRpcMethod.ListAuditRecords] = createListAuditRecordsHandler({
     auditStore,
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   // Register credential CRUD handlers
   handlers[CesRpcMethod.GetCredential] = (async (req: { account: string }) => {
     const value = await secureKeyBackend.get(req.account);
     return { found: value !== undefined, value };
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
-  handlers[CesRpcMethod.SetCredential] = (async (req: { account: string; value: string }) => {
+  handlers[CesRpcMethod.SetCredential] = (async (req: {
+    account: string;
+    value: string;
+  }) => {
     const ok = await secureKeyBackend.set(req.account, req.value);
     return { ok };
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
-  handlers[CesRpcMethod.DeleteCredential] = (async (req: { account: string }) => {
+  handlers[CesRpcMethod.DeleteCredential] = (async (req: {
+    account: string;
+  }) => {
     const result = await secureKeyBackend.delete(req.account);
     return { result };
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   handlers[CesRpcMethod.ListCredentials] = (async () => {
     const accounts = await secureKeyBackend.list();
     return { accounts };
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
-  handlers[CesRpcMethod.BulkSetCredentials] = (async (req: { credentials: Array<{ account: string; value: string }> }) => {
+  handlers[CesRpcMethod.BulkSetCredentials] = (async (req: {
+    credentials: Array<{ account: string; value: string }>;
+  }) => {
     const results = [];
     for (const { account, value } of req.credentials) {
       const ok = await secureKeyBackend.set(account, value);
       results.push({ account, ok });
     }
     return { results };
-  }) as typeof handlers[string];
+  }) as (typeof handlers)[string];
 
   return handlers;
 }
@@ -306,7 +360,9 @@ async function main(): Promise<void> {
   initLogger({ dir: getCesLogDir(), retentionDays: 30 });
   const log = getLogger("main");
 
-  log.info(`Starting CES v${CES_PROTOCOL_VERSION} (local mode, stdio transport)`);
+  log.info(
+    `Starting CES v${CES_PROTOCOL_VERSION} (local mode, stdio transport)`,
+  );
 
   const controller = new AbortController();
 
@@ -318,11 +374,25 @@ async function main(): Promise<void> {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 
+  // Build the credential backend and run one-time migrations before starting
+  // the RPC server. Migrations complete synchronously before any connection
+  // is accepted — the backend is then passed to buildHandlers so it is not
+  // re-instantiated.
+  const secureKeyBackend = createLocalSecureKeyBackend(
+    dirname(getSecurityDir()),
+  );
+  await runCesMigrations(
+    getCesDataRoot("local"),
+    secureKeyBackend,
+    CES_MIGRATIONS,
+  );
+  log.info("CES local startup: migrations complete");
+
   // Build the handler registry with all available RPC implementations.
   // Use a mutable ref so audit records capture the handshake session ID
   // once it's negotiated (the handshake completes before any RPC call).
   const sessionIdRef: SessionIdRef = { current: `ces-local-${Date.now()}` };
-  const handlers = buildHandlers(sessionIdRef);
+  const handlers = buildHandlers(sessionIdRef, secureKeyBackend);
 
   const rpcLog = getLogger("rpc");
   const server = new CesRpcServer({

package/src/managed-errors.ts

@@ -1,9 +1,9 @@
 /**
  * Error message constants for managed-mode CES.
  *
- * Re-exported from @vellumai/ces-contracts so both the assistant and
+ * Re-exported from @vellumai/service-contracts so both the assistant and
  * credential-executor can share the constant via the approved shared-code
  * path without violating the hard process-boundary isolation.
  */
 
-export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "@vellumai/ces-contracts";
+export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "@vellumai/service-contracts/credential-rpc";

package/src/managed-lazy-getters.ts

@@ -23,10 +23,10 @@ export interface ApiKeyRef {
 }
 
 /**
- * Mutable reference to the platform assistant ID. For warm-pool pods the
- * PLATFORM_ASSISTANT_ID env var is empty at startup; the assistant forwards
- * the ID via the handshake or update_managed_credential RPC after
- * provisioning, and `.current` is updated so lazy getters pick it up.
+ * Mutable reference to the platform assistant ID. The assistant ID is not
+ * available at CES startup (warm-pool pods); the assistant forwards it via
+ * the handshake or update_managed_credential RPC after provisioning, and
+ * `.current` is updated so lazy getters pick it up.
  */
 export interface AssistantIdRef {
   current: string;

package/src/managed-main.ts

@@ -22,7 +22,7 @@ import { createServer as createNetServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
 import { Readable, Writable } from "node:stream";
 
-import { CES_PROTOCOL_VERSION, CesRpcMethod } from "@vellumai/ces-contracts";
+import { CES_PROTOCOL_VERSION, CesRpcMethod } from "@vellumai/service-contracts/credential-rpc";
 
 import { AuditStore } from "./audit/store.js";
 import { PersistentGrantStore } from "./grants/persistent-store.js";
@@ -56,13 +56,15 @@ import { validateSourceUrl } from "./toolstore/manifest.js";
 import { buildCesEgressHooks } from "./commands/egress-hooks.js";
 import { resolveManagedSubject } from "./subjects/managed.js";
 import { materializeManagedToken } from "./materializers/managed-platform.js";
-import { HandleType, parseHandle } from "@vellumai/ces-contracts";
+import { HandleType, parseHandle } from "@vellumai/service-contracts/credential-rpc";
 import { buildLazyGetters, type ApiKeyRef, type AssistantIdRef } from "./managed-lazy-getters.js";
 import { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "./managed-errors.js";
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
 import { handleCredentialRoute, type CredentialRouteDeps } from "./http/credential-routes.js";
 import { handleLogExportRoute } from "./http/log-export-routes.js";
+import { CES_MIGRATIONS } from "./migrations/registry.js";
+import { runCesMigrations } from "./migrations/runner.js";
 
 // ---------------------------------------------------------------------------
 // Logging
@@ -543,6 +545,10 @@ async function main(): Promise<void> {
   const vellumRoot = join(assistantDataMount, ".vellum");
   const secureKeyBackend = createLocalSecureKeyBackend(vellumRoot);
 
+  // Run one-time credential store migrations before accepting connections.
+  await runCesMigrations(getCesDataRoot("managed"), secureKeyBackend, CES_MIGRATIONS);
+  log.info("CES managed startup: migrations complete");
+
   // Set up credential CRUD routes if a service token is configured.
   // The assistant and gateway use CES_SERVICE_TOKEN to authenticate
   // credential management requests over HTTP.
@@ -586,7 +592,7 @@ async function main(): Promise<void> {
   // are available to handlers at call time (after the handshake completes).
   const sessionIdRef: SessionIdRef = { current: `ces-managed-${Date.now()}` };
   const apiKeyRef: ApiKeyRef = { current: "" };
-  const assistantIdRef: AssistantIdRef = { current: process.env["PLATFORM_ASSISTANT_ID"] ?? "" };
+  const assistantIdRef: AssistantIdRef = { current: "" };
   const handlers = buildHandlers(sessionIdRef, apiKeyRef, assistantIdRef, secureKeyBackend);
 
   const rpcLog = getLogger("rpc");

package/src/materializers/local-oauth-lookup.ts

@@ -65,12 +65,12 @@ function rowToRecord(row: OAuthConnectionRow): OAuthConnectionRecord {
  * Create a read-only OAuth connection lookup backed by the assistant's
  * SQLite database.
  *
- * @param vellumRoot - The Vellum root directory (e.g. `~/.vellum`).
+ * @param workspaceDir - The workspace directory (e.g. `~/.vellum/workspace`).
  */
 export function createLocalOAuthLookup(
-  vellumRoot: string,
+  workspaceDir: string,
 ): OAuthConnectionLookup {
-  const dbPath = join(vellumRoot, "workspace", "data", "db", "assistant.db");
+  const dbPath = join(workspaceDir, "data", "db", "assistant.db");
 
   return {
     getById(connectionId: string): OAuthConnectionRecord | undefined {
@@ -80,9 +80,10 @@ export function createLocalOAuthLookup(
       try {
         db = new Database(dbPath, { readonly: true });
         const row = db
-          .query<OAuthConnectionRow, [string, string]>(
-            `SELECT * FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`,
-          )
+          .query<
+            OAuthConnectionRow,
+            [string, string]
+          >(`SELECT * FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`)
           .get(connectionId, "active");
 
         if (!row) return undefined;

package/src/materializers/local-token-refresh.ts

@@ -88,20 +88,24 @@ async function resolveRefreshConfig(
 
     // 1. Look up the connection to get oauth_app_id and provider_key
     const conn = db
-      .query<OAuthConnectionRow, [string, string]>(
-        `SELECT id, oauth_app_id, provider_key FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`,
-      )
+      .query<
+        OAuthConnectionRow,
+        [string, string]
+      >(`SELECT id, oauth_app_id, provider_key FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`)
       .get(connectionId, "active");
 
     if (!conn) {
-      return { error: `No active OAuth connection found for "${connectionId}"` };
+      return {
+        error: `No active OAuth connection found for "${connectionId}"`,
+      };
     }
 
     // 2. Look up the app to get client_id and client_secret_credential_path
     const app = db
-      .query<OAuthAppRow, [string]>(
-        `SELECT id, provider_key, client_id, client_secret_credential_path FROM oauth_apps WHERE id = ? LIMIT 1`,
-      )
+      .query<
+        OAuthAppRow,
+        [string]
+      >(`SELECT id, provider_key, client_id, client_secret_credential_path FROM oauth_apps WHERE id = ? LIMIT 1`)
       .get(conn.oauth_app_id);
 
     if (!app) {
@@ -110,9 +114,10 @@ async function resolveRefreshConfig(
 
     // 3. Look up the provider to get token_url and auth method
     const provider = db
-      .query<OAuthProviderRow, [string]>(
-        `SELECT provider_key, token_url, refresh_url, token_endpoint_auth_method, token_exchange_body_format FROM oauth_providers WHERE provider_key = ? LIMIT 1`,
-      )
+      .query<
+        OAuthProviderRow,
+        [string]
+      >(`SELECT provider_key, token_url, refresh_url, token_endpoint_auth_method, token_exchange_body_format FROM oauth_providers WHERE provider_key = ? LIMIT 1`)
       .get(conn.provider_key);
 
     if (!provider) {
@@ -123,7 +128,9 @@ async function resolveRefreshConfig(
     const tokenUrl = provider.refresh_url || provider.token_url;
 
     if (!tokenUrl || !app.client_id) {
-      return { error: `Missing OAuth2 refresh config for "${conn.provider_key}"` };
+      return {
+        error: `Missing OAuth2 refresh config for "${conn.provider_key}"`,
+      };
     }
 
     // 4. Retrieve the client secret from secure storage
@@ -131,8 +138,11 @@ async function resolveRefreshConfig(
       app.client_secret_credential_path,
     );
 
-    const authMethod = (provider.token_endpoint_auth_method as TokenEndpointAuthMethod | null) ?? "client_secret_post";
-    const bodyFormat = (provider.token_exchange_body_format as "form" | "json" | null) ?? "form";
+    const authMethod =
+      (provider.token_endpoint_auth_method as TokenEndpointAuthMethod | null) ??
+      "client_secret_post";
+    const bodyFormat =
+      (provider.token_exchange_body_format as "form" | "json" | null) ?? "form";
 
     return {
       tokenUrl,
@@ -238,10 +248,10 @@ async function performTokenRefresh(
  * @param secureKeyBackend - Backend for retrieving the OAuth client secret.
  */
 export function createLocalTokenRefreshFn(
-  vellumRoot: string,
+  workspaceDir: string,
   secureKeyBackend: SecureKeyBackend,
 ): TokenRefreshFn {
-  const dbPath = join(vellumRoot, "workspace", "data", "db", "assistant.db");
+  const dbPath = join(workspaceDir, "data", "db", "assistant.db");
 
   return async (
     connectionId: string,

package/src/materializers/local.ts

@@ -32,7 +32,7 @@ import {
   RefreshDeduplicator,
   persistRefreshedTokens,
 } from "@vellumai/credential-storage";
-import { HandleType } from "@vellumai/ces-contracts";
+import { HandleType } from "@vellumai/service-contracts/credential-rpc";
 
 import type {
   ResolvedLocalSubject,

package/src/migrations/001-no-op.ts

@@ -0,0 +1,19 @@
+import type { CesMigration } from "./types.js";
+
+/**
+ * No-op foundation migration.
+ *
+ * Establishes the CES migration system and seeds the checkpoint file for
+ * all existing installations. The next real migration (API key → credential
+ * key rekeying) will follow this one.
+ */
+export const noOpMigration: CesMigration = {
+  id: "001-no-op",
+  description: "Seed CES migration checkpoint (no-op foundation)",
+  run(_backend): void {
+    // Intentionally empty — seeds the checkpoint file for existing installs.
+  },
+  down(_backend): void {
+    // Intentionally empty — nothing to reverse.
+  },
+};