ai-shield-core 0.1.0 → 0.2.0

package/dist/audit/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/audit/logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA+C;gBAErD,MAAM,EAAE,iBAAiB;IAUrC,wBAAwB;IAClB,GAAG,CACP,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,EACzB,KAAK,GAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GACL,OAAO,CAAC,IAAI,CAAC;IA+BhB,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,4CAA4C;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B;AAID,qBAAa,iBAAkB,YAAW,UAAU;IAC5C,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5B,OAAO,CAAC,KAAK;CAUd;AAID,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,EAAE,WAAW,EAAE,CAAM;IAEtB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC7B"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/audit/logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA+C;gBAErD,MAAM,EAAE,iBAAiB;IAerC,wBAAwB;IAClB,GAAG,CACP,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,EACzB,KAAK,GAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GACL,OAAO,CAAC,IAAI,CAAC;IA+BhB,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,4CAA4C;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B;AAID,qBAAa,iBAAkB,YAAW,UAAU;IAC5C,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5B,OAAO,CAAC,KAAK;CAUd;AAID,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,EAAE,WAAW,EAAE,CAAM;IAEtB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC7B"}

package/dist/audit/logger.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryAuditStore = exports.ConsoleAuditStore = exports.AuditLogger = void 0;
-const node_crypto_1 = require("node:crypto");
-const node_crypto_2 = require("node:crypto");
-class AuditLogger {
+import { randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
+export class AuditLogger {
     store;
     buffer = [];
     batchSize;
@@ -15,19 +12,24 @@ 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 */
     async log(input, result, context = {}, extra = {}) {
         const record = {
-            id: (0, node_crypto_1.randomUUID)(),
+            id: randomUUID(),
             timestamp: new Date(),
             sessionId: context.sessionId,
             agentId: context.agentId,
             userIdHash: context.userId
-                ? (0, node_crypto_2.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: (0, node_crypto_2.createHash)("sha256").update(input).digest("hex"),
+            inputHash: createHash("sha256").update(input).digest("hex"),
             inputTokenCount: Math.ceil(input.length / 4), // rough estimate
             model: extra.model,
             securityDecision: result.decision,
@@ -62,9 +64,8 @@ class AuditLogger {
         await this.store.close();
     }
 }
-exports.AuditLogger = AuditLogger;
 // --- Console Store (for development) ---
-class ConsoleAuditStore {
+export class ConsoleAuditStore {
     async write(record) {
         this.print(record);
     }
@@ -83,9 +84,8 @@ class ConsoleAuditStore {
         process.stderr.write(`[AI-Shield] ${icon} | ${record.scanDurationMs.toFixed(1)}ms | agent=${record.agentId ?? "-"} | ${record.inputHash.substring(0, 8)}...${violations}\n`);
     }
 }
-exports.ConsoleAuditStore = ConsoleAuditStore;
 // --- Memory Store (for testing) ---
-class MemoryAuditStore {
+export class MemoryAuditStore {
     records = [];
     async write(record) {
         this.records.push(record);
@@ -96,5 +96,4 @@ class MemoryAuditStore {
     async flush() { }
     async close() { }
 }
-exports.MemoryAuditStore = MemoryAuditStore;
 //# sourceMappingURL=logger.js.map

package/dist/audit/types.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=types.js.map

package/dist/cache/lru.js

@@ -1,11 +1,8 @@
-"use strict";
 // ============================================================
 // LRU Cache — O(1) scan result caching with TTL
 // Uses Map insertion-order for LRU eviction
 // ============================================================
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ScanLRUCache = void 0;
-class ScanLRUCache {
+export class ScanLRUCache {
     cache = new Map();
     maxSize;
     ttlMs;
@@ -70,5 +67,4 @@ class ScanLRUCache {
         return removed;
     }
 }
-exports.ScanLRUCache = ScanLRUCache;
 //# sourceMappingURL=lru.js.map

package/dist/canary/memory.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryCanaryEntry, MemoryCanaryVerification } from "../types.js";
+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 declare function mintMemoryCanary(id: string, content: string, tenantId?: string, options?: MintMemoryCanaryOptions): MemoryCanaryEntry;
+/**
+ * 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 declare function verifyMemoryCanary(entry: MemoryCanaryEntry, observedContent: string, options?: {
+    tenantId?: string;
+}): MemoryCanaryVerification;
+/**
+ * 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 declare function rotateMemoryCanary(prev: MemoryCanaryEntry, newContent: string): MemoryCanaryEntry;
+/**
+ * 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 declare function buildSentinelEntry(scope: string, tenantId?: string): MemoryCanaryEntry;
+/**
+ * Bulk verify a set of stored entries against their canaries. Returns
+ * the IDs that failed verification, with the reason.
+ */
+export declare function bulkVerify(entries: Array<{
+    canary: MemoryCanaryEntry;
+    observedContent: string;
+    expectedTenantId?: string;
+}>): Array<{
+    id: string;
+    reason: NonNullable<MemoryCanaryVerification["reason"]>;
+}>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/canary/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/canary/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAgCrB,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,CAsBnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,EACxB,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,wBAAwB,CAuD1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAEnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAChB,iBAAiB,CAQnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,GACD,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAA;CAAE,CAAC,CAchF"}

package/dist/canary/memory.js

@@ -0,0 +1,194 @@
+import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
+// ============================================================
+// 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;
+/**
+ * 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, content, tenantId, options = {}) {
+    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, observedContent, options = {}) {
+    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, newContent) {
+    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, tenantId) {
+    // 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) {
+    const failures = [];
+    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, content, token, tenantId) {
+    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, b) {
+    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"));
+}
+//# sourceMappingURL=memory.js.map

package/dist/context/wrap-context.d.ts

@@ -0,0 +1,105 @@
+import type { WrappedContext, Violation } from "../types.js";
+/**
+ * Input shape for `wrapContext()`. Each named field is conventional;
+ * pass only what applies.
+ */
+export interface WrapContextInput {
+    /** Developer-controlled prompt. Always `trust: "system"`. */
+    system?: string;
+    /** Direct user message(s). `trust: "untrusted"`, `source: "user"`. */
+    user?: string | string[];
+    /** Retrieved documents. `trust: "untrusted"`, `source: "rag"`. */
+    retrieved?: Array<{
+        content: string;
+        label?: string;
+    } | string>;
+    /** MCP / function tool descriptions about to be exposed to the model. */
+    tools?: Array<{
+        content: string;
+        label?: string;
+    } | string>;
+    /** Stored memory facts. `trust: "untrusted"`, `source: "memory"`. */
+    memory?: Array<{
+        content: string;
+        label?: string;
+    } | string>;
+    /** Scraped / fetched web content. */
+    web?: Array<{
+        content: string;
+        label?: string;
+    } | string>;
+    /** Output from another agent (multi-agent pipelines). */
+    agentOutput?: Array<{
+        content: string;
+        label?: string;
+    } | string>;
+    /**
+     * Promote specific named segments to `"trusted"` (e.g. an internal
+     * knowledge base whose contents you control end-to-end).
+     * Match is by `label` substring, case-insensitive.
+     */
+    trustedLabels?: string[];
+}
+/**
+ * Build a `WrappedContext` from typed inputs.
+ *
+ * Trust assignment:
+ * - `system` -> system
+ * - `retrieved`/`tools`/`memory`/`web`/`agent-output` -> untrusted
+ * - `user` -> untrusted (a user is not trusted in this threat model — they
+ *   can also inject; the `untrusted` label means "scan aggressively")
+ * - any segment whose `label` matches one of `trustedLabels` -> trusted
+ *
+ * Trust does NOT mean "skip scanning". It only governs how
+ * `assemblePrompt()` and the per-segment policy decide whether to
+ * include the segment in the final assembled prompt.
+ */
+export declare function wrapContext(input: WrapContextInput): WrappedContext;
+/**
+ * Scan every segment with the source-specific ingestion profile.
+ * Mutates `ctx` in place by attaching `scanResults` + `decision`,
+ * AND returns the same object for chaining.
+ */
+export declare function scanWrappedContext(ctx: WrappedContext, options?: {
+    strictness?: "low" | "medium" | "high";
+}): Promise<WrappedContext>;
+/**
+ * Assemble a prompt string respecting tier boundaries.
+ *
+ * Order: `system` → `trusted` retrieved/memory/tool-desc → `user`
+ *      → all remaining `untrusted` segments wrapped in fenced markers.
+ *
+ * Why `trusted` before `user`? Putting developer-marked trusted
+ * context above the user message reduces the chance an untrusted user
+ * prompt re-frames the trusted reference material below it.
+ *
+ * Untrusted segments are wrapped in an explicit fence so a downstream
+ * model has a chance to attend to provenance. This is not a guarantee
+ * (no in-band marker is) but it is the single highest-leverage
+ * mitigation we can apply at the toolkit layer per Anthropic +
+ * OpenAI Model Spec guidance.
+ *
+ * Pass `strictMode: true` to OMIT blocked segments entirely. Default
+ * keeps them but fences them with a `<BLOCKED>` marker so an auditor
+ * can see what was tried.
+ */
+export interface AssembleOptions {
+    strictMode?: boolean;
+    /** Custom fence labels. Defaults are sensible. */
+    fences?: {
+        untrusted?: {
+            open: string;
+            close: string;
+        };
+        blocked?: {
+            open: string;
+            close: string;
+        };
+    };
+}
+export declare function assemblePrompt(ctx: WrappedContext, options?: AssembleOptions): string;
+/**
+ * Convenience aggregator: violations across all scanned segments.
+ */
+export declare function flattenViolations(ctx: WrappedContext): Violation[];
+//# sourceMappingURL=wrap-context.d.ts.map

package/dist/context/wrap-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-context.d.ts","sourceRoot":"","sources":["../../src/context/wrap-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,cAAc,EAGd,SAAS,EACV,MAAM,aAAa,CAAC;AAmBrB;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAChE,yEAAyE;IACzE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAC5D,qEAAqE;IACrE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAC7D,qCAAqC;IACrC,GAAG,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAC1D,yDAAyD;IACzD,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAClE;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAmEnE;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;CAAO,GACvD,OAAO,CAAC,cAAc,CAAC,CAmCzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5C,OAAO,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3C,CAAC;CACH;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAyER;AAUD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,EAAE,CAGlE"}

package/dist/context/wrap-context.js

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { IngestionScanner } from "../scanner/ingestion.js";
+/**
+ * Build a `WrappedContext` from typed inputs.
+ *
+ * Trust assignment:
+ * - `system` -> system
+ * - `retrieved`/`tools`/`memory`/`web`/`agent-output` -> untrusted
+ * - `user` -> untrusted (a user is not trusted in this threat model — they
+ *   can also inject; the `untrusted` label means "scan aggressively")
+ * - any segment whose `label` matches one of `trustedLabels` -> trusted
+ *
+ * Trust does NOT mean "skip scanning". It only governs how
+ * `assemblePrompt()` and the per-segment policy decide whether to
+ * include the segment in the final assembled prompt.
+ */
+export function wrapContext(input) {
+    const segments = [];
+    const trustedLabels = (input.trustedLabels ?? []).map((s) => s.toLowerCase());
+    // Critic H1 — substring match would let an attacker-supplied label
+    // like "untrusted-doc-INTERNAL-kb-poisoned" claim trust because it
+    // CONTAINS the trusted prefix. Match exact or path-anchored only.
+    const isTrustedLabel = (label) => {
+        if (!label)
+            return false;
+        const lc = label.toLowerCase();
+        return trustedLabels.some((tl) => lc === tl || lc.startsWith(tl + "/"));
+    };
+    const push = (content, source, trust, label) => {
+        if (typeof content !== "string" || content.length === 0)
+            return;
+        segments.push({
+            source,
+            trust,
+            content,
+            label,
+            contentHash: hashContent(content),
+        });
+    };
+    // System: always trust=system. The `source` field is unused for
+    // system segments because `trust === "system"` is the authoritative
+    // signal — Analyst A2 round 1 review. We keep `source: "user"` here
+    // only because `ContextSegment.source` is non-optional; any code that
+    // branches on `seg.source` MUST first check `seg.trust !== "system"`.
+    if (input.system) {
+        push(input.system, "user", "system", "system-prompt");
+    }
+    // User messages.
+    if (input.user) {
+        const userInputs = Array.isArray(input.user) ? input.user : [input.user];
+        for (const u of userInputs) {
+            push(u, "user", "untrusted", "user");
+        }
+    }
+    // Helper for the array-of-{content,label} groups.
+    const pushGroup = (items, source) => {
+        if (!items)
+            return;
+        for (const item of items) {
+            const content = typeof item === "string" ? item : item.content;
+            const label = typeof item === "string" ? undefined : item.label;
+            const trust = isTrustedLabel(label) ? "trusted" : "untrusted";
+            push(content, source, trust, label);
+        }
+    };
+    pushGroup(input.retrieved, "rag");
+    pushGroup(input.tools, "tool-desc");
+    pushGroup(input.memory, "memory");
+    pushGroup(input.web, "web");
+    pushGroup(input.agentOutput, "agent-output");
+    return { segments };
+}
+/**
+ * Scan every segment with the source-specific ingestion profile.
+ * Mutates `ctx` in place by attaching `scanResults` + `decision`,
+ * AND returns the same object for chaining.
+ */
+export async function scanWrappedContext(ctx, options = {}) {
+    const scanner = new IngestionScanner({
+        strictness: options.strictness ?? "high",
+    });
+    const results = [];
+    let worst = "allow";
+    for (let i = 0; i < ctx.segments.length; i += 1) {
+        const seg = ctx.segments[i];
+        // System segments skip the scanner — they're developer-authored and
+        // running the heuristic over a real system prompt would flood with
+        // false positives (system prompts ARE instructions, by definition).
+        if (seg.trust === "system") {
+            results.push({ segmentIndex: i, decision: "allow", violations: [] });
+            continue;
+        }
+        const scanContext = {
+            source: seg.source,
+            trustTier: seg.trust,
+        };
+        const r = await scanner.scan(seg.content, scanContext);
+        results.push({
+            segmentIndex: i,
+            decision: r.decision,
+            violations: r.violations,
+        });
+        if (priority(r.decision) > priority(worst)) {
+            worst = r.decision;
+        }
+    }
+    ctx.scanResults = results;
+    ctx.decision = worst;
+    return ctx;
+}
+export function assemblePrompt(ctx, options = {}) {
+    const fences = {
+        untrusted: options.fences?.untrusted ?? {
+            open: "<UNTRUSTED_CONTENT source=",
+            close: "</UNTRUSTED_CONTENT>",
+        },
+        blocked: options.fences?.blocked ?? {
+            open: "<BLOCKED_CONTENT source=",
+            close: "</BLOCKED_CONTENT>",
+        },
+    };
+    // Pre-build a segment→index map ONCE. Avoids O(n²) `indexOf` inside the
+    // assembly loop AND removes a TOCTOU on mutable `ctx.segments` (Critic
+    // H2 + Analyst A4 round 1 review).
+    const segmentIndexMap = new Map();
+    ctx.segments.forEach((s, i) => segmentIndexMap.set(s, i));
+    const segmentResultMap = new Map();
+    for (const r of ctx.scanResults ?? []) {
+        segmentResultMap.set(r.segmentIndex, r);
+    }
+    const ordered = [];
+    // 1. system
+    ordered.push(...ctx.segments.filter((s) => s.trust === "system"));
+    // 2. trusted (retrieved/memory/tool-desc the dev marked as trusted)
+    ordered.push(...ctx.segments.filter((s) => s.trust === "trusted"));
+    // 3. user (untrusted, source="user")
+    ordered.push(...ctx.segments.filter((s) => s.source === "user" && s.trust === "untrusted"));
+    // 4. all remaining untrusted, preserve original order within group.
+    for (const s of ctx.segments) {
+        if (s.trust === "untrusted" && s.source !== "user") {
+            ordered.push(s);
+        }
+    }
+    const parts = [];
+    for (const seg of ordered) {
+        const segIdx = segmentIndexMap.get(seg) ?? -1;
+        const segResult = segIdx >= 0 ? segmentResultMap.get(segIdx) : undefined;
+        const blocked = segResult?.decision === "block";
+        if (blocked) {
+            if (options.strictMode) {
+                // Drop entirely.
+                continue;
+            }
+            parts.push(`${fences.blocked.open}"${seg.source}" label="${seg.label ?? ""}">\n${seg.content}\n${fences.blocked.close}`);
+            continue;
+        }
+        if (seg.trust === "system") {
+            parts.push(seg.content);
+        }
+        else if (seg.trust === "trusted") {
+            parts.push(seg.content);
+        }
+        else if (seg.source === "user" && seg.trust === "untrusted") {
+            // User input keeps its natural shape — fencing every user message
+            // creates more noise than signal.
+            parts.push(seg.content);
+        }
+        else {
+            parts.push(`${fences.untrusted.open}"${seg.source}" label="${seg.label ?? ""}">\n${seg.content}\n${fences.untrusted.close}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function priority(d) {
+    return d === "block" ? 2 : d === "warn" ? 1 : 0;
+}
+/**
+ * Convenience aggregator: violations across all scanned segments.
+ */
+export function flattenViolations(ctx) {
+    if (!ctx.scanResults)
+        return [];
+    return ctx.scanResults.flatMap((r) => r.violations);
+}
+//# sourceMappingURL=wrap-context.js.map