@dmsdc-ai/aigentry-telepty 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [Unreleased]
+
+### Added — seamless cross-machine on Tailscale (auto bind + auto trust) (#672)
+
+- **On a Tailscale host, a fresh install is cross-machine-ready with zero manual env.** At
+  startup the daemon detects its tailnet interface (a `100.64.0.0/10` address, via a pure
+  live scan of `os.networkInterfaces()` — no subprocess, no `tailscale` CLI dependency) and
+  **binds :3848 to the tailnet IP only, plus loopback**. LAN/public interfaces stay closed,
+  so the inject/control API is reachable **only from your Tailnet** — this does **not**
+  reopen the telepty#50 / audit hole (it never binds `0.0.0.0`). Tailnet peers are trusted
+  automatically (Tailscale ACLs already gate tailnet membership), so no token/allowlist is
+  needed. The tailnet IP is **discovered live every start, never persisted** — a
+  Tailscale-reassigned IP is followed automatically.
+- **Preserved safe defaults & overrides.** No tailnet detected ⇒ loopback-only (telepty#50
+  unchanged). Manual `TELEPTY_BIND` / `HOST` / `TELEPTY_PEER_ALLOWLIST` always win over
+  auto-detect. New `TELEPTY_NO_TAILNET_AUTO=1` forces loopback even on a tailnet.
+- **Detection hardened against ISP-CGNAT.** `100.64.0.0/10` is also the shared ISP-CGNAT
+  range; detection prefers a Tailscale-named interface (`tailscale*` / `utun*` / a
+  `Tailscale` adapter) and, when it can only match by range, flags it in the banner so an
+  operator on ISP-CGNAT can opt out.
+- **`TELEPTY_PEER_ALLOWLIST` now supports CIDRs** (via native `net.BlockList`) as the
+  `:170` comment always documented; exact-IP entries keep exact-match semantics.
+- **Windows:** on the auto path the daemon adds the inbound firewall allow-rule
+  automatically when elevated, otherwise prints the exact one-time `netsh` command.
+- **Trust boundary (docs):** a Tailscale host auto-exposes :3848 to the *entire* tailnet;
+  restrict with `TELEPTY_PEER_ALLOWLIST` or disable with `TELEPTY_NO_TAILNET_AUTO=1`.
+  Zero-config cross-machine is Tailscale-specific; other topologies use the manual
+  `TELEPTY_BIND` path. Addressing stays IP-free — use MagicDNS names with `<id>@<host>`.
+
 ## [0.6.6] - 2026-06-14
 
 ### Fixed — duplicate same-id `allow` flap loop + `kill` doesn't stick (#56)

package/README.md

@@ -126,6 +126,34 @@ environment default is enabled.
 
 telepty auto-discovers sessions across your Tailnet. All commands (`list`, `attach`, `inject`, `rename`, `multicast`, `broadcast`) work seamlessly across machines.
 
