dsh-mask 0.2.9 → 0.2.10

package/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`dsh-mask` anonymizes PII at the model boundary: it rewrites the messages that enter a step so that phones, emails, ID cards, bank cards, keys, and IPs become `<TYPE_N>` placeholders, and it keeps a `placeholder → original` restore table so those placeholders can be mapped back at the display layer. The hard invariant is that **the plaintext never enters the session log** — the masked form is what gets logged and sent to the model, so model-visible content reconstructs from the log in placeholder form.
+`dsh-mask` anonymizes PII at the model boundary: it rewrites the messages that enter a step so that phones, emails, ID cards, bank cards, keys, and IPs become `<TYPE_N>` placeholders, and it keeps a `placeholder → original` restore table host-side so those placeholders stay reversible. The restore surface this form ships is the `/mask restore <text>` command plus the exported `RestoreStore` seam; automatically mapping placeholders back in the client UI is the browser half this pure-host form does not ship (see `README.md` Known limitations). The hard invariant is that **the plaintext never enters the session log** — the masked form is what gets logged and sent to the model, so model-visible content reconstructs from the log in placeholder form.
 
 ## Roles
 
@@ -71,4 +71,4 @@ The `dsh_mask` domain has one `restore` table keyed by session id. Its record ho
 
 - `mode: regex+ner` — external name/address recognition; fails loudly until a recognizer is wired in (the detector Provider seam above is the plug point).
 - `scope: tools` — implemented as `tools/post-execute` result-content masking. Tool-argument rewriting is deliberately NOT offered upstream: `tools/pre-execute`'s `PreToolDecision` has no input rewrite because logged/rendered arguments must match what ran, so `tools` scope masks the other model-visible tool surface (the result content) instead of the arguments.
-- A browser half would consume the restore table to transparently un-mask assistant bubbles; the host-side restore surface (`/mask restore` + `RestoreStore.restore`) ships, and the browser slot is feature-flagged behind `maskClientEnabled` (default false) pending live slot-catalog verification.
+- A browser half would consume the restore table to transparently un-mask assistant bubbles; the host-side restore surface (`/mask restore` + `RestoreStore.restore`) ships, and `maskClientEnabled` (default false) is the key reserved for that browser slot pending live slot-catalog verification. The key is declared in the schema and validated at load, but no runtime code reads it yet, so it has no effect until the browser half ships.

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.10] - 2026-09-12
+
+### Fixed
+
+- Correct the package description: it claimed the plugin anonymizes "names … and addresses", which the pure-host form never did — `person` and `address` are NER-only entities and `mode: regex+ner` fails loudly at load (see `README.md` Known limitations, `ARCHITECTURE.md`, `SECURITY.md`). The description now states the regex-detectable set (phone, email, ID card, bank card, key, opt-in IP) and records the NER limitation. The false claim was the only one in the repository and was visible on the npm package page; a published version cannot be corrected retroactively, so this takes effect with the next release.
+- Correct the display-layer claim in the description and in all five READMEs. Both said the restore table lets placeholders be mapped back "at the display layer" / that "the restore table and `restore()` are the complete host-side seam a client plugin would consume". There is no display-layer restore: the browser half is not shipped, `index.mjs` exports no bare `restore()` (the seam is the `RestoreStore` class, whose methods take a session id), and `RestoreStore` is a host-side class a browser half cannot consume directly. The text now states what exists — the host-side table and `RestoreStore` seam, reached through a host remote by any future client half, with `/mask restore <text>` as today's unmasking surface.
+- Describe `maskClientEnabled` accurately rather than as dead code. The key is deliberately part of the published surface — declared in `types.d.ts`, documented in `cordis.patch.yml` with its rationale, defaulted in the `Config` schema, and asserted by `test/index.test.mjs` — so it stays. What the docs now say is narrower and true: the key is schema-declared and validated at load, but no runtime code reads it yet, so it has no effect until the browser half ships.
+- Correct the "opt-in" scope in the Chinese README's request-time masking bullet: it called every entity opt-in, while only `ip` is (phone, email, ID card, bank card, and key are on by default). The English copy already said this; the Spanish, Portuguese, and Hindi bullets already scoped `(opt-in)` to `ip` and were left unchanged.
+
+### Docs
+
+- Declare the region-specific scope of the built-in detectors in all five READMEs' Known limitations: `phone` matches mainland-China mobile numbers only (`1[3-9]` plus nine digits) and `id-card` matches the 18-character Chinese resident ID only, so other countries' phone numbers and national identifiers are not detected. `email`, `ip`, and `key` are region-agnostic; `bank-card` accepts any 16-19 digit run at a lower confidence score. The behaviour is unchanged — the limitation was simply undocumented.
+
 ## [0.2.9] - 2026-09-12
 
 ### Changed

package/README-es.md

