dsh-lan-guard 0.1.0 → 0.2.0
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/CHANGELOG.md +27 -3
- package/README.md +117 -67
- package/README.zh.md +115 -69
- package/lib/client.js +104 -66
- package/lib/client.js.map +1 -1
- package/lib/index.d.ts +45 -7
- package/lib/index.js +159 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,10 +1,34 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## [0.
|
|
3
|
+
## [0.2.0] — 2026-09-25
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### 新增 — 升级检测(SPEC F8,方案 A)
|
|
6
|
+
|
|
7
|
+
- **只读检测**:宿主查询 `https://registry.npmjs.org/dsh-lan-guard/latest`,与运行版本比较;成功/失败都缓存 **6 小时**,「检查更新」按钮可强制刷新(`?force=1`)。
|
|
8
|
+
- **新端点**:`GET /plugins/dsh-lan-guard/update[?force=1]`(管理面、只读、遵守原生栅栏)。
|
|
9
|
+
- **版本比较自实现**:支持 `x.y.z` 与预发布后缀(遵循 semver 优先级),**不引入 `semver` 依赖**。
|
|
10
|
+
- **失败即报告**:离线/注册表不可用 → `error: 'registry_unavailable'`,只提示、不抛错,不影响门禁与代理。
|
|
11
|
+
- **设置页 UI**:分区内芯片(绿「vX ✓ 最新」/ 蓝「vX ➔ vY」/ 灰「检查失败」)+「检查更新」+ 静态链接(GitHub / 更新日志 / 反馈 Issue);有新版时展开面板给出**可复制的升级命令**并提示「需你手动重启 dsh 才生效」。
|
|
12
|
+
- **明确不做**:不自动安装、不自动重启、不接 GitHub API(更新亮点改为指向仓库 CHANGELOG 的静态链接)——宿主只报告,操作权留在人手里。
|
|
13
|
+
- 测试:新增 `tests/update-check.test.ts`(9 项:版本解析/比较/预发布优先级、缓存与 force、注册表失败与网络异常均不抛错);`pnpm test` **219 项**全绿。
|
|
14
|
+
|
|
15
|
+
### 移除 — 右下角「局域网访问已开启」状态胶囊(P4-f)
|
|
16
|
+
|
|
17
|
+
用户反馈后移除。原因:该胶囊(官方追加型 seat `shell.overlay`)把**免密链接(含 `dsh_` token)常驻在屏幕右下角**——截屏或共享屏幕时会一并被拍到;且 `sessionStorage` 的「不再显示」只在当前标签页会话有效,**每次新会话都会再次出现**。
|
|
18
|
+
|
|
19
|
+
- 客户端不再注册任何 `shell.overlay` 内容(`StatusOverlay`、seat 常量与相关 CSS 一并删除);
|
|
20
|
+
- 局域网状态改由设置页「扫码访问」tab 呈现(状态胶囊「运行中」+ 地址 + 唯一二维码);
|
|
21
|
+
- SPEC F6 与 PLAN 的 P4-f 条目已标注为「移除」,不是「未实现」。
|
|
6
22
|
|
|
7
|
-
## [
|
|
23
|
+
## [0.1.1] — 2026-09-25
|
|
24
|
+
|
|
25
|
+
### 文档
|
|
26
|
+
|
|
27
|
+
- **README 重写为中英双语用户文档**(README.md / README.zh.md,各 147 行,结构与 dsh-update-status 对齐):徽章 + 语言互链 + 锚点导航 + 「能力 / 安装 / 使用 / 兼容性(含版本对应表)/ 配置(完整键表)/ 排障 / 安全边界 / 卸载 / 开发」;原先的「计划提供的能力」等实施前规划稿措辞已全部替换为已发布状态的描述。
|
|
28
|
+
|
|
29
|
+
## [0.1.0] — 2026-09-24
|
|
30
|
+
|
|
31
|
+
本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
8
32
|
|
|
9
33
|
### 实现 — P2 门禁 + 设置 UI(2026-09-24)
|
|
10
34
|
|
package/README.md
CHANGED
|
@@ -1,106 +1,156 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">DSH LAN Guard</h1>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">Use the official DeepSeek Harness Web UI from your phone — a gated reverse proxy on your LAN that never touches DSH's own loopback binding.</p>
|
|
4
4
|
|
|
5
|
-
>
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://www.npmjs.com/package/dsh-lan-guard"><img src="https://img.shields.io/npm/v/dsh-lan-guard?label=npm&color=CB3837" alt="npm version"></a>
|
|
7
|
+
<a href="https://github.com/idoall/dsh-lan-guard/actions/workflows/ci.yml"><img src="https://github.com/idoall/dsh-lan-guard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
8
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F172A" alt="MIT"></a>
|
|
9
|
+
</p>
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<p align="center">English | <a href="README.zh.md">中文</a></p>
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="#features">Features</a> ·
|
|
15
|
+
<a href="#install">Install</a> ·
|
|
16
|
+
<a href="#usage">Usage</a> ·
|
|
17
|
+
<a href="#compatibility">Compatibility</a> ·
|
|
18
|
+
<a href="#configuration">Configuration</a> ·
|
|
19
|
+
<a href="#troubleshooting">Troubleshooting</a> ·
|
|
20
|
+
<a href="#security-boundary">Security</a> ·
|
|
21
|
+
<a href="#uninstall">Uninstall</a> ·
|
|
22
|
+
<a href="#development">Development</a>
|
|
23
|
+
</p>
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
> DSH LAN Guard is a community plugin for DeepSeek Harness. It does not modify DSH core, does not change DSH's own listening address, and reuses the official Web UI unmodified.
|
|
12
26
|
|
|
13
|
-
|
|
14
|
-
- **The official Web UI is reused as-is** — no layout replacement, no UI hijacking;
|
|
15
|
-
- **Password-gated** — opening the port is not the point; who gets in is;
|
|
16
|
-
- **Self-signed HTTPS on by default** — it can be turned off; the settings page then explains the impact.
|
|
27
|
+
DSH serves its Web UI on `127.0.0.1` only, so phones and tablets cannot reach it, and DSH deliberately refuses to bind `0.0.0.0`. This plugin leaves that binding alone and runs a **second, gated port** that proxies the official UI to your LAN: password gate, self-signed HTTPS by default, a QR code to open it on a phone, and per-device pairing you can revoke one by one.
|
|
17
28
|
|
|
18
|
-
|
|
29
|
+
## Features
|
|
19
30
|
|
|
20
|
-
|
|
31
|
+
- **Gated reverse proxy** — full HTTP and WebSocket forwarding (the official UI's `/api/remote.mux` mux included), `Host`/`Origin` rewriting, hop-by-hop header stripping, `502` when the upstream is unreachable.
|
|
32
|
+
- **Password gate** — PBKDF2-SHA256 (600,000 iterations), a separate **access password** (phones) and **admin password** (this console), a `dsh_` passwordless link, persistent visitor sessions, per-IP lockout and CSRF checks.
|
|
33
|
+
- **Self-signed HTTPS by default** — generates its own `DSH LAN Guard CA`, issues a leaf certificate for the selected NIC address, and keeps the CA identity stable across restarts so devices only trust it once.
|
|
34
|
+
- **Your own machine is never locked** — direct `127.0.0.1` access is physically unlocked. Remote access follows `auth.adminPolicy`: read-only (default), password-unlocked, or open.
|
|
35
|
+
- **Per-device pairing** — a phone that passes the gate names itself once, receives an HttpOnly device cookie, appears in the settings page (name / created / last used / source IP) and can be revoked individually. A revoked device is refused with `403` immediately.
|
|
36
|
+
- **Settings inside the official page** — a "局域网访问" section with four tabs: QR access, authentication, authorised devices, connection & certificates. All typography and colours use the official design tokens; the official layout is never replaced.
|
|
37
|
+
- **Configurable port** — defaults to `3081` (DSH's port + 1), walks up to ten ports when that one is taken, editable in the settings page with an availability check.
|
|
38
|
+
- **Optional mDNS** — off by default; advertises `_dsh-lan-guard._tcp` when enabled.
|
|
21
39
|
|
|
22
|
-
|
|
40
|
+
## Install
|
|
23
41
|
|
|
24
|
-
|
|
42
|
+
```sh
|
|
43
|
+
dsh plugin --profile web add dsh-lan-guard
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Then restart DSH once (the plugin's server half is loaded at startup) and open **Settings → 局域网访问**.
|
|
47
|
+
|
|
48
|
+
## Usage
|
|
49
|
+
|
|
50
|
+
1. In **Settings → 局域网访问 → 安全认证**, set an **access password** (at least 8 characters). Until you do, the gate refuses every device.
|
|
51
|
+
2. In **连接与证书**, pick the NIC to publish on. `0.0.0.0` is the default for a configured plugin; set `listenHost: 127.0.0.1` in the config to keep it local-only while you try it out.
|
|
52
|
+
3. Open the **扫码访问** tab and scan the QR code with your phone.
|
|
53
|
+
4. On the phone: trust the `DSH LAN Guard CA` certificate (the SHA-256 fingerprint is shown in the settings page), enter the access password once, then **name the device** on the pairing page.
|
|
54
|
+
5. The phone now runs the official DSH UI. It appears under **已授权设备**, where you can revoke it at any time.
|
|
25
55
|
|
|
26
|
-
|
|
27
|
-
| --- | --- | --- |
|
|
28
|
-
| Gate | None, or relying on DSH's own cookie fence | Built-in password gate + per-IP lockout |
|
|
29
|
-
| UI | Some replace the official UI with a mobile-specific layout | **Official UI untouched** (so it does not drift with DSH releases) |
|
|
30
|
-
| DSH config | Some flip `host` to `0.0.0.0` | Leaves DSH's binding alone; proxies on a separate port |
|
|
31
|
-
| Transport | Usually plain HTTP | Self-signed HTTPS on by default, can be turned off |
|
|
56
|
+
> Remote devices are **read-only** by default (`adminPolicy: local_only`): they can use DSH but cannot change plugin settings. Switch the policy on the desktop if you want a phone to manage them.
|
|
32
57
|
|
|
33
|
-
|
|
58
|
+
## Compatibility
|
|
34
59
|
|
|
35
|
-
|
|
60
|
+
Current release: plugin **`0.1.0`** is verified against DeepSeek Harness **`0.1.7-rc.1`** (the latest release candidate).
|
|
36
61
|
|
|
37
|
-
|
|
38
|
-
- Request-header rewriting and upstream session-cookie injection (so proxied traffic looks like a local loopback request to DSH)
|
|
39
|
-
- Password gate: separate access and admin passwords, token links, persistent sessions, per-IP failure lockout
|
|
40
|
-
- Settings UI: mounted inside the **official DSH settings page** (registers an official seat; does not replace the official UI) for the gate, the access URL, and the QR code
|
|
41
|
-
- Self-signed HTTPS by default: long-lived CA plus a leaf certificate for the NIC's current IP; turning it off shows an impact notice
|
|
42
|
-
- LAN QR code: the settings page shows the current URL, with a password link and an admin-unlocked token link
|
|
43
|
-
- Multi-NIC detection and selection (virtual adapters down-ranked)
|
|
44
|
-
- Official Web UI left completely unchanged
|
|
62
|
+
### Which plugin version goes with which DeepSeek Harness version
|
|
45
63
|
|
|
46
|
-
|
|
64
|
+
| Plugin | Verified DeepSeek Harness | On npm | What that version is |
|
|
65
|
+
| --- | --- | --- | --- |
|
|
66
|
+
| **`0.1.0`** | `0.1.7-rc.1` | `latest` | First release: gated reverse proxy, self-signed HTTPS, device pairing, settings UI, QR access |
|
|
47
67
|
|
|
48
|
-
|
|
68
|
+
- The declared range is `>=0.1.7-rc.1 <0.2.0` (`dsh.engines.dsh`), and `dsh.compatibility.dshReleases` records `0.1.7-rc.1: compatible`.
|
|
69
|
+
- A DSH release that is not listed is **unverified** — test it before trusting it.
|
|
70
|
+
- Install a specific version when it matters:
|
|
49
71
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
- ❌ Modifying DSH source or its `host` binding
|
|
54
|
-
- ❌ Multi-user accounts
|
|
72
|
+
```sh
|
|
73
|
+
dsh plugin --profile web add dsh-lan-guard@0.1.0
|
|
74
|
+
```
|
|
55
75
|
|
|
56
|
-
|
|
76
|
+
## Configuration
|
|
57
77
|
|
|
58
|
-
|
|
78
|
+
The plugin reads its config from its Cordis entry (profile patch or `dsh plugin` config). Defaults are conservative: **nothing is published until you say so.**
|
|
59
79
|
|
|
60
|
-
|
|
80
|
+
```yaml
|
|
81
|
+
enabled: true # master switch
|
|
82
|
+
listenHost: 0.0.0.0 # default 127.0.0.1 (loopback only); set to face the LAN
|
|
83
|
+
listenPort: 3081 # DSH port + 1; auto-walks up to 10 ports when taken
|
|
84
|
+
upstreamOrigin: http://127.0.0.1:3080
|
|
85
|
+
dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard
|
|
86
|
+
networkInterface: en0 # optional: publish on one NIC (empty = automatic)
|
|
87
|
+
tls:
|
|
88
|
+
mode: self-signed # 'self-signed' (default) | 'provided' | 'off'
|
|
89
|
+
allowInsecureLan: false # required acknowledgement for LAN plain HTTP
|
|
90
|
+
mdns:
|
|
91
|
+
enabled: false # advertise _dsh-lan-guard._tcp
|
|
92
|
+
auth:
|
|
93
|
+
mode: token_and_password # 'token_and_password' | 'password' | 'token'
|
|
94
|
+
adminPolicy: local_only # 'local_only' (default) | 'password_unlock' | 'open'
|
|
95
|
+
adminProtection: true # admin console needs the admin password
|
|
96
|
+
allowLoopback: true # 127.0.0.1 visitors skip the gate (physically unlocked)
|
|
97
|
+
requirePairing: true # new remote devices must name themselves once
|
|
98
|
+
```
|
|
61
99
|
|
|
62
|
-
|
|
63
|
-
| --- | --- |
|
|
64
|
-
| `README.md` / [`README.zh.md`](README.zh.md) | Project overview (this file) |
|
|
65
|
-
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
|
|
66
|
-
| [`docs/SPEC.md`](docs/SPEC.md) | Technical specification: what it does and does not do |
|
|
67
|
-
| [`docs/PLAN.md`](docs/PLAN.md) | Staged implementation plan and acceptance criteria |
|
|
100
|
+
Every key above can also be changed from the settings page (the non-sensitive ones are declared as volatile config fields).
|
|
68
101
|
|
|
69
|
-
|
|
102
|
+
## Updates
|
|
70
103
|
|
|
71
|
-
|
|
72
|
-
| --- | --- |
|
|
73
|
-
| [`AGENTS.md`](AGENTS.md) | **AI collaboration charter**: responsibilities, red lines, stop points, workflow, drift self-check |
|
|
74
|
-
| [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) | Permission boundaries: allowed / forbidden / ask-first, responsibility matrix |
|
|
75
|
-
| [`docs/RESEARCH.md`](docs/RESEARCH.md) | Verified DSH facts baseline (with file paths and line numbers) |
|
|
76
|
-
| [`docs/RELEASE.md`](docs/RELEASE.md) | Release process and authorization levels |
|
|
104
|
+
The settings page shows the running version next to the newest one on npm, with a **copyable** upgrade command:
|
|
77
105
|
|
|
78
|
-
|
|
106
|
+
```sh
|
|
107
|
+
dsh plugin --profile web add dsh-lan-guard@latest
|
|
108
|
+
```
|
|
79
109
|
|
|
80
|
-
|
|
110
|
+
The plugin never installs anything by itself and never restarts DSH — run the command yourself and restart DSH once. The check only asks the public npm registry, is cached for six hours, and a failure is reported in the UI instead of breaking the gate.
|
|
81
111
|
|
|
82
|
-
##
|
|
112
|
+
## Troubleshooting
|
|
83
113
|
|
|
84
|
-
|
|
85
|
-
- A LAN is not a trusted network. Any device on the same subnet can attempt to connect, so the gate is mandatory, not optional;
|
|
86
|
-
- Self-signed HTTPS requires trusting the CA on the phone once;
|
|
87
|
-
- Passwords are stored as PBKDF2-SHA256 hashes; no plaintext credentials or private keys will ever appear in this repository.
|
|
114
|
+
**The phone shows a certificate warning.** The CA is self-signed: install/trust `DSH LAN Guard CA` once per device. Compare the fingerprint shown in **连接与证书** before trusting it.
|
|
88
115
|
|
|
89
|
-
|
|
116
|
+
**The phone cannot reach the address at all.** Check that the phone is on the same network, that the address matches the QR code, and that no VPN or "private relay" feature is intercepting traffic. The settings page shows the address the listener is actually bound to.
|
|
90
117
|
|
|
91
|
-
|
|
118
|
+
**"配置的端口 X 已被占用,已自动改用 Y".** Something else holds the port; the plugin moved on by itself. Set a different port in **连接与证书** (it has an availability check) or free the port.
|
|
92
119
|
|
|
93
|
-
|
|
120
|
+
**"此设备已被移除访问权限" (403).** The device was revoked under **已授权设备**. Delete that record to let it pair again.
|
|
121
|
+
|
|
122
|
+
**I forgot the access password.** On the machine that runs DSH, open `http://127.0.0.1:3080` (direct loopback access is physically unlocked) and set a new one. On a headless server, delete `secrets.json` in `dataDir` and set a new password — until then the gate refuses every device.
|
|
94
123
|
|
|
95
|
-
|
|
124
|
+
**Every device asks for the password again after I changed it.** That is intentional: changing the access password or the auth mode revokes every existing visitor session.
|
|
125
|
+
|
|
126
|
+
**Plain HTTP on the LAN is refused.** `listenHost` + `tls.mode: 'off'` is rejected unless you set `tls.allowInsecureLan: true` — the gate password would otherwise travel in clear text.
|
|
127
|
+
|
|
128
|
+
## Security boundary
|
|
129
|
+
|
|
130
|
+
- DSH's own listener is untouched; this plugin never edits DSH config or the official UI.
|
|
131
|
+
- Secrets (`secrets.json`, `devices.json`, sessions) live in `dataDir` with mode `600`; the plaintext device token is returned once and only its SHA-256 hash is stored.
|
|
132
|
+
- The gate applies before the listener is useful, and the proxy stamps every forwarded request with an unforgeable origin marker so the host can tell the machine's own operator from a proxied visitor.
|
|
133
|
+
- Loopback direct access is **physically unlocked by design** — anyone who can already use that machine can change these settings.
|
|
134
|
+
- The access password is **shared**: revoking a device invalidates that device's identity cookie immediately, but re-pairing with the password from another browser is still possible. A permanent per-machine ban would need device fingerprinting or per-device tokens.
|
|
135
|
+
- LAN-only by design: no public tunnels, no IM bots, no port forwarding.
|
|
136
|
+
|
|
137
|
+
## Uninstall
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
dsh plugin --profile web remove dsh-lan-guard
|
|
141
|
+
rm -rf ~/.dsh/profiles/web/data/dsh-lan-guard # optional: removes secrets, devices and the CA
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Development
|
|
96
145
|
|
|
97
146
|
```sh
|
|
98
147
|
pnpm install
|
|
99
|
-
pnpm test
|
|
100
|
-
pnpm run build
|
|
148
|
+
pnpm test # unit + integration tests (typecheck included)
|
|
149
|
+
pnpm run build # bundles lib/index.js and lib/client.js
|
|
150
|
+
pnpm run verify # typecheck + tests + build + pack dry-run
|
|
101
151
|
```
|
|
102
152
|
|
|
103
|
-
|
|
153
|
+
The design and verification record lives in [`docs/`](docs/) — `SPEC.md` (what it must do), `PLAN.md` (phase gates and what was verified when), `RESEARCH.md` (verified DSH facts), `GUARDRAILS.md` (red lines), `RELEASE.md` (release flow).
|
|
104
154
|
|
|
105
155
|
## License
|
|
106
156
|
|
package/README.zh.md
CHANGED
|
@@ -1,110 +1,156 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">DSH LAN Guard</h1>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">在手机上使用官方 DeepSeek Harness Web 界面——一个局域网内的门禁反向代理,不改动 DSH 自身的回环绑定。</p>
|
|
4
4
|
|
|
5
|
-
>
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://www.npmjs.com/package/dsh-lan-guard"><img src="https://img.shields.io/npm/v/dsh-lan-guard?label=npm&color=CB3837" alt="npm 版本"></a>
|
|
7
|
+
<a href="https://github.com/idoall/dsh-lan-guard/actions/workflows/ci.yml"><img src="https://github.com/idoall/dsh-lan-guard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
8
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F172A" alt="MIT"></a>
|
|
9
|
+
</p>
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<p align="center"><a href="README.md">English</a> | 中文</p>
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="#能力">能力</a> ·
|
|
15
|
+
<a href="#安装">安装</a> ·
|
|
16
|
+
<a href="#使用">使用</a> ·
|
|
17
|
+
<a href="#兼容性">兼容性</a> ·
|
|
18
|
+
<a href="#配置">配置</a> ·
|
|
19
|
+
<a href="#排障">排障</a> ·
|
|
20
|
+
<a href="#安全边界">安全边界</a> ·
|
|
21
|
+
<a href="#卸载">卸载</a> ·
|
|
22
|
+
<a href="#开发">开发</a>
|
|
23
|
+
</p>
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
> DSH LAN Guard 是 DeepSeek Harness 的社区插件。它**不修改 DSH 核心**、**不改动 DSH 自身的监听地址**,并**原样复用官方 Web UI**。
|
|
12
26
|
|
|
13
|
-
|
|
14
|
-
- **官方 Web UI 原样复用**——不替换、不劫持界面,手机上看到的就是官方界面;
|
|
15
|
-
- **带密码门禁**——端口不是敞开就完事,进来的人得先过门;
|
|
16
|
-
- **默认自签 HTTPS**——可关闭;关闭时设置页会说明明文传输和浏览器能力受限。
|
|
27
|
+
DSH 的 Web 界面只监听 `127.0.0.1`,手机、平板无法访问;而 DSH 官方明确拒绝绑定 `0.0.0.0`。本插件不碰那个绑定,而是另开一个**带门禁的端口**,把官方界面代理到局域网:密码门禁、默认自签 HTTPS、手机扫码入口,以及可逐个吊销的设备配对。
|
|
17
28
|
|
|
18
|
-
|
|
29
|
+
## 能力
|
|
19
30
|
|
|
20
|
-
|
|
31
|
+
- **门禁反向代理**:完整转发 HTTP 与 WebSocket(含官方界面的 `/api/remote.mux` 长连接),改写 `Host`/`Origin`,剥离逐跳头,上游不可达时返回 `502`。
|
|
32
|
+
- **密码门禁**:PBKDF2-SHA256(600,000 次迭代);**访问密码**(手机等访客)与**管理密码**(本管理台)分离;`dsh_` 免密链接;持久访客会话;按 IP 锁定与 CSRF 校验。
|
|
33
|
+
- **默认自签 HTTPS**:自动生成 `DSH LAN Guard CA`,按所选网卡地址签发叶证书;CA 身份跨重启不变,所以每台设备只需信任一次。
|
|
34
|
+
- **本机永不锁定**:直连 `127.0.0.1` 物理免锁;远程访问按 `auth.adminPolicy` 处理——只读(默认)、需密码解锁、或不锁。
|
|
35
|
+
- **设备配对**:远程设备通过门禁后自己命名一次,获得 HttpOnly 设备身份 cookie,出现在设置页(名称 / 创建时间 / 最近使用 / 来源 IP),可逐个吊销;被吊销的设备立刻收到 `403`。
|
|
36
|
+
- **设置挂在官方设置页内**:「局域网访问」分区含四个 tab——扫码访问、安全认证、已授权设备、连接与证书。排版与配色全部使用官方设计 token,**不替换任何官方布局**。
|
|
37
|
+
- **端口可配置**:默认 `3081`(DSH 端口 + 1),被占用时自动往后顺延(最多试 10 个),设置页可改并带可用性检查。
|
|
38
|
+
- **可选 mDNS**:默认关闭;开启后广播 `_dsh-lan-guard._tcp`。
|
|
21
39
|
|
|
22
|
-
|
|
40
|
+
## 安装
|
|
23
41
|
|
|
24
|
-
|
|
42
|
+
```sh
|
|
43
|
+
dsh plugin --profile web add dsh-lan-guard
|
|
44
|
+
```
|
|
25
45
|
|
|
26
|
-
|
|
46
|
+
然后**重启一次 DSH**(插件的服务端半边在启动时加载),打开 **设置 → 局域网访问**。
|
|
27
47
|
|
|
28
|
-
|
|
29
|
-
| --- | --- | --- |
|
|
30
|
-
| 门禁 | 无,或依赖 DSH 自身的 cookie 栅栏 | 自带密码门禁 + IP 失败锁定 |
|
|
31
|
-
| UI | 有的替换官方界面做手机专属布局 | **官方 UI 零改动**(因此不随 DSH 版本漂移) |
|
|
32
|
-
| DSH 配置 | 有的把 `host` 改成 `0.0.0.0` | 不动 DSH 绑定,代理在另一个端口 |
|
|
33
|
-
| 传输 | 多为明文 HTTP | 默认自签 HTTPS,可关闭 |
|
|
48
|
+
## 使用
|
|
34
49
|
|
|
35
|
-
|
|
50
|
+
1. 在 **设置 → 局域网访问 → 安全认证** 里设置**访问密码**(至少 8 位)。没设之前,门禁拒绝所有设备。
|
|
51
|
+
2. 在 **连接与证书** 里选择对外公布的网卡。配置后默认监听 `0.0.0.0`;想先本机试跑就把配置里的 `listenHost` 设为 `127.0.0.1`。
|
|
52
|
+
3. 打开 **扫码访问** tab,用手机扫描二维码。
|
|
53
|
+
4. 手机上:信任 `DSH LAN Guard CA` 证书(SHA-256 指纹在设置页可复制)、输入一次访问密码,然后在**配对页**给这台设备起个名字。
|
|
54
|
+
5. 手机现在运行的就是官方 DSH 界面。它会出现在 **已授权设备** 里,你可随时吊销。
|
|
36
55
|
|
|
37
|
-
|
|
56
|
+
> 远程设备默认是**只读**的(`adminPolicy: local_only`):能用 DSH,但不能改插件设置。想让手机也能管理,在桌面把策略改掉。
|
|
38
57
|
|
|
39
|
-
|
|
40
|
-
- 请求头改写与上游会话 cookie 注入(让代理流量在 DSH 看来是本机回环请求)
|
|
41
|
-
- 密码门禁:访问密码 + 独立管理密码、免密链接令牌、持久会话、按 IP 的失败锁定
|
|
42
|
-
- 设置界面:挂在 **DSH 官方设置页**里(注册官方 seat,不替换官方 UI),用于配置门禁、查看访问地址和扫码
|
|
43
|
-
- 默认自签 HTTPS:长期 CA + 按网卡 IP 签发的叶证书;可关闭,关闭时提示影响
|
|
44
|
-
- 局域网二维码:设置页展示当前地址,支持普通链接和需管理员解锁的免密链接
|
|
45
|
-
- 多网卡识别与选择(虚拟网卡降权)
|
|
46
|
-
- 官方 Web UI 零改动
|
|
58
|
+
## 兼容性
|
|
47
59
|
|
|
48
|
-
|
|
60
|
+
当前版本:插件 **`0.1.0`** 已在 DeepSeek Harness **`0.1.7-rc.1`**(最新候选版本)上验证通过。
|
|
49
61
|
|
|
50
|
-
|
|
62
|
+
### 插件版本与 DeepSeek Harness 版本的对应
|
|
51
63
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
- ❌ 修改 DSH 源码或其 `host` 绑定
|
|
56
|
-
- ❌ 多用户账号体系
|
|
64
|
+
| 插件 | 已验证的 DeepSeek Harness | npm 上 | 这个版本是什么 |
|
|
65
|
+
| --- | --- | --- | --- |
|
|
66
|
+
| **`0.1.0`** | `0.1.7-rc.1` | `latest` | 首个版本:门禁反向代理、自签 HTTPS、设备配对、设置页、扫码访问 |
|
|
57
67
|
|
|
58
|
-
|
|
68
|
+
- 声明范围 `>=0.1.7-rc.1 <0.2.0`(`dsh.engines.dsh`),`dsh.compatibility.dshReleases` 记录 `0.1.7-rc.1: compatible`。
|
|
69
|
+
- 未列入的 DSH 版本属**未验证**——请自行验证后再使用。
|
|
70
|
+
- 需要锁定版本时:
|
|
59
71
|
|
|
60
|
-
|
|
72
|
+
```sh
|
|
73
|
+
dsh plugin --profile web add dsh-lan-guard@0.1.0
|
|
74
|
+
```
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
## 配置
|
|
63
77
|
|
|
64
|
-
|
|
78
|
+
插件从它的 Cordis 条目读取配置(profile patch 或 `dsh plugin` 配置)。默认值保守:**你不开口,它不对外公布。**
|
|
65
79
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
80
|
+
```yaml
|
|
81
|
+
enabled: true # 总开关
|
|
82
|
+
listenHost: 0.0.0.0 # 默认 127.0.0.1(仅回环);要面向局域网需显式设置
|
|
83
|
+
listenPort: 3081 # DSH 端口 + 1;被占用时自动顺延(最多 10 个)
|
|
84
|
+
upstreamOrigin: http://127.0.0.1:3080
|
|
85
|
+
dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard
|
|
86
|
+
networkInterface: en0 # 可选:只在一个网卡上公布(留空 = 自动)
|
|
87
|
+
tls:
|
|
88
|
+
mode: self-signed # 'self-signed'(默认)| 'provided' | 'off'
|
|
89
|
+
allowInsecureLan: false # 局域网明文 HTTP 的显式风险确认
|
|
90
|
+
mdns:
|
|
91
|
+
enabled: false # 广播 _dsh-lan-guard._tcp
|
|
92
|
+
auth:
|
|
93
|
+
mode: token_and_password # 'token_and_password' | 'password' | 'token'
|
|
94
|
+
adminPolicy: local_only # 'local_only'(默认)| 'password_unlock' | 'open'
|
|
95
|
+
adminProtection: true # 管理台需要管理密码
|
|
96
|
+
allowLoopback: true # 127.0.0.1 访客跳过门禁(物理免锁)
|
|
97
|
+
requirePairing: true # 新的远程设备必须先命名一次
|
|
98
|
+
```
|
|
72
99
|
|
|
73
|
-
|
|
100
|
+
以上各项也可在设置页修改(非敏感项声明为 volatile 配置字段)。
|
|
74
101
|
|
|
75
|
-
|
|
76
|
-
| --- | --- |
|
|
77
|
-
| [`AGENTS.md`](AGENTS.md) | **AI 协作总纲**:职责、红线、停止点、工作流、漂移自检 |
|
|
78
|
-
| [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) | 权限边界:可做 / 不可做 / 必须先问、职责矩阵 |
|
|
79
|
-
| [`docs/RESEARCH.md`](docs/RESEARCH.md) | 已核实的 DSH 事实基线(含文件路径与行号) |
|
|
80
|
-
| [`docs/RELEASE.md`](docs/RELEASE.md) | 发布流程与授权级别 |
|
|
102
|
+
## 升级
|
|
81
103
|
|
|
82
|
-
|
|
104
|
+
设置页会显示「当前版本 → npm 上最新版本」,并给出**可复制**的升级命令:
|
|
83
105
|
|
|
84
|
-
|
|
106
|
+
```sh
|
|
107
|
+
dsh plugin --profile web add dsh-lan-guard@latest
|
|
108
|
+
```
|
|
85
109
|
|
|
86
|
-
|
|
110
|
+
本插件**不会自己安装任何东西,也不会重启 DSH**——命令由你执行,执行后手动重启一次 dsh。检测只访问公开的 npm registry,结果缓存 6 小时;连不上时只在界面上提示,不影响门禁与代理。
|
|
87
111
|
|
|
88
|
-
|
|
89
|
-
- 局域网不是可信网络。同网段的任何设备都能尝试连接,因此门禁是必需项而非可选项;
|
|
90
|
-
- 自签 HTTPS 需要在手机上一次性信任 CA 证书;
|
|
91
|
-
- 密码以 PBKDF2-SHA256 哈希存储,仓库内不会出现任何明文凭据或私钥。
|
|
112
|
+
## 排障
|
|
92
113
|
|
|
93
|
-
|
|
114
|
+
**手机提示证书不受信任。** CA 是自签的:每台设备安装/信任一次 `DSH LAN Guard CA`。信任前先比对 **连接与证书** 里显示的指纹。
|
|
94
115
|
|
|
95
|
-
|
|
116
|
+
**手机完全连不上。** 确认手机在同一网络、地址与二维码一致,并检查是否有 VPN 或「专用代理/中继」类功能拦截流量。设置页会显示监听器**实际绑定**的地址。
|
|
96
117
|
|
|
97
|
-
|
|
118
|
+
**「配置的端口 X 已被占用,已自动改用 Y」。** 端口被别的程序占着,插件已自行顺延。可在 **连接与证书** 换端口(带可用性检查),或释放该端口。
|
|
119
|
+
|
|
120
|
+
**「此设备已被移除访问权限」(403)。** 该设备已在 **已授权设备** 中被吊销。删除那条记录即可让它重新配对。
|
|
121
|
+
|
|
122
|
+
**我忘了访问密码。** 在运行 DSH 的电脑上直连 `http://127.0.0.1:3080`(本机直连物理免锁)重设。无头服务器则删除 `dataDir` 下的 `secrets.json` 后重设——在此之前门禁会拒绝所有设备。
|
|
123
|
+
|
|
124
|
+
**改过密码后所有设备都要重新输密码。** 这是有意的:更换访问密码或切换验证模式会**吊销所有已有访客会话**。
|
|
98
125
|
|
|
99
|
-
|
|
126
|
+
**局域网明文 HTTP 被拒绝。** `listenHost` + `tls.mode: 'off'` 会被拒绝,除非显式设置 `tls.allowInsecureLan: true`——否则门禁密码将明文传输。
|
|
127
|
+
|
|
128
|
+
## 安全边界
|
|
129
|
+
|
|
130
|
+
- DSH 自身的监听地址不被改动;本插件从不修改 DSH 配置或官方 UI。
|
|
131
|
+
- 密钥(`secrets.json`、`devices.json`、会话)存放在 `dataDir`,权限 `600`;设备令牌明文只返回一次,落盘只存 SHA-256 哈希。
|
|
132
|
+
- 门禁先于监听可用;代理给每个转发请求打上不可伪造的来源标记,宿主据此区分「本机操作者」与「经代理的访客」。
|
|
133
|
+
- 回环直连**按设计物理免锁**——能使用这台电脑的人本就能改这些设置。
|
|
134
|
+
- 访问密码是**共享**的:吊销设备会立即让该设备的身份 cookie 失效,但换个浏览器用密码仍可重新配对。要「同一台机器永久拉黑」需要设备指纹或每设备独立令牌。
|
|
135
|
+
- 只面向局域网:不做公网隧道、不做 IM Bot、不做端口转发。
|
|
136
|
+
|
|
137
|
+
## 卸载
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
dsh plugin --profile web remove dsh-lan-guard
|
|
141
|
+
rm -rf ~/.dsh/profiles/web/data/dsh-lan-guard # 可选:删除密钥、设备记录与 CA
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## 开发
|
|
100
145
|
|
|
101
146
|
```sh
|
|
102
147
|
pnpm install
|
|
103
|
-
pnpm test
|
|
104
|
-
pnpm run build
|
|
148
|
+
pnpm test # 单元 + 集成测试(含类型检查)
|
|
149
|
+
pnpm run build # 打包 lib/index.js 与 lib/client.js
|
|
150
|
+
pnpm run verify # 类型检查 + 测试 + 构建 + pack dry-run
|
|
105
151
|
```
|
|
106
152
|
|
|
107
|
-
|
|
153
|
+
设计与验证记录在 [`docs/`](docs/):`SPEC.md`(要做什么)、`PLAN.md`(阶段门禁与逐项验证记录)、`RESEARCH.md`(已核实的 DSH 事实)、`GUARDRAILS.md`(红线)、`RELEASE.md`(发布流程)。
|
|
108
154
|
|
|
109
155
|
## 许可
|
|
110
156
|
|