geth/docs/roadmap.md

Roadmap

This roadmap is intended to be checkable. Each item should either be completed with tests/docs or split into smaller items before implementation.

Status markers:

• [ ] Not started
• [~] In progress
• [x] Done

Phase 0: Bootstrap

Goal: establish a compiling single-binary local runtime with local state, local control, local CAS, service installation, and written architecture decisions.

• [x] Single geth binary with daemon and control modes. Acceptance criteria:

  • cargo run -p geth -- init initializes a temp GETH_HOME.
  • cargo run -p geth -- daemon run starts one local daemon.
  • No gethd or gethctl binaries exist in the workspace.

• [x] Local daemon control socket. Acceptance criteria:

  • Control request/response types roundtrip through JSONL serialization.
  • geth status and geth node id talk to a running daemon.
  • Control decoding treats input as untrusted and returns structured errors.

• [x] Local metadata store and identity. Acceptance criteria:

  • SQLite migrations are idempotent.
  • Agent identity persists across repeated opens of the same GETH_HOME.
  • Store schema includes resources, auth/keychain logs, CAS, peers, modules, SSH cert requests, certificates, and revocations.

• [x] Local filesystem CAS. Acceptance criteria:

  • geth cas add/hash/has/get/list work through the daemon.
  • Blob paths use BLAKE3 hashes under cas/blobs/<aa>/<bb>/<hash>.
  • Unit or integration tests verify bytes roundtrip unchanged.

• [x] User service installer. Acceptance criteria:

  • geth daemon service print --manager systemd|launchd|windows-task prints the expected user-level service definition or command.
  • Linux install targets a systemd user unit, not a system service.
  • macOS install targets a launchd user agent.
  • Windows install targets a per-user scheduled task.
  • Tests verify generated definitions do not target privileged system services.

• [x] Bootstrap docs and ADRs. Acceptance criteria:

  • README explains what geth is and what it is not.
  • Architecture docs state Iroh-only remote communication and SSH trust role.
  • ADRs cover single binary, Iroh-only transport, resources, auth, SSH, CAS, synchronized structures, service installation, and SSH certificate flows.

Phase 1: Iroh Foundation

Goal: make the daemon own a real Iroh endpoint and establish authenticated geth-to-geth connections without granting trust from discovery alone.

• [x] Pin and compile Iroh dependencies. Acceptance criteria:

  • iroh is added only after APIs are pinned and cargo check --workspace passes.
  • geth-iroh exposes endpoint startup/shutdown wrappers.
  • Docs note exact crate versions and any API assumptions.

• [x] Daemon-owned Iroh endpoint. Acceptance criteria:

  • The daemon creates one shared Iroh endpoint on startup.
  • geth status --json reports endpoint status and EndpointID.
  • Endpoint identity is bound to agent/node identity in local metadata.
  • Restarting the daemon preserves higher-level node identity.

• [x] Built-in relay policy and configuration. Acceptance criteria:

  • Config can select disabled, default Iroh relays, and staging relays.
  • The intended product default uses relays unless explicitly disabled.
  • geth status --json reports the selected relay mode.
  • Tests cover config parsing and endpoint builder relay-mode selection.

• [x] Custom relay maps. Acceptance criteria:

  • Config can define and select named custom relay maps.
  • Invalid relay URLs fail config validation with clear errors.
  • Status output identifies the selected custom relay map without exposing unrelated config.

• [x] Iroh LAN address discovery. Acceptance criteria:

  • Config can enable or disable Iroh local-network discovery.
  • The daemon registers Iroh's local mDNS-like discovery service when enabled.
  • geth status --json reports whether local-network discovery is enabled.

• [x] Signed peer-card LAN discovery payloads. Acceptance criteria:

  • [x] Manual geth peer export/import/list can exchange signed peer cards and store them as untrusted candidates.
  • [x] Exported daemon peer cards include Iroh EndpointID plus available relay/direct address candidates.
  • [x] The daemon can advertise and discover signed geth peer cards over LAN discovery.
  • [x] Imported peer cards are stored only as untrusted peer candidates.
  • [x] Discovered EndpointIDs do not grant module access without keychain/auth validation.

• [x] Protocol/router scaffold. Acceptance criteria:

  • ALPN constants are registered through one module router.
  • Unknown ALPNs are rejected explicitly.
  • Tests cover registration collisions and unknown protocol handling.

• [x] Peer cards. Acceptance criteria:

  • A peer card contains node ID, agent ID, endpoint candidates, timestamp, and signature metadata.
  • Peer-card signatures cover deterministic canonical payloads and reject tampered endpoint candidates.
  • Peer cards are stored in peer_cards.
  • Invalid or unsigned peer cards do not update trust state.

