@vellumai/credential-executor 0.5.6 → 0.5.8

package/node_modules/@vellumai/ces-contracts/package.json

@@ -2,6 +2,7 @@
   "name": "@vellumai/ces-contracts",
   "version": "0.0.1",
   "private": true,
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/node_modules/@vellumai/ces-contracts/src/error.ts

@@ -3,7 +3,7 @@
  * dependencies between index.ts and rpc.ts.
  */
 
-import { z } from "zod/v4";
+import { z } from "zod";
 
 export const RpcErrorSchema = z.object({
   code: z.string(),

package/node_modules/@vellumai/ces-contracts/src/grants.ts

@@ -9,7 +9,7 @@
  * - Audit record summaries (materialization events)
  */
 
-import { z } from "zod/v4";
+import { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Grant proposal types

package/node_modules/@vellumai/ces-contracts/src/handles.ts

@@ -20,7 +20,7 @@
  *    is the platform-assigned connection identifier.
  */
 
-import { z } from "zod/v4";
+import { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Handle type discriminator

package/node_modules/@vellumai/ces-contracts/src/index.ts

@@ -7,7 +7,7 @@
  * module so that both sides can depend on it without circular references.
  */
 
-import { z } from "zod/v4";
+import { z } from "zod";
 import { RpcErrorSchema } from "./error.js";
 
 // ---------------------------------------------------------------------------

package/node_modules/@vellumai/ces-contracts/src/rpc.ts

@@ -25,9 +25,15 @@
  *
  * **Lifecycle**
  * - `update_managed_credential` — Push an updated API key to CES after hatch
+ *
+ * **Credential CRUD**
+ * - `get_credential` — Retrieve a credential by account name
+ * - `set_credential` — Store or update a credential
+ * - `delete_credential` — Delete a credential by account name
+ * - `list_credentials` — List all credential account names
  */
 
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   AuditRecordSummarySchema,
   GrantProposalSchema,
@@ -51,6 +57,14 @@ export const CesRpcMethod = {
   ListAuditRecords: "list_audit_records",
   /** Push an updated assistant credential to CES after post-hatch provisioning. */
   UpdateManagedCredential: "update_managed_credential",
+  /** Retrieve a single credential by account name. */
+  GetCredential: "get_credential",
+  /** Store or update a credential by account name. */
+  SetCredential: "set_credential",
+  /** Delete a credential by account name. */
+  DeleteCredential: "delete_credential",
+  /** List all credential account names. */
+  ListCredentials: "list_credentials",
 } as const;
 
 export type CesRpcMethod =
@@ -421,6 +435,79 @@ export type UpdateManagedCredentialResponse = z.infer<
   typeof UpdateManagedCredentialResponseSchema
 >;
 
+// ---------------------------------------------------------------------------
+// get_credential
+// ---------------------------------------------------------------------------
+
+export const GetCredentialSchema = z.object({
+  /** The account name to look up. */
+  account: z.string(),
+});
+export type GetCredential = z.infer<typeof GetCredentialSchema>;
+
+export const GetCredentialResponseSchema = z.object({
+  /** Whether the credential was found. */
+  found: z.boolean(),
+  /** The credential value (present only when found). */
+  value: z.string().optional(),
+});
+export type GetCredentialResponse = z.infer<
+  typeof GetCredentialResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// set_credential
+// ---------------------------------------------------------------------------
+
+export const SetCredentialSchema = z.object({
+  /** The account name to store the credential under. */
+  account: z.string(),
+  /** The credential value to store. */
+  value: z.string(),
+});
+export type SetCredential = z.infer<typeof SetCredentialSchema>;
+
+export const SetCredentialResponseSchema = z.object({
+  /** Whether the credential was successfully stored. */
+  ok: z.boolean(),
+});
+export type SetCredentialResponse = z.infer<
+  typeof SetCredentialResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// delete_credential
+// ---------------------------------------------------------------------------
+
+export const DeleteCredentialSchema = z.object({
+  /** The account name to delete. */
+  account: z.string(),
+});
+export type DeleteCredential = z.infer<typeof DeleteCredentialSchema>;
+
+export const DeleteCredentialResponseSchema = z.object({
+  /** The result of the delete operation. */
+  result: z.enum(["deleted", "not-found", "error"]),
+});
+export type DeleteCredentialResponse = z.infer<
+  typeof DeleteCredentialResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// list_credentials
+// ---------------------------------------------------------------------------
+
+export const ListCredentialsSchema = z.object({});
+export type ListCredentials = z.infer<typeof ListCredentialsSchema>;
+
+export const ListCredentialsResponseSchema = z.object({
+  /** The account names of all stored credentials. */
+  accounts: z.array(z.string()),
+});
+export type ListCredentialsResponse = z.infer<
+  typeof ListCredentialsResponseSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Full RPC contract type map
 // ---------------------------------------------------------------------------
@@ -466,6 +553,22 @@ export interface CesRpcContract {
     request: UpdateManagedCredential;
     response: UpdateManagedCredentialResponse;
   };
+  [CesRpcMethod.GetCredential]: {
+    request: GetCredential;
+    response: GetCredentialResponse;
+  };
+  [CesRpcMethod.SetCredential]: {
+    request: SetCredential;
+    response: SetCredentialResponse;
+  };
+  [CesRpcMethod.DeleteCredential]: {
+    request: DeleteCredential;
+    response: DeleteCredentialResponse;
+  };
+  [CesRpcMethod.ListCredentials]: {
+    request: ListCredentials;
+    response: ListCredentialsResponse;
+  };
 }
 
 /**
@@ -508,4 +611,20 @@ export const CesRpcSchemas = {
     request: UpdateManagedCredentialSchema,
     response: UpdateManagedCredentialResponseSchema,
   },
+  [CesRpcMethod.GetCredential]: {
+    request: GetCredentialSchema,
+    response: GetCredentialResponseSchema,
+  },
+  [CesRpcMethod.SetCredential]: {
+    request: SetCredentialSchema,
+    response: SetCredentialResponseSchema,
+  },
+  [CesRpcMethod.DeleteCredential]: {
+    request: DeleteCredentialSchema,
+    response: DeleteCredentialResponseSchema,
+  },
+  [CesRpcMethod.ListCredentials]: {
+    request: ListCredentialsSchema,
+    response: ListCredentialsResponseSchema,
+  },
 } as const;

package/node_modules/@vellumai/credential-storage/package.json

@@ -2,6 +2,7 @@
   "name": "@vellumai/credential-storage",
   "version": "0.0.1",
   "private": true,
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/node_modules/@vellumai/egress-proxy/package.json

@@ -2,6 +2,7 @@
   "name": "@vellumai/egress-proxy",
   "version": "0.0.1",
   "private": true,
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.5.6",
+  "version": "0.5.8",
+  "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/__tests__/local-secure-key-backend.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Filesystem-level tests for the CES local SecureKeyBackend.
+ *
+ * These tests exercise `createLocalSecureKeyBackend` with real files and
+ * env-var overrides, separate from the in-memory resolver/materialiser
+ * tests in `local-materializers.test.ts`.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createLocalSecureKeyBackend } from "../materializers/local-secure-key-backend.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir(): string {
+  const dir = join(tmpdir(), `ces-backend-test-${randomBytes(8).toString("hex")}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createLocalSecureKeyBackend — filesystem", () => {
+  let tmpDir: string | undefined;
+  let savedSecurityDir: string | undefined;
+
+  afterEach(() => {
+    if (savedSecurityDir !== undefined) {
+      process.env.CREDENTIAL_SECURITY_DIR = savedSecurityDir;
+    } else {
+      delete process.env.CREDENTIAL_SECURITY_DIR;
+    }
+    if (tmpDir && existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+    tmpDir = undefined;
+    savedSecurityDir = undefined;
+  });
+
+  function setup(): { securityDir: string; vellumRoot: string } {
+    tmpDir = makeTmpDir();
+    const securityDir = join(tmpDir, "security");
+    mkdirSync(securityDir, { recursive: true });
+    savedSecurityDir = process.env.CREDENTIAL_SECURITY_DIR;
+    process.env.CREDENTIAL_SECURITY_DIR = securityDir;
+    // vellumRoot is unused when CREDENTIAL_SECURITY_DIR is set,
+    // but we pass tmpDir for consistency
+    return { securityDir, vellumRoot: tmpDir };
+  }
+
+  test("set() on a fresh security directory creates store.key and keys.enc", async () => {
+    const { securityDir, vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+
+    const result = await backend.set("test/key", "secret-value");
+    expect(result).toBe(true);
+
+    // store.key exists, is 32 bytes, mode 0o600
+    const keyPath = join(securityDir, "store.key");
+    expect(existsSync(keyPath)).toBe(true);
+    const keyBuf = readFileSync(keyPath);
+    expect(keyBuf.length).toBe(32);
+    const mode = statSync(keyPath).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    // keys.enc exists and is valid v2 JSON
+    const encPath = join(securityDir, "keys.enc");
+    expect(existsSync(encPath)).toBe(true);
+    const store = JSON.parse(readFileSync(encPath, "utf-8"));
+    expect(store.version).toBe(2);
+    expect(typeof store.entries).toBe("object");
+
+    // Round-trip
+    const value = await backend.get("test/key");
+    expect(value).toBe("secret-value");
+  });
+
+  test("subsequent set() calls append to the existing store without recreating files", async () => {
+    const { securityDir, vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+
+    await backend.set("key1", "val1");
+    const keyAfterFirst = readFileSync(join(securityDir, "store.key"));
+
+    await backend.set("key2", "val2");
+    const keyAfterSecond = readFileSync(join(securityDir, "store.key"));
+
+    // store.key was not regenerated
+    expect(Buffer.compare(keyAfterFirst, keyAfterSecond)).toBe(0);
+
+    // keys.enc has exactly 2 entries
+    const store = JSON.parse(readFileSync(join(securityDir, "keys.enc"), "utf-8"));
+    expect(Object.keys(store.entries).length).toBe(2);
+
+    // Both values round-trip
+    expect(await backend.get("key1")).toBe("val1");
+    expect(await backend.get("key2")).toBe("val2");
+  });
+
+  test("set() against a pre-existing v1 store preserves format and round-trips", async () => {
+    const { securityDir, vellumRoot } = setup();
+
+    // Manually write a v1 store
+    const salt = randomBytes(32).toString("hex");
+    const v1Store = { version: 1, salt, entries: {} };
+    writeFileSync(join(securityDir, "keys.enc"), JSON.stringify(v1Store, null, 2), {
+      mode: 0o600,
+    });
+
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    const result = await backend.set("v1-key", "v1-value");
+    expect(result).toBe(true);
+
+    // Read back and verify format preserved
+    const storeAfter = JSON.parse(readFileSync(join(securityDir, "keys.enc"), "utf-8"));
+    expect(storeAfter.version).toBe(1);
+    expect(storeAfter.salt).toBe(salt);
+    expect(Object.keys(storeAfter.entries)).toContain("v1-key");
+
+    // store.key was NOT created (v1 stores don't use it)
+    expect(existsSync(join(securityDir, "store.key"))).toBe(false);
+
+    // Round-trip
+    const value = await backend.get("v1-key");
+    expect(value).toBe("v1-value");
+  });
+
+  test("get() returns undefined when no store exists", async () => {
+    const { vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    const value = await backend.get("anything");
+    expect(value).toBeUndefined();
+  });
+
+  test("list() returns empty array when no store exists", async () => {
+    const { vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    const keys = await backend.list();
+    expect(keys).toEqual([]);
+  });
+
+  test("delete() returns error when no store exists", async () => {
+    const { vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    const result = await backend.delete("anything");
+    expect(result).toBe("error");
+  });
+});

package/src/__tests__/managed-integration.test.ts

@@ -29,6 +29,10 @@ import {
   CesRpcMethod,
   type HandshakeAck,
   type ListGrantsResponse,
+  type GetCredentialResponse,
+  type SetCredentialResponse,
+  type DeleteCredentialResponse,
+  type ListCredentialsResponse,
   type RpcEnvelope,
 } from "@vellumai/ces-contracts";
 
@@ -40,6 +44,7 @@ import {
   createListAuditRecordsHandler,
 } from "../grants/rpc-handlers.js";
 import { CesRpcServer, type RpcHandlerRegistry, type SessionIdRef } from "../server.js";
+import { createLocalSecureKeyBackend } from "../materializers/local-secure-key-backend.js";
 
 // ---------------------------------------------------------------------------
 // Environment setup
@@ -52,6 +57,7 @@ const SAVED_ENV_KEYS = [
   "CES_BOOTSTRAP_SOCKET",
   "CES_HEALTH_PORT",
   "CES_MODE",
+  "CREDENTIAL_SECURITY_DIR",
 ] as const;
 
 type SavedEnv = Record<string, string | undefined>;
@@ -107,6 +113,39 @@ function buildMinimalHandlers(dataDir: string): RpcHandlerRegistry {
   return handlers;
 }
 
+/**
+ * Build an RPC handler registry with credential CRUD handlers backed by
+ * a real SecureKeyBackend using a temp directory for credential storage.
+ *
+ * Mirrors the handler registration in managed-main.ts.
+ */
+function buildCredentialHandlers(vellumRoot: string): RpcHandlerRegistry {
+  const secureKeyBackend = createLocalSecureKeyBackend(vellumRoot);
+  const handlers: RpcHandlerRegistry = {};
+
+  handlers[CesRpcMethod.GetCredential] = (async (req: { account: string }) => {
+    const value = await secureKeyBackend.get(req.account);
+    return { found: value !== undefined, value };
+  }) as typeof handlers[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];
+
+  handlers[CesRpcMethod.DeleteCredential] = (async (req: { account: string }) => {
+    const result = await secureKeyBackend.delete(req.account);
+    return { result };
+  }) as typeof handlers[string];
+
+  handlers[CesRpcMethod.ListCredentials] = (async () => {
+    const accounts = await secureKeyBackend.list();
+    return { accounts };
+  }) as typeof handlers[string];
+
+  return handlers;
+}
+
 /**
  * Accept a single connection on a Unix socket and return
  * readable/writable streams plus cleanup helpers.
@@ -351,13 +390,13 @@ describe("managed CES integration (real Unix socket)", () => {
         const url = new URL(req.url);
         if (url.pathname === "/healthz") {
           return new Response(
-            JSON.stringify({ status: "ok", version: CES_PROTOCOL_VERSION }),
+            JSON.stringify({ status: "ok" }),
             { headers: { "Content-Type": "application/json" } },
           );
         }
         if (url.pathname === "/readyz") {
           return new Response(
-            JSON.stringify({ ready: true, version: CES_PROTOCOL_VERSION }),
+            JSON.stringify({ status: "ok", rpcConnected: false }),
             { status: 200, headers: { "Content-Type": "application/json" } },
           );
         }
@@ -466,13 +505,11 @@ describe("managed CES integration (real Unix socket)", () => {
     expect(healthzResp.status).toBe(200);
     const healthzBody = await healthzResp.json();
     expect(healthzBody.status).toBe("ok");
-    expect(healthzBody.version).toBe(CES_PROTOCOL_VERSION);
 
     const readyzResp = await fetch(`http://localhost:${healthPort}/readyz`);
     expect(readyzResp.status).toBe(200);
     const readyzBody = await readyzResp.json();
-    expect(readyzBody.ready).toBe(true);
-    expect(readyzBody.version).toBe(CES_PROTOCOL_VERSION);
+    expect(readyzBody.status).toBe("ok");
 
     // -- Step 5: Unknown method returns METHOD_NOT_FOUND -----------------------
     const unknownRpcId = "rpc-3";
@@ -631,3 +668,277 @@ describe("managed CES integration (real Unix socket)", () => {
     controller.abort();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Credential CRUD RPC tests
+// ---------------------------------------------------------------------------
+
+describe("credential CRUD RPC", () => {
+  /**
+   * Helper: set up a Unix socket server with credential CRUD handlers,
+   * connect a client, and complete the handshake. Returns the client
+   * socket and a serve promise for cleanup.
+   */
+  async function setupCredentialRpc(): Promise<{
+    clientSock: Socket;
+    servePromise: Promise<void>;
+  }> {
+    savedEnv = saveEnv();
+    tmpDir = mkdtempSync(join(tmpdir(), "ces-cred-integ-"));
+    const dataDir = join(tmpDir, "ces-data");
+    const securityDir = join(tmpDir, "security");
+    const socketDir = join(tmpDir, "bootstrap");
+    const socketPath = join(socketDir, "ces.sock");
+    mkdirSync(dataDir, { recursive: true });
+    mkdirSync(securityDir, { recursive: true });
+    mkdirSync(socketDir, { recursive: true });
+
+    process.env["CES_DATA_DIR"] = dataDir;
+    process.env["CES_MODE"] = "managed";
+    process.env["CREDENTIAL_SECURITY_DIR"] = securityDir;
+
+    controller = new AbortController();
+
+    const connectionPromise = acceptOneConnection(socketPath, controller.signal);
+    clientSocket = await connectToSocket(socketPath);
+    const conn = await connectionPromise;
+
+    // vellumRoot is unused when CREDENTIAL_SECURITY_DIR is set,
+    // but we pass dataDir for consistency with the backend API.
+    const handlers = buildCredentialHandlers(dataDir);
+
+    serverRpcServer = new CesRpcServer({
+      input: conn.readable,
+      output: conn.writable,
+      handlers,
+      logger: { log: () => {}, warn: () => {}, error: () => {} },
+      signal: controller.signal,
+    });
+
+    const servePromise = serverRpcServer.serve();
+
+    // Complete the handshake
+    sendMessage(clientSocket, {
+      type: "handshake_request",
+      protocolVersion: CES_PROTOCOL_VERSION,
+      sessionId: `cred-integ-${Date.now()}`,
+    });
+    const hsMessages = await readMessages(clientSocket, 1);
+    const ack = hsMessages[0] as HandshakeAck;
+    expect(ack.type).toBe("handshake_ack");
+    expect(ack.accepted).toBe(true);
+
+    return { clientSock: clientSocket, servePromise };
+  }
+
+  test("set + get round-trip", async () => {
+    const { clientSock, servePromise } = await setupCredentialRpc();
+
+    // Set credential
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-set-1",
+      kind: "request",
+      method: CesRpcMethod.SetCredential,
+      payload: { account: "test-key", value: "secret-value" },
+      timestamp: new Date().toISOString(),
+    });
+
+    const setMessages = await readMessages(clientSock, 1);
+    expect(setMessages.length).toBe(1);
+    const setResp = setMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(setResp.id).toBe("cred-set-1");
+    expect(setResp.kind).toBe("response");
+    expect(setResp.method).toBe(CesRpcMethod.SetCredential);
+    const setPayload = setResp.payload as SetCredentialResponse;
+    expect(setPayload.ok).toBe(true);
+
+    // Get credential
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-get-1",
+      kind: "request",
+      method: CesRpcMethod.GetCredential,
+      payload: { account: "test-key" },
+      timestamp: new Date().toISOString(),
+    });
+
+    const getMessages = await readMessages(clientSock, 1);
+    expect(getMessages.length).toBe(1);
+    const getResp = getMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(getResp.id).toBe("cred-get-1");
+    expect(getResp.kind).toBe("response");
+    expect(getResp.method).toBe(CesRpcMethod.GetCredential);
+    const getPayload = getResp.payload as GetCredentialResponse;
+    expect(getPayload).toEqual({ found: true, value: "secret-value" });
+
+    clientSock.end();
+    controller.abort();
+    await servePromise;
+  });
+
+  test("list includes set key", async () => {
+    const { clientSock, servePromise } = await setupCredentialRpc();
+
+    // Set a credential first
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-set-2",
+      kind: "request",
+      method: CesRpcMethod.SetCredential,
+      payload: { account: "test-key", value: "secret-value" },
+      timestamp: new Date().toISOString(),
+    });
+    await readMessages(clientSock, 1);
+
+    // List credentials
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-list-1",
+      kind: "request",
+      method: CesRpcMethod.ListCredentials,
+      payload: {},
+      timestamp: new Date().toISOString(),
+    });
+
+    const listMessages = await readMessages(clientSock, 1);
+    expect(listMessages.length).toBe(1);
+    const listResp = listMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(listResp.id).toBe("cred-list-1");
+    expect(listResp.kind).toBe("response");
+    expect(listResp.method).toBe(CesRpcMethod.ListCredentials);
+    const listPayload = listResp.payload as ListCredentialsResponse;
+    expect(listPayload.accounts).toContain("test-key");
+
+    clientSock.end();
+    controller.abort();
+    await servePromise;
+  });
+
+  test("delete credential", async () => {
+    const { clientSock, servePromise } = await setupCredentialRpc();
+
+    // Set a credential first
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-set-3",
+      kind: "request",
+      method: CesRpcMethod.SetCredential,
+      payload: { account: "test-key", value: "secret-value" },
+      timestamp: new Date().toISOString(),
+    });
+    await readMessages(clientSock, 1);
+
+    // Delete credential
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-del-1",
+      kind: "request",
+      method: CesRpcMethod.DeleteCredential,
+      payload: { account: "test-key" },
+      timestamp: new Date().toISOString(),
+    });
+
+    const delMessages = await readMessages(clientSock, 1);
+    expect(delMessages.length).toBe(1);
+    const delResp = delMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(delResp.id).toBe("cred-del-1");
+    expect(delResp.kind).toBe("response");
+    expect(delResp.method).toBe(CesRpcMethod.DeleteCredential);
+    const delPayload = delResp.payload as DeleteCredentialResponse;
+    expect(delPayload).toEqual({ result: "deleted" });
+
+    clientSock.end();
+    controller.abort();
+    await servePromise;
+  });
+
+  test("get after delete returns not found", async () => {
+    const { clientSock, servePromise } = await setupCredentialRpc();
+
+    // Set a credential
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-set-4",
+      kind: "request",
+      method: CesRpcMethod.SetCredential,
+      payload: { account: "test-key", value: "secret-value" },
+      timestamp: new Date().toISOString(),
+    });
+    await readMessages(clientSock, 1);
+
+    // Delete it
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-del-2",
+      kind: "request",
+      method: CesRpcMethod.DeleteCredential,
+      payload: { account: "test-key" },
+      timestamp: new Date().toISOString(),
+    });
+    await readMessages(clientSock, 1);
+
+    // Get after delete
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-get-2",
+      kind: "request",
+      method: CesRpcMethod.GetCredential,
+      payload: { account: "test-key" },
+      timestamp: new Date().toISOString(),
+    });
+
+    const getMessages = await readMessages(clientSock, 1);
+    expect(getMessages.length).toBe(1);
+    const getResp = getMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(getResp.id).toBe("cred-get-2");
+    expect(getResp.kind).toBe("response");
+    expect(getResp.method).toBe(CesRpcMethod.GetCredential);
+    const getPayload = getResp.payload as GetCredentialResponse;
+    expect(getPayload).toEqual({ found: false });
+
+    clientSock.end();
+    controller.abort();
+    await servePromise;
+  });
+
+  test("delete non-existent credential returns not-found", async () => {
+    const { clientSock, servePromise } = await setupCredentialRpc();
+
+    // Set a credential first to initialize the store file on disk.
+    // Without a store file, delete returns "error" (no store) rather
+    // than "not-found" (store exists, key absent).
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-set-init",
+      kind: "request",
+      method: CesRpcMethod.SetCredential,
+      payload: { account: "init-key", value: "init-value" },
+      timestamp: new Date().toISOString(),
+    });
+    await readMessages(clientSock, 1);
+
+    // Delete a credential that was never set
+    sendMessage(clientSock, {
+      type: "rpc",
+      id: "cred-del-3",
+      kind: "request",
+      method: CesRpcMethod.DeleteCredential,
+      payload: { account: "nonexistent" },
+      timestamp: new Date().toISOString(),
+    });
+
+    const delMessages = await readMessages(clientSock, 1);
+    expect(delMessages.length).toBe(1);
+    const delResp = delMessages[0] as RpcEnvelope & { type: "rpc" };
+    expect(delResp.id).toBe("cred-del-3");
+    expect(delResp.kind).toBe("response");
+    expect(delResp.method).toBe(CesRpcMethod.DeleteCredential);
+    const delPayload = delResp.payload as DeleteCredentialResponse;
+    expect(delPayload).toEqual({ result: "not-found" });
+
+    clientSock.end();
+    controller.abort();
+    await servePromise;
+  });
+});

