@sleep2agi/commhub-server 0.9.0-preview.23 → 0.9.0-preview.231

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.
Files changed (408) hide show
  1. package/README.md +129 -9
  2. package/bin/commhub.ts +93 -9
  3. package/package.json +7 -7
  4. package/src/ack-create-request-transport.test.ts +182 -0
  5. package/src/ack-create-request.test.ts +50 -7
  6. package/src/admin-delete-network-http.test.ts +228 -0
  7. package/src/admin-networks-http.test.ts +88 -0
  8. package/src/adoption-candidates-http.test.ts +137 -0
  9. package/src/adoption-candidates.ts +158 -0
  10. package/src/agent-access-batch.test.ts +210 -0
  11. package/src/agent-access.ts +487 -0
  12. package/src/agent-acl-groups-http.test.ts +247 -0
  13. package/src/agent-acl-http.test.ts +659 -0
  14. package/src/agent-acl-slice3-http.test.ts +654 -0
  15. package/src/agent-department-http.test.ts +215 -0
  16. package/src/agent-groups-perf.test.ts +223 -0
  17. package/src/agent-notice.ts +48 -0
  18. package/src/agent-team-whoami-http.test.ts +98 -0
  19. package/src/agent-teams-http.test.ts +330 -0
  20. package/src/agent-teams.ts +244 -0
  21. package/src/alias-baseline-2571.test.ts +162 -0
  22. package/src/alias-baseline.ts +113 -0
  23. package/src/alias-filter.test.ts +72 -0
  24. package/src/alias-filter.ts +42 -0
  25. package/src/api-host-supervisors-can-create-nodes.test.ts +350 -0
  26. package/src/api-host-supervisors-fallback.test.ts +6 -7
  27. package/src/api-host-supervisors-runtime-readiness.test.ts +195 -0
  28. package/src/api-nodes-shape.test.ts +95 -4
  29. package/src/auth-password-change-cli-tokens-http.test.ts +423 -0
  30. package/src/auth-sessions-http.test.ts +250 -0
  31. package/src/auth-validate.test.ts +5 -1
  32. package/src/auth-weak-password-login.test.ts +176 -0
  33. package/src/auth.ts +609 -51
  34. package/src/avatar-validate.test.ts +52 -2
  35. package/src/avatar-validate.ts +35 -1
  36. package/src/backfill-node-ids-2664.test.ts +128 -0
  37. package/src/binding-generation-http.test.ts +121 -0
  38. package/src/blocked-exit-on-reply.test.ts +122 -0
  39. package/src/broadcast-fanout-2721.test.ts +149 -0
  40. package/src/broadcast-fanout.ts +117 -0
  41. package/src/chain-attempt-dedup.test.ts +447 -0
  42. package/src/clip.test.ts +36 -0
  43. package/src/clip.ts +46 -0
  44. package/src/clone-node.test.ts +248 -0
  45. package/src/clone-node.ts +289 -0
  46. package/src/codex-config-flags.ts +77 -0
  47. package/src/codex-fork-contract.ts +23 -0
  48. package/src/codex-fork-migration.test.ts +38 -0
  49. package/src/commhub-bin-args.test.ts +85 -0
  50. package/src/config-apply-validate.test.ts +188 -1
  51. package/src/config-apply-validate.ts +222 -3
  52. package/src/cors-origins.test.ts +73 -0
  53. package/src/create-node-blocked-gate.test.ts +356 -0
  54. package/src/create-node-network-id.test.ts +91 -0
  55. package/src/create-node-tool-schema.test.ts +49 -0
  56. package/src/create-node-unicode-name.test.ts +120 -0
  57. package/src/create-node-validate.test.ts +199 -7
  58. package/src/create-node-validate.ts +232 -15
  59. package/src/create-node-workdir.test.ts +289 -0
  60. package/src/create-node.ts +88 -23
  61. package/src/daemon-provider-snapshots.test.ts +421 -0
  62. package/src/daemon-provider-snapshots.ts +327 -0
  63. package/src/daemon-token-owner-http.test.ts +236 -0
  64. package/src/dashboard-slash-routing-http.test.ts +109 -0
  65. package/src/db-adapter-guard.test.ts +148 -0
  66. package/src/db-adapter-translate.test.ts +128 -0
  67. package/src/db-adapter.ts +377 -91
  68. package/src/db-timestamp.test.ts +38 -0
  69. package/src/db-timestamp.ts +15 -0
  70. package/src/db.ts +1264 -153
  71. package/src/delivered-without-push.test.ts +140 -0
  72. package/src/department-groups-http.test.ts +209 -0
  73. package/src/department-groups-sync-http.test.ts +328 -0
  74. package/src/department-groups.ts +434 -0
  75. package/src/department-heads-http.test.ts +350 -0
  76. package/src/department-heads.ts +226 -0
  77. package/src/departments-agent-count.test.ts +132 -0
  78. package/src/departments-http.test.ts +185 -0
  79. package/src/departments-mcp.test.ts +128 -0
  80. package/src/departments.ts +318 -0
  81. package/src/desktop-message-seam.test.ts +150 -0
  82. package/src/desktop-message.test.ts +368 -0
  83. package/src/dm-file-scope-http.test.ts +178 -0
  84. package/src/empty-node-sweeper.test.ts +104 -0
  85. package/src/empty-node-sweeper.ts +88 -0
  86. package/src/env-transport-gate-http.test.ts +240 -0
  87. package/src/env-transport-gate.ts +80 -0
  88. package/src/env-transport-policy.ts +56 -0
  89. package/src/etag-of.test.ts +57 -0
  90. package/src/event-loop-lag.test.ts +180 -0
  91. package/src/event-loop-lag.ts +201 -0
  92. package/src/ext-token-shared.test.ts +60 -0
  93. package/src/ext-validation-regression.test.ts +131 -0
  94. package/src/external-schedule-edits-http.test.ts +321 -0
  95. package/src/external-schedule-edits-timestamps.test.ts +64 -0
  96. package/src/external-schedule-edits.ts +327 -0
  97. package/src/file-download-authz-dev-open.test.ts +1 -1
  98. package/src/file-download-authz.test.ts +73 -18
  99. package/src/file-download-date-bucket.test.ts +436 -0
  100. package/src/file-network-scope-dev-open.test.ts +97 -0
  101. package/src/file-network-scope.test.ts +732 -0
  102. package/src/group-membership-events-http.test.ts +264 -0
  103. package/src/group-messages-http.test.ts +482 -0
  104. package/src/group-messages.ts +297 -0
  105. package/src/health-anon-readers.ts +60 -0
  106. package/src/health-host-disk-2756.test.ts +71 -0
  107. package/src/health-redaction.test.ts +1740 -2
  108. package/src/host-supervisor-identity-http.test.ts +152 -0
  109. package/src/host-supervisor-identity.ts +92 -0
  110. package/src/host-supervisors-daemon-version.test.ts +137 -0
  111. package/src/http-gzip.test.ts +94 -0
  112. package/src/http-gzip.ts +112 -0
  113. package/src/hub-catalog-read-http.test.ts +437 -0
  114. package/src/hub-provider-config.test.ts +156 -0
  115. package/src/hub-provider-config.ts +170 -0
  116. package/src/hub-timestamp.test.ts +38 -0
  117. package/src/hub-timestamp.ts +27 -0
  118. package/src/human-dm.ts +215 -0
  119. package/src/human-inbox.ts +42 -0
  120. package/src/inbox-caller.ts +49 -0
  121. package/src/inbox-count-sse.test.ts +310 -0
  122. package/src/inbox-count.ts +29 -0
  123. package/src/index.ts +6 -2
  124. package/src/license-state.test.ts +56 -0
  125. package/src/license-state.ts +48 -0
  126. package/src/list-host-supervisors.test.ts +15 -4
  127. package/src/mcp-context-cost-http.test.ts +127 -0
  128. package/src/mcp-inflight.test.ts +92 -0
  129. package/src/mcp-inflight.ts +38 -0
  130. package/src/mcp-projects-events-http.test.ts +165 -0
  131. package/src/mcp-route-label-http.test.ts +120 -0
  132. package/src/mcp-write-network-resolution.test.ts +435 -0
  133. package/src/member-audit-network-id-http.test.ts +93 -0
  134. package/src/member-presence-http.test.ts +210 -0
  135. package/src/messages-ack-by-agent-http.test.ts +142 -0
  136. package/src/migrate-sqlite-to-pg.test.ts +47 -0
  137. package/src/migrate-sqlite-to-pg.ts +263 -0
  138. package/src/model-auth-notify-http.test.ts +181 -0
  139. package/src/model-auth-notify.ts +116 -0
  140. package/src/network-name-http.test.ts +75 -0
  141. package/src/network-rules-http.test.ts +169 -0
  142. package/src/network-rules.ts +129 -0
  143. package/src/network-scope.ts +276 -0
  144. package/src/network-token-membership-http.test.ts +139 -0
  145. package/src/node-alias-control.ts +12 -0
  146. package/src/node-attrs.test.ts +47 -2
  147. package/src/node-caller-identity-http.test.ts +1091 -0
  148. package/src/node-create-request-status-http.test.ts +105 -0
  149. package/src/node-daemon-bindings.test.ts +132 -0
  150. package/src/node-daemon-bindings.ts +135 -0
  151. package/src/node-failure-alert.test.ts +150 -0
  152. package/src/node-failure-alert.ts +177 -0
  153. package/src/node-files-transport.test.ts +344 -0
  154. package/src/node-health-codex-login.test.ts +120 -0
  155. package/src/node-health-dispatch-http.test.ts +335 -0
  156. package/src/node-health-guard.ts +121 -0
  157. package/src/node-health-passthrough.test.ts +115 -0
  158. package/src/node-health-store.ts +101 -0
  159. package/src/node-id-alias.test.ts +190 -0
  160. package/src/node-identity-conflict-http.test.ts +269 -0
  161. package/src/node-identity-conflict.ts +142 -0
  162. package/src/node-identity-mismatch.test.ts +74 -0
  163. package/src/node-in-flight-tasks.ts +31 -0
  164. package/src/node-lifecycle-controllable.test.ts +64 -0
  165. package/src/node-lifecycle-controllable.ts +53 -0
  166. package/src/node-lifecycle-read-http.test.ts +250 -0
  167. package/src/node-lifecycle-read.ts +124 -0
  168. package/src/node-logs-transport.test.ts +263 -0
  169. package/src/node-peer-allowlist.test.ts +114 -0
  170. package/src/node-permissions-http.test.ts +728 -0
  171. package/src/node-permissions.ts +494 -0
  172. package/src/node-request-retention.test.ts +281 -0
  173. package/src/node-request-retention.ts +120 -0
  174. package/src/node-secret-rest-http.test.ts +190 -0
  175. package/src/node-serviceability.test.ts +86 -0
  176. package/src/node-serviceability.ts +124 -0
  177. package/src/node-session-control-http.test.ts +310 -0
  178. package/src/node-session-control.ts +258 -0
  179. package/src/node-skills-transport.test.ts +212 -0
  180. package/src/node-token-identity.ts +35 -0
  181. package/src/node-token-ownership.ts +51 -0
  182. package/src/node-token-privilege-http.test.ts +158 -0
  183. package/src/not-found-api-http.test.ts +67 -0
  184. package/src/observer-avatar-http.test.ts +102 -9
  185. package/src/observer-push.test.ts +76 -0
  186. package/src/opencode-catalog-report-http.test.ts +139 -0
  187. package/src/opencode-v2-catalog.test.ts +268 -0
  188. package/src/opencode-v2-catalog.ts +356 -0
  189. package/src/package-version-consistency.test.ts +25 -0
  190. package/src/parent-source-marker.test.ts +50 -0
  191. package/src/password-network-tokens.ts +25 -0
  192. package/src/peer-reply-atomic.test.ts +457 -0
  193. package/src/peer-reply-capability.test.ts +70 -0
  194. package/src/pg-worker.ts +87 -0
  195. package/src/poll-pacing.test.ts +74 -0
  196. package/src/poll-pacing.ts +123 -0
  197. package/src/project-dir-warn-clear-http.test.ts +132 -0
  198. package/src/project-viewer-can-http.test.ts +116 -0
  199. package/src/push.test.ts +20 -10
  200. package/src/push.ts +382 -9
  201. package/src/redact-tokens.test.ts +86 -0
  202. package/src/redact-tokens.ts +43 -0
  203. package/src/rejection-counters.test.ts +72 -0
  204. package/src/rejection-counters.ts +173 -0
  205. package/src/rename.ts +38 -10
  206. package/src/reply-target-derivation.test.ts +96 -0
  207. package/src/report-status-handover-capabilities-http.test.ts +124 -0
  208. package/src/report-status-host-schema.test.ts +235 -0
  209. package/src/report-status-resume-id-handover.test.ts +184 -0
  210. package/src/report-status-secret-keys.test.ts +140 -0
  211. package/src/require-explicit-test-db.ts +9 -0
  212. package/src/requirement-due-reminders-http.test.ts +620 -0
  213. package/src/requirement-due-reminders.ts +416 -0
  214. package/src/requirement-events-http.test.ts +295 -0
  215. package/src/requirement-events.test.ts +45 -0
  216. package/src/requirement-events.ts +144 -0
  217. package/src/requirement-notify.ts +165 -0
  218. package/src/requirement-participant-notify-http.test.ts +309 -0
  219. package/src/requirement-tag-ops-http.test.ts +443 -0
  220. package/src/requirement-tag-tree-http.test.ts +275 -0
  221. package/src/requirement-tag-tree.ts +127 -0
  222. package/src/requirement-tags.ts +102 -0
  223. package/src/requirements-abandoned-http.test.ts +236 -0
  224. package/src/requirements-comment-http.test.ts +167 -0
  225. package/src/requirements-completed-at-migration.test.ts +70 -0
  226. package/src/requirements-errors-mcp-http.test.ts +164 -0
  227. package/src/requirements-errors.ts +158 -0
  228. package/src/requirements-etag-http.test.ts +91 -0
  229. package/src/requirements-http.test.ts +709 -0
  230. package/src/requirements-last-event-http.test.ts +349 -0
  231. package/src/requirements-list-mcp-slim-http.test.ts +155 -0
  232. package/src/requirements-list-slim-http.test.ts +324 -0
  233. package/src/requirements-mcp.test.ts +163 -0
  234. package/src/requirements-migrate.ts +283 -0
  235. package/src/requirements-owner-strict-mcp-http.test.ts +145 -0
  236. package/src/requirements-people-http.test.ts +114 -0
  237. package/src/requirements-people-mcp-http.test.ts +231 -0
  238. package/src/requirements-people.ts +196 -0
  239. package/src/requirements-priority-lowest.test.ts +114 -0
  240. package/src/requirements-projects-network-echo.test.ts +57 -0
  241. package/src/requirements-projects-parent-http.test.ts +123 -0
  242. package/src/requirements-search-http.test.ts +182 -0
  243. package/src/requirements-search.test.ts +32 -0
  244. package/src/requirements-search.ts +145 -0
  245. package/src/requirements-seq-http.test.ts +193 -0
  246. package/src/requirements-seq-migration.test.ts +63 -0
  247. package/src/requirements-start-date.test.ts +125 -0
  248. package/src/requirements-stats-http.test.ts +357 -0
  249. package/src/requirements-stats.ts +195 -0
  250. package/src/requirements-status-participants-http.test.ts +222 -0
  251. package/src/requirements-upgrade-e2e.test.ts +126 -0
  252. package/src/requirements-upgrade-migration.test.ts +98 -0
  253. package/src/requirements.ts +2064 -0
  254. package/src/resolve-port.test.ts +57 -0
  255. package/src/resolve-port.ts +44 -0
  256. package/src/rest-alias-network-fallback-http.test.ts +123 -0
  257. package/src/rest-alias-network-fallback.test.ts +60 -0
  258. package/src/rest-alias-network-fallback.ts +65 -0
  259. package/src/rest-explicit-columns-http.test.ts +266 -0
  260. package/src/rest-identity.test.ts +130 -0
  261. package/src/rest-identity.ts +141 -0
  262. package/src/rest-projections.ts +72 -0
  263. package/src/rest-read-network-real-chain.test.ts +97 -0
  264. package/src/rest-write-network-resolution.test.ts +133 -0
  265. package/src/restart-readiness-http.test.ts +121 -0
  266. package/src/restricted-files.ts +76 -0
  267. package/src/retention-first-sweep-quiet.test.ts +31 -0
  268. package/src/retention.test.ts +100 -40
  269. package/src/retention.ts +423 -104
  270. package/src/route-callers-http.test.ts +120 -0
  271. package/src/route-timing.test.ts +218 -0
  272. package/src/route-timing.ts +262 -0
  273. package/src/rules-file-duplicate-alias.test.ts +234 -0
  274. package/src/rules-file-session-target.test.ts +207 -0
  275. package/src/rules-file-transport.test.ts +237 -0
  276. package/src/runtime-label.test.ts +22 -0
  277. package/src/runtime-label.ts +21 -0
  278. package/src/runtime-readiness.ts +90 -0
  279. package/src/schedule-agent-mcp-http.test.ts +432 -0
  280. package/src/schedule-agent.ts +252 -0
  281. package/src/schedule-starved.test.ts +92 -0
  282. package/src/schedule-starved.ts +114 -0
  283. package/src/scheduled-backoff-http.test.ts +193 -0
  284. package/src/scheduled-backoff.ts +64 -0
  285. package/src/scheduled-doorbell-nodeless-session.test.ts +134 -0
  286. package/src/scheduled-failure-backoff-2622.test.ts +145 -0
  287. package/src/scheduled-failure-code.test.ts +73 -0
  288. package/src/scheduled-failure-code.ts +105 -0
  289. package/src/scheduled-failures-http.test.ts +279 -0
  290. package/src/scheduled-failures.ts +425 -0
  291. package/src/scheduled-noprogress-backoff-2622.test.ts +163 -0
  292. package/src/scheduled-offline-backoff-probe.test.ts +56 -0
  293. package/src/scheduled-offline.test.ts +131 -0
  294. package/src/scheduled-offline.ts +66 -0
  295. package/src/scheduled-outcome-guidance-http.test.ts +139 -0
  296. package/src/scheduled-outcome-guidance.ts +9 -0
  297. package/src/scheduled-reply-unread-http.test.ts +212 -0
  298. package/src/scheduled-requirement-wake-http.test.ts +279 -0
  299. package/src/scheduled-requirement-wake.ts +125 -0
  300. package/src/scheduled-run-terminal.test.ts +268 -0
  301. package/src/scheduled-skip-blocking-task.test.ts +120 -0
  302. package/src/scheduled-skip-path-backoff-2622.test.ts +98 -0
  303. package/src/scheduled-stuck-http.test.ts +316 -0
  304. package/src/scheduled-stuck-notice-cap.test.ts +80 -0
  305. package/src/scheduled-stuck.ts +219 -0
  306. package/src/scheduled-tasks-http.test.ts +679 -0
  307. package/src/scheduled-tasks.ts +959 -0
  308. package/src/scheduled-work-outcome-http.test.ts +154 -0
  309. package/src/scheduled-work-outcome.ts +50 -0
  310. package/src/scoped-secrets.ts +141 -0
  311. package/src/send-dedup-request-id.test.ts +229 -0
  312. package/src/send-reply-agent-warning.test.ts +38 -38
  313. package/src/send-reply-alias-optional.test.ts +131 -0
  314. package/src/send-reply-attachments.test.ts +458 -0
  315. package/src/send_dedup.test.ts +54 -0
  316. package/src/send_dedup.ts +52 -6
  317. package/src/serve-error.test.ts +73 -0
  318. package/src/serve-error.ts +56 -0
  319. package/src/server.ts +5035 -457
  320. package/src/session-task-on-dispatch.ts +14 -0
  321. package/src/session-token-ownership-http.test.ts +122 -0
  322. package/src/shared/codex-inventory.ts +41 -0
  323. package/src/shared/daemon-provider-login.ts +31 -0
  324. package/src/shared/daemon-provider-snapshot.ts +52 -0
  325. package/src/shared/external-schedule-contract.ts +60 -0
  326. package/src/shared/node-name.test.ts +62 -0
  327. package/src/shared/node-name.ts +161 -0
  328. package/src/shared/probe-host-allowlist-drift.test.ts +45 -0
  329. package/src/shared/provider-application.ts +29 -0
  330. package/src/shared/provider-collection.ts +14 -0
  331. package/src/shared/provider-initialization.ts +8 -0
  332. package/src/shared/reserved-env-drift.test.ts +10 -0
  333. package/src/shared/scoped-secret-contract.ts +5 -0
  334. package/src/shared/task-content-limit-drift.test.ts +28 -0
  335. package/src/shared/task-content-limit.ts +25 -0
  336. package/src/side-thread-command-transport.test.ts +312 -0
  337. package/src/side-thread-command-transport.ts +318 -0
  338. package/src/side-thread-http-integration.test.ts +233 -0
  339. package/src/side-thread-http.ts +504 -0
  340. package/src/side-thread-production.test.ts +72 -0
  341. package/src/side-thread-production.ts +118 -0
  342. package/src/side-thread.test.ts +1067 -0
  343. package/src/side-thread.ts +2499 -0
  344. package/src/skillhub-http.test.ts +142 -0
  345. package/src/sqlite-close-checkpoint.test.ts +78 -0
  346. package/src/start-node.test.ts +264 -0
  347. package/src/status-alias-filter-http.test.ts +106 -0
  348. package/src/status-alias-resolver-http.test.ts +163 -0
  349. package/src/status-alias-resolver.ts +19 -0
  350. package/src/status-node-id-filter-http.test.ts +161 -0
  351. package/src/status-read-cache-http.test.ts +229 -0
  352. package/src/status-read-cache.ts +129 -0
  353. package/src/stop-delete-node.test.ts +567 -1
  354. package/src/task-access-http.test.ts +402 -0
  355. package/src/task-access.ts +420 -0
  356. package/src/task-activity.ts +60 -0
  357. package/src/task-auth-origin-http.test.ts +93 -0
  358. package/src/task-auth-origin.test.ts +24 -0
  359. package/src/task-auth-origin.ts +7 -0
  360. package/src/task-consumption.test.ts +490 -0
  361. package/src/task-diagnostic-http.test.ts +149 -0
  362. package/src/task-diagnostic.test.ts +115 -0
  363. package/src/task-diagnostic.ts +118 -0
  364. package/src/task-expiry-notice-http.test.ts +287 -0
  365. package/src/task-expiry-notice.ts +315 -0
  366. package/src/task-idempotency-mcp.test.ts +142 -0
  367. package/src/task-idempotency.test.ts +76 -0
  368. package/src/task-idempotency.ts +81 -0
  369. package/src/task-late-replies.ts +54 -0
  370. package/src/task-late-reply-http.test.ts +227 -0
  371. package/src/task-lifecycle-watcher-busy.test.ts +114 -0
  372. package/src/task-lifecycle-watcher.test.ts +204 -0
  373. package/src/task-lifecycle-watcher.ts +109 -0
  374. package/src/task-network-resolution-http.test.ts +140 -0
  375. package/src/task-offline-delivery-2668.test.ts +119 -0
  376. package/src/task-offline-delivery.ts +81 -0
  377. package/src/task-orphan-http.test.ts +287 -0
  378. package/src/task-orphan.ts +119 -0
  379. package/src/task-queue-ahead-http.test.ts +309 -0
  380. package/src/task-queue-ahead-scale.test.ts +236 -0
  381. package/src/task-queue-ahead.ts +186 -0
  382. package/src/task-rejection-log-http.test.ts +160 -0
  383. package/src/task-rejection-log.ts +61 -0
  384. package/src/task-sender-http.test.ts +143 -0
  385. package/src/task-stale-open-http.test.ts +292 -0
  386. package/src/task-stale-open.ts +103 -0
  387. package/src/tasks-pagination-http.test.ts +141 -0
  388. package/src/team-rules-status-http.test.ts +90 -0
  389. package/src/team-rules-status.test.ts +59 -0
  390. package/src/team-rules-status.ts +72 -0
  391. package/src/tmux-allowlist.test.ts +48 -0
  392. package/src/tool-audience-http.test.ts +230 -0
  393. package/src/tool-audience.ts +127 -0
  394. package/src/tools-list-json-schema.test.ts +94 -0
  395. package/src/tools.ts +4310 -419
  396. package/src/upload-early-reject-guard.test.ts +155 -0
  397. package/src/uploads-http.test.ts +86 -7
  398. package/src/uploads.ts +103 -6
  399. package/src/user-avatar-http.test.ts +74 -0
  400. package/src/user-avatar-image.ts +160 -0
  401. package/src/user-avatar-migration.test.ts +25 -0
  402. package/src/user-avatar-upload-http.test.ts +348 -0
  403. package/src/user-inbox-by-agent-http.test.ts +161 -0
  404. package/src/user-inbox-netid-notnull.test.ts +122 -0
  405. package/src/user-inbox-read-http.test.ts +223 -0
  406. package/src/user-inbox-schema.test.ts +54 -0
  407. package/src/version-stats.test.ts +66 -0
  408. package/src/version-stats.ts +109 -0
