@flowcodex/core 0.3.0

package/tests/run-controller.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { RunController } from '../src/kernel/run-controller.js';
+
+describe('RunController', () => {
+  describe('signal', () => {
+    it('starts not aborted', () => {
+      const rc = new RunController();
+      expect(rc.aborted).toBe(false);
+      expect(rc.signal.aborted).toBe(false);
+    });
+  });
+
+  describe('abort', () => {
+    it('marks signal as aborted', () => {
+      const rc = new RunController();
+      rc.abort();
+      expect(rc.aborted).toBe(true);
+    });
+
+    it('abort is idempotent', () => {
+      const rc = new RunController();
+      rc.abort('reason1');
+      rc.abort('reason2');
+      expect(rc.signal.reason).toBe('reason1');
+    });
+  });
+
+  describe('onAbort hooks', () => {
+    it('fires hooks on abort in LIFO order', async () => {
+      const rc = new RunController();
+      const order: string[] = [];
+      rc.onAbort(() => { order.push('first'); });
+      rc.onAbort(() => { order.push('second'); });
+      rc.abort();
+      await new Promise((r) => setTimeout(r, 10));
+      expect(order).toEqual(['second', 'first']);
+    });
+
+    it('returns unsubscribe that removes the hook', async () => {
+      const rc = new RunController();
+      let fired = false;
+      const unsub = rc.onAbort(() => { fired = true; });
+      unsub();
+      rc.abort();
+      await new Promise((r) => setTimeout(r, 10));
+      expect(fired).toBe(false);
+    });
+
+    it('hook errors are caught and sent to errorSink', async () => {
+      const errors: string[] = [];
+      const rc = new RunController({
+        errorSink: (err) => { errors.push(String(err)); },
+      });
+      rc.onAbort(() => { throw new Error('hook-fail'); });
+      rc.onAbort(() => { });
+      rc.abort();
+      await new Promise((r) => setTimeout(r, 10));
+      expect(errors).toContain('Error: hook-fail');
+    });
+  });
+
+  describe('dispose', () => {
+    it('fires hooks on normal dispose', async () => {
+      const rc = new RunController();
+      let fired = false;
+      rc.onAbort(() => { fired = true; });
+      await rc.dispose();
+      expect(fired).toBe(true);
+    });
+
+    it('dispose is idempotent', async () => {
+      const rc = new RunController();
+      let count = 0;
+      rc.onAbort(() => { count++; });
+      await rc.dispose();
+      await rc.dispose();
+      expect(count).toBe(1);
+    });
+
+    it('abort then dispose fires hooks only once', async () => {
+      const rc = new RunController();
+      let count = 0;
+      rc.onAbort(() => { count++; });
+      rc.abort();
+      await new Promise((r) => setTimeout(r, 10));
+      await rc.dispose();
+      expect(count).toBe(1);
+    });
+  });
+
+  describe('parent signal', () => {
+    it('aborts when parent aborts', () => {
+      const parent = new AbortController();
+      const rc = new RunController({ parentSignal: parent.signal });
+      parent.abort('parent-reason');
+      expect(rc.aborted).toBe(true);
+      expect(rc.signal.reason).toBe('parent-reason');
+    });
+
+    it('already-aborted parent aborts immediately', () => {
+      const parent = new AbortController();
+      parent.abort('early');
+      const rc = new RunController({ parentSignal: parent.signal });
+      expect(rc.aborted).toBe(true);
+    });
+
+    it('removes parent listener on dispose', async () => {
+      const parent = new AbortController();
+      const rc = new RunController({ parentSignal: parent.signal });
+      await rc.dispose();
+      parent.abort('late');
+      expect(rc.aborted).toBe(false);
+    });
+  });
+});

