Skip to main content

Crate weirdnet_net

Crate weirdnet_net 

Source
Expand description

§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.
  • 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.

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.

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);

Re-exports§

pub use exchange::Answer;
pub use exchange::DEFAULT_TTL_MS;
pub use exchange::Derived;
pub use exchange::Offer;
pub use exchange::Token;
pub use exchange::normalize_code;
pub use node::Handler;
pub use node::Message;
pub use node::Node;
pub use node::NodeConfig;
pub use node::Sighting;
pub use node::Status;
pub use profile::Profile;
pub use profile::WEIRDNET;

Modules§

addr
Addresses: which are worth giving to others, which are reachable from elsewhere, how good each is for reaching a relay, and one circuit per relay.
exchange
Key exchanges: authenticated X25519 Diffie-Hellman between two node identities, and the invitation tokens and links that carry them.
identity
A node’s identity: an Ed25519 keypair made on first use. The application keeps it wherever it keeps secrets (an encrypted database, say) through IdentityStore; the crate never writes it anywhere itself.
invite
Invitation automation: the nodes run key exchanges themselves. An offer goes to the peer over the node (a connect request), signed by the node that sends it; the answer comes back in the reply, or later (a poll from the offerer, or the answerer delivering it) when the other side has to decide first. Two nodes that offer to each other at once settle on one exchange. A node is its key: the first completed exchange pins it (trust on first use), and another node using a pinned node’s name is flagged (impostor).
node
The libp2p node: TCP and QUIC (or an in-memory transport for tests) with Noise and Yamux; mDNS on the local network; Kademlia, identify and ping; relay client and (opt-in) relay server with DCUtR hole punching; AutoNAT; and request-response on the profile’s protocol id, carrying the application’s own request and response types (CBOR).
profile
Identifier profiles: every protocol id, token prefix, link scheme, signature domain and derivation label the crate puts on the wire or under a signature. WEIRDNET is the default. An application with nodes already in the field passes its own profile with the values those nodes use, so its bytes stay exactly as they were; two profiles never mix on one connection, because nodes on different protocol ids don’t talk at all.
sealed
Sealed exchange messaging over a node: a request sealed under an exchange key goes out inside the application’s own envelope, and the answer comes back sealed the other way.
shard
Dark-shard blobs as custodians keep and return them. The blob is sealed by weirdnet-keys (dark::seal) before it reaches the network; nodes only carry it and never see what is inside. Splitting, sealing, claim tags and recovery are the keys crate’s; which custodians to trust is the application’s.
sync
Keys for linked-node sync: pages travel sealed under a key derived from the user’s signing key (which only the user’s own nodes hold), on top of the exchange key. The derivation and the sealing are done by weirdnet-keys; what is synced is the application’s.
user
User identities: a person’s Ed25519 signing key, separate from node keys. The user certifies each node it links (a signature over the node’s peer id) and can revoke it later; peers check these before treating a node as acting for a user. A Card is what a node says about its user: the public key and the certificates, never a secret.

Structs§

Key32
A 256-bit secret key, wiped on drop and never printed.
Keypair
Identity keypair of a node.
Multiaddr
Representation of a Multiaddr.
PeerId
Identifier of a peer of the network.
PublicKey
The public key of a node’s identity keypair.
Sealed
A sealed message: hex nonce and hex ciphertext (with its tag).

Enums§

NetError
What went wrong. Applications map these onto their own errors; the messages say what happened without naming the application.

Functions§

now_ms
Milliseconds since the Unix epoch.
short_peer_id
The last 8 characters of a peer id.

Type Aliases§

Result