pi-information-protecter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 — 2026-09-18
+
+首个公开版本：**个人敏感信息保护插件 — Sensitive Personal Information (SPI) Protecter**。
+
+### 新增
+
+- Pi 最终 provider 请求体的本地脱敏，覆盖系统提示、历史、工具结果及工具定义。
+- `protecter.json` 敏感词数组、字面匹配及 JavaScript 正则表达式。
+- 随机 192-bit 占位符、仅内存映射、最终回复及工具参数本地还原。
+- TUI Markdown 流式展示还原；已学习敏感值在当前实例内继续按精确值保护。
+- 配置文件 0600 权限及直接访问防护，配置异常与扫描超时的安全替代请求。
+- Worker 正则扫描与资源限制；`/protecter status` 和 `/protecter reload`。
+- 配置示例、安全边界说明及自动化测试，包括真实 Pi loader/runner 集成测试。
+
+### 兼容性与已知限制
+
+- Node.js 22+，Pi `@earendil-works/pi-coding-agent` 0.85.1–0.85.x；验证基线 0.85.1。
+- 初始规则为空，需用户本地配置；不会自动识别所有 SPI。
+- 暂不支持上下文压缩、带摘要的树导航及常见多模态附件。
+- RPC/JSON 流式 delta 保留占位符，最终消息还原；映射不会跨进程保存。
+- 不是沙箱；不防任意 shell 编码绕过，不覆盖独立网络调用、HTTP 认证 headers、本地会话及导出。详见 SECURITY.md。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-information-protecter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# pi-information-protecter
+
+**个人敏感信息保护插件 — Sensitive Personal Information (SPI) Protecter。**
+
+这是一个 Pi 扩展：在本地审查即将发往 LLM 网关的请求，用随机占位符替换配置中的个人敏感信息；模型返回占位符后，在本地还原为原始内容。可用于 URL、电话号码、身份证／ID、姓名、凭证、密码等。**它是规则驱动的意外泄漏防护，不是安全沙箱、自动 PII 识别器或加密代理。**
+
+## 安装
+
+要求 Node.js 22+、`@earendil-works/pi-coding-agent` **0.85.1–0.85.x**（验证基线 0.85.1）。旧 `@mariozechner/*` 版本不在兼容范围内。
+
+```bash
+# 安装首个版本（固定版本便于复现）
+pi install npm:pi-information-protecter@0.1.0
+
+# 或在源码仓库内本地安装；本地路径安装不会复制仓库
+pi install "$PWD"
+# 或单次加载
+pi -e ./src/index.ts
+```
+
+已运行的 Pi 请执行 `/reload`。插件注册了 worker，因此分发时需要保留完整 `src/` 目录，不能只复制 `index.ts`。
+
+版本变更见 [CHANGELOG.md](CHANGELOG.md)。源码贡献与发布流程见仓库中的 `CONTRIBUTING.md` 和 `docs/RELEASING.md`。
+
+首次会话启动时创建 `~/.pi/agent/protecter.json`，遵循 Pi 的 `PI_CODING_AGENT_DIR` 覆盖设置。不会改写已有配置，不会读取项目级同名配置。Unix 文件权限收紧为 `0600`；符号链接、硬链接、多于 1 MiB 的配置和非当前用户所有的文件会被拒绝。Windows 还需用户自行配置 ACL。
+
+## 配置敏感信息
+
+**请用本地编辑器编辑配置，不要让模型帮你填写真实密码，也不要把真实配置提交到 Git。** 初始数组为空，此时没有个人信息检测规则，界面会警告；插件不声称自动识别全部敏感信息。
+
+```json
+{
+  "version": 1,
+  "sensitiveWords": [
+    "张三",
+    { "type": "literal", "value": "your-private-password" },
+    { "type": "regex", "pattern": "https?://[^\\s\\\"<>]+", "flags": "i" },
+    { "type": "regex", "pattern": "(?<!\\d)1[3-9]\\d{9}(?!\\d)" }
+  ]
+}
+```
+
+更多示例见 [`protecter.example.json`](protecter.example.json)，这些仅为示例规则，不会自动启用。号码示例不做真实性／校验位检查，姓名和密码通常应使用精确值规则。
+
+- 字符串及 `literal`：大小写敏感、全量字面匹配（不是正则）。
+- `regex`：JavaScript 正则，替换**整个匹配**；需要只匹配凭证值时可用 lookbehind。支持 `g i m s u`，自动补 `g`。不支持 `/pattern/flags` 简写。
+- 正则中的反斜杠要按 JSON 规则写为 `\\`；不能匹配空字符串。运行中遇到零宽匹配会拒绝该请求。
+- 匹配重叠时合并区间，避免只遮住短词而暴露长词后缀；同一原文在当前扩展实例中复用同一个占位符。
+- 已匹配过的原文会在当前实例内继续按精确值保护，即使正则前缀消失或规则被删除。这样可以防止本地还原后的内容在后续请求中漏出；退出／重载后清除这些内存记录。
+- 每次请求重新读取、校验配置。`/protecter`、`/protecter status` 或 `/protecter reload` 只报告规则／内存映射数量，不打印敏感值。没有把敏感值通过命令参数添加的功能。
+- 配置最多 1000 条规则，每个词／模式最多 8192 字符；扫描时间上限 2 秒，请求 JSON 上限 8 MiB。超限拒绝，不降级为明文。
+
+## 工作方式
+
+```text
+用户输入／历史／工具结果／系统提示／工具定义
+                 ↓
+Pi before_provider_request：最终 JSON payload 文本扫描
+                 ↓
+__PIP_<192-bit random hex>__ → LLM 网关
+                 ↓
+模型回复 → 本地 message_end 还原 + tool_call 参数还原
+```
+
+1. 扫描请求 JSON 的字符串、键和数字；也会解析 JSON 字符串形式的工具参数，避免转义隐藏匹配。不会修改本地用户输入或历史原文。
+2. 使用 `crypto.randomBytes(24)` 生成占位符。映射**只保存在内存**，不写配置、会话自定义条目、日志或模型提示。用户仍可在本地看到原文。
+3. 最终 assistant 文本、thinking 和工具参数还原；TUI 的 Markdown transformer 在完整占位符到达时还原流式显示，尚未到齐时可能暂时显示部分占位符。RPC/JSON 的流式 delta 仍为占位符，最终 `message_end` 还原。占位符被模型改写或截断时无法还原。
+4. 工具执行前还原参数，让合法的本地文件操作能够使用原始值；下一次请求再次脱敏。**恢复真实凭证并不是工具授权或防外传机制。**
+5. 正则匹配在可终止 worker 中运行，避免恶意／低效正则阻塞主线程。扫描失败时请求替换为 `{}` 并请求终止，不依赖会被 Pi 吞掉的 hook 异常。可能仍产生空请求或网关校验错误，但不返回原始 payload。
+
+### 配置文件访问保护
+
+以**统一出口脱敏为主，配置直接访问拦截为辅**。不全面禁用 shell：
+
+- 在 `tool_call` 拦截明确涉及 `protecter.json` 的输入，包括常见 `read`、`write`、`edit` 和 `bash cat …`。
+- 路径参数解析 `@`、`~`、相对路径、`file://`，检查符号链接及 inode 别名。阻止 `grep/find/ls` 扫描包含配置的祖先目录。
+- 如果完整原始配置意外出现在请求文本中，也尝试整体替换。
+- **这只是尽力保护**：动态 shell、base64、分段输出、目录内部 symlink、任意第三方工具、网络发送均可绕过路径检查。不能保证恶意模型永远无法获取配置。不要把任意 shell 的能力与强隔离同时视为已实现。
+
+## 当前限制（请先读）
+
+- 只保护命中规则的文本；不识别同义改写、字符拆分、任意编码。附件中无法可靠检查 SPI，因此检测到常见图片／音频／视频／文件块时拒绝整个请求；不是 OCR。
+- 为避免摘要调用的不同生命周期泄漏／残留无法恢复的占位符，暂时取消 `/compact`、自动压缩和带摘要的 `/tree`。不带摘要的树导航可用；长会话请 `/new`。
+- 映射在退出、`/reload`、会话切换时丢弃。已完成并还原的本地消息不依赖映射；崩溃前的残留占位符、旧摘要、原始 delta 无法跨重启恢复。
+- 规则过宽（例如 `.`、全部数字或常见协议词）可能改写请求协议字段、模型名、工具 schema 或 ID，导致请求失败。数值命中会转为占位符字符串。优先使用具体规则。
+- 同一占位符会暴露“值相同”的关系；文本上下文也可能推断身份。这不是形式化匿名化。
+- 请求 hook 不覆盖 HTTP headers、认证 API key、网关地址、Pi 遥测、`/share`、其他扩展自行调用 `fetch`／模型 SDK 或工具网络访问。向模型提供服务的网关仍需要收到用于认证的网关凭证。
+- **请将本插件排在其他 payload 修改扩展之后，并且只运行受信任的扩展。** 后续处理器仍可重新加入原文；其他扩展拥有本机权限，插件无法约束它们。插件加载失败时 Pi 也可能继续运行，应检查状态再输入敏感信息。
+- 本地会话、终端、导出和工具写出的文件可能包含原文；本项目不加密或清理它们。
+
+详细威胁模型见 [SECURITY.md](SECURITY.md)。
+
+## 开发与验证
+
+```bash
+npm ci
+npm run check
+```
+
+测试使用临时目录和虚构敏感值，不读取用户真实配置，不使用真实 API key 或访问 LLM 网关。包含脱敏／还原、正则超时、配置权限、路径防护及真实 Pi 扩展加载器／事件 runner 集成测试。
+
+接口依据：[Pi Extensions](https://pi.dev/docs/latest/extensions)、本机 0.85.1 扩展文档及 runner 实现。项目遵循 MIT License。

package/SECURITY.md

@@ -0,0 +1,30 @@
+# SPI Protecter 安全边界
+
+## 目标
+
+防止正常使用 Pi 时，已配置的个人敏感信息以原始文本意外进入 LLM 请求体。威胁模型假设 Pi 核心、provider 实现、操作系统及其他已加载扩展可信，且该扩展成功加载、最终 hook 确实被调用。
+
+## 非目标
+
+- 不是操作系统沙箱，不防御同 UID 程序、恶意扩展、任意代码执行、调试器或内存抓取。
+- 不防御对文本任意编码、拆分、翻译、截图／OCR后的重构；不提供自动隐私分类或形式化匿名化。
+- 不保护网关认证 header、网关 endpoint、工具请求、独立 SDK 请求、遥测、会话导出或 `/share`。
+- 不加密本地配置／会话／终端，也不在秘密被模型推断出来后自动阻止它外传。
+
+## 实现策略
+
+- 全 payload 文本出口扫描；随机 192-bit 占位符，只在本地内存保存反向映射。
+- 正则 worker 2 秒超时、资源及输入限制。异常不包含原始配置、规则或请求文本。
+- Pi 0.85.1 runner 会捕获 before_provider_request 异常并继续发送当前 payload，因此错误路径必须返回安全替代 `{}`，并尽力 abort。不能宣传为“一定没有 HTTP 请求”，只能保证该处理器不回退原始 payload。
+- 配置单独创建，Unix 0600，读取时拒绝链接／非普通文件／多链接／其他用户所有文件。目录和操作系统权限仍需用户维护；路径检查存在 TOCTOU，不能抵御恶意本地并发修改。
+- 直接文件访问拦截只是纵深防护。`bash` 可以绕过字符串检查；配置目录祖先保护会有误拦截。
+- 配置整体文本检测只是补充，不保证各种重新格式化后的规则定义都被掩盖。
+- 辅助压缩和树摘要保守禁用。未经验证的新 Pi 版本不应直接扩大兼容范围。
+
+## 安全部署建议
+
+1. 本地填写具体规则，确认状态与规则数量；空配置并不具备个人信息检测能力。
+2. 使用虚构样例在自己信任的测试网关抓取请求验证，绝不要用真实秘密测试。
+3. 避免同时使用上传日志／导出会话／自动遥测类扩展；确认 payload 处理顺序。
+4. 高风险环境用容器／独立用户／独立文件系统，把配置放在执行工具不可访问的位置；同时限制网络出口。单靠本扩展不能提供这层保证。
+5. 不向公共 issue 提交真实配置、映射、会话或含个人信息的抓包数据。

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pi-information-protecter",
+  "version": "0.1.0",
+  "description": "Sensitive Personal Information (SPI) Protecter — local reversible privacy redaction for Pi",
+  "type": "module",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/taills/pi-information-protecter.git" },
+  "homepage": "https://github.com/taills/pi-information-protecter#readme",
+  "bugs": { "url": "https://github.com/taills/pi-information-protecter/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "keywords": ["pi-package", "pi-extension", "privacy", "redaction"],
+  "files": ["src", "README.md", "SECURITY.md", "CHANGELOG.md", "protecter.example.json", "LICENSE"],
+  "pi": { "extensions": ["./src/index.ts"] },
+  "engines": { "node": ">=22" },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": ">=0.85.1 <0.86.0" },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  }
+}

package/protecter.example.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "sensitiveWords": [
+    "张三",
+    { "type": "literal", "value": "replace-with-your-real-password" },
+    { "type": "regex", "pattern": "https?://[^\\s\\\"<>]+", "flags": "i" },
+    { "type": "regex", "pattern": "(?<!\\d)1[3-9]\\d{9}(?!\\d)" },
+    { "type": "regex", "pattern": "(?<![0-9A-Za-z])\\d{17}[0-9Xx](?![0-9A-Za-z])" },
+    { "type": "regex", "pattern": "(?<=Bearer )[A-Za-z0-9._~+/-]+=*", "flags": "i" }
+  ]
+}