@@ -121,7 +121,8 @@ Todas las opciones son campos Schemastery `Config` (modificables desde cordis.ym
 ## Known limitations
 
 - **Solo regex.** `person` y `address` requieren un reconocedor NER externo; fallan al cargar. Cubierto de serie: teléfono, correo, documento, tarjeta, clave e IP (opt-in).
-- **La restauración visual necesita una mitad de cliente.** Enmascarar es host-side; desenmascarar burbujas en la UI es una función de navegador que esta forma host puro no incluye. La tabla y `restore()` son el seam host-side completo.
+- **Patrones específicos de región.** Los detectores `phone` e `id-card` solo reconocen formatos de China continental: `phone` es `1[3-9]` seguido de nueve dígitos, e `id-card` es un documento de residente chino de 18 caracteres (17 dígitos más un dígito o `X`). Los teléfonos y documentos de otros países no se detectan. `email`, `ip` y `key` no dependen de la región; `bank-card` acepta cualquier secuencia de 16-19 dígitos con menor confianza.
+- **La restauración visual necesita una mitad de cliente.** Enmascarar es host-side; desenmascarar burbujas en la UI es una función de navegador que esta forma host puro no incluye. El host conserva la tabla y el seam `RestoreStore` exportado (sus métodos piden un id de sesión), así que una futura mitad de cliente debe consumirlos mediante un remoto del host, no directamente; hoy la superficie de desenmascarado es el comando `/mask restore <text>`, y la clave `maskClientEnabled` se declara y valida pero ningún código en ejecución la lee todavía.
 - **Eventos en `0.1.2-rc.1`.** El host aún no registra `mask/*`, así que los appends de auditoría se omiten (las sesiones siguen cargando).
 
 ## Development

package/README-hi.md

@@ -121,7 +121,8 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 ## Known limitations
 
 - **केवल regex।** `person` और `address` को बाहरी NER पहचानकर्ता चाहिए; लोड पर विफल। बॉक्स में: फ़ोन, ईमेल, आईडी कार्ड, बैंक कार्ड, कुंजी और IP (opt-in)।
-- **डिस्प्ले-लेयर पुनर्स्थापना को क्लाइंट आधा चाहिए।** मास्किंग host-side है; UI बुलबुलों को खोलना एक ब्राउज़र-आधा सुविधा है जो यह शुद्ध-host रूप नहीं देता। तालिका और `restore()` पूर्ण host-side seam हैं।
+- **क्षेत्र-विशिष्ट पैटर्न।** `phone` और `id-card` डिटेक्टर केवल मुख्य भूमि चीन के प्रारूप पहचानते हैं: `phone` = `1[3-9]` के बाद नौ अंक, और `id-card` = 18 वर्णों वाला चीनी निवासी आईडी (17 अंक और एक अंक या `X`)। अन्य देशों के फ़ोन नंबर और राष्ट्रीय पहचान पत्र नहीं पकड़े जाते। `email`, `ip` और `key` क्षेत्र-निरपेक्ष हैं; `bank-card` किसी भी 16-19 अंकों की श्रृंखला को कम विश्वास के साथ स्वीकार करता है।
+- **डिस्प्ले-लेयर पुनर्स्थापना को क्लाइंट आधा चाहिए।** मास्किंग host-side है; UI बुलबुलों को खोलना एक ब्राउज़र-आधा सुविधा है जो यह शुद्ध-host रूप नहीं देता। host तालिका और निर्यातित `RestoreStore` seam रखता है (उसके मेथड को session id चाहिए), इसलिए भविष्य का क्लाइंट आधा उन्हें host remote से लेगा, सीधे नहीं; आज अनमास्किंग का सतह `/mask restore <text>` कमांड है, और `maskClientEnabled` कुंजी schema में घोषित व मान्य होती है पर अभी कोई रनटाइम कोड उसे नहीं पढ़ता।
 - **`0.1.2-rc.1` इवेंट।** host अभी `mask/*` दर्ज नहीं करता, इसलिए ऑडिट appends छोड़े जाते हैं (सत्र लोड होते रहते हैं)।
 
 ## Development

package/README-pt.md

@@ -121,7 +121,8 @@ Todas as opções são campos Schemastery `Config` (alteráveis via cordis.yml).
 ## Known limitations
 
 - **Somente regex.** `person` e `address` exigem um reconhecedor NER externo; falham ao carregar. Coberto de série: telefone, e-mail, documento, cartão, chave e IP (opt-in).
-- **A restauração visual precisa de uma metade de cliente.** Mascarar é host-side; desmascarar bolhas na UI é uma função de navegador que esta forma host puro não inclui. A tabela e `restore()` são o seam host-side completo.
+- **Padrões específicos de região.** Os detectores `phone` e `id-card` reconhecem apenas formatos da China continental: `phone` é `1[3-9]` seguido de nove dígitos, e `id-card` é um documento de residente chinês de 18 caracteres (17 dígitos mais um dígito ou `X`). Telefones e documentos de outros países não são detectados. `email`, `ip` e `key` não dependem da região; `bank-card` aceita qualquer sequência de 16-19 dígitos com menor confiança.
+- **A restauração visual precisa de uma metade de cliente.** Mascarar é host-side; desmascarar bolhas na UI é uma função de navegador que esta forma host puro não inclui. O host mantém a tabela e o seam `RestoreStore` exportado (seus métodos pedem um id de sessão), então uma futura metade de cliente precisa consumi-los por um remoto do host, não diretamente; hoje a superfície de desmascaramento é o comando `/mask restore <text>`, e a chave `maskClientEnabled` é declarada e validada mas nenhum código em execução a lê ainda.
 - **Eventos em `0.1.2-rc.1`.** O host ainda não registra `mask/*`, então os appends de auditoria são omitidos (sessões continuam carregando).
 
 ## Development

package/README-zh.md

@@ -35,7 +35,7 @@
 
 `dsh-mask` 在**模型边界**匿名化个人数据——消息进入模型之前——并维护一张恢复表，以便在展示层把占位符映射回原文：
 
-- **请求前遮罩** —— 重写 `agent/pre-step` 消息，使电话、邮箱、身份证、银行卡、密钥与 IP（均可按需开启）变成 `<PHONE_1>` 之类的占位符。被遮罩的文本才是落盘并发送给模型的内容。
+- **请求前遮罩** —— 重写 `agent/pre-step` 消息，使电话、邮箱、身份证、银行卡、密钥（默认开启）与 IP（可选）变成 `<PHONE_1>` 之类的占位符。被遮罩的文本才是落盘并发送给模型的内容。
 - **恢复表** —— `占位符 → 原文` 映射只存内存与受控 storage domain（`dsh_mask`）；原文绝不进会话日志。
 - **审计不含明文** —— `mask/applied` 会话事件只记「替换了 N 处 + 类型分布」，不记原文与映射。
 - **`/mask` 命令** —— `status`（计数 + 分布）、`on`/`off`（运行时开关）、`restore <text>`（还原占位符）、`help`。
@@ -139,7 +139,8 @@ profile patch 覆盖示例：
 ## Known limitations
 
 - **仅正则。** 姓名（`person`）与地址（`address`）识别需要外部 NER 识别器，纯 host 零依赖形态未捆绑；`mode: regex+ner` 与这些实体在加载期响亮失败。开箱即用覆盖电话、邮箱、身份证、银行卡、密钥与（可选）IP。
-- **展示层还原需要浏览器半。** 遮罩完全在 host 侧，但客户端 UI 中透明还原助手气泡属于浏览器半功能，本纯 host 形态未交付；恢复表与 `restore()` 是供客户端插件消费的完整 host 侧 seam，交互需求现由 `/mask restore` 覆盖。
+- **正则具地域局限。** `phone` 与 `id-card` 只匹配中国大陆格式：`phone` 为 `1[3-9]` 加九位数字，`id-card` 为 18 位中国居民身份证（17 位数字加一位数字或 `X`）。其他国家的电话号码与证件号码不会被检出。`email`、`ip`、`key` 与地域无关；`bank-card` 以较低置信度接受任意 16-19 位数字串。
+- **展示层还原需要浏览器半。** 遮罩完全在 host 侧，但客户端 UI 中透明还原助手气泡属于浏览器半功能，本纯 host 形态未交付。host 侧保留恢复表与已导出的 `RestoreStore` seam（其方法需要会话 id），因此未来的客户端半需经 host 远程面间接消费，而非直接使用；当前的反遮罩入口是 `/mask restore <text>` 命令；`maskClientEnabled` 键会被 schema 声明与校验，但尚无任何运行时代码读取它。
 - **`0.1.2-rc.1` 会话事件。** 宿主尚未收录 `mask/*` 事件类型，且其 `Session.append` 不盖章 `ignorable` 信封，因此 alpha.3 上会话日志审计 append 被跳过（会话仍可加载）；宿主收录类型或支持 `ignorable` 信封后自动开启。
 
 ## Development

package/README.md

@@ -4,7 +4,7 @@
 - **1024 store channel**: `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-mask` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking).
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-mask)
 
