@edgeproc/privacy-core 0.2.0 → 0.2.1

package/README.md

@@ -1,60 +1,61 @@
 # @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
+You get a letter from a doctor, or a bank statement with a charge you don't
+recognize, and you want an AI chatbot to explain it. So you paste the whole
+thing in — your name, your phone number, your card number, all of it — because
+that's the only way to get the answer.
 
-```bash
-# Node >= 22.13 and pnpm. Then, from the repo root:
-pnpm install && pnpm demo
+This library is the other way around. It finds the private bits **on your own
+device**, swaps each one for a label like `[CARD_1]`, and sends only the
+labeled version to the model. When the answer comes back, it puts your real
+values back in, locally. The model helps you. The model never sees you.
+
+Here is the whole idea. Say you paste this:
+
+```text
+I want to dispute a charge on my card.
+Account holder: Grace Hopper
+Email: grace.hopper@example.com
+Phone: (415) 555-0132
+Card on file: 4242 4242 4242 4242
+On 01/14/2026 I was charged $482.10 at Whole Foods and I was never there.
+```
+
+This is what actually leaves your device:
+
+```text
+I want to dispute a charge on my card.
+Account holder: [NAME_1]
+Email: [EMAIL_1]
+Phone: [PHONE_1]
+Card on file: [CARD_1]
+On [DATE_1] I was charged [AMOUNT_1] at [MERCHANT_1] and I was never there.
 ```
 
-Open <http://localhost:5173>. A synthetic bank statement is pre-loaded. You will
-see, top to bottom:
+The model writes its reply about `[NAME_1]` and `[CARD_1]`. Before you read it,
+the library swaps the real values back in — on your machine, from a table the
+model was never shown. You see a normal answer about Grace Hopper's card.
 
-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.
+Three words you'll see below, defined once:
 
-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/`).
+- **redact** — replace a private value with a label.
+- **rehydrate** — put the real value back when the answer returns.
+- **egress** — anything leaving your device for the network.
 
-## Use it as a library
+## Run it yourself in one minute
 
-```ts
+You need [Node](https://nodejs.org) 22.13 or newer. No API key, no account —
+the loop runs against a built-in offline stand-in model.
+
+```bash
+mkdir privacy-try && cd privacy-try
+npm init -y && npm pkg set type=module
+npm install @edgeproc/privacy-core
+```
+
+Save this as `try-it.mjs`:
+
+```js
 import {
   approve,
   makeProvider,
@@ -63,62 +64,227 @@ import {
   Vault,
 } from "@edgeproc/privacy-core";
 
+// The thing you'd normally paste straight into a chatbot.
+const statement = `I want to dispute a charge on my card.
+Account holder: Grace Hopper
+Email: grace.hopper@example.com
+Phone: (415) 555-0132
+Card on file: 4242 4242 4242 4242
+On 01/14/2026 I was charged $482.10 at Whole Foods and I was never there.`;
+
+// The vault holds your real values. It lives in this process, on this machine.
 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);
