Skip to content

Commit 918fbbf

Browse files
committed
docs(security): 路由清单补上 persona 与 conflicts,并用测试锁住它
安全模型节的两张路由清单是从代码抄的,抄漏了没人发现: - 开放读漏了 /persona(policy token-write,GET/HEAD 开放) - 受门控漏了 /conflicts(policy token,只读也要 Bearer) - 受门控把 /mode、/features、/commands 的 GET 分支也算进去了,实际开放 改成「写操作按非 GET 分支描述、四条读单独列出」,并在 test/security-doc.test.js 加两条双向比对:拿 createApi 真实装配出的路由 (policy 来自注册声明)逐条对文档清单,少写、多写、写错边都红。 变异验证:删 /persona → 开放读用例红;删 /conflicts → 受门控用例红; 多写 /nope → 受门控用例红;还原 → 6 pass。
1 parent e231def commit 918fbbf

4 files changed

Lines changed: 81 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3E63DD?style=flat-square" alt="license"></a>
1111
<a href="https://github.com/slow-stack/mneme/actions"><img src="https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml?style=flat-square&label=CI" alt="CI"></a>
1212
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-22%2B-3E63DD?style=flat-square&logo=nodedotjs&logoColor=white" alt="node"></a>
13-
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2131%20passed-3E63DD?style=flat-square" alt="tests"></a>
13+
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2137%20passed-3E63DD?style=flat-square" alt="tests"></a>
1414
<a href="https://codecov.io/gh/slow-stack/mneme"><img src="https://img.shields.io/codecov/c/github/slow-stack/mneme/main?style=flat-square" alt="coverage"></a>
1515
<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome"></a>
1616
</p>
@@ -266,7 +266,7 @@ dsh-mneme-serve # 默认 ~/.dsh/memory + 127.0.0.1:8790
266266

267267
```bash
268268
cd dsh-mneme && npm install
269-
npm test # 2131 个测试
269+
npm test # 2137 个测试
270270
npm run stress # 三轴线压测
271271
npm run sync # src → lib 同步
272272
```
@@ -542,7 +542,7 @@ Community projects that wire mneme into more platforms — not part of this repo
542542

543543
```bash
544544
cd dsh-mneme && npm install
545-
npm test # 2131 tests
545+
npm test # 2137 tests
546546
npm run stress # three-axis stress test
547547
npm run sync # src → lib sync
548548
```

‎SECURITY.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -153,11 +153,11 @@ The token is a lock on the **write** surface, not a wall around the whole API.
153153

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.
156-
- **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/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/llm-providers`, plus the `GET` branches of `/profile`, `/rules`, `/features`, `/mode`, `/commands`. Treat them as readable by anything local.
157-
- **Gated routes (when a token is configured)**: all writes (`/create`, `/update`, `/delete`, `/import`, `/mode`, `/features`, `/commands`, `/conflicts/resolve`, `PUT /profile`, `PUT /rules`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/health`) and the sensitive reads `/export` and `/external-api`.
156+
- **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/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/llm-providers`, plus the `GET`/`HEAD` branches of `/profile`, `/rules`, `/persona`, `/mode`, `/features`, `/commands`. Treat them as readable by anything local.
157+
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/mode`, `/features`, `/commands` — plus four reads: `/export`, `/external-api`, `/conflicts`, `/health`.
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.
160-
- **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 matrix above is derived from code, not from anyone's memory.
160+
- **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.
161161

162162
---
163163

@@ -534,11 +534,11 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
534534

