feat(pairing): dial loopback relays by handle (E4) + close MCP poisoned-card gap (#358)

* feat(pairing): dial loopback relays by handle (E4) + close MCP poisoned-card gap

`wire dial nick@127.0.0.1:8771` now reaches a local-dev / sandbox relay. The
federation-handle domain validator rejected any `:port`, so a custom-port
loopback relay couldn't be named in a handle at all (the V0_13_2 E4 item).

- `endpoints::is_loopback_host` — one shared predicate (exact `127.0.0.1` /
  `localhost` / `::1`) now used by `infer_scope_from_url`, the validator, the
  URL builder, and the phishing-warning suppression, so scheme and scope
  classification can't drift.
- `is_valid_domain` accepts a `host:port` authority ONLY for a loopback host
  (port 1..=65535). Non-loopback host+port stays rejected — public handles are
  port-less; a public relay on a custom port belongs behind a 443 TLS edge.
- new `relay_url_for_domain` picks `http://` for a loopback authority, `https://`
  otherwise, replacing the 4 unconditional `format!("https://{domain}")` fallback
  sites (pair_profile, cli/pairing, cli/setup `wire up --relay`, mcp tool_add).
- `is_known_relay_domain` treats loopback as known — no spurious cross-relay
  phishing warning for the operator's own machine.

Security (from the adversarial design review):
- MCP `tool_add` now runs the same poisoned-card DID-key fingerprint hard-refuse
  the CLI `cmd_add` had — a rogue relay serving a card whose key != its claimed
  DID is rejected on BOTH paths (was CLI-only; E4's loopback path made the MCP
  gap newly reachable).
- THREAT_MODEL T14 documents the loopback-SSRF trade-off (prompt-injected dial to
  a loopback port); bilateral accept + the fingerprint refuse remain the gates.

Tests: loopback parse / non-loopback reject / port-range unit tests +
relay_url_for_domain scheme regression guard; in-situ `wire dial nick@127.0.0.1:PORT`
pair + message round-trip over http loopback. Full lib suite green (615).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XmVWMe6fE54U1drShE1yMT

* fix(pairing): address E4 gate-2 review — drop ::1, honest predicate doc, +tests

Built-thing review of the E4 change (3 MINOR, no blockers):
- Exclude IPv6 `::1` from `is_loopback_host`: it was accepted by the validator
  but `relay_url_for_domain` produced a bracket-less, malformed `http://::1:port`.
  IPv6 loopback handles aren't a real use case and need `[::1]:port` bracketing
  the handle path doesn't carry — reject cleanly instead. (`::1` was vestigial in
  `infer_scope_from_url` anyway: its host-extraction never yields a bare `::1`.)
- Correct the `is_loopback_host` doc: it's the single predicate for the E4
  TRUST-PATH gates, not literally every loopback check — `session.rs::url_is_loopback`
  is a separate, deliberately-broader /8 predicate for same-box session discovery.
- Tests: reject `bob@:8771` (empty host) and `bob@::1:8771` (IPv6 exclusion).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XmVWMe6fE54U1drShE1yMT

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: laulpogan

SANDBOX_HARDEN_SPEC.md

@@ -94,6 +94,31 @@ plan → gate#1 → develop → in-situ test → gate#2 → loop).
   sandbox/loopback relay can't be named in a `wire dial nick@host:port` handle.
   Recommend relaxing for local scope (V0_13_2 E4). Workaround shipped in docs: invite flow.
 