+// 1. REDACT — swap every detected value for a label.
+const pending = await redactForEgress(statement, vault);
+console.log("--- what would leave your device ---");
+console.log(pending.redactedText);
+
+// 2. APPROVE — you read the above and say yes. Nothing is sendable until you do.
+const payload = approve(pending, (entry) => console.log("\n[audit]", entry.kind));
+
+// 3. SEND — with no API key, this uses a built-in offline stand-in model.
+const { provider, label } = makeProvider();
+const reply = await provider.complete(payload);
+console.log(`\n--- reply from ${label} — it only ever saw the text above ---`);
+console.log(reply.redactedText);
+
+// 4. REHYDRATE — put your real values back, locally.
+console.log("\n--- what you actually read ---");
+console.log(rehydrate(reply.redactedText, vault, payload.vaultRef));
+```
+
+Then `node try-it.mjs`. You get:
 
-// 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));
+```text
+--- what would leave your device ---
+I want to dispute a charge on my card.
+Account holder: [NAME_1]
+Email: [EMAIL_1]
+Phone: [PHONE_1]
+Card on file: [CARD_1]
+On [DATE_1] I was charged [AMOUNT_1] at [MERCHANT_1] and I was never there.
+
+[audit] approve
+
+--- reply from NoLLMProvider (offline echo) — it only ever saw the text above ---
+Summary (offline echo — no API key set):
+I reviewed your statement. It referenced 7 redacted value(s): [NAME_1], [EMAIL_1], [PHONE_1], [CARD_1], [DATE_1], [AMOUNT_1], [MERCHANT_1].
+The first flagged value, [NAME_1], is the one to check.
+(Set OPENROUTER_API_KEY + VITE_USE_OPENROUTER=1 to call a real model via the dev proxy.)
+
+--- what you actually read ---
+Summary (offline echo — no API key set):
+I reviewed your statement. It referenced 7 redacted value(s): Grace Hopper, grace.hopper@example.com, (415) 555-0132, 4242 4242 4242 4242, 01/14/2026, $482.10, Whole Foods.
+The first flagged value, Grace Hopper, is the one to check.
+(Set OPENROUTER_API_KEY + VITE_USE_OPENROUTER=1 to call a real model via the dev proxy.)
+```
+
+The last two blocks are the point: the model's reply mentions `[NAME_1]`, and
+what you read says *Grace Hopper*. That substitution happened on your machine,
+after the network call was over.
 
-// provider.complete accepts ONLY a RedactedPayload — raw text won't compile.
-const response = await provider.complete(payload);
+## See it in a browser
 
-// restore real values locally, on-device — bound to the payload's vault.
-const answer = rehydrate(response.redactedText, vault, payload.vaultRef);
+Clone this repo and run the demo, which does the same loop with a live preview
+of exactly what will be sent:
+
+```bash
+pnpm install && pnpm demo   # then open http://localhost:5173
 ```
 
-## The honest hard truth (read this first, it is not a footnote)
+![Paste a statement, preview exactly what leaves, send only labels, read a rehydrated answer.](docs/demo.png)
+
+Open your browser's network tab and watch the request. Only labels go out.
+Nothing is sent until you click **Approve & send** — you approve the exact
+outgoing text, not a promise about it.
+
+To prove it without a browser window, `pnpm test:e2e` drives the same loop in
+real Chromium, intercepts the outbound request, and fails if any real value
+appears in it.
+
+## What this does not protect you from
+
+Read this before you trust it with anything that matters. Over-claiming privacy
+is worse than claiming none.
+
+- **It only hides what it recognizes.** Detection is a fixed ruleset — patterns
+  plus checksums (card numbers are Luhn-checked, IBANs mod-97-checked) plus small
+  dictionaries. It will miss an oddly formatted account number, an unusual name,
+  a kind of private data nobody wrote a rule for. The built-in name list is three
+  demo names; general name detection is not shipped. **That is why you review the
+  outgoing text before it goes.** A human catching a miss is the actual
+  guarantee; the tool's job is to make the text you're about to send visible and
+  approvable, not to promise it caught everything.
 
-Two limits define what this can and cannot promise. Stating them up front is the
-point — over-claiming privacy is worse than claiming none.
+- **Hiding names is not the same as being anonymous.** Even with every name and
+  number stripped, the shape of the text can identify you: "$482.10, the word
+  *insurance*, early January" can point at one person with no identifier left in
+  it. This reduces direct leakage of identifiers. It does not make data
+  anonymous, and it will not stop someone deliberately trying to re-identify you.
 
-- **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.
+- **The vault is in memory and clears on reload.** Your real values are held in
+  ordinary process/tab memory for the length of the session, by design in this
+  version. An encrypted stored vault is on the roadmap, not shipped.
 
-- **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**.
+- **Browser key custody is same-origin, not hardware-backed.** Signing keys held
+  in a browser are protected by the browser's same-origin rules and nothing
+  stronger. Anything that can run code on your origin — a malicious extension, a
+  cross-site scripting bug, a compromised dependency — can reach them. There is
+  no secure element or OS keychain involved.
 
-If those two limits are unacceptable for a use case, this is the wrong tool.
+If any of those limits are unacceptable for what you're doing, this is the wrong
+tool. Say so out loud rather than working around it.
+
+## Receipts: a record of what was allowed and what was blocked
+
+Receipts are **opt-in**. Hand `guardedProvider` a governance context — a
+provider name, your signing key, and an `onReceipt` callback — and from then on
+every decision it makes is signed into a **receipt**: a small record saying
+"text with this fingerprint was allowed (or refused) to go to this provider",
+signed with your key. Refusals are recorded too, so a blocked send can't just
+vanish. A receipt never contains the text itself, only a SHA-256 hash of it.
+
+Omit that argument and you get exactly the same redaction and the same
+fail-closed guard — just no receipt. Turn receipts on when you need to prove
+afterwards what left the device; leave them off when you don't.
+
+Signing and verifying live in `@edgeproc/avow`, so add it alongside:
+`npm install @edgeproc/avow`.
+
+```js
+import { generateSeedHex, publicKeyHex, verifySignature } from "@edgeproc/avow";
+import {
+  approve,
+  guardedProvider,
+  NoLLMProvider,
+  redactForEgress,
+  Vault,
+} from "@edgeproc/privacy-core";
+
+const seedHex = generateSeedHex(); // your signing key, generated on this device
+const receipts = [];
+
+const provider = guardedProvider(new NoLLMProvider(), {
+  provider: "offline-echo",
+  seedHex,
+  onReceipt: (r) => receipts.push(r),
+});
+
+const vault = new Vault();
+const pending = await redactForEgress("Card on file: 4242 4242 4242 4242", vault);
+await provider.complete(approve(pending, () => {}));
+
+// A payload the guard never approved is refused — and the refusal is recorded too.
+// (In TypeScript this call wouldn't even compile; plain JS shows the runtime half.)
+await provider
+  .complete({ redactedText: "raw card 4242 4242 4242 4242", vaultRef: { id: "x" } })
+  .catch((err) => console.log("refused:", err.constructor.name));
+
+for (const r of receipts) console.log(r.payload);
+
+// Anyone holding your public key can check the receipts were not edited later.
+await verifySignature(receipts[0], await publicKeyHex(seedHex));
+console.log("\nsignature check: passed");
+```
+
+```text
+refused: UnapprovedPayloadError
+{
+  action: 'llm.egress',
+  provider: 'offline-echo',
+  args_digest: 'sha256:091a3728dd5622843e14ffb925abcec1bd1cb5ad6461154ab0893b68f63d50b1',
+  decision: 'allow',
+  detector_version: '1'
+}
+{
+  action: 'llm.egress',
+  provider: 'offline-echo',
+  args_digest: 'sha256:6726c6222d515ab998abb62680724ca993157f40a9021ab0643d0e967f4b417b',
+  decision: 'deny',
+  detector_version: '1'
+}
+
+signature check: passed
+```
+
+**What a receipt is worth, precisely.** A signature proves a record has not been
+altered *since it was signed*. It says nothing about whether the machine that
+signed it was already compromised at the time. If an attacker controls the host,
+they can make it sign a true-looking record of a decision you never wanted.
+Receipts give you tamper-evidence after the fact, not a trustworthy host.
 
 ---
 
-## Under the hood (for developers)
+# For developers
+
+## The part that makes leaking a compile error
+
+The rule "don't send raw text to the model" isn't a convention here, and it isn't
+a runtime check you could forget to call. Provider adapters accept **only** a
+branded `RedactedPayload` type, and the only thing that mints one is the
+redaction pipeline (`redactForEgress` → `approve`). A plain `string` is not
+assignable to it, so this:
+
+```ts
+import { NoLLMProvider } from "@edgeproc/privacy-core";
+
+const provider = new NoLLMProvider();
+await provider.complete("my card is 4242 4242 4242 4242");
+```
 
-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.
+fails before it ever runs:
 
-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.
+```text
+oops.ts(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'RedactedPayload'.
+  Type 'string' is not assignable to type 'Branded<"RedactedPayload">'.
+```
+
+TypeScript's brand disappears at runtime, so the same guarantee is enforced a
+second way: every approved payload is registered by object identity, and
+`assertApproved()` rejects a hand-built or spread-cloned look-alike before any
+network call — that's the `UnapprovedPayloadError` in the receipts example
+above. `pnpm build` re-proves the compile-time half on every build.
 
 ## Architecture — maps 1:1 to `src/`
 
@@ -126,10 +292,12 @@ hand-forged or spread-cloned look-alike before any network call is made.
 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
+├── egress.ts           # the boundary: branded RedactedPayload + LlmProvider + unsafeBypass
+├── egressReceipt.ts    # signs allow/deny decisions into receipts when governed (hash only)
+├── errors.ts           # typed fail-closed errors
 ├── 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)
+├── vault.ts            # Vault — reversible token<->value map (in-memory)
 ├── detect/
 │   ├── detector.ts     # detect() — merges patterns + dictionaries, drops overlaps
 │   ├── patterns.ts     # the deterministic ruleset (generic + finance packs)
@@ -142,46 +310,90 @@ src/
                         #   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.
+Detection is deliberately deterministic — same input, same spans, no model, no
+download, testable offline. The contextual name-detection tier that would widen
+recall is a separate, optional adapter and is not shipped (see
+[Roadmap](#roadmap)). See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the
+flow in detail.
 
-### Public API
+## 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 |
+| `assertApproved` | fn | runtime half of the guard — rejects unminted payloads |
+| `guardedProvider` | fn | wrap a provider so the runtime guard runs at one chokepoint — plus receipts if given a governance context |
 | `LlmProvider` | interface | provider contract — accepts only `RedactedPayload` |
+| `PendingRedaction` | type | a redaction proposal awaiting explicit review — not yet sendable |
+| `RedactedPayload` | type | the branded egress type |
+| `unsafeBypass` | fn | the explicit, audited escape hatch |
+| `buildEgressSubject` | fn | build the signed subject (hash of redacted text, decision, provider) |
+| `contentHash` | fn | the canonical hash a verifier recomputes `args_digest` with |
+| `DETECTOR_VERSION` | const | version tag for the detector ruleset, recorded in each receipt |
+| `EgressDecision` | type | the guard's verdict on one egress attempt — allow or deny |
+| `EgressGovernance` | interface | how a guarded provider seals its decisions (signer seed + receipt sink) |
+| `EgressSubject` | type | the signed, hash-only record of one egress decision |
+| `EgressSubjectInput` | interface | what the caller supplies to build an `EgressSubject` |
+| `sealEgressReceipt` | fn | sign one egress decision into a receipt |
+| `makeProvider` | fn | config-driven provider selector |
+| `ProviderConfig` | interface | host-supplied config (API key, model, endpoint) for `makeProvider` |
+| `SelectedProvider` | interface | the provider `makeProvider` picked, plus a label for the UI |
 | `NoLLMProvider` | class | offline echo provider |
+| `OpenRouterConfig` | interface | config for `OpenRouterProvider` (API key, model, endpoint) |
 | `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 |
+| `redactForEgress` | fn | detect → vault-write → brand → a `PendingRedaction` proposal |
+| `rehydrate` | fn | restore real values locally from placeholders |
+| `AuditEntry` | interface | one append-only audit record (redact / approve / unsafe-bypass) |
+| `AuditSink` | type | the audit callback signature callers supply to `approve`/`unsafeBypass` |
+| `EntityType` | type | the PII categories the detector recognizes (CARD, SSN, EMAIL, ...) |
+| `RedactedResponse` | interface | a provider's reply, still in placeholder form until rehydrated |
+| `Span` | interface | one detected PII span (type, value, start, end) |
+| `VaultRef` | interface | opaque handle to a vault's token → value mappings |
+| `Vault` | class | reversible token↔value map |
+
+Typed fail-closed errors are exported too: `ForgedPayloadError`,
+`PlaceholderCollisionError`, `ResidualValueError`, `UnapprovedPayloadError`,
+`UnresolvedPlaceholderError`, `VaultMismatchError`.
 
 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)