-**PII masking middleware for DeepSeek Harness — anonymize personal data before it reaches the model, restore it at the display layer.**
+**PII masking middleware for DeepSeek Harness — anonymize personal data before it reaches the model, keep it reversible host-side.**
 
 *Phones, emails, ID cards, bank cards, keys, and more become placeholders at the model boundary; the plaintext never enters your session log.*
 
@@ -34,9 +34,9 @@
 
 ## What you get
 
-`dsh-mask` anonymizes personal data **at the model boundary** — before a message reaches the model — and keeps a restore table so placeholders can be mapped back to the originals at the display layer:
+`dsh-mask` anonymizes personal data **at the model boundary** — before a message reaches the model — and keeps a restore table host-side so placeholders stay reversible:
 
-- **Request-time masking** — `agent/pre-step` messages are rewritten so phones, emails, ID cards, bank cards, keys, and IPs (each opt-in) become `<PHONE_1>`-style placeholders. The masked text is what gets logged and sent to the model.
+- **Request-time masking** — `agent/pre-step` messages are rewritten so phones, emails, ID cards, bank cards, and keys (on by default) and IPs (opt-in) become `<PHONE_1>`-style placeholders. The masked text is what gets logged and sent to the model.
 - **Restore table** — the `placeholder → original` map lives only in memory and a controlled storage domain (`dsh_mask`); the plaintext never enters the session log.
 - **Audit, not plaintext** — the `mask/applied` session event records only "replaced N values + type distribution", never the original text or the mapping.
 - **`/mask` command** — `status` (counts + distribution), `on`/`off` (runtime toggle), `restore <text>` (unmap placeholders), `help`.
