dsh-lan-guard 0.3.1 → 0.3.2

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
@@ -1,169 +1,228 @@
1
1
  <h1 align="center">DSH LAN Guard</h1>
2
2
 
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>
3
+ <p align="center">Expose the desktop DSH Web UI to your LAN safely: a gated reverse proxy with self-signed HTTPS by default and a QR code to open it on a phone. DSH's own loopback binding and the official UI stay untouched.</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
6
  <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>
7
+ <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>
8
8
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F172A" alt="MIT"></a>
9
+ <img src="https://img.shields.io/badge/DSH-0.1.7--rc.2-4B6BFB" alt="DSH 0.1.7-rc.2">
9
10
  </p>
10
11
 
11
12
  <p align="center">English | <a href="README.zh.md">中文</a></p>
12
13
 
13
14
  <p align="center">
14
- <a href="#features">Features</a> ·
15
- <a href="#install">Install</a> ·
16
- <a href="#usage">Usage</a> ·
15
+ <a href="#what-it-does">What it does</a> ·
16
+ <a href="#quick-start">Quick start</a> ·
17
+ <a href="#settings">Settings</a> ·
17
18
  <a href="#compatibility">Compatibility</a> ·
18
- <a href="#configuration">Configuration</a> ·
19
+ <a href="#security-boundary">Security boundary</a> ·
19
20
  <a href="#troubleshooting">Troubleshooting</a> ·
20
- <a href="#security-boundary">Security</a> ·
21
- <a href="#uninstall">Uninstall</a> ·
22
- <a href="#development">Development</a>
21
+ <a href="CHANGELOG.md">Changelog</a>
23
22
  </p>
24
23
 
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.
24
+ > DSH LAN Guard is a DeepSeek Harness community plugin. It registers one section in the official settings page (`settings.section`), replaces no official layout, and modifies neither DSH source nor DSH's own listen binding.
25
+
26
+ DSH serves its Web UI on `127.0.0.1` only, and it deliberately refuses to bind `0.0.0.0`. This plugin leaves that binding alone and opens a **second, gated** listener on another port, proxying the official UI outward as-is: a password gate, self-signed HTTPS by default, a QR code to open it on a phone, and device pairing you can approve or block one by one. **One restart after install is all it takes** — no hand-written configuration.
26
27
 
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.
28
+ <p align="center">
29
+ <img src="./assets/settings-access.png" width="78%" alt="Settings → 局域网访问 → 扫码访问: running state, passwordless link and a scannable QR code">
30
+ </p>
28
31
 
