@twinsearth/w2m-dsh-plugin 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -1,59 +1,51 @@
+## [0.5.8] — 2026-10-11
+
+### Fixed
+
+* **The CHANGELOG was out of order, and the claims gate caught it.** My bump scripts anchored the new
+  entry on the wrong heading, so v0.5.5 ended up *above* v0.5.6 and v0.5.7 and "the newest entry" stopped
+  meaning anything — which is exactly the assertion `test/claims.test.mjs` makes. Entries are ordered
+  newest-first again, and the anchor is the top of the file rather than a version I have to remember.
+* **Mojibake in shipped code.** `src/agent/mdns-wire.mjs` is packed, and its comments carried an em dash
+  and a section sign that had been decoded as the wrong encoding and re-saved, so a reader would have
+  seen `鈥` and `搂` where the RFC references belong. The same damage was in `test/mdns-discover.test.mjs`.
+  All five mDNS files are ASCII now, and the repository's own mojibake scan is clean.
+
+### Notes
+
+* Fix-forward again, and for the same reason: v0.5.6 and v0.5.7 are published and stay published.
+* Three releases in an hour, each fixing a defect the previous one introduced and a gate caught. That is
+  the gates working, but it is also a release process with no pre-flight of its own — which is the next
+  thing this project should fix rather than the next thing it should be proud of.
+* No runtime change: the code in v0.5.8 is the code in v0.5.6.
 # Changelog
 
 All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.5.5] — 2026-10-11
+## [0.5.7] — 2026-10-11
 
 ### Fixed
 
-* **The v0.5.4 loader failure, with the cause the loader actually reported** rather than the hypothesis
-  that stood in for it:
-
-  ```
-  w2m (@twinsearth/w2m-dsh-plugin/tools): Error: cannot get property "connection" without inject
-    at registerTargetRoutes (src/plugin/fleet-target.mjs:483:25)
-  ```
-
-  cordis throws on reading a service property the fiber never declared, so the entry died and took all
-  eight tools with it. **Every existing test was blind to this**, because they drive the plugin with a
-  plain-object context where an undeclared read merely yields `undefined` — the fake was more forgiving
-  than the runtime. Fixed with `ctx.inject(['connection'], …)`, which is also the only shape that can
-  work: in the real composition the service is genuinely absent while `apply()` runs, and siblings are
-  mounted concurrently.
-* **The client half was never composed either, for a second and independent reason:** the bundle row
-  named the subpath `@twinsearth/w2m-dsh-plugin/tools` instead of the package, and a client package is
-  identified by its Loader row specifier — a subpath resolves to no `package.json`, so `dsh.client` was
-  never read and no boot-graph row was built. The row now names the package.
-* **A silent route rejection:** the control fetched `/w2m/target`, but fetch routes are validated
-  against `/api/`, and the refusal failed only a child fiber, so nothing surfaced. Now
-  `/api/w2m/target`, mirrored in the shipped bundle.
-
-### Added
-
-* **`test/loader-entry.test.mjs`** — the test that would have caught v0.5.4: it packs the tree, installs
-  the tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
-  `DSH_HOME`, and boots it with the real `runProfile` under the Harness runtime, asserting that the
-  entry activates, all eight tools are registered, the boot-graph row is composed from the shipped
-  bundle, and no failed entry names the package. **Proved in both directions**: 6/6 pass on the fixed
-  tree and 6/6 fail against the preserved v0.5.4 tarball, failing on precisely the loader error quoted
-  above. It skips loudly, naming the probes it tried, when no installation is found.
-* Cheap always-on guards in `test/client-bundle.test.mjs` that need no Harness: the platform field, the
-  client export, the row must be the bare package name, and the bundle's route must equal the host's.
+* **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
 