+## E4 — loopback handle port support (iteration 2, branch e4-local-relay, operator-authorized 2026-06-29)
+
+Tier HIGH (trust-path: federation handle domain validation). Goal: `wire dial nick@127.0.0.1:8771`
+reaches a loopback relay. Scope = **loopback only** (the clean boundary: loopback ⟹ http is certain;
+internal-DNS-name ⟹ http/https is a guess → those keep using the invite flow).
+
+Design:
+1. `is_valid_domain` (pair_profile.rs:163): split optional `:port` (rsplit_once); if port present,
+   accept ONLY when host is loopback (`localhost` / 127.0.0.0/8); validate port 1..=65535 + host labels.
+   Non-loopback + port stays REJECTED (preserves port-less public-handle convention). No-port unchanged.
+2. New `relay_url_for_domain(domain)` → `http://` for loopback host, else `https://`. Replaces the 3
+   `format!("https://{}", domain)` fallback sites (pair_profile.rs:266, cli/pairing.rs:1176, mcp.rs:1730).
+3. `is_known_relay_domain` (pairing.rs:685): loopback = implicitly-known (suppress spurious phishing warn).
+
+TDD contract (runnable check):
+- parse_handle Ok: `n@127.0.0.1:8771`, `n@localhost:8771`, `n@127.0.0.1` (already), `n@wireup.net` (unchanged).
+- parse_handle Err: `n@evil.com:1337`, `n@wireup.net:8443` (non-loopback+port), `n@127.0.0.1:0`,
+  `n@127.0.0.1:99999`, `n@:8771`, `n@127.0.0.1:abc`.
+- relay_url_for_domain: `127.0.0.1:8771`→http, `localhost:9`→http, `wireup.net`→https (public unchanged).
+- in-situ: `wire dial n@127.0.0.1:<port>` to a local relay → pairs + message lands.
+
+Gate#1 (design persona review): security + protocol/compat — DISPATCHED. Key risk under review:
+SSRF via `tool_add`/auto-dial on untrusted input hitting a loopback port (note: wire already GETs
+well-known on any operator-chosen domain; loopback is the sensitive subset, response not returned to attacker).
+
 ## Gate ledger
 - Gate#1 (plan): folded into gate#2 (de-scoped to MEDIUM — no trust-path code change).
 - Gate#2 (built-thing review over diff): **PASS after fixes.** 3 parallel Sonnet reviewers

docs/SANDBOXES.md

@@ -44,28 +44,32 @@ message between two *separate* container identities, see the
 "custom-port relays" note below — on a non-wireup relay you must pair with the
 **invite flow**, not `wire dial <handle>`.
 
-## Custom-port / loopback / sandbox relays — use the invite flow
+## Custom-port relays — loopback by handle (E4), or the invite flow
 
 A wire **federation handle** is `nick@domain` and assumes a public, port-less
-HTTPS domain (e.g. `alice@wireup.net`, implicitly `:443`). The domain validator
-(`src/pair_profile.rs::is_valid_domain`) **rejects any `:port` suffix** — the `:`
-fails its per-label character check — so a custom-port relay can't be named in a
-handle at all. (A bare single-label host like `nick@relay` *passes* the validator
-but then fails at DNS/TCP, not with a clean error.) So inside a sandbox where the
-relay is `http://relay:8770` or `http://127.0.0.1:8771`:
-
-```text
-wire dial knit-ash@relay:8770  ->  error: domain "relay:8770" invalid
-                                   — must be lowercase ASCII, dot-separated
+HTTPS domain (e.g. `alice@wireup.net`, implicitly `:443`).
+
+**Loopback relays are dialable by handle (E4).** `is_valid_domain` accepts a
+`:port` suffix when the host is a loopback literal (`127.0.0.1` / `localhost`),
+and the client speaks `http://` to it (local relays don't terminate TLS). So a
+same-box / loopback sandbox relay works directly:
+
+```bash
+wire dial knit-ash@127.0.0.1:8771 "hello"   # resolves over http://127.0.0.1:8771
 ```
 
