@tangle-network/agent-app 0.1.6 → 0.1.7

package/dist/chunk-KWHLTXLE.js

@@ -0,0 +1,95 @@
+// src/redact/index.ts
+var DEFAULT_REDACTION_PATTERNS = [
+  { kind: "ssn", pattern: /\d{3}-\d{2}-\d{4}/ },
+  { kind: "ein", pattern: /\d{2}-\d{7}/ }
+];
+var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+  "ssn",
+  "ein",
+  "password",
+  "apikey",
+  "token",
+  "secret",
+  "authorization",
+  "email",
+  "phone"
+]);
+function redactString(value, patterns) {
+  for (const { kind, pattern } of patterns) {
+    if (pattern.test(value)) return `[REDACTED:${kind}]`;
+  }
+  return value;
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function redactForIngestion(value, options = {}) {
+  const patterns = options.extraPatterns ? [...DEFAULT_REDACTION_PATTERNS, ...options.extraPatterns] : DEFAULT_REDACTION_PATTERNS;
+  const walk = (v) => {
+    if (typeof v === "string") return redactString(v, patterns);
+    if (Array.isArray(v)) return v.map(walk);
+    if (isPlainObject(v)) {
+      const out = {};
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = SENSITIVE_KEYS.has(k.toLowerCase()) ? "[REDACTED:field]" : walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(value);
+}
+function detectSpans(text, patterns = DEFAULT_REDACTION_PATTERNS) {
+  const raw = [];
+  for (const { kind, pattern } of patterns) {
+    const g = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+    for (const m of text.matchAll(g)) {
+      if (m.index === void 0 || m[0].length === 0) continue;
+      raw.push({ kind, start: m.index, end: m.index + m[0].length, text: m[0] });
+    }
+  }
+  raw.sort((a, b) => a.start - b.start || b.end - a.end);
+  const spans = [];
+  let cursor = -1;
+  let i = 0;
+  for (const s of raw) {
+    if (s.start < cursor) continue;
+    spans.push({ id: `span-${i++}`, ...s });
+    cursor = s.end;
+  }
+  return spans;
+}
+async function buildRedactedDocument(text, options) {
+  const spans = detectSpans(text, options.patterns);
+  const segments = [];
+  let pos = 0;
+  for (const span of spans) {
+    if (span.start > pos) segments.push({ type: "text", text: text.slice(pos, span.start) });
+    segments.push({ type: "redacted", id: span.id, kind: span.kind, cipher: await options.encrypt(span.text) });
+    pos = span.end;
+  }
+  if (pos < text.length) segments.push({ type: "text", text: text.slice(pos) });
+  return { segments };
+}
+async function revealSpan(doc, spanId, options) {
+  const seg = doc.segments.find(
+    (s) => s.type === "redacted" && s.id === spanId
+  );
+  if (!seg) return { ok: false, reason: "not_found" };
+  const allowed = await options.canReveal({ id: seg.id, kind: seg.kind });
+  if (!allowed) return { ok: false, reason: "forbidden" };
+  const value = await options.decrypt(seg.cipher);
+  if (options.onReveal) await options.onReveal({ id: seg.id, kind: seg.kind });
+  return { ok: true, value };
+}
+
+export {
+  DEFAULT_REDACTION_PATTERNS,
+  redactForIngestion,
+  detectSpans,
+  buildRedactedDocument,
+  revealSpan
+};
+//# sourceMappingURL=chunk-KWHLTXLE.js.map

package/dist/chunk-KWHLTXLE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/redact/index.ts"],"sourcesContent":["/**\n * PII redaction — two complementary modes.\n *\n * 1. ONE-WAY scrub (`redactForIngestion`): for production trace payloads. Tool\n *    args + results (and once, the LLM span's prompt) cross the wire into the\n *    ingestion store, which also feeds the analyst-loop's LLM prompts, so\n *    personal identifiers MUST be stripped before they leave the request path.\n *    Destructive — the original is gone, replaced by a sentinel.\n *\n * 2. REVERSIBLE redaction (`buildRedactedDocument` / `revealSpan`): for the UI.\n *    A document is split into text + redacted segments; each redacted original\n *    is kept ENCRYPTED (via a caller-supplied `encrypt` seam → `agent-app/crypto`)\n *    so a viewer can reveal a single span on demand, gated by an authorization\n *    callback and an audit hook. The mask is presentation; the original is\n *    recoverable by an authorized reveal, not lost.\n *\n * Discipline: cheap deterministic string patterns + well-known sensitive object\n * keys (value replaced, key kept, so the shape stays debuggable); recurse arrays\n * + plain objects only; NEVER throw on the one-way path.\n */\n\n/** A named PII pattern. `pattern` is matched case-insensitively at the string\n *  level; keep it non-global (global instances are derived where needed). */\nexport interface RedactionPattern {\n  kind: string\n  pattern: RegExp\n}\n\n/** The default deterministic patterns. Extend via the `extraPatterns` /\n *  `patterns` options rather than forking this module (the seam that lets a\n *  product add e.g. a credit-card matcher without a local copy). */\nexport const DEFAULT_REDACTION_PATTERNS: readonly RedactionPattern[] = [\n  { kind: 'ssn', pattern: /\\d{3}-\\d{2}-\\d{4}/ },\n  { kind: 'ein', pattern: /\\d{2}-\\d{7}/ },\n]\n\nconst SENSITIVE_KEYS = new Set([\n  'ssn',\n  'ein',\n  'password',\n  'apikey',\n  'token',\n  'secret',\n  'authorization',\n  'email',\n  'phone',\n])\n\nexport interface RedactForIngestionOptions {\n  /** Extra patterns appended to {@link DEFAULT_REDACTION_PATTERNS} for the\n   *  string-level scrub (e.g. credit-card). Additive — defaults still apply. */\n  extraPatterns?: readonly RedactionPattern[]\n}\n\nfunction redactString(value: string, patterns: readonly RedactionPattern[]): string {\n  for (const { kind, pattern } of patterns) {\n    if (pattern.test(value)) return `[REDACTED:${kind}]`\n  }\n  return value\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== 'object') return false\n  const proto = Object.getPrototypeOf(value)\n  return proto === Object.prototype || proto === null\n}\n\n/**\n * One-way PII scrub for telemetry/ingestion. Backward-compatible: called with no\n * options it behaves exactly as before (SSN/EIN strings + sensitive object keys\n * → sentinels). `extraPatterns` lets a product add matchers (e.g. credit-card)\n * without forking this module.\n */\nexport function redactForIngestion(value: unknown, options: RedactForIngestionOptions = {}): unknown {\n  const patterns = options.extraPatterns\n    ? [...DEFAULT_REDACTION_PATTERNS, ...options.extraPatterns]\n    : DEFAULT_REDACTION_PATTERNS\n  const walk = (v: unknown): unknown => {\n    if (typeof v === 'string') return redactString(v, patterns)\n    if (Array.isArray(v)) return v.map(walk)\n    if (isPlainObject(v)) {\n      const out: Record<string, unknown> = {}\n      for (const [k, val] of Object.entries(v)) {\n        out[k] = SENSITIVE_KEYS.has(k.toLowerCase()) ? '[REDACTED:field]' : walk(val)\n      }\n      return out\n    }\n    return v\n  }\n  return walk(value)\n}\n\n// ── Reversible document redaction (the UI path) ─────────────────────────────\n\n/** A detected PII span in a source string. */\nexport interface RedactionSpan {\n  /** Stable within a document (index-derived) — used for reveal + audit. */\n  id: string\n  kind: string\n  start: number\n  end: number\n  text: string\n}\n\n/**\n * Find non-overlapping PII spans in `text`. Matches every pattern, sorts by\n * position, and drops overlaps (first match wins). Deterministic — no ids that\n * vary per call.\n */\nexport function detectSpans(\n  text: string,\n  patterns: readonly RedactionPattern[] = DEFAULT_REDACTION_PATTERNS,\n): RedactionSpan[] {\n  const raw: Array<{ kind: string; start: number; end: number; text: string }> = []\n  for (const { kind, pattern } of patterns) {\n    const g = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`)\n    for (const m of text.matchAll(g)) {\n      if (m.index === undefined || m[0].length === 0) continue\n      raw.push({ kind, start: m.index, end: m.index + m[0].length, text: m[0] })\n    }\n  }\n  raw.sort((a, b) => a.start - b.start || b.end - a.end)\n  const spans: RedactionSpan[] = []\n  let cursor = -1\n  let i = 0\n  for (const s of raw) {\n    if (s.start < cursor) continue // overlaps an earlier (higher-priority) span\n    spans.push({ id: `span-${i++}`, ...s })\n    cursor = s.end\n  }\n  return spans\n}\n\n/** A redacted document segment: literal text, or a masked span with the\n *  original kept ENCRYPTED for an authorized reveal. */\nexport type RedactedDocSegment =\n  | { type: 'text'; text: string }\n  | { type: 'redacted'; id: string; kind: string; cipher: string }\n\nexport interface RedactedDocument {\n  segments: RedactedDocSegment[]\n}\n\nexport interface BuildRedactedDocumentOptions {\n  /** Encrypt one original span value. Wire it to `agent-app/crypto`\n   *  (`encryptWithKey` / `createFieldCrypto`). The cipher is what's stored. */\n  encrypt: (plaintext: string) => string | Promise<string>\n  /** Patterns to detect (default: {@link DEFAULT_REDACTION_PATTERNS}). */\n  patterns?: readonly RedactionPattern[]\n}\n\n/**\n * Split `text` into text + redacted segments, encrypting each redacted span's\n * original. The result carries NO plaintext PII — only the masked structure and\n * ciphertext — so it is safe to ship to a client; reveal happens server-side via\n * {@link revealSpan}.\n */\nexport async function buildRedactedDocument(\n  text: string,\n  options: BuildRedactedDocumentOptions,\n): Promise<RedactedDocument> {\n  const spans = detectSpans(text, options.patterns)\n  const segments: RedactedDocSegment[] = []\n  let pos = 0\n  for (const span of spans) {\n    if (span.start > pos) segments.push({ type: 'text', text: text.slice(pos, span.start) })\n    segments.push({ type: 'redacted', id: span.id, kind: span.kind, cipher: await options.encrypt(span.text) })\n    pos = span.end\n  }\n  if (pos < text.length) segments.push({ type: 'text', text: text.slice(pos) })\n  return { segments }\n}\n\nexport interface RevealSpanOptions {\n  /** Decrypt a span cipher. Wire to `agent-app/crypto` (`decryptWithKey`). */\n  decrypt: (cipher: string) => string | Promise<string>\n  /** Authorization gate — return false to deny the reveal (fail-closed). */\n  canReveal: (segment: { id: string; kind: string }) => boolean | Promise<boolean>\n  /** Audit hook — invoked only on a granted reveal (the caller records who/when). */\n  onReveal?: (segment: { id: string; kind: string }) => void | Promise<void>\n}\n\nexport interface RevealResult {\n  ok: boolean\n  value?: string\n  /** `not_found` | `forbidden` when `ok` is false. */\n  reason?: string\n}\n\n/**\n * Reveal one redacted span's original, gated + audited. Fail-closed: an unknown\n * id or a denied `canReveal` returns `{ ok: false }` and never decrypts; a\n * granted reveal decrypts, fires `onReveal` for the audit trail, and returns the\n * value.\n */\nexport async function revealSpan(\n  doc: RedactedDocument,\n  spanId: string,\n  options: RevealSpanOptions,\n): Promise<RevealResult> {\n  const seg = doc.segments.find((s): s is Extract<RedactedDocSegment, { type: 'redacted' }> =>\n    s.type === 'redacted' && s.id === spanId,\n  )\n  if (!seg) return { ok: false, reason: 'not_found' }\n  const allowed = await options.canReveal({ id: seg.id, kind: seg.kind })\n  if (!allowed) return { ok: false, reason: 'forbidden' }\n  const value = await options.decrypt(seg.cipher)\n  if (options.onReveal) await options.onReveal({ id: seg.id, kind: seg.kind })\n  return { ok: true, value }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { DeriveKeyOptions, createFieldCrypto, decodeHexKey, decryptAesGcm, decry
 export { JsonRecord, PersistedChatMessageForTurn, ResolvedChatTurn, StreamEvent, asRecord, asString, buildUserTextParts, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName } from './stream/index.js';
 export { HubExecClient, HubExecClientOptions, HubExecErrorCode, HubExecResult, HubInvokeDeps, HubInvokeInput, HubInvokeOutcome, ParsedIntegrationAction, invokeIntegrationHub, resolveIntegrationAction } from './integrations/index.js';
 export { JsonObject, KvLike, RateLimitResult, RequestContext, SecurityHeaderOptions, addSecurityHeaders, checkRateLimit, extractRequestContext, parseJsonObjectBody, requireString } from './web/index.js';
-export { redactForIngestion } from './redact/index.js';
+export { BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, RedactForIngestionOptions, RedactedDocSegment, RedactedDocument, RedactionPattern, RedactionSpan, RevealResult, RevealSpanOptions, buildRedactedDocument, detectSpans, redactForIngestion, revealSpan } from './redact/index.js';
 export { CompletionRequirement, CompletionVerdict, CorrectnessChecker, ProducedState, RuntimeEventLike, SatisfiedBy, TaskGold, createLlmCorrectnessChecker, extractProducedState, verifyCompletion, weightedComposite } from '@tangle-network/agent-eval';
 export { D as DEFAULT_TANGLE_ROUTER_BASE_URL, R as ResolveModelOptions, T as TangleModelConfig, r as resolveTangleModelConfig } from './model-BOP69mVu.js';
 import '@tangle-network/agent-knowledge';

package/dist/index.js

@@ -1,6 +1,10 @@
 import {
-  redactForIngestion
-} from "./chunk-C5CREGT2.js";
+  DEFAULT_REDACTION_PATTERNS,
+  buildRedactedDocument,
+  detectSpans,
+  redactForIngestion,
+  revealSpan
+} from "./chunk-KWHLTXLE.js";
 import {
   DEFAULT_HARNESS,
   KNOWN_HARNESSES,
@@ -124,6 +128,7 @@ export {
   DEFAULT_APP_TOOL_PATHS,
   DEFAULT_HARNESS,
   DEFAULT_HEADER_NAMES,
+  DEFAULT_REDACTION_PATTERNS,
   DEFAULT_TANGLE_ROUTER_BASE_URL,
   DELEGATION_MCP_SERVER_KEY,
   DELEGATION_TOOLS,
@@ -143,6 +148,7 @@ export {
   buildDelegationMcpServer,
   buildHttpMcpServer,
   buildKnowledgeRequirements,
+  buildRedactedDocument,
   buildUserTextParts,
   checkRateLimit,
   coerceHarness,
@@ -171,6 +177,7 @@ export {
   delegationMcpForConfig,
   deriveKey,
   deriveSignals,
+  detectSpans,
   dispatchAppTool,
   encodeEvent,
   encryptAesGcm,
@@ -202,6 +209,7 @@ export {
   resolveTangleModelConfig,
   resolveToolId,
   resolveToolName,
+  revealSpan,
   reviewCandidate,
   runAppToolLoop,
   streamAppToolLoop,

package/dist/redact/index.d.ts

@@ -1,22 +1,114 @@
 /**
- * PII redaction for production trace payloads.
+ * PII redaction — two complementary modes.
  *
- * The chat-trace emission sites pass tool args + results — and at one
- * point the LLM span carried the system prompt + user message verbatim
- * — through the wire. Anything that lands in the ingestion store is
- * also fair game for the analyst-loop's LLM prompts, so personal
- * identifiers MUST be stripped before they leave the request path.
+ * 1. ONE-WAY scrub (`redactForIngestion`): for production trace payloads. Tool
+ *    args + results (and once, the LLM span's prompt) cross the wire into the
+ *    ingestion store, which also feeds the analyst-loop's LLM prompts, so
+ *    personal identifiers MUST be stripped before they leave the request path.
+ *    Destructive — the original is gone, replaced by a sentinel.
  *
- * Discipline:
- *   - Match cheap, deterministic patterns at the string level (SSN, EIN).
- *   - Match well-known sensitive object keys (case-insensitive) and
- *     replace the value, never the key, so the shape of the object
- *     remains debuggable.
- *   - Recurse arrays + plain objects only; pass through everything else
- *     unchanged (numbers, booleans, null, undefined, functions, etc).
- *   - NEVER throw — a redaction failure must not crash the chat handler.
- *     Unrecognized inputs round-trip as-is.
+ * 2. REVERSIBLE redaction (`buildRedactedDocument` / `revealSpan`): for the UI.
+ *    A document is split into text + redacted segments; each redacted original
+ *    is kept ENCRYPTED (via a caller-supplied `encrypt` seam → `agent-app/crypto`)
+ *    so a viewer can reveal a single span on demand, gated by an authorization
+ *    callback and an audit hook. The mask is presentation; the original is
+ *    recoverable by an authorized reveal, not lost.
+ *
+ * Discipline: cheap deterministic string patterns + well-known sensitive object
+ * keys (value replaced, key kept, so the shape stays debuggable); recurse arrays
+ * + plain objects only; NEVER throw on the one-way path.
+ */
+/** A named PII pattern. `pattern` is matched case-insensitively at the string
+ *  level; keep it non-global (global instances are derived where needed). */
+interface RedactionPattern {
+    kind: string;
+    pattern: RegExp;
+}
+/** The default deterministic patterns. Extend via the `extraPatterns` /
+ *  `patterns` options rather than forking this module (the seam that lets a
+ *  product add e.g. a credit-card matcher without a local copy). */
+declare const DEFAULT_REDACTION_PATTERNS: readonly RedactionPattern[];
+interface RedactForIngestionOptions {
+    /** Extra patterns appended to {@link DEFAULT_REDACTION_PATTERNS} for the
+     *  string-level scrub (e.g. credit-card). Additive — defaults still apply. */
+    extraPatterns?: readonly RedactionPattern[];
+}
+/**
+ * One-way PII scrub for telemetry/ingestion. Backward-compatible: called with no
+ * options it behaves exactly as before (SSN/EIN strings + sensitive object keys
+ * → sentinels). `extraPatterns` lets a product add matchers (e.g. credit-card)
+ * without forking this module.
+ */
+declare function redactForIngestion(value: unknown, options?: RedactForIngestionOptions): unknown;
+/** A detected PII span in a source string. */
+interface RedactionSpan {
+    /** Stable within a document (index-derived) — used for reveal + audit. */
+    id: string;
+    kind: string;
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Find non-overlapping PII spans in `text`. Matches every pattern, sorts by
+ * position, and drops overlaps (first match wins). Deterministic — no ids that
+ * vary per call.
+ */
+declare function detectSpans(text: string, patterns?: readonly RedactionPattern[]): RedactionSpan[];
+/** A redacted document segment: literal text, or a masked span with the
+ *  original kept ENCRYPTED for an authorized reveal. */
+type RedactedDocSegment = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'redacted';
+    id: string;
+    kind: string;
+    cipher: string;
+};
+interface RedactedDocument {
+    segments: RedactedDocSegment[];
+}
+interface BuildRedactedDocumentOptions {
+    /** Encrypt one original span value. Wire it to `agent-app/crypto`
+     *  (`encryptWithKey` / `createFieldCrypto`). The cipher is what's stored. */
+    encrypt: (plaintext: string) => string | Promise<string>;
+    /** Patterns to detect (default: {@link DEFAULT_REDACTION_PATTERNS}). */
+    patterns?: readonly RedactionPattern[];
+}
+/**
+ * Split `text` into text + redacted segments, encrypting each redacted span's
+ * original. The result carries NO plaintext PII — only the masked structure and
+ * ciphertext — so it is safe to ship to a client; reveal happens server-side via
+ * {@link revealSpan}.
+ */
+declare function buildRedactedDocument(text: string, options: BuildRedactedDocumentOptions): Promise<RedactedDocument>;
+interface RevealSpanOptions {
+    /** Decrypt a span cipher. Wire to `agent-app/crypto` (`decryptWithKey`). */
+    decrypt: (cipher: string) => string | Promise<string>;
+    /** Authorization gate — return false to deny the reveal (fail-closed). */
+    canReveal: (segment: {
+        id: string;
+        kind: string;
+    }) => boolean | Promise<boolean>;
+    /** Audit hook — invoked only on a granted reveal (the caller records who/when). */
+    onReveal?: (segment: {
+        id: string;
+        kind: string;
+    }) => void | Promise<void>;
+}
+interface RevealResult {
+    ok: boolean;
+    value?: string;
+    /** `not_found` | `forbidden` when `ok` is false. */
+    reason?: string;
+}
+/**
+ * Reveal one redacted span's original, gated + audited. Fail-closed: an unknown
+ * id or a denied `canReveal` returns `{ ok: false }` and never decrypts; a
+ * granted reveal decrypts, fires `onReveal` for the audit trail, and returns the
+ * value.
  */
-declare function redactForIngestion(value: unknown): unknown;
+declare function revealSpan(doc: RedactedDocument, spanId: string, options: RevealSpanOptions): Promise<RevealResult>;
 
-export { redactForIngestion };
+export { type BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, type RedactForIngestionOptions, type RedactedDocSegment, type RedactedDocument, type RedactionPattern, type RedactionSpan, type RevealResult, type RevealSpanOptions, buildRedactedDocument, detectSpans, redactForIngestion, revealSpan };

package/dist/redact/index.js

@@ -1,7 +1,15 @@
 import {
-  redactForIngestion
-} from "../chunk-C5CREGT2.js";
+  DEFAULT_REDACTION_PATTERNS,
+  buildRedactedDocument,
+  detectSpans,
+  redactForIngestion,
+  revealSpan
+} from "../chunk-KWHLTXLE.js";
 export {
-  redactForIngestion
+  DEFAULT_REDACTION_PATTERNS,
+  buildRedactedDocument,
+  detectSpans,
+  redactForIngestion,
+  revealSpan
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "packageManager": "pnpm@10.33.4",
   "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
   "keywords": [

package/dist/chunk-C5CREGT2.js

@@ -1,45 +0,0 @@
-// src/redact/index.ts
-var SSN_PATTERN = /\d{3}-\d{2}-\d{4}/;
-var EIN_PATTERN = /\d{2}-\d{7}/;
-var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
-  "ssn",
-  "ein",
-  "password",
-  "apikey",
-  "token",
-  "secret",
-  "authorization",
-  "email",
-  "phone"
-]);
-function redactString(value) {
-  if (SSN_PATTERN.test(value)) return "[REDACTED:ssn]";
-  if (EIN_PATTERN.test(value)) return "[REDACTED:ein]";
-  return value;
-}
-function isPlainObject(value) {
-  if (value === null || typeof value !== "object") return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-function redactForIngestion(value) {
-  if (typeof value === "string") return redactString(value);
-  if (Array.isArray(value)) return value.map(redactForIngestion);
-  if (isPlainObject(value)) {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      if (SENSITIVE_KEYS.has(k.toLowerCase())) {
-        out[k] = "[REDACTED:field]";
-        continue;
-      }
-      out[k] = redactForIngestion(v);
-    }
-    return out;
-  }
-  return value;
-}
-
-export {
-  redactForIngestion
-};
-//# sourceMappingURL=chunk-C5CREGT2.js.map

package/dist/chunk-C5CREGT2.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/redact/index.ts"],"sourcesContent":["/**\n * PII redaction for production trace payloads.\n *\n * The chat-trace emission sites pass tool args + results — and at one\n * point the LLM span carried the system prompt + user message verbatim\n * — through the wire. Anything that lands in the ingestion store is\n * also fair game for the analyst-loop's LLM prompts, so personal\n * identifiers MUST be stripped before they leave the request path.\n *\n * Discipline:\n *   - Match cheap, deterministic patterns at the string level (SSN, EIN).\n *   - Match well-known sensitive object keys (case-insensitive) and\n *     replace the value, never the key, so the shape of the object\n *     remains debuggable.\n *   - Recurse arrays + plain objects only; pass through everything else\n *     unchanged (numbers, booleans, null, undefined, functions, etc).\n *   - NEVER throw — a redaction failure must not crash the chat handler.\n *     Unrecognized inputs round-trip as-is.\n */\n\nconst SSN_PATTERN = /\\d{3}-\\d{2}-\\d{4}/\nconst EIN_PATTERN = /\\d{2}-\\d{7}/\n\nconst SENSITIVE_KEYS = new Set([\n  'ssn',\n  'ein',\n  'password',\n  'apikey',\n  'token',\n  'secret',\n  'authorization',\n  'email',\n  'phone',\n])\n\nfunction redactString(value: string): string {\n  if (SSN_PATTERN.test(value)) return '[REDACTED:ssn]'\n  if (EIN_PATTERN.test(value)) return '[REDACTED:ein]'\n  return value\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== 'object') return false\n  const proto = Object.getPrototypeOf(value)\n  return proto === Object.prototype || proto === null\n}\n\nexport function redactForIngestion(value: unknown): unknown {\n  if (typeof value === 'string') return redactString(value)\n  if (Array.isArray(value)) return value.map(redactForIngestion)\n  if (isPlainObject(value)) {\n    const out: Record<string, unknown> = {}\n    for (const [k, v] of Object.entries(value)) {\n      if (SENSITIVE_KEYS.has(k.toLowerCase())) {\n        out[k] = '[REDACTED:field]'\n        continue\n      }\n      out[k] = redactForIngestion(v)\n    }\n    return out\n  }\n  return value\n}\n"],"mappings":";AAoBA,IAAM,cAAc;AACpB,IAAM,cAAc;AAEpB,IAAM,iBAAiB,oBAAI,IAAI;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAuB;AAC3C,MAAI,YAAY,KAAK,KAAK,EAAG,QAAO;AACpC,MAAI,YAAY,KAAK,KAAK,EAAG,QAAO;AACpC,SAAO;AACT;AAEA,SAAS,cAAc,OAAkD;AACvE,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AACxD,QAAM,QAAQ,OAAO,eAAe,KAAK;AACzC,SAAO,UAAU,OAAO,aAAa,UAAU;AACjD;AAEO,SAAS,mBAAmB,OAAyB;AAC1D,MAAI,OAAO,UAAU,SAAU,QAAO,aAAa,KAAK;AACxD,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,kBAAkB;AAC7D,MAAI,cAAc,KAAK,GAAG;AACxB,UAAM,MAA+B,CAAC;AACtC,eAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,KAAK,GAAG;AAC1C,UAAI,eAAe,IAAI,EAAE,YAAY,CAAC,GAAG;AACvC,YAAI,CAAC,IAAI;AACT;AAAA,MACF;AACA,UAAI,CAAC,IAAI,mBAAmB,CAAC;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}