@vellumai/credential-executor 0.5.6 → 0.5.7

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/rpc.ts

@@ -25,6 +25,12 @@
  *
  * **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";
@@ -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.7",
+  "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

@@ -351,13 +351,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 +466,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";

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

@@ -110,7 +110,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,7 +123,7 @@ 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.",
     );
   }
@@ -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.",
               };
             }
@@ -342,7 +342,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 +354,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" },

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);