package/tests/sanity.test.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import { FLOWCODEX_VERSION, FLOWCODEX_NAME, FlowCodexError, ERROR_CODES } from '../src/index.js';
+
+describe('sanity', () => {
+  it('FLOWCODEX_VERSION matches package.json', () => {
+    const pkgPath = fileURLToPath(new URL('../../../package.json', import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version: string };
+    expect(FLOWCODEX_VERSION).toBe(pkg.version);
+  });
+
+  it('should export name', () => {
+    expect(FLOWCODEX_NAME).toBe('flowcodex');
+  });
+
+  it('should export FlowCodexError', () => {
+    const err = new FlowCodexError({
+      message: 'test',
+      code: ERROR_CODES.UNKNOWN,
+      subsystem: 'general',
+    });
+    expect(err).toBeInstanceOf(Error);
+    expect(err.code).toBe('UNKNOWN');
+  });
+});

package/tests/schema-validator.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import { validateAgainstSchema } from '../src/execution/schema-validator.js';
+
+describe('schema-validator', () => {
+  it('passes when no schema', () => {
+    const result = validateAgainstSchema({ foo: 'bar' }, undefined);
+    expect(result.ok).toBe(true);
+  });
+
+  it('passes when empty schema', () => {
+    const result = validateAgainstSchema({ foo: 'bar' }, {});
+    expect(result.ok).toBe(true);
+  });
+
+  it('checks required fields', () => {
+    const schema = {
+      type: 'object',
+      properties: { name: { type: 'string' }, age: { type: 'integer' } },
+      required: ['name', 'age'],
+    };
+    const result = validateAgainstSchema({ name: 'foo' }, schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((e) => e.path === 'age')).toBe(true);
+  });
+
+  it('checks types', () => {
+    const schema = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    };
+    const result = validateAgainstSchema({ name: 123 }, schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors[0]?.message).toContain('expected type "string"');
+  });
+
+  it('checks integer type', () => {
+    const schema = {
+      type: 'object',
+      properties: { count: { type: 'integer' } },
+      required: ['count'],
+    };
+    expect(validateAgainstSchema({ count: 5 }, schema).ok).toBe(true);
+    expect(validateAgainstSchema({ count: 5.5 }, schema).ok).toBe(false);
+  });
+
+  it('checks enum values', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        status: { type: 'string', enum: ['pending', 'done'] },
+      },
+      required: ['status'],
+    };
+    expect(validateAgainstSchema({ status: 'pending' }, schema).ok).toBe(true);
+    expect(validateAgainstSchema({ status: 'unknown' }, schema).ok).toBe(false);
+  });
+
+  it('validates array items', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        items: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+      required: ['items'],
+    };
+    expect(validateAgainstSchema({ items: ['a', 'b'] }, schema).ok).toBe(true);
+    expect(validateAgainstSchema({ items: ['a', 123] }, schema).ok).toBe(false);
+  });
+
+  it('passes valid complex input', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        count: { type: 'integer' },
+        active: { type: 'boolean' },
+      },
+      required: ['name', 'count', 'active'],
+    };
+    const result = validateAgainstSchema({ name: 'test', count: 10, active: true }, schema);
+    expect(result.ok).toBe(true);
+  });
+
+  it('accepts extra properties not in schema', () => {
+    const schema = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    };
+    const result = validateAgainstSchema({ name: 'foo', extra: 123 }, schema);
+    expect(result.ok).toBe(true);
+  });
+
+  it('rejects non-object when object expected', () => {
+    const schema = { type: 'object' };
+    const result = validateAgainstSchema('not an object', schema);
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects non-array when array expected', () => {
+    const schema = { type: 'array' };
+    const result = validateAgainstSchema('not an array', schema);
+    expect(result.ok).toBe(false);
+  });
+});

