@vellumai/credential-executor 0.8.12-staging.2 → 0.9.0-staging.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.8.12-staging.2",
+  "version": "0.9.0-staging.1",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -12,7 +12,10 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { createLocalSecureKeyBackend } from "../materializers/local-secure-key-backend.js";
+import {
+  createLocalSecureKeyBackend,
+  StoreUnavailableError,
+} from "../materializers/local-secure-key-backend.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -153,4 +156,49 @@ describe("createLocalSecureKeyBackend — filesystem", () => {
     const result = await backend.delete("anything");
     expect(result).toBe("error");
   });
+
+  // -------------------------------------------------------------------------
+  // UNAVAILABLE (store exists but cannot be read / decrypted) must be distinct
+  // from ABSENT (no store, or the store reads cleanly but lacks the key). The
+  // former throws so the RPC layer reports `unreachable`; the latter returns
+  // undefined/[]. This is the cold-start fix: a transiently-unreadable store or
+  // missing key material must never masquerade as "credential not found".
+  // -------------------------------------------------------------------------
+
+  test("get() THROWS (not undefined) when the store file exists but is unreadable", async () => {
+    const { securityDir, vellumRoot } = setup();
+    // A store file that exists but cannot be parsed (e.g. a partial/corrupt
+    // read) — distinct from no store at all.
+    writeFileSync(join(securityDir, "keys.enc"), "{ not valid json", {
+      mode: 0o600,
+    });
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    await expect(backend.get("anything")).rejects.toThrow(StoreUnavailableError);
+  });
+
+  test("get() returns undefined when the store reads cleanly but the key is absent", async () => {
+    const { vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    await backend.set("present/key", "v"); // valid store with one entry
+    // A genuinely missing key in a readable store is ABSENT, not unavailable.
+    expect(await backend.get("absent/key")).toBeUndefined();
+  });
+
+  test("get() THROWS when a v2 entry exists but store.key is missing (cold-start key-material race)", async () => {
+    const { securityDir, vellumRoot } = setup();
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    await backend.set("k", "v"); // creates the v2 store + store.key
+    expect(await backend.get("k")).toBe("v"); // sanity: warm read works
+    // Simulate the cold-start window where the key material is transiently
+    // unavailable: the entry still exists, but it cannot be decrypted yet.
+    rmSync(join(securityDir, "store.key"));
+    await expect(backend.get("k")).rejects.toThrow(StoreUnavailableError);
+  });
+
+  test("list() THROWS (not []) when the store file exists but is unreadable", async () => {
+    const { securityDir, vellumRoot } = setup();
+    writeFileSync(join(securityDir, "keys.enc"), "{ corrupt", { mode: 0o600 });
+    const backend = createLocalSecureKeyBackend(vellumRoot);
+    await expect(backend.list()).rejects.toThrow(StoreUnavailableError);
+  });
 });

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

@@ -65,7 +65,7 @@ function rowToRecord(row: OAuthConnectionRow): OAuthConnectionRecord {
  * Create a read-only OAuth connection lookup backed by the assistant's
  * SQLite database.
  *
- * @param workspaceDir - The workspace directory (e.g. `~/.vellum/workspace`).
+ * @param workspaceDir - The workspace directory (e.g. `$VELLUM_WORKSPACE_DIR`).
  */
 export function createLocalOAuthLookup(
   workspaceDir: string,

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

@@ -278,6 +278,34 @@ function readStore(storePath: string): StoreFile | null {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `get()` / `list()` when the credential store is UNAVAILABLE — the
+ * store file exists but cannot be read, the v2 `store.key` (or v1 machine
+ * entropy) key material is missing, or an entry fails to decrypt. This is
+ * deliberately DISTINCT from a credential being ABSENT (no store file yet, or
+ * the store reads cleanly but lacks the requested key), which returns
+ * `undefined` / `[]`.
+ *
+ * The distinction matters on CES cold start: for a brief window after a
+ * (re)start the key material can be transiently unreadable (see the
+ * `entropyGetter` note on {@link createLocalSecureKeyBackend} — "the file may
+ * not exist at construction time but appears later"). Returning `undefined`
+ * there reports a credential that EXISTS as "not found"; throwing instead
+ * surfaces the true state to the RPC layer (a `HANDLER_ERROR` the daemon maps
+ * to `unreachable`), so a transient read failure is never mistaken for a
+ * missing credential.
+ */
+export class StoreUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreUnavailableError";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Backend implementation
 // ---------------------------------------------------------------------------
@@ -310,29 +338,50 @@ export function createLocalSecureKeyBackend(
 
   return {
     async get(key: string): Promise<string | undefined> {
-      try {
-        const store = readStore(storePath);
-        if (!store) return undefined;
-
-        const entry = store.entries[key];
-        if (!entry) return undefined;
-
-        let aesKey: Buffer;
-        if (store.version === 2) {
-          const storeKey = readStoreKey(vellumRoot);
-          if (!storeKey) return undefined;
-          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);
+      const store = readStore(storePath);
+      if (!store) {
+        // No store file at all → the credential is genuinely ABSENT. A store
+        // file that EXISTS but could not be read is UNAVAILABLE, not absent —
+        // surface it rather than reporting a false "not found".
+        if (existsSync(storePath)) {
+          throw new StoreUnavailableError(
+            "credential store exists but could not be read",
+          );
         }
-
-        return decrypt(entry, aesKey);
-      } catch {
         return undefined;
       }
+
+      const entry = store.entries[key];
+      // The store read cleanly and has no such entry → genuinely not found.
+      if (!entry) return undefined;
+
+      let aesKey: Buffer;
+      if (store.version === 2) {
+        const storeKey = readStoreKey(vellumRoot);
+        if (!storeKey) {
+          // The entry exists but the key material to decrypt it is unavailable
+          // (the cold-start race). Unavailable, NOT not-found.
+          throw new StoreUnavailableError(
+            "v2 store entry present but store.key is unavailable",
+          );
+        }
+        aesKey = storeKey;
+      } else {
+        // v1: derive key from machine entropy via PBKDF2. `entropy` is an
+        // OPTIONAL override (managed mode); when undefined, deriveKey falls
+        // back to local machine entropy — the normal local-mode path, so an
+        // undefined value here is NOT "unavailable". A v1 cold-start race (the
+        // override entropy file not yet present) yields the wrong key and
+        // surfaces below as a decrypt failure → unavailable.
+        const entropy = entropyGetter?.() ?? staticEntropy;
+        const salt = Buffer.from(store.salt, "hex");
+        aesKey = deriveKey(salt, entropy);
+      }
+
+      // A decrypt failure means corrupt data or wrong key material — the
+      // credential exists but we cannot produce its value. Let it propagate as
+      // unavailable rather than swallowing it into a false "not found".
+      return decrypt(entry, aesKey);
     },
 
     // NOTE: read-modify-write without file locking. The atomic rename
@@ -387,13 +436,18 @@ export function createLocalSecureKeyBackend(
     },
 
     async list(): Promise<string[]> {
-      try {
-        const store = readStore(storePath);
-        if (!store) return [];
-        return Object.keys(store.entries);
-      } catch {
+      const store = readStore(storePath);
+      if (!store) {
+        // Mirror get(): a store file that exists but is unreadable is
+        // UNAVAILABLE (surface it), not an empty credential set.
+        if (existsSync(storePath)) {
+          throw new StoreUnavailableError(
+            "credential store exists but could not be read",
+          );
+        }
         return [];
       }
+      return Object.keys(store.entries);
     },
   };
 }