sovr-mcp-proxy 7.0.0 → 7.2.0

package/dist/auditDashboard.d.mts

@@ -0,0 +1,208 @@
+/**
+ * SOVR Audit Dashboard — Structured Audit Logs, Statistics, and Export
+ *
+ * P2-1: Provides the "Trust Vault" backend for audit evidence.
+ *
+ * Features:
+ *   - Structured audit event storage (in-memory + file persistence)
+ *   - Real-time statistics aggregation (call volume, success rate, latency)
+ *   - Time-series trend analysis (hourly/daily/weekly)
+ *   - CSV and JSON export for offline analysis
+ *   - Risk distribution tracking
+ *   - Top-N analysis (most blocked tools, most active policies)
+ *   - Session-based grouping
+ *   - Quota usage tracking with prediction
+ */
+interface AuditEntry {
+    /** Unique entry ID */
+    id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Unix timestamp (ms) for sorting */
+    epochMs: number;
+    /** Event type */
+    type: AuditEventType;
+    /** Tool name */
+    toolName: string;
+    /** Sanitized arguments (secrets redacted) */
+    arguments: Record<string, unknown>;
+    /** Decision made */
+    decision: 'allow' | 'block' | 'transform' | 'require-approval' | 'rate-limited' | 'error';
+    /** Risk score (0-100) */
+    riskScore: number;
+    /** Risk level */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Policy that triggered the decision */
+    policyId?: string;
+    /** Reason for decision */
+    reason: string;
+    /** Duration of processing (ms) */
+    durationMs: number;
+    /** Session ID (groups related calls) */
+    sessionId?: string;
+    /** User/agent identifier */
+    agentId?: string;
+    /** Error message if any */
+    error?: string;
+    /** Upstream result summary */
+    resultSummary?: string;
+}
+type AuditEventType = 'tool_call' | 'policy_match' | 'approval_request' | 'approval_granted' | 'approval_denied' | 'rate_limit' | 'error' | 'config_change' | 'session_start' | 'session_end';
+interface DashboardStats {
+    /** Time range of data */
+    timeRange: {
+        from: string;
+        to: string;
+    };
+    /** Total events */
+    totalEvents: number;
+    /** Events by decision */
+    byDecision: Record<string, number>;
+    /** Events by risk level */
+    byRiskLevel: Record<string, number>;
+    /** Events by tool */
+    byTool: Record<string, number>;
+    /** Events by type */
+    byType: Record<string, number>;
+    /** Success rate (allowed / total) */
+    successRate: number;
+    /** Average latency (ms) */
+    avgLatencyMs: number;
+    /** P95 latency (ms) */
+    p95LatencyMs: number;
+    /** P99 latency (ms) */
+    p99LatencyMs: number;
+    /** Events per minute (current rate) */
+    eventsPerMinute: number;
+    /** Top blocked tools */
+    topBlocked: Array<{
+        tool: string;
+        count: number;
+    }>;
+    /** Top triggered policies */
+    topPolicies: Array<{
+        policyId: string;
+        count: number;
+    }>;
+    /** Risk score distribution (histogram) */
+    riskHistogram: Array<{
+        range: string;
+        count: number;
+    }>;
+}
+interface TrendPoint {
+    /** Time bucket label */
+    label: string;
+    /** Unix timestamp of bucket start */
+    epochMs: number;
+    /** Total events in bucket */
+    total: number;
+    /** Allowed events */
+    allowed: number;
+    /** Blocked events */
+    blocked: number;
+    /** Average risk score */
+    avgRisk: number;
+    /** Average latency */
+    avgLatency: number;
+}
+interface QuotaStatus {
+    /** Current period usage */
+    used: number;
+    /** Period limit */
+    limit: number;
+    /** Usage percentage */
+    percentage: number;
+    /** Predicted exhaustion date (ISO) */
+    predictedExhaustion?: string;
+    /** Daily average usage */
+    dailyAverage: number;
+    /** Days remaining at current rate */
+    daysRemaining?: number;
+}
+interface AuditDashboardConfig {
+    /** Maximum entries to keep in memory */
+    maxEntries: number;
+    /** File path for persistent storage (optional) */
+    persistPath?: string;
+    /** Auto-save interval (ms) */
+    autoSaveInterval: number;
+    /** Quota limit per period */
+    quotaLimit: number;
+    /** Quota period (ms) */
+    quotaPeriod: number;
+    /** Redact patterns for sensitive data */
+    redactPatterns: RegExp[];
+}
+declare class AuditDashboard {
+    private entries;
+    private config;
+    private saveTimer;
+    private quotaCounter;
+    private quotaPeriodStart;
+    constructor(config?: Partial<AuditDashboardConfig>);
+    /** Record a new audit entry */
+    record(entry: Omit<AuditEntry, 'id' | 'timestamp' | 'epochMs'>): AuditEntry;
+    /** Get entries with optional filters */
+    query(filters?: {
+        from?: number;
+        to?: number;
+        toolName?: string;
+        decision?: string;
+        riskLevel?: string;
+        sessionId?: string;
+        agentId?: string;
+        limit?: number;
+        offset?: number;
+    }): {
+        entries: AuditEntry[];
+        total: number;
+    };
+    /** Get a single entry by ID */
+    getById(id: string): AuditEntry | undefined;
+    /** Get dashboard statistics for a time range */
+    getStats(from?: number, to?: number): DashboardStats;
+    /** Get time-series trend data */
+    getTrends(granularity?: 'hourly' | 'daily' | 'weekly', from?: number, to?: number): TrendPoint[];
+    /** Get current quota status with prediction */
+    getQuotaStatus(): QuotaStatus;
+    /** Export audit log as CSV */
+    exportCSV(filters?: {
+        from?: number;
+        to?: number;
+    }): string;
+    /** Export audit log as JSON */
+    exportJSON(filters?: {
+        from?: number;
+        to?: number;
+    }): string;
+    /** Export Trust Bundle (evidence package) */
+    exportTrustBundle(sessionId?: string): {
+        bundleId: string;
+        exportedAt: string;
+        entries: AuditEntry[];
+        stats: DashboardStats;
+        integrity: string;
+    };
+    /** Start a new audit session */
+    startSession(agentId?: string): string;
+    /** End an audit session */
+    endSession(sessionId: string): void;
+    /** Get total entry count */
+    get size(): number;
+    /** Clear all entries */
+    clear(): void;
+    /** Destroy and cleanup */
+    destroy(): void;
+    private redactSensitive;
+    private formatBucketLabel;
+    private persist;
+}
+/** Create a dashboard with sensible defaults */
+declare function createAuditDashboard(overrides?: Partial<AuditDashboardConfig>): AuditDashboard;
+/** Create a dashboard for free tier (limited retention) */
+declare function createFreeTierDashboard(): AuditDashboard;
+/** Create a dashboard for pro tier */
+declare function createProDashboard(): AuditDashboard;
+
+export { AuditDashboard, type AuditDashboardConfig, type AuditEntry, type AuditEventType, type DashboardStats, type QuotaStatus, type TrendPoint, createAuditDashboard, createFreeTierDashboard, createProDashboard };

