@dotsetlabs/tollgate 0.1.0

package/dist/audit/exporter.js

@@ -0,0 +1,366 @@
+/**
+ * Audit Export Module for Tollgate
+ *
+ * Exports audit records in various formats for compliance reporting,
+ * log aggregation, and SIEM integration.
+ *
+ * Supported formats:
+ * - JSON Lines (JSONL) - for log aggregation (Splunk, ELK, etc.)
+ * - CSV - for spreadsheet analysis
+ * - CEF (Common Event Format) - for SIEM systems
+ *
+ * @example
+ * ```typescript
+ * import { AuditExporter } from './exporter.js';
+ *
+ * const exporter = new AuditExporter(logger);
+ *
+ * // Export as JSON Lines
+ * const jsonl = exporter.exportJsonLines({ since: new Date('2024-01-01') });
+ *
+ * // Export as CSV
+ * const csv = exporter.exportCsv({ useRedacted: true });
+ *
+ * // Export as CEF for SIEM
+ * const cef = exporter.exportCef({ server: 'postgres' });
+ * ```
+ */
+/**
+ * CEF severity levels mapped from risk levels.
+ */
+const CEF_SEVERITY = {
+    safe: 0,
+    read: 1,
+    write: 4,
+    destructive: 7,
+    dangerous: 10,
+    // Default for policy decisions
+    allow: 1,
+    deny: 4,
+    prompt: 3,
+};
+/**
+ * Audit exporter for generating compliance reports.
+ */
+export class AuditExporter {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Exports audit records as JSON Lines (JSONL).
+     *
+     * Each line is a complete JSON object, suitable for log aggregation systems.
+     *
+     * @param options - Export options
+     * @returns JSONL string with one record per line
+     */
+    exportJsonLines(options = {}) {
+        const records = this.getRecords(options);
+        const lines = [];
+        for (const record of records) {
+            const exportRecord = this.formatRecordForExport(record, options.useRedacted ?? true);
+            lines.push(JSON.stringify(exportRecord));
+        }
+        if (options.includeSessionGrants) {
+            const grants = this.logger.getActiveSessionGrants(options.server);
+            for (const grant of grants) {
+                lines.push(JSON.stringify({
+                    type: 'session_grant',
+                    ...this.formatGrantForExport(grant),
+                }));
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Exports audit records as CSV.
+     *
+     * @param options - Export options
+     * @returns CSV string with headers
+     */
+    exportCsv(options = {}) {
+        const records = this.getRecords(options);
+        const useRedacted = options.useRedacted ?? true;
+        // CSV headers
+        const headers = [
+            'id',
+            'timestamp',
+            'server',
+            'tool',
+            'policy_decision',
+            'policy_rule',
+            'policy_reason',
+            'analyzer',
+            'risk_level',
+            'user_decision',
+            'result',
+            'error_message',
+            'duration_ms',
+            'session_grant_id',
+            'correlation_id',
+            'client_id',
+            'args',
+        ];
+        const lines = [headers.join(',')];
+        for (const record of records) {
+            const args = useRedacted && record.argsRedacted
+                ? record.argsRedacted
+                : JSON.stringify(record.args);
+            const row = [
+                this.escapeCsv(record.id),
+                this.escapeCsv(record.timestamp.toISOString()),
+                this.escapeCsv(record.server),
+                this.escapeCsv(record.tool),
+                this.escapeCsv(record.policyDecision),
+                this.escapeCsv(record.policyRule ?? ''),
+                this.escapeCsv(record.policyReason ?? ''),
+                this.escapeCsv(record.analyzer ?? ''),
+                this.escapeCsv(record.riskLevel ?? ''),
+                this.escapeCsv(record.userDecision ?? ''),
+                this.escapeCsv(record.result ?? ''),
+                this.escapeCsv(record.errorMessage ?? ''),
+                record.durationMs?.toString() ?? '',
+                this.escapeCsv(record.sessionGrantId ?? ''),
+                this.escapeCsv(record.correlationId ?? ''),
+                this.escapeCsv(record.clientId ?? ''),
+                this.escapeCsv(args),
+            ];
+            lines.push(row.join(','));
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Exports audit records in CEF (Common Event Format).
+     *
+     * CEF is widely supported by SIEM systems like Splunk, ArcSight, and QRadar.
+     *
+     * Format: CEF:Version|Device Vendor|Device Product|Device Version|Signature ID|Name|Severity|Extension
+     *
+     * @param options - Export options
+     * @returns CEF formatted string with one event per line
+     */
+    exportCef(options = {}) {
+        const records = this.getRecords(options);
+        const useRedacted = options.useRedacted ?? true;
+        const lines = [];
+        for (const record of records) {
+            const cef = this.formatCefEvent(record, useRedacted);
+            lines.push(cef);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Gets records based on export options.
+     */
+    getRecords(options) {
+        return this.logger.getRecentCalls({
+            limit: options.limit ?? 10000, // Default to a large number for exports
+            server: options.server,
+            since: options.since,
+            until: options.until,
+            riskLevel: options.riskLevel,
+            includeRedacted: options.useRedacted ?? true,
+        });
+    }
+    /**
+     * Formats an audit record for JSON export.
+     */
+    formatRecordForExport(record, useRedacted) {
+        return {
+            type: 'tool_call',
+            id: record.id,
+            timestamp: record.timestamp.toISOString(),
+            server: record.server,
+            tool: record.tool,
+            args: useRedacted && record.argsRedacted
+                ? JSON.parse(record.argsRedacted)
+                : record.args,
+            policy: {
+                decision: record.policyDecision,
+                rule: record.policyRule,
+                reason: record.policyReason,
+            },
+            analysis: record.analyzer ? {
+                analyzer: record.analyzer,
+                riskLevel: record.riskLevel,
+            } : undefined,
+            approval: record.userDecision ? {
+                decision: record.userDecision,
+                sessionGrantId: record.sessionGrantId,
+            } : undefined,
+            result: {
+                status: record.result,
+                error: record.errorMessage,
+                durationMs: record.durationMs,
+            },
+            context: {
+                correlationId: record.correlationId,
+                clientId: record.clientId,
+            },
+        };
+    }
+    /**
+     * Formats a session grant for JSON export.
+     */
+    formatGrantForExport(grant) {
+        return {
+            id: grant.id,
+            createdAt: grant.createdAt.toISOString(),
+            expiresAt: grant.expiresAt?.toISOString(),
+            server: grant.server,
+            scope: grant.scope,
+            scopeValue: grant.scopeValue,
+            tool: grant.tool,
+            grantedBy: grant.grantedBy,
+            originalRequestId: grant.originalRequestId,
+            usageCount: grant.usageCount,
+            revoked: grant.revokedAt ? {
+                at: grant.revokedAt.toISOString(),
+                by: grant.revokedBy,
+            } : undefined,
+        };
+    }
+    /**
+     * Formats a CEF event from an audit record.
+     *
+     * CEF format: CEF:0|Vendor|Product|Version|SignatureID|Name|Severity|Extension
+     */
+    formatCefEvent(record, useRedacted) {
+        const vendor = 'Tollgate';
+        const product = 'MCP-Security-Proxy';
+        const version = '1.0';
+        // Signature ID based on action
+        const signatureId = this.getCefSignatureId(record);
+        // Event name
+        const name = `${record.server}:${record.tool} ${record.policyDecision}`;
+        // Severity (0-10 scale)
+        const severity = this.getCefSeverity(record);
+        // CEF extension fields
+        const extensions = this.getCefExtensions(record, useRedacted);
+        // Escape special characters in CEF fields
+        const escapedName = this.escapeCef(name);
+        return `CEF:0|${vendor}|${product}|${version}|${signatureId}|${escapedName}|${severity}|${extensions}`;
+    }
+    /**
+     * Gets the CEF signature ID for a record.
+     */
+    getCefSignatureId(record) {
+        const base = record.policyDecision === 'allow' ? '100'
+            : record.policyDecision === 'deny' ? '200'
+                : '300';
+        const risk = record.riskLevel
+            ? { safe: '0', read: '1', write: '2', destructive: '3', dangerous: '4' }[record.riskLevel] ?? '9'
+            : '9';
+        return `${base}${risk}`;
+    }
+    /**
+     * Gets the CEF severity for a record.
+     */
+    getCefSeverity(record) {
+        // Use risk level if available, otherwise use policy decision
+        if (record.riskLevel) {
+            return CEF_SEVERITY[record.riskLevel] ?? 3;
+        }
+        return CEF_SEVERITY[record.policyDecision] ?? 3;
+    }
+    /**
+     * Gets CEF extension fields for a record.
+     */
+    getCefExtensions(record, useRedacted) {
+        const extensions = [];
+        // Standard CEF fields
+        extensions.push(`rt=${record.timestamp.getTime()}`); // Receipt Time
+        extensions.push(`src=${record.server}`); // Source
+        extensions.push(`act=${record.policyDecision}`); // Action
+        // Custom fields
+        extensions.push(`cs1=${this.escapeCefValue(record.tool)}`);
+        extensions.push(`cs1Label=Tool`);
+        if (record.policyRule) {
+            extensions.push(`cs2=${this.escapeCefValue(record.policyRule)}`);
+            extensions.push(`cs2Label=PolicyRule`);
+        }
+        if (record.riskLevel) {
+            extensions.push(`cs3=${record.riskLevel}`);
+            extensions.push(`cs3Label=RiskLevel`);
+        }
+        if (record.userDecision) {
+            extensions.push(`cs4=${record.userDecision}`);
+            extensions.push(`cs4Label=UserDecision`);
+        }
+        if (record.result) {
+            extensions.push(`outcome=${record.result === 'success' ? 'Success' : 'Failure'}`);
+        }
+        if (record.durationMs !== undefined) {
+            extensions.push(`cn1=${record.durationMs}`);
+            extensions.push(`cn1Label=DurationMs`);
+        }
+        if (record.correlationId) {
+            extensions.push(`externalId=${this.escapeCefValue(record.correlationId)}`);
+        }
+        // Add args (redacted if requested)
+        const args = useRedacted && record.argsRedacted
+            ? record.argsRedacted
+            : JSON.stringify(record.args);
+        extensions.push(`msg=${this.escapeCefValue(args)}`);
+        return extensions.join(' ');
+    }
+    /**
+     * Escapes a value for CSV format.
+     */
+    escapeCsv(value) {
+        if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+            return `"${value.replace(/"/g, '""')}"`;
+        }
+        return value;
+    }
+    /**
+     * Escapes a CEF header field (pipe and backslash).
+     */
+    escapeCef(value) {
+        return value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+    }
+    /**
+     * Escapes a CEF extension value (equals and newlines).
+     */
+    escapeCefValue(value) {
+        return value
+            .replace(/\\/g, '\\\\')
+            .replace(/=/g, '\\=')
+            .replace(/\n/g, '\\n')
+            .replace(/\r/g, '\\r');
+    }
+}
+/**
+ * Creates an exporter and exports records in the specified format.
+ *
+ * @param logger - The audit logger to export from
+ * @param format - The export format
+ * @param options - Export options
+ * @returns Formatted export string
+ */
+export function exportAuditRecords(logger, format, options = {}) {
+    const exporter = new AuditExporter(logger);
+    switch (format) {
+        case 'json': {
+            // Pretty-printed JSON array
+            const records = logger.getRecentCalls({
+                limit: options.limit ?? 10000,
+                server: options.server,
+                since: options.since,
+                until: options.until,
+                riskLevel: options.riskLevel,
+            });
+            return JSON.stringify(records, null, 2);
+        }
+        case 'jsonl':
+            return exporter.exportJsonLines(options);
+        case 'csv':
+            return exporter.exportCsv(options);
+        case 'cef':
+            return exporter.exportCef(options);
+        default:
+            throw new Error(`Unsupported export format: ${format}`);
+    }
+}
+//# sourceMappingURL=exporter.js.map

package/dist/audit/exporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.js","sourceRoot":"","sources":["../../src/audit/exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAyBH;;GAEG;AACH,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,EAAE;IACb,+BAA+B;IAC/B,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;CACV,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,aAAa;IACJ;IAApB,YAAoB,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAE3C;;;;;;;OAOG;IACH,eAAe,CAAC,UAAyB,EAAE;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;YACrF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;oBACxB,IAAI,EAAE,eAAe;oBACrB,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;iBACpC,CAAC,CAAC,CAAC;YACN,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,UAAyB,EAAE;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;QAEhD,cAAc;QACd,MAAM,OAAO,GAAG;YACd,IAAI;YACJ,WAAW;YACX,QAAQ;YACR,MAAM;YACN,iBAAiB;YACjB,aAAa;YACb,eAAe;YACf,UAAU;YACV,YAAY;YACZ,eAAe;YACf,QAAQ;YACR,eAAe;YACf,aAAa;YACb,kBAAkB;YAClB,gBAAgB;YAChB,WAAW;YACX,MAAM;SACP,CAAC;QAEF,MAAM,KAAK,GAAa,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAE5C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,WAAW,IAAI,MAAM,CAAC,YAAY;gBAC7C,CAAC,CAAC,MAAM,CAAC,YAAY;gBACrB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAEhC,MAAM,GAAG,GAAG;gBACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;gBAC9C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC7B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;gBAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc,CAAC;gBACrC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;gBACvC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;gBACzC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;gBACrC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;gBACtC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;gBACzC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;gBACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;gBACzC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;gBAC3C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;gBAC1C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;gBACrC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aACrB,CAAC;YAEF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,UAAyB,EAAE;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;QAChD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,UAAU,CAAC,OAAsB;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;YAChC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK,EAAE,wCAAwC;YACvE,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,eAAe,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;SAC7C,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,qBAAqB,CAC3B,MAAmB,EACnB,WAAoB;QAEpB,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE;YACzC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,WAAW,IAAI,MAAM,CAAC,YAAY;gBACtC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC;gBACjC,CAAC,CAAC,MAAM,CAAC,IAAI;YACf,MAAM,EAAE;gBACN,QAAQ,EAAE,MAAM,CAAC,cAAc;gBAC/B,IAAI,EAAE,MAAM,CAAC,UAAU;gBACvB,MAAM,EAAE,MAAM,CAAC,YAAY;aAC5B;YACD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC1B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAC,CAAC,SAAS;YACb,QAAQ,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;gBAC9B,QAAQ,EAAE,MAAM,CAAC,YAAY;gBAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;aACtC,CAAC,CAAC,CAAC,SAAS;YACb,MAAM,EAAE;gBACN,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,YAAY;gBAC1B,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B;YACD,OAAO,EAAE;gBACP,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,oBAAoB,CAAC,KAAyB;QACpD,OAAO;YACL,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;YACxC,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE;YACzC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;gBACzB,EAAE,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;gBACjC,EAAE,EAAE,KAAK,CAAC,SAAS;aACpB,CAAC,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,MAAmB,EAAE,WAAoB;QAC9D,MAAM,MAAM,GAAG,UAAU,CAAC;QAC1B,MAAM,OAAO,GAAG,oBAAoB,CAAC;QACrC,MAAM,OAAO,GAAG,KAAK,CAAC;QAEtB,+BAA+B;QAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAEnD,aAAa;QACb,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAExE,wBAAwB;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAE7C,uBAAuB;QACvB,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAE9D,0CAA0C;QAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAEzC,OAAO,SAAS,MAAM,IAAI,OAAO,IAAI,OAAO,IAAI,WAAW,IAAI,WAAW,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;IACzG,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,MAAmB;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK;YACpD,CAAC,CAAC,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK;gBAC1C,CAAC,CAAC,KAAK,CAAC;QAEV,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS;YAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG;YACjG,CAAC,CAAC,GAAG,CAAC;QAER,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,MAAmB;QACxC,6DAA6D;QAC7D,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,OAAO,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,YAAY,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,MAAmB,EAAE,WAAoB;QAChE,MAAM,UAAU,GAAa,EAAE,CAAC;QAEhC,sBAAsB;QACtB,UAAU,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe;QACpE,UAAU,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS;QAClD,UAAU,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS;QAE1D,gBAAgB;QAChB,UAAU,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3D,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAEjC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,UAAU,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACjE,UAAU,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,UAAU,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;YAC3C,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAED,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,UAAU,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,UAAU,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;YAC5C,UAAU,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;QAED,mCAAmC;QACnC,MAAM,IAAI,GAAG,WAAW,IAAI,MAAM,CAAC,YAAY;YAC7C,CAAC,CAAC,MAAM,CAAC,YAAY;YACrB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,UAAU,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpD,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,KAAa;QAC7B,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QAC1C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,KAAa;QAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,KAAa;QAClC,OAAO,KAAK;aACT,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;aACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;aACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;CACF;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAmB,EACnB,MAAoB,EACpB,UAAyB,EAAE;IAE3B,MAAM,QAAQ,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAE3C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,4BAA4B;YAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;gBACpC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;gBAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAE3C,KAAK,KAAK;YACR,OAAO,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC,KAAK,KAAK;YACR,OAAO,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC;YACE,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/dist/audit/logger.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Audit Logger for Tollgate
+ *
+ * Logs all tool invocations and session grants to SQLite database
+ * for compliance, debugging, and analytics.
+ *
+ * Features:
+ * - Schema versioning with automatic migrations
+ * - PII redaction for compliance (GDPR, SOC2)
+ * - Enhanced metadata for security analysis
+ */
+import { type AuditRecord, type SessionGrantRecord, type RiskLevel } from './schema.js';
+import type { ToolCallContext, PolicyDecision } from '../policy/types.js';
+import type { ApprovalResult } from '../approval/types.js';
+import type { SessionGrant } from '../session/types.js';
+import { type RedactionOptions } from './redaction.js';
+/**
+ * Options for the AuditLogger.
+ */
+export interface AuditLoggerOptions {
+    /** Path to the SQLite database file */
+    dbPath?: string;
+    /** Enable PII redaction (default: true) */
+    enableRedaction?: boolean;
+    /** PII redaction options */
+    redactionOptions?: RedactionOptions;
+    /**
+     * Store raw (unredacted) args in the database.
+     * WARNING: Setting this to true stores PII in the database, which may
+     * violate compliance requirements (GDPR, SOC2, HIPAA). Only enable for
+     * debugging in non-production environments.
+     * Default: false
+     */
+    storeRawArgs?: boolean;
+}
+/**
+ * AuditLogger records all tool calls and session grants to SQLite.
+ *
+ * Uses WAL mode for concurrent access and prepared statements for performance.
+ *
+ * @example
+ * ```typescript
+ * const logger = new AuditLogger();
+ *
+ * // Log a tool call attempt
+ * const id = logger.logAttempt(context, decision);
+ *
+ * // Later, log the result
+ * logger.logResult(id, 'approved', 'success', undefined, 150);
+ *
+ * // Log a session grant
+ * logger.logSessionGrant(grant);
+ * ```
+ */
+export declare class AuditLogger {
+    private db;
+    private insertToolCallStmt;
+    private updateToolCallStmt;
+    private insertSessionGrantStmt;
+    private updateSessionGrantUsageStmt;
+    private redactor;
+    private enableRedaction;
+    private storeRawArgs;
+    constructor(optionsOrPath?: string | AuditLoggerOptions);
+    /**
+     * Initializes the database schema with version tracking and migrations.
+     */
+    private initializeSchema;
+    /**
+     * Applies migration to version 2 (compliance fields).
+     */
+    private applyMigrationV2;
+    /**
+     * Logs a tool call attempt.
+     *
+     * @param context - The tool call context
+     * @param decision - The policy decision
+     * @param sessionGrantId - ID of session grant that authorized this call (if any)
+     * @param metadata - Additional metadata for the audit record
+     * @returns The generated audit record ID
+     */
+    logAttempt(context: ToolCallContext, decision: PolicyDecision, sessionGrantId?: string, metadata?: {
+        correlationId?: string;
+        clientId?: string;
+    }): string;
+    /**
+     * Updates a tool call record with the final result.
+     *
+     * @param id - The audit record ID from logAttempt
+     * @param userDecision - The user's approval decision (if prompted)
+     * @param result - Whether the tool call succeeded or failed
+     * @param errorMessage - Error message (if result is 'error')
+     * @param durationMs - Total duration of the tool call
+     */
+    logResult(id: string, userDecision: ApprovalResult | null, result: 'success' | 'error', errorMessage?: string, durationMs?: number): void;
+    /**
+     * Logs a new session grant.
+     *
+     * @param grant - The session grant to log
+     */
+    logSessionGrant(grant: SessionGrant): void;
+    /**
+     * Increments the usage count for a session grant.
+     *
+     * @param grantId - The session grant ID
+     */
+    logSessionGrantUsage(grantId: string): void;
+    /**
+     * Marks a session grant as revoked.
+     *
+     * @param grantId - The session grant ID
+     * @param revokedBy - Who revoked it (e.g., 'user', 'timeout', 'policy')
+     */
+    revokeSessionGrant(grantId: string, revokedBy: string): void;
+    /**
+     * Gets recent tool calls with optional filtering.
+     */
+    getRecentCalls(limitOrOptions?: number | {
+        limit?: number;
+        server?: string;
+        since?: Date;
+        until?: Date;
+        riskLevel?: RiskLevel;
+        includeRedacted?: boolean;
+    }): AuditRecord[];
+    /**
+     * Gets active session grants for a server.
+     *
+     * @param server - Server name to filter by (optional)
+     * @returns Array of active grants
+     */
+    getActiveSessionGrants(server?: string): SessionGrantRecord[];
+    /**
+     * Gets aggregate statistics for tool calls.
+     */
+    getStats(): {
+        total: number;
+        allowed: number;
+        denied: number;
+        prompted: number;
+        sessionAuthorized: number;
+    };
+    /**
+     * Gets session grant statistics.
+     */
+    getSessionStats(): {
+        totalGrants: number;
+        activeGrants: number;
+        expiredGrants: number;
+        revokedGrants: number;
+        totalUsage: number;
+    };
+    /** Closes the database connection. */
+    close(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/audit/logger.d.ts.map

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