geth/docs/roadmap.md

Roadmap

This is the long-term product and feature roadmap. It is intentionally broader than the pre-deployment hardening effort, so unchecked items here do not imply that a completed production-readiness phase has regressed. Each item should either be completed with tests/docs or split into smaller items before implementation.

Status markers:

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

For deployment-readiness work that cuts across feature areas, see docs/production-readiness-roadmap.md.

Operator Usability

• [x] Enforce one daemon per geth home. Acceptance criteria:

  • [x] Daemon startup claims the local control endpoint before starting network and background modules.
  • [x] A live endpoint rejects another daemon with the stable daemon_already_running code instead of unlinking the first Unix socket or replacing the first Windows named-pipe server.
  • [x] Stale, unreachable Unix socket paths are recovered automatically; Windows pipe lifetime is owned by the server handle.
  • [x] Tests cover stale recovery and live second-daemon rejection.

• [x] Keep local control available when Iroh-native startup degrades. Acceptance criteria:

  • [x] Endpoint startup and native blob/docs/gossip initialization failures do not prevent the local control daemon from serving.
  • [x] Partial native runtime handles are released and a partially started endpoint is closed.
  • [x] Status reports each native backend as unavailable with the runtime failure note instead of claiming a compiled backend is healthy.
  • [x] Tests inject a post-endpoint native-store failure and verify clean degradation where UDP endpoint binding is available.

• [x] Use a platform-native local control carrier. Acceptance criteria:

  • [x] Linux and macOS retain per-home Unix-domain sockets.
  • [x] Windows derives a deterministic per-home named-pipe name and uses Tokio named-pipe clients and server instances for the same JSONL protocol.
  • [x] Unary control, SSH proxying, and TCP byte forwarding share one async local-stream abstraction without adding another executable or remote transport.
  • [x] Unix-socket forwarding is cfg-gated with an explicit unsupported result on Windows, and a platform transport roundtrip runs in CI tests.

• [x] Make startup modes and the daemon lifecycle discoverable. Acceptance criteria:

  • [x] Base and nested CLI help explain every command family instead of showing unlabeled command names.
  • [x] geth daemon install initializes, installs, enables, and starts a background service for the current user.
  • [x] Common start, stop, status, and uninstall operations do not require the nested compatibility command path.
  • [x] Service status reports running, inactive/not-installed, and unknown manager states without treating every nonzero status probe as an action failure.
  • [x] geth daemon run --ephemeral creates disposable state and prints the exact --home selector needed by another terminal.
  • [x] Unix user-service shutdown handles SIGTERM through the daemon's graceful Iroh/task/socket cleanup path.
  • [x] Tests cover lifecycle parsing, help discoverability, and explicit home selection without mutating a real user service manager.

• [x] Make leaf-command arguments self-explanatory. Acceptance criteria:

  • [x] Every positional argument and option has operator-facing help text, including fields generated across deeply nested command families.
  • [x] Ambiguous fields such as KV keys, resource names, conflict kinds, and forwarding targets use command-specific wording where it affects correct use.
  • [x] Enrollment requests, authorization grants, CAS root application, and KV writes include copy-paste examples in their leaf help.
  • [x] A recursive CLI test fails when a future argument is added without a description.

• [x] Add a safe configuration workflow. Acceptance criteria:

  • [x] geth config path/show/validate identify the selected file, expose built-in defaults when it is absent, and report parse or semantic errors.
  • [x] geth config set supports the common Iroh and live-sync settings, preserves unrelated TOML and comments, and validates before replacement.
  • [x] Updates use a same-directory temporary file and clearly report that a daemon restart is required.
  • [x] Tests cover comment preservation, invalid-update rollback, and creation from defaults in an isolated temporary home.

• [x] Document task-oriented user stories. Acceptance criteria:

  • [x] Workflows cover disposable evaluation, persistent background use, owner setup, enrollment, CAS transfer, synchronized application state, automation, diagnosis, backup, and recovery.
  • [x] Each workflow identifies its success signal and relevant trust or durability boundary.
  • [x] Documentation distinguishes automated coverage from real-machine, hardware-key, relay, and privileged-interface dogfooding.

• [x] Add unified service-log inspection. Acceptance criteria:

  • [x] One CLI command gives the platform-appropriate user-service log view or an exact recovery command on Linux, macOS, and Windows.
  • [x] Log access remains user-scoped and does not require a system service.
  • [x] Human and JSON output distinguish unavailable logs, an uninstalled service, and an installed service with no log entries.

