Node Discovery

Draft specification

Maturity: Draft — not yet validated by a reference implementation. Subject to change during Runtime development.

See Protocol Specifications for reading order and the full specification index.

Abstract

This specification defines the Faberio Node Discovery service — the mechanism by which runtimes locate and connect to other nodes within a trusted information space.

Node discovery enables participating runtimes to find peers, exchange connectivity information, and establish communication without centralized infrastructure. Discovery operates within the boundaries of trust relationships that define each information space.

An information space may comprise participants' personal devices — smartphones, tablets, laptops, and personal computers — always-on servers run by users or independent operators, or both.

Nodes MUST obtain administrator approval before participating in node-level background replication within an information space. Until approved, a node MAY connect for discovery and enrollment but MUST NOT synchronize shared data.

---

1. Scope

This specification defines:

• information space membership and administrator approval
• discovery records and their format
• discovery mechanisms
• peer registry management
• discovery within information spaces
• export, backup, node migration, and information space relocation or fork
• security requirements for discovery

This specification does not define:

• node identity and authentication (see Identity Model)
• object identifiers (see Object Identifier)
• application discovery
• transport protocol implementation (see Node Connectivity)
• administrator user interface and workflow tooling

---

2. Motivation

Distributed applications require nodes to communicate across independently operated infrastructure. Without discovery, every node would need manually configured addresses for all peers — an approach that does not scale and breaks when nodes move, restart, or join networks dynamically.

Faberio solves this with a decentralized discovery service built into the Runtime. Nodes share signed discovery records within trusted information spaces, allowing peers to find each other without a central registry.

Discovery is scoped to information spaces — groups of runtimes that trust one another. A node may participate in multiple information spaces simultaneously, maintaining independent peer registries for each.

---

3. Concepts

3.1 Information Space

An information space is a trust boundary formed by runtimes that have established mutual trust. Discovery operates exclusively within an information space. Nodes in different information spaces do not exchange discovery records unless trust is explicitly established between them.

Each information space is stored as a database object with a UUIDv7 identifier and a human-readable name.

3.2 Information Space Object

An information space is represented by the following database object:

Field	Description
id	UUIDv7 object identifier
display_name	Human-readable name of the information space

The id is used as information_space_id in discovery records, peer registries, and access control policies. The display_name is used for presentation in user interfaces and management tools.

Information space records are created when a new trust boundary is established. Participating nodes reference the information space by its UUIDv7 id.

A node is not limited to a single information space. The relationship between nodes and information spaces is many-to-many — one node may belong to multiple spaces, and one space may contain multiple nodes.

3.3 Information Space Membership

Node participation in an information space is represented by a membership database object:

Field	Description
id	UUIDv7 object identifier
node_id	UUIDv7 of the participating node record
information_space_id	UUIDv7 of the information space record
status	pending, approved, or rejected
requested_at	Time membership was requested (Unix milliseconds)
approved_by	UUIDv7 of the approving administrator user (nullable)
approved_at	Time of approval (Unix milliseconds, nullable)

Each membership record links one node to one information space. A node that participates in three information spaces has three membership records.

When a node requests to join an information space, a membership record is created with status: pending. When a node leaves, the membership record is removed. Membership does not affect the node's UUIDv7 record or cryptographic identity — only its participation in a specific trust boundary.

Membership records are stored within the information space and replicate across approved nodes through node-level background synchronization.

Status	Discovery	Node-level replication
pending	MAY connect to bootstrap peers, exchange discovery records	MUST NOT synchronize shared data
approved	Full participation	Full node-level background replication
rejected	MUST NOT participate	MUST NOT participate

The first node that creates an information space MUST receive status: approved automatically — otherwise no administrator would exist to approve subsequent nodes.

3.4 Administrator Approval

Administrator is not a platform-level role. Applications define which users MAY approve node membership requests by granting them write access to node membership records within the information space (see Data Access Control).

Approval workflow:

1. a node operator configures a bootstrap peer and requests join to an information space
2. a membership record is created with status: pending
3. an administrator reviews pending node memberships
4. the administrator updates status to approved and sets approved_by, approved_at
5. the approval replicates to all participating nodes
6. the node begins node-level background replication

Implementations MUST NOT allow node-level background replication with peers whose membership is pending or rejected.

Pending nodes MAY appear in peer registries through discovery exchange so administrators can identify them. Receiving nodes MUST NOT initiate node-level replication with pending peers.

