Prove the TUN carries an application's traffic, and make Phase D one command

The oldest claim on the honest list had never been evidenced: that the tunnel
carries traffic for an application. It could not be, from inside this app —
which is forced out of its own tunnel in every mode, because a VPN inside its
own tunnel is a routing loop — and the script written to do it from a shell had
never run, because adb cannot start a VPN.

It can now. TunnelHolderTest brings the tunnel up and holds it, asserts nothing,
and skips unless asked for by name. e2e-tunnel-fetch.sh uses it, and the shell
user — who is not this app — fetches twenty megabytes through the TUN with a
matching SHA-256, over both carriers, with the Portal's own byte counters moving
by the same amount.

Three things had to be learned to get there, and all three are the kind that
would have been learned on a physical device at a worse moment.

**Loopback never enters a VPN's TUN.** The kernel routes 127.0.0.0/8 to `lo`
rather than to the default route, so the trick that works from inside the app —
choose an address only the Portal can reach — proves nothing from a shell: a
loopback target proves only that loopback is loopback. The evidence is the
Portal's counters instead, which neither half of the script can fake.

**A truncated transfer is non-empty.** The retry loop accepted any file with
bytes in it, so a hold window that expired mid-transfer produced nine megabytes
of twenty and the digest failed afterwards with no attempt left — reporting a
corrupt tunnel when what it had was a short read. Verification moved inside the
loop.

**A Portal emits its counters on a timer.** Reading them two seconds after a
fetch reads the line from before it, and reports that a transfer which plainly
happened relayed nothing.

The guard added yesterday moved from `TunnelHarness.start` to the fetch, which
is where the invalid inference is actually made. Bringing a tunnel up is a fine
thing to do with any target; it is fetching from inside this app that cannot
prove anything.

device-acceptance.sh runs all six of Phase D as one command: Private DNS, the
package-visibility count that is D-16, address families, traffic over both
carriers, battery management and path MTU. It reports each as a pass, a failure,
or something only a person watching the device can settle — and says loudly when
it is run against an emulator, because none of the six is answered by one.

Exercised against the emulator: four passed, none failed, three left for a
human. That checks the script, not the client.

Gates green; device suite 53 cases.

Author: AlbertoDeckow

app/src/androidTest/kotlin/eu/nodepass/somewhere/vpn/TunnelHarness.kt

@@ -65,16 +65,19 @@ object TunnelHarness {
                     throw AssertionError("the test node URL does not parse: ${parsed.reason.detail}")
             }
 