• [x] Verify background-service installation readiness and durability. Acceptance criteria:

  • [x] Direct geth daemon install waits for local control readiness by default and reports a log-inspection recovery command on timeout.
  • [x] Service executable paths are canonical regular files; Cargo-target and temporary binaries are copied atomically into the selected geth home by default rather than leaving a fragile service reference.
  • [x] An explicit override supports intentional transient development services, and advanced install can still omit immediate startup.
  • [x] Tests cover transient path detection/copying, file-log states, and user-scoped generated definitions.

• [x] Normalize machine-readable CLI output. Acceptance criteria:

  • [x] --json emits one pretty JSON document and --jsonl emits each result as one compact physical line; the flags are mutually exclusive.
  • [x] Direct CLI results, local-control responses, and service reports use stable top-level type fields without mixing operator prose into stdout.
  • [x] Machine-mode failures use the stable error envelope, include a focused recovery hint when available, and exit nonzero.
  • [x] Tests and automation documentation define the single-document and line-oriented contracts.

• [x] Make resource and capability vocabulary discoverable offline. Acceptance criteria:

  • [x] geth resource capabilities [family] lists exact resource ID patterns, capability strings, and important operations or host effects.
  • [x] Discovery works before initialization and without a running daemon, and explicitly states that viewing the catalog does not grant access.
  • [x] Human, JSON, and JSONL forms include a copy-paste grant template.
  • [x] Tests cover the full catalog, family filtering, common aliases, and unknown-family recovery.

• [x] Publish copy-paste installation entrypoints for release artifacts. Acceptance criteria:

  • [x] Linux, macOS, and Windows installation instructions verify artifact checksums and put the single geth executable on PATH.
  • [x] Installation stays separate from explicit geth daemon install so downloading a binary never silently creates trust state or starts a service.
  • [x] Upgrade and uninstall instructions preserve or explicitly remove the selected geth home.
  • [x] Tagged release CI smoke-tests checksum verification and the installed binary through the same Unix and PowerShell entrypoints users run.

Long-Term Goal: Distributed Homelab Overlay

Goal: evolve geth into a distributed, fault-tolerant homelab overlay runtime in the spirit of NetBird/Tailscale, while preserving geth's core invariants: Iroh is the only remote geth transport, discovery is untrusted, SSH keys are trust anchors rather than transport keys, and authorization remains resource-scoped and capability-based.

This is a long-term product direction, not a claim about the current prototype. The target is a usable personal/family/lab mesh that can survive intermittent nodes, changing network locations, partial discovery failures, and offline admin devices without depending on one always-online coordination server.

• [ ] Distributed overlay control plane. Acceptance criteria:

  • [ ] Overlay membership, virtual IP assignment, route advertisements, node capabilities, and revocations are represented as signed replicated resource data.
  • [ ] The control plane has documented conflict semantics for concurrent joins, renames, IP conflicts, route changes, and revocations.
  • [ ] Nodes can converge from static sigchain publication, peer live-sync, and Iroh-connected peers without requiring a central coordinator.
  • [ ] Stale or partitioned nodes are detectable in geth overlay status and geth sync status --json.

• [ ] Fault-tolerant peer and path selection. Acceptance criteria:

  • [ ] Nodes maintain multiple candidate addresses from Iroh relays, local discovery, imported peer cards, and static publication.
  • [ ] Packet routing retries healthy paths and backs off failed paths without granting trust from discovery metadata.
  • [ ] Relay use, direct connections, LAN discovery, and path failures are visible in human and JSON status output.
  • [ ] Integration tests simulate peer restart, address rotation, relay-only connectivity, and temporary peer unavailability.

• [ ] Production overlay routing features. Acceptance criteria:

  • [ ] Overlay supports stable virtual IPv4 addressing with collision detection and operator-visible remediation.
  • [ ] Subnet-router resources can advertise selected LAN routes with explicit capabilities and revocation behavior.
  • [ ] Exit-node routing is modeled as an explicit resource and requires dedicated capabilities.
  • [ ] MTU selection, packet size limits, and fragmentation/drop behavior are documented and tested.

• [ ] Homelab DNS and service discovery. Acceptance criteria:

  • [ ] Nodes can publish signed names and service records into replicated resource metadata.
  • [ ] A local resolver or hosts-file integration can expose overlay names without requiring global DNS changes.
  • [ ] DNS/service data is separated from untrusted LAN discovery and can be explained through auth/keychain state.
  • [ ] Revoked nodes and stale records disappear from the trusted view after verified sync.