3.5 Discovery Record

A discovery record is a signed data structure that advertises a node's identity and connectivity information within a specific information space. Nodes exchange discovery records to inform peers of their presence and capabilities. A node participating in multiple spaces publishes one discovery record per space.

3.6 Peer Registry

Each node maintains a peer registry for each information space it participates in. The peer registry stores discovery records of known peers and is updated as new peers are discovered or existing peers go offline.

---

4. Discovery Record

4.1 Format

A discovery record MUST contain the following fields:

Field	Type	Description
node_id	string	Cryptographic Node ID (see Identity Model)
display_name	string	Human-readable name of the node
public_key	bytes	Ed25519 public key
endpoints	array	Transport addresses at which the node accepts connections
capabilities	array	Platform services offered by the node
information_space_id	UUIDv7	Identifier of the information space object
issued_at	timestamp	Time the record was created (Unix milliseconds)
expires_at	timestamp	Time after which the record SHOULD be considered stale
signature	bytes	Ed25519 signature over the record payload

A discovery record is always scoped to a single information space. A node that participates in multiple information spaces MUST publish a separate discovery record for each space, each with the corresponding information_space_id. The records share the same node_id, display_name, and public_key, but are independently signed and exchanged within their respective spaces.

4.2 Endpoints

Each endpoint entry MUST contain:

Field	Type	Description
transport	string	Transport protocol (e.g. tcp, quic, websocket)
address	string	Host address
port	integer	Port number

A node MAY advertise multiple endpoints to support different transport protocols or network interfaces.

4.3 Capabilities

The capabilities field advertises which platform services the node provides. Standard capability values include:

• messaging
• rpc
• replication
• storage
• discovery

Implementations MAY define additional capability values. Peers use capabilities to determine which services are available on a node.

4.4 Record Signing

Discovery records MUST be signed by the node's private key.

The signature MUST cover all fields except signature itself, serialized in a canonical format.

Receiving nodes MUST verify the signature using the public_key field before accepting a discovery record. Records with invalid signatures MUST be rejected.

4.5 Record Expiration

Discovery records MUST include issued_at and expires_at timestamps.

Implementations SHOULD use a default expiration period of 24 hours. Nodes MUST refresh their discovery records before expiration by issuing updated records with a new issued_at and expires_at.

Expired records MUST be removed from the peer registry.

---

5. Discovery Mechanisms

Faberio supports three discovery mechanisms. Implementations MUST support configured peers and peer exchange. Local network discovery is optional.

5.1 Configured Peers

A node MAY be configured with a list of known peer endpoints — bootstrap nodes — used to request join to an information space.

On startup, the node:

1. connects to configured peers and performs mutual authentication
2. creates a membership record with status: pending (unless auto-approved as space creator)
3. exchanges discovery records
4. waits for administrator approval before node-level replication begins

Configured peers provide a reliable entry point when no other discovery mechanism has populated the peer registry yet. Bootstrap peers MUST NOT initiate node-level replication with nodes whose membership is not approved.

5.2 Peer Exchange

Nodes exchange discovery records with trusted peers to propagate knowledge of the information space.

When two nodes establish a connection:

1. each node sends its own discovery record
2. each node MAY send discovery records of other known peers
3. receiving nodes verify signatures and store valid records in the peer registry

Peer exchange allows the peer registry to grow as nodes request join to the information space. Only approved nodes participate in node-level background replication.

5.3 Local Network Discovery

Implementations MAY support local network discovery using multicast or broadcast on LAN segments.

When enabled, a node periodically broadcasts its discovery record on the local network. Other nodes on the same LAN that participate in the same information space receive and store the record.

Local network discovery MUST still require mutual authentication before trust is established. Broadcasting a discovery record does not automatically grant membership approval or replication access — it only makes the node's presence known.

---

6. Information Space Scoping

Discovery is always scoped to an information space.

A node that participates in multiple information spaces maintains a separate peer registry for each space. Discovery records exchanged in space A MUST NOT be added to the peer registry of space B.

The information_space_id field in the discovery record identifies which space the record belongs to. Records with a mismatched information_space_id MUST be rejected.

6.1 Independence

Information spaces are fully independent. Each space maintains its own:

• peer registry
• discovery context
• replicated data
• access control policies

Operations in one information space MUST NOT affect another. Failures, partitions, or policy changes in space A MUST NOT impact space B, even when both spaces are hosted on the same node.

