geth/AGENTS.md

# AGENTS.md

This repository is `geth`, a Rust monorepo for a personal, local-first,
Iroh-based mesh runtime. It is not the Ethereum geth client.

`geth` has one executable only:

- daemon mode: `geth daemon run`
- control mode: `geth status`, `geth node ...`, `geth cas ...`, etc.

Do not add separate `gethd` or `gethctl` binaries.

## Core Invariants

- All remote geth node-to-node communication must be over Iroh.
- SSH is not a geth transport and must not become a fallback transport.
- SSH keys are admin trust anchors and ecosystem integration points.
- SSH certificate flows and SSH proxying are geth-managed workflows carried by
  local control now and Iroh later.
- The daemon owns the Iroh endpoint, local identity, local metadata store,
  resource registry, module routing, and synchronized data structures.
- Discovery is untrusted and never grants capabilities or trust.
- Authorization is resource-scoped and capability-based.
- Signed data must use deterministic canonical encoding, not arbitrary JSON.
- Bearer secrets may grant resource-specific access but must not create trusted
  node identity or trust graph mutation rights.

## Workspace Shape

- Binary crate: `crates/geth`
- CLI definitions and formatting: `crates/geth-cli`
- Daemon orchestration and local control: `crates/geth-node`
- Local JSONL control protocol: `crates/geth-control`
- Shared newtypes: `crates/geth-types`
- Canonical encoding/hash helpers: `crates/geth-codec`
- Config/path handling: `crates/geth-config`
- Local SQLite metadata store: `crates/geth-store`
- Local CAS: `crates/geth-cas`
- SSH trust/cert models: `crates/geth-ssh-identity`

Keep crates focused. Do not create a `geth-common` crate.

## Implementation Rules

- Prefer existing crate boundaries and patterns.
- Libraries should use `thiserror`; binaries may use `anyhow`.
- Keep async only where it is useful.
- Treat network and control inputs as untrusted.
- Do not implement complex cryptographic protocols casually. Add types,
  roadmap notes, and explicit non-claims when a feature is only scaffolded.
- Do not claim Keyhive/BeeKEM-level security properties until they are actually
  designed, implemented, and tested.
- User service installation must target user service managers, not system
  service managers.

## Testing Requirements

Every behavior change should include tests proportional to risk:

- Add unit tests for pure data models, reducers, encoders, path generation, and
  command builders.
- Add integration tests for CLI/daemon behavior when practical.
- Use temp directories and temp `GETH_HOME` values.
- Avoid tests that require privileged services, real YubiKeys, real network
  relays, or host service-manager mutation.
- For platform-specific behavior, use generated-definition tests or cfg guards.

Before finishing a code change, run at least:

```sh
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace
```

Also run clippy when reasonable:

```sh
cargo clippy --workspace --all-targets -- -D warnings
```

If a command cannot be run, state why in the final report.

## Documentation And Roadmap

Keep documentation updated with behavior changes:

- Update `README.md` for user-visible commands or workflows.
- Update `docs/architecture.md` for architectural boundaries or invariants.
- Add or update ADRs in `docs/adr/` for durable decisions.
- Update `docs/roadmap.md` whenever a feature is added, completed, split, or
  deferred.

Roadmap items should be actionable and checkable:

- Use `[ ]`, `[~]`, or `[x]`.
- Include acceptance criteria.
- Split vague items before implementation.
- Do not mark an item done unless the acceptance criteria are met or revised
  honestly.

## Current Feature Boundaries

- Local daemon, local control socket, local identity, local store, local CAS,
  daemon-owned Iroh endpoint startup, built-in relay-mode config, SSH
  certificate metadata, revocation metadata, user service definitions, and a
  pinned `geth-iroh` endpoint wrapper with protocol-router scaffold, peer-card
  types, manual signed peer-card export/import/list commands, `geth peer ping`
  and `geth peer auth-check` over Iroh, signed peer-card LAN discovery payloads,
  authorized `geth cas fetch`, `geth ssh cert sync`, and
  `geth ssh revocation sync` over the Iroh control ALPN, untrusted
  discovery-backend trait, custom relay-map config, and Iroh local-network
  discovery toggle exist.