• [ ] Cross-platform operational polish. Acceptance criteria:

  • [ ] Linux TUN setup documents required user-service permissions, CAP_NET_ADMIN, and distro-specific recovery steps.
  • [ ] macOS release builds document required entitlements and user-service launch behavior.
  • [ ] Windows builds package or clearly locate Wintun and install a per-user daemon task.
  • [ ] geth guide overlay contains an end-to-end two-machine smoke test for each supported platform class.

• [ ] Security and auditability bar for overlay use. Acceptance criteria:

  • [ ] Every packet-forwarding, subnet-routing, exit-node, DNS, and service discovery operation has an explicit resource/capability check.
  • [ ] auth explain can answer why a node may or may not route packets, advertise a subnet, use an exit node, or publish a service name.
  • [ ] Bearer secrets can invite limited overlay access without granting trust graph mutation rights.
  • [ ] The docs state what properties geth provides today and avoid claims equivalent to Keyhive/BeeKEM, WireGuard, NetBird, or Tailscale unless those properties are actually implemented and tested.

Initial Viability Closure Plan

These items established a smooth end-to-end test target for the intended personal mesh use cases. The cross-cutting pre-deployment requirements and the remaining real-machine gate are tracked in the production-readiness roadmap.

Implementation order:

1. [x] Close remote authorization and replicated-state safety gaps. Acceptance criteria:

   • [x] Add initial two-daemon tests proving denied remote pubsub publish, remote pipe listen, and SSH admin shell requests do not mutate serving node state.
   • [x] Add initial two-daemon tests proving unsigned replicated keychain/auth operations are rejected and not imported.
   • [x] Add initial two-daemon tests proving invalidly signed replicated keychain/auth operations are rejected and not imported.
   • [x] Add tests proving conflicting replicated keychain/auth records do not mutate trust/resource state.
   • [x] Improve auth explain diagnostics enough for operators to distinguish discovered-only peers, missing endpoint bindings, missing grants, matching grants, revocations, and bearer access.

2. [x] Replace bootstrap sync transports with Iroh-native backends where the pinned APIs are stable. Acceptance criteria:

   • [x] CAS uses iroh-blobs or has a documented pinned blocker.
   • [x] KV uses Iroh Documents or has a documented pinned blocker.
   • [x] Pubsub uses iroh-gossip or has a documented pinned blocker.
   • [x] geth status reports the current bootstrap backend, target crate, target version, and blocker for CAS, KV, and pubsub.

3. [x] Polish file sync reconciliation. Acceptance criteria:

   • [x] Add a safe three-way apply path for non-conflicting create/update/delete/rename changes.
   • [x] Keep ambiguous changes as durable conflicts.
   • [x] Add two-root integration coverage.

4. [x] Replace JSON document state with durable Automerge documents. Acceptance criteria:

   • [x] Store Automerge documents durably.
   • [x] Sync Automerge changes over Iroh.
   • [x] Gate document sync with resource authorization.

5. [x] Harden DB sync for real cr-sqlite usage. Acceptance criteria:

   • [x] Add a real cr-sqlite-enabled two-node integration test, or document a precise blocker if the extension is unavailable in CI/dev.
   • [x] Decide and document whether CAS-backed DB snapshots/batches are part of the prototype.

6. [x] Finish operational first-run polish. Acceptance criteria:

   • [x] README has a two-machine walkthrough for the main smoke tests.
   • [x] CLI recovery errors tell operators the next command to run.
   • [x] JSON sync status is script-friendly for stale/failed peer detection.
   • [x] Shell completions are generated from the Clap command tree for bash, zsh, fish, PowerShell, and elvish.
   • [x] Completion installation examples are available through geth guide completions.

• [x] Two-node operator-flow test coverage. Acceptance criteria:

  • [x] A two-daemon test covers owner-rooted init, peer-card exchange, enrollment request submission, owner approval, geth sync now, and geth sync status.
  • [x] A two-daemon test proves approved keychain/auth state reaches the enrolled node without using the old one-off node enroll sync shortcut.
  • [x] Tests assert unsigned replicated keychain/auth records do not mutate local trust or resource state.
  • [x] Tests assert invalidly signed replicated keychain/auth records do not mutate local trust or resource state.
  • [x] Tests assert conflicting replicated keychain/auth records do not mutate local trust or resource state.

• [x] Remote authorization enforcement audit. Acceptance criteria:

  • [x] Every remote mutable operation has an explicit resource capability check before mutating local state or opening a host service, or is documented as a signed-log import / owner-reviewed enrollment exception.
  • [x] A test-backed remote guard matrix documents the expected guard for each remote operation and fails if mutating/service-opening operations rely on discovery alone.
  • [x] Tests cover denied and allowed paths for CAS, KV, DB, document, pubsub, pipe, SSH proxy/admin shell, SSH cert metadata, and revocations.
  • [x] Initial two-daemon denied-mutation coverage exists for remote pubsub publish, remote pipe listen, and SSH admin shell.
  • [x] auth explain output can explain discovered-only peers, missing endpoint bindings, missing grants, matching grants, revocations, and bearer access.

