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, untrusted discovery-backend trait, and custom relay-map config exist.
- mDNS discovery transport, peer auth over Iroh, cr-sqlite, iroh-docs,
  iroh-gossip, iroh-blobs, Automerge sync, real auth enforcement, OpenSSH KRL
  generation, and Keyhive/BeeKEM-style authorization are future roadmap items
  unless implemented later.