+## Calling a real model
+
+The library is environment-agnostic: you pass your own key in, and it is never
+read from the environment for you. The bundled demo keeps `OPENROUTER_API_KEY`
+server-side — a same-origin dev proxy injects it, so it never reaches the browser
+bundle. Copy `.env.example` → `examples/demo/.env`, set the key, add
+`VITE_USE_OPENROUTER=1`, and re-run `pnpm demo`.
+
+## Working on this repo
+
+```bash
+pnpm install
+pnpm gate   # lint → typecheck → unit tests with coverage → browser e2e → build
+```
+
+`pnpm gate` is exactly what CI runs. See
+[docs/QUICKSTART.md](docs/QUICKSTART.md) and
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Roadmap
 
 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.
+- **Encrypted stored vault** (AES-GCM + passphrase KDF over IndexedDB). Today's
+  vault is in-memory and clears on reload.
+- **Contextual name/place detection** to widen recall past the fixed ruleset;
+  would be an optional, off-by-default adapter.
+- **Durable audit and receipt storage** — the sinks are wired today; persistence
+  is not.
+- **More domain rule packs** (medical, legal, HR, identity) beyond the generic +
+  finance set, and generalization modes (amount bucketing, date coarsening) that
+  would start to address the anonymity limit above.
 
 ## License
 