• [x] Iroh-native backend replacement. Acceptance criteria:

  • [x] CAS fetch/provider paths use iroh-blobs or a documented pinned equivalent instead of bootstrap control-ALPN blob transfer.
  • [x] KV metadata and entries replicate through Iroh Documents or a documented pinned equivalent.
  • [x] Pubsub wakeups/presence use iroh-gossip or a documented pinned equivalent.
  • [x] Fallback/stub behavior remains clearly marked where APIs are not yet pinned.
  • [x] Upgrade geth-iroh to stable iroh 1.0.0 with matching iroh-blobs 0.103.0, iroh-docs 0.101.0, and iroh-gossip 0.101.0 without introducing a second daemon endpoint.

• [x] File sync reconciliation polish. Acceptance criteria:

  • [x] cas root apply has a richer three-way base/local/remote reconcile path for safe updates and deletes.
  • [x] Ambiguous changes continue to produce durable conflicts instead of overwriting local files.
  • [x] Tests cover create/update/delete/rename application across two local roots.

• [x] Durable Automerge documents. Acceptance criteria:

  • [x] Document state is stored as durable Automerge data, not only JSON last-writer-wins state.
  • [x] Sync exchanges durable Automerge state over the protected Iroh control path and merges received Automerge documents.
  • [x] Resource authorization gates remote document reads and writes.

• [x] Operational first-run polish. Acceptance criteria:

  • [x] README has a complete two-machine walkthrough for owner init, enrollment, grants, sync status, SSH cert request/approval, SSH proxy, KV, CAS/file-root, and DB/document smoke tests.
  • [x] CLI errors for stale peer cards, missing endpoint bindings, missing grants, unavailable relays, unavailable service managers, and unsupported platform features tell the operator what command to run next.
  • [x] geth init --help and geth guide <topic> explain owner setup, enrollment, key roles, service installation, and smoke-test workflows from the binary itself.
  • [x] geth sync status --json is sufficient for scripts to detect stale peers and failed streams.

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 endpoint. Acceptance criteria:

  • Control request/response types roundtrip through JSONL serialization.
  • geth status and geth node id talk to a running daemon.
  • Unix sockets and Windows named pipes carry the same local protocol.
  • 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.
  • Direct install verifies local daemon readiness and exposes unified logs.
  • Transient build artifacts are copied into the selected geth home before a service definition references them unless explicitly overridden.
  • Tests verify generated definitions do not target privileged system services.

• [x] GitHub CI, security, and release automation. Acceptance criteria:

  • [x] CI runs formatting, clippy, docs, check, and deterministic workspace tests on Linux, macOS, and Windows.
  • [x] Cross-platform jobs keep GETH_TEST_SKIP_IROH=1 for deterministic host-networking behavior.
  • [x] Ubuntu CI has a required Iroh integration job covering live daemon-to-daemon bootstrap, peer control, sync, native modules, pipe forwarding, SSH proxy handshakes, and overlay ALPN authorization.
  • [x] RustSec advisory scanning runs on pull requests, pushes, manual dispatch, and a weekly schedule.
  • [x] CodeQL and dependency review workflows are present for GitHub-native security scanning.
  • [x] Release workflow builds Linux x86_64, macOS x86_64/arm64, and Windows x86_64 archives for v* tags and manual dispatch.
  • [x] Release archives have SHA-256 files, an aggregate checksum manifest, and checksum-verifying installer smoke tests.
  • [x] Dependabot is configured for Cargo and GitHub Actions updates.

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

• [x] Authorized sync status summary. Acceptance criteria:

  • [x] The daemon can ask an imported peer for sync stream watermarks over the protected Iroh control ALPN.
  • [x] The serving peer validates the caller's signed peer card against the observed Iroh EndpointID before returning watermarks.
  • [x] The serving peer only includes streams where the caller already has the relevant resource capability.
  • [x] Background live-sync skips per-module pulls when the authorized remote watermark has not advanced.
  • [x] geth sync status reports last local attempt, success, cursor, import/rejection counts, and error for each recorded peer stream.
  • [x] Failed background live-sync streams record consecutive failures and retry-after metadata.
  • [x] geth sync now [node] triggers the same best-effort sync pass that background live sync uses, bypassing stream backoff for operator retries.
  • [x] Tests verify unauthorized streams are omitted from summary output.
  • [x] Tests verify persisted stream health is exposed in local sync status.

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.

