Aleksandr Bogomiakov
90ef5cefec
Offline devices reserved names and IPv4 addresses indefinitely, leaving stale members in the device history. Give every authenticated network participant the same right to retire another device's observed signed claim without an owner, quorum, permanent identity ban or secret change. Add a separately signed retirement containing the target's original signed claim as proof. Verify both signatures and network scopes, retain the strongest proved cutoff per target with deterministic ties, and suppress claim versions at or below it in membership, hostname ownership and IPv4 allocation. Keep the old signed records and range agreement, and retain markers after a newer claim returns so old replicas cannot resurrect obsolete reservations. A returning device signs a newer claim, allocates against current holders and resets its previous hostname priority rather than taking a reused name with an old time. Commit local retirement and the requester's author counter atomically before announcing it; receivers persist proofs before applying them. Bound history to 1024 targets by default, reject additional targets without evicting protection, and treat corrupt or over-limit mandatory storage as an explicit error. Repeat bounded marker batches with a per-session rotating cursor so queue pressure cannot indefinitely starve later markers. Exclude retired claims and cached hints from history-derived discovery without preventing a fresh authenticated device from returning. Expose Agent::forget_node through the shared local control API. CLI command tsng network forget-node accepts exact network names, full ids or unique id prefixes, and exact node hostnames, ids, prefixes or overlay IPv4 addresses. Ambiguous selections change nothing. Recheck the observed version and refuse self, online nodes, the selected exit node and absent or changed claims. Add Forget with an identity confirmation to offline tray device rows. Widen Show devices to 1440x640 with an 800x400 minimum to fit its contents. Control ALPN/version advances to tsunagi/ctrl/7 and local IPC to 21; upgrade all peers and restart the agent with matching CLI/tray clients. Data ALPN 5, network identity derivation, handshake encoding and existing record signing bytes remain unchanged. SQLite schema 9 adds retirement storage while retaining identity, secrets, settings and signed claims. Document behavior and limits. Validation on Linux through nix develop: - cargo fmt --all -- --check - cargo clippy --locked --workspace --all-targets -- -D warnings - cargo test --locked --workspace --all-targets: 519 passed, 2 existing ignored tests; inherited TSUNAGI_CONTROL_SOCKET and TSUNAGI_CONTROL_GROUP were unset - git diff --check and the built CLI forget-node help Tests use real iroh authentication and SQLite. Cover restart, stale-replica recovery, equal rights and network isolation, hostname reuse and return, twelve marker batches through a two-message queue, malformed signatures and proofs, invented future cutoffs, deterministic merge, capacity, migration and injected counter-write rollback, selectors and cleanup through two real CLI processes. Earlier iterations caught a private test API, a collapsible tray conditional and a crash-based CLI test waiting for QUIC's idle timeout; corrected before the final successful suite. Manual tray rendering, macOS/Windows, privileged TUNs and public-network traversal were not run. The requested RC tag is v0.1.0-rc.31; no push was requested.
8.2 KiB
8.2 KiB
Threat model and known limits
Read this before relying on anything here. The protocol is in protocol.md.
What is protected
- Network membership. A peer must prove knowledge of
auth_key, derived from the network name and shared secret, to get an authenticated session. Knowing the publicNetworkId, or an agent's address, is not enough. - Endpoint authenticity. iroh's QUIC/TLS handshake authenticates the remote endpoint id, which is its public key. Identities in the membership transcript are taken from the certificate, never from a peer's claim.
- Connection binding. The membership proof includes TLS exporter output, so a proof captured on one connection does not verify on another.
- Role separation. Initiator and responder proofs cover different transcripts, so a proof cannot be reflected back at its sender.
- Network isolation. A session authenticated for network A cannot carry messages for network B, even over a shared physical connection.
- Confidentiality and integrity in transit. Provided by QUIC/TLS. This crate adds no encryption of its own.
- Overlay address ownership. A peer's overlay address is derived from its public key, not taken from its announcement. Outbound packets go to the owner of the destination address; inbound packets are dropped unless their source is the address derived for the peer that sent them. A member can therefore neither receive nor forge another member's traffic. See wireguard.md.
- Tunnelled traffic is end-to-end encrypted by WireGuard, independently of this crate. Carriers may be iroh, TLS, direct WG or pairwise AWG; confidentiality does not depend on a particular carrier.
- Resource bounds. Frame lengths are validated before allocation; strings, lists, queues, concurrent dials and in-flight handshakes are all bounded; handshakes, dials and writes have timeouts.
What is not protected
- Anyone who knows the secret is a full participant. They can create arbitrarily many identities, flood the network with records and collide with other participants' names. This is why a majority is not a root of trust. Signatures protect authorship; they do not make a participant honest.
- Cleanup rights are equal. Any member can retire an observed signed claim of another device, freeing its hostname and IPv4 reservation. A valid original claim bounds the cutoff; a member cannot invent a future cutoff or forge the target's release. The local API refuses online nodes, but a remote signature cannot prove that a target was offline. A live target may publish a newer claim; a malicious member can repeatedly disrupt reservations. Cleanup is not expulsion or secret revocation. See sync-model.md.
- Weak secrets. This targets high-entropy secrets. There is no PAKE, so a
short human passphrase can be guessed offline by anyone who can reach the
handshake. Use
NetworkSecret::generate(). - Public address publication. With
TransportPolicy::N0DefaultsorDirectOnly, iroh publishes a signed record of this endpoint's addresses, keyed by its endpoint id, to the public pkarr/DNS service run by Number 0 ("n0", the company behind iroh) atdns.iroh.link, and resolves peers through it. The network secret is never published and membership cannot be inferred from a single record, but the endpoint's existence and its addresses become public.LocalOnlypublishes nothing. - Addresses and metadata are observable. Anyone able to watch the network
sees addresses, timing and volume. Discovery backends see the
discovery_keyand the addresses published under it, which is enough to map a network's participants. This library does not make a network anonymous, and having iroh under it does not make it so. - A cloned state directory is a cloned identity.
state.sqliteholds the device secret key and the network secrets. Copying it copies the participant. Restoring an old backup rolls the agent's state back and can replay stale versions until it meets a replica holding the newer signed state. Retained cleanup markers prevent old claims from resurrecting after that merge; they cannot help if every copy of a marker has been lost. - A compromised host. The secret is on disk to survive restarts. File permissions are owner-only where the platform supports it, and the state directory takes an ownership lock, but neither defends against a user who can read the file or against malware running as that user.
- User IP traffic. Carried by the WireGuard plugin over an iroh data connection, and encrypted by WireGuard end to end. Filtering it is still the operating system's and the user's job: the plugin creates connectivity between members and does not police what flows over it.
- Traffic metadata reaches the relay when one is used. If iroh cannot hole punch, the data connection goes through a relay, which then sees the volume and timing of tunnelled traffic — though not its contents, which WireGuard encrypted, nor the iroh layer's contents.
- Exit nodes. A member that offers one carries other members' internet traffic and sees where it goes; a member that uses one trusts it completely. Anyone holding the network secret can use an offered exit node. See exit-node.md.
- Overlay address squatting. A member can mint many WireGuard keys and therefore occupy many overlay addresses. It cannot pick which ones, but it can consume them and appear as many participants.
- Plugin keys on disk. The WireGuard private keys live in the plugin's own
wireguard.sqlite, owner-only where the platform supports it. Copying that file copies this agent's overlay identity, exactly as copyingstate.sqlitecopies its control plane identity. - What the data plane does not police. Address ownership stops a member impersonating another member. It does not stop a member sending whatever it likes from its own address.
- Denial of service. Bounds and timeouts stop trivial resource exhaustion from a single peer. They do not make the agent resistant to a determined attacker who knows the secret, and no rate limiting per identity exists yet.
- Global freshness. A signature proves authorship, not that you have the newest state. See sync-model.md.
- Discovery is not trustworthy. It returns candidates. A hostile or stale discovery backend can waste dial attempts and learn addresses; it cannot forge membership.
Deliberate design consequences
- No owner, no vote. Nobody can evict anybody. Removing a participant means changing the secret, which creates a different network space that the removed participant cannot enter.
- Rotating the secret is not revocation of past access. Anyone who held the old secret keeps whatever they already saw.
- Local deactivation is not revocation. Deactivating a network stops this agent participating. It says nothing about anyone else.
- Failures are contained, not escalated. A bad proof, wrong secret, malformed frame or unknown version rejects one message or one session. It never stops another network and never stops the agent, and there is no irreversible global error flag.
Cryptographic choices
Standard primitives only, no home-made constructions: HKDF-SHA256 (RFC 5869) for key separation, HMAC-SHA256 for the membership proof, constant-time verification, iroh's Ed25519 endpoint keys and QUIC/TLS for the transport, and RFC 5705 TLS exporter output for channel binding. There is no custom encryption layer and no custom PAKE.
Pairwise AWG masking
AWG profiles, PSKs and outer keys are private to one authenticated pair attempt, not shared network state. Address candidates are unverified until authenticated outer WireGuard data arrives. Header protection and structured signature packets reduce fixed wire markers; they do not guarantee admission by DPI or hide traffic analysis. iroh control availability remains a prerequisite. Encrypted end-to-end delivery probes detect sustained carrier loss, never confer membership and pass the same signed source/destination admission as ordinary IP traffic. See amnezia.md for limits and tested scope.