@connexum/ai-governance 1.0.0-beta.11

package/dist/audit/provenance-signer.js

@@ -0,0 +1,315 @@
+"use strict";
+/**
+ * ProvenanceSigner -- P4-AIR-03 (EU AI Act Art. 50)
+ *
+ * Signs AI-generated narrative report bodies with AI-provenance metadata.
+ * Produces a signed envelope that auditors can independently verify to
+ * confirm the report was generated by our runtime with the declared model.
+ *
+ * Signed envelope fields:
+ *   - contentHash: SHA-256 of the narrative body string
+ *   - art50Disclosure: EU AI Act Art. 50 metadata block
+ *   - packBindings: compliance packs that were in force at generation time
+ *   - chainHeadHash: audit-chain tip hash at generate time
+ *   - signedAt: ISO-8601 timestamp
+ *   - signature: HMAC-SHA256 over canonical JSON of all above fields
+ *
+ * Security:
+ *   - Signing key must be AI_PROVENANCE_HMAC_KEY env var (>= 32 chars).
+ *   - AI_PROVENANCE_HMAC_KEY must be distinct from all other boot secrets
+ *     (enforced at boot by the distinct-secret boot gate).
+ *   - Canonical JSON sorts keys alphabetically before signing to prevent
+ *     field-reordering attacks.
+ *
+ * Spec: P4-AIR-03 AC 7-9
+ *
+ * @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.HomoglyphKeyError = void 0;
+exports.validateProvenanceHmacKey = validateProvenanceHmacKey;
+exports.canonicalJson = canonicalJson;
+exports.signProvenance = signProvenance;
+exports.verifyProvenance = verifyProvenance;
+exports.verifyContentHash = verifyContentHash;
+const crypto = __importStar(require("node:crypto"));
+const SDK_VERSION = '1.0.0-beta.1';
+// ---------------------------------------------------------------------------
+// Boot-gate check (exported so the boot gate can call it)
+// ---------------------------------------------------------------------------
+/**
+ * Validate the AI_PROVENANCE_HMAC_KEY at boot time.
+ *
+ * Requirements:
+ *   - Must be present (non-empty).
+ *   - Must be >= 32 characters.
+ *   - Must be distinct from the other 5 named boot secrets.
+ *
+ * Throws on any violation (fail-closed).
+ */
+function validateProvenanceHmacKey(provenanceKey, otherSecrets = {}) {
+    if (!provenanceKey) {
+        throw new Error('SECURITY: AI_PROVENANCE_HMAC_KEY is not set. ' +
+            'This key is required to sign AI-provenance envelopes (P4-AIR-03 / EU AI Act Art. 50). ' +
+            'Set AI_PROVENANCE_HMAC_KEY in the environment (32+ chars, distinct from ' +
+            'TRUST_ANCHOR_HMAC, ENTITLEMENT_SIGNING_KEY, JWT_SECRET, ENCRYPTION_KEY, APPROVAL_SECRET).');
+    }
+    if (provenanceKey.length < 32) {
+        throw new Error('SECURITY: AI_PROVENANCE_HMAC_KEY must be at least 32 characters. ' +
+            'Shorter secrets are trivially brute-forceable.');
+    }
+    for (const [name, value] of Object.entries(otherSecrets)) {
+        if (value && provenanceKey === value) {
+            throw new Error(`SECURITY: AI_PROVENANCE_HMAC_KEY must not equal ${name}. ` +
+                'Shared signing key defeats separation of AI-provenance attestation from other security controls.');
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Canonical JSON
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown by canonicalJson when homoglyph duplicate keys are detected.
+ *
+ * H9d: An object whose keys collide after NFKC normalization is a tamper
+ * attempt. The canonical form would silently drop one of the values.
+ * We throw instead so callers can emit an audit event and fail closed.
+ *
+ * Example: { "\u0041dmin": 1, "Admin": 2 } -- '\u0041' is 'A' after NFKC,
+ * so both keys normalize to "Admin". The second entry would shadow the first.
+ */
+class HomoglyphKeyError extends Error {
+    /** Object path where the collision was detected (dot-notation) */
+    path;
+    /** The two raw keys that collide after NFKC normalization */
+    collidingKeys;
+    /** The shared NFKC-normalized form */
+    normalizedKey;
+    constructor(path, key1, key2, normalizedKey) {
+        super(`canonicalJson: homoglyph duplicate key detected at "${path}": ` +
+            `"${key1}" and "${key2}" both normalize to "${normalizedKey}" under NFKC. ` +
+            'This is a tamper attempt. Refusing to produce canonical form.');
+        this.name = 'HomoglyphKeyError';
+        this.path = path;
+        this.collidingKeys = [key1, key2];
+        this.normalizedKey = normalizedKey;
+    }
+}
+exports.HomoglyphKeyError = HomoglyphKeyError;
+/**
+ * Produce a canonical (sorted-keys, deterministic) JSON string.
+ * Prevents field-reordering attacks on the signature.
+ *
+ * H4 fix: arrays are now handled deterministically:
+ *   - Arrays of objects: each element has its keys sorted recursively.
+ *   - Arrays of primitives: elements are sorted lexicographically so that
+ *     ["b","a"] and ["a","b"] produce the same canonical form.
+ *   - Mixed arrays: objects are recursed, primitives are sorted by
+ *     their JSON serialization.
+ *
+ * H9d fix: object keys are NFKC-normalized before sorting. If two keys in
+ * the same object normalize to the same NFKC form (homoglyph attack),
+ * HomoglyphKeyError is thrown. Callers must catch this and emit an audit
+ * event (canonicalJson.homoglyph-key-rejected) before failing closed.
+ */
+function canonicalJson(obj) {
+    return JSON.stringify(_canonicalize(obj, ''));
+}
+function _canonicalize(val, path) {
+    if (val === null || val === undefined)
+        return val;
+    if (Array.isArray(val)) {
+        // Recurse into each element first
+        const recurse = val.map((el, i) => _canonicalize(el, `${path}[${i}]`));
+        // Sort the array for determinism:
+        //   - All elements serialized to string for stable comparison
+        return recurse.sort((a, b) => {
+            const sa = JSON.stringify(a) ?? '';
+            const sb = JSON.stringify(b) ?? '';
+            return sa < sb ? -1 : sa > sb ? 1 : 0;
+        });
+    }
+    if (typeof val === 'object') {
+        const rawKeys = Object.keys(val);
+        // H9d: Normalize keys with NFKC and detect homoglyph collisions
+        // before sorting. A collision means two different raw keys map to
+        // the same normalized form -- a tamper attempt.
+        const normalizedMap = new Map(); // normalizedKey -> first rawKey
+        for (const rawKey of rawKeys) {
+            const normalized = rawKey.normalize('NFKC');
+            if (normalizedMap.has(normalized)) {
+                const firstKey = normalizedMap.get(normalized);
+                const currentPath = path ? `${path}.${rawKey}` : rawKey;
+                throw new HomoglyphKeyError(currentPath, firstKey, rawKey, normalized);
+            }
+            normalizedMap.set(normalized, rawKey);
+        }
+        // Sort by NFKC-normalized key for consistent ordering
+        const sortedRawKeys = rawKeys.sort((a, b) => {
+            const na = a.normalize('NFKC');
+            const nb = b.normalize('NFKC');
+            return na < nb ? -1 : na > nb ? 1 : 0;
+        });
+        const sorted = {};
+        for (const rawKey of sortedRawKeys) {
+            const normalizedKey = rawKey.normalize('NFKC');
+            const childPath = path ? `${path}.${normalizedKey}` : normalizedKey;
+            sorted[normalizedKey] = _canonicalize(val[rawKey], childPath);
+        }
+        return sorted;
+    }
+    return val;
+}
+// ---------------------------------------------------------------------------
+// SHA-256 helpers
+// ---------------------------------------------------------------------------
+function sha256(input) {
+    return crypto.createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+function hmacSha256(payload, key) {
+    return crypto.createHmac('sha256', key).update(payload, 'utf-8').digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Sign
+// ---------------------------------------------------------------------------
+/**
+ * Sign a narrative body and produce a ProvenanceEnvelope.
+ *
+ * The envelope can be attached to a report response so external auditors
+ * can verify it with verifyProvenance().
+ *
+ * @throws Error if hmacKey is missing or shorter than 32 characters.
+ */
+function signProvenance(input) {
+    const key = input.hmacKey ?? process.env['AI_PROVENANCE_HMAC_KEY'] ?? '';
+    if (!key || key.length < 32) {
+        throw new Error('AI_PROVENANCE_HMAC_KEY is missing or too short (must be >= 32 chars). ' +
+            'Cannot sign AI-provenance envelope.');
+    }
+    const contentHash = sha256(input.narrativeBody);
+    const signedAt = new Date().toISOString();
+    const art50Disclosure = {
+        wasLlmGenerated: true,
+        model: input.modelId,
+        modelProvider: input.modelProvider,
+        generatedAt: input.generatedAt,
+        governanceRuntime: `@connexum/ai-governance@${SDK_VERSION}`,
+    };
+    // Build the unsigned envelope (all fields except signature)
+    const unsigned = {
+        contentHash,
+        art50Disclosure,
+        packBindings: [...input.packBindings].sort(), // deterministic order
+        chainHeadHash: input.chainHeadHash,
+        signedAt,
+    };
+    const canonical = canonicalJson(unsigned);
+    const signature = hmacSha256(canonical, key);
+    return { ...unsigned, signature };
+}
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+/**
+ * Verify a ProvenanceEnvelope produced by signProvenance().
+ *
+ * Checks:
+ *   1. All required fields are present.
+ *   2. The HMAC signature is valid over the canonical JSON of the non-sig fields.
+ *
+ * Does NOT re-hash the narrative body against contentHash -- the caller
+ * should separately verify contentHash === SHA-256(narrativeBody) if they
+ * have the body available.
+ *
+ * Returns { valid: true } on success, { valid: false, reason } on failure.
+ */
+function verifyProvenance(envelope, hmacKey) {
+    // Check required fields
+    const requiredFields = [
+        'contentHash',
+        'art50Disclosure',
+        'packBindings',
+        'chainHeadHash',
+        'signedAt',
+        'signature',
+    ];
+    for (const field of requiredFields) {
+        if (envelope[field] === undefined || envelope[field] === null) {
+            return { valid: false, reason: `Missing required field: ${field}` };
+        }
+    }
+    if (!envelope.art50Disclosure.wasLlmGenerated) {
+        return { valid: false, reason: 'art50Disclosure.wasLlmGenerated must be true' };
+    }
+    if (!hmacKey || hmacKey.length < 32) {
+        return { valid: false, reason: 'Verification key is missing or too short' };
+    }
+    // Reconstruct the unsigned portion and recompute signature
+    const { signature: _sig, ...unsigned } = envelope;
+    const canonical = canonicalJson(unsigned);
+    const expected = hmacSha256(canonical, hmacKey);
+    try {
+        const sigBuf = Buffer.from(_sig, 'hex');
+        const expBuf = Buffer.from(expected, 'hex');
+        if (sigBuf.length !== expBuf.length) {
+            return { valid: false, reason: 'Signature length mismatch' };
+        }
+        if (!crypto.timingSafeEqual(sigBuf, expBuf)) {
+            return { valid: false, reason: 'Signature mismatch -- envelope may have been tampered with' };
+        }
+    }
+    catch {
+        return { valid: false, reason: 'Signature comparison failed (malformed hex)' };
+    }
+    return { valid: true };
+}
+/**
+ * Verify that the contentHash in an envelope matches the actual body.
+ *
+ * This is a separate check so callers can verify both the envelope
+ * signature AND the body integrity in two steps.
+ */
+function verifyContentHash(envelope, narrativeBody) {
+    const actual = sha256(narrativeBody);
+    if (actual !== envelope.contentHash) {
+        return {
+            valid: false,
+            reason: `Content hash mismatch: expected ${envelope.contentHash}, got ${actual}`,
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=provenance-signer.js.map

package/dist/audit/provenance-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-signer.js","sourceRoot":"","sources":["../../src/audit/provenance-signer.ts"],"names":[],"mappings":"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"}

package/dist/audit/redis-event-bus.d.ts

@@ -0,0 +1,103 @@
+/**
+ * RedisEventBus -- Redis pub/sub transport implementing the same public surface
+ * as the file-based EventBus.
+ *
+ * Motivation: the file-based EventBus suffers 3-60 second cross-pod latency on
+ * shared NFS/EFS because Linux NFS stat caching delays file-change visibility.
+ * Healthcare HA deployments require sub-second event propagation. Redis pub/sub
+ * delivers sub-millisecond cross-pod latency.
+ *
+ * Usage:
+ *   REDIS_EVENT_BUS_ENABLED=true   -- activates this transport (default: false)
+ *   REDIS_URL=redis://...          -- full connection string (required when enabled)
+ *
+ * When REDIS_EVENT_BUS_ENABLED is false (the default), this module is never
+ * instantiated and the file-based EventBus remains the only transport. The two
+ * implementations are additive, not exclusive.
+ *
+ * Architecture notes:
+ *   - One Redis channel per EventType (e.g. "aiag:events:handoff:created").
+ *     This scales well: subscribers only receive the event types they care about,
+ *     avoiding per-subscriber envelope filtering overhead.
+ *   - A wildcard '*' subscriber additionally subscribes to the catch-all channel
+ *     "aiag:events:*" via Redis PSUBSCRIBE.
+ *   - Disconnect: auto-reconnect with exponential backoff (100ms .. 30s).
+ *     During disconnect a local warning is logged; events are NOT spooled to file
+ *     (enhancement deferred per Wave B scope).
+ *   - The file-based EventBus is NOT replaced. Run both in parallel or choose
+ *     one per deployment via env var.
+ *
+ * @connexum/ai-governance  Wave-B
+ */
+import type { EventType, EventHandler } from './event-bus';
+export declare function isRedisEventBusEnabled(): boolean;
+export interface RedisEventBusConfig {
+    /** Redis connection string. Reads REDIS_URL env var when not provided. */
+    redisUrl?: string;
+    /** Agent name for source tagging on emitted events. */
+    agentName: string;
+    /**
+     * Maximum reconnect delay in ms. Default: 30_000 (30 s).
+     * Backoff doubles from 100ms up to this cap.
+     */
+    maxReconnectDelayMs?: number;
+}
+export declare class RedisEventBus {
+    private readonly agentName;
+    private readonly redisUrl;
+    private readonly maxReconnectDelayMs;
+    /** Type-specific handlers (mirrors EventBus.handlers) */
+    private handlers;
+    /** Publisher client -- used for PUBLISH */
+    private pubClient;
+    /** Subscriber client -- used for SUBSCRIBE / PSUBSCRIBE */
+    private subClient;
+    private started;
+    private stopped;
+    /** The set of EventTypes that have registered handlers (for selective subscription) */
+    private subscribedTypes;
+    private wildcardSubscribed;
+    constructor(config: RedisEventBusConfig);
+    /**
+     * Subscribe to an event type (or '*' for all events).
+     * Handlers registered before start() are effective immediately after start().
+     * Handlers registered after start() cause a live SUBSCRIBE on the sub client.
+     */
+    on(type: EventType | '*', handler: EventHandler): void;
+    /**
+     * Emit an event -- publishes to the appropriate Redis channel.
+     * Also dispatches locally to any local handlers registered on this instance
+     * (same pod semantics).
+     */
+    emit(type: EventType, data: Record<string, unknown>, target?: string): void;
+    /**
+     * Start the Redis pub/sub transport.
+     * Creates publisher + subscriber clients, subscribes to all registered types.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the Redis pub/sub transport.
+     * Disconnects both pub and sub clients.
+     */
+    stop(): Promise<void>;
+    /**
+     * Create an ioredis client with auto-reconnect backoff.
+     * `role` is 'pub' or 'sub' -- used only for log labelling.
+     */
+    private makeClient;
+    /**
+     * Subscribe the sub client to the channel for a given EventType (or wildcard).
+     * Idempotent: no-ops if already subscribed.
+     */
+    private subscribeToType;
+    /**
+     * Handle an incoming Redis message from either SUBSCRIBE or PSUBSCRIBE.
+     * Skips events sourced from this agent (already dispatched locally in emit()).
+     */
+    private handleIncoming;
+    /**
+     * Dispatch an event to all registered handlers for its type and wildcard handlers.
+     */
+    private dispatch;
+}
+//# sourceMappingURL=redis-event-bus.d.ts.map

package/dist/audit/redis-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-event-bus.d.ts","sourceRoot":"","sources":["../../src/audit/redis-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAgB,YAAY,EAAE,MAAM,aAAa,CAAC;AAMzE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAsBD,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAmD;IAEnE,2CAA2C;IAC3C,OAAO,CAAC,SAAS,CAAwC;IACzD,2DAA2D;IAC3D,OAAO,CAAC,SAAS,CAAwC;IAEzD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IAExB,uFAAuF;IACvF,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,MAAM,EAAE,mBAAmB;IAUvC;;;;OAIG;IACH,EAAE,CAAC,IAAI,EAAE,SAAS,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAWtD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAwB3E;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B5B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAoClB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAsBtB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAmBjB"}