@edgeproc/privacy-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish Seshadri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @edgeproc/privacy-core
+
+A browser-side privacy boundary for LLM calls. Raw private text stays on your
+device; only **policy-approved, redacted** text is allowed to reach an external
+LLM; the model's reply is **rehydrated locally** so you see real values again.
+
+![The wow loop: paste a statement, preview exactly what leaves, send only placeholders, get a rehydrated answer.](docs/wow.png)
+
+## TL;DR
+
+- **What it is** — a TypeScript library that redacts sensitive text *before* it
+  leaves the browser, swapping each detected value for a typed placeholder
+  (`[CARD_1]`, `[NAME_2]`, `[AMOUNT_1]`), then restores the real values locally
+  when the model replies. You see and approve the exact text that will be sent.
+- **Why it works** — you can't send raw text by accident. The only way to hand
+  text to the model runs through the redaction step, and you see and approve the
+  exact placeholders-only version before anything is sent. If code tries to skip
+  that and send raw text, it won't even build — the safety is baked into the code
+  itself, not a rule you have to remember. (The mechanism is in
+  [Under the hood](#under-the-hood-for-developers).)
+- **Why it exists** — people paste bank statements, medical notes, and contracts
+  into chatbots every day, and all of it leaves the device in the clear. This
+  makes the boundary *visible and approvable* instead of invisible.
+- **Status** — `0.1.0`, graduated from a proven spike. Deterministic detection
+  spine + reversible **in-memory** vault + Egress Guard + redact→rehydrate loop +
+  runnable demo. Unpublished (pre-registry). The encrypted vault and contextual
+  NER are deliberately **deferred** — see [Roadmap](#roadmap).
+
+## Quickstart — one command, see the proof
+
+```bash
+# Node >= 22.13 and pnpm. Then, from the repo root:
+pnpm install && pnpm demo
+```
+
+Open <http://localhost:5173>. A synthetic bank statement is pre-loaded. You will
+see, top to bottom:
+
+1. **The raw text** you'd normally paste into a chatbot.
+2. **The redaction set + the exact wire payload** — every real value replaced by
+   a placeholder. Open your browser's network tab to confirm: only this redacted
+   text would leave the device.
+3. Click **Send**. By default it uses the offline echo provider (runs cold). To
+   call a real model, set `OPENROUTER_API_KEY` + `VITE_USE_OPENROUTER=1` (copy
+   `.env.example` → `examples/demo/.env`): the demo then routes through a
+   same-origin **dev proxy** that injects the key server-side, so it never
+   reaches the browser. Either way, **only placeholders cross the wire**.
+4. **The rehydrated answer** — placeholders swapped back to real values locally,
+   values that never left your machine.
+
+Prefer to see the guarantee enforced headlessly? `pnpm test:e2e` drives the loop
+in real chromium, intercepts the request, and asserts only placeholders cross the
+wire (the screenshot lands in the gitignored `test-results/`).
+
+## Use it as a library
+
+```ts
+import {
+  approve,
+  makeProvider,
+  redactForEgress,
+  rehydrate,
+  Vault,
+} from "@edgeproc/privacy-core";
+
+const vault = new Vault();
+const { provider } = makeProvider({ apiKey: process.env.OPENROUTER_API_KEY });
+
+// detect + vault-write + brand — produces a PendingRedaction: a review PROPOSAL,
+// not yet sendable (no provider will accept it).
+const pending = await redactForEgress(rawStatement, vault);
+
+// The explicit review step turns the proposal into a sendable RedactedPayload.
+// The audit sink is REQUIRED, so every approval is observable.
+const payload = approve(pending, (entry) => console.log(entry));
+
+// provider.complete accepts ONLY a RedactedPayload — raw text won't compile.
+const response = await provider.complete(payload);
+
+// restore real values locally, on-device — bound to the payload's vault.
+const answer = rehydrate(response.redactedText, vault, payload.vaultRef);
+```
+
+## The honest hard truth (read this first, it is not a footnote)
+
+Two limits define what this can and cannot promise. Stating them up front is the
+point — over-claiming privacy is worse than claiming none.
+
+- **Detection recall *is* the product. Anything the detector misses leaks
+  silently.** No redactor catches everything: regex misses oddly-formatted
+  values, NER misses unusual names, novel PII types are invisible to both. So v0
+  does **not** promise "we redact everything." The v0 guarantee is scoped to
+  **user-confirmed redaction**: the human reviews the proposed redaction set in
+  the preview and approves it before send. Misses are caught by a person, not
+  promised away by the tool. The guard's job is to make the boundary *visible and
+  approvable*, not to claim perfect detection.
+
+- **Redaction is not anonymization.** Even with every literal identifier removed,
+  the *structure* still leaks a behavioral fingerprint. "`$482.10` + the word
+  *insurance* + *early January*" can re-identify a person even though no name,
+  card, or SSN survived. Privacy-core reduces direct identifier leakage; it does
+  **not** make data anonymous, and it does not defend against a determined
+  re-identification attack. Generalization modes (amount bucketing, date
+  coarsening) that would start to address this are explicitly **deferred**.
+
+If those two limits are unacceptable for a use case, this is the wrong tool.
+
+---
+
+## Under the hood (for developers)
+
+The "it won't even build" guarantee is a **type-enforced Egress Guard**, not a
+convention. Provider adapters accept *only* a branded `RedactedPayload`, whose
+sole constructor is the redaction pipeline (`redactForEgress` → `approve`). A
+raw `string` is not assignable to that type, so **handing raw text to a provider
+is a compile error** — not a discipline you have to remember. `pnpm build` (tsc)
+proves it on every build.
+
+The same guarantee is re-checked at runtime so a cast can't defeat it: every
+approved payload is registered by identity, and `assertApproved()` rejects a
+hand-forged or spread-cloned look-alike before any network call is made.
+
+## Architecture — maps 1:1 to `src/`
+
+```text
+src/
+├── index.ts            # public API barrel — the production surface, nothing else
+├── types.ts            # shared domain types (EntityType, Span, AuditEntry, …)
+├── egress.ts           # the moat: branded RedactedPayload + LlmProvider + unsafeBypass
+├── redact.ts           # redactForEgress — the ONLY legitimate payload constructor
+├── rehydrate.ts        # local restore of real values after the reply
+├── vault.ts            # Vault — reversible token<->value map (in-memory, v0)
+├── detect/
+│   ├── detector.ts     # detect() — merges patterns + dictionaries, drops overlaps
+│   ├── patterns.ts     # the deterministic ruleset (generic + finance packs)
+│   └── checksums.ts    # Luhn (cards) + IBAN mod-97
+├── providers/
+│   ├── factory.ts      # makeProvider — picks OpenRouter or the offline echo
+│   ├── nollm.ts        # NoLLMProvider — offline echo, runs with no API key
+│   └── openrouter.ts   # OpenRouterProvider — OpenAI-compatible chat/completions
+└── testing.ts          # SYNTHETIC_STATEMENT fixture — via the ./testing subpath,
+                        #   NEVER from the main barrel
+```
+
+The flow is the portfolio's deterministic-core law: a fast, deterministic
+detection **spine** (`detect`) plus a bounded, optional inference adapter (the
+NER tier — deferred). The net-new product IP is the reversible loop + vault +
+the type-enforced Egress Guard.
+
+### Public API
+
+Everything `src/index.ts` exports, and nothing more:
+
+| Export | Kind | Role |
+|---|---|---|
+| `detect` | fn | deterministic PII span detection |
+| `redactForEgress` | fn | detect → vault-write → brand → a `PendingRedaction` proposal |
+| `approve` | fn | explicit review step → mints the sendable payload (audit sink required) |
+| `rehydrate` | fn | restore real values locally from placeholders |
+| `Vault` | class | reversible token↔value map |
+| `RedactedPayload` | type | the branded egress type |
+| `LlmProvider` | interface | provider contract — accepts only `RedactedPayload` |
+| `NoLLMProvider` | class | offline echo provider |
+| `OpenRouterProvider` | class | OpenAI-compatible provider |
+| `makeProvider` | fn | env-driven provider selector |
+| `guardedProvider` | fn | wrap a provider so the runtime egress guard runs at one chokepoint |
+| `unsafeBypass` | fn | the explicit, audited escape hatch |
+
+The brand factory (`mintPendingRedaction`) and the `SYNTHETIC_STATEMENT` fixture
+are intentionally **not** on the front door — a payload can be earned, not
+forged, and a fixture is never shipped by accident.
+
+## Roadmap (explicitly deferred — not shipped in 0.1.0)
+
+Labeled so no one mistakes it for current scope:
+
+- **Encrypted IndexedDB vault** (AES-GCM + passphrase KDF). v0 uses an
+  **in-memory** vault that clears on reload — plainly stated, by design.
+- **Contextual NER adapter** (names/merchants/locations regex misses) — depends
+  on the not-yet-extracted `@edgeproc/browser` runtime; off by default.
+- **Audit-log persistence** (the audit sink is wired today; durable storage is
+  deferred).
+- **More domain packs** (medical, legal, HR, identity) beyond the lifted generic
+  + finance set, and **generalization / anonymization** modes.
+
+## License
+
+MIT. Recognizer patterns are ported from Microsoft Presidio (MIT); the
+redact/rehydrate vault design follows LLM Guard's `Anonymize`/`Vault` (MIT),
+reimplemented here in TypeScript.

package/dist/detect/checksums.d.ts

@@ -0,0 +1,5 @@
+/** Luhn check for card numbers (digits only). */
+export declare function luhnValid(digits: string): boolean;
+/** ISO 13616 IBAN mod-97 check. */
+export declare function ibanValid(raw: string): boolean;
+//# sourceMappingURL=checksums.d.ts.map

package/dist/detect/checksums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksums.d.ts","sourceRoot":"","sources":["../../src/detect/checksums.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAejD;AAWD,mCAAmC;AACnC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ9C"}

package/dist/detect/checksums.js

@@ -0,0 +1,37 @@
+/** Luhn check for card numbers (digits only). */
+export function luhnValid(digits) {
+    const d = digits.replace(/\D/g, "");
+    if (d.length < 13 || d.length > 19)
+        return false;
+    let sum = 0;
+    let dbl = false;
+    for (let i = d.length - 1; i >= 0; i--) {
+        let n = d.charCodeAt(i) - 48;
+        if (dbl) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        dbl = !dbl;
+    }
+    return sum % 10 === 0;
+}
+/** Compute n mod 97 over a decimal string too large for Number. */
+function mod97(numeric) {
+    let remainder = 0;
+    for (const ch of numeric) {
+        remainder = (remainder * 10 + (ch.charCodeAt(0) - 48)) % 97;
+    }
+    return remainder;
+}
+/** ISO 13616 IBAN mod-97 check. */
+export function ibanValid(raw) {
+    const s = raw.replace(/\s+/g, "").toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{1,30}$/.test(s))
+        return false;
+    const rearranged = s.slice(4) + s.slice(0, 4);
+    const expanded = rearranged.replace(/[A-Z]/g, (c) => String(c.charCodeAt(0) - 55));
+    return mod97(expanded) === 1;
+}
+//# sourceMappingURL=checksums.js.map

package/dist/detect/checksums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksums.js","sourceRoot":"","sources":["../../src/detect/checksums.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,GAAG,EAAE,CAAC;YACR,CAAC,IAAI,CAAC,CAAC;YACP,IAAI,CAAC,GAAG,CAAC;gBAAE,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,GAAG,IAAI,CAAC,CAAC;QACT,GAAG,GAAG,CAAC,GAAG,CAAC;IACb,CAAC;IACD,OAAO,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;AACxB,CAAC;AAED,mEAAmE;AACnE,SAAS,KAAK,CAAC,OAAe;IAC5B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,SAAS,GAAG,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAChD,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAClD,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAC7B,CAAC;IACF,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}

package/dist/detect/detector.d.ts

@@ -0,0 +1,12 @@
+import type { Span } from "../types.js";
+/**
+ * Detect all PII spans deterministically: structured patterns + checksums plus
+ * the finance/name dictionaries. Overlaps are dropped; the result is sorted by
+ * start offset and non-overlapping.
+ *
+ * Recall is the product: anything not matched here leaks unless a human catches
+ * it in the preview. The contextual NER tier that would widen recall is
+ * deliberately deferred (see Roadmap).
+ */
+export declare function detect(text: string): Span[];
+//# sourceMappingURL=detector.d.ts.map

package/dist/detect/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/detect/detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,IAAI,EAAE,MAAM,aAAa,CAAC;AAiDpD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,CAO3C"}

package/dist/detect/detector.js

@@ -0,0 +1,57 @@
+import { MERCHANTS, NAMES, RULES } from "./patterns.js";
+function dictSpans(text, type, dict) {
+    const out = [];
+    for (const term of dict) {
+        let from = 0;
+        let idx = text.indexOf(term, from);
+        while (idx !== -1) {
+            out.push({ type, value: term, start: idx, end: idx + term.length });
+            from = idx + term.length;
+            idx = text.indexOf(term, from);
+        }
+    }
+    return out;
+}
+function regexSpans(text, rule) {
+    const out = [];
+    for (const m of text.matchAll(rule.re)) {
+        // If the rule has a capture group, that group is the value; else whole match.
+        const value = m[1] ?? m[0];
+        if (rule.accept && !rule.accept(value))
+            continue;
+        const start = m.index + m[0].indexOf(value);
+        out.push({ type: rule.type, value, start, end: start + value.length });
+    }
+    return out;
+}
+/** Drop overlapping spans (earlier/longer wins), keeping a sorted, disjoint set. */
+function dropOverlaps(spans) {
+    const sorted = [...spans].sort((a, b) => a.start - b.start || b.end - b.start - (a.end - a.start));
+    const kept = [];
+    let lastEnd = -1;
+    for (const s of sorted) {
+        if (s.start >= lastEnd) {
+            kept.push(s);
+            lastEnd = s.end;
+        }
+    }
+    return kept;
+}
+/**
+ * Detect all PII spans deterministically: structured patterns + checksums plus
+ * the finance/name dictionaries. Overlaps are dropped; the result is sorted by
+ * start offset and non-overlapping.
+ *
+ * Recall is the product: anything not matched here leaks unless a human catches
+ * it in the preview. The contextual NER tier that would widen recall is
+ * deliberately deferred (see Roadmap).
+ */
+export function detect(text) {
+    const all = [
+        ...RULES.flatMap((r) => regexSpans(text, r)),
+        ...dictSpans(text, "MERCHANT", MERCHANTS),
+        ...dictSpans(text, "NAME", NAMES),
+    ];
+    return dropOverlaps(all);
+}
+//# sourceMappingURL=detector.js.map

package/dist/detect/detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../src/detect/detector.ts"],"names":[],"mappings":"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"}

package/dist/detect/patterns.d.ts

@@ -0,0 +1,22 @@
+import type { EntityType } from "../types.js";
+/** A regex recognizer, optionally gated by a checksum/structure accept-test. */
+export interface Rule {
+    readonly type: EntityType;
+    readonly re: RegExp;
+    readonly accept?: (match: string) => boolean;
+}
+/**
+ * The Tier-1 deterministic ruleset (generic + finance packs, v0 scope).
+ * Patterns + checksums are ported from Microsoft Presidio's recognizer set;
+ * we reuse the durable, well-tested structure, not Presidio's Python runtime.
+ */
+export declare const RULES: readonly Rule[];
+/** The finance pack's merchant name set (deterministic dictionary lookup). */
+export declare const MERCHANTS: readonly string[];
+/**
+ * A tiny known-names dictionary. Real name coverage is the job of the deferred
+ * NER adapter (see Roadmap); this keeps the deterministic spine self-contained
+ * and the wow-demo runnable with zero download.
+ */
+export declare const NAMES: readonly string[];
+//# sourceMappingURL=patterns.d.ts.map

package/dist/detect/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/detect/patterns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,gFAAgF;AAChF,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAC9C;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAcvB,CAAC;AAEX,8EAA8E;AAC9E,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAM7B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,MAAM,EAIzB,CAAC"}

package/dist/detect/patterns.js

@@ -0,0 +1,40 @@
+import { ibanValid, luhnValid } from "./checksums.js";
+/**
+ * The Tier-1 deterministic ruleset (generic + finance packs, v0 scope).
+ * Patterns + checksums are ported from Microsoft Presidio's recognizer set;
+ * we reuse the durable, well-tested structure, not Presidio's Python runtime.
+ */
+export const RULES = [
+    { type: "EMAIL", re: /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g },
+    {
+        type: "IBAN",
+        re: /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{2,4})+\b/g,
+        accept: ibanValid,
+    },
+    { type: "CARD", re: /\b(?:\d[ -]?){13,19}\b/g, accept: luhnValid },
+    { type: "SSN", re: /\b\d{3}-\d{2}-\d{4}\b/g },
+    { type: "ROUTING", re: /\bRouting number:\s*(\d{9})\b/g },
+    { type: "ACCOUNT", re: /\bAccount number:\s*(\d{9,12})\b/g },
+    { type: "PHONE", re: /\(\d{3}\)\s?\d{3}-\d{4}\b/g },
+    { type: "AMOUNT", re: /\$\d{1,3}(?:,\d{3})*(?:\.\d{2})?\b/g },
+    { type: "DATE", re: /\b\d{2}\/\d{2}\/\d{4}\b/g },
+];
+/** The finance pack's merchant name set (deterministic dictionary lookup). */
+export const MERCHANTS = [
+    "Whole Foods",
+    "Starbucks",
+    "Amazon",
+    "Walmart",
+    "Costco",
+];
+/**
+ * A tiny known-names dictionary. Real name coverage is the job of the deferred
+ * NER adapter (see Roadmap); this keeps the deterministic spine self-contained
+ * and the wow-demo runnable with zero download.
+ */
+export const NAMES = [
+    "Ada Lovelace",
+    "Grace Hopper",
+    "Alan Turing",
+];
+//# sourceMappingURL=patterns.js.map