+### Zero-config on Tailscale (auto bind + auto trust)
+
+On a host that is on a **Tailscale tailnet**, a fresh install is cross-machine-ready with
+**no manual env**. At startup the daemon detects its tailnet interface (a `100.64.0.0/10`
+address) and:
+
+- **binds :3848 to the tailnet IP only** (plus loopback) — LAN/public interfaces stay
+  closed, so the control API is reachable **only from your Tailnet**, never the flat LAN;
+- **trusts tailnet peers automatically** — Tailscale's own ACLs already gate who is on the
+  tailnet, so a tailnet peer needs no token or manual allowlist.
+
+> **Trust boundary:** on a Tailscale host, telepty auto-exposes :3848 to your **entire
+> tailnet** (every peer Tailscale's ACLs let onto it). If you share your tailnet with
+> machines you don't fully trust, set `TELEPTY_PEER_ALLOWLIST` to restrict to specific
+> peers/CIDRs, or `TELEPTY_NO_TAILNET_AUTO=1` to stay loopback-only.
+
+**Zero-config cross-machine is Tailscale-specific.** On a non-Tailscale host (plain LAN,
+other mesh VPNs) the daemon stays **loopback-only** (the safe default) — set `TELEPTY_BIND`
++ `TELEPTY_PEER_ALLOWLIST` manually to expose it. Manual `TELEPTY_BIND` / `HOST` /
+`TELEPTY_PEER_ALLOWLIST` always win over auto-detect.
+
+**Windows:** Defender Firewall blocks inbound on the tailnet interface by default. On the
+auto path the daemon adds the inbound allow-rule automatically when run elevated, otherwise
+it prints the exact one-time `netsh` command in the startup banner.
+
+Addressing stays **IP-free**: use MagicDNS / hostnames with `<id>@<host>` (below) — you
+never need to type a `100.x.y.z` address.
+
 ### `<id>@<host>` syntax
 
 To target a specific host (when the same session ID exists on multiple hosts,

package/daemon.js

@@ -12,6 +12,7 @@ const terminalBackend = require('./terminal-backend');
 const { installWebSocketTransport, isOpenWebSocket } = require('./src/transport/websocket');
 const { createPeerRelay, relayPeersFromEnv } = require('./src/transport/peer-relay');
 const { createAuthMiddleware, createIsAllowedPeer, createVerifyJwt } = require('./src/protocol/http-auth');
+const { detectTailnet, TAILNET_CIDR } = require('./src/net/tailnet');
 const { FileMailbox } = require('./src/mailbox/index');
 const { DeliveryEngine } = require('./src/mailbox/delivery');
 const { UnixSocketNotifier } = require('./src/mailbox/notifier');
@@ -170,6 +171,19 @@ app.use(express.json());
 // Peer allowlist: comma-separated IPs/CIDRs in TELEPTY_PEER_ALLOWLIST env
 const PEER_ALLOWLIST = (process.env.TELEPTY_PEER_ALLOWLIST || '').split(',').map(s => s.trim()).filter(Boolean);
 
+// #672 tailnet auto (seamless cross-machine): detect the tailnet interface once at boot
+// via a PURE live scan of os.networkInterfaces(). D1: the IP is discovered, never
+// configured — used only in-memory for this run, never persisted, and re-detected every
+// start so a Tailscale-reassigned IP is followed automatically. Broker mode has its own
+// network posture (HTTPS + per-node JWT) and is excluded from auto-bind/auto-trust.
+const TAILNET = brokerServer ? null : detectTailnet();
+const TAILNET_IP = TAILNET ? TAILNET.ip : null;
+const AUTO_TAILNET = isTailnetAuto(process.env, TAILNET_IP);
+// Auto-trust the tailnet CIDR on the auto path — safe because the socket is bound to the
+// tailnet interface only (§Q2). NEVER widen a manual allowlist: an operator's explicit
+// TELEPTY_PEER_ALLOWLIST is passed through verbatim.
+const effectivePeerAllowlist = resolveEffectivePeerAllowlist(PEER_ALLOWLIST, AUTO_TAILNET);
+
 // #533 Phase 2 — peer-lane inject guardrail. The orchestrator sid(s) define the
 // ORCH LANE (always allowed). Space-separated; default matches aigentry-orchestrator
 // bin/ask.sh so both ends agree on "who is the orchestrator" from one config. If this
@@ -265,7 +279,7 @@ const relayToPeers = createPeerRelay({
 const JWT_SECRET = process.env.TELEPTY_JWT_SECRET || null;
 
 const verifyJwt = createVerifyJwt(JWT_SECRET);
-const isAllowedPeer = createIsAllowedPeer(PEER_ALLOWLIST);
+const isAllowedPeer = createIsAllowedPeer(effectivePeerAllowlist);
 
 // Health check – no auth required
 app.get('/api/health', (req, res) => {
@@ -286,20 +300,71 @@ let boundPort = Number(PORT);
 // opt-in: TELEPTY_BIND=0.0.0.0 (preferred) or the legacy HOST override.
 // BREAKING: cross-machine peers that dialed this daemon directly over LAN
 // need the opt-in on the daemon host after a restart (see CHANGELOG).
-function resolveBindHost(env) {
-  return env.TELEPTY_BIND || env.HOST || '127.0.0.1';
+// Truthy for an opt-out/flag env var: set and not a falsey literal ('', '0', 'false').
+function isTruthyEnv(v) {
+  return v != null && v !== '' && v !== '0' && String(v).toLowerCase() !== 'false';
+}
+
+// #672 tailnet auto: the zero-config tailnet path is active only when a tailnet IP was
+// detected AND the operator set no manual bind override AND did not opt out.
+function isTailnetAuto(env, tailnetIp) {
+  return !!tailnetIp && !env.TELEPTY_BIND && !env.HOST && !isTruthyEnv(env.TELEPTY_NO_TAILNET_AUTO);
 }
 
-// One-line bind-address banner so operators can see (and fix) their exposure
-// posture at startup without reading docs.
-function formatBindHint(host) {
+// #672: auto-trust the tailnet CIDR ONLY when on the auto path with no manual allowlist.
+// A non-empty manual allowlist is respected verbatim (never widened to the whole /10).
+function resolveEffectivePeerAllowlist(peerAllowlist, autoTailnet) {
+  return (autoTailnet && peerAllowlist.length === 0) ? [TAILNET_CIDR] : peerAllowlist;
+}
+
+// telepty#50 + #672: loopback by default; explicit TELEPTY_BIND/HOST win; on a detected
+// tailnet with no override, bind the LIVE tailnet IP (never 0.0.0.0). The tailnetIp arg
+// is optional so legacy 1-arg callers keep the exact #50 behavior.
+function resolveBindHost(env, tailnetIp) {
+  if (env.TELEPTY_BIND) return env.TELEPTY_BIND;
+  if (env.HOST) return env.HOST;
+  if (isTailnetAuto(env, tailnetIp)) return tailnetIp;
+  return '127.0.0.1';
+}
+
+// Bind-address banner so operators can see (and fix) their exposure posture at startup
+// without reading docs. Multi-line for the tailnet/loopback cases (G2).
+function formatBindHint(host, tailnet) {
+  if (tailnet && host === tailnet.ip) {
+    const rangeNote = tailnet.nameMatched
+      ? ''
+      : `\n   note: tailnet IP matched by CGNAT range only (iface "${tailnet.iface}" not Tailscale-named) — if this is ISP-CGNAT, set TELEPTY_NO_TAILNET_AUTO=1`;
+    return `   bind: ${host} (tailnet auto) — reachable from your Tailnet only; LAN/public closed (loopback also served)${rangeNote}`;
+  }
   if (host === '127.0.0.1' || host === 'localhost' || host === '::1') {
-    return `   bind: ${host} (loopback only) — LAN peers cannot connect; opt in with TELEPTY_BIND=0.0.0.0`;
+    return `   bind: ${host} (loopback only) — LAN peers cannot connect; opt in with TELEPTY_BIND=0.0.0.0`
+      + `\n   cross-machine: zero-config needs Tailscale (auto-binds the tailnet); otherwise set TELEPTY_BIND + TELEPTY_PEER_ALLOWLIST`;
   }
   return `   bind: ${host} — reachable from the network (TELEPTY_BIND/HOST opt-in)`;
 }
 
-const HOST = resolveBindHost(process.env);
+// G1 (win32 only): a correct tailnet bind is not enough on Windows — Defender Firewall
+// blocks inbound on the tailnet iface by default. Detect the rule; auto-add if elevated,
+// else print the exact one-time command. Never fatal. No-op on mac/Linux.
+function maybeGuideWindowsFirewall(port) {
+  if (process.platform !== 'win32') return;
+  try {
+    const { ensureInboundRule } = require('./src/net/win-firewall');
+    const r = ensureInboundRule({ port });
+    if (r.action === 'exists') {
+      console.log(`   firewall: inbound rule "${r.ruleName}" present — tailnet peers can reach :${port}`);
+    } else if (r.action === 'added') {
+      console.log(`   firewall: added inbound allow rule "${r.ruleName}" for :${port} (TCP)`);
+    } else {
+      console.log(`   firewall: Windows blocks inbound on :${port} by default. Run once as Administrator:`);
+      console.log(`     ${r.command}`);
+    }
+  } catch (e) {
+    console.warn(`[FIREWALL] check skipped: ${e && e.message}`);
+  }
+}
+
+const HOST = resolveBindHost(process.env, TAILNET_IP);
 process.title = 'telepty-daemon';
 
 // Singleton claim — guarded so a test require neither exits (when a daemon is running) nor
@@ -4058,6 +4123,32 @@ if (require.main === module || process.env.AIGENTRY_TELEPTY_DAEMON_MAIN === '1')
       console.log(formatBindHint(HOST)); // telepty#50
       runStartupBootstrapRestore();
     });
+  } else if (AUTO_TAILNET) {
+    // #672 tailnet auto path: bind loopback as the PRIMARY (drives bootstrap/boundPort
+    // and effectively never fails), then add an additive best-effort listener on the
+    // live tailnet IP so tailnet peers reach :3848 — LAN/public sockets stay closed. An
+    // IP flap between detect and listen degrades to loopback-only (logged), never a
+    // crash. ponytail: no auto-rebind on flap — a restart re-detects; add a re-detect
+    // loop only if flaps prove real in the field.
+    server = app.listen(PORT, '127.0.0.1', () => {
+      const address = server.address();
+      boundPort = (address && address.port) || Number(PORT);
+      console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${boundPort}`);
+      console.log(formatBindHint(HOST, TAILNET));
+      maybeGuideWindowsFirewall(boundPort); // G1: Windows inbound-rule guide/auto-add
+      runStartupBootstrapRestore();
+      nodeBrokerClient = startNodeBrokerClient();
+    });
+    // Additive tailnet listener — same HTTP posture as the loopback primary (the daemon
+    // is HTTP by design; TLS is broker-mode only, and tailnet transport is already
+    // WireGuard-encrypted). app.listen() returns a fresh server, so this is a second
+    // socket on the same app. ponytail: fixed-PORT production shares one port on both
+    // listeners; a PORT=0 ephemeral run would split ports, but the auto path is never
+    // taken under PORT=0 in the suite (TELEPTY_NO_TAILNET_AUTO=1 default in setup-env.js).
+    const tailnetServer = app.listen(Number(PORT), TAILNET_IP);
+    tailnetServer.on('error', (e) => {
+      console.warn(`[BIND] tailnet listener ${TAILNET_IP}:${Number(PORT)} unavailable (staying loopback-only): ${e && e.message}`);
+    });
   } else {
     server = app.listen(PORT, HOST, () => {
       const address = server.address();
@@ -4447,6 +4538,8 @@ module.exports = {
   loadNodeBrokerConfig,           // node-mode: resolve broker.json / env config (or null)
   startNodeBrokerClient,          // node-mode: start createBrokerClient (default-OFF; in-process deliver)
   deliverInjectionToSession,      // §4.3: the in-process delivery wired into the broker-client
-  resolveBindHost,                // telepty#50: pure bind-address policy (loopback default, env opt-in)
-  formatBindHint,                 // telepty#50: startup bind/exposure banner line
+  resolveBindHost,                // telepty#50 + #672: pure bind-address policy (loopback default, env opt-in, tailnet auto)
+  formatBindHint,                 // telepty#50 + #672: startup bind/exposure banner line
+  isTailnetAuto,                  // #672: pure predicate — is the zero-config tailnet path active
+  resolveEffectivePeerAllowlist,  // #672: pure allowlist policy — auto-trust tailnet without widening a manual set
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -37,9 +37,9 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "preuninstall": "node scripts/preuninstall.js",
-    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
-    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/tailnet-autobind.test.js test/win-firewall.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/tailnet-autobind.test.js test/win-firewall.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
+    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/tailnet-autobind.test.js test/win-firewall.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.test.js test/telepty-kill.test.js test/dupid-flap-kill-stick-56.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/session-store-persistence.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/daemon-lifecycle-55.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js test/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/idle-unconfirmed-decayed-619.test.js test/inject-redeliver.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "typecheck": "tsc --noEmit",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },

package/src/net/tailnet.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// Tailnet detection for seamless cross-machine (tailnet auto-bind + auto-trust).
+// PURE + injectable: takes an os.networkInterfaces()-shaped object so the decision
+// logic is unit-testable without a real tailnet. No subprocess (no `tailscale` CLI):
+// the interface scan already yields the bind IP, and a child_process call would only
+// add a PATH/exec failure mode + a command-injection surface. Article-17 fallback IS
+// the scan itself.
+
+const os = require('os');
+const net = require('net');
+
+// Tailscale assigns node IPs from the CGNAT range 100.64.0.0/10 (100.64.0.0 –
+// 100.127.255.255). This is also the *effective trust CIDR* — safe only because the
+// daemon binds the socket to the tailnet interface itself (see daemon.js), so only
+// WireGuard-tunneled tailnet peers can reach it.
+const TAILNET_CIDR = '100.64.0.0/10';
+
+const _cgnat = new net.BlockList();
+_cgnat.addSubnet('100.64.0.0', 10, 'ipv4');
+function inTailnetRange(ip) {
+  return typeof ip === 'string' && net.isIPv4(ip) && _cgnat.check(ip, 'ipv4');
+}
+
+// R1: 100.64.0.0/10 is ALSO the shared ISP-CGNAT range — a machine directly on ISP
+// CGNAT (some VPS/direct-modem setups) can carry a 100.64.x address on a REAL,
+// non-Tailscale interface. Binding+trusting that would expose :3848 to the ISP-CGNAT
+// segment (other customers). The iface NAME (already a key in networkInterfaces())
+// disambiguates at zero cost: prefer a Tailscale-named iface; fall back to range-only
+// only when none is named, and flag that fallback so an operator can see + opt out.
+const TAILSCALE_NAME = /tailscale|^utun/i; // tailscale0 (Linux) / utun* (macOS) / Tailscale adapter (Windows)
+
+function isIPv4Addr(addr) {
+  return addr && !addr.internal && (addr.family === 'IPv4' || addr.family === 4);
+}
+
+// Returns { ip, iface, nameMatched } for the tailnet interface, or null if none.
+//   nameMatched=true  → iface name looked like Tailscale (high confidence)
+//   nameMatched=false → range-only fallback (could be ISP-CGNAT; caller flags it)
+function detectTailnet(interfaces = os.networkInterfaces()) {
+  if (!interfaces || typeof interfaces !== 'object') return null;
+  let rangeOnly = null; // first in-range candidate whose name did NOT match
+  for (const iface of Object.keys(interfaces)) {
+    const addrs = interfaces[iface];
+    if (!Array.isArray(addrs)) continue;
+    for (const addr of addrs) {
+      if (!isIPv4Addr(addr) || !inTailnetRange(addr.address)) continue;
+      if (TAILSCALE_NAME.test(iface)) {
+        return { ip: addr.address, iface, nameMatched: true }; // name + range → done
+      }
+      if (!rangeOnly) rangeOnly = { ip: addr.address, iface, nameMatched: false };
+    }
+  }
+  return rangeOnly; // range-only fallback, or null when no candidate at all
+}
+
+// Convenience for callers that only need the bind IP.
+function detectTailnetIp(interfaces) {
+  const d = detectTailnet(interfaces);
+  return d ? d.ip : null;
+}
+
+module.exports = { detectTailnet, detectTailnetIp, inTailnetRange, TAILNET_CIDR };

package/src/net/win-firewall.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// G1 (Windows only): auto-binding the tailnet interface is necessary but NOT sufficient
+// on Windows — Defender Firewall blocks inbound on the tailnet iface by default, so a
+// tailnet peer still can't reach :3848 after a correct bind. Detect the inbound rule; add
+// it automatically when the daemon runs elevated, otherwise print the exact one-time
+// command. Never fatal. ponytail: no cross-firewall abstraction — mac/Linux need nothing.
+//
+// SECURITY: uses spawnSync with an ARGUMENT ARRAY (no shell) and the only interpolated
+// value is the port, validated to an integer in [1,65535] — no command-injection surface.
+
+const { spawnSync } = require('child_process');
+
+function toPort(port) {
+  const p = Math.trunc(Number(port));
+  if (!Number.isInteger(p) || p < 1 || p > 65535) throw new Error(`invalid port: ${port}`);
+  return p;
+}
+
+function firewallRuleName(port) {
+  return `telepty-${toPort(port)}`;
+}
+
+function addRuleArgs(port) {
+  const p = toPort(port);
+  return ['advfirewall', 'firewall', 'add', 'rule', `name=telepty-${p}`, 'dir=in', 'action=allow', 'protocol=TCP', `localport=${p}`];
+}
+
+function showRuleArgs(port) {
+  return ['advfirewall', 'firewall', 'show', 'rule', `name=telepty-${toPort(port)}`];
+}
+
+// The copy-pasteable command shown in the banner when we can't add it ourselves.
+function commandString(port) {
+  const p = toPort(port);
+  return `netsh advfirewall firewall add rule name="telepty-${p}" dir=in action=allow protocol=TCP localport=${p}`;
+}
+
+// runner is injectable for tests: (args) => { status, stdout, stderr, error }
+function defaultRunner(args) {
+  const r = spawnSync('netsh', args, { encoding: 'utf8', windowsHide: true });
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '', error: r.error };
+}
+
+function ruleExists(port, runner = defaultRunner) {
+  const r = runner(showRuleArgs(port));
+  // netsh 'show rule' → status 0 + rule text when present; nonzero / "No rules match" when absent.
+  if (!r || r.error) return false;
+  return r.status === 0 && /telepty-\d+/i.test(r.stdout || '');
+}
+
+// Returns { action: 'exists'|'added'|'guide', ruleName, command }.
+function ensureInboundRule({ port, runner = defaultRunner } = {}) {
+  const ruleName = firewallRuleName(port);
+  const command = commandString(port);
+  if (ruleExists(port, runner)) return { action: 'exists', ruleName, command };
+  const add = runner(addRuleArgs(port));
+  if (add && !add.error && add.status === 0) return { action: 'added', ruleName, command };
+  // unelevated or failed → guide the operator, never crash
+  return { action: 'guide', ruleName, command };
+}
+
+module.exports = { firewallRuleName, addRuleArgs, showRuleArgs, commandString, ruleExists, ensureInboundRule };

package/src/protocol/http-auth.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const net = require('net');
 
 function createVerifyJwt(JWT_SECRET) {
   function verifyJwt(token) {
@@ -53,16 +54,47 @@ function isRevokedNode(revokedNodes, decodedJwtOrSub) {
   return false;
 }
 
+// Build a net.BlockList from allowlist entries so the ":170 comment"-promised
+// "IPs/CIDRs" actually work: `a.b.c.d/n` → subnet, plain IP → exact address (exact
+// entries keep the prior includes() semantics). Native (Node v15+), zero-dep. A
+// malformed entry is skipped, never fatal. Returns null when the list is empty so the
+// caller can preserve the "empty = allow all authenticated" branch.
+function buildAllowBlockList(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  const bl = new net.BlockList();
+  for (const raw of entries) {
+    const entry = String(raw).trim();
+    if (!entry) continue;
+    try {
+      const slash = entry.indexOf('/');
+      if (slash !== -1) {
+        const addr = entry.slice(0, slash);
+        const prefix = Number(entry.slice(slash + 1));
+        const type = net.isIPv6(addr) ? 'ipv6' : 'ipv4';
+        bl.addSubnet(addr, prefix, type);
+      } else {
+        const type = net.isIPv6(entry) ? 'ipv6' : 'ipv4';
+        bl.addAddress(entry, type);
+      }
+    } catch { /* skip a malformed allowlist entry — never crash the daemon */ }
+  }
+  return bl;
+}
+
 function createIsAllowedPeer(PEER_ALLOWLIST) {
+  const blockList = buildAllowBlockList(PEER_ALLOWLIST);
   function isAllowedPeer(ip) {
     if (!ip) return false;
     const cleanIp = ip.replace('::ffff:', '');
-    // Localhost always allowed (includes SSH tunnel traffic)
+    // Localhost always allowed (includes SSH tunnel traffic). FIRST — auto-populating
+    // the allowlist can never tighten loopback.
     if (cleanIp === '127.0.0.1' || ip === '::1') return true;
-    // Peer allowlist
-    if (PEER_ALLOWLIST.length > 0) return PEER_ALLOWLIST.includes(cleanIp);
-    // No allowlist = allow all authenticated
-    return true;
+    // No allowlist = allow all authenticated (preserved)
+    if (!blockList) return true;
+    // Peer allowlist — CIDR + exact match
+    try {
+      return blockList.check(cleanIp, net.isIPv6(cleanIp) ? 'ipv6' : 'ipv4');
+    } catch { return false; }
   }
 
   return isAllowedPeer;