dsh-railkeeper 0.1.0 → 0.1.1

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/README.md CHANGED
@@ -50,7 +50,13 @@ The one internal seam it does use: rewriting a slot registration's `options` doe
50
50
 
51
51
  ## HTTP surface
52
52
 
53
- All endpoints live under `/railkeeper/api`, are reachable only from loopback, and are also fenced by `Host`; write requests additionally require same-origin (or no `Origin` at all, which is the Desktop IPC bridge).
53
+ All endpoints live under `/railkeeper/api` and pass three admission layers, in this order:
54
+
55
+ 1. **DSH's own trust fence** — every request asks `ctx.connection.requestRejection(req)` first. Routes mounted with `webServer.register` do not go through DSH's Host/Origin admission on their own, so the plugin has to ask. This is the authoritative check.
56
+ 2. **A local fallback** — the socket peer must be loopback *and* the `Host` header must name a loopback authority. Comparing only `Origin` against `Host` is bypassable by DNS rebinding, where both become the attacker's domain; requiring a loopback `Host` is what actually stops it. `sec-fetch-site: cross-site` is refused.
57
+ 3. **JSON for writes** — `POST`/`PUT` must declare `application/json`. A cross-site form cannot send that without a preflight, so this closes the simple-request CSRF class. The browser half always sends it.
58
+
59
+ A `403` from the fence is rejected outright. A `401` (trustworthy but unauthenticated) is *not*: the desktop page is loaded over `dsh-app://`, not `http://127.0.0.1`, so its `fetch` may not carry the auth cookie — refusing that would blank the UI. It falls through to layer 2, which still blocks the cross-site shapes.
54
60
 
55
61
  | Method | Path | Purpose |
56
62
  |---|---|---|
package/README.zh-CN.md CHANGED
@@ -50,7 +50,13 @@ Railkeeper 刻意**不依赖**任何 Harness 客户端包(React 除外):
50
50
 
51
51
  ## HTTP 接口
52
52
 
53
- 全部挂在 `/railkeeper/api` 下,只允许回环访问,并额外校验 `Host`;写请求还要求同源(完全没有 `Origin` 的情况放行,那是桌面版的 IPC 桥)。
53
+ 全部挂在 `/railkeeper/api` 下,按顺序过三道准入:
54
+
55
+ 1. **DSH 自己的信任栅栏** —— 每个请求先问 `ctx.connection.requestRejection(req)`。用 `webServer.register` 挂上的路由**不经过** DSH 自己的 Host/Origin 准入,所以插件必须主动问。这一层是权威判据。
56
+ 2. **本地兜底** —— socket 对端必须是回环,且 `Host` 头必须是回环权威。为什么不能只比 `Origin` 与 `Host`:DNS rebinding 之后两者会一起变成攻击者的域名,比较相等反而通过;要求 `Host` 是回环才真的挡住。`sec-fetch-site: cross-site` 一律拒绝。
57
+ 3. **写请求必须是 JSON** —— `POST`/`PUT` 必须声明 `application/json`。跨站表单无法不带预检就发这个头,于是简单请求类 CSRF 被挡住。浏览器半区一直是这么发的。
58
+
59
+ 栅栏返回 `403` 直接拒;返回 `401`(可信但未认证)**不**拒:桌面端页面由 `dsh-app://` 加载,不是 `http://127.0.0.1`,它的 `fetch` 不一定带得上 auth cookie,一律拒会把界面掐死。`401` 交给第 2 层判,跨站形态仍被挡住。
54
60
 
55
61
  | 方法 | 路径 | 用途 |
56
62
  |---|---|---|
package/docs/DETAIL.md CHANGED
@@ -53,6 +53,12 @@ One JSON document at `$DSH_HOME/railkeeper.json`, split per profile:
53
53
  - Rows for panels that are not currently registered are kept, so reinstalling a plugin restores its position. They are listed under "Configured but not installed".
54
54
  - An invalid document is never written. On read, a corrupt file is copied to `railkeeper.json.corrupt-<timestamp>` and an empty configuration is served; the file is never deleted.
