@captainsafia/burrow 1.3.0 → 2.0.0-preview.7add0dd

package/README.md

@@ -1,6 +1,6 @@
 # burrow
 
-Burrow is a platform-agnostic, directory-scoped secrets manager. Secrets are stored outside your repos in a local SQLite store and exportable to various formats via the CLI. For a nicer dev experience, Burrow currently stores secrets in a plain-text format outside the target repo, which means that secrets can still be leaked to other users on your machine or people who gain access to your device. But, for your day-to-day dev use, this beats keeping secrets in gitignored files in your repo.
+Burrow is a platform-agnostic, directory-scoped secrets manager. Secrets are stored outside your repos in a local SQLite store and exportable to various formats via the CLI. Secret values are encrypted at rest before being written to SQLite.
 
 <p align="center">
   <img src="demo.gif" alt="burrow demo" width="600">
@@ -19,7 +19,7 @@ Burrow is a platform-agnostic, directory-scoped secrets manager. Secrets are sto
 **Linux/macOS:**
 
 ```bash
-curl -fsSL https://safia.rocks/burrow/install.sh | sh
+curl -fsSL https://i.captainsafia.sh/captainsafia/burrow | sh
 ```
 
 ## Usage
@@ -98,6 +98,22 @@ When you request secrets for a directory, burrow:
 3. Deeper scopes override shallower ones
 4. Tombstones (from `unset`) block inheritance
 
+### Encryption at rest
+
+Burrow encrypts non-null secret values with AES-256-GCM before writing them to `store.db`.
+
+- **Primary key storage:** Burrow uses `Bun.secrets` to store a per-config encryption key in the OS credential store (Keychain on macOS, libsecret providers on Linux, and Credential Manager on Windows).
+- **Headless fallback:** if `Bun.secrets` is unavailable (for example in minimal CI containers without a running secret service), Burrow stores the key in `store.key` in the config directory with restrictive permissions on Unix.
+
+### Migration strategy
+
+Burrow uses a versioned database schema and encrypted payload format:
+
+1. **Schema migration (v1 → v2):** on first access, Burrow upgrades legacy stores to schema version 2.
+2. **In-place value migration:** all non-null plaintext values are encrypted and written back in place.
+3. **Idempotent migration:** values already marked as encrypted are skipped, so migration can be safely retried.
+4. **Future encrypted migrations:** encrypted payloads include a version prefix (`burrow:enc:v1:`), so future formats can be migrated deterministically.
+
 ## Library Usage
 
 Burrow also works as a TypeScript/JavaScript library:

package/dist/api.js

@@ -1,7 +1,7 @@
 // src/storage/index.ts
 import { Database } from "bun:sqlite";
-import { chmod, mkdir } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { chmod as chmod2, mkdir } from "node:fs/promises";
+import { join as join3 } from "node:path";
 
 // src/platform/index.ts
 import { homedir } from "node:os";
@@ -43,19 +43,188 @@ function isWindows() {
   return process.platform === "win32";
 }
 
