carlos-flow 2.7.0 → 2.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +368 -351
- package/MIGRATION.md +162 -5
- package/README.en.md +13 -9
- package/README.md +19 -8
- package/README.zh.md +19 -8
- package/TRIGGER_GUIDE.md +2 -2
- package/ghost.json +18 -1
- package/package.json +1 -1
- package/plugins/carlos-flow-trigger.js +215 -215
- package/scripts/check-no-dead-handler.mjs +2 -2
- package/scripts/clean-readme-noise.mjs +53 -53
- package/scripts/lang-audit.mjs +164 -164
- package/scripts/mutation-check.mjs +483 -483
- package/scripts/sync-readme.mjs +102 -102
- package/scripts/verify-activation-e2e.sh +55 -55
- package/src/card.js +288 -288
- package/src/dispatch.js +451 -310
- package/src/index.js +1411 -1297
- package/src/protocol.js +76 -76
- package/src/state.js +192 -9
package/src/protocol.js
CHANGED
|
@@ -1,77 +1,77 @@
|
|
|
1
|
-
// Carlos Flow 协议 — 路由档位 / 四段合同 / 报告规格 / 错误分层 / 状态字段的唯一真源。
|
|
2
|
-
// 被协调器(coordinator)与各角色 Agent 共同引用。
|
|
3
|
-
|
|
4
|
-
export const PROTOCOL = {
|
|
5
|
-
ROUTE_TABLE: `| 档 | 场景 | 动作 |
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| T0 | 讨论 / 解释 / 概念澄清 | 直接答,不派发、不填卡,0 个子 Agent,无门禁 |
|
|
8
|
-
| T1 | 只读调研(摸清代码现状) | 派 explore,1 个子 Agent,免门禁 |
|
|
9
|
-
| T2 | 修改代码 / 配置 / 文档 | 留痕 → 派 executor → 派 auditor,2 个子 Agent,机械门禁 + 独立复核 |
|
|
10
|
-
|
|
11
|
-
判定口径:要写文件 = T2;要读文件但不写 = T1;两者都不需要 = T0`,
|
|
12
|
-
|
|
13
|
-
FOUR_CONTRACT: `四段合同(每段一行,主 Agent 必须在任务卡里写全):
|
|
14
|
-
1. objective:一句话目标。
|
|
15
|
-
2. output format:executor 报告 ≤300 字,四段式 —— 结论 / 改动(file:line 逐条)/ 验证结果 / 遗留风险。
|
|
16
|
-
3. tool guidance:验证命令由主 Agent 指定,executor 不得自选测试项。
|
|
17
|
-
4. task boundaries:只准改清单里的文件,一个不多;要改别的 → 停下来在报告里说明,不要自己扩大范围。`,
|
|
18
|
-
|
|
19
|
-
REPORT_SPEC: `executor 报告 ≤300 字,四段式:结论 / 改动 / 验证 / 遗留风险。
|
|
20
|
-
auditor 报告 ≤200 字,五段式:裁定 / 失败类型 / scope 标注 / 证据 / 附注。`,
|
|
21
|
-
|
|
22
|
-
ERROR_LAYERS: `| 层 | 触发 | 处置 |
|
|
23
|
-
|---|---|---|
|
|
24
|
-
| 基础设施故障 | 网络抖动、模型不可用、配额耗尽 | 静默降级或改用 Explore / 自读只读验证,不把原始错误喂回 |
|
|
25
|
-
| Agent 故障 | 工具名错、参数错 | 把错误喂回并附恢复指引 |
|
|
26
|
-
| 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件 |`,
|
|
27
|
-
|
|
28
|
-
STATE_FIELDS: `{"card":null,"card_ts":0,"tier":"read_only","task_id":null,"dispatch_count":0,"write_files":0,"last_user_ts":0,"bypass":false,"bypass_ts":0,"verdict":null,"completed_ok":false,"stale":false}`,
|
|
29
|
-
|
|
30
|
-
AUDIT_EVENTS: `["run","finding","decision","resolution"]`,
|
|
31
|
-
|
|
32
|
-
BYPASS_WORDS: `["直接干","跳过门禁","免检","别管流程","不用走流程"]`,
|
|
33
|
-
|
|
34
|
-
CARD_TEMPLATE: `FLOW_CARD:{"goal":"一句话目标","quote":"用户原话摘录","scope":["只准改的文件"],"acceptance":["可判定的验收标准"],"unknowns":[],"assumptions":[],"files":[{"path":"a/b.py","line":1}],"verify":{"cmd":"pytest -q tests/x.py"},"confirmed":false}`,
|
|
35
|
-
};
|
|
36
|
-
|
|
37
|
-
// 敏感文件名单(三种匹配方式:文件名命中 / 路径段命中 / 扩展名命中)
|
|
38
|
-
const SENSITIVE_NAMES = new Set([
|
|
39
|
-
".env", ".env.local", ".env.development", ".env.production", ".env.test",
|
|
40
|
-
"settings.json", "settings.local.json",
|
|
41
|
-
"package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
|
|
42
|
-
"poetry.lock", "requirements.txt",
|
|
43
|
-
"dockerfile", "docker-compose.yml", "docker-compose.yaml", "makefile",
|
|
44
|
-
]);
|
|
45
|
-
|
|
46
|
-
const SENSITIVE_SEGMENTS = new Set([
|
|
47
|
-
"migrations", "deploy", "deployment", "k8s", "kube",
|
|
48
|
-
".github", ".gitlab", "secrets", "certs", "terraform",
|
|
49
|
-
]);
|
|
50
|
-
|
|
51
|
-
const SENSITIVE_EXTENSIONS = new Set([
|
|
52
|
-
".pem", ".key", ".p12", ".pfx", ".env",
|
|
53
|
-
]);
|
|
54
|
-
|
|
55
|
-
export function isSensitive(rel) {
|
|
56
|
-
if (typeof rel !== "string" || rel.length === 0) return false;
|
|
57
|
-
const normalized = rel.replace(/\\/g, "/").toLowerCase();
|
|
58
|
-
const segments = normalized.split("/").filter((s) => s.length > 0);
|
|
59
|
-
const base = segments.length ? segments[segments.length - 1] : normalized;
|
|
60
|
-
|
|
61
|
-
if (SENSITIVE_NAMES.has(base)) return true;
|
|
62
|
-
// 只检查目录段(不含最后一段文件名):与 card.js 保持一致
|
|
63
|
-
for (const seg of segments.slice(0, -1)) {
|
|
64
|
-
if (SENSITIVE_SEGMENTS.has(seg)) return true;
|
|
65
|
-
}
|
|
66
|
-
for (const ext of SENSITIVE_EXTENSIONS) {
|
|
67
|
-
if (base.endsWith(ext)) return true;
|
|
68
|
-
}
|
|
69
|
-
return false;
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
export function riskTier(scope) {
|
|
73
|
-
if (!Array.isArray(scope) || scope.length === 0) return "read_only";
|
|
74
|
-
if (scope.some((p) => isSensitive(p))) return "sensitive";
|
|
75
|
-
if (scope.length === 1) return "single_file";
|
|
76
|
-
return "cross_module";
|
|
1
|
+
// Carlos Flow 协议 — 路由档位 / 四段合同 / 报告规格 / 错误分层 / 状态字段的唯一真源。
|
|
2
|
+
// 被协调器(coordinator)与各角色 Agent 共同引用。
|
|
3
|
+
|
|
4
|
+
export const PROTOCOL = {
|
|
5
|
+
ROUTE_TABLE: `| 档 | 场景 | 动作 |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| T0 | 讨论 / 解释 / 概念澄清 | 直接答,不派发、不填卡,0 个子 Agent,无门禁 |
|
|
8
|
+
| T1 | 只读调研(摸清代码现状) | 派 explore,1 个子 Agent,免门禁 |
|
|
9
|
+
| T2 | 修改代码 / 配置 / 文档 | 留痕 → 派 executor → 派 auditor,2 个子 Agent,机械门禁 + 独立复核 |
|
|
10
|
+
|
|
11
|
+
判定口径:要写文件 = T2;要读文件但不写 = T1;两者都不需要 = T0`,
|
|
12
|
+
|
|
13
|
+
FOUR_CONTRACT: `四段合同(每段一行,主 Agent 必须在任务卡里写全):
|
|
14
|
+
1. objective:一句话目标。
|
|
15
|
+
2. output format:executor 报告 ≤300 字,四段式 —— 结论 / 改动(file:line 逐条)/ 验证结果 / 遗留风险。
|
|
16
|
+
3. tool guidance:验证命令由主 Agent 指定,executor 不得自选测试项。
|
|
17
|
+
4. task boundaries:只准改清单里的文件,一个不多;要改别的 → 停下来在报告里说明,不要自己扩大范围。`,
|
|
18
|
+
|
|
19
|
+
REPORT_SPEC: `executor 报告 ≤300 字,四段式:结论 / 改动 / 验证 / 遗留风险。
|
|
20
|
+
auditor 报告 ≤200 字,五段式:裁定 / 失败类型 / scope 标注 / 证据 / 附注。`,
|
|
21
|
+
|
|
22
|
+
ERROR_LAYERS: `| 层 | 触发 | 处置 |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| 基础设施故障 | 网络抖动、模型不可用、配额耗尽 | 静默降级或改用 Explore / 自读只读验证,不把原始错误喂回 |
|
|
25
|
+
| Agent 故障 | 工具名错、参数错 | 把错误喂回并附恢复指引 |
|
|
26
|
+
| 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件 |`,
|
|
27
|
+
|
|
28
|
+
STATE_FIELDS: `{"card":null,"card_ts":0,"tier":"read_only","task_id":null,"dispatch_count":0,"write_files":0,"last_user_ts":0,"bypass":false,"bypass_ts":0,"verdict":null,"completed_ok":false,"stale":false}`,
|
|
29
|
+
|
|
30
|
+
AUDIT_EVENTS: `["run","finding","decision","resolution"]`,
|
|
31
|
+
|
|
32
|
+
BYPASS_WORDS: `["直接干","跳过门禁","免检","别管流程","不用走流程"]`,
|
|
33
|
+
|
|
34
|
+
CARD_TEMPLATE: `FLOW_CARD:{"goal":"一句话目标","quote":"用户原话摘录","scope":["只准改的文件"],"acceptance":["可判定的验收标准"],"unknowns":[],"assumptions":[],"files":[{"path":"a/b.py","line":1}],"verify":{"cmd":"pytest -q tests/x.py"},"confirmed":false}`,
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
// 敏感文件名单(三种匹配方式:文件名命中 / 路径段命中 / 扩展名命中)
|
|
38
|
+
const SENSITIVE_NAMES = new Set([
|
|
39
|
+
".env", ".env.local", ".env.development", ".env.production", ".env.test",
|
|
40
|
+
"settings.json", "settings.local.json",
|
|
41
|
+
"package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
|
|
42
|
+
"poetry.lock", "requirements.txt",
|
|
43
|
+
"dockerfile", "docker-compose.yml", "docker-compose.yaml", "makefile",
|
|
44
|
+
]);
|
|
45
|
+
|
|
46
|
+
const SENSITIVE_SEGMENTS = new Set([
|
|
47
|
+
"migrations", "deploy", "deployment", "k8s", "kube",
|
|
48
|
+
".github", ".gitlab", "secrets", "certs", "terraform",
|
|
49
|
+
]);
|
|
50
|
+
|
|
51
|
+
const SENSITIVE_EXTENSIONS = new Set([
|
|
52
|
+
".pem", ".key", ".p12", ".pfx", ".env",
|
|
53
|
+
]);
|
|
54
|
+
|
|
55
|
+
export function isSensitive(rel) {
|
|
56
|
+
if (typeof rel !== "string" || rel.length === 0) return false;
|
|
57
|
+
const normalized = rel.replace(/\\/g, "/").toLowerCase();
|
|
58
|
+
const segments = normalized.split("/").filter((s) => s.length > 0);
|
|
59
|
+
const base = segments.length ? segments[segments.length - 1] : normalized;
|
|
60
|
+
|
|
61
|
+
if (SENSITIVE_NAMES.has(base)) return true;
|
|
62
|
+
// 只检查目录段(不含最后一段文件名):与 card.js 保持一致
|
|
63
|
+
for (const seg of segments.slice(0, -1)) {
|
|
64
|
+
if (SENSITIVE_SEGMENTS.has(seg)) return true;
|
|
65
|
+
}
|
|
66
|
+
for (const ext of SENSITIVE_EXTENSIONS) {
|
|
67
|
+
if (base.endsWith(ext)) return true;
|
|
68
|
+
}
|
|
69
|
+
return false;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function riskTier(scope) {
|
|
73
|
+
if (!Array.isArray(scope) || scope.length === 0) return "read_only";
|
|
74
|
+
if (scope.some((p) => isSensitive(p))) return "sensitive";
|
|
75
|
+
if (scope.length === 1) return "single_file";
|
|
76
|
+
return "cross_module";
|
|
77
77
|
}
|
package/src/state.js
CHANGED
|
@@ -93,7 +93,7 @@ export function sanitizeId(s) {
|
|
|
93
93
|
|
|
94
94
|
// 当前状态文件结构版本号。
|
|
95
95
|
// 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
|
|
96
|
-
export const CURRENT_SCHEMA_VERSION =
|
|
96
|
+
export const CURRENT_SCHEMA_VERSION = 2;
|
|
97
97
|
|
|
98
98
|
/**
|
|
99
99
|
* 迁移旧版本的状态文件。
|
|
@@ -104,6 +104,9 @@ export const CURRENT_SCHEMA_VERSION = 1;
|
|
|
104
104
|
* v0 → v1:最早的版本没有 schemaVersion 字段(等于 v0)。
|
|
105
105
|
* · 补上 schemaVersion
|
|
106
106
|
* · dispatch_baseline 早期不存在 → 补空数组(无基线时裁定走全量判定,更保守)
|
|
107
|
+
*
|
|
108
|
+
* v1 → v2:新增 last_falsify(负对照记录)。
|
|
109
|
+
* · 旧状态没有这个字段 → 补 null(表示「还没做负对照」,裁定会拒绝 PASS)
|
|
107
110
|
*/
|
|
108
111
|
export function migrate(parsed) {
|
|
109
112
|
if (!parsed || typeof parsed !== "object") return parsed;
|
|
@@ -119,6 +122,12 @@ export function migrate(parsed) {
|
|
|
119
122
|
v = 1;
|
|
120
123
|
}
|
|
121
124
|
|
|
125
|
+
if (v < 2) {
|
|
126
|
+
// v1 → v2
|
|
127
|
+
if (out.last_falsify === undefined) out.last_falsify = null;
|
|
128
|
+
v = 2;
|
|
129
|
+
}
|
|
130
|
+
|
|
122
131
|
out.schemaVersion = CURRENT_SCHEMA_VERSION;
|
|
123
132
|
return out;
|
|
124
133
|
}
|
|
@@ -158,6 +167,12 @@ export function defaultState() {
|
|
|
158
167
|
// 再与卡片 scope 比对 —— 这样既能拦住越界,又不会把用户自己原有的
|
|
159
168
|
// 未提交改动误判为越界。没有基线时退化为全量判定(更保守,fail-closed)。
|
|
160
169
|
dispatch_baseline: [],
|
|
170
|
+
// 负对照记录(flow_falsify 写入)。
|
|
171
|
+
// 为什么需要:只看 exitCode===0 时,`verify.cmd` 可以是 `|| true` / `echo ok`
|
|
172
|
+
// 这类**空测试** —— 改动前后都退 0,门禁却以为「验证通过了」。
|
|
173
|
+
// 负对照要求:改动前必须失败、改动后必须通过,才证明这个测试真的在测本次改动。
|
|
174
|
+
// null = 还没做负对照(此时 flow_verdict 拒绝 PASS)。
|
|
175
|
+
last_falsify: null,
|
|
161
176
|
};
|
|
162
177
|
}
|
|
163
178
|
|
|
@@ -173,11 +188,14 @@ export function loadState(sid) {
|
|
|
173
188
|
}
|
|
174
189
|
|
|
175
190
|
export function saveState(sid, state) {
|
|
191
|
+
// 落盘脱敏:`state.card` 可能携带密钥片段(verify.cmd/token/password),
|
|
192
|
+
// 不能明文落盘。sanitizeFields 只脱敏 value,key 名保留。
|
|
193
|
+
const safeState = sanitizeFields(state ?? defaultState());
|
|
176
194
|
const dir = path.join(RUNS_DIR, sanitizeId(sid));
|
|
177
195
|
fs.mkdirSync(dir, { recursive: true });
|
|
178
196
|
const tmp = path.join(dir, "state.json.tmp");
|
|
179
197
|
const target = path.join(dir, "state.json");
|
|
180
|
-
fs.writeFileSync(tmp, JSON.stringify(
|
|
198
|
+
fs.writeFileSync(tmp, JSON.stringify(safeState, null, 2), "utf8");
|
|
181
199
|
fs.renameSync(tmp, target);
|
|
182
200
|
return target;
|
|
183
201
|
}
|
|
@@ -273,6 +291,47 @@ function lastHashOf(file) {
|
|
|
273
291
|
}
|
|
274
292
|
}
|
|
275
293
|
|
|
294
|
+
// 审计文件按天分片(`${localDate()}.jsonl`)。
|
|
295
|
+
//
|
|
296
|
+
// 审计链是「分片链表」:前一天的最后一条记录的 hash 应当传给后一天的第一条
|
|
297
|
+
// 的 prevHash。**旧代码 `audit()` 只取当天文件的 tail**(当天文件不存在时退化成
|
|
298
|
+
// 全 0),于是链子每天都在午夜断开——攻击者篡改**任意历史天**的记录,今天
|
|
299
|
+
// 的 `verifyAuditChain()` 查不出来。
|
|
300
|
+
//
|
|
301
|
+
// 新增三个辅助:
|
|
302
|
+
// · auditDayFiles() → 按日期升序排列的审计文件清单
|
|
303
|
+
// · lastHashOfDay(date)→ 某天文件最后一条记录的 hash(不存在那一天退化为 ZERO)
|
|
304
|
+
// · nextPrevHash(date) → 取「当天 tail」,当天没有则往前找最近一天的 tail
|
|
305
|
+
//
|
|
306
|
+
// `audit()` 用 nextPrevHash 把每天的 tail 串成完整链,
|
|
307
|
+
// `verifyAuditChain()` 用同一套规则逐天串联验证。
|
|
308
|
+
function auditDayFiles() {
|
|
309
|
+
try {
|
|
310
|
+
return fs.readdirSync(AUDIT_DIR).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)).sort();
|
|
311
|
+
} catch {
|
|
312
|
+
return [];
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
function lastHashOfDay(date) {
|
|
317
|
+
return lastHashOf(path.join(AUDIT_DIR, `${date}.jsonl`));
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
// 取「当天 tail」,当天没有就往前找最近一天的 tail(修跨天断链)
|
|
321
|
+
function nextPrevHash(date) {
|
|
322
|
+
const file = path.join(AUDIT_DIR, `${date}.jsonl`);
|
|
323
|
+
const prev = lastHashOf(file);
|
|
324
|
+
if (prev !== "0".repeat(64)) return prev; // 当天有链,正常运行
|
|
325
|
+
// 当天还没有记录:**从 date 前一天起**按日期降序找最近已有 tail,绝不看 future。
|
|
326
|
+
const today = localDate();
|
|
327
|
+
const sorted = auditDayFiles().sort().filter((f) => f.slice(0, 10) < today);
|
|
328
|
+
for (let i = sorted.length - 1; i >= 0; i--) {
|
|
329
|
+
if (sorted[i].slice(0, 10) >= date) continue; // 只能找 date 之前的
|
|
330
|
+
const h = lastHashOf(path.join(AUDIT_DIR, sorted[i]));
|
|
331
|
+
if (h !== "0".repeat(64)) return h;
|
|
332
|
+
}
|
|
333
|
+
return "0".repeat(64);
|
|
334
|
+
}
|
|
276
335
|
// 哈希载荷:除链字段外的全部字段,保持写入/校验口径完全一致
|
|
277
336
|
function auditPayload(rec) {
|
|
278
337
|
const SKIP = new Set(["ts", "type", "sessionID", "prevHash", "hash"]);
|
|
@@ -283,6 +342,64 @@ function auditPayload(rec) {
|
|
|
283
342
|
return JSON.stringify(out);
|
|
284
343
|
}
|
|
285
344
|
|
|
345
|
+
// 敏感信息脱敏
|
|
346
|
+
//
|
|
347
|
+
// 用户卡片里可能包含密钥/密码(`verify.cmd` 里的 `sk_live_xxx`、`token`、
|
|
348
|
+
// `password`),审计记录也接受任意 `fields`——如果原样落盘,**门禁本身成了泄露源**。
|
|
349
|
+
//
|
|
350
|
+
// 规则:
|
|
351
|
+
// · key 命中 `secret/key/password/pwd/token/credential/auth` 之一(不区分大小写)
|
|
352
|
+
// · 或 string value 里含有 `sk_|secret=|password=|token=|api_key=|sk_live|sk_test`
|
|
353
|
+
// → 记为敏感 value,脱敏:长度 ≤ 8 → `[脱敏]`,否则头尾各保留 4 个字符中间 ***
|
|
354
|
+
//
|
|
355
|
+
// 任何异常都不可抛(`audit` 必须永不抛错),脱敏失败则原地返回原值。
|
|
356
|
+
function isSensitiveKey(k) {
|
|
357
|
+
try {
|
|
358
|
+
return typeof k === "string" && /[Ss]ecret|[Kk]ey|[Pp]assword|[Pp]wd|[Tt]oken|[Cc]redential|[Aa]uth/.test(k);
|
|
359
|
+
} catch {
|
|
360
|
+
return false;
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
const SENSITIVE_VALUES_RE = /sk_|secret=|password=|token=|api_key=|sk_live|sk_test|secret:/i;
|
|
364
|
+
function isSensitiveValue(v) {
|
|
365
|
+
try {
|
|
366
|
+
return typeof v === "string" && v.length > 0 && SENSITIVE_VALUES_RE.test(v);
|
|
367
|
+
} catch {
|
|
368
|
+
return false;
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
function maskValue(v) {
|
|
372
|
+
try {
|
|
373
|
+
if (typeof v === "string" && v.length > 0) {
|
|
374
|
+
if (v.length <= 8) return "[脱敏]";
|
|
375
|
+
return v.slice(0, 4) + "***" + v.slice(-4);
|
|
376
|
+
}
|
|
377
|
+
return v;
|
|
378
|
+
} catch {
|
|
379
|
+
return v;
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
function sanitizeValue(v) {
|
|
383
|
+
try {
|
|
384
|
+
if (Array.isArray(v)) return v.map(sanitizeValue);
|
|
385
|
+
if (v && typeof v === "object") {
|
|
386
|
+
const out = {};
|
|
387
|
+
for (const k of Object.keys(v)) {
|
|
388
|
+
const val = v[k];
|
|
389
|
+
out[k] = isSensitiveKey(k) || isSensitiveValue(val) ? maskValue(val) : sanitizeValue(val);
|
|
390
|
+
}
|
|
391
|
+
return out;
|
|
392
|
+
}
|
|
393
|
+
return v;
|
|
394
|
+
} catch {
|
|
395
|
+
return v;
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
export function sanitizeFields(o) {
|
|
399
|
+
return sanitizeValue(o ?? {});
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
|
|
286
403
|
// ---- 审计链哈希模式 ----
|
|
287
404
|
//
|
|
288
405
|
// 裸 SHA-256 哈希链能防的是「**意外**损坏」(截断、位翻转、误删),
|
|
@@ -316,17 +433,20 @@ function computeAuditHash(rec, prev) {
|
|
|
316
433
|
|
|
317
434
|
// 追加审计行;永不抛错,失败仅写 stderr;返回记录对象
|
|
318
435
|
export function audit(type, sid, fields = {}) {
|
|
436
|
+
// 落盘脱敏:用户卡片/审计字段里的密钥片段(verify.cmd 等)不能明文入盘。
|
|
437
|
+
const sanitized = sanitizeFields(fields);
|
|
319
438
|
const rec = {
|
|
320
439
|
ts: new Date().toISOString(),
|
|
321
440
|
type,
|
|
322
441
|
sessionID: sanitizeId(sid),
|
|
323
|
-
...
|
|
442
|
+
...sanitized,
|
|
324
443
|
};
|
|
325
444
|
try {
|
|
326
445
|
fs.mkdirSync(AUDIT_DIR, { recursive: true });
|
|
327
446
|
const file = path.join(AUDIT_DIR, `${localDate()}.jsonl`);
|
|
328
|
-
// 前驱 hash
|
|
329
|
-
|
|
447
|
+
// 前驱 hash 取自当天文件 tail;当天没有记录时退成分片链上一天的 tail
|
|
448
|
+
//(nextPrevHash),这样审计链在午夜也不断开。
|
|
449
|
+
const prev = nextPrevHash(localDate());
|
|
330
450
|
rec.prevHash = prev;
|
|
331
451
|
rec.hash = computeAuditHash(rec, prev);
|
|
332
452
|
// 单次 appendFileSync:O_APPEND 语义,多进程并发写不会互相截断
|
|
@@ -339,12 +459,70 @@ export function audit(type, sid, fields = {}) {
|
|
|
339
459
|
return rec;
|
|
340
460
|
}
|
|
341
461
|
|
|
342
|
-
//
|
|
462
|
+
// 校验审计链完整性(可选:需完整文件,不能只看尾部)。
|
|
463
|
+
//
|
|
464
|
+
// 审计文件按天分片(`localDate().jsonl`),审计链是「分片链表」:
|
|
465
|
+
// 前一天最后一条记录的 hash 是后一天第一条记录的 prevHash(nextPrevHash)。
|
|
466
|
+
// 所以默认 `verifyAuditChain()` **逐天串联所有记录** 验证整条链——
|
|
467
|
+
// 攻击者篡改任意一天的任意记录,整链检测都会 break(配合 CARLOS_FLOW_AUDIT_KEY
|
|
468
|
+
// 为 HMAC 时做得到;plain 模式可在推荐结果里看到 mode 降级声明)。
|
|
469
|
+
//
|
|
470
|
+
// `opts.date` 给定的一天 → 只验证那一天(验证起点是前一天 tail,跨天)。
|
|
471
|
+
// `opts.fullChain` 默认 true → 验证全部天的完整链。
|
|
343
472
|
export function verifyAuditChain(opts = {}) {
|
|
344
473
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|
|
345
474
|
// ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效:
|
|
346
475
|
// 传 date='2020-01-01' 读的仍是**今天**的文件,调用方以为在查历史、
|
|
347
476
|
// 实际拿到今天的数据(错而不报,最难发现)。
|
|
477
|
+
const fullChain = typeof opts.fullChain === "boolean" ? opts.fullChain : true;
|
|
478
|
+
if (fullChain && !opts.date) {
|
|
479
|
+
// 全链验证:逐天(按文件名升序 == 升时)串联,每天的 tail 是下一天的 prevHash。
|
|
480
|
+
const files = auditDayFiles();
|
|
481
|
+
const byDay = [];
|
|
482
|
+
let total = 0, broken = 0, legacy = 0;
|
|
483
|
+
const brokenAt = [];
|
|
484
|
+
let prev = "0".repeat(64); // 链起点
|
|
485
|
+
for (const f of files) {
|
|
486
|
+
let raw = "";
|
|
487
|
+
try {
|
|
488
|
+
raw = fs.readFileSync(path.join(AUDIT_DIR, f), "utf8");
|
|
489
|
+
} catch {
|
|
490
|
+
continue;
|
|
491
|
+
}
|
|
492
|
+
let dayBroken = 0, dayLegacy = 0;
|
|
493
|
+
for (const line of raw.split("\n")) {
|
|
494
|
+
const t = line.trim();
|
|
495
|
+
if (!t) continue;
|
|
496
|
+
let r;
|
|
497
|
+
try {
|
|
498
|
+
r = JSON.parse(t);
|
|
499
|
+
} catch {
|
|
500
|
+
continue;
|
|
501
|
+
}
|
|
502
|
+
total++;
|
|
503
|
+
if (typeof r.hash !== "string") {
|
|
504
|
+
// 旧格式记录(无 hash)→ 计入 legacy 计数,但**不重置链起点**
|
|
505
|
+
legacy++;
|
|
506
|
+
dayLegacy++;
|
|
507
|
+
continue;
|
|
508
|
+
}
|
|
509
|
+
const expect = computeAuditHash(r, prev);
|
|
510
|
+
if (expect !== r.hash || r.prevHash !== prev) {
|
|
511
|
+
broken++;
|
|
512
|
+
dayBroken++;
|
|
513
|
+
if (brokenAt.length < 10) brokenAt.push({ date: f.slice(0, 10), ts: r.ts, type: r.type, kind: r.kind });
|
|
514
|
+
}
|
|
515
|
+
prev = r.hash;
|
|
516
|
+
}
|
|
517
|
+
byDay.push({ date: f.slice(0, 10), dayBroken, dayLegacy, tailHash: prev });
|
|
518
|
+
}
|
|
519
|
+
return {
|
|
520
|
+
ok: broken === 0, total, broken, legacy, brokenAt, byDay, mode: auditHashMode(),
|
|
521
|
+
note: "全链验证:逐天串联,每天的 tail 是下一天的前驱。",
|
|
522
|
+
};
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
// 单日验证:按 date 读一天文件,链起点用前一天 tail(跨天联动)或全 0(新链第一天)。
|
|
348
526
|
const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
|
|
349
527
|
let raw = "";
|
|
350
528
|
try {
|
|
@@ -352,10 +530,14 @@ export function verifyAuditChain(opts = {}) {
|
|
|
352
530
|
} catch {
|
|
353
531
|
return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file, mode: auditHashMode() };
|
|
354
532
|
}
|
|
533
|
+
// 单日的链起点:前一个 tail hash(跨天)或全 0(新链第一天)。
|
|
534
|
+
const files = auditDayFiles();
|
|
355
535
|
let prev = "0".repeat(64);
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
536
|
+
for (const f of files) {
|
|
537
|
+
if (f === `${rawDate}.jsonl`) break;
|
|
538
|
+
prev = lastHashOf(path.join(AUDIT_DIR, f));
|
|
539
|
+
}
|
|
540
|
+
let total = 0, broken = 0, legacy = 0;
|
|
359
541
|
const brokenAt = [];
|
|
360
542
|
for (const line of raw.split("\n")) {
|
|
361
543
|
const t = line.trim();
|
|
@@ -391,6 +573,7 @@ export function verifyAuditChain(opts = {}) {
|
|
|
391
573
|
return { ok: broken === 0, total, broken, legacy, brokenAt, file, mode: auditHashMode() };
|
|
392
574
|
}
|
|
393
575
|
|
|
576
|
+
|
|
394
577
|
export function readAudit(opts = {}) {
|
|
395
578
|
const { sessionId, type, limit } = opts;
|
|
396
579
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|