@sleep2agi/commhub-server 0.9.0-preview.236 → 0.9.0-preview.238
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/package.json +1 -1
- package/src/health-redaction.test.ts +79 -0
- package/src/hub-catalog-read-http.test.ts +16 -0
- package/src/hub-provider-config.ts +13 -2
- package/src/server.ts +28 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sleep2agi/commhub-server",
|
|
3
|
-
"version": "0.9.0-preview.
|
|
3
|
+
"version": "0.9.0-preview.238",
|
|
4
4
|
"description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.ts",
|
|
@@ -852,6 +852,64 @@ describe("#473 anonymous /health — watchdog contract intact, no topology leak"
|
|
|
852
852
|
expect(HEALTH_FIELD_META.served_at.frozen_at_boot).toBeUndefined();
|
|
853
853
|
});
|
|
854
854
|
|
|
855
|
+
// 2026-10-31 —— **分类不决定「变不变」,还缺「窗口」这个参数**(外部复核 (e):
|
|
856
|
+
// 「`startedAt` 属 instance,却会在 failover 时变,正是你自己那张表的反例;
|
|
857
|
+
// 处理分三态 pinned / excluded / allowed,而不是混进白名单」)。
|
|
858
|
+
//
|
|
859
|
+
// 本仓的 `frozen_at_boot: true` 到此为止只是一条**声明**:没有任何断言把它和
|
|
860
|
+
// 「同一个进程在窗口内读两次,这个值不变」对上。声明与行为之间没有桥,
|
|
861
|
+
// 于是分类错了只会被下一个人读出来,不会被测试读出来。
|
|
862
|
+
//
|
|
863
|
+
// 判据(三态在这里的落法):
|
|
864
|
+
// pinned = frozen_at_boot:true ⇒ 窗口内必须**逐字节相同**,变了就红
|
|
865
|
+
// allowed = 没打 frozen 标 ⇒ 变不变都可以,本测试不管
|
|
866
|
+
// excluded = 会变且不该被 pinned ⇒ 必须存在并在正向对照里出现(见下)
|
|
867
|
+
// 窗口显式:WINDOW_MS 写在断言里,而不是「两次读一下大概就行」。
|
|
868
|
+
test("frozen_at_boot fields really do not change within a declared window", async () => {
|
|
869
|
+
const { HEALTH_FIELD_META } = await import("./server.js");
|
|
870
|
+
const WINDOW_MS = 1200;
|
|
871
|
+
expect(WINDOW_MS).toBeGreaterThan(0); // 窗口为 0 的「没变」不构成读数
|
|
872
|
+
|
|
873
|
+
const a = await (await fetch(`${BASE}/health`)).json() as Record<string, unknown>;
|
|
874
|
+
await new Promise((r) => setTimeout(r, WINDOW_MS));
|
|
875
|
+
const b = await (await fetch(`${BASE}/health`)).json() as Record<string, unknown>;
|
|
876
|
+
|
|
877
|
+
// 每一个 pinned 字段还必须**声明窗口**:不写窗口的「不变」无法被证伪。
|
|
878
|
+
// 三态(外部复核 (e)):pinned = 有窗口且窗口内必须不变;allowed = 没打标;
|
|
879
|
+
// excluded = 会变且不该被打成 pinned —— 它必须存在,否则「都 pinned」就没有反例。
|
|
880
|
+
const pinnedAll = Object.entries(HEALTH_FIELD_META).filter(([, m]) => m.frozen_at_boot === true);
|
|
881
|
+
const noWindow = pinnedAll.filter(([, m]) => !m.stable_within).map(([k]) => k);
|
|
882
|
+
expect(noWindow).toEqual([]); // 声明了 pinned 就必须声明窗口
|
|
883
|
+
const windows = new Set(pinnedAll.map(([, m]) => m.stable_within));
|
|
884
|
+
for (const w of windows) expect(["request", "process", "deploy"]).toContain(w as string);
|
|
885
|
+
|
|
886
|
+
const pinned = pinnedAll
|
|
887
|
+
.map(([k]) => k)
|
|
888
|
+
.filter((k) => k in a && k in b);
|
|
889
|
+
// 分母:匿名投影里至少要能看见 1 个 pinned 字段,否则这条测试是真空真
|
|
890
|
+
expect(pinned.length).toBeGreaterThan(0);
|
|
891
|
+
|
|
892
|
+
const moved = pinned.filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
|
|
893
|
+
expect(moved).toEqual([]); // 声明是 pinned,就必须在窗口内真的不动
|
|
894
|
+
|
|
895
|
+
// ⚠️ 这条检查的**弱点必须写出来**(否则它会被读成比实际更强的东西):
|
|
896
|
+
// 一个值**本来就在这个窗口里不变**的字段,即使被错误地标成 pinned,也照样通过。
|
|
897
|
+
// 实测 witness:把 `sessions_count` 标成 `frozen_at_boot + stable_within:"process"`,
|
|
898
|
+
// 测试**仍然绿** —— 因为空测试库里它恒为 0。
|
|
899
|
+
// ⇒ 这条断言真正守住的是「标了 pinned 的字段在窗口内不许变」,
|
|
900
|
+
// 它**不能**守住「pinned 打得对」。后者只有两种办法:
|
|
901
|
+
// ① 造一个真会变的场景(连接数变化 / 重启 / failover)再读两次;
|
|
902
|
+
// ② 用第二个观测者(另一个实例、另一台机器),而不是对同一实例再采样一次。
|
|
903
|
+
// 今天本仓两样都没有 ⇒ 这一格只能到「窗口声明 + 窗口内不变」为止。
|
|
904
|
+
//
|
|
905
|
+
// 正向对照:窗口内必须**有东西会变**,否则「都没变」可能只是「两次读的是同一份缓存」。
|
|
906
|
+
// 这不是洁癖:一个恒定的响应体可以让上面那条永远绿。
|
|
907
|
+
const changed = Object.keys(a).filter((k) => k in b && JSON.stringify(a[k]) !== JSON.stringify(b[k]));
|
|
908
|
+
expect(changed.length).toBeGreaterThan(0);
|
|
909
|
+
// 且变化必须**不含**任何 pinned 字段(与上面互为镜像:一条说“没变”,一条说“别的在变”)
|
|
910
|
+
expect(changed.filter((k) => pinned.includes(k))).toEqual([]);
|
|
911
|
+
});
|
|
912
|
+
|
|
855
913
|
// 2026-10-31 —— credential 的「可对账性」是**字段取值**,不是注释里的辩论。
|
|
856
914
|
test("joinability decides anonymity, not the reader's interpretation", async () => {
|
|
857
915
|
const { HEALTH_FIELD_META, mayBePublic } = await import("./server.js");
|
|
@@ -1206,6 +1264,27 @@ describe("#473 anonymous /health — watchdog contract intact, no topology leak"
|
|
|
1206
1264
|
expect(forbidden).toEqual([]);
|
|
1207
1265
|
});
|
|
1208
1266
|
|
|
1267
|
+
// 2026-10-31 —— **「谁写的」比「谁先谁后」更抗重构**(外部复核:头集合当主判据)。
|
|
1268
|
+
// 部署前面有 nginx/反代时,客户端拿到的错误页可能不是我们写的。
|
|
1269
|
+
// 判据不是「content-type 是 json」(那要求每个客户端都记得先看),
|
|
1270
|
+
// 而是一个**静态**产出者标记:有它 ⇒ 这段字节出自 hub;没有 ⇒ 出自它前面的某一层。
|
|
1271
|
+
// 必须是静态值:一旦它随进程/版本变化,它就变成了指纹(与 version_role 那条相冲突)。
|
|
1272
|
+
test("every hub response carries a constant producer marker (so a proxy page is distinguishable)", async () => {
|
|
1273
|
+
const paths = ["/health", "/api/definitely-not-a-route", "/"];
|
|
1274
|
+
const seen: (string | null)[] = [];
|
|
1275
|
+
for (const path of paths) {
|
|
1276
|
+
const res = await fetch(`${BASE}${path}`);
|
|
1277
|
+
seen.push(res.headers.get("X-CommHub"));
|
|
1278
|
+
}
|
|
1279
|
+
// 三个不同出口(健康检查 / 404 / 帮助页)都必须带,且值相同
|
|
1280
|
+
expect(seen).toEqual(["hub", "hub", "hub"]);
|
|
1281
|
+
// 静态性:同一路径两次读到的值必须一致(否则它是指纹,不是产出者标记)
|
|
1282
|
+
const again = await fetch(`${BASE}/health`);
|
|
1283
|
+
expect(again.headers.get("X-CommHub")).toBe("hub");
|
|
1284
|
+
// 与「匿名无指纹」那条不冲突:这个头不含 git/commit/build 类词
|
|
1285
|
+
expect(/git|commit|build[-_]?(sha|id)?/.test("x-commhub")).toBe(false);
|
|
1286
|
+
});
|
|
1287
|
+
|
|
1209
1288
|
test("no dead entries: every allow-listed key is actually served to anonymous callers", async () => {
|
|
1210
1289
|
const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
|
|
1211
1290
|
const plain = await (await fetch(`${BASE}/health`)).json() as any;
|
|
@@ -480,6 +480,22 @@ describe("GET /api/providers", () => {
|
|
|
480
480
|
// 而语义已经不是你想的那个。」)
|
|
481
481
|
// ⇒ 读点必须落在**路由文件**里(server.ts),否则等于表有了、用法另有其处。
|
|
482
482
|
// 位置:读点必须落在**实现或路由**里(不是只落在注释里)
|
|
483
|
+
// 2026-10-31 —— **兜底不许把「我们的缺陷」说成「客户端的错」**:
|
|
484
|
+
// 表里查不到的码 ⇒ 归因指向了错误的行动方(返回 400 会让客户端去改自己的请求)。
|
|
485
|
+
// 判据同「遍历每个抛点断言它不等于 catch-all」:逐个码断言它映射到**自己那一格**,
|
|
486
|
+
// 再断言未登记的码落 500 而不是 400。
|
|
487
|
+
const { PROVIDER_WRITE_ERROR_CODES: CODES, PROVIDER_WRITE_STATUS: STATUS, providerWriteStatus: statusOf } =
|
|
488
|
+
await import("./hub-provider-config.js");
|
|
489
|
+
const CLOSED = new Set([400, 401, 403, 404, 409, 500, 503]);
|
|
490
|
+
for (const code of CODES) {
|
|
491
|
+
expect(statusOf(code)).toBe(STATUS[code]);
|
|
492
|
+
expect(CLOSED.has(statusOf(code))).toBe(true);
|
|
493
|
+
}
|
|
494
|
+
// 镜像(must-fire):一个**不在表里**的码必须落到 500,不能落 400
|
|
495
|
+
const bogus = statusOf("definitely_not_a_listed_code" as any);
|
|
496
|
+
expect(bogus).toBe(500);
|
|
497
|
+
expect(bogus).not.toBe(400);
|
|
498
|
+
|
|
483
499
|
const readerFiles = new Set(readers.map((r) => String(r.f).split("/").pop()));
|
|
484
500
|
expect(readerFiles.size).toBeGreaterThan(0);
|
|
485
501
|
expect([...readerFiles].some((f) => f === "server.ts" || f === "hub-provider-config.ts" || f === "requirements.ts")).toBe(true);
|
|
@@ -50,8 +50,19 @@ export const PROVIDER_WRITE_STATUS: Record<ProviderWriteErrorCode, number> = {
|
|
|
50
50
|
hub_provider_save_failed: 500,
|
|
51
51
|
vault_unavailable: 503,
|
|
52
52
|
};
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
/**
|
|
54
|
+
* 码 → HTTP 状态。
|
|
55
|
+
*
|
|
56
|
+
* 2026-10-31 —— 参数类型从 `string` 收紧到 `ProviderWriteErrorCode`:
|
|
57
|
+
* 之前签名收 `string`,于是「表里加码、忘了加状态」在**调用点**不会被类型拦住
|
|
58
|
+
* (编译器只看见一个字符串)。而 `Record<ProviderWriteErrorCode, number>` 只在
|
|
59
|
+
* 「用类型化的键去索引」时才保证穷尽 —— 签名放宽就等于把穷尽性丢了。
|
|
60
|
+
*
|
|
61
|
+
* 兜底也改了方向:`?? 400` 会告诉客户端「你的请求不对」,而表里查不到的码是**我们**的缺陷
|
|
62
|
+
* ⇒ 归因指向了错误的行动方。现在兜底返回 500(服务端错误),并让测试断言它不被 400 顶替。
|
|
63
|
+
*/
|
|
64
|
+
export function providerWriteStatus(code: ProviderWriteErrorCode): number {
|
|
65
|
+
return PROVIDER_WRITE_STATUS[code] ?? 500;
|
|
55
66
|
}
|
|
56
67
|
const idValid = (id: unknown) => typeof id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(id);
|
|
57
68
|
function auth(h: Human, write: boolean, owner = false) {
|
package/src/server.ts
CHANGED
|
@@ -1173,6 +1173,20 @@ export interface HealthFieldMeta {
|
|
|
1173
1173
|
* 只写「什么算」的分类,对形似字段没有抵抗力。
|
|
1174
1174
|
*/
|
|
1175
1175
|
frozen_at_boot?: true;
|
|
1176
|
+
/**
|
|
1177
|
+
* 2026-10-31 —— **分类必须带窗口**(外部复核 (e):「六分类不决定『变不变』,
|
|
1178
|
+
* 还缺『窗口』这一参数;`startedAt` 属 instance 却会在 failover 时变,
|
|
1179
|
+
* 处理应分三态 pinned / excluded / allowed,而不是混进白名单」)。
|
|
1180
|
+
*
|
|
1181
|
+
* 「这个字段是常量」不是一句可以单独成立的话——它总得回答「在多长的时间里」。
|
|
1182
|
+
* 本仓的取值:
|
|
1183
|
+
* request —— 同一次请求内不变(例如聚合出来的标签)
|
|
1184
|
+
* process —— 同一个进程内不变(startedAt / pid / boot_id / git_commit);
|
|
1185
|
+
* **跨进程会变**(重启 / failover / 换制品),所以它不能用来做实例身份
|
|
1186
|
+
* deploy —— 跨进程也不变(例如 version_source 的取值域)
|
|
1187
|
+
* ⇒ 一个分类不写窗口,就无法被证伪:读一次相同与读一年相同,在断言上同形。
|
|
1188
|
+
*/
|
|
1189
|
+
stable_within?: "request" | "process" | "deploy";
|
|
1176
1190
|
/** 为什么把它放这一档(只在有争议的字段上写) */
|
|
1177
1191
|
why?: string;
|
|
1178
1192
|
}
|
|
@@ -1212,7 +1226,7 @@ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
|
|
|
1212
1226
|
// 前提必须成立:uptime 来自 process.uptime()(单调),**不是** Date.now()-startedAt(同源就没判别力)。
|
|
1213
1227
|
why: "进程已运行秒数(process.uptime(),单调时钟)。与 served_at/startedAt 不同源:墙钟被 NTP 冻结时它仍在走 ⇒ 可判「是钟停了还是进程停了」",
|
|
1214
1228
|
},
|
|
1215
|
-
startedAt: { frozen_at_boot: true, class: "gauge", granularity: "instant", why: "窗口起点;去掉它,event_loop 里的 stall 计数就没有分母时刻戳" },
|
|
1229
|
+
startedAt: { frozen_at_boot: true, stable_within: "process", class: "gauge", granularity: "instant", why: "窗口起点;去掉它,event_loop 里的 stall 计数就没有分母时刻戳" },
|
|
1216
1230
|
sessions_count: { class: "gauge", granularity: "level" },
|
|
1217
1231
|
sse_connections: { class: "gauge", granularity: "level" },
|
|
1218
1232
|
mcp_inflight: { class: "gauge", granularity: "level" },
|
|
@@ -1304,7 +1318,7 @@ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
|
|
|
1304
1318
|
|
|
1305
1319
|
// ── landmark:精确位置/身份 ──────────────────────────────────────────
|
|
1306
1320
|
git_commit: {
|
|
1307
|
-
frozen_at_boot: true,
|
|
1321
|
+
frozen_at_boot: true, stable_within: "deploy",
|
|
1308
1322
|
class: "landmark",
|
|
1309
1323
|
why: "精确告诉外部这是哪一版代码(本仓公开)⇒ 等于指路到已知问题清单",
|
|
1310
1324
|
identity_class: "artifact",
|
|
@@ -1328,10 +1342,10 @@ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
|
|
|
1328
1342
|
},
|
|
1329
1343
|
// 逐会话明细 = 拓扑 ⇒ 只需「有几个」,不需要「哪几个」(与 #473 的审计同一条)
|
|
1330
1344
|
sse_sessions: { class: "landmark", why: "按键列出连接 = 网络 id + 别名,正是 #473 那个泄露面" },
|
|
1331
|
-
pid: { frozen_at_boot: true, class: "landmark" },
|
|
1332
|
-
boot_id: { frozen_at_boot: true, class: "landmark" },
|
|
1333
|
-
proc_start_ticks: { frozen_at_boot: true, class: "landmark" },
|
|
1334
|
-
kernel_started_at: { frozen_at_boot: true, class: "landmark", why: "内核口径的精确启动时刻 ⇒ 可与外部日志对账" },
|
|
1345
|
+
pid: { frozen_at_boot: true, stable_within: "process", class: "landmark" },
|
|
1346
|
+
boot_id: { frozen_at_boot: true, stable_within: "process", class: "landmark" },
|
|
1347
|
+
proc_start_ticks: { frozen_at_boot: true, stable_within: "process", class: "landmark" },
|
|
1348
|
+
kernel_started_at: { frozen_at_boot: true, stable_within: "process", class: "landmark", why: "内核口径的精确启动时刻 ⇒ 可与外部日志对账" },
|
|
1335
1349
|
kernel_started_at_note: { class: "landmark" },
|
|
1336
1350
|
|
|
1337
1351
|
// ── credential ─────────────────────────────────────────────────────
|
|
@@ -1714,6 +1728,14 @@ function withCors(req: Request, res: Response): Response {
|
|
|
1714
1728
|
for (const [k, v] of Object.entries(headers)) {
|
|
1715
1729
|
res.headers.set(k, v);
|
|
1716
1730
|
}
|
|
1731
|
+
// 2026-10-31 —— **「谁写的」比「谁先谁后」更抗重构**(外部复核:
|
|
1732
|
+
// 「头集合作第二主判据:它判『谁写的』,不判『谁先谁后』」)。
|
|
1733
|
+
// 部署在前面有 nginx / 任何反代时,客户端拿到的错误页可能不是我们写的:
|
|
1734
|
+
// 代理的 502/504 页面是 HTML,而我们的错误是 JSON —— 但只靠 content-type 判,
|
|
1735
|
+
// 等于要求每个客户端都记得先看 content-type。
|
|
1736
|
+
// ⇒ 加一个**静态**的产出者标记:同一个值永远不变,所以它不构成指纹
|
|
1737
|
+
// (与 `version_role` / `git_commit` 那类「回答我站在哪一层」的头不是一回事)。
|
|
1738
|
+
res.headers.set("X-CommHub", "hub");
|
|
1717
1739
|
return res;
|
|
1718
1740
|
}
|
|
1719
1741
|
|