update spec

README.md

@@ -35,16 +35,19 @@ Each node receives heartbeats from different hosts, registering their state, nam
 
 Node can also provide DNS server front-end for ease integration into DNS resolvers such as unbound, dnsmasq or systemd-resolved.
 
+
 ## Exterior and Interior
 
 Exterior connections are made over low-trust medium, such as WAN internet, therefore encryption layer must protect from replay attacks and ensure unique packets.
 
 Interior connections are made over high-trust medium, like VPN tunnels, such as OpenVPN or Tailscale. Only interior connection can be used to sync state between nodes.
 
+
 ## Host
 
 Each host "heartbeats" it's state - such as WAN IP, uptime, resource usage. Host can heartbeat over exterior and interior connections, but information request can only be made through interior, and state must be synced only over interior, since, at moment of request or sync, the exterior uplink information, such as WAN IP, may not be availble, thus, interior connection must be always available and low-cost.
 
+
 ## State
 
 Host's state consists of:
@@ -55,6 +58,60 @@ Node's state is table of hosts' states + their last heartbeat time.
 Node state must also include generation ID, which must be guaranteed to be unique in scope of last 128 generations.
 A new generation should only happen when any of the hosts has new heartbeat.
 
+
+## Sync state broadcast
+
+When consensus met state must be synchronized across all nodes. In order to that happen, neighbor nodes must be discovered.
+
+
+The broadcast procedure is follow.
+1. List of neighbor list must be already established (through neighbor discovery)
+2. Sync packet formed including the list of nodes it's targeted to: all neighbor (excluding broadcasting node)
+3. Send sync packet over interior connections to all nodes
+4. In order for broadcast to not loop and be short, each node, on sync packet arrival, must
+- Merge it's neighbor list - that way neighbor discovery will also happen, update node neighbor list and/or add new nodes to broadcast
+- Remember generation ID of sync packet and ignore any other sync packets with same generation ID.
+
+
+This procedure will cause tolerable amount of packet storm, but it will also serve good purpose of re-sending packet if previous was dropped on network path
+
+
+## Host-to-node introduction
+
+All hosts must be pre-configured with node public key.
+
+
+When host is not introduced to a node
+- Host didn't configured host private key
+- Node does not have host public key
+
+
+The following procude must be done:
+1. Host forms "introduction" packet containing:
+- Host ID
+- Host name
+- Host public key
+2. Host encrypts this packet with node public key
+3. On success, node replies with greeting packet encrypted with host public key
+4. Host determines success by ability to decrypt with host private key and verifying "protocol magic byte sequence"
+
+After host introduction, host will be able to query and heartbeat to a node.
+
+
+## Node-to-node introduction
+
+The first node in network must configure it's node public and private key.
+Node public key will be shared to hosts by outside means of configuration.
+
+
+All nodes share same node key pair.
+
+
+Node introduction is consequence of state sync/broadcast. Node encrypts packet for another node using NODE PRIVATE KEY and sends it over Interior connection, while target node decrypts with public node key. That way, no host can node-sync to node.
+
+Node should never node-sync to a host, since host can decrypt sync packet using already pre-configured node public key. That's usually no issue when all nodes configured with proper ACLs and initial neighbor lists.
+
+
 ## Software architecture
 
 - Config are INI files.