@cleocode/core 2026.4.11 → 2026.4.13

package/src/store/__tests__/api-key-kdf.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Unit tests for api-key-kdf.ts (T349).
+ *
+ * @task T349
+ * @epic T310
+ */
+
+import { createHmac, randomBytes } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { deriveApiKey, deriveLegacyProjectKey } from '../api-key-kdf.js';
+
+describe('api-key-kdf', () => {
+  const machineKey = Buffer.from(
+    '0000000000000000000000000000000000000000000000000000000000000001',
+    'hex',
+  );
+  const globalSalt = Buffer.from(
+    '1111111111111111111111111111111111111111111111111111111111111111',
+    'hex',
+  );
+
+  describe('deriveApiKey', () => {
+    it('returns a 32-byte Buffer', () => {
+      const key = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      expect(key).toBeInstanceOf(Buffer);
+      expect(key.length).toBe(32);
+    });
+
+    it('is deterministic for identical inputs', () => {
+      const k1 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      const k2 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      expect(k2.equals(k1)).toBe(true);
+    });
+
+    it('produces different keys for different agentIds', () => {
+      const k1 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      const k2 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-2' });
+      expect(k2.equals(k1)).toBe(false);
+    });
+
+    it('produces different keys for different machineKeys', () => {
+      const otherMachine = randomBytes(32);
+      const k1 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      const k2 = deriveApiKey({ machineKey: otherMachine, globalSalt, agentId: 'agent-1' });
+      expect(k2.equals(k1)).toBe(false);
+    });
+
+    it('produces different keys for different globalSalts', () => {
+      const otherSalt = randomBytes(32);
+      const k1 = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      const k2 = deriveApiKey({ machineKey, globalSalt: otherSalt, agentId: 'agent-1' });
+      expect(k2.equals(k1)).toBe(false);
+    });
+
+    it('throws on empty machineKey', () => {
+      expect(() =>
+        deriveApiKey({ machineKey: Buffer.alloc(0), globalSalt, agentId: 'agent-1' }),
+      ).toThrow(/machineKey/);
+    });
+
+    it('throws on globalSalt of wrong size', () => {
+      expect(() =>
+        deriveApiKey({ machineKey, globalSalt: Buffer.alloc(16), agentId: 'agent-1' }),
+      ).toThrow(/globalSalt.*32/);
+    });
+
+    it('throws on empty agentId', () => {
+      expect(() => deriveApiKey({ machineKey, globalSalt, agentId: '' })).toThrow(/agentId/);
+    });
+
+    it('uses HMAC-SHA256 primitive (compatibility with external crypto libs)', () => {
+      const key = Buffer.concat([machineKey, globalSalt]);
+      const expected = createHmac('sha256', key).update('agent-1', 'utf8').digest();
+      const actual = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      expect(actual.equals(expected)).toBe(true);
+    });
+  });
+
+  describe('deriveLegacyProjectKey', () => {
+    it('returns a 32-byte Buffer', () => {
+      const key = deriveLegacyProjectKey(machineKey, '/home/user/project');
+      expect(key).toBeInstanceOf(Buffer);
+      expect(key.length).toBe(32);
+    });
+
+    it('is deterministic', () => {
+      const k1 = deriveLegacyProjectKey(machineKey, '/p');
+      const k2 = deriveLegacyProjectKey(machineKey, '/p');
+      expect(k2.equals(k1)).toBe(true);
+    });
+
+    it('produces different keys for different project paths', () => {
+      const k1 = deriveLegacyProjectKey(machineKey, '/project-a');
+      const k2 = deriveLegacyProjectKey(machineKey, '/project-b');
+      expect(k2.equals(k1)).toBe(false);
+    });
+
+    it('differs from new KDF for same machineKey + agentId', () => {
+      const legacy = deriveLegacyProjectKey(machineKey, 'agent-1');
+      const modern = deriveApiKey({ machineKey, globalSalt, agentId: 'agent-1' });
+      // Would be a bug if identical — legacy has no salt
+      expect(modern.equals(legacy)).toBe(false);
+    });
+
+    it('throws on empty machineKey', () => {
+      expect(() => deriveLegacyProjectKey(Buffer.alloc(0), '/p')).toThrow(/machineKey/);
+    });
+
+    it('throws on empty projectPath', () => {
+      expect(() => deriveLegacyProjectKey(machineKey, '')).toThrow(/projectPath/);
+    });
+  });
+});

