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.

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

- `[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.
  - `[ ]` 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.
  - `[ ]` `geth pubsub pub/sub` works across local test nodes over Iroh.
  - `[ ]` Pubsub publish/subscribe access is capability checked.
  - `[ ]` 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.
  - `[ ]` `geth pipe listen/connect` can connect two local test nodes over Iroh.
  - `[ ]` 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.

- `[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.