@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/layers/agent-base/privacy/files/lib/privacy/detectors.ts

@@ -0,0 +1,179 @@
+// detectors — structured PII patterns. Each detector is pure: takes text,
+// returns spans. No state, no IO. Composes with the public detectPII()
+// API in index.ts.
+//
+// Coverage: structured PII that has a deterministic shape. Names,
+// addresses, and other semantic PII require a NER backend (see
+// nerBackend in index.ts) — those are NOT handled here.
+
+import type { PiiSpan, PiiType } from './types.js'
+
+interface Detector {
+  type: PiiType
+  scan: (text: string) => PiiSpan[]
+}
+
+// Luhn check for credit-card validation. Drops false positives like
+// 16-digit phone numbers or order IDs.
+function luhnValid(digits: string): boolean {
+  let sum = 0
+  let alt = false
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = digits.charCodeAt(i) - 48
+    if (n < 0 || n > 9) return false
+    if (alt) {
+      n *= 2
+      if (n > 9) n -= 9
+    }
+    sum += n
+    alt = !alt
+  }
+  return sum % 10 === 0
+}
+
+const SSN = {
+  type: 'ssn' as const,
+  scan(text: string): PiiSpan[] {
+    const re = /\b(?!000|666|9\d{2})(\d{3})[-\s]?(?!00)\d{2}[-\s]?(?!0000)\d{4}\b/g
+    const spans: PiiSpan[] = []
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      spans.push({ start: m.index, end: m.index + m[0].length, type: 'ssn', confidence: 'high', value: m[0] })
+    }
+    return spans
+  },
+}
+
+const EMAIL = {
+  type: 'email' as const,
+  scan(text: string): PiiSpan[] {
+    // RFC 5322-lite — covers practical addresses, rejects obvious nonsense.
+    const re = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g
+    const spans: PiiSpan[] = []
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      spans.push({ start: m.index, end: m.index + m[0].length, type: 'email', confidence: 'high', value: m[0] })
+    }
+    return spans
+  },
+}
+
+const PHONE = {
+  type: 'phone' as const,
+  scan(text: string): PiiSpan[] {
+    // North American + international leading-+ formats. Rejects sub-10-digit
+    // sequences (those are typically order IDs / part numbers).
+    const re = /\b(?:\+?1[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})\b|\+\d{2,4}[-.\s]?\d{3,5}[-.\s]?\d{3,5}\b/g
+    const spans: PiiSpan[] = []
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      spans.push({ start: m.index, end: m.index + m[0].length, type: 'phone', confidence: 'medium', value: m[0] })
+    }
+    return spans
+  },
+}
+
+const CREDIT_CARD = {
+  type: 'credit-card' as const,
+  scan(text: string): PiiSpan[] {
+    // Match 13-19 digit groups with separators, then Luhn-validate.
+    const re = /\b(?:\d[\s-]?){13,19}\b/g
+    const spans: PiiSpan[] = []
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      const digits = m[0].replace(/[\s-]/g, '')
+      if (digits.length >= 13 && digits.length <= 19 && luhnValid(digits)) {
+        spans.push({ start: m.index, end: m.index + m[0].length, type: 'credit-card', confidence: 'high', value: m[0] })
+      }
+    }
+    return spans
+  },
+}
+
+const IP_ADDRESS = {
+  type: 'ip' as const,
+  scan(text: string): PiiSpan[] {
+    const v4 = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d{1,2})\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d{1,2})\b/g
+    const v6 = /\b(?:[A-Fa-f0-9]{1,4}:){7}[A-Fa-f0-9]{1,4}\b|\b(?:[A-Fa-f0-9]{1,4}:){1,7}:\b|\b:(?::[A-Fa-f0-9]{1,4}){1,7}\b/g
+    const spans: PiiSpan[] = []
+    for (const re of [v4, v6]) {
+      let m: RegExpExecArray | null
+      while ((m = re.exec(text)) !== null) {
+        // Skip private/loopback ranges as low-PII (operator can opt-in via allow list)
+        const isPrivate = /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|127\.|::1)/.test(m[0])
+        spans.push({
+          start: m.index,
+          end: m.index + m[0].length,
+          type: 'ip',
+          confidence: isPrivate ? 'low' : 'medium',
+          value: m[0],
+        })
+      }
+    }
+    return spans
+  },
+}
+
+// API keys + tokens — high-confidence patterns from known providers.
+// Each entry: regex + provider name (for the redaction label).
+const API_KEY_PATTERNS: { re: RegExp; provider: string }[] = [
+  { re: /\bsk-[A-Za-z0-9]{32,}\b/g, provider: 'openai' },
+  { re: /\bsk-ant-[A-Za-z0-9-_]{32,}\b/g, provider: 'anthropic' },
+  { re: /\bsk-tan-[A-Za-z0-9-_]{20,}\b/g, provider: 'tangle' },
+  { re: /\bAKIA[0-9A-Z]{16}\b/g, provider: 'aws-access-key' },
+  { re: /\b(?:gh[pous]_[A-Za-z0-9]{36})\b/g, provider: 'github' },
+  { re: /\bxoxb-\d+-\d+-[A-Za-z0-9]+\b/g, provider: 'slack-bot' },
+  { re: /\b(?:eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})\b/g, provider: 'jwt' },
+  // M9 fix: explicit length cap (≤16384 chars between BEGIN/END) so an
+  // adversarial 100MB pseudo-PEM doesn't cause exponential regex scanning.
+  // Real PEM private keys are well under this cap (RSA 4096 ≈ 3.5KB armored).
+  { re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]{0,16384}?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, provider: 'pem-private-key' },
+]
+
+const API_KEY = {
+  type: 'api-key' as const,
+  scan(text: string): PiiSpan[] {
+    const spans: PiiSpan[] = []
+    for (const { re, provider } of API_KEY_PATTERNS) {
+      let m: RegExpExecArray | null
+      while ((m = re.exec(text)) !== null) {
+        spans.push({
+          start: m.index,
+          end: m.index + m[0].length,
+          type: 'api-key',
+          confidence: 'high',
+          value: m[0],
+          subtype: provider,
+        })
+      }
+    }
+    return spans
+  },
+}
+
+// Date of birth — only when a date appears alongside DOB-shaped context
+// markers ("DOB", "born", "birthday"). Bare dates are too ambiguous to
+// flag without the context anchor.
+const DATE_OF_BIRTH = {
+  type: 'dob' as const,
+  scan(text: string): PiiSpan[] {
+    const re = /\b(?:DOB|D\.O\.B\.|date of birth|born(?: on)?|birthday)\s*[:\s]*((?:19|20)\d{2}[-/]\d{1,2}[-/]\d{1,2}|\d{1,2}[-/]\d{1,2}[-/](?:19|20)?\d{2}|(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2},?\s+(?:19|20)?\d{2})/gi
+    const spans: PiiSpan[] = []
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      const dateStart = m.index + m[0].indexOf(m[1]!)
+      spans.push({ start: dateStart, end: dateStart + m[1]!.length, type: 'dob', confidence: 'high', value: m[1]! })
+    }
+    return spans
+  },
+}
+
+export const STRUCTURED_DETECTORS: readonly Detector[] = Object.freeze([
+  SSN,
+  EMAIL,
+  PHONE,
+  CREDIT_CARD,
+  IP_ADDRESS,
+  API_KEY,
+  DATE_OF_BIRTH,
+])