6.2 Application Access

A node may participate in multiple information spaces, but applications running on that node do not automatically gain access to all of them.

By default, an application has access to no information spaces. The node operator MUST explicitly configure which information spaces each application may access.

Default	Configured
Application cannot read or write replicated data in any information space	Application is granted access to one or more specific information spaces

When an application accesses replicated state — through the database or file storage APIs — the Runtime MUST verify that the application is authorized for the target information_space_id. Messaging and RPC are used internally by the Replication service and are not exposed to applications.

---

7. Peer Registry Management

7.1 Storage

Each node stores its peer registries locally. Peer registries are not replicated across nodes — each node builds its own view of the information space based on discovery exchanges.

7.2 Updates

The peer registry is updated when:

• a new valid discovery record is received
• a node refreshes its own discovery record
• a record expires
• a peer is explicitly removed by the operator

7.3 Reachability

Implementations SHOULD periodically verify peer reachability by attempting connections to registered endpoints.

If a peer is unreachable for a configurable timeout period, its record SHOULD be marked as stale but not immediately removed — the peer may be temporarily offline.

7.4 Removal

A node MAY explicitly withdraw from an information space by sending a signed withdrawal message to known peers. Upon receiving a withdrawal message, peers MUST remove the node's discovery record from their registry.

---

8. Discovery Flow

1. Node starts and loads configured peers for the information space
2. Node connects to configured peers and performs mutual authentication
3. Node creates membership record (pending) unless space creator (auto-approved)
4. Nodes exchange discovery records
5. Peer registry is updated with new records
6. Administrator approves node membership
7. Node connects to discovered peers and begins node-level replication
8. Peer exchange propagates records across the information space

---

9. Security Requirements

Implementations MUST:

• verify Ed25519 signatures on all discovery records before acceptance
• reject records with expired expires_at timestamps
• reject records with mismatched information_space_id
• require mutual authentication before exchanging discovery records
• verify node membership status: approved before node-level background replication
• replicate node membership records across approved nodes
• reject node-level replication with peers whose membership is pending or rejected
• scope peer registries to information spaces
• verify application authorization before granting access to an information space

Implementations MUST NOT:

• grant applications implicit access to all information spaces on a node

• initiate node-level replication with unapproved nodes

• accept unsigned discovery records

• share discovery records across information space boundaries

• grant access to platform services based solely on receiving a discovery record

• expose user data in discovery records

Discovery makes a node's presence known. Membership approval gates node-level replication. User access to data still requires user approval and access policies as defined in the Identity Model and Data Access Control.

---

10. Export, Backup, and Migration

Operators and administrators need data portability — backup for disaster recovery, export for compliance, and migration when hardware or hosting changes. Faberio treats these as Runtime responsibilities coordinated with Distributed Database §10 and Distributed File Storage §10.

10.1 Operator Backup

Each node maintains local replicas per information space. An operator backup captures the node’s local state plus non-replicated secrets:

Item	Backup location
Database and file replicas	Runtime-coordinated snapshot or storage-engine dump
Membership and policy records	Included in database replica
Node private key	Operator secret store (NixOS sops, container secrets volume) — not in replicated records
Connectivity config	NixOS module options, container env, TLS material

Backups MUST remain under operator control. Restoring a backup on new hardware is a valid node migration path (section 10.4).

10.2 Portable Export and Import

Export produces an open archive scoped to one information_space_id — database records, file objects (when enabled), and platform metadata the exporter is authorized to read. Import applies an archive to a target node and space, with CRDT merge for overlapping UUIDs.

See Distributed Database §10.2–10.4 for format and space-fork rules. Import into a new information space requires creating that space, bootstrap membership, and re-approving nodes and users — export does not copy trust automatically.

10.3 Relocate Information Space

Relocate means the same information_space_id continues on new infrastructure — for example moving all community nodes from one VPS provider to NixOS home servers.

1. Each operator performs node migration (section 10.4) or adds a new approved node and allows peers to converge before removing old nodes.
2. Bootstrap peer lists and discovery endpoints are updated across operators.
3. Membership records and policies replicate to new nodes through normal sync — no new space identifier is required.

Relocate is cooperative: administrators coordinate cutover so at least one approved node holds a current replica during migration.

10.4 Migrate Node (Same Information Space)

Node migration redeploys one node without changing the information space trust boundary.

Requirements:

