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

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. [~] 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.
   • [ ] Add tests proving conflicting replicated keychain/auth records do not mutate trust/resource state.
   • [ ] Improve auth explain diagnostics enough for operators to distinguish discovered-only peers, missing endpoint bindings, missing grants, matching grants, revocations, and bearer access.

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

   • [ ] CAS uses iroh-blobs or has a documented pinned blocker.
   • [ ] KV uses Iroh Documents or has a documented pinned blocker.
   • [ ] Pubsub uses iroh-gossip or has a documented pinned blocker.

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

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

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

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

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

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

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

   • [ ] README has a two-machine walkthrough for the main smoke tests.
   • [ ] CLI recovery errors tell operators the next command to run.
   • [ ] JSON sync status is script-friendly for stale/failed peer detection.

• [~] 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.
  • [ ] Tests assert conflicting replicated keychain/auth records do not mutate local trust or resource state.

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

  • [ ] Every remote mutable operation has an explicit resource capability check before mutating local state or opening a host service.
  • [ ] 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.
  • [ ] auth explain output can explain discovered-only peers, missing endpoint bindings, missing grants, matching grants, revocations, and bearer access.

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

  • [ ] CAS fetch/provider paths use iroh-blobs or a documented pinned equivalent instead of bootstrap control-ALPN blob transfer.
  • [ ] KV metadata and entries replicate through Iroh Documents or a documented pinned equivalent.
  • [ ] Pubsub wakeups/presence use iroh-gossip or a documented pinned equivalent.
  • [ ] Fallback/stub behavior remains clearly marked where APIs are not yet pinned.

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

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

• [~] Durable Automerge documents. Acceptance criteria:

  • [ ] Document state is stored as durable Automerge data, not only JSON last-writer-wins state.
  • [ ] Sync converges according to Automerge semantics across two nodes.
  • [ ] Resource authorization gates remote document reads and writes.

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

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

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

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

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

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

• [~] 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.
  • [ ] Replace the bootstrap control-ALPN transfer with iroh-blobs provider/fetch behavior.

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

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

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

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

  • [x] geth pubsub pub/sub works against the local daemon.
  • [x] Local pubsub messages are kept in a bounded daemon-lifetime ring buffer.
  • [x] Pubsub messages are documented and tested as lossy notifications, not durable facts.
  • [x] geth pubsub pub <topic> <message> --node <node-id> publishes to an imported peer over Iroh.
  • [x] Remote pubsub publish requires pubsub.publish on resource:pubsub:<topic>.
  • [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.
  • [ ] Replace bootstrap remote publish with iroh-gossip topics.
  • [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.

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

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

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

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

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

• [~] 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.
  • [ ] Add an integration test with a real cr-sqlite-enabled SQLite DB that proves two local test nodes exchange and apply changes.
  • [ ] Optional CAS-backed snapshots or batches are documented if used.

• [~] Automerge document resource. Acceptance criteria:

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

• [ ] Automerge sync over Iroh. Acceptance criteria:

  • [x] Bootstrap JSON last-writer-wins sync works across two local test nodes over Iroh.
  • Resource authorization gates read/write sync.
  • Conflicts converge according to Automerge semantics.

Phase 6: File Sync And Advanced Local-First Auth

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

• [x] CAS tree objects. Acceptance criteria:

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

• [~] File roots. Acceptance criteria:

  • [x] A file root maps a local path to a CAS tree resource.
  • [x] geth cas root add/list/scan persists local root metadata and latest tree state.
  • [x] Scan detects create/update/delete/rename changes.
  • [x] Scan output documents that geth never overwrites file roots without a recorded future sync decision.
  • [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.
  • [ ] Future completion adds a richer three-way apply using base/local/remote trees for automatic safe updates and deletes.

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