# PeerNet v0.1.0 - Table of Contents

Default-deny peer-to-peer messaging for Elixir. BEAM-distribution-shaped
ergonomics (expose / call / send) between mutually-suspicious peers, with
Noise XX cryptographic handshake, ChaCha20-Poly1305 transport encryption,
pluggable LAN discovery, and walkie-talkie semantics.

## Pages

- [PeerNet](readme.md)
- [Changelog](changelog.md)
- [PeerNet — Implementation plan](plan.md)

- Guides
  - [PeerNet wire protocol](protocol.md)
  - [PeerNet cookbook](cookbook.md)

## Modules

- [PeerNet](PeerNet.md): Public API for the PeerNet library and the per-instance supervisor.
- [PeerNet.Channel.CipherState](PeerNet.Channel.CipherState.md): Per-direction AEAD key + counter. Treat as opaque; mutate only via
`PeerNet.Channel.encrypt/2` and `PeerNet.Channel.decrypt/2` (which
return updated structs).

- Identity &amp; trust
  - [PeerNet.Identity](PeerNet.Identity.md): Cryptographic identity for a PeerNet node — an X25519 keypair that uniquely
identifies one peer to all the others.
  - [PeerNet.Trust](PeerNet.Trust.md): Persistent allowlist of peer public keys this node will talk to.

- Wire &amp; dispatch
  - [PeerNet.Channel](PeerNet.Channel.md): Post-handshake transport: ChaCha20-Poly1305 AEAD over the same Frame
layer used during the handshake.
  - [PeerNet.Frame](PeerNet.Frame.md): Wire framing for PeerNet — length-prefixed Erlang Term Format payloads
with safety guards against malformed or hostile input.
  - [PeerNet.Handlers](PeerNet.Handlers.md): Default-deny registry of named, peer-callable handlers.

- Handshake
  - [PeerNet.Handshake](PeerNet.Handshake.md): Mutual-authentication handshake for PeerNet — implementation of the Noise
protocol's `XX` pattern with the suite
`Noise_XX_25519_ChaChaPoly_SHA256`.

- Transport
  - [PeerNet.Acceptor](PeerNet.Acceptor.md): TCP listener for one PeerNet instance. Accepts inbound connections and
spawns one `PeerNet.Connection` per accepted socket.
  - [PeerNet.Connection](PeerNet.Connection.md): One connection to one peer — a `GenServer` that owns a TCP socket, drives
the `PeerNet.Handshake` to completion, and then multiplexes
`:call`/`:reply`/`:send` envelopes over the wire.
  - [PeerNet.Connection.Supervisor](PeerNet.Connection.Supervisor.md): `DynamicSupervisor` for live `PeerNet.Connection` processes.
  - [PeerNet.Liveness](PeerNet.Liveness.md): Application-level heartbeat for one peer connection.

- Discovery
  - [PeerNet.Discovery](PeerNet.Discovery.md): Behaviour for discovering peers on a network.
  - [PeerNet.Discovery.Manual](PeerNet.Discovery.Manual.md): No-op discovery implementation — exposes inject points so tests and
manually-configured setups can drive discovery events at will.
  - [PeerNet.Discovery.UDP](PeerNet.Discovery.UDP.md): LAN UDP-broadcast discovery. Each instance
  - [PeerNet.Discovery.UDP.Transport](PeerNet.Discovery.UDP.Transport.md): Behaviour for the UDP transport used by `PeerNet.Discovery.UDP`.
  - [PeerNet.Discovery.UDP.Transport.GenUDP](PeerNet.Discovery.UDP.Transport.GenUDP.md): Production transport for `PeerNet.Discovery.UDP` — wraps Erlang
`:gen_udp` with broadcast enabled.
  - [PeerNet.Discovery.UDP.Wire](PeerNet.Discovery.UDP.Wire.md): Compact wire format for UDP-broadcast peer announcements.

- Network monitor
  - [PeerNet.NetworkMonitor](PeerNet.NetworkMonitor.md): Behaviour for noticing when this host's network situation changes —
primarily, when the set of local IP addresses gains or loses entries.
  - [PeerNet.NetworkMonitor.Polling](PeerNet.NetworkMonitor.Polling.md): Default `PeerNet.NetworkMonitor` implementation. Polls
`:inet.getifaddrs/0` on a configurable interval (default 5 seconds)
and notifies subscribers when the local IP set changes.

- Registry &amp; convenience
  - [PeerNet.BeamDist](PeerNet.BeamDist.md): Convenience layer that gives a specifically-trusted peer
BEAM-distribution-like RPC access — `apply(mod, fun, args)` over the
PeerNet wire, with the peer's identity verified cryptographically.
  - [PeerNet.Registry](PeerNet.Registry.md): Per-instance registry of peer state — pubkey → {connection, last-seen
address, status} — plus the auto-connect dispatcher.