535535
- **真正的边界是回环 + 宿主监听器。** 宿主侧路由(`/api/dsh-mneme/*`)挂在 DSH 端口上,该端口绑 `127.0.0.1`,并由宿主挡掉 DNS rebinding 与跨站浏览器请求。这道围栏**不建立身份**:任何本地进程、以及任何跑在宿主同源页面里的脚本,都在这道围栏之内。
536536
- **鉴权是 opt-in 且 fail-open。** `apiToken` 默认为空;为空期间 `isAuthorized()` 对每个请求都返回 true——读和写都放行。配了 token 之后,它守的是写路由与敏感读,不守普通读。
537-
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/llm-providers`,以及 `/profile`、`/rules`、`/features`、`/mode`、`/commands` 的 `GET` 分支。把它们当作「本地任何东西都能读」。
538-
- **受门控的路由(配了 token 之后)**:全部写操作(`/create`、`/update`、`/delete`、`/import`、`/mode`、`/features`、`/commands`、`/conflicts/resolve`、`PUT /profile`、`PUT /rules`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/health`)以及敏感读 `/export`、`/external-api`。
537+
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/llm-providers`,以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands` 的 `GET`/`HEAD` 分支。把它们当作「本地任何东西都能读」。
538+
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`,以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands` 的非 `GET` 分支——外加四条读:`/export`、`/external-api`、`/conflicts`、`/health`。
539539
- **独立数据面**(`127.0.0.1:8790`)是反过来的形状:除 `GET /health` 外每条路由都要自己的 Bearer token。因此把 `externalApiHost` 指向非回环地址,就等于把它变成一个「明文、只靠 token」的 HTTP 面——这是运营者的显式决定。
540540
- **推论**:如果你把插件暴露到回环之外(反代、绑非回环地址),请设 `apiToken`,**并**核对上面那串开放读是否也能被看到——它们不受 token 保护。
541-
- **这张表怎么保持为真**:每条路由在注册时自己声明 `policy`(`open` / `token` / `token-write`),`createRouteRegistrar` 在路由没声明或复用同一路径时直接抛错。新路由忘了归类会**启动失败**,而不是静默开门——上面这张矩阵来自代码,不来自谁的记忆。
541+
- **这张表怎么保持为真**:每条路由在注册时自己声明 `policy`(`open` / `token` / `token-write`),`createRouteRegistrar` 在路由没声明或复用同一路径时直接抛错。新路由忘了归类会**启动失败**,而不是静默开门。上面两张清单还会被 `dsh-mneme/test/security-doc.test.js` 拿真实装配出来的路由做双向比对——加了路由却不更新这一节,CI 会红,而不是悄悄漂走。这张矩阵来自代码,不来自谁的记忆。
542542

543543
---
544544

