Remote-access security hardening: audit + lock down the any-device→tunnel→shell path

[dotdevdotdev]

Umbrella: portal-boundary hardening

Re-scoped 2026-06-18 after the security audit (audit comment) + the #420 networking review. Original framing ("wide-open, unaudited any-device→tunnel→shell") was stale on two counts:

1. The core ask already shipped (PR feat(portal): security hardening — origin checks + token auth (close the no-auth gap behind the bind default) #247/feat(portal): security hardening — origin checks + token auth (#247) #248): server.host defaults to 127.0.0.1, bearer-token auth, refuse-to-start-without-token on non-loopback, constant-time compare, MCP is stdio-only (never network-exposed).
2. agentwire owns no internet tunnel (Networking/tunnel footprint review: what does agentwire own, and should it? #420): the "from anywhere" path is the user's own cloudflared/tailscale. agentwire's responsibility ends at "the portal refuses unauthenticated requests regardless of what's in front of it." This issue hardens only the portal listener — not tunnels, not remote-machine SSH.

Residual gaps → follow-up issues

Created (high-risk — leaked-token blast radius):

• Per-device portal credentials + pairing flow #423 — Per-device portal credentials + pairing flow (single shared god-token → named, revocable per-device)
• Capability scopes for portal devices (full vs ptt) #424 — Capability scopes (full vs ptt) (leaked PTT token = RCE → "can talk to one session")
• Freeze security-critical config from the portal API #425 — Freeze security-critical config from the API (token can currently disable its own auth + safety rules)

Backlog (pull when ready):

• Auth-failure audit log + per-IP lockout + optional owner email on a burst (reuse Resend)
• TLS-or-loopback enforcement (refuse non-loopback plaintext bind without explicit --insecure)
• Reduce unauthenticated fingerprint (/health, /, /mobile confirm agentwire pre-token) — low priority
• Verify/fix artifact path-traversal on DELETE /api/artifacts/{filename:.+} + upload write target

Retracted: "retire the remote SSH terminal branch" — that's cross-machine session viewing, KEEP (see #420).

Verification (baseline, already satisfiable)

From a second device without the token, every non-public route returns 401; with the token, full access works. #423/#424 are what make "full access" scoped instead of all-or-nothing.

[dotdevdotdev]

Remote-access security audit (audit-only — no code changed)

Read the actual listener (agentwire/server.py), the auth layer (agentwire/security.py), tunnels/network (tunnels.py, network.py), the MCP entrypoint (mcp_server.py), config defaults (config.py), and the frontend token handling (static/js/api.js, token-modal.js, mobile.js).

Headline: the core ask is already shipped

The issue's premise — "wide-open, currently-unaudited" — is stale. PR #247/#248 already landed exactly the model #295's launch copy promises:

• server.host defaults to 127.0.0.1 (config.py:61). Loopback by default.
• Bearer-token auth (security.py): token at ~/.agentwire/portal.token (0600, auto-generated). HTTP Authorization: Bearer <t>, WebSocket agentwire.bearer.<t> subprotocol. Constant-time compare (hmac.compare_digest).
• Non-loopback bind refuses to start without a token (validate_startup_security, wired at server.py:5778-5782). auth_token: "" disables auth but is only sane on loopback.
• Origin/CSRF check on every mutation + WS upgrade, always on.
• MCP server is stdio-only (mcp_server.py:2857, transport="stdio") — started by Claude Code locally, never network-exposed. Not part of the tunnel surface at all.

So this audit reframes from "build auth" to "validate the control + close the residual gaps," which are real and material.

---

Surface inventory (everything the listener exposes)

aiohttp app, ~90 routes, bind 127.0.0.1:8765 (configurable). Two tiers:

Public / unauthenticated (_is_public_path): GET /, GET /mobile, GET /health, GET /static/*. Page shells + healthcheck only — do nothing without the token, but confirm "an agentwire portal lives here" to anyone with the URL (fingerprint).

Token-gated (everything else), by blast radius:

Tier	Routes	If token leaks
CRITICAL — full RCE	GET /ws/terminal/{name} (tmux attach → live interactive shell, incl. ssh -t … tmux attach to remote machines), POST /send/{name} (arbitrary keystrokes into a session), POST /api/create / …/recreate / …/spawn-sibling / …/fork, POST /api/scheduler/tasks/{name}/run, POST /api/desktop/*, POST /api/council/start	Own the dev box, and any SSH-reachable remote machine.
HIGH — config/secrets + persistence	POST /api/config (writes raw ~/.agentwire/config.yaml — can rewrite executables/services = RCE, set host, or set auth_token: "" to disable auth entirely), POST /api/config/reload, POST /api/safety/config (disable the rm-rf damage-control rules), POST /api/machines / DELETE (add/remove SSH targets)	Persist, escalate, and turn off the safety net with the same token.
MEDIUM — info disclosure	GET /api/sessions{,/local,/remote}, /api/projects, /api/history{,/{id}} (+resume), /api/roles, /api/scratchpad, /api/scheduler/{board,events,live}, /api/council/archive, session output WS /ws/{name}	Leak project paths, full conversation history, machine inventory, notes.
MEDIUM — input/cost/write	POST /transcribe (burns cloud STT credits if a cloud backend is set), POST /upload → ~/.agentwire/uploads/, POST /api/artifacts/upload + DELETE /api/artifacts/{filename:.+} (served at /artifacts — stored-content vector; the .+ regex on delete wants a path-traversal check)	Credit burn, disk writes, possible traversal.

Auth is binary and god-mode: one shared token unlocks the entire table above. There is no read-only tier and no per-device identity.

---

Risk assessment — residual gaps

1. Single shared token, not per-device (the explicit Remote-access security hardening: audit + lock down the any-device→tunnel→shell path #396 ask). Every device — your laptop and a phone that only ever does PTT — holds the same god token. Can't revoke one device, can't attribute actions, rotation logs out everyone. Token sits in localStorage, pasted via a 401 modal.
2. No command scoping. Token = full API. A phone whose only job is push-to-talk can tmux attach and get a root-equivalent shell. PTT should be a capability subset, not the whole surface.
3. Config-write is an auth-disable + RCE pivot. POST /api/config writes raw YAML — an attacker who's in can set auth_token: "", rewrite executables, and persist. Read-side redaction (server.py:3583) is cosmetic; the write path is unrestricted.
4. Safety rules are API-writable. POST /api/safety/config can disable the damage-control hooks (rm -rf blocking) with the same token — defense-in-depth defeated by one secret.
5. No auth-failure logging, no lockout, no alerting. 401s are silent. A leaked URL being probed produces no audit trail and no owner notification (Resend is already wired for usage-limit recovery — reusable here).
6. Token transport relies on TLS that's opt-in. SSL only turns on if cert+key exist (config.py:45). A non-loopback plaintext LAN bind sends the bearer token in cleartext. Fine when the BYO ingress tunnel terminates TLS (cloudflared/tailscale do); a footgun for a bare LAN bind.
7. Unauthenticated fingerprint. /health, /, /mobile confirm agentwire before any token check.

What's already good: loopback default, refuse-to-start guard, constant-time compare, WS token in subprotocol (not the URL, so it stays out of logs/referrers), MCP off the network entirely.

---

Proposed actions → surface each closes

• A. Bless the shipped baseline (loopback default + refuse-to-start). Document as the floor. Closes the "wide-open" framing.
• B. Per-device credentials + pairing flow. Replace the single token with named, individually-revocable device tokens issued via a host-shown pairing code / QR (agentwire portal pair), registry under ~/.agentwire/. Closes Simplified CLI commands with consistent -s/--session pattern #1; enables feat: permission modes for per-session permission control #2 and feat: enhanced Create Session form with machine selector, worktrees, and validation #5 attribution.
• C. Capability scopes per device (full vs ptt). Middleware maps device→scope→route allowlist; ptt may transcribe + send to a whitelisted session only — no terminal WS, no create, no config, no safety. Closes feat: permission modes for per-session permission control #2; shrinks a leaked phone token from RCE to "can talk to one session."
• D. Freeze security-critical config from the API. auth_token, server.host, executables, and safety-disable become file-edit-on-host only; reject them in POST /api/config & /api/safety/config. Closes feat: refactor templates from custom regex to Jinja2 #3, feat: CLI full parity with remote support and worktrees #4.
• E. Auth-failure audit log + coarse per-IP lockout, optional owner email on a burst (reuse Resend). Closes feat: enhanced Create Session form with machine selector, worktrees, and validation #5.
• F. TLS-or-loopback enforcement. Refuse a non-loopback plaintext bind unless --insecure is explicit; document that the BYO tunnel must terminate TLS. Closes feat: add restricted permission mode for voice-only sessions #6.
• G. Reduce unauthenticated fingerprint. Minimal /health; optionally a generic token-gate on / and /mobile. Closes feat: Network-aware CLI with tunnels and remote commands #7 (low priority).
• H. Verify artifact path-traversal on DELETE /api/artifacts/{filename:.+} + upload write target. Closes the open question in the MEDIUM tier.

---

Coordination with #420 (networking footprint)

The exposure #396 is about is NOT owned by agentwire today. The internet-facing "any-device→shell" path is the user's own ingress tunnel (cloudflared/ngrok/tailscale) pointed at portal:8765. Agentwire's tunnels.py is the opposite direction — outbound ssh -L forwards FROM this host TO remote agentwire services (host→host, not internet ingress).

Implications for sequencing:

• The listener hardening (B–G) is needed regardless of Networking/tunnel footprint review: what does agentwire own, and should it? #420. It hardens our listener, which is ours no matter who owns the tunnel. It should not wait on Networking/tunnel footprint review: what does agentwire own, and should it? #420.
• What Networking/tunnel footprint review: what does agentwire own, and should it? #420 could shrink is the multi-host plumbing, not the exposure: tunnels.py, network.py, machines.json, the tunnels up/down/status CLI+MCP. If Networking/tunnel footprint review: what does agentwire own, and should it? #420 cuts those, this audit's internet surface is unchanged (it was never the exposure), but the remote-machine branch of handle_terminal_ws (ssh -t … tmux attach, server.py:1979-1998) and the remote-add machine routes would go with it.
• Recommendation: proceed with B–G now; gate only proposed issue feat: implement session templates for pre-configured session setups #8 below on Networking/tunnel footprint review: what does agentwire own, and should it? #420's keep/cut.

---

Proposed follow-up implementation issues (NOT created — for your approval)

1. Per-device portal credentials + pairing flow — named, individually-revocable device tokens via a host-shown pairing code; agentwire portal pair + device registry. (action B)
2. Capability scopes for portal devices (full vs ptt) — middleware-enforced per-device route allowlists; PTT limited to transcribe + send to a whitelisted session. (action C)
3. Freeze security-critical config from the API — auth_token/host/executables/safety-disable become host-file-only, rejected by the config & safety POST endpoints. (action D)
4. Auth-failure audit logging + per-IP lockout — log 401s with source to ~/.agentwire/logs/, coarse backoff, optional owner email on a burst. (action E)
5. TLS-or-loopback enforcement — refuse non-loopback plaintext bind without --insecure; document BYO-tunnel-terminates-TLS. (action F)
6. Reduce unauthenticated fingerprint — minimal /health, optional generic token-gate on the page shells. (action G)
7. Verify + fix artifact path-traversal — audit DELETE /api/artifacts/{filename:.+} and upload write paths; constrain to the artifacts dir. (action H)
8. (gated on Networking/tunnel footprint review: what does agentwire own, and should it? #420) Retire the remote-machine SSH terminal branch — only if Networking/tunnel footprint review: what does agentwire own, and should it? #420 cuts multi-host networking: remove the remote ssh … tmux attach path + tunnels/network wiring.

Verification (from the issue) is already satisfiable today: from a second device without the token, every non-public route returns 401; with the token, full access works. The gap this audit surfaces is that "full access" is all-or-nothing — issues 1 & 2 are what make it scoped.

[dotdevdotdev]

Re-scope (per #420's networking review)

#420 confirmed what my audit flagged and made it sharper: agentwire ships zero tunnel-provider code — the phone→portal tunnel is 100% bring-your-own (Cloudflare/Tailscale/ngrok, docs-only). So agentwire's security responsibility ends at "the portal refuses unauthenticated requests regardless of what's in front of it." It cannot and should not harden the user's tunnel.

That maps cleanly onto my audit above — everything in my surface inventory, risk table, and actions A–G is the portal's local security boundary (bind host, bearer/per-device auth, command scoping, config/safety lockdown, 401 logging, TLS). All of it stands unchanged. This is exactly #420's touchpoint C — KEEP, the only thing #396 should harden.

Two retractions to stay out of #420's lane:

• Proposed issue feat: implement session templates for pre-configured session setups #8 (retire the remote-machine SSH terminal branch) — withdrawn. That's the SSH service-router, which Networking/tunnel footprint review: what does agentwire own, and should it? #420 owns and is slated to cut/scope-down (its follow-up Simplified CLI commands with consistent -s/--session pattern #1). I won't propose hardening or touching it; hardening a surface that's being removed is the wasted work Networking/tunnel footprint review: what does agentwire own, and should it? #420 exists to prevent.
• The Networking/tunnel footprint review: what does agentwire own, and should it? #420 coordination section above is superseded by this note — treat the tunnel/tunnels.py/network.py/remote-SSH discussion there as informational only, not a proposal.

Final scope of this audit = portal auth/bind/TLS boundary only. The proposed follow-up issues that remain live are 1–7 (per-device pairing, ptt capability scopes, freeze security-critical config from the API, 401 audit-log + lockout, TLS-or-loopback, fingerprint reduction, artifact path-traversal verify). Drop #8.

Note for the issue body: #420's own follow-up list includes "Re-scope #396 to the portal auth/bind/TLS boundary only — de-scope SSH service-router + provider-tunnel hardening; update the issue body." This comment is that re-scope on the audit side; the body edit is the owner's to make.