ai-shield-core 0.1.0

package/dist/shield.d.ts

@@ -0,0 +1,31 @@
+import type { ShieldConfig, ScanResult, ScanContext } from "./types.js";
+import { PolicyEngine } from "./policy/engine.js";
+export declare class AIShield {
+    private chain;
+    private policyEngine;
+    private costTracker;
+    private auditLogger;
+    private scanCache;
+    private config;
+    constructor(config?: ShieldConfig);
+    /** Scan input text — the main API */
+    scan(input: string, context?: ScanContext): Promise<ScanResult>;
+    /** Check cost budget before making an LLM call */
+    checkBudget(entityId: string, model: string, estimatedInputTokens: number, estimatedOutputTokens?: number): Promise<import("./types.js").BudgetCheckResult>;
+    /** Record cost after receiving LLM response */
+    recordCost(entityId: string, model: string, inputTokens: number, outputTokens: number): Promise<import("./types.js").CostRecord | null>;
+    /** Get current spend for an entity */
+    getCurrentSpend(entityId: string): Promise<number>;
+    /** Get the policy engine */
+    getPolicy(): PolicyEngine;
+    /** Clear the scan cache */
+    clearCache(): void;
+    /** Get cache stats */
+    get cacheSize(): number;
+    /** Graceful shutdown */
+    close(): Promise<void>;
+    private buildCacheKey;
+    private setupScanners;
+    private setupAudit;
+}
+//# sourceMappingURL=shield.d.ts.map

package/dist/shield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shield.d.ts","sourceRoot":"","sources":["../src/shield.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAKpF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,GAAE,YAAiB;IAyBrC,qCAAqC;IAC/B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BzE,kDAAkD;IAC5C,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,oBAAoB,EAAE,MAAM,EAC5B,qBAAqB,CAAC,EAAE,MAAM;IAahC,+CAA+C;IACzC,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM;IAMtB,sCAAsC;IAChC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxD,4BAA4B;IAC5B,SAAS,IAAI,YAAY;IAIzB,2BAA2B;IAC3B,UAAU,IAAI,IAAI;IAIlB,sBAAsB;IACtB,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wBAAwB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;IAkDrB,OAAO,CAAC,UAAU;CA2BnB"}

