π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(encryption): ADR-096 Phase 1 β vault primitives + tests
Reuvencb9a9f346c27
diff --git a/v3/@claude-flow/cli/__tests__/encryption-vault.test.ts b/v3/@claude-flow/cli/__tests__/encryption-vault.test.tsnew file mode 100644index 0000000000..ae845fef69--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/encryption-vault.test.ts@@ -0,0 +1,268 @@+/**+ * Tests for src/encryption/vault.ts (ADR-096 Phase 1).+ *+ * These pin the wire format + cipher contract so future iterations can't+ * silently change either without a coordinated migration. The format is+ * meant to be stable across versions β every encrypted file shipped before+ * a format change has to keep decrypting under the new code.+ */++import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { randomBytes } from 'node:crypto';++import {+ MAGIC,+ decodeKey,+ decryptBuffer,+ encryptBuffer,+ getKey,+ isEncryptedBlob,+ isEncryptionEnabled,+} from '../src/encryption/vault.js';++// Per-test env reset β these tests mutate process.env and must not leak.+const SAVED_ENV: Record<string, string | undefined> = {};+function saveEnv(...names: string[]) {+ for (const n of names) SAVED_ENV[n] = process.env[n];+}+function restoreEnv() {+ for (const [n, v] of Object.entries(SAVED_ENV)) {+ if (v === undefined) delete process.env[n];+ else process.env[n] = v;+ }+}++describe('vault (ADR-096 Phase 1)', () => {+ beforeEach(() => {+ saveEnv('CLAUDE_FLOW_ENCRYPT_AT_REST', 'CLAUDE_FLOW_ENCRYPTION_KEY');+ });+ afterEach(() => {+ restoreEnv();+ });++ describe('isEncryptionEnabled', () => {+ it('is false when the env var is unset', () => {+ delete process.env.CLAUDE_FLOW_ENCRYPT_AT_REST;+ expect(isEncryptionEnabled()).toBe(false);+ });++ it.each(['1', 'true', 'TRUE', 'yes', 'on', ' on '])(+ 'is true for "%s"',+ (v) => {+ process.env.CLAUDE_FLOW_ENCRYPT_AT_REST = v;+ expect(isEncryptionEnabled()).toBe(true);+ },+ );++ it.each(['0', 'false', 'no', 'off', 'maybe', ''])(+ 'is false for "%s"',+ (v) => {+ process.env.CLAUDE_FLOW_ENCRYPT_AT_REST = v;+ expect(isEncryptionEnabled()).toBe(false);+ },+ );+ });++ describe('decodeKey', () => {+ it('decodes 64-char hex', () => {+ const hex = 'a'.repeat(64);+ expect(decodeKey(hex).length).toBe(32);+ });++ it('decodes 44-char base64 (padded)', () => {+ const b64 = randomBytes(32).toString('base64');+ expect(b64).toMatch(/=$/);+ expect(decodeKey(b64).length).toBe(32);+ });++ it('decodes 43-char base64 (unpadded)', () => {+ const b64 = randomBytes(32).toString('base64').replace(/=+$/, '');+ expect(decodeKey(b64).length).toBe(32);+ });++ it('rejects too-short hex', () => {+ expect(() => decodeKey('a'.repeat(63))).toThrow(/Invalid/);+ });++ it('rejects too-long hex', () => {+ expect(() => decodeKey('a'.repeat(65))).toThrow(/Invalid/);+ });++ it('rejects non-hex / non-base64 garbage', () => {+ expect(() => decodeKey('not a key at all!!!')).toThrow(/Invalid/);+ });++ it('rejects base64 of the wrong length (16 bytes)', () => {+ const b64 = randomBytes(16).toString('base64');+ expect(() => decodeKey(b64)).toThrow(/Invalid/);+ });++ it('trims surrounding whitespace before validating', () => {+ const hex = 'b'.repeat(64);+ expect(decodeKey(` ${hex}\n`).length).toBe(32);+ });+ });++ describe('getKey', () => {+ it('throws with a clear message when the env var is unset', () => {+ delete process.env.CLAUDE_FLOW_ENCRYPTION_KEY;+ expect(() => getKey()).toThrow(/CLAUDE_FLOW_ENCRYPTION_KEY/);+ });++ it('returns a 32-byte buffer when the env var holds valid hex', () => {+ process.env.CLAUDE_FLOW_ENCRYPTION_KEY = 'c'.repeat(64);+ expect(getKey().length).toBe(32);+ });+ });++ describe('encrypt / decrypt round-trip', () => {+ const key = randomBytes(32);++ it('round-trips an empty buffer', () => {+ const blob = encryptBuffer(Buffer.alloc(0), key);+ expect(decryptBuffer(blob, key).length).toBe(0);+ });++ it('round-trips small text', () => {+ const plain = Buffer.from('hello world', 'utf-8');+ expect(decryptBuffer(encryptBuffer(plain, key), key).equals(plain)).toBe(+ true,+ );+ });++ it('round-trips JSON the way session-tools writes it', () => {+ const obj = { sessionId: 'sess-1', name: 'audit', stats: { tasks: 5 } };+ const plain = Buffer.from(JSON.stringify(obj, null, 2), 'utf-8');+ const round = JSON.parse(+ decryptBuffer(encryptBuffer(plain, key), key).toString('utf-8'),+ );+ expect(round).toEqual(obj);+ });++ it('round-trips a large random buffer (megabyte-scale)', () => {+ const plain = randomBytes(1_048_576); // 1MB+ expect(decryptBuffer(encryptBuffer(plain, key), key).equals(plain)).toBe(+ true,+ );+ });++ it('produces different ciphertext for the same plaintext (random IV)', () => {+ const plain = Buffer.from('repeated', 'utf-8');+ const a = encryptBuffer(plain, key);+ const b = encryptBuffer(plain, key);+ expect(a.equals(b)).toBe(false);+ });+ });++ describe('wire format', () => {+ it('begins with the RFE1 magic', () => {+ const blob = encryptBuffer(Buffer.from('x', 'utf-8'), randomBytes(32));+ expect(blob.subarray(0, 4)).toEqual(MAGIC);+ });++ it('has at least magic+iv+tag bytes (32) for any plaintext', () => {+ const blob = encryptBuffer(Buffer.alloc(0), randomBytes(32));+ // magic(4) + iv(12) + tag(16) = 32 minimum+ expect(blob.length).toBeGreaterThanOrEqual(32);+ });+ });++ describe('isEncryptedBlob', () => {+ it('detects a freshly-encrypted blob', () => {+ const blob = encryptBuffer(Buffer.from('hi', 'utf-8'), randomBytes(32));+ expect(isEncryptedBlob(blob)).toBe(true);+ });++ it('returns false for plaintext JSON', () => {+ expect(isEncryptedBlob(Buffer.from('{"a":1}', 'utf-8'))).toBe(false);+ });++ it('returns false for the SQLite header', () => {+ // Real .swarm/memory.db files start with "SQLite format 3\0"+ expect(isEncryptedBlob(Buffer.from('SQLite format 3\0', 'utf-8'))).toBe(+ false,+ );+ });++ it('returns false for a blob shorter than the magic+iv+tag minimum', () => {+ expect(isEncryptedBlob(MAGIC)).toBe(false); // magic alone, but length < 32+ });++ it('returns false for a non-Buffer input', () => {+ expect(isEncryptedBlob('not a buffer' as unknown as Buffer)).toBe(false);+ });+ });++ describe('tamper detection', () => {+ const key = randomBytes(32);++ it('rejects a blob with a flipped ciphertext byte', () => {+ const plain = Buffer.from('sensitive data', 'utf-8');+ const blob = Buffer.from(encryptBuffer(plain, key));+ // Flip a byte inside the ciphertext region (after magic+iv, before tag)+ blob[20] ^= 0xff;+ expect(() => decryptBuffer(blob, key)).toThrow();+ });++ it('rejects a blob with a flipped auth-tag byte', () => {+ const blob = Buffer.from(+ encryptBuffer(Buffer.from('payload', 'utf-8'), key),+ );+ blob[blob.length - 1] ^= 0xff;+ expect(() => decryptBuffer(blob, key)).toThrow();+ });++ it('rejects a blob with a flipped IV byte', () => {+ const blob = Buffer.from(+ encryptBuffer(Buffer.from('payload', 'utf-8'), key),+ );+ blob[5] ^= 0xff; // inside the IV region (offset 4..15)+ expect(() => decryptBuffer(blob, key)).toThrow();+ });++ it('rejects a blob with a corrupted magic', () => {+ const blob = Buffer.from(+ encryptBuffer(Buffer.from('payload', 'utf-8'), key),+ );+ blob[0] = 0x00; // break the magic+ expect(() => decryptBuffer(blob, key)).toThrow(/bad magic/);+ });++ it('rejects a blob shorter than the minimum length', () => {+ expect(() => decryptBuffer(Buffer.alloc(10), key)).toThrow(/too short/);+ });++ it('rejects a wrong-key decrypt (GCM auth fails)', () => {+ const blob = encryptBuffer(Buffer.from('payload', 'utf-8'), key);+ const wrongKey = randomBytes(32);+ expect(() => decryptBuffer(blob, wrongKey)).toThrow();+ });+ });++ describe('input validation', () => {+ const key = randomBytes(32);++ it('encryptBuffer rejects a non-Buffer plaintext', () => {+ expect(() =>+ encryptBuffer('string' as unknown as Buffer, key),+ ).toThrow(/Buffer/);+ });++ it('encryptBuffer rejects a wrong-size key', () => {+ expect(() =>+ encryptBuffer(Buffer.from('x'), randomBytes(16)),+ ).toThrow(/32-byte/);+ });++ it('decryptBuffer rejects a non-Buffer blob', () => {+ expect(() =>+ decryptBuffer('string' as unknown as Buffer, key),+ ).toThrow(/Buffer/);+ });++ it('decryptBuffer rejects a wrong-size key', () => {+ const blob = encryptBuffer(Buffer.from('x'), key);+ expect(() => decryptBuffer(blob, randomBytes(16))).toThrow(/32-byte/);+ });+ });+});diff --git a/v3/@claude-flow/cli/src/encryption/vault.ts b/v3/@claude-flow/cli/src/encryption/vault.tsnew file mode 100644index 0000000000..e02d4ca228--- /dev/null+++ b/v3/@claude-flow/cli/src/encryption/vault.ts@@ -0,0 +1,192 @@+/**+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).+ *+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a+ * symmetric key, using a magic-byte format so readers of older plaintext+ * stores can detect-then-pass-through during the migration window.+ *+ * Phase 1 deliberately ships only the cipher primitives + the env-var key+ * source. Keychain (keytar) and interactive passphrase resolution land in+ * a follow-up iteration so the blast radius of this commit is limited to+ * a single self-contained module with no native dependencies.+ *+ * Wire format (output of encryptBuffer):+ *+ * +---------+-----------+----------------+--------++ * | magic 4 | iv 12 | ciphertext N | tag 16 |+ * +---------+-----------+----------------+--------++ * "RFE1" random AES-256-GCM GCM+ *+ * The magic distinguishes encrypted blobs from plaintext during the+ * incremental migration: readers call isEncryptedBlob() and either+ * decryptBuffer() or treat the bytes as plaintext, so existing+ * .claude-flow/sessions/*.json files keep working unchanged.+ */++import {+ createCipheriv,+ createDecipheriv,+ randomBytes,+ timingSafeEqual,+} from 'node:crypto';++// ββ Constants ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++/** ASCII "RFE1" β Ruflo File Encrypted v1. 4 bytes. */+export const MAGIC = Buffer.from([0x52, 0x46, 0x45, 0x31]); // "RFE1"+const MAGIC_LEN = MAGIC.length; // 4+const IV_LEN = 12; // GCM-recommended nonce size+const TAG_LEN = 16; // GCM auth tag+const KEY_LEN = 32; // AES-256+const ALG = 'aes-256-gcm' as const;+const MIN_BLOB_LEN = MAGIC_LEN + IV_LEN + TAG_LEN; // empty plaintext still has these++const ENV_ENABLE_FLAG = 'CLAUDE_FLOW_ENCRYPT_AT_REST';+const ENV_KEY_VAR = 'CLAUDE_FLOW_ENCRYPTION_KEY';++// ββ Public API βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++/**+ * True when at-rest encryption should be applied to writes.+ *+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else+ * β including unset β keeps the legacy plaintext path. This is the gate+ * that lets the 1865-test baseline keep passing unchanged while users opt+ * into encryption.+ */+export function isEncryptionEnabled(): boolean {+ const v = process.env[ENV_ENABLE_FLAG];+ if (typeof v !== 'string') return false;+ const norm = v.trim().toLowerCase();+ return norm === '1' || norm === 'true' || norm === 'yes' || norm === 'on';+}++/**+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.+ *+ * Phase 1 supports only the env-var source; keychain and passphrase+ * resolution are deferred to a follow-up iteration (see ADR-096). When+ * encryption is enabled but no key resolves, this throws with a clear+ * message rather than silently falling back to plaintext (fail-closed).+ *+ * Accepted encodings (auto-detected by length):+ * - 64-char hex (32 bytes)+ * - 44-char base64 (32 bytes + padding)+ * - exactly 32 raw bytes (rare; for callers that pre-decode)+ *+ * Anything else is rejected β we'd rather fail loudly than encrypt with a+ * truncated key.+ */+export function getKey(): Buffer {+ const raw = process.env[ENV_KEY_VAR];+ if (!raw) {+ throw new Error(+ `${ENV_ENABLE_FLAG} is set but ${ENV_KEY_VAR} is not. ` ++ `Provide a 32-byte key as 64-char hex or 44-char base64. ` ++ `See ADR-096 for keychain/passphrase support (coming in a follow-up).`,+ );+ }+ return decodeKey(raw);+}++/**+ * Decode a key string. Exposed for testing and for the future passphrase+ * resolver, which will scrypt-derive a Buffer and hand it back through here+ * to share the same length-check.+ */+export function decodeKey(raw: string): Buffer {+ const trimmed = raw.trim();+ // Hex first β strict 64 chars [0-9a-fA-F]+ if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {+ return Buffer.from(trimmed, 'hex');+ }+ // Base64 β accept padded 44-char or unpadded 43-char forms+ if (/^[A-Za-z0-9+/]{43}=?$/.test(trimmed)) {+ const buf = Buffer.from(trimmed, 'base64');+ if (buf.length === KEY_LEN) return buf;+ }+ throw new Error(+ `Invalid ${ENV_KEY_VAR}: expected 32-byte key as 64-char hex or 44-char base64`,+ );+}++/**+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).+ *+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under+ * GCM is catastrophic β every call MUST produce a different IV. Node's+ * randomBytes is csprng-backed so this is automatic; the function takes+ * no IV input deliberately.+ */+export function encryptBuffer(plaintext: Buffer, key: Buffer): Buffer {+ if (!Buffer.isBuffer(plaintext)) {+ throw new TypeError('encryptBuffer: plaintext must be a Buffer');+ }+ if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {+ throw new TypeError(`encryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);+ }+ const iv = randomBytes(IV_LEN);+ const cipher = createCipheriv(ALG, key, iv);+ const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);+ const tag = cipher.getAuthTag();+ return Buffer.concat([MAGIC, iv, ciphertext, tag]);+}++/**+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM+ * auth tag fail loudly on tamper (Node throws "Unsupported state or+ * unable to authenticate data" β we let that propagate).+ *+ * Pre-condition: caller has already determined this is an encrypted+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a+ * mistaken plaintext blob still fails loudly rather than producing+ * garbage.+ */+export function decryptBuffer(blob: Buffer, key: Buffer): Buffer {+ if (!Buffer.isBuffer(blob)) {+ throw new TypeError('decryptBuffer: blob must be a Buffer');+ }+ if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {+ throw new TypeError(`decryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);+ }+ if (blob.length < MIN_BLOB_LEN) {+ throw new Error(+ `decryptBuffer: blob too short (${blob.length}B; need >= ${MIN_BLOB_LEN}B)`,+ );+ }+ const magic = blob.subarray(0, MAGIC_LEN);+ // timingSafeEqual to avoid an oracle on the magic bytes specifically;+ // not strictly required (the magic isn't secret) but cheap and correct.+ if (!timingSafeEqual(magic, MAGIC)) {+ throw new Error(+ 'decryptBuffer: bad magic β blob is not Ruflo-encrypted (RFE1)',+ );+ }+ const iv = blob.subarray(MAGIC_LEN, MAGIC_LEN + IV_LEN);+ const tag = blob.subarray(blob.length - TAG_LEN);+ const ciphertext = blob.subarray(MAGIC_LEN + IV_LEN, blob.length - TAG_LEN);++ const decipher = createDecipheriv(ALG, key, iv);+ decipher.setAuthTag(tag);+ return Buffer.concat([decipher.update(ciphertext), decipher.final()]);+}++/**+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is+ * long enough to be a valid encrypted blob. Used by readers during the+ * incremental migration: legacy plaintext files return false and flow+ * through the existing read path unchanged.+ *+ * Note: this is a heuristic. A plaintext file that happens to start with+ * "RFE1" would be misdetected β we accept that vanishingly small risk+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption+ * will then fail with a clear error rather than silently corrupt.+ */+export function isEncryptedBlob(blob: Buffer): boolean {+ if (!Buffer.isBuffer(blob)) return false;+ if (blob.length < MIN_BLOB_LEN) return false;+ return timingSafeEqual(blob.subarray(0, MAGIC_LEN), MAGIC);+}