29
- ## Features
32
+ ## What it does
30
33
 
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.
34
+ - **Gated reverse proxy** — relays HTTP and WebSocket end to end (including the official UI's `/api/remote.mux` long connection), rewrites `Host`/`Origin`, strips hop-by-hop headers, and answers `502` when the upstream is down. DSH's own binding and configuration are never touched.
35
+ - **LAN-ready by default, but reachable is not the same as enterable** — it binds `0.0.0.0`, so **one restart** after install is enough. The gate is on by default and **refuses every device until you set an access password**, and TLS is self-signed by default — nothing travels in clear. Switch to "this machine only" in the settings page if you prefer.
36
+ - **Two passwords** — PBKDF2-SHA256 (600,000 iterations). The **access password** logs visitor devices in; the **admin password** unlocks this settings page's management console (it falls back to the access password). Plus a `dsh_` passwordless link, persistent visitor sessions, per-IP lockout and CSRF checks.
37
+ - **Self-signed HTTPS by default, with a stable CA** — generates a `DSH LAN Guard CA` and signs a leaf certificate for the current NIC addresses. Changing IP only re-signs the leaf, so each device trusts the CA once.
38
+ - **Your own machine is never locked** — direct `127.0.0.1` access is physically unlocked (whoever can use this computer could change these settings anyway). Remote access follows `adminPolicy`: read-only (default), password-unlocked, or open.
39
+ - **Device pairing and permanent blocking** — a phone names itself once when it first passes the gate, receives an HttpOnly device-identity cookie, and appears under **已授权设备** (name / created / last used / source IP) where you can **revoke and block** it. Blocking does not rely on device fingerprinting: re-pairing with the access password from another browser is refused too, and unblocking is the only way back.
40
+ - **Settings inside the official page** — the "局域网访问" section has four tabs: QR access, authentication, authorised devices, and connection & certificates. All typography and colours use the official design tokens; **no official layout is replaced**.
41
+ - **Configurable port and listen scope** — defaults to `3081` (DSH's port + 1) and walks up to ten ports when that one is taken, with an availability check in the settings page. The listen scope toggles between "LAN (default)" and "this machine only"; both need a DSH restart.
38
42
  - **Optional mDNS** — off by default; advertises `_dsh-lan-guard._tcp` when enabled.
43
+ - **Update check** — the settings page shows "current version → latest on npm" with a copyable upgrade command. The plugin **never installs or restarts anything itself**.
44
+
45
+ ## Quick start
39
46
 
40
- ## Install
47
+ Requirements:
48
+
49
+ - DeepSeek Harness with a Web profile
50
+ - Node.js 20 or newer
51
+ - Verified DeepSeek Harness: `0.1.7-rc.2`
52
+
53
+ Install from npm:
41
54
 
42
55
  ```sh
43
- dsh plugin --profile web add dsh-lan-guard
56
+ dsh plugin --profile web add dsh-lan-guard@latest
44
57
  ```
45
58
 
46
- Then restart DSH once (the plugin's server half is loaded at startup) and open **Settings → 局域网访问**.
59
+ Install from GitHub:
47
60
 
48
- ## Usage
61
+ ```sh
62
+ dsh plugin --profile web add "github:idoall/dsh-lan-guard"
63
+ ```
49
64
 
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.
65
+ Install from a local clone:
55
66
 
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.
67
+ ```sh
68
+ git clone https://github.com/idoall/dsh-lan-guard.git
69
+ cd dsh-lan-guard
70
+ pnpm install && pnpm run build
71
+ dsh plugin --profile web add "link:$(pwd)"
72
+ ```
57
73
 
58
- ## Compatibility
74
+ Then **restart DSH once** and open **Settings → 局域网访问**. After that restart the plugin is already listening on the LAN (default `0.0.0.0:3081`, self-signed HTTPS + gate); all you do is:
59
75
 
60
- Current release: plugin **`0.3.1`** is verified against DeepSeek Harness **`0.1.7-rc.2`** (the latest release candidate).
76
+ 1. Set an **access password** (at least 8 characters) under **安全认证**. Until you do, the gate refuses every device.
77
+ 2. Check the **listen scope** under **连接与证书** (LAN by default) and pick the NIC to publish on — the NIC decides which IP the QR code / access URL uses and which addresses the self-signed certificate covers.
78
+ 3. Scan the QR under **扫码访问**, trust `DSH LAN Guard CA` once on the phone, enter the access password, and name the device. The phone then runs the official DSH UI.
61
79
 
62
- ### Which plugin version goes with which DeepSeek Harness version
80
+ > 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.
63
81
 
64
- | Plugin | Verified DeepSeek Harness | On npm | What that version is |
65
- | --- | --- | --- | --- |
66
- | **`0.3.1`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | `latest` | Verification release for DSH `0.1.7-rc.2`: no code change — compatibility metadata and this table updated |
67
- | `0.3.0` | `0.1.7-rc.1` | published | Device approval and permanent ban (F9); fixed the blank page when opening a shared `?auth=` link |
68
- | `0.2.0` | `0.1.7-rc.1` | published | Update detection; removed the bottom-right status pill; spacing fix |
69
- | `0.1.1` | `0.1.7-rc.1` | published | Documentation release: bilingual user README |
70
- | `0.1.0` | `0.1.7-rc.1` | published | First release: gated reverse proxy, self-signed HTTPS, device pairing, settings UI, QR access |
82
+ ## Settings
71
83
 
72
- - The declared range is `>=0.1.7-rc.1 <0.2.0` (`dsh.engines.dsh`), and `dsh.compatibility.dshReleases` records **`0.1.7-rc.2: compatible`** and `0.1.7-rc.1: compatible`.
73
- - **How `0.3.1` was verified on `0.1.7-rc.2`**: every host/client surface this plugin uses is present and unchanged — `webServer.register` / `indexTaps`, `connection.requestRejection`, `connection.authenticatedUrl`, the additive `settings.section` and `shell.overlay` seats, and `@deepseek-ai/schemastery` — and the plugin runs end-to-end (settings page, QR access, gate, proxy) on that release. No source change was required.
74
- - A DSH release that is not listed is **unverified** — test it before trusting it.
75
- - Install a specific version when it matters:
84
+ Everything lives under **Settings → 局域网访问**, in four tabs. The non-sensitive switches (`enabled`, `listenPort`, `listenHost`, `networkInterface`, `auth.mode`, `auth.adminPolicy`, `auth.adminProtection`, `auth.allowLoopback`, `auth.requirePairing`, `auth.requireApproval`) are editable directly; `listenPort` and `listenHost` take effect on the next DSH restart; `dataDir` and `tls.*` are startup fields that need a profile-patch edit.
76
85
 
77
- ```sh
78
- dsh plugin --profile web add dsh-lan-guard@0.3.1
79
- ```
86
+ | Setting | Default | Effect |
87
+ | --- | --- | --- |
88
+ | Listen scope | **LAN `0.0.0.0`** | Whether the LAN can reach the port. "This machine only `127.0.0.1`" is more conservative; needs a DSH restart. Both choices keep the gate and self-signed HTTPS in force. |
89
+ | Proxy port | **3081** | DSH's port + 1; walks up to ten ports when taken, with an availability check. Needs a DSH restart. |
90
+ | NIC to publish on | automatic | Decides which IP the QR code / access URL uses and which addresses the certificate covers; virtual NICs are de-prioritised and labelled. |
91
+ | Auth mode | **passwordless QR + password** | Also "password only" or "secure token only". Switching **revokes every existing visitor session**. |
92
+ | Access password | unset | The login password for visitor devices. **While unset, the gate refuses every device.** |
93
+ | Admin password | unset | Unlocks this settings page's management console; falls back to the access password. |
94
+ | Loopback exempt | **on** | Direct `127.0.0.1` access skips the gate (physically unlocked). |
95
+ | Require naming | **on** | A new device must name itself once before it appears in the device list. |
96
+ | Require approval | off | When on, a named device still needs your **批准** before it is let in. |
97
+ | TLS | **self-signed HTTPS** | Turning it off sends the gate password in clear; a non-loopback bind with TLS off is **refused at startup** unless you set `tls.allowInsecureLan: true`. |
80
98
 
81
- ## Configuration
99
+ <p align="center">
100
+ <img src="./assets/settings-connection.png" width="78%" alt="Connection &amp; certificates: the listen-scope switch between LAN (default) and this-machine-only, the proxy port with its availability check, and NIC selection">
101
+ </p>
82
102
 
83
- 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.**
103
+ The plugin reads its config from its Cordis entry. **Every key has a usable default, so a fresh install works as-is:**
84
104
 
85
105
  ```yaml
86
- enabled: true # master switch
87
- listenHost: 0.0.0.0 # default 127.0.0.1 (loopback only); set to face the LAN
88
- listenPort: 3081 # DSH port + 1; auto-walks up to 10 ports when taken
89
- upstreamOrigin: http://127.0.0.1:3080
90
- dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard
91
- networkInterface: en0 # optional: publish on one NIC (empty = automatic)
92
- tls:
93
- mode: self-signed # 'self-signed' (default) | 'provided' | 'off'
94
- allowInsecureLan: false # required acknowledgement for LAN plain HTTP
95
- mdns:
96
- enabled: false # advertise _dsh-lan-guard._tcp
97
- auth:
98
- mode: token_and_password # 'token_and_password' | 'password' | 'token'
99
- adminPolicy: local_only # 'local_only' (default) | 'password_unlock' | 'open'
100
- adminProtection: true # admin console needs the admin password
101
- allowLoopback: true # 127.0.0.1 visitors skip the gate (physically unlocked)
102
- requirePairing: true # new remote devices must name themselves once
106
+ # ~/.dsh/profiles/web/cordis.patch.yml (optional: write only what you want to change)
107
+ - id: dsh-lan-guard
108
+ config:
109
+ listenHost: 0.0.0.0 # LAN-facing by default; '127.0.0.1' = this machine only, or one NIC IP
110
+ listenPort: 3081 # DSH port + 1; auto-walks up to 10 ports when taken
111
+ networkInterface: en0 # optional: publish on one NIC (empty = automatic)
112
+ dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard # optional; this is the derived default
113
+ tls:
114
+ mode: self-signed # 'self-signed' (default) | 'provided' | 'off'
115
+ allowInsecureLan: false # required acknowledgement for LAN plain HTTP
116
+ mdns:
117
+ enabled: false # advertise _dsh-lan-guard._tcp
118
+ auth:
119
+ mode: token_and_password # 'token_and_password' | 'password' | 'token'
120
+ adminPolicy: local_only # 'local_only' (default) | 'password_unlock' | 'open'
121
+ adminProtection: true # admin console needs the admin password
122
+ allowLoopback: true # 127.0.0.1 visitors skip the gate (physically unlocked)
123
+ requirePairing: true # new remote devices must name themselves once
103
124
  ```
104
125
 
105
- Every key above can also be changed from the settings page (the non-sensitive ones are declared as volatile config fields).
126
+ `dataDir` is the only key that needs explaining: **omit it** and the plugin uses `<active profile>/data/dsh-lan-guard` (e.g. `~/.dsh/profiles/web/data/dsh-lan-guard`); **set it** and your value wins (a leading `~` is expanded). It only decides where the plugin's private state (password hashes, device-token hashes, sessions, self-signed CA) lives — never whether the plugin works.
106
127
 
107
- ## Device approval and permanent ban
128
+ <p align="center">
129
+ <img src="./assets/settings-security.png" width="78%" alt="Authentication: the three-way mode selector, access and admin password fields, and the loopback-exempt switch">
130
+ </p>
108
131
 
109
- Paired devices are listed under **Settings → 局域网访问 → 已授权设备** with three groups: **pending**, **approved** and **blocked**.
132
+ <p align="center">
133
+ <img src="./assets/settings-devices.png" width="78%" alt="Authorised devices: naming and admin-approval switches, plus the device list with revoke-and-block">
134
+ </p>
110
135
 
111
- - Turn on **新设备需要管理员批准** to require an explicit approval before a newly paired device is let in (off by default). A pending phone sees a "waiting for approval" page until you press **批准**.
112
- - **吊销并拉黑** cuts a device off permanently: its identity is blocked, and re-pairing with the access password from another browser is refused too. **解除拉黑** is the only way back.
113
- - This deliberately does not use device fingerprinting (which breaks whenever the browser or OS changes) — the operator decides, and the decision sticks.
136
+ ## Compatibility
114
137
 
115
- ## Updates
138
+ Current version: plugin **`0.3.2`**, verified on DeepSeek Harness **`0.1.7-rc.2`**.
116
139
 
117
- The settings page shows the running version next to the newest one on npm, with a **copyable** upgrade command:
140
+ | Plugin | Verified DeepSeek Harness | What this version is |
141
+ | --- | --- | --- |
142
+ | **`0.3.2`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Install and go: LAN-facing default + derived `dataDir`; Liquid Glass settings page at official sizes; single-line scrolling access URL |
143
+ | **`0.3.1`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Verification release for `0.1.7-rc.2`: no code change, only compatibility metadata |
144
+ | `0.3.0` | `0.1.7-rc.1` | Device approval and permanent blocking; fixed the blank page when opening a shared `?auth=` link |
145
+ | `0.2.0` | `0.1.7-rc.1` | Update check; removed the corner status pill; spacing fixes |
146
+ | `0.1.1` | `0.1.7-rc.1` | Documentation release: bilingual user READMEs |
147
+ | `0.1.0` | `0.1.7-rc.1` | First release: gated reverse proxy, self-signed HTTPS, device pairing, settings page, QR access |
118
148
 
119
- ```sh
120
- dsh plugin --profile web add dsh-lan-guard@latest
121
- ```
149
+ - Declared range `>=0.1.7-rc.1 <0.2.0` (`dsh.engines.dsh`); DSH versions not listed are **unverified** — verify them yourself before use.
150
+ - Host/client interfaces this plugin uses: `webServer.register` / `indexTaps`, `connection.requestRejection`, `connection.authenticatedUrl`, the additive `settings.section` seat, `@deepseek-ai/schemastery`, and `profileContext` (for deriving the default data directory).
151
+ - **Breaking default change (from `0.3.2`)**: `listenHost` now defaults to `0.0.0.0` instead of `127.0.0.1`, so one restart after install is enough; `0.3.1` and earlier default to loopback only. The gate and self-signed TLS defaults are unchanged (with no password the gate still refuses every device). See the [CHANGELOG](CHANGELOG.md).
122
152
 
123
- 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.
153
+ The official UI is reused with zero modifications and adapts on a phone viewport:
154
+
155
+ <p align="center">
156
+ <img src="./assets/mobile.png" width="30%" alt="The official DSH UI at a 390px phone viewport: the plugin only proxies, the interface is the official one">
157
+ </p>
158
+
159
+ ## Security boundary
160
+
161
+ - DSH's own listen address is never changed; the plugin modifies no DSH configuration, session data, or official UI.
162
+ - **Gate before listener** — the listener only opens after the gate object is constructed. The LAN-facing default is acceptable precisely because `auth.enabled` defaults to true, **the gate refuses every non-loopback device while no access password is set**, and TLS defaults to self-signed. All three must hold together.
163
+ - Secrets (`secrets.json`, `devices.json`, sessions) live in `dataDir` with mode `600`; passwords are stored only as PBKDF2-SHA256 hashes, a device token is returned in plaintext once and only its SHA-256 hash is stored, and **the passwordless-link token is never written to logs**.
164
+ - The proxy stamps every forwarded request with an unforgeable source marker so the host can tell "the machine's own operator" from "a visitor through the proxy".
165
+ - Loopback access is **physically unlocked by design** — whoever can use this computer could change these settings anyway.
166
+ - The access password is **shared**: revoking a device invalidates that device's identity cookie immediately, but the same browser can re-pair with the password. Permanently blocking one machine would need device fingerprinting or per-device tokens, which this project deliberately avoids.
167
+ - LAN only: no public tunnels, no IM bots, no port forwarding.
168
+ - The plugin **installs, restarts and pushes nothing**: you copy and run the upgrade command yourself.
124
169
 
125
170
  ## Troubleshooting
126
171
 
127
- **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.
172
+ **The phone says the certificate is not trusted.** The CA is self-signed: install/trust `DSH LAN Guard CA` once per device. Compare the SHA-256 fingerprint shown under **连接与证书** first.
128
173
 
129
- **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.
174
+ **The phone cannot connect at all.** Confirm both devices are on the same network and that the address matches the QR code, check for a VPN or a "private relay"-style feature intercepting traffic, and make sure the **listen scope** was not switched to "this machine only".
130
175
 
131
- **"配置的端口 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.
176
+ **The settings page says the port is open to the LAN but no access password is set.** That is the expected intermediate state: the port is reachable, but the gate refuses every device and leaks nothing. Set an access password under **安全认证**.
132
177
 
133
- **"此设备已被移除访问权限" (403).** The device was revoked under **已授权设备**. Delete that record to let it pair again.
178
+ **"Configured port X was taken; switched to Y."** Another program holds the port and the plugin walked forward. Change the port under **连接与证书** (with an availability check) or free it.
179
+
180
+ **"This device's access was removed" (403).** The device was revoked or blocked under **已授权设备**. Delete the record to let it pair again (a blocked device needs **解除拉黑** first).
134
181
 
135
182
  **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.
136
183
 
137
- **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.
184
+ **Every device needs the password again after I changed it.** That is intentional: changing the access password or switching the auth mode **revokes every existing visitor session**.
138
185
 
139
- **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.
186
+ **Plain HTTP on the LAN is refused.** A non-loopback `listenHost` with `tls.mode: 'off'` is rejected unless you set `tls.allowInsecureLan: true` — the gate password would otherwise travel in clear text.
140
187
 
141
- ## Security boundary
188
+ ## Upgrade
142
189
 
143
- - DSH's own listener is untouched; this plugin never edits DSH config or the official UI.
144
- - 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.
145
- - 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.
146
- - Loopback direct access is **physically unlocked by design** — anyone who can already use that machine can change these settings.
147
- - 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.
148
- - LAN-only by design: no public tunnels, no IM bots, no port forwarding.
190
+ The settings page shows "current version → latest on npm" with a **copyable** upgrade command:
191
+
192
+ ```sh
193
+ dsh plugin --profile web add dsh-lan-guard@latest
194
+ ```
195
+
196
+ The plugin **installs nothing and restarts nothing** — you run the command and then restart DSH once. The check only queries the public npm registry and caches results for six hours; when it cannot reach the registry it says so in the UI and leaves the gate and proxy untouched.
149
197
 
150
198
  ## Uninstall
151
199
 
152
200
  ```sh
153
201
  dsh plugin --profile web remove dsh-lan-guard
154
- rm -rf ~/.dsh/profiles/web/data/dsh-lan-guard # optional: removes secrets, devices and the CA
202
+ rm -rf ~/.dsh/profiles/web/data/dsh-lan-guard # optional: removes secrets, device records and the CA
155
203
  ```
156
204
 
157
205
  ## Development
158
206
 
159
207
  ```sh
160
208
  pnpm install
161
- pnpm test # unit + integration tests (typecheck included)
209
+ pnpm test # unit + integration tests (includes type checking)
162
210
  pnpm run build # bundles lib/index.js and lib/client.js
163
211
  pnpm run verify # typecheck + tests + build + pack dry-run
164
212
  ```
165
213
 
166
- 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).
214
+ The client half registers into the official additive `settings.section` seat; the host half mounts through the package's own `cordis.patch.yml`.
215
+
216
+ ## Release
217
+
218
+ Releases are tag-driven. Update `package.json`, move the matching CHANGELOG section out of `Unreleased`, write `release-notes/v<version>.md` with both language anchors, then push the release commit and tag:
219
+
220
+ ```sh
221
+ git tag v0.3.1
222
+ git push origin v0.3.1
223
+ ```
224
+
225
+ The release workflow checks that the tag matches the `package.json` version and that the notes carry both anchors, then runs `pnpm run verify`, packs the plugin, publishes through npm trusted publishing (OIDC), and creates a GitHub Release with the tarball attached.
167
226
 
168
227
  ## License
169
228