55
55
 
56
+ ## Route access
57
+
58
+ `/railkeeper/api/*` is mounted with `webServer.register`, which DSH does **not** put behind its own Host/Origin admission. Railkeeper therefore asks `ctx.connection.requestRejection(req)` itself on every request, then falls back to requiring a loopback peer and a loopback `Host` (a plain `Origin`-versus-`Host` comparison is bypassable by DNS rebinding), then requires `application/json` on writes.
59
+
60
+ A `403` from the fence is honoured. A `401` falls through to the loopback check instead of being refused, because the desktop page is served from `dsh-app://` and its `fetch` may not carry the auth cookie; refusing it would blank the UI while blocking nothing extra — cross-site shapes still fail the loopback check.
61
+
56
62
  ## Self-test
57
63
 
58
64
  Shortly after load, railkeeper runs an invisible self-test (the menu it opens is not painted and does not take focus) over the two paths that fail silently: selecting a panel through `layout.selectPanel`, and clicking a flyout item through a real `MouseEvent`. Results are `selectProbe` and `clickProbe` in `GET /railkeeper/api/client-status`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-railkeeper",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Railkeeper for DeepSeek Harness: reorder, rename, hide, re-icon and group the left rail panels. Changes apply instantly and survive restarts.",
5
5
  "repository": {
6
6
  "type": "git",
package/src/host/index.js CHANGED
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * dsh-railkeeper —— 宿主半区入口。
3
3
  *
4
- * 只做两件事:建配置存储、把 loopback API 挂到 webServer 上。
5
- * 不依赖任何硬服务;profile 没有 webServer 时插件保持静默(界面半区会
6
- * 显示“宿主不可用”而不是整包失败)。
4
+ * 做三件事:建配置存储、取到 DSH 的浏览器信任栅栏、把 API 挂到 webServer 上。
5
+ * 不声明硬依赖;profile 没有 webServer 时插件保持静默(界面半区会显示
6
+ * “宿主不可用”而不是整包失败),没有 connection 时路由退回自己的本地判据。
7
7
  */
8
8
  import { ConfigStore } from './store.js'
9
9
  import { API_PREFIX, createApiHandler } from './routes.js'
@@ -23,7 +23,41 @@ export function apply(ctx, config) {
23
23
  home: config?.home,
24
24
  profileId: config?.profileId,
25
25
  })
26
- const handler = createApiHandler(store)
26
+ /**
27
+ * DSH 的浏览器信任栅栏(`ctx.connection.requestRejection`)。
28
+ *
29
+ * 为什么必须主动取:`webServer.register` 挂上的路由**不经过** DSH 自己的
30
+ * Host/Origin 准入,所以插件得自己去问一次。官方 web 面插件
31
+ * (dsh-host-open-in-app)把 connection 声明成硬依赖;这里按可选服务取,
32
+ * 保留本插件“缺服务只降级、不整个加载失败”的性质 —— 没有 connection 就是
33
+ * 没有 web carrier,也就没有浏览器请求需要防。
34
+ */
35
+ let connectionService
36
+ ctx.inject(['connection'], (scope) => {
37
+ try {
38
+ const service = scope.get('connection')
39
+ if (service !== undefined && service !== null) connectionService = service
40
+ } catch {
41
+ connectionService = undefined
42
+ }
43
+ })
44
+
45
+ /**
46
+ * 问 DSH 这道栅栏放不放行。
47
+ * @param {import('node:http').IncomingMessage} req
48
+ * @returns {number | undefined} 非 undefined 表示应以此状态码拒绝
49
+ */
50
+ function requestRejection(req) {
51
+ const service = connectionService
52
+ if (service === undefined || typeof service.requestRejection !== 'function') return undefined
53
+ try {
54
+ return service.requestRejection(req)
55
+ } catch {
56
+ return undefined
57
+ }
58
+ }
59
+
60
+ const handler = createApiHandler(store, { requestRejection })
27
61
 
