ai-shield-core 0.1.0 → 0.2.0

package/dist/shield.js

@@ -1,18 +1,15 @@
-"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");
+import { ScannerChain } from "./scanner/chain.js";
+import { HeuristicScanner } from "./scanner/heuristic.js";
+import { PIIScanner } from "./scanner/pii.js";
+import { ToolPolicyScanner } from "./policy/tools.js";
+import { PolicyEngine } from "./policy/engine.js";
+import { CostTracker } from "./cost/tracker.js";
+import { AuditLogger, ConsoleAuditStore } from "./audit/logger.js";
+import { ScanLRUCache } from "./cache/lru.js";
 // ============================================================
 // AIShield — Main class, single entry point
 // ============================================================
-class AIShield {
+export class AIShield {
     chain;
     policyEngine;
     costTracker;
@@ -21,19 +18,19 @@ class AIShield {
     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 });
+        this.policyEngine = new PolicyEngine(config.preset ?? "public_website");
+        this.chain = new 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)
+            ? new 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({
+            ? new ScanLRUCache({
                 maxSize: config.cache.maxSize,
                 ttlMs: config.cache.ttlMs,
             })
@@ -41,6 +38,15 @@ class AIShield {
     }
     /** Scan input text — the main API */
     async scan(input, context = {}) {
+        // Input-length guard — without this a user-supplied multi-MB prompt would
+        // trigger every regex scan on the full buffer, which is O(n) best-case
+        // but pathological under ReDoS-prone patterns. 256 KB handles every
+        // real chat/tool input we care about with plenty of headroom; override
+        // via AI_SHIELD_MAX_INPUT_BYTES when needed.
+        const maxInputBytes = Number(process.env.AI_SHIELD_MAX_INPUT_BYTES ?? 262_144);
+        if (input.length > maxInputBytes) {
+            input = input.slice(0, maxInputBytes);
+        }
         // Apply preset if not set in context
         if (!context.preset) {
             context.preset = this.config.preset ?? "public_website";
@@ -59,8 +65,11 @@ class AIShield {
             const cacheKey = this.buildCacheKey(input, context);
             this.scanCache.set(cacheKey, result);
         }
-        // Log to audit if enabled
-        if (this.auditLogger) {
+        // Log to audit if enabled — but never double-log the same input when
+        // a downstream caller re-scans cached content (result.meta.cached is set
+        // by the cache hit path above; here it is always false but we guard to
+        // be explicit and so subclasses extending scan() stay safe).
+        if (this.auditLogger && !result.meta.cached) {
             void this.auditLogger.log(input, result, context);
         }
         return result;
@@ -117,7 +126,7 @@ class AIShield {
         // 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({
+            this.chain.add(new HeuristicScanner({
                 strictness: config.injection?.strictness ?? "medium",
                 threshold: config.injection?.threshold ?? preset.injection.threshold,
                 customPatterns: config.injection?.customPatterns?.map((pattern, i) => ({
@@ -131,7 +140,7 @@ class AIShield {
         }
         // 2. PII scanner
         if (config.pii?.enabled !== false) {
-            this.chain.add(new pii_js_1.PIIScanner({
+            this.chain.add(new PIIScanner({
                 action: config.pii?.action ?? this.policyEngine.getPIIAction(),
                 locale: config.pii?.locale,
                 types: config.pii?.types,
@@ -149,7 +158,7 @@ class AIShield {
                         this.policyEngine.getMaxToolChainDepth(),
                 },
             };
-            this.chain.add(new tools_js_1.ToolPolicyScanner(toolPolicy, config.tools.manifestPins));
+            this.chain.add(new ToolPolicyScanner(toolPolicy, config.tools.manifestPins));
         }
     }
     setupAudit(config) {
@@ -158,27 +167,26 @@ class AIShield {
         let store;
         switch (config.audit?.store) {
             case "console":
-                store = new logger_js_1.ConsoleAuditStore();
+                store = new 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();
+                store = new 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();
+                store = new ConsoleAuditStore();
                 break;
         }
-        return new logger_js_1.AuditLogger({
+        return new AuditLogger({
             store,
             batchSize: config.audit?.batchSize,
             flushIntervalMs: config.audit?.flushIntervalMs,
         });
     }
 }
-exports.AIShield = AIShield;
 //# sourceMappingURL=shield.js.map

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 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 type ViolationType = "prompt_injection" | "pii_detected" | "tool_denied" | "tool_rate_limit" | "budget_exceeded" | "content_policy" | "manifest_drift" | "ingested_injection" | "untrusted_instruction" | "memory_poisoning" | "circuit_breaker_open" | "blast_radius_exceeded";
 export interface Violation {
     type: ViolationType;
     scanner: string;
@@ -29,16 +29,154 @@ export interface Scanner {
     name: string;
     scan(input: string, context: ScanContext): Promise<ScannerResult>;
 }
+/**
+ * Where a piece of content came from. Determines how aggressively the
+ * ingestion scanner treats instruction-like patterns.
+ *
+ * - `user`        — Direct user message. Treat normally.
+ * - `rag`         — Retrieved document chunk (vector store, knowledge base).
+ *                   Instructions here are almost always an indirect-injection
+ *                   attempt.
+ * - `tool-desc`   — MCP tool description / OpenAI function schema / tool args
+ *                   that came from a remote MCP server. High-risk vector
+ *                   per Lakera 2026 advisory + OX Security MCP CVEs.
+ * - `memory`      — Persisted memory entry (knowledge graph, session
+ *                   history, vector memory). Subject to persistence-poisoning.
+ * - `web`         — Scraped web page / HTML. Hidden-instruction risk via
+ *                   HTML comments, CSS-hidden text, unicode tricks.
+ * - `agent-output`— Output from another agent flowing into this one
+ *                   (multi-agent contagion).
+ */
+export type IngestionSource = "user" | "rag" | "tool-desc" | "memory" | "web" | "agent-output";
+/**
+ * Privilege tier of a content segment. The toolkit treats instructions
+ * coming from `untrusted` sources differently from those in `system`
+ * or `trusted` segments. See `wrapContext()`.
+ */
+export type TrustTier = "system" | "trusted" | "untrusted";
 export interface ScanContext {
     agentId?: string;
     sessionId?: string;
     userId?: string;
-    userType?: "lead" | "agency" | "customer" | "internal";
+    userType?: string;
     locale?: string;
     preset?: PresetName;
     tools?: ToolCall[];
+    /**
+     * Provenance of the content being scanned. Defaults to `"user"` when
+     * unset. Set to `"rag"`/`"tool-desc"`/`"memory"`/`"web"`/`"agent-output"`
+     * to engage indirect-injection heuristics.
+     */
+    source?: IngestionSource;
+    /**
+     * Privilege tier of the content. Defaults inferred from `source`:
+     * `user` → untrusted, everything else → untrusted, `system` only when
+     * explicitly set via `wrapContext()`.
+     */
+    trustTier?: TrustTier;
 }
 export type PresetName = "public_website" | "internal_support" | "ops_agent";
+/**
+ * A single content segment with provenance + trust tagging.
+ * Produced by `wrapContext()`, consumed by `assemblePrompt()` and
+ * any policy that needs to enforce tier boundaries.
+ */
+export interface ContextSegment {
+    /** Source of the segment. */
+    source: IngestionSource;
+    /** Privilege tier. */
+    trust: TrustTier;
+    /** Raw text content. */
+    content: string;
+    /** Optional human-readable origin label (e.g. "wikipedia.org/wiki/X"). */
+    label?: string;
+    /** Optional SHA-256 content hash for poisoning detection. */
+    contentHash?: string;
+}
+export interface WrappedContext {
+    /** All segments in the order they were added. */
+    segments: ContextSegment[];
+    /** Per-segment scan results (filled by `scanWrappedContext()`). */
+    scanResults?: Array<{
+        segmentIndex: number;
+        decision: ScanDecision;
+        violations: Violation[];
+    }>;
+    /** Aggregate decision across all segments. */
+    decision?: ScanDecision;
+}
+/**
+ * A memory entry sealed with a content hash + sentinel canary.
+ * `verifyMemoryCanary()` re-derives the hash on read and flags
+ * silent mutation.
+ */
+export interface MemoryCanaryEntry {
+    /** Stable identifier of the memory entry (e.g. "fact:12345"). */
+    id: string;
+    /** Original content at write time. */
+    content: string;
+    /** SHA-256(`${id}\0${content}\0${canaryToken}`). */
+    contentHash: string;
+    /** Random sentinel token. Used to bind verification to this write. */
+    canaryToken: string;
+    /** When the canary was minted. */
+    createdAt: Date;
+    /** Optional tenant scope so leaks across tenants are detectable. */
+    tenantId?: string;
+}
+export interface MemoryCanaryVerification {
+    valid: boolean;
+    reason?: "content_mutated" | "canary_missing" | "tenant_mismatch" | "hash_mismatch";
+    /** When invalid: the mutated content actually read. */
+    observed?: string;
+}
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerConfig {
+    /** Logical tool name this breaker applies to. */
+    tool: string;
+    /** Optional sub-scope (per-agent, per-session, per-tenant). */
+    scope?: string;
+    /** Anomaly count that trips the breaker. Default: 5. */
+    failureThreshold?: number;
+    /** Rolling window in ms for the failure count. Default: 60_000. */
+    windowMs?: number;
+    /** How long the breaker stays open after tripping (ms). Default: 60_000. */
+    cooldownMs?: number;
+    /** Max calls per `windowMs`. Default: unlimited. */
+    maxCallsPerWindow?: number;
+    /** Max "destructive" calls per `windowMs`. Default: unlimited. */
+    maxWritesPerWindow?: number;
+    /** Optional human-in-the-loop confirmation hook. */
+    onDestructive?: (info: {
+        tool: string;
+        scope?: string;
+        context: ScanContext;
+    }) => boolean | Promise<boolean>;
+    /** Treat this tool as destructive (default: inferred via wildcard list). */
+    isDestructive?: boolean;
+}
+export interface CircuitBreakerDecision {
+    /** Whether the call may proceed. */
+    allowed: boolean;
+    /** Current state. */
+    state: CircuitState;
+    /** Reason if `allowed = false`. */
+    reason?: "circuit_open" | "rate_limit" | "blast_radius_exceeded" | "hitl_denied";
+    /** Detail for logs. */
+    message?: string;
+    /** Suggested retry-after in ms when state = open. */
+    retryAfterMs?: number;
+}
+/**
+ * Minimal counter store usable by the circuit breaker.
+ * Compatible subset of `ioredis` so existing
+ * `cost.tracker.RedisLike` deployments can be reused.
+ */
+export interface CounterStoreLike {
+    get(key: string): Promise<string | null>;
+    incrbyfloat(key: string, increment: number): Promise<string>;
+    expire(key: string, seconds: number): Promise<number>;
+}
 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 {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,kBAAkB,GAClB,sBAAsB,GACtB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,IAAI,EAAE;QACJ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnE;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,KAAK,GACL,WAAW,GACX,QAAQ,GACR,KAAK,GACL,cAAc,CAAC;AAEnB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,WAAW,CAAC;AAI7E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,sBAAsB;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,YAAY,CAAC;QACvB,UAAU,EAAE,SAAS,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAID;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EACH,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,WAAW,CAAC;KACtB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,qBAAqB;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EACH,cAAc,GACd,YAAY,GACZ,uBAAuB,GACvB,aAAa,CAAC;IAClB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAID,MAAM,MAAM,OAAO,GACf,OAAO,GACP,OAAO,GACP,MAAM,GACN,aAAa,GACb,eAAe,GACf,oBAAoB,GACpB,wBAAwB,GACxB,YAAY,GACZ,sBAAsB,CAAC;AAE3B,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE;QACP,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,IAAI,CAAC;CAChB;AAID,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,YAAY,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAID,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "ai-shield-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "type": "module",
   "description": "LLM Security SDK — Prompt Injection Detection, PII Protection, Cost Control, Audit",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,8 +12,8 @@
     }
   },
   "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit"
+    "build": "tsc -b",
+    "typecheck": "tsc -b"
   },
   "dependencies": {},
   "peerDependencies": {

package/src/audit/logger.ts

@@ -28,6 +28,11 @@ export class AuditLogger {
     this.flushTimer = setInterval(() => {
       void this.flush();
     }, flushMs);
+    // Allow the Node process to exit even if the timer is pending —
+    // clean shutdown should go through close(), not rely on the timer.
+    if (typeof this.flushTimer.unref === "function") {
+      this.flushTimer.unref();
+    }
   }
 
   /** Log a scan result */
@@ -48,7 +53,7 @@ export class AuditLogger {
       sessionId: context.sessionId,
       agentId: context.agentId,
       userIdHash: context.userId
-        ? createHash("sha256").update(context.userId).digest("hex").substring(0, 16)
+        ? createHash("sha256").update(context.userId).digest("hex").substring(0, 32)
         : undefined,
       requestType: context.tools?.length ? "tool_call" : "chat",
       inputHash: createHash("sha256").update(input).digest("hex"),

package/src/canary/memory.ts

@@ -0,0 +1,259 @@
+import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
+import type {
+  MemoryCanaryEntry,
+  MemoryCanaryVerification,
+} from "../types.js";
+
+// ============================================================
+// Memory Canary — Persistence-Poisoning Detection
+//
+// Existing canary tokens defend the *system prompt*: inject a sentinel
+// + check the response for leakage. That works for prompt-extraction
+// attacks but does nothing for the broader class of *persistence
+// poisoning*: an attacker mutates a stored memory entry, knowledge-graph
+// fact, or RAG document so that the next retrieval steers the model.
+//
+// MemoryCanary seals each write with:
+//   1. A random sentinel token bound to the entry (`canaryToken`).
+//   2. A SHA-256 hash over `id || content || canaryToken` so any silent
+//      mutation of `content` between write and read is detectable.
+//   3. Optional `tenantId` binding so a cross-tenant leak surfaces as
+//      an explicit `tenant_mismatch` reason.
+//
+// Storage of the canary metadata is the caller's responsibility — the
+// returned `MemoryCanaryEntry` is JSON-serialisable and meant to be
+// persisted alongside the memory entry (separate column / sidecar key).
+//
+// The library does not store secrets and does not need a key. The
+// security property is integrity (mutation detection), not
+// confidentiality.
+// ============================================================
+
+/** Minimum allowed canary-token length in bytes (= 16 hex chars). */
+const MIN_TOKEN_BYTES = 8;
+/** Default canary-token length: 16 random bytes -> 32 hex chars. */
+const DEFAULT_TOKEN_BYTES = 16;
+
+export interface MintMemoryCanaryOptions {
+  /**
+   * Override token byte length. Minimum 8 (16 hex chars). Default 16.
+   * Longer = stronger guessing resistance, but the hex string lives in
+   * sidecar storage so the overhead is negligible.
+   */
+  tokenBytes?: number;
+}
+
+/**
+ * Mint a canary for a memory entry. Call at write time, persist the
+ * returned `MemoryCanaryEntry` alongside (or in place of) the raw entry.
+ *
+ * @param id        Stable identifier of the memory entry.
+ * @param content   The content being stored.
+ * @param tenantId  Optional tenant scope.
+ */
+export function mintMemoryCanary(
+  id: string,
+  content: string,
+  tenantId?: string,
+  options: MintMemoryCanaryOptions = {},
+): MemoryCanaryEntry {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("mintMemoryCanary: 'id' must be a non-empty string");
+  }
+  if (typeof content !== "string") {
+    throw new TypeError("mintMemoryCanary: 'content' must be a string");
+  }
+  const tokenBytes = Math.max(
+    MIN_TOKEN_BYTES,
+    options.tokenBytes ?? DEFAULT_TOKEN_BYTES,
+  );
+  const canaryToken = randomBytes(tokenBytes).toString("hex");
+  const contentHash = computeHash(id, content, canaryToken, tenantId);
+
+  return {
+    id,
+    content,
+    contentHash,
+    canaryToken,
+    createdAt: new Date(),
+    tenantId,
+  };
+}
+
+/**
+ * Verify a previously minted canary against the content read back from
+ * storage. Returns `valid: true` only if both the content matches what
+ * was sealed and the tenant binding (if any) matches.
+ *
+ * Use case 1 — mutation detection:
+ * ```ts
+ * const entry = mintMemoryCanary("fact:42", "Sky is blue.");
+ * await db.write({ ...entry });
+ *
+ * // ... later ...
+ * const stored = await db.read("fact:42");
+ * const ver = verifyMemoryCanary(stored, stored.content);
+ * if (!ver.valid) {
+ *   logger.security("Memory poisoning suspected", { id, reason: ver.reason });
+ * }
+ * ```
+ *
+ * Use case 2 — cross-tenant leak detection:
+ * ```ts
+ * // tenant A reads what should be a tenant-B-only entry
+ * const ver = verifyMemoryCanary(entry, entry.content, { tenantId: "tenant-A" });
+ * // ver.reason === "tenant_mismatch"
+ * ```
+ */
+export function verifyMemoryCanary(
+  entry: MemoryCanaryEntry,
+  observedContent: string,
+  options: { tenantId?: string } = {},
+): MemoryCanaryVerification {
+  if (!entry || typeof entry !== "object") {
+    return { valid: false, reason: "canary_missing" };
+  }
+  if (
+    typeof entry.canaryToken !== "string" ||
+    entry.canaryToken.length < MIN_TOKEN_BYTES * 2
+  ) {
+    return { valid: false, reason: "canary_missing" };
+  }
+  if (typeof observedContent !== "string") {
+    return { valid: false, reason: "content_mutated" };
+  }
+  // Tenant binding is fail-closed. If the entry was minted with a
+  // tenantId, the caller MUST supply the same tenantId. A caller that
+  // omits `options.tenantId` against a tenant-bound entry surfaces as
+  // a leak rather than a silent pass (Critic C2 from round 1 review).
+  if (entry.tenantId !== undefined) {
+    if (
+      options.tenantId === undefined ||
+      options.tenantId !== entry.tenantId
+    ) {
+      return {
+        valid: false,
+        reason: "tenant_mismatch",
+        observed: observedContent,
+      };
+    }
+  } else if (
+    options.tenantId !== undefined &&
+    entry.tenantId !== options.tenantId
+  ) {
+    // Caller passed a tenantId but the entry has none — also a mismatch.
+    return {
+      valid: false,
+      reason: "tenant_mismatch",
+      observed: observedContent,
+    };
+  }
+
+  const expectedHash = computeHash(
+    entry.id,
+    observedContent,
+    entry.canaryToken,
+    entry.tenantId,
+  );
+  if (!hashesEqual(expectedHash, entry.contentHash)) {
+    return {
+      valid: false,
+      reason:
+        observedContent === entry.content ? "hash_mismatch" : "content_mutated",
+      observed: observedContent,
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Re-mint a canary after legitimate content edit. Returns a new
+ * sealed entry that supersedes the old one. The old `canaryToken`
+ * is rotated so a replay of the previous hash is also invalidated.
+ */
+export function rotateMemoryCanary(
+  prev: MemoryCanaryEntry,
+  newContent: string,
+): MemoryCanaryEntry {
+  return mintMemoryCanary(prev.id, newContent, prev.tenantId);
+}
+
+/**
+ * Inject a *sentinel* memory entry — a decoy fact whose mutation would
+ * indicate the store was tampered with. Pair with `findSentinelMutations()`
+ * in a periodic sweep over the memory store.
+ *
+ * Returns a `MemoryCanaryEntry` with deterministic content that callers
+ * can recognise. The content includes the canary token so even content
+ * inspection (not just hash compare) catches mutation.
+ */
+export function buildSentinelEntry(
+  scope: string,
+  tenantId?: string,
+): MemoryCanaryEntry {
+  // ID combines timestamp (for ordering) + random suffix (so enumeration
+  // by approximate-time guessing is infeasible — Critic M2 round 1).
+  const idSuffix = randomBytes(4).toString("hex");
+  const id = `ai-shield-sentinel:${scope}:${Date.now().toString(36)}-${idSuffix}`;
+  const nonce = randomBytes(8).toString("hex");
+  const content = `[AI-Shield sentinel — do not modify] scope=${scope} nonce=${nonce}`;
+  return mintMemoryCanary(id, content, tenantId);
+}
+
+/**
+ * Bulk verify a set of stored entries against their canaries. Returns
+ * the IDs that failed verification, with the reason.
+ */
+export function bulkVerify(
+  entries: Array<{
+    canary: MemoryCanaryEntry;
+    observedContent: string;
+    expectedTenantId?: string;
+  }>,
+): Array<{ id: string; reason: NonNullable<MemoryCanaryVerification["reason"]> }> {
+  const failures: Array<{
+    id: string;
+    reason: NonNullable<MemoryCanaryVerification["reason"]>;
+  }> = [];
+  for (const e of entries) {
+    const v = verifyMemoryCanary(e.canary, e.observedContent, {
+      tenantId: e.expectedTenantId,
+    });
+    if (!v.valid && v.reason) {
+      failures.push({ id: e.canary.id, reason: v.reason });
+    }
+  }
+  return failures;
+}
+
+// --- Internal helpers ---
+
+function computeHash(
+  id: string,
+  content: string,
+  token: string,
+  tenantId?: string,
+): string {
+  return createHash("sha256")
+    .update(id)
+    .update("\0")
+    .update(content)
+    .update("\0")
+    .update(token)
+    .update("\0")
+    .update(tenantId ?? "")
+    .digest("hex");
+}
+
+/**
+ * Constant-time hex string compare. Falls back to a non-timing-safe
+ * direct compare only when lengths differ (which is itself the leak
+ * we want surfaced as a `false`, so this is fine).
+ */
+function hashesEqual(a: string, b: string): boolean {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  if (a.length !== b.length) return false;
+  // Safe — both buffers have identical length, both come from
+  // hex(SHA-256), no untrusted input.
+  return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}