@quint-security/core 0.1.2

package/src/db.ts

@@ -0,0 +1,184 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { AuditEntry } from "./types.js";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS audit_log (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp       TEXT NOT NULL,
+  server_name     TEXT NOT NULL,
+  direction       TEXT NOT NULL,
+  method          TEXT NOT NULL,
+  message_id      TEXT,
+  tool_name       TEXT,
+  arguments_json  TEXT,
+  response_json   TEXT,
+  verdict         TEXT NOT NULL,
+  risk_score      INTEGER,
+  risk_level      TEXT,
+  policy_hash     TEXT NOT NULL DEFAULT '',
+  prev_hash       TEXT NOT NULL DEFAULT '',
+  nonce           TEXT NOT NULL DEFAULT '',
+  signature       TEXT NOT NULL,
+  public_key      TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_timestamp   ON audit_log(timestamp);
+CREATE INDEX IF NOT EXISTS idx_server_name ON audit_log(server_name);
+CREATE INDEX IF NOT EXISTS idx_tool_name   ON audit_log(tool_name);
+CREATE INDEX IF NOT EXISTS idx_verdict     ON audit_log(verdict);
+`;
+
+// Migration: add columns if they don't exist (for DBs created before this version)
+const MIGRATIONS = [
+  `ALTER TABLE audit_log ADD COLUMN policy_hash TEXT NOT NULL DEFAULT ''`,
+  `ALTER TABLE audit_log ADD COLUMN prev_hash TEXT NOT NULL DEFAULT ''`,
+  `ALTER TABLE audit_log ADD COLUMN nonce TEXT NOT NULL DEFAULT ''`,
+  `ALTER TABLE audit_log ADD COLUMN risk_score INTEGER`,
+  `ALTER TABLE audit_log ADD COLUMN risk_level TEXT`,
+];
+
+export class AuditDb {
+  private db: Database.Database;
+
+  constructor(dbPath: string) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.exec(SCHEMA);
+    this.migrate();
+  }
+
+  private migrate(): void {
+    for (const sql of MIGRATIONS) {
+      try {
+        this.db.exec(sql);
+      } catch {
+        // Column already exists — ignore
+      }
+    }
+  }
+
+  /** Get the signature of the last entry (for hash chaining) */
+  getLastSignature(): string | null {
+    const row = this.db.prepare(
+      "SELECT signature FROM audit_log ORDER BY id DESC LIMIT 1"
+    ).get() as { signature: string } | undefined;
+    return row?.signature ?? null;
+  }
+
+  /**
+   * Atomically read the last signature and insert a new entry.
+   * This prevents chain breaks when multiple proxy instances share a DB.
+   */
+  insertAtomic(buildEntry: (prevSignature: string | null) => Omit<AuditEntry, "id">): number {
+    const insertStmt = this.db.prepare(`
+      INSERT INTO audit_log
+        (timestamp, server_name, direction, method, message_id, tool_name,
+         arguments_json, response_json, verdict, risk_score, risk_level,
+         policy_hash, prev_hash, nonce, signature, public_key)
+      VALUES
+        (@timestamp, @server_name, @direction, @method, @message_id, @tool_name,
+         @arguments_json, @response_json, @verdict, @risk_score, @risk_level,
+         @policy_hash, @prev_hash, @nonce, @signature, @public_key)
+    `);
+    const lastSigStmt = this.db.prepare(
+      "SELECT signature FROM audit_log ORDER BY id DESC LIMIT 1"
+    );
+
+    let rowId = 0;
+    this.db.transaction(() => {
+      const lastRow = lastSigStmt.get() as { signature: string } | undefined;
+      const entry = buildEntry(lastRow?.signature ?? null);
+      const result = insertStmt.run(entry);
+      rowId = result.lastInsertRowid as number;
+    })();
+    return rowId;
+  }
+
+  insert(entry: Omit<AuditEntry, "id">): number {
+    const stmt = this.db.prepare(`
+      INSERT INTO audit_log
+        (timestamp, server_name, direction, method, message_id, tool_name,
+         arguments_json, response_json, verdict, risk_score, risk_level,
+         policy_hash, prev_hash, nonce, signature, public_key)
+      VALUES
+        (@timestamp, @server_name, @direction, @method, @message_id, @tool_name,
+         @arguments_json, @response_json, @verdict, @risk_score, @risk_level,
+         @policy_hash, @prev_hash, @nonce, @signature, @public_key)
+    `);
+    const result = stmt.run(entry);
+    return result.lastInsertRowid as number;
+  }
+
+  getById(id: number): AuditEntry | undefined {
+    return this.db.prepare("SELECT * FROM audit_log WHERE id = ?").get(id) as AuditEntry | undefined;
+  }
+
+  /** Get entries in ID order (ascending) for chain verification */
+  getRange(startId: number, endId: number): AuditEntry[] {
+    return this.db.prepare(
+      "SELECT * FROM audit_log WHERE id >= ? AND id <= ? ORDER BY id ASC"
+    ).all(startId, endId) as AuditEntry[];
+  }
+
+  /** Get all entries in ID order (ascending) for chain verification */
+  getAll(): AuditEntry[] {
+    return this.db.prepare("SELECT * FROM audit_log ORDER BY id ASC").all() as AuditEntry[];
+  }
+
+  query(opts: {
+    server?: string;
+    tool?: string;
+    verdict?: string;
+    since?: string;
+    limit?: number;
+  } = {}): AuditEntry[] {
+    const conditions: string[] = [];
+    const params: Record<string, unknown> = {};
+
+    if (opts.server) {
+      conditions.push("server_name = @server");
+      params.server = opts.server;
+    }
+    if (opts.tool) {
+      conditions.push("tool_name = @tool");
+      params.tool = opts.tool;
+    }
+    if (opts.verdict) {
+      conditions.push("verdict = @verdict");
+      params.verdict = opts.verdict;
+    }
+    if (opts.since) {
+      conditions.push("timestamp >= @since");
+      params.since = opts.since;
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = opts.limit ?? 100;
+
+    return this.db.prepare(
+      `SELECT * FROM audit_log ${where} ORDER BY id DESC LIMIT ${limit}`
+    ).all(params) as AuditEntry[];
+  }
+
+  getLast(n: number): AuditEntry[] {
+    return this.db.prepare(
+      "SELECT * FROM audit_log ORDER BY id DESC LIMIT ?"
+    ).all(n) as AuditEntry[];
+  }
+
+  count(): number {
+    const row = this.db.prepare("SELECT COUNT(*) as cnt FROM audit_log").get() as { cnt: number };
+    return row.cnt;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+export function openAuditDb(dataDir: string): AuditDb {
+  return new AuditDb(join(dataDir, "quint.db"));
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./crypto.js";
+export * from "./db.js";
+export * from "./auth-db.js";
+export * from "./auth.js";
+export * from "./config.js";
+export * from "./log.js";
+export * from "./risk.js";

package/src/log.ts

@@ -0,0 +1,32 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+type Level = keyof typeof LEVELS;
+
+let currentLevel: Level = "info";
+
+export function setLogLevel(level: Level): void {
+  currentLevel = level;
+}
+
+export function getLogLevel(): Level {
+  return currentLevel;
+}
+
+function shouldLog(level: Level): boolean {
+  return LEVELS[level] >= LEVELS[currentLevel];
+}
+
+export function logDebug(msg: string): void {
+  if (shouldLog("debug")) process.stderr.write(`quint [debug]: ${msg}\n`);
+}
+
+export function logInfo(msg: string): void {
+  if (shouldLog("info")) process.stderr.write(`quint: ${msg}\n`);
+}
+
+export function logWarn(msg: string): void {
+  if (shouldLog("warn")) process.stderr.write(`quint [warn]: ${msg}\n`);
+}
+
+export function logError(msg: string): void {
+  if (shouldLog("error")) process.stderr.write(`quint [error]: ${msg}\n`);
+}

package/src/risk.ts

@@ -0,0 +1,228 @@
+/**
+ * Risk scoring engine.
+ *
+ * Each intercepted action gets a risk score from 0–100.
+ * The score is based on:
+ *   1. The method being called (tools/call is riskier than tools/list)
+ *   2. The tool name (some tools are inherently more dangerous)
+ *   3. The arguments (e.g. destructive keywords like "delete", "drop", "rm")
+ *   4. Accumulated behavior (repeated high-risk attempts escalate)
+ *
+ * If the score exceeds a threshold, the action can be:
+ *   - Flagged for manual approval
+ *   - Auto-denied
+ *   - Trigger session/token revocation
+ */
+
+// ── Built-in risk patterns ──────────────────────────────────────
+
+interface RiskPattern {
+  /** Glob pattern for tool name */
+  tool: string;
+  /** Base risk score for this tool (0-100) */
+  baseScore: number;
+}
+
+const DEFAULT_TOOL_RISKS: RiskPattern[] = [
+  // Destructive file operations
+  { tool: "Delete*",       baseScore: 80 },
+  { tool: "Remove*",       baseScore: 80 },
+  { tool: "Rm*",           baseScore: 80 },
+  // Write operations
+  { tool: "Write*",        baseScore: 50 },
+  { tool: "Create*",       baseScore: 40 },
+  { tool: "Update*",       baseScore: 45 },
+  { tool: "Edit*",         baseScore: 45 },
+  // Database operations
+  { tool: "*Sql*",         baseScore: 60 },
+  { tool: "*Query*",       baseScore: 40 },
+  { tool: "*Database*",    baseScore: 55 },
+  // Execution
+  { tool: "*Execute*",     baseScore: 70 },
+  { tool: "*Run*",         baseScore: 65 },
+  { tool: "*Shell*",       baseScore: 75 },
+  { tool: "*Bash*",        baseScore: 75 },
+  { tool: "*Command*",     baseScore: 70 },
+  // Network
+  { tool: "*Fetch*",       baseScore: 35 },
+  { tool: "*Http*",        baseScore: 35 },
+  { tool: "*Request*",     baseScore: 35 },
+  // Read operations (low risk)
+  { tool: "Read*",         baseScore: 10 },
+  { tool: "Get*",          baseScore: 10 },
+  { tool: "List*",         baseScore: 5 },
+  { tool: "Search*",       baseScore: 10 },
+];
+
+// Argument keywords that bump the risk score
+const DANGEROUS_ARG_KEYWORDS = [
+  { pattern: /\bdrop\b/i,       boost: 30 },
+  { pattern: /\bdelete\b/i,     boost: 25 },
+  { pattern: /\btruncate\b/i,   boost: 25 },
+  { pattern: /\brm\s+-rf\b/i,   boost: 30 },
+  { pattern: /\bformat\b/i,     boost: 20 },
+  { pattern: /\b(sudo|chmod|chown)\b/i, boost: 25 },
+  { pattern: /\bpassword\b/i,   boost: 15 },
+  { pattern: /\bsecret\b/i,     boost: 15 },
+  { pattern: /\btoken\b/i,      boost: 10 },
+  { pattern: /\b(\.env|credentials)\b/i, boost: 20 },
+];
+
+// ── Risk scoring logic ──────────────────────────────────────────
+
+import { globMatch } from "./config.js";
+
+export interface RiskScore {
+  /** Final score 0-100 (capped) */
+  score: number;
+  /** Base score from tool pattern match */
+  baseScore: number;
+  /** Boost from argument analysis */
+  argBoost: number;
+  /** Boost from repeated high-risk behavior */
+  behaviorBoost: number;
+  /** Human-readable risk level */
+  level: "low" | "medium" | "high" | "critical";
+  /** Reasons contributing to the score */
+  reasons: string[];
+}
+
+export interface RiskThresholds {
+  /** Score at which action is flagged for review (default 60) */
+  flag: number;
+  /** Score at which action is auto-denied (default 85) */
+  deny: number;
+  /** Number of high-risk actions in window before revocation (default 5) */
+  revokeAfter: number;
+  /** Time window in ms for behavior tracking (default 5 minutes) */
+  windowMs: number;
+}
+
+const DEFAULT_THRESHOLDS: RiskThresholds = {
+  flag: 60,
+  deny: 85,
+  revokeAfter: 5,
+  windowMs: 5 * 60 * 1000,
+};
+
+/**
+ * In-memory tracker for repeated high-risk behavior per subject.
+ */
+class BehaviorTracker {
+  // subjectId → timestamps of high-risk actions
+  private history: Map<string, number[]> = new Map();
+  private windowMs: number;
+
+  constructor(windowMs: number) {
+    this.windowMs = windowMs;
+  }
+
+  record(subjectId: string): void {
+    const now = Date.now();
+    const entries = this.history.get(subjectId) ?? [];
+    entries.push(now);
+    this.history.set(subjectId, entries);
+  }
+
+  /** Count of high-risk actions within the sliding window. */
+  count(subjectId: string): number {
+    const cutoff = Date.now() - this.windowMs;
+    const entries = this.history.get(subjectId) ?? [];
+    const recent = entries.filter((t) => t > cutoff);
+    // Prune old entries
+    this.history.set(subjectId, recent);
+    return recent.length;
+  }
+}
+
+export class RiskEngine {
+  private thresholds: RiskThresholds;
+  private tracker: BehaviorTracker;
+  private customPatterns: RiskPattern[];
+
+  constructor(opts?: { thresholds?: Partial<RiskThresholds>; customPatterns?: RiskPattern[] }) {
+    this.thresholds = { ...DEFAULT_THRESHOLDS, ...opts?.thresholds };
+    this.tracker = new BehaviorTracker(this.thresholds.windowMs);
+    this.customPatterns = opts?.customPatterns ?? [];
+  }
+
+  /**
+   * Score a tool call.
+   * @param toolName  The MCP tool being called
+   * @param argsJson  JSON string of arguments (optional)
+   * @param subjectId Who is making the call (API key ID, session subject, or "anonymous")
+   */
+  score(toolName: string, argsJson: string | null, subjectId: string = "anonymous"): RiskScore {
+    const reasons: string[] = [];
+    let baseScore = 20; // default for unknown tools
+
+    // Check custom patterns first, then defaults
+    const allPatterns = [...this.customPatterns, ...DEFAULT_TOOL_RISKS];
+    for (const pattern of allPatterns) {
+      if (globMatch(pattern.tool, toolName)) {
+        baseScore = pattern.baseScore;
+        reasons.push(`tool "${toolName}" matches pattern "${pattern.tool}" (base=${pattern.baseScore})`);
+        break;
+      }
+    }
+
+    if (reasons.length === 0) {
+      reasons.push(`tool "${toolName}" — no pattern match, using default base score`);
+    }
+
+    // Argument analysis
+    let argBoost = 0;
+    if (argsJson) {
+      for (const kw of DANGEROUS_ARG_KEYWORDS) {
+        if (kw.pattern.test(argsJson)) {
+          argBoost += kw.boost;
+          reasons.push(`argument contains "${kw.pattern.source}" (+${kw.boost})`);
+        }
+      }
+    }
+
+    // Behavior escalation
+    let behaviorBoost = 0;
+    const recentCount = this.tracker.count(subjectId);
+    if (recentCount > 0) {
+      // Each prior high-risk action in the window adds 5 points
+      behaviorBoost = recentCount * 5;
+      reasons.push(`${recentCount} high-risk action(s) in window (+${behaviorBoost})`);
+    }
+
+    const raw = baseScore + argBoost + behaviorBoost;
+    const score = Math.min(100, Math.max(0, raw));
+
+    const level = score >= this.thresholds.deny ? "critical"
+      : score >= this.thresholds.flag ? "high"
+      : score >= 30 ? "medium"
+      : "low";
+
+    // Record if this was a high-risk action
+    if (score >= this.thresholds.flag) {
+      this.tracker.record(subjectId);
+    }
+
+    return { score, baseScore, argBoost, behaviorBoost, level, reasons };
+  }
+
+  /**
+   * Check if the subject should be revoked based on repeated high-risk behavior.
+   */
+  shouldRevoke(subjectId: string): boolean {
+    return this.tracker.count(subjectId) >= this.thresholds.revokeAfter;
+  }
+
+  /**
+   * Determine the action based on risk score.
+   */
+  evaluate(risk: RiskScore): "allow" | "flag" | "deny" {
+    if (risk.score >= this.thresholds.deny) return "deny";
+    if (risk.score >= this.thresholds.flag) return "flag";
+    return "allow";
+  }
+
+  getThresholds(): RiskThresholds {
+    return { ...this.thresholds };
+  }
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+// ── JSON-RPC types ──────────────────────────────────────────────
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse;
+
+// ── MCP-specific helpers ────────────────────────────────────────
+
+export interface McpToolCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+// ── Policy types ────────────────────────────────────────────────
+
+export type Action = "allow" | "deny";
+export type Verdict = "allow" | "deny" | "passthrough";
+
+export interface ToolRule {
+  tool: string;
+  action: Action;
+}
+
+export interface ServerPolicy {
+  server: string;
+  default_action: Action;
+  tools: ToolRule[];
+}
+
+export interface PolicyConfig {
+  version: number;
+  data_dir: string;
+  log_level: "debug" | "info" | "warn" | "error";
+  servers: ServerPolicy[];
+}
+
+// ── Audit log types ─────────────────────────────────────────────
+
+export interface AuditEntry {
+  id?: number;
+  timestamp: string;
+  server_name: string;
+  direction: "request" | "response";
+  method: string;
+  message_id: string | null;
+  tool_name: string | null;
+  arguments_json: string | null;
+  response_json: string | null;
+  verdict: Verdict;
+  risk_score: number | null;
+  risk_level: string | null;
+  policy_hash: string;
+  prev_hash: string;
+  nonce: string;
+  signature: string;
+  public_key: string;
+}
+
+// ── Auth types ──────────────────────────────────────────────────
+
+export interface ApiKey {
+  id: string;           // Public identifier (prefix: qk_)
+  key_hash: string;     // SHA-256 hex of the raw key
+  owner_id: string;     // Who created it
+  label: string;        // Human-readable name
+  scopes: string;       // Comma-separated scopes (e.g. "proxy:read,audit:write")
+  created_at: string;   // ISO-8601
+  expires_at: string | null;  // ISO-8601 or null for no expiry
+  revoked: boolean;
+}
+
+export interface Session {
+  id: string;           // Opaque session token (UUID v4)
+  subject_id: string;   // API key ID or user ID
+  auth_method: string;  // "api_key" | "passkey"
+  scopes: string;       // Inherited from credential
+  issued_at: string;    // ISO-8601
+  expires_at: string;   // ISO-8601 (default: issued_at + 24h)
+  revoked: boolean;
+}
+
+// ── Crypto types ────────────────────────────────────────────────
+
+export interface KeyPair {
+  publicKey: string;   // SPKI PEM
+  privateKey: string;  // PKCS8 PEM
+}
+
+// ── Helper: check if message is a JSON-RPC request ──────────────
+
+export function isJsonRpcRequest(msg: unknown): msg is JsonRpcRequest {
+  if (typeof msg !== "object" || msg === null) return false;
+  const obj = msg as Record<string, unknown>;
+  return obj.jsonrpc === "2.0" && typeof obj.method === "string";
+}
+
+export function isJsonRpcResponse(msg: unknown): msg is JsonRpcResponse {
+  if (typeof msg !== "object" || msg === null) return false;
+  const obj = msg as Record<string, unknown>;
+  return obj.jsonrpc === "2.0" && ("result" in obj || "error" in obj);
+}
+
+export function isToolCallRequest(msg: JsonRpcRequest): boolean {
+  return msg.method === "tools/call";
+}
+
+export function extractToolInfo(msg: JsonRpcRequest): { name: string; args: Record<string, unknown> } | null {
+  if (!isToolCallRequest(msg)) return null;
+  const params = msg.params as McpToolCallParams | undefined;
+  if (!params?.name) return null;
+  return {
+    name: params.name,
+    args: params.arguments ?? {},
+  };
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}