深度编辑
@hackylabs/deep-redact是用于Node.js和Deno的由规则驱动的编辑库. 它使你能够表达要编辑什么——一个关键名称,一个路径,一个正格克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 政策一经初始化就汇编,并在每项请求中重新使用,使之适合高通量生产用途.
图书馆 fast-redact 需要为可能出现敏感字段的每个地点提供明确的路径(a.b.password, (中文(简体) ), a.c.password,....。深重置反转这个:一个单曲 keys: ['password'] 规则目标 password 字段在任意深度。 它还增加了路径编号库无法提供的能力,如部分字符串编辑(瞄准较大值内的敏感模式)和重复结构的通配符路径选择器.
特征
- 深度不可知关键规则 ——在任何巢穴深度编辑任意字段的名称;不需要路径计数
- 精确和结构化路径瞄准 ——当需要精确度时,将编辑指向特定地点
- Regex 属性匹配 ——通过正则表达式匹配字段名称
- 子字符串目标 ——编辑一个在较大值内出现的敏感字符串,而不只是全值替换
- 通关卡和排除路径选择器 几乎在任何深度处理重复结构(
['addresses.*', { ignore: 'country' }])而不列出每个索引 - 结构化和序列化产出 ——返回活对象图或保证-JSON安全字符串(
serialise: true(中文(简体) ) - 内置和自定义变压器 ——超越特定运行时间类型在序列化输出中的表现方式
- 内设安保 ——通过内存耗竭来防止原型污染和DoS
- 控制台适配器 - 可选
console.*通过明确的适配器编辑
基线
- 节点
24.14.1 [email protected]tsdownVitestESLint
安装
npm install @hackylabs/deep-redact
pnpm add @hackylabs/deep-redact
yarn add @hackylabs/deep-redact
bun add @hackylabs/deep-redact
德诺 ——将软件包添加到导入地图中(deno.json:
{
"imports": {
"@hackylabs/deep-redact": "npm:@hackylabs/[email protected]"
}
}
快速启动
import { deepRedact } from '@hackylabs/deep-redact'
const redact = deepRedact({ keys: ['password', 'token'] })
redact({ user: { password: 'secret', safe: 'keep this' }, token: 'abc123', id: 1 })
// { user: { password: '[REDACTED]', safe: 'keep this' }, token: '[REDACTED]', id: 1 }
基准
由承诺的手工艺品产生 test/artefacts/benchmarks/speed/. Node.js 24 LTS, Apple M系列. 1万个暖热后稳定状态.
TLDR 头条
如果原始吞吐量是您的主要制约因素, 您可以接受详尽的路径计数, 使用
fast-redact换句话说. 它是专为JSON-string最大输出速度而专门建造的,在那种狭义的场景中,它将超越任何规则驱动的库. 当您需要深度不可知的目标、通配符路径、下行编辑或内置的安全保障时使用深重写.
如果你选择快速重写, 注意权衡:
- 没有深度不可知的关键规则 ——必须明确列举每一个敏感路径
- 无双通卡( N)
**路径选择器 - 你不能瞄准目标records.**.email不列出每个深度 - 没有子字符串目标 ——仅全值替换;不支持部分字符串编辑
- 没有序列安全变压器管道 - 没有内置处理
BigInt, (中文(简体) ),Date, (中文(简体) ),Map, (中文(简体) ),Set, (中文(简体) ),Error, (中文(简体) ),RegExp,或URL数值 - 没有污染保护原型 - 没有防守
__proto__财务报告和审定财务报表constructor.prototype注射 - 没有可配置的深度或节点限制 ——没有通过深巢或过大的有效载荷进行防护
结构化产出(serialise: false(中文(简体) )
v4, v3, 并快速编辑全部返回一个平版 JavaScript 对象 .
QQ快取是第三方图书馆,而不是深取的版本. 其被显示为吞吐量参考;其特征设置和保证与深红相异,因此它不是一种相类似比较.
v4 为 ~ 17× 更快 ~ 与基于路径的工作量和 ~ 10× 更快 ~ 关于通配符工作量.
序列化产出( E)serialise: true(中文(简体) )
所有四个解决方案都返回一个JSON字符串.
• 快速编辑是第三方图书馆;json-stringify-regex是一种天真的本土方法(JSON.stringify(value).replace(pattern, replacement)),不是图书馆. 既未进行深红字的结构编辑,也未提供其保证,因此两者都显示为吞吐量参考,而非类似比较.
v4在序列化模式下保持快于v3. 快速重写和json-stringify-regex具有吞吐量优势,因为它们的输出路径完全面向字符串生产.
相对于深红活性v2,序列相加不一:v4在基于路径的工作量上大致平分,而宽重(wildcard)的工作量则较慢. 这笔差额是安全v2的费用没有提供——根据 serialise: true,v4 运行生成 BigInt, (中文(简体) ), Date, (中文(简体) ), Map, (中文(简体) ), Set, (中文(简体) ), Error, (中文(简体) ), RegExp,以及 URL 它检测和校正了循环引用 而不是扔在它们身上 (通过 maxNodes编号 :maxDepth (b) 支票是反递增的,增加了可忽略不计的费用。 设定 onBudgetExceeded: 'truncate' 无法用 a 关闭 [TRUNCATED] 标记而不是投掷。 )
这些安全通行证是内在的 serialise: true 无法单独关闭。 如果您不需要这些保证, 想要匹配 v2 的吞吐量( 或者更好), 设置 serialise: false 自己开 JSON.stringify:结构化输出路径跳过变压器,圆通引用完全通过. 这会恢复V2的取舍 JSON.stringify 将弹出 BigInt 和通告参考, Map编号 :Set 序列为 {},以及 undefined 被删除.
全速和资源基准结果: docs/benchmarks/speed-results.md 财务报告和审定财务报表 docs/benchmarks/resource-results.md。 。 。 .
配置
deepRedact(options) 接受单个选项对象。 所有选项都是可选的.
顶级选项
| 选项 | 类型 | 默认 | 需求 | 说明 |
|---|---|---|---|---|
keys | KeySelector[] | [] | 没有 | 编辑任何匹配所列密钥的字段, 任何深度 |
paths | PathEntry[] | [] | 没有 | 编辑特定路径的字段; 支持精确的字符串、结构化路径、通配符和排除选择器 |
stringTests | StringTest[] | [] | 没有 | 调整字符串值内的匹配模式 |
censor | string | function | '[REDACTED]' | 没有 | 替换值或函数 (value, context) => replacement |
serialise | boolean | function | false | 没有 | true 返回 JSON 安全字符串; 函数接收安全图表并可能返回任意字符串 |
remove | boolean | false | 没有 | 从输出中删除匹配的密钥, 而不是替换其值 |
retainStructure | boolean | false | 没有 | 当父母相匹配时, 保留子孙节点可以用于低优先级规则 |
replaceStringByLength | boolean | false | 没有 | 重复 censor 匹配已编辑值的字符长度的字符串 |
types | ValueTypeName[] | ['string'] | 没有 | typeof 符合编辑条件的类别; 其数值类型未列出的匹配密钥未受影响 |
fuzzyKeyMatch | boolean | false | 没有 | 当配置的密钥是字段名的子字符串时匹配(例如. 'pass' 匹配 'password'(中文(简体) ) |
caseSensitiveKeyMatch | boolean | true | 没有 | 何时 false,在比较前将密钥名称(分解非单词字符,小写)正常化 |
maxDepth | number | 500 | 没有 | 停止穿越这个筑巢深度; 警戒深筑巢载荷 |
maxNodes | number | 50000 | 没有 | 在这么多节点后停止穿行; 防范过大的有效载荷 DoS |
onBudgetExceeded | 'throw' | 'truncate' | 'throw' | 没有 | 在一个 maxDepth编号 :maxNodes 突破, 'throw' 引起内部预算错误; 'truncate' 将违法节点替换为 [TRUNCATED] 停止, 关闭 |
transformers | TransformersOption | 内置默认值 | 没有 | 覆盖运行时间类型在序列化输出中的体现 |
diagnostics | DiagnosticsOptions | —— 说 | 没有 | 结构化降解/预算事件 Opt-in sink; 默认沉默( 无控制台输出) 。 过 getNodeConsoleDiagnosticSink() 作为 sink 登录到控制台 |
ValueTypeName 这是: 'string', (中文(简体) ), 'number', (中文(简体) ), 'bigint', (中文(简体) ), 'boolean', (中文(简体) ), 'object', (中文(简体) ), 'function', (中文(简体) ), 'symbol', (中文(简体) ), 'undefined'。 。 。 .
KeySelector
每个条目 keys 可能是一个平地 string页:1 RegExp,或一个 KeyRule 每个密钥覆盖的对象.
keys 横穿平原对象、阵列、类例本身的可假设字段,以及 Map编号 :Set 目录. Map 条目密钥在结构输出中保留原始密钥对象的同时,与其成型的字符串形式相匹配; Set 成员按插入顺序穿行,但其数字位置是路径段而不是合成键.
| 外地 | 类型 | 默认 | 需求 | 说明 |
|---|---|---|---|---|
key | string | RegExp | —— 说 | 对 | 要匹配的密钥 |
censor | string | function | 顶级 censor | 没有 | 只覆盖此密钥的审查者 |
remove | boolean | 顶级 remove | 没有 | 仅为此密钥覆盖删除 |
retainStructure | boolean | 顶级 retainStructure | 没有 | 仅保留此密钥的构造 |
replaceStringByLength | boolean | 顶级 replaceStringByLength | 没有 | 仅为此密钥取代 StringByLength |
fuzzyKeyMatch | boolean | 顶级 fuzzyKeyMatch | 没有 | 仅覆盖此密钥的模糊密钥 |
caseSensitiveKeyMatch | boolean | 顶级 caseSensitiveKeyMatch | 没有 | 仅覆盖此密钥的敏感KeyMatch |
PathEntry
每个条目 paths 可能是平面点注释字符串(如:. 'user.profile.ssn'),结构化路径数组,或 PathRule 用于 per-path 覆盖的对象.
结构化路径数组可能包含:
| 片段类型 | 示例 | 匹配 |
|---|---|---|
string 或者说 number | 'password' | 精确键或索引 |
RegExp | /^pass/i | 匹配正则x 的密钥 |
{ any: true } | —— 说 | 任何单一的密钥( E)*(中文(简体) ) |
{ anyDepth: true } | —— 说 | 任意深度的零键或多键( N)**(中文(简体) ) |
{ ignore: string | number | RegExp } | { ignore: 'country' } | 从周边通配符中排除密钥 |
| 外地 | 类型 | 默认 | 需求 | 说明 |
|---|---|---|---|---|
path | string | PathSegments[] | —— 说 | 对 | 匹配的路径 |
censor | string | function | 顶级 censor | 没有 | 仅覆盖此路径的审查者 |
remove | boolean | 顶级 remove | 没有 | 仅为此路径覆盖删除 |
retainStructure | boolean | 顶级 retainStructure | 没有 | 覆盖仅保留此路径的构造 |
replaceStringByLength | boolean | 顶级 replaceStringByLength | 没有 | 仅为此路径取代 StringByLength |
StringTest
每个条目 stringTests 也许是赤裸的 RegExp (全值替换为 censor或一个 SubstringRule 用于部分替换.
| 外地 | 类型 | 需求 | 说明 |
|---|---|---|---|
pattern | RegExp | 对 | 对照字符串值测试正则表达式 |
replacer | (value: string, pattern: RegExp) => string | 对 | 返回已编辑的字符串;仅在 pattern 匹配 |
TransformersOption
变形器控制非 JSON 运行时类型在何时被显示 serialise: true。每个变压器是一个函数 (value: unknown) => unknown ,或者返回已变换的值,或者返回未变换的值以传递给链条中的下一个变压器.
| 外地 | 类型 | 说明 |
|---|---|---|
byType.bigint | Transformer[] | 适用于 BigInt 值( 不查阅) byType.object(中文(简体) ) |
byType.object | Transformer[] | 首先适用于内置构造器类型和未知对象类型 |
byConstructor.Date | Transformer[] | 适用于 Date 实例 |
byConstructor.Error | Transformer[] | 适用于 Error 实例 |
byConstructor.Map | Transformer[] | 适用于 Map 实例 |
byConstructor.RegExp | Transformer[] | 适用于 RegExp 实例 |
byConstructor.Set | Transformer[] | 适用于 Set 实例 |
byConstructor.URL | Transformer[] | 适用于 URL 实例 |
byConstructor.custom | CustomConstructorTransformerRegistration[] | 自定义类型匹配 instanceof 按声明顺序排列 |
fallback | Transformer[] | 当没有较早的变压器返回已更改的值时应用 |
内置变压器会产生决定性的标记对象(例如. { _transformer: 'date', datetime: '<ISO string>' }) (中文(简体) ). 见 docs/architecture/serialise-output.md 用于完整的调度命令和标记形状.
执行阶段. 用户 byConstructor.custom 财务报告和审定财务报表 byConstructor.Error 变压器运行 在正常转弯之前,在两种序列模式中:匹配的类实例转换为您返回的平面对象,然后由您擦除 keys编号 :paths 规则。 这就是PII在类中嵌入的方式——例如: Error编号 :AxiosError 携带 config.data 有效载荷——在没有预先正常步骤的情况下进行编辑(见 在错误实例中编辑 PII) (中文(简体) ). 其它水桶(byType, (中文(简体) ), fallback用户 byConstructor.{Date,Map,RegExp,Set,URL})仅在 serialise: true pass; 依赖这种仅序列化的行为——即变压器输出能从编辑中逃脱的行为——是 已贬值 支持上面的一等桶.
DiagnosticsOptions
| 外地 | 类型 | 说明 |
|---|---|---|
sink | (event: DiagnosticEvent) => void | 当一个值退化为 '[UNSUPPORTED]' 序列化期间 |
公共 API
import { createRedactor, deepRedact } from '@hackylabs/deep-redact'
// deepRedact and createRedactor are the same factory under different names
const redact = deepRedact({ keys: ['secret'] })
const same = createRedactor({ keys: ['secret'] })
文档
工作实例
- 关键目标
- 模糊和大小写不敏感密钥匹配
- 路径选择
- 通关卡路径段并忽略选择器
- Regex 属性匹配
- 按键规则覆盖
- 子字符串目标
- 替换和去除
- 结构化对序列化输出
- 自定义变压器
- 在错误实例中编辑 PII
- 值类型允许列表
- Singleton / 服务端设置
- 控制台编辑适配器
移徙指南
建筑和设计
平台和安全小组
- 标准化指南 支助能力,针对语义、核查证据和通过决定的范围
脚本
pnpm run buildpnpm run lintpnpm run testpnpm run generate-exportspnpm run generate-readmepnpm run verify-generated-filespnpm run benchpnpm run bench:generate-charts