wireguard: make PrivateKey and PublicKey two distinct types

Signed-off-by: Alejandro Mery <amery@jpi.io>

cmd/jpictl/env.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+
+	"git.jpi.io/amery/jpictl/pkg/zones"
+)
+
+// Command
+var envCmd = &cobra.Command{
+	Use:   "env",
+	Short: "generates environment variables for shell scripts",
+	RunE: func(_ *cobra.Command, _ []string) error {
+		m, err := zones.New(cfg.Base, cfg.Domain)
+		if err != nil {
+			return err
+		}
+
+		return m.WriteEnv(os.Stdout)
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(envCmd)
+}

go.mod

@@ -3,16 +3,17 @@ module git.jpi.io/amery/jpictl
 go 1.19
 
 require (
+	darvaza.org/core v0.9.5
 	darvaza.org/resolver v0.5.2
 	darvaza.org/sidecar v0.0.0-20230721122716-b9c54b8adbaf
 	darvaza.org/slog v0.5.2
 	github.com/burntSushi/toml v0.3.1
 	github.com/mgechev/revive v1.3.2
 	github.com/spf13/cobra v1.7.0
+	gopkg.in/gcfg.v1 v1.2.3
 )
 
 require (
-	darvaza.org/core v0.9.5 // indirect
 	darvaza.org/slog/handlers/filter v0.4.4 // indirect
 	darvaza.org/slog/handlers/zerolog v0.4.4 // indirect
 	github.com/BurntSushi/toml v1.3.2 // indirect
@@ -36,4 +37,5 @@ require (
 	golang.org/x/sys v0.11.0 // indirect
 	golang.org/x/text v0.12.0 // indirect
 	golang.org/x/tools v0.12.0 // indirect
+	gopkg.in/warnings.v0 v0.1.2 // indirect
 )

go.sum

@@ -87,6 +87,10 @@ golang.org/x/text v0.12.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/tools v0.12.0 h1:YW6HUoUmYBpwSgyaGaZq1fHjrBjX1rlpZ54T6mu2kss=
 golang.org/x/tools v0.12.0/go.mod h1:Sc0INKfu04TlqNoRA1hgpFZbhYXHPr4V5DzpSBTPqQM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/gcfg.v1 v1.2.3 h1:m8OOJ4ccYHnx2f4gQwpno8nAX5OGOh7RLaaz0pj3Ogs=
+gopkg.in/gcfg.v1 v1.2.3/go.mod h1:yesOnuUOFQAhST5vPY4nbZsb/huCgGGXlipJsBn0b3o=
+gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
+gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

pkg/wireguard/config.go

@@ -0,0 +1,219 @@
+package wireguard
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/netip"
+	"strconv"
+	"strings"
+
+	"darvaza.org/core"
+	"gopkg.in/gcfg.v1"
+)
+
+// Config represents a wgN.conf file
+type Config struct {
+	Interface InterfaceConfig
+	Peer      []PeerConfig
+}
+
+// GetAddress is a shortcut to the interface's address
+func (f *Config) GetAddress() netip.Addr {
+	return f.Interface.Address
+}
+
+// Peers tells how many peers are described
+func (f *Config) Peers() int {
+	return len(f.Peer)
+}
+
+// InterfaceConfig represents the [Interface] section
+type InterfaceConfig struct {
+	Address    netip.Addr
+	PrivateKey PrivateKey
+	ListenPort uint16
+}
+
+// PeerConfig represents a [Peer] section
+type PeerConfig struct {
+	PublicKey  PublicKey
+	Endpoint   EndpointAddress
+	AllowedIPs []netip.Prefix
+}
+
+// EndpointAddress is a host:port pair to reach the Peer
+type EndpointAddress struct {
+	Host string
+	Port uint16
+}
+
+// Name returns the first part of a hostname
+func (ep EndpointAddress) Name() string {
+	before, _, _ := strings.Cut(ep.Host, ".")
+	return before
+}
+
+func (ep EndpointAddress) String() string {
+	switch {
+	case ep.Host == "":
+		return ""
+	case ep.Port == 0:
+		return ep.Host
+	case !strings.ContainsRune(ep.Host, ':'):
+		return fmt.Sprintf("%s:%v", ep.Host, ep.Port)
+	default:
+		return fmt.Sprintf("[%s]:%v", ep.Host, ep.Port)
+	}
+}
+
+// FromString sets the EndpointAddress from a given "[host]:port"
+func (ep *EndpointAddress) FromString(s string) error {
+	host, port, err := core.SplitHostPort(s)
+	if err != nil {
+		return err
+	}
+
+	ep.Host = host
+
+	switch {
+	case port != "":
+		n, _ := strconv.ParseUint(port, 10, 16)
+		ep.Port = uint16(n)
+	default:
+		ep.Port = 0
+	}
+
+	return nil
+}
+
+type intermediateConfig struct {
+	Interface interfaceConfig
+	Peer      peersConfig
+}
+
+func (v *intermediateConfig) Export() (*Config, error) {
+	var out Config
+	var err error
+
+	// Interface
+	out.Interface, err = v.Interface.Export()
+	if err != nil {
+		return nil, err
+	}
+
+	// Peers
+	peers, ok := v.PeersCount()
+	if !ok {
+		return nil, errors.New("inconsistent Peer data")
+	}
+
+	for i := 0; i < peers; i++ {
+		p, err := v.ExportPeer(i)
+		if err != nil {
+			err = core.Wrapf(err, "Peer[%v]:", i)
+			return nil, err
+		}
+
+		out.Peer = append(out.Peer, p)
+	}
+
+	return &out, nil
+}
+
+type interfaceConfig struct {
+	Address    netip.Addr
+	PrivateKey string
+	ListenPort uint16
+}
+
+func (p interfaceConfig) Export() (InterfaceConfig, error) {
+	var err error
+
+	out := InterfaceConfig{
+		Address:    p.Address,
+		ListenPort: p.ListenPort,
+	}
+
+	out.PrivateKey, err = PrivateKeyFromBase64(p.PrivateKey)
+	if err != nil {
+		err = core.Wrap(err, "PrivateKey")
+		return InterfaceConfig{}, err
+	}
+
+	return out, nil
+}
+
+type peersConfig struct {
+	PublicKey  []string
+	Endpoint   []string
+	AllowedIPs []string
+}
+
+func (v *intermediateConfig) ExportPeer(i int) (PeerConfig, error) {
+	var out PeerConfig
+
+	// Endpoint
+	s := v.Peer.Endpoint[i]
+	err := out.Endpoint.FromString(s)
+	if err != nil {
+		err = core.Wrap(err, "Endpoint")
+		return out, err
+	}
+
+	// PublicKey
+	out.PublicKey, err = PublicKeyFromBase64(v.Peer.PublicKey[i])
+	if err != nil {
+		err = core.Wrap(err, "PublicKey")
+		return out, err
+	}
+
+	// AllowedIPs
+	s = v.Peer.AllowedIPs[i]
+	out.AllowedIPs, err = parseAllowedIPs(s)
+	if err != nil {
+		err = core.Wrap(err, "AllowedIPs")
+		return out, err
+	}
+
+	return out, nil
+}
+
+func parseAllowedIPs(data string) ([]netip.Prefix, error) {
+	var out []netip.Prefix
+
+	for _, s := range strings.Split(data, ",") {
+		s = strings.TrimSpace(s)
+		p, err := netip.ParsePrefix(s)
+		if err != nil {
+			return out, err
+		}
+
+		out = append(out, p)
+	}
+
+	return out, nil
+}
+
+func (v *intermediateConfig) PeersCount() (int, bool) {
+	c0 := len(v.Peer.Endpoint)
+	c1 := len(v.Peer.PublicKey)
+	c2 := len(v.Peer.AllowedIPs)
+
+	if c0 != c1 || c1 != c2 {
+		return 0, false
+	}
+
+	return c0, true
+}
+
+// NewConfigFromReader parses a wgN.conf file
+func NewConfigFromReader(r io.Reader) (*Config, error) {
+	temp := &intermediateConfig{}
+
+	if err := gcfg.ReadInto(temp, r); err != nil {
+		return nil, err
+	}
+
+	return temp.Export()
+}

pkg/wireguard/keys.go

@@ -0,0 +1,96 @@
+package wireguard
+
+import (
+	"bytes"
+	"encoding/base64"
+	"errors"
+)
+
+const (
+	// PrivateKeySize is the length in bytes of a Wireguard Private Key
+	PrivateKeySize = 32
+	// PublicKeySize is the length in bytes of a Wireguard Public Key
+	PublicKeySize = 32
+)
+
+var (
+	// ErrInvalidKeySize indicates the key size is wrong
+	ErrInvalidKeySize = errors.New("invalid key size")
+)
+
+type (
+	// PrivateKey is a binary Wireguard Private Key
+	PrivateKey []byte
+	// PublicKey is a binary Wireguard Public Key
+	PublicKey []byte
+)
+
+func (key PrivateKey) String() string {
+	return encodeKey(key)
+}
+
+func (pub PublicKey) String() string {
+	return encodeKey(pub)
+}
+
+// IsZero tells if the key hasn't been set
+func (key PrivateKey) IsZero() bool {
+	return len(key) == 0
+}
+
+// IsZero tells if the key hasn't been set
+func (pub PublicKey) IsZero() bool {
+	return len(pub) == 0
+}
+
+// Equal checks if two private keys are identical
+func (key PrivateKey) Equal(alter PrivateKey) bool {
+	return bytes.Equal(key, alter)
+}
+
+// Equal checks if two public keys are identical
+func (pub PublicKey) Equal(alter PublicKey) bool {
+	return bytes.Equal(pub, alter)
+}
+
+// PrivateKeyFromBase64 decodes a base64-based string into
+// a [PrivateKey]
+func PrivateKeyFromBase64(data string) (PrivateKey, error) {
+	b, err := decodeKey(data, PrivateKeySize)
+	return b, err
+}
+
+// PublicKeyFromBase64 decodes a base64-based string into
+// a [PublicKey]
+func PublicKeyFromBase64(data string) (PublicKey, error) {
+	b, err := decodeKey(data, PublicKeySize)
+	return b, err
+}
+
+func encodeKey(b []byte) string {
+	switch {
+	case len(b) == 0:
+		return ""
+	default:
+		return base64.StdEncoding.EncodeToString(b)
+	}
+}
+
+func decodeKey(data string, size int) ([]byte, error) {
+	b, err := base64.StdEncoding.DecodeString(data)
+	switch {
+	case err != nil:
+		return []byte{}, err
+	case len(b) != size:
+		err = ErrInvalidKeySize
+		return []byte{}, err
+	default:
+		return b, nil
+	}
+}
+
+// KeyPair holds a Key pair
+type KeyPair struct {
+	PrivateKey PrivateKey
+	PublicKey  PublicKey
+}

pkg/wireguard/wireguard.go

@@ -0,0 +1,2 @@
+// Package wireguard deals with wireguard config
+package wireguard

pkg/zones/env.go

@@ -0,0 +1,104 @@
+package zones
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// WriteEnv generates environment variables for shell scripts
+func (m *Zones) WriteEnv(w io.Writer) error {
+	var buf bytes.Buffer
+
+	m.writeEnvVarFn(&buf, genEnvZones, "ZONES")
+	m.ForEachZone(func(z *Zone) bool {
+		m.writeEnvZone(&buf, z)
+		return false
+	})
+
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+func (m *Zones) writeEnvZone(w io.Writer, z *Zone) {
+	zoneID := z.ID
+
+	// ZONE{zoneID}
+	m.writeEnvVar(w, genEnvZoneNodes(z), "ZONE%v", zoneID)
+
+	// ZONE{zoneID}_NAME
+	m.writeEnvVar(w, z.Name, "ZONE%v_%s", zoneID, "NAME")
+
+	// ZONE{zoneID}_GW
+	gatewayID := getRingZeroGatewayID(z)
+	m.writeEnvVar(w, fmt.Sprintf("%v", gatewayID), "ZONE%v_%s", zoneID, "GW")
+
+	// ZONE{zoneID}_IP
+	ip, _ := RingZeroAddress(zoneID, gatewayID)
+	m.writeEnvVar(w, ip.String(), "ZONE%v_%s", zoneID, "IP")
+}
+
+func (m *Zones) writeEnvVarFn(w io.Writer, fn func(*Zones) string, name string, args ...any) {
+	var value string
+
+	if fn != nil {
+		value = fn(m)
+	}
+
+	m.writeEnvVar(w, value, name, args...)
+}
+
+func (*Zones) writeEnvVar(w io.Writer, value string, name string, args ...any) {
+	if len(args) > 0 {
+		name = fmt.Sprintf(name, args...)
+	}
+
+	if name != "" {
+		value = strings.TrimSpace(value)
+
+		_, _ = fmt.Fprintf(w, "%s=%q\n", name, value)
+	}
+}
+
+func genEnvZones(m *Zones) string {
+	s := make([]string, 0, len(m.Zones))
+	for _, z := range m.Zones {
+		s = append(s, fmt.Sprintf("%v", z.ID))
+	}
+
+	return strings.Join(s, " ")
+}
+
+func genEnvZoneNodes(z *Zone) string {
+	s := make([]string, 0, len(z.Machines))
+	for _, p := range z.Machines {
+		s = append(s, p.Name)
+	}
+	return strings.Join(s, " ")
+}
+
+func getRingZeroGatewayID(z *Zone) int {
+	var firstNodeID, gatewayID int
+
+	z.ForEachMachine(func(p *Machine) bool {
+		nodeID := p.ID()
+
+		if firstNodeID == 0 {
+			firstNodeID = nodeID
+		}
+
+		if _, found := p.getRingInfo(0); found {
+			gatewayID = nodeID
+		}
+
+		return gatewayID != 0
+	})
+
+	switch {
+	case gatewayID == 0:
+		return firstNodeID
+	default:
+		return gatewayID
+	}
+}

pkg/zones/machine.go

@@ -1,7 +1,10 @@
 package zones
 
 import (
+	"fmt"
+	"io/fs"
 	"net/netip"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"sync"
@@ -13,9 +16,10 @@ type Machine struct {
 
 	zone *Zone
 	id   int
-	Name string
+	Name string `toml:"name"`
 
-	PublicAddresses []netip.Addr
+	PublicAddresses []netip.Addr `toml:"public,omitempty"`
+	RingAddresses   []*RingInfo  `toml:"rings,omitempty"`
 }
 
 func (m *Machine) String() string {
@@ -56,3 +60,29 @@ func (m *Machine) FullName() string {
 
 	return m.Name
 }
+
+// ReadFile reads a file from the machine's config directory
+func (m *Machine) ReadFile(name string, args ...any) ([]byte, error) {
+	base := m.zone.zones.dir
+	fullName := m.getFilename(name, args...)
+
+	return fs.ReadFile(base, fullName)
+}
+
+func (m *Machine) getFilename(name string, args ...any) string {
+	if len(args) > 0 {
+		name = fmt.Sprintf(name, args...)
+	}
+
+	s := []string{
+		m.zone.Name,
+		m.Name,
+		name,
+	}
+
+	return filepath.Join(s...)
+}
+
+func (m *Machine) getPeerByName(name string) (*Machine, bool) {
+	return m.zone.zones.GetMachineByName(name)
+}

pkg/zones/machine_rings.go

@@ -0,0 +1,136 @@
+package zones
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+
+	"darvaza.org/core"
+
+	"git.jpi.io/amery/jpictl/pkg/wireguard"
+)
+
+// GetWireguardConfig reads a wgN.conf file
+func (m *Machine) GetWireguardConfig(ring int) (*wireguard.Config, error) {
+	data, err := m.ReadFile("wg%v.conf", ring)
+	if err != nil {
+		return nil, err
+	}
+
+	r := bytes.NewReader(data)
+	return wireguard.NewConfigFromReader(r)
+}
+
+func (m *Machine) tryApplyWireguardConfig(ring int) error {
+	wg, err := m.GetWireguardConfig(ring)
+	switch {
+	case os.IsNotExist(err):
+		return nil
+	case err != nil:
+		return err
+	default:
+		return m.applyWireguardConfig(ring, wg)
+	}
+}
+
+func (m *Machine) applyWireguardConfig(ring int, wg *wireguard.Config) error {
+	addr := wg.GetAddress()
+	zoneID, nodeID, ok := Rings[ring].Decode(addr)
+	if !ok {
+		return fmt.Errorf("%s: invalid wg%v address: %s", m.Name, ring, addr)
+	}
+
+	if err := m.applyZoneNodeID(zoneID, nodeID); err != nil {
+		err = core.Wrapf(err, "%s: wg%v:%s", m.Name, ring, addr)
+		return err
+	}
+
+	if err := m.applyWireguardInterfaceConfig(ring, wg.Interface); err != nil {
+		err = core.Wrapf(err, "%s: wg%v:%s", m.Name, ring, addr)
+		return err
+	}
+
+	for _, peer := range wg.Peer {
+		if err := m.applyWireguardPeerConfig(ring, peer); err != nil {
+			err = core.Wrapf(err, "%s: wg%v:%s", m.Name, ring, addr)
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (m *Machine) getRingInfo(ring int) (*RingInfo, bool) {
+	for _, ri := range m.RingAddresses {
+		if ri.Ring == ring {
+			return ri, true
+		}
+	}
+
+	return nil, false
+}
+
+func (m *Machine) applyRingInfo(ring int, new *RingInfo) error {
+	cur, found := m.getRingInfo(ring)
+	if !found {
+		// first, append
+		m.RingAddresses = append(m.RingAddresses, new)
+		return nil
+	}
+
+	// extra, merge
+	return cur.Merge(new)
+}
+
+func (m *Machine) applyWireguardInterfaceConfig(ring int, data wireguard.InterfaceConfig) error {
+	ri := &RingInfo{
+		Ring:    ring,
+		Enabled: true,
+		Address: data.Address,
+		Keys: &wireguard.KeyPair{
+			PrivateKey: data.PrivateKey,
+		},
+	}
+
+	return m.applyRingInfo(ring, ri)
+}
+
+func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) error {
+	peer, found := m.getPeerByName(pc.Endpoint.Name())
+	switch {
+	case !found:
+		// unknown
+	case ring == 1 && m.zone != peer.zone:
+		// invalid zone
+	default:
+		// apply RingInfo
+		ri := &RingInfo{
+			Ring:    ring,
+			Enabled: true,
+			Keys: &wireguard.KeyPair{
+				PublicKey: pc.PublicKey,
+			},
+		}
+
+		return peer.applyRingInfo(ring, ri)
+	}
+
+	return fmt.Errorf("%q: invalid peer endpoint", pc.Endpoint.Host)
+}
+
+func (m *Machine) applyZoneNodeID(zoneID, nodeID int) error {
+	switch {
+	case zoneID == 0:
+		return fmt.Errorf("invalid %s", "zoneID")
+	case nodeID == 0:
+		return fmt.Errorf("invalid %s", "nodeID")
+	case m.ID() != nodeID:
+		return fmt.Errorf("invalid %s: %v ≠ %v", "zoneID", m.ID(), nodeID)
+	case m.zone.ID != 0 && m.zone.ID != zoneID:
+		return fmt.Errorf("invalid %s: %v ≠ %v", "zoneID", m.zone.ID, zoneID)
+	case m.zone.ID == 0:
+		m.zone.ID = zoneID
+	}
+
+	return nil
+}

pkg/zones/machine_scan.go

@@ -24,3 +24,13 @@ func (m *Machine) updatePublicAddresses() error {
 	m.PublicAddresses = addrs
 	return nil
 }
+
+func (m *Machine) scan() error {
+	for i := 0; i < RingsCount; i++ {
+		if err := m.tryApplyWireguardConfig(i); err != nil {
+			return err
+		}
+	}
+
+	return m.updatePublicAddresses()
+}

pkg/zones/rings.go

@@ -0,0 +1,195 @@
+package zones
+
+import (
+	"fmt"
+	"net/netip"
+
+	"git.jpi.io/amery/jpictl/pkg/wireguard"
+)
+
+const (
+	// MaxZoneID indicates the highest ID allowed for a Zone
+	MaxZoneID = 0xf
+	// MaxNodeID indicates the highest Machine ID allowed within a Zone
+	MaxNodeID = 0xff - 1
+	// RingsCount indicates how many wireguard rings we have
+	RingsCount = 2
+)
+
+// RingInfo contains represents the Wireguard endpoint details
+// for a Machine on a particular ring
+type RingInfo struct {
+	Ring    int                `toml:"ring"`
+	Enabled bool               `toml:"enabled,omitempty"`
+	Keys    *wireguard.KeyPair `toml:"keys,omitempty"`
+	Address netip.Addr         `toml:"address,omitempty"`
+}
+
+// Merge attempts to combine two RingInfo structs
+func (ri *RingInfo) Merge(alter *RingInfo) error {
+	switch {
+	case ri.Ring != alter.Ring:
+		// different ring
+		return fmt.Errorf("invalid %s: %v ≠ %v", "ring", ri.Ring, alter.Ring)
+	case ri.Enabled != alter.Enabled:
+		// different state
+		return fmt.Errorf("invalid %s: %v ≠ %v", "enabled", ri.Enabled, alter.Enabled)
+	case !canMergeAddress(ri.Address, alter.Address):
+		// different address
+		return fmt.Errorf("invalid %s: %v ≠ %v", "address", ri.Address, alter.Address)
+	case !canMergeKeyPairs(ri.Keys, alter.Keys):
+		// incompatible keypairs
+		return fmt.Errorf("invalid %s: %s ≠ %s", "keys", ri.Keys, alter.Keys)
+	}
+
+	switch {
+	case ri.Keys == nil:
+		// assign keypair
+		ri.Keys = alter.Keys
+	case alter.Keys != nil:
+		// fill the gaps on our keypair
+		if ri.Keys.PrivateKey.IsZero() {
+			ri.Keys.PrivateKey = alter.Keys.PrivateKey
+		}
+		if ri.Keys.PublicKey.IsZero() {
+			ri.Keys.PublicKey = alter.Keys.PublicKey
+		}
+	}
+
+	if addressEqual(ri.Address, netip.Addr{}) {
+		// assign address
+		ri.Address = alter.Address
+	}
+
+	return nil
+}
+
+func canMergeAddress(ip1, ip2 netip.Addr) bool {
+	var zero netip.Addr
+
+	switch {
+	case addressEqual(ip1, zero) || addressEqual(ip2, zero) || addressEqual(ip1, ip2):
+		return true
+	default:
+		return false
+	}
+}
+
+func addressEqual(ip1, ip2 netip.Addr) bool {
+	return ip1.Compare(ip2) == 0
+}
+
+func canMergeKeyPairs(p1, p2 *wireguard.KeyPair) bool {
+	switch {
+	case p1 == nil || p2 == nil:
+		return true
+	case !p1.PrivateKey.IsZero() && !p2.PrivateKey.IsZero() && !p1.PrivateKey.Equal(p2.PrivateKey):
+		return false
+	case !p1.PublicKey.IsZero() && !p2.PublicKey.IsZero() && !p1.PublicKey.Equal(p2.PublicKey):
+		return false
+	default:
+		return true
+	}
+}
+
+// RingAddressEncoder provides encoder/decoder access for a particular
+// Wireguard ring
+type RingAddressEncoder struct {
+	ID     int
+	Encode func(zoneID, nodeID int) (netip.Addr, bool)
+	Decode func(addr netip.Addr) (zoneID, nodeID int, ok bool)
+}
+
+var (
+	// RingZero is a wg0 address encoder/decoder
+	RingZero = RingAddressEncoder{
+		ID:     0,
+		Decode: ParseRingZeroAddress,
+		Encode: RingZeroAddress,
+	}
+	// RingOne is a wg1 address encoder/decoder
+	RingOne = RingAddressEncoder{
+		ID:     1,
+		Decode: ParseRingOneAddress,
+		Encode: RingOneAddress,
+	}
+	// Rings provides indexed access to the ring address encoders
+	Rings = [RingsCount]RingAddressEncoder{
+		RingZero,
+		RingOne,
+	}
+)
+
+// ValidZoneID checks if the given zoneID is a valid 4 bit zone number.
+//
+// 0 is reserved, and only allowed when composing CIDRs.
+func ValidZoneID(zoneID int) bool {
+	switch {
+	case zoneID < 0 || zoneID > MaxZoneID:
+		return false
+	default:
+		return true
+	}
+}
+
+// ValidNodeID checks if the given nodeID is a valid 8 bit number.
+// nodeID is unique within a Zone.
+// 0 is reserved, and only allowed when composing CIDRs.
+func ValidNodeID(nodeID int) bool {
+	switch {
+	case nodeID < 0 || nodeID > MaxNodeID:
+		return false
+	default:
+		return true
+	}
+}
+
+// ParseRingZeroAddress extracts zone and node ID from a wg0 [netip.Addr]
+// wg0 addresses are of the form `10.0.{{zoneID}}.{{nodeID}}`
+func ParseRingZeroAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
+	if addr.IsValid() {
+		a4 := addr.As4()
+
+		if a4[0] == 10 && a4[1] == 0 {
+			return int(a4[2]), int(a4[3]), true
+		}
+	}
+	return 0, 0, false
+}
+
+// RingZeroAddress returns a wg0 IP address
+func RingZeroAddress(zoneID, nodeID int) (netip.Addr, bool) {
+	switch {
+	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
+		return netip.Addr{}, false
+	default:
+		a4 := [4]uint8{10, 0, uint8(zoneID), uint8(nodeID)}
+		return netip.AddrFrom4(a4), true
+	}
+}
+
+// ParseRingOneAddress extracts zone and node ID from a wg1 [netip.Addr]
+// wg1 addresses are of the form `10.{{zoneID << 4}}.{{nodeID}}`
+func ParseRingOneAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
+	if addr.IsValid() {
+		a4 := addr.As4()
+
+		if a4[0] == 10 && a4[2] == 0 {
+			zoneID = int(a4[1] >> 4)
+			nodeID = int(a4[3])
+			return zoneID, nodeID, true
+		}
+	}
+	return 0, 0, false
+}
+
+// RingOneAddress returns a wg1 IP address
+func RingOneAddress(zoneID, nodeID int) (netip.Addr, bool) {
+	switch {
+	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
+		return netip.Addr{}, false
+	default:
+		a4 := [4]uint8{10, 0, uint8(zoneID << 4), uint8(nodeID)}
+		return netip.AddrFrom4(a4), true
+	}
+}

pkg/zones/scan.go

@@ -2,9 +2,25 @@ package zones
 
 import (
 	"io/fs"
+	"sort"
 )
 
 func (m *Zones) scan() error {
+	for _, fn := range []func() error{
+		m.scanDirectory,
+		m.scanMachines,
+		m.scanZoneIDs,
+		m.scanSort,
+	} {
+		if err := fn(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (m *Zones) scanDirectory() error {
 	// each directory is a zone
 	entries, err := fs.ReadDir(m.dir, ".")
 	if err != nil {
@@ -29,6 +45,76 @@ func (m *Zones) scan() error {
 	return nil
 }
 
+func (m *Zones) scanMachines() error {
+	var err error
+	m.ForEachMachine(func(p *Machine) bool {
+		err = p.scan()
+		return err != nil
+	})
+	return err
+}
+
+func (m *Zones) scanZoneIDs() error {
+	var hasMissing bool
+	var lastZoneID int
+
+	m.ForEachZone(func(z *Zone) bool {
+		switch {
+		case z.ID == 0:
+			hasMissing = true
+		case z.ID > lastZoneID:
+			lastZoneID = z.ID
+		}
+
+		return false
+	})
+
+	if hasMissing {
+		next := lastZoneID + 1
+
+		m.ForEachZone(func(z *Zone) bool {
+			if z.ID == 0 {
+				z.ID, next = next, next+1
+			}
+
+			return false
+		})
+	}
+
+	return nil
+}
+
+func (m *Zones) scanSort() error {
+	sort.SliceStable(m.Zones, func(i, j int) bool {
+		id1 := m.Zones[i].ID
+		id2 := m.Zones[j].ID
+		return id1 < id2
+	})
+
+	m.ForEachZone(func(z *Zone) bool {
+		sort.SliceStable(z.Machines, func(i, j int) bool {
+			id1 := z.Machines[i].ID()
+			id2 := z.Machines[j].ID()
+			return id1 < id2
+		})
+
+		return false
+	})
+
+	m.ForEachMachine(func(p *Machine) bool {
+		sort.SliceStable(p.RingAddresses, func(i, j int) bool {
+			ri1 := p.RingAddresses[i]
+			ri2 := p.RingAddresses[j]
+
+			return ri1.Ring < ri2.Ring
+		})
+
+		return false
+	})
+
+	return nil
+}
+
 func (z *Zone) scan() error {
 	// each directory is a machine
 	entries, err := fs.ReadDir(z.zones.dir, z.Name)
@@ -43,10 +129,6 @@ func (z *Zone) scan() error {
 				Name: e.Name(),
 			}
 
-			if err := m.updatePublicAddresses(); err != nil {
-				return err
-			}
-
 			z.Machines = append(z.Machines, m)
 		}
 	}

pkg/zones/zones.go

@@ -22,6 +22,16 @@ func (z *Zone) String() string {
 	return z.Name
 }
 
+// ForEachMachine calls a function for each Machine in the zone
+// until instructed to terminate the loop
+func (z *Zone) ForEachMachine(fn func(*Machine) bool) {
+	for _, p := range z.Machines {
+		if fn(p) {
+			return
+		}
+	}
+}
+
 // Zones represents all zones in a cluster
 type Zones struct {
 	dir      fs.FS
@@ -31,11 +41,57 @@ type Zones struct {
 	Zones []*Zone `toml:"zones"`
 }
 
+// ForEachMachine calls a function for each Machine in the cluster
+// until instructed to terminate the loop
+func (m *Zones) ForEachMachine(fn func(*Machine) bool) {
+	m.ForEachZone(func(z *Zone) bool {
+		var term bool
+
+		z.ForEachMachine(func(p *Machine) bool {
+			term = fn(p)
+			return term
+		})
+
+		return term
+	})
+}
+
+// ForEachZone calls a function for each Zone in the cluster
+// until instructed to terminate the loop
+func (m *Zones) ForEachZone(fn func(*Zone) bool) {
+	for _, p := range m.Zones {
+		if fn(p) {
+			// terminate
+			return
+		}
+	}
+}
+
+// GetMachineByName looks for a machine with the specified
+// name on any zone
+func (m *Zones) GetMachineByName(name string) (*Machine, bool) {
+	var out *Machine
+
+	if name != "" {
+		m.ForEachMachine(func(p *Machine) bool {
+			if p.Name == name {
+				out = p
+			}
+
+			return out != nil
+		})
+	}
+
+	return out, out != nil
+}
+
 // NewFS builds a [Zones] tree using the given directory
 func NewFS(dir fs.FS, domain string) (*Zones, error) {
+	lockuper := resolver.NewCloudflareLookuper()
+
 	z := &Zones{
 		dir:      dir,
-		resolver: resolver.SystemResolver(true),
+		resolver: resolver.NewResolver(lockuper),
 		domain:   domain,
 	}