Documentation

Install it, then earn the payload.

The public surface of @gainratio/privacy-core 0.3.2: installation, the four-step loop, every export, how the vault mapping works, the typed errors, and how to deploy the boundary without weakening it.

Install

ES modules only. Node 22.13 or newer, or a modern browser bundler. The library is tested in Chromium and its public barrel is browser-safe.

npm install @gainratio/privacy-core
# or
pnpm add @gainratio/privacy-core
# or
yarn add @gainratio/privacy-core

There is one runtime dependency: @gainratio/avow ^0.5.3, used to sign the optional egress receipts. No account and no API key are needed to try the library.

import {
  approve,
  guardedProvider,
  NoLLMProvider,
  redactForEgress,
  rehydrate,
  Vault,
} from "@gainratio/privacy-core";

The loop

This is the whole flow. It prints each step, including the audit log. NoLLMProvider is an offline echo, so the run needs no key and no network.

import {
  approve, guardedProvider, NoLLMProvider, redactForEgress, rehydrate, Vault,
} from "@gainratio/privacy-core";

const statement =
  "Grace Hopper, card 4242 4242 4242 4242, was charged $482.10 at Whole Foods on 01/14/2026.";

const vault = new Vault(); // holds your real values, in this process, on this machine
const audit = (e) => console.log("[audit]", e.kind, e.placeholders);

const pending = await redactForEgress(statement, vault, audit);
console.log("leaves your machine:", pending.redactedText);

const payload = approve(pending, audit);

const reply = await guardedProvider(new NoLLMProvider()).complete(payload);
console.log("model replied:", reply.redactedText);

console.log("you read:", rehydrate(reply.redactedText, vault, payload.vaultRef));

1. Redact. redactForEgress detects values, writes them to the Vault, and returns a PendingRedaction proposal. It is not sendable.
2. Approve. approve is the explicit review action. It requires an audit sink and mints the only capability a provider accepts.
3. Send. A provider — the offline echo, OpenRouter, or your own — receives the approved payload and puts only placeholders on the wire.
4. Restore. rehydrate takes the payload's vaultRef, checks it against the vault, and replaces the labels locally.

API

Everything src/index.ts exports, and nothing more. The brand factory mintPendingRedaction is intentionally not public, and test fixtures live only behind the /testing subpath.

Core signatures

detect(text: string): Span[]

redactForEgress(
  raw: string,
  vault: Vault,
  audit?: AuditSink,
): Promise<PendingRedaction>

approve(pending: PendingRedaction, audit: AuditSink): RedactedPayload

guardedProvider(inner: LlmProvider, governance?: EgressGovernance): LlmProvider

rehydrate(redactedText: string, vault: Vault, expectedRef: VaultRef): string

unsafeBypass(raw: string, reason: string, audit: AuditSink): RedactedPayload

makeProvider(config?: ProviderConfig): SelectedProvider

Core and audit

Providers

Receipts

Configuration

The library reads no environment variables; your code passes every setting in.

makeProvider fails closed with MissingApiKeyError when there is no usable key and allowOffline is not true. It is env-agnostic: it never reads a key for you.

Placeholders and the vault mapping

A placeholder is a typed label, not a hash: [CARD_1], [EMAIL_2]. The mapping is the Vault, and it lives only in memory.

const vault = new Vault();

await redactForEgress("Card 4242 4242 4242 4242", vault);
// text:  Card [CARD_1]
// vault: [CARD_1] ↔ 4242 4242 4242 4242

await redactForEgress("Again: 4242 4242 4242 4242", vault);
// same value, same vault → [CARD_1] again

await redactForEgress("ada@example.com and grace@example.com", vault);
// two different values → [EMAIL_1] and [EMAIL_2]

• Stable within a vault. The same (type, value) always receives the same token. Each entity type has its own counter, so [CARD_1] and [EMAIL_1] are separate.
• The reference is frozen. The payload carries payload.vaultRef, an opaque handle whose id identifies the vault. rehydrate checks that id first; a different vault fails with VaultMismatchError.
• Every label must resolve. Under the bound vault, an unknown [TYPE_n] token fails with UnresolvedPlaceholderError. The function does not leave a lookalike token in the reply.
• A new vault starts over. new Vault() gets a new id and counters start at 1. Hold the vault for the length of the conversation that the payload belongs to.
• Placeholder-shaped input is refused. If the raw text already contains something like [CARD_1], redaction fails with PlaceholderCollisionError, because restore would be ambiguous.
• Nothing is persisted. The vault is ordinary process or tab memory and clears on reload. An encrypted IndexedDB vault is planned, not shipped. Do not share a vault between users.
• The map is only as complete as detection. A value the ruleset missed is never written to the vault, so it cannot be restored, and it may still leave in the reviewed text.