-**This is expected.** Pair via the invite flow instead, which carries the full
-relay URL (port included) in the invite token and bypasses handle resolution
-entirely — validated container-to-container on a `:8770` relay:
+Non-loopback hosts stay port-less (`evil.com:8443` is rejected) — a public relay
+on a custom port should sit behind a 443 TLS edge (Cloudflare Tunnel / Caddy).
+
+**A custom-port relay reached by an internal DNS name** (e.g. the Docker
+service name `relay.wire.local:8770`) still can't be a handle: http-vs-https
+isn't inferable from the name. Pair via the **invite flow**, which carries the
+full relay URL (scheme + port) in the token — validated container-to-container
+on a `:8770` relay:
 
 ```bash
 # On peer A (already `wire up`-ed against the local relay):
-A_INVITE=$(wire invite --relay http://relay:8770 --json | jq -r .invite_url)
+A_INVITE=$(wire invite --relay http://relay.wire.local:8770 --json | jq -r .invite_url)
 
 # On peer B:
 wire accept-invite "$A_INVITE"     # pins A, exchanges signed cards
@@ -76,10 +80,10 @@ Same-box sibling sessions (one `$WIRE_HOME`, distinct `WIRE_SESSION_ID`) can use
 bare-nick `wire dial` directly — they resolve as local sisters, not federation.
 See `scripts/hello-world-validate.sh` for that path.
 
-> Limitation tracked: relaxing `is_valid_domain` to accept `host:port` for
-> local/loopback scope (so `wire dial` works to a sandbox relay) is the E4 item
-> in `docs/V0_13_2_PLATFORM_HARDENING.md`. Until that lands, the invite flow is
-> the supported sandbox-relay pairing path.
+> Security note: loopback handle dialing widens the prompt-injection SSRF
+> surface to loopback ports (T14 in `docs/THREAT_MODEL.md`); the bilateral
+> `wire_accept` gate and the poisoned-card fingerprint hard-refuse (now on the
+> MCP path too) still apply.
 
 ## OpenShell (egress-policy sandboxes)
 

docs/THREAT_MODEL.md

@@ -208,6 +208,19 @@ in hostile-host scenarios. Documented as host responsibility. Operators
 choosing an MCP host should prefer one with explicit user-confirmation
 primitives for trust-mutating tools.
 
+**E4 trade-off (loopback handle ports, 2026-06-29):** allowing `nick@127.0.0.1:PORT`
+handles (so `wire dial` reaches a local-dev / sandbox relay) widens this residual:
+a prompt-injected agent told to dial `foo@127.0.0.1:<port>` now makes a
+`GET http://127.0.0.1:<port>/.well-known/wire/agent` against an arbitrary loopback
+port (blind SSRF — the response is verified-or-discarded locally, never returned to
+the attacker; non-loopback `host:port` stays rejected, so the surface is loopback
+only). The bilateral `wire_accept` gate is unaffected — no pair completes without
+operator consent — and the poisoned-card key/DID-fingerprint hard-refuse now fires
+on the MCP `tool_add` path too (parity with CLI `cmd_add`), so a rogue loopback
+relay serving a substituted card is rejected. A host wanting a tighter gate can key
+off the loopback target before letting an agent auto-dial; wire surfaces the dial
+target in the tool args so the host has the hook.
+
 ## Threat T13 — relay process compromise leaks to other host workloads
 
 **Threat:** the wire relay process (or any wire process) is exploited via a memory-safety bug in a Rust dependency, an axum/hyper HTTP CVE, or a malicious crate in the supply chain. Attacker now has code execution as the user that owns the wire process. On a shared host running wire alongside other workloads (a Spark box running forge / slancha-api / training pipelines / SSH keys / Anthropic API keys / etc.), this is a *lateral movement* problem distinct from the wire protocol's threat model.

docs/V0_13_2_PLATFORM_HARDENING.md

@@ -37,7 +37,7 @@ Full rc10 Windows matrix GREEN (glossy): B + E2-bidirectional + pair-all-local +
 | id | gap | tier | note |
 |----|-----|------|------|
 | E3 | `add-peer-slot` REPLACES endpoints, doesn't merge → clobbers federation route (data loss) | 🟡 rc5 | now additive — upsert by relay_url into peer `endpoints[]` |