package/src/store/__tests__/backup-crypto.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for backup-crypto.ts (T345).
+ *
+ * Covers: round-trip correctness, magic/version header, ciphertext
+ * non-determinism (random salt + nonce), error paths (wrong passphrase,
+ * truncated payload, bit-flip tamper, magic mismatch, too-short), and
+ * isEncryptedBundle detection.
+ *
+ * @task T345
+ * @epic T311
+ */
+
+import crypto from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { decryptBundle, encryptBundle, isEncryptedBundle } from '../backup-crypto.js';
+
+describe('backup-crypto', () => {
+  const plaintext = Buffer.from('Hello, CLEO backup world! 🌍 Non-ASCII: ñoño café');
+  const passphrase = 'correct horse battery staple';
+
+  it('round-trip: decrypt(encrypt(x)) == x', () => {
+    const encrypted = encryptBundle(plaintext, passphrase);
+    const decrypted = decryptBundle(encrypted, passphrase);
+    expect(decrypted.equals(plaintext)).toBe(true);
+  });
+
+  it('encryptBundle output starts with CLEOENC1 magic', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(enc.subarray(0, 8).toString('utf8')).toBe('CLEOENC1');
+  });
+
+  it('encryptBundle output has version byte 0x01 at offset 8', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(enc[8]).toBe(0x01);
+  });
+
+  it('two encryptions of same input differ (random salt + nonce)', () => {
+    const e1 = encryptBundle(plaintext, passphrase);
+    const e2 = encryptBundle(plaintext, passphrase);
+    expect(e1.equals(e2)).toBe(false);
+  });
+
+  it('decryptBundle throws on wrong passphrase', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(() => decryptBundle(enc, 'wrong passphrase')).toThrow(/authentication failed/);
+  });
+
+  it('decryptBundle throws on truncated ciphertext (auth tag missing)', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    const truncated = enc.subarray(0, enc.length - 1);
+    expect(() => decryptBundle(truncated, passphrase)).toThrow();
+  });
+
+  it('decryptBundle throws on flipped bit (auth tag fails)', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    // Flip a byte in the middle of the ciphertext region
+    const tampered = Buffer.from(enc);
+    const idx = 16 + 32 + 12 + 5; // well inside ciphertext region
+    tampered[idx] ^= 0x01;
+    expect(() => decryptBundle(tampered, passphrase)).toThrow(/authentication failed/);
+  });
+
+  it('decryptBundle throws on magic mismatch', () => {
+    const bogus = Buffer.alloc(128);
+    expect(() => decryptBundle(bogus, passphrase)).toThrow(/magic mismatch/);
+  });
+
+  it('decryptBundle throws on payload too short', () => {
+    const tiny = Buffer.alloc(32);
+    expect(() => decryptBundle(tiny, passphrase)).toThrow(/too short/);
+  });
+
+  it('encryptBundle throws on empty passphrase', () => {
+    expect(() => encryptBundle(plaintext, '')).toThrow(/passphrase/);
+  });
+
+  it('isEncryptedBundle returns true for magic header', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(isEncryptedBundle(enc.subarray(0, 8))).toBe(true);
+  });
+
+  it('isEncryptedBundle returns false for random data', () => {
+    const random = crypto.randomBytes(32);
+    expect(isEncryptedBundle(random)).toBe(false);
+  });
+
+  it('handles large payloads (1 MB)', () => {
+    const large = crypto.randomBytes(1024 * 1024);
+    const enc = encryptBundle(large, passphrase);
+    const dec = decryptBundle(enc, passphrase);
+    expect(dec.equals(large)).toBe(true);
+  });
+
+  it('scrypt derivation is deterministic for same passphrase + salt', () => {
+    // Indirectly verified: two independent round-trips both recover the plaintext.
+    const e1 = encryptBundle(plaintext, passphrase);
+    const e2 = encryptBundle(plaintext, passphrase);
+    expect(decryptBundle(e1, passphrase).equals(plaintext)).toBe(true);
+    expect(decryptBundle(e2, passphrase).equals(plaintext)).toBe(true);
+  });
+});