• [x] Untrusted discovery backend trait. Acceptance criteria:

  • Discovery returns candidate peer cards only.
  • No discovery result grants capabilities or trust.
  • auth explain can distinguish "discovered" from "trusted".

• [x] Basic authenticated peer connection. Acceptance criteria:

  • [x] geth peer ping <node-id> dials another node over Iroh using an imported signed peer card.
  • [x] The remote side validates the caller's signed peer card and stores it as a candidate only.
  • [x] The ping response records negotiated ALPN and remote endpoint identity.
  • [x] The remote side proves an agent/node binding before protected module access.
  • [x] Protected module handlers reject requests that only know an EndpointID and lack resource capabilities.

Phase 2: Trust And Authorization

Goal: replace stubs with signed, reducible keychain/auth operation logs and resource-scoped capability decisions.

• [x] Canonical signed operation envelope. Acceptance criteria:

  • Keychain and auth ops use deterministic canonical encoding for signatures.
  • JSON is not used as the signed representation.
  • Tests verify equivalent operations hash/sign identically across runs.

• [~] SSH-admin-rooted keychain initialization. Acceptance criteria:

  • [x] geth keychain init records a local KeychainInit.
  • [x] geth keychain init --admin-key <path> records an admin SSH public key fingerprint.
  • [x] geth keychain status reports the reduced local keychain view.
  • [ ] Future completion records signed KeychainInit operations.
  • [ ] OpenSSH signature namespaces are explicit in the signing flow.
  • [ ] Missing ssh-keygen or unavailable hardware keys produce clear errors during signing.

• [x] Keychain operation reducer. Acceptance criteria:

  • Admin keys, users, devices, nodes, agents, and endpoint bindings reduce into a current keychain view.
  • Revoked keys/devices/nodes are excluded from active views.
  • Tests cover add, rename, revoke, and endpoint rotation.

• [x] Resource auth operation reducer. Acceptance criteria:

  • Resource create, authority set, grants, revocations, and groups reduce into a current permission view.
  • Capabilities are strings, including scoped forms such as kv.write_prefix:apps/foo/.
  • Tests cover grant, revoke, group membership, and denied access.

• [~] auth explain real decision path. Acceptance criteria:

  • [x] geth auth grant and geth auth revoke persist local auth ops.
  • [x] geth auth explain <subject> <resource> <capability> reports allowed/denied from the local auth-op reducer when local ops exist.
  • [x] Output includes the grant ID or missing grant that caused the result.
  • [x] JSON output is stable enough for tests and scripts.
  • [ ] Future completion requires signed-op validation before accepting replicated auth ops.

• [~] Resource secrets and bearer invites. Acceptance criteria:

  • [x] geth secret create <resource> records resource secret epoch 1 metadata.
  • [x] geth secret rotate <resource> records the next resource secret epoch.
  • [x] Secret epoch rotation is represented in durable metadata.
  • [x] Bearer secrets grant only resource-scoped capabilities.
  • [x] Bearer principals cannot mutate trust graph state by default.
  • [x] Tests verify bearer access does not imply node identity.
  • [ ] Future completion requires bearer challenge-response proof instead of metadata-only local records.

• [~] SSH certificate and revocation lifecycle. Acceptance criteria:

  • [x] geth ssh cert request/requests/approve/import/list persist local metadata.
  • [x] Approval emits an explicit ssh-keygen -s ... command for CA/YubiKey use.
  • [x] geth ssh revocation add/list/export persists and exports revocations.
  • [x] Revocations can be exported as JSONL and OpenSSH KRL specification text or as a binary OpenSSH KRL through ssh-keygen.
  • [x] Authorized peers can pull SSH cert-flow metadata with geth ssh cert sync <node-id>.
  • [x] Authorized peers can pull SSH revocation metadata with geth ssh revocation sync <node-id>.
  • [x] The daemon background live-sync loop refreshes known peers without a manual command.
  • [x] SSH metadata live-sync stores per-peer high-water cursors in module_state and requests only records at or beyond the cursor.
  • [ ] Future completion requires auth checks for local request, approve, import, publish, and read capabilities.

Phase 3: CAS, KV, And Pubsub

Goal: turn local CAS and stubs into Iroh-backed replicated modules while keeping authorization and durable-state boundaries clear.

