Bootstrap geth Rust workspace

docs/architecture.md

@@ -0,0 +1,88 @@
+# 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.