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

For deployment-readiness work that cuts across feature areas, see
[`docs/production-readiness-roadmap.md`](production-readiness-roadmap.md).

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

## Prototype Viability Closure Plan

These are the remaining gaps that must close before the prototype is a smooth
end-to-end test target for the intended personal mesh use cases.

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.

- `[~]` 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.
  - `[ ]` 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 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]` 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, macOS, and Windows archives for `v*`
    tags and manual dispatch.
  - `[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]` `geth sync now [node]` triggers the same best-effort sync pass that
    background live sync uses.
  - `[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 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]` Tests verify encrypted blob roundtrip and wrong resource/secret
    rejection.
  - `[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.