eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
geth/AGENTS.md

7.1 KiB
Raw Blame History

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:

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

Also run clippy when reasonable:

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, 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. Signature validation and 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 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 or OpenSSH KRL specification text. Binary KRL generation/import is still roadmap work.
  • Signed peer-card LAN discovery payloads, peer auth over Iroh, cr-sqlite, iroh-docs, iroh-blobs, Automerge sync, real auth enforcement, OpenSSH KRL generation, and Keyhive/BeeKEM-style authorization are future roadmap items unless implemented later.