• [~] Iroh-blobs CAS integration. Acceptance criteria:

  • [x] geth cas fetch <node-id> <hash> can fetch a blob from an imported peer over the daemon-owned Iroh control ALPN.
  • [x] The serving peer validates the caller's signed peer card against the observed Iroh EndpointID before considering authorization.
  • [x] Remote CAS fetch requires cas.fetch on resource:cas:local.
  • [x] The requester verifies returned bytes against the requested BLAKE3 CAS hash before storing them locally.
  • [x] Local add/get/hash/has/list behavior remains backward compatible.
  • [ ] Replace the bootstrap control-ALPN transfer with iroh-blobs provider/fetch behavior.
  • [ ] Provider tracking is recorded locally.

• [x] CAS pin and cache policy. Acceptance criteria:

  • [x] geth cas pin <hash> persists local pin metadata.
  • [x] geth cas unpin <hash> removes local pin metadata.
  • [x] geth cas list reports pinned versus unpinned blobs.
  • [x] Pinned blobs are retained across cache cleanup.
  • [x] Unpinned cached blobs can be evicted by policy.
  • [x] Tests cover attempted eviction of pinned data.

• [ ] Encrypted private blobs. Acceptance criteria:

  • Private blob payloads are encrypted before network distribution.
  • Access is gated by resource secret epoch material.
  • Docs explicitly avoid claiming forward secrecy or PCS.

• [~] Iroh-docs KV integration. Acceptance criteria:

  • [x] geth kv create/set/get works against a named local KV resource.
  • [x] KV metadata and entries are durable in the local SQLite store.
  • [x] The auth evaluator allows kv.write_prefix:<prefix> grants to satisfy matching kv.write_key:<key> requests.
  • [x] Tests cover allowed and denied prefix-scoped KV write explanations.
  • [x] geth kv set --subject <principal> enforces local capability decisions for non-local test callers.
  • [x] geth kv sync <node-id> <name> pulls authorized updates from an imported peer over Iroh.
  • [x] Remote KV sync requires kv.read on resource:kv:<name>.
  • [x] Background live-sync refreshes local KV stores from known peers using per-peer/per-KV high-water cursors.
  • [ ] KV metadata is replicated through Iroh Documents.

• [~] Iroh-gossip pubsub integration. Acceptance criteria:

  • [x] geth pubsub pub/sub works against the local daemon.
  • [x] Local pubsub messages are kept in a bounded daemon-lifetime ring buffer.
  • [x] Pubsub messages are documented and tested as lossy notifications, not durable facts.
  • [x] geth pubsub pub <topic> <message> --node <node-id> publishes to an imported peer over Iroh.
  • [x] Remote pubsub publish requires pubsub.publish on resource:pubsub:<topic>.
  • [ ] Replace bootstrap remote publish with iroh-gossip topics.
  • [ ] Pubsub subscribe works across local test nodes over Iroh or gossip.
  • [ ] Docs and tests keep durable state in CAS/KV/document/db instead.

Phase 4: Pipes, SSH Proxy, And SSH Distribution

Goal: add authorized stream-oriented management workflows over Iroh.

• [~] Dumbpipe-style Iroh streams. Acceptance criteria:

  • [x] geth pipe listen/connect works against a local daemon-lifetime registry.
  • [x] Tests cover local listener registration, local connect matching, and daemon restart behavior.
  • [x] geth pipe connect <name> --node <node-id> can connect to an imported peer over Iroh at the control-plane level.
  • [x] Remote pipe connect requires pipe.connect on resource:pipe:<name>.
  • [ ] Remote pipe listen requires pipe.listen when remote listener creation is added.
  • [ ] Pipe connect carries bidirectional byte streams over Iroh.
  • [ ] Streams close cleanly and propagate errors.

• [ ] TCP forwarding. Acceptance criteria:

  • A local TCP listener can forward over an authorized Iroh pipe.
  • Tests cover basic request/response forwarding.
  • Forwarding is resource-scoped and can be disabled by auth.

• [ ] Unix socket forwarding where supported. Acceptance criteria:

  • Unix socket forwarding is available on Unix platforms.
  • Unsupported platforms return clear errors.
  • Tests skip or use cfg guards where sockets are unavailable.

• [ ] SSH proxy over Iroh. Acceptance criteria:

  • geth ssh proxy <node> opens an authorized Iroh stream.
  • Remote daemon checks ssh_proxy.connect before connecting to local sshd or admin shell.
  • Knowing an EndpointID alone cannot reach sshd.