package/dist/shield.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIShield = void 0;
+const chain_js_1 = require("./scanner/chain.js");
+const heuristic_js_1 = require("./scanner/heuristic.js");
+const pii_js_1 = require("./scanner/pii.js");
+const tools_js_1 = require("./policy/tools.js");
+const engine_js_1 = require("./policy/engine.js");
+const tracker_js_1 = require("./cost/tracker.js");
+const logger_js_1 = require("./audit/logger.js");
+const lru_js_1 = require("./cache/lru.js");
+// ============================================================
+// AIShield — Main class, single entry point
+// ============================================================
+class AIShield {
+    chain;
+    policyEngine;
+    costTracker;
+    auditLogger;
+    scanCache;
+    config;
+    constructor(config = {}) {
+        this.config = config;
+        this.policyEngine = new engine_js_1.PolicyEngine(config.preset ?? "public_website");
+        this.chain = new chain_js_1.ScannerChain({ earlyExit: true });
+        // Build scanner chain based on config
+        this.setupScanners(config);
+        // Cost tracker (optional, needs Redis for distributed use)
+        this.costTracker = config.cost?.enabled !== false && config.cost?.budgets
+            ? new tracker_js_1.CostTracker(config.cost.budgets)
+            : null;
+        // Audit logger (optional)
+        this.auditLogger = this.setupAudit(config);
+        // Scan cache (enabled when cache config is provided)
+        this.scanCache = config.cache && config.cache.enabled !== false
+            ? new lru_js_1.ScanLRUCache({
+                maxSize: config.cache.maxSize,
+                ttlMs: config.cache.ttlMs,
+            })
+            : null;
+    }
+    /** Scan input text — the main API */
+    async scan(input, context = {}) {
+        // Apply preset if not set in context
+        if (!context.preset) {
+            context.preset = this.config.preset ?? "public_website";
+        }
+        // Check cache
+        if (this.scanCache) {
+            const cacheKey = this.buildCacheKey(input, context);
+            const cached = this.scanCache.get(cacheKey);
+            if (cached) {
+                return { ...cached, meta: { ...cached.meta, cached: true } };
+            }
+        }
+        const result = await this.chain.run(input, context);
+        // Store in cache
+        if (this.scanCache) {
+            const cacheKey = this.buildCacheKey(input, context);
+            this.scanCache.set(cacheKey, result);
+        }
+        // Log to audit if enabled
+        if (this.auditLogger) {
+            void this.auditLogger.log(input, result, context);
+        }
+        return result;
+    }
+    /** Check cost budget before making an LLM call */
+    async checkBudget(entityId, model, estimatedInputTokens, estimatedOutputTokens) {
+        if (!this.costTracker) {
+            return { allowed: true, currentSpend: 0, remainingBudget: Infinity };
+        }
+        return this.costTracker.checkBudget(entityId, model, estimatedInputTokens, estimatedOutputTokens);
+    }
+    /** Record cost after receiving LLM response */
+    async recordCost(entityId, model, inputTokens, outputTokens) {
+        if (!this.costTracker)
+            return null;
+        return this.costTracker.recordCost(entityId, model, inputTokens, outputTokens);
+    }
+    /** Get current spend for an entity */
+    async getCurrentSpend(entityId) {
+        if (!this.costTracker)
+            return 0;
+        return this.costTracker.getCurrentSpend(entityId);
+    }
+    /** Get the policy engine */
+    getPolicy() {
+        return this.policyEngine;
+    }
+    /** Clear the scan cache */
+    clearCache() {
+        this.scanCache?.clear();
+    }
+    /** Get cache stats */
+    get cacheSize() {
+        return this.scanCache?.size ?? 0;
+    }
+    /** Graceful shutdown */
+    async close() {
+        this.scanCache?.clear();
+        if (this.auditLogger) {
+            await this.auditLogger.close();
+        }
+    }
+    // --- Private setup ---
+    buildCacheKey(input, context) {
+        // Include preset + tool names in key since they affect scan results
+        const parts = [context.preset ?? "default"];
+        if (context.tools?.length) {
+            parts.push(context.tools.map((t) => t.name).sort().join(","));
+        }
+        parts.push(input);
+        return parts.join("\x00");
+    }
+    setupScanners(config) {
+        // 1. Heuristic injection scanner (always on unless explicitly disabled)
+        if (config.injection?.enabled !== false) {
+            const preset = this.policyEngine.getPreset();
+            this.chain.add(new heuristic_js_1.HeuristicScanner({
+                strictness: config.injection?.strictness ?? "medium",
+                threshold: config.injection?.threshold ?? preset.injection.threshold,
+                customPatterns: config.injection?.customPatterns?.map((pattern, i) => ({
+                    id: `CUSTOM-${i + 1}`,
+                    category: "instruction_override",
+                    pattern,
+                    weight: 0.25,
+                    description: `Custom pattern #${i + 1}`,
+                })),
+            }));
+        }
+        // 2. PII scanner
+        if (config.pii?.enabled !== false) {
+            this.chain.add(new pii_js_1.PIIScanner({
+                action: config.pii?.action ?? this.policyEngine.getPIIAction(),
+                locale: config.pii?.locale,
+                types: config.pii?.types,
+                allowedTypes: config.pii?.allowedTypes,
+            }));
+        }
+        // 3. Tool policy scanner
+        if (config.tools?.enabled !== false && config.tools?.policies) {
+            const toolPolicy = {
+                permissions: config.tools.policies,
+                global: {
+                    dangerousPatterns: config.tools.globalDangerousPatterns ??
+                        this.policyEngine.getDangerousToolPatterns(),
+                    maxToolChainDepth: config.tools.maxToolChainDepth ??
+                        this.policyEngine.getMaxToolChainDepth(),
+                },
+            };
+            this.chain.add(new tools_js_1.ToolPolicyScanner(toolPolicy, config.tools.manifestPins));
+        }
+    }
+    setupAudit(config) {
+        if (config.audit?.enabled === false)
+            return null;
+        let store;
+        switch (config.audit?.store) {
+            case "console":
+                store = new logger_js_1.ConsoleAuditStore();
+                break;
+            case "postgresql":
+                // PostgreSQL store would be imported separately to keep core lightweight
+                // For now, fall through to console
+                store = new logger_js_1.ConsoleAuditStore();
+                break;
+            case "memory":
+            default:
+                // If no store configured and audit not explicitly enabled, skip
+                if (!config.audit?.store && config.audit?.enabled !== true)
+                    return null;
+                store = new logger_js_1.ConsoleAuditStore();
+                break;
+        }
+        return new logger_js_1.AuditLogger({
+            store,
+            batchSize: config.audit?.batchSize,
+            flushIntervalMs: config.audit?.flushIntervalMs,
+        });
+    }
+}
+exports.AIShield = AIShield;
+//# sourceMappingURL=shield.js.map

