geth/docs/adr/0016-owner-node-enrollment.md

ADR 0016: Owner-Rooted Node Enrollment

Status

Accepted.

Context

Geth needs a practical device-management flow: initialize a mesh with an admin/owner identity, bind local daemon instances to named nodes/devices, list devices by name, grant resource capabilities, and revoke devices. This must not be a mutable device table because the project needs to evolve toward replicated local-first authorization.

Decision

Owner and node management is represented as signed keychain operations. geth init --admin-key <pub> --signing-key <key> --node-name <name> records KeychainInit, AdminKeyAdd, UserAdd, DeviceAdd, NodeAdd, and AgentBind operations. When owner setup options are used, both --admin-key and --signing-key are required. Geth signs canonical keychain payloads with OpenSSH using the geth.keychain.v1@geth.local namespace.

The active device list is the reduced keychain view, surfaced through geth node list. Renames and revocations are additional keychain operations. Resource permissions remain resource-scoped auth operations and can be managed with geth node grant and geth node revoke-grant; the CLI requires an admin --signing-key so these mutations replicate as signed auth operations. Endpoint rotation is modeled with signed NodeEndpointAdd and NodeEndpointRevoke operations exposed as geth node endpoint-add and geth node endpoint-revoke.

New nodes can request enrollment with geth node enroll request. The request is signed by the requesting agent key and includes the stable node ID, agent ID, requested node name, optional endpoint ID, and requested resource capabilities. The request can be submitted over Iroh with geth node enroll submit or moved as a JSON file and imported on the owner machine.

The owner approves with geth node enroll approve --signing-key <key>. Approval records signed keychain operations for the device, node, agent binding, and endpoint binding, plus signed auth operations for approved capabilities. The requesting node can run geth node enroll sync <owner-node> to pull both signed logs.

geth keychain sync <node> pulls keychain operations and signatures over Iroh from an imported peer. The receiver imports only operations with valid OpenSSH signatures from currently trusted admin keys over the canonical keychain payload. geth auth sync <node> applies the same trusted-admin signature rule to resource auth operations. Discovery and peer cards still grant no trust by themselves.

Consequences

Node names are convenience labels over stable node IDs. Endpoint rotation should add or revoke endpoint bindings without replacing the node identity.

The current sync model is a pull-based signed operation log. It is not yet a Keyhive-style convergent authority and does not implement advanced group cryptography. Conflict resolution for concurrent signed operations is still the deterministic reducer, not a richer collaborative authority protocol.