package/registry/layers/agent-base/privacy/files/lib/privacy/index.test.ts

@@ -0,0 +1,172 @@
+// Tests for agent-base:privacy. Adversarial: structured PII shapes that
+// trip naive regexes (Luhn-invalid card-shaped numbers, IPv6 corner cases,
+// SSN with reserved area numbers), idempotency on already-redacted text,
+// allow-list semantics, NER backend integration + error swallowing.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { detectPII, redactPII, assertNoPII } from './index.js'
+import type { PiiSpan } from './types.js'
+
+test('SSN: detects xxx-xx-xxxx', async () => {
+  const r = await detectPII('Patient SSN: 123-45-6789, please verify')
+  const ssn = r.spans.find((s) => s.type === 'ssn')
+  assert.ok(ssn)
+  assert.equal(ssn!.value, '123-45-6789')
+  assert.equal(ssn!.confidence, 'high')
+})
+
+test('SSN: rejects reserved area numbers (000, 666, 9xx)', async () => {
+  const r = await detectPII('Try 000-12-3456 or 666-12-3456 or 999-12-3456 — none are valid')
+  assert.equal(r.spans.filter((s) => s.type === 'ssn').length, 0)
+})
+
+test('SSN: rejects xx-xxxx with all zeros in group', async () => {
+  const r = await detectPII('123-00-4567 should not match (group of zeros)')
+  assert.equal(r.spans.filter((s) => s.type === 'ssn').length, 0)
+})
+
+test('Email: catches standard addresses', async () => {
+  const r = await detectPII('Contact alice@example.com or bob.smith+filter@sub.co.uk')
+  assert.equal(r.spans.filter((s) => s.type === 'email').length, 2)
+})
+
+test('Phone: detects NANP variants', async () => {
+  const cases = [
+    '(555) 123-4567',
+    '+1-555-123-4567',
+    '555.123.4567',
+    '5551234567',
+  ]
+  for (const c of cases) {
+    const r = await detectPII(`Call me at ${c} please`)
+    assert.ok(r.spans.find((s) => s.type === 'phone'), `should detect ${c}`)
+  }
+})
+
+test('Credit card: Luhn-validates', async () => {
+  // Real Luhn-valid Visa test number
+  const valid = '4111-1111-1111-1111'
+  const invalid = '1234-5678-9012-3456' // Luhn-invalid
+  const validR = await detectPII(`charge ${valid}`)
+  const invalidR = await detectPII(`reference ${invalid}`)
+  assert.ok(validR.spans.find((s) => s.type === 'credit-card'), 'valid Luhn should match')
+  assert.equal(invalidR.spans.filter((s) => s.type === 'credit-card').length, 0, 'invalid Luhn should NOT match')
+})
+
+test('IPv4: distinguishes private from public', async () => {
+  const r = await detectPII('Public 8.8.8.8 or private 192.168.1.1')
+  const ips = r.spans.filter((s) => s.type === 'ip')
+  assert.equal(ips.length, 2)
+  const pub = ips.find((s) => s.value === '8.8.8.8')
+  const priv = ips.find((s) => s.value === '192.168.1.1')
+  assert.equal(pub!.confidence, 'medium')
+  assert.equal(priv!.confidence, 'low')
+})
+
+test('API key: detects multi-provider', async () => {
+  const text = `OpenAI: sk-abc123def456ghi789jkl012mno345pqr678
+  Anthropic: sk-ant-api01-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+  Tangle: sk-tan-xyz789abc456def012
+  AWS: AKIAIOSFODNN7EXAMPLE
+  GitHub: ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`
+  const r = await detectPII(text)
+  const keys = r.spans.filter((s) => s.type === 'api-key')
+  assert.ok(keys.length >= 4, `expected ≥4 api keys, got ${keys.length}`)
+  assert.ok(keys.find((k) => k.subtype === 'openai'))
+  assert.ok(keys.find((k) => k.subtype === 'aws-access-key'))
+})
+
+test('DOB: requires context anchor', async () => {
+  const withContext = await detectPII('DOB: 1985-04-12, patient ID 42')
+  assert.ok(withContext.spans.find((s) => s.type === 'dob'))
+  // Without anchor, bare "1985-04-12" is too ambiguous.
+  const noContext = await detectPII('Schedule next quarterly review for 1985-04-12')
+  assert.equal(noContext.spans.filter((s) => s.type === 'dob').length, 0)
+})
+
+test('redactPII: default replaces with [REDACTED:type] preserving last-4 for ssn/cc', async () => {
+  const r = await redactPII('Patient 123-45-6789 paid 4111111111111111')
+  assert.ok(r.changed)
+  assert.match(r.redacted, /\[REDACTED:ssn:\*\*\*\*6789\]/)
+  assert.match(r.redacted, /\[REDACTED:credit-card:\*\*\*\*1111\]/)
+})
+
+test('redactPII: custom redactWith for field-aware policies', async () => {
+  const r = await redactPII('Email alice@example.com', {
+    redactWith: (span) => (span.type === 'email' ? '<email>' : `[${span.type}]`),
+  })
+  assert.match(r.redacted, /<email>/)
+})
+
+test('redactPII: idempotent — already-redacted text is unchanged', async () => {
+  const original = 'Patient SSN: [REDACTED:ssn:****6789] handled'
+  const r = await redactPII(original)
+  assert.equal(r.changed, false)
+  assert.equal(r.redacted, original)
+})
+
+test('allow list: skips specified types', async () => {
+  const r = await detectPII('Public 8.8.8.8 reachable from alice@example.com', { allow: ['ip'] })
+  assert.equal(r.spans.filter((s) => s.type === 'ip').length, 0)
+  assert.equal(r.spans.filter((s) => s.type === 'email').length, 1)
+})
+
+test('minConfidence floor: drops low-confidence spans', async () => {
+  const r = await detectPII('Internal 192.168.1.1 only', { minConfidence: 'medium' })
+  assert.equal(r.spans.filter((s) => s.type === 'ip').length, 0, 'low-confidence private IP should be dropped at medium floor')
+})
+
+test('nerBackend: integrates semantic spans', async () => {
+  const fakeNer = async (text: string): Promise<PiiSpan[]> => {
+    const idx = text.indexOf('John Smith')
+    if (idx < 0) return []
+    return [{ start: idx, end: idx + 'John Smith'.length, type: 'person-name', confidence: 'high', value: 'John Smith' }]
+  }
+  const r = await detectPII('Patient John Smith born 1960', { nerBackend: fakeNer })
+  assert.ok(r.spans.find((s) => s.type === 'person-name'))
+  assert.equal(r.semanticBackend, 'custom')
+})
+
+test('nerBackend: errors are swallowed; structured detection still runs', async () => {
+  const broken = async (): Promise<PiiSpan[]> => {
+    throw new Error('NER backend down')
+  }
+  const r = await detectPII('Email: test@example.com', { nerBackend: broken })
+  assert.ok(r.spans.find((s) => s.type === 'email'), 'structured detection should survive NER failure')
+})
+
+test('mergeOverlapping: higher-confidence span wins', async () => {
+  // The phone regex CAN match parts of an SSN due to digit count overlap.
+  // Verify the higher-confidence SSN match wins.
+  const r = await detectPII('SSN: 123-45-6789')
+  const ssn = r.spans.filter((s) => s.type === 'ssn')
+  assert.equal(ssn.length, 1)
+  // The phone detector wouldn't match this exact format, but if it did, SSN should win.
+})
+
+test('assertNoPII: throws on detection', async () => {
+  await assert.rejects(
+    () => assertNoPII('email: alice@example.com'),
+    /PII detected/,
+  )
+})
+
+test('assertNoPII: passes on clean text', async () => {
+  await assertNoPII('No sensitive data here, just a sentence')
+})
+
+test('detectPII: durationMs reported', async () => {
+  const r = await detectPII('alice@example.com')
+  assert.ok(r.durationMs >= 0)
+  assert.ok(typeof r.durationMs === 'number')
+})
+
+test('private key block: full PEM detected', async () => {
+  const pem = `-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+-----END RSA PRIVATE KEY-----`
+  const r = await detectPII(`Config:\n${pem}\nDone.`)
+  const keys = r.spans.filter((s) => s.type === 'api-key' && s.subtype === 'pem-private-key')
+  assert.equal(keys.length, 1)
+})

