@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.0

package/README.md

@@ -250,7 +250,7 @@ dsh plugin --profile <profile-name> add @twinsearth/w2m-dsh-plugin
 
 ```bash
 dsh plugin --profile <profile-name> add \
-  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.9/twinsearth-w2m-dsh-plugin-0.5.9.tgz
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.6.3/twinsearth-w2m-dsh-plugin-0.6.3.tgz
 ```
 
 **From the repository** — the form a marketplace's one-click installer uses (it clones
@@ -624,6 +624,13 @@ move with it: `claims` is 19 tests here and **22 when `dist/` holds a packed tar
 its two tarball-vs-`package.json` checks run instead of skipping — so a checkout with `dist/` measures
 **1,142 tests / 1,134 pass / 4 skip**, and that is the number to expect from a release tree.
 
+> **These counts are the v0.5.9 measurement and have not been re-taken since.** They are kept, dated
+> and attributed rather than refreshed, because a figure presented as current without having been
+> measured is the failure this project's own rules exist to prevent. Suites added after v0.5.9 —
+> `p2p-crypto`, and from v0.7.0 `chatops-approval` and `chatops-policy` — are therefore **not** in
+> any total on this page. Treat every count below as a v0.5.9 measurement until a release re-runs
+> the suite on its own host and says so.
+
 **Which script runs which suite matters, because they are not the same set:**
 
 | Command | Suites | Result on this host (v0.5.9) |
@@ -810,7 +817,7 @@ node bin/w2m-localside.mjs --rabbit http://<中继地址>:8787 --pair PAIR-XXXXX
 
 # 3) 装 DSH 插件
 dsh plugin --profile <profile-name> add \
