dsh-msg9-kit 0.2.0 → 0.2.2

package/README.md

@@ -73,6 +73,7 @@ themes alike.
 | `msg9_peers` | List the sibling workspaces' inboxes (address book for cross-workspace sync) |
 | `msg9_rotate` | Rotate the current workspace's key (recover from a lost/leaked key) |
 | `msg9_status` | Owner + current workspace + cursor + state file; `verify=true` checks the key |
+| `msg9_notify` | Pause/resume new-mail wake-ups for this instance (`on` / `off` / `status`) — the same mute switch as the panel bell |
 
 Plus `/msg9` to print the owner and the registered workspace inboxes.
 
@@ -137,10 +138,16 @@ The panel resolves the same workspace from the current session's `cwd` (the
 
 ## Install
 
+```bash
+dsh plugin --profile web add dsh-msg9-kit
+# then restart dsh web and refresh the browser
+```
+
+From source (for development):
+
 ```bash
 npm install && npm run build          # builds lib/index.js + lib/client.js
 bash scripts/install-personal.sh      # dsh plugin --profile web add <this dir>
-# then restart dsh web and refresh the browser
 ```
 
 The plugin is one Loader entry; its `dsh.client` manifest makes the browser load
@@ -200,6 +207,12 @@ State (`~/.dsh/msg9-kit/state.json`, 0600, written atomically):
 A state file that fails to parse is never silently discarded: it is copied to
 `state.json.corrupt-*` and reported, because it holds irreplaceable inbox keys.
 
+One `DSH_HOME` supports **one dsh instance**: writes are serialized with a
+`state.json.lock` file lock, so a second instance sharing the same state file
+fails loudly (`state file is locked by another process`) instead of silently
+overwriting irreplaceable inbox keys. Run each instance with its own
+`DSH_HOME` / `MSG9_STATE_FILE`.
+
 ## Typical use
 
 ```
@@ -219,8 +232,16 @@ what it sent, and the address book it messages most.
 
 ## HTTP bridge
 
-The panel talks to these same-origin routes (loopback / same-origin only, never
-a key in the response):
+The panel talks to these same-origin routes (never a key in the response).
+Requests are accepted only when the connection itself comes from loopback
+(`remoteAddress`), plus a same-origin `Origin` check for browsers — a forged
+`Host` header from another local process does not pass.
+
+Threat-model boundary (per audit): a local process connecting via loopback is
+still trusted — deliberately, since it could read `~/.dsh/msg9-kit/state.json`
+directly anyway; HTTP-layer defence cannot and need not keep out the machine's
+owner. What this check actually closes is remote clients forging `Host` when
+dsh web binds a non-loopback address, and cross-origin browser pages:
 
 | Route | Purpose |
 |---|---|

package/README.zh-CN.md

@@ -61,6 +61,7 @@
 | `msg9_peers` | 列出**兄弟 workspace** 的收件箱（跨 workspace 同步的地址簿） |
 | `msg9_rotate` | 轮换当前 workspace 的 key（本地 key 丢失/泄漏时恢复） |
 | `msg9_status` | owner + 当前 workspace + 游标 + 状态文件；`verify=true` 校验 key |
+| `msg9_notify` | 暂停/恢复本实例的新邮件唤醒（`on` / `off` / `status`）——和面板铃铛是同一个静音开关 |
 
 另有 `/msg9` 命令，打印 owner 与已登记的 workspace 收件箱。
 
@@ -102,10 +103,16 @@ dsh-<slug>-<hash4>@msg9.io
 
 ## 安装
 
+```bash
+dsh plugin --profile web add dsh-msg9-kit
+# 然后重启 dsh web 并刷新浏览器
+```
+
+从源码改装（开发时）：
+
 ```bash
 npm install && npm run build          # 产出 lib/index.js + lib/client.js
 bash scripts/install-personal.sh      # 等价于 dsh plugin --profile web add <本目录>
-# 然后重启 dsh web 并刷新浏览器
 ```
 
 插件只有一个 Loader entry，包内的 `dsh.client` 声明让浏览器从同一个包加载 `./client` 面，因此图标和面板无需额外配置。
@@ -155,6 +162,8 @@ bash scripts/install-personal.sh      # 等价于 dsh plugin --profile web add <
 
 状态文件解析失败时**不会**被静默清空：它会先被复制为 `state.json.corrupt-*` 再报错——因为里面存着不可再生的收件箱 key。
 
+一个 `DSH_HOME` 只支持**一个 dsh 实例**：写入前会对 `state.json.lock` 加文件锁，第二个共享同一状态文件的实例会响亮报错（`state file is locked by another process`），而不是互相覆盖不可再生的收件箱 key。多实例请各用各的 `DSH_HOME` / `MSG9_STATE_FILE`。
+
 ## 典型用法
 
 ```
@@ -173,7 +182,9 @@ msg9_send({ to: "dsh-alpha-a1b2@msg9.io", text: "schema 已更新", correlation_
 
 ## HTTP 桥
 
-面板调用的同源接口（只接受本机 / 同源请求，响应里永不含 key）：
+面板调用的同源接口（响应里永不含 key）。只接受连接来源本身是本机 loopback（`remoteAddress`）的请求，浏览器另有 `Origin` 同源校验——本机其他进程伪造 `Host` 头不再放行。
+
+威胁模型边界（审计澄清）：本机进程经 loopback 连接仍会被信任——这是有意的，因为这类进程本就可以直读 `~/.dsh/msg9-kit/state.json`，HTTP 层防不住也不必防「机器主人」。这层校验真正关掉的是：dsh web 绑定非 loopback 地址时远程伪造 `Host` 的客户端，以及跨源浏览器页面。
 
 | 路由 | 用途 |
 |---|---|