package/dist/shield.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+export type ScanDecision = "allow" | "warn" | "block";
+export type ViolationType = "prompt_injection" | "pii_detected" | "tool_denied" | "tool_rate_limit" | "budget_exceeded" | "content_policy" | "manifest_drift";
+export interface Violation {
+    type: ViolationType;
+    scanner: string;
+    score: number;
+    threshold: number;
+    message: string;
+    detail?: string;
+}
+export interface ScanResult {
+    safe: boolean;
+    decision: ScanDecision;
+    sanitized: string;
+    violations: Violation[];
+    meta: {
+        scanDurationMs: number;
+        scannersRun: string[];
+        cached: boolean;
+    };
+}
+export interface ScannerResult {
+    decision: ScanDecision;
+    violations: Violation[];
+    sanitized?: string;
+    durationMs: number;
+}
+export interface Scanner {
+    name: string;
+    scan(input: string, context: ScanContext): Promise<ScannerResult>;
+}
+export interface ScanContext {
+    agentId?: string;
+    sessionId?: string;
+    userId?: string;
+    userType?: "lead" | "agency" | "customer" | "internal";
+    locale?: string;
+    preset?: PresetName;
+    tools?: ToolCall[];
+}
+export type PresetName = "public_website" | "internal_support" | "ops_agent";
+export type PIIType = "email" | "phone" | "iban" | "credit_card" | "german_tax_id" | "german_personal_id" | "german_social_security" | "ip_address" | "url_with_credentials";
+export type PIIAction = "block" | "mask" | "tokenize" | "allow";
+export interface PIIEntity {
+    type: PIIType;
+    value: string;
+    start: number;
+    end: number;
+    confidence: number;
+}
+export interface ToolCall {
+    name: string;
+    arguments?: Record<string, unknown>;
+    serverId?: string;
+}
+export interface ToolPermissions {
+    allowed: string[];
+    denied?: string[];
+    maxCallsPerMinute?: number;
+    maxCallsPerSession?: number;
+    requireApproval?: string[];
+}
+export interface ToolPolicy {
+    permissions: Record<string, ToolPermissions>;
+    global?: {
+        dangerousPatterns?: string[];
+        readOnlyMode?: boolean;
+        maxToolChainDepth?: number;
+    };
+}
+export interface ToolManifestPin {
+    serverId: string;
+    toolsHash: string;
+    toolCount: number;
+    knownTools: string[];
+    pinnedAt: Date;
+}
+export type BudgetPeriod = "hourly" | "daily" | "monthly";
+export interface BudgetConfig {
+    softLimit: number;
+    hardLimit: number;
+    period: BudgetPeriod;
+}
+export interface CostEstimate {
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCost: number;
+    model: string;
+}
+export interface CostRecord {
+    entityId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    timestamp: Date;
+}
+export interface BudgetCheckResult {
+    allowed: boolean;
+    currentSpend: number;
+    remainingBudget: number;
+    warning?: string;
+}
+export interface AuditRecord {
+    id: string;
+    timestamp: Date;
+    sessionId?: string;
+    agentId?: string;
+    userIdHash?: string;
+    requestType: "chat" | "tool_call" | "agent_to_agent";
+    inputHash: string;
+    inputTokenCount?: number;
+    model?: string;
+    securityDecision: ScanDecision;
+    securityReason?: string;
+    violations: Violation[];
+    scanDurationMs: number;
+    outputTokenCount?: number;
+    toolsCalled?: string[];
+    costUsd?: number;
+}
+export interface InjectionConfig {
+    enabled?: boolean;
+    strictness?: "low" | "medium" | "high";
+    action?: "block" | "warn" | "flag";
+    threshold?: number;
+    customPatterns?: RegExp[];
+}
+export interface PIIConfig {
+    enabled?: boolean;
+    action?: PIIAction;
+    locale?: string;
+    types?: Partial<Record<PIIType, PIIAction>>;
+    allowedTypes?: PIIType[];
+}
+export interface CostConfig {
+    enabled?: boolean;
+    budgets?: Record<string, BudgetConfig>;
+    pricing?: Record<string, {
+        inputPer1M: number;
+        outputPer1M: number;
+    }>;
+    redisUrl?: string;
+}
+export interface AuditConfig {
+    enabled?: boolean;
+    store?: "postgresql" | "memory" | "console";
+    connectionString?: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    retentionDays?: number;
+}
+export interface ToolConfig {
+    enabled?: boolean;
+    policies?: Record<string, ToolPermissions>;
+    globalDangerousPatterns?: string[];
+    maxToolChainDepth?: number;
+    manifestPins?: ToolManifestPin[];
+}
+export interface CacheConfig {
+    /** Disable caching (default: enabled when cache config is provided) */
+    enabled?: boolean;
+    /** Maximum cached entries (default: 1000) */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 300_000 = 5 minutes) */
+    ttlMs?: number;
+}
+export interface ShieldConfig {
+    injection?: InjectionConfig;
+    pii?: PIIConfig;
+    cost?: CostConfig;
+    audit?: AuditConfig;
+    tools?: ToolConfig;
+    cache?: CacheConfig;
+    preset?: PresetName;
+}
+export interface ModelPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+    cachedInputPer1M?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// ============================================================
+// AI Shield Core Types
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,uBAAuB;AACvB,+DAA+D"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "ai-shield-core",
+  "version": "0.1.0",
+  "description": "LLM Security SDK — Prompt Injection Detection, PII Protection, Cost Control, Audit",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "ioredis": ">=5.0.0",
+    "pg": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": { "optional": true },
+    "pg": { "optional": true }
+  },
+  "license": "MIT"
+}

