@connexum/ai-governance 1.0.0-beta.11

package/dist/security/access-review.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * AccessReview -- Quarterly access review for compliance frameworks.
+ *
+ * SOC 2, HIPAA, and ISO 27001 require periodic review of access rights.
+ * This module automates the review process:
+ *   - Generates access review reports
+ *   - Flags inactive operators for deactivation
+ *   - Tracks review completion status
+ *   - Maintains review audit trail
+ *
+ * T-060: Quarterly access review automation.
+ *
+ * @connexum/ai-governance
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessReview = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const log_1 = require("../util/log");
+const log = (0, log_1.createLogger)('access-review');
+class AccessReview {
+    config;
+    cyclesFile;
+    auditFile;
+    constructor(config) {
+        this.config = {
+            reviewFrequencyMs: 30 * 60 * 1000, // 30 min (DEV MODE -- production: 90 * 24 * 60 * 60 * 1000 / 90 days)
+            inactivityThresholdDays: 1, // 1 day (DEV MODE -- production: 30)
+            organizationName: 'Organization',
+            ...config,
+        };
+        if (!fs.existsSync(config.reviewDir)) {
+            fs.mkdirSync(config.reviewDir, { recursive: true });
+        }
+        this.cyclesFile = path.join(config.reviewDir, 'review-cycles.json');
+        this.auditFile = path.join(config.reviewDir, 'review-audit.jsonl');
+    }
+    /**
+     * Start a new review cycle.
+     */
+    startReview(operators) {
+        const now = new Date();
+        const cycle = {
+            id: `review_${crypto.randomBytes(6).toString('hex')}`,
+            startedAt: now.toISOString(),
+            deadline: new Date(now.getTime() + 14 * 24 * 60 * 60 * 1000).toISOString(), // 14 days to complete
+            status: 'IN_PROGRESS',
+            entries: operators.map(op => this.createEntry(op)),
+        };
+        const cycles = this.loadCycles();
+        cycles.push(cycle);
+        this.saveCycles(cycles);
+        this.audit('REVIEW_STARTED', cycle.id, { operatorCount: operators.length });
+        log.info('Access review started', { id: cycle.id, operators: operators.length });
+        return cycle;
+    }
+    /**
+     * Record a review decision for an operator.
+     */
+    recordDecision(cycleId, operatorId, decision, reviewedBy, notes) {
+        const cycles = this.loadCycles();
+        const cycle = cycles.find(c => c.id === cycleId);
+        if (!cycle)
+            throw new Error(`Review cycle ${cycleId} not found`);
+        if (cycle.status === 'COMPLETED')
+            throw new Error('Review cycle already completed');
+        const entry = cycle.entries.find(e => e.operatorId === operatorId);
+        if (!entry)
+            throw new Error(`Operator ${operatorId} not in this review`);
+        entry.decision = decision;
+        entry.reviewedBy = reviewedBy;
+        entry.reviewedAt = new Date().toISOString();
+        entry.notes = notes;
+        this.saveCycles(cycles);
+        this.audit('DECISION_RECORDED', cycleId, { operatorId, decision, reviewedBy });
+    }
+    /**
+     * Complete a review cycle (all decisions must be recorded).
+     */
+    completeReview(cycleId) {
+        const cycles = this.loadCycles();
+        const cycle = cycles.find(c => c.id === cycleId);
+        if (!cycle)
+            throw new Error(`Review cycle ${cycleId} not found`);
+        const pendingCount = cycle.entries.filter(e => e.decision === 'PENDING').length;
+        if (pendingCount > 0) {
+            throw new Error(`Cannot complete: ${pendingCount} operators still pending review`);
+        }
+        cycle.status = 'COMPLETED';
+        cycle.completedAt = new Date().toISOString();
+        cycle.summary = this.computeSummary(cycle);
+        this.saveCycles(cycles);
+        this.audit('REVIEW_COMPLETED', cycleId, cycle.summary);
+        return cycle.summary;
+    }
+    /**
+     * Check if a review is due based on the last completed review.
+     *
+     * SYSTEMIC-M2 contract (2026-04-22): the return direction is
+     * "review IS due" -- callers must treat `true` as "access must be
+     * re-attested NOW" and `false` as "review not yet due, no action
+     * needed." Any caller that interprets `true` as "no review needed"
+     * has the direction inverted and must be fixed immediately.
+     *
+     * @returns {boolean} true = review is due (access must be re-attested);
+     *                    false = review not yet due, no action needed.
+     */
+    isReviewDue() {
+        const cycles = this.loadCycles();
+        const completed = cycles
+            .filter(c => c.status === 'COMPLETED' && c.completedAt)
+            .sort((a, b) => new Date(b.completedAt).getTime() - new Date(a.completedAt).getTime());
+        if (completed.length === 0)
+            return true;
+        const lastCompleted = new Date(completed[0].completedAt).getTime();
+        return (Date.now() - lastCompleted) > this.config.reviewFrequencyMs;
+    }
+    /**
+     * Get the current (most recent) review cycle.
+     */
+    getCurrentCycle() {
+        const cycles = this.loadCycles();
+        return cycles[cycles.length - 1];
+    }
+    /**
+     * Get all review cycles.
+     */
+    getAllCycles() {
+        return this.loadCycles();
+    }
+    /**
+     * Get overdue review cycles.
+     */
+    getOverdue() {
+        const now = Date.now();
+        const cycles = this.loadCycles();
+        return cycles.filter(c => {
+            if (c.status === 'COMPLETED')
+                return false;
+            return new Date(c.deadline).getTime() < now;
+        });
+    }
+    /**
+     * Get review statistics across all cycles.
+     */
+    getStats() {
+        const cycles = this.loadCycles();
+        const completed = cycles.filter(c => c.status === 'COMPLETED');
+        const overdue = this.getOverdue();
+        const lastCompleted = completed
+            .sort((a, b) => new Date(b.completedAt).getTime() - new Date(a.completedAt).getTime())[0];
+        return {
+            totalCycles: cycles.length,
+            completedCycles: completed.length,
+            overdueCycles: overdue.length,
+            isReviewDue: this.isReviewDue(),
+            lastCompletedAt: lastCompleted?.completedAt,
+        };
+    }
+    // --- Private ---
+    createEntry(op) {
+        const flags = [];
+        const now = Date.now();
+        const threshold = this.config.inactivityThresholdDays * 24 * 60 * 60 * 1000;
+        if (!op.active) {
+            flags.push('INACTIVE');
+        }
+        if (op.lastActivity) {
+            const lastActive = new Date(op.lastActivity).getTime();
+            if (now - lastActive > threshold) {
+                flags.push('NO_RECENT_LOGIN');
+            }
+        }
+        else {
+            flags.push('NO_RECENT_LOGIN');
+        }
+        if (op.role === 'ADMIN') {
+            flags.push('ELEVATED_PRIVILEGES');
+        }
+        if (op.createdAt) {
+            const created = new Date(op.createdAt).getTime();
+            if (now - created < 30 * 24 * 60 * 60 * 1000) {
+                flags.push('NEW_OPERATOR');
+            }
+        }
+        return {
+            operatorId: op.id,
+            operatorName: op.name,
+            role: op.role,
+            active: op.active,
+            lastActivity: op.lastActivity,
+            flags,
+            decision: 'PENDING',
+        };
+    }
+    computeSummary(cycle) {
+        const entries = cycle.entries;
+        return {
+            totalOperators: entries.length,
+            retained: entries.filter(e => e.decision === 'RETAIN').length,
+            modified: entries.filter(e => e.decision === 'MODIFY').length,
+            revoked: entries.filter(e => e.decision === 'REVOKE').length,
+            pending: entries.filter(e => e.decision === 'PENDING').length,
+            flaggedInactive: entries.filter(e => e.flags.includes('INACTIVE') || e.flags.includes('NO_RECENT_LOGIN')).length,
+            completionRate: entries.filter(e => e.decision !== 'PENDING').length / entries.length,
+        };
+    }
+    loadCycles() {
+        if (!fs.existsSync(this.cyclesFile))
+            return [];
+        try {
+            return JSON.parse(fs.readFileSync(this.cyclesFile, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    saveCycles(cycles) {
+        fs.writeFileSync(this.cyclesFile, JSON.stringify(cycles, null, 2));
+    }
+    audit(action, cycleId, data) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            action,
+            cycleId,
+            ...data,
+        };
+        try {
+            fs.appendFileSync(this.auditFile, JSON.stringify(entry) + '\n');
+        }
+        catch {
+            log.error('Failed to write review audit', { cycleId, action });
+        }
+    }
+}
+exports.AccessReview = AccessReview;
+//# sourceMappingURL=access-review.js.map

package/dist/security/access-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-review.js","sourceRoot":"","sources":["../../src/security/access-review.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2CAA6B;AAC7B,+CAAiC;AACjC,qCAA2C;AAE3C,MAAM,GAAG,GAAG,IAAA,kBAAY,EAAC,eAAe,CAAC,CAAC;AA8D1C,MAAa,YAAY;IACf,MAAM,CAA+B;IACrC,UAAU,CAAS;IACnB,SAAS,CAAS;IAE1B,YAAY,MAA0B;QACpC,IAAI,CAAC,MAAM,GAAG;YACZ,iBAAiB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,sEAAsE;YACzG,uBAAuB,EAAE,CAAC,EAAE,qCAAqC;YACjE,gBAAgB,EAAE,cAAc;YAChC,GAAG,MAAM;SACV,CAAC;QAEF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,SAAyB;QACnC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAgB;YACzB,EAAE,EAAE,UAAU,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;YACrD,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;YAC5B,QAAQ,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,sBAAsB;YAClG,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;SACnD,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAExB,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5E,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QAEjF,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,cAAc,CACZ,OAAe,EACf,UAAkB,EAClB,QAAwC,EACxC,UAAkB,EAClB,KAAc;QAEd,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,YAAY,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAEpF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;QACnE,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,UAAU,qBAAqB,CAAC,CAAC;QAEzE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC1B,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;QAC9B,KAAK,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC5C,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;QAEpB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;IACjF,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,OAAe;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,YAAY,CAAC,CAAC;QAEjE,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;QAChF,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,oBAAoB,YAAY,iCAAiC,CAAC,CAAC;QACrF,CAAC;QAED,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;QAC3B,KAAK,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC7C,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,OAAO,EAAE,KAAK,CAAC,OAA6C,CAAC,CAAC;QAE7F,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,WAAW;QACT,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,MAAM;aACrB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,WAAW,CAAC;aACtD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,WAAY,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,WAAY,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAE3F,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAExC,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAY,CAAC,CAAC,OAAO,EAAE,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,eAAe;QACb,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,UAAU;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAEjC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YACvB,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;gBAAE,OAAO,KAAK,CAAC;YAC3C,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,QAAQ;QAON,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAElC,MAAM,aAAa,GAAG,SAAS;aAC5B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,WAAY,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,WAAY,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAE9F,OAAO;YACL,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,eAAe,EAAE,SAAS,CAAC,MAAM;YACjC,aAAa,EAAE,OAAO,CAAC,MAAM;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;YAC/B,eAAe,EAAE,aAAa,EAAE,WAAW;SAC5C,CAAC;IACJ,CAAC;IAED,kBAAkB;IAEV,WAAW,CAAC,EAAgB;QAClC,MAAM,KAAK,GAAiB,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,uBAAuB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAE5E,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzB,CAAC;QAED,IAAI,EAAE,CAAC,YAAY,EAAE,CAAC;YACpB,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;YACvD,IAAI,GAAG,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;gBACjC,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChC,CAAC;QAED,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,IAAI,GAAG,GAAG,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;gBAC7C,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAED,OAAO;YACL,UAAU,EAAE,EAAE,CAAC,EAAE;YACjB,YAAY,EAAE,EAAE,CAAC,IAAI;YACrB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,YAAY,EAAE,EAAE,CAAC,YAAY;YAC7B,KAAK;YACL,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC;IAEO,cAAc,CAAC,KAAkB;QACvC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,OAAO;YACL,cAAc,EAAE,OAAO,CAAC,MAAM;YAC9B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,MAAM;YAC7D,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,MAAM;YAC7D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,MAAM;YAC5D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM;YAC7D,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM;YAChH,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;SACtF,CAAC;IACJ,CAAC;IAEO,UAAU;QAChB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,OAAO,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,MAAqB;QACtC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACrE,CAAC;IAEO,KAAK,CAAC,MAAc,EAAE,OAAe,EAAE,IAA6B;QAC1E,MAAM,KAAK,GAAG;YACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM;YACN,OAAO;YACP,GAAG,IAAI;SACR,CAAC;QAEF,IAAI,CAAC;YACH,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAClE,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;CACF;AA9PD,oCA8PC"}

package/dist/security/agent-auth.d.ts

@@ -0,0 +1,92 @@
+/**
+ * AgentAuth -- Inter-agent authentication via HMAC-signed handoffs.
+ *
+ * Prevents handoff forgery between agents. Each agent has a derived
+ * secret from its name + SOUL content. All handoffs carry HMAC-SHA256
+ * signatures that are verified before acceptance.
+ *
+ * Addresses OWASP ASI07 (Inter-Agent Authentication).
+ *
+ * @connexum/ai-governance
+ */
+export interface AgentAuthConfig {
+    /** Directory containing agent SOUL/identity files */
+    agentsDir: string;
+    /** Shared secret seed (combined with agent identity for per-agent secrets) */
+    secretSeed: string;
+    /** Handoff log file path (JSONL) */
+    handoffLogPath?: string;
+    /** Signature validity window in ms (default: 300000 = 5 min) */
+    signatureWindowMs?: number;
+    /** Directory for persistent nonce storage (enables cross-restart replay protection) */
+    nonceStoreDir?: string;
+}
+export interface SignedHandoff {
+    id: string;
+    from: string;
+    to: string;
+    task: string;
+    payload?: Record<string, unknown>;
+    timestamp: string;
+    signature: string;
+    /** Nonce to prevent replay attacks */
+    nonce: string;
+}
+export interface HandoffVerification {
+    valid: boolean;
+    handoff: SignedHandoff;
+    reason?: string;
+}
+export declare class AgentAuth {
+    private config;
+    /** Cache of agent secrets derived from identity files */
+    private secretCache;
+    /** Used nonces with timestamps (prevent replay with TTL-based expiry) */
+    private usedNonces;
+    /** Persistent nonce store (survives process restart) */
+    private nonceStore;
+    constructor(config: AgentAuthConfig);
+    /**
+     * Create a signed handoff from one agent to another.
+     */
+    createHandoff(from: string, to: string, task: string, payload?: Record<string, unknown>): SignedHandoff;
+    /**
+     * Verify a signed handoff is authentic and hasn't been tampered with.
+     */
+    verifyHandoff(handoff: SignedHandoff): HandoffVerification;
+    /**
+     * Accept a handoff: verify + mark as accepted.
+     */
+    acceptHandoff(handoff: SignedHandoff, acceptingAgent: string): HandoffVerification;
+    /**
+     * Get the agent secret for signing. Derives using HKDF from agent identity + seed.
+     * Cached for performance with file modification tracking.
+     */
+    deriveAgentSecret(agentName: string): string;
+    /**
+     * Generate a shared verification token that two agents can use
+     * to establish a trusted channel.
+     */
+    createChannelToken(agent1: string, agent2: string): string;
+    /**
+     * List recent handoffs from the log.
+     */
+    getRecentHandoffs(limit?: number): Array<Record<string, unknown>>;
+    /**
+     * Clear the nonce cache (for testing or maintenance).
+     */
+    clearNonces(): void;
+    /**
+     * Prune nonces older than 2x the signature window.
+     * Prevents unbounded memory growth while maintaining replay protection
+     * for all nonces within the validity window.
+     */
+    private pruneExpiredNonces;
+    /**
+     * Clear the secret cache (if agent files change).
+     */
+    clearSecretCache(): void;
+    private buildSignatureMessage;
+    private logHandoff;
+}
+//# sourceMappingURL=agent-auth.d.ts.map

package/dist/security/agent-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-auth.d.ts","sourceRoot":"","sources":["../../src/security/agent-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAA4B;IAC1C,yDAAyD;IACzD,OAAO,CAAC,WAAW,CAAkC;IACrD,yEAAyE;IACzE,OAAO,CAAC,UAAU,CAAkC;IACpD,wDAAwD;IACxD,OAAO,CAAC,UAAU,CAA2B;gBAEjC,MAAM,EAAE,eAAe;IAkBnC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAiBvG;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,mBAAmB;IAmD1D;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,GAAG,mBAAmB;IAiBlF;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAwD5C;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAW1D;;OAEG;IACH,iBAAiB,CAAC,KAAK,GAAE,MAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAerE;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAMxB,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,UAAU;CAkBnB"}

package/dist/security/agent-auth.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * AgentAuth -- Inter-agent authentication via HMAC-signed handoffs.
+ *
+ * Prevents handoff forgery between agents. Each agent has a derived
+ * secret from its name + SOUL content. All handoffs carry HMAC-SHA256
+ * signatures that are verified before acceptance.
+ *
+ * Addresses OWASP ASI07 (Inter-Agent Authentication).
+ *
+ * @connexum/ai-governance
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentAuth = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const nonce_store_1 = require("./nonce-store");
+class AgentAuth {
+    config;
+    /** Cache of agent secrets derived from identity files */
+    secretCache = new Map();
+    /** Used nonces with timestamps (prevent replay with TTL-based expiry) */
+    usedNonces = new Map();
+    /** Persistent nonce store (survives process restart) */
+    nonceStore = null;
+    constructor(config) {
+        this.config = {
+            agentsDir: config.agentsDir,
+            secretSeed: config.secretSeed,
+            handoffLogPath: config.handoffLogPath || path.join(config.agentsDir, '..', 'audit', 'handoffs.jsonl'),
+            signatureWindowMs: config.signatureWindowMs ?? 300000,
+            nonceStoreDir: config.nonceStoreDir || '',
+        };
+        // Initialize persistent nonce store if directory is provided
+        if (this.config.nonceStoreDir) {
+            this.nonceStore = new nonce_store_1.NonceStore({
+                storePath: path.join(this.config.nonceStoreDir, 'handoff-nonces.jsonl'),
+                ttlMs: this.config.signatureWindowMs * 2,
+            });
+        }
+    }
+    /**
+     * Create a signed handoff from one agent to another.
+     */
+    createHandoff(from, to, task, payload) {
+        const timestamp = new Date().toISOString();
+        const nonce = crypto.randomBytes(16).toString('hex');
+        const id = `handoff_${Date.now()}_${nonce.slice(0, 8)}`;
+        const message = this.buildSignatureMessage(from, to, task, timestamp, nonce);
+        const secret = this.deriveAgentSecret(from);
+        const signature = crypto.createHmac('sha256', secret)
+            .update(message)
+            .digest('hex');
+        const handoff = { id, from, to, task, payload, timestamp, signature, nonce };
+        this.logHandoff('created', handoff);
+        return handoff;
+    }
+    /**
+     * Verify a signed handoff is authentic and hasn't been tampered with.
+     */
+    verifyHandoff(handoff) {
+        // Prune expired nonces before checking (TTL = 2x signature window)
+        this.pruneExpiredNonces();
+        // Check replay (nonce reuse) -- both in-memory and persistent store
+        if (this.usedNonces.has(handoff.nonce) ||
+            (this.nonceStore && this.nonceStore.has(handoff.nonce))) {
+            this.logHandoff('replay-rejected', handoff);
+            return { valid: false, handoff, reason: 'Nonce already used (replay attack)' };
+        }
+        // Check timestamp window
+        const handoffTime = new Date(handoff.timestamp).getTime();
+        const now = Date.now();
+        if (Math.abs(now - handoffTime) > this.config.signatureWindowMs) {
+            this.logHandoff('expired', handoff);
+            return { valid: false, handoff, reason: `Handoff expired (${Math.round(Math.abs(now - handoffTime) / 1000)}s old, max ${this.config.signatureWindowMs / 1000}s)` };
+        }
+        // Verify HMAC signature
+        const message = this.buildSignatureMessage(handoff.from, handoff.to, handoff.task, handoff.timestamp, handoff.nonce);
+        const secret = this.deriveAgentSecret(handoff.from);
+        const expectedSignature = crypto.createHmac('sha256', secret)
+            .update(message)
+            .digest('hex');
+        // F-NEW-CRIT-35: length-check before timingSafeEqual (Node throws
+        // ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH on unequal-length buffers).
+        // A malformed handoff.signature (wrong length / non-hex) would crash
+        // the verifier with an uncaught RangeError. Treat length mismatch as
+        // signature-invalid (fail-closed).
+        const sigBuf = Buffer.from(handoff.signature, 'hex');
+        const expBuf = Buffer.from(expectedSignature, 'hex');
+        if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
+            this.logHandoff('signature-invalid', handoff);
+            return { valid: false, handoff, reason: 'HMAC signature verification failed' };
+        }
+        // Mark nonce as used with timestamp for TTL expiry
+        this.usedNonces.set(handoff.nonce, Date.now());
+        // Persist to disk for cross-restart replay protection
+        if (this.nonceStore) {
+            this.nonceStore.add(handoff.nonce);
+        }
+        this.logHandoff('verified', handoff);
+        return { valid: true, handoff };
+    }
+    /**
+     * Accept a handoff: verify + mark as accepted.
+     */
+    acceptHandoff(handoff, acceptingAgent) {
+        // Verify the handoff is addressed to this agent
+        if (handoff.to !== acceptingAgent) {
+            return {
+                valid: false,
+                handoff,
+                reason: `Handoff addressed to '${handoff.to}', not '${acceptingAgent}'`,
+            };
+        }
+        const verification = this.verifyHandoff(handoff);
+        if (verification.valid) {
+            this.logHandoff('accepted', handoff, { acceptedBy: acceptingAgent });
+        }
+        return verification;
+    }
+    /**
+     * Get the agent secret for signing. Derives using HKDF from agent identity + seed.
+     * Cached for performance with file modification tracking.
+     */
+    deriveAgentSecret(agentName) {
+        // Check cache with file modification invalidation
+        const cached = this.secretCache.get(agentName);
+        const cacheKey = `${agentName}:mtime`;
+        const cachedMtime = this.secretCache.get(cacheKey);
+        // Try to read agent's SOUL/identity content for additional entropy
+        let identityContent = '';
+        let fileMtime = '';
+        const possibleFiles = [
+            path.join(this.config.agentsDir, `${agentName}.md`),
+            path.join(this.config.agentsDir, `${agentName}-agent.md`),
+        ];
+        for (const file of possibleFiles) {
+            if (fs.existsSync(file)) {
+                try {
+                    const stat = fs.statSync(file);
+                    fileMtime = stat.mtimeMs.toString();
+                    const content = fs.readFileSync(file, 'utf-8');
+                    // Extract SOUL section if present
+                    const soulMatch = content.match(/## SOUL[^\n]*\n([\s\S]*?)(?=\n## |\n---|\Z)/);
+                    identityContent = soulMatch ? soulMatch[1] : content.slice(0, 200);
+                }
+                catch {
+                    // Fall through to seed-only derivation
+                }
+                break;
+            }
+        }
+        // Return cached secret only if file hasn't changed
+        if (cached && cachedMtime === fileMtime)
+            return cached;
+        // HKDF-like derivation: extract then expand
+        // Step 1: Extract -- PRK from seed + identity
+        const salt = crypto.createHash('sha256')
+            .update(`connexum-agent-auth-salt:${agentName}`)
+            .digest();
+        const ikm = `${this.config.secretSeed}:${agentName}:${identityContent}`;
+        const prk = crypto.createHmac('sha256', salt)
+            .update(ikm)
+            .digest();
+        // Step 2: Expand -- derive final key
+        const info = Buffer.from(`connexum-agent-secret-v1:${agentName}`);
+        const secret = crypto.createHmac('sha256', prk)
+            .update(Buffer.concat([info, Buffer.from([1])]))
+            .digest('hex');
+        this.secretCache.set(agentName, secret);
+        this.secretCache.set(cacheKey, fileMtime);
+        return secret;
+    }
+    /**
+     * Generate a shared verification token that two agents can use
+     * to establish a trusted channel.
+     */
+    createChannelToken(agent1, agent2) {
+        const secret1 = this.deriveAgentSecret(agent1);
+        const secret2 = this.deriveAgentSecret(agent2);
+        // Deterministic: always combine in sorted order
+        const [a, b] = [secret1, secret2].sort();
+        return crypto.createHash('sha256')
+            .update(`channel:${a}:${b}`)
+            .digest('hex');
+    }
+    /**
+     * List recent handoffs from the log.
+     */
+    getRecentHandoffs(limit = 50) {
+        const logPath = this.config.handoffLogPath;
+        if (!fs.existsSync(logPath))
+            return [];
+        const lines = fs.readFileSync(logPath, 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .slice(-limit);
+        return lines.map(line => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return { raw: line };
+            }
+        });
+    }
+    /**
+     * Clear the nonce cache (for testing or maintenance).
+     */
+    clearNonces() {
+        this.usedNonces.clear();
+    }
+    /**
+     * Prune nonces older than 2x the signature window.
+     * Prevents unbounded memory growth while maintaining replay protection
+     * for all nonces within the validity window.
+     */
+    pruneExpiredNonces() {
+        const ttl = this.config.signatureWindowMs * 2;
+        const now = Date.now();
+        for (const [nonce, timestamp] of this.usedNonces) {
+            if (now - timestamp > ttl) {
+                this.usedNonces.delete(nonce);
+            }
+        }
+    }
+    /**
+     * Clear the secret cache (if agent files change).
+     */
+    clearSecretCache() {
+        this.secretCache.clear();
+    }
+    // --- Private helpers ---
+    buildSignatureMessage(from, to, task, timestamp, nonce) {
+        // Use JSON canonical form to avoid delimiter collision (pipe chars in field values)
+        return JSON.stringify([from, to, task, timestamp, nonce]);
+    }
+    logHandoff(event, handoff, extra) {
+        const logDir = path.dirname(this.config.handoffLogPath);
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            event: `handoff:${event}`,
+            handoffId: handoff.id,
+            from: handoff.from,
+            to: handoff.to,
+            task: handoff.task,
+            ...extra,
+        };
+        fs.appendFileSync(this.config.handoffLogPath, JSON.stringify(entry) + '\n');
+    }
+}
+exports.AgentAuth = AgentAuth;
+//# sourceMappingURL=agent-auth.js.map