ai-shield-core 0.1.0 → 0.3.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,169 @@
+import type { TrustTier, WrappedContext, ScanDecision, 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[];
+export interface AgentHop {
+    /** The agent that PRODUCED the payload entering this hop. */
+    agentId: string;
+    /** Trust tier the payload was treated as at this hop. */
+    trust: TrustTier;
+    /** Scan decision for this hop's payload. */
+    decision: ScanDecision;
+    /** Violations found at this hop. */
+    violations: Violation[];
+}
+export interface PropagateTrustOptions {
+    /**
+     * Trust tier of the producing agent's output. Defaults to `untrusted` —
+     * agent output is attacker-influenceable by construction. Only set to
+     * `trusted` for an agent whose output you control end-to-end.
+     */
+    fromTrust?: TrustTier;
+    /**
+     * Chain returned by an earlier `propagateTrust()` call. Pass it to keep
+     * contamination sticky across A→B→C. Omit for the first link.
+     */
+    priorChain?: AgentHop[];
+    /** Ingestion-scanner strictness for the contagion scan. Default `high`. */
+    strictness?: "low" | "medium" | "high";
+}
+export interface TrustPropagationResult {
+    /** No contamination anywhere in the chain (including prior hops). */
+    safe: boolean;
+    /** Worst decision across the whole chain — sticky (once block, stays). */
+    decision: ScanDecision;
+    /**
+     * Trust tier the RECEIVING agent should treat the payload as. Degrades to
+     * `untrusted` the moment this hop — or any prior hop — warns or blocks.
+     */
+    effectiveTrust: TrustTier;
+    /** Full chain including this hop. Feed back as `priorChain` for the next. */
+    hops: AgentHop[];
+    /** Every violation across the chain, newest hop last. */
+    violations: Violation[];
+}
+/**
+ * Scan one agent-to-agent hand-off and propagate trust along the chain.
+ *
+ * @param payload      The producing agent's output (= consuming agent's input).
+ * @param fromAgentId  Agent that produced `payload`.
+ * @param toAgentId    Agent about to consume `payload`.
+ *
+ * @example
+ * ```ts
+ * import { propagateTrust } from "ai-shield-core";
+ *
+ * // A → B
+ * let chain = await propagateTrust(aOutput, "researcher", "planner");
+ * // B → C, contamination at A stays sticky through to C
+ * chain = await propagateTrust(bOutput, "planner", "executor", {
+ *   priorChain: chain.hops,
+ * });
+ * if (chain.effectiveTrust !== "trusted" && !chain.safe) {
+ *   // an upstream agent was poisoned — do not let the executor act on it
+ *   haltPipeline(chain.violations);
+ * }
+ * ```
+ */
+export declare function propagateTrust(payload: string, fromAgentId: string, toAgentId: string, options?: PropagateTrustOptions): Promise<TrustPropagationResult>;
+//# 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":"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"}