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

6.8 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. File roots, scan workflows, and sync conflict handling 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.