@complior/engine 0.9.0

package/src/domain/passport/builder/manifest-diff.ts

@@ -0,0 +1,89 @@
+// US-S05-24: Manifest Diff — compare passport versions and detect breaking changes
+
+export interface ManifestDiffField {
+  readonly field: string;
+  readonly path: string;
+  readonly oldValue: unknown;
+  readonly newValue: unknown;
+  readonly changeType: 'added' | 'removed' | 'modified';
+  readonly severity: 'low' | 'medium' | 'high';
+}
+
+export interface ManifestDiffResult {
+  readonly agentName: string;
+  readonly totalChanges: number;
+  readonly added: number;
+  readonly removed: number;
+  readonly modified: number;
+  readonly changes: readonly ManifestDiffField[];
+  readonly hasBreakingChanges: boolean;
+}
+
+const HIGH_SEVERITY_FIELDS = new Set([
+  'autonomy_level', 'permissions', 'constraints', 'compliance',
+  'risk_class', 'prohibited_actions',
+]);
+
+const MEDIUM_SEVERITY_FIELDS = new Set([
+  'model', 'owner', 'framework', 'logging', 'data_access',
+]);
+
+const fieldSeverity = (path: string): 'low' | 'medium' | 'high' => {
+  const top = path.split('.')[0] ?? '';
+  if (HIGH_SEVERITY_FIELDS.has(top)) return 'high';
+  if (MEDIUM_SEVERITY_FIELDS.has(top)) return 'medium';
+  return 'low';
+};
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const diffObjects = (
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  prefix: string,
+): ManifestDiffField[] => {
+  const changes: ManifestDiffField[] = [];
+  const allKeys = new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+
+  for (const key of allKeys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const oldVal = oldObj[key];
+    const newVal = newObj[key];
+
+    if (oldVal === undefined && newVal !== undefined) {
+      changes.push({ field: key, path, oldValue: undefined, newValue: newVal, changeType: 'added', severity: fieldSeverity(path) });
+    } else if (oldVal !== undefined && newVal === undefined) {
+      changes.push({ field: key, path, oldValue: oldVal, newValue: undefined, changeType: 'removed', severity: fieldSeverity(path) });
+    } else if (isRecord(oldVal) && isRecord(newVal)) {
+      changes.push(...diffObjects(oldVal, newVal, path));
+    } else if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+      changes.push({ field: key, path, oldValue: oldVal, newValue: newVal, changeType: 'modified', severity: fieldSeverity(path) });
+    }
+  }
+
+  return changes;
+};
+
+export const computeManifestDiff = (
+  agentName: string,
+  oldManifest: Record<string, unknown>,
+  newManifest: Record<string, unknown>,
+): ManifestDiffResult => {
+  const changes = diffObjects(oldManifest, newManifest, '');
+
+  const added = changes.filter(c => c.changeType === 'added').length;
+  const removed = changes.filter(c => c.changeType === 'removed').length;
+  const modified = changes.filter(c => c.changeType === 'modified').length;
+  const hasBreakingChanges = changes.some(c => c.severity === 'high');
+
+  return Object.freeze({
+    agentName,
+    totalChanges: changes.length,
+    added,
+    removed,
+    modified,
+    changes: Object.freeze(changes),
+    hasBreakingChanges,
+  });
+};

package/src/domain/passport/builder/manifest-files.ts

@@ -0,0 +1,17 @@
+import type { FileInfo } from '../../../ports/scanner.port.js';
+
+const AGENTS_DIR = '.complior/agents/';
+const MANIFEST_SUFFIX = '-manifest.json';
+
+export const isPassportManifest = (relativePath: string): boolean =>
+  relativePath.includes(AGENTS_DIR) && relativePath.endsWith(MANIFEST_SUFFIX);
+
+export const filterPassportManifests = (files: readonly FileInfo[]): readonly FileInfo[] =>
+  files.filter((f) => isPassportManifest(f.relativePath));
+
+/** Extract risk_class from a parsed passport manifest JSON. Defaults to 'limited'. */
+export const extractRiskClass = (manifest: Record<string, unknown>): string => {
+  const compliance = manifest.compliance as Record<string, unknown> | undefined;
+  const euAiAct = compliance?.eu_ai_act as Record<string, unknown> | undefined;
+  return (euAiAct?.risk_class as string) ?? 'limited';
+};