package/registry/layers/agent-base/privacy/files/lib/privacy/index.ts

@@ -0,0 +1,150 @@
+// agent-base:privacy — PII detection + redaction at intentional egress
+// points. Bundles call detectPII / redactPII before logging, forwarding,
+// or storing data that crossed a trust boundary.
+//
+// Threat model (what this primitive defends):
+//   - Output leak: agent writes its chain-of-thought to a log; PII in the
+//     reasoning lands in the observability vendor's storage.
+//   - Forward leak: agent forwards data to another agent / external API
+//     with more fields than the receiver needs.
+//
+// Threat model (what this does NOT defend):
+//   - The agent reading PHI from a webhook. The data IS the data; the
+//     filter scrubs at egress, not at ingress.
+//   - Network-level interception. That's TLS at the gateway.
+//   - The operator deliberately disabling the filter via `allow`.
+//
+// Composition: pure functions. Bundles pick which detectors apply,
+// which spans to allow, and what redaction shape to use. Per-egress
+// configuration, not global mutable state.
+
+import { STRUCTURED_DETECTORS } from './detectors.js'
+import type {
+  DetectResult,
+  PiiSpan,
+  PiiType,
+  RedactOptions,
+  RedactResult,
+} from './types.js'
+
+export type { PiiSpan, PiiType, RedactOptions, DetectResult, RedactResult } from './types.js'
+
+const CONFIDENCE_RANK: Record<PiiSpan['confidence'], number> = { high: 3, medium: 2, low: 1 }
+
+function defaultRedactWith(span: PiiSpan): string {
+  // Last-4 visible for credit-card and SSN by default — keep enough for
+  // record reconciliation, hide enough to avoid PCI/PII exposure. Bundles
+  // override via opts.redactWith when they need different policy.
+  if (span.type === 'credit-card' || span.type === 'ssn') {
+    const digits = span.value.replace(/\D/g, '')
+    return digits.length >= 4 ? `[REDACTED:${span.type}:****${digits.slice(-4)}]` : `[REDACTED:${span.type}]`
+  }
+  if (span.type === 'api-key' && span.subtype) {
+    return `[REDACTED:api-key:${span.subtype}]`
+  }
+  return `[REDACTED:${span.type}]`
+}
+
+function mergeOverlapping(spans: PiiSpan[]): PiiSpan[] {
+  if (spans.length === 0) return spans
+  const sorted = [...spans].sort((a, b) => a.start - b.start || b.end - a.end)
+  const out: PiiSpan[] = []
+  for (const span of sorted) {
+    const last = out[out.length - 1]
+    if (last && span.start < last.end) {
+      // Overlap — keep the higher-confidence one; if equal, the larger span.
+      const lastRank = CONFIDENCE_RANK[last.confidence]
+      const spanRank = CONFIDENCE_RANK[span.confidence]
+      if (spanRank > lastRank || (spanRank === lastRank && span.end - span.start > last.end - last.start)) {
+        out[out.length - 1] = span
+      }
+      continue
+    }
+    out.push(span)
+  }
+  return out
+}
+
+function passConfidenceFloor(span: PiiSpan, floor: PiiSpan['confidence']): boolean {
+  return CONFIDENCE_RANK[span.confidence] >= CONFIDENCE_RANK[floor]
+}
+
+/**
+ * Detect PII spans in `text`. Pure: no side effects, no logging, no env
+ * reads. Bundles wrap this in their own audit-logging if needed.
+ */
+export async function detectPII(text: string, opts: RedactOptions = {}): Promise<DetectResult> {
+  const t0 = performance.now()
+  const allow = new Set(opts.allow ?? [])
+  const minConfidence = opts.minConfidence ?? 'low'
+
+  // Structured detectors — synchronous, no IO.
+  let spans: PiiSpan[] = []
+  for (const detector of STRUCTURED_DETECTORS) {
+    if (allow.has(detector.type)) continue
+    spans.push(...detector.scan(text))
+  }
+
+  // Semantic detector — optional, async, errors caught.
+  let semanticBackend: DetectResult['semanticBackend'] = 'none'
+  if (opts.nerBackend) {
+    semanticBackend = 'custom'
+    try {
+      const nerSpans = await opts.nerBackend(text)
+      // NER returns whatever types it knows; respect allow list.
+      spans.push(...nerSpans.filter((s) => !allow.has(s.type)))
+    } catch (err) {
+      // Backend failure must NOT bypass detection; log to stderr and continue.
+      // Bundles that need a hard guarantee should call detectPII once and
+      // assert the result before egress.
+      process.stderr.write(`[agent-base:privacy] nerBackend error (continuing with structured detectors only): ${(err as Error).message}\n`)
+    }
+  }
+
+  spans = spans.filter((s) => passConfidenceFloor(s, minConfidence))
+  spans = mergeOverlapping(spans)
+
+  return { spans, semanticBackend, durationMs: Math.round(performance.now() - t0) }
+}
+
+/**
+ * Redact PII from `text`. Returns the redacted string + the spans that
+ * were redacted + a `changed` flag for fast-path logging.
+ *
+ * Idempotent: redacting an already-redacted string is a no-op (the
+ * `[REDACTED:...]` markers don't match any detector).
+ */
+export async function redactPII(text: string, opts: RedactOptions = {}): Promise<RedactResult> {
+  const t0 = performance.now()
+  const detection = await detectPII(text, opts)
+  if (detection.spans.length === 0) {
+    return { redacted: text, spans: [], changed: false, durationMs: Math.round(performance.now() - t0) }
+  }
+
+  const redactWith = opts.redactWith ?? defaultRedactWith
+  const sortedDesc = [...detection.spans].sort((a, b) => b.start - a.start)
+
+  let redacted = text
+  for (const span of sortedDesc) {
+    const replacement = redactWith(span, text)
+    redacted = redacted.slice(0, span.start) + replacement + redacted.slice(span.end)
+  }
+
+  return {
+    redacted,
+    spans: detection.spans,
+    changed: true,
+    durationMs: Math.round(performance.now() - t0),
+  }
+}
+
+/**
+ * Convenience: throw if PII is detected. Use in test harnesses or in
+ * deployments where unexpected PII at an egress point is a hard fault.
+ */
+export async function assertNoPII(text: string, opts: RedactOptions = {}): Promise<void> {
+  const detection = await detectPII(text, opts)
+  if (detection.spans.length === 0) return
+  const summary = detection.spans.map((s) => `${s.type}@${s.start}`).join(', ')
+  throw new Error(`PII detected: ${summary}`)
+}