• [x] 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.
  • [x] geth keychain init --signing-key <path> signs recorded keychain ops with ssh-keygen -Y sign.
  • [x] OpenSSH keychain signatures use the explicit geth.keychain.v1@geth.local namespace.
  • [x] Keychain OpenSSH signatures are stored in local SQLite.
  • [x] geth keychain status reports the stored keychain signature count.
  • [x] geth keychain status verifies stored keychain signatures against canonical payloads with OpenSSH when public key material is available.
  • [x] AdminKeyAdd carries OpenSSH public key material, principal, and optional validity metadata so the admin key registry is reconstructable from the signed log itself.
  • [x] geth keychain admin-add and geth keychain admin-revoke append signed admin-key registry operations.
  • [x] geth keychain allowed-signers exports the active admin key view in OpenSSH allowed_signers format.
  • [x] geth keychain allowed-signers --out <path> writes the active OpenSSH allowed_signers projection directly to a file.
  • [x] geth keychain sign-file --in <path> --out <sig> signs arbitrary snapshots, such as externally managed authorized_keys, with an active admin key under an explicit namespace.
  • [x] geth keychain verify-file --in <path> --signature <sig> verifies a snapshot signature against the current keychain-derived allowed_signers projection or a supplied --allowed-signers file.
  • [x] geth keychain sigchain --out <path> writes the appendable JSONL sigchain suitable for static website publication.
  • [x] geth keychain publish-bundle --out <dir> writes a static website bundle rooted at https://example.com/.well-known/sshsigchain/ by default.
  • [x] Publication bundles include allowed_signers, geth.sigchain.jsonl, geth.sigchain.checkpoint.json, and a detached checkpoint signature.
  • [x] Publication bundles can copy and sign external snapshots with --snapshot <name>=<path> without making the keychain own their contents.
  • [x] geth keychain verify-sigchain --in <path> verifies a JSONL sigchain file by replaying operations and signatures.
  • [x] geth keychain import-sigchain --in <path> imports a JSONL sigchain only if replay verification rejects no operations.
  • [x] geth keychain verify-checkpoint verifies checkpoint signatures, checkpoint hashes, base URL, and sigchain head consistency.
  • [x] geth keychain fetch --url <base> --import fetches static bundles with curl for HTTP(S) or filesystem reads for local/file URLs.
  • [x] Static fetch/import records the last accepted checkpoint per source URL and rejects older checkpoints for rollback resistance.
  • [x] geth keychain explain <op-id> and explain-signer <key-id> provide basic audit output for operations and admin signers.
  • [x] Agent/FIDO signing is supported through OpenSSH by passing a public key or security-key stub to --signing-key; PKCS#11 is documented as an ssh-agent-backed flow when loaded with ssh-add -s <provider>.
  • [x] geth keychain verify replays the keychain sigchain against the previously accepted admin-key view.
  • [x] Reusable sigchain mechanics live in geth-keychain, not in daemon orchestration code.
  • [x] geth-keychain exposes transport-neutral allowed-signers projection, replay verification with an injected verifier, and appendable JSONL sigchain encode/decode helpers for static hosting or alternate transports.
  • [x] geth-keychain exposes KeychainProfile so non-geth applications can use distinct signature namespaces and default principals.
  • [x] geth-keychain exposes a KeychainSignatureVerifier trait so callers can plug in OpenSSH, HSM, WebCrypto, service-side, or test verification backends without daemon coupling.
  • [x] docs/sigchain-keychain.md documents the sigchain data model, verification algorithm, commands, and current security limits.
  • [x] Missing ssh-keygen or unavailable hardware keys produce clear errors during signing.
  • [x] Tests cover signed keychain init with a generated local OpenSSH key when ssh-keygen is available.
  • [x] Tests cover local OpenSSH verification of stored keychain signatures.
  • [x] geth init --admin-key --signing-key --node-name records signed owner/user/device/node/agent binding operations.
  • [x] geth node list/rename/revoke operate on the reduced keychain view.
  • [x] geth node rename/revoke require an admin signing key.
  • [x] geth keychain sync <node> verifies signatures from currently trusted admin keys before accepting keychain ops.
  • [x] Keychain live sync advertises and consumes per-peer high-water cursors instead of blindly re-requesting the full log on every tick.
  • [x] geth node enroll request creates an agent-key-signed enrollment request with requested node name and capabilities.
  • [x] geth node enroll join combines explicit admin-key trust bootstrap, candidate-only peer-card import, request creation, and Iroh submission while leaving owner approval as a separate admin-signed step.
  • [x] geth node enroll submit/import/list moves pending enrollment requests over Iroh or JSON file for owner review.
  • [x] geth node enroll approve --signing-key records signed keychain ops for device/node/agent/endpoint enrollment.
  • [x] geth node enroll sync <owner-node> pulls approved signed keychain and auth state onto the requesting node.
  • [x] geth node endpoint-add/revoke --signing-key records signed endpoint rotation operations.