package/src/domain/passport/crypto-signer.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { generateKeyPair, signPassport, verifyPassport } from './crypto-signer.js';
+import { buildPassport } from './builder/manifest-builder.js';
+import type { PassportBuildInput } from './builder/manifest-builder.js';
+import type { AgentPassport } from '../../types/passport.types.js';
+
+// --- Helpers ---
+
+const testInput: PassportBuildInput = {
+  agent: {
+    name: 'crypto-test-agent',
+    entryFile: 'src/index.ts',
+    framework: 'OpenAI',
+    language: 'typescript',
+    detectedSdks: ['openai'],
+    detectedModels: ['gpt-4'],
+    confidence: 0.9,
+    sourceFiles: ['src/index.ts'],
+  },
+  autonomy: {
+    level: 'L3',
+    evidence: {
+      human_approval_gates: 2,
+      unsupervised_actions: 1,
+      no_logging_actions: 0,
+      auto_rated: true,
+    },
+    agentType: 'hybrid',
+  },
+  permissions: {
+    tools: ['search'],
+    dataAccess: { read: ['users'], write: [], delete: [] },
+    denied: [],
+    mcpServers: [],
+    humanApprovalRequired: [],
+  },
+  scanResult: undefined,
+};
+
+// --- Tests ---
+
+describe('crypto-signer', () => {
+  it('generates valid ed25519 key pair', () => {
+    const { publicKey, privateKey } = generateKeyPair();
+
+    expect(publicKey).toContain('BEGIN PUBLIC KEY');
+    expect(publicKey).toContain('END PUBLIC KEY');
+    expect(privateKey).toContain('BEGIN PRIVATE KEY');
+    expect(privateKey).toContain('END PRIVATE KEY');
+  });
+
+  it('sign and verify roundtrip', () => {
+    const { publicKey: _pub, privateKey } = generateKeyPair();
+    const unsignedManifest = buildPassport(testInput);
+
+    const signature = signPassport(unsignedManifest, privateKey);
+
+    const signedManifest: AgentPassport = {
+      ...unsignedManifest,
+      signature,
+    };
+
+    expect(verifyPassport(signedManifest)).toBe(true);
+  });
+
+  it('detects tampered manifest', () => {
+    const { publicKey: _pub, privateKey } = generateKeyPair();
+    const unsignedManifest = buildPassport(testInput);
+
+    const signature = signPassport(unsignedManifest, privateKey);
+
+    // Tamper with the agent_id after signing
+    const tamperedManifest: AgentPassport = {
+      ...unsignedManifest,
+      agent_id: 'ag_tampered-id',
+      signature,
+    };
+
+    expect(verifyPassport(tamperedManifest)).toBe(false);
+  });
+
+  it('signature contains valid algorithm and hash', () => {
+    const { publicKey: _pub, privateKey } = generateKeyPair();
+    const unsignedManifest = buildPassport(testInput);
+
+    const signature = signPassport(unsignedManifest, privateKey);
+
+    expect(signature.algorithm).toBe('ed25519');
+    expect(signature.hash).toMatch(/^sha256:[0-9a-f]+$/);
+    // value is base64 encoded
+    expect(signature.value).toMatch(/^[A-Za-z0-9+/]+=*$/);
+  });
+});

package/src/domain/passport/crypto-signer.ts

