eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
geth/docs/roadmap.md

13 KiB
Raw Blame History

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.

  • [ ] LAN mDNS discovery. Acceptance criteria:

    • The daemon can advertise and discover local geth peer cards over mDNS.
    • mDNS results are stored only as untrusted peer candidates.
    • 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 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".

  • [ ] Basic authenticated peer connection. Acceptance criteria:

    • A node can dial another node over Iroh using an EndpointID from a peer card.
    • The remote side proves an agent/node binding before module access.
    • Knowing only an EndpointID is insufficient to access a protected module.

Phase 2: Trust And Authorization

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

  • [ ] 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:

    • geth keychain init records a signed KeychainInit.
    • OpenSSH signature namespaces are explicit.
    • Missing ssh-keygen or unavailable hardware keys produce clear errors.

  • [ ] 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.

  • [ ] 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:

    • geth auth explain <subject> <resource> <capability> reports allowed/denied.
    • Output includes the operation chain or missing grant that caused the result.
    • JSON output is stable enough for tests and scripts.

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

    • Bearer secrets grant only resource-scoped capabilities.
    • Bearer principals cannot mutate trust graph state by default.
    • Secret epoch rotation is represented in durable metadata.
    • Tests verify bearer access does not imply node identity.

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

    • geth ssh cert request/requests/approve/import/list persist local metadata.
    • Approval emits an explicit ssh-keygen -s ... command for CA/YubiKey use.
    • geth ssh revocation add/list/export persists and exports revocations.
    • Future completion requires auth checks for 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:

    • Local CAS can provide and fetch blobs over Iroh.
    • Provider tracking is recorded locally.
    • Local add/get/hash/has/list behavior remains backward compatible.

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

    • Pinned blobs are retained across cache cleanup.
    • Unpinned cached blobs can be evicted by policy.
    • Tests cover pin, unpin, list, and 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:

    • geth kv create/set/get works against a named KV resource.
    • Prefix-scoped capabilities can allow or deny writes.
    • KV metadata is durable and replicated through Iroh Documents.

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

    • geth pubsub pub/sub works for local test nodes.
    • Pubsub messages are lossy notifications, not durable facts.
    • 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:

    • geth pipe listen/connect can connect two local test nodes.
    • Pipe access requires pipe.listen or pipe.connect.
    • 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:

    • Issued cert records and revocation records replicate over Iroh.
    • Consumers can list current certs/revocations from local state while offline.
    • Conflicting or unsigned records are rejected or quarantined.

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

    • Revocation records can produce an OpenSSH KRL file.
    • Existing KRL files can be imported into revocation metadata where possible.
    • Tests cover serial, key ID, public key, and certificate revocations.

Phase 5: DB And Documents

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

  • [ ] 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.

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

    • The module can read changes from crsql_changes.
    • Schema hash/version metadata is included in sync batches.
    • Tests use a temp SQLite DB and deterministic fixture 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:

    • geth document create/status works for local documents.
    • Document state is stored durably.
    • Tests cover 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.

  • [ ] CAS tree objects. Acceptance criteria:

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

  • [ ] File roots. Acceptance criteria:

    • A file root maps a local path to a CAS tree resource.
    • Scan detects create/update/delete/rename changes.
    • Sync never silently overwrites local changes without a recorded decision.

  • [ ] Conflict handling. Acceptance criteria:

    • Conflicts are represented as durable metadata.
    • CLI can list conflicts and choose a resolution.
    • Tests cover concurrent edit, delete/edit, and rename conflicts.

  • [ ] 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.