‎dsh-mneme/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
[![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
66
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
77
[![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
8-
[![tests](https://img.shields.io/badge/tests-2131%20passed-success)](https://github.com/slow-stack/mneme)
8+
[![tests](https://img.shields.io/badge/tests-2137%20passed-success)](https://github.com/slow-stack/mneme)
99
[![CI](https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml)](https://github.com/slow-stack/mneme/actions)
1010
[![node](https://img.shields.io/badge/node-22%2B-blue)](https://nodejs.org)
1111
[![npm downloads](https://img.shields.io/npm/d18m/@modusensus/dsh-mneme.svg?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -673,7 +673,7 @@ src/
673673
├── api.js # HTTP 路由(Web 面板数据通道,含 /conflicts 冲突队列)
674674
└── index.js # 插件接线
675675
lib/ # src 的同步分发产物(npm run sync;发布前由 root prepack 的 check-sync.js 校验一致性;唯一手写例外 lib/client.js——Web 面板 bundle,sync 不覆盖)
676-
test/ # 2131 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
676+
test/ # 2137 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
677677
scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js / benchmark-embed.js / benchmark-rerank.js 基准 · sync-test-badge.mjs 测试徽章 · build-runtime-manifest.mjs 运行时清单
678678
```
679679
@@ -682,7 +682,7 @@ scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
682682
```bash
683683
cd dsh-mneme
684684
npm install # 安装 peer 依赖(以 devDependencies 形式,用于本地测试)
685-
npm test # 运行 2131 个测试
685+
npm test # 运行 2137 个测试
686686
npm run stress # 三轴线压测:长会话检索 / 冲突仲裁 / 多 Agent 并发(离线 mock LLM)
687687
npm run sync # 把 src/ 同步到 lib/(发布时由 prepack 钩子自动执行)
688688
```

‎dsh-mneme/test/security-doc.test.js‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ import assert from "node:assert/strict";
88
import { readFileSync, existsSync } from "node:fs";
99
import { fileURLToPath } from "node:url";
1010
import path from "node:path";
11+
import { createStore } from "../src/store.js";
12+
import { createService } from "../src/service.js";
13+
import { createSettings } from "../src/settings.js";
14+
import { createApi } from "../src/api.js";
1115

1216
const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
1317
const repoRoot = path.dirname(pkgRoot);
@@ -68,3 +72,68 @@ test("SECURITY.md 不再把供应商写成已停用的那家", () => {
6872
// 文档里曾长期写着第三方商业扫描平台(该平台并不在 CI 里跑)。
6973
assert.ok(!/OrbisAI/i.test(doc), "依赖扫描工具应写 CI 里真实在跑的那几个,不能留旧供应商名");
7074
});
75+
76+
// 安全模型节那两张路由清单是「从代码抄出来的」,抄错了没人会发现:
77+
// 实测就漏过 /persona(token-write,GET 开放)与 /conflicts(token,只读也要 token)。
78+
// 这里不重跑鉴权逻辑(那是 route-policy.test.js 的事),只锁「文档清单 == 代码里的 policy 声明」:
79+
// 以真实装配出来的路由为准,双向比对——文档少写、多写、写错边,都红。
80+
function declaredRoutes() {
81+
const store = createStore(":memory:");
82+
const service = createService({ store, mirror: null, config: {} });
83+
const settings = createSettings(store.db);
84+
const mounted = [];
85+
createApi(
86+
{ webServer: { register(route) { mounted.push(route); return () => {}; } } },
87+
service, settings, { add() {}, remove() {}, list: () => [] }, null, undefined, "secret-token"
88+
);
89+
// 路由名去掉公共前缀,文档里写的是 /export 而不是 /api/dsh-mneme/export。
90+
return mounted.map((route) => ({
91+
name: route.path.replace("/api/dsh-mneme", "") || "/",
92+
policy: route.policy
93+
}));
94+
}
95+
96+
// 从清单行里抠出反引号包着的路由。只认「可选方法 + 斜杠开头」的形状,
97+
// 这样 `GET`/`HEAD` 这种纯方法名不会被当成路径。
98+
function routesInBullet(line) {
99+
const out = [];
100+
for (const m of line.matchAll(/`([^`]+)`/g)) {
101+
const hit = m[1].trim().match(/^(?:GET|HEAD|POST|PUT|PATCH|DELETE)?\s*(\/\S*)$/);
102+
if (hit) out.push(hit[1]);
103+
}
104+
return out;
105+
}
106+
107+
function bullet(prefix) {
108+
const line = doc.split(/\r?\n/).find((l) => l.startsWith(prefix));
109+
assert.ok(line, `SECURITY.md 里应有以「${prefix}」开头的清单行`);
110+
return routesInBullet(line);
111+
}
112+
113+
// 文档里的 /semantic/graph/* 覆盖代码里的 /semantic/graph/ego 与 /semantic/graph/entity-attrs。
114+
function covers(docEntry, name) {
115+
if (docEntry === name) return true;
116+
return docEntry.endsWith("/*") && name.startsWith(docEntry.slice(0, -1));
117+
}
118+
119+
test("SECURITY.md 的开放读清单与代码里的 policy 声明一致", () => {
120+
const open = declaredRoutes().filter((r) => r.policy === "open" || r.policy === "token-write");
121+
for (const prefix of ["- **Open reads", "- **开放读"]) {
122+
const listed = bullet(prefix);
123+
const missing = open.filter((r) => !listed.some((e) => covers(e, r.name))).map((r) => r.name);
124+
assert.deepEqual(missing, [], `${prefix} 漏了这些实际开放的路由:${missing.join(", ")}`);
125+
const stale = listed.filter((e) => !open.some((r) => covers(e, r.name)));
126+
assert.deepEqual(stale, [], `${prefix} 写了代码里并不开放的路由:${stale.join(", ")}`);
127+
}
128+
});
129+
130+
test("SECURITY.md 的受门控清单与代码里的 policy 声明一致", () => {
131+
const gated = declaredRoutes().filter((r) => r.policy === "token" || r.policy === "token-write");
132+
for (const prefix of ["- **Gated routes", "- **受门控的路由"]) {
133+
const listed = bullet(prefix);
134+
const missing = gated.filter((r) => !listed.some((e) => covers(e, r.name))).map((r) => r.name);
135+
assert.deepEqual(missing, [], `${prefix} 漏了这些实际受门控的路由:${missing.join(", ")}`);
136+
const stale = listed.filter((e) => !gated.some((r) => covers(e, r.name)));
137+
assert.deepEqual(stale, [], `${prefix} 写了代码里并不受门控的路由:${stale.join(", ")}`);
138+
}
139+
});

0 commit comments

Comments
 (0)