• [~] SSH certificate and revocation distribution. Acceptance criteria:

  • [x] Cert request and imported certificate records can be pulled from an imported peer over Iroh.
  • [x] Revocation records can be pulled from an imported peer over Iroh.
  • [x] Remote sync validates the caller's signed peer card against the observed Iroh EndpointID before considering authorization.
  • [x] Cert metadata sync requires ssh_cert.sync on resource:ssh:certs.
  • [x] Revocation metadata sync requires ssh_revocation.sync on resource:ssh:revocations.
  • [x] Consumers can list current certs/revocations from local state while offline after sync.
  • [x] Background live-sync uses the same protected Iroh path and cursor state as manual sync.
  • [ ] Replace pull-only metadata sync with a resource log or CRDT model.
  • [ ] Conflicting or unsigned records are rejected or quarantined.

• [x] OpenSSH KRL import/export. Acceptance criteria:

  • [x] Revocation records can produce an OpenSSH KRL specification file.
  • [x] Tests cover serial, key ID, and public key revocation spec lines.
  • [x] Revocation records can produce an OpenSSH binary KRL file.
  • [x] Tests cover binary KRL export for public-key revocations when ssh-keygen is available.
  • [x] JSONL exports and OpenSSH KRL specification source files can be imported into revocation metadata.
  • [x] Binary OpenSSH KRL import returns a clear unsupported message because KRL files are not enumerable through OpenSSH tooling.
  • [x] Tests cover JSONL and KRL-spec import.
  • [x] Tests cover certificate revocations.

Phase 5: DB And Documents

Goal: add durable synchronized data structures for SQLite/cr-sqlite and Automerge documents.

• [x] DB resource registration. Acceptance criteria:

  • geth db add <name> <path> records DB metadata.
  • geth db status <name> reports local path, schema metadata, and sync state.
  • Nonexistent paths and invalid names produce clear errors.

• [x] cr-sqlite change extraction. Acceptance criteria:

  • [x] DB status detects whether crsql_changes exists.
  • [x] DB status reports crsql_changes row count, columns, and max db_version when available.
  • [x] Tests use a temp SQLite DB and deterministic fixture changes.
  • [x] The module can extract typed change batches from crsql_changes.
  • [x] Schema hash/version metadata is included in extracted change batches.
  • [x] Extracted batches are exposed through geth db changes.

• [ ] DB sync over Iroh. Acceptance criteria:

  • Two local test nodes can exchange and apply DB changes.
  • Schema mismatch is detected before applying changes.
  • Optional CAS-backed snapshots or batches are documented if used.

• [~] Automerge document resource. Acceptance criteria:

  • [x] geth document create/status works for local documents.
  • [x] Document metadata and empty JSON state are stored durably.
  • [x] geth document set/get stores and returns validated local JSON state.
  • [x] Tests cover create, update, save, and reload of local JSON document state.
  • [ ] Automerge document state is stored durably.
  • [ ] Tests cover Automerge create, update, save, and reload.

• [ ] Automerge sync over Iroh. Acceptance criteria:

  • Two local test nodes can synchronize document changes.
  • Resource authorization gates read/write sync.
  • Conflicts converge according to Automerge semantics.

Phase 6: File Sync And Advanced Local-First Auth

Goal: build higher-level local-first collaboration on CAS trees, resource auth, and future group key evolution.

• [x] CAS tree objects. Acceptance criteria:

  • [x] Tree objects describe directories, files, executable bits, and blob hashes.
  • [x] Tree objects are content-addressed and stored in CAS.
  • [x] Tests cover deterministic tree hashing.

• [~] File roots. Acceptance criteria:

  • [x] A file root maps a local path to a CAS tree resource.
  • [x] geth cas root add/list/scan persists local root metadata and latest tree state.
  • [x] Scan detects create/update/delete/rename changes.
  • [x] Scan output documents that geth never overwrites file roots without a recorded future sync decision.
  • [ ] File roots can be synced across nodes.

• [~] Conflict handling. Acceptance criteria:

  • [x] Conflicts are represented as durable metadata.
  • [x] CLI/control can record, list, and choose a resolution for local conflict metadata.
  • [x] Tests cover local concurrent edit conflict record/list/resolve.
  • [ ] Future sync records conflicts automatically from base/local/remote tree comparisons.
  • [ ] Tests cover automatic concurrent edit, delete/edit, and rename conflict detection.

• [ ] Keyhive-like convergent capabilities. Acceptance criteria:

  • Capability state is represented as local-first replicated auth data.
  • Convergent grant/revoke semantics are documented and tested.
  • Migration from current auth ops is documented.

• [ ] BeeKEM/CGKA-inspired group key evolution. Acceptance criteria:

  • Design doc states exact security properties and non-properties.
  • Prototype is behind explicit experimental module boundaries.
  • Current resource secret epoch model remains compatible or has a migration.