carlos-flow 2.6.3 → 2.7.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 +96 -0
- package/README.en.md +67 -2
- package/README.md +72 -5
- package/README.zh.md +72 -5
- package/TRIGGER_GUIDE.md +2 -2
- package/bridge/mcp-bridge.js +15 -1
- package/client/carlos.js +122 -11
- package/ghost.json +1 -1
- package/package.json +10 -3
- 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/mutation-check.mjs +94 -51
- package/src/dispatch.js +63 -5
- package/src/index.js +66 -21
- package/src/state.js +97 -13
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,47 @@ export function sanitizeId(s) {
|
|
|
91
91
|
return v;
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
+
// 当前状态文件结构版本号。
|
|
95
|
+
// 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
|
|
96
|
+
export const CURRENT_SCHEMA_VERSION = 1;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* 迁移旧版本的状态文件。
|
|
100
|
+
*
|
|
101
|
+
* 逐版本迁移,每一步都只处理「从 vN 到 vN+1」的差异,
|
|
102
|
+
* 保证任何历史版本都能一路迁到当前版本(不跳步)。
|
|
103
|
+
*
|
|
104
|
+
* v0 → v1:最早的版本没有 schemaVersion 字段(等于 v0)。
|
|
105
|
+
* · 补上 schemaVersion
|
|
106
|
+
* · dispatch_baseline 早期不存在 → 补空数组(无基线时裁定走全量判定,更保守)
|
|
107
|
+
*/
|
|
108
|
+
export function migrate(parsed) {
|
|
109
|
+
if (!parsed || typeof parsed !== "object") return parsed;
|
|
110
|
+
let v = Number(parsed.schemaVersion);
|
|
111
|
+
if (!Number.isInteger(v) || v < 0) v = 0; // 无版本号 → 当作 v0
|
|
112
|
+
const out = { ...parsed };
|
|
113
|
+
|
|
114
|
+
if (v < 1) {
|
|
115
|
+
// v0 → v1
|
|
116
|
+
if (!Array.isArray(out.dispatch_baseline)) out.dispatch_baseline = [];
|
|
117
|
+
if (!Array.isArray(out.activation_pending)) out.activation_pending = [];
|
|
118
|
+
if (typeof out.activation_activated !== "boolean") out.activation_activated = false;
|
|
119
|
+
v = 1;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
out.schemaVersion = CURRENT_SCHEMA_VERSION;
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
|
|
94
126
|
export function defaultState() {
|
|
95
127
|
return {
|
|
128
|
+
// 状态文件结构版本号。
|
|
129
|
+
// 为什么需要:早先靠 {...defaultState(), ...parsed} 做防御性合并,
|
|
130
|
+
// 但**没有版本号** —— 将来改字段名(如 bypass_ts → bypass_at)时,
|
|
131
|
+
// 老用户的 state.json 里那个旧字段会被当成「未知字段」静默丢弃,
|
|
132
|
+
// 表现为「免检没清零」「待补项丢失」这类**很难定位**的退化。
|
|
133
|
+
// 加了版本号 + migrate(),旧状态会被**显式迁移**而不是静默降级。
|
|
134
|
+
schemaVersion: CURRENT_SCHEMA_VERSION,
|
|
96
135
|
card: null,
|
|
97
136
|
card_ts: 0,
|
|
98
137
|
tier: "read_only",
|
|
@@ -114,6 +153,11 @@ export function defaultState() {
|
|
|
114
153
|
// 闸门状态由「卡片内容 + 此标记」幂等派生,不再依赖上一轮的 pending 传递,
|
|
115
154
|
// 这样跨进程并发写入也不会出现「卡片为空却 pending=[]」的矛盾组合。
|
|
116
155
|
activation_activated: false,
|
|
156
|
+
// 派发时记录的工作区改动基线(文件路径数组)。
|
|
157
|
+
// 用途:裁定前用「当前改动 - 基线」算出**本次执行引入的**改动,
|
|
158
|
+
// 再与卡片 scope 比对 —— 这样既能拦住越界,又不会把用户自己原有的
|
|
159
|
+
// 未提交改动误判为越界。没有基线时退化为全量判定(更保守,fail-closed)。
|
|
160
|
+
dispatch_baseline: [],
|
|
117
161
|
};
|
|
118
162
|
}
|
|
119
163
|
|
|
@@ -122,7 +166,7 @@ export function loadState(sid) {
|
|
|
122
166
|
const file = path.join(RUNS_DIR, sanitizeId(sid), "state.json");
|
|
123
167
|
const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
124
168
|
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return defaultState();
|
|
125
|
-
return { ...defaultState(), ...parsed };
|
|
169
|
+
return { ...defaultState(), ...migrate(parsed) };
|
|
126
170
|
} catch {
|
|
127
171
|
return defaultState();
|
|
128
172
|
}
|
|
@@ -239,6 +283,37 @@ function auditPayload(rec) {
|
|
|
239
283
|
return JSON.stringify(out);
|
|
240
284
|
}
|
|
241
285
|
|
|
286
|
+
// ---- 审计链哈希模式 ----
|
|
287
|
+
//
|
|
288
|
+
// 裸 SHA-256 哈希链能防的是「**意外**损坏」(截断、位翻转、误删),
|
|
289
|
+
// **防不了有意篡改**:攻击者能读文件,就能重算整条链。
|
|
290
|
+
//
|
|
291
|
+
// 因此提供两种模式:
|
|
292
|
+
// · hmac —— 设置了 CARLOS_FLOW_AUDIT_KEY 时使用带密钥的 HMAC-SHA256。
|
|
293
|
+
// 攻击者没有密钥 → 重算不出正确 hash → 篡改必被发现。
|
|
294
|
+
// · plain —— 未设置密钥时的降级模式(裸 SHA-256),**在 verify 结果里
|
|
295
|
+
// 显式标注 mode**,让调用方知道自己拿到的是哪种保证。
|
|
296
|
+
//
|
|
297
|
+
// 不做「默认启用 HMAC」:没有密钥就签不了名,用户第一次用就会报错。
|
|
298
|
+
// 也不做「假装 HMAC」:plain 模式必须诚实地说自己只是弱保证。
|
|
299
|
+
const AUDIT_KEY = (() => {
|
|
300
|
+
const k = process.env.CARLOS_FLOW_AUDIT_KEY;
|
|
301
|
+
return typeof k === "string" && k.length >= 16 ? k : null;
|
|
302
|
+
})();
|
|
303
|
+
|
|
304
|
+
export function auditHashMode() {
|
|
305
|
+
return AUDIT_KEY ? "hmac" : "plain";
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
// 计算一条记录的 hash(写入与校验必须用同一套函数,否则永远对不上)
|
|
309
|
+
function computeAuditHash(rec, prev) {
|
|
310
|
+
const payload = rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev;
|
|
311
|
+
if (AUDIT_KEY) {
|
|
312
|
+
return createHmac("sha256", AUDIT_KEY).update(payload).digest("hex");
|
|
313
|
+
}
|
|
314
|
+
return createHash("sha256").update(payload).digest("hex");
|
|
315
|
+
}
|
|
316
|
+
|
|
242
317
|
// 追加审计行;永不抛错,失败仅写 stderr;返回记录对象
|
|
243
318
|
export function audit(type, sid, fields = {}) {
|
|
244
319
|
const rec = {
|
|
@@ -253,9 +328,7 @@ export function audit(type, sid, fields = {}) {
|
|
|
253
328
|
// 前驱 hash 取自目标文件尾部 → 与进程数无关,切换状态目录也不会断链
|
|
254
329
|
const prev = lastHashOf(file);
|
|
255
330
|
rec.prevHash = prev;
|
|
256
|
-
rec.hash =
|
|
257
|
-
.update(rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev)
|
|
258
|
-
.digest("hex");
|
|
331
|
+
rec.hash = computeAuditHash(rec, prev);
|
|
259
332
|
// 单次 appendFileSync:O_APPEND 语义,多进程并发写不会互相截断
|
|
260
333
|
fs.appendFileSync(file, JSON.stringify(rec) + "\n", "utf8");
|
|
261
334
|
} catch (e) {
|
|
@@ -269,12 +342,15 @@ export function audit(type, sid, fields = {}) {
|
|
|
269
342
|
// 校验审计链完整性(可选:需完整文件,不能只看尾部)
|
|
270
343
|
export function verifyAuditChain(opts = {}) {
|
|
271
344
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|
|
272
|
-
|
|
345
|
+
// ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效:
|
|
346
|
+
// 传 date='2020-01-01' 读的仍是**今天**的文件,调用方以为在查历史、
|
|
347
|
+
// 实际拿到今天的数据(错而不报,最难发现)。
|
|
348
|
+
const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
|
|
273
349
|
let raw = "";
|
|
274
350
|
try {
|
|
275
351
|
raw = fs.readFileSync(file, "utf8");
|
|
276
352
|
} catch {
|
|
277
|
-
return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file };
|
|
353
|
+
return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file, mode: auditHashMode() };
|
|
278
354
|
}
|
|
279
355
|
let prev = "0".repeat(64);
|
|
280
356
|
let total = 0;
|
|
@@ -292,27 +368,35 @@ export function verifyAuditChain(opts = {}) {
|
|
|
292
368
|
}
|
|
293
369
|
total++;
|
|
294
370
|
if (typeof r.hash !== "string") {
|
|
371
|
+
// 旧格式记录(无 hash)→ 计入 legacy 计数,但**不重置链起点**。
|
|
372
|
+
//
|
|
373
|
+
// 早先这里写的是 prev = "0".repeat(64),于是**一条**旧记录就会让
|
|
374
|
+
// 它之后所有记录的 prevHash 全部对不上 → 全判 broken。
|
|
375
|
+
// 后果:v2.5 升级上来的用户,审计链校验会长期报红,
|
|
376
|
+
// 而 README 把「可验证审计链」列为核心能力 —— 用户会以为自己的
|
|
377
|
+
// 审计记录被篡改了。**漏报比误报可接受,误报更伤信任。**
|
|
295
378
|
legacy++;
|
|
296
|
-
prev = "0".repeat(64);
|
|
297
379
|
continue;
|
|
298
380
|
}
|
|
299
|
-
const expect =
|
|
300
|
-
.update(r.ts + r.type + r.sessionID + auditPayload(r) + prev)
|
|
301
|
-
.digest("hex");
|
|
381
|
+
const expect = computeAuditHash(r, prev);
|
|
302
382
|
if (expect !== r.hash || r.prevHash !== prev) {
|
|
303
383
|
broken++;
|
|
304
384
|
if (brokenAt.length < 10) brokenAt.push({ ts: r.ts, type: r.type, kind: r.kind });
|
|
305
385
|
}
|
|
306
386
|
prev = r.hash;
|
|
307
387
|
}
|
|
308
|
-
|
|
388
|
+
// mode 字段说明本次校验的**保证强度**:
|
|
389
|
+
// hmac → 带密钥(CARLOS_FLOW_AUDIT_KEY),能发现有意篡改
|
|
390
|
+
// plain → 裸 SHA-256,只能发现意外损坏(攻击者能重算整条链)
|
|
391
|
+
return { ok: broken === 0, total, broken, legacy, brokenAt, file, mode: auditHashMode() };
|
|
309
392
|
}
|
|
310
393
|
|
|
311
394
|
export function readAudit(opts = {}) {
|
|
312
395
|
const { sessionId, type, limit } = opts;
|
|
313
396
|
const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
|
|
314
397
|
try {
|
|
315
|
-
|
|
398
|
+
// ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效。
|
|
399
|
+
const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
|
|
316
400
|
const raw = fs.readFileSync(file, "utf8");
|
|
317
401
|
const out = [];
|
|
318
402
|
for (const line of raw.split("\n")) {
|