@sovr/sql-proxy 0.0.2 → 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import { EventEmitter } from 'node:events';
+import { EvalResult, PolicyEngine } from '@sovr/engine';
+export { Channel, EvalRequest, EvalResult, PolicyRule, RiskLevel, SqlContext, Verdict } from '@sovr/engine';
+
+/**
+ * @sovr/proxy-sql v2.0.0 — SQL Proxy with Full Billing System
+ *
+ * A transparent SQL proxy that sits between AI agents and databases,
+ * intercepting all SQL statements and routing them through the SOVR
+ * Policy Engine before execution.
+ *
+ * Features:
+ * 1. PostgreSQL wire protocol interception (frontend ↔ proxy ↔ backend)
+ * 2. Statement-level parsing and classification (17 statement types)
+ * 3. DDL blocking (DROP, ALTER, TRUNCATE)
+ * 4. High-risk DML detection (DELETE/UPDATE without WHERE)
+ * 5. SQL injection detection (UNION injection, tautology, comment injection, stacked queries)
+ * 6. Table whitelist/blacklist access control
+ * 7. Billing Reporter — 7 event types, batch flush, quota check, overage degradation
+ * 8. Mandatory API Key enforcement
+ * 9. Full audit logging of all intercepted queries
+ *
+ * Architecture:
+ *   Agent → SQL Proxy (port 5433) → SOVR Policy Engine → PostgreSQL (port 5432)
+ *   Billing: Every gate-check/block/allow → billingBuffer → batch POST → /api/v1/metering/batch
+ *
+ * @example
+ * ```ts
+ * import { SqlProxy } from '@sovr/proxy-sql';
+ * import { PolicyEngine, DEFAULT_RULES } from '@sovr/engine';
+ *
+ * const engine = new PolicyEngine({ rules: DEFAULT_RULES });
+ * const proxy = new SqlProxy({
+ *   engine,
+ *   apiKey: process.env.SOVR_API_KEY!,
+ *   listenPort: 5433,
+ *   targetHost: 'localhost',
+ *   targetPort: 5432,
+ *   tableWhitelist: ['public.orders', 'public.products'],
+ *   billing: { enabled: true },
+ * });
+ *
+ * await proxy.start();
+ * // Agent connects to localhost:5433 instead of 5432
+ * // All DDL and dangerous DML are intercepted and billed
+ * ```
+ */
+
+/**
+ * SOVR Billing Event Types — aligned with the pricing model:
+ * 1. gate.check — low price or included in quota (every policy evaluation)
+ * 2. gate.block — usually free or very low price (blocked requests)
+ * 3. irreversible.allowed — HIGH PRICE core tax base (allowed irreversible ops)
+ * 4. trust_bundle.issued — medium-high price (Trust Bundle generation)
+ * 5. trust_bundle.exported — higher price (audit necessity)
+ * 6. replay.requested — optional, per-use or monthly (trace replay)
+ * 7. auditor.session — enterprise billing (external audit sessions)
+ */
+type BillingEventType = 'gate.check' | 'gate.block' | 'irreversible.allowed' | 'trust_bundle.issued' | 'trust_bundle.exported' | 'replay.requested' | 'auditor.session';
+interface BillingEvent {
+    event_type: BillingEventType;
+    action: string;
+    resource: string;
+    verdict: string;
+    api_key: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+interface BillingConfig {
+    /** Enable billing event reporting (default: true) */
+    enabled?: boolean;
+    /** Metering endpoint URL (default: SOVR cloud) */
+    meteringEndpoint?: string;
+    /** Batch flush interval in milliseconds (default: 10000) */
+    flushIntervalMs?: number;
+    /** Maximum events in buffer before auto-flush (default: 500) */
+    bufferMax?: number;
+}
+interface SqlInjectionResult {
+    detected: boolean;
+    patterns: string[];
+    severity: 'none' | 'high' | 'critical';
+}
+interface SqlProxyConfig {
+    /** Policy engine instance */
+    engine: PolicyEngine;
+    /** SOVR API Key (REQUIRED — register at https://sovr.inc/register) */
+    apiKey?: string;
+    /** Port to listen on */
+    listenPort: number;
+    /** Target database host */
+    targetHost: string;
+    /** Target database port */
+    targetPort: number;
+    /** Listen host (default: 127.0.0.1) */
+    listenHost?: string;
+    /** Actor ID for audit trail */
+    actorId?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Callback when a query is blocked */
+    onBlocked?: (info: BlockedQueryInfo) => void | Promise<void>;
+    /** Callback for all evaluated queries */
+    onEvaluated?: (info: EvaluatedQueryInfo) => void | Promise<void>;
+    /** v2.0: Billing configuration */
+    billing?: BillingConfig;
+    /** v2.0: Table whitelist — only these tables are accessible (if set) */
+    tableWhitelist?: string[];
+    /** v2.0: Table blacklist — these tables are always blocked */
+    tableBlacklist?: string[];
+    /** v2.0: Enable SQL injection detection (default: true) */
+    sqlInjectionDetection?: boolean;
+}
+interface BlockedQueryInfo {
+    sql: string;
+    statementType: StatementType;
+    tables: string[];
+    decision: EvalResult;
+    timestamp: number;
+    /** v2.0: SQL injection detection result */
+    injectionResult?: SqlInjectionResult;
+}
+interface EvaluatedQueryInfo {
+    sql: string;
+    statementType: StatementType;
+    tables: string[];
+    decision: EvalResult;
+    timestamp: number;
+    /** v2.0: SQL injection detection result */
+    injectionResult?: SqlInjectionResult;
+}
+interface SqlProxyStats {
+    totalQueries: number;
+    allowedQueries: number;
+    blockedQueries: number;
+    escalatedQueries: number;
+    activeConnections: number;
+    startedAt: number;
+    /** v2.0: SQL injection blocks */
+    injectionBlocks: number;
+    /** v2.0: Table ACL blocks */
+    tableAclBlocks: number;
+    /** v2.0: Billing stats */
+    billingEventsReported: number;
+    billingEventsDropped: number;
+    billingBufferSize: number;
+    /** v2.0: Per-event-type counters */
+    billingByType: Record<BillingEventType, number>;
+}
+type StatementType = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'DROP' | 'ALTER' | 'TRUNCATE' | 'CREATE' | 'GRANT' | 'REVOKE' | 'BEGIN' | 'COMMIT' | 'ROLLBACK' | 'SET' | 'SHOW' | 'EXPLAIN' | 'COPY' | 'OTHER';
+/** Parsed SQL statement info */
+interface ParsedStatement {
+    type: StatementType;
+    tables: string[];
+    hasWhereClause: boolean;
+    isMultiStatement: boolean;
+    raw: string;
+}
+/**
+ * Lightweight SQL statement parser.
+ * Not a full SQL parser — classifies statements and extracts key metadata
+ * for policy evaluation without heavy dependencies.
+ */
+declare function parseSQL(sql: string): ParsedStatement;
+/**
+ * Detect SQL injection patterns in a raw SQL string.
+ * Returns detection result with matched pattern names and severity.
+ */
+declare function detectSqlInjection(sql: string): SqlInjectionResult;
+declare class SqlProxy extends EventEmitter {
+    private readonly engine;
+    private readonly apiKey;
+    private readonly listenPort;
+    private readonly listenHost;
+    private readonly targetHost;
+    private readonly targetPort;
+    private readonly actorId;
+    private readonly verbose;
+    private readonly onBlocked?;
+    private readonly onEvaluated?;
+    private server;
+    private readonly tableWhitelist;
+    private readonly tableBlacklist;
+    private readonly sqlInjectionDetection;
+    private billingEnabled;
+    private billingEndpoint;
+    private billingBuffer;
+    private billingFlushTimer;
+    private readonly BILLING_FLUSH_INTERVAL;
+    private readonly BILLING_BUFFER_MAX;
+    private stats;
+    constructor(config: SqlProxyConfig);
+    /**
+     * Start the SQL proxy server + billing reporter.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the SQL proxy server + flush remaining billing events.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get proxy statistics (including billing stats).
+     */
+    getStats(): SqlProxyStats;
+    private initBillingReporter;
+    /**
+     * Record a billing event into the buffer.
+     * Fire-and-forget — never blocks the main request flow.
+     */
+    recordBillingEvent(event_type: BillingEventType, action: string, resource: string, verdict: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Flush billing buffer to the metering endpoint.
+     * Batch POST — fire-and-forget with re-queue on failure.
+     */
+    private flushBillingBuffer;
+    /**
+     * Classify a gate-check result into the appropriate billing event type.
+     * Key pricing principle: "放行的不可逆动作" is the highest-price tax base.
+     */
+    private classifyBillingEvent;
+    /**
+     * Record billing event from a policy engine evaluation result.
+     * Automatically classifies the event type based on statement type + verdict.
+     */
+    private recordGateCheckBilling;
+    /**
+     * Check if the queried tables pass the ACL check.
+     * Returns null if allowed, or a reason string if blocked.
+     */
+    private checkTableAcl;
+    private handleConnection;
+    private processClientData;
+    private evaluateStatement;
+    private log;
+    /** v2.0: Async version check */
+    private _checkVersion;
+}
+
+export { type BillingConfig, type BillingEvent, type BillingEventType, type BlockedQueryInfo, type EvaluatedQueryInfo, type ParsedStatement, type SqlInjectionResult, SqlProxy, type SqlProxyConfig, type SqlProxyStats, type StatementType, detectSqlInjection, parseSQL };