package/dist/auditDashboard.d.ts

@@ -0,0 +1,208 @@
+/**
+ * SOVR Audit Dashboard — Structured Audit Logs, Statistics, and Export
+ *
+ * P2-1: Provides the "Trust Vault" backend for audit evidence.
+ *
+ * Features:
+ *   - Structured audit event storage (in-memory + file persistence)
+ *   - Real-time statistics aggregation (call volume, success rate, latency)
+ *   - Time-series trend analysis (hourly/daily/weekly)
+ *   - CSV and JSON export for offline analysis
+ *   - Risk distribution tracking
+ *   - Top-N analysis (most blocked tools, most active policies)
+ *   - Session-based grouping
+ *   - Quota usage tracking with prediction
+ */
+interface AuditEntry {
+    /** Unique entry ID */
+    id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Unix timestamp (ms) for sorting */
+    epochMs: number;
+    /** Event type */
+    type: AuditEventType;
+    /** Tool name */
+    toolName: string;
+    /** Sanitized arguments (secrets redacted) */
+    arguments: Record<string, unknown>;
+    /** Decision made */
+    decision: 'allow' | 'block' | 'transform' | 'require-approval' | 'rate-limited' | 'error';
+    /** Risk score (0-100) */
+    riskScore: number;
+    /** Risk level */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Policy that triggered the decision */
+    policyId?: string;
+    /** Reason for decision */
+    reason: string;
+    /** Duration of processing (ms) */
+    durationMs: number;
+    /** Session ID (groups related calls) */
+    sessionId?: string;
+    /** User/agent identifier */
+    agentId?: string;
+    /** Error message if any */
+    error?: string;
+    /** Upstream result summary */
+    resultSummary?: string;
+}
+type AuditEventType = 'tool_call' | 'policy_match' | 'approval_request' | 'approval_granted' | 'approval_denied' | 'rate_limit' | 'error' | 'config_change' | 'session_start' | 'session_end';
+interface DashboardStats {
+    /** Time range of data */
+    timeRange: {
+        from: string;
+        to: string;
+    };
+    /** Total events */
+    totalEvents: number;
+    /** Events by decision */
+    byDecision: Record<string, number>;
+    /** Events by risk level */
+    byRiskLevel: Record<string, number>;
+    /** Events by tool */
+    byTool: Record<string, number>;
+    /** Events by type */
+    byType: Record<string, number>;
+    /** Success rate (allowed / total) */
+    successRate: number;
+    /** Average latency (ms) */
+    avgLatencyMs: number;
+    /** P95 latency (ms) */
+    p95LatencyMs: number;
+    /** P99 latency (ms) */
+    p99LatencyMs: number;
+    /** Events per minute (current rate) */
+    eventsPerMinute: number;
+    /** Top blocked tools */
+    topBlocked: Array<{
+        tool: string;
+        count: number;
+    }>;
+    /** Top triggered policies */
+    topPolicies: Array<{
+        policyId: string;
+        count: number;
+    }>;
+    /** Risk score distribution (histogram) */
+    riskHistogram: Array<{
+        range: string;
+        count: number;
+    }>;
+}
+interface TrendPoint {
+    /** Time bucket label */
+    label: string;
+    /** Unix timestamp of bucket start */
+    epochMs: number;
+    /** Total events in bucket */
+    total: number;
+    /** Allowed events */
+    allowed: number;
+    /** Blocked events */
+    blocked: number;
+    /** Average risk score */
+    avgRisk: number;
+    /** Average latency */
+    avgLatency: number;
+}
+interface QuotaStatus {
+    /** Current period usage */
+    used: number;
+    /** Period limit */
+    limit: number;
+    /** Usage percentage */
+    percentage: number;
+    /** Predicted exhaustion date (ISO) */
+    predictedExhaustion?: string;
+    /** Daily average usage */
+    dailyAverage: number;
+    /** Days remaining at current rate */
+    daysRemaining?: number;
+}
+interface AuditDashboardConfig {
+    /** Maximum entries to keep in memory */
+    maxEntries: number;
+    /** File path for persistent storage (optional) */
+    persistPath?: string;
+    /** Auto-save interval (ms) */
+    autoSaveInterval: number;
+    /** Quota limit per period */
+    quotaLimit: number;
+    /** Quota period (ms) */
+    quotaPeriod: number;
+    /** Redact patterns for sensitive data */
+    redactPatterns: RegExp[];
+}
+declare class AuditDashboard {
+    private entries;
+    private config;
+    private saveTimer;
+    private quotaCounter;
+    private quotaPeriodStart;
+    constructor(config?: Partial<AuditDashboardConfig>);
+    /** Record a new audit entry */
+    record(entry: Omit<AuditEntry, 'id' | 'timestamp' | 'epochMs'>): AuditEntry;
+    /** Get entries with optional filters */
+    query(filters?: {
+        from?: number;
+        to?: number;
+        toolName?: string;
+        decision?: string;
+        riskLevel?: string;
+        sessionId?: string;
+        agentId?: string;
+        limit?: number;
+        offset?: number;
+    }): {
+        entries: AuditEntry[];
+        total: number;
+    };
+    /** Get a single entry by ID */
+    getById(id: string): AuditEntry | undefined;
+    /** Get dashboard statistics for a time range */
+    getStats(from?: number, to?: number): DashboardStats;
+    /** Get time-series trend data */
+    getTrends(granularity?: 'hourly' | 'daily' | 'weekly', from?: number, to?: number): TrendPoint[];
+    /** Get current quota status with prediction */
+    getQuotaStatus(): QuotaStatus;
+    /** Export audit log as CSV */
+    exportCSV(filters?: {
+        from?: number;
+        to?: number;
+    }): string;
+    /** Export audit log as JSON */
+    exportJSON(filters?: {
+        from?: number;
+        to?: number;
+    }): string;
+    /** Export Trust Bundle (evidence package) */
+    exportTrustBundle(sessionId?: string): {
+        bundleId: string;
+        exportedAt: string;
+        entries: AuditEntry[];
+        stats: DashboardStats;
+        integrity: string;
+    };
+    /** Start a new audit session */
+    startSession(agentId?: string): string;
+    /** End an audit session */
+    endSession(sessionId: string): void;
+    /** Get total entry count */
+    get size(): number;
+    /** Clear all entries */
+    clear(): void;
+    /** Destroy and cleanup */
+    destroy(): void;
+    private redactSensitive;
+    private formatBucketLabel;
+    private persist;
+}
+/** Create a dashboard with sensible defaults */
+declare function createAuditDashboard(overrides?: Partial<AuditDashboardConfig>): AuditDashboard;
+/** Create a dashboard for free tier (limited retention) */
+declare function createFreeTierDashboard(): AuditDashboard;
+/** Create a dashboard for pro tier */
+declare function createProDashboard(): AuditDashboard;
+
+export { AuditDashboard, type AuditDashboardConfig, type AuditEntry, type AuditEventType, type DashboardStats, type QuotaStatus, type TrendPoint, createAuditDashboard, createFreeTierDashboard, createProDashboard };