monora-ai 2.0.0 → 2.1.3

package/dist/executiveSummary.js

@@ -38,40 +38,181 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAMEWORK_WEIGHTS = void 0;
+exports.getFrameworkWeights = getFrameworkWeights;
 exports.calculateComplianceScore = calculateComplianceScore;
 exports.generateExecutiveSummary = generateExecutiveSummary;
+exports.generateEvidenceMapping = generateEvidenceMapping;
 exports.writeExecutiveSummary = writeExecutiveSummary;
 const fs = __importStar(require("fs"));
+/**
+ * Default framework weights (balanced governance).
+ */
+const DEFAULT_WEIGHTS = {
+    policyViolation: 10,
+    maxPolicyPenalty: 50,
+    chainIntegrityFailed: 30,
+    chainIntegrityDisabled: 10,
+    signingEnabled: 10,
+    signingDisabled: 5,
+    walEnabled: 5,
+    walDisabled: 5,
+    unknownModel: 5,
+    maxUnknownPenalty: 15,
+    dataHandlingEnabled: 0,
+    dataHandlingDisabled: 0,
+    aiActEnabled: 0,
+};
+/**
+ * Framework-specific weight profiles.
+ */
+exports.FRAMEWORK_WEIGHTS = {
+    default: DEFAULT_WEIGHTS,
+    // SOC 2 - Emphasizes audit trails, integrity, and security controls
+    soc2: {
+        policyViolation: 12,
+        maxPolicyPenalty: 60,
+        chainIntegrityFailed: 40,
+        chainIntegrityDisabled: 15,
+        signingEnabled: 15,
+        signingDisabled: 10,
+        walEnabled: 10,
+        walDisabled: 5,
+        unknownModel: 5,
+        maxUnknownPenalty: 15,
+        dataHandlingEnabled: 5,
+        dataHandlingDisabled: 0,
+        aiActEnabled: 0,
+    },
+    // GDPR - Emphasizes data handling, PII protection, and consent
+    gdpr: {
+        policyViolation: 8,
+        maxPolicyPenalty: 40,
+        chainIntegrityFailed: 25,
+        chainIntegrityDisabled: 10,
+        signingEnabled: 5,
+        signingDisabled: 3,
+        walEnabled: 5,
+        walDisabled: 3,
+        unknownModel: 3,
+        maxUnknownPenalty: 10,
+        dataHandlingEnabled: 20,
+        dataHandlingDisabled: 15,
+        aiActEnabled: 10,
+    },
+    // HIPAA - Emphasizes encryption, access controls, and audit trails
+    hipaa: {
+        policyViolation: 15,
+        maxPolicyPenalty: 60,
+        chainIntegrityFailed: 35,
+        chainIntegrityDisabled: 15,
+        signingEnabled: 20,
+        signingDisabled: 15,
+        walEnabled: 10,
+        walDisabled: 5,
+        unknownModel: 8,
+        maxUnknownPenalty: 25,
+        dataHandlingEnabled: 15,
+        dataHandlingDisabled: 10,
+        aiActEnabled: 0,
+    },
+    // AI Act (EU) - Emphasizes transparency, human oversight, and documentation
+    ai_act: {
+        policyViolation: 10,
+        maxPolicyPenalty: 50,
+        chainIntegrityFailed: 30,
+        chainIntegrityDisabled: 15,
+        signingEnabled: 10,
+        signingDisabled: 5,
+        walEnabled: 5,
+        walDisabled: 3,
+        unknownModel: 10,
+        maxUnknownPenalty: 30,
+        dataHandlingEnabled: 10,
+        dataHandlingDisabled: 5,
+        aiActEnabled: 15,
+    },
+    // ISO 27001 - Emphasizes information security management
+    iso27001: {
+        policyViolation: 12,
+        maxPolicyPenalty: 55,
+        chainIntegrityFailed: 35,
+        chainIntegrityDisabled: 15,
+        signingEnabled: 15,
+        signingDisabled: 10,
+        walEnabled: 10,
+        walDisabled: 5,
+        unknownModel: 5,
+        maxUnknownPenalty: 15,
+        dataHandlingEnabled: 10,
+        dataHandlingDisabled: 5,
+        aiActEnabled: 0,
+    },
+    // PCI-DSS - Emphasizes payment data protection
+    pci_dss: {
+        policyViolation: 15,
+        maxPolicyPenalty: 60,
+        chainIntegrityFailed: 40,
+        chainIntegrityDisabled: 20,
+        signingEnabled: 20,
+        signingDisabled: 15,
+        walEnabled: 10,
+        walDisabled: 5,
+        unknownModel: 5,
+        maxUnknownPenalty: 15,
+        dataHandlingEnabled: 20,
+        dataHandlingDisabled: 15,
+        aiActEnabled: 0,
+    },
+};
+/**
+ * Get weights for a specific compliance framework.
+ */
+function getFrameworkWeights(framework) {
+    if (!framework) {
+        return DEFAULT_WEIGHTS;
+    }
+    const normalized = framework.toLowerCase().replace(/[- ]/g, '_');
+    return exports.FRAMEWORK_WEIGHTS[normalized] || DEFAULT_WEIGHTS;
+}
 /**
  * Calculate compliance score (0-100) based on governance controls.
  *
- * Scoring breakdown:
- * - Base score: 100
- * - Policy violations: -10 per violation (max -50)
- * - Chain integrity: -30 if failed, -10 if disabled
- * - Signing enabled: +10 bonus (if disabled: -5)
- * - WAL enabled: +5 bonus (if disabled: -5)
- * - Unknown models used: -5 per model (max -15)
+ * Scoring uses framework-specific weights when a compliance framework is specified.
+ * Supported frameworks: soc2, gdpr, hipaa, ai_act, iso27001, pci_dss
+ *
+ * @param report - The compliance report data
+ * @param chainStatus - Status of hash chain ('verified', 'failed', 'disabled')
+ * @param config - Monora configuration
+ * @param framework - Optional compliance framework for weighted scoring
  */
