Tokenhush 的工作原理

一次请求的完整路径

网关位于你的工具与模型提供商之间。它会完整读取每个外发请求，把命中值改写为占位符，并把占位符映射保留在本地、限定于当前会话。

1. 外发请求

   网关读取完整 JSON 请求体并遍历每个叶子节点，运行全部六个检测器。每个命中项变成一个会话级占位符，例如__PII_email_9f2c8a4b6d1e__。脱敏后的请求体随后转发到上游。

2. 上游

   提供商收到脱敏后的请求体：命中值的位置是占位符。未被检测器标记的值仍会照常发出，因此检测器质量就是这个工具诚实的边界。

3. 入站响应

   返回的占位符会被替换为原值，且只发生在通往客户端的路径上。流式响应按增量处理，包括跨分块边界被拆开的占位符。

4. 本地审计

   每个请求向本地存储追加一条仅含元数据的记录：提供方、路径、字节数、检测器命中。除非你显式启用，内容不会被记录；记录以 HMAC 链式相连，篡改可被检测。

出站永不回填的设计不变量

这条不变量封住了一条具体的攻击路径。提示注入可以试图让编码工具把一个已存储的机密回显进新的外发请求。如果网关在外发方向替换占位符，该请求就会把原值带给模型。由于回填仅发生在入站方向，出现在外发请求体里的占位符就仍然只是占位符。

• 这是设计不变量，不是防护保证。 检测是确定性、精度优先的规则：误报会让模型输出退化，漏报会让内容外发。诚实的说法是高置信拦截加全程可审计，而不是承诺任何敏感内容都不会离开。
• 映射只在内存中，且限定于当前会话。 重启网关会丢失映射，之后的回填可能把占位符显示在输出里。这是安全降级，不是泄露。
• 例外由你掌控。 允许清单可以让指定字面量不参与脱敏，内容插件可以加入你自己的检测与转换步骤。

六个检测器覆盖什么

检测刻意保持确定性：规则成本低、可解释、可调整。不调用模型，不做语义猜测。

密钥前缀

已知的密钥形态，例如 sk-、AKIA、ghp_。

高熵字符串

不带命名前缀、形态随机的高熵令牌。

JSON Web Token

按结构识别的三段式签名令牌。

PEM 私钥头

被粘贴进提示词或文件的私钥材料。

银行卡号

用 Luhn 校验和确认候选数字，而不只看位数。

邮箱地址

经常出现在提示词、diff 与日志里的常见 PII。

在内置规则之外，核心提供两条扩展路径：一份让指定字面量永不脱敏的允许清单，以及运行在管道内的内容插件（Inspector 与 Transformer）。V1 仅支持编译期插件，详见公开插件文档。

网关的覆盖范围

覆盖从任何支持自定义 base URL 或端点的工具开始，也就是公开 README 中列出的 CLI 与 IDE 工具。不暴露该设置的工具（例如部分 IDE agent、桌面聊天应用与浏览器 UI）不在公开核心的范围内：它不安装根证书，也不做系统级拦截。

你的工具到网关的流量留在环回接口上；网关到提供商的流量通过 HTTPS 发出，携带脱敏后的请求体。

公开来源

本页内容整理自开源核心的公开材料：

• 工作原理（README）
• 数据流、组件与硬性不变量
• 威胁模型与检测器取舍
• 内容插件（Inspector / Transformer）