@@ -100,7 +100,7 @@ All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id
 | `persistRestoreTable` | `true` | Persist the restore table to the controlled `dsh_mask` storage domain (`false` = memory only) |
 | `maxRestoreEntriesPerSession` | `500` | Per-session restore entry cap (oldest evicted first) |
 | `maxSessions` | `1000` | In-memory session cap (least-recently-used evicted, mapping reloaded on demand) |
-| `maskClientEnabled` | `false` | Feature flag for the browser half "reveal" bubble (defensive; off by default until the live slot catalog verifies the target slot) |
+| `maskClientEnabled` | `false` | Feature flag for the browser half "reveal" bubble (defensive; off by default until the live slot catalog verifies the target slot). The key is schema-declared and validated, but no runtime code reads it yet, so it changes nothing until the browser half ships |
 
 Example override in your profile patch:
 
@@ -142,7 +142,8 @@ Example override in your profile patch:
 ## Known limitations
 
 - **Regex only.** Name (`person`) and address (`address`) recognition needs an external NER recognizer, which the pure-host zero-dependency form does not bundle; `mode: regex+ner` and those entities fail loudly at load. The PII types covered out of the box are phone, email, ID card, bank card, key, and (opt-in) IP.
-- **Display-layer restore needs a client half.** Masking is fully host-side, but transparently un-masking the assistant bubbles in the client UI is a browser-half feature this pure-host form does not ship; the restore table and `restore()` are the complete host-side seam a client plugin would consume, and `/mask restore` covers interactive needs today.
+- **Region-specific patterns.** The `phone` and `id-card` detectors match mainland-China formats only: `phone` is `1[3-9]` followed by nine digits, and `id-card` is an 18-character Chinese resident ID (17 digits plus a digit or `X`). Phone numbers and national identifiers from other countries are not detected. `email`, `ip`, and `key` are region-agnostic; `bank-card` accepts any 16-19 digit run at a lower confidence score.
+- **Display-layer restore needs a client half.** Masking is fully host-side, but transparently un-masking the assistant bubbles in the client UI is a browser-half feature this pure-host form does not ship. The host side keeps the restore table and the exported `RestoreStore` seam (its methods take a session id), so a future client half would reach them through a host remote rather than directly; today the unmasking surface is the `/mask restore <text>` command, and the `maskClientEnabled` key is validated but read by no runtime code yet.
 - **Session events on `0.1.2-rc.1`.** The harness does not yet record `mask/*` event types, and its `Session.append` does not stamp the `ignorable` envelope, so on alpha.3 the session-log audit appends are skipped (sessions keep loading); the plugin enables them automatically once a host records the types or supports the `ignorable` envelope.
 
 ## Development

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mask",
-  "description": "PII masking middleware for DeepSeek Harness: anonymize names, phones, emails, ID cards, bank cards, keys, and addresses to placeholders before they reach the model, restore them at the display layer, keep the restore table only in memory and a controlled storage domain, never log plaintext, and expose /mask and the mask_test tool",
-  "version": "0.2.9",
+  "description": "PII masking middleware for DeepSeek Harness: regex-detect and replace phones, emails, ID cards, bank cards, keys, and (opt-in) IPs with placeholders before they reach the model, keep the restore table host-side (memory plus a controlled storage domain, never the session log) with the /mask restore command and the exported RestoreStore seam, and expose /mask status and the mask_test tool. Name and address recognition needs an external NER recognizer, which this pure-host form does not bundle: mode \"regex+ner\" and the person/address entities fail loudly at load. The phone and ID-card detectors match mainland-China formats only.",
+  "version": "0.2.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/PerryLink/dsh-mask.git"