# weirdnet-net
Peer-to-peer networking for applications that keep their own data: a libp2p node, key
exchanges with invitation tokens and links, sealed messaging over those exchanges, node
identities, and user certificates and cards. The application brings its own request and
response types, its own storage and its own policy; the crate brings the wire.
- `node`: a `Node<Q, R>` over TCP and QUIC (or an in-memory transport for tests) with Noise
and Yamux, mDNS, Kademlia, identify, ping, a relay client and an opt-in relay server,
DCUtR hole punching and AutoNAT. The swarm runs on its own thread; the handle is blocking.
Requests are the application's `Q`, answers its `R` (CBOR), answered by a `Handler`.
`NodeConfig::relay_limits` sets what the relay server allows: `RelayLimits::default()`
keeps libp2p's (2-minute, 128 KiB circuits, enough for hole punching and small requests),
`RelayLimits::unlimited()` caps nothing, so circuits carry data.
Key-only dialing: `request_key(peer, …)` finds a peer by its key alone (the DHT, then
circuits through this node's relays and names servers); `request_user(user_id, …)` looks
the user's record up and dials it.
Request and response caps and the request timeout are `NodeConfig` settings
(`request_max`, `response_max`, `request_timeout`; 8 MiB, 256 MiB and 60 s by default).
- `stream`: byte streams with no size cap. An application accepts its own protocol ids
(`Node::accept_streams("/myapp/sync/1", Limits)`) and opens them
(`Node::open_stream(peer, addrs, protocol, Limits)`); one node carries any number of
apps' protocols, and a protocol nobody accepts is refused. A `Stream` is `AsyncRead` +
`AsyncWrite` (any executor) and blocking `Read` + `Write`, with backpressure (a window of
unacknowledged bytes) and per-protocol `Limits` (window, frame size, open streams, backlog,
idle reset, how long to wait for a path). Streams move between paths without losing or
repeating a byte: when a direct connection comes up (hole punching or a dial) the opener
moves its relayed streams there, and when a connection goes away the stream carries on over
the path that is left (relays are kept warm while streams are open). `Stream::path`,
`Stream::moves`, `Node::paths` and `Node::drop_path` show and steer that.
- `events`: what the node is doing. `Node::events()` is a stream (or `next_timeout`) of
listeners, external addresses, connections with their path, relay reservations made and
lost, and the NAT verdict; `Node::watch_status()` waits for the `Status` to change. Apps
call `Node::pause` and `Node::resume` as they go to the background and back, and
`Node::network_changed` when the device changes networks. Lost reservations are asked for
again with backoff. `request_async`, `connect_async` and `dial_async` suit async callers on
any executor. CI checks Android (aarch64-linux-android) and iOS (aarch64-apple-ios) builds and
runs the tests on Linux, macOS and Windows.
- `wss`: WebSocket over TLS for networks that only let HTTPS out. Every node dials
`/dns/<name>/tcp/443/tls/ws/p2p/<id>` (or `/wss`) trusting the web PKI; with
`NodeConfig::wss` set to a `WssTls` (`from_pem_files("fullchain.pem", "privkey.pem")`) a node
also listens on `/ip4/0.0.0.0/tcp/443/tls/ws`. Noise and Yamux run inside, so peer ids are
checked as on TCP. A renewed certificate takes a restart for now.
- `ingress`: public HTTPS for hosts without a public address, by SNI passthrough. An
ingress peer (`Ingress::start(&node, IngressConfig { https: 0.0.0.0:443, http: 0.0.0.0:80, .. },
binding)`) reads only the ClientHello's server name, finds the host that registered it and
splices the bytes over a `/weirdnet/ingress/1` stream behind a PROXY v2 header (client
address, name). TLS ends on the host (`Node::accept_ingress`); the ingress holds no key. A
host registers with `Node::register_ingress` and an `IngressGrant` signed by its user key;
the ingress checks the grant, the user's certificate for the node and the DNS binding
`_weirdnet.<name> TXT "v=1 user=<id>"` (`DnsBinding`). Port 80 forwards ACME HTTP-01 for
registered names and redirects the rest to HTTPS. `Ingress::revoke(name)` stops a site on
this device and `set_enabled(false)` stops forwarding altogether. No HTTP/3 passthrough
and no per-grant byte limits yet.
- `addr::dnsaddr_record(name, port, peer)`: the `_dnsaddr.<name>` TXT record
(`dnsaddr=/dns/<name>/tcp/<port>/p2p/<peer>`) for Grindvakt or any DNS provider to write, and
`dnsaddr_dial(name, peer)` to reach the node by it. `NodeConfig::dns_servers` picks the
resolver; without it the system's is used, or public resolvers where there is none (Android).
- `content`: files by content. `add_reader`/`add_bytes` split a file into content-defined
chunks (an rsync-style rolling checksum, 16 to 256 KiB) in the application's `ChunkStore`
(`MemoryStore`, `DirStore` or its own) and return a `FileIndex`; the file's root is the
BLAKE3 hash of that index, and an edit changes only the chunks around it. A `Manifest` maps
paths to roots, sizes and app metadata, versioned and signed by a user key, with roots it
revokes. `serve(&node, store, allow)` answers `/weirdnet/content/1` for what `allow` lets
each peer have; `fetch` (or `fetch_async`) gets a root's index and the chunks the store
lacks from one or more `Source`s, checking every hash, so a newer version moves only its
changed chunks and an interrupted fetch picks up where it stopped. `fetch_range` gets only
the chunks under a byte range and `read_range` reads it. Public content goes in the DHT
with `Node::provide(&provider_key(&root))` and is found with `Node::providers`.
- `member` and `join`: lasting membership. A `Membership` (resource, member's user id, a
role id the application interprets, issued and optional expiry times) is signed by the
owner's user key; a `MemberRevocation` voids a user's memberships of a resource issued up
to a time, and travels in the content `Manifest` (`member_revocations`) or any way the app
likes, collected in `Revocations`. A member's node presents the membership with its user's
card on a stream (`present`); the host checks it is valid, unrevoked and the card's
certificate is for the very node speaking (`read_presented`, `check_presented`). To ask for
membership, a user signs a `JoinRequest` and sends it on `/weirdnet/join/1`
(`request_join`); `serve_joins` checks it, applies per-user and per-node rate limits and a
cap on pending requests, and keeps it in the app's `JoinQueue`. The owner `approve`s (a
membership) or `deny`s (a signed `Denial`), and sending the same request again fetches the
answer.
- `names`: where a peer is now. A `PeerRecord` (addresses and relay circuits, home relay,
`seq`, expiry of at most a day) is signed by the node key and chained to the user key by
the node's certificate; a `Withdrawal`, signed by one of the user's nodes with a higher
`seq`, removes it and holds until it expires. Records go to the home relay's names server
(`/weirdnet/names/1`: `Node::register`, `discover`, `lookup`; a node serves it with
`NodeConfig::names_server`) and, while the device hosts something, to the Kademlia DHT
under `SHA-256("weirdnet/peer/" + user id)` (`put_entry`, `get_entries`), where every
storing node runs `Profile::accept`: valid signature, unrevoked certificate, unexpired,
higher `seq` wins. `_weirdnet.<name> TXT "v=1 user=<id>"` binds a domain to a user
(`binding_txt`, `parse_binding`).
- `exchange`: signed offers and answers (Ed25519 node keys, fresh X25519 keys), the derived
exchange key, a ten-digit short code and a fingerprint to compare out of band, tokens and
links (invitations), scopes with an expiry, and sealed messages bound to the exchange and
direction.
- `sealed`: send a sealed request through the application's envelope and open the answer
(`call`), and answer one only for the exchange's own, Noise-authenticated peer (`serve`).
- `invite`: invitation automation over the application's records (`Host`) and messages
(`Ask`, `Say`): `connect` (hello, then an offer delivered and answered on the spot or kept
for the owner), answering on arrival when the host's `decide` says so, `poll` and
`settle` for kept offers and undelivered answers, crossing offers settled on one exchange,
trust on first use (`known`, `pinned`, `impostor`, names resolving to the pinned node),
relay addresses for a peer and the addresses fit for invite links.
- `identity`, `user`, `sync`, `shard`, `addr`: node identities through an `IdentityStore`,
user certificates, revocations, cards and link grants, the linked-node sync key, dark-shard
blobs as custodians carry them, and address helpers.
`harness/netns.sh` runs nodes in Linux network namespaces behind iptables NAT routers
(`examples/netns_node.rs`), and CI runs it: reservations on a relay, a stream that starts
on the relay and moves to a hole-punched direct path across two NATs, a symmetric NAT that
stays on the relay, QUIC to the relay, mDNS on a LAN, and AutoNAT verdicts, each with a
content fetch. Run it with `sudo harness/netns.sh target/debug/examples/netns_node`.
Every identifier on the wire or under a signature comes from a `Profile`. `WEIRDNET` is the
default (`/weirdnet/net/1`, `wnet-x1-offer:`, `weirdnet://join/`, port 4747 and so on). An
application with nodes already in the field passes its own profile with the values those
nodes use, so nothing changes for them.
Key cryptography is not here: every derivation, seal and open goes through `weirdnet-keys`,
and key backups and recovery stay there. Shard blobs and backups cross the network as opaque
bytes. See `SECURITY.md` for the boundaries and what has not been checked.
```rust
use weirdnet_net::{WEIRDNET, Keypair, exchange::Token, profile::invite_scope};
let (anna, ben) = (Keypair::generate_ed25519(), Keypair::generate_ed25519());
let p = &WEIRDNET;
let (offer, secret) = p.offer(&anna, "anna", vec![], invite_scope("garden", "member"), 0, 60_000).unwrap();
let link = p.link(&p.offer_token(&offer).unwrap());
let Token::Offer(seen) = p.parse_token(&link).unwrap() else { unreachable!() };
p.verify_offer(&seen, 1).unwrap();
let (answer, on_ben) = p.answer(&ben, &seen, "ben", vec![], 1).unwrap();
let on_anna = p.complete(&answer, &offer, &secret[..]).unwrap();
assert_eq!(on_anna.short_code, on_ben.short_code);
```