@@ -0,0 +1,180 @@
1
+ // #2614 —— 事件循环停顿监测 + 慢 SQL 日志的单元测试。
2
+ //
3
+ // 这两个东西的价值不在“能测出停顿”,而在**停顿发生时留下可对齐的证据**:
4
+ // 2026-10-26 生产两次 RSS 3.6/4.5 GB 的尖峰,事后只能靠“日志静默几十秒”
5
+ // 手工推断,`/api/stats/routes` 只给出受害者请求(含排队时间)。
6
+ // 所以测试要钉住的是语义:怎么算一次停顿、留什么档、日志阈值怎么生效、关闭后还计数。
7
+
8
+ import { describe, expect, test } from "bun:test";
9
+ import {
10
+ eventLoopStats,
11
+ noteRequestServed,
12
+ recordGap,
13
+ resetEventLoopLagForTests,
14
+ startEventLoopLagMonitor,
15
+ } from "./event-loop-lag.js";
16
+ import { formatSlowSql, slowSqlThresholdMs } from "./db-adapter.js";
17
+
18
+ describe("event-loop-lag: recordGap", () => {
19
+ test("正常 tick(≈interval)不算停顿", () => {
20
+ resetEventLoopLagForTests();
21
+ expect(recordGap(260, { intervalMs: 250, thresholdMs: 2000 })).toBe(10);
22
+ const s = eventLoopStats();
23
+ expect(s.stall_count).toBe(0);
24
+ expect(s.max_gap_ms).toBe(260);
25
+ expect(s.recent_stalls).toEqual([]);
26
+ });
27
+
28
+ test("超过阈值的 tick 记一条停顿,带 stall_ms / rss_mb / at", () => {
29
+ resetEventLoopLagForTests();
30
+ const now = Date.parse("2026-10-26T22:10:41Z");
31
+ const stall = recordGap(28_000, { intervalMs: 250, thresholdMs: 2000, rssMb: 4502, now });
32
+ expect(stall).toBe(27_750);
33
+ const s = eventLoopStats();
34
+ expect(s.stall_count).toBe(1);
35
+ expect(s.last_stall_ms).toBe(27_750);
36
+ expect(s.last_stall_at).toBe("2026-10-26T22:10:41.000Z");
37
+ expect(s.max_gap_ms).toBe(28_000);
38
+ expect(s.recent_stalls[0]).toMatchObject({ gap_ms: 28_000, stall_ms: 27_750, rss_mb: 4502 });
39
+ });
40
+
41
+ test("recent_stalls 最新在前,且只保留 20 条", () => {
42
+ resetEventLoopLagForTests();
43
+ for (let i = 0; i < 25; i++) {
44
+ recordGap(5_000 + i, { intervalMs: 250, thresholdMs: 2_000, rssMb: 300, now: 1_700_000_000_000 + i * 1_000 });
45
+ }
46
+ const s = eventLoopStats();
47
+ expect(s.stall_count).toBe(25);
48
+ expect(s.recent_stalls.length).toBe(20);
49
+ // 最新一条是 i=24
50
+ expect(s.recent_stalls[0].gap_ms).toBe(5_024);
51
+ expect(s.recent_stalls[19].gap_ms).toBe(5_005);
52
+ });
53
+
54
+ test("记录这段间隔里服务了多少请求(区分“阻塞”与“timer 饥饿”)", () => {
55
+ resetEventLoopLagForTests();
56
+ recordGap(85_000, { intervalMs: 250, thresholdMs: 2_000, rssMb: 2076, served: 137 });
57
+ const s = eventLoopStats();
58
+ expect(s.recent_stalls[0].requests_since_last_tick).toBe(137);
59
+ // 0 服务数 = 这段时间真的什么都没推进
60
+ recordGap(30_000, { intervalMs: 250, thresholdMs: 2_000, rssMb: 500, served: 0 });
61
+ expect(eventLoopStats().recent_stalls[0].requests_since_last_tick).toBe(0);
62
+ });
63
+
64
+ test("max_gap_ms 保留历史最大值(回落后不被覆盖)", () => {
65
+ resetEventLoopLagForTests();
66
+ recordGap(47_000, { intervalMs: 250, thresholdMs: 2_000 });
67
+ recordGap(260, { intervalMs: 250, thresholdMs: 2_000 });
68
+ const s = eventLoopStats();
69
+ expect(s.max_gap_ms).toBe(47_000);
70
+ expect(s.last_gap_ms).toBe(260);
71
+ });
72
+ });
73
+
74
+ describe("event-loop-lag: startEventLoopLagMonitor", () => {
75
+ test("阈值 0 时不打日志,但仍然计数", async () => {
76
+ resetEventLoopLagForTests();
77
+ const logs: string[] = [];
78
+ const timer = startEventLoopLagMonitor({
79
+ intervalMs: 20,
80
+ thresholdMs: 0,
81
+ log: (m) => logs.push(m),
82
+ rssMb: () => 123,
83
+ });
84
+ // 同步阻塞 80ms,让下一次 tick 一定超阈值
85
+ const until = performance.now() + 80;
86
+ while (performance.now() < until) { /* spin */ }
87
+ await Bun.sleep(60);
88
+ clearInterval(timer);
89
+ expect(logs).toEqual([]);
90
+ expect(eventLoopStats().max_gap_ms).toBeGreaterThan(0);
91
+ });
92
+
93
+ test("真实停顿会打一行 [commhub stall] 且带 rss", async () => {
94
+ resetEventLoopLagForTests();
95
+ const logs: string[] = [];
96
+ const timer = startEventLoopLagMonitor({
97
+ intervalMs: 20,
98
+ thresholdMs: 40,
99
+ log: (m) => logs.push(m),
100
+ rssMb: () => 4502,
101
+ // 这条测的是「停顿怎么打日志」,不是启动尖峰。测试进程刚起来几秒,
102
+ // 不关掉启动宽限的话第一个 tick 会被当成启动尖峰跳过(见 #2721 那组用例)。
103
+ bootGraceMs: 0,
104
+ });
105
+ const until = performance.now() + 120;
106
+ while (performance.now() < until) { /* spin 阻塞事件循环 */ }
107
+ await Bun.sleep(60);
108
+ clearInterval(timer);
109
+ expect(logs.length).toBeGreaterThan(0);
110
+ expect(logs[0]).toStartWith("[commhub stall] loop idle ~");
111
+ expect(logs[0]).toContain("rss 4502 MB");
112
+ expect(logs[0]).toContain("served 0 req");
113
+ });
114
+ });
115
+
116
+ describe("db-adapter: 慢 SQL 日志", () => {
117
+ test("默认阈值 1000ms;环境变量可调,0 表示关闭", () => {
118
+ const prev = process.env.COMMHUB_SLOW_SQL_MS;
119
+ try {
120
+ delete process.env.COMMHUB_SLOW_SQL_MS;
121
+ expect(slowSqlThresholdMs()).toBe(1000);
122
+ process.env.COMMHUB_SLOW_SQL_MS = "250";
123
+ expect(slowSqlThresholdMs()).toBe(250);
124
+ process.env.COMMHUB_SLOW_SQL_MS = "0";
125
+ expect(slowSqlThresholdMs()).toBe(0);
126
+ process.env.COMMHUB_SLOW_SQL_MS = "not-a-number";
127
+ expect(slowSqlThresholdMs()).toBe(1000);
128
+ } finally {
129
+ if (prev === undefined) delete process.env.COMMHUB_SLOW_SQL_MS;
130
+ else process.env.COMMHUB_SLOW_SQL_MS = prev;
131
+ }
132
+ });
133
+
134
+ test("日志压平换行并截断,且不含绑定参数", () => {
135
+ const sql = "DELETE FROM agent_telemetry\n WHERE created_at < datetime('now', ?1)";
136
+ const line = formatSlowSql(10_588.4, sql);
137
+ expect(line).toStartWith("[commhub slow-sql] 10588ms DELETE FROM agent_telemetry WHERE created_at < datetime('now', ?1)");
138
+ expect(line).not.toContain("\n");
139
+ const long = formatSlowSql(1_200, "SELECT " + "x".repeat(500));
140
+ expect(long.length).toBeLessThanOrEqual("[commhub slow-sql] 1200ms ".length + 160);
141
+ });
142
+ });
143
+
144
+ // #2721 —— **只跳过第一个 tick**。
145
+ //
146
+ // 事故形状:进程启动后 3 秒记到 gap 2972ms —— 那是「监控开始 → 第一次 tick」被
147
+ // 模块加载/开库/迁移占满的时间,度量的是启动耗时,不是线上停顿。
148
+ //
149
+ // 第一版实现用的是 10 秒**时间窗**,等于监控在前 10 秒什么都不记,
150
+ // 把下面那条「阈值 40ms、spin 120ms 应打停顿日志」的既有测试整体吞掉了
151
+ // —— 修完 qa.yml 事故、QA 恢复后立刻红。窗口越宽越像「把监控关一会儿」。
152
+ describe("#2721 启动尖峰不算停顿(判据:进程 uptime)", () => {
153
+ test("进程刚启动时的第一个 gap 被跳过", async () => {
154
+ resetEventLoopLagForTests();
155
+ const logs: string[] = [];
156
+ const timer = startEventLoopLagMonitor({
157
+ intervalMs: 20, thresholdMs: 40, log: (m) => logs.push(m), rssMb: () => 123,
158
+ bootGraceMs: 15_000, uptimeMs: () => 3_000, // 模拟「启动后 3 秒」
159
+ });
160
+ const until = performance.now() + 120;
161
+ while (performance.now() < until) { /* spin 落在第一个 tick */ }
162
+ await Bun.sleep(80);
163
+ clearInterval(timer);
164
+ expect(logs).toEqual([]);
165
+ });
166
+
167
+ test("进程已经跑了一会儿 ⇒ 第一个 gap 照常记录(不能把监控关掉)", async () => {
168
+ resetEventLoopLagForTests();
169
+ const logs: string[] = [];
170
+ const timer = startEventLoopLagMonitor({
171
+ intervalMs: 20, thresholdMs: 40, log: (m) => logs.push(m), rssMb: () => 123,
172
+ bootGraceMs: 15_000, uptimeMs: () => 600_000, // 进程跑了 10 分钟
173
+ });
174
+ const until = performance.now() + 120;
175
+ while (performance.now() < until) { /* spin */ }
176
+ await Bun.sleep(80);
177
+ clearInterval(timer);
178
+ expect(logs.length).toBeGreaterThan(0);
179
+ });
180
+ });
@@ -0,0 +1,201 @@
1
+ // #2614 —— 事件循环停顿监测(只观测,不改任何行为)。
2
+ //
3
+ // 背景:2026-10-26 21:55–22:12 生产 Hub 出现两次内存尖峰(RSS 3.6 → 4.5 GB),
4
+ // 伴随机 `mcp_inflight` 387 → 807。事后看日志才发现**同一时刻日志静默 14–47 秒**
5
+ // ——Hub 是单线程(Bun + 同步 SQLite),日志静默就等于事件循环被阻塞。
6
+ //
7
+ // 现有 `/api/stats/routes` 只能告诉我们“哪个请求**受害**了”(它的耗时包含了排队时间),
8
+ // 不能告诉我们“当时**谁**在阻塞”。缺的就是停顿本身的时间序列。
9
+ //
10
+ // 这个模块补上这一格:每 `intervalMs` 醒一次,量 `now - lastTick`;
11
+ // 正常情况 ≈ interval,超出 `thresholdMs` 的部分就是一次真实停顿。
12
+ // 停顿会:① 计数/留档(`/health` 的 `event_loop` 字段可读);
13
+ // ② 打一行日志(带当时的 RSS,方便和内存曲线对齐)。
14
+ //
15
+ // 注意:`setInterval` 自己也会被阻塞 —— 这正是我们要测量的东西。
16
+ // 停顿结束后第一次 tick 的 gap 就是停顿长度,不需要外部进程配合。
17
+
18
+ export type EventLoopStall = {
19
+ /** 这个间隔里处理完的请求数:0 = 真的没推进;>0 = 循环在干活,只是 timer 被饿住。 */
20
+ /** ISO 时间(停顿**结束**的时刻,即这次 tick 的时间)。 */
21
+ at: string;
22
+ /** 距上次 tick 的实际间隔(毫秒)。等于 interval + 停顿。 */
23
+ gap_ms: number;
24
+ /** 停顿量 = gap - interval。 */
25
+ stall_ms: number;
26
+ /** 停顿结束时的进程 RSS(MB),用于和内存尖峰对齐。 */
27
+ rss_mb: number;
28
+ requests_since_last_tick?: number;
29
+ };
30
+
31
+ const KEEP_STALLS = 20;
32
+
33
+ /**
34
+ * #2614(第二轮)—— 2026-10-27 00:39 线上出现 gap 84887ms,但**同一时段日志在正常写**
35
+ * (00:38:52 / 00:38:58 / 00:39:08 …),而且 `/api/stats/routes` 里最慢的请求只有 2.4s。
36
+ * 也就是说:事件循环**没有被阻塞 84 秒**,是 **timer 回调被 I/O 队列饿住**了。
37
+ * 只看 tick 间隔会把这两种情况混成一条“卡了 84 秒”的假结论。
38
+ *
39
+ * 区分办法:数一下这个间隔里**服务了多少请求**。
40
+ * requests_since_last_tick > 0 ⇒ 循环在干活 ⇒ 这是 timer 饥饿(高负载/大批回调)
41
+ * requests_since_last_tick = 0 ⇒ 真的没有推进任何请求 ⇒ 才可能是同步阻塞
42
+ */
43
+ let servedSinceTick = 0;
44
+
45
+ /** 请求处理完成时调用(route-timing 里)。只计数,不参与任何决策。 */
46
+ export function noteRequestServed(): void {
47
+ servedSinceTick++;
48
+ }
49
+
50
+ let maxGapMs = 0;
51
+ let lastGapMs = 0;
52
+ let stallCount = 0;
53
+ let lastStallAt: string | null = null;
54
+ let lastStallMs = 0;
55
+ const stalls: EventLoopStall[] = [];
56
+
57
+ /** 记录一次 tick 间隔。返回这次 tick 的停顿量(毫秒,可为负→归零)。 */
58
+ export function recordGap(
59
+ gapMs: number,
60
+ opts: { intervalMs?: number; thresholdMs?: number; rssMb?: number; now?: number; served?: number } = {},
61
+ ): number {
62
+ const interval = opts.intervalMs ?? 250;
63
+ const threshold = opts.thresholdMs ?? 2000;
64
+ lastGapMs = gapMs;
65
+ if (gapMs > maxGapMs) maxGapMs = gapMs;
66
+ const stallMs = Math.max(0, gapMs - interval);
67
+ if (stallMs < threshold) return stallMs;
68
+ const at = new Date(opts.now ?? Date.now()).toISOString();
69
+ stallCount++;
70
+ lastStallAt = at;
71
+ lastStallMs = stallMs;
72
+ stalls.push({
73
+ at,
74
+ gap_ms: Math.round(gapMs),
75
+ stall_ms: Math.round(stallMs),
76
+ rss_mb: opts.rssMb ?? 0,
77
+ requests_since_last_tick: opts.served ?? 0,
78
+ });
79
+ while (stalls.length > KEEP_STALLS) stalls.shift();
80
+ return stallMs;
81
+ }
82
+
83
+ /**
84
+ * 2026-10-31 —— 窗口两端必须跟着读数一起走(#3174)。
85
+ *
86
+ * 原来 event_loop 给了 stall_count / last_stall_at,却没有窗口起点:
87
+ * 计数器随进程重启归零,而「归零」与「从未发生」在读数上同值 ⇒
88
+ * 单独引用 stall_count 的读者会把它读成「从上线以来没卡过」。
89
+ *
90
+ * ⇒ 现在两个时刻戳都在这对象里:`since`(起点,模块初始化时冻结)与 `observed_at`(读的时刻)。
91
+ * 引用者不必再去 /health 顶层猜窗口,窗口与读数同域。
92
+ * 判据:分子分母各要自己的时刻戳;**被声明的那个永远不算**。
93
+ */
94
+ let sinceIso = new Date().toISOString();
95
+
96
+ export function eventLoopStats(): {
97
+ max_gap_ms: number;
98
+ last_gap_ms: number;
99
+ stall_count: number;
100
+ last_stall_ms: number;
101
+ last_stall_at: string | null;
102
+ recent_stalls: EventLoopStall[];
103
+ /** 窗口起点(本进程 event-loop 观察开始时刻)。 */
104
+ since: string;
105
+ /** 这次读的时刻。与 `since` 一起才构成窗口;单独任一个都不构成。 */
106
+ observed_at: string;
107
+ } {
108
+ return {
109
+ max_gap_ms: Math.round(maxGapMs),
110
+ last_gap_ms: Math.round(lastGapMs),
111
+ stall_count: stallCount,
112
+ last_stall_ms: Math.round(lastStallMs),
113
+ last_stall_at: lastStallAt,
114
+ recent_stalls: [...stalls].reverse(),
115
+ since: sinceIso,
116
+ observed_at: new Date().toISOString(),
117
+ };
118
+ }
119
+
120
+ /** 只给测试用:清空累计状态。 */
121
+ export function resetEventLoopLagForTests(): void {
122
+ maxGapMs = 0;
123
+ lastGapMs = 0;
124
+ stallCount = 0;
125
+ lastStallAt = null;
126
+ lastStallMs = 0;
127
+ stalls.length = 0;
128
+ sinceIso = new Date().toISOString(); // 重置窗口起点 —— 否则测试里「归零」与「没归零」同形
129
+ }
130
+
131
+ function envMs(name: string, fallback: number): number {
132
+ const raw = Number(process.env[name]);
133
+ return Number.isFinite(raw) && raw >= 0 ? raw : fallback;
134
+ }
135
+
136
+ /**
137
+ * 启动监测。返回 timer(调用方负责 clearInterval)。
138
+ * - `COMMHUB_STALL_LOG_MS`:停顿日志阈值,默认 2000 ms,设 0 关闭日志(仍计数);
139
+ * - `COMMHUB_STALL_TICK_MS`:采样间隔,默认 250 ms。
140
+ */
141
+ export function startEventLoopLagMonitor(opts: {
142
+ intervalMs?: number;
143
+ thresholdMs?: number;
144
+ log?: (msg: string) => void;
145
+ rssMb?: () => number;
146
+ /**
147
+ * #2721 —— 启动期的 tick gap 不算停顿。判据是**进程启动多久了**,不是第几个 tick。
148
+ *
149
+ * 事故形状:进程 22:21:06 启动,14:21:09.835Z 记到 gap 2972ms —— 启动后 3 秒。
150
+ * 那段 gap 度量的是「监控开始 → 第一次 tick」被模块加载/开库/迁移占满的时间。
151
+ *
152
+ * 两版错误实现(都试过,都被既有测试抓住):
153
+ * ① 10 秒**时间窗** → 监控在前 10 秒什么都不记,「阈值 40ms + spin 120ms 应打日志」直接吞掉
154
+ * ② 只跳**第一个 tick** → 测试里的 spin 恰好落在第一个 tick,同样吞掉
155
+ *
156
+ * 真正的区别不是「第几个 tick」,而是**这段时间里进程有没有可能还在启动**。
157
+ * 所以:只有当 tick 到来时进程 uptime 仍小于 bootGraceMs,才把 gap 当作启动尖峰。
158
+ * 启动 20 秒之后的第一条 gap 依旧照常记录 —— 那时候它不可能是启动耗时。
159
+ */
160
+ bootGraceMs?: number;
161
+ /** 测试注入:返回进程已运行的毫秒数(默认 process.uptime())。 */
162
+ uptimeMs?: () => number;
163
+ } = {}): ReturnType<typeof setInterval> {
164
+ const intervalMs = opts.intervalMs ?? Math.max(50, envMs("COMMHUB_STALL_TICK_MS", 250));
165
+ const thresholdMs = opts.thresholdMs ?? envMs("COMMHUB_STALL_LOG_MS", 2000);
166
+ const log = opts.log ?? ((m: string) => console.log(m));
167
+ const rssMb = opts.rssMb ?? (() => Math.round(process.memoryUsage().rss / 1048576));
168
+ let last = performance.now();
169
+ const startedAt = last;
170
+ // #2721 —— 启动预热不算停顿。
171
+ // 实测:2026-10-29 这次进程 22:21:06 起来,14:21:09.835Z 记到一次 gap 2972ms,
172
+ // 也就是**启动后 3 秒**。那段时间在做模块加载 / 打开 DB / 迁移,第一个 tick 必然偏大。
173
+ // 不排除它的后果是:每次部署都会在 `/health` 里留一条「停顿」,而它和线上真实卡顿长得一模一样。
174
+ const bootGraceMs = opts.bootGraceMs ?? envMs("COMMHUB_STALL_BOOT_GRACE_MS", 15_000);
175
+ const uptimeMs = opts.uptimeMs ?? (() => process.uptime() * 1000);
176
+ let firstTick = true;
177
+ const timer = setInterval(() => {
178
+ const now = performance.now();
179
+ const gap = now - last;
180
+ last = now;
181
+ const rss = rssMb();
182
+ const served = servedSinceTick;
183
+ servedSinceTick = 0;
184
+ // 启动尖峰:只可能是**第一个** tick,且到来时进程才刚起来。
185
+ // 两个条件缺一不可 —— 只看「第一个 tick」会吞掉运行中立刻发生的真实停顿。
186
+ if (firstTick) {
187
+ firstTick = false;
188
+ if (uptimeMs() < bootGraceMs) return;
189
+ }
190
+ const stall = recordGap(gap, { intervalMs, thresholdMs, rssMb: rss, served });
191
+ if (thresholdMs > 0 && stall >= thresholdMs) {
192
+ // 和 retention/slow-sql 的日志同一前缀,方便 grep。
193
+ // `served` 是判据的关键:它非零就说明循环在干活,这段“gap”是 timer 被饿住,不是阻塞。
194
+ log(`[commhub stall] loop idle ~${Math.round(stall)}ms (tick gap ${Math.round(gap)}ms, rss ${rss} MB, served ${served} req)`);
195
+ }
196
+ }, intervalMs);
197
+ // 监测不该拖住进程退出。
198
+ (timer as unknown as { unref?: () => void }).unref?.();
199
+ last = performance.now();
200
+ return timer;
201
+ }
@@ -0,0 +1,60 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import {
3
+ buildStoragePath,
4
+ pathForExistingBlob,
5
+ validateIndexEntry,
6
+ } from "./uploads.js";
7
+
8
+ const fileId = "0123456789abcdef0123456789abcdef";
9
+ const dateBucket = "2026-08-09";
10
+ const uploadsRoot = "/srv/uploads";
11
+
12
+ const malicious = [
13
+ "../x",
14
+ "/abs/x",
15
+ ".png/../../y",
16
+ ".p ng",
17
+ ".p\0ng",
18
+ ".\\..\\x",
19
+ "." + "a".repeat(17),
20
+ ".tar.gz",
21
+ ];
22
+
23
+ const legal = ["", ".png", ".PNG", ".mp4", "." + "a".repeat(16)];
24
+
25
+ describe("#527 shared extension-token invariant", () => {
26
+ test("new-upload path rejects every malformed token and accepts the shared legal set", () => {
27
+ for (const ext of malicious) {
28
+ expect(() => buildStoragePath(fileId, ext, { uploadsRoot })).toThrow(/ext .* is invalid/);
29
+ }
30
+ for (const ext of legal) {
31
+ expect(buildStoragePath(fileId, ext, { uploadsRoot }).ext).toBe(ext);
32
+ }
33
+ });
34
+
35
+ test("existing-blob path rejects every malformed token and accepts the shared legal set", () => {
36
+ for (const ext of malicious) {
37
+ expect(() => pathForExistingBlob(dateBucket, fileId, ext, { uploadsRoot })).toThrow(/ext .* is invalid/);
38
+ }
39
+ for (const ext of legal) {
40
+ expect(pathForExistingBlob(dateBucket, fileId, ext, { uploadsRoot }).ext).toBe(ext);
41
+ }
42
+ });
43
+
44
+ test("stored-index gate rejects every malformed token and accepts the shared legal set", () => {
45
+ for (const ext of malicious) {
46
+ expect(validateIndexEntry({ file_id: fileId, date_bucket: dateBucket, ext, size: 0 })).toBe(false);
47
+ }
48
+ for (const ext of legal) {
49
+ expect(validateIndexEntry({ file_id: fileId, date_bucket: dateBucket, ext, size: 0 })).toBe(true);
50
+ }
51
+ });
52
+
53
+ test("all three boundaries fail closed on non-string runtime values", () => {
54
+ for (const ext of [undefined, null, 7, {}, []]) {
55
+ expect(() => buildStoragePath(fileId, ext as never, { uploadsRoot })).toThrow(/ext .* is invalid/);
56
+ expect(() => pathForExistingBlob(dateBucket, fileId, ext as never, { uploadsRoot })).toThrow(/ext .* is invalid/);
57
+ expect(validateIndexEntry({ file_id: fileId, date_bucket: dateBucket, ext, size: 0 })).toBe(false);
58
+ }
59
+ });
60
+ });
@@ -0,0 +1,131 @@
1
+ // Task #25 — regression pins for ext validation in validateIndexEntry.
2
+ //
3
+ // 🔴 SCOPE: this suite exercises the stored-index boundary through
4
+ // `validateIndexEntry`. Issue #527 removed the three independent copies
5
+ // of the stored extension-token grammar: buildStoragePath,
6
+ // pathForExistingBlob and validateIndexEntry now use one shared private
7
+ // validator. `ext-token-shared.test.ts` separately pins all three call
8
+ // sites. sanitizeExt remains intentionally independent because it parses
9
+ // a client filename rather than validating an already-extracted token.
10
+ //
11
+ // Background (通信龙 d01bb8ce): the stored extension-token grammar
12
+ // `/^\.[A-Za-z0-9]{1,16}$/` correctly rejects 11 known malicious ext
13
+ // values (path-escape, traversal, absolute paths, doubles, NUL bytes,
14
+ // backslash forms, over-length, whitespace). Verified via real-run on
15
+ // origin/main by lead — 11/11 malicious values → false.
16
+ //
17
+ // But NO test locked that behavior. Anyone who widens the regex in the
18
+ // future (accidentally or on purpose) would not hit a red test — the
19
+ // live protection would degrade silently. This suite pins current
20
+ // behavior in two directions:
21
+ //
22
+ // 1. SAFETY (欠修 direction) — 11 malicious values → false, one row
23
+ // per value with the exact literal. If regex is widened to accept
24
+ // any of them, that row turns red.
25
+ // 2. NON-REGRESSION (过修 direction) — a set of common legitimate
26
+ // extensions → true. If regex is tightened to reject any of them
27
+ // (e.g. someone locks down to a whitelist), that row turns red.
28
+ //
29
+ // Witnessed-red for the SAFETY rows: temporarily widen the regex to
30
+ // `/./` (or comment it out) in validateIndexEntry, run this suite,
31
+ // confirm all 11 malicious rows turn red, then revert. The mutation
32
+ // itself is not committed; the assertion IS the mutation-red proof
33
+ // for the reader. Recording the mutation output in the followup PR
34
+ // body (per Constraint 3 discipline established in #503).
35
+ //
36
+ // Pure unit test — no server setup, no DB, no filesystem. The regex
37
+ // lives in a pure function, so the guard is testable at that level.
38
+
39
+ import { describe, expect, test } from "bun:test";
40
+ import { validateIndexEntry } from "./uploads.js";
41
+
42
+ // A structurally-valid base entry — file_id / date_bucket / size all
43
+ // pass their own checks — so `ext` is the only field a test row varies.
44
+ // This isolates the ext regex as the deciding factor.
45
+ const validBase = {
46
+ file_id: "0123456789abcdef0123456789abcdef",
47
+ date_bucket: "2026-07-30",
48
+ size: 0,
49
+ };
50
+
51
+ describe("Task #25 (#503 followup) — ext validation regression pins", () => {
52
+ describe("SAFETY: the 11 malicious ext values from lead d01bb8ce all return false", () => {
53
+ // Each row uses the exact literal from lead's verification list so
54
+ // a widening regex catches on the same value the manual audit did.
55
+ const malicious: Array<{ label: string; ext: string }> = [
56
+ { label: "path-escape prefix", ext: "../x" },
57
+ { label: "deep traversal to /etc", ext: "../../etc/passwd" },
58
+ { label: "absolute path", ext: "/abs/x" },
59
+ { label: "double-dot alone", ext: ".." },
60
+ { label: "single-dot alone", ext: "." },
61
+ { label: "chained after legit prefix", ext: ".png/../../y" },
62
+ { label: "embedded whitespace", ext: ".p ng" },
63
+ { label: "over-length (>16 chars)", ext: "." + "a".repeat(17) },
64
+ { label: "embedded NUL byte", ext: ".p\x00ng" },
65
+ { label: "backslash traversal", ext: ".\\..\\x" },
66
+ { label: "double-backslash prefix", ext: "..\\x" },
67
+ ];
68
+ for (const { label, ext } of malicious) {
69
+ test(`rejects: ${label} — ext=${JSON.stringify(ext)}`, () => {
70
+ expect(validateIndexEntry({ ...validBase, ext })).toBe(false);
71
+ });
72
+ }
73
+
74
+ test("precondition: 11 malicious cases enumerated (defends against silent test-shrink)", () => {
75
+ // If someone deletes rows from the malicious list, this fails
76
+ // instead of the deletion silently narrowing the guard. Number
77
+ // matches lead's verification list — bump only when lead adds a
78
+ // case and confirms it via real-run.
79
+ expect(malicious.length).toBe(11);
80
+ });
81
+ });
82
+
83
+ describe("NON-REGRESSION: common legitimate extensions all return true (防过修)", () => {
84
+ // These are the extensions the live upload path actually produces
85
+ // via sanitizeExt / mime-typed multipart uploads. If someone
86
+ // tightens the regex to a stricter whitelist, any of these turning
87
+ // red flags a break in a normal user path.
88
+ const legal = [".png", ".pdf", ".pptx", ".jpg", ".jpeg", ".txt", ".mp4", ".zip", ".json", ".md"];
89
+ for (const ext of legal) {
90
+ test(`accepts: ext=${JSON.stringify(ext)}`, () => {
91
+ expect(validateIndexEntry({ ...validBase, ext })).toBe(true);
92
+ });
93
+ }
94
+
95
+ test("empty ext is accepted (file with no extension is a legitimate upload)", () => {
96
+ expect(validateIndexEntry({ ...validBase, ext: "" })).toBe(true);
97
+ });
98
+
99
+ test("precondition: at least 10 legitimate ext values pinned", () => {
100
+ // Same discipline as the malicious side — reject silent shrink.
101
+ expect(legal.length).toBeGreaterThanOrEqual(10);
102
+ });
103
+ });
104
+
105
+ describe("regex shape assumptions (documented, not enforced by the function)", () => {
106
+ // These rows document facts the current regex enforces beyond the
107
+ // 11 malicious literals. They are close to the boundary and would
108
+ // be the first things to move if someone reworked the regex.
109
+ test("upper-case extensions accepted (regex is case-insensitive by [A-Za-z])", () => {
110
+ expect(validateIndexEntry({ ...validBase, ext: ".PNG" })).toBe(true);
111
+ });
112
+ test("mixed-case extensions accepted", () => {
113
+ expect(validateIndexEntry({ ...validBase, ext: ".PdF" })).toBe(true);
114
+ });
115
+ test("digits after dot accepted (e.g. .mp4, .mp3)", () => {
116
+ expect(validateIndexEntry({ ...validBase, ext: ".mp4" })).toBe(true);
117
+ });
118
+ test("exactly 16 chars after dot is accepted (upper bound of {1,16})", () => {
119
+ expect(validateIndexEntry({ ...validBase, ext: "." + "a".repeat(16) })).toBe(true);
120
+ });
121
+ test("exactly 17 chars after dot is rejected (immediately past upper bound)", () => {
122
+ expect(validateIndexEntry({ ...validBase, ext: "." + "a".repeat(17) })).toBe(false);
123
+ });
124
+ test("compound extensions like .tar.gz are rejected (contains inner dot)", () => {
125
+ // Documented: the current regex does not support compound
126
+ // extensions. If we ever want .tar.gz support, it needs its
127
+ // own explicit design + this row updated with lead sign-off.
128
+ expect(validateIndexEntry({ ...validBase, ext: ".tar.gz" })).toBe(false);
129
+ });
130
+ });
131
+ });