@yawlabs/tailscale-mcp 0.23.0 → 0.23.2

package/README.md

@@ -732,17 +732,17 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 
 ## Running on oam.js (optional)
 
-[oam.js](https://oamjs.org) runs this server unmodified, and the `tailscale-mcp` command only ever uses the **latest oam release, currently 0.18.0**. Verified against the published oam 0.18.0: full MCP handshake, all 97 admin-API tools plus `tailscale_tool_groups`, all 4 resources, identical error responses, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+[oam.js](https://oamjs.org) runs this server unmodified, and the `tailscale-mcp` command only ever uses the **latest oam release, currently 0.19.5**. Verified against the published oam 0.19.5: full MCP handshake, all 97 admin-API tools plus `tailscale_tool_groups`, all 4 resources, identical error responses, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
 
-**oam 0.18.0 is the minimum.** A floor matters here: releases before 0.9.0 ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument, and this server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one.
+**oam 0.19.5 is the minimum.** A floor matters here: releases before 0.9.0 ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument, and this server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one.
 
 How the `tailscale-mcp` command (`bin/tailscale-mcp.mjs`) picks a runtime:
 
-- **`TAILSCALE_MCP_RUNTIME=auto`** (the default) — if a client already launched it with `oam run` on oam 0.18.0 or newer, the server runs in that process. Otherwise it uses `OAM_BIN` when that is 0.18.0 or newer, else asks every oam binary it can find — `OAM_INSTALL_DIR` when that is set, then `%LOCALAPPDATA%\oam\bin` and `~/.oam/bin` on Windows, `~/.oam/bin` elsewhere, then `PATH` — for its version and uses the newest at or above the floor (on a tie the installed copy wins). With none, it runs on Node. An oam host older than 0.18.0 never serves the server itself: it hands off to the newest usable oam, or to Node on `PATH`, or exits with an error when there is neither. Whenever it looks for an oam, stderr names an `OAM_BIN` that was passed over and why; the oam binaries it found and passed over are named, each with its reason, only when no usable oam turns up.
+- **`TAILSCALE_MCP_RUNTIME=auto`** (the default) — if a client already launched it with `oam run` on oam 0.19.5 or newer, the server runs in that process. Otherwise it uses `OAM_BIN` when that is 0.19.5 or newer, else asks every oam binary it can find — `OAM_INSTALL_DIR` when that is set, then `%LOCALAPPDATA%\oam\bin` and `~/.oam/bin` on Windows, `~/.oam/bin` elsewhere, then `PATH` — for its version and uses the newest at or above the floor (on a tie the installed copy wins). With none, it runs on Node. An oam host older than 0.19.5 never serves the server itself: it hands off to the newest usable oam, or to Node on `PATH`, or exits with an error when there is neither. Whenever it looks for an oam, stderr names an `OAM_BIN` that was passed over and why; the oam binaries it found and passed over are named, each with its reason, only when no usable oam turns up.
 - **`TAILSCALE_MCP_RUNTIME=oam`** — the same, but exit with an error instead of falling back to Node. The error names the remedy for what it actually found: `oam self-update` for an oam older than the floor, a check of the binary for one that would not run, and installing oam only when none was found (and on linux-arm64, which oam publishes no build for, not even then).
 - **`TAILSCALE_MCP_RUNTIME=node`** — always Node: in-process under `npx`, handed off to Node on `PATH` when a client launches the command with `oam run`.
 
-The value is case-insensitive; anything else is warned about on stderr and treated as `auto`. On Windows only `oam.exe` counts: an `oam.cmd` / `oam.bat` shim is never run, and it is named on stderr only when no usable oam turns up.
+The value is case-insensitive and surrounding whitespace is ignored; anything else is warned about on stderr and treated as `auto`. On Windows only `oam.exe` counts: an `oam.cmd` / `oam.bat` shim is never run, and it is named on stderr only when no usable oam turns up.
 
 ### Sandboxing (opt-in)
 
@@ -767,14 +767,14 @@ The sandbox applies to the CLI subcommands too, and with the filesystem denied `
 }
 ```
 
-**Measure startup on your own hardware.** An MCP client cold-starts this server once per session, so startup is the cost that actually gets paid, and on the machine this was measured on node won it — 437ms vs 1554ms for `oam run` over 10 warmed runs (an earlier 5-run round showed 326ms vs 427ms; the box was busy, so treat the magnitude as noisy and the direction as the finding). Those runs used an oam that predates the 0.18.0 floor and have not been repeated since, so do not read them as a current ranking.
+**Measure startup on your own hardware.** An MCP client cold-starts this server once per session, so startup is the cost that actually gets paid, and on the machine this was measured on node won it — 437ms vs 1554ms for `oam run` over 10 warmed runs (an earlier 5-run round showed 326ms vs 427ms; the box was busy, so treat the magnitude as noisy and the direction as the finding). Those runs were taken with an oam older than 0.18.0 and have not been repeated since, so do not read them as a current ranking.
 
 The published `tailscale-mcp` command prefers the newest usable oam it finds (see above). Without oam that costs almost nothing: discovery is file-existence checks only, never a subprocess, and the fallback runs the server inside the Node process npm already started. With oam installed, though, the command boots Node, runs `--version` on every oam binary it found to pick the newest, and only then boots oam, so it is always slower than pointing your client at a runtime directly — the config above for oam, `node /path/to/tailscale-mcp/dist/index.js` for Node. `TAILSCALE_MCP_RUNTIME=node` skips oam entirely.
 
 Two places oam *does* win for this repo, both opt-in and neither touching the npm package:
 
 - **`npm run check:oam`** — type-checks via `oam check` (tsgo, TypeScript 7 native). Measured 4015ms against 7680ms for `tsc --noEmit`, same clean result. `npx tsc --noEmit` remains the portable default.
-- **`npm run build:binary:oam`** — builds the standalone binary via `oam compile` instead of Node SEA. Measured ~57.7 MB against ~73.6 MB for the Node SEA carrier *before* its blob is injected. Writes `bin/<platform>-<arch>/` (or `bin/$TAILSCALE_MCP_BINARY_TARGET/` for a cross-build), while `npm run build:binary` adds a `-glibc` / `-musl` suffix on Linux; `scripts/stage-release-asset.mjs` looks in both and stages the newer build — run one or the other per target. If you redistribute that binary it embeds oam's runtime, so ship oam's `LICENSE`, `NOTICE` and `THIRD_PARTY_LICENSES.md` with it. A cross-build (`TAILSCALE_MCP_BINARY_TARGET=<platform>-<arch>`) downloads the target's oam release binary as its carrier and checks it against the release's signed `RELEASE-MANIFEST`, verified with `ssh-keygen -Y verify` (OpenSSH 8.1+) against oam's release keys in `scripts/oam-release-keys/`; it aborts when the signature, the manifest or the checksum does not check out. An `OAM_VERSION` older than v0.18.0, released before oam signed its releases, is checked against its `SHA256SUMS` only once that file matches the digest pinned for the tag in `scripts/oam-release-keys/presigning-sums`.
+- **`npm run build:binary:oam`** — builds the standalone binary via `oam compile` (~57.7 MB measured). Writes `bin/<platform>-<arch>/` (or `bin/$TAILSCALE_MCP_BINARY_TARGET/` for a cross-build), which `scripts/stage-release-asset.mjs` then stages under the public asset name. If you redistribute that binary it embeds oam's runtime, so ship oam's `LICENSE`, `NOTICE` and `THIRD_PARTY_LICENSES.md` with it. A cross-build (`TAILSCALE_MCP_BINARY_TARGET=<platform>-<arch>`) downloads the target's oam release binary as its carrier and checks it against the release's signed `RELEASE-MANIFEST`, verified with `ssh-keygen -Y verify` (OpenSSH 8.1+) against oam's release keys in `scripts/oam-release-keys/`; it aborts when the signature, the manifest or the checksum does not check out. An `OAM_VERSION` below v0.18.0, released before oam signed its releases, is checked against its `SHA256SUMS` only once that file matches the digest pinned for the tag in `scripts/oam-release-keys/presigning-sums`.
 
 The source stays runtime-agnostic on purpose: no `oam:` imports anywhere, and tests stay on `node:test`. That is what keeps the Node fallback real rather than nominal. Note that any `oam` invocation writes a bytecode cache to `oam/` in the working directory — already in `.gitignore`.
 

package/bin/tailscale-mcp.mjs

@@ -105,7 +105,7 @@
  * shipped bundle; keep it in step.
  *
  * MINIMUM OAM VERSION
- * The latest oam release, 0.18.0 -- bump OAM_MIN when oam ships a newer one.
+ * The latest oam release, 0.19.5 -- bump OAM_MIN when oam ships a newer one.
  * Only the current oam is used and verified; an older one is passed over for a
  * newer oam, or for Node. The floor is not cosmetic: before 0.9.0
  * `child_process.execFile` ran its arguments through a SHELL, `exec` accepted
@@ -138,7 +138,7 @@ import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The latest oam release, and the oldest one used. See MINIMUM OAM VERSION above. */
-const OAM_MIN = [0, 18, 0];
+const OAM_MIN = [0, 19, 5];
 
 /**
  * The oldest Node this package supports, matching package.json `engines.node`.
@@ -353,6 +353,15 @@ function fallbackInProcess(hostOam) {
   return hostOam === undefined || atLeast(parseVersion(hostOam), OAM_MIN);
 }
 
+/**
+ * True when an on/off opt-in is set: "1" or "true", any case, surrounding
+ * whitespace ignored -- cmd.exe's `set FOO=1 && ...` stores "1 ". The same rule
+ * as envFlagOn in src/env-flag.ts; this file is plain .mjs and cannot import it.
+ */
+function envFlagOn(value) {
+  return /^(1|true)$/i.test((value ?? "").trim());
+}
+
 /**
  * The `--permission` grant list, or [] when the sandbox is not requested.
  *
@@ -360,7 +369,7 @@ function fallbackInProcess(hostOam) {
  * not after it. `oam run --permission file.js` is rejected outright, which is a
  * good failure but only because it is loud -- ordering here is load-bearing.
  *
- * Net grants, since oam 0.18.0 (the floor): an entry without a port admits that
+ * Net grants, as of oam 0.18.0: an entry without a port admits that
  * host on every port, and a `host:port` entry admits that port alone -- for
  * fetch and https.request exactly as for sockets. Up to 0.17.1 a port-scoped
  * entry admitted no HTTP request at all, which is why this used to be a bare
@@ -370,7 +379,7 @@ function fallbackInProcess(hostOam) {
  * it produces silent misbehaviour, not a clear denial.
  */
 function sandboxFlags() {
-  if (process.env.TAILSCALE_MCP_SANDBOX !== "1") return [];
+  if (!envFlagOn(process.env.TAILSCALE_MCP_SANDBOX)) return [];
 
   // ONE host, deliberately. Every outbound request the bundle makes targets
   // api.tailscale.com: BASE_URL, the OAuth token exchange, and the absolute-URL
@@ -858,11 +867,12 @@ if (nodeFloorMessage) {
 // which is the opposite of what was asked for. Same handling as index.ts gives
 // an unknown subcommand: auto is still the right landing place, it just stops
 // being silent. An empty value is treated as unset, since `FOO=$UNSET` in a
-// wrapper script is how it usually gets there.
+// wrapper script is how it usually gets there, and surrounding whitespace is
+// dropped first: cmd.exe's `set TAILSCALE_MCP_RUNTIME=node && ...` stores "node ".
 const RUNTIMES = ["auto", "node", "oam"];
 const requested = process.env.TAILSCALE_MCP_RUNTIME;
-const mode = (requested ?? "auto").toLowerCase();
-if (requested && !RUNTIMES.includes(mode)) {
+const mode = (requested?.trim() || "auto").toLowerCase();
+if (requested?.trim() && !RUNTIMES.includes(mode)) {
   // Echo what was SET, not the lowercased form, so the typo is recognisable in
   // the host's log next to the config line that produced it.
   errSync(
@@ -876,6 +886,14 @@ const hostOam = process.versions.oam;
 // "would the spawn carry --permission" cannot drift from what the spawn below
 // actually passes.
 const sandbox = sandboxFlags();
+// A security opt-in that did not take must not be silent: "yes" or "on" reads as
+// a request for the sandbox, and serving unsandboxed without a word would hide it.
+const sandboxRaw = (process.env.TAILSCALE_MCP_SANDBOX ?? "").trim();
+if (sandbox.length === 0 && sandboxRaw !== "") {
+  errSync(
+    `tailscale-mcp: TAILSCALE_MCP_SANDBOX="${process.env.TAILSCALE_MCP_SANDBOX}" is not 1 or true -- the sandbox is NOT enabled.\n`,
+  );
+}
 const plan = runtimePlan({ mode, hostOam, sandbox: sandbox.length > 0 });
 
 if (plan === "in-process") {