chatpanel-pii 0.1.0

package/LICENSE

@@ -0,0 +1,168 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+bridge, and related developer tools and services (https://chatpanel.net)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+> bridge, and related developer tools and services (https://chatpanel.net)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately.  If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations that an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,58 @@
+# chatpanel-pii
+
+The **canonical ChatPanel privacy engine** — reversible PII redaction +
+pseudonymization with local entity detection. Pure, dependency-free ESM. This is
+the **single source of truth** shared by the ChatPanel
+[extension](https://github.com/chatpanel/chatpanel-extension),
+[gateway](https://github.com/chatpanel/chatpanel-gateway), and
+[bridge](https://github.com/chatpanel/chatpanel-bridge): a privacy feature added
+here is picked up by all of them.
+
+```js
+import { createVault, redactText, restoreText, detectEntities } from 'chatpanel-pii';
+
+const vault = createVault();
+const safe = redactText('email alex@example.com', vault, { tier: 'basic' });
+// → 'email [[EMAIL_1]]'
+restoreText(safe, vault);
+// → 'email alex@example.com'
+```
+
+The model only ever sees opaque, stable placeholders like `[[PERSON_1]]` /
+`[[EMAIL_2]]`, so it can still reason about *who said what* without seeing the
+real values — and they're reconstructed locally on the way back.
+
+## What's inside
+
+| Module | Exports | Role |
+|--------|---------|------|
+| `pii-redact.js` | `createVault`, `redactText`, `restoreText`, `restoreWithAliases`, `vaultToJSON`/`vaultFromJSON`, `hasToken` | deterministic redact/restore + the per-conversation vault |
+| `pii-detect.js` | `detectEntities`, `normalizeEntities`, `EXTRACT_SYS`, … | local entity detection (any HTTP NER endpoint, or a local OpenAI-compatible LLM) |
+| `pipeline.js` | `redactOutbound`, `makeStreamRestorer`, `restore`, `restoreDeep`, `redactResult`, `effectiveTier`, `gatedDictionary`, `gatedScope` | pure turn orchestration + the free/Pro tier, scope, and dictionary gating |
+
+Import the barrel (`chatpanel-pii`) or a submodule
+(`chatpanel-pii/pii-redact.js`).
+
+## Tiers
+
+- **`basic`** — deterministic regex: emails, phones, IPs, cards (Luhn), SSNs, API
+  keys, plus a small user dictionary.
+- **`full`** — basic + entity-aware: detected people / orgs / locations and an
+  unlimited custom dictionary. `effectiveTier(cfg, isPro)` downgrades `full`→`basic`
+  for non-Pro callers, so consumers enforce free/Pro identically.
+
+A dictionary entry with an `alias` **pseudonymizes** (permanent substitution the
+model and the user both see); without one it **redacts** to a reversible token.
+
+## Design notes
+
+- **Pure + dependency-free** so it unit-tests trivially and runs identically in a
+  browser extension, a Node proxy, and a CLI bridge.
+- **Reversibility is best-effort**: if a model paraphrases a placeholder instead
+  of echoing it, that reference won't restore — but the privacy guarantee (the
+  real value never left the device) always holds.
+
+## License
+
+Source-available under the same license as the rest of ChatPanel — see
+[LICENSE](LICENSE).

package/index.js

@@ -0,0 +1,14 @@
+// chatpanel-pii — the canonical ChatPanel privacy engine. Single source of truth
+// for reversible PII redaction + pseudonymization, shared by the extension, the
+// gateway, and the bridge. Pure + dependency-free ESM.
+//
+//   import { createVault, redactText, restoreText, detectEntities } from 'chatpanel-pii';
+//
+// Submodules are also importable directly:
+//   'chatpanel-pii/pii-redact.js'   deterministic redact/restore + vault
+//   'chatpanel-pii/pii-detect.js'   local NER / LLM entity detection
+//   'chatpanel-pii/pipeline.js'     pure turn orchestration + tier/scope gating
+
+export * from './pii-redact.js';
+export * from './pii-detect.js';
+export * from './pipeline.js';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "chatpanel-pii",
+  "version": "0.1.0",
+  "description": "The canonical ChatPanel privacy engine — reversible PII redaction + pseudonymization with local entity detection. Pure, dependency-free ESM shared by the ChatPanel extension, gateway, and bridge.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./pii-redact.js": "./pii-redact.js",
+    "./pii-detect.js": "./pii-detect.js",
+    "./pipeline.js": "./pipeline.js"
+  },
+  "files": [
+    "index.js",
+    "pii-redact.js",
+    "pii-detect.js",
+    "pipeline.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://chatpanel.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatpanel/chatpanel-pii.git"
+  },
+  "keywords": [
+    "privacy",
+    "pii",
+    "redaction",
+    "pseudonymization",
+    "ner",
+    "anonymization",
+    "llm",
+    "chatpanel"
+  ],
+  "author": "ChatPanel (https://chatpanel.net)",
+  "license": "SEE LICENSE IN LICENSE",
+  "sideEffects": false
+}

package/pii-detect.js

@@ -0,0 +1,156 @@
+// Phase 2: configurable, LOCAL entity detection.
+//
+// Produces [{value, type}] spans that feed the redaction engine, so names / orgs /
+// IDs get redacted WITHOUT a hand-maintained dictionary. Detection runs on-device
+// only — the detector is a local NER service (spaCy / Presidio / any HTTP service)
+// or a local LLM (OpenAI-compatible, e.g. a gemma served by llama.cpp). Raw text
+// reaches the detector but never the final agent; only the redacted text does.
+//
+// Performance / flexibility (the whole point):
+//   - backends are pluggable and user-configured (URL + model + timeout).
+//   - a content-hash cache avoids re-detecting unchanged text.
+//   - a per-call timeout + fail-open means a slow/broken detector NEVER blocks the
+//     chat — redaction silently falls back to the deterministic layer.
+//   - input is length-capped so a huge transcript can't stall detection.
+
+const cache = new Map(); // key -> [{value,type}]
+const CACHE_MAX = 300;
+
+export function clearDetectCache() { cache.clear(); }
+
+function cacheKey(text, det) {
+  let h = 5381;
+  const s = `${det?.backend}|${det?.url}|${det?.model}|${text}`;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return `${s.length}:${h}`;
+}
+
+export function withTimeout(promise, ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('detect timeout')), Math.max(200, ms || 1500));
+    const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')); };
+    if (signal) signal.addEventListener?.('abort', onAbort, { once: true });
+    promise.then(
+      (v) => { clearTimeout(timer); resolve(v); },
+      (e) => { clearTimeout(timer); reject(e); },
+    );
+  });
+}
+
+// Map common NER labels (spaCy, HF, Presidio) onto our placeholder types.
+function normType(t) {
+  const s = String(t || 'ENTITY').toUpperCase().replace(/[^A-Z0-9]/g, '') || 'ENTITY';
+  const map = {
+    PER: 'PERSON', PERSON: 'PERSON', PERSONNAME: 'PERSON',
+    ORG: 'ORG', ORGANIZATION: 'ORG',
+    GPE: 'LOCATION', LOC: 'LOCATION', LOCATION: 'LOCATION',
+    NORP: 'GROUP', EMAIL: 'EMAIL', EMAILADDRESS: 'EMAIL',
+    PHONE: 'PHONE', PHONENUMBER: 'PHONE',
+  };
+  return map[s] || s;
+}
+
+// Identifiers we ALWAYS redact (also caught deterministically). The user-facing
+// category toggles (person/org/location/number) control the rest, so geography
+// questions still work if "location" is turned off, etc. Numeric/temporal labels
+// (DATE, CARDINAL, ORDINAL…) are noisy — small NER models tag "today" / "4" — so
+// they only count when the value is a long digit run (phone/account/ID).
+const ALWAYS_KEEP = new Set(['EMAIL', 'PHONE', 'SSN', 'CREDITCARD', 'IBAN', 'ID']);
+const LOCATION_TYPES = new Set(['LOCATION', 'FAC', 'ADDRESS', 'GROUP', 'NRP']);
+
+function keepEntity(value, type, types) {
+  const on = (k) => !types || types[k] !== false; // default on
+  if (ALWAYS_KEEP.has(type)) return true;
+  if (type === 'PERSON') return on('person');
+  if (type === 'ORG') return on('org');
+  if (LOCATION_TYPES.has(type)) return on('location');
+  const digits = (String(value).match(/\d/g) || []).length;
+  return digits >= 7 ? on('number') : false;
+}
+
+// Normalize the many detector response shapes to [{value, type}], de-duplicated.
+// `types` (optional) is the user's category toggles {person,org,location,number}.
+export function normalizeEntities(data, types) {
+  let list = [];
+  if (Array.isArray(data)) list = data;
+  else if (data && Array.isArray(data.entities)) list = data.entities;
+  else if (data && Array.isArray(data.ents)) list = data.ents; // spaCy displacy
+  else if (data && Array.isArray(data.results)) list = data.results; // Presidio
+  const out = [];
+  const seen = new Set();
+  for (const e of list) {
+    if (!e) continue;
+    const value = String(e.value ?? e.text ?? e.entity ?? e.word ?? '').trim();
+    const type = normType(e.type ?? e.label ?? e.entity_group ?? e.entity_type ?? e.tag);
+    if (!value || value.length > 200 || !keepEntity(value, type, types)) continue;
+    const k = `${type}:${value.toLowerCase()}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push({ value, type });
+  }
+  return out;
+}
+
+export function parseJsonLoose(s) {
+  if (!s) return null;
+  const a = String(s).indexOf('{');
+  const b = String(s).lastIndexOf('}');
+  if (a < 0 || b <= a) return null;
+  try { return JSON.parse(String(s).slice(a, b + 1)); } catch { return null; }
+}
+
+export const EXTRACT_SYS = 'You extract sensitive entities from text for redaction. '
+  + 'Return ONLY JSON: {"entities":[{"value":"<verbatim text>","type":"PERSON|ORG|LOCATION|ID|EMAIL|PHONE|OTHER"}]}. '
+  + 'Copy each value exactly as it appears. Include people, organizations, locations, and account/ID numbers. No commentary, no code fences.';
+
+async function detectViaEndpoint(text, det, signal, fetchImpl) {
+  const res = await fetchImpl(det.url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(det.apiKey ? { Authorization: `Bearer ${det.apiKey}` } : {}) },
+    body: JSON.stringify({ text }),
+    signal,
+  });
+  if (!res.ok) throw new Error(`detect HTTP ${res.status}`);
+  return normalizeEntities(await res.json(), det.types);
+}
+
+async function detectViaOpenAI(text, det, signal, fetchImpl) {
+  const base = String(det.url || '').replace(/\/$/, '');
+  const url = /\/chat\/completions$/.test(base) ? base : `${base}/v1/chat/completions`;
+  const res = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(det.apiKey ? { Authorization: `Bearer ${det.apiKey}` } : {}) },
+    body: JSON.stringify({
+      model: det.model || 'local',
+      temperature: 0,
+      max_tokens: det.maxTokens || 256,
+      messages: [{ role: 'system', content: EXTRACT_SYS }, { role: 'user', content: text }],
+    }),
+    signal,
+  });
+  if (!res.ok) throw new Error(`detect HTTP ${res.status}`);
+  const json = await res.json();
+  const content = json?.choices?.[0]?.message?.content ?? json?.content ?? '';
+  return normalizeEntities(parseJsonLoose(content), det.types);
+}
+
+// Returns [{value, type}] spans for `text`, or [] (fail-open) on any error/timeout.
+export async function detectEntities(text, cfg, { signal, fetchImpl = globalThis.fetch, strict = false } = {}) {
+  const det = cfg?.detection;
+  if (!det || !det.backend || det.backend === 'off' || !det.url || typeof fetchImpl !== 'function') return [];
+  const capped = String(text || '').slice(0, det.maxChars || 8000);
+  if (capped.trim().length < 8) return [];
+  const key = cacheKey(capped, det);
+  if (!strict && cache.has(key)) return cache.get(key);
+  const run = det.backend === 'endpoint' ? detectViaEndpoint : detectViaOpenAI;
+  let ents = [];
+  try {
+    ents = await withTimeout(run(capped, det, signal, fetchImpl), det.timeoutMs || 1500, signal);
+  } catch (e) {
+    if (strict) throw e; // surface errors to the Test button
+    ents = []; // otherwise fail open — deterministic redaction still applies
+  }
+  if (cache.size >= CACHE_MAX) cache.clear();
+  if (!strict) cache.set(key, ents);
+  return ents;
+}

package/pii-redact.js

@@ -0,0 +1,193 @@
+// Reversible PII redaction.
+//
+// Strips sensitive values out of everything that leaves the device for a model
+// (chat text, attached page/meeting context, and tool results we feed back), then
+// reconstructs the originals when the reply is rendered to the user. The model
+// only ever sees opaque, stable placeholders like [[EMAIL_1]] / [[PERSON_2]] — so
+// it can still reason about "who said what" without seeing the real values.
+//
+// Pure + dependency-free so it is unit-testable and runs identically for API and
+// CLI/bridge agents (both assemble their outbound payload through providers.js).
+//
+// Tiers (the licensing seam):
+//   'basic' — deterministic regex: emails, phones, IPs, cards (Luhn), SSNs, keys.
+//   'full'  — basic + entity-aware: known people/orgs (meeting roster, contacts,
+//             the user's own identity) and a user-editable custom dictionary.
+//
+// Reversibility caveat: if the model paraphrases instead of echoing a token, that
+// one reference won't restore (it shows the token) — but the privacy guarantee
+// (the real value never left the device) always holds.
+
+const TOKEN_RE = /\[\[([A-Z][A-Z0-9]*)_(\d+)\]\]/g;
+
+// A vault is the per-conversation mapping between placeholders and originals. Keep
+// one per conversation so PERSON_1 means the same entity across turns.
+export function createVault() {
+  // `aliases` maps a pseudonym (e.g. "Alex") back to the real value (e.g. "Suresh")
+  // so LOCAL tool calls (history/meeting search) can run on real data. The reply
+  // restorer ignores it — pseudonyms stay permanent in the user's view.
+  return { byToken: new Map(), byValue: new Map(), counts: new Map(), aliases: new Map() };
+}
+
+export function vaultToJSON(vault) {
+  return {
+    entries: [...(vault?.byToken || new Map())].map(([token, value]) => ({ token, value })),
+    aliases: [...(vault?.aliases || new Map())].map(([alias, value]) => ({ alias, value })),
+  };
+}
+
+export function vaultFromJSON(data) {
+  const vault = createVault();
+  for (const { token, value } of data?.entries || []) {
+    const m = /^\[\[([A-Z][A-Z0-9]*)_(\d+)\]\]$/.exec(token);
+    vault.byToken.set(token, value);
+    vault.byValue.set(value, token);
+    if (m) vault.counts.set(m[1], Math.max(vault.counts.get(m[1]) || 0, Number(m[2])));
+  }
+  for (const { alias, value } of data?.aliases || []) vault.aliases.set(alias, value);
+  return vault;
+}
+
+function tokenFor(vault, type, value) {
+  const existing = vault.byValue.get(value);
+  if (existing) return existing;
+  const t = String(type || 'PII').toUpperCase().replace(/[^A-Z0-9]/g, '') || 'PII';
+  const n = (vault.counts.get(t) || 0) + 1;
+  vault.counts.set(t, n);
+  const token = `[[${t}_${n}]]`;
+  vault.byToken.set(token, value);
+  vault.byValue.set(value, token);
+  return token;
+}
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function luhnValid(digits) {
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (alt) { d *= 2; if (d > 9) d -= 9; }
+    sum += d;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+// Deterministic detectors. Each: { type, re, valid? }. Order = priority; more
+// specific patterns run first so they win the bytes before greedier ones.
+const DETECTORS = [
+  { type: 'EMAIL', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+  { type: 'SSN', re: /\b\d{3}-\d{2}-\d{4}\b/g },
+  {
+    type: 'KEY',
+    re: /\b(?:sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g,
+  },
+  {
+    type: 'IP',
+    re: /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/g,
+  },
+  {
+    // Phone: only count it if it has a separator or a leading + and 7–15 digits —
+    // so long bare ids (a 11-digit page id, an order number) are NOT redacted.
+    type: 'PHONE',
+    re: /(?<![\w.])\+?\d[\d ().-]{6,}\d(?![\w])/g,
+    valid: (m) => {
+      const digits = m.replace(/\D/g, '');
+      // Needs a separator / leading + OR be a bare 10-digit run (a typed phone like
+      // 9320434444). 11+ bare digits still require formatting so long ids aren't hit.
+      return digits.length >= 7 && digits.length <= 15
+        && (/[ ().-]/.test(m) || m.trimStart().startsWith('+') || digits.length === 10);
+    },
+  },
+  {
+    type: 'CARD',
+    re: /\b(?:\d[ -]?){13,19}\b/g,
+    valid: (m) => { const d = m.replace(/\D/g, ''); return d.length >= 13 && d.length <= 19 && luhnValid(d); },
+  },
+];
+
+// Redact `text`, recording placeholders in `vault`. `entities` (full tier) is a
+// list of { value, type } known names/orgs; `dictionary` is the user's custom
+// list of { value, type } (exact strings) or { pattern, flags, type } (regex).
+export function redactText(text, vault, {
+  tier = 'basic',
+  entities = [],
+  dictionary = [],
+} = {}) {
+  if (text == null || text === '') return text;
+  let out = String(text);
+  const v = vault || createVault();
+
+  const entityTier = tier === 'full' || tier === 'entities';
+
+  // 1) User dictionary first — highest authority, user explicitly chose these.
+  //    An entry with `alias` PSEUDONYMIZES: permanent substitution (the model and
+  //    the user's transcript both see the alias, never reversed). Otherwise it
+  //    REDACTS to a reversible [[TYPE_n]] placeholder restored in the user's view.
+  for (const d of dictionary || []) {
+    if (!d) continue;
+    try {
+      const re = d.pattern
+        ? new RegExp(d.pattern, d.flags && /g/.test(d.flags) ? d.flags : `${d.flags || ''}g`)
+        : (d.value ? new RegExp(`(?<![\\w])${escapeRegex(d.value)}(?![\\w])`, 'gi') : null);
+      if (!re) continue;
+      if (d.alias != null && d.alias !== '') {
+        out = out.replace(re, () => d.alias); // pseudonymize: model + reply see the alias…
+        // …but record alias→original so LOCAL tool args (history/meeting search) map
+        // back to the real value. Local lookups must hit real data; only the model is blinded.
+        if (d.value) v.aliases.set(d.alias, d.value);
+      } else {
+        out = out.replace(re, (m) => tokenFor(v, d.type || (d.pattern ? 'PII' : 'TERM'), d.pattern ? m : d.value));
+      }
+    } catch {
+      /* a bad user regex must never break redaction */
+    }
+  }
+
+  // 2) Known entities (full tier) — longest value first so "Alex Rivera" wins
+  //    before a bare "Alex". Restores to the canonical entity value.
+  if (entityTier) {
+    const ents = [...(entities || [])].filter((e) => e && e.value)
+      .sort((a, b) => String(b.value).length - String(a.value).length);
+    for (const e of ents) {
+      const re = new RegExp(`(?<![\\w])${escapeRegex(e.value)}(?![\\w])`, 'gi');
+      out = out.replace(re, () => tokenFor(v, e.type || 'PERSON', e.value));
+    }
+  }
+
+  // 3) Deterministic detectors (all tiers).
+  for (const det of DETECTORS) {
+    out = out.replace(det.re, (m) => (!det.valid || det.valid(m) ? tokenFor(v, det.type, m) : m));
+  }
+  return out;
+}
+
+// Swap placeholders back to their originals. Unknown tokens are left untouched.
+export function restoreText(text, vault) {
+  if (text == null || !vault) return text;
+  return String(text).replace(TOKEN_RE, (m) => (vault.byToken.has(m) ? vault.byToken.get(m) : m));
+}
+
+// Restore for LOCAL use only — e.g. tool-call args that hit on-device history /
+// meeting search. Undoes reversible tokens AND pseudonyms, so local lookups run on
+// the real values. NOT used for the user-facing reply (pseudonyms stay there).
+export function restoreWithAliases(text, vault) {
+  let out = restoreText(text, vault);
+  if (vault?.aliases?.size) {
+    for (const [alias, real] of vault.aliases) {
+      if (!alias) continue;
+      out = out.replace(new RegExp(`(?<![\\w])${escapeRegex(alias)}(?![\\w])`, 'g'), () => real);
+    }
+  }
+  return out;
+}
+
+// True if the text still contains any redaction placeholder (useful for streaming
+// restore — buffer a tail when a token may be split across chunks).
+export function hasToken(text) {
+  TOKEN_RE.lastIndex = 0;
+  return TOKEN_RE.test(String(text || ''));
+}

package/pipeline.js

@@ -0,0 +1,130 @@
+// Pure turn-level orchestration shared by every ChatPanel surface (extension,
+// gateway, bridge). It composes the deterministic engine (pii-redact.js) into the
+// message pipeline and applies the tier / scope / dictionary gating.
+//
+// What lives HERE (portable): redactOutbound, redactToolResult/redactResult,
+// makeStreamRestorer, restore/restoreDeep, effectiveTier + gating.
+//
+// What stays in the EXTENSION (host glue, NOT here): reading
+// settings.ui.piiRedaction, the module-level Pro entitlement, and chrome storage.
+// Those wrap these pure functions with host-specific config.
+
+import { redactText, restoreText, restoreWithAliases } from './pii-redact.js';
+
+export function redactionEnabled(cfg) {
+  return !!(cfg && cfg.mode && cfg.mode !== 'off');
+}
+
+// The entity (name/org) tier is Pro; Free silently falls back to deterministic
+// regex so the feature still does something useful without the upsell breaking.
+export function effectiveTier(cfg, isPro) {
+  const t = cfg?.tier === 'full' ? 'full' : 'basic';
+  return t === 'full' && !isPro ? 'basic' : t;
+}
+
+// Free ceiling: deterministic SECRET redaction on CHAT only, with a small
+// dictionary. Names/orgs (full tier), wider scope, an unlimited dictionary, and
+// the model layer are Pro. Enforced here as defense-in-depth.
+export const FREE_DICT_LIMIT = 3;
+
+export function gatedDictionary(cfg, isPro) {
+  const d = Array.isArray(cfg?.dictionary) ? cfg.dictionary : [];
+  return isPro ? d : d.slice(0, FREE_DICT_LIMIT);
+}
+
+export function gatedScope(cfg, isPro) {
+  const s = cfg?.scope || {};
+  if (isPro) return s;
+  return { chat: s.chat !== false, context: false, history: false, toolResults: false };
+}
+
+export function redactOpts(cfg, isPro, entities) {
+  return {
+    tier: effectiveTier(cfg, isPro),
+    entities: entities || [],
+    dictionary: gatedDictionary(cfg, isPro),
+  };
+}
+
+// Returns redacted COPIES — never mutates the stored conversation.
+export function redactOutbound({ messages, system, vault, cfg, isPro = false, entities = [] }) {
+  if (!redactionEnabled(cfg) || !vault) return { messages, system };
+  const opts = redactOpts(cfg, isPro, entities);
+  const scope = gatedScope(cfg, isPro);
+  const redactMsg = (m) => {
+    const copy = { ...m };
+    if (scope.chat !== false && m.content) copy.content = redactText(m.content, vault, opts);
+    if (Array.isArray(m.attachments)) {
+      copy.attachments = m.attachments.map((a) => {
+        if (a.kind === 'image' || !a.text) return a;
+        const isHistory = a.kind === 'history-rag';
+        if (isHistory ? scope.history === false : scope.context === false) return a;
+        return { ...a, text: redactText(a.text, vault, opts) };
+      });
+    }
+    return copy;
+  };
+  return {
+    messages: (messages || []).map(redactMsg),
+    system: system ? redactText(system, vault, opts) : system,
+  };
+}
+
+export function redactToolResult(text, { vault, cfg, isPro = false, entities = [] } = {}) {
+  if (!redactionEnabled(cfg) || !vault || !gatedScope(cfg, isPro).toolResults) return text;
+  if (typeof text !== 'string') return text;
+  return redactText(text, vault, redactOpts(cfg, isPro, entities));
+}
+
+// Streaming-safe restorer. push() returns text safe to display now; flush() the rest.
+export function makeStreamRestorer(vault) {
+  let buf = '';
+  return {
+    push(chunk) {
+      if (!vault) return chunk || '';
+      buf += chunk || '';
+      const open = buf.lastIndexOf('[[');
+      let safe;
+      if (open !== -1 && !buf.slice(open).includes(']]')) {
+        safe = buf.slice(0, open);
+        buf = buf.slice(open);
+      } else {
+        safe = buf;
+        buf = '';
+      }
+      return restoreText(safe, vault);
+    },
+    flush() {
+      const out = vault ? restoreText(buf, vault) : buf;
+      buf = '';
+      return out;
+    },
+  };
+}
+
+export function restore(text, vault) {
+  return vault ? restoreText(text, vault) : text;
+}
+
+// Deep-restore a value (tool-call args contain tokens; local tools must run on the
+// REAL values). restoreWithAliases undoes pseudonyms too — local lookups hit real
+// data; only the model stays blinded.
+export function restoreDeep(value, vault) {
+  if (!vault) return value;
+  if (typeof value === 'string') return restoreWithAliases(value, vault);
+  if (Array.isArray(value)) return value.map((v) => restoreDeep(v, vault));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = restoreDeep(value[k], vault);
+    return out;
+  }
+  return value;
+}
+
+export function redactResult(result, ctx) {
+  if (typeof result === 'string') return redactToolResult(result, ctx);
+  if (result && typeof result === 'object' && typeof result.text === 'string') {
+    return { ...result, text: redactToolResult(result.text, ctx) };
+  }
+  return result;
+}