carlos-flow 2.6.3 → 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/AGENTS.md +101 -0
- package/CHANGELOG.md +368 -255
- package/MIGRATION.md +162 -5
- package/README.en.md +79 -10
- package/README.md +89 -11
- package/README.zh.md +89 -11
- package/TRIGGER_GUIDE.md +2 -2
- package/bridge/mcp-bridge.js +15 -1
- package/client/carlos.js +122 -11
- package/ghost.json +18 -1
- package/package.json +10 -3
- package/plugins/carlos-flow-trigger.js +215 -215
- package/scripts/check-claims.mjs +188 -0
- package/scripts/check-no-dead-handler.mjs +88 -0
- package/scripts/check-params.mjs +188 -0
- package/scripts/clean-readme-noise.mjs +53 -53
- package/scripts/lang-audit.mjs +164 -164
- package/scripts/mutation-check.mjs +435 -392
- 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 -252
- package/src/index.js +1411 -1252
- package/src/protocol.js +76 -76
- package/src/state.js +288 -21
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
|
@@ -3,7 +3,7 @@ import fs from "node:fs";
|
|
|
3
3
|
import path from "node:path";
|
|
4
4
|
import os from "node:os";
|
|
5
5
|
import { spawnSync } from "node:child_process";
|
|
6
|
-
import { createHash } from "node:crypto";
|
|
6
|
+
import { createHash, createHmac } from "node:crypto";
|
|
7
7
|
|
|
8
8
|
|
|
9
9
|
// 展开路径里的 `~`(家目录)。
|
|
@@ -91,8 +91,56 @@ export function sanitizeId(s) {
|
|
|
91
91
|
return v;
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
+
// 当前状态文件结构版本号。
|
|
95
|
+
// 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
|
|
96
|
+
export const CURRENT_SCHEMA_VERSION = 2;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* 迁移旧版本的状态文件。
|
|
100
|
+
*
|
|
101
|
+
* 逐版本迁移,每一步都只处理「从 vN 到 vN+1」的差异,
|
|
102
|
+
* 保证任何历史版本都能一路迁到当前版本(不跳步)。
|
|
103
|
+
*
|
|
104
|
+
* v0 → v1:最早的版本没有 schemaVersion 字段(等于 v0)。
|
|
105
|
+
* · 补上 schemaVersion
|
|
106
|
+
* · dispatch_baseline 早期不存在 → 补空数组(无基线时裁定走全量判定,更保守)
|
|
107
|
+
*
|
|
108
|
+
* v1 → v2:新增 last_falsify(负对照记录)。
|
|
109
|
+
* · 旧状态没有这个字段 → 补 null(表示「还没做负对照」,裁定会拒绝 PASS)
|
|
110
|
+
*/
|
|
111
|
+
export function migrate(parsed) {
|
|
112
|
+
if (!parsed || typeof parsed !== "object") return parsed;
|
|
113
|
+
let v = Number(parsed.schemaVersion);
|
|
114
|
+
if (!Number.isInteger(v) || v < 0) v = 0; // 无版本号 → 当作 v0
|
|
115
|
+
const out = { ...parsed };
|
|
116
|
+
|
|
117
|
+
if (v < 1) {
|
|
118
|
+
// v0 → v1
|
|
119
|
+
if (!Array.isArray(out.dispatch_baseline)) out.dispatch_baseline = [];
|
|
120
|
+
if (!Array.isArray(out.activation_pending)) out.activation_pending = [];
|
|
121
|
+
if (typeof out.activation_activated !== "boolean") out.activation_activated = false;
|
|
122
|
+
v = 1;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
if (v < 2) {
|
|
126
|
+
// v1 → v2
|
|
127
|
+
if (out.last_falsify === undefined) out.last_falsify = null;
|
|
128
|
+
v = 2;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
out.schemaVersion = CURRENT_SCHEMA_VERSION;
|
|
132
|
+
return out;
|
|
133
|
+
}
|
|
134
|
+
|
|
94
135
|
export function defaultState() {
|
|
95
136
|
return {
|
|
137
|
+
// 状态文件结构版本号。
|
|
138
|
+
// 为什么需要:早先靠 {...defaultState(), ...parsed} 做防御性合并,
|
|
139
|
+
// 但**没有版本号** —— 将来改字段名(如 bypass_ts → bypass_at)时,
|
|
140
|
+
// 老用户的 state.json 里那个旧字段会被当成「未知字段」静默丢弃,
|
|
141
|
+
// 表现为「免检没清零」「待补项丢失」这类**很难定位**的退化。
|
|
142
|
+
// 加了版本号 + migrate(),旧状态会被**显式迁移**而不是静默降级。
|
|
143
|
+
schemaVersion: CURRENT_SCHEMA_VERSION,
|
|
96
144
|
card: null,
|
|
97
145
|
card_ts: 0,
|
|
98
146
|
tier: "read_only",
|
|
@@ -114,6 +162,17 @@ export function defaultState() {
|
|
|
114
162
|
// 闸门状态由「卡片内容 + 此标记」幂等派生,不再依赖上一轮的 pending 传递,
|
|
115
163
|
// 这样跨进程并发写入也不会出现「卡片为空却 pending=[]」的矛盾组合。
|
|
116
164
|
activation_activated: false,
|
|
165
|
+
// 派发时记录的工作区改动基线(文件路径数组)。
|
|
166
|
+
// 用途:裁定前用「当前改动 - 基线」算出**本次执行引入的**改动,
|
|
167
|
+
// 再与卡片 scope 比对 —— 这样既能拦住越界,又不会把用户自己原有的
|
|
168
|
+
// 未提交改动误判为越界。没有基线时退化为全量判定(更保守,fail-closed)。
|
|
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,
|
|
117
176
|
};
|
|
118
177
|
}
|
|
119
178
|
|
|
@@ -122,18 +181,21 @@ export function loadState(sid) {
|
|
|
122
181
|
const file = path.join(RUNS_DIR, sanitizeId(sid), "state.json");
|
|
123
182
|
const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
124
183
|
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return defaultState();
|
|
125
|
-
return { ...defaultState(), ...parsed };
|
|
184
|
+
return { ...defaultState(), ...migrate(parsed) };
|
|
126
185
|
} catch {
|
|
127
186
|
return defaultState();
|
|
128
187
|
}
|
|
129
188
|
}
|
|
130
189
|
|
|
131
190
|
export function saveState(sid, state) {
|
|
191
|
+
// 落盘脱敏:`state.card` 可能携带密钥片段(verify.cmd/token/password),
|
|
192
|
+
// 不能明文落盘。sanitizeFields 只脱敏 value,key 名保留。
|
|
193
|
+
const safeState = sanitizeFields(state ?? defaultState());
|
|
132
194
|
const dir = path.join(RUNS_DIR, sanitizeId(sid));
|
|
133
195
|
fs.mkdirSync(dir, { recursive: true });
|
|
134
196
|
const tmp = path.join(dir, "state.json.tmp");
|
|
135
197
|
const target = path.join(dir, "state.json");
|
|
136
|
-
fs.writeFileSync(tmp, JSON.stringify(
|
|
198
|
+
fs.writeFileSync(tmp, JSON.stringify(safeState, null, 2), "utf8");
|
|
137
199
|
fs.renameSync(tmp, target);
|
|
138
200
|
return target;
|
|
139
201
|
}
|
|
@@ -229,6 +291,47 @@ function lastHashOf(file) {
|
|
|
229
291
|
}
|
|
230
292
|
}
|
|
231
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
|
+
}
|
|
232
335
|
// 哈希载荷:除链字段外的全部字段,保持写入/校验口径完全一致
|
|
233
336
|
function auditPayload(rec) {
|
|
234
337
|
const SKIP = new Set(["ts", "type", "sessionID", "prevHash", "hash"]);
|
|
@@ -239,23 +342,113 @@ function auditPayload(rec) {
|
|
|
239
342
|
return JSON.stringify(out);
|
|
240
343
|
}
|
|
241
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
|
+
|
|
403
|
+
// ---- 审计链哈希模式 ----
|
|
404
|
+
//
|
|
405
|
+
// 裸 SHA-256 哈希链能防的是「**意外**损坏」(截断、位翻转、误删),
|
|
406
|
+
// **防不了有意篡改**:攻击者能读文件,就能重算整条链。
|
|
407
|
+
//
|
|
408
|
+
// 因此提供两种模式:
|
|
409
|
+
// · hmac —— 设置了 CARLOS_FLOW_AUDIT_KEY 时使用带密钥的 HMAC-SHA256。
|
|
410
|
+
// 攻击者没有密钥 → 重算不出正确 hash → 篡改必被发现。
|
|
411
|
+
// · plain —— 未设置密钥时的降级模式(裸 SHA-256),**在 verify 结果里
|
|
412
|
+
// 显式标注 mode**,让调用方知道自己拿到的是哪种保证。
|
|
413
|
+
//
|
|
414
|
+
// 不做「默认启用 HMAC」:没有密钥就签不了名,用户第一次用就会报错。
|
|
415
|
+
// 也不做「假装 HMAC」:plain 模式必须诚实地说自己只是弱保证。
|
|
416
|
+
const AUDIT_KEY = (() => {
|
|
417
|
+
const k = process.env.CARLOS_FLOW_AUDIT_KEY;
|
|
418
|
+
return typeof k === "string" && k.length >= 16 ? k : null;
|
|
419
|
+
})();
|
|
420
|
+
|
|
421
|
+
export function auditHashMode() {
|
|
422
|
+
return AUDIT_KEY ? "hmac" : "plain";
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
// 计算一条记录的 hash(写入与校验必须用同一套函数,否则永远对不上)
|
|
426
|
+
function computeAuditHash(rec, prev) {
|
|
427
|
+
const payload = rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev;
|
|
428
|
+
if (AUDIT_KEY) {
|
|
429
|
+
return createHmac("sha256", AUDIT_KEY).update(payload).digest("hex");
|
|
430
|
+
}
|
|
431
|
+
return createHash("sha256").update(payload).digest("hex");
|
|
432
|
+
}
|
|
433
|
+
|
|
242
434
|
// 追加审计行;永不抛错,失败仅写 stderr;返回记录对象
|
|
243
435
|
export function audit(type, sid, fields = {}) {
|
|
436
|
+
// 落盘脱敏:用户卡片/审计字段里的密钥片段(verify.cmd 等)不能明文入盘。
|
|
437
|
+
const sanitized = sanitizeFields(fields);
|
|
244
438
|
const rec = {
|
|
245
439
|
ts: new Date().toISOString(),
|
|
246
440
|
type,
|
|
247
441
|
sessionID: sanitizeId(sid),
|
|
248
|
-
...
|
|
442
|
+
...sanitized,
|
|
249
443
|
};
|
|
250
444
|
try {
|
|
251
445
|
fs.mkdirSync(AUDIT_DIR, { recursive: true });
|
|
252
446
|
const file = path.join(AUDIT_DIR, `${localDate()}.jsonl`);
|
|
253
|
-
// 前驱 hash
|
|
254
|
-
|
|
447
|
+
// 前驱 hash 取自当天文件 tail;当天没有记录时退成分片链上一天的 tail
|
|
448
|
+
//(nextPrevHash),这样审计链在午夜也不断开。
|
|
449
|
+
const prev = nextPrevHash(localDate());
|
|
255
450
|
rec.prevHash = prev;
|
|
256
|
-
rec.hash =
|
|
257
|
-
.update(rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev)
|
|
258
|
-
.digest("hex");
|
|
451
|
+
rec.hash = computeAuditHash(rec, prev);
|
|
259
452
|
// 单次 appendFileSync:O_APPEND 语义,多进程并发写不会互相截断
|
|
260
453
|
fs.appendFileSync(file, JSON.stringify(rec) + "\n", "utf8");
|
|
261
454
|
} catch (e) {
|
|
@@ -266,20 +459,85 @@ export function audit(type, sid, fields = {}) {
|
|
|
266
459
|
return rec;
|
|
267
460
|
}
|
|
268
461
|
|
|
269
|
-
//
|
|
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 → 验证全部天的完整链。
|
|
270
472
|
export function verifyAuditChain(opts = {}) {
|
|
271
473
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|
|
272
|
-
|
|
474
|
+
// ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效:
|
|
475
|
+
// 传 date='2020-01-01' 读的仍是**今天**的文件,调用方以为在查历史、
|
|
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(新链第一天)。
|
|
526
|
+
const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
|
|
273
527
|
let raw = "";
|
|
274
528
|
try {
|
|
275
529
|
raw = fs.readFileSync(file, "utf8");
|
|
276
530
|
} catch {
|
|
277
|
-
return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file };
|
|
531
|
+
return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file, mode: auditHashMode() };
|
|
278
532
|
}
|
|
533
|
+
// 单日的链起点:前一个 tail hash(跨天)或全 0(新链第一天)。
|
|
534
|
+
const files = auditDayFiles();
|
|
279
535
|
let prev = "0".repeat(64);
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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;
|
|
283
541
|
const brokenAt = [];
|
|
284
542
|
for (const line of raw.split("\n")) {
|
|
285
543
|
const t = line.trim();
|
|
@@ -292,27 +550,36 @@ export function verifyAuditChain(opts = {}) {
|
|
|
292
550
|
}
|
|
293
551
|
total++;
|
|
294
552
|
if (typeof r.hash !== "string") {
|
|
553
|
+
// 旧格式记录(无 hash)→ 计入 legacy 计数,但**不重置链起点**。
|
|
554
|
+
//
|
|
555
|
+
// 早先这里写的是 prev = "0".repeat(64),于是**一条**旧记录就会让
|
|
556
|
+
// 它之后所有记录的 prevHash 全部对不上 → 全判 broken。
|
|
557
|
+
// 后果:v2.5 升级上来的用户,审计链校验会长期报红,
|
|
558
|
+
// 而 README 把「可验证审计链」列为核心能力 —— 用户会以为自己的
|
|
559
|
+
// 审计记录被篡改了。**漏报比误报可接受,误报更伤信任。**
|
|
295
560
|
legacy++;
|
|
296
|
-
prev = "0".repeat(64);
|
|
297
561
|
continue;
|
|
298
562
|
}
|
|
299
|
-
const expect =
|
|
300
|
-
.update(r.ts + r.type + r.sessionID + auditPayload(r) + prev)
|
|
301
|
-
.digest("hex");
|
|
563
|
+
const expect = computeAuditHash(r, prev);
|
|
302
564
|
if (expect !== r.hash || r.prevHash !== prev) {
|
|
303
565
|
broken++;
|
|
304
566
|
if (brokenAt.length < 10) brokenAt.push({ ts: r.ts, type: r.type, kind: r.kind });
|
|
305
567
|
}
|
|
306
568
|
prev = r.hash;
|
|
307
569
|
}
|
|
308
|
-
|
|
570
|
+
// mode 字段说明本次校验的**保证强度**:
|
|
571
|
+
// hmac → 带密钥(CARLOS_FLOW_AUDIT_KEY),能发现有意篡改
|
|
572
|
+
// plain → 裸 SHA-256,只能发现意外损坏(攻击者能重算整条链)
|
|
573
|
+
return { ok: broken === 0, total, broken, legacy, brokenAt, file, mode: auditHashMode() };
|
|
309
574
|
}
|
|
310
575
|
|
|
576
|
+
|
|
311
577
|
export function readAudit(opts = {}) {
|
|
312
578
|
const { sessionId, type, limit } = opts;
|
|
313
579
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|
|
314
580
|
try {
|
|
315
|
-
|
|
581
|
+
// ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效。
|
|
582
|
+
const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
|
|
316
583
|
const raw = fs.readFileSync(file, "utf8");
|
|
317
584
|
const out = [];
|
|
318
585
|
for (const line of raw.split("\n")) {
|