# PeerNet — Implementation plan > Status: in-progress, v1 scoped to walkie-talkie chat + asymmetric BEAM-dist > compatibility. Initiated 2026-05-05. ## Why this exists The Erlang/Elixir ecosystem has nothing in the gap between: - **BEAM distribution** — ergonomic, but cookie-based trust = remote shell on every cluster member. Unsafe between mutually-suspicious peers. - **HTTP / Phoenix Channels** — safe, but client-server, needs infrastructure. - **WebRTC, libp2p, Iroh** — peer-to-peer, but heavyweight and not BEAM-native. PeerNet aims to fill it: BEAM-dist-shaped ergonomics (`expose` / `call` / `send`) between mutually-suspicious peers, with cryptographic identity and default-deny authorization. Pure-Elixir, transport-pluggable, no infrastructure. ## Goals (v1) - **Default-deny.** No handle is reachable from a peer until explicitly `expose`'d. No `:rpc.call` shell, no remote code load, no remote process introspection. - **Cryptographic peer identity.** Ed25519 keypairs; pubkey is the address; trust list is explicit (paired peers only). - **Network resilience.** Pubkey = logical address. Peers reconnect across IP changes, network switches, and transient disconnects without app code knowing. - **BEAM dist coexistence.** Runs alongside regular Erlang dist on the same node; no port conflicts. Optional `PeerNet.BeamDist` convenience module for asymmetric full-access scenarios (e.g. phone controlling Nerves). - **Walkie-talkie semantics.** Drop-by-default on offline send. No store-and-forward, no ack/retry, no message ordering guarantees beyond per-connection FIFO. - **Same-network discovery.** mDNS for peer discovery. Internet-spanning is out of scope for v1. ## Non-goals (v1) - Group chat / multi-recipient messaging - NAT traversal / hole punching - Offline message queueing - File transfer / large payload streaming - iOS background mode workarounds - Cross-language wire interop (BEAM-only for v1) ## Architecture ``` ┌──────────────────────────────────────┐ │ PeerNet (public API) │ │ expose / call / send / pair / list │ └──────────────────────────────────────┘ │ ┌───────────────────────────┼───────────────────────────┐ │ │ │ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │ Identity │ │ Trust │ │ Handlers │ │ keypair │ │ allowlist │ │ registered │ │ persisted │ │ persisted │ │ {name → fn} │ └────────────┘ └──────────────┘ └──────────────┘ │ ┌───────────────┴────────────────┐ │ │ ┌──────────┐ ┌──────────────┐ │ Registry │ ← pubkey → state │ Discovery │ │ (state) │ ←─────────────────→│ (mDNS) │ └──────────┘ └──────────────┘ │ │ manages connections (DynamicSupervisor) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Connection (1 per peer) │ │ ├─ Handshake (Noise XX, Ed25519 verify, AEAD wrap) │ │ ├─ Frame (length-prefixed safe ETF) │ │ ├─ Liveness (app-level ping/pong) │ │ └─ Reconnector (exponential backoff) │ └─────────────────────────────────────────────────────────────┘ │ ┌─────┴──────┐ │ TCP socket │ └────────────┘ ``` ## Module breakdown + line estimates | Module | Est. lines | Pure? | Notes | |------------------------------|-----------:|:-----:|-----------------------------------------| | `PeerNet` | ~80 | N | Public API surface | | `PeerNet.Application` | ~30 | N | OTP app | | `PeerNet.Supervisor` | ~40 | N | Top-level supervision tree | | `PeerNet.Identity` | ~100 | Y | Ed25519 keypair gen / load / save | | `PeerNet.Trust` | ~80 | Y | Allowlist of peer pubkeys | | `PeerNet.Handlers` | ~80 | Y | Exposed handle registry + dispatch | | `PeerNet.Frame` | ~80 | Y | Length-prefix framing + safe ETF | | `PeerNet.Registry` | ~120 | N | Pubkey-keyed state, transitions | | `PeerNet.Discovery` | ~100 | N | mDNS announce + listen via mdns_lite | | `PeerNet.Connection` | ~250 | N | TCP + Noise + framing + lifecycle | | `PeerNet.Connection.Sup` | ~30 | N | DynamicSupervisor | | `PeerNet.Handshake` | ~150 | ~ | Noise XX state machine | | `PeerNet.Liveness` | ~50 | N | App-level heartbeat | | `PeerNet.Reconnector` | ~60 | N | Exponential backoff | | `PeerNet.NetworkMonitor` | ~80 | N | IP-change events (polling default impl) | | `PeerNet.BeamDist` | ~80 | Y | Opt-in RPC-like handle for asym trust | | **Total** | **~1410** | | + tests ≈ 2–3× the impl size | ## Wire format Length-prefixed framing over TCP. Each frame: ``` | 4-byte big-endian length | Noise-AEAD-encrypted payload | ``` Inner payload, after Noise decrypt: ```elixir {:call, request_id, handle_name, args} # → reply expected {:reply, request_id, result} # match by request_id {:send, handle_name, args} # fire-and-forget {:ping, nonce} # liveness {:pong, nonce} # liveness reply {:error, request_id, reason} # call failed ``` Encoded via `:erlang.term_to_binary/2` with `[:safe]` decoding via `:erlang.binary_to_term/2` — defends against atom-exhaustion attacks. `request_id` is a 64-bit random integer. Replies match on it. ## Cryptography - **Identity**: Ed25519 keypair via `:crypto.generate_key(:eddsa, :ed25519)`. - **Handshake**: Noise XX pattern (mutual auth, both sides learn each other's static keys). Both sides verify the other's static key against the trust list before completing the handshake. - **Transport AEAD**: ChaCha20-Poly1305 via the Noise CipherState. - **Library decision**: Depend on a maintained Noise crate for v1 (e.g. `noise_ex`). If none is suitable, vendor a minimal Noise XX implementation built on `:crypto` primitives. Document the choice in `lib/peer_net/handshake.ex` so it can be swapped later. ## BEAM dist compatibility (asymmetric trust) PeerNet does **not** speak the disterl wire protocol. It coexists with disterl (different ports, different transport, no conflict). The asymmetric-trust use case (e.g. phone controlling Nerves) is served by an opt-in convenience module: ```elixir # On the Nerves device — explicit grant per peer: PeerNet.expose(:beam_admin, &PeerNet.BeamDist.handle/2, authorize: fn pubkey -> pubkey == @phone_pubkey end) # On the phone — RPC-style sugar: PeerNet.BeamDist.call(nerves_pubkey, MyMod, :restart_wifi, []) PeerNet.BeamDist.cast(nerves_pubkey, Logger, :info, ["hi from phone"]) ``` Internally, `BeamDist.handle/2` accepts `{:rpc, mod, fun, args}` tuples and calls `apply(mod, fun, args)`. The grant is explicit per pubkey; without it, the handle is unreachable. This gives BEAM-dist-equivalent semantics where you actually want them, gated by cryptographic identity. Asymmetric: only the granted peer can make calls. The Nerves device cannot reciprocally RPC the phone unless the phone separately grants. ## TDD order Implement bottom-up so each module's tests can run without mocking the next layer: ### Phase 1 — pure modules (no network) 1. **`PeerNet.Identity`** — keypair generation, persistence, fingerprinting. Pure functions, file I/O. Tests use `tmp_dir` fixtures. 2. **`PeerNet.Trust`** — pubkey allowlist with persistence. Pure logic. 3. **`PeerNet.Frame`** — encode / decode roundtrip, malformed input rejection, atom-exhaustion defense. 4. **`PeerNet.Handlers`** — register, lookup, default-deny. Pure logic. ### Phase 2 — networked modules 5. **`PeerNet.Handshake`** — Noise XX state machine. Test via in-process pairs (initiator + responder in the same BEAM, byte-buffer transport). 6. **`PeerNet.Connection`** — full connection lifecycle. Test via two connections on `127.0.0.1` in the same BEAM. 7. **`PeerNet.Registry`** — peer state tracking. Test in isolation with simulated events. 8. **`PeerNet.Liveness` + `Reconnector`** — small modules, tested with simulated time / process-message-injection. 9. **`PeerNet.NetworkMonitor`** — define behaviour, ship a polling default, test with a mock implementation. ### Phase 3 — discovery + integration 10. **`PeerNet.Discovery`** — mdns_lite wrapper. Hardware-dependent integration tests under `@tag :integration`. 11. **End-to-end integration tests** — two PeerNet instances in the same BEAM, full pair / send / call / disconnect / reconnect flow. ### Phase 4 — convenience 12. **`PeerNet.BeamDist`** — RPC-style sugar layer, ~80 lines on top of the primitives. ## Documentation - `@moduledoc` on every module describing purpose + when to use it. - `@doc` on every public function with examples. - `@spec` on every public function. - `README.md` — quick-start, architecture diagram, threat model. - `guides/protocol.md` — wire-format specification + handshake walkthrough. - `guides/cookbook.md` — common patterns (pairing flow, BEAM-dist usage). - Doctests where they make sense (Identity, Trust, Frame). ## Threat model (must document, not just code) - **Adversary**: a peer on the same network who can observe and inject packets, but is not in the trust list. - **Defended against**: passive eavesdropping (Noise AEAD); MITM (Noise XX with pubkey verification); replay (Noise nonces); denial-of-service via malformed wire (Frame validation, safe ETF); resource exhaustion via atom interning (`:safe` ETF flag); impersonation (Ed25519 sigs). - **Not defended against**: side-channel timing, traffic analysis, peers in the trust list misbehaving, OS-level compromise. ## Milestones - **M1** ✅ — Phase 1 complete. Pure modules: Identity, Trust, Frame, Handlers. 49 tests + 8 doctests, all green. - **M2 (POC)** ✅ — Phase 2 transport landed in challenge-response form: Handshake (Ed25519 signed nonces), Connection, PeerIndex, Acceptor, full per-instance supervision. Two PeerNet instances in the same BEAM can `expose`/`call`/`send` over loopback TCP. End-to-end integration tests cover happy path, untrusted-peer rejection, no-such-handle, and fire-and-forget send. **Caveat**: v0 transport is **plaintext over TCP** — the channel is authenticated but not encrypted. Local-trusted-network only until M2.5. - **M2.5** ✅ — Replaced challenge-response with **Noise XX** (`Noise_XX_25519_ChaChaPoly_SHA256`). Hand-rolled SymmetricState + CipherState + HandshakeState on `:crypto` primitives, ~440 lines. All post-handshake traffic is AEAD-encrypted via the new `PeerNet.Channel` module (ChaCha20-Poly1305, Noise nonce format, per-direction CipherStates). Identity migrated from Ed25519 to X25519 (the curve Noise uses for both DH and the static key). No public API changes — `PeerNet.expose/4`, `call/5`, `send/4` are unchanged. Frame layer gained a raw-bytes encode/decode path (`Frame.encode_raw/1`, `Frame.decode_raw/1`) so AEAD ciphertexts pass through without ETF double-wrapping. - **M3 (almost complete)** ✅ — Liveness, Registry with auto- reconnect via exponential backoff, Discovery behaviour + Manual + UDP impls. Auto-discovery on a LAN works: `PeerNet.Discovery.UDP` broadcasts a compact 39-byte announce (magic + version + port + pubkey) every 5s and listens for the same on UDP `4040`. Discovered trusted peers are auto-dialled by the Registry; the resulting connection is callable as soon as the handshake completes. **Notes on mDNS vs UDP**: `mdns_lite` exposes only the announce side; it has no public browse API. Rolling proper mDNS browsing on `:gen_udp` + `:inet_dns` is ~1 session of work and gets us interop with iOS Bonjour and Android NSD. UDP broadcast (what we shipped) is simpler, works on desktop / Nerves, but needs platform-specific permissions on mobile (`NSLocalNetworkUsageDescription` etc). **For mobile**: the right layering is for the host app's NIF to provide a `Discovery.Bonjour` / `Discovery.NSD` impl that wraps platform mDNS APIs. PeerNet ships the Behaviour and the UDP reference impl; mob plugs in the platform-specific one. **NetworkMonitor** ✅ — behaviour + polling default implementation. Subscribers (the Registry by default) get `{:network_changed, change}` events. On change, Registry tears down all live connections so reconnect logic dials fresh sockets on the new network immediately. **Pending**: `Discovery.MDNS` (true mDNS via `:inet_dns`). - **M4 (partial)** ✅ — `BeamDist` convenience module landed. Asymmetric-trust RPC: receiver exposes `:beam_admin` with an `authorize:` predicate per pubkey; caller invokes via `BeamDist.call/6` or `cast/6`. Tests cover happy path + forbidden + unknown-op. Docs polish complete: protocol.md fully describes Noise XX wire format and frame layering; cookbook.md has working patterns for every use case with test references. CHANGELOG.md tracks the v0.1 features. **Pending**: Hex `0.1.0` release (mostly admin — see `RELEASING.md`).