@datacules/agent-identity-compliance 0.2.1

package/README.md

@@ -0,0 +1,188 @@
+# `@datacules/agent-identity-compliance`
+
+Compliance report generation + tamper-evident audit log for [`@datacules/agent-identity`](../../core).
+
+Answers regulatory audit questions directly from your audit logs — no custom queries.
+Provides a SHA-256 hash chain logger and CLI verifier for SOC 2, GDPR, and HIPAA evidence.
+
+## Install
+
+```bash
+npm install @datacules/agent-identity-compliance
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `ComplianceReportGenerator` | Generate SOC 2 / GDPR / HIPAA reports from audit logs |
+| `HashChainAuditLogger` | Wraps any audit sink — appends SHA-256 chain fields to every entry |
+| `ChainVerifier` | Replays the chain and returns intact/broken status |
+| CLI `agent-identity audit verify` | Verify a JSONL audit log file from the command line |
+| CLI `agent-identity report` | Generate a compliance report from a JSONL audit log file |
+
+---
+
+## Compliance Reports
+
+```typescript
+import { ComplianceReportGenerator, MemoryReportStore } from '@datacules/agent-identity-compliance';
+
+const generator = new ComplianceReportGenerator({
+  store: new MemoryReportStore(auditEntries), // or your own ReportStore
+  piiTags: ['pii', 'phi', 'personal', 'financial'],
+  businessHoursStart: 9,
+  businessHoursEnd: 18,
+});
+
+// SOC 2 CC6 — Logical and Physical Access Controls
+const report = await generator.generate({
+  type: 'soc2',
+  from: '2026-01-01T00:00:00Z',
+  to: '2026-03-31T23:59:59Z',
+});
+
+// GDPR Article 30 — Records of Processing Activities (Markdown output)
+const gdprReport = await generator.generate({
+  type: 'gdpr',
+  from: '2026-01-01T00:00:00Z',
+  to: '2026-03-31T23:59:59Z',
+  format: 'markdown',
+});
+
+console.log(report.agentAccessSummary);        // which agents used which credentials
+console.log(report.piiResourceAccess);         // all accesses to PII-tagged resources
+console.log(report.offHoursAccess);            // accesses outside business hours
+console.log(report.credentialRotationHistory); // rotation events
+console.log(report.anomalyEvents);             // all flagged anomalies
+```
+
+### Report sections
+
+| Section | Description |
+|---------|-------------|
+| `agentAccessSummary` | Per-agent resolution counts, credentials used, resources accessed |
+| `piiResourceAccess` | All resolutions against resources tagged `pii`, `phi`, or `personal` |
+| `offHoursAccess` | Resolutions outside configured business hours (includes weekends) |
+| `credentialRotationHistory` | `credential.rotated` events — when, which credential |
+| `anomalyEvents` | All `credential.anomaly` events with signal and severity |
+
+---
+
+## Tamper-Evident Audit Log (Hash Chain)
+
+Wrap any existing audit logger to make every entry part of a SHA-256 linked chain:
+
+```typescript
+import { HashChainAuditLogger } from '@datacules/agent-identity-compliance';
+import { ConsoleAuditLogger } from '@datacules/agent-identity-audit';
+import { createRouter } from '@datacules/agent-identity';
+
+// 1. Wrap any existing logger
+const base = new ConsoleAuditLogger();
+const chained = new HashChainAuditLogger(base);
+
+// 2. Use the chained logger with the router — everything else is unchanged
+const router = createRouter(credentials, rules, chained);
+```
+
+The underlying sink receives entries with two extra fields:
+
+```json
+{
+  "userId": "user-abc",
+  "credentialId": "cred-openai",
+  "action": "read",
+  "timestamp": "2026-05-28T10:00:00.000Z",
+  "...": "...",
+  "prevHash": "a3f8...",
+  "hash":     "9c12..."
+}
+```
+
+Any retroactive modification to any field in any entry breaks the chain from that point forward — detectable in O(n) time.
+
+### Verifying the chain programmatically
+
+```typescript
+import { ChainVerifier } from '@datacules/agent-identity-compliance';
+import { readFileSync } from 'node:fs';
+
+const jsonl = readFileSync('./audit.jsonl', 'utf8');
+const result = ChainVerifier.verifyJsonl(jsonl);
+
+console.log(result.intact);      // true / false
+console.log(result.entryCount);  // number of entries verified
+console.log(result.rootHash);    // SHA-256 of the last entry (publish to an anchor)
+console.log(result.brokenAt);    // entry index of first broken link (null if intact)
+console.log(result.brokenReason); // human-readable reason (null if intact)
+```
+
+---
+
+## CLI
+
+The package ships a zero-dependency CLI (`agent-identity`) for offline log verification and report generation.
+
+### Verify an audit log
+
+```bash
+agent-identity audit verify --file ./audit.jsonl
+```
+
+Output:
+```
+Audit log verification — /path/to/audit.jsonl
+Entries verified : 47382
+Chain status     : ✅  INTACT
+Chain root hash  : 9c12a3f8...b4e2
+```
+
+If a line has been modified:
+```
+Chain status     : ❌  BROKEN
+Broken at entry  : 1204
+Reason           : Entry 1204: hash mismatch — entry data appears to have been modified
+```
+
+Exit code 0 = intact, exit code 1 = broken or empty. Suitable for CI gates:
+
+```bash
+agent-identity audit verify --file ./audit.jsonl || { echo "Audit log tampered!"; exit 1; }
+```
+
+### Generate a compliance report
+
+```bash
+# SOC 2 CC6 — JSON output (default)
+agent-identity report soc2 --file ./audit.jsonl
+
+# GDPR Article 30 — Markdown, filtered to Q1 2026
+agent-identity report gdpr \
+  --file ./audit.jsonl \
+  --from 2026-01-01 \
+  --to   2026-03-31 \
+  --format markdown
+
+# HIPAA §164.312 — save to file
+agent-identity report hipaa --file ./audit.jsonl > ./reports/hipaa-q2.json
+```
+
+---
+
+## Custom ReportStore
+
+```typescript
+import type { ReportStore } from '@datacules/agent-identity-compliance';
+
+class PostgresReportStore implements ReportStore {
+  async queryEntries(from: string, to: string) {
+    return db.query(
+      'SELECT * FROM audit_log WHERE timestamp BETWEEN $1 AND $2 ORDER BY timestamp ASC',
+      [from, to]
+    );
+  }
+}
+
+const generator = new ComplianceReportGenerator({ store: new PostgresReportStore() });
+```

package/bin/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * agent-identity CLI
+ *
+ * Commands:
+ *
+ *   audit verify --file <path> [--quiet]
+ *     Verify the SHA-256 chain of a JSONL audit log file.
+ *     Exit 0 if intact, exit 1 if broken or empty.
+ *
+ *   report <type> --file <path> [--from <ISO>] [--to <ISO>] [--format json|markdown]
+ *     Generate a compliance report from a JSONL audit log file.
+ *     <type> must be one of: soc2 | gdpr | hipaa | custom
+ *     Output is written to stdout.
+ *
+ * Examples:
+ *
+ *   agent-identity audit verify --file ./audit.jsonl
+ *   agent-identity report soc2 --file ./audit.jsonl --format markdown
+ *   agent-identity report gdpr --file ./audit.jsonl --from 2026-01-01 --to 2026-03-31
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ─── Argument parsing ────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { args, positional };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────────
+
+function die(msg) {
+  process.stderr.write(`\nError: ${msg}\n\n`);
+  printHelp();
+  process.exit(1);
+}
+
+function printHelp() {
+  process.stdout.write(`
+agent-identity — Datacules LLC
+
+Usage:
+  agent-identity audit verify --file <path> [--quiet]
+  agent-identity report <type> --file <path> [--from <ISO>] [--to <ISO>] [--format json|markdown]
+
+Commands:
+  audit verify    Verify the SHA-256 hash chain of a JSONL audit log file.
+                  Exits 0 if intact, 1 if broken or empty.
+
+  report <type>   Generate a compliance report from a JSONL audit log.
+                  type: soc2 | gdpr | hipaa | custom
+
+Options:
+  --file <path>   Path to the JSONL audit log file (required)
+  --from <ISO>    Report period start (ISO 8601, default: beginning of log)
+  --to <ISO>      Report period end   (ISO 8601, default: end of log)
+  --format        Output format for report: json (default) | markdown
+  --quiet         Suppress progress output (audit verify only)
+
+Examples:
+  agent-identity audit verify --file ./audit.jsonl
+  agent-identity report soc2 --file ./audit.jsonl --format markdown
+  agent-identity report gdpr --file ./audit.jsonl --from 2026-01-01 --to 2026-06-30
+`);
+}
+
+function readJsonlFile(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    die(`File not found: ${resolved}`);
+  }
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+// ─── SHA-256 chain verification (inline — mirrors ChainVerifier from index.ts) ──
+// We inline a plain-JS version so the CLI works without requiring the TS build.
+
+const { createHash } = require('node:crypto');
+
+function computeEntryHash(entry, prevHash) {
+  const { hash: _h, prevHash: _p, ...coreFields } = entry;
+  void _h; void _p;
+  const sortedKeys = Object.keys(coreFields).sort();
+  const payload = {};
+  for (const k of sortedKeys) payload[k] = coreFields[k];
+  return createHash('sha256')
+    .update(JSON.stringify(payload) + prevHash)
+    .digest('hex');
+}
+
+function verifyJsonl(jsonl) {
+  const entries = [];
+  const lines = jsonl.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      return {
+        intact: false,
+        entryCount: entries.length,
+        rootHash: entries[entries.length - 1]?.hash ?? null,
+        brokenAt: entries.length,
+        brokenReason: `Line ${i + 1}: failed to parse as JSON — log file may be corrupted`,
+      };
+    }
+  }
+
+  if (entries.length === 0) {
+    return { intact: false, entryCount: 0, rootHash: null, brokenAt: null, brokenReason: 'Log is empty — nothing to verify' };
+  }
+
+  let prevHash = '';
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.prevHash !== prevHash) {
+      return {
+        intact: false,
+        entryCount: entries.length,
+        rootHash: entries[i - 1]?.hash ?? null,
+        brokenAt: i,
+        brokenReason: `Entry ${i}: prevHash mismatch — expected ${prevHash.slice(0, 16)}… got ${String(entry.prevHash).slice(0, 16)}…`,
+      };
+    }
+    const expected = computeEntryHash(entry, prevHash);
+    if (entry.hash !== expected) {
+      return {
+        intact: false,
+        entryCount: entries.length,
+        rootHash: entries[i - 1]?.hash ?? null,
+        brokenAt: i,
+        brokenReason: `Entry ${i}: hash mismatch — entry data appears to have been modified`,
+      };
+    }
+    prevHash = entry.hash;
+  }
+
+  return { intact: true, entryCount: entries.length, rootHash: prevHash, brokenAt: null, brokenReason: null };
+}
+
+// ─── Compliance report (inline — mirrors ComplianceReportGenerator) ─────────────
+
+function isOffHours(timestamp, startHour = 9, endHour = 18) {
+  const d = new Date(timestamp);
+  const hour = d.getUTCHours();
+  const day = d.getUTCDay();
+  if (day === 0 || day === 6) return true;
+  return hour < startHour || hour >= endHour;
+}
+
+function generateReport(type, entries, format) {
+  const agentMap = new Map();
+  const piiAccess = [];
+  const offHours = [];
+  const rotations = [];
+  const anomalies = [];
+  const piiTags = ['pii', 'phi', 'personal'];
+
+  for (const e of entries) {
+    if (!e.action.startsWith('credential.')) {
+      let s = agentMap.get(e.userId);
+      if (!s) {
+        s = { userId: e.userId, credentialIds: [], resourceIds: [], actionCounts: {}, resolutionCount: 0, firstSeen: e.timestamp, lastSeen: e.timestamp };
+        agentMap.set(e.userId, s);
+      }
+      if (!s.credentialIds.includes(e.credentialId)) s.credentialIds.push(e.credentialId);
+      if (!s.resourceIds.includes(e.resourceId)) s.resourceIds.push(e.resourceId);
+      s.actionCounts[e.action] = (s.actionCounts[e.action] ?? 0) + 1;
+      s.resolutionCount += 1;
+      if (e.timestamp < s.firstSeen) s.firstSeen = e.timestamp;
+      if (e.timestamp > s.lastSeen) s.lastSeen = e.timestamp;
+
+      if (piiTags.some(tag => e.resourceId.toLowerCase().includes(tag))) piiAccess.push(e);
+      if (isOffHours(e.timestamp)) offHours.push({ timestamp: e.timestamp, userId: e.userId, action: e.action, resourceId: e.resourceId, credentialId: e.credentialId });
+    }
+    if (e.action === 'credential.rotated') rotations.push({ credentialId: e.credentialId, rotatedAt: e.timestamp, triggeredBy: e.userId });
+    if (e.action === 'credential.anomaly') anomalies.push({ timestamp: e.timestamp, userId: e.userId, credentialId: e.credentialId, signal: e.signal ?? 'unknown', severity: e.severity ?? 'unknown' });
+  }
+
+  const summary = Array.from(agentMap.values()).sort((a, b) => b.resolutionCount - a.resolutionCount);
+
+  const report = {
+    type,
+    generatedAt: new Date().toISOString(),
+    periodFrom: entries[0]?.timestamp ?? 'n/a',
+    periodTo: entries[entries.length - 1]?.timestamp ?? 'n/a',
+    agentAccessSummary: summary,
+    piiResourceAccess: piiAccess,
+    offHoursAccess: offHours,
+    credentialRotationHistory: rotations,
+    anomalyEvents: anomalies,
+    totalEntries: entries.length,
+    summary: `${type.toUpperCase()} report: ${entries.length} total resolutions, ${piiAccess.length} PII accesses, ${offHours.length} off-hours accesses, ${anomalies.length} anomaly events`,
+  };
+
+  if (format === 'markdown') {
+    const lines = [
+      `# Agent Identity — ${type.toUpperCase()} Compliance Report`,
+      `**Period:** ${report.periodFrom} – ${report.periodTo}`,
+      `**Generated:** ${report.generatedAt}`,
+      `**Total resolutions:** ${report.totalEntries}`,
+      '',
+      '## Agent Access Summary',
+      '| Agent | Resolutions | Credentials | Resources | First Seen | Last Seen |',
+      '|-------|-------------|-------------|-----------|------------|-----------|',
+      ...summary.map(a => `| ${a.userId} | ${a.resolutionCount} | ${a.credentialIds.length} | ${a.resourceIds.length} | ${a.firstSeen.slice(0,10)} | ${a.lastSeen.slice(0,10)} |`),
+      '',
+      `## PII Resource Access (${piiAccess.length} events)`,
+      piiAccess.length === 0 ? '_None_' : piiAccess.map(e => `- ${e.timestamp} | ${e.userId} | ${e.action} | ${e.resourceId}`).join('\n'),
+      '',
+      `## Off-Hours Access (${offHours.length} events)`,
+      offHours.length === 0 ? '_None_' : offHours.map(e => `- ${e.timestamp} | ${e.userId} | ${e.action} | ${e.resourceId}`).join('\n'),
+      '',
+      `## Credential Rotation History (${rotations.length} rotations)`,
+      rotations.length === 0 ? '_None_' : rotations.map(r => `- ${r.rotatedAt} | ${r.credentialId} | triggered by ${r.triggeredBy}`).join('\n'),
+      '',
+      `## Anomaly Events (${anomalies.length} events)`,
+      anomalies.length === 0 ? '_None_' : anomalies.map(a => `- ${a.timestamp} | ${a.userId} | ${a.credentialId} | ${a.signal} (${a.severity})`).join('\n'),
+    ];
+    return lines.join('\n');
+  }
+
+  return JSON.stringify(report, null, 2);
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const { args, positional } = parseArgs(argv);
+
+if (positional.length === 0 || positional[0] === 'help' || args.help || args.h) {
+  printHelp();
+  process.exit(0);
+}
+
+const command = positional[0];
+const subCommand = positional[1];
+
+// ── agent-identity audit verify ──────────────────────────────────────────────────
+if (command === 'audit' && subCommand === 'verify') {
+  if (!args.file) die('--file <path> is required');
+
+  const content = readJsonlFile(args.file);
+  const result = verifyJsonl(content);
+
+  if (!args.quiet) {
+    process.stdout.write(`\nAudit log verification — ${path.resolve(args.file)}\n`);
+    process.stdout.write(`Entries verified : ${result.entryCount}\n`);
+    process.stdout.write(`Chain status     : ${result.intact ? '\u2705  INTACT' : '\u274C  BROKEN'}\n`);
+    if (result.rootHash) {
+      process.stdout.write(`Chain root hash  : ${result.rootHash}\n`);
+    }
+    if (!result.intact) {
+      process.stdout.write(`Broken at entry  : ${result.brokenAt ?? 'n/a'}\n`);
+      process.stdout.write(`Reason           : ${result.brokenReason}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  process.exit(result.intact ? 0 : 1);
+}
+
+// ── agent-identity report <type> ────────────────────────────────────────────────
+if (command === 'report') {
+  const reportType = subCommand;
+  if (!reportType || !['soc2', 'gdpr', 'hipaa', 'custom'].includes(reportType)) {
+    die(`report type must be one of: soc2 | gdpr | hipaa | custom (got: ${reportType ?? 'none'})`);
+  }
+  if (!args.file) die('--file <path> is required');
+
+  const content = readJsonlFile(args.file);
+  const lines = content.split('\n').filter(l => l.trim());
+  let entries;
+  try {
+    entries = lines.map(l => JSON.parse(l));
+  } catch (err) {
+    die(`Failed to parse JSONL file: ${err.message}`);
+  }
+
+  // Filter by date range if provided
+  let filtered = entries;
+  if (args.from) {
+    const start = new Date(args.from).getTime();
+    filtered = filtered.filter(e => new Date(e.timestamp).getTime() >= start);
+  }
+  if (args.to) {
+    const end = new Date(args.to).getTime();
+    filtered = filtered.filter(e => new Date(e.timestamp).getTime() <= end);
+  }
+
+  const format = args.format === 'markdown' ? 'markdown' : 'json';
+  const output = generateReport(reportType, filtered, format);
+  process.stdout.write(output + '\n');
+  process.exit(0);
+}
+
+// ── Unknown command ──────────────────────────────────────────────────────────────
+die(`Unknown command: ${command} ${subCommand ?? ''}`.trim());

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@datacules/agent-identity-compliance",
+  "version": "0.2.1",
+  "private": false,
+  "description": "Compliance report generator + tamper-evident audit log for @datacules/agent-identity — SOC 2, GDPR, HIPAA reports, SHA-256 chain verification CLI",
+  "author": "Datacules LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hvrcharon1/agent-identity.git",
+    "directory": "packages/integrations/compliance"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "agent-identity": "./bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "@datacules/agent-identity": "^0.1.0"
+  }
+}