111 lines
4.2 KiB
Markdown
111 lines
4.2 KiB
Markdown
# 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 exist.
|
|
- Custom relay maps, mDNS discovery, 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.
|