package/dist/detect/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../src/detect/patterns.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAStD;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAoB;IACpC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,+BAA+B,EAAE;IACtD;QACE,IAAI,EAAE,MAAM;QACZ,EAAE,EAAE,yCAAyC;QAC7C,MAAM,EAAE,SAAS;KAClB;IACD,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,yBAAyB,EAAE,MAAM,EAAE,SAAS,EAAE;IAClE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,wBAAwB,EAAE;IAC7C,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,gCAAgC,EAAE;IACzD,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,mCAAmC,EAAE;IAC5D,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,4BAA4B,EAAE;IACnD,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,qCAAqC,EAAE;IAC7D,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,0BAA0B,EAAE;CACxC,CAAC;AAEX,8EAA8E;AAC9E,MAAM,CAAC,MAAM,SAAS,GAAsB;IAC1C,aAAa;IACb,WAAW;IACX,QAAQ;IACR,SAAS;IACT,QAAQ;CACA,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsB;IACtC,cAAc;IACd,cAAc;IACd,aAAa;CACL,CAAC"}

package/dist/egress.d.ts

@@ -0,0 +1,85 @@
+import { type EgressGovernance } from "./egressReceipt.js";
+import type { AuditSink, VaultRef } from "./types.js";
+/**
+ * The egress boundary, expressed as a capability earned in two explicit steps:
+ *
+ *  1. `redactForEgress` mints a {@link PendingRedaction} — a review PROPOSAL.
+ *     It is not sendable; no provider accepts it. Zero detections do NOT relax
+ *     this: an empty redaction set still requires the explicit review step,
+ *     because "the detector found nothing" is not the same as "a reviewer
+ *     approved this content to leave the device".
+ *  2. `approve` — the explicit review action — converts a pipeline-minted
+ *     pending into a {@link RedactedPayload}, the sendable capability.
+ *
+ * Both types carry a compile-time phantom brand (a raw `string` or hand-rolled
+ * object literal is not assignable), and every value minted here is registered
+ * in a module-private WeakSet so the capability also holds at RUNTIME in plain
+ * JS — a structurally identical forgery is rejected by {@link approve} and by
+ * every provider adapter (via {@link assertApproved}).
+ */
+declare const brand: unique symbol;
+interface Branded<B extends string> {
+    readonly [brand]: B;
+}
+/** A redaction proposal awaiting explicit review. NOT sendable. */
+export type PendingRedaction = Branded<"PendingRedaction"> & {
+    readonly redactedText: string;
+    readonly vaultRef: VaultRef;
+    /** The placeholder tokens the reviewer is being asked to approve. */
+    readonly placeholders: readonly string[];
+};
+/** The sendable capability: reviewed, redacted content — never raw content. */
+export type RedactedPayload = Branded<"RedactedPayload"> & {
+    readonly redactedText: string;
+    readonly vaultRef: VaultRef;
+    readonly approvedAt: number;
+};
+/** The egress boundary: providers accept ONLY an approved RedactedPayload. */
+export interface LlmProvider {
+    complete(payload: RedactedPayload): Promise<import("./types.js").RedactedResponse>;
+}
+/**
+ * Runtime half of the egress guard. Every provider adapter MUST call this
+ * before doing anything with a payload; it rejects any object that was not
+ * minted by {@link approve} or {@link unsafeBypass} — TypeScript branding
+ * alone cannot stop a plain-JS caller, this check does.
+ */
+export declare function assertApproved(payload: RedactedPayload): void;
+/**
+ * Internal factory used by the redact pipeline. Intentionally NOT re-exported
+ * from the public barrel — a pending is earned from detection, not built.
+ */
+export declare function mintPendingRedaction(redactedText: string, vaultRef: VaultRef, placeholders: readonly string[]): PendingRedaction;
+/**
+ * THE explicit approval step — the only way a PendingRedaction becomes
+ * sendable. Approval is a deliberate human/reviewer action, never a side
+ * effect: even a zero-detection result passes through here. It refuses any
+ * object the pipeline did not mint (a hand-built "pending" would smuggle
+ * unreviewed text past the guard).
+ *
+ * The `audit` sink is REQUIRED — an approval that no one can observe is not
+ * an approval this boundary will grant. (Same stance as {@link unsafeBypass}.)
+ */
+export declare function approve(pending: PendingRedaction, audit: AuditSink): RedactedPayload;
+/**
+ * Wrap any {@link LlmProvider} so the runtime egress guard runs at ONE
+ * chokepoint before the inner provider ever sees the payload. TypeScript's
+ * brand stops a raw string at compile time, but a hand-rolled or third-party
+ * provider could still forget to call {@link assertApproved} at runtime — this
+ * wrapper makes that impossible for any provider obtained through it.
+ *
+ * With `governance`, the chokepoint additionally seals EVERY decision — each
+ * allow and each fail-closed deny — as a signed Avow effect receipt (see
+ * {@link file://./egressReceipt.ts}). The deny receipt digests the redacted
+ * text that was ATTEMPTED, and only its hash; nothing reaches the inner
+ * provider on a deny either way.
+ */
+export declare function guardedProvider(inner: LlmProvider, governance?: EgressGovernance): LlmProvider;
+/**
+ * The explicit, named, audited escape hatch — the ONLY way raw text can be
+ * made sendable without going through detection + review. It cannot be silent:
+ * it always emits an audit entry recording the human-supplied reason.
+ */
+export declare function unsafeBypass(raw: string, reason: string, audit: AuditSink): RedactedPayload;
+export {};
+//# sourceMappingURL=egress.d.ts.map

