88 lines
3.5 KiB
Markdown
88 lines
3.5 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.
|
|
|
|
## 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.
|