package/tests/secret-scrubber.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { DefaultSecretScrubber } from '../src/infrastructure/secret-scrubber.js';
+
+describe('DefaultSecretScrubber', () => {
+  const scrubber = new DefaultSecretScrubber();
+
+  describe('scrub', () => {
+    it('returns clean text unchanged', () => {
+      expect(scrubber.scrub('hello world')).toBe('hello world');
+    });
+
+    it('redacts Anthropic API key', () => {
+      const text = 'The key is sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:anthropic_key]');
+      expect(result).not.toContain('sk-ant-');
+    });
+
+    it('redacts OpenAI API key', () => {
+      const text = 'key: sk-xxxxxxxxxxxxxxxxxxxxxxxx';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:openai_key]');
+    });
+
+    it('redacts GitHub PAT', () => {
+      const text = 'token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:github_pat]');
+    });
+
+    it('redacts AWS access key', () => {
+      const text = 'aws key: AKIAIOSFODNN7EXAMPLE';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:aws_access_key]');
+    });
+
+    it('redacts JWT', () => {
+      const text = 'jwt: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:jwt]');
+    });
+
+    it('redacts Bearer token', () => {
+      const text = 'Authorization: Bearer dGhpcy1pcy1hLXZlcnktbG9uZy1iZWFyZXItdG9rZW4tZm9yLXRlc3Rpbmc';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:bearer_token]');
+    });
+
+    it('redacts private key block', () => {
+      const text = '-----BEGIN RSA PRIVATE KEY-----\nMIIBxQIBAAJBALW0g1qD\n-----END RSA PRIVATE KEY-----';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:private_key]');
+    });
+
+    it('redacts MongoDB URI', () => {
+      const text = 'mongodb://user:pass@cluster.mongodb.net/db';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:mongodb_uri]');
+    });
+
+    it('redacts PostgreSQL URI', () => {
+      const text = 'postgres://user:password@localhost:5432/db';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:postgres_uri]');
+    });
+
+    it('redacts Redis URI', () => {
+      const text = 'redis://:password@localhost:6379';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:redis_uri]');
+    });
+
+    it('redacts high-entropy env var', () => {
+      const text = 'API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:');
+    });
+  });
+
+  describe('hasCredentialAnchors (fast path)', () => {
+    it('returns false for plain text', () => {
+      expect(scrubber.hasCredentialAnchors('just a normal log line')).toBe(false);
+    });
+
+    it('returns true for text with anchor', () => {
+      expect(scrubber.hasCredentialAnchors('key is sk-ant-xxx')).toBe(true);
+      expect(scrubber.hasCredentialAnchors('ghp_token_here')).toBe(true);
+      expect(scrubber.hasCredentialAnchors('AKIA...')).toBe(true);
+    });
+  });
+
+  describe('scrubObject', () => {
+    it('scrubs strings in nested objects', () => {
+      const obj = {
+        safe: 'hello',
+        key: 'sk-xxxxxxxxxxxxxxxxxxxxxxxx',
+        nested: {
+          token: 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        },
+      };
+      const result = scrubber.scrubObject(obj);
+      expect(result.safe).toBe('hello');
+      expect(result.key).toContain('[REDACTED:');
+      expect(result.nested.token).toContain('[REDACTED:');
+    });
+
+    it('scrubs strings in arrays', () => {
+      const arr = ['safe text', 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'];
+      const result = scrubber.scrubObject(arr);
+      expect(result[0]).toBe('safe text');
+      expect(result[1]).toContain('[REDACTED:');
+    });
+
+    it('handles null and undefined', () => {
+      expect(scrubber.scrubObject(null)).toBeNull();
+      expect(scrubber.scrubObject(undefined)).toBeUndefined();
+    });
+
+    it('handles numbers and booleans', () => {
+      expect(scrubber.scrubObject(42)).toBe(42);
+      expect(scrubber.scrubObject(true)).toBe(true);
+    });
+  });
+
+  describe('multiple secrets in one text', () => {
+    it('redacts multiple different secrets', () => {
+      const text = 'keys: sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxx and ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';
+      const result = scrubber.scrub(text);
+      expect(result).toContain('[REDACTED:anthropic_key]');
+      expect(result).toContain('[REDACTED:github_pat]');
+    });
+  });
+});

