@bysir/herdr-web 0.4.0 → 0.5.1

package/README.md

@@ -80,7 +80,7 @@ The ⚙ at the right end of the top bar is the **settings panel**; its "Devices"
 
 **Out of codes? Go back to the machine and run `herdr-web pair`.** That is not laziness either — see below.
 
-The old never-expiring `~/.herdr-web/token` is demoted to **bootstrap only**: an old bookmark exchanges it for a device credential on first open and scrubs the token out of the URL, after which you should `rm ~/.herdr-web/token`. Details and reasoning in [SECURITY.md](SECURITY.md) (Chinese).
+The old never-expiring `~/.herdr-web/token` is demoted to **bootstrap only**: an old bookmark exchanges it for a device credential on first open and scrubs the token out of the URL, after which you should `rm ~/.herdr-web/token`. Details and reasoning in [SECURITY.md](docs/dev/SECURITY.md) (Chinese).
 
 Once connected it **types `herdr` for you**. To type something else, or nothing: `HERDR_WEB_ONCONNECT` (set it to an empty string to stay in the shell). Adding a path segment to the URL (`/work`) gives you **a different herdr session** — see [First run](#first-run). The old "run herdr" button in the top bar is gone: with autotyping it earns its place less than once a day, and the soft key bar ships a preset for it if you want one.
 
@@ -150,7 +150,7 @@ the page** (an image in the clipboard is uploaded directly). Where the path land
 the outbox is open — appended to your draft, or typed straight into the terminal.
 
 → Why a separate box at all, how images actually work, the two-way caveats, measured polling
-latency: [OUTBOX.md](OUTBOX.md)
+latency: [OUTBOX.md](docs/dev/OUTBOX.md)
 
 ### Soft key bar
 
@@ -166,7 +166,7 @@ Settings → Soft keys.
   the combination.
 - `act:` actions run in the browser and send no bytes: `act:kbd` (system keyboard), `act:img`
   (upload), `act:panes` (pane list), `act:files` (file browsing), `act:clip` / `act:paste`
-  ([copy and paste on a phone](MOBILE.md#手机上怎么复制--粘贴)).
+  ([copy and paste on a phone](docs/dev/MOBILE.md#手机上怎么复制--粘贴)).
 - Every key has a **"double-tap"** checkbox; close pane / close tab / `/clear` ship with it on —
   keys sit close together and a misfire cannot be undone.
 - "Load presets" pours sixty-odd keys into "My keys", after which every one of them is yours to edit.
@@ -189,8 +189,8 @@ It is an index, not a second interface: after the tap you are looking at the sam
 every keyboard habit is unchanged.
 
 → Sort order, the "3 minutes ago" column, when a notice fires, how the badge counts, system
-notifications: [MOBILE.md](MOBILE.md)
-　How that text is scraped off the screen: [COMPOSER.md](COMPOSER.md)
+notifications: [MOBILE.md](docs/dev/MOBILE.md)
+　How that text is scraped off the screen: [COMPOSER.md](docs/dev/COMPOSER.md)
 
 ### File browsing
 
@@ -208,7 +208,7 @@ allowlist would not stop them and would only get in the way daily. If you want o
 `HERDR_WEB_FILE_ROOTS` (that is a real jail); to remove the feature, `HERDR_WEB_FILES=0`.
 
 → The short-lived link route and the four hard rules on it (never `text/html`, why SVG is safe to
-render): [SECURITY.md](SECURITY.md)
+render): [SECURITY.md](docs/dev/SECURITY.md)
 
 ### Phones and tablets
 
@@ -234,7 +234,7 @@ row of keys. **Landscape and portrait keep separate sets**, swapped on rotation.
 arranged on a phone do not follow you to the desktop, while the definitions stay shared.
 
 → Why the gestures are split this way, how the keyboard is handled, copy and paste on a phone, the
-details of the dock and the top bar: [MOBILE.md](MOBILE.md)
+details of the dock and the top bar: [MOBILE.md](docs/dev/MOBILE.md)
 
 ### Settings panel
 
@@ -255,7 +255,7 @@ Keys the browser keeps for itself: on macOS `⌘W` `⌘T` `⌘N` `Ctrl+Tab`; on
 
 Copy `⌘C` (or `Ctrl+Shift+C`) · paste `⌘V` · clear `⌘K` · `Option` is Meta by default. Copy and
 paste on a phone is a different story — herdr copies to the clipboard of **the machine running
-herdr** — see [MOBILE.md](MOBILE.md#手机上怎么复制--粘贴).
+herdr** — see [MOBILE.md](docs/dev/MOBILE.md#手机上怎么复制--粘贴).
 
 ## Configuration
 
@@ -289,7 +289,7 @@ Changes take effect on restart — configuration is read once at startup. To con
 
 | Variable | Default | Meaning |
 |---|---|---|
-| `HERDR_WEB_PORT` | `7788` | Port |
+| `HERDR_WEB_PORT` | `7788` | The main port. **It only serves the local network**: a connection whose peer is not loopback / private / link-local / CGNAT gets 403 and nothing else. Public access is a separate, explicit port — see `HERDR_WEB_PUBLIC_PORT` |
 | `HERDR_WEB_HOST` | `127.0.0.1` | Listen address; `0.0.0.0` opens it to the LAN |
 | `HERDR_WEB_TOKEN` | reads `~/.herdr-web/token` | **Legacy**; only good for bootstrapping once (exchanged for a device credential). Not generated on new installs |
 | `HERDR_WEB_SHELL` | `$SHELL` | The shell run inside the PTY |
@@ -311,11 +311,12 @@ Changes take effect on restart — configuration is read once at startup. To con
 
 ### Exposure / TLS / credentials
 
-Details in [SECURITY.md](SECURITY.md) (Chinese).
+Details in [SECURITY.md](docs/dev/SECURITY.md) (Chinese).
 
 | Variable | Default | Meaning |
 |---|---|---|
-| `HERDR_WEB_EXPOSED` | off | `=1` **declares that this port is reachable from the internet** (frp / port forwarding / tunnels). Behind frp the process usually listens on 127.0.0.1 and every request also comes from 127.0.0.1, so "is the listen address local" tells you nothing; it cannot be detected, only declared. Once declared: TLS is mandatory and loopback-without-pairing is turned off |
+| `HERDR_WEB_PUBLIC_PORT` | off | **The port to expose.** Opens a second listener on `0.0.0.0:<port>` sharing the same handler, and that is where a tunnel / port forward / reverse proxy should point — never at the main port, which serves the local network only. Requests arriving here are treated as public: loopback-without-pairing and the legacy token's `loopback` tier do not apply (the source address of a tunnelled request is 127.0.0.1 too, so the only trustworthy signal is *which listener it landed on*), the rate limiter's "never block localhost" exemption is off, and TLS becomes mandatory. Why a separate port instead of a switch on the main port: a switch is a *declaration*, and declarations get forgotten — the person (or agent) writing code on this machine sees `127.0.0.1:7788` and has no way to know a tunnel is forwarding it, so every decision made under "only my machine can reach this" becomes a hole. With a separate port, forgetting to configure it means the tunnel gets connection refused |
+| `HERDR_WEB_EXPOSED` | off | **Legacy; prefer `HERDR_WEB_PUBLIC_PORT`.** `=1` declares that *the main port itself* is reachable from the internet (frp / port forwarding / tunnels) — it cannot be detected, only declared. Once declared: TLS is mandatory, loopback-without-pairing is turned off, and the main port's "local network only" gate is lifted (you said it is public). Kept for machines already configured this way |
 | `HERDR_WEB_TLS_CERT` / `_KEY` | empty | Use the certificate you supply. If you own a domain and got a real certificate via DNS-01, take this route — zero browser warnings, no profiles to install, least friction |
 | `HERDR_WEB_ACME_DNS` | empty | Let herdr-web **get its own certificate**; the value is the DNS provider: `cloudflare` / `alidns` / `tencentcloud` / `route53` / `digitalocean` / `huaweicloud`. It uses DNS-01, so nothing has to reach you from outside — behind NAT, or with the domain pointed at a LAN address, it still works. **Where to get each provider's token and what scope it needs: [DNS.md](DNS.md)** (Chinese) |
 | `HERDR_WEB_ACME_EMAIL` | empty | ACME account email. Can be empty, but then you get no expiry reminders either |
@@ -355,10 +356,11 @@ Details in [SECURITY.md](SECURITY.md) (Chinese).
 # 2. Phone / tablet on the LAN: self-signed TLS, pair by scanning the banner QR
 HERDR_WEB_HOST=0.0.0.0 ./herdr-web
 
-# 3. Exposed through frp / a tunnel: EXPOSED must be declared (the process only
-#    listens on 127.0.0.1 and cannot tell whether anyone outside can reach it),
-#    PUBLIC_URL decides which address the QR code encodes
-HERDR_WEB_EXPOSED=1 HERDR_WEB_TLS=proxy \
+# 3. Exposed through frp / a tunnel: point the tunnel at PUBLIC_PORT, never at the
+#    main port — the main port only serves the local network, and every default on
+#    it assumes the internet cannot reach it. PUBLIC_URL decides which address the
+#    QR code encodes
+HERDR_WEB_PUBLIC_PORT=17788 HERDR_WEB_TLS=proxy \
 HERDR_WEB_PUBLIC_URL=https://herdr.example.com \
 HERDR_WEB_HOSTNAME=herdr.example.com ./herdr-web
 
@@ -469,20 +471,22 @@ without a PTY), so the door is designed on that premise. What is implemented:
   moving to a new device does not require going back to the machine, and session credential lifetime
   can drop from three months to one day.
 
-→ Threat model, the reasoning behind each choice, what is not built yet: [SECURITY.md](SECURITY.md)
+→ Threat model, the reasoning behind each choice, what is not built yet: [SECURITY.md](docs/dev/SECURITY.md)
 　Reaching it from the internet (frp / tunnels) and the four TLS tiers: [DEPLOY.md](DEPLOY.md)
 
 ## Documents
 
 Everything below is in Chinese — that is where the "why" lives.
 
+**This file, plus DEPLOY / DNS, is the user documentation.** The first five below live in [`docs/dev/`](docs/dev/README.md) — that layer is *why it is built this way*: design rationale, hand-verified semantics, and the traps that fail silently.
+
 | What you want | Where |
 |---|---|
-| Outbox: why a separate box, how images work, measured polling latency | [OUTBOX.md](OUTBOX.md) |
-| Reading the screen: scraping the input line, scraping what the agent said | [COMPOSER.md](COMPOSER.md) |
-| herdr socket API semantics, verified by hand | [HERDR-API.md](HERDR-API.md) |
-| The whole phone / tablet layer (gestures, keyboard, dock, top bar, notices, clipboard) | [MOBILE.md](MOBILE.md) |
-| Security design and threat model; the rules on the file-serving route | [SECURITY.md](SECURITY.md) |
+| Outbox: why a separate box, how images work, measured polling latency | [OUTBOX.md](docs/dev/OUTBOX.md) |
+| Reading the screen: scraping the input line, scraping what the agent said | [COMPOSER.md](docs/dev/COMPOSER.md) |
+| herdr socket API semantics, verified by hand | [HERDR-API.md](docs/dev/HERDR-API.md) |
+| The whole phone / tablet layer (gestures, keyboard, dock, top bar, notices, clipboard) | [MOBILE.md](docs/dev/MOBILE.md) |
+| Security design and threat model; the rules on the file-serving route | [SECURITY.md](docs/dev/SECURITY.md) |
 | Where to run it, public access, TLS tiers | [DEPLOY.md](DEPLOY.md) |
 | Getting a DNS token from each provider and the scope it needs | [DNS.md](DNS.md) |
 | Read before changing code (layout, releasing, colours, the silent traps) | [CLAUDE.md](CLAUDE.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bysir/herdr-web",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "浏览器里的 herdr 终端 + 语音投稿。一个 Go 二进制，前端嵌在里面。",
   "license": "MIT",
   "homepage": "https://github.com/zbysir/herdr-web#readme",
@@ -29,9 +29,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@bysir/herdr-web-darwin-arm64": "0.4.0",
-    "@bysir/herdr-web-darwin-x64": "0.4.0",
-    "@bysir/herdr-web-linux-arm64": "0.4.0",
-    "@bysir/herdr-web-linux-x64": "0.4.0"
+    "@bysir/herdr-web-darwin-arm64": "0.5.1",
+    "@bysir/herdr-web-darwin-x64": "0.5.1",
+    "@bysir/herdr-web-linux-arm64": "0.5.1",
+    "@bysir/herdr-web-linux-x64": "0.5.1"
   }
 }