@zxh126/pi-redact-secrets 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Redacts `input`, `tool_result` (including `structuredContent`) and `message_end`
+  before content reaches the model or the session file.
+- Standard rule set: PEM blocks, `Authorization` headers, OpenAI/GitHub/npm/AWS
+  tokens, JWTs, DSN passwords, URL userinfo, JSON secret fields, and
+  `KEY=value` assignments (prefixes and full-width colons included).
+- Optional `strict` profile with a high-entropy rule.
+- Literal secrets from `secrets`, `secretFiles` (dotenv/TOML/YAML/JSON) and an
+  external `secretCommand`.
+- `/redact`, `/redact reload`, `/redact init` commands.
+- Idempotent replacements, per-rule hit counts, and a value-free log file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 harry zhang
+
+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

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# pi-redact-secrets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](./README.zh-CN.md)
+
+Redact secrets **before** they reach the model or the session file.
+
+A [pi](https://pi.dev) extension that hooks the three places where text enters a
+conversation and masks credentials in flight:
+
+| Hook | Catches |
+|---|---|
+| `input` | Anything you type or paste — including messages relayed from Telegram/QQ/Slack bridges |
+| `tool_result` | Output of every tool: `bash`, `pwsh`, `read`, `grep`, MCP servers, codemode scripts |
+| `message_end` | The model's own output, so it cannot echo a secret back into the transcript |
+
+Because redaction happens on the way in, the secret never reaches the model
+context and never lands in `~/.pi/agent/sessions/*.jsonl`.
+
+```
+you / tool ──▶ [ redact ] ──▶ model context ──▶ session file
+                    │
+                    └─ patterns (known shapes) + literals (your exact values)
+```
+
+## Install
+
+```bash
+pi install npm:@zxh126/pi-redact-secrets
+```
+
+Try it without changing your settings:
+
+```bash
+pi -e npm:@zxh126/pi-redact-secrets
+```
+
+Then start pi (or `/reload` a running session) and check the status:
+
+```
+/redact
+```
+
+## Configure
+
+Everything is optional. Without a config file you get the standard rule set and no
+literal secrets.
+
+```bash
+/redact init       # writes ~/.pi/agent/redact-secrets.json with the defaults
+```
+
+```jsonc
+// ~/.pi/agent/redact-secrets.json
+{
+  "redactInput": true,
+  "redactToolResult": true,
+  "redactMessage": true,
+  "profile": "standard",          // "standard" | "strict"
+  "secrets": ["my-exact-password"],
+  "secretFiles": ["~/.env", "~/.pi/agent/dbhub/mysql.toml"],
+  "secretCommand": {
+    "command": "pwsh",
+    "args": ["-NoProfile", "-File", "~/.pi/agent/dump-secrets.ps1"],
+    "timeoutMs": 8000
+  },
+  "minSecretLength": 8,
+  "logFile": "~/.pi/agent/redact-secrets.log"
+}
+```
+
+Set `PI_REDACT_SECRETS_CONFIG` to use a different config path (handy for projects).
+
+| Key | Default | Meaning |
+|---|---|---|
+| `redactInput` | `true` | Redact user input. Turn off if you sometimes need to hand a real secret to the model on purpose. |
+| `redactToolResult` | `true` | Redact tool output. |
+| `redactMessage` | `true` | Redact finalized messages. |
+| `profile` | `"standard"` | `strict` adds a high-entropy rule for random strings that match no known shape. Noisier because base64 blobs match too. |
+| `secrets` | `[]` | Literal values to replace verbatim. |
+| `secretFiles` | `[]` | Files to mine for literals: `.env`/TOML/YAML `KEY=value` lines with secret-looking keys, `scheme://user:pass@` DSNs, and `.json` files with secret-looking keys. |
+| `secretCommand` | — | Executable whose stdout is a JSON array of literal strings, or one secret per line. Runs without a shell, with a timeout. |
+| `minSecretLength` | `8` | Shorter literals are ignored — they would corrupt ordinary text. |
+| `logFile` | `~/.pi/agent/redact-secrets.log` | One line per redaction: counts per rule, never the values. |
+
+### Why literals matter
+
+Patterns only catch *recognisable* secrets (`sk-…`, `ghp_…`, PEM blocks, DSNs,
+`password=…`). A database password like `264613@Ms` looks like ordinary text and
+would slip through. Literals close that gap: point `secretFiles` at the config
+files your machine already uses, or have `secretCommand` produce the values at
+session start.
+
+The extension ships **no cryptography of its own**. It reads plaintext once at
+session start and keeps it in memory, so encryption is the job of the secret
+store you already trust — one per platform:
+
+| Platform | Store | `secret-tool`-style command |
+|---|---|---|
+| Windows | DPAPI (`CryptProtectData`) | `pwsh -File dump-secrets.ps1` |
+| macOS | Keychain | `security find-generic-password -s pi-secrets -w` |
+| Linux (desktop) | Secret Service (GNOME Keyring / KWallet) | `secret-tool lookup service pi-secrets` |
+| Linux (server) | `0600` file, or `systemd-creds` on systemd ≥ 250 | `cat ~/.pi-secrets` / `systemd-creds decrypt x.cred -` |
+
+Two constraints matter when you pick one, because `secretCommand` runs without a
+TTY (so nothing can prompt for a passphrase at session start):
+
+- **Must be unlocked without a prompt.** DPAPI, Keychain and Secret Service all
+  qualify: the OS already holds the key from your login. `gpg`, `age` and `pass`
+  do **not** — they ask for a passphrase through pinentry, which fails from a
+  background command unless an agent is already unlocked. If you want them
+  anyway, use `--pinentry-mode loopback --passphrase-file`, or a wrapper that
+  pulls the passphrase from a keyring.
+- **Durability.** User-scope DPAPI blobs are bound to the user profile. Windows
+  re-encrypts the master keys when you change your *own* password, but an
+  **administrator password reset** (or a profile rebuild) leaves them
+  undecryptable — the secrets are gone, and Windows Credential Manager entries
+  (git credentials, RDP passwords) go with them. Keep a password reset disk, or
+  put long-lived secrets somewhere whose recovery does not depend on the account
+  (password manager, hardware token, `systemd-creds` with TPM). This is the same
+  trade-off any login-bound key store makes, including Keychain and Secret
+  Service — DPAPI is not special here, it is just the one that fails loudest.
+
+Each of those is one executable that prints the values, so `secretCommand` stays
+platform-neutral:
+
+```jsonc
+// Windows — DPAPI blobs, decrypted by PowerShell
+{ "secretCommand": { "command": "pwsh", "args": ["-NoProfile", "-File", "~/dump-secrets.ps1"] } }
+
+// macOS — one Keychain item per line
+{ "secretCommand": { "command": "security", "args": ["find-generic-password", "-s", "pi-secrets", "-w"] } }
+
+// Linux — Secret Service
+{ "secretCommand": { "command": "secret-tool", "args": ["lookup", "service", "pi-secrets"] } }
+
+// Linux without a keyring — a file only your account can read
+{ "secretCommand": { "command": "cat", "args": ["/home/me/.pi-secrets"] } }
+```
+
+A command may print either a JSON array of strings or plain lines (one secret per
+line). Shell pipelines need an explicit shell, because `secretCommand` never uses
+one: `{ "command": "sh", "args": ["-c", "pass show pi/secrets"] }`.
+
+A Windows DPAPI example (`dump-secrets.ps1`) that prints a JSON array:
+
+```powershell
+$list = [System.Collections.Generic.List[string]]::new()
+function AddV($v) {
+  if (-not $v) { return }
+  $s = [string]$v
+  if ($s.Length -ge 8 -and $s -notmatch '^\d+$') { if (-not $list.Contains($s)) { $list.Add($s) } }
+}
+# … read your own config files or decrypt DPAPI blobs here …
+AddV (ConvertTo-SecureString (Get-Content "$HOME\.secret.dpapi" -Raw) |
+  ForEach-Object { [Runtime.InteropServices.Marshal]::PtrToStringBSTR(
+    [Runtime.InteropServices.Marshal]::SecureStringToBSTR($_)) })
+ConvertTo-Json -InputObject @($list) -Compress
+```
+
+On Linux, the equivalent without a keyring is a `chmod 600` file; if you need it
+encrypted and prompt-free, use `systemd-creds` (systemd ≥ 250) or a TPM-backed
+store:
+
+```bash
+printf '%s\n' "$DB_PASSWORD" "$SMTP_CODE" > ~/.pi-secrets
+chmod 600 ~/.pi-secrets
+# secretCommand = { command = "cat", args = ["/home/me/.pi-secrets"] }
+```
+
+`secretFiles` is the zero-setup option: it works with a `chmod 600` file you
+already have (`.env`, `~/.pgpass`-style configs, `dbhub/mysql.toml`). It gives you
+no encryption, only whatever filesystem permissions you set — fine for a
+single-user laptop, not enough for a shared host.
+
+## Rules
+
+| Rule | Example input | Output |
+|---|---|---|
+| `pem` | `-----BEGIN OPENSSH PRIVATE KEY-----…` | `<REDACTED-PEM>` |
+| `auth-header` | `Authorization: Bearer abcdef123456` | `Authorization: Bearer <REDACTED>` |
+| `openai-key` | `sk-proj-abcdefghijklmnop` | `sk-<REDACTED>` |
+| `github-token` | `ghp_abcdefghijklmnopqrst` | `<REDACTED-GH>` |
+| `npm-token` | `npm_abcdefghijklmnopqrstuvwxyz` | `npm_<REDACTED>` |
+| `aws-access-key` | `AKIAIOSFODNN7EXAMPLE` | `AKIA<REDACTED>` |
+| `jwt` | `eyJhbGciOi….eyJzdWIi….s3cr3t` | `<REDACTED-JWT>` |
+| `dsn` | `mysql://root:pa55word@host/db` | `mysql://root:***@host/db` |
+| `url-userinfo` | `https://user:pass@host` | `https://***:***@host` |
+| `json-secret` | `{"appSecret": "eFh2DD4o…"}` | `{"appSecret": "<REDACTED>"}` |
+| `key-value` | `SMTP_PASS=…`, `db_password: …`, `密码：…` | `SMTP_PASS=<REDACTED>` |
+| `high-entropy` (strict) | long mixed-case random string | `<REDACTED-HIGH-ENTROPY>` |
+
+Rules are **idempotent**: already-masked values (`***`, `<REDACTED>`) are not
+matched again, so text is not rewritten twice when a session is resumed.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/redact` | Rule count, literal count and sources, toggles, config and log paths |
+| `/redact reload` | Re-read the config file and re-run `secretCommand` |
+| `/redact init` | Write a sample config (never overwrites) |
+
+## Platform support
+
+The extension is plain Node.js: no native modules, no shell-outs, no platform branches.
+
+| | Status |
+|---|---|
+| Windows 10/11 | Verified (Node 24, PowerShell 7 + pi 1.4) |
+| macOS | Expected to work — same code paths as Linux |
+| Linux (x64/arm64) | Expected to work; `ubuntu-latest` × Node 22/24 in CI |
+
+- **Node ≥ 22.18** is required, because the package ships TypeScript sources and
+  relies on Node's native type stripping (pi itself already requires Node 22+).
+- Paths use `path.join`/`os.homedir()`; `~` and `~/` are expanded in config values.
+  No drive letters or Windows-only APIs anywhere.
+- `secretCommand` runs through `execFile` **without a shell**, so the command and
+  its arguments are platform-native (`pwsh` on Windows, `sh`/`node`/`python3` on
+  Linux). Nothing is hardcoded.
+- The log file is created with mode `0600` on POSIX (ignored on Windows).
+
+## What it does not do
+
+- **Tool arguments are not redacted.** Rewriting `bash`/`pwsh` arguments would
+  change what actually runs, so `pwsh -Command "login --password hunter2"` keeps the
+  secret in the tool call. Put secrets in environment variables or files instead.
+- **`tool_result.details` is left alone** — UI renderers depend on it.
+- Redaction is best-effort, pattern-based. It reduces exposure; it is not a
+  guarantee. Anything that never leaves the machine is still the safer design.
+- Secrets already written to a session file stay there. Use a one-off pass over
+  `~/.pi/agent/sessions/**/*.jsonl` if you need to clean history.
+
+## Development
+
+```bash
+git clone <repo> && cd pi-redact-secrets
+npm test          # node --test, no build step needed (Node ≥ 22.18 strips types)
+npm run check     # tsc --noEmit
+pi -e .           # load the package from this directory
+```
+
+CI runs `npm test` and `npm run check` on `ubuntu-latest` with Node 22 and 24.
+`test/extension.test.ts` drives the extension through a fake `ExtensionAPI`, so the
+three hooks, config loading, literal collection and the log file are covered without
+starting pi.
+
+Layout:
+
+```
+src/index.ts     pi wiring: hooks + /redact command
+src/rules.ts     pattern rules and replacement templates
+src/redactor.ts  pure redaction engine (unit-tested, no I/O)
+src/literals.ts  literal-secret collection (config, files, command)
+src/config.ts    config schema, defaults and validation
+```
+
+The engine has no pi dependency, so it can be embedded elsewhere:
+
+```ts
+import { Redactor } from "@zxh126/pi-redact-secrets/src/redactor.ts";
+
+const redactor = new Redactor({ profile: "strict" });
+redactor.setSecrets(["my-exact-password"]);
+redactor.redact("password=my-exact-password"); // { text: "password=<REDACTED>", hits: 1, byRule: {…} }
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,250 @@
+# pi-redact-secrets
+
+[English](./README.md) · **简体中文**
+
+在内容**进入模型上下文或写入会话文件之前**把敏感串替换掉。
+
+一个 [pi](https://pi.dev) 扩展，挂在文本进入对话的三条路径上：
+
+| 钩子 | 覆盖范围 |
+|---|---|
+| `input` | 你输入/粘贴的内容——包括从 QQ、Telegram、Slack 等桥接进来的消息 |
+| `tool_result` | 所有工具输出：`bash`、`pwsh`、`read`、`grep`、MCP、codemode 脚本 |
+| `message_end` | 模型自己的输出，避免它把密钥复述回对话里 |
+
+因为脱敏发生在入口处，密钥不会进入模型上下文，也不会写进
+`~/.pi/agent/sessions/*.jsonl`。
+
+```
+你 / 工具 ──▶ [ 脱敏 ] ──▶ 模型上下文 ──▶ 会话文件
+                 │
+                 └─ 规则（已知形状） + 字面量（你机器上的真实值）
+```
+
+## 安装
+
+```bash
+pi install npm:@zxh126/pi-redact-secrets
+```
+
+只想临时试用、不动配置：
+
+```bash
+pi -e npm:@zxh126/pi-redact-secrets
+```
+
+然后在 pi 里 `/reload`（或新开），查看状态：
+
+```
+/redact
+```
+
+## 配置
+
+全部可选。没有配置文件时使用标准规则集、没有字面量。
+
+```bash
+/redact init       # 生成 ~/.pi/agent/redact-secrets.json
+```
+
+```jsonc
+{
+  "redactInput": true,
+  "redactToolResult": true,
+  "redactMessage": true,
+  "profile": "standard",          // "standard" | "strict"
+  "secrets": ["我的精确口令"],
+  "secretFiles": ["~/.env", "~/.pi/agent/dbhub/mysql.toml"],
+  "secretCommand": {
+    "command": "pwsh",
+    "args": ["-NoProfile", "-File", "~/.pi/agent/dump-secrets.ps1"],
+    "timeoutMs": 8000
+  },
+  "minSecretLength": 8,
+  "logFile": "~/.pi/agent/redact-secrets.log"
+}
+```
+
+环境变量 `PI_REDACT_SECRETS_CONFIG` 可以指定别的配置路径。
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `redactInput` | `true` | 是否脱敏用户输入。若有时确实要把口令交给模型，可关掉 |
+| `redactToolResult` | `true` | 是否脱敏工具输出 |
+| `redactMessage` | `true` | 是否脱敏最终消息 |
+| `profile` | `"standard"` | `strict` 额外启用高熵规则，能抓未知形状的随机串，但 base64 也会被误伤 |
+| `secrets` | `[]` | 逐字替换的字面量 |
+| `secretFiles` | `[]` | 从文件提取字面量：`.env`/TOML/YAML 里 key 名像密钥的 `KEY=value`、`scheme://user:pass@` 形式的 DSN、以及含密钥字段的 `.json` |
+| `secretCommand` | — | 执行该程序，stdout 输出 JSON 字符串数组或每行一个值作为字面量；不经 shell，有超时 |
+| `minSecretLength` | `8` | 太短的字面量会被忽略（否则会误伤普通文本） |
+| `logFile` | `~/.pi/agent/redact-secrets.log` | 每次脱敏记一行：按规则的命中数，**不含值** |
+
+### 为什么需要字面量
+
+规则只能抓「有特征的」密钥（`sk-…`、`ghp_…`、PEM 块、DSN、`password=…`）。
+像 `264613@Ms` 这种数据库口令在文本里看起来就是普通词，规则抓不到。
+字面量补这个缺口：把 `secretFiles` 指向你机器上已有的配置文件，或用
+`secretCommand` 在会话启动时现算。
+
+扩展本体**不带任何加密实现**：它只在会话启动时读一次明文并保存在内存里。加密交给你
+本来就信任的那个密钥库，按平台来：
+
+| 平台 | 密钥库 | 对应命令 |
+|---|---|---|
+| Windows | DPAPI（`CryptProtectData`） | `pwsh -File dump-secrets.ps1` |
+| macOS | 钥匙串 | `security find-generic-password -s pi-secrets -w` |
+| Linux（桌面） | Secret Service（GNOME Keyring / KWallet） | `secret-tool lookup service pi-secrets` |
+| Linux（服务器） | `0600` 文件，或 systemd ≥ 250 上的 `systemd-creds` | `cat ~/.pi-secrets` / `systemd-creds decrypt x.cred -` |
+
+选哪个之前得知道两条限制，因为 `secretCommand` 是**没有 TTY** 的后台执行：
+
+- **必须能无提示解锁**。DPAPI、钥匙串、Secret Service 都满足：系统在登录时就已经拿到了密钥。
+  `gpg`、`age`、`pass` **不**满足：它们通过 pinentry 要口令，后台命令直接失败
+  （除非 agent 已解锁）。真想用它们就写 `--pinentry-mode loopback --passphrase-file`，
+  或者包一层从密钥环取口令的脚本。
+- **耐久性**。用户级 DPAPI 密文绑在用户配置上。你**自己改密码**时 Windows 会重新包装主密钥，
+  但**管理员重置密码**（或重建用户配置）后主密钥就解不开了——密钥数据直接报废，
+  Windows 凭据管理器里的东西（git 凭据、RDP 密码）一起没。要么做一张密码重设盘，
+  要么把长期密钥放到不依赖账户的地方（密码管理器、硬件令牌、带 TPM 的 `systemd-creds`）。
+  这其实是所有「绑定登录态」的密钥库共有的问题，钥匙串和 Secret Service 也一样——
+  只是 DPAPI 这条翻车声音最大。
+
+每个都只是一个打印值的可执行文件，所以 `secretCommand` 本身保持平台无关：
+
+```jsonc
+// Windows：DPAPI blob，由 PowerShell 解密
+{ "secretCommand": { "command": "pwsh", "args": ["-NoProfile", "-File", "~/dump-secrets.ps1"] } }
+
+// macOS：钥匙串里一条，每行一个值
+{ "secretCommand": { "command": "security", "args": ["find-generic-password", "-s", "pi-secrets", "-w"] } }
+
+// Linux：Secret Service
+{ "secretCommand": { "command": "secret-tool", "args": ["lookup", "service", "pi-secrets"] } }
+
+// Linux 没有密钥环：一个只有你账户能读的文件
+{ "secretCommand": { "command": "cat", "args": ["/home/me/.pi-secrets"] } }
+```
+
+命令可以输出 **JSON 字符串数组**，也可以输出**纯文本、每行一个**（`secret-tool`、
+`security`、`pass`、`gpg` 都是这种形式）。需要管道就用显式 shell，因为
+`secretCommand` 从不经 shell：`{ "command": "sh", "args": ["-c", "pass show pi/secrets"] }`。
+
+Windows DPAPI 示例（`dump-secrets.ps1`，输出 JSON 数组）：
+
+```powershell
+$list = [System.Collections.Generic.List[string]]::new()
+function AddV($v) {
+  if (-not $v) { return }
+  $s = [string]$v
+  if ($s.Length -ge 8 -and $s -notmatch '^\d+$') { if (-not $list.Contains($s)) { $list.Add($s) } }
+}
+# …在这里读你自己的配置文件或解密 DPAPI blob…
+AddV (ConvertTo-SecureString (Get-Content "$HOME\.secret.dpapi" -Raw) |
+  ForEach-Object { [Runtime.InteropServices.Marshal]::PtrToStringBSTR(
+    [Runtime.InteropServices.Marshal]::SecureStringToBSTR($_)) })
+ConvertTo-Json -InputObject @($list) -Compress
+```
+
+Linux 上无密钥环时的等价做法是一个 `chmod 600` 文件；要加密又不能提示，
+就用 `systemd-creds`（systemd ≥ 250）或 TPM 支持的存储：
+
+```bash
+printf '%s\n' "$DB_PASSWORD" "$SMTP_CODE" > ~/.pi-secrets
+chmod 600 ~/.pi-secrets
+# secretCommand = { command = "cat", args = ["/home/me/.pi-secrets"] }
+```
+
+`secretFiles` 是零配置选项：直接用你已经有的 `chmod 600` 文件（`.env`、类 `~/.pgpass`
+的配置、`dbhub/mysql.toml`）。它不提供加密，只有文件系统权限——单用户笔记本尚可，
+共享主机不够。
+
+## 规则
+
+| 规则 | 输入示例 | 输出 |
+|---|---|---|
+| `pem` | `-----BEGIN OPENSSH PRIVATE KEY-----…` | `<REDACTED-PEM>` |
+| `auth-header` | `Authorization: Bearer abcdef123456` | `Authorization: Bearer <REDACTED>` |
+| `openai-key` | `sk-proj-abcdefghijklmnop` | `sk-<REDACTED>` |
+| `github-token` | `ghp_abcdefghijklmnopqrst` | `<REDACTED-GH>` |
+| `npm-token` | `npm_abcdefghijklmnopqrstuvwxyz` | `npm_<REDACTED>` |
+| `aws-access-key` | `AKIAIOSFODNN7EXAMPLE` | `AKIA<REDACTED>` |
+| `jwt` | `eyJhbGciOi….eyJzdWIi….s3cr3t` | `<REDACTED-JWT>` |
+| `dsn` | `mysql://root:pa55word@host/db` | `mysql://root:***@host/db` |
+| `url-userinfo` | `https://user:pass@host` | `https://***:***@host` |
+| `json-secret` | `{"appSecret": "eFh2DD4o…"}` | `{"appSecret": "<REDACTED>"}` |
+| `key-value` | `SMTP_PASS=…`、`db_password: …`、`密码：…` | `SMTP_PASS=<REDACTED>` |
+| `high-entropy`（strict） | 长随机串 | `<REDACTED-HIGH-ENTROPY>` |
+
+规则是**幂等**的：已脱敏的值（`***`、`<REDACTED>`）不会被二次匹配，恢复会话时
+不会出现占位符套占位符。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/redact` | 规则数、字面量数量与来源、开关、配置与日志路径 |
+| `/redact reload` | 重新读取配置并重跑 `secretCommand` |
+| `/redact init` | 写一份示例配置（不会覆盖已有文件） |
+
+## 跨平台
+
+纯 Node 实现：没有原生模块、没有 shell 调用、没有平台分支。
+
+| 平台 | 状态 |
+|---|---|
+| Windows 10/11 | 已验证：Node 24、PowerShell 7、pi 1.4 |
+| Linux (x64) | 已验证：Ubuntu 20.04 + Node 22.23.4（28 个测试，含钩子接线测试） |
+| macOS / arm64 | 预期可用——与 Linux 同一套代码路径 |
+
+- **需要 Node ≥ 22.18**：包直接发布 TypeScript 源码，依赖 Node 原生类型剥离（pi 本身也要求 Node 22+）。
+- 路径一律走 `path.join` / `os.homedir()`，配置值里的 `~`、`~/` 会被展开；代码里没有任何盘符或 Windows 专有 API。
+- `secretCommand` 通过 `execFile` 执行，**不经 shell**，命令与参数由你按平台填写（Windows 用 `pwsh`，Linux 用 `sh`/`node`/`python3`），没有任何写死的可执行文件。
+- 日志文件在 POSIX 上以 `0600` 权限创建（Windows 忽略该模式）。
+
+## 它不做什么
+
+- **不脱敏工具参数**。改写 `bash`/`pwsh` 的参数等于改变实际执行的命令，所以
+  `pwsh -Command "login --password hunter2"` 里的口令仍会留在工具调用里。
+  请改用环境变量或文件传参。
+- **不动 `tool_result.details`**，TUI 渲染依赖它。
+- 脱敏是「尽力而为 + 基于模式」的：它降低暴露面，不是保证。最安全的做法仍然是
+  让敏感数据不离开本机。
+- 已经写进会话文件的历史不会自动清理。需要的话对
+  `~/.pi/agent/sessions/**/*.jsonl` 做一次离线处理。
+
+## 开发
+
+```bash
+npm test          # node --test，无需构建（Node ≥ 22.18 原生剥离类型）
+npm run check     # tsc --noEmit
+pi -e .           # 从本目录加载包
+```
+
+CI 在 `ubuntu-latest` 上用 Node 22 和 24 跑 `npm test` 与 `npm run check`。
+`test/extension.test.ts` 用一个假的 `ExtensionAPI` 驱动扩展，不用启动 pi 就能覆盖三个钩子、
+配置读取、字面量收集和日志文件。
+
+结构：
+
+```
+src/index.ts     pi 接线：三个钩子 + /redact 命令
+src/rules.ts     规则与替换模板
+src/redactor.ts  纯脱敏引擎（有单测、无 I/O）
+src/literals.ts  字面量收集（配置、文件、命令）
+src/config.ts    配置结构、默认值与校验
+```
+
+引擎不依赖 pi，可以单独使用：
+
+```ts
+import { Redactor } from "@zxh126/pi-redact-secrets/src/redactor.ts";
+
+const redactor = new Redactor({ profile: "strict" });
+redactor.setSecrets(["我的精确口令"]);
+redactor.redact("password=我的精确口令");
+// { text: "password=<REDACTED>", hits: 1, byRule: {…} }
+```
+
+## 许可
+
+MIT

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@zxh126/pi-redact-secrets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Redact secrets from pi tool output, user input and messages before they reach the model or the session file.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "redaction",
+    "secrets",
+    "security",
+    "privacy"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "harry zhang <zxh_126@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/zxh126/pi-redact-secrets.git"
+  },
+  "homepage": "https://gitee.com/zxh126/pi-redact-secrets#readme",
+  "bugs": {
+    "url": "https://gitee.com/zxh126/pi-redact-secrets/issues"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "test:watch": "node --test --watch test/*.test.ts",
+    "check": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}