|
| 1 | +// #164 A2:写入边界的密钥 / PII 判据。判据来源是 #164 A2(维护者 09-28 把认领转给 |
| 2 | +// 本侧),消费方是 #254 的写入准入——`write-admission.js` 从 #332 起就留了 |
| 3 | +// `sensitiveScan` 注入点,本模块是那个占位的实现。 |
| 4 | +// |
| 5 | +// 为什么判据独立成文件、不写进 write-admission.js:判据的归属是 #164 A2,闸门的归属 |
| 6 | +// 是 #254。闸门只消费 `{kind, label}`(deny 面已在 #332 定死),判据自己既不认识 |
| 7 | +// 「会话预算」也不认识 `llm_audit_logs`——换一个判据(比如将来接更重的 PII 分类器) |
| 8 | +// 只换注入的那一行。写入边界的另外两个出口(autoSummarize / dream 输出)要复用同一份 |
| 9 | +// 判据时也直接 import 本模块的 `scanSensitive`,不必各写一套形状。 |
| 10 | +// |
| 11 | +// 三条判据口径(前两条是 #254 已定的硬约束,第三条是本模块自己的): |
| 12 | +// |
| 13 | +// 1. 零 LLM、纯确定性。写入路径在最上游,这里多花的时间会乘上每一次写入;EdgeMem |
| 14 | +// (2609.05553)那句「能不用模型判定就不用」说的就是这一层。 |
| 15 | +// |
| 16 | +// 2. 假阳率由负样本定。`test/helpers/write-admission-samples.js` 的 12 条负样本是 |
| 17 | +// #332 就配好的验收面,维护者把话说死了:「同一套负样本原样跑,抓错任何一条就不 |
| 18 | +// 算落地」。所以本模块的形状是**先认形状再认关键词**——纯关键词匹配在那组负样本 |
| 19 | +// 上全军覆没(「把 API key 放进环境变量」这类讨论句里一个凭据值都没有)。 |
| 20 | +// |
| 21 | +// 3. 报最严重的那一类(`kind` 落审计)。同一个字符串可能同时像两类(`sk_live_` 前缀 |
| 22 | +// 既是 Stripe 的形状、也能被通用的 `sk-` 规则吃下),所以规则表按「越具体越靠前」 |
| 23 | +// 排,命中即返回。密钥在前、PII 在后:两者误杀面差一个量级(密钥串出现在正常项目 |
| 24 | +// 记忆里就是事故,邮箱 / 手机号完全可能是正当内容),同时命中时报更严重的那一类。 |
| 25 | +// `kind` 是稳定判据键(不是展示文案),enforce 打开前先按它看分布,将来要按类放行 |
| 26 | +// 也只改策略、不动判据。 |
| 27 | +// |
| 28 | +// 已知边界(都是「宁漏不误杀」的取舍,不是遗漏): |
| 29 | +// - 只扫文本(title / content / tags)。不扫路径、id、时间戳这类元数据字段——它们 |
| 30 | +// 由系统生成,不是用户写进来的内容,扫它们只会引入假阳。 |
| 31 | +// - 中文关键词(密码 / 令牌)不认。补进去会让「密码必须脱敏后再入库」这类讨论句 |
| 32 | +// 命中,而那正是负样本 group 的形状。要覆盖中文赋值得先设计「关键词语种 × 值形状」 |
| 33 | +// 的两维判据,不在本批。 |
| 34 | +// - 手机号只认大陆移动号段(1[3-9] + 9 位),固定电话与带国家码的写法不认。宽一位 |
| 35 | +// 就会把长度相近的订单号 / 内部编号吃进来,而 PII 这一档的误杀面已经比密钥大一档。 |
| 36 | +// - 银行卡号加 Luhn 校验:`0000000000000000`、`4111111111111112` 这类形状对但校验 |
| 37 | +// 不过的串不报。少了这道校验,任何 16 位数字串(订单号、时间戳拼接)都会命中。 |
| 38 | +// |
| 39 | +// 归一化:这里**不**用 content-hash.js 的 normalizeForHash。那套口径(NFKC → 小写 → |
| 40 | +// 去标点)是为「只差格式的两条写入是否同一件事」定的,判据要的是原串的形状——大小写 |
| 41 | +// 是密钥 alphabet 的一部分(`AKIA` 与 `akia` 不是同一个值),去掉 `-` / `_` 会把 JWT |
| 42 | +// 与 Slack token 的分段结构一起折没。两个口径别互换。 |
| 43 | + |
| 44 | +/** 判据命中的返回形状(与 `createWriteAdmission` 的 sensitiveScan 契约一致)。 */ |
| 45 | +// kind 是稳定键、label 是给人看的一行说明;两者都落 llm_audit_logs 的 |
| 46 | +// metadata.deny,所以别在其中塞运行时的值(命中的凭据本身绝不落盘 / 不回显)。 |
| 47 | +const SECRET_RULES = [ |
| 48 | + { kind: "aws_access_key", label: "AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ }, |
| 49 | + // AWS 的 secret access key 没有前缀,只能靠赋值键认:`AWS_SECRET_ACCESS_KEY` / |
| 50 | + // `aws_secret_access_key` 这个键名是它的形状。最早的一批 `secret` 关键词规则被 |
| 51 | + // 「必须在赋值号前」的位置要求挡在外面(多词键里 `secret` 后面跟的是 `_`,不是 |
| 52 | + // `:`/`=`),所以它得单独一条。40 位下限取 AWS 官方密钥的固定长度。 |
| 53 | + { |
| 54 | + kind: "aws_secret_key", |
| 55 | + label: "AWS secret access key", |
| 56 | + // 键名不分大小写,所以挂 `/i` 而不是行内修饰符组 `(?i:...)`:后者是 ES2025 语法, |
| 57 | + // CI 矩阵里的 Node 22 直接抛 SyntaxError(本文件其余规则也没有用它的)。 |
| 58 | + // 值那一半本来就是 `[A-Za-z0-9/+=]`,带上 `/i` 不改变大小写敏感度。 |
| 59 | + re: /(?:aws[_-]?secret[_-]?access[_-]?key)\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])/i |
| 60 | + }, |
| 61 | + { kind: "github_token", label: "GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/ }, |
| 62 | + { kind: "slack_token", label: "Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ }, |
| 63 | + // PEM 头是明文私钥的确定标志,带不带正文都一样判——`BEGIN` 与 `PRIVATE KEY` 之间 |
| 64 | + // 可能有 `RSA` / `EC` / `OPENSSH`,所以中间那段是 [A-Z ]*。 |
| 65 | + { kind: "private_key", label: "PEM private key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ }, |
| 66 | + { kind: "jwt", label: "JSON Web Token", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ }, |
| 67 | + { kind: "connection_string", label: "credentials in URL", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/:@]{6,}@/ }, |
| 68 | + // Stripe 排在通用 `sk-` 之前:`sk_live_…` 两条规则都吃,先到的那条决定 kind。 |
| 69 | + // 只认 sk_live_(生产密钥):sk_test_ 是公开测试密钥,报它是纯误杀。 |
| 70 | + { kind: "stripe_key", label: "Stripe secret key", re: /\bsk_live_[A-Za-z0-9]{16,}\b/ }, |
| 71 | + { kind: "npm_token", label: "npm auth token", re: /_authToken\s*=\s*[A-Za-z0-9_-]{20,}/ }, |
| 72 | + // 下限 24 而不是 20:这是一条纯收紧、不动语料读数的加固——OpenAI 的 key 没有校验 |
| 73 | + // 位,前缀 + 长度是唯一形状,20 位会把更长的假阳性面留在表里。`sk-` 后面跟短串的 |
| 74 | + // 赋值句仍会被赋值型那条认下(那是**对的**:值长了 8 位以上就该报)。 |
| 75 | + { kind: "openai_key", label: "OpenAI API key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b/ }, |
| 76 | + { |
| 77 | + // 赋值型:最常见的一类,也是负样本组(占位符 / 环境变量 / 模板变量 / 只提关键词) |
| 78 | + // 的主要靶子。判据是「关键词 + 赋值号 + 右边真的是个值的形状」,值本身不校验 |
| 79 | + // alphabet——凭据值没有通用形状,能通用的只有「它不像占位符」。 |
| 80 | + kind: "assigned_secret", |
| 81 | + label: "assigned credential literal", |
| 82 | + re: /(?:^|[^A-Za-z0-9_])(?:password|passwd|pwd|secret|api[_-]?key|token)\b\s*[:=]\s*["']?([^\s"']{8,})/i, |
| 83 | + // 占位符守卫:右边是尖括号占位、shell / 模板变量、环境变量读取、或一串 x / * / … |
| 84 | + // 时不算命中。少这道守卫,`password: <redacted>` 与 `token: ${TOKEN}` 都会被报, |
| 85 | + // 而它们正是「配置里该怎么写」的示例文本。 |
| 86 | + guard: (value) => !/^(?:<[^>]*>|\$\{|\$[A-Z_]+$|process\.env|redacted|xx+|\*+|\u2026)/i.test(value) |
| 87 | + } |
| 88 | +]; |
| 89 | + |
| 90 | +const PII_RULES = [ |
| 91 | + { |
| 92 | + kind: "email", |
| 93 | + label: "email address", |
| 94 | + // 先看 TLD 再看 `@`:反过来的 `(?:[A-Za-z]{2,}\.)+[A-Za-z]{2,}` 对 |
| 95 | + // `[email protected]` 这类可以回溯出指数条路径。 |
| 96 | + re: /\b[A-Za-z0-9._%+-]+@(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}\b/ |
| 97 | + }, |
| 98 | + { kind: "cn_mobile", label: "mainland mobile number", re: /(?<!\d)1[3-9]\d{9}(?!\d)/ }, |
| 99 | + { kind: "cn_id_card", label: "mainland ID number", re: /(?<![0-9A-Za-z])\d{17}[\dXx](?![0-9A-Za-z])/ }, |
| 100 | + { kind: "bank_card", label: "payment card number", re: /(?<!\d)(?:\d{13,19})(?!\d)/, luhn: true } |
| 101 | +]; |
| 102 | + |
| 103 | +/** |
| 104 | + * Luhn(模 10)校验。银行卡号这一档只靠位数与首字符形状会把所有 13–19 位数字串 |
| 105 | + * 都吃进来,而项目记忆里长度差不多的数字串(订单号、拼接的时间戳)很常见;校验位 |
| 106 | + * 是卡号自带的、零成本的第二道形状。负样本里没有卡号形状的串,这道校验是防未列举 |
| 107 | + * 的那一类(同时它也不影响正样本:4111111111111111 是 Luhn 通过的公开测试卡号)。 |
| 108 | + * @param {string} value 归一后的数字串(可能含分隔符) |
| 109 | + */ |
| 110 | +function passesLuhn(value) { |
| 111 | + const digits = value.replace(/\D/g, ""); |
| 112 | + if (digits.length < 13 || digits.length > 19) return false; |
| 113 | + let sum = 0; |
| 114 | + let double = false; |
| 115 | + for (let i = digits.length - 1; i >= 0; i--) { |
| 116 | + let d = digits.charCodeAt(i) - 48; |
| 117 | + if (double) { |
| 118 | + d *= 2; |
| 119 | + if (d > 9) d -= 9; |
| 120 | + } |
| 121 | + sum += d; |
| 122 | + double = !double; |
| 123 | + } |
| 124 | + return sum % 10 === 0; |
| 125 | +} |
| 126 | + |
| 127 | +/** |
| 128 | + * 扫一段文本里的密钥 / PII。命中返回 `{kind, label}`、未命中返回 null,不抛。 |
| 129 | + * |
| 130 | + * 只认第一处命中(按规则表顺序 = 严重度顺序)。一次写入里出现第二条凭据时不再报—— |
| 131 | + * deny 面只记判据类别,报多条只是把同一件事写几遍。 |
| 132 | + * @param {unknown} value |
| 133 | + * @returns {{kind: string, label: string}|null} |
| 134 | + */ |
| 135 | +export function scanSensitive(value) { |
| 136 | + const text = typeof value === "string" ? value : String(value ?? ""); |
| 137 | + if (!text) return null; |
| 138 | + for (const rule of [...SECRET_RULES, ...PII_RULES]) { |
| 139 | + const match = text.match(rule.re); |
| 140 | + if (!match) continue; |
| 141 | + // 守卫只看捕获组:没有捕获组的规则天然没有守卫。 |
| 142 | + if (rule.guard && !rule.guard(match[1] ?? "")) continue; |
| 143 | + if (rule.luhn && !passesLuhn(match[0])) continue; |
| 144 | + return { kind: rule.kind, label: rule.label }; |
| 145 | + } |
| 146 | + return null; |
| 147 | +} |
| 148 | + |
| 149 | +/** |
| 150 | + * 判据的两种调用面,共用同一份规则表: |
| 151 | + * `scanSensitive(text)` — 任意文本,给写入边界之外的消费方(autoSummarize / |
| 152 | + * dream 输出)直接调;它们手里是文本,不是记忆行。 |
| 153 | + * `createSensitiveScan({config})` — `write-admission.js` 的 `sensitiveScan` 契约, |
| 154 | + * 入参是记忆对象、返回 `{kind, label}` 或 null。 |
| 155 | + * |
| 156 | + * 开关在工厂里判一次:`sensitiveScanEnabled` 关时返回 null,闸门侧连函数都拿不到, |
| 157 | + * 于是「第 1 级只跑空白 / 噪声」这条路与 #332 合并时**逐字段一致**(那一版根本没有 |
| 158 | + * 这个函数)。这个键是 A2 自己的闸,不是 writeAdmission.enabled 的子开关——A2 落在 |
| 159 | + * 写入边界(#164 的措辞是「默认仅告警、拦截 opt-in」),与 #254 第 1 级的空白 / 噪声 |
| 160 | + * 是两批判据,不该被同一个开关绑死。 |
| 161 | + * |
| 162 | + * @param {{config?: object}} [deps] |
| 163 | + * @returns {((memory: object) => ({kind: string, label: string}|null))|null} |
| 164 | + */ |
| 165 | +export function createSensitiveScan({ config } = {}) { |
| 166 | + if (config?.sensitiveScanEnabled !== true) return null; |
| 167 | + const scan = (memory) => { |
| 168 | + const text = [memory?.title, memory?.content, ...(Array.isArray(memory?.tags) ? memory.tags : [])] |
| 169 | + .filter((s) => typeof s === "string") |
| 170 | + .join("\n"); |
| 171 | + return scanSensitive(text); |
| 172 | + }; |
| 173 | + // 工厂只认「开 / 关」;enforce 由 write-admission 决定(命中即 deny 还是仅告警), |
| 174 | + // 判据自己不碰决策——那一步在闸门里。两层分开就能先开检测看分布、再开拦截。 |
| 175 | + return scan; |
| 176 | +} |
0 commit comments