@chatpanel/pii 0.7.4 → 0.10.0

package/README.md

@@ -29,6 +29,8 @@ real values — and they're reconstructed locally on the way back.
 | `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 |
+| `net.js` | `isBlockedHost`, `assertEndpointUrl`, `assertPublicWebUrl`, … | the SSRF host classifier + outbound-URL guard every ChatPanel process applies |
+| `trust.js` | `callerTrust`, `classifyOrigin`, `isPaired`, `capRunOptions`, `minReach`, `createPairingStore` | who is calling a ChatPanel localhost server (pinned extension / paired token / unpaired / local), the reach ceiling that follows, and single-use pairing codes |
 
 Import the barrel (`@chatpanel/pii`) or a submodule
 (`@chatpanel/pii/pii-redact.js`).

package/detector-router.js

@@ -0,0 +1,112 @@
+// DETECTOR ROUTING — which detectors to run on THIS machine, and why (privacy-routing.md §4.4, §6).
+//
+// One model cannot cover chat text (Privacy Filter finds a lowercase name and never a city;
+// a NER model the reverse), and the best model is a 1 GB resident that would swap an 8 GB
+// laptop with a browser and a coding agent open. So the choice is a judgement about the
+// machine: how much memory detectors may take, which of the catalogued models fit, and what
+// to offer when the good ones do not — a detector on a server, which is what a hosted tier
+// is too. Pure: the catalogue, the machine and what is installed come in; a primary, a union,
+// the reasons and the alternatives come out. The gateway applies it; the clients draw it.
+
+/**
+ * How much resident memory detectors may take on a machine of this size: 8% of RAM, never
+ * under 300 MB (the small English model must always fit). 8 GB → 655 MB; 16 GB → 1.3 GB;
+ * 32 GB → 2.6 GB. The figure is a budget for the UNION, not one model: the sum of `ramMB`
+ * of everything loaded.
+ */
+export function detectorBudgetMB(totalRamMB) {
+  const total = Number(totalRamMB) || 0;
+  return Math.max(300, Math.round(total * 0.08));
+}
+
+/**
+ * Resident cost of a catalogue entry — `ramMB` when declared, else ~2.3× the q8 download:
+ * measured 2026-09-19, bert-base-NER (105 MB on disk) added ~240 MB to the process; Privacy
+ * Filter (1.6 GB int8 on disk) ~700 MB, which is why it declares `ramMB` itself.
+ */
+export function residentMB(model) {
+  if (Number(model?.ramMB) > 0) return Number(model.ramMB);
+  return Math.round((Number(model?.approxMB) || 200) * 2.3);
+}
+
+/**
+ * Is this catalogue entry a general NER model — the kind that finds places and organisations?
+ * Privacy Filter is not (no LOC/ORG label, by design); the PII-specialised multilingual model
+ * is not either for this purpose: it tags a city but measured 0 of 7 lowercase names, so it is
+ * never the model chosen to complement Privacy Filter (privacy-routing.md §3.2).
+ */
+function findsPlaces(m) { return !/private|privacy|pii/i.test(String(m.id)); }
+function isPrivacyModel(m) { return /privacy-filter/i.test(String(m.id)); }
+function multilingual(m) { return /multilingual|multilang/i.test(String(m.id)) || /multi|languages/i.test(String(m.lang || '')); }
+
+/**
+ * Recommend a primary and a union for this machine.
+ *
+ * @param catalog   [{ id, label, approxMB, ramMB?, minRamMB?, lang?, installed? }]
+ * @param machine   { totalRamMB, langs?: ['en','de',…] (languages seen in this user's text), nonLatin?: bool }
+ * @param providers optional [{ id, name, reach, capabilities: ['detect'…] }] — servers that can
+ *                  detect for this machine (an org box, the hosted tier) — offered when the
+ *                  good models do not fit here.
+ * @returns { primary, union, budgetMB, usedMB, reason, skipped: [{ id, why }], alternatives: [{ kind, id?, why }] }
+ */
+export function recommendDetector(catalog = [], machine = {}, providers = []) {
+  const budgetMB = detectorBudgetMB(machine.totalRamMB);
+  const wantMulti = !!machine.nonLatin || (Array.isArray(machine.langs) && machine.langs.some((l) => l && l !== 'en'));
+  const byId = (id) => catalog.find((m) => m.id === id);
+  const small = catalog.find((m) => /Xenova\/bert-base-NER$/.test(m.id)) || catalog[0];
+  const privacy = catalog.find(isPrivacyModel);
+  const placesModel = catalog.filter(findsPlaces).filter((m) => wantMulti ? multilingual(m) : !multilingual(m))
+    // the biggest place-finder that is not the privacy model: accuracy over size within the budget
+    .sort((a, b) => residentMB(b) - residentMB(a))[0] || small;
+
+  const chosen = [];
+  const skipped = [];
+  let usedMB = 0;
+  const take = (m, role) => {
+    if (!m || chosen.some((c) => c.id === m.id)) return false;
+    const cost = residentMB(m);
+    if (usedMB + cost > budgetMB) { skipped.push({ id: m.id, why: `${role}: needs ~${cost} MB, ${budgetMB - usedMB} MB of the ${budgetMB} MB detector budget left` }); return false; }
+    chosen.push(m); usedMB += cost; return true;
+  };
+  // The privacy model first — it is the one that finds what redaction is for — then a
+  // place-finder beside it; if the privacy model does not fit, the place-finder alone.
+  const gotPrivacy = take(privacy, 'private people, addresses, secrets');
+  take(placesModel, 'places and organisations');
+  if (!chosen.length) take(small, 'the smallest model');
+  if (!chosen.length && small) { chosen.push(small); usedMB += residentMB(small); } // the floor: always something
+
+  const primary = chosen[0].id;
+  const union = chosen.slice(1).map((m) => m.id);
+  const reasons = [];
+  if (gotPrivacy) reasons.push(`${byId(primary).label || primary} finds private people (lowercase too), addresses and secrets`);
+  if (union.length) reasons.push(`${union.map((id) => byId(id)?.label || id).join(' + ')} add${union.length === 1 ? 's' : ''} places and organisations`);
+  if (!gotPrivacy && privacy) reasons.push(`Privacy Filter (~${residentMB(privacy)} MB) does not fit the ${budgetMB} MB this machine can spare for detectors`);
+  reasons.push(`~${usedMB} MB of ${budgetMB} MB (this machine: ${Math.round((machine.totalRamMB || 0) / 1024)} GB)`);
+
+  const alternatives = [];
+  if (!gotPrivacy && privacy) {
+    const servers = (providers || []).filter((p) => (p.capabilities || p.provides || []).includes('detect'));
+    for (const p of servers) alternatives.push({ kind: p.reach === 'device' ? 'local-server' : 'server', id: p.id, why: `${p.name || p.id} can run the detection for this machine (${p.reach || 'remote'})` });
+    if (!servers.length) alternatives.push({ kind: 'server', why: 'run detection on a server — an engine server on a bigger machine, or a hosted detector — and add it under Models' });
+  }
+  return { primary, union, budgetMB, usedMB, reason: reasons.join(' · '), skipped, alternatives };
+}
+
+/**
+ * Trim a CONFIGURED union to what fits this machine, in priority order — the guard a
+ * gateway applies before loading, so a config copied to a smaller laptop never swaps it.
+ * Returns the ids to load and the ones skipped with the reason.
+ */
+export function fitUnion(primaryId, unionIds, catalog = [], machine = {}) {
+  const budgetMB = detectorBudgetMB(machine.totalRamMB);
+  const cost = (id) => residentMB(catalog.find((m) => m.id === id) || { approxMB: 200 });
+  let usedMB = cost(primaryId); // the primary always loads — the user chose it
+  const load = [];
+  const skipped = [];
+  for (const id of unionIds || []) {
+    const c = cost(id);
+    if (usedMB + c > budgetMB) { skipped.push({ id, why: `needs ~${c} MB; ${Math.max(0, budgetMB - usedMB)} MB of the ${budgetMB} MB detector budget left on this machine` }); continue; }
+    load.push(id); usedMB += c;
+  }
+  return { load, skipped, budgetMB, usedMB };
+}

package/index.js

@@ -11,6 +11,7 @@
 //   'chatpanel-pii/tool-rank.js'    deterministic tool narrowing (auto mode)
 //   'chatpanel-pii/sanitize.js'     Unicode de-steganography (strip invisible/format chars)
 //   'chatpanel-pii/net.js'          SSRF host classifier + outbound-URL guard
+//   'chatpanel-pii/trust.js'        who is calling a localhost server (origin → trust), pairing codes
 
 export * from './pii-redact.js';
 export * from './pii-detect.js';
@@ -19,3 +20,4 @@ export * from './tool-rank.js';
 export * from './tool-harness.js';
 export * from './sanitize.js';
 export * from './net.js';
+export * from './trust.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/pii",
-  "version": "0.7.4",
+  "version": "0.10.0",
   "description": "The canonical ChatPanel privacy engine \u2014 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",
@@ -12,7 +12,9 @@
     "./tool-rank.js": "./tool-rank.js",
     "./tool-harness.js": "./tool-harness.js",
     "./sanitize.js": "./sanitize.js",
-    "./net.js": "./net.js"
+    "./net.js": "./net.js",
+    "./detector-router.js": "./detector-router.js",
+    "./trust.js": "./trust.js"
   },
   "files": [
     "index.js",
@@ -23,6 +25,8 @@
     "tool-harness.js",
     "sanitize.js",
     "net.js",
+    "detector-router.js",
+    "trust.js",
     "LICENSE",
     "README.md"
   ],

package/pii-detect.js

@@ -56,6 +56,8 @@ export function withTimeout(promise, ms, signal) {
 //   • HF bert-base-NER       PER, ORG, LOC, MISC
 //   • Presidio               PERSON, PHONE_NUMBER, EMAIL_ADDRESS, US_SSN…
 //   • ai4privacy / multilang GIVENNAME, SURNAME, STREET, ZIPCODE, TELEPHONENUM…
+//   • OpenAI privacy-filter  private_person, private_address, private_email, private_phone,
+//                            private_date, private_url, account_number, secret
 //
 // When adding a model, run one sentence through it and map every label it returns. An
 // unrecognised label is a hole, and it is an invisible one.
@@ -63,7 +65,7 @@ function normType(t) {
   const s = String(t || 'ENTITY').toUpperCase().replace(/[^A-Z0-9]/g, '') || 'ENTITY';
   const map = {
     // People
-    PER: 'PERSON', PERSON: 'PERSON', PERSONNAME: 'PERSON',
+    PER: 'PERSON', PERSON: 'PERSON', PERSONNAME: 'PERSON', PRIVATEPERSON: 'PERSON',
     GIVENNAME: 'PERSON', FIRSTNAME: 'PERSON', MIDDLENAME: 'PERSON',
     SURNAME: 'PERSON', LASTNAME: 'PERSON', FULLNAME: 'PERSON',
     // Organisations
@@ -74,10 +76,11 @@ function normType(t) {
     CITY: 'LOCATION', STATE: 'LOCATION', COUNTY: 'LOCATION', COUNTRY: 'LOCATION',
     STREET: 'ADDRESS', BUILDINGNUM: 'ADDRESS', BUILDINGNUMBER: 'ADDRESS',
     ZIPCODE: 'ADDRESS', POSTCODE: 'ADDRESS', SECADDRESS: 'ADDRESS', ADDRESS: 'ADDRESS',
+    PRIVATEADDRESS: 'ADDRESS',
     NORP: 'GROUP',
     // Contact
-    EMAIL: 'EMAIL', EMAILADDRESS: 'EMAIL',
-    PHONE: 'PHONE', PHONENUMBER: 'PHONE', TELEPHONENUM: 'PHONE', PHONEIMEI: 'ID',
+    EMAIL: 'EMAIL', EMAILADDRESS: 'EMAIL', PRIVATEEMAIL: 'EMAIL',
+    PHONE: 'PHONE', PHONENUMBER: 'PHONE', TELEPHONENUM: 'PHONE', PRIVATEPHONE: 'PHONE', PHONEIMEI: 'ID',
     // Numbers that identify a person. These are ALWAYS redacted (see ALWAYS_KEEP), which is
     // the point of naming them rather than leaving them to the digit-count fallback.
     SOCIALNUM: 'SSN', USSSN: 'SSN', SSN: 'SSN',
@@ -86,7 +89,9 @@ function normType(t) {
     ACCOUNTNUM: 'ID', ACCOUNTNUMBER: 'ID', TAXNUM: 'ID', IDCARDNUM: 'ID',
     DRIVERLICENSENUM: 'ID', PASSPORTNUM: 'ID', VEHICLEVRM: 'ID',
     // A date of birth identifies; a plain date does not, and small models tag "today".
-    DATEOFBIRTH: 'ID', DOB: 'ID',
+    // privacy-filter's private_date is already the identifying kind (it tags "today" as O),
+    // and its private_url is a personal link — a profile, a shared doc — which identifies too.
+    DATEOFBIRTH: 'ID', DOB: 'ID', PRIVATEDATE: 'ID', PRIVATEURL: 'ID',
     // Handles and secrets
     USERNAME: 'ID', USERID: 'ID', IP: 'ID', IPADDRESS: 'ID', MAC: 'ID',
     PASSWORD: 'SECRET', APIKEY: 'SECRET', SECRET: 'SECRET',
@@ -137,6 +142,47 @@ export function normalizeEntities(data, types) {
   return out;
 }
 
+// CASE RECOVERY — the second pass for lowercase chat text.
+//
+// Every cased NER model is weak on a lowercase name: measured 2026-09-19, Privacy Filter
+// returned nothing for `hi. I am suresh. last time I saw you in austin…` and 1.00 for the
+// same sentence with `Suresh`; the multilingual NER tagged `Seattle` and missed `seattle`.
+// People type chat in lowercase. So a detector runs twice when the draft is lowercase-heavy:
+// once on the text, once on this re-cased copy, and the spans are unioned.
+//
+// The re-casing capitalises every word that is NOT a common word — the stop-list below —
+// so `austin` becomes `Austin` but `am` does not become `Am` (capitalising everything
+// dragged neighbours into spans: `Am Suresh`, `Priya Said`). Measured on the eight failing
+// sentences: 2 of 3 misses recovered, zero false positives on neutral prose ("summarize
+// this page about kubernetes" stays clean — `kubernetes` is capitalised and still nothing).
+//
+// LENGTH-PRESERVING BY CONSTRUCTION: only a single character is upper-cased, and only when
+// its upper-case form is one character (`ß` → `SS` would not be). So an offset into the
+// copy is the same offset into the original, and the caller takes the VALUE from the
+// original — the redactor then sees `seattle`, not `Seattle`.
+const RECASE_STOP = new Set(('a an the i am is are was were be been being to of in on at for and or but if so not no yes ok okay '
+  + 'hi hello hey you your yours me my mine we us our ours they them their he him his she her it its this that these those '
+  + 'what where when who whom why how which do does did done have has had having will would can could should may might must shall '
+  + 'there here now then last next first time day days week month year today tomorrow yesterday see saw seen say said tell told '
+  + 'go went gone come came get got give gave take took make made know knew think thought want need like just also very really '
+  + 'with from into onto over under about after before between through during without within up down out off again still '
+  + 'used use using live lived move moved work worked help please thanks thank sorry new old good bad more most some any all each '
+  + 'because as than too so such only own same other another much many few both either neither every never always often').split(/\s+/));
+
+export function recaseForDetection(text) {
+  const src = String(text || '');
+  let changed = false;
+  const out = src.replace(/(^|[^\p{L}\p{N}'’])(\p{Ll})(\p{L}*)/gu, (m, before, first, rest) => {
+    const word = first + rest;
+    if (RECASE_STOP.has(word)) return m;
+    const up = first.toUpperCase();
+    if (up.length !== 1 || up === first) return m;
+    changed = true;
+    return before + up + rest;
+  });
+  return { text: out, changed };
+}
+
 export function parseJsonLoose(s) {
   if (!s) return null;
   const a = String(s).indexOf('{');

package/trust.js

@@ -0,0 +1,192 @@
+// Who is calling a ChatPanel localhost server — and how far to trust it.
+//
+// The bridge (4319) and the gateway (4320) bind to loopback, so every caller is on this
+// machine or in this machine's browser. That is not one population, it is four, and the
+// server has to tell them apart from the two things a request carries: its `Origin` header
+// (set honestly by every browser, absent from a native process) and a per-install bearer
+// token (a file only this user can read).
+//
+//   token     the per-install token was presented → a process running as the user (the
+//             desktop app, the CLI, `chatpanel-gateway mcp`) or a client the user PAIRED.
+//   pinned    the Origin is one of ChatPanel's OWN published extension ids. A browser never
+//             lets one extension send another's origin, so this is the extension itself.
+//   unpaired  a browser extension we do not recognise, or a page on localhost. Sandboxed —
+//             no filesystem, cannot read the token — but it CAN talk to this port, and it
+//             reads whatever the reply says. Treated as a stranger at the door: allowed to
+//             chat, never to reach the machine, until the user pairs it.
+//   local     no Origin, no token: some native process. Fine for the open data plane, not
+//             for anything that spawns an agent or reconfigures a server.
+//   web       any other web origin. Refused before this classification is ever consulted;
+//             it exists so the answer is never "undefined".
+//
+// The split matters because of what an agent can do. A capped tool policy ("read-only, no
+// web tools") is a real defence when the REPLY goes somewhere safe (a paired phone) — but a
+// caller that is itself the egress reads the reply, so for an unpaired caller the only cap
+// that means anything is "no filesystem at all" (reach `device`). That is why `unpaired`
+// maps to the conversational tier, not the read tier.
+//
+// Pure: no node APIs, no crypto — so the bridge can vendor it and the extension can show a
+// user the same classification the server applied. The pairing-code store takes `now` and
+// `random` injected for the same reason.
+
+/** ChatPanel's published extension ids. A dev build has a different id — see EXTRA ids. */
+export const CHATPANEL_EXTENSION_IDS = Object.freeze([
+  'icemacffhbgnfoofclgdbcdmnlkkklem', // Chrome Web Store
+  'jkmmbleapaognlonbnllpaoeibmfkjmp', // Microsoft Edge Add-ons
+]);
+
+const EXT_ID = /^[a-p]{32}$/;
+
+/** Parse an operator's comma/space-separated extension-id list (an env var or config key). Invalid ids are dropped. */
+export function parseExtensionIds(raw) {
+  return String(raw || '')
+    .split(/[\s,]+/)
+    .map((s) => s.trim().toLowerCase().replace(/^chrome-extension:\/\//, '').replace(/\/+$/, ''))
+    .filter((s) => EXT_ID.test(s));
+}
+
+/**
+ * What an Origin header says about the sender.
+ *   'none'      no header — a native process
+ *   'pinned'    chrome-extension://<one of ours or the operator's extra ids>
+ *   'extension' chrome-extension:// or moz-extension:// we do not recognise. Firefox origins are
+ *               a per-profile UUID, so even ChatPanel's own Firefox build lands here — it pairs.
+ *   'localhost' http://localhost / 127.0.0.1 / [::1] — a dev page
+ *   'web'       anything else
+ */
+export function classifyOrigin(origin, { extensionIds = [] } = {}) {
+  const o = String(origin || '').trim();
+  if (!o) return 'none';
+  const m = /^chrome-extension:\/\/([a-p]{32})\/?$/i.exec(o);
+  if (m) {
+    const id = m[1].toLowerCase();
+    if (CHATPANEL_EXTENSION_IDS.includes(id) || (extensionIds || []).includes(id)) return 'pinned';
+    return 'extension';
+  }
+  if (/^(chrome|moz)-extension:\/\//i.test(o)) return 'extension';
+  if (/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?\/?$/i.test(o)) return 'localhost';
+  return 'web';
+}
+
+/**
+ * The trust level of one request. `hasToken` is the server's own (timing-safe) token check;
+ * this function never sees the secret. Token beats everything: a paired Firefox extension or a
+ * dev build presents the token and is trusted exactly like the pinned one.
+ */
+export function callerTrust({ origin, hasToken = false, extensionIds = [] } = {}) {
+  if (hasToken) return 'token';
+  const kind = classifyOrigin(origin, { extensionIds });
+  if (kind === 'pinned') return 'pinned';
+  if (kind === 'extension' || kind === 'localhost') return 'unpaired';
+  if (kind === 'none') return 'local';
+  return 'web';
+}
+
+/** Trusted enough to run an agent with the user's configured permissions, reconfigure a server, or mint a pairing code. */
+export function isPaired(trust) {
+  return trust === 'token' || trust === 'pinned';
+}
+
+// Reach tiers, least to most. `device` is conversational only; `trusted` is machine-wide
+// read with no egress; `any` is "no cap here — the configured permission mode applies".
+const REACH_RANK = Object.freeze({ device: 0, trusted: 1, any: 2 });
+
+/** The stricter of two reach tiers. An unknown tier is the strictest — fail closed. */
+export function minReach(a, b) {
+  const ra = REACH_RANK[a] ?? 0;
+  const rb = REACH_RANK[b] ?? 0;
+  const pick = ra <= rb ? a : b;
+  return REACH_RANK[pick] === undefined ? 'device' : pick;
+}
+
+/** The reach ceiling a caller of this trust may run an agent under, or null for "no ceiling from trust". */
+export function reachCeiling(trust) {
+  if (isPaired(trust)) return null;
+  return 'device';
+}
+
+// Run options an unpaired caller must never choose. Each one reaches the machine directly:
+// a working directory or worktree to read, credentials to hand the run, a permission mode
+// to escalate, argv/env to smuggle a flag through. With reach `device` the agent has no
+// filesystem anyway; stripping these is what makes that true before the engine is chosen.
+const UNPAIRED_STRIP = Object.freeze([
+  'workingDir', 'workspace', 'grants', 'connectionId', 'permissionMode', 'extraArgs', 'env', 'runEnv', 'reach',
+]);
+
+/**
+ * Apply a caller's ceiling to the run options a request asked for. A paired caller's options
+ * come back untouched. An unpaired caller's come back with the machine-reaching options
+ * removed and `reach` forced to the ceiling (never looser than what the body declared).
+ */
+export function capRunOptions(options, trust) {
+  const ceiling = reachCeiling(trust);
+  const src = options && typeof options === 'object' ? options : {};
+  if (!ceiling) return { ...src };
+  const out = {};
+  for (const [k, v] of Object.entries(src)) if (!UNPAIRED_STRIP.includes(k)) out[k] = v;
+  out.reach = minReach(src.reach || ceiling, ceiling);
+  return out;
+}
+
+/** Engines that enforce a reach ceiling in their tool policy. A capped run may only use one of these. */
+export const REACH_ENFORCING_ENGINES = Object.freeze(['claude']);
+
+/**
+ * Whether an engine may run under a capped reach. Only an engine that turns `reach` into a
+ * tool policy can honour a cap; any other would silently run at its configured permission
+ * mode, which is the escalation the cap exists to prevent.
+ */
+export function engineHonoursReach(engine, reach) {
+  if (!reach || reach === 'any') return true;
+  return REACH_ENFORCING_ENGINES.includes(String(engine || ''));
+}
+
+// ---------------------------------------------------------------------------------------
+// Pairing codes. How a client that CANNOT read the token file (a Firefox build, a dev build,
+// a browser on the far side of a sandbox) gets one: the user asks the running server for a
+// code (`chatpanel-gateway pair`, admin-authorized), types it into the client, and the client
+// exchanges it for the token over loopback. The code is short-lived, single-use, and a
+// handful of wrong guesses burn it — 6 digits at 5 attempts in 5 minutes is not brute-forceable
+// from a page, and the page cannot ask for a new one.
+
+export const PAIRING_TTL_MS = 5 * 60 * 1000;
+export const PAIRING_MAX_ATTEMPTS = 5;
+
+/** Render a 6-digit code as `123-456` for a human; the store compares digits only. */
+export function formatPairingCode(code) {
+  const d = String(code || '').replace(/\D/g, '');
+  return d.length === 6 ? `${d.slice(0, 3)}-${d.slice(3)}` : d;
+}
+
+/**
+ * A single-slot pairing store. Creating a new code replaces the old one, so at most one code
+ * is live per server. `random()` must return a float in [0, 1) — `Math.random` is fine for a
+ * 6-digit code that lives five minutes behind an attempt cap; pass `crypto`-backed for taste.
+ */
+export function createPairingStore({ now = () => Date.now(), random = Math.random, ttlMs = PAIRING_TTL_MS, maxAttempts = PAIRING_MAX_ATTEMPTS } = {}) {
+  let live = null; // { code, expiresAt, attempts }
+
+  function issue() {
+    const code = String(Math.floor(random() * 1e6)).padStart(6, '0');
+    live = { code, expiresAt: now() + ttlMs, attempts: 0 };
+    return { code, display: formatPairingCode(code), expiresAt: live.expiresAt };
+  }
+
+  /** Try a code. Returns { ok: true } once and burns the code; { ok: false, reason } otherwise. */
+  function claim(input) {
+    if (!live) return { ok: false, reason: 'no pairing code is active — ask the server for one' };
+    if (now() > live.expiresAt) { live = null; return { ok: false, reason: 'pairing code expired — ask for a new one' }; }
+    live.attempts += 1;
+    const guess = String(input || '').replace(/\D/g, '');
+    if (guess.length === 6 && guess === live.code) { live = null; return { ok: true }; }
+    if (live.attempts >= maxAttempts) { live = null; return { ok: false, reason: 'too many wrong codes — ask for a new one' }; }
+    return { ok: false, reason: 'wrong pairing code' };
+  }
+
+  function active() {
+    if (live && now() > live.expiresAt) live = null;
+    return live ? { expiresAt: live.expiresAt, attemptsLeft: maxAttempts - live.attempts } : null;
+  }
+
+  return { issue, claim, active };
+}