-function calculateComplianceScore(report, chainStatus, config) {
+function calculateComplianceScore(report, chainStatus, config, framework) {
+    const weights = getFrameworkWeights(framework);
     let score = 100;
     const breakdown = {};
+    const applyAdjustment = (key, intended) => {
+        if (intended === 0) {
+            return;
+        }
+        const headroom = 100 - score;
+        const floor = 0 - score;
+        const applied = intended > 0 ? Math.min(intended, headroom) : Math.max(intended, floor);
+        breakdown[key] = applied;
+        score += applied;
+    };
     // Policy violations
     const violations = report.violations || [];
     const violationCount = violations.length;
-    const violationPenalty = Math.min(violationCount * 10, 50);
+    const violationPenalty = Math.min(violationCount * weights.policyViolation, weights.maxPolicyPenalty);
     if (violationPenalty > 0) {
-        breakdown['policy_violations'] = -violationPenalty;
-        score -= violationPenalty;
+        applyAdjustment('policy_violations', -violationPenalty);
     }
     // Chain integrity
     if (chainStatus === 'failed') {
-        breakdown['chain_integrity_failed'] = -30;
-        score -= 30;
+        applyAdjustment('chain_integrity_failed', -weights.chainIntegrityFailed);
     }
     else if (chainStatus === 'disabled') {
-        breakdown['chain_integrity_disabled'] = -10;
-        score -= 10;
+        applyAdjustment('chain_integrity_disabled', -weights.chainIntegrityDisabled);
     }
     else {
         breakdown['chain_integrity_verified'] = 0;
@@ -79,30 +220,38 @@ function calculateComplianceScore(report, chainStatus, config) {
     // Signing
     const signing = config.signing || {};
     if (signing.enabled) {
-        breakdown['signing_enabled'] = 10;
-        score += 10;
+        applyAdjustment('signing_enabled', weights.signingEnabled);
     }
     else {
-        breakdown['signing_disabled'] = -5;
-        score -= 5;
+        applyAdjustment('signing_disabled', -weights.signingDisabled);
     }
     // WAL (crash resilience)
     const wal = config.wal || {};
     if (wal.enabled) {
-        breakdown['wal_enabled'] = 5;
-        score += 5;
+        applyAdjustment('wal_enabled', weights.walEnabled);
     }
     else {
-        breakdown['wal_disabled'] = -5;
-        score -= 5;
+        applyAdjustment('wal_disabled', -weights.walDisabled);
     }
     // Unknown models used
     const compliance = report.model_compliance || {};
     const unknownModels = compliance.unknown_models_used || [];
-    const unknownPenalty = Math.min(unknownModels.length * 5, 15);
+    const unknownPenalty = Math.min(unknownModels.length * weights.unknownModel, weights.maxUnknownPenalty);
     if (unknownPenalty > 0) {
-        breakdown['unknown_models'] = -unknownPenalty;
-        score -= unknownPenalty;
+        applyAdjustment('unknown_models', -unknownPenalty);
+    }
+    // Data handling (framework-specific bonus/penalty)
+    const dataHandling = config.data_handling || {};
+    if (dataHandling.enabled && weights.dataHandlingEnabled > 0) {
+        applyAdjustment('data_handling_enabled', weights.dataHandlingEnabled);
+    }
+    else if (!dataHandling.enabled && weights.dataHandlingDisabled > 0) {
+        applyAdjustment('data_handling_disabled', -weights.dataHandlingDisabled);
+    }
+    // AI Act compliance (framework-specific bonus)
+    const aiAct = config.ai_act || {};
+    if (aiAct.enabled && weights.aiActEnabled > 0) {
+        applyAdjustment('ai_act_enabled', weights.aiActEnabled);
     }
     // Clamp score to 0-100
     score = Math.max(0, Math.min(100, score));
@@ -128,6 +277,7 @@ function calculateComplianceScore(report, chainStatus, config) {
         grade,
         breakdown,
         max_score: 100,
+        framework: framework || 'default',
     };
 }
 /**
@@ -342,6 +492,9 @@ function generateExecutiveSummary(report, events, chainStatus, config, traceId)
         }
     }
     lines.push('');
+    // Evidence Mapping Section
+    const evidenceLines = generateEvidenceSection(events);
+    lines.push(...evidenceLines);
     // Footer
     lines.push('---');
     lines.push('');
@@ -349,6 +502,116 @@ function generateExecutiveSummary(report, events, chainStatus, config, traceId)
     lines.push('');
     return lines.join('\n');
 }
+/**
+ * Evidence mapping for compliance frameworks.
+ */
+const CONTROL_EVENT_MAPPING = {
+    soc2: [
+        { controlId: 'CC6.1', controlName: 'Logical Access Controls', eventTypes: ['llm_call', 'tool_call'] },
+        { controlId: 'CC7.2', controlName: 'System Monitoring', eventTypes: ['llm_call', 'tool_call', 'agent_step'] },
+        { controlId: 'CC8.1', controlName: 'Change Management', eventTypes: ['policy_violation'] },
+    ],
+    gdpr: [
+        { controlId: 'Art.5', controlName: 'Data Processing Principles', eventTypes: ['llm_call'] },
+        { controlId: 'Art.25', controlName: 'Data Protection by Design', eventTypes: ['llm_call', 'tool_call'] },
+        { controlId: 'Art.30', controlName: 'Records of Processing', eventTypes: ['llm_call', 'tool_call', 'agent_step'] },
+    ],
+    hipaa: [
+        { controlId: '164.312(b)', controlName: 'Audit Controls', eventTypes: ['llm_call', 'tool_call', 'agent_step'] },
+        { controlId: '164.312(c)', controlName: 'Integrity Controls', eventTypes: ['llm_call'] },
+        { controlId: '164.312(d)', controlName: 'Authentication', eventTypes: ['llm_call', 'tool_call'] },
+    ],
+    ai_act: [
+        { controlId: 'Art.13', controlName: 'Transparency & Disclosure', eventTypes: ['llm_call'] },
+        { controlId: 'Art.14', controlName: 'Human Oversight', eventTypes: ['agent_step', 'tool_call'] },
+        { controlId: 'Art.17', controlName: 'Quality Management', eventTypes: ['llm_call', 'policy_violation'] },
+    ],
+    iso27001: [
+        { controlId: 'A.12.4', controlName: 'Logging and Monitoring', eventTypes: ['llm_call', 'tool_call', 'agent_step'] },
+        { controlId: 'A.12.6', controlName: 'Technical Vulnerability Management', eventTypes: ['policy_violation'] },
+        { controlId: 'A.14.2', controlName: 'Security in Development', eventTypes: ['llm_call', 'tool_call'] },
+    ],
+    iso42001: [
+        { controlId: '6.1.2', controlName: 'AI Risk Assessment', eventTypes: ['llm_call', 'policy_violation'] },
+        { controlId: '8.4', controlName: 'AI System Development', eventTypes: ['llm_call', 'tool_call', 'agent_step'] },
+        { controlId: '9.1', controlName: 'Monitoring & Measurement', eventTypes: ['llm_call', 'tool_call'] },
+    ],
+};
+/**
+ * Generate evidence mapping for compliance controls.
+ */
+function generateEvidenceMapping(events, framework) {
+    const evidence = [];
+    // Count events by type
+    const eventsByType = {};
+    for (const event of events) {
+        const eventType = event.event_type || 'unknown';
+        if (!eventsByType[eventType]) {
+            eventsByType[eventType] = [];
+        }
+        eventsByType[eventType].push(event);
+    }
+    // Get frameworks to process
+    const frameworksToProcess = framework
+        ? [framework.toLowerCase().replace(/[- ]/g, '_')]
+        : Object.keys(CONTROL_EVENT_MAPPING);
+    for (const fw of frameworksToProcess) {
+        const controls = CONTROL_EVENT_MAPPING[fw];
+        if (!controls)
+            continue;
+        for (const control of controls) {
+            let totalCount = 0;
+            const sampleIds = [];
+            for (const eventType of control.eventTypes) {
+                const matchingEvents = eventsByType[eventType] || [];
+                totalCount += matchingEvents.length;
+                // Collect sample event IDs (up to 3 per control)
+                for (const evt of matchingEvents.slice(0, 3 - sampleIds.length)) {
+                    if (evt.event_id && sampleIds.length < 3) {
+                        sampleIds.push(evt.event_id);
+                    }
+                }
+            }
+            if (totalCount > 0) {
+                evidence.push({
+                    controlId: control.controlId,
+                    controlName: control.controlName,
+                    framework: fw.toUpperCase().replace(/_/g, ' '),
+                    eventTypes: control.eventTypes,
+                    eventCount: totalCount,
+                    sampleEventIds: sampleIds,
+                });
+            }
+        }
+    }
+    return evidence;
+}
+/**
+ * Generate evidence section for executive summary.
+ */
+function generateEvidenceSection(events, framework) {
+    const lines = [];
+    const evidence = generateEvidenceMapping(events, framework);
+    if (evidence.length === 0) {
+        return lines;
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push('## Compliance Evidence Mapping');
+    lines.push('');
+    lines.push('Events linked to specific compliance controls:');
+    lines.push('');
+    lines.push('| Framework | Control ID | Control Name | Events | Sample IDs |');
+    lines.push('|-----------|------------|--------------|--------|------------|');
+    for (const item of evidence) {
+        const sampleIds = item.sampleEventIds.length > 0
+            ? item.sampleEventIds.map(id => `\`${id.slice(0, 12)}...\``).join(', ')
+            : '-';
+        lines.push(`| ${item.framework} | ${item.controlId} | ${item.controlName} | ${item.eventCount} | ${sampleIds} |`);
+    }
+    lines.push('');
+    return lines;
+}
 /**
  * Write executive summary to a file.
  */

package/dist/identity.d.ts

@@ -0,0 +1,143 @@
+/**
+ * User/identity tracking for SOC 2 CC6 access control compliance.
+ *
+ * This module provides identity context management for tracking who invoked
+ * each AI call, supporting SOC 2 access control audit trails.
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical identity tracking APIs:
+ *   - setIdentity() / set_identity()
+ *   - getIdentity() / get_identity()
+ *   - clearIdentity() / clear_identity()
+ *   - withIdentity() / identity_context()
+ */
+import { MonoraConfig } from './config';
+/**
+ * Represents a user/system identity for audit tracking.
+ */
+export interface Identity {
+    /** Unique identifier for the user (required if identity.require_user_id is True). */
+    userId: string;
+    /** Optional session identifier for grouping related calls. */
+    sessionId?: string;
+    /** Authentication method used (oauth2, api_key, jwt, etc.). */
+    authMethod?: string;
+    /** List of roles assigned to the user. */
+    roles?: string[];
+    /** Organization identifier for multi-tenant systems. */
+    orgId?: string;
+    /** Additional custom identity metadata. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for converting identity to dict.
+ */
+export interface IdentityToDictOptions {
+    /** Include roles array in output. */
+    includeRoles?: boolean;
+    /** Include org_id in output. */
+    includeOrg?: boolean;
+    /** Hash user_id for privacy (SHA-256). */
+    redactUserId?: boolean;
+}
+/**
+ * Convert identity to dictionary for event inclusion.
+ *
+ * @param identity - The identity object.
+ * @param options - Conversion options.
+ * @returns Dictionary representation of identity.
+ */
+export declare function identityToDict(identity: Identity, options?: IdentityToDictOptions): Record<string, any>;
+/**
+ * Set the current identity context.
+ *
+ * All subsequent events will include this identity information until
+ * clearIdentity() is called or the context exits.
+ *
+ * Note: This sets identity in the current async context. For scoped identity,
+ * use withIdentity() instead.
+ *
+ * @param identity - The identity to set.
+ * @returns The identity object.
+ *
+ * @example
+ * ```typescript
+ * setIdentity({ userId: 'usr_123', sessionId: 'sess_456', roles: ['admin'] });
+ * // All subsequent AI calls will include identity
+ * await llmCall(...);
+ * ```
+ */
+export declare function setIdentity(identity: Identity): Identity;
+/**
+ * Get the current identity from context.
+ *
+ * @returns The current Identity object, or undefined if not set.
+ */
+export declare function getIdentity(): Identity | undefined;
+/**
+ * Clear the current identity context.
+ */
+export declare function clearIdentity(): void;
+/**
+ * Run a function within a specific identity context.
+ *
+ * The identity is automatically cleared when the function completes.
+ *
+ * @param identity - The identity to use.
+ * @param fn - The function to execute.
+ * @returns The result of the function.
+ *
+ * @example
+ * ```typescript
+ * await withIdentity({ userId: 'usr_789', roles: ['analyst'] }, async () => {
+ *   await llmCall(...);  // Includes identity
+ * });
+ * // Identity cleared after function completes
+ * ```
+ */
+export declare function withIdentity<T>(identity: Identity, fn: () => T): T;
+/**
+ * Async version of withIdentity for async functions.
+ *
+ * @param identity - The identity to use.
+ * @param fn - The async function to execute.
+ * @returns Promise resolving to the result of the function.
+ */
+export declare function withIdentityAsync<T>(identity: Identity, fn: () => Promise<T>): Promise<T>;
+/**
+ * Bind a function to the current identity context.
+ *
+ * The returned function, when called, will execute with the captured
+ * identity context regardless of where it's called from.
+ *
+ * @param fn - The function to bind to the current identity.
+ * @returns A wrapped function that will execute with the captured identity.
+ *
+ * @example
+ * ```typescript
+ * setIdentity({ userId: 'usr_123' });
+ * const boundCallback = bindIdentity(myCallback);
+ * // Call from anywhere - identity is preserved
+ * boundCallback();
+ * ```
+ */
+export declare function bindIdentity<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Get identity dict for event inclusion based on config.
+ *
+ * This is called internally when building events to include identity
+ * information according to the configuration settings.
+ *
+ * @param config - The Monora configuration.
+ * @returns Identity dict for event inclusion, or undefined if identity not set
+ *          or identity tracking is disabled.
+ */
+export declare function getIdentityForEvent(config: MonoraConfig): Record<string, any> | undefined;
+/**
+ * Validate that identity is set if required by config.
+ *
+ * @param config - The Monora configuration.
+ * @throws Error if require_user_id is true but no identity is set.
+ */
+export declare function validateIdentityRequirement(config: MonoraConfig): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgCrB;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAIxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,SAAS,CAElD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAElE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAQxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAgBjC;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAetE"}