@@ -0,0 +1,157 @@
+import {
+  generateKeyPairSync,
+  createPrivateKey,
+  createPublicKey,
+  sign,
+  verify,
+  createHash,
+} from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { AgentPassport, SignatureBlock } from '../../types/passport.types.js';
+
+// --- Key constants ---
+
+const DEFAULT_KEYS_DIR = join(homedir(), '.config', 'complior', 'keys');
+const PRIVATE_KEY_FILE = 'complior-ed25519.key';
+const PUBLIC_KEY_FILE = 'complior-ed25519.pub';
+
+// --- Key pair generation ---
+
+export const generateKeyPair = (): {
+  publicKey: string;
+  privateKey: string;
+} => {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKey, privateKey };
+};
+
+// --- Key pair persistence ---
+
+export const loadOrCreateKeyPair = async (
+  keysDir?: string,
+): Promise<{ publicKey: string; privateKey: string }> => {
+  const dir = keysDir ?? DEFAULT_KEYS_DIR;
+  const privatePath = join(dir, PRIVATE_KEY_FILE);
+  const publicPath = join(dir, PUBLIC_KEY_FILE);
+
+  try {
+    const [privateKey, publicKey] = await Promise.all([
+      readFile(privatePath, 'utf-8'),
+      readFile(publicPath, 'utf-8'),
+    ]);
+    return { publicKey, privateKey };
+  } catch {
+    // Keys don't exist, generate new ones
+    const keyPair = generateKeyPair();
+
+    await mkdir(dir, { recursive: true });
+    await writeFile(privatePath, keyPair.privateKey, { mode: 0o600 });
+    await writeFile(publicPath, keyPair.publicKey);
+
+    return keyPair;
+  }
+};
+
+// --- Canonical payload ---
+
+const buildCanonicalPayload = (
+  agentId: string,
+  permissions: unknown,
+  constraints: unknown,
+  compliance: unknown,
+  timestamp: string,
+): string => {
+  const payload = {
+    agent_id: agentId,
+    compliance,
+    constraints,
+    permissions,
+    timestamp,
+  };
+  return JSON.stringify(payload, Object.keys(payload).sort());
+};
+
+// --- Public key extraction from private key ---
+
+const extractPublicKeyBase64 = (privateKeyPem: string): string => {
+  const privKeyObject = createPrivateKey(privateKeyPem);
+  const pubKeyObject = createPublicKey(privKeyObject);
+  const derBuffer = pubKeyObject.export({ type: 'spki', format: 'der' });
+  return Buffer.from(derBuffer).toString('base64');
+};
+
+// --- Manifest signing ---
+
+export const signPassport = (
+  manifest: Omit<AgentPassport, 'signature'>,
+  privateKey: string,
+): SignatureBlock => {
+  const timestamp = new Date().toISOString();
+
+  // 1. Build canonical payload with sorted keys
+  const canonical = buildCanonicalPayload(
+    manifest.agent_id,
+    manifest.permissions,
+    manifest.constraints,
+    manifest.compliance,
+    timestamp,
+  );
+
+  // 2. SHA-256 hash of canonical payload
+  const hash = createHash('sha256').update(canonical).digest('hex');
+
+  // 3. Sign canonical payload with ed25519 (no hash algorithm needed for ed25519)
+  const signatureBytes = sign(null, Buffer.from(canonical), privateKey);
+
+  // 4. Extract public key as base64 of DER-encoded public key
+  const publicKeyBase64 = extractPublicKeyBase64(privateKey);
+
+  return {
+    algorithm: 'ed25519',
+    public_key: publicKeyBase64,
+    signed_at: timestamp,
+    hash: 'sha256:' + hash,
+    value: Buffer.from(signatureBytes).toString('base64'),
+  };
+};
+
+// --- Manifest verification ---
+
+export const verifyPassport = (manifest: AgentPassport): boolean => {
+  try {
+    const { signature } = manifest;
+
+    // 1. Rebuild canonical payload using signed_at from signature
+    const canonical = buildCanonicalPayload(
+      manifest.agent_id,
+      manifest.permissions,
+      manifest.constraints,
+      manifest.compliance,
+      signature.signed_at,
+    );
+
+    // 2. Verify hash integrity
+    const expectedHash =
+      'sha256:' + createHash('sha256').update(canonical).digest('hex');
+    if (signature.hash !== expectedHash) return false;
+
+    // 3. Reconstruct public key from base64 DER
+    const derBuffer = Buffer.from(signature.public_key, 'base64');
+    const publicKeyObject = createPublicKey({
+      key: derBuffer,
+      format: 'der',
+      type: 'spki',
+    });
+
+    // 4. Verify ed25519 signature
+    const signatureBytes = Buffer.from(signature.value, 'base64');
+    return verify(null, Buffer.from(canonical), publicKeyObject, signatureBytes);
+  } catch {
+    return false;
+  }
+};

