@twinsearth/w2m-dsh-plugin 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -54,6 +54,98 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 * Still unverified, and not claimed: how the control *renders*. No browser was opened. What is proven is
   the entire host side — the entry activates, the eight tools register, the boot-graph row is composed
   from the shipped bundle, the route is registered and attached — plus the seat shape in a VM test.
+## [0.5.7] — 2026-10-11
+
+### Fixed
+
+* **v0.5.6 shipped without its own documents.** `TROUBLESHOOTING.md` and `SECURITY.md` were written,
+  reviewed and committed, and then **not packed**, because `files` names the documents individually
+  rather than by pattern. Anyone installing v0.5.6 got the code and none of the guidance. They are in the
+  package now, and `test/claims.test.mjs` is the place this class of defect belongs.
+* **v0.5.6 shipped without its own gates wired in.** `test/claims.test.mjs`, `test/loader-entry.test.mjs`
+  and the two mDNS suites existed and passed, but were listed in none of `test`, `test:all` or `verify` —
+  a test that does not run protects nothing, which is the exact defect this release's own study
+  identified in someone else's repository. All four are wired in.
+* A typographic character (a smart quote) in `test/mdns-discover.test.mjs`, caught by the repository's
+  own mojibake scan.
+
+### Notes
+
+* Fix-forward, not a rewrite: v0.5.6 is published and stays published, because the alternative is
+  rewriting history someone may already have. Both defects are mine, and both are the class this project
+  keeps naming — a claim that nothing checks.
+* No runtime change: the code in v0.5.7 is the code in v0.5.6.
+## [0.5.6] — 2026-10-11
+
+### Fixed
+
+* **The client entry could not activate, and that made the whole application refuse to start.**
+  v0.5.4 and v0.5.5 were withdrawn for it. The real cause, taken from the page itself rather than
+  guessed:
+
+  ```
+  w2m-client-probe: apply threw for @twinsearth/w2m-dsh-plugin: cannot get property "locale" without inject
+  Error: web boot: 1 entry did not activate
+  ```
+
+  Cordis throws for any `ctx.<name>` a fiber reads without declaring it, and the client half declared
+  `inject = []`. **The first throw was `locale`, not `slots`** — so declaring the seat alone, or guarding
+  the locale alone, would each still have died. Now `inject = ['slots']` (a declared name is a *required*
+  dependency, which is why `locale` is deliberately not among them), the optional carrier is read
+  inject-free with `ctx.get('locale')` while its dictionary registration rides a child fiber, a context
+  with no usable seat becomes a **no-op with a diagnostic** instead of taking the page down, and `apply`
+  prints the inner message to the error-level renderer console — the channel the crash log reads — and
+  then rethrows, because a swallow would boot a healthy-looking page with no control.
+* **A failed entry was invisible unless you read fiber state.** `cordis-plugin-loader` no longer
+  propagates a failed mount to `await ctx.loader.await()`, and the loader driver inspected only the one
+  entry it knew about — so a failure landing on a **child** fiber (our silently-refused route) went
+  unseen. The driver now sweeps the whole registry and reports `failedFibers`.
+
+### Added
+
+* **A gate that would have caught all of it**: `test/loader-entry.test.mjs` packs the tree, installs the
+  tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
+  `DSH_HOME`, boots it with the real `runProfile`, activates the client entries through the real module
+  system, and — when a browser is present — boots the profile's own page and asserts our control renders.
+  Proven in both directions: **10/10 on this tree, 2 failures against the preserved pre-fix tarball, 9
+  against the v0.5.4 one**, and with a deliberately injected route defect it names the **child** fiber
+  while "entry active" and "eight tools" still pass. It reports one stage per line, so a failure names
+  its cause.
+* **`test/claims.test.mjs`** — 22 checks that our own published claims match the artifact, with the
+  registered tool set *measured* by importing the entry. It caught a stale claim in our README on its
+  **first run** (`README.md` said the installer asserts 5 tools; it asserts 8), and its author's own
+  mutation proof caught two false greens in its first draft — a scan that extracted zero tool names and
+  a lookahead that invented one out of a metric.
+* **`TROUBLESHOOTING.md`** — 17 symptom-indexed sections that name the culprit when it is not us (pnpm's
+  `minimumReleaseAge`, carrier-grade NAT, the OS firewall, an installer that rewrites the profile patch),
+  ending with a data-location table and a reason-code table.
+* **`SECURITY.md`** — a private reporting channel and **no public-issue route**, an honest support table,
+  and the consent model written out: what a paired machine may and may not do, and that we never write to
+  another machine's `authorized_keys`.
+* **`CONTRIBUTING.md`** — one page of falsifiable conventions, including **"a test that would pass
+  against a broken artifact is not evidence"** and **"run mutation proofs in a copy, never in the shared
+  tree"** (both learned the hard way).
+* **Opt-in LAN discovery** (`src/agent/mdns-wire.mjs`, `src/agent/mdns.mjs`, `src/plugin/mdns-discover.mjs`):
+  a bounded, hand-written DNS/mDNS codec with parse hardening (a pointer may only name a *prior* offset, so
+  termination is a property of the format; a 128-hop budget reported separately from a loop; label, name,
+  record and packet caps; every read bounds-checked) and a discovery source exposed through
+  `w2m_devices`' new `include_discovered` (default `false`). **Discovery is a hint, never an
+  authorisation**: a discovered device is refused as a dispatch target unless the relay already lists it
+  and it is online, and the positive control is tested so the rule cannot pass by refusing everything.
+
+### Notes
+
+* **v0.5.4 and v0.5.5 remain DO NOT INSTALL.** This release also exists so that `latest` on the registry,
+  which still pointed at v0.5.5, stops handing out a version that prevents the application from starting.
+* **Upgrading from v0.5.4 needs one edit outside this package**: the profile's `cordis.patch.yml` must
+  name the package (`@twinsearth/w2m-dsh-plugin`), not the `/tools` subpath. With the corrected bundle row
+  a mismatch makes the loader skip the whole patch and silently revert every configured value to its
+  default. The claims gate now checks this.
+* **LAN discovery is unverified on a real network.** Every socket in its suite is loopback and no packet
+  left the host, so it says nothing about whether a switch forwards `224.0.0.251` or how a real
+  Bonjour/Avahi peer answers. There is **no third-party interoperability test**, no probing or conflict
+  resolution, IPv4 only, and the responder is **built and tested but not started** by the plugin —
+  loading a plugin should not silently multicast on the host's network.
 ## [0.5.4] — 2026-10-11
 
 > **DO NOT INSTALL 0.5.4.** It fails to load in the Harness: the loader entry