package/src/main.ts

@@ -261,6 +261,27 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
     auditStore,
   }) 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];
+
+  handlers[CesRpcMethod.SetCredential] = (async (req: { account: string; value: string }) => {
+    const ok = await secureKeyBackend.set(req.account, req.value);
+    return { ok };
+  }) as typeof handlers[string];
+
+  handlers[CesRpcMethod.DeleteCredential] = (async (req: { account: string }) => {
+    const result = await secureKeyBackend.delete(req.account);
+    return { result };
+  }) as typeof handlers[string];
+
+  handlers[CesRpcMethod.ListCredentials] = (async () => {
+    const accounts = await secureKeyBackend.list();
+    return { accounts };
+  }) as typeof handlers[string];
+
   return handlers;
 }
 

package/src/managed-main.ts

@@ -57,6 +57,7 @@ import { materializeManagedToken } from "./materializers/managed-platform.js";
 import { HandleType, parseHandle } from "@vellumai/ces-contracts";
 import { buildLazyGetters, type ApiKeyRef } 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";
 
@@ -90,7 +91,7 @@ function ensureDataDirs(): void {
 // Build RPC handler registry (managed mode)
 // ---------------------------------------------------------------------------
 
-function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHandlerRegistry {
+function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef, secureKeyBackend: SecureKeyBackend): RpcHandlerRegistry {
   // -- Grant stores ----------------------------------------------------------
   const persistentGrantStore = new PersistentGrantStore(
     getCesGrantsDir("managed"),
@@ -110,7 +111,7 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHan
   // from the bootstrap handshake (the assistant forwards it after hatch).
   // We use a lazy getter so the handshake-provided key takes effect even
   // though handlers are built before the handshake completes.
-  const platformBaseUrl = process.env["PLATFORM_BASE_URL"] ?? "";
+  const platformBaseUrl = process.env["VELLUM_PLATFORM_URL"] ?? "";
   const assistantId = process.env["PLATFORM_ASSISTANT_ID"] ?? "";
 
   const { getAssistantApiKey, getManagedSubjectOptions, getManagedMaterializerOptions } =
@@ -123,16 +124,15 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHan
 
   if (!platformBaseUrl || !assistantId) {
     warn(
-      "PLATFORM_BASE_URL and/or PLATFORM_ASSISTANT_ID not set. " +
+      "VELLUM_PLATFORM_URL and/or PLATFORM_ASSISTANT_ID not set. " +
         "Managed credential materialisation will depend on the handshake-provided API key.",
     );
   }
 
   // -- Workspace root for command execution cwd ------------------------------
-  // Prefer WORKSPACE_DIR when set (new Docker layout mounts workspace at
-  // /workspace). Fall back to the legacy path derived from the assistant
-  // data mount for backwards compatibility.
-  const defaultWorkspaceDir = process.env["WORKSPACE_DIR"] ?? (() => {
+  // Use VELLUM_WORKSPACE_DIR when set, otherwise fall back to the legacy
+  // path derived from the assistant data mount.
+  const defaultWorkspaceDir = process.env["VELLUM_WORKSPACE_DIR"] ?? (() => {
     const assistantDataMount =
       process.env["CES_ASSISTANT_DATA_MOUNT"] ?? "/assistant-data-ro";
     return join(join(assistantDataMount, ".vellum"), "workspace");
@@ -207,7 +207,7 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHan
               return {
                 ok: false as const,
                 error:
-                  "PLATFORM_BASE_URL and/or ASSISTANT_API_KEY not set. " +
+                  "VELLUM_PLATFORM_URL and/or ASSISTANT_API_KEY not set. " +
                   "Managed credential materialisation is not available.",
               };
             }
@@ -322,6 +322,27 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHan
     auditStore,
   }) 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];
+
+  handlers[CesRpcMethod.SetCredential] = (async (req: { account: string; value: string }) => {
+    const ok = await secureKeyBackend.set(req.account, req.value);
+    return { ok };
+  }) as typeof handlers[string];
+
+  handlers[CesRpcMethod.DeleteCredential] = (async (req: { account: string }) => {
+    const result = await secureKeyBackend.delete(req.account);
+    return { result };
+  }) as typeof handlers[string];
+
+  handlers[CesRpcMethod.ListCredentials] = (async () => {
+    const accounts = await secureKeyBackend.list();
+    return { accounts };
+  }) as typeof handlers[string];
+
   return handlers;
 }
 
@@ -342,7 +363,7 @@ function startHealthServer(
       const url = new URL(req.url);
       if (url.pathname === "/healthz") {
         return new Response(
-          JSON.stringify({ status: "ok", version: CES_PROTOCOL_VERSION }),
+          JSON.stringify({ status: "ok" }),
           { headers: { "Content-Type": "application/json" } },
         );
       }
@@ -354,7 +375,7 @@ function startHealthServer(
         // without a connection anyway, so readiness is purely about the
         // process being up and able to accept a future connection.
         return new Response(
-          JSON.stringify({ ready: true, rpcConnected, version: CES_PROTOCOL_VERSION }),
+          JSON.stringify({ status: "ok", rpcConnected }),
           {
             status: 200,
             headers: { "Content-Type": "application/json" },
@@ -498,6 +519,14 @@ async function main(): Promise<void> {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 
+  // Create the secure key backend unconditionally — it's needed by both
+  // HTTP credential routes (when CES_SERVICE_TOKEN is set) and RPC
+  // credential CRUD handlers (always available).
+  const assistantDataMount =
+    process.env["CES_ASSISTANT_DATA_MOUNT"] ?? "/assistant-data-ro";
+  const vellumRoot = join(assistantDataMount, ".vellum");
+  const secureKeyBackend = createLocalSecureKeyBackend(vellumRoot);
+
   // 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.
@@ -505,11 +534,7 @@ async function main(): Promise<void> {
   let credentialDeps: CredentialRouteDeps | null = null;
 
   if (serviceToken) {
-    const assistantDataMount =
-      process.env["CES_ASSISTANT_DATA_MOUNT"] ?? "/assistant-data-ro";
-    const vellumRoot = join(assistantDataMount, ".vellum");
-    const backend = createLocalSecureKeyBackend(vellumRoot);
-    credentialDeps = { backend, serviceToken };
+    credentialDeps = { backend: secureKeyBackend, serviceToken };
     log("Credential CRUD routes enabled (CES_SERVICE_TOKEN configured)");
   } else {
     warn(
@@ -545,7 +570,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 handlers = buildHandlers(sessionIdRef, apiKeyRef);
+  const handlers = buildHandlers(sessionIdRef, apiKeyRef, secureKeyBackend);
 
   const server = new CesRpcServer({
     input: connection.readable,

package/src/materializers/local-secure-key-backend.ts

@@ -123,6 +123,61 @@ function readStoreKey(vellumRoot: string): Buffer | null {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Auto-initialization helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read or generate the v2 store key. If the key file does not exist,
+ * creates a new 32-byte random key and writes it atomically.
+ */
+function getOrReadStoreKey(vellumRoot: string): Buffer {
+  const existing = readStoreKey(vellumRoot);
+  if (existing) return existing;
+
+  const securityDir = resolveSecurityDir(vellumRoot);
+  mkdirSync(securityDir, { recursive: true });
+
+  const key = randomBytes(KEY_LENGTH);
+  const keyPath = join(securityDir, STORE_KEY_FILENAME);
+  const tmpPath = keyPath + `.tmp.${process.pid}`;
+  writeFileSync(tmpPath, key, { mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, keyPath);
+
+  return key;
+}
+
+/**
+ * Read an existing store or create a new empty v2 store. Returns the store
+ * and the AES key needed to encrypt/decrypt entries.
+ *
+ * For existing v1 stores, throws so the caller can fall back to the legacy
+ * PBKDF2 path (v1 stores cannot be auto-initialized with a store key).
+ */
+function getOrCreateStore(
+  storePath: string,
+  vellumRoot: string,
+): { store: StoreFile; aesKey: Buffer } {
+  const existing = readStore(storePath);
+  if (existing) {
+    if (existing.version === 1) {
+      throw new Error("v1 store cannot be auto-initialized");
+    }
+    const storeKey = readStoreKey(vellumRoot);
+    if (!storeKey) {
+      throw new Error("v2 store exists but store.key is missing or corrupt");
+    }
+    return { store: existing, aesKey: storeKey };
+  }
+
+  // No store exists — create a new empty v2 store
+  const aesKey = getOrReadStoreKey(vellumRoot);
+  const store: StoreFileV2 = { version: 2, entries: {} };
+  writeStore(store, storePath);
+  return { store, aesKey };
+}
+
 // ---------------------------------------------------------------------------
 // Machine entropy (must match assistant/src/security/encrypted-store.ts)
 // ---------------------------------------------------------------------------
@@ -287,19 +342,25 @@ export function createLocalSecureKeyBackend(
     // future improvement.
     async set(key: string, value: string): Promise<boolean> {
       try {
-        const store = readStore(storePath);
-        if (!store) return false;
-
+        let store: StoreFile;
         let aesKey: Buffer;
-        if (store.version === 2) {
-          const storeKey = readStoreKey(vellumRoot);
-          if (!storeKey) return false;
-          aesKey = storeKey;
-        } else {
-          // v1: derive key from machine entropy via PBKDF2
-          const entropy = entropyGetter?.() ?? staticEntropy;
-          const salt = Buffer.from(store.salt, "hex");
-          aesKey = deriveKey(salt, entropy);
+
+        try {
+          const result = getOrCreateStore(storePath, vellumRoot);
+          store = result.store;
+          aesKey = result.aesKey;
+        } catch {
+          // Fallback: v1 store or other error — try legacy PBKDF2 path
+          const existing = readStore(storePath);
+          if (!existing) return false;
+          store = existing;
+          if (store.version === 1) {
+            const entropy = entropyGetter?.() ?? staticEntropy;
+            const salt = Buffer.from(store.salt, "hex");
+            aesKey = deriveKey(salt, entropy);
+          } else {
+            return false;
+          }
         }
 
         store.entries[key] = encrypt(value, aesKey);