package/src/domain/passport/discovery/agent-discovery.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect } from 'vitest';
+import type { ScanContext, FileInfo } from '../../../ports/scanner.port.js';
+import type { ParsedDependency } from '../../scanner/layers/layer3-parsers.js';
+import { discoverAgents } from './agent-discovery.js';
+
+// --- Helpers ---
+
+const createFile = (
+  relativePath: string,
+  content: string,
+  extension?: string,
+): FileInfo => ({
+  path: `/home/user/my-project/${relativePath}`,
+  content,
+  extension: extension ?? `.${relativePath.split('.').pop()}`,
+  relativePath,
+});
+
+const createMockContext = (
+  files: readonly FileInfo[],
+  projectPath = '/home/user/my-project',
+): ScanContext => ({
+  files,
+  projectPath,
+});
+
+const createMockDeps = (names: readonly string[]): readonly ParsedDependency[] =>
+  names.map((name) => ({ name, version: '1.0.0', ecosystem: 'npm' }));
+
+// --- Tests ---
+
+describe('discoverAgents', () => {
+  it('returns empty array when no AI SDK detected', () => {
+    const ctx = createMockContext([
+      createFile('src/index.ts', 'console.log("hello")'),
+    ]);
+    const deps = createMockDeps(['express', 'lodash']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toEqual([]);
+  });
+
+  it('discovers agent with OpenAI SDK', () => {
+    const ctx = createMockContext([
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();
+const res = await client.chat.completions.create({ model: 'gpt-4' });`,
+      ),
+    ]);
+    const deps = createMockDeps(['openai']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].detectedSdks).toContain('openai');
+    expect(result[0].framework).toBe('OpenAI');
+  });
+
+  it('discovers agent with LangChain framework', () => {
+    const ctx = createMockContext([
+      createFile(
+        'src/chain.ts',
+        `import { AgentExecutor } from 'langchain/agents';
+const executor = new AgentExecutor({ agent, tools });`,
+      ),
+    ]);
+    const deps = createMockDeps(['langchain']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].detectedSdks).toContain('langchain');
+    expect(result[0].framework).toBe('LangChain');
+  });
+
+  it('detects model names from source', () => {
+    const ctx = createMockContext([
+      createFile(
+        'src/bot.ts',
+        `import Anthropic from '@anthropic-ai/sdk';
+const msg = await client.messages.create({ model: 'claude-sonnet-4-20250514' });`,
+      ),
+    ]);
+    const deps = createMockDeps(['@anthropic-ai/sdk']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].detectedModels).toContain('claude-sonnet-4-20250514');
+  });
+
+  it('infers name from package.json', () => {
+    const ctx = createMockContext([
+      createFile('package.json', JSON.stringify({ name: 'test-bot' }), '.json'),
+      createFile(
+        'src/index.ts',
+        'import OpenAI from "openai"; openai.chat.completions.create({})',
+      ),
+    ]);
+    const deps = createMockDeps(['openai']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('test-bot');
+  });
+
+  it('infers name from project path', () => {
+    const ctx = createMockContext(
+      [
+        createFile(
+          'src/index.ts',
+          'import OpenAI from "openai"; openai.chat.completions.create({})',
+        ),
+      ],
+      '/home/user/my-agent',
+    );
+    const deps = createMockDeps(['openai']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('my-agent');
+  });
+
+  it('calculates confidence correctly', () => {
+    // All signals present: sdk (0.2) + framework (0.2) + model (0.1) + base (0.5) = 1.0
+    const ctx = createMockContext([
+      createFile(
+        'src/agent.ts',
+        `import { AgentExecutor } from 'langchain/agents';
+const executor = new AgentExecutor({ agent, tools });
+const model = 'gpt-4o-mini';`,
+      ),
+    ]);
+    const deps = createMockDeps(['langchain']);
+
+    const result = discoverAgents(ctx, deps);
+
+    expect(result).toHaveLength(1);
+    // base 0.5 + sdk detected 0.2 + framework found 0.2 + model found 0.1 = 1.0
+    expect(result[0].confidence).toBeCloseTo(1.0);
+  });
+
+  describe('endpoint detection', () => {
+    it('detects port from .env file', () => {
+      const ctx = createMockContext([
+        createFile('.env', 'PORT=4000\nNODE_ENV=production', '.env'),
+        createFile(
+          'src/index.ts',
+          'import OpenAI from "openai"; openai.chat.completions.create({})',
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toEqual(['http://localhost:4000']);
+    });
+
+    it('detects port from code (serve pattern)', () => {
+      const ctx = createMockContext([
+        createFile(
+          'src/server.ts',
+          `import { Hono } from 'hono';
+import OpenAI from 'openai';
+const app = new Hono();
+app.post('/api/chat', async (c) => { openai.chat.completions.create({}); });
+export default { port: 3000, fetch: app.fetch };`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toEqual(['http://localhost:3000/api/chat']);
+    });
+
+    it('detects port from .listen() pattern', () => {
+      const ctx = createMockContext([
+        createFile(
+          'src/app.ts',
+          `import OpenAI from 'openai';
+const app = express();
+app.listen(8080);
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toEqual(['http://localhost:8080']);
+    });
+
+    it('detects multiple routes and builds full URLs', () => {
+      const ctx = createMockContext([
+        createFile('.env', 'PORT=4000', '.env'),
+        createFile(
+          'src/routes.ts',
+          `import OpenAI from 'openai';
+app.post('/api/chat', handler);
+app.post('/v1/chat/completions', handler);
+app.get('/health', handler);
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toContain('http://localhost:4000/api/chat');
+      expect(result[0].detectedEndpoints).toContain('http://localhost:4000/v1/chat/completions');
+      expect(result[0].detectedEndpoints).toContain('http://localhost:4000/health');
+    });
+
+    it('returns no endpoints when no port detected', () => {
+      const ctx = createMockContext([
+        createFile(
+          'src/agent.ts',
+          `import OpenAI from 'openai';
+const client = new OpenAI();
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toBeUndefined();
+    });
+
+    it('detects port from Dockerfile EXPOSE', () => {
+      const ctx = createMockContext([
+        createFile('Dockerfile', 'FROM node:20\nEXPOSE 3000\nCMD ["node", "server.js"]', 'Dockerfile'),
+        createFile(
+          'src/agent.ts',
+          `import OpenAI from 'openai';
+app.post('/api/chat', handler);
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toContain('http://localhost:3000/api/chat');
+    });
+
+    it('detects port from docker-compose.yml ports mapping', () => {
+      const ctx = createMockContext([
+        createFile('docker-compose.yml', "services:\n  app:\n    ports:\n      - '8080:8080'", 'docker-compose.yml'),
+        createFile(
+          'src/agent.ts',
+          `import OpenAI from 'openai';
+app.post('/api/chat', handler);
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toContain('http://localhost:8080/api/chat');
+    });
+
+    it('prefers .env PORT over code-detected port', () => {
+      const ctx = createMockContext([
+        createFile('.env', 'PORT=5000', '.env'),
+        createFile(
+          'src/server.ts',
+          `import OpenAI from 'openai';
+app.post('/api/chat', handler);
+export default { port: 3000, fetch: app.fetch };
+openai.chat.completions.create({});`,
+        ),
+      ]);
+      const deps = createMockDeps(['openai']);
+
+      const result = discoverAgents(ctx, deps);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].detectedEndpoints).toEqual(['http://localhost:5000/api/chat']);
+    });
+  });
+});