131 lines
6 KiB
Markdown
131 lines
6 KiB
Markdown
# 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.
|
|
|
|
Service management is also exposed through the single binary. `geth daemon
|
|
service ...` installs and controls a user-level service definition for the local
|
|
daemon. The initial backends are systemd user units on Linux, launchd user agents
|
|
on macOS, and per-user scheduled tasks on Windows. Geth does not install itself
|
|
as a privileged system service.
|
|
|
|
## 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`.
|
|
|
|
The first pinned Iroh integration uses `iroh = 0.90.0`, because newer
|
|
Rust-1.85-compatible candidates in the 0.93-0.95 range failed to compile through
|
|
a transitive `ed25519-dalek` prerelease dependency. `geth-iroh` wraps
|
|
`iroh::Endpoint::builder()`, configures geth ALPNs with `Builder::alpns`, uses
|
|
`Builder::relay_mode`, persists an `iroh::SecretKey` as hex-encoded 32-byte key
|
|
material, and shuts down through `Endpoint::close().await`. Relay mode defaults
|
|
to disabled until daemon policy and discovery are implemented.
|
|
|
|
The target product should use Iroh relay support for practical internet
|
|
connectivity and mDNS/LAN discovery for local networks. These are connectivity
|
|
and candidate-discovery mechanisms only. They do not grant trust, mutate
|
|
authorization state, or make EndpointID knowledge sufficient for access.
|
|
|
|
The daemon starts this endpoint during `geth daemon run` and keeps it alive for
|
|
the daemon lifetime. When endpoint startup succeeds, the Iroh EndpointID is
|
|
recorded as a transport binding for the stable geth node identity. If local UDP
|
|
binding is unavailable, the daemon keeps local control running and reports the
|
|
Iroh startup error through status output.
|
|
|
|
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.
|
|
|
|
SSH certificate flows use the same split. Nodes can request new OpenSSH
|
|
certificates or renewals through geth metadata. A machine with the CA key or
|
|
YubiKey can approve the request and run an explicit `ssh-keygen -s ...` command,
|
|
then import the resulting certificate for distribution. Certificate and key
|
|
revocations are stored as signed-list-ready records and will be replicated over
|
|
Iroh in later phases.
|
|
|
|
## 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.
|
|
|
|
`geth-ssh-identity` defines SSH trust namespaces plus certificate request,
|
|
approval, certificate import, and revocation-list data models. The bootstrap
|
|
persists these flows locally and exports revocations as JSONL. It does not yet
|
|
generate OpenSSH KRL binaries or replicate the lists over Iroh.
|
|
|
|
## 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.
|
|
- SSH certificate issuance must be explicitly approved by an authorized
|
|
principal before signing.
|
|
- SSH certificate and key revocations are durable metadata that should be
|
|
distributed over Iroh, not fetched through unauthenticated discovery.
|
|
- Network and control decoders treat input as untrusted.
|
|
- Service installation targets user service managers, not system service
|
|
managers.
|