• [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] Node capability management. Acceptance criteria:

  • [x] geth node grant <node> <resource> <capability> records a signed resource-scoped capability grant for a known node.
  • [x] geth node revoke-grant <resource> <grant-id> records grant revocation as a signed auth op.
  • [x] Node names can be used for management commands where the keychain view has a unique active node name.
  • [x] Enrollment approval signs capability grants as auth ops.
  • [x] geth auth sync <node> imports only auth ops signed by currently trusted admin keys.
  • [x] Auth live sync advertises and consumes per-peer high-water cursors instead of blindly re-requesting the full log on every tick.
  • [x] geth auth grant/revoke --signing-key records signed auth ops.

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

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

  • [x] geth auth grant and geth auth revoke persist signed local auth ops when run through the CLI.
  • [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.
  • [x] Replicated auth sync requires trusted-admin signatures before import.
  • [x] Human and JSON output include diagnostics for discovered-only peers, missing and matched endpoint bindings, matching grants, revoked grants, and bearer access.

• [x] 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.
  • [x] geth secret bearer challenge/prove/verify exercises resource-scoped bearer challenge-response proofs.
  • [x] Tests verify valid bearer proofs and capability-scoped proof denial.
  • [x] Remote module authorization paths accept optional bearer proofs for the requested resource capability without granting node identity.
  • [x] Tests verify remote CAS fetch succeeds through a bearer proof before the caller has a node grant.
  • [x] Bearer creation separates the persisted public bearer id from the private bearer token returned to the caller.
  • [x] Bearer list/revoke operate on public bearer ids while proof and remote authorization use the private token.
  • [x] Tests verify the public bearer id differs from the private token and remote bearer auth uses the token.

• [x] 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 cert approve --sign can run ssh-keygen, import the resulting OpenSSH certificate, and mark the request signed.
  • [x] Tests cover signing with a generated local OpenSSH CA key when ssh-keygen is available.
  • [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] Background live-sync can be disabled or retuned with [sync] live_sync_enabled and live_sync_interval_ms.
  • [x] SSH metadata live-sync stores per-peer high-water cursors in module_state and requests only records at or beyond the cursor.
  • [x] Local SSH cert request/read/approve/import commands can enforce ssh_cert.request, ssh_cert.read, ssh_cert.approve, and ssh_cert.import for explicit non-owner --subject principals.
  • [x] Local SSH revocation publish/read/import commands can enforce ssh_revocation.publish, ssh_revocation.read, and ssh_revocation.import for explicit non-owner --subject principals.
  • [x] Tests cover denied and granted non-owner local SSH cert request and revocation publish flows.
  • [x] Sync import rejects conflicting certificate request, certificate, and revocation records with ids that already exist locally.
  • [x] Tests verify conflicting SSH cert request and revocation records do not overwrite local metadata.
  • [x] Accepted SSH cert/revocation records carry agent-key signed provenance over deterministic canonical payloads.
  • [x] Sync import rejects unsigned or invalidly signed cert-flow and revocation records that are not already-known conflicting ids.

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.

• [x] 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.
  • [x] Successful fetches record the serving peer as a local provider for the CAS hash.
  • [x] geth cas providers <hash> lists locally known providers.
  • [x] Tests cover local provider metadata storage.
  • [x] Replace the bootstrap control-ALPN byte transfer with iroh-blobs provider/fetch behavior using the daemon-owned iroh 1.0.0 endpoint and pinned iroh-blobs 0.103.0.
  • [x] CAS fetch keeps the geth control-ALPN authorization preflight before opening the native iroh-blobs payload transfer.
  • [x] Local CAS adds and daemon startup mirror available blobs into the native iroh-blobs store so peers can fetch them through /iroh-bytes/4.

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

• [x] Encrypted private blobs. Acceptance criteria:

  • [x] geth cas add-private <resource> <path> stores an encrypted CAS envelope instead of plaintext payload bytes.
  • [x] geth cas get-private <resource> <hash> --out <path> decrypts with a matching local resource secret epoch.
  • [x] Access is gated by local resource secret epoch material.
  • [x] New writes use an AES-256-GCM envelope with resource-bound associated data and random nonces.
  • [x] Prototype BLAKE3-XOR envelopes from earlier pre-deployment builds are rejected with a clear error.
  • [x] Tests verify encrypted blob roundtrip, tamper detection, wrong resource/secret rejection, old-envelope rejection, and nonce uniqueness.
  • [x] Docs explicitly avoid claiming forward secrecy or PCS.

• [x] 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.
  • [x] KV metadata is replicated through Iroh Documents.
  • [x] Authorized peers receive read-only Iroh Documents tickets, not write capabilities, after geth control authorization succeeds.
  • [x] Tests cover imported KV docs state after authorized remote sync.

• [x] 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>.
  • [x] geth pubsub sub <topic> --node <node-id> reads an authorized peer snapshot over Iroh.
  • [x] Remote pubsub subscribe requires pubsub.subscribe on resource:pubsub:<topic>.
  • [x] Tests cover denied and allowed remote pubsub subscribe.
  • [x] Replace bootstrap remote publish with iroh-gossip topics.
  • [x] Authorized remote publish/subscribe joins deterministic iroh-gossip topics after geth control authorization.
  • [x] 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.

• [x] 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>.
  • [x] geth pipe listen <name> --node <node-id> can register an authorized daemon-lifetime listener on an imported peer.
  • [x] Remote pipe listen requires pipe.listen on resource:pipe:<name>.
  • [x] Tests cover denied and allowed remote listener registration.
  • [x] geth pipe send <name> [message|--in <path>|--in -] --node <node-id> carries a byte message over the dedicated /geth/pipe/1 Iroh ALPN.
  • [x] geth pipe recv <name> drains daemon-lifetime pipe messages.
  • [x] Remote pipe send requires pipe.connect on resource:pipe:<name>.
  • [x] TCP forwarding carries bidirectional byte streams over Iroh.
  • [x] TCP streams close cleanly and propagate errors through the local forwarder logs.

• [x] TCP forwarding. Acceptance criteria:

  • [x] A local loopback TCP listener can forward over an authorized Iroh pipe with geth pipe forward-tcp.
  • [x] The remote side connects only to explicit loopback socket addresses in the prototype.
  • [x] Forwarding is resource-scoped with pipe.forward on resource:pipe-tcp:<target>.
  • [x] Tests cover address validation and TCP pipe wire request/response serialization.
  • [x] A conditional two-node integration test covers a TCP request/response forwarding exchange when local Iroh endpoint binding is available in the test environment.

• [x] Optional Iroh overlay network. Acceptance criteria:

  • [x] Add a focused geth-overlay crate for overlay names, CIDRs, resource IDs, capabilities, status, and plan models.
  • [x] Reserve /geth/overlay/1 in the daemon-owned Iroh protocol router.
  • [x] Add overlay as a resource kind and document capabilities: overlay.join, overlay.route, and overlay.admin.
  • [x] Add CLI/control commands for geth overlay status, plan, join, and leave.
  • [x] Prototype commands make clear that host networking changes require explicit overlay up.
  • [x] Tests cover overlay validation and control serialization.
  • [x] Persist overlay network configuration and membership state as resource metadata.
  • [x] Implement resource-authorized overlay join using resource secrets without granting node identity.
  • [x] Store only a secret fingerprint in overlay membership state.
  • [x] Tests cover persisted overlay join/status/leave and bearer-token enforcement for overlay.join.
  • [x] Add platform-specific, opt-in TUN/Wintun interface plans with generated-definition tests and no privileged test requirements.
  • [x] Route IPv4 packets over /geth/overlay/1 using the shared daemon Iroh endpoint.
  • [x] Validate overlay packet routing with two-node Iroh tests and overlay.route authorization checks.
  • [x] Add candidate peer listing from untrusted peer-card metadata.
  • [x] Implement actual TUN/Wintun-style activation as an explicit user opt-in through geth overlay up/down.
  • [x] Runtime reads validated IPv4 packets from the TUN device, routes them to imported peer cards by deterministic overlay IP, and injects authorized remote packets back into the device.
  • [x] Runtime activation surfaces privilege/setup errors clearly instead of silently falling back to a non-overlay transport.
  • [x] Add live peer/IP coordination over trusted resource metadata and untrusted discovery candidates.
  • [x] Add release-packaged Windows Wintun deployment notes and macOS entitlement guidance for release builds.

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

  • [x] Unix socket forwarding is available on Unix platforms through geth pipe forward-unix.
  • [x] Forwarding is resource-scoped with pipe.forward on resource:pipe-unix:<target>.
  • [x] Unix socket paths must be absolute and reject parent-directory components.
  • [x] Tests cover Unix path validation and pipe wire request serialization.
  • [x] Unsupported platforms return clear errors.
  • [x] Tests cover a full two-node Unix socket forwarding exchange.

• [x] SSH proxy over Iroh. Acceptance criteria:

  • [x] geth ssh proxy <node> contacts an imported peer over the dedicated /geth/ssh-proxy/1 Iroh ALPN.
  • [x] Remote daemon checks ssh_proxy.connect on resource:ssh-proxy:local before returning proxy connection metadata.
  • [x] Tests cover denied and granted SSH proxy control-plane attempts.
  • [x] Knowing an EndpointID alone cannot reach sshd.
  • [x] The proxy opens a dedicated authorized Iroh byte stream.
  • [x] Remote daemon connects that stream to local sshd at 127.0.0.1:22 only after authorization.
  • [x] Future completion adds a restricted built-in geth admin shell option.

• [x] 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.
  • [x] Replace pull-only metadata sync with a resource log or CRDT model.
  • [x] Sync responses carry ordered SSH distribution log entries derived from signed cert requests, signed certificate imports, and signed revocation records.
  • [x] Conflicting records with already-known ids are rejected during import rather than replacing local metadata.
  • [x] Unsigned records are rejected during sync import once signed provenance is part of the metadata format.

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

• [x] DB sync over Iroh. Acceptance criteria:

  • [x] geth db sync <node-id> <name> exists and talks to the daemon.
  • [x] Remote DB sync uses the protected Iroh control ALPN.
  • [x] The serving peer validates the caller's signed peer card against the observed Iroh EndpointID before considering authorization.
  • [x] Remote DB sync requires db.sync on the remote resource:db:<name>.
  • [x] The response carries typed crsql_changes batches plus schema metadata.
  • [x] The requester detects schema mismatch before advancing the sync cursor.
  • [x] Background live-sync runs DB sync for local DB resources and known peers.
  • [x] Per-peer/per-DB high-water cursors are stored in module_state.
  • [x] Extracted batches are exposed through geth db changes.
  • [x] Compatible remote batches are inserted into the local crsql_changes table or view before advancing the cursor.
  • [x] Tests cover typed batch application into deterministic fixture crsql_changes tables.
  • [x] A real cr-sqlite-enabled two-node integration test is blocked in this dev environment because no sqlite3 CLI or cr-sqlite extension artifact is available. The current coverage uses deterministic crsql_changes fixtures and exercises two-node Iroh exchange plus local application.
  • [x] CAS-backed DB snapshots/batches are deferred beyond the prototype. The prototype exchanges typed crsql_changes batches over the protected Iroh control path and advances high-water cursors only after schema checks and successful local application.

• [x] Automerge document resource. Acceptance criteria:

  • [x] geth document create/status works for local documents.
  • [x] Document metadata and empty Automerge state are stored durably.
  • [x] geth document set/get stores durable Automerge save bytes and returns a validated JSON view.
  • [x] Tests cover create, update, save, and reload of local Automerge document state.
  • [x] geth document sync <node-id> <name> pulls authorized Automerge state from an imported peer over Iroh.
  • [x] Background live-sync refreshes local Automerge documents from known peers using per-peer/per-document cursors.
  • [x] Automerge document state is stored durably.
  • [x] Tests cover Automerge create, update, save, and reload.

• [x] Automerge sync over Iroh. Acceptance criteria:

  • [x] Automerge state sync works across two local test nodes over Iroh.
  • [x] Resource authorization gates read/write sync.
  • [x] Received Automerge documents are merged rather than stored as raw JSON blobs.

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.

• [x] 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.
  • [x] geth cas root sync <node-id> <name> pulls authorized remote file-root tree metadata over the protected Iroh control path.
  • [x] Remote file-root sync requires cas.fetch on resource:cas-tree:<name>.
  • [x] Sync imports CAS tree bytes and records a peer-qualified remote root with path remote:<node>:<name> without writing files into the working tree or overwriting same-named local roots.
  • [x] Background live-sync imports updated authorized file-root trees from sync-status cas-tree:<name> watermarks and stores per-peer cursors.
  • [x] geth cas root apply <root> --to <path> materializes missing files and directories from a CAS tree without deleting extras or overwriting local edits.
  • [x] Apply records durable conflicts for differing local paths.
  • [x] geth cas root apply <root> --to <path> uses a registered local root's previous scan as the base for automatic safe creates, updates, deletes, and renames when the current local filesystem still matches that base.
  • [x] Ambiguous three-way changes remain durable conflicts instead of being overwritten.

• [x] 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.
  • [x] Future sync records conflicts automatically from base/local/remote tree comparisons.
  • [x] 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.