Detection coverage

Detection is a fixed ruleset, so the honest version of “it finds the private bits” is a list. This is the whole of it. If a format is not in the left column, it is not detected, and the review step is what catches it.

The repository proves the recognized column at the wire, with test/detector-completeness.test.ts, and pins a recall floor against v0.2.2. The limits that are easiest to widen by accident are pinned as tests too. Read the source table.

Errors

Every typed failure extends PrivacyCoreError. They are fail-closed signals: the safe reaction is to stop the send or restore, not to continue past it.

Non-2xx HTTP responses from the OpenRouter adapter reject with an Error carrying the status and body; the typed errors above cover the boundary, timeout, size and malformed-reply paths.

Deployment guidance

privacy-core is a library, not a service. It ships no server component: you bring the provider, the review screen and, if you need one, the proxy that holds the model key.

Run the boundary where the text is

The promise is that real values stay on the user's device. That holds when redaction runs in the client before the provider call. The package also runs on Node 22.13+, but if you run it on a server, the vault is server memory and the “on-device” framing no longer describes your architecture.

Keep the provider key server-side

The library is environment-agnostic: you pass the key in, and it never reads one from the environment for you. The bundled demo keeps OPENROUTER_API_KEY server-side and injects it through a same-origin dev proxy; the key never reaches the browser bundle. A real key shipped to the browser is a bug.

import { makeProvider } from "@gainratio/privacy-core";

const { provider, label } = makeProvider({
  apiKey: process.env.OPENROUTER_API_KEY, // server-side only
  model: "openai/gpt-4o-mini",
});

A browser path can point the endpoint at your own same-origin proxy. The sentinel key only selects the OpenRouter code path; it is not a secret.

const { provider } = makeProvider({
  apiKey: "via-proxy", // non-secret sentinel, not the real key
  endpoint: "/api/chat",
});

Hold one vault per conversation

Create a Vault for the interaction and keep it until you have rehydrated the reply. Pass payload.vaultRef to rehydrate; never share a vault between users. The vault clears on reload, so a refresh starts a new one.

Put the preview in front of approve

The review step is part of the security boundary. Render pending.redactedText exactly as it will be sent, let the person read it, and call approve only after that. The detector catches the listed formats; the person catches the rest.

Treat the origin as part of the boundary

The vault and any browser-held signing key are readable by anything that can run code on your origin: a malicious extension, an XSS bug or a compromised dependency. Keep third-party scripts off the origin, keep the app on HTTPS, and do not treat the library as a substitute for a clean client.

Respect the budgets

Input is capped at 512 KiB of UTF-8. OpenRouter requests default to a 30-second deadline and a 1 MiB response cap. Override timeoutMs or maxResponseBytes only with a deliberate, tested budget; timeout and overflow failures are typed and fail closed.

Decide whether you need receipts

Receipts are opt-in. Give guardedProvider a governance context and every allow or deny is signed into a receipt containing a SHA-256 hash of the text, the decision and the provider name — never the text itself. Persisting those receipts is your job; the sinks are wired, durable storage is planned. Receipts are tamper-evident, not a statement that the signing host was uncompromised.

Ship with the checks green

The repository's gate is pnpm gate: lint, type checks, unit tests with 100% coverage thresholds, the Playwright wire proof and the build. The e2e test drives the real demo in Chromium, intercepts the outbound request and fails if any real value appears in it. Run it before you change how your app builds its provider request.

Key limits

• Only the formats in the detection table are found. General names, addresses and free text are not detected.
• Redaction is not anonymisation; context can still re-identify a person.
• The vault is in-memory and clears on reload. There is no shipped encrypted persistence.
• A compromised device, extension, XSS bug or dependency can read the vault and a browser-held signing key.
• The library does not control what the AI provider does with the labelled text it receives.
• Input is capped at 512 KiB per call; split larger documents into reviewed sections.

The security page covers the threat model, the test evidence and private reporting.

Next

• Copyable examples from the README and API docs
• Threat model, boundaries and reporting
• The full API reference on GitHub
• Architecture and the test evidence