package/src/audit/logger.ts

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
+import type { AuditRecord, ScanResult, ScanContext } from "../types.js";
+import type { AuditStore } from "./types.js";
+
+// ============================================================
+// Audit Logger — Batched writes to pluggable backend
+// Stores metadata + hashes, NOT raw content (DSGVO)
+// ============================================================
+
+export interface AuditLoggerConfig {
+  store: AuditStore;
+  batchSize?: number;
+  flushIntervalMs?: number;
+}
+
+export class AuditLogger {
+  private store: AuditStore;
+  private buffer: AuditRecord[] = [];
+  private batchSize: number;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: AuditLoggerConfig) {
+    this.store = config.store;
+    this.batchSize = config.batchSize ?? 100;
+    const flushMs = config.flushIntervalMs ?? 1000;
+
+    this.flushTimer = setInterval(() => {
+      void this.flush();
+    }, flushMs);
+  }
+
+  /** Log a scan result */
+  async log(
+    input: string,
+    result: ScanResult,
+    context: ScanContext = {},
+    extra: {
+      model?: string;
+      outputTokenCount?: number;
+      toolsCalled?: string[];
+      costUsd?: number;
+    } = {},
+  ): Promise<void> {
+    const record: AuditRecord = {
+      id: randomUUID(),
+      timestamp: new Date(),
+      sessionId: context.sessionId,
+      agentId: context.agentId,
+      userIdHash: context.userId
+        ? createHash("sha256").update(context.userId).digest("hex").substring(0, 16)
+        : undefined,
+      requestType: context.tools?.length ? "tool_call" : "chat",
+      inputHash: createHash("sha256").update(input).digest("hex"),
+      inputTokenCount: Math.ceil(input.length / 4), // rough estimate
+      model: extra.model,
+      securityDecision: result.decision,
+      securityReason: result.violations.length > 0
+        ? result.violations.map((v) => v.message).join("; ")
+        : undefined,
+      violations: result.violations,
+      scanDurationMs: result.meta.scanDurationMs,
+      outputTokenCount: extra.outputTokenCount,
+      toolsCalled: extra.toolsCalled,
+      costUsd: extra.costUsd,
+    };
+
+    this.buffer.push(record);
+
+    if (this.buffer.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+
+  /** Flush buffered records to store */
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+
+    const batch = this.buffer.splice(0);
+    await this.store.writeBatch(batch);
+  }
+
+  /** Close the logger (flush + stop timer) */
+  async close(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+    await this.store.close();
+  }
+}
+
+// --- Console Store (for development) ---
+
+export class ConsoleAuditStore implements AuditStore {
+  async write(record: AuditRecord): Promise<void> {
+    this.print(record);
+  }
+
+  async writeBatch(records: AuditRecord[]): Promise<void> {
+    for (const record of records) this.print(record);
+  }
+
+  async flush(): Promise<void> { /* noop */ }
+  async close(): Promise<void> { /* noop */ }
+
+  private print(record: AuditRecord): void {
+    const icon = record.securityDecision === "block" ? "BLOCK" : record.securityDecision === "warn" ? "WARN " : "ALLOW";
+    const violations = record.violations.length > 0
+      ? ` [${record.violations.map((v) => v.message).join(", ")}]`
+      : "";
+    // Using stderr to not interfere with application output
+    process.stderr.write(
+      `[AI-Shield] ${icon} | ${record.scanDurationMs.toFixed(1)}ms | agent=${record.agentId ?? "-"} | ${record.inputHash.substring(0, 8)}...${violations}\n`,
+    );
+  }
+}
+
+// --- Memory Store (for testing) ---
+
+export class MemoryAuditStore implements AuditStore {
+  records: AuditRecord[] = [];
+
+  async write(record: AuditRecord): Promise<void> {
+    this.records.push(record);
+  }
+
+  async writeBatch(records: AuditRecord[]): Promise<void> {
+    this.records.push(...records);
+  }
+
+  async flush(): Promise<void> { /* noop */ }
+  async close(): Promise<void> { /* noop */ }
+}