-| E4 | domain validator rejects loopback/IP → `dial`/`add` can't express `nick@127.0.0.1:8771` | bug | relax validator when scope=local |
+| E4 | domain validator rejects loopback/IP → `dial`/`add` can't express `nick@127.0.0.1:8771` | ✅ DONE (2026-06-29) | `is_valid_domain` accepts a loopback `host:port` (exact `127.0.0.1`/`localhost` via shared `endpoints::is_loopback_host`); new `relay_url_for_domain` picks `http://` for loopback at all 4 URL sites; loopback phishing-warn suppressed; MCP `tool_add` gained the CLI's poisoned-card fingerprint refuse; SSRF trade-off noted in THREAT_MODEL T14 |
 | E5 | `dial <peer>` on already-pinned returns `already_pinned`, won't refresh endpoints → peer that binds local AFTER pairing can't upgrade | bug | `wire repin/refresh <peer>` |
 | E2 | daemon never serviced a bind-relay'd local slot (`run_sync_pull` pulled only the primary endpoint) | 🟡 rc6 | pull ALL self endpoints with per-slot cursors; resilient to one slot erroring |
 | E1 | `wire up` doesn't register a local session / auto-start|detect local relay → same-box defaults to federation | feature | |

src/cli/mod.rs

@@ -33,6 +33,7 @@ mod upgrade;
 
 pub(crate) use comms::here_summary;
 pub(crate) use comms::parse_deadline_until;
+pub(crate) use pairing::resolved_key_fingerprint;
 pub(crate) use relay::cmd_bind_relay;
 pub use relay::error_smells_like_slot_4xx;
 pub use relay::run_sync_pull;

src/cli/pairing.rs

