geth/docs/architecture.md

Architecture

geth is a single-binary local-first mesh runtime. One executable provides both daemon mode and control mode. The daemon owns local identity, metadata storage, the future shared Iroh endpoint, resource registry, module routing, and local control socket. Control commands connect to the Unix socket and send typed JSONL requests.

Iroh-Only Remote Communication

Remote geth node-to-node communication is Iroh-only. The daemon will own one shared Iroh endpoint and register module protocols on ALPNs such as /geth/cas/1, /geth/kv/1, /geth/pipe/1, and /geth/ssh-proxy/1.

SSH keys are not transport keys. They are admin trust anchors and signing identities for keychain and authorization operations. SSH proxying, when added, will carry SSH bytes over an authorized Iroh stream and will not make SSH a geth transport backend.

Resource Model

Everything meaningful is modeled as a resource. Resources have a kind, name, authority reference, local role, replication policy, retention policy, and status. Authorization is resource-scoped and capability-based.

Resource kinds:

• db: cr-sqlite-backed SQLite synchronization
• kv: Iroh Documents backed key-value data
• pipe: authorized byte streams and forwarding
• document: Automerge CRDT documents
• pubsub: lossy notifications and presence
• cas: content-addressed blobs
• ssh-proxy: SSH/admin proxying over Iroh

Module Overview

geth-cas is implemented locally first using BLAKE3 hashes and filesystem blob storage. Iroh-blobs, providers, encrypted blobs, manifests, and file sync trees are future work.

geth-kv, geth-db, geth-document, geth-pubsub, geth-pipe, and geth-ssh-proxy currently define types, command shape, and roadmap stubs.

Keychain, Auth, And Secrets

The identity plane is geth-keychain: admin keys, users, devices, nodes, agents, and endpoint bindings. Endpoint rotation must not destroy higher-level node identity.

The authorization plane is geth-auth: resource-local signed operation logs, grants, revocations, groups, and auth explain.

The payload access plane is geth-secrets: resource master secrets, epochs, key envelopes, bearer secrets, and rotation. Revocation for private data is modeled initially as secret epoch rotation.

Multi-User Direction

The project is structured for future multi-user local-first authorization:

• authorization is replicated data, not one mutable ACL blob
• resources can carry or delegate to their own auth state
• users, devices, nodes, agents, and endpoints are separate principals
• capabilities are the underlying permission unit
• bearer access is resource-scoped and does not mutate the trust graph
• offline revocation is eventual
• encryption key distribution is part of authorization

Keyhive/BeeKEM Roadmap

Resource secret epochs are the v0/v1 approximation for private payload access. Later designs can add Keyhive-like convergent capabilities and BeeKEM/CGKA-style group key evolution. The bootstrap does not implement BeeKEM and does not claim strong forward secrecy or post-compromise security.

Security Invariants

• All remote node-to-node communication is over Iroh.
• SSH is not a geth transport.
• SSH keys are admin trust anchors and signing identities.
• Agent/node keys handle routine local identity.
• Discovery is untrusted.
• Knowing an EndpointID does not grant access.
• Bearer secrets are resource-scoped capabilities.
• Bearer access does not imply trust graph mutation rights.
• Authorization is capability-based and resource-scoped.
• Network and control decoders treat input as untrusted.