package/dist/egress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,CAAC,MAAM,KAAK,EAAE,OAAO,MAAM,CAAC;AAEnC,UAAU,OAAO,CAAC,CAAC,SAAS,MAAM;IAChC,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CACN,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,OAAO,YAAY,EAAE,gBAAgB,CAAC,CAAC;CACnD;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAO7D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,gBAAgB,CAIlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,SAAS,GACf,eAAe,CAmBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,UAAU,CAAC,EAAE,gBAAgB,GAC5B,WAAW,CAab;AAuBD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,GACf,eAAe,CASjB"}

package/dist/egress.js

@@ -0,0 +1,115 @@
+import { sealEgressReceipt, } from "./egressReceipt.js";
+import { ForgedPayloadError, UnapprovedPayloadError } from "./errors.js";
+/** Module-private: every pending the redaction pipeline actually minted. */
+const mintedPending = new WeakSet();
+/**
+ * Module-private: every payload the guard actually approved. A WeakSet keyed
+ * by object IDENTITY — callers cannot reproduce membership by building a
+ * structurally identical object, and entries vanish with the payloads.
+ */
+const approvedPayloads = new WeakSet();
+/**
+ * Runtime half of the egress guard. Every provider adapter MUST call this
+ * before doing anything with a payload; it rejects any object that was not
+ * minted by {@link approve} or {@link unsafeBypass} — TypeScript branding
+ * alone cannot stop a plain-JS caller, this check does.
+ */
+export function assertApproved(payload) {
+    if (!approvedPayloads.has(payload)) {
+        throw new UnapprovedPayloadError("payload was not approved by the egress guard — providers only accept " +
+            "the capability minted by approve() (or the audited unsafeBypass)");
+    }
+}
+/**
+ * Internal factory used by the redact pipeline. Intentionally NOT re-exported
+ * from the public barrel — a pending is earned from detection, not built.
+ */
+export function mintPendingRedaction(redactedText, vaultRef, placeholders) {
+    const pending = Object.freeze({ redactedText, vaultRef, placeholders });
+    mintedPending.add(pending);
+    return pending;
+}
+/**
+ * THE explicit approval step — the only way a PendingRedaction becomes
+ * sendable. Approval is a deliberate human/reviewer action, never a side
+ * effect: even a zero-detection result passes through here. It refuses any
+ * object the pipeline did not mint (a hand-built "pending" would smuggle
+ * unreviewed text past the guard).
+ *
+ * The `audit` sink is REQUIRED — an approval that no one can observe is not
+ * an approval this boundary will grant. (Same stance as {@link unsafeBypass}.)
+ */
+export function approve(pending, audit) {
+    if (!mintedPending.has(pending)) {
+        throw new ForgedPayloadError("approve() only accepts a PendingRedaction minted by redactForEgress — " +
+            "hand-built objects are rejected so unreviewed text cannot be approved");
+    }
+    const payload = Object.freeze({
+        redactedText: pending.redactedText,
+        vaultRef: pending.vaultRef,
+        approvedAt: Date.now(),
+    });
+    approvedPayloads.add(payload);
+    audit({
+        kind: "approve",
+        at: payload.approvedAt,
+        placeholders: pending.placeholders,
+    });
+    return payload;
+}
+/**
+ * Wrap any {@link LlmProvider} so the runtime egress guard runs at ONE
+ * chokepoint before the inner provider ever sees the payload. TypeScript's
+ * brand stops a raw string at compile time, but a hand-rolled or third-party
+ * provider could still forget to call {@link assertApproved} at runtime — this
+ * wrapper makes that impossible for any provider obtained through it.
+ *
+ * With `governance`, the chokepoint additionally seals EVERY decision — each
+ * allow and each fail-closed deny — as a signed Avow effect receipt (see
+ * {@link file://./egressReceipt.ts}). The deny receipt digests the redacted
+ * text that was ATTEMPTED, and only its hash; nothing reaches the inner
+ * provider on a deny either way.
+ */
+export function guardedProvider(inner, governance) {
+    return {
+        async complete(payload) {
+            try {
+                assertApproved(payload);
+            }
+            catch (denied) {
+                await sealDecision(governance, payload.redactedText, "deny");
+                throw denied;
+            }
+            await sealDecision(governance, payload.redactedText, "allow");
+            return inner.complete(payload);
+        },
+    };
+}
+/** Seal one guard decision and hand it to the governance sink, if governed. */
+async function sealDecision(governance, redactedText, decision) {
+    if (!governance)
+        return;
+    const { provider, seedHex, onReceipt, detectorVersion } = governance;
+    onReceipt(await sealEgressReceipt({
+        provider,
+        redactedText,
+        decision,
+        ...(detectorVersion === undefined ? {} : { detectorVersion }),
+    }, seedHex));
+}
+/**
+ * The explicit, named, audited escape hatch — the ONLY way raw text can be
+ * made sendable without going through detection + review. It cannot be silent:
+ * it always emits an audit entry recording the human-supplied reason.
+ */
+export function unsafeBypass(raw, reason, audit) {
+    audit({ kind: "unsafe-bypass", at: Date.now(), reason });
+    const payload = Object.freeze({
+        redactedText: raw,
+        vaultRef: { id: "unsafe-no-vault" },
+        approvedAt: Date.now(),
+    });
+    approvedPayloads.add(payload);
+    return payload;
+}
+//# sourceMappingURL=egress.js.map

package/dist/egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"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"}