-  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.9/twinsearth-w2m-dsh-plugin-0.5.9.tgz
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.6.3/twinsearth-w2m-dsh-plugin-0.6.3.tgz
 ```
 
 然后在 profile 的 `cordis.patch.yml` 里给插件 `rabbitUrl`（留空即用共享服务器）与 `operatorToken`，重启 DSH，即可直接用自然语言指挥：

package/bin/w2m-rabbit.mjs

@@ -53,6 +53,9 @@ Credentials and state:
   --no-persist           Keep everything in memory; forget devices and tasks on
                          restart.
   --pairing-code <c>     Use a fixed pairing code instead of a generated one.
+--fleet <id>           Bind this relay to one account's fleet. Omitted, the relay serves
+                       every device (the pre-v0.7.7 behaviour). Set, a device with no
+                       fleet reaches nothing and a device in another fleet is invisible.
 
 Request signing (v0.3.0):
   --signing-secret <s>   Shared secret for HMAC-signed requests. Unset means the relay does
@@ -98,6 +101,9 @@ try {
       port: { type: 'string' },
       state: { type: 'string' },
       'pairing-code': { type: 'string' },
+      // v0.7.7: bind this relay to a fleet. Omitted means every device, which is the
+      // pre-v0.7.7 behaviour and therefore the migration-safe default.
+      fleet: { type: 'string' },
       'heartbeat-ms': { type: 'string' },
       'grace-ms': { type: 'string' },
       'base-path': { type: 'string' },

package/deploy/server/README.md

@@ -0,0 +1,109 @@
+# Running the relay on a server
+
+These are the units the shared relay **actually runs**, copied from
+`/etc/systemd/system/` on the live host rather than written from the documentation. They are in the
+repository because "how the server runs" is part of the thing being open-sourced — and because a
+unit that exists only on one machine is a unit nobody can review, reproduce, or audit.
+
+## The three services
+
+| Unit | What it is | Port |
+|---|---|---|
+| `w2m-rabbit.service` | The relay: P2P rendezvous, signalling, and the task ledger | 8787 |
+| `w2m-stun.service` | STUN responder, for reflexive address discovery during hole punching | 3478 |
+| `w2m-localside.service` | A Localside agent, so the server is itself a fleet machine | — |
+
+`w2m-localside` is deliberately the same agent every other machine runs. The server is not
+privileged in the fleet's protocol — it is a peer that happens to be reachable — and running it
+through the normal agent is what keeps that true.
+
+## ⚠️ What is NOT here, and why
+
+**`/var/lib/w2m/rabbit/` is not in this repository and must never be.**
+
+It holds:
+
+| File | Why it must not be published |
+|---|---|
+| `operator-token.txt` | **Full control of the fleet.** Anyone holding it can dispatch any allowed command to every machine. |
+| `ledger` | The task history: every command run, on which machine, with which results. |
+
+Two mechanisms keep this true, because one is not enough:
+
+1. **`.gitignore`** refuses the paths, so an accidental `git add -A` cannot stage them.
+2. **`scripts/scan-for-secrets.mjs`** reads the **content** of every tracked file and fails the
+   release on a credential shape. A `.gitignore` refuses a *path*; the ways a credential actually
+   escapes are pasting one into a source file, a fixture, or an example — so tracked content is
+   what gets read.
+
+Run it before a release:
+
+```bash
+node scripts/scan-for-secrets.mjs .
+# 0 blocking, N for review -> exit 0
+```
+
+`REVIEW` findings (long hex strings, high-entropy assignments) are **not fatal by design**: a
+scanner whose false positives block releases is a scanner someone deletes. Only real credential
+shapes stop anything.
+
+## Installing
+
+```bash
+# 1. A user that owns the state and nothing else.
+sudo useradd --system --home /var/lib/w2m --shell /usr/sbin/nologin w2m
+
+# 2. The paths the units reference.
+sudo install -d -o w2m -g w2m /opt/w2m /var/lib/w2m /var/log/w2m
+
+# 3. The code, at the tag being deployed.
+sudo -u w2m git clone https://github.com/TwinsEarth/dsh-windows2macos /opt/w2m/app
+sudo -u w2m git -C /opt/w2m/app checkout v0.7.10
+
+# 4. The units.
+sudo cp deploy/server/*.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now w2m-rabbit w2m-stun
+
+# 5. Pair the server as a fleet machine, then enable the agent.
+sudo systemctl enable --now w2m-localside
+```
+
+## Notes on the hardening, since it is easy to weaken by accident
+
+Every unit sets `NoNewPrivileges`, `PrivateTmp`, `ProtectHome`, and a `ProtectSystem` level, and
+writes only inside `/var/lib/w2m` via `ReadWritePaths`. That last one matters: `ProtectSystem=full`
+makes `/usr` and `/boot` read-only, so an agent that tried to write anywhere else would fail
+loudly rather than silently succeed on a machine that should not be writable.
+
+`w2m-stun` is stricter (`ProtectSystem=strict`, `RestrictAddressFamilies=AF_INET AF_INET6`) because
+it needs a socket and nothing else.
+
+**If you add a capability to an agent, check `ReadWritePaths` first.** The failure is a permission
+error at runtime, which looks like a bug in the agent rather than a hardening setting.
+
+## The `--fleet` flag, and why it is absent here
+
+`w2m-rabbit` accepts `--fleet <account code>`, which binds the relay to one account's fleet. It is
+**absent from this unit on purpose**, and the relay therefore runs unscoped: every paired device
+reaches every other.
+
+Turning it on is not a configuration change — it is a **fleet migration**:
+
+1. the account code must be read on a machine that is **signed in** (a headless server cannot
+   produce one; it has no DeepSeek account),
+2. the relay restarts scoped,
+3. **every device must be re-paired**, because a device receives its fleet *from the pairing code*,
+   and on a scoped relay a device with no fleet reaches **nothing**.
+
+Step 3 is the risk: the fleet goes silent until each machine is re-paired. That is the intended
+fail-safe direction and it is still an outage while it lasts.
+
+## Deliberately not included
+
+* **TLS termination.** The live relay is behind a proxy that handles it; `--base-path` and
+  `--trust-proxy` exist for that arrangement and the certificate is the operator's business.
+* **Backups.** The state directory is small (about 1 MB) and is the operator's to schedule. The
+  deployment script below does back it up before a swap, which is not the same as a backup policy.
+* **Log rotation.** `StandardOutput=append:` grows without bound; the live host rotates
+  `/var/log/w2m/*.log` outside these units.

package/deploy/server/deploy-w2m.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+#
+# Deploy one release tarball to a running relay, with a rollback that is automatic rather than
+# remembered.
+#
+# This is the script the live server was updated with (v0.6.3 -> v0.7.7 -> v0.7.10). It is in the
+# repository because a deployment that exists only in someone's shell history is a deployment nobody
+# can review — and because the order of these steps is the whole safety argument:
+#
+#   1. verify the checksum BEFORE unpacking, so a truncated upload cannot become a running service
+#   2. back up the tree in place, so rollback does not depend on the network
+#   3. stage and check for entry points BEFORE swapping, so a bad tarball never reaches the
+#      live path
+#   4. restart and health-check, and roll back automatically if the health check fails
+#
+# Step 3 is the one that matters most: `git archive` of a wrong subdirectory produces a tarball that
+# unpacks cleanly and contains no `bin/`, and without the entry-point check that becomes a service
+# that starts, finds nothing to run, and reports a confusing error.
+#
+# Usage: deploy-w2m.sh <tarball> <expected-sha256> [--fleet <account-code>]
+#
+set -euo pipefail
+
+APP_DIR=/opt/w2m/app
+BACKUP_ROOT=/opt/w2m
+STATE_DIR=/var/lib/w2m
+SERVICES=(w2m-rabbit w2m-stun w2m-localside)
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+
+TARBALL="${1:-}"
+EXPECTED="${2:-}"
+FLEET=""
+if [ "${3:-}" = "--fleet" ]; then FLEET="${4:-}"; fi
+
+if [ -z "$TARBALL" ] || [ -z "$EXPECTED" ]; then
+  echo "usage: $0 <tarball> <expected-sha256> [--fleet <account-code>]" >&2
+  exit 2
+fi
+if [ ! -f "$TARBALL" ]; then echo "no such tarball: $TARBALL" >&2; exit 2; fi
+
+echo "=== 1. verify the artefact ==="
+ACTUAL=$(sha256sum "$TARBALL" | awk '{print $1}')
+echo "  expected $EXPECTED"
+echo "  actual   $ACTUAL"
+if [ "$ACTUAL" != "$EXPECTED" ]; then
+  echo "  CHECKSUM MISMATCH -- refusing to deploy. A truncated upload must never become a service." >&2
+  exit 1
+fi
+echo "  checksum OK"
+
+echo
+echo "=== 2. what is running now ==="
+if [ -f "$APP_DIR/package.json" ]; then
+  echo "  $APP_DIR is version $(node -e "process.stdout.write(require('$APP_DIR/package.json').version)")"
+else
+  echo "  $APP_DIR has no package.json (first deploy?)"
+fi
+for s in "${SERVICES[@]}"; do
+  printf '  %-16s %s\n' "$s" "$(systemctl is-active "$s" 2>/dev/null || echo inactive)"
+done
+
+echo
+echo "=== 3. back up the current tree ==="
+BACKUP="$BACKUP_ROOT/backup-$STAMP"
+if [ -d "$APP_DIR" ]; then
+  cp -a "$APP_DIR" "$BACKUP"
+  echo "  $APP_DIR -> $BACKUP"
+else
+  echo "  nothing to back up"
+fi
+
+echo
+echo "=== 4. unpack to staging and check it ==="
+STAGING=$(mktemp -d)
+trap 'rm -rf "$STAGING"' EXIT
+tar -xzf "$TARBALL" -C "$STAGING"
+# The tarball contains a single `package/` root, by npm convention.
+SRC="$STAGING/package"
+if [ ! -d "$SRC" ]; then SRC="$STAGING"; fi
+
+STAGED_VERSION=$(node -e "process.stdout.write(require('$SRC/package.json').version)" 2>/dev/null || echo "?")
+echo "  staged version: $STAGED_VERSION"
+
+# The check that turns a confusing runtime failure into a clear deployment failure.
+MISSING=""
+for f in bin/w2m-rabbit.mjs bin/w2m-stun.mjs bin/w2m-localside.mjs package.json; do
+  [ -e "$SRC/$f" ] || MISSING="$MISSING $f"
+done
+if [ -n "$MISSING" ]; then
+  echo "  MISSING ENTRY POINTS:$MISSING" >&2
+  echo "  refusing to swap: this tarball would install a service that cannot start." >&2
+  exit 1
+fi
+echo "  entry points present"
+
+echo
+echo "=== 5. swap into place ==="
+rm -rf "$APP_DIR.old"
+if [ -d "$APP_DIR" ]; then mv "$APP_DIR" "$APP_DIR.old"; fi
+cp -a "$SRC" "$APP_DIR"
+chown -R w2m:w2m "$APP_DIR" 2>/dev/null || true
+echo "  swapped; previous tree kept at $APP_DIR.old"
+
+echo
+echo "=== 6. restart ==="
+# The relay's fleet binding: omitted means unscoped, which is the pre-v0.7.8 behaviour.
+if [ -n "$FLEET" ]; then
+  echo "  --fleet $FLEET requested"
+  if grep -q -- '--fleet' /etc/systemd/system/w2m-rabbit.service; then
+    sed -i "s|--fleet [^ ]*|--fleet $FLEET|" /etc/systemd/system/w2m-rabbit.service
+  else
+    sed -i "s|\(--state [^ ]*\)|\1 --fleet $FLEET|" /etc/systemd/system/w2m-rabbit.service
+  fi
+  systemctl daemon-reload
+  echo "  WARNING: the relay is now scoped. A device with no fleet reaches NOTHING."
+  echo "           Every device must be re-paired with a code issued by this relay."
+fi
+systemctl restart "${SERVICES[@]}"
+
+echo
+echo "=== 7. health check ==="
+sleep 4
+HEALTHY=1
+for s in "${SERVICES[@]}"; do
+  STATE=$(systemctl is-active "$s" 2>/dev/null || echo inactive)
+  printf '  %-16s %s\n' "$s" "$STATE"
+  [ "$STATE" = "active" ] || HEALTHY=0
+done
+
+if command -v curl >/dev/null 2>&1; then
+  HEALTH=$(curl -fsS --max-time 10 http://127.0.0.1:8787/healthz 2>/dev/null || echo "")
+  if [ -n "$HEALTH" ]; then
+    echo "  healthz: $HEALTH"
+  else
+    echo "  healthz: NO ANSWER"
+    HEALTHY=0
+  fi
+fi
+
+if [ "$HEALTHY" != "1" ]; then
+  echo
+  echo "=== 8. ROLLBACK ==="
+  if [ -d "$BACKUP" ]; then
+    rm -rf "$APP_DIR"
+    mv "$BACKUP" "$APP_DIR"
+    systemctl restart "${SERVICES[@]}"
+    echo "  rolled back to the previous tree and restarted" >&2
+  else
+    echo "  no backup to roll back to" >&2
+  fi
+  exit 1
+fi
+
+echo
+echo "=== deployed ==="
+echo "  version:  $STAGED_VERSION"
+echo "  backup:   $BACKUP"
+echo "  previous: $APP_DIR.old (removable once this is proven)"
+echo
+echo "  NOTE: relay state lives in $STATE_DIR and was NOT touched by this script."
+echo "        The ledger and the operator token survive a deploy; that is deliberate."

package/deploy/server/w2m-localside.service

@@ -0,0 +1,31 @@
+[Unit]
+Description=W2M Localside agent (shared server as a fleet machine)
+After=network-online.target w2m-rabbit.service
+Wants=network-online.target
+Wants=w2m-rabbit.service
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+WorkingDirectory=/opt/w2m/demo
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-localside.mjs \
+  --rabbit http://127.0.0.1:8787 \
+  --project /opt/w2m/shared \
+  --name jp-shared \
+  --state /var/lib/w2m/localside-jp \
+  --p2p-mode auto \
+  --p2p-port 41234 \
+  --allowed-commands '["node --version","node --test","node -e","git status --porcelain","git rev-parse","git log","git diff","npm test","npm run"]'
+Restart=always
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/w2m
+StandardOutput=append:/var/log/w2m/localside.log
+StandardError=append:/var/log/w2m/localside.log
+
+[Install]
+WantedBy=multi-user.target

package/deploy/server/w2m-rabbit.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=W2M Rabbit relay (P2P rendezvous, signalling and task ledger)
+Documentation=https://github.com/TwinsEarth/dsh-windows2macos
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+WorkingDirectory=/opt/w2m/app
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-rabbit.mjs --host 0.0.0.0 --port 8787 --state /var/lib/w2m/rabbit
+Restart=always
+RestartSec=2
+# The relay holds no model credentials and no working copy; it needs its state dir and
+# nothing else. NoNewPrivileges + ProtectSystem close the obvious escalation paths.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/w2m
+StandardOutput=append:/var/log/w2m/rabbit.log
+StandardError=append:/var/log/w2m/rabbit.log
+
+[Install]
+WantedBy=multi-user.target

package/deploy/server/w2m-stun.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=W2M STUN responder - reflexive address discovery for P2P hole punching
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-stun.mjs --host 0.0.0.0 --port 3478 --log-level info
+Restart=always
+RestartSec=2
+StartLimitIntervalSec=60
+StartLimitBurst=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6
+StandardOutput=append:/var/log/w2m/stun.log
+StandardError=append:/var/log/w2m/stun.log
+
+[Install]
+WantedBy=multi-user.target