package/src/audit/schema.sql

@@ -0,0 +1,51 @@
+-- AI Shield Audit Schema
+-- Append-only, partitioned by month for retention policies
+
+CREATE TABLE IF NOT EXISTS ai_shield_audit (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  session_id UUID,
+  agent_id VARCHAR(64),
+  user_id_hash VARCHAR(64),
+  request_type VARCHAR(20) NOT NULL,
+  input_hash VARCHAR(64) NOT NULL,
+  input_token_count INTEGER,
+  model VARCHAR(64),
+  security_decision VARCHAR(10) NOT NULL,
+  security_reason TEXT,
+  violations JSONB NOT NULL DEFAULT '[]',
+  scan_duration_ms INTEGER,
+  output_token_count INTEGER,
+  tools_called TEXT[],
+  cost_usd NUMERIC(10, 6),
+  created_month DATE NOT NULL DEFAULT DATE_TRUNC('month', NOW())
+) PARTITION BY RANGE (created_month);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_ai_shield_audit_session ON ai_shield_audit (session_id);
+CREATE INDEX IF NOT EXISTS idx_ai_shield_audit_agent ON ai_shield_audit (agent_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_ai_shield_audit_decision ON ai_shield_audit (security_decision) WHERE security_decision != 'allow';
+CREATE INDEX IF NOT EXISTS idx_ai_shield_audit_violations ON ai_shield_audit USING GIN (violations);
+
+-- Cost tracking table
+CREATE TABLE IF NOT EXISTS ai_shield_cost_records (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  entity_id VARCHAR(128) NOT NULL,
+  model VARCHAR(64) NOT NULL,
+  input_tokens INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  cost_usd NUMERIC(10, 6) NOT NULL,
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_ai_shield_cost_entity ON ai_shield_cost_records (entity_id, timestamp);
+
+-- Tool manifest pins
+CREATE TABLE IF NOT EXISTS ai_shield_manifest_pins (
+  server_id VARCHAR(128) PRIMARY KEY,
+  tools_hash VARCHAR(64) NOT NULL,
+  tool_count INTEGER NOT NULL,
+  known_tools JSONB NOT NULL,
+  pinned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);

package/src/audit/types.ts

@@ -0,0 +1,16 @@
+import type { AuditRecord } from "../types.js";
+
+// ============================================================
+// Audit Store Interface — pluggable backends
+// ============================================================
+
+export interface AuditStore {
+  /** Write a single record */
+  write(record: AuditRecord): Promise<void>;
+  /** Write a batch of records */
+  writeBatch(records: AuditRecord[]): Promise<void>;
+  /** Flush any buffered records */
+  flush(): Promise<void>;
+  /** Close the store */
+  close(): Promise<void>;
+}