# 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.