package/registry/layers/agent-base/privacy/files/lib/privacy/types.ts

@@ -0,0 +1,66 @@
+// Shared types for the privacy layer.
+
+export type PiiType =
+  | 'ssn'
+  | 'email'
+  | 'phone'
+  | 'credit-card'
+  | 'ip'
+  | 'api-key'
+  | 'dob'
+  // Semantic types (require nerBackend):
+  | 'person-name'
+  | 'address'
+  | 'account-number'
+  | 'unknown'
+
+export interface PiiSpan {
+  /** Inclusive start offset into the source text. */
+  start: number
+  /** Exclusive end offset. */
+  end: number
+  type: PiiType
+  /** Hand-tuned per detector. NER backends should set their own. */
+  confidence: 'high' | 'medium' | 'low'
+  /** The matched substring; useful for logging and field-aware policies. */
+  value: string
+  /** For api-key spans: provider id (openai / anthropic / aws-access-key / ...). */
+  subtype?: string
+}
+
+export interface RedactOptions {
+  /** Custom redaction shape per span. Default: `[REDACTED:{type}]`.
+   * Receives the span and the original full text so callers can do
+   * field-aware partial redaction (e.g. last-4 SSN). */
+  redactWith?: (span: PiiSpan, original: string) => string
+  /** PII types to LEAVE alone. Default: []. Use cases:
+   *   - allow: ['ip']           // internal-network deployment
+   *   - allow: ['email', 'phone'] // CRM-like agent that intentionally retains
+   */
+  allow?: PiiType[]
+  /** Drop spans below this confidence. Default: 'low' (keep everything). */
+  minConfidence?: 'high' | 'medium' | 'low'
+  /** Optional NER backend for semantic PII (names, addresses, account numbers).
+   * Operator wires openai/privacy-filter, Microsoft Presidio, or AWS Comprehend
+   * here. Receives the full text; returns spans the structured detectors don't
+   * handle. Errors are caught and logged; never propagate. */
+  nerBackend?: (text: string) => Promise<PiiSpan[]>
+}
+
+export interface DetectResult {
+  /** Spans found, sorted by start offset, non-overlapping (overlaps merged
+   * with the higher-confidence type winning). */
+  spans: PiiSpan[]
+  /** Backend used for semantic detection (if any). */
+  semanticBackend?: 'none' | 'custom'
+  /** Time spent on detection, milliseconds. */
+  durationMs: number
+}
+
+export interface RedactResult {
+  redacted: string
+  spans: PiiSpan[]
+  /** True iff at least one span was redacted. */
+  changed: boolean
+  durationMs: number
+}