package/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing
+
+One page. Everything here is a rule you can check, not a preference — if a line in this document
+cannot be verified by reading the diff, it does not belong here.
+
+## Setup
+
+```bash
+git clone https://github.com/TwinsEarth/dsh-windows2macos
+cd dsh-windows2macos
+npm install            # dev tools only: eslint, prettier, globals
+node --version         # must satisfy package.json engines: >=20.19.0
+```
+
+There are **no runtime dependencies** — `dependencies` in `package.json` is `{}` and stays that way.
+Adding one is a design change, not a convenience, and it will be refused. `@deepseek-ai/dsh-tools` is
+an optional peer: the plugin imports it when DSH provides it and falls back to a small offline shim
+when it does not, so the suites run with no Harness installed.
+
+## The commands
+
+```bash
+# The unit suites (what scripts.test runs), and everything including e2e
+node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs
+npm test
+npm run test:all
+
+# One suite while you work
+node --test --test-force-exit test/claims.test.mjs
+
+# Lint: must be 0 errors, and 0 warnings
+node node_modules/eslint/bin/eslint.js .
+
+# Entry points import: lib/tools.js and lib/index.js, the specifiers a profile mounts
+node scripts/check-entrypoints.mjs
+
+# The installed copy registers its tools (point it at a profile's node_modules copy)
+node scripts/verify-installed.mjs <path-to-installed-package>
+```
+
+`scripts/check-entrypoints.mjs` proves the entry points **import**. It does not prove the loader
+**composes** them — those are different failures, and the second one shipped once (v0.5.4: the entry
+failed inside the real Loader and every tool disappeared while `verify-installed.mjs` passed). When
+your change touches mounting, exports, `cordis.patch.yml` or the client half, run
+`test/loader-entry.test.mjs` too: it installs the packed tarball with `dsh plugin add` into a
+throwaway profile under a throwaway `DSH_HOME` and boots it with the real `runProfile`.
+
+## Conventions
+
+Each line is checkable against a diff.
+
+1. **Zero runtime dependencies.** `dependencies === {}` in `package.json`. Node built-ins only.
+2. **Argv execution, never a shell string.** A command is an array of arguments passed to
+   `spawn`/`execFile` with no shell. No `exec`, no `shell: true`, no string interpolation into a
+   command line. This is what makes the allow-list meaningful: a shell would re-parse the argv the
+   allow-list just approved.
+3. **One named constant per network bound.** Every timeout, port, retry count, size limit and
+   interval is a named `const` in one place, exported if a test needs it. A literal `5000` in a
+   request call is a review comment.
+4. **A failure carries a reason code, not a boolean.** `{ ok: false, code: 'W2M_UNREACHABLE', ... }`
+   or a thrown error with `code` — never `false`, never `null`, never a bare string. `undefined` may
+   mean "absent"; it may not mean "failed".
+5. **Commit format: `<type>: <one line>`.** Types: `feat`, `fix`, `docs`, `test`, `chore`, `perf`,
+   `refactor`, `build`, `ci`. One line, imperative, no trailing period; put the argument for the
+   change in the body, not in the subject.
+6. **Docs changes are code changes.** If a claim in `README.md`, `PROTOCOL.md` or a deploy guide is
+   now false, fix it in the same PR. `test/claims.test.mjs` gates the machine-checkable subset.
+7. **A test that would pass against a broken artifact is not evidence.** See below.
+8. **Say what you verified, and how.** In the PR: what was run live, what was covered by a test, and
+   what is not verified at all. "Not verified" is an acceptable answer; an implied verification is
+   not.
+
+## Rule 7, in full: prefer the real runtime to a stand-in
+
+This project learned it the hard way. The v0.5.4 loader failure was invisible to **every** existing
+test, because those tests drove the plugin with a plain-object context where reading an undeclared
+service property merely yields `undefined`. The real Loader throws instead. The fake was more
+forgiving than the runtime, so the suite was green while the shipped artifact broke the application.
+
+Therefore:
+
+- **Drive the real thing when the real thing is reachable.** The entry points, the packed tarball,
+  the real Loader, a real pnpm install into a throwaway profile, the real `fetch` against a local
+  server. `test/loader-entry.test.mjs` exists precisely to pay this cost once.
+- **When a stand-in is unavoidable, prove it in both directions.** A fix is not demonstrated by a
+  green test alone. Take the broken artifact, keep it, and show the new test **fails** against it —
+  then show it passes against the fix. `test/loader-entry.test.mjs` does this: 6/6 pass on the fixed
+  tree and 6/6 fail against the preserved v0.5.4 tarball, on the exact loader error.
+- **Make the fake stricter than the runtime, never more forgiving.** If your stub silently accepts
+  something the runtime throws on, the test is measuring your stub.
+- **A skip must be loud and must name what it could not reach.** A test that quietly returns when a
+  probe is missing is worse than no test: it reports confidence it does not have. Say which probe you
+  tried and how to enable it.
+- **Fix a claim's drift at its source.** If a document, a count or a version is wrong, correct it
+  rather than exempting it in the test that caught it. An exemption list is where a gate goes to die.
+
+## Pull requests
+
+1. **Branch** off `main`; do not commit to `main`.
+2. **Keep it one idea.** A rename plus a behaviour change plus a doc rewrite is three PRs.
+3. **Run before you push**, and paste the real output into the PR:
+
+   ```bash
+   npm test
+   node node_modules/eslint/bin/eslint.js .
+   node scripts/check-entrypoints.mjs
+   ```
+
+4. **Describe verification, not effort.** The PR body answers: what changed, what proves it, what is
+   not proven, and which commands you ran with their result counts.
+5. **Add a CHANGELOG entry** under the version you are working on, in the existing style. A behaviour
+   change with no CHANGELOG line will be sent back.
+6. **Reviewers check the conventions list above**, line by line, against the diff. Expect to be asked
+   "which constant?", "which code?", "what did you run?".
+7. **A version that must not be installed gets marked.** If a release is broken after publication,
+   add `DO NOT INSTALL` to its CHANGELOG entry, in its own section, and say why. `test/claims.test.mjs`
+   reads that marker: it refuses to let the current version be one the CHANGELOG tells users not to
+   install.
+
+## Security
+
+Do not open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md) for the private
+channel and what to include.