package/tests/secret-vault.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { DefaultSecretVault, ENCRYPTED_PREFIX, isSecretField } from '../src/session/secret-vault.js';
+import * as fsSync from 'node:fs';
+
+let tmpDir: string;
+let keyFile: string;
+
+describe('DefaultSecretVault', () => {
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-vault-'));
+    keyFile = path.join(tmpDir, '.key');
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('encrypts and decrypts correctly', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const plaintext = 'sk-ant-api03-my-secret-key';
+    const encrypted = vault.encrypt(plaintext);
+    expect(encrypted.startsWith(ENCRYPTED_PREFIX)).toBe(true);
+    expect(encrypted).not.toContain(plaintext);
+    const decrypted = vault.decrypt(encrypted);
+    expect(decrypted).toBe(plaintext);
+  });
+
+  it('is idempotent on encrypted values', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const encrypted = vault.encrypt('hello');
+    expect(vault.encrypt(encrypted)).toBe(encrypted);
+  });
+
+  it('decrypt returns plaintext for unencrypted values', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    expect(vault.decrypt('plain-value')).toBe('plain-value');
+  });
+
+  it('isEncrypted detects the prefix', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    expect(vault.isEncrypted('enc:v1:abc:def:ghi')).toBe(true);
+    expect(vault.isEncrypted('plaintext')).toBe(false);
+  });
+
+  it('creates key file if missing', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    vault.encrypt('test');
+    const stat = fsSync.statSync(keyFile);
+    expect(stat.size).toBe(32);
+  });
+
+  it('reuses existing key file', () => {
+    const vault1 = new DefaultSecretVault({ keyFile });
+    const encrypted = vault1.encrypt('secret');
+
+    const vault2 = new DefaultSecretVault({ keyFile });
+    const decrypted = vault2.decrypt(encrypted);
+    expect(decrypted).toBe('secret');
+  });
+
+  it('different key files produce different ciphertexts', () => {
+    const keyFile2 = path.join(tmpDir, '.key2');
+    const vault1 = new DefaultSecretVault({ keyFile });
+    const vault2 = new DefaultSecretVault({ keyFile: keyFile2 });
+    const enc1 = vault1.encrypt('same-secret');
+    const enc2 = vault2.encrypt('same-secret');
+    expect(enc1).not.toBe(enc2);
+  });
+
+  it('throws on malformed encrypted value', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    expect(() => vault.decrypt('enc:v1:malformed')).toThrow('malformed');
+  });
+
+  it('throws on tampered ciphertext (auth tag mismatch)', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const encrypted = vault.encrypt('secret-data');
+    const tampered = encrypted.slice(0, -4) + 'AAAA';
+    expect(() => vault.decrypt(tampered)).toThrow();
+  });
+
+  it('each encryption uses a unique IV', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const enc1 = vault.encrypt('same-input');
+    const enc2 = vault.encrypt('same-input');
+    expect(enc1).not.toBe(enc2);
+    expect(vault.decrypt(enc1)).toBe('same-input');
+    expect(vault.decrypt(enc2)).toBe('same-input');
+  });
+
+  it('handles empty string', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const encrypted = vault.encrypt('');
+    expect(vault.decrypt(encrypted)).toBe('');
+  });
+
+  it('handles unicode', () => {
+    const vault = new DefaultSecretVault({ keyFile });
+    const plaintext = 'héllo wörld 日本語';
+    const encrypted = vault.encrypt(plaintext);
+    expect(vault.decrypt(encrypted)).toBe(plaintext);
+  });
+});
+
+describe('isSecretField', () => {
+  it('detects apiKey', () => {
+    expect(isSecretField('apiKey')).toBe(true);
+    expect(isSecretField('api_key')).toBe(true);
+  });
+
+  it('detects token/password/secret', () => {
+    expect(isSecretField('authToken')).toBe(true);
+    expect(isSecretField('password')).toBe(true);
+    expect(isSecretField('client_secret')).toBe(true);
+    expect(isSecretField('accessToken')).toBe(true);
+  });
+
+  it('does not flag publicKey', () => {
+    expect(isSecretField('publicKey')).toBe(false);
+    expect(isSecretField('public_key')).toBe(false);
+  });
+
+  it('does not flag regular fields', () => {
+    expect(isSecretField('name')).toBe(false);
+    expect(isSecretField('port')).toBe(false);
+    expect(isSecretField('timeout')).toBe(false);
+  });
+});