Skip to content

Commit bd8a2ca

Browse files
committed
feat(panel): 矛盾账本只读页 + conflictLedgerMode 面板座位(#641 beta 第三阶段收官)
- GET /conflicts/ledger(policy: token):分诊分布(按 tier 计数)+ 最近 账本行。conflict_ledger 是 bookkeeping 表,行不是待办——处置由 enforce 档自动完成,面板只回答「账本里有什么、分布如何」。SECURITY.md 受门控 读清单同步(zh+en,六条读 → 七条读),security-doc.test.js 双向比对通过。 - 状态页「矛盾账本」只读卡:分诊分布一行 + 最近 8 行(tier/状态/首见日期); 空账本整块不渲染(与冲突队列同款不打扰原则)。与冲突队列互补——队列是 「等人来」的待办(freeze),账本是「机器观察/处置过什么」的只读面 (shadow/enforce)。 - conflictLedgerMode 面板座位:高级区三档下拉(off/shadow/enforce),紧挨 conflictFreezeEnabled——两者语义关联(enforce 与 freeze 互斥,同开时冻结 让位),隔开摆放会让人以为各自独立。0.14.0 发版后 shadow 周从面板直接开。 - EPISTEMIC_PRIORITY 从 decisions.js 导出复用。 全量 3355 tests / 3354 pass / 0 fail(pipefail)。
1 parent 1eacb90 commit bd8a2ca

5 files changed

Lines changed: 177 additions & 3 deletions

File tree

‎SECURITY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ The token is a lock on the **write** surface, not a wall around the whole API.
154154
- **The real boundary is loopback + the DSH host listener.** The host-side routes (`/api/dsh-mneme/*`) are mounted on the DSH port, which binds `127.0.0.1` and is fenced by the host against DNS rebinding and cross-site browser requests. That fence does **not** establish identity: any local process, and any page running in the host's own origin, is inside the perimeter.
155155
- **Authentication is opt-in and fail-open.** `apiToken` defaults to empty; while it is empty, `isAuthorized()` returns true for every request — reads *and* writes. Setting a token gates the write routes and the sensitive reads; it does not gate plain reads.
156156
- **Open reads (no token even when one is configured)**: `GET /`, `/info`, `/version-check`, `/list`, `/recall-stats`, `/search`, `/semantic`, `/semantic/llm-audit`, `/semantic/llm-audit/stats`, `/semantic/consolidation-stats`, `/semantic/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/diary`, `/diary/entry`, `/diary/library`, `/diary/library/entry`, `/llm-providers`, `/config-keys`, plus the `GET`/`HEAD` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge`, `/diary/compose`, `/diary/export`, of the two share-receive routes `/receive` and `/receive/undo`, of `/profile-facts/apply`, of the six chorography read routes `/choro/repos`, `/choro/modules`, `/choro/page`, `/choro/search`, `/choro/claims`, `/choro/run` (M1/finale: they read repo-local wiki pages and `choro_*` index tables — not memory rows; with `chorographyEnabled` off they uniformly answer `409 disabled`, the #497 mount-anyway-gate-in-logic pattern), of the two T1 job routes `/choro/t1` and `/choro/t1/status` (same `token-write` shape as `/choro/run`: the only token-exempt branch is a `405`, and the POST itself answers `409 disabled` unless both `chorographyEnabled` and `chorographyT1FromPanel` are on), and of the three `token-write` knowledge-base routes `/kb/collections`, `/kb/ingest` and `/kb/search` (again only a `405` is genuinely open on them, because `needsToken()` exempts `GET`/`HEAD` under `token-write`; the two plain-`token` reads under `/kb/*` stay gated even on `GET`). `/choro/run` is the same shape as `/receive`: a `token-write` route whose GET branch is token-exempt, so the only genuinely open thing on that path is a `405` — the POST write itself stays gated. Treat them as readable by anything local. `/receive` and `/receive/undo` belong on this list even though they write: under the `token-write` policy, `needsToken()` exempts `GET`/`HEAD` from the token, so the only thing genuinely open on those two paths is a `405` — no read branch exists. `/profile-facts/apply` is POST-only for the same reason (its only open branch is a `405`). The `GET` branch of `/profile-facts` stays open even while `profileFactsEnabled` is off: facts survive a switch-off and the panel must be able to show them (same reasoning as `GET /profile`). This section mirrors the policy declarations rather than anyone's intent, which is why a write route shows up under "open reads"; `dsh-mneme/test/security-doc.test.js` compares both lists against the routes actually mounted, in both directions.
157-
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/bootstrap`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, `/profile/extract` (POST-only: one host-LLM call that returns a profile **draft**; other methods get 405 before any side effect), `/profile-facts/apply` (POST-only: per-fact manual corrections from the panel; writes the `profile_facts` tables, never `user_settings`), `/profile-facts/run` (POST-only, `token` policy like `/profile/extract`: one host-LLM maintenance pass with no read branch; 409 while `profileFactsEnabled` is off), `/choro/run` (POST-only: the panel "rebuild skeleton" write path, re-running T0 into the repo's `.chorography/**`; with `chorographyEnabled` off it uniformly answers 409 disabled), `/choro/t1` (POST-only: spawns a real T1 run through the choro CLI — a host-LLM pass that costs money, so it carries its own `chorographyT1FromPanel` switch on top of `chorographyEnabled`), `/choro/t1/status` (the job poll: its `logTail` carries CLI/model output, so it is not a public-repo read like the rest of `/choro/*`), `/kb/collections`, `/kb/search` (POST-only writes; the only token-exempt branch is the `405`, same shape as `/choro/run`), `/kb/ingest` (POST-only: pulls a configured local source into the knowledge base; source-level failures still answer `200` with `ok:false`, which is a result, not a permission), `/kb/docs`, `/kb/doc` (plain `token`: they hand back whatever collection content the user ingested — that is private material, unlike the repo-documentation `/choro/*` reads), `/receive`, `/receive/undo` (the two share-receive routes write into *this* machine's library, which is why they are `token-write`), `/diary/compose` (POST-only: one host-LLM call that writes `<memoryDir>/diaries/<projectKey>/YYYY-MM-DD.md`; 409 while `diaryEnabled` is off), `/diary/export` (POST-only: copies one entry into the *user's* bound project directory, which is outside every path the plugin otherwise owns — 409 on an existing target unless `overwrite` is explicit), and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge` — plus six reads: `/export`, `/external-api`, `/conflicts`, `/health`, `/share`, `/memory/provenance`. `/share` is gated because the share pack is a whole-library read delivered over POST, and it answers 405 to GET — no open read path exists. `/memory/provenance` is gated because it returns the **verbatim raw text** of distilled conversation windows (opt-in via `distillRecords.enabled`); chained with the open list route it would otherwise let any local process enumerate ids and then pull that text back, which reaches the same result as `/export` in a different shape.
157+
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/bootstrap`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, `/profile/extract` (POST-only: one host-LLM call that returns a profile **draft**; other methods get 405 before any side effect), `/profile-facts/apply` (POST-only: per-fact manual corrections from the panel; writes the `profile_facts` tables, never `user_settings`), `/profile-facts/run` (POST-only, `token` policy like `/profile/extract`: one host-LLM maintenance pass with no read branch; 409 while `profileFactsEnabled` is off), `/choro/run` (POST-only: the panel "rebuild skeleton" write path, re-running T0 into the repo's `.chorography/**`; with `chorographyEnabled` off it uniformly answers 409 disabled), `/choro/t1` (POST-only: spawns a real T1 run through the choro CLI — a host-LLM pass that costs money, so it carries its own `chorographyT1FromPanel` switch on top of `chorographyEnabled`), `/choro/t1/status` (the job poll: its `logTail` carries CLI/model output, so it is not a public-repo read like the rest of `/choro/*`), `/kb/collections`, `/kb/search` (POST-only writes; the only token-exempt branch is the `405`, same shape as `/choro/run`), `/kb/ingest` (POST-only: pulls a configured local source into the knowledge base; source-level failures still answer `200` with `ok:false`, which is a result, not a permission), `/kb/docs`, `/kb/doc` (plain `token`: they hand back whatever collection content the user ingested — that is private material, unlike the repo-documentation `/choro/*` reads), `/receive`, `/receive/undo` (the two share-receive routes write into *this* machine's library, which is why they are `token-write`), `/diary/compose` (POST-only: one host-LLM call that writes `<memoryDir>/diaries/<projectKey>/YYYY-MM-DD.md`; 409 while `diaryEnabled` is off), `/diary/export` (POST-only: copies one entry into the *user's* bound project directory, which is outside every path the plugin otherwise owns — 409 on an existing target unless `overwrite` is explicit), and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/profile-facts`, `/mode`, `/features`, `/commands`, `/nudge` — plus seven reads: `/export`, `/external-api`, `/conflicts`, `/conflicts/ledger` (read-only triage ledger — tier/status/detection timestamps and title-level info, same sensitivity as `/conflicts`), `/health`, `/share`, `/memory/provenance`. `/share` is gated because the share pack is a whole-library read delivered over POST, and it answers 405 to GET — no open read path exists. `/memory/provenance` is gated because it returns the **verbatim raw text** of distilled conversation windows (opt-in via `distillRecords.enabled`); chained with the open list route it would otherwise let any local process enumerate ids and then pull that text back, which reaches the same result as `/export` in a different shape.
158158
- **The standalone data plane** (`127.0.0.1:8790`) is the opposite shape: every route except `GET /health` requires its own Bearer token. Pointing `externalApiHost` at a non-loopback address therefore turns it into a plaintext, token-only HTTP surface — an explicit operator decision.
159159
- **Consequence**: if you expose the plugin beyond loopback (reverse proxy, non-loopback bind), set `apiToken` *and* check that the plain reads above are acceptable to expose — they are not covered by it.
160160
- **How this list stays true**: every route declares its own `policy` (`open` / `token` / `token-write`) at registration, and `createRouteRegistrar` throws when a route has none or reuses a path. A new route that forgets its classification **fails to boot** instead of silently opening. The two lists above are compared against the routes actually mounted by `dsh-mneme/test/security-doc.test.js` in both directions, so adding a route without updating this section fails CI rather than quietly drifting — the matrix is derived from code, not from anyone's memory.
@@ -552,7 +552,7 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
552552
- **真正的边界是回环 + 宿主监听器。** 宿主侧路由(`/api/dsh-mneme/*`)挂在 DSH 端口上,该端口绑 `127.0.0.1`,并由宿主挡掉 DNS rebinding 与跨站浏览器请求。这道围栏**不建立身份**:任何本地进程、以及任何跑在宿主同源页面里的脚本,都在这道围栏之内。
553553
- **鉴权是 opt-in 且 fail-open。** `apiToken` 默认为空;为空期间 `isAuthorized()` 对每个请求都返回 true——读和写都放行。配了 token 之后,它守的是写路由与敏感读,不守普通读。
554554
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/consolidation-stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/diary`、`/diary/entry`、`/diary/library`、`/diary/library/entry`、`/llm-providers`、`/config-keys`,以及 `/profile`、`/rules`、`/persona`、`/profile-facts`、`/mode`、`/features`、`/commands`、`/nudge`、`/diary/compose`、`/diary/export`、`/receive`、`/receive/undo`、`/profile-facts/apply`、`/choro/repos`、`/choro/modules`、`/choro/page`、`/choro/search`、`/choro/claims`、`/choro/run`、`/choro/t1`、`/choro/t1/status`、`/kb/collections`、`/kb/ingest`、`/kb/search` 的 `GET`/`HEAD` 分支。`/choro/run` 与 `/receive` 同款:token-write 的 GET 分支免 token 后真正开放的只有一个 405(它只收 POST),出现在这里是 policy 声明的忠实投影。把它们当作「本地任何东西都能读」。`/receive`、`/receive/undo` 明明是写路由也出现在这一串里,这不是笔误:`token-write` 下 `needsToken()` 对 `GET`/`HEAD` 免 token,所以这两条路径上真正「开放」的只有一个 `405`,压根没有可读分支;`/profile-facts/apply` 同理只收 POST,开放的唯一分支是一个 `405`。`/profile-facts` 的 `GET` 分支在 `profileFactsEnabled` 关着时同样开放:开关关掉后存量事实还在库里,面板要能展示(与 `GET /profile` 同一理由)。`/choro/*` 六条(chorography 仓库地志读侧,M1 + 收尾档)读的是**仓库里的 MD 页与 choro_* 索引表**,不是记忆行——内容是代码仓库的公开文档面,`chorographyEnabled` 关着时统一回 409 disabled(路由挂着、逻辑层挡,#497 先例),不因为开放读而绕过这个闸。这一节照 policy 声明抄、不照意图写,`dsh-mneme/test/security-doc.test.js` 会拿真实装配出来的路由双向比对这两行。
555-
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/bootstrap`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`、`/profile/extract`(只收 POST:花一次宿主 LLM 产一段画像**草稿**,其它方法在产生任何副作用之前就 405)、`/profile-facts/apply`(只收 POST:面板的逐条人工修正;写的是 profile_facts 三表,绝不碰 user_settings)、`/profile-facts/run`(只收 POST,`token` 政策与 `/profile/extract` 同款:一次宿主 LLM 维护轮,无读分支;`profileFactsEnabled` 关着时 409)、`/choro/run`(只收 POST:面板「重建骨架」的写入口,重跑 T0 落仓库磁盘的 `.chorography/**`——chorographyEnabled 关着时统一 409 disabled)、`/choro/t1`(只收 POST:经 choro CLI 真起一次 T1——一次要花模型额度的宿主 LLM 作业,所以在 `chorographyEnabled` 之上另有一枚 `chorographyT1FromPanel` 闸)、`/choro/t1/status`(任务轮询:`logTail` 里带 CLI 与模型的原始输出,不属 `/choro/*` 其余几条那种「仓库公开文档面」)、`/kb/collections`、`/kb/search`(只收 POST 的写入口,token-write 下真正开放的只有一个 405,与 `/choro/run` 同款)、`/kb/ingest`(只收 POST:把用户配置的本地来源抽进知识库;来源级失败仍回 `200` + `ok:false`,那是结果不是权限)、`/kb/docs`、`/kb/doc`(纯 `token`:回的是用户导进来的集合内容,属私料,与 `/choro/*` 那类仓库文档读侧不同量级)、`/receive`、`/receive/undo`(这两条写的是**本机自己的库**,所以归 `token-write`)、`/diary/compose`(只收 POST:花一次宿主 LLM 写 `<memoryDir>/diaries/<项目键>/YYYY-MM-DD.md`;`diaryEnabled` 关着时 409)、`/diary/export`(只收 POST:把某一篇**复制**进用户绑定的项目目录——那是插件本来不拥有的路径,目标已存在时默认 409,要覆盖必须显式传 `overwrite`),以及 `/profile`、`/rules`、`/persona`、`/profile-facts`、`/mode`、`/features`、`/commands`、`/nudge` 的非 `GET` 分支——外加六条读:`/export`、`/external-api`、`/conflicts`、`/health`、`/share`(分享包是「用 POST 递出来的全库读取」,GET 一律 405,没有开放的读分支)、`/memory/provenance`(它回的是蒸馏窗口的**逐字会话原文**,并自 #512 起按窗口带出 `distill_run_id` / `run_type` / `trigger_source` / `run_status` 的运行归因;`distillRecords.enabled` 打开才有;否则把它和上面那个开放的列表路由串起来,任何本地进程都能先枚举 id、再按 id 把那些原文捞回去——可达结果与 `/export`(一次拿全库)同量级,只是换了形状)。
555+
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/bootstrap`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`、`/profile/extract`(只收 POST:花一次宿主 LLM 产一段画像**草稿**,其它方法在产生任何副作用之前就 405)、`/profile-facts/apply`(只收 POST:面板的逐条人工修正;写的是 profile_facts 三表,绝不碰 user_settings)、`/profile-facts/run`(只收 POST,`token` 政策与 `/profile/extract` 同款:一次宿主 LLM 维护轮,无读分支;`profileFactsEnabled` 关着时 409)、`/choro/run`(只收 POST:面板「重建骨架」的写入口,重跑 T0 落仓库磁盘的 `.chorography/**`——chorographyEnabled 关着时统一 409 disabled)、`/choro/t1`(只收 POST:经 choro CLI 真起一次 T1——一次要花模型额度的宿主 LLM 作业,所以在 `chorographyEnabled` 之上另有一枚 `chorographyT1FromPanel` 闸)、`/choro/t1/status`(任务轮询:`logTail` 里带 CLI 与模型的原始输出,不属 `/choro/*` 其余几条那种「仓库公开文档面」)、`/kb/collections`、`/kb/search`(只收 POST 的写入口,token-write 下真正开放的只有一个 405,与 `/choro/run` 同款)、`/kb/ingest`(只收 POST:把用户配置的本地来源抽进知识库;来源级失败仍回 `200` + `ok:false`,那是结果不是权限)、`/kb/docs`、`/kb/doc`(纯 `token`:回的是用户导进来的集合内容,属私料,与 `/choro/*` 那类仓库文档读侧不同量级)、`/receive`、`/receive/undo`(这两条写的是**本机自己的库**,所以归 `token-write`)、`/diary/compose`(只收 POST:花一次宿主 LLM 写 `<memoryDir>/diaries/<项目键>/YYYY-MM-DD.md`;`diaryEnabled` 关着时 409)、`/diary/export`(只收 POST:把某一篇**复制**进用户绑定的项目目录——那是插件本来不拥有的路径,目标已存在时默认 409,要覆盖必须显式传 `overwrite`),以及 `/profile`、`/rules`、`/persona`、`/profile-facts`、`/mode`、`/features`、`/commands`、`/nudge` 的非 `GET` 分支——外加七条读:`/export`、`/external-api`、`/conflicts`、`/conflicts/ledger`(矛盾分诊账本的只读面:tier/status/检出时间与标题级信息,与 `/conflicts` 同级——处置由 enforce 档自动完成,行不是待办)、`/health`、`/share`(分享包是「用 POST 递出来的全库读取」,GET 一律 405,没有开放的读分支)、`/memory/provenance`(它回的是蒸馏窗口的**逐字会话原文**,并自 #512 起按窗口带出 `distill_run_id` / `run_type` / `trigger_source` / `run_status` 的运行归因;`distillRecords.enabled` 打开才有;否则把它和上面那个开放的列表路由串起来,任何本地进程都能先枚举 id、再按 id 把那些原文捞回去——可达结果与 `/export`(一次拿全库)同量级,只是换了形状)。
556556
- **独立数据面**(`127.0.0.1:8790`)是反过来的形状:除 `GET /health` 外每条路由都要自己的 Bearer token。因此把 `externalApiHost` 指向非回环地址,就等于把它变成一个「明文、只靠 token」的 HTTP 面——这是运营者的显式决定。
557557
- **推论**:如果你把插件暴露到回环之外(反代、绑非回环地址),请设 `apiToken`,**并**核对上面那串开放读是否也能被看到——它们不受 token 保护。
558558
- **这张表怎么保持为真**:每条路由在注册时自己声明 `policy`(`open` / `token` / `token-write`),`createRouteRegistrar` 在路由没声明或复用同一路径时直接抛错。新路由忘了归类会**启动失败**,而不是静默开门。上面两张清单还会被 `dsh-mneme/test/security-doc.test.js` 拿真实装配出来的路由做双向比对——加了路由却不更新这一节,CI 会红,而不是悄悄漂走。这张矩阵来自代码,不来自谁的记忆。

0 commit comments

Comments
 (0)