Ways to find iroh tunnels in the world around us
README.md

iroh-aware #

Your iroh endpoint, announced from your pocket. An Android app that advertises an iroh endpoint over Wi-Fi Aware peer-to-peer discovery — no internet, no shared LAN, no server. Named Data Networking is the long-game successor to the announcement layer.

1234build EndpointRecord (NodeId · port · relay hint)NAN beacon: service "com.superbfowle.iroh.aware.v1" + 44-byte record in the cleardecode → dedupe → show peerEndpoint.connect(NodeAddr) — relay first, then direct hintstwo devices, same room. discovery needs no connectivity at all.v2, once an iroh core is embedded:QUIC flows end-to-end.Wi-Fi Aware was pure signaling.Phone A — publisherPhone B — subscriberPhone A — publisherPhone B — subscriber

The idea: signaling, not a pipe #

iroh splits connection setup into two planes, and the split is the whole design:

Plane Job In iroh
Discovery (control) "where is node X reachable?" — given a NodeId, produce addressing data Pluggable Discovery trait; ships with DNS/pkarr, mainline DHT, mDNS backends
Transport (data) actually move bytes QUIC over UDP — hole-punched direct, relay fallback

So this project is a rendezvous publication, not a tunnel. We write a small record — who we are, where to try us — into a local radio channel that peers can hear, and let iroh do everything hard about connecting. Wi-Fi Aware's service discovery maps onto this almost embarrassingly well:

  • publish() ↔ announce our record
  • subscribe() ↔ discover peers' records
  • service-specific-info blob ↔ the record itself (44-byte fixed header + TLVs, 200-byte budget)

And one genuinely speculative idea keeps the door open: the Wi-Fi Aware NAN datapath is a real IP interface pair between two nearby phones. If QUIC can ride it (irhdn-datapath), then the discovery medium becomes a transport and the whole stack works with zero infrastructure.

What works today vs what doesn't #

✅ Works ⏳ Pending ❌ Not yet
Compiles to debug APK, JVM tests green On-device publish-session verification (irhdn-discovery-publish) Dialing discovered peers (needs embedded core, irhdn-discovery-dial)
Wire-format codec w/ full round-trip test matrix Two-device resolve verification (irhdn-discovery-resolve) Real ed25519 identity — current NodeId is a persisted random placeholder (caveat)
Dual-role Aware link: publish and subscribe on one attach Verifying the true NAN service-info cap (~255B cited, unconfirmed) Embedded iroh core / JNI pipeline (irhdn-transport-jni)
Runtime permission flow for API 33+ and ≤32 WebTransport gateway, NDN layer

Roadmap #

Tracked in beads — bd list, prefix irhdn.

Ver Epic Scope Status
v0 — Compilable skeleton: mise toolchain, Gradle wrapper, Aware availability probe ✅ done
v1 irhdn-discovery Announce/resolve endpoint records over Wi-Fi Aware ◐ code complete, device verification open
v2 irhdn-transport Embedded iroh core via JNI/cargo-ndk; real dialing; QUIC over the NAN datapath; WebTransport spike open
v3 irhdn-ndn NDN-style named announcements, trust schema, forwarder evals, presence sync open, speculative

Dependency shape (from bd list): survey → record → {publish, resolve} → dial; everything transport-shaped hangs off irhdn-transport-jni → -endpoint.

How it works #

app/src/main/java/com/superbfowle/iroh/aware/
├── MainActivity.kt          permission flow, start button, peer list UI
└── aware/
    ├── EndpointRecord.kt    wire format v1 codec — strict decode, tolerant TLVs
    ├── Identity.kt          placeholder NodeId: SecureRandom 32B, prefs-persisted
    └── AwareLink.kt         ONE attach, BOTH roles (mirrors the bitchat reference)

Wire format v1 (full spec: .design/wifi-aware/wire-format.md):

offset  size  field
0       1     version           = 0x01
1       32    node_id           raw iroh NodeId (ed25519 pubkey)
33      2     quic_port         u16 big-endian; 0 = unspecified until v2
35      8     timestamp_sec     u64 big-endian unix seconds
43      1     flags             bit 0: relay TLV follows
44      ..    TLVs              type u8, len u8, value — 0x01 = "host[:port]" relay

Decoders are strict about the header (version, truncation, unknown flags) and tolerant of unknown TLV types, so v2/v3 can extend without breaking v1 readers.

Design decisions worth knowing:

  • No signature in v1. The NodeId is the identity; spoofing resistance arrives with iroh's own handshake when dialing lands. Signed envelopes (pkarr-style) are the NDN-era concern.
  • There is no peer-lost callback on DiscoverySessionCallback — peer expiry is a timestamp filter in the UI, not an event.
  • NAN beacons are immutable: a changed record means stop/start republish. Cheap enough for now; revisit when a live endpoint makes records change often.

Building #

Toolchain is mise-managed — Java 17 (Temurin), Gradle 8.14.5, AGP 8.13.2, KGP 2.3.21, compileSdk/targetSdk 35, minSdk 26 (the Wi-Fi Aware baseline, matching n0's own Android demo). ANDROID_HOME resolves through mise.toml; no emulator or device needed to build.

mise exec -- ./gradlew :app:assembleDebug        # APK → app/build/outputs/apk/debug/
mise exec -- ./gradlew :app:testDebugUnitTest   # wire-format test matrix (9 tests)
mise exec -- ./gradlew :app:assembleDebug :app:testDebugUnitTest

Provisioning details and every gotcha hit along the way (Debian's ancient system Gradle, core-ktx↔AGP compatibility pins, SDK licensing) live in .design/android-skeleton/setup-notes.md.

Running on hardware #

adb install -r app/build/outputs/apk/debug/app-debug.apk

Grant the nearby-devices prompt, hit Announce & browse. Two phones running the app should list each other within seconds of NAN discovery. First check a device supports Aware at all — OEM firmware routinely ships API 26+ with the feature disabled; Ditto's wifi-aware-checker app answers that in one tap.

Prior art & references #

Each of these earned its place by contributing something concrete:

  • n0-computer/iroh-live Android demo — the template for v2: cargo-ndk → jniLibs pipeline, Kotlin JNI bridge, strip step, minSdk-26 rationale. Local checkout: ~/archive/n0-computer/iroh-live.
  • NodleCode/wifi-aware — research notes plus WifiAwareMeshServiceLatest.kt, a complete working dual-role mesh service. Our AwareLink structure follows its attach-once/publish+subscribe pattern. Not a library — prior art only.
  • Android Wi-Fi Aware overview — platform API surface, permission model, datapath mechanics.
  • getditto/wifi-aware-checker — documents the OEM-firmware lottery; its availability-probe pattern is in our stub.
  • m1ga/ti.wifi-aware — Titanium module; clearest minimal publish/subscribe/message flow and the NEARBY_WIFI_DEVICES request order.
  • iroh Discovery trait — the upstream shape irhdn-discovery-rust-trait wants to fill: NAN announce/resolve behind a Discovery impl any Rust Endpoint could use.
  • pkarr — signed DNS packets; iroh's existing announcement envelope and the natural bridge from our TLV records to named signed data.
  • Named Data Networking · NFD-android — the v3 horizon: names instead of channels, interests as pull-based rendezvous.

Deeper dives live under .design/ — capability survey, wire-format rationale, toolchain notes — each written against the tickets that consumed them.