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 +7 -1
- package/README.zh-CN.md +7 -1
- package/docs/DETAIL.md +6 -0
- package/package.json +1 -1
- package/src/host/index.js +38 -4
- package/src/host/routes.js +51 -4
- package/test/host.test.mjs +56 -2
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
|
|
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`
|
|
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.
|
|
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
|
-
*
|
|
5
|
-
*
|
|
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
|
-
|
|
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')
|
package/src/host/routes.js
CHANGED
|
@@ -10,9 +10,21 @@
|
|
|
10
10
|
* GET /client-status 读取最近的上报
|
|
11
11
|
* GET /legacy 读取 dsh-panellist 的旧配置并转换形状(迁移用)
|
|
12
12
|
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
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')
|
package/test/host.test.mjs
CHANGED
|
@@ -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
|
+
})
|