@tangle-network/agent-app 0.1.7 → 0.1.9

package/dist/{chunk-KWHLTXLE.js → chunk-5RMIUJDI.js}

@@ -15,11 +15,31 @@ var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
   "phone"
 ]);
 function redactString(value, patterns) {
-  for (const { kind, pattern } of patterns) {
-    if (pattern.test(value)) return `[REDACTED:${kind}]`;
+  for (const { kind, pattern, validate } of patterns) {
+    if (!validate) {
+      if (pattern.test(value)) return `[REDACTED:${kind}]`;
+      continue;
+    }
+    const g = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+    for (const m of value.matchAll(g)) {
+      if (m[0].length > 0 && validate(m[0])) return `[REDACTED:${kind}]`;
+    }
   }
   return value;
 }
+function maskSpans(text, patterns = DEFAULT_REDACTION_PATTERNS) {
+  const spans = detectSpans(text, patterns);
+  if (spans.length === 0) return text;
+  let out = "";
+  let pos = 0;
+  for (const s of spans) {
+    if (s.start > pos) out += text.slice(pos, s.start);
+    out += `[REDACTED:${s.kind}]`;
+    pos = s.end;
+  }
+  if (pos < text.length) out += text.slice(pos);
+  return out;
+}
 function isPlainObject(value) {
   if (value === null || typeof value !== "object") return false;
   const proto = Object.getPrototypeOf(value);
@@ -27,13 +47,22 @@ function isPlainObject(value) {
 }
 function redactForIngestion(value, options = {}) {
   const patterns = options.extraPatterns ? [...DEFAULT_REDACTION_PATTERNS, ...options.extraPatterns] : DEFAULT_REDACTION_PATTERNS;
+  const sensitiveKeys = options.extraSensitiveKeys ? /* @__PURE__ */ new Set([...SENSITIVE_KEYS, ...options.extraSensitiveKeys.map((k) => k.toLowerCase())]) : SENSITIVE_KEYS;
+  const maskString = options.stringMode === "mask-spans" ? (s) => maskSpans(s, patterns) : (s) => redactString(s, patterns);
+  const seen = /* @__PURE__ */ new WeakSet();
   const walk = (v) => {
-    if (typeof v === "string") return redactString(v, patterns);
-    if (Array.isArray(v)) return v.map(walk);
+    if (typeof v === "string") return maskString(v);
+    if (Array.isArray(v)) {
+      if (seen.has(v)) return v;
+      seen.add(v);
+      return v.map(walk);
+    }
     if (isPlainObject(v)) {
+      if (seen.has(v)) return v;
+      seen.add(v);
       const out = {};
       for (const [k, val] of Object.entries(v)) {
-        out[k] = SENSITIVE_KEYS.has(k.toLowerCase()) ? "[REDACTED:field]" : walk(val);
+        out[k] = sensitiveKeys.has(k.toLowerCase()) ? "[REDACTED:field]" : walk(val);
       }
       return out;
     }
@@ -43,10 +72,11 @@ function redactForIngestion(value, options = {}) {
 }
 function detectSpans(text, patterns = DEFAULT_REDACTION_PATTERNS) {
   const raw = [];
-  for (const { kind, pattern } of patterns) {
+  for (const { kind, pattern, validate } 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;
+      if (validate && !validate(m[0])) continue;
       raw.push({ kind, start: m.index, end: m.index + m[0].length, text: m[0] });
     }
   }
@@ -87,9 +117,10 @@ async function revealSpan(doc, spanId, options) {
 
 export {
   DEFAULT_REDACTION_PATTERNS,
+  maskSpans,
   redactForIngestion,
   detectSpans,
   buildRedactedDocument,
   revealSpan
 };
-//# sourceMappingURL=chunk-KWHLTXLE.js.map
+//# sourceMappingURL=chunk-5RMIUJDI.js.map

package/dist/chunk-5RMIUJDI.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  /** Optional predicate over each match — the pattern fires only when it returns\n   *  true. For matches a regex alone can't decide (e.g. a Luhn check on a\n   *  card-number candidate). When set, the value is scanned globally and the\n   *  first match that passes wins; when absent, a plain `pattern.test` decides. */\n  validate?: (match: string) => boolean\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  /** Extra sensitive object-key names (case-insensitive) added to the built-in\n   *  set, e.g. the snake_case `api_key` an intake form uses. Additive. */\n  extraSensitiveKeys?: readonly string[]\n  /**\n   * How a matched string is rewritten:\n   * - `'collapse'` (default) — the whole string becomes `[REDACTED:<kind>]` on\n   *   the first matching pattern. Safest for telemetry: nothing of the original\n   *   survives.\n   * - `'mask-spans'` — only the matched substrings are replaced (each with\n   *   `[REDACTED:<kind>]`), preserving surrounding text. Use when a downstream\n   *   reader needs the non-PII context (e.g. an analyst loop reading prose).\n   */\n  stringMode?: 'collapse' | 'mask-spans'\n}\n\nfunction redactString(value: string, patterns: readonly RedactionPattern[]): string {\n  for (const { kind, pattern, validate } of patterns) {\n    if (!validate) {\n      if (pattern.test(value)) return `[REDACTED:${kind}]`\n      continue\n    }\n    const g = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`)\n    for (const m of value.matchAll(g)) {\n      if (m[0].length > 0 && validate(m[0])) return `[REDACTED:${kind}]`\n    }\n  }\n  return value\n}\n\n/**\n * Replace only the PII substrings in `text`, preserving everything around them\n * (the `mask-spans` string mode). Built on {@link detectSpans} so matching,\n * non-overlap, and `validate` predicates behave identically to the reversible\n * path. Each span becomes `[REDACTED:<kind>]`.\n */\nexport function maskSpans(\n  text: string,\n  patterns: readonly RedactionPattern[] = DEFAULT_REDACTION_PATTERNS,\n): string {\n  const spans = detectSpans(text, patterns)\n  if (spans.length === 0) return text\n  let out = ''\n  let pos = 0\n  for (const s of spans) {\n    if (s.start > pos) out += text.slice(pos, s.start)\n    out += `[REDACTED:${s.kind}]`\n    pos = s.end\n  }\n  if (pos < text.length) out += text.slice(pos)\n  return out\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 sensitiveKeys = options.extraSensitiveKeys\n    ? new Set([...SENSITIVE_KEYS, ...options.extraSensitiveKeys.map((k) => k.toLowerCase())])\n    : SENSITIVE_KEYS\n  const maskString =\n    options.stringMode === 'mask-spans'\n      ? (s: string) => maskSpans(s, patterns)\n      : (s: string) => redactString(s, patterns)\n  // Cycle guard: a payload with a circular reference would otherwise recurse\n  // forever. On re-encountering an object/array, return it untouched to break\n  // the cycle (the same value was already redacted on its first visit).\n  const seen = new WeakSet<object>()\n  const walk = (v: unknown): unknown => {\n    if (typeof v === 'string') return maskString(v)\n    if (Array.isArray(v)) {\n      if (seen.has(v)) return v\n      seen.add(v)\n      return v.map(walk)\n    }\n    if (isPlainObject(v)) {\n      if (seen.has(v)) return v\n      seen.add(v)\n      const out: Record<string, unknown> = {}\n      for (const [k, val] of Object.entries(v)) {\n        out[k] = sensitiveKeys.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, validate } 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      if (validate && !validate(m[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 { BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, RedactForIngestionOptions, RedactedDocSegment, RedactedDocument, RedactionPattern, RedactionSpan, RevealResult, RevealSpanOptions, buildRedactedDocument, detectSpans, redactForIngestion, revealSpan } from './redact/index.js';
+export { BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, RedactForIngestionOptions, RedactedDocSegment, RedactedDocument, RedactionPattern, RedactionSpan, RevealResult, RevealSpanOptions, buildRedactedDocument, detectSpans, maskSpans, 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

@@ -2,9 +2,10 @@ import {
   DEFAULT_REDACTION_PATTERNS,
   buildRedactedDocument,
   detectSpans,
+  maskSpans,
   redactForIngestion,
   revealSpan
-} from "./chunk-KWHLTXLE.js";
+} from "./chunk-5RMIUJDI.js";
 import {
   DEFAULT_HARNESS,
   KNOWN_HARNESSES,
@@ -191,6 +192,7 @@ export {
   invokeIntegrationHub,
   isAppToolName,
   isHarness,
+  maskSpans,
   mergePersistedPart,
   messageHasTurnId,
   normalizeClientTurnId,

package/dist/redact/index.d.ts

@@ -23,6 +23,11 @@
 interface RedactionPattern {
     kind: string;
     pattern: RegExp;
+    /** Optional predicate over each match — the pattern fires only when it returns
+     *  true. For matches a regex alone can't decide (e.g. a Luhn check on a
+     *  card-number candidate). When set, the value is scanned globally and the
+     *  first match that passes wins; when absent, a plain `pattern.test` decides. */
+    validate?: (match: string) => boolean;
 }
 /** The default deterministic patterns. Extend via the `extraPatterns` /
  *  `patterns` options rather than forking this module (the seam that lets a
@@ -32,7 +37,27 @@ 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[];
+    /** Extra sensitive object-key names (case-insensitive) added to the built-in
+     *  set, e.g. the snake_case `api_key` an intake form uses. Additive. */
+    extraSensitiveKeys?: readonly string[];
+    /**
+     * How a matched string is rewritten:
+     * - `'collapse'` (default) — the whole string becomes `[REDACTED:<kind>]` on
+     *   the first matching pattern. Safest for telemetry: nothing of the original
+     *   survives.
+     * - `'mask-spans'` — only the matched substrings are replaced (each with
+     *   `[REDACTED:<kind>]`), preserving surrounding text. Use when a downstream
+     *   reader needs the non-PII context (e.g. an analyst loop reading prose).
+     */
+    stringMode?: 'collapse' | 'mask-spans';
 }
+/**
+ * Replace only the PII substrings in `text`, preserving everything around them
+ * (the `mask-spans` string mode). Built on {@link detectSpans} so matching,
+ * non-overlap, and `validate` predicates behave identically to the reversible
+ * path. Each span becomes `[REDACTED:<kind>]`.
+ */
+declare function maskSpans(text: string, patterns?: readonly RedactionPattern[]): string;
 /**
  * One-way PII scrub for telemetry/ingestion. Backward-compatible: called with no
  * options it behaves exactly as before (SSN/EIN strings + sensitive object keys
@@ -111,4 +136,4 @@ interface RevealResult {
  */
 declare function revealSpan(doc: RedactedDocument, spanId: string, options: RevealSpanOptions): Promise<RevealResult>;
 
-export { type BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, type RedactForIngestionOptions, type RedactedDocSegment, type RedactedDocument, type RedactionPattern, type RedactionSpan, type RevealResult, type RevealSpanOptions, buildRedactedDocument, detectSpans, redactForIngestion, revealSpan };
+export { type BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, type RedactForIngestionOptions, type RedactedDocSegment, type RedactedDocument, type RedactionPattern, type RedactionSpan, type RevealResult, type RevealSpanOptions, buildRedactedDocument, detectSpans, maskSpans, redactForIngestion, revealSpan };

package/dist/redact/index.js

@@ -2,13 +2,15 @@ import {
   DEFAULT_REDACTION_PATTERNS,
   buildRedactedDocument,
   detectSpans,
+  maskSpans,
   redactForIngestion,
   revealSpan
-} from "../chunk-KWHLTXLE.js";
+} from "../chunk-5RMIUJDI.js";
 export {
   DEFAULT_REDACTION_PATTERNS,
   buildRedactedDocument,
   detectSpans,
+  maskSpans,
   redactForIngestion,
   revealSpan
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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-KWHLTXLE.js.map

@@ -1 +0,0 @@
-{"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":[]}