x402: foolproof deps + correct mac/Linux tunnel requirement in manifest

The manifest claimed macOS/Linux need nothing for the tunnel ("WireGuard
ships with the OS"). Tracing sentinel-go-sdk shows the CLI does NOT bundle
a tunnel -- it shells out: WireGuard nodes run `wg-quick up` (needs system
wireguard-tools), V2Ray nodes run `v2ray run --config` (needs a v2ray
binary on PATH). Corrected /manifest tldr, platforms, and connectMacLinux
to state the real native deps (Go 1.24+, wireguard-tools, v2ray), and
added an explicit `install` block + viem to packages so a zero-experience
agent has the complete npm set (`npm install @x402/fetch @x402/evm viem
blue-js-sdk`) and the out-of-npm native deps spelled out.

Also normalize e2e-maclinux.sh to LF / no-BOM / ASCII separators (a prior
PowerShell round-trip had reintroduced CRLF and mojibake'd the box-drawing
dashes), and surface wg-quick/v2ray as explicit STEP 0 checks in the runner.

Author: Sentinel-Bluebuilder

fresh-test/e2e-maclinux.sh

@@ -1,28 +1,29 @@
 #!/usr/bin/env bash
-# ─────────────────────────────────────────────────────────────────────────────
-# x402 AI Agent — macOS / Linux End-to-End Test (native CLI path)
+# ======================================================================
+# x402 AI Agent -- macOS / Linux End-to-End Test (native CLI path)
 #
 # Proves the documented macOS/Linux connect path actually works end-to-end:
 #   pay USDC on Base over HTTP 402  ->  Sentinel provision  ->  connect via the
 #   native `sentinel-dvpncli` tool (the path /manifest.connectMacLinux prescribes).
 #
 # The Windows path is verified by e2e-selffund.mjs. This script is the missing
-# piece — run it ON a Mac or Linux host to turn "built" into "verified".
+# piece -- run it ON a Mac or Linux host to turn "built" into "verified".
 #
 # It self-funds: the payment phase reuses pay-phase.mjs which reads the operator
 # key from wallets.env and funds a throwaway agent, then runs the x402 402 flow.
 #
 # Prerequisites on the host:
-#   - Node 20+ (for the payment phase)  - Go 1.24+ (for sentinel-dvpncli)
-#   - WireGuard (ships with macOS; `apt install wireguard` / `pacman -S wireguard-tools` on Linux)
+#   - Node 20+ (for the payment phase)   - Go 1.24+ (for sentinel-dvpncli)
+#   - WireGuard tools (wg-quick): apt install wireguard-tools | brew install
+#     wireguard-tools | pacman -S wireguard-tools. The CLI shells out to it.
 #   - sudo available (WireGuard nodes bring the interface up as root)
-#   - NOT Fedora (SELinux blocks VPN interfaces — documented limitation)
+#   - NOT Fedora (SELinux blocks VPN interfaces -- documented limitation)
 #
 # Usage:
 #   bash e2e-maclinux.sh              # 1day tier, live server
 #   TIER=7days bash e2e-maclinux.sh
 #   SERVER_URL=http://localhost:4020 bash e2e-maclinux.sh
-# ─────────────────────────────────────────────────────────────────────────────
+# ======================================================================
 set -euo pipefail
 
 SERVER_URL="${SERVER_URL:-https://x402.sentinel.co}"
@@ -35,17 +36,17 @@ line() { printf '%s\n' "========================================================
 say()  { printf '%s\n' "$*"; }
 
 line
-say "  x402 AI AGENT — macOS/LINUX END-TO-END TEST"
+say "  x402 AI AGENT -- macOS/LINUX END-TO-END TEST"
 say "  Server: $SERVER_URL   Tier: $TIER"
 line
 
-# ─── STEP 0: environment ───
+# --- STEP 0: environment ---
 say ""
 say "--- STEP 0: ENVIRONMENT ---"
 uname_s="$(uname -s)"
 say "  OS: $uname_s"
 if [ -f /etc/fedora-release ]; then
-  say "  [FAIL] Fedora detected — SELinux blocks VPN interfaces (documented as unsupported)."
+  say "  [FAIL] Fedora detected -- SELinux blocks VPN interfaces (documented as unsupported)."
   exit 2
 fi
 command -v node >/dev/null 2>&1 || { say "  [FAIL] node not found (need Node 20+)"; exit 2; }
@@ -58,9 +59,18 @@ if ! command -v "$CLI" >/dev/null 2>&1; then
   exit 2
 fi
 say "  cli:  $($CLI version 2>/dev/null | head -1 || echo present)"
-command -v wg-quick >/dev/null 2>&1 || command -v wg >/dev/null 2>&1 || say "  [WARN] WireGuard tools not found — tunnel bring-up may fail"
+# The CLI shells out to wg-quick (WireGuard nodes) or v2ray (V2Ray nodes) -- it
+# does NOT bundle a tunnel. Most nodes are WireGuard, so wg-quick is effectively
+# required; v2ray is a soft dependency only needed if a V2Ray node is selected.
+if command -v wg-quick >/dev/null 2>&1; then
+  say "  wg-quick: $(command -v wg-quick)"
+else
+  say "  [WARN] wg-quick not found -- WireGuard nodes will fail to connect."
+  say "         Install: apt install wireguard-tools | brew install wireguard-tools | pacman -S wireguard-tools"
+fi
+command -v v2ray >/dev/null 2>&1 && say "  v2ray:    $(command -v v2ray)" || say "  [note] v2ray binary not on PATH -- only needed if a V2Ray node is selected."
 
-# ─── STEP 1-4: pay + provision (cross-platform Node phase) ───
+# --- STEP 1-4: pay + provision (cross-platform Node phase) ---
 say ""
 say "--- STEP 1-4: PAY + PROVISION (x402) ---"
 # pay-phase.mjs self-funds and runs the 402 flow, then prints a JSON line:
@@ -88,7 +98,7 @@ NODE_ADDR="$(extract nodeAddress)"
 [ -z "$MNEMONIC" ] && { say "  [FAIL] could not parse mnemonic from provision result"; exit 1; }
 say "  Provisioned: sub=$SUB_ID node=$NODE_ADDR feeGranter=$FEE_GRANTER"
 
-# ─── STEP 5: keys add (import the funded agent wallet) ───
+# --- STEP 5: keys add (import the funded agent wallet) ---
 say ""
 say "--- STEP 5: IMPORT WALLET (sentinel-dvpncli keys add) ---"
 # Remove any stale key of the same name first (idempotent re-runs).
@@ -97,7 +107,7 @@ say "--- STEP 5: IMPORT WALLET (sentinel-dvpncli keys add) ---"
 printf '%s\n\n' "$MNEMONIC" | "$CLI" keys add agent --keyring.backend test >/dev/null
 say "  Imported agent key for $SENT_ADDR"
 
-# ─── STEP 6: session-start (operator fee-grants the gas) ───
+# --- STEP 6: session-start (operator fee-grants the gas) ---
 say ""
 say "--- STEP 6: SESSION-START ---"
 "$CLI" tx session-start "$NODE_ADDR" \
@@ -107,7 +117,7 @@ say "--- STEP 6: SESSION-START ---"
   --keyring.backend test \
   --rpc.chain-id "$CHAIN_ID" \
   --output-format json >/dev/null
-say "  session-start broadcast — resolving session id..."
+say "  session-start broadcast -- resolving session id..."
 
 # session-start doesn't print the id cleanly; query it back and take the newest.
 SESSION_ID=""
@@ -120,7 +130,7 @@ done
 [ -z "$SESSION_ID" ] && { say "  [FAIL] could not resolve session id after session-start"; exit 1; }
 say "  Session id: $SESSION_ID"
 
-# ─── STEP 7: connect (build the tunnel) ───
+# --- STEP 7: connect (build the tunnel) ---
 say ""
 say "--- STEP 7: CONNECT ---"
 SUDO=""
@@ -133,7 +143,7 @@ sleep 20
 VPN_IP="$(curl -s --max-time 15 https://api.ipify.org || echo unknown)"
 say "  Exit IP through tunnel: $VPN_IP"
 
-# ─── STEP 8: teardown ───
+# --- STEP 8: teardown ---
 say ""
 say "--- STEP 8: DISCONNECT ---"
 kill "$CONNECT_PID" >/dev/null 2>&1 || true
@@ -145,14 +155,14 @@ kill "$CONNECT_PID" >/dev/null 2>&1 || true
   --output-format json >/dev/null 2>&1 || say "  (session-cancel best-effort)"
 say "  Session $SESSION_ID cancelled."
 
-# ─── Report ───
+# --- Report ---
 say ""
 line
 if [ "$VPN_IP" != "unknown" ] && [ -n "$VPN_IP" ]; then
-  say "  RESULT: PASS — agent paid on Base and tunneled out via $VPN_IP (session $SESSION_ID)"
+  say "  RESULT: PASS -- agent paid on Base and tunneled out via $VPN_IP (session $SESSION_ID)"
   RC=0
 else
-  say "  RESULT: PARTIAL — paid + session started, but tunnel IP could not be verified"
+  say "  RESULT: PARTIAL -- paid + session started, but tunnel IP could not be verified"
   RC=1
 fi
 line

server/src/index.ts

@@ -299,8 +299,9 @@ app.get('/manifest', (_req, res) => {
     description: 'Pay USDC, get a Sentinel dVPN subscription. One HTTP request, one EIP-3009 signature.',
     tldr: [
       'You need: (a) an EVM wallet with USDC on Base, (b) a Sentinel wallet from `createWallet()` in `blue-js-sdk/ai-path`.',
+      'Install (agent side only — you do NOT clone this repo): `npm install @x402/fetch @x402/evm viem blue-js-sdk`. That is the complete dependency set for paying and connecting. The express/@x402/express/dotenv packages are operator-only — ignore them.',
       `POST ${network === 'eip155:8453' ? 'https://x402.sentinel.co' : '/'}/vpn/connect/{1day|7days|30days} with { sentinelAddr } using @x402/fetch to auto-sign the 402. Tiers cost $0.033 / $0.233 / $1.00 USDC — pick the smallest that covers your need; $0.033 is enough to start. Add { country: "DE" } to get a node in a specific country (GET /nodes lists what is available). Payment is identical on every OS.`,
-      'Connecting differs by OS. macOS & Linux (easiest): WireGuard ships with the OS — use the native CLI `sentinel-dvpncli` (go install github.com/sentinel-official/sentinel-dvpncli@latest), then import the key (`printf \'%s\\n\\n\' "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test`), `tx session-start <nodeAddress> --subscription-id <id> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test`, resolve the id with `query sessions --account-addr <sent1...> --subscription-id <id> --output-format json`, then `connect <sessionId>`. See sentinel.connectMacLinux. Only Fedora is unsupported (SELinux blocks VPNs).',
+      'Connecting differs by OS. macOS & Linux: use the native CLI `sentinel-dvpncli` (go install github.com/sentinel-official/sentinel-dvpncli@latest — needs Go 1.24+). The CLI shells out to the system tunnel binary, so install `wireguard-tools` (provides `wg-quick`; most nodes are WireGuard) and, for V2Ray nodes, a `v2ray` binary on PATH. Then import the key (`printf \'%s\\n\\n\' "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test`), `tx session-start <nodeAddress> --subscription-id <id> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test`, resolve the id with `query sessions --account-addr <sent1...> --subscription-id <id> --output-format json`, then `connect <sessionId>` (sudo to bring the interface up). See sentinel.connectMacLinux. Only Fedora is unsupported (SELinux blocks VPNs).',
       'Windows (heavier): run `await setup()` from `blue-js-sdk/ai-path` first — it auto-downloads V2Ray (no admin) and installs WireGuard — then `connect({ mnemonic, subscriptionId, feeGranter, nodeAddress })`. See sentinel.connectWindows.',
       'Tunnel is up. You paid as little as $0.033 USDC (1day) up to $1.00 (30day), zero gas on Base, zero gas on Sentinel.',
     ],
@@ -450,9 +451,15 @@ app.get('/manifest', (_req, res) => {
       { step: 9, actor: 'agent', action: 'MsgStartSession (gas paid by operator via fee grant)' },
       { step: 10, actor: 'agent', action: 'Direct WireGuard/V2Ray handshake with node — tunnel up' },
     ],
+    install: {
+      npm: 'npm install @x402/fetch @x402/evm viem blue-js-sdk',
+      note: 'Agent side only — you do NOT clone this repo. The four packages above are the complete set for paying + connecting on every OS. express / @x402/express / dotenv are operator-only; do not install them.',
+      nativeMacLinux: 'The macOS/Linux connect path also needs, OUTSIDE npm: Go 1.24+ (to `go install` sentinel-dvpncli), wireguard-tools (provides `wg-quick`, for WireGuard nodes), and a `v2ray` binary on PATH (for V2Ray nodes). The Windows path needs none of these — setup() fetches them.',
+    },
     packages: {
       payment: '@x402/fetch',
       scheme: '@x402/evm',
+      evm: 'viem',
       sentinel: 'blue-js-sdk/ai-path',
     },
     example: {
@@ -517,11 +524,12 @@ app.get('/manifest', (_req, res) => {
         returns: { address: 'sent1... (use this as sentinelAddr)', mnemonic: 'string (persist this)' },
         note: 'Generate once per agent. The address goes in the request body; the mnemonic signs MsgStartSession.',
       },
-      platforms: 'Payment is identical on every OS; only the connect step differs. macOS & Linux are the easiest path (native CLI, WireGuard ships with the OS — see connectMacLinux). Windows uses the heavier JS-SDK path (see connectWindows / connect). Only Fedora is unsupported: its SELinux blocks VPN interfaces and cannot be bypassed programmatically.',
+      platforms: 'Payment is identical on every OS; only the connect step differs. macOS & Linux use the native CLI (sentinel-dvpncli + a system tunnel binary — see connectMacLinux). Windows uses the JS-SDK path where setup() fetches the tunnel binaries for you (see connectWindows / connect). Only Fedora is unsupported: its SELinux blocks VPN interfaces and cannot be bypassed programmatically.',
       connectMacLinux: {
         tool: 'sentinel-dvpncli',
         install: 'go install github.com/sentinel-official/sentinel-dvpncli@latest (Go 1.24+); binary lands in $(go env GOPATH)/bin',
-        why: 'Easiest path — WireGuard ships with macOS and mainstream Linux, so nothing to install for the tunnel. Flag-driven, non-interactive.',
+        nativeDeps: 'The CLI does NOT bundle a tunnel — it shells out. WireGuard nodes run `wg-quick up` (install wireguard-tools: `apt install wireguard-tools` / `brew install wireguard-tools` / `pacman -S wireguard-tools`). V2Ray nodes run `v2ray run --config` (install a `v2ray` binary on PATH). Most nodes are WireGuard; install wireguard-tools at minimum. Bringing the interface up needs sudo.',
+        why: 'Flag-driven, non-interactive — good for agents. Trade-off vs Windows: you install the tunnel binary yourself (Windows setup() auto-fetches it).',
         steps: [
           'keys add: printf \'%s\\n\\n\' "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test  (import the SAME wallet whose sentinelAddr you sent to x402. keys add is INTERACTIVE — no --recover flag: line 1 answers the mnemonic prompt, the blank line 2 accepts the default empty BIP-39 passphrase. A single-line echo would hang on the passphrase prompt.)',
           'session-start: sentinel-dvpncli tx session-start <nodeAddress> --subscription-id <subscriptionId> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test --rpc.chain-id sentinelhub-2 --output-format json  (operator fee-grants the gas)',