• Membership for the node MUST remain approved (or be re-approved if the operator creates a fresh membership record).
• If the node record UUIDv7 id is preserved, peers continue to recognize the same node object; connectivity endpoints change in operator config and discovery/bootstrap settings.
• User device nodes follow the same pattern; user private keys MUST be migrated through the secure device enrollment channel if keys are not included in operator backup.

10.5 Fork Information Space

Fork creates a new information space from exported data — for example splitting a community or cloning a template space.

1. Authorized operator exports space A.
2. Operator creates information space B with a new information_space_id.
3. Operator imports the archive into B on one or more nodes.
4. Administrators configure membership, user approval, and policies in B independently of A.

Fork preserves data; it does not preserve live federation with A. Cross-space replication remains forbidden.

The reference MVP prioritizes peer snapshot recovery and operator backup for server nodes; full export/import CLI may ship in later hardening.

---

11. Examples

11.1 Discovery Record

Each discovery record belongs to one information space. Example record for Project Alpha:

{
  "node_id": "a3f8c2e17b4d9a0e5f1c8b2d6e4a7f90",
  "display_name": "Home Server",
  "public_key": "3a7f...e2b1",
  "endpoints": [
    {
      "transport": "quic",
      "address": "192.168.1.10",
      "port": 7700
    }
  ],
  "capabilities": ["messaging", "rpc", "replication", "storage", "discovery"],
  "information_space_id": "0195a3f0-8000-7890-abcd-000000000001",
  "issued_at": 1718000000000,
  "expires_at": 1718086400000,
  "signature": "8f2c...9a1d"
}

The same node participating in Team Beta publishes a separate record with a different information_space_id and signature:

{
  "node_id": "a3f8c2e17b4d9a0e5f1c8b2d6e4a7f90",
  "display_name": "Home Server",
  "public_key": "3a7f...e2b1",
  "endpoints": [
    {
      "transport": "quic",
      "address": "192.168.1.10",
      "port": 7700
    }
  ],
  "capabilities": ["messaging", "rpc", "replication", "storage", "discovery"],
  "information_space_id": "0195a3f0-8100-7891-bcde-000000000002",
  "issued_at": 1718000001000,
  "expires_at": 1718086401000,
  "signature": "4b9e...7c3f"
}

11.2 Joining an Information Space

1. Operator configures bootstrap peer: 203.0.113.5:7700
2. Node starts, connects to bootstrap peer
3. Mutual authentication using Ed25519 key pairs
4. Membership record created (status: pending)
5. Exchange discovery records
6. Administrator approves membership (status: approved)
7. Node-level replication begins
8. Bootstrap peer shares records of other known peers
9. Node connects to discovered peers
10. Peer registry contains approved peers

11.3 Node Membership Approval

New node requests join to Project Alpha:

Membership record:
  node_id:              0195a3f0-9000-7895-efab-000000000005
  information_space_id: 0195a3f0-8000-7890-abcd-000000000001
  status:               pending

Node-level replication attempt:
  from: New Node
  to:   Bootstrap Node

Result: Denied — membership not approved

Administrator approves:
  status:      approved
  approved_by: 0195a3f0-8100-7891-bcde-000000000010
  approved_at: 1718000000000

Node-level replication:
Result: Allowed — membership approved on both nodes

11.4 Information Space Creation

1. Operator creates a new information space
2. UUIDv7 assigned to information space record
3. Information space record stored:

   id:           0195a3f0-8000-7890-abcd-000000000001
   display_name: Project Alpha

4. Founding node creates membership record (status: approved)
5. Founding node begins replication — no prior administrator required

11.5 Node Joining Multiple Spaces

Node: Home Server (0195a3f0-7f78-7894-abcd-ef0123456789)

Membership records:
  - Home Server + Project Alpha  (status: approved)
  - Home Server + Team Beta      (status: pending)

Discovery records:
  - Home Server in Project Alpha (information_space_id: ...0001)
  - Home Server in Team Beta     (information_space_id: ...0002)

The node maintains separate peer registries and discovery contexts for each space.

11.6 Multi-Space Participation

Node A participates in:
  - Project Alpha  (0195a3f0-8000-7890-abcd-000000000001, peers: B, C)
  - Team Beta      (0195a3f0-8100-7891-bcde-000000000002, peers: D)

Discovery in Project Alpha does not expose peers from Team Beta.
Node A maintains two independent peer registries.

---

12. References

• Identity Model
• Object Identifier