- Canonical signed-operation envelopes exist for keychain/auth signature
  payloads. The keychain reducer builds an active identity view for admin keys,
  users, devices, nodes, agents, and endpoint bindings.
- The auth reducer builds a current permission view for resources, grants,
  groups, and bearer access. The daemon persists local auth grant/revoke ops
  and uses them for `auth explain`. `kv set --subject <principal>` enforces
  local KV write grants for non-local test callers. Signature validation and
  broader daemon-side module enforcement are still roadmap work.
- The daemon persists local keychain init/admin-key ops and reduces them for
  `keychain status`. SSH signature capture/verification is still roadmap work.
- Local CAS supports pin/unpin metadata, surfaced through `cas list`, and
  `cas cleanup` evicts unpinned blobs while retaining pinned blobs. The daemon
  can fetch CAS blobs from an imported signed peer card over Iroh when the peer
  grants `cas.fetch` on `resource:cas:local`; full `iroh-blobs` provider
  integration is still roadmap work.
- The CAS crate can build deterministic tree objects for local file trees and
  store those manifests as CAS blobs. The daemon can register and scan local
  file roots, reporting create/update/delete/rename changes without writing back
  to the working tree. Durable local file-conflict records can be listed and
  resolved manually; automatic cross-node conflict detection and file sync are
  still roadmap work.
- DB resources can be registered locally and report local-only status plus a
  read-only SQLite schema summary/hash and `crsql_changes` metadata when
  present. The DB crate and daemon can extract typed read-only `crsql_changes`
  batches through `geth db changes` for future sync messages. cr-sqlite loading,
  applying remote changes, and sync are still roadmap work.
- KV stores support local SQLite-backed create/set/get. Iroh Documents
  replication and command-level prefix-capability enforcement are still roadmap
  work. The auth evaluator already understands `kv.write_prefix:<prefix>`
  grants for `kv.write_key:<key>` requests.
- Document resources can be registered locally and updated with validated local
  JSON state. Automerge editing/state and sync are still roadmap work.
- Pubsub supports local daemon-lifetime publish/subscribe snapshots through a
  bounded in-memory ring buffer. Iroh-gossip replication, private topics, and
  pubsub capability enforcement are still roadmap work.
- Pipe listen/connect supports a local daemon-lifetime registry only. Iroh byte
  streams, TCP/Unix forwarding, and pipe capability enforcement are still
  roadmap work.
- Resource secret epoch metadata can be created, rotated, and listed locally.
  Bearer access metadata can be created/listed/revoked as resource-scoped auth
  ops and must not allow trust graph mutation capabilities. Payload encryption,
  key envelopes, and bearer challenge-response are still roadmap work.
- SSH revocations can be exported as JSONL, OpenSSH KRL specification text, or
  binary OpenSSH KRL files generated through `ssh-keygen`. JSONL and OpenSSH KRL
  specification imports are supported; binary KRL import is unsupported because
  OpenSSH KRL files are not enumerable through OpenSSH tooling. Tests cover
  public-key and certificate binary KRL revocations when `ssh-keygen` is
  available. Authorized peers can pull SSH certificate-flow metadata with
  `ssh_cert.sync` on `resource:ssh:certs` and revocation metadata with
  `ssh_revocation.sync` on `resource:ssh:revocations`; this is pull-only
  metadata sync, not yet a CRDT/resource-log replication model.
- cr-sqlite, iroh-docs, iroh-blobs provider/fetch, Automerge sync, broader auth
  enforcement, and Keyhive/BeeKEM-style authorization are future roadmap items
  unless implemented later.