package/dist/detect/patterns.d.ts

@@ -16,7 +16,7 @@ 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.
+ * and the demo runnable with zero download.
  */
 export declare const NAMES: readonly string[];
 //# sourceMappingURL=patterns.d.ts.map

package/dist/detect/patterns.js

@@ -30,7 +30,7 @@ export const MERCHANTS = [
 /**
  * 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.
+ * and the demo runnable with zero download.
  */
 export const NAMES = [
     "Ada Lovelace",

package/dist/egressReceipt.d.ts

@@ -3,12 +3,19 @@
  *
  * The Egress Guard already gates whether redacted text may leave the device
  * (see {@link file://./egress.ts}). This module makes that decision *provable*:
- * every allow or deny is expressed as a Writ-style governed effect — an
+ * an allow or deny is expressed as a Writ-style governed effect — an
  * `EgressSubject` — and signed into a tamper-evident receipt via the shared
  * `@edgeproc/avow` envelope. A holder of the signer's public key can later
  * verify exactly which egress decisions were taken, without ever seeing the
  * content.
  *
+ * SCOPE — sealing is opt-in: receipts are produced only for a
+ * {@link file://./egress.ts guardedProvider} that was given an
+ * {@link EgressGovernance} context. A caller who omits it still gets the full
+ * redaction and the same fail-closed guard, just no receipt. The guarantee
+ * below therefore reads: *once governed*, every allow and every deny at that
+ * chokepoint is sealed.
+ *
  * INVARIANT — no plaintext in a receipt: the subject stores only
  * `args_digest = sha256(canonical({ redactedText }))`, never the text itself,
  * and never the raw PII the vault holds. A receipt records *that* a decision

package/dist/egressReceipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"egressReceipt.d.ts","sourceRoot":"","sources":["../src/egressReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAe,KAAK,aAAa,EAAe,MAAM,gBAAgB,CAAC;AAI9E,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,8EAA8E;AAC9E,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,4EAA4E;AAC5E,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAEvC"}
+{"version":3,"file":"egressReceipt.d.ts","sourceRoot":"","sources":["../src/egressReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAe,KAAK,aAAa,EAAe,MAAM,gBAAgB,CAAC;AAI9E,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,8EAA8E;AAC9E,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,4EAA4E;AAC5E,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAEvC"}

package/dist/egressReceipt.js

@@ -3,12 +3,19 @@
  *
  * The Egress Guard already gates whether redacted text may leave the device
  * (see {@link file://./egress.ts}). This module makes that decision *provable*:
- * every allow or deny is expressed as a Writ-style governed effect — an
+ * an allow or deny is expressed as a Writ-style governed effect — an
  * `EgressSubject` — and signed into a tamper-evident receipt via the shared
  * `@edgeproc/avow` envelope. A holder of the signer's public key can later
  * verify exactly which egress decisions were taken, without ever seeing the
  * content.
  *
+ * SCOPE — sealing is opt-in: receipts are produced only for a
+ * {@link file://./egress.ts guardedProvider} that was given an
+ * {@link EgressGovernance} context. A caller who omits it still gets the full
+ * redaction and the same fail-closed guard, just no receipt. The guarantee
+ * below therefore reads: *once governed*, every allow and every deny at that
+ * chokepoint is sealed.
+ *
  * INVARIANT — no plaintext in a receipt: the subject stores only
  * `args_digest = sha256(canonical({ redactedText }))`, never the text itself,
  * and never the raw PII the vault holds. A receipt records *that* a decision

package/dist/egressReceipt.js.map

@@ -1 +1 @@
-{"version":3,"file":"egressReceipt.js","sourceRoot":"","sources":["../src/egressReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAsB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE9E,6EAA6E;AAC7E,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAmB7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAWpC,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAyB;IAEzB,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,MAAM,WAAW,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;QACpE,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,gBAAgB,EAAE,KAAK,CAAC,eAAe,IAAI,gBAAgB;KAC5D,CAAC;AACJ,CAAC;AAkBD,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAyB,EACzB,OAAe;IAEf,OAAO,WAAW,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"egressReceipt.js","sourceRoot":"","sources":["../src/egressReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAsB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE9E,6EAA6E;AAC7E,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAmB7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAWpC,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAyB;IAEzB,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,MAAM,WAAW,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;QACpE,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,gBAAgB,EAAE,KAAK,CAAC,eAAe,IAAI,gBAAgB;KAC5D,CAAC;AACJ,CAAC;AAkBD,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAyB,EACzB,OAAe;IAEf,OAAO,WAAW,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}

package/dist/providers/nollm.d.ts

@@ -4,7 +4,8 @@ import type { RedactedResponse } from "../types.js";
  * Offline fallback provider — runs with NO API key. It does NOT touch the
  * network; it echoes a plausible analyst reply that references the same
  * placeholders, so the rehydrate step has something to restore. This is what
- * makes the demo runnable cold, with the wow-loop fully intact.
+ * makes the demo runnable cold, with the full redact → send → rehydrate loop
+ * intact.
  */
 export declare class NoLLMProvider implements LlmProvider {
     complete(payload: RedactedPayload): Promise<RedactedResponse>;

package/dist/providers/nollm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nollm.d.ts","sourceRoot":"","sources":["../../src/providers/nollm.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,WAAW;IACzC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqBlE;CACF"}
+{"version":3,"file":"nollm.d.ts","sourceRoot":"","sources":["../../src/providers/nollm.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,WAAW;IACzC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqBlE;CACF"}

package/dist/providers/nollm.js

@@ -3,7 +3,8 @@ import { assertApproved, } from "../egress.js";
  * Offline fallback provider — runs with NO API key. It does NOT touch the
  * network; it echoes a plausible analyst reply that references the same
  * placeholders, so the rehydrate step has something to restore. This is what
- * makes the demo runnable cold, with the wow-loop fully intact.
+ * makes the demo runnable cold, with the full redact → send → rehydrate loop
+ * intact.
  */
 export class NoLLMProvider {
     async complete(payload) {

package/dist/providers/nollm.js.map

@@ -1 +1 @@
-{"version":3,"file":"nollm.js","sourceRoot":"","sources":["../../src/providers/nollm.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAGf,MAAM,cAAc,CAAC;AAGtB;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,iEAAiE;QACjE,cAAc,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CACtE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CACZ,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACvE,MAAM,KAAK,GAAG;YACZ,0CAA0C;YAC1C,4CAA4C,MAAM,CAAC,MAAM,uBAAuB,IAAI,GAAG;SACxF,CAAC;QACF,yEAAyE;QACzE,0EAA0E;QAC1E,kDAAkD;QAClD,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,4BAA4B,MAAM,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC;QAC5E,CAAC;QACD,KAAK,CAAC,IAAI,CACR,0FAA0F,CAC3F,CAAC;QACF,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC5C,CAAC;CACF"}
+{"version":3,"file":"nollm.js","sourceRoot":"","sources":["../../src/providers/nollm.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAGf,MAAM,cAAc,CAAC;AAGtB;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,iEAAiE;QACjE,cAAc,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CACtE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CACZ,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACvE,MAAM,KAAK,GAAG;YACZ,0CAA0C;YAC1C,4CAA4C,MAAM,CAAC,MAAM,uBAAuB,IAAI,GAAG;SACxF,CAAC;QACF,yEAAyE;QACzE,0EAA0E;QAC1E,kDAAkD;QAClD,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,4BAA4B,MAAM,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC;QAC5E,CAAC;QACD,KAAK,CAAC,IAAI,CACR,0FAA0F,CAC3F,CAAC;QACF,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC5C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgeproc/privacy-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -8,6 +8,10 @@
   "description": "A browser-side privacy boundary for LLM calls: redact on-device, send only placeholders, rehydrate locally — enforced by a type-checked Egress Guard.",
   "license": "MIT",
   "author": "Harish Seshadri",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hseshadr/privacy-core.git"
+  },
   "packageManager": "pnpm@11.5.0",
   "engines": {
     "node": ">=22.13"