-* **An upgrade from v0.5.4 requires one edit outside this package:** `cordis.patch.yml` in the profile
-  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 — silently reverting `rabbitUrl`,
-  `operatorToken`, `stateDir`, `projectDir`, `machineName`, `p2pMode` and `allowedCommands` to their
-  shipped defaults. Measured both ways with `--dump-config`.
-* **0.5.4 remains DO NOT INSTALL.** This release exists so that a rebuilt artifact is distinguishable
-  from the broken one by version alone.
-* 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.
+* 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
@@ -125,6 +117,58 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   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.5] — 2026-10-11
+
+### Fixed
+
+* **The v0.5.4 loader failure, with the cause the loader actually reported** rather than the hypothesis
+  that stood in for it:
+
+  ```
+  w2m (@twinsearth/w2m-dsh-plugin/tools): Error: cannot get property "connection" without inject
+    at registerTargetRoutes (src/plugin/fleet-target.mjs:483:25)
+  ```
+
+  cordis throws on reading a service property the fiber never declared, so the entry died and took all
+  eight tools with it. **Every existing test was blind to this**, because they drive the plugin with a
+  plain-object context where an undeclared read merely yields `undefined` — the fake was more forgiving
+  than the runtime. Fixed with `ctx.inject(['connection'], …)`, which is also the only shape that can
+  work: in the real composition the service is genuinely absent while `apply()` runs, and siblings are
+  mounted concurrently.
+* **The client half was never composed either, for a second and independent reason:** the bundle row
+  named the subpath `@twinsearth/w2m-dsh-plugin/tools` instead of the package, and a client package is
+  identified by its Loader row specifier — a subpath resolves to no `package.json`, so `dsh.client` was
+  never read and no boot-graph row was built. The row now names the package.
+* **A silent route rejection:** the control fetched `/w2m/target`, but fetch routes are validated
+  against `/api/`, and the refusal failed only a child fiber, so nothing surfaced. Now
+  `/api/w2m/target`, mirrored in the shipped bundle.
+
+### Added
+
+* **`test/loader-entry.test.mjs`** — the test that would have caught v0.5.4: it packs the tree, installs
+  the tarball with the installation's own `dsh plugin add` into a throwaway profile under a throwaway
+  `DSH_HOME`, and boots it with the real `runProfile` under the Harness runtime, asserting that the
+  entry activates, all eight tools are registered, the boot-graph row is composed from the shipped
+  bundle, and no failed entry names the package. **Proved in both directions**: 6/6 pass on the fixed
+  tree and 6/6 fail against the preserved v0.5.4 tarball, failing on precisely the loader error quoted
+  above. It skips loudly, naming the probes it tried, when no installation is found.
+* Cheap always-on guards in `test/client-bundle.test.mjs` that need no Harness: the platform field, the
+  client export, the row must be the bare package name, and the bundle's route must equal the host's.
+
+### Notes
+
+* **An upgrade from v0.5.4 requires one edit outside this package:** `cordis.patch.yml` in the profile
+  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 — silently reverting `rabbitUrl`,
+  `operatorToken`, `stateDir`, `projectDir`, `machineName`, `p2pMode` and `allowedCommands` to their
+  shipped defaults. Measured both ways with `--dump-config`.
+* **0.5.4 remains DO NOT INSTALL.** This release exists so that a rebuilt artifact is distinguishable
+  from the broken one by version alone.
+* 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.4] — 2026-10-11
 
 > **DO NOT INSTALL 0.5.4.** It fails to load in the Harness: the loader entry
@@ -165,6 +209,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   serves the plugin from the profile's `node_modules`; the new revision must be installed *and the
   Harness restarted* before the control appears. The control is therefore in the artifact and not in the
   running UI, and this entry says so rather than implying otherwise.
+
 ## [0.5.3] — 2026-10-11
 
 ### Added
@@ -194,6 +239,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 * Every socket in the new suite is loopback and crosses no NAT; that is stated in the suite header and
   is not evidence that a real translation can be crossed.
 * No protocol version bump: `envelope_version` stays `1.0` and a v0.4.x/v0.5.x peer is unaffected.
+
 ## [0.5.2] — 2026-10-10
 
 ### Fixed
@@ -227,6 +273,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 * This release exists because `deploy/` and `docs/` are inside the published package: after v0.5.1 the
   tag and the tarball had drifted, and a release is the only honest way to close that.
 * No runtime change to the eight tools.
+
 ## [0.5.1] — 2026-10-10
 
 ### Fixed
@@ -261,6 +308,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   supervisor leaves the agent alive with its punch socket still bound (`0.0.0.0:41235`).
 * Also included: the test fix for `test/outbound-only.test.mjs`, whose port was being read from the
   timestamp rather than from the field that states it (commit `57dbc5f`).
+
 ## [0.5.0] — 2026-10-10
 
 The release that stops treating "the relay carried it" as the only answer for a machine behind a
@@ -740,7 +788,6 @@ written down as not measured.
   this entry claim it is. The WAN measurement is one hop with one NAT, and it is
   labelled as one hop with one NAT.
 
-
 ## [0.3.9] — 2026-10-09
 
 P2P hole punching, so the payload path no longer has to cross the relay.

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/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.