@vellumai/credential-executor 0.4.56 → 0.5.0

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

@@ -15,10 +15,11 @@ export type RpcError = z.infer<typeof RpcErrorSchema>;
 
 /**
  * Error returned when a local_static credential handle is used in managed
- * mode. The encrypted key store uses PBKDF2 key derivation from user
- * identity (username, homedir), but the assistant container runs as root
- * while CES runs as ces — different derived keys make decryption silently
- * fail. Managed deployments must use platform_oauth handles exclusively.
+ * mode. v2 stores use a UID-independent `store.key` file that removes the
+ * technical barrier (legacy v1 relied on PBKDF2 key derivation from user
+ * identity, which broke across container users). The restriction is now a
+ * policy choice: managed deployments use platform_oauth handles exclusively
+ * for simpler lifecycle and centralized token management.
  */
 export const MANAGED_LOCAL_STATIC_REJECTION_ERROR =
   "local_static credential handles are not supported in managed mode. " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.4.56",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/managed-main.ts

@@ -133,14 +133,16 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef): RpcHan
 
   // -- Build handler registry ------------------------------------------------
   // NOTE: local_static credential handles are NOT supported in managed mode.
-  // The encrypted key store uses PBKDF2 key derivation from user identity
-  // (username, homedir), but the assistant container runs as root while CES
-  // runs as ces — different derived keys make decryption silently fail.
-  // Managed deployments must use platform_oauth handles exclusively.
+  // v2 stores use a UID-independent `store.key` file that removes the
+  // technical barrier (legacy v1 stores relied on PBKDF2 key derivation
+  // from user identity, which broke across container users). The managed-
+  // mode restriction is now a policy choice: managed deployments use
+  // platform_oauth handles exclusively for simpler lifecycle and
+  // centralized token management.
   //
   // We provide error-returning stubs for localMaterialiser/localSubjectDeps
   // so the HTTP handler compiles but any local_static request gets a clear
-  // error message rather than a silent decryption failure.
+  // rejection message.
 
   const localMaterialiserStub = {
     materialise: async () => ({

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

@@ -12,16 +12,24 @@
  * encrypted store so subsequent reads (by both CES and the assistant)
  * see the updated value.
  *
- * The encrypted store uses AES-256-GCM with a key derived from machine-
- * specific entropy via PBKDF2. The derivation includes `userInfo().username`
- * and `userInfo().homedir`, so the key is only correct when CES runs as the
- * same OS user as the assistant.
+ * Two store formats are supported:
  *
- * **This backend must NOT be used in managed mode.** In managed (sidecar)
- * deployments, the assistant container runs as `root` while the CES
- * container runs as `ces` (uid 1001). The different user identity produces
- * a different PBKDF2-derived key, causing silent decryption failures.
- * Managed deployments must use `platform_oauth` handles exclusively.
+ * - **v2 (primary):** AES-256-GCM with a random 32-byte key stored at
+ *   `<vellumRoot>/protected/store.key`. The key is machine-independent —
+ *   any process that can read the key file can decrypt the store.
+ *
+ * - **v1 (legacy):** AES-256-GCM with a key derived from machine-specific
+ *   entropy via PBKDF2. The derivation includes `userInfo().username` and
+ *   `userInfo().homedir`, so the key is only correct when CES runs as the
+ *   same OS user as the assistant.
+ *
+ * **Managed-mode restriction (v1 only):** For legacy v1 stores, the
+ * different container user identity produces a different PBKDF2-derived
+ * key, causing silent decryption failures. v2 stores use a
+ * UID-independent `store.key` file that can be shared via volume mount,
+ * removing this technical barrier. Managed deployments currently use
+ * `platform_oauth` handles exclusively as a policy choice (simpler
+ * lifecycle, centralized token management).
  */
 
 import {
@@ -30,7 +38,7 @@ import {
   pbkdf2Sync,
   randomBytes,
 } from "node:crypto";
-import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { hostname, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -60,12 +68,42 @@ interface EncryptedEntry {
   data: string;
 }
 
-interface StoreFile {
+interface StoreFileV1 {
   version: 1;
   salt: string;
   entries: Record<string, EncryptedEntry>;
 }
 
+interface StoreFileV2 {
+  version: 2;
+  entries: Record<string, EncryptedEntry>;
+}
+
+type StoreFile = StoreFileV1 | StoreFileV2;
+
+// ---------------------------------------------------------------------------
+// Store key file (v2 format)
+// ---------------------------------------------------------------------------
+
+const STORE_KEY_FILENAME = "store.key";
+
+/**
+ * Read the v2 store key file from `<vellumRoot>/protected/store.key`.
+ * Returns the raw 32-byte key buffer, or null if the file is missing,
+ * wrong size, or unreadable.
+ */
+function readStoreKey(vellumRoot: string): Buffer | null {
+  try {
+    const keyPath = join(vellumRoot, "protected", STORE_KEY_FILENAME);
+    if (!existsSync(keyPath)) return null;
+    const buf = readFileSync(keyPath);
+    if (buf.length !== KEY_LENGTH) return null;
+    return buf;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Machine entropy (must match assistant/src/security/encrypted-store.ts)
 // ---------------------------------------------------------------------------
@@ -152,14 +190,15 @@ function readStore(storePath: string): StoreFile | null {
   try {
     const raw = readFileSync(storePath, "utf-8");
     const parsed = JSON.parse(raw);
-    if (
-      parsed.version !== 1 ||
-      typeof parsed.salt !== "string" ||
-      typeof parsed.entries !== "object"
-    ) {
-      return null;
+    if (typeof parsed.entries !== "object") return null;
+
+    if (parsed.version === 1 && typeof parsed.salt === "string") {
+      return parsed as StoreFileV1;
+    }
+    if (parsed.version === 2) {
+      return parsed as StoreFileV2;
     }
-    return parsed as StoreFile;
+    return null;
   } catch {
     return null;
   }
@@ -204,12 +243,19 @@ export function createLocalSecureKeyBackend(
         const entry = store.entries[key];
         if (!entry) return undefined;
 
-        // Lazy re-read: prefer getter (handles startup race) over static value.
-        const entropy = entropyGetter?.() ?? staticEntropy;
+        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 salt = Buffer.from(store.salt, "hex");
-        const derivedKey = deriveKey(salt, entropy);
-        return decrypt(entry, derivedKey);
+        return decrypt(entry, aesKey);
       } catch {
         return undefined;
       }
@@ -225,10 +271,19 @@ export function createLocalSecureKeyBackend(
         const store = readStore(storePath);
         if (!store) return false;
 
-        const entropy = entropyGetter?.() ?? staticEntropy;
-        const salt = Buffer.from(store.salt, "hex");
-        const derivedKey = deriveKey(salt, entropy);
-        store.entries[key] = encrypt(value, derivedKey);
+        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);
+        }
+
+        store.entries[key] = encrypt(value, aesKey);
         writeStore(store, storePath);
         return true;
       } catch {