package/src/config.ts

@@ -0,0 +1,120 @@
+import {
+  constants,
+  closeSync,
+  fchmodSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+export type Rule =
+  | string
+  | { type: "literal"; value: string }
+  | { type: "regex"; pattern: string; flags?: string };
+export interface Config {
+  version: 1;
+  sensitiveWords: Rule[];
+}
+export const DEFAULT_CONFIG: Config = { version: 1, sensitiveWords: [] };
+export const CONFIG_ERROR =
+  "protecter: 配置无法安全读取或格式无效；请在本地修复 protecter.json。";
+
+export function parseConfig(raw: string): Config {
+  try {
+    const value = JSON.parse(raw);
+    if (
+      !value ||
+      value.version !== 1 ||
+      !Array.isArray(value.sensitiveWords) ||
+      value.sensitiveWords.length > 1000 ||
+      Object.keys(value).some((k) => !["version", "sensitiveWords"].includes(k))
+    )
+      throw new Error();
+    for (const rule of value.sensitiveWords) {
+      if (typeof rule === "string") {
+        if (!rule || rule.length > 8192) throw new Error();
+        continue;
+      }
+      if (!rule || typeof rule !== "object") throw new Error();
+      if (rule.type === "literal") {
+        if (
+          Object.keys(rule).some((k) => !["type", "value"].includes(k)) ||
+          typeof rule.value !== "string" ||
+          !rule.value ||
+          rule.value.length > 8192
+        )
+          throw new Error();
+      } else if (rule.type === "regex") {
+        if (
+          Object.keys(rule).some(
+            (k) => !["type", "pattern", "flags"].includes(k),
+          ) ||
+          typeof rule.pattern !== "string" ||
+          !rule.pattern ||
+          rule.pattern.length > 8192 ||
+          (rule.flags !== undefined &&
+            (typeof rule.flags !== "string" || !/^[gimsu]*$/.test(rule.flags)))
+        )
+          throw new Error();
+        const re = new RegExp(rule.pattern, rule.flags ?? "");
+        if (re.test("")) throw new Error();
+      } else throw new Error();
+    }
+    return value;
+  } catch {
+    throw new Error(CONFIG_ERROR);
+  }
+}
+
+/** Do not follow a symlink, accept a hard-linked file, or print parser/OS errors containing secrets. */
+export function loadConfig(
+  path: string,
+  create = false,
+): { config: Config; raw: string } {
+  let fd: number | undefined;
+  try {
+    if (create) {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      try {
+        const initial = openSync(
+          path,
+          constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+          0o600,
+        );
+        try {
+          writeFileSync(
+            initial,
+            JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n",
+          );
+        } finally {
+          closeSync(initial);
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+    }
+    fd = openSync(
+      path,
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    );
+    const stat = fstatSync(fd);
+    if (
+      !stat.isFile() ||
+      stat.nlink !== 1 ||
+      stat.size > 1024 * 1024 ||
+      (process.getuid && stat.uid !== process.getuid())
+    )
+      throw new Error();
+    if (process.platform !== "win32") fchmodSync(fd, 0o600);
+    const raw = readFileSync(fd, "utf8");
+    if (Buffer.byteLength(raw) > 1024 * 1024) throw new Error();
+    return { config: parseConfig(raw), raw };
+  } catch {
+    throw new Error(CONFIG_ERROR);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}

package/src/engine.ts

@@ -0,0 +1,114 @@
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.ts";
+
+export const REQUEST_ERROR =
+  "protecter: 请求已清空。配置无效、扫描超时或包含不支持的附件；修复后重试。";
+export class Protecter {
+  private readonly tokens = new Map<string, string>();
+  private queue: Promise<unknown> = Promise.resolve();
+  private readonly workers = new Set<Worker>();
+  private closed = false;
+  constructor(
+    readonly configPath: string,
+    private readonly timeoutMs = 2000,
+  ) {}
+
+  initialize(): void {
+    loadConfig(this.configPath, true);
+  }
+  get mappingCount(): number {
+    return this.tokens.size;
+  }
+
+  /** Serialise scans so two requests cannot assign different tokens to the same value. */
+  redact(payload: unknown): Promise<unknown> {
+    const run = this.queue.then(() => this.scan(payload));
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  private async scan(payload: unknown): Promise<unknown> {
+    if (this.closed) throw new Error(REQUEST_ERROR);
+    const { config, raw } = loadConfig(this.configPath);
+    const serialized = JSON.stringify(payload);
+    if (!serialized || Buffer.byteLength(serialized) > 8 * 1024 * 1024)
+      throw new Error(REQUEST_ERROR);
+    let snapshot: unknown;
+    try {
+      snapshot = JSON.parse(serialized);
+    } catch {
+      throw new Error(REQUEST_ERROR);
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const worker = new Worker(
+        fileURLToPath(new URL("./scan-worker.mjs", import.meta.url)),
+        {
+          workerData: {
+            payload: snapshot,
+            rules: config.sensitiveWords,
+            entries: [...this.tokens],
+            configRaw: raw,
+          },
+          resourceLimits: { maxOldGenerationSizeMb: 128 },
+        },
+      );
+      this.workers.add(worker);
+      const finish = (data?: {
+        payload: unknown;
+        additions: [string, string][];
+      }) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.workers.delete(worker);
+        void worker.terminate();
+        if (!data || this.closed) {
+          reject(new Error(REQUEST_ERROR));
+          return;
+        }
+        for (const [token, original] of data.additions)
+          this.tokens.set(token, original);
+        resolve(data.payload);
+      };
+      const timer = setTimeout(() => finish(), this.timeoutMs);
+      worker.once("message", (data) => finish(data.failed ? undefined : data));
+      worker.once("error", () => finish());
+      worker.once("exit", () => finish());
+    });
+  }
+
+  restoreText(text: string): string {
+    // One pass, never recursively expand text introduced by a replacement.
+    return text.replace(
+      /__PIP_[a-f0-9]{48}__/g,
+      (token) => this.tokens.get(token) ?? token,
+    );
+  }
+
+  restore<T>(value: T, depth = 0): T {
+    if (depth > 80) throw new Error("protecter: 响应层级过深。");
+    if (typeof value === "string") return this.restoreText(value) as T;
+    if (Array.isArray(value))
+      return value.map((item) => this.restore(item, depth + 1)) as T;
+    if (value && typeof value === "object") {
+      const result: Record<string, unknown> = Object.create(null);
+      for (const [key, item] of Object.entries(value)) {
+        const nextKey = this.restoreText(key);
+        if (Object.hasOwn(result, nextKey))
+          throw new Error("protecter: 响应键冲突。");
+        result[nextKey] = this.restore(item, depth + 1);
+      }
+      return result as T;
+    }
+    return value;
+  }
+
+  close(): void {
+    this.closed = true;
+    this.tokens.clear();
+    for (const worker of this.workers) void worker.terminate();
+    this.workers.clear();
+  }
+}

package/src/guard.ts

@@ -0,0 +1,65 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function normalized(path: string, cwd: string): string {
+  let value = path.replace(/^@/, "");
+  if (value.startsWith("file://")) value = fileURLToPath(value);
+  if (value === "~" || value.startsWith("~/"))
+    value = homedir() + value.slice(1);
+  return resolve(cwd, value);
+}
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    return parent === path
+      ? path
+      : resolve(canonical(parent), relative(parent, path));
+  }
+}
+function contains(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function sameFile(a: string, b: string): boolean {
+  try {
+    const x = statSync(a),
+      y = statSync(b);
+    return x.dev === y.dev && x.ino === y.ino;
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort access guard. Arbitrary shell/third-party tools are NOT sandboxed. */
+export function blocksConfigAccess(
+  tool: string,
+  input: Record<string, unknown>,
+  cwd: string,
+  configPath: string,
+): boolean {
+  const target = canonical(resolve(configPath));
+  const serialized = JSON.stringify(input);
+  if (/protecter\.json/i.test(serialized) || serialized.includes(configPath))
+    return true;
+  const candidate = input.path ?? input.file_path ?? input.filePath;
+  const recursive = ["grep", "find", "ls"].includes(tool);
+  if (typeof candidate !== "string" && !recursive) return false;
+  try {
+    const path = normalized(
+      typeof candidate === "string" ? candidate : ".",
+      cwd,
+    );
+    const real = canonical(path);
+    return (
+      real === target ||
+      sameFile(path, configPath) ||
+      (recursive && contains(real, target))
+    );
+  } catch {
+    return true;
+  }
+}

package/src/index.ts

@@ -0,0 +1,146 @@
+import {
+  getAgentDir,
+  VERSION,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { loadConfig } from "./config.ts";
+import { Protecter, REQUEST_ERROR } from "./engine.ts";
+import { blocksConfigAccess } from "./guard.ts";
+
+/** Explicitly install this after other extensions that rewrite outgoing payloads. */
+export default function informationProtecter(pi: ExtensionAPI): void {
+  const engine = new Protecter(join(getAgentDir(), "protecter.json"));
+  const compatible =
+    /^0\.85\./.test(VERSION) && Number(VERSION.split(".")[2]) >= 1;
+  let healthy = false;
+
+  pi.on("session_start", (_event, ctx) => {
+    try {
+      if (!compatible) throw new Error();
+      engine.initialize();
+      healthy = true;
+      const count = loadConfig(engine.configPath).config.sensitiveWords.length;
+      ctx.ui.setStatus("protecter", `SPI Protecter · ${count} rules`);
+      if (count === 0)
+        ctx.ui.notify(
+          "SPI Protecter：敏感词数组为空，请在本地编辑 protecter.json 后使用。",
+          "warning",
+        );
+    } catch {
+      healthy = false;
+      ctx.ui.notify(REQUEST_ERROR, "error");
+    }
+  });
+
+  pi.on("before_provider_request", async (event, ctx) => {
+    try {
+      if (!compatible) throw new Error();
+      const payload = await engine.redact(event.payload);
+      healthy = true;
+      return payload;
+    } catch {
+      healthy = false;
+      // Pi catches thrown hook errors and continues with the ORIGINAL payload.
+      // Always return an empty replacement first; abort/notifications are best-effort.
+      try {
+        await ctx.abort();
+      } catch {
+        /* replacement below remains mandatory */
+      }
+      try {
+        ctx.ui.notify(REQUEST_ERROR, "error");
+      } catch {
+        /* never fail open */
+      }
+      return {}; // May produce a provider validation error, but contains NO original data.
+    }
+  });
+
+  pi.on("message_end", (event) => {
+    if (event.message.role !== "assistant") return;
+    // Preserve IDs, signatures, usage and provider metadata; only restore user-facing content.
+    const message = event.message;
+    return {
+      message: {
+        ...message,
+        content: message.content.map((block) => {
+          if (block.type === "text")
+            return { ...block, text: engine.restoreText(block.text) };
+          if (block.type === "thinking")
+            return { ...block, thinking: engine.restoreText(block.thinking) };
+          if (block.type === "toolCall")
+            return { ...block, arguments: engine.restore(block.arguments) };
+          return block;
+        }),
+        ...(message.errorMessage
+          ? { errorMessage: engine.restoreText(message.errorMessage) }
+          : {}),
+      },
+    };
+  });
+
+  pi.registerMarkdownTransformer((text, context) =>
+    context.messageType === "user" ? text : engine.restoreText(text),
+  );
+
+  pi.on("tool_call", (event, ctx) => {
+    if (!healthy) return { block: true, reason: "SPI Protecter 尚未就绪。" };
+    const restored = engine.restore(event.input);
+    for (const key of Object.keys(event.input))
+      delete (event.input as Record<string, unknown>)[key];
+    Object.assign(event.input, restored);
+    if (
+      blocksConfigAccess(
+        event.toolName,
+        event.input,
+        ctx.cwd,
+        engine.configPath,
+      )
+    ) {
+      return {
+        block: true,
+        reason: "SPI Protecter：禁止工具访问保护配置，请由用户在本地编辑。",
+      };
+    }
+  });
+
+  // These auxiliary request paths have different lifecycle/response restoration semantics.
+  // Until separately verified, cancel instead of silently sending plaintext summaries.
+  pi.on("session_before_compact", (_event, ctx) => {
+    ctx.ui.notify(
+      "SPI Protecter：暂不支持远程上下文压缩，请使用 /new 开始新会话。",
+      "warning",
+    );
+    return { cancel: true };
+  });
+  pi.on("session_before_tree", (event) =>
+    event.preparation.userWantsSummary ? { cancel: true } : undefined,
+  );
+
+  pi.registerCommand("protecter", {
+    description: "SPI Protecter 状态与本地配置校验（不显示敏感值）",
+    handler: async (args, ctx) => {
+      if (args.trim() && !["status", "reload"].includes(args.trim())) {
+        ctx.ui.notify(
+          "用法：/protecter [status|reload]。不要在命令参数中填写敏感值。",
+          "info",
+        );
+        return;
+      }
+      try {
+        if (!compatible) throw new Error();
+        const { config } = loadConfig(engine.configPath);
+        healthy = true;
+        ctx.ui.notify(
+          `SPI Protecter：${config.sensitiveWords.length} 条规则；${engine.mappingCount} 个内存映射。配置每次请求重新读取。`,
+          "info",
+        );
+      } catch {
+        healthy = false;
+        ctx.ui.notify(REQUEST_ERROR, "error");
+      }
+    },
+  });
+  pi.on("session_shutdown", () => engine.close());
+}

package/src/scan-worker.mjs

@@ -0,0 +1,150 @@
+// A separate worker bounds user-supplied JavaScript regex execution (including ReDoS).
+import { parentPort, workerData } from "node:worker_threads";
+import { randomBytes } from "node:crypto";
+
+try {
+  const { payload, rules, entries, configRaw } = workerData;
+  const originalToToken = new Map(
+    entries.map(([token, original]) => [original, token]),
+  );
+  const tokenToOriginal = new Map(entries);
+  const additions = [];
+  const matchers = rules.map((rule) => {
+    if (typeof rule === "string") return { literal: rule };
+    if (rule.type === "literal") return { literal: rule.value };
+    return {
+      regex: new RegExp(
+        rule.pattern,
+        [...new Set((rule.flags ?? "") + "g")].join(""),
+      ),
+    };
+  });
+  // A restored value may lose its original regex context (e.g. a Bearer prefix).
+  // Keep learned originals protected for the lifetime of this extension instance.
+  for (const original of originalToToken.keys())
+    matchers.push({ literal: original });
+  // Defense in depth for an accidentally pasted full configuration (not a sandbox).
+  const compactConfig = JSON.stringify(JSON.parse(configRaw));
+  matchers.push({ literal: configRaw }, { literal: compactConfig });
+  const payloadText = JSON.stringify(payload);
+  let matches = 0;
+  let nodes = 0;
+  function tokenFor(original) {
+    let token = originalToToken.get(original);
+    if (token) return token;
+    if (tokenToOriginal.size >= 50000) throw new Error();
+    do {
+      token = `__PIP_${randomBytes(24).toString("hex")}__`;
+    } while (tokenToOriginal.has(token) || payloadText.includes(token));
+    originalToToken.set(original, token);
+    tokenToOriginal.set(token, original);
+    additions.push([token, original]);
+    return token;
+  }
+  function redactPlain(text) {
+    const spans = [];
+    for (const matcher of matchers) {
+      if (matcher.literal === undefined) {
+        matcher.regex.lastIndex = 0;
+        for (const match of text.matchAll(matcher.regex)) {
+          if (!match[0].length) throw new Error();
+          spans.push([match.index, match.index + match[0].length]);
+          if (++matches > 100000) throw new Error();
+        }
+      } else {
+        if (!matcher.literal) continue;
+        let start = 0;
+        while ((start = text.indexOf(matcher.literal, start)) !== -1) {
+          spans.push([start, start + matcher.literal.length]);
+          if (++matches > 100000) throw new Error();
+          start++; // Include overlapping occurrences.
+        }
+      }
+    }
+    spans.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    const merged = [];
+    for (const span of spans) {
+      const prev = merged.at(-1);
+      if (prev && span[0] < prev[1]) prev[1] = Math.max(prev[1], span[1]);
+      else merged.push([...span]);
+    }
+    let result = "",
+      cursor = 0;
+    for (const [start, end] of merged) {
+      result += text.slice(cursor, start) + tokenFor(text.slice(start, end));
+      cursor = end;
+    }
+    return result + text.slice(cursor);
+  }
+  function redact(text) {
+    // Only OUR tokens are exempt, not arbitrary strings with a similar prefix.
+    let result = "",
+      cursor = 0;
+    for (const match of text.matchAll(/__PIP_[a-f0-9]{48}__/g)) {
+      if (!tokenToOriginal.has(match[0])) continue;
+      result += redactPlain(text.slice(cursor, match.index)) + match[0];
+      cursor = match.index + match[0].length;
+    }
+    return result + redactPlain(text.slice(cursor));
+  }
+  function walk(value, depth = 0) {
+    if (++nodes > 200000 || depth > 80) throw new Error();
+    if (typeof value === "string") {
+      if (value.includes(configRaw) || value.includes(compactConfig))
+        return redact(value);
+      // OpenAI serializes tool arguments as JSON strings: decode escapes BEFORE matching.
+      if (/^\s*[[{]/.test(value)) {
+        let parsed;
+        try {
+          parsed = JSON.parse(value);
+        } catch {
+          /* ordinary prose */
+        }
+        if (parsed && typeof parsed === "object") {
+          const inner = JSON.stringify(walk(parsed, depth + 1));
+          const outer = redact(inner);
+          if (outer === inner) return inner;
+          // A rule may span JSON syntax or match a whole JSON-shaped secret.
+          // Return altered JSON only if it still parses; otherwise reject the request.
+          JSON.parse(outer);
+          return outer;
+        }
+      }
+      return redact(value);
+    }
+    if (typeof value === "number") {
+      const transformed = redact(String(value));
+      return transformed === String(value) ? value : transformed;
+    }
+    if (Array.isArray(value)) return value.map((item) => walk(item, depth + 1));
+    if (value && typeof value === "object") {
+      // No claim to perform OCR or redact opaque attachments. Reject rather than leak.
+      if (
+        typeof value.type === "string" &&
+        /image|audio|video|document|(^|_)file($|_)/i.test(value.type)
+      )
+        throw new Error();
+      if (
+        Object.keys(value).some((key) =>
+          /^(inlineData|inline_data|fileData|file_data|image_url|input_audio)$/.test(
+            key,
+          ),
+        )
+      )
+        throw new Error();
+      const result = Object.create(null);
+      for (const [key, item] of Object.entries(value)) {
+        const nextKey = redact(key);
+        if (Object.hasOwn(result, nextKey)) throw new Error();
+        result[nextKey] = walk(item, depth + 1);
+      }
+      return result;
+    }
+    if (value === null || typeof value === "boolean") return value;
+    throw new Error();
+  }
+  parentPort.postMessage({ payload: walk(payload), additions });
+} catch {
+  // Never serialize an exception, original payload or configuration back into diagnostics.
+  parentPort.postMessage({ failed: true });
+}