package/registry/layers/agent-base/privacy/manifest.json

@@ -0,0 +1,74 @@
+{
+  "id": "privacy",
+  "slot": "agent-base",
+  "description": "PII detection + redaction primitive for agent egress points. Structured detectors (SSN, email, phone, credit-card-with-Luhn, IPv4/v6, multi-provider API keys, contextual DOB) ship in the layer; semantic detection (person names, addresses) is delegated to an optional pluggable nerBackend (operator wires openai/privacy-filter, Microsoft Presidio, or AWS Comprehend as a subprocess). Pure functions; no global state; bundles call detectPII / redactPII / assertNoPII at the trust boundaries they own. Composes with agent-base:integrity for HMAC-signed forwarding of redacted payloads.",
+  "appliesTo": [
+    "agent-runtime-legal-counsel-ts",
+    "agent-runtime-tax-ts",
+    "agent-runtime-wealth-manager-ts",
+    "agent-runtime-auditor-ts",
+    "agent-runtime-recruiter-ts",
+    "agent-runtime-doctor-ts",
+    "multi-agent-legal-ops-ts"
+  ],
+  "provides": [
+    "privacy:detect",
+    "privacy:redact",
+    "privacy:assert-no-pii"
+  ],
+  "defaults": {
+    "privacyLayer": true,
+    "structuredDetectors": [
+      "ssn",
+      "email",
+      "phone",
+      "credit-card",
+      "ip",
+      "api-key",
+      "dob"
+    ],
+    "semanticBackend": "none-by-default-opt-in-via-bundle"
+  },
+  "files": [
+    {
+      "source": "files/lib/privacy/index.ts",
+      "target": "src/lib/privacy/index.ts"
+    },
+    {
+      "source": "files/lib/privacy/types.ts",
+      "target": "src/lib/privacy/types.ts"
+    },
+    {
+      "source": "files/lib/privacy/detectors.ts",
+      "target": "src/lib/privacy/detectors.ts"
+    },
+    {
+      "source": "files/lib/privacy/index.test.ts",
+      "target": "src/lib/privacy/index.test.ts"
+    },
+    {
+      "source": "files/lib/privacy/README.md",
+      "target": "src/lib/privacy/README.md"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/lib/privacy/index.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/privacy/types.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/privacy/detectors.ts"
+    }
+  ],
+  "contextHints": {
+    "extensionPoints": [
+      "src/lib/privacy/"
+    ],
+    "commands": []
+  }
+}