@vellumai/assistant 0.4.56 → 0.5.0

package/src/security/encrypted-store.ts

@@ -1,12 +1,12 @@
 /**
- * Encrypted-at-rest key storage — fallback for systems without OS keychain.
+ * Encrypted-at-rest key storage -- fallback for systems without OS keychain.
  *
- * Uses AES-256-GCM with a key derived from machine-specific entropy:
- *   - hostname, username, platform, arch, homedir
- *   - PBKDF2 with 100k iterations + a persisted random salt
+ * v2 stores use a cryptographically random 32-byte `store.key` file as the
+ * AES-256-GCM key directly (no key derivation). The key file lives alongside
+ * `keys.enc` in `~/.vellum/protected/`.
  *
- * Secrets are stored in `~/.vellum/keys.enc` as a JSON blob encrypted
- * with the derived key. Each entry has its own IV for authenticated encryption.
+ * v1 stores (legacy) derived the AES key from machine-specific entropy via
+ * PBKDF2. Existing v1 stores are automatically migrated to v2 on first access.
  *
  * Provides the same get/set/delete interface as `keychain.ts`.
  */
@@ -17,7 +17,13 @@ import {
   pbkdf2Sync,
   randomBytes,
 } from "node:crypto";
-import { chmodSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { hostname, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -36,18 +42,27 @@ const PBKDF2_ITERATIONS =
   // In tests, PBKDF2 key derivation dominates runtime (~1-2s per file).
   // 1 iteration is sufficient for correctness; 100k is for brute-force resistance.
   process.env.BUN_TEST === "1" ? 1 : 100_000;
-const SALT_LENGTH = 32; // bytes
 
-/** On-disk format for the encrypted store. */
-interface StoreFile {
-  /** Version for future format changes. */
+// ---------------------------------------------------------------------------
+// On-disk formats
+// ---------------------------------------------------------------------------
+
+/** v1 on-disk format (legacy): PBKDF2-derived key from machine entropy. */
+interface StoreFileV1 {
   version: 1;
   /** Hex-encoded salt for PBKDF2 key derivation. */
   salt: string;
-  /** Individual encrypted entries keyed by account name. */
   entries: Record<string, EncryptedEntry>;
 }
 
+/** v2 on-disk format: random store.key used directly as AES key. */
+interface StoreFileV2 {
+  version: 2;
+  entries: Record<string, EncryptedEntry>;
+}
+
+type StoreFile = StoreFileV1 | StoreFileV2;
+
 /** A single encrypted value. */
 interface EncryptedEntry {
   /** Hex-encoded IV. */
@@ -74,10 +89,74 @@ export function _setStorePath(path: string | null): void {
 }
 
 // ---------------------------------------------------------------------------
-// Machine entropy for key derivation
+// Store key file (v2)
 // ---------------------------------------------------------------------------
 
-export function getMachineEntropy(): string {
+const STORE_KEY_FILENAME = "store.key";
+const STORE_KEY_LENGTH = 32; // bytes
+
+let storeKeyPathOverride: string | null = null;
+
+/** @internal Test-only: override the store key file path. Pass `null` to reset. */
+export function _setStoreKeyPath(path: string | null): void {
+  storeKeyPathOverride = path;
+}
+
+function getStoreKeyPath(): string {
+  return (
+    storeKeyPathOverride ?? join(dirname(getStorePath()), STORE_KEY_FILENAME)
+  );
+}
+
+/**
+ * Read the store.key file. Returns the raw 32-byte key buffer, or null
+ * if the file is missing, wrong size, or unreadable.
+ */
+function readStoreKey(): Buffer | null {
+  const keyPath = getStoreKeyPath();
+  if (!pathExists(keyPath)) return null;
+  try {
+    const buf = readFileSync(keyPath);
+    if (buf.length !== STORE_KEY_LENGTH) return null;
+    return buf;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a cryptographically random store key and write it atomically
+ * to `<dir>/store.key` with 0o600 permissions. Returns the key buffer.
+ */
+function generateAndWriteStoreKey(dir: string): Buffer {
+  ensureDir(dir);
+  const key = randomBytes(STORE_KEY_LENGTH);
+  const keyPath = join(dir, STORE_KEY_FILENAME);
+  const tmpPath = keyPath + `.tmp.${process.pid}`;
+  writeFileSync(tmpPath, key, { mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, keyPath);
+  return key;
+}
+
+/**
+ * Read the existing store key, or generate and write a new one if missing.
+ */
+function getOrReadStoreKey(dir: string): Buffer {
+  const existing = readStoreKey();
+  if (existing) return existing;
+  return generateAndWriteStoreKey(dir);
+}
+
+// ---------------------------------------------------------------------------
+// Machine entropy for key derivation (legacy v1 only)
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated @internal Kept only for v1->v2 migration path.
+ * Derives entropy from publicly-knowable machine properties.
+ */
+function getMachineEntropy(): string {
   const parts: string[] = [];
   try {
     parts.push(hostname());
@@ -99,11 +178,75 @@ export function getMachineEntropy(): string {
   return parts.join(":");
 }
 
+/**
+ * @deprecated @internal Kept only for v1->v2 migration path.
+ * Derives an AES key from machine entropy via PBKDF2.
+ */
 function deriveKey(salt: Buffer): Buffer {
   const entropy = getMachineEntropy();
   return pbkdf2Sync(entropy, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
 }
 
+// ---------------------------------------------------------------------------
+// Key resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the AES key for a given store format.
+ * - v2: reads store.key file (returns null if missing)
+ * - v1: derives key from machine entropy via PBKDF2
+ */
+function getKeyForStore(store: StoreFile): Buffer | null {
+  if (store.version === 2) {
+    return readStoreKey();
+  }
+  return deriveKey(Buffer.from(store.salt, "hex"));
+}
+
+// ---------------------------------------------------------------------------
+// v1 -> v2 migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Migrate a v1 store to v2 format:
+ * 1. Get or generate a random store.key
+ * 2. Decrypt each entry with the legacy PBKDF2-derived key
+ * 3. Re-encrypt each entry with the random store key
+ *
+ * Entries that fail to decrypt (corrupt/tampered) are logged and skipped.
+ * Returns null if a fatal error occurs (e.g. can't write store.key).
+ */
+function migrateV1ToV2(store: StoreFileV1): StoreFileV2 | null {
+  const protectedDir = dirname(getStorePath());
+
+  let storeKey: Buffer;
+  try {
+    storeKey = getOrReadStoreKey(protectedDir);
+  } catch (err) {
+    log.error({ err }, "Failed to create store.key during v1->v2 migration");
+    return null;
+  }
+
+  // Derive the legacy key for decryption
+  const legacyKey = deriveKey(Buffer.from(store.salt, "hex"));
+
+  const newEntries: Record<string, EncryptedEntry> = Object.create(null);
+
+  for (const [account, entry] of Object.entries(store.entries)) {
+    try {
+      const plaintext = decrypt(entry, legacyKey);
+      newEntries[account] = encrypt(plaintext, storeKey);
+    } catch (err) {
+      log.warn(
+        { err, account },
+        "Skipping corrupt entry during v1->v2 migration",
+      );
+    }
+  }
+
+  return { version: 2, entries: newEntries };
+}
+
 // ---------------------------------------------------------------------------
 // Store I/O
 // ---------------------------------------------------------------------------
@@ -124,25 +267,34 @@ function readStore(): StoreFile | null {
 
   try {
     const parsed = JSON.parse(raw);
-    if (
-      parsed.version !== 1 ||
-      typeof parsed.salt !== "string" ||
-      typeof parsed.entries !== "object"
-    ) {
+
+    if (typeof parsed.entries !== "object") {
       throw new Error("Encrypted store has invalid format");
     }
-    // Use null-prototype object for entries to prevent prototype pollution
-    const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
-    Object.assign(safeEntries, parsed.entries);
-    parsed.entries = safeEntries;
-    return parsed as StoreFile;
+
+    // Accept v2 (no salt required) or v1 (salt required)
+    if (parsed.version === 2) {
+      const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+      Object.assign(safeEntries, parsed.entries);
+      parsed.entries = safeEntries;
+      return parsed as StoreFileV2;
+    }
+
+    if (parsed.version === 1 && typeof parsed.salt === "string") {
+      const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+      Object.assign(safeEntries, parsed.entries);
+      parsed.entries = safeEntries;
+      return parsed as StoreFileV1;
+    }
+
+    throw new Error("Encrypted store has invalid format");
   } catch (err) {
-    // Corrupted or invalid store file — back it up and start fresh so the
+    // Corrupted or invalid store file -- back it up and start fresh so the
     // daemon doesn't crash on every credential access.
     const backupPath = `${path}.corrupt.${Date.now()}`;
     log.error(
       { err, backupPath },
-      "Encrypted store is corrupt — backing up and resetting",
+      "Encrypted store is corrupt -- backing up and resetting",
     );
     try {
       renameSync(path, backupPath);
@@ -154,48 +306,37 @@ function readStore(): StoreFile | null {
 }
 
 /**
- * Well-known filename for the persisted machine entropy.
- * Written alongside `keys.enc` so the CES sidecar (which mounts the
- * assistant data volume read-only) can derive the same AES key.
+ * Well-known filename for the persisted machine entropy (legacy).
+ * Written alongside `keys.enc` so the CES sidecar could derive the same AES key.
+ * Superseded by `store.key` in v2 format.
  */
 const ENTROPY_FILENAME = "entropy.key";
 
 /**
- * Persist the current machine entropy next to the key store so the managed
- * CES sidecar can read it and derive the same decryption key.
- *
- * Only writes in containerized (managed) mode — in local mode, CES runs on
- * the same machine and derives the same entropy natively, so the file is
- * unnecessary and would weaken offline security by persisting entropy to disk.
+ * Ensure the `store.key` file exists and is accessible on the shared mount
+ * (containerized/managed mode). Best-effort delete the old `entropy.key` file
+ * since v2 stores no longer need it.
  */
-function persistEntropy(protectedDir: string): void {
+function persistStoreKey(protectedDir: string): void {
   if (!getIsContainerized()) return;
   try {
-    const entropyPath = join(protectedDir, ENTROPY_FILENAME);
-    const tmpPath = entropyPath + `.tmp.${process.pid}`;
-    writeFileSync(tmpPath, getMachineEntropy(), { mode: 0o600 });
-    chmodSync(tmpPath, 0o600);
-    renameSync(tmpPath, entropyPath);
+    const storeKeyPath = join(protectedDir, STORE_KEY_FILENAME);
+    if (!pathExists(storeKeyPath)) {
+      // store.key should already exist from normal creation, but ensure it
+      getOrReadStoreKey(protectedDir);
+    }
   } catch {
-    // Best-effort — managed mode will log a clear error if it's missing.
+    // Best-effort
   }
-}
 
-/**
- * Backfill `entropy.key` for existing encrypted stores that predate the
- * entropy persistence feature. If the store file exists but `entropy.key`
- * does not, write it now so the managed CES sidecar can derive the key.
- */
-function backfillEntropyIfMissing(): void {
-  if (!getIsContainerized()) return;
+  // Best-effort cleanup of legacy entropy.key
   try {
-    const protectedDir = dirname(getStorePath());
     const entropyPath = join(protectedDir, ENTROPY_FILENAME);
-    if (!pathExists(entropyPath)) {
-      persistEntropy(protectedDir);
+    if (pathExists(entropyPath)) {
+      unlinkSync(entropyPath);
     }
   } catch {
-    // Best-effort — don't break reads if backfill fails.
+    // Best-effort -- don't fail if cleanup of old file doesn't work.
   }
 }
 
@@ -211,23 +352,36 @@ function writeStore(store: StoreFile): void {
   chmodSync(tmpPath, 0o600);
   renameSync(tmpPath, path);
 
-  // Keep entropy.key in sync so the managed CES sidecar can decrypt.
-  persistEntropy(protectedDir);
+  // Keep store.key in sync so the managed CES sidecar can decrypt.
+  persistStoreKey(protectedDir);
 }
 
-function getOrCreateStore(): StoreFile {
+function getOrCreateStore(): StoreFileV2 {
   const existing = readStore();
-  if (existing) return existing;
 
-  const salt = randomBytes(SALT_LENGTH);
-  const entries: Record<string, EncryptedEntry> = Object.create(null);
-  const store: StoreFile = {
-    version: 1,
-    salt: salt.toString("hex"),
-    entries,
-  };
-  writeStore(store);
-  return store;
+  if (!existing) {
+    // Fresh store: generate store.key and create v2 format
+    const protectedDir = dirname(getStorePath());
+    getOrReadStoreKey(protectedDir);
+    const entries: Record<string, EncryptedEntry> = Object.create(null);
+    const store: StoreFileV2 = { version: 2, entries };
+    writeStore(store);
+    return store;
+  }
+
+  if (existing.version === 1) {
+    // Migrate v1 -> v2
+    const migrated = migrateV1ToV2(existing);
+    if (migrated) {
+      writeStore(migrated);
+      return migrated;
+    }
+    // Migration failed fatally -- fall through and use v1 as-is won't work
+    // because we can't get the key. Throw so callers handle the error.
+    throw new Error("Failed to migrate encrypted store from v1 to v2");
+  }
+
+  return existing;
 }
 
 // ---------------------------------------------------------------------------
@@ -264,7 +418,7 @@ function decrypt(entry: EncryptedEntry, key: Buffer): string {
 }
 
 // ---------------------------------------------------------------------------
-// Public API — matches keychain.ts interface
+// Public API -- matches keychain.ts interface
 // ---------------------------------------------------------------------------
 
 /**
@@ -276,15 +430,30 @@ export function getKey(account: string): string | undefined {
     const store = readStore();
     if (!store) return undefined;
 
-    // Backfill entropy.key for existing stores that were created before
-    // entropy persistence was added. Only needed in managed mode.
-    backfillEntropyIfMissing();
+    // If v1, trigger migration
+    if (store.version === 1) {
+      const migrated = migrateV1ToV2(store);
+      if (migrated) {
+        writeStore(migrated);
+        const entry = migrated.entries[account];
+        if (!entry) return undefined;
+        const key = getKeyForStore(migrated);
+        if (!key) return undefined;
+        return decrypt(entry, key);
+      }
+      // Migration failed -- try reading with legacy key
+      const entry = store.entries[account];
+      if (!entry) return undefined;
+      const key = getKeyForStore(store);
+      if (!key) return undefined;
+      return decrypt(entry, key);
+    }
 
     const entry = store.entries[account];
     if (!entry) return undefined;
 
-    const salt = Buffer.from(store.salt, "hex");
-    const key = deriveKey(salt);
+    const key = getKeyForStore(store);
+    if (!key) return undefined;
     return decrypt(entry, key);
   } catch (err) {
     log.debug({ err, account }, "Failed to read from encrypted store");
@@ -299,8 +468,8 @@ export function getKey(account: string): string | undefined {
 export function setKey(account: string, value: string): boolean {
   try {
     const store = getOrCreateStore();
-    const salt = Buffer.from(store.salt, "hex");
-    const key = deriveKey(salt);
+    const key = getKeyForStore(store);
+    if (!key) return false;
     store.entries[account] = encrypt(value, key);
     writeStore(store);
     return true;
@@ -310,7 +479,7 @@ export function setKey(account: string, value: string): boolean {
   }
 }
 
-/** Result of a delete operation — distinguishes success, not-found, and error. */
+/** Result of a delete operation -- distinguishes success, not-found, and error. */
 export type DeleteKeyResult = "deleted" | "not-found" | "error";
 
 /**
@@ -320,8 +489,23 @@ export type DeleteKeyResult = "deleted" | "not-found" | "error";
  */
 export function deleteKey(account: string): DeleteKeyResult {
   try {
-    const store = readStore();
-    if (!store || !Object.prototype.hasOwnProperty.call(store.entries, account))
+    const existing = readStore();
+    if (!existing) return "not-found";
+
+    // Ensure v1→v2 migration happens when a store exists
+    let store: StoreFileV2;
+    if (existing.version === 1) {
+      const migrated = migrateV1ToV2(existing);
+      if (!migrated) {
+        throw new Error("Failed to migrate encrypted store from v1 to v2");
+      }
+      writeStore(migrated);
+      store = migrated;
+    } else {
+      store = existing;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(store.entries, account))
       return "not-found";
 
     delete store.entries[account];

package/src/skills/catalog-install.ts

@@ -19,6 +19,7 @@ import {
   getWorkspaceSkillsDir,
   readPlatformToken,
 } from "../util/platform.js";
+import { deleteSkillCapabilityMemory } from "./skill-memory.js";
 
 const log = getLogger("catalog-install");
 
@@ -31,6 +32,14 @@ export interface CatalogSkill {
   emoji?: string;
   includes?: string[];
   version?: string;
+  metadata?: {
+    vellum?: {
+      "display-name"?: string;
+      "activation-hints"?: string[];
+      "avoid-when"?: string[];
+      "feature-flag"?: string;
+    };
+  };
 }
 
 export interface CatalogManifest {
@@ -280,6 +289,7 @@ export function uninstallSkillLocally(skillId: string): void {
 
   rmSync(skillDir, { recursive: true, force: true });
   removeSkillsIndexEntry(skillId);
+  deleteSkillCapabilityMemory(skillId);
 }
 
 export async function installSkillLocally(

package/src/skills/managed-store.ts

@@ -13,6 +13,7 @@ import { stringify as stringifyYaml } from "yaml";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
+import { deleteSkillCapabilityMemory } from "./skill-memory.js";
 
 const log = getLogger("managed-store");
 
@@ -307,6 +308,7 @@ export function deleteManagedSkill(
   }
 
   rmSync(skillDir, { recursive: true });
+  deleteSkillCapabilityMemory(id);
   log.info({ id, path: skillDir }, "Deleted managed skill");
 
   let indexUpdated = false;