package/README.md

@@ -535,7 +535,7 @@ the plugin:
 
 ```bash
 node scripts/check-entrypoints.mjs   # imports lib/tools.js, the exact specifier cordis.patch.yml mounts
-node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 5 tools
+node scripts/verify-installed.mjs <path-to-installed-package>   # asserts the installed copy registers 8 tools
 ```
 
 **Not verified:**
@@ -588,6 +588,8 @@ Issues and pull requests are welcome. If you change observable behaviour, update
 `PROTOCOL.md` in the same commit — that file is the contract three components
 agree on.
 
+When something does not work, start from the symptom: [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
 ## License
 
 [MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,162 @@
+# Security policy
+
+This document covers two things: how to report a vulnerability **privately**, and the consent model —
+what a machine that joins your fleet can and cannot do. The second is the claim this project asks you
+to trust, so it is stated as behaviour you can check, not as a promise.
+
+---
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a vulnerability.** A public issue is readable by everyone the moment
+it is filed, including anyone who has not updated yet, and it turns a fix into a race. This project
+deliberately does **not** offer a public-issue route for security reports.
+
+Use GitHub's private vulnerability reporting — the form creates a private advisory only the
+maintainers can see:
+
+```
+https://github.com/TwinsEarth/dsh-windows2macos/security/advisories/new
+```
+
+If that page is unavailable, open a **non-sensitive** issue that says only _"I have a security report
+and need a private channel"_, with no details, no reproducer and no affected version. A maintainer
+will open the private thread. Do not put the substance in the issue.
+
+### What to include
+
+The report is only actionable if it starts from a shape we can reproduce. Please include:
+
+1. **What you can do that you should not be able to** — one sentence, then the steps.
+2. **Affected version**, exactly as installed
+   (`node -p "require('./node_modules/@twinsearth/w2m-dsh-plugin/package.json').version"`), and which
+   of the two halves is involved: the DSH plugin, the relay (`w2m-rabbit`), the per-machine agent
+   (`w2m-localside`), or the STUN responder.
+3. **The trust boundary you crossed.** This project's boundaries are: the operator token vs. the
+   device token; the per-machine allow-list; and the direct UDP path vs. the relay. Saying which one
+   moved is most of the analysis.
+4. **A reproducer**, or the exact commands and their output. If it needs two machines, say what the
+   second one was doing.
+5. **Your assessment of impact**, and whether the issue is public already.
+
+### What we will do
+
+- Acknowledge the report in the private thread.
+- Say whether we can reproduce it, and if not, say what we would need.
+- Tell you when a fixed version is published, and credit you unless you ask us not to.
+
+No bug bounty is offered. Do not test against infrastructure you do not own: the shared relay is a
+real service and other people's machines are paired to it.
+
+---
+
+## Supported versions
+
+**The supported line is v0.5.3 and everything before it.** A version is installable unless the table
+says otherwise. Security fixes land on the newest installable version; older installable versions are
+not back-patched unless a report makes that necessary, and if it does, this table will say so.
+
+| Version                | Installable        | Note                                                                                                                           |
+| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| **v0.5.6 and later**   | not yet released   | In progress as this document is written. Check `CHANGELOG.md` for the newest entry that is not marked withdrawn.               |
+| v0.5.5                 | **no — withdrawn** | Fails to activate during DSH's web boot, which makes the whole application refuse to start, and takes all eight tools with it. |
+| v0.5.4                 | **no — withdrawn** | Same loader failure. `CHANGELOG.md` marks it `DO NOT INSTALL`.                                                                 |
+| **v0.5.3 and earlier** | **yes**            | The supported line. The client half was added in v0.5.4; v0.5.3 is a host-only plugin that loads.                              |
+
+The withdrawals are not a security judgement: those versions are not installable, so they are not
+supported. `CHANGELOG.md` is the authority — an entry marked `DO NOT INSTALL` is not supported
+whatever this table says, and the reverse is also true.
+
+### Installing a supported version
+
+```bash
+# The newest installable version from the registry
+dsh plugin --profile <profile> add @twinsearth/w2m-dsh-plugin@0.5.3
+
+# Or the same bytes from the release, verified against SHA256SUMS from the same release
+dsh plugin --profile <profile> add \
+  https://github.com/TwinsEarth/dsh-windows2macos/releases/download/v0.5.3/twinsearth-w2m-dsh-plugin-0.5.3.tgz
+```
+
+A version published minutes ago may be invisible to pnpm's `minimumReleaseAge` gate. That is the
+gate working, not a supply-chain problem — see `TROUBLESHOOTING.md` §11.
+
+---
+
+## The consent model
+
+Pairing a machine is a decision. This is exactly what it grants, and what it does not.
+
+### Two credentials, on purpose
+
+| Credential         | Held by                                                                           | Can                                                                     | Cannot                                                                                            |
+| ------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Operator token** | the dispatcher: your DSH profile (`operatorToken` config or `W2M_OPERATOR_TOKEN`) | authorise a _dispatch_ — send work to machines                          | read another machine's results, or act as an agent. No request that dispatches is sent without it |
+| **Device token**   | each machine's agent, in its own state directory (§16 of `TROUBLESHOOTING.md`)    | take work offered to **that** machine and report that machine's results | dispatch work to any machine, including itself                                                    |
+
+The split is the point: a machine that can receive work does not thereby gain the ability to command
+the others. If a machine's device token is stolen, the damage is confined to that machine's own
+execution surface; it cannot be used to drive the fleet.
+
+The relay writes the operator token once, on first start, and prints it once on stderr. It is
+deliberately absent from `--json` output — a token in a log is a leak. Treat it as a credential: it is
+never needed in a bug report.
+
+### What a paired machine can do
+
+- **Run commands you allow, in the project directory it was pointed at.** The allow-list is
+  **default-deny** and matches the whole `argv`, token by token: an entry `node --test` permits
+  `node --test x.test.mjs` and refuses `node --testify x`. An empty list is not "nothing runs" — it
+  means the plugin-side gate is not applied, so rely on the agent-side `--allowed-commands`.
+- **Read the project** it was started with, and compute git anchors and fingerprints over it.
+- **Report results**, including command output, to the relay — where the operator who dispatched the
+  work can read them.
+- **Reach its peers' punch port over UDP**, if the punch succeeds.
+
+### What a paired machine cannot do
+
+- **Run anything outside its allow-list.** A refused command is reported as `refused` with
+  `COMMAND_NOT_ALLOWED`, not executed.
+- **Command other machines.** That requires the operator token, which the agent is not given.
+- **Read another machine's results.** This is the claim people most reasonably doubt, and it is worth
+  being precise: the operator token authorises _dispatch_. A machine's results are visible to whoever
+  holds the operator token for that relay — the ledger is the relay's, not the agent's — so an agent
+  holding only its device token cannot enumerate or fetch another machine's output.
+- **Ask for your interactive confirmation per command.** There is no approval prompt in the loop. The
+  allow-list is the gate, which is why it is default-deny and why you should make it as narrow as the
+  work allows.
+- **Write to `~/.ssh/authorized_keys` — on any machine, ever.** Neither the plugin, the relay nor the
+  agent installs an SSH key, opens an SSH server, or adds a key file anywhere. The design reason is
+  that cross-machine execution here does not need SSH: every machine makes only outbound connections,
+  and Windows has no `sshd` by default. If you find anything in this project writing to an
+  `authorized_keys` file, that is a security report — please use the private channel above.
+
+### What it touches on your machine
+
+Declared here and machine-readably in `package.json`'s `disclosure`, because installing a plugin runs
+its code with your permissions:
+
+| Surface          | What it is                                                                                                                                                                                                      |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**   | reads and writes inside the project directory you name (anchors, fingerprints), plus its own state directory: the spool, `agent-state.json`, `device.json` and `device.key`                                     |
+| **Network**      | the configured relay (default: the shared server), the STUN servers (one is the shared server, three are public), and UDP to peer machines                                                                      |
+| **Inbound**      | peers can reach this machine's punch port. It is **ephemeral unless you pin it** with `--p2p-port`; pinning is what makes a narrow firewall rule possible, and an ephemeral port means a broader rule is needed |
+| **Credentials**  | the operator token in profile config or `W2M_OPERATOR_TOKEN`; the device token and key under the state directory                                                                                                |
+| **Jurisdiction** | data crosses between wherever your machines are and wherever the relay is; the reference deployment is CN ↔ JP                                                                                                  |
+
+### What this project does not claim
+
+- **The relay sees your task metadata and results.** It is the ledger. If that is not acceptable for
+  a workload, run your own relay — `deploy/` covers shared-server, nginx, Caddy, Docker, WireGuard and
+  systemd shapes — or do not use this plugin for that workload.
+- **The direct path is a security boundary.** A successful UDP hole punch means a peer can send you
+  packets on that socket. The data plane's encryption status is a separate, in-progress subject and is
+  specified in `docs/P2P-CRYPTO.md`; `w2m_status` reports what is actually in force rather than what is
+  intended.
+- **`chmod 0600` means the same thing everywhere.** On NTFS it is best-effort: the file mode does not
+  restrict other users of that Windows machine. The key file's protection on Windows is the account's
+  own filesystem ACLs, not the mode this project sets.
+- **Anything is verified by the attacker's absence.** The plugin's own test suites are the evidence we
+  have, and they are listed in `README.md` with what is and is not covered. Two things in particular
+  are **not** verified: a real Windows↔macOS pair over the network, and one account driving two
+  machines' model sessions.