@polpo-ai/vault-crypto 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPolpo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @polpo-ai/vault-crypto — AES-256-GCM encryption helpers for Polpo vault stores.
+ *
+ * Shared by EncryptedVaultStore (file-based) and DrizzleVaultStore (database-backed).
+ * Single source of truth for vault encryption logic.
+ *
+ * Key resolution:
+ *   1. POLPO_VAULT_KEY env var (hex-encoded 32 bytes) — for CI/Docker
+ *   2. ~/.polpo/vault.key file (auto-generated on first use) — for local dev
+ *
+ * Wire format: 12-byte IV | 16-byte auth tag | ciphertext (all as a single Buffer).
+ */
+/**
+ * Resolve the encryption key from env var or key file.
+ * Auto-generates key file on first use.
+ */
+export declare function resolveKey(): Buffer;
+/**
+ * Encrypt a buffer with AES-256-GCM.
+ * Returns: IV (12 bytes) | auth tag (16 bytes) | ciphertext.
+ */
+export declare function encrypt(data: Buffer, key: Buffer): Buffer;
+/**
+ * Decrypt a buffer previously encrypted with `encrypt()`.
+ * Expects the same wire format: IV | auth tag | ciphertext.
+ */
+export declare function decrypt(blob: Buffer, key: Buffer): Buffer;
+/**
+ * Encrypt a JSON-serializable value. Returns a base64-encoded string
+ * suitable for storage in a TEXT/VARCHAR column.
+ */
+export declare function encryptJson(value: unknown, key: Buffer): string;
+/**
+ * Decrypt a base64-encoded string back to a parsed JSON value.
+ * Returns the fallback if decryption or parsing fails.
+ */
+export declare function decryptJson<T>(encoded: string, key: Buffer, fallback: T): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAqCnC;AAID;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAUzD;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAQ3E"}

package/dist/index.js

@@ -0,0 +1,118 @@
+/**
+ * @polpo-ai/vault-crypto — AES-256-GCM encryption helpers for Polpo vault stores.
+ *
+ * Shared by EncryptedVaultStore (file-based) and DrizzleVaultStore (database-backed).
+ * Single source of truth for vault encryption logic.
+ *
+ * Key resolution:
+ *   1. POLPO_VAULT_KEY env var (hex-encoded 32 bytes) — for CI/Docker
+ *   2. ~/.polpo/vault.key file (auto-generated on first use) — for local dev
+ *
+ * Wire format: 12-byte IV | 16-byte auth tag | ciphertext (all as a single Buffer).
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// ── Constants ──
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32; // 256 bits
+const GLOBAL_KEY_DIR = join(homedir(), ".polpo");
+const GLOBAL_KEY_FILE = join(GLOBAL_KEY_DIR, "vault.key");
+// ── Key Management ──
+/**
+ * Resolve the encryption key from env var or key file.
+ * Auto-generates key file on first use.
+ */
+export function resolveKey() {
+    // 1. Check env var first (CI/Docker override)
+    const envKey = process.env.POLPO_VAULT_KEY;
+    if (envKey) {
+        const buf = Buffer.from(envKey, "hex");
+        if (buf.length !== KEY_LENGTH) {
+            throw new Error(`POLPO_VAULT_KEY must be ${KEY_LENGTH * 2} hex characters (${KEY_LENGTH} bytes). Got ${envKey.length} characters.`);
+        }
+        return buf;
+    }
+    // 2. Read or generate key file
+    if (existsSync(GLOBAL_KEY_FILE)) {
+        const raw = readFileSync(GLOBAL_KEY_FILE);
+        // Key file can be raw bytes or hex-encoded
+        if (raw.length === KEY_LENGTH)
+            return raw;
+        const hex = raw.toString("utf-8").trim();
+        const buf = Buffer.from(hex, "hex");
+        if (buf.length === KEY_LENGTH)
+            return buf;
+        throw new Error(`Invalid vault key file: ${GLOBAL_KEY_FILE}. Expected ${KEY_LENGTH} bytes.`);
+    }
+    // Auto-generate
+    if (!existsSync(GLOBAL_KEY_DIR)) {
+        mkdirSync(GLOBAL_KEY_DIR, { recursive: true });
+    }
+    const key = randomBytes(KEY_LENGTH);
+    writeFileSync(GLOBAL_KEY_FILE, key);
+    // Set restrictive permissions (owner-only)
+    try {
+        chmodSync(GLOBAL_KEY_FILE, 0o600);
+    }
+    catch {
+        // chmod may fail on Windows — non-fatal
+    }
+    return key;
+}
+// ── Low-level encrypt / decrypt ──
+/**
+ * Encrypt a buffer with AES-256-GCM.
+ * Returns: IV (12 bytes) | auth tag (16 bytes) | ciphertext.
+ */
+export function encrypt(data, key) {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([iv, authTag, encrypted]);
+}
+/**
+ * Decrypt a buffer previously encrypted with `encrypt()`.
+ * Expects the same wire format: IV | auth tag | ciphertext.
+ */
+export function decrypt(blob, key) {
+    if (blob.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+        throw new Error("Vault data is corrupted (too short).");
+    }
+    const iv = blob.subarray(0, IV_LENGTH);
+    const authTag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+// ── JSON convenience helpers ──
+/**
+ * Encrypt a JSON-serializable value. Returns a base64-encoded string
+ * suitable for storage in a TEXT/VARCHAR column.
+ */
+export function encryptJson(value, key) {
+    const json = JSON.stringify(value);
+    const plain = Buffer.from(json, "utf-8");
+    const blob = encrypt(plain, key);
+    return blob.toString("base64");
+}
+/**
+ * Decrypt a base64-encoded string back to a parsed JSON value.
+ * Returns the fallback if decryption or parsing fails.
+ */
+export function decryptJson(encoded, key, fallback) {
+    try {
+        const blob = Buffer.from(encoded, "base64");
+        const plain = decrypt(blob, key);
+        return JSON.parse(plain.toString("utf-8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@polpo-ai/vault-crypto",
+  "version": "0.2.0",
+  "description": "AES-256-GCM encryption helpers for Polpo vault stores",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "OpenPolpo Contributors",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lumea-labs/polpo.git",
+    "directory": "packages/vault-crypto"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}