Files

T

tsunagiandClaude Opus 5 ea7aaa2b69 Implement the WireGuard data plane plugin

The first IP plugin, built on the data plane boundary the core already had.

Plugin:
- one X25519 key per network in the plugin's own wireguard.sqlite, separate
  from the iroh identity and from the network secret; a damaged store is an
  error, never a silently regenerated identity
- deterministic IPv6 ULA overlay: every member derives the same /64 from the
  network id and its own /128 from its WireGuard public key, so no
  coordinator allocates addresses
- AllowedIPs are derived locally, never taken from a peer's announcement, so
  a member cannot claim another member's overlay address; a mismatched claim
  is rejected
- bounded, versioned, validated announcement carried as the existing opaque
  capability payload, which the core still never parses
- each agent builds its own full-mesh configuration (N-1 peers) and
  reconciles on every change and on a timer, repairing drift
- WireguardBackend abstraction: RecordingBackend in memory, and WgToolBackend
  driving real wg/ip on Linux, split into a pure planner plus parsers and a
  thin executor so everything interesting is testable without root

Core, three generic additions the plugin needed:
- IpPlugin::on_network_activated, so per-network state is ready before peers
- PluginContext for re-announcements and error reports from plugin tasks,
  with errors counted by the owning network runtime
- IpPlugin::shutdown, awaited with a grace period, so system objects go away

94 tests pass offline with no privileges: 35 new WireGuard unit tests and 12
integration tests over real iroh connections. The real wg/ip backend needs
root and is behind --ignored in tests/wireguard_system.rs; it was not run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-21 11:07:31 +01:00

3.9 KiB

Raw Blame History

Planned state synchronisation

Nothing in this document is implemented. The proof of concept exchanges hostname and capability announcements over live sessions and keeps no replicated history. That is also why WireGuard peer membership is session-scoped today: a peer disappears from the overlay configuration when its control session ends, because there is no agreed durable state to keep it. This file records the intended direction so the module boundaries in architecture.md stay compatible with it, and so nobody mistakes the current announcements for synchronisation.

There is no fake "ready CRDT" here and no snapshots that are not actually verified.

The problem

The network may be unstable. A participant can come back after months. So:

no dependence on the author of a change being online;
no dependence on acknowledgements from every participant ever seen;
any available replica holding the signed data must be able to hand it to a returning participant without the original author present.

The model

Signed self-contained state per author, merged between replicas.

A record contains: the network, the author, the author's own retained version, the full current content, and a signature. A change log may speed delivery up, but recovery must never require the entire chain from the first event.

A network snapshot is a set of verifiable authored records plus the revocations needed to interpret them. It is not a SQLite dump, and not a single document trusted merely because the neighbour who forwarded it signed it.

Merge rules

A snapshot is merged into local state, never substituted for it wholesale.
An older version never rolls back a newer known one.
Absence from a snapshot does not mean deletion.
Duplicates do not change the result.
Two conflicting signed records at the same version from the same author need explicit handling; they are not resolved by luck.
Neither arrival order nor system clocks decide a winner.
Compaction must not drop what is needed to stop revoked records being resurrected.

Hostnames

A hostname is a mutable binding to a persistent author, not an identity. A rename must be a signed record that revokes the specific old binding and announces the new one, ideally atomically in one record.

Turning a computer off is not a revocation of its hostname and does not remove the participant. Revocations are not dropped merely because they are old, and no acknowledgement from offline peers is required to keep working.

Storage requirement this creates

When signed records land, writing the event and bumping the author's own counter must happen in one SQLite transaction, committed before the change is published to the network. SQLite gives atomic commit; use it instead of separate, inconsistent writes. state.sqlite already has a schema version and migrations for this.

Limits to state honestly

Data that every copy has lost is not recoverable from the secret.
A signature proves authorship, not global freshness: a replica can be behind, and you cannot tell from the signature alone.
An isolated new client can end up with incomplete state and has no way to know what it is missing.
Anyone who knows the secret can author records, so a majority of records is not evidence of anything.

Future tests

These are not implemented and must not be reported as passing:

snapshot merge against the rules above, including conflicting same-version records;
revocation propagation and resistance to resurrection after compaction;
long network partitions and rejoin after an extended absence;
hostname rename with atomic revoke-and-announce;
recovery of a returning participant from a replica that is not the author;
NAT traversal and hole punching between real hosts;
relay fallback behaviour against a self-hosted relay;
multi-process and multi-host deployment, as opposed to several library instances inside one test process.

3.9 KiB Raw Blame History