@complior/engine 0.9.0

package/src/domain/audit/audit-package.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createAuditPackage, type AuditPackageDeps } from './audit-package.js';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { gunzipSync } from 'node:zlib';
+
+const createTempProject = (): string => {
+  const dir = join(
+    tmpdir(),
+    `complior-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(join(dir, '.complior', 'evidence'), { recursive: true });
+  mkdirSync(join(dir, '.complior', 'agents'), { recursive: true });
+  return dir;
+};
+
+describe('createAuditPackage', () => {
+  let testDir: string;
+  let deps: AuditPackageDeps;
+
+  beforeEach(() => {
+    testDir = createTempProject();
+    deps = { getProjectPath: () => testDir };
+  });
+
+  it('creates a gzipped tar archive', async () => {
+    writeFileSync(join(testDir, '.complior', 'evidence', 'chain.json'), '[]');
+    const { buffer } = await createAuditPackage(deps);
+    expect(buffer).toBeInstanceOf(Buffer);
+    expect(buffer.length).toBeGreaterThan(0);
+    // Verify it's valid gzip (magic number: 1f 8b)
+    expect(buffer[0]).toBe(0x1f);
+    expect(buffer[1]).toBe(0x8b);
+  });
+
+  it('returns manifest with file hashes', async () => {
+    writeFileSync(join(testDir, '.complior', 'evidence', 'chain.json'), '[]');
+    const { manifest } = await createAuditPackage(deps);
+    expect(manifest.exportDate).toBeTruthy();
+    expect(manifest.toolVersion).toBeTruthy();
+    expect(manifest.integrityHash).toBeTruthy();
+    expect(manifest.files.length).toBeGreaterThanOrEqual(1);
+    expect(manifest.files[0].hash).toHaveLength(64); // SHA-256
+  });
+
+  it('includes manifest in the archive', async () => {
+    writeFileSync(
+      join(testDir, '.complior', 'agents', 'bot-manifest.json'),
+      '{}',
+    );
+    const { buffer, totalFiles } = await createAuditPackage(deps);
+    // totalFiles includes the manifest itself
+    expect(totalFiles).toBeGreaterThanOrEqual(2); // agent file + manifest
+    // Decompress and verify tar contains audit-manifest.json
+    const decompressed = gunzipSync(buffer);
+    const content = decompressed.toString('utf8');
+    expect(content).toContain('audit-manifest.json');
+  });
+
+  it('collects files from evidence directory', async () => {
+    writeFileSync(
+      join(testDir, '.complior', 'evidence', 'chain.json'),
+      '{"entries":[]}',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(manifest.files.some((f) => f.path.includes('chain.json'))).toBe(
+      true,
+    );
+  });
+
+  it('collects files from agents directory', async () => {
+    writeFileSync(
+      join(testDir, '.complior', 'agents', 'test-manifest.json'),
+      '{}',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(
+      manifest.files.some((f) => f.path.includes('test-manifest.json')),
+    ).toBe(true);
+  });
+
+  it('handles empty project gracefully', async () => {
+    const emptyDir = join(tmpdir(), `complior-empty-${Date.now()}`);
+    mkdirSync(emptyDir, { recursive: true });
+    const emptyDeps = { getProjectPath: () => emptyDir };
+    const { manifest, totalFiles } = await createAuditPackage(emptyDeps);
+    // Only the manifest itself
+    expect(totalFiles).toBe(1);
+    expect(manifest.files.length).toBe(0); // manifest isn't in its own file list
+    rmSync(emptyDir, { recursive: true, force: true });
+  });
+
+  it('computes integrity hash from file hashes', async () => {
+    writeFileSync(join(testDir, '.complior', 'evidence', 'chain.json'), '[]');
+    writeFileSync(
+      join(testDir, '.complior', 'agents', 'bot-manifest.json'),
+      '{}',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(manifest.integrityHash).toHaveLength(64);
+  });
+
+  it('includes last-scan.json if present', async () => {
+    writeFileSync(
+      join(testDir, '.complior', 'last-scan.json'),
+      '{"score":85}',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(manifest.files.some((f) => f.path === 'last-scan.json')).toBe(true);
+  });
+
+  it('handles missing last-scan.json gracefully', async () => {
+    const { manifest } = await createAuditPackage(deps);
+    expect(manifest.files.some((f) => f.path === 'last-scan.json')).toBe(
+      false,
+    );
+  });
+
+  it('decompressed archive contains tar headers with complior-audit prefix', async () => {
+    writeFileSync(join(testDir, '.complior', 'evidence', 'chain.json'), '[]');
+    const { buffer } = await createAuditPackage(deps);
+    const decompressed = gunzipSync(buffer);
+    expect(decompressed.toString('utf8')).toContain('complior-audit/');
+  });
+
+  it('collects files from nested subdirectories', async () => {
+    mkdirSync(join(testDir, '.complior', 'evidence', 'sub'), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(testDir, '.complior', 'evidence', 'sub', 'nested.json'),
+      '{}',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(
+      manifest.files.some((f) => f.path.includes('nested.json')),
+    ).toBe(true);
+  });
+
+  it('collects files from reports directory', async () => {
+    mkdirSync(join(testDir, '.complior', 'reports'), { recursive: true });
+    writeFileSync(
+      join(testDir, '.complior', 'reports', 'fria-bot.md'),
+      '# FRIA Report',
+    );
+    const { manifest } = await createAuditPackage(deps);
+    expect(
+      manifest.files.some((f) => f.path.includes('fria-bot.md')),
+    ).toBe(true);
+  });
+});

package/src/domain/audit/audit-package.ts

@@ -0,0 +1,166 @@
+import { createGzip } from 'node:zlib';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { ENGINE_VERSION } from '../../version.js';
+
+// --- Types ---
+
+export interface AuditPackageManifest {
+  readonly exportDate: string;
+  readonly toolVersion: string;
+  readonly files: readonly { path: string; size: number; hash: string }[];
+  readonly integrityHash: string;
+}
+
+export interface AuditPackageDeps {
+  readonly getProjectPath: () => string;
+}
+
+export interface AuditPackageResult {
+  readonly manifest: AuditPackageManifest;
+  readonly buffer: Buffer;
+  readonly totalFiles: number;
+}
+
+// --- Tar helpers ---
+
+/** Build a POSIX tar header (512 bytes) for a single file entry. */
+const tarHeader = (name: string, size: number): Buffer => {
+  const header = Buffer.alloc(512, 0);
+  // name (100 bytes)
+  header.write(name.slice(0, 100), 0, 100, 'utf8');
+  // mode (8 bytes)
+  header.write('0000644\0', 100, 8, 'utf8');
+  // uid (8 bytes)
+  header.write('0001000\0', 108, 8, 'utf8');
+  // gid (8 bytes)
+  header.write('0001000\0', 116, 8, 'utf8');
+  // size (12 bytes, octal)
+  header.write(size.toString(8).padStart(11, '0') + '\0', 124, 12, 'utf8');
+  // mtime (12 bytes, octal)
+  const mtime = Math.floor(Date.now() / 1000);
+  header.write(mtime.toString(8).padStart(11, '0') + '\0', 136, 12, 'utf8');
+  // checksum placeholder (8 spaces)
+  header.write('        ', 148, 8, 'utf8');
+  // typeflag (regular file)
+  header.write('0', 156, 1, 'utf8');
+
+  // Calculate checksum
+  let checksum = 0;
+  for (let i = 0; i < 512; i++) checksum += header[i];
+  header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8, 'utf8');
+
+  return header;
+};
+
+/** Pad buffer to 512-byte boundary. */
+const padTo512 = (size: number): Buffer => {
+  const remainder = size % 512;
+  return remainder === 0 ? Buffer.alloc(0) : Buffer.alloc(512 - remainder, 0);
+};
+
+/** Recursively collect files from a directory (if it exists). */
+const collectFiles = async (
+  dir: string,
+  basePath: string,
+): Promise<{ path: string; content: Buffer }[]> => {
+  const files: { path: string; content: Buffer }[] = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...(await collectFiles(fullPath, basePath)));
+      } else if (entry.isFile()) {
+        const content = await readFile(fullPath);
+        files.push({ path: relative(basePath, fullPath), content });
+      }
+    }
+  } catch {
+    // Directory doesn't exist, skip
+  }
+  return files;
+};
+
+// --- Main export ---
+
+export const createAuditPackage = async (
+  deps: AuditPackageDeps,
+): Promise<AuditPackageResult> => {
+  const projectPath = deps.getProjectPath();
+  const compliorDir = join(projectPath, '.complior');
+
+  // Collect artifacts from known locations
+  const artifactDirs = [
+    join(compliorDir, 'evidence'),
+    join(compliorDir, 'agents'),
+    join(compliorDir, 'fria'),
+    join(compliorDir, 'policies'),
+    join(compliorDir, 'audit'),
+    join(compliorDir, 'reports'),
+    join(compliorDir, 'exports'),
+  ];
+
+  const allFiles: { path: string; content: Buffer }[] = [];
+
+  for (const dir of artifactDirs) {
+    allFiles.push(...(await collectFiles(dir, compliorDir)));
+  }
+
+  // Also try to add the latest scan result if it exists
+  try {
+    const scanPath = join(compliorDir, 'last-scan.json');
+    const scanContent = await readFile(scanPath);
+    allFiles.push({ path: 'last-scan.json', content: scanContent });
+  } catch {
+    // No scan result, skip
+  }
+
+  // Build manifest
+  const manifestFiles = allFiles.map((f) => ({
+    path: f.path,
+    size: f.content.length,
+    hash: createHash('sha256').update(f.content).digest('hex'),
+  }));
+
+  const integrityHash = createHash('sha256')
+    .update(manifestFiles.map((f) => f.hash).join(''))
+    .digest('hex');
+
+  const manifest: AuditPackageManifest = {
+    exportDate: new Date().toISOString(),
+    toolVersion: ENGINE_VERSION,
+    files: manifestFiles,
+    integrityHash,
+  };
+
+  // Add manifest to the archive
+  const manifestBuffer = Buffer.from(JSON.stringify(manifest, null, 2));
+  allFiles.push({ path: 'audit-manifest.json', content: manifestBuffer });
+
+  // Build tar archive
+  const tarChunks: Buffer[] = [];
+  for (const file of allFiles) {
+    const entryPath = `complior-audit/${file.path}`;
+    tarChunks.push(tarHeader(entryPath, file.content.length));
+    tarChunks.push(file.content);
+    tarChunks.push(padTo512(file.content.length));
+  }
+  // End of archive marker (two 512-byte zero blocks)
+  tarChunks.push(Buffer.alloc(1024, 0));
+
+  const tarBuffer = Buffer.concat(tarChunks);
+
+  // Gzip compress
+  const gzipped = await new Promise<Buffer>((resolve, reject) => {
+    const gzip = createGzip({ level: 9 });
+    const chunks: Buffer[] = [];
+    gzip.on('data', (chunk: Buffer) => chunks.push(chunk));
+    gzip.on('end', () => resolve(Buffer.concat(chunks)));
+    gzip.on('error', reject);
+    gzip.end(tarBuffer);
+  });
+
+  return { manifest, buffer: gzipped, totalFiles: allFiles.length };
+};

package/src/domain/audit/audit-trail.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createAuditStore } from './audit-trail.js';
+
+const mockSign = (hash: string): string => `sig:${hash.slice(0, 8)}`;
+
+describe('createAuditStore', () => {
+  let tempDir: string;
+  let trailPath: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'audit-'));
+    trailPath = join(tempDir, 'audit', 'trail.jsonl');
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns empty summary for empty trail', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    const summary = await store.getSummary();
+
+    expect(summary.totalEntries).toBe(0);
+    expect(summary.eventCounts).toEqual({});
+    expect(summary.agentNames).toEqual([]);
+    expect(summary.firstEntry).toBe('');
+    expect(summary.lastEntry).toBe('');
+  });
+
+  it('appends entry with correct fields', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    const entry = await store.append('passport.created', { name: 'bot-a', path: '/tmp/test' }, 'bot-a');
+
+    expect(entry.id).toBeTruthy();
+    expect(entry.timestamp).toBeTruthy();
+    expect(entry.agentName).toBe('bot-a');
+    expect(entry.eventType).toBe('passport.created');
+    expect(entry.payload).toEqual({ name: 'bot-a', path: '/tmp/test' });
+    expect(entry.signature).toBeTruthy();
+  });
+
+  it('generates unique IDs for each entry', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    const e1 = await store.append('passport.created', { n: 1 });
+    const e2 = await store.append('scan.completed', { n: 2 });
+
+    expect(e1.id).not.toBe(e2.id);
+  });
+
+  it('entries are signed (signature not empty)', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    const entry = await store.append('scan.completed', { score: 85 });
+
+    expect(entry.signature).toBeTruthy();
+    expect(entry.signature.startsWith('sig:')).toBe(true);
+  });
+
+  it('query filters by agentName', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    await store.append('passport.created', {}, 'bot-a');
+    await store.append('passport.created', {}, 'bot-b');
+    await store.append('scan.completed', {}, 'bot-a');
+
+    const results = await store.query({ agentName: 'bot-a' });
+    expect(results).toHaveLength(2);
+    expect(results.every(e => e.agentName === 'bot-a')).toBe(true);
+  });
+
+  it('query filters by eventType', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    await store.append('passport.created', {}, 'bot-a');
+    await store.append('scan.completed', { score: 80 });
+    await store.append('scan.completed', { score: 90 });
+
+    const results = await store.query({ eventType: 'scan.completed' });
+    expect(results).toHaveLength(2);
+    expect(results.every(e => e.eventType === 'scan.completed')).toBe(true);
+  });
+
+  it('query filters by since/until', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    await store.append('passport.created', {}, 'bot-a');
+    // Small delay to get different timestamps
+    await new Promise(r => setTimeout(r, 10));
+    const e2 = await store.append('scan.completed', {});
+    await new Promise(r => setTimeout(r, 10));
+    await store.append('fria.generated', {});
+
+    const results = await store.query({ since: e2.timestamp });
+    expect(results.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('query respects limit', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    await store.append('passport.created', {});
+    await store.append('scan.completed', {});
+    await store.append('fria.generated', {});
+
+    const results = await store.query({ limit: 2 });
+    expect(results).toHaveLength(2);
+  });
+
+  it('getSummary aggregates correctly', async () => {
+    const store = createAuditStore(trailPath, mockSign);
+    await store.append('passport.created', {}, 'bot-a');
+    await store.append('passport.created', {}, 'bot-b');
+    await store.append('scan.completed', {}, 'bot-a');
+
+    const summary = await store.getSummary();
+    expect(summary.totalEntries).toBe(3);
+    expect(summary.eventCounts['passport.created']).toBe(2);
+    expect(summary.eventCounts['scan.completed']).toBe(1);
+    expect(summary.agentNames).toContain('bot-a');
+    expect(summary.agentNames).toContain('bot-b');
+    expect(summary.firstEntry).toBeTruthy();
+    expect(summary.lastEntry).toBeTruthy();
+  });
+});

package/src/domain/audit/audit-trail.ts

@@ -0,0 +1,174 @@
+import { appendFile, readFile, mkdir, stat, rename } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+
+/** Maximum JSONL file size in bytes before rotation (50 MB) */
+const MAX_TRAIL_SIZE = 50 * 1024 * 1024;
+
+/** Maximum entries to keep in active trail after rotation */
+const MAX_TRAIL_ENTRIES = 10_000;
+
+export type AuditEventType =
+  | 'passport.created' | 'passport.updated' | 'passport.exported' | 'passport.imported'
+  | 'fria.generated' | 'scan.completed' | 'fix.applied'
+  | 'evidence.verified' | 'worker_notification.generated'
+  | 'policy.generated' | 'document.generated' | 'test_suite.generated'
+  | 'readiness.computed'
+  | 'adversarial.completed'
+  | 'supply-chain.audited';
+
+export interface AuditEntry {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly agentName?: string;
+  readonly eventType: AuditEventType;
+  readonly payload: Record<string, unknown>;
+  readonly signature: string;
+}
+
+export interface AuditFilter {
+  readonly agentName?: string;
+  readonly since?: string;
+  readonly until?: string;
+  readonly eventType?: AuditEventType;
+  readonly limit?: number;
+}
+
+export interface AuditTrailSummary {
+  readonly totalEntries: number;
+  readonly eventCounts: Record<string, number>;
+  readonly agentNames: readonly string[];
+  readonly firstEntry: string;
+  readonly lastEntry: string;
+}
+
+export interface AuditStore {
+  readonly append: (eventType: AuditEventType, payload: Record<string, unknown>, agentName?: string) => Promise<AuditEntry>;
+  readonly query: (filter: AuditFilter) => Promise<readonly AuditEntry[]>;
+  readonly getSummary: () => Promise<AuditTrailSummary>;
+}
+
+const isAuditEntry = (v: unknown): v is AuditEntry =>
+  typeof v === 'object' && v !== null
+  && 'id' in v && typeof v.id === 'string'
+  && 'eventType' in v && typeof v.eventType === 'string'
+  && 'signature' in v && typeof v.signature === 'string';
+
+const parseEntries = (content: string, onError?: (line: string, error: unknown) => void): AuditEntry[] => {
+  const entries: AuditEntry[] = [];
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (isAuditEntry(parsed)) entries.push(parsed);
+    } catch (err) {
+      onError?.(trimmed, err);
+    }
+  }
+  return entries;
+};
+
+export const createAuditStore = (
+  trailPath: string,
+  signHash: (hash: string) => string,
+  onParseError?: (line: string, error: unknown) => void,
+): AuditStore => {
+  const append = async (eventType: AuditEventType, payload: Record<string, unknown>, agentName?: string): Promise<AuditEntry> => {
+    const id = randomUUID();
+    const timestamp = new Date().toISOString();
+
+    const unsigned = { id, timestamp, agentName, eventType, payload };
+    const hash = createHash('sha256').update(JSON.stringify(unsigned)).digest('hex');
+    const signature = signHash(hash);
+
+    const entry: AuditEntry = { ...unsigned, signature };
+
+    await mkdir(dirname(trailPath), { recursive: true });
+
+    // Rotate if file exceeds size limit
+    try {
+      const { size } = await stat(trailPath);
+      if (size > MAX_TRAIL_SIZE) {
+        const dateSuffix = new Date().toISOString().replace(/[:.]/g, '-');
+        await rename(trailPath, `${trailPath}.${dateSuffix}.bak`);
+      }
+    } catch {
+      // File doesn't exist yet — no rotation needed
+    }
+
+    await appendFile(trailPath, JSON.stringify(entry) + '\n');
+
+    return entry;
+  };
+
+  const readAll = async (): Promise<AuditEntry[]> => {
+    try {
+      const content = await readFile(trailPath, 'utf-8');
+      const entries = parseEntries(content, onParseError);
+      // Cap to last MAX_TRAIL_ENTRIES to avoid excessive memory usage
+      return entries.length > MAX_TRAIL_ENTRIES
+        ? entries.slice(entries.length - MAX_TRAIL_ENTRIES)
+        : entries;
+    } catch {
+      // File does not exist yet — expected on first run
+      return [];
+    }
+  };
+
+  const query = async (filter: AuditFilter): Promise<readonly AuditEntry[]> => {
+    let entries = await readAll();
+
+    if (filter.agentName) {
+      entries = entries.filter(e => e.agentName === filter.agentName);
+    }
+    if (filter.eventType) {
+      entries = entries.filter(e => e.eventType === filter.eventType);
+    }
+    if (filter.since) {
+      entries = entries.filter(e => e.timestamp >= filter.since!);
+    }
+    if (filter.until) {
+      entries = entries.filter(e => e.timestamp <= filter.until!);
+    }
+    if (filter.limit !== undefined && filter.limit > 0) {
+      entries = entries.slice(-filter.limit);
+    }
+
+    return entries;
+  };
+
+  const getSummary = async (): Promise<AuditTrailSummary> => {
+    const entries = await readAll();
+
+    if (entries.length === 0) {
+      return {
+        totalEntries: 0,
+        eventCounts: {},
+        agentNames: [],
+        firstEntry: '',
+        lastEntry: '',
+      };
+    }
+
+    const eventCounts: Record<string, number> = {};
+    const agentSet = new Set<string>();
+
+    for (const e of entries) {
+      eventCounts[e.eventType] = (eventCounts[e.eventType] ?? 0) + 1;
+      if (e.agentName) agentSet.add(e.agentName);
+    }
+
+    const timestamps = entries.map(e => e.timestamp).sort();
+
+    return {
+      totalEntries: entries.length,
+      eventCounts,
+      agentNames: [...agentSet].sort(),
+      firstEntry: timestamps[0]!,
+      lastEntry: timestamps[timestamps.length - 1]!,
+    };
+  };
+
+  return Object.freeze({ append, query, getSummary });
+};

package/src/domain/audit/index.ts

@@ -0,0 +1,8 @@
+export { buildPermissionsMatrix } from './permissions-matrix.js';
+export type { PermissionConflict, PermissionsMatrix } from './permissions-matrix.js';
+
+export { createAuditStore } from './audit-trail.js';
+export type { AuditEventType, AuditEntry, AuditFilter, AuditTrailSummary, AuditStore } from './audit-trail.js';
+
+export { createAuditPackage } from './audit-package.js';
+export type { AuditPackageManifest, AuditPackageDeps, AuditPackageResult } from './audit-package.js';