@@ -663,7 +663,7 @@ fn print_resolved_profile(resolved: &Value) {
 /// a mismatch means the relay served a card whose key does not match its own
 /// DID (a poisoned-discovery red flag). `matches` is false when the card has no
 /// usable key or `did_fp` is empty. Pure → unit-tested.
-fn resolved_key_fingerprint(card: &Value, did: &str) -> (Option<String>, String, bool) {
+pub(crate) fn resolved_key_fingerprint(card: &Value, did: &str) -> (Option<String>, String, bool) {
     let did_fp = did.rsplit('-').next().unwrap_or("").to_string();
     let computed = card
         .get("verify_keys")
@@ -686,6 +686,17 @@ fn is_known_relay_domain(peer_domain: &str, our_relay_url: &str) -> bool {
     // Hard-coded known-good list. wireup.net is the default relay.
     const KNOWN_GOOD: &[&str] = &["wireup.net", "wire.laulpogan.com"];
     let peer_domain = peer_domain.trim().to_ascii_lowercase();
+    // E4: a loopback authority is the operator's OWN machine — there is no
+    // off-box relay to impersonate, so suppress the cross-relay phishing
+    // warning. (`peer_domain` carries the port, e.g. `127.0.0.1:8771`; strip it
+    // before the loopback check.)
+    let peer_host = peer_domain
+        .rsplit_once(':')
+        .map(|(h, _)| h)
+        .unwrap_or(peer_domain.as_str());
+    if crate::endpoints::is_loopback_host(peer_host) {
+        return true;
+    }
     if KNOWN_GOOD.iter().any(|k| *k == peer_domain) {
         return true;
     }
@@ -1173,7 +1184,7 @@ pub(super) fn cmd_add(
         .and_then(Value::as_str)
         .map(str::to_string)
         .or_else(|| relay_override.map(str::to_string))
-        .unwrap_or_else(|| format!("https://{}", parsed.domain));
+        .unwrap_or_else(|| crate::pair_profile::relay_url_for_domain(&parsed.domain));
 
     // 3. Pin peer in trust + relay-state. slot_token will arrive via ack.
     config::update_trust(|trust| {

src/cli/setup.rs

@@ -30,7 +30,11 @@ pub(crate) fn cmd_up(
             if r.starts_with("http://") || r.starts_with("https://") {
                 r.to_string()
             } else {
-                format!("https://{r}")
+                // E4: schemeless relay arg → http:// for a loopback authority
+                // (local relays speak plaintext), https:// otherwise. Without
+                // this, `wire up --relay 127.0.0.1:8771` would publish an
+                // https:// self-relay and the loopback slot would be dead.
+                crate::pair_profile::relay_url_for_domain(r)
             }
         }
         None => crate::pair_invite::DEFAULT_RELAY.to_string(),

src/endpoints.rs

@@ -483,13 +483,32 @@ pub fn infer_scope_from_url(url: &str) -> EndpointScope {
         .split(':')
         .next()
         .unwrap_or("");
-    if host == "127.0.0.1" || host == "localhost" || host == "::1" {
+    if is_loopback_host(host) {
         EndpointScope::Local
     } else {
         EndpointScope::Federation
     }
 }
 
+/// True iff `host` (no scheme, no port) is a loopback address the E4 trust-path
+/// gates treat as `Local` scope: `infer_scope_from_url`, the handle validator +
+/// URL builder (`pair_profile::is_valid_domain` / `relay_url_for_domain`), and
+/// the `is_known_relay_domain` phishing-warning suppression all key off THIS one
+/// predicate so scheme + scope can never disagree. Keeping one predicate is
+/// load-bearing: if these gates disagreed on "loopback", a handle could parse +
+/// get an `http://` URL while being classified `Federation` (advertised off-box).
+///
+/// IPv4 `127.0.0.1` + `localhost` only. IPv6 `::1` is intentionally excluded — an
+/// IPv6 authority needs bracketing (`[::1]:port`) the handle/URL path doesn't
+/// carry, so `nick@::1:port` is rejected rather than half-accepted into a
+/// malformed `http://::1:port`; use `127.0.0.1` for a loopback handle. Do not
+/// broaden the IPv4 set to the full /8 here without updating every caller. (NB:
+/// `session.rs::url_is_loopback` is a SEPARATE, deliberately-broader /8 predicate
+/// for same-box session discovery — not a trust gate.)
+pub fn is_loopback_host(host: &str) -> bool {
+    host == "127.0.0.1" || host == "localhost"
+}
+
 /// True iff this endpoint set is reachable ONLY from the same box — every
 /// endpoint resolves (by URL) to a loopback/`Local` or `Uds` address, with no
 /// off-box `Federation`/LAN host. A peer pinned this way can't complete a

src/mcp.rs

@@ -1716,6 +1716,23 @@ fn tool_add(args: &Value) -> Result<Value, String> {
         .and_then(Value::as_str)
         .ok_or("resolved missing did")?
         .to_string();
+
+    // Poisoned-discovery hard-refuse — parity with CLI `cmd_add` (#247 finding 4).
+    // A relay can serve a card with a VALID self-signature (so resolve_handle's
+    // verify passes) whose key does NOT hash to the fingerprint in its claimed
+    // DID — identity substitution. The CLI refused this; the MCP path did not, so
+    // an agent-driven `wire_dial` would pin it. E4 widens the reachable relay set
+    // (loopback), making the gap newly exploitable via a rogue local relay — so
+    // close it on both paths.
+    let (peer_fp, _did_fp, fp_matches) =
+        crate::cli::resolved_key_fingerprint(&peer_card, &peer_did);
+    if peer_fp.is_some() && !fp_matches {
+        return Err(format!(
+            "REFUSING to pair `{handle}` — the resolved card's key fingerprint ({}) does not match its claimed DID `{peer_did}` (poisoned discovery: the relay served a card whose key ≠ its identity). Verify with the peer out-of-band.",
+            peer_fp.as_deref().unwrap_or("?")
+        ));
+    }
+
     let peer_handle = crate::agent_card::display_handle_from_did(&peer_did).to_string();
     let peer_slot_id = resolved
         .get("slot_id")
@@ -1727,7 +1744,7 @@ fn tool_add(args: &Value) -> Result<Value, String> {
         .and_then(Value::as_str)
         .map(str::to_string)
         .or_else(|| relay_override.map(str::to_string))
-        .unwrap_or_else(|| format!("https://{}", parsed.domain));
+        .unwrap_or_else(|| crate::pair_profile::relay_url_for_domain(&parsed.domain));
 
     // Pin peer in trust + relay-state. slot_token arrives via ack later.
     crate::config::update_trust(|trust| {