+// src/storage/encryption.ts
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var ENCRYPTION_SERVICE = "burrow.safia.dev";
+var LEGACY_ENCRYPTION_SERVICE = "burrow";
+var ENCRYPTION_KEY_NAME_PREFIX = "store-key";
+var ENCRYPTION_KEY_FILE = "store.key";
+var ENCRYPTION_KEY_BYTES = 32;
+var ENCRYPTION_IV_BYTES = 12;
+var ENCRYPTION_AUTH_TAG_BYTES = 16;
+var ANY_ENCRYPTED_VALUE_PREFIX = "burrow:enc:";
+var ENCRYPTED_VALUE_PREFIX_V1 = "burrow:enc:v1:";
+
+class SecretValueEncryptor {
+  keySecretName;
+  fallbackKeyPath;
+  keyPromise;
+  constructor(configDir) {
+    const configHash = createHash("sha256").update(configDir).digest("hex");
+    this.keySecretName = `${ENCRYPTION_KEY_NAME_PREFIX}-${configHash}`;
+    this.fallbackKeyPath = join2(configDir, ENCRYPTION_KEY_FILE);
+  }
+  isEncryptedValue(value) {
+    return value.startsWith(ANY_ENCRYPTED_VALUE_PREFIX);
+  }
+  async encrypt(plainText) {
+    const key = await this.getOrCreateKey();
+    const iv = randomBytes(ENCRYPTION_IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ciphertext = Buffer.concat([
+      cipher.update(plainText, "utf8"),
+      cipher.final()
+    ]);
+    const authTag = cipher.getAuthTag();
+    return `${ENCRYPTED_VALUE_PREFIX_V1}${iv.toString("base64")}.${authTag.toString("base64")}.${ciphertext.toString("base64")}`;
+  }
+  async decrypt(value) {
+    if (!this.isEncryptedValue(value)) {
+      return value;
+    }
+    if (!value.startsWith(ENCRYPTED_VALUE_PREFIX_V1)) {
+      throw new Error("Unsupported encrypted value format in secrets store");
+    }
+    const encoded = value.slice(ENCRYPTED_VALUE_PREFIX_V1.length);
+    const [ivBase64, authTagBase64, ciphertextBase64, ...rest] = encoded.split(".");
+    if (rest.length > 0 || ivBase64 === undefined || authTagBase64 === undefined || ciphertextBase64 === undefined) {
+      throw new Error("Malformed encrypted value in secrets store");
+    }
+    const iv = Buffer.from(ivBase64, "base64");
+    const authTag = Buffer.from(authTagBase64, "base64");
+    const ciphertext = Buffer.from(ciphertextBase64, "base64");
+    if (iv.byteLength !== ENCRYPTION_IV_BYTES) {
+      throw new Error("Malformed encrypted value (invalid IV length)");
+    }
+    if (authTag.byteLength !== ENCRYPTION_AUTH_TAG_BYTES) {
+      throw new Error("Malformed encrypted value (invalid auth tag length)");
+    }
+    const key = await this.getOrCreateKey();
+    try {
+      const decipher = createDecipheriv("aes-256-gcm", key, iv);
+      decipher.setAuthTag(authTag);
+      const decrypted = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final()
+      ]);
+      return decrypted.toString("utf8");
+    } catch {
+      throw new Error("Failed to decrypt value from secrets store. The encryption key may be unavailable or has changed.");
+    }
+  }
+  async getOrCreateKey() {
+    this.keyPromise ??= this.loadOrCreateKey();
+    return this.keyPromise;
+  }
+  async loadOrCreateKey() {
+    const fallbackKey = await this.readFallbackKey();
+    if (fallbackKey) {
+      await this.tryStoreInBunSecrets(fallbackKey);
+      return fallbackKey;
+    }
+    const bunSecretsKey = await this.readKeyFromBunSecrets();
+    if (bunSecretsKey) {
+      return bunSecretsKey;
+    }
+    const generatedKey = randomBytes(ENCRYPTION_KEY_BYTES);
+    const storedInBunSecrets = await this.tryStoreInBunSecrets(generatedKey);
+    if (!storedInBunSecrets) {
+      await this.writeFallbackKey(generatedKey);
+    }
+    return generatedKey;
+  }
+  async readKeyFromBunSecrets() {
+    let keyMaterial;
+    try {
+      keyMaterial = await Bun.secrets.get({
+        service: ENCRYPTION_SERVICE,
+        name: this.keySecretName
+      });
+    } catch {
+      return;
+    }
+    if (keyMaterial === null) {
+      keyMaterial = await this.readKeyFromLegacyService();
+      if (keyMaterial === null) {
+        return;
+      }
+      const key = parseKeyMaterial(keyMaterial, `Bun.secrets (${LEGACY_ENCRYPTION_SERVICE})`);
+      await this.tryStoreInBunSecrets(key);
+      return key;
+    }
+    return parseKeyMaterial(keyMaterial, "Bun.secrets");
+  }
+  async tryStoreInBunSecrets(key) {
+    try {
+      await Bun.secrets.set({
+        service: ENCRYPTION_SERVICE,
+        name: this.keySecretName,
+        value: key.toString("base64")
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async readKeyFromLegacyService() {
+    try {
+      return await Bun.secrets.get({
+        service: LEGACY_ENCRYPTION_SERVICE,
+        name: this.keySecretName
+      });
+    } catch {
+      return null;
+    }
+  }
+  async readFallbackKey() {
+    try {
+      const keyMaterial = await readFile(this.fallbackKeyPath, "utf8");
+      return parseKeyMaterial(keyMaterial, this.fallbackKeyPath);
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+  }
+  async writeFallbackKey(key) {
+    await writeFile(this.fallbackKeyPath, `${key.toString("base64")}
+`, "utf8");
+    if (!isWindows()) {
+      await chmod(this.fallbackKeyPath, 384);
+    }
+  }
+}
+function parseKeyMaterial(value, source) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`Encryption key in ${source} is empty`);
+  }
+  const key = Buffer.from(trimmed, "base64");
+  if (key.byteLength !== ENCRYPTION_KEY_BYTES) {
+    throw new Error(`Encryption key in ${source} must be ${ENCRYPTION_KEY_BYTES} bytes`);
+  }
+  return key;
+}
+
 // src/storage/index.ts
 var DEFAULT_STORE_FILE = "store.db";
+var STORE_VERSION = 2;
 
 class Storage {
   configDir;
   storeFileName;
+  encryptor;
   db = null;
   constructor(options = {}) {
     this.configDir = options.configDir ?? getConfigDir();
     this.storeFileName = options.storeFileName ?? DEFAULT_STORE_FILE;
+    this.encryptor = new SecretValueEncryptor(this.configDir);
   }
   get storePath() {
-    return join2(this.configDir, this.storeFileName);
+    return join3(this.configDir, this.storeFileName);
   }
   async ensureDb() {
     if (this.db) {
@@ -63,11 +232,11 @@ class Storage {
     }
     await mkdir(this.configDir, { recursive: true });
     if (!isWindows()) {
-      await chmod(this.configDir, 448);
+      await chmod2(this.configDir, 448);
     }
     this.db = new Database(this.storePath);
     if (!isWindows()) {
-      await chmod(this.storePath, 384);
+      await chmod2(this.storePath, 384);
     }
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`
@@ -90,23 +259,52 @@ class Storage {
     this.db.run("CREATE INDEX IF NOT EXISTS idx_trusted_paths_inode ON trusted_paths (inode)");
     const versionResult = this.db.query("PRAGMA user_version").get();
     const currentVersion = versionResult?.user_version ?? 0;
-    if (currentVersion === 0) {
-      this.db.run("PRAGMA user_version = 1");
-    } else if (currentVersion !== 1) {
-      throw new Error(`Unsupported store version: ${currentVersion}. Expected: 1`);
+    if (currentVersion === 0 || currentVersion === 1) {
+      await this.migrateValuesToEncryption(this.db);
+      this.db.run(`PRAGMA user_version = ${STORE_VERSION}`);
+    } else if (currentVersion !== STORE_VERSION) {
+      throw new Error(`Unsupported store version: ${currentVersion}. Expected: ${STORE_VERSION}`);
     }
     return this.db;
   }
+  async migrateValuesToEncryption(db) {
+    const rows = db.query("SELECT path, key, value FROM secrets WHERE value IS NOT NULL").all();
+    if (rows.length === 0) {
+      return;
+    }
+    const updates = [];
+    for (const row of rows) {
+      if (this.encryptor.isEncryptedValue(row.value)) {
+        continue;
+      }
+      updates.push({
+        path: row.path,
+        key: row.key,
+        value: await this.encryptor.encrypt(row.value)
+      });
+    }
+    if (updates.length === 0) {
+      return;
+    }
+    const updateSecret = db.query("UPDATE secrets SET value = ? WHERE path = ? AND key = ?");
+    const applyUpdates = db.transaction((pendingUpdates) => {
+      for (const update of pendingUpdates) {
+        updateSecret.run(update.value, update.path, update.key);
+      }
+    });
+    applyUpdates(updates);
+  }
   async setSecret(canonicalPath, key, value) {
     const db = await this.ensureDb();
     const updatedAt = new Date().toISOString();
+    const storedValue = value === null ? null : await this.encryptor.encrypt(value);
     db.query(`
       INSERT INTO secrets (path, key, value, updated_at)
       VALUES (?, ?, ?, ?)
       ON CONFLICT(path, key) DO UPDATE SET
         value = excluded.value,
         updated_at = excluded.updated_at
-    `).run(canonicalPath, key, value, updatedAt);
+    `).run(canonicalPath, key, storedValue, updatedAt);
   }
   async getPathSecrets(canonicalPath) {
     const db = await this.ensureDb();
@@ -116,8 +314,9 @@ class Storage {
     }
     const secrets = {};
     for (const row of rows) {
+      const decodedValue = row.value === null ? null : await this.encryptor.decrypt(row.value);
       secrets[row.key] = {
-        value: row.value,
+        value: decodedValue,
         updatedAt: row.updated_at
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captainsafia/burrow",
-  "version": "1.3.0",
+  "version": "2.0.0-preview.7add0dd",
   "description": "Platform-agnostic, directory-scoped secrets manager",
   "type": "module",
   "main": "dist/api.js",