28
62
  ctx.inject(['webServer'], (webCtx) => {
29
63
  const webServer = webCtx.reflect.get('webServer')
@@ -10,9 +10,21 @@
10
10
  * GET /client-status 读取最近的上报
11
11
  * GET /legacy 读取 dsh-panellist 的旧配置并转换形状(迁移用)
12
12
  *
13
- * 两道栅栏:
14
- * - loopback:socket 对端必须是本机回环,且 Host 头必须是回环权威;
15
- * - 写入来源:带 Origin 的写请求必须与 Host 同源(DNS rebinding 防护)。
13
+ * 三层准入,缺一不可:
14
+ *
15
+ * 1. **DSH 的信任栅栏**(`ctx.connection.requestRejection`,见 ../host/index.js)。
16
+ * `webServer.register` 挂上的路由不经过 DSH 自己的 Host/Origin 准入,所以
17
+ * 插件必须主动去问它。这一层是权威判据。
18
+ * 2. **本地兜底**(`isLoopbackRequest`):socket 对端是回环,且 Host 头是回环
19
+ * 权威。为什么不能只比 Origin 与 Host:DNS rebinding 之后两者会一起变成
20
+ * 攻击者的域名,比较相等反而通过;要求 Host 是回环才真的挡住。
21
+ * 3. **写请求必须是 JSON**(`isJsonRequest`):浏览器对 application/json 会先
22
+ * 发预检,跨站表单无法自带这个头,于是简单请求类 CSRF 被挡在外面。
23
+ *
24
+ * 对 401 与 403 区别对待:403 是 Host/Origin 栅栏拒绝;401 是"可信但未认证"。
25
+ * 桌面端页面由 `dsh-app://` 协议加载,与 127.0.0.1 不同源,它的 fetch 不一定
26
+ * 带得上 auth cookie —— 一律按 401 拒会把界面读数整个掐死,所以 401 交给第 2
27
+ * 层判(跨站形态仍被第 2 层挡住)。
16
28
  */
17
29
  import { SCHEMA_VERSION } from '../shared/config.js'
18
30
 
@@ -72,6 +84,19 @@ function hasSameOrigin(req) {
72
84
  }
73
85
  }
74
86
 
87
+ /**
88
+ * 写请求是否声明了 JSON 请求体。
89
+ *
90
+ * 浏览器对 `application/json` 会先发预检,跨站表单无法伪造这个头,所以
91
+ * "必须声明 JSON"本身就是一条 CSRF 防线(简单请求类)。
92
+ * @param {import('node:http').IncomingMessage} req
93
+ */
94
+ function isJsonRequest(req) {
95
+ const raw = req.headers['content-type']
96
+ if (typeof raw !== 'string') return false
97
+ return raw.split(';')[0].trim().toLowerCase() === 'application/json'
98
+ }
99
+
75
100
  /**
76
101
  * 读取请求体并解析为 JSON。
77
102
  * @param {import('node:http').IncomingMessage} req
@@ -145,7 +170,7 @@ function respondError(res, status, error, details) {
145
170
  * 创建前缀路由处理函数。
146
171
  * @param {import('./store.js').ConfigStore} store
147
172
  */
148
- export function createApiHandler(store) {
173
+ export function createApiHandler(store, hooks = {}) {
149
174
  /** @type {Array<Record<string, unknown>>} */
150
175
  const clientRecords = []
151
176
 
@@ -155,10 +180,32 @@ export function createApiHandler(store) {
155
180
  */
156
181
  return function handle(req, res) {
157
182
  void (async () => {
183
+ // 第 1 层:DSH 自己的信任栅栏(web carrier 在时才有)。
184
+ // `webServer.register` 挂的路由不经过 DSH 的准入,所以必须主动问一次。
185
+ if (typeof hooks.requestRejection === 'function') {
186
+ let rejection
187
+ try {
188
+ rejection = hooks.requestRejection(req)
189
+ } catch {
190
+ rejection = undefined
191
+ }
192
+ if (rejection === 403) {
193
+ respondError(res, 403, 'request rejected')
194
+ return
195
+ }
196
+ // 401(可信但未认证)不在此拒绝:见文件头说明,交给第 2 层。
197
+ }
198
+ // 第 2 层:本地兜底(回环对端 + 回环 Host)。
158
199
  if (!isLoopbackRequest(req)) {
159
200
  respondError(res, 403, 'loopback access only')
160
201
  return
161
202
  }
203
+ // 第 3 层:写请求必须声明 JSON。
204
+ const rawMethod = (req.method ?? 'GET').toUpperCase()
205
+ if ((rawMethod === 'POST' || rawMethod === 'PUT') && !isJsonRequest(req)) {
206
+ respondError(res, 415, 'content-type must be application/json')
207
+ return
208
+ }
162
209
  let url
163
210
  try {
164
211
  url = new URL(req.url ?? '/', 'http://localhost')
@@ -14,9 +14,9 @@ import { normalizeConfig } from '../src/shared/config.js'
14
14
  const tempHome = () => mkdtemp(join(tmpdir(), 'railkeeper-test-'))
15
15
 
16
16
  /** 起一个真的 HTTP 服务,走完整的请求路径而不是直接调 handler。 */
17
- async function withServer(home, run) {
17
+ async function withServer(home, run, hooks = {}) {
18
18
  const store = new ConfigStore({ home, profileId: 'test' })
19
- const server = createServer(createApiHandler(store))
19
+ const server = createServer(createApiHandler(store, hooks))
20
20
  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
21
21
  const { port } = server.address()
22
22
  const base = `http://127.0.0.1:${port}${API_PREFIX}`
@@ -266,3 +266,57 @@ test('路由:现场上报在内存里保留最近若干条', async () => {
266
266
  assert.equal(records.records[0].profileId, 'test')
267
267
  })
268
268
  })
269
+
270
+ test('路由:DSH 栅栏返回 403 时直接拒绝', async () => {
271
+ const home = await tempHome()
272
+ await withServer(home, async ({ base }) => {
273
+ const response = await fetch(`${base}/health`)
274
+ assert.equal(response.status, 403)
275
+ }, { requestRejection: () => 403 })
276
+ })
277
+
278
+ test('路由:DSH 栅栏返回 401 时退回本地判据(回环请求放行)', async () => {
279
+ // 桌面端页面由 dsh-app:// 加载,与 127.0.0.1 不同源,fetch 不一定带得上
280
+ // auth cookie。一律按 401 拒会把界面读数整个掐死。
281
+ const home = await tempHome()
282
+ await withServer(home, async ({ base }) => {
283
+ const response = await fetch(`${base}/health`)
284
+ assert.equal(response.status, 200)
285
+ }, { requestRejection: () => 401 })
286
+ })
287
+
288
+ test('路由:DSH 栅栏自己抛错时不能让请求崩掉', async () => {
289
+ const home = await tempHome()
290
+ await withServer(home, async ({ base }) => {
291
+ const response = await fetch(`${base}/health`)
292
+ assert.equal(response.status, 200, '栅栏异常时退回本地判据,而不是 500')
293
+ }, {
294
+ requestRejection: () => {
295
+ throw new Error('service exploded')
296
+ },
297
+ })
298
+ })
299
+
300
+ test('路由:写请求不声明 JSON 时回 415', async () => {
301
+ const home = await tempHome()
302
+ await withServer(home, async ({ base }) => {
303
+ const response = await fetch(`${base}/config/reset`, {
304
+ method: 'POST',
305
+ headers: { 'content-type': 'text/plain' },
306
+ body: '{}',
307
+ })
308
+ assert.equal(response.status, 415)
309
+ })
310
+ })
311
+
312
+ test('路由:PUT 不声明 JSON 时同样回 415', async () => {
313
+ const home = await tempHome()
314
+ await withServer(home, async ({ base }) => {
315
+ const response = await fetch(`${base}/config`, {
316
+ method: 'PUT',
317
+ headers: { 'content-type': 'application/x-www-form-urlencoded' },
318
+ body: 'config=%7B%7D',
319
+ })
320
+ assert.equal(response.status, 415)
321
+ })
322
+ })