clanService/phonebox-global: decentralized phone network over yggdrasil

New service alongside phonebox. Boxes get a random 6 digit number (100000-999999) signed by the machine's yggdrasil key. A serf gossip cluster on yggdrasil port 7946 exchanges the signed records; phonebox-sync verifies key -> address derivation and the signature and writes the number -> address map to /run/phonebox/numbers for the asterisk dialplan. Any yggdrasil node running the service can reach any other; clan-core's ygg-input filter is opened for SIP, RTP and gossip. Includes a two-node VM test proving directory convergence and a call over yggdrasil. The existing phonebox service is untouched.
2026-09-18 02:10:05 +00:00
parent 0906700ad6
commit f398daacb5
32 changed files with 939 additions and 0 deletions
@@ -0,0 +1,45 @@
+A peer to peer phone relay network built on top of yggdrasil.
+
+Successor of the `phonebox` service with a global, decentralized number
+directory. Every box is reachable from any yggdrasil node running this
+service, not only from members of the same clan. A machine runs either
+`phonebox` or `phonebox-global`, not both (they share the asterisk setup).
+Regenerate vars with `clan vars generate --generator phonebox-global`.
+
+## Numbers
+
+Each box gets a random 6 digit number (100000-999999) when its vars are
+generated. The number is signed with the box's yggdrasil private key, so a
+number is cryptographically bound to the yggdrasil address it belongs to;
+nobody can claim a number for an address they do not own. Regenerate the
+`phonebox` vars to get a new number.
+
+Dialing from a phone plugged into the ATA:
+
+| dialed        | reaches                                    |
+| ------------- | ------------------------------------------ |
+| `NNNNNN`      | the phone on box `NNNNNN` (line `00`)      |
+| `NNNNNNXX`    | line `XX` on box `NNNNNN`                  |
+| `00`, `01`... | local lines on this box                    |
+| `888`         | fax of the current number directory        |
+| `000`         | fax echo test                              |
+| `999`         | hello world                                |
+
+Caller ID on the callee is the caller's box number followed by its line, so
+calling it back works.
+
+## Directory
+
+There is no central registry. Each box runs a serf agent on yggdrasil port
+7946 that gossips its signed number record (`number`, `key`, `sig`, `owner`
+tags) to every other box it knows about. On every membership change the
+`phonebox-sync` handler verifies all records and writes the resulting
+`number -> yggdrasil address` map to `/run/phonebox/numbers/`, which the
+asterisk dialplan reads at call time.
+
+Bootstrapping: boxes of the same clan join each other automatically. To
+connect to boxes outside the clan add one of their yggdrasil addresses to
+`extraPeers`; after the first successful join the agent remembers the whole
+membership in `/var/lib/phonebox/serf.snapshot` and rejoins on its own.
+
+`serf members -rpc-addr 127.0.0.1:7373` shows the live directory.