-        refuseADirectlyReachableTarget()
-
         SomewhereVpnService.start(context, node)
         await("the tunnel to come up") { TunnelController.state.value is TunnelState.Connected }
     }
 
     /**
-     * Refuses to run a tunnel case whose target this device can reach without a
+     * Refuses an in-app fetch of a target this device can reach without a
      * tunnel.
      *
+     * On the fetch rather than on `start`, because it is the fetch that makes
+     * the invalid inference. Bringing a tunnel up is a fine thing to do with any
+     * target — `TunnelHolderTest` does it so that a *shell* can use the tunnel,
+     * and a shell is not this app.
+     *
      * **This exists because the suite spent a day proving nothing.** Every case
      * here fetches over an ordinary socket from inside the app's own process,
      * and this client is forced out of its own tunnel in every mode — a VPN
@@ -131,6 +134,8 @@ object TunnelHarness {
      * not catch it.
      */
     fun fetchAndDigest(url: String): Fetched {
+        refuseADirectlyReachableTarget()
+
         // NO_PROXY, deliberately. Emulators commonly carry a system HTTP proxy
         // — this one advertises 10.0.2.2:6152 — and `HttpURLConnection` honours
         // it while `curl` does not, which is why the same fetch can look broken

app/src/androidTest/kotlin/eu/nodepass/somewhere/vpn/TunnelHolderTest.kt

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 The Somewhere Authors
+
+package eu.nodepass.somewhere.vpn
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * Brings a tunnel up and holds it, so that a shell can use it.
+ *
+ * ## Why this exists
+ *
+ * The claim that matters most on a physical device — *does the TUN carry an
+ * application's traffic* — cannot be made from inside this app. This client is
+ * forced out of its own tunnel in every mode, because a VPN inside its own
+ * tunnel is a routing loop, so instrumentation's sockets never enter the TUN.
+ * The claim belongs to a process that is not this app, and the one available is
+ * `adb shell`, which runs as the shell user and *is* inside the tunnel.
+ *
+ * But `adb` cannot start a VPN: `VpnService` needs consent and an application
+ * to bind it. So the shell needs something inside the app to bring the tunnel
+ * up and keep it up while the shell works — which is this.
+ *
+ * It is not a test and asserts nothing. It skips unless asked for by name, so
+ * an ordinary suite run never sits here holding a tunnel open for a minute.
+ */
+@RunWith(AndroidJUnit4::class)
+class TunnelHolderTest {
+    @Test
+    fun holdTheTunnelOpen() {
+        val seconds =
+            InstrumentationRegistry.getArguments().getString("nowhereHoldSeconds")?.toIntOrNull()
+        assumeTrue(
+            "not asked to hold a tunnel; pass -e nowhereHoldSeconds N",
+            seconds != null && seconds > 0,
+        )
+
+        E2eEnvironment.requireConsent(TunnelHarness.context)
+        TunnelHarness.start()
+        try {
+            // Printed so a script can wait for the tunnel rather than sleeping
+            // a guessed interval, which is the difference between a check that
+            // is slow and one that is flaky.
+            println("TUNNEL_UP")
+            System.out.flush()
+            Thread.sleep(seconds!! * 1_000L)
+        } finally {
+            TunnelHarness.stop()
+            println("TUNNEL_DOWN")
+        }
+    }
+}

conformance/cases/l1-coverage.md

@@ -255,8 +255,22 @@ What replaces them:
   goes through the session layer at a target only the Portal can reach.
 - The claim about the **TUN itself** carrying an application's traffic belongs to
   `conformance/scripts/e2e-tunnel-fetch.sh`, which drives the fetch from the
-  shell user — who is not this app and therefore is inside the tunnel. **That
-  script is written and has not yet been run end to end.**
+  shell user — who is not this app and therefore is inside the tunnel. **It has
+  now run**: 20,971,520 bytes with a matching digest, over both carriers, with
+  the Portal's own counters moving by the same amount. That is the first
+  evidence this project has ever had that the TUN carries an application's
+  traffic.
+
+  Two things it had to learn first. **Loopback never enters a VPN's TUN** — the
+  kernel routes 127.0.0.0/8 to `lo` rather than to the default route — so the
+  trick that works from inside the app, choosing an address only the Portal can
+  reach, proves nothing from a shell. The evidence is the Portal's byte counters
+  instead. And a **truncated** transfer is non-empty, so a retry loop that
+  accepted any non-empty file reported a corrupt tunnel when what it had was a
+  hold window that expired mid-transfer.
+
+- `conformance/scripts/device-acceptance.sh` runs the whole of Phase D as one
+  command against whatever device is attached.
 
 # L3
 

conformance/scripts/device-acceptance.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Phase D: what only a physical device can answer.
+#
+# Everything else in this suite runs on an emulator, and an emulator is not a
+# phone in five specific ways that a VPN meets on its first real device. This
+# runs the checks that can be run, records the observations that can only be
+# looked at, and prints a report either way -- because "each failure has a
+# recorded symptom and a hypothesis" is a result and a run that never happened
+# is not.
+#
+# Usage:
+#   NOWHERE_E2E_PORTAL=host:port NOWHERE_E2E_TARGET=host:port \
+#   NOWHERE_PORTAL_LOG=/path/to/portal.log \
+#   conformance/scripts/device-acceptance.sh
+#
+# The target must be an HTTP origin the **Portal** can reach, serving /blob.bin
+# and /small.bin with an X-Content-Sha256 header -- the one e2e-fakeip.sh
+# starts, or the extracted copy of it.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+DEVICE="${NOWHERE_DEVICE:-}"
+PORTAL="${NOWHERE_E2E_PORTAL:-}"
+TARGET="${NOWHERE_E2E_TARGET:-}"
+APP_ID="eu.nodepass.somewhere"
+
+PASSES=0; FAILS=0; NOTES=0
+pass() { echo "  PASS  $*"; PASSES=$((PASSES+1)); }
+miss() { echo "  FAIL  $*"; FAILS=$((FAILS+1)); }
+note() { echo "  NOTE  $*"; NOTES=$((NOTES+1)); }
+head2() { printf '\n── %s\n' "$*"; }
+die()  { echo "cannot start: $*" >&2; exit 2; }
+
+command -v adb >/dev/null || die "adb is not on PATH"
+[ -n "$DEVICE" ] || DEVICE="$(adb devices | awk '$2=="device"{print $1; exit}')"
+[ -n "$DEVICE" ] || die "no device"
+[ -n "$PORTAL" ] || die "set NOWHERE_E2E_PORTAL"
+[ -n "$TARGET" ] || die "set NOWHERE_E2E_TARGET"
+
+sh() { adb -s "$DEVICE" shell "$@" 2>/dev/null | tr -d '\r'; }
+
+MODEL="$(sh getprop ro.product.model)"
+SDK="$(sh getprop ro.build.version.sdk)"
+ABI="$(sh getprop ro.product.cpu.abi)"
+EMULATED="$(sh getprop ro.kernel.qemu)"
+
+echo "Somewhere · device acceptance"
+echo "  device   $DEVICE"
+echo "  model    $MODEL"
+echo "  android  API $SDK, $ABI"
+if [ "$EMULATED" = "1" ]; then
+    echo
+    echo "  !! This is an emulator. Every check below will run and none of them"
+    echo "     answers the question Phase D exists for, which is what a phone"
+    echo "     does. Use it to check the script, not the client."
+fi
+
+# ── 1. Private DNS ──────────────────────────────────────────────────────────
+# Modern Android defaults to Automatic, and the resolver then speaks DoT to a
+# resolver of its own rather than sending UDP/53 to the address the TUN
+# announces. Fake-IP depends on seeing those queries; if it does not, remote
+# name resolution silently stops happening.
+head2 "1. Private DNS"
+PRIVATE_DNS="$(sh settings get global private_dns_mode)"
+case "$PRIVATE_DNS" in
+    off) pass "Private DNS is off; the resolver will use the TUN's" ;;
+    opportunistic|"null"|"") note "Private DNS is '$PRIVATE_DNS' (Automatic). The resolver may speak DoT and bypass the TUN's resolver. Watch whether names resolve below." ;;
+    hostname) miss "Private DNS is set to a specific hostname ($(sh settings get global private_dns_specifier)). DoT will bypass the TUN's resolver." ;;
+    *) note "Private DNS mode is '$PRIVATE_DNS', which this script does not know" ;;
+esac
+
+# ── 2. The app list, which is D-16 ──────────────────────────────────────────
+# The manifest declares <queries> for launcher-visible apps instead of asking
+# for QUERY_ALL_PACKAGES. Whether that is enough has never been measured
+# against a device with real applications on it. This is the measurement.
+head2 "2. Package visibility (D-16)"
+INSTALLED="$(sh 'pm list packages -3' | wc -l | tr -d ' ')"
+LAUNCHABLE="$(sh 'cmd package query-activities --brief -a android.intent.action.MAIN -c android.intent.category.LAUNCHER' | grep -c '/' || true)"
+echo "  third-party packages installed:      $INSTALLED"
+echo "  packages with a launcher activity:   $LAUNCHABLE"
+if [ "${INSTALLED:-0}" -lt 5 ]; then
+    note "only $INSTALLED third-party apps here, so this measures nothing. Run it on a device someone uses."
+elif [ "${LAUNCHABLE:-0}" -gt 0 ] && [ "$INSTALLED" -gt 0 ]; then
+    note "compare these two by hand against the per-app screen. D-16 closes as 'neither' if the screen's list is close to $INSTALLED, and reopens with a number if it is not."
+fi
+
+# ── 3. Address families ─────────────────────────────────────────────────────
+# The TUN carries a v4 address and a v4 default route and nothing else, and
+# fake-IP answers AAAA with NODATA by design. On an IPv6-only mobile network
+# that may carry nothing at all.
+head2 "3. Address families on the current network"
+V4="$(sh 'ip -4 addr show scope global' | grep -c 'inet ' || true)"
+V6="$(sh 'ip -6 addr show scope global' | grep -c 'inet6' || true)"
+echo "  global IPv4 addresses: $V4"
+echo "  global IPv6 addresses: $V6"
+if [ "${V4:-0}" -eq 0 ] && [ "${V6:-0}" -gt 0 ]; then
+    miss "IPv6-only network. This client's TUN carries no IPv6 route, so it will carry nothing here. This is the case Phase D exists to find."
+elif [ "${V6:-0}" -gt 0 ]; then
+    note "dual-stack. v6 traffic takes the underlying network rather than the tunnel, by design and unchanged."
+else
+    pass "IPv4 only; the TUN's single route covers it"
+fi
+
+# ── 4. The tunnel actually carries traffic ──────────────────────────────────
+# Both carriers, because a device is where a carrier difference would first
+# show as something other than a test failure.
+for CARRIER in tcp udp; do
+    head2 "4. Traffic over the tunnel ($CARRIER)"
+    if NOWHERE_E2E_CARRIER="$CARRIER" "$ROOT/e2e-tunnel-fetch.sh" "$TARGET" /blob.bin > "/tmp/somewhere-fetch-$CARRIER.log" 2>&1; then
+        RELAYED="$(grep -o 'the Portal relayed [0-9]* bytes' "/tmp/somewhere-fetch-$CARRIER.log" | head -1)"
+        ATTEMPT="$(grep -o 'on attempt [0-9]*' "/tmp/somewhere-fetch-$CARRIER.log" | head -1)"
+        pass "20 MB intact over $CARRIER — ${RELAYED:-no counter}, ${ATTEMPT:-first attempt}"
+    else
+        miss "$CARRIER: $(tail -3 "/tmp/somewhere-fetch-$CARRIER.log" | tr '\n' ' ')"
+    fi
+done
+
+# ── 5. Doze and battery management ──────────────────────────────────────────
+# Vendor battery managers kill foreground services that survive indefinitely on
+# an emulator. There is no way to assert the outcome from here; what can be
+# reported is whether the app is exempt, which is what a user would have to
+# change.
+head2 "5. Battery management"
+STANDBY="$(sh "am get-standby-bucket $APP_ID")"
+IGNORING="$(sh "dumpsys deviceidle whitelist" | grep -c "$APP_ID" || true)"
+echo "  standby bucket:                 ${STANDBY:-unknown}"
+echo "  exempt from battery optimisation: $([ "${IGNORING:-0}" -gt 0 ] && echo yes || echo no)"
+note "leave the tunnel running and the screen off for thirty minutes, then check it is still up. Nothing here can do that for you."
+
+# ── 6. MTU ──────────────────────────────────────────────────────────────────
+# TUN_MTU is 1500. Real cellular paths are frequently smaller, and there is TLS
+# or QUIC framing on top. QUIC makes this sharper: a datagram that does not fit
+# is not fragmented by the path.
+head2 "6. Path MTU"
+UNDERLYING="$(sh "ip link show" | grep -E "wlan0|rmnet|eth0" | grep -o "mtu [0-9]*" | head -1 | cut -d' ' -f2)"
+echo "  underlying interface MTU: ${UNDERLYING:-unknown}"
+if [ -n "$UNDERLYING" ] && [ "$UNDERLYING" -lt 1500 ] 2>/dev/null; then
+    miss "the path MTU is $UNDERLYING, below the TUN's 1500. Large packets will need fragmenting somewhere, and this client does not do it."
+else
+    pass "the underlying MTU is ${UNDERLYING:-1500}, so the TUN's 1500 fits"
+fi
+
+# ── Report ──────────────────────────────────────────────────────────────────
+printf '\n%s\n' "──────────────────────────────────────────"
+echo "$PASSES passed, $FAILS failed, $NOTES to look at by hand"
+echo
+echo "A NOTE is not a pass. It is something only a person watching the device"
+echo "can settle, and leaving it unsettled is the honest state until they do."
+[ "$FAILS" -eq 0 ] || exit 1