176 lines
6.2 KiB
Markdown
176 lines
6.2 KiB
Markdown
# geth
|
|
|
|
`geth` is a personal, local-first mesh runtime for scripts, devices, databases,
|
|
documents, blobs, pipes, and future multi-user collaboration.
|
|
|
|
This project is not the Ethereum `geth` client. The project and executable are
|
|
still named `geth`.
|
|
|
|
## One Binary
|
|
|
|
There is one executable: `geth`.
|
|
|
|
It has daemon mode and control mode:
|
|
|
|
```sh
|
|
geth init
|
|
geth daemon run
|
|
geth daemon service install
|
|
geth status
|
|
geth node id
|
|
geth resource list
|
|
geth cas add ./file
|
|
```
|
|
|
|
The daemon owns local identity, the Iroh endpoint, trust state, resource
|
|
registry, module router, local metadata store, and synchronized data structures.
|
|
Most non-daemon commands talk to the daemon through a local Unix socket at
|
|
`$GETH_HOME/run/geth.sock`.
|
|
|
|
The daemon can also install itself as a user service:
|
|
|
|
```sh
|
|
geth daemon service install
|
|
geth daemon service status
|
|
geth daemon service uninstall
|
|
```
|
|
|
|
The bootstrap service managers are systemd user units on Linux, launchd user
|
|
agents on macOS, and per-user scheduled tasks on Windows. These are user-level
|
|
services, not system services.
|
|
|
|
## Transport And SSH
|
|
|
|
All remote node-to-node geth communication is designed to happen over Iroh only.
|
|
SSH is not a geth transport backend, and there is no SSH fallback transport.
|
|
The default node config uses Iroh's default relay policy for practical
|
|
connectivity; set `[iroh].relay_mode = "disabled"` for local-only/offline
|
|
development. Named custom relay maps can be selected with
|
|
`relay_mode = "custom"` and `relay_map = "<name>"`. Iroh local-network
|
|
discovery is enabled by default with `[iroh].local_discovery = true`.
|
|
|
|
SSH keys are used as admin trust anchors and ecosystem integration points.
|
|
OpenSSH, FIDO, and YubiKey-backed keys can sign geth trust objects through
|
|
canonical geth envelopes with explicit namespaces such as
|
|
`geth.keychain.v1@geth.local`. Future SSH proxying may carry SSH protocol bytes
|
|
over authorized Iroh streams, but the geth transport remains Iroh.
|
|
|
|
SSH certificate request and renewal flows are managed as geth metadata. A node
|
|
can create a certificate request, another machine can approve it and receive an
|
|
explicit `ssh-keygen -s ...` command suitable for a CA key or YubiKey-backed CA,
|
|
and the resulting `-cert.pub` can be imported for distribution. Certificate and
|
|
key revocation entries are tracked locally and can be exported as JSONL or as an
|
|
OpenSSH KRL specification file for later `ssh-keygen -k` use. Future Iroh
|
|
replication will distribute these records between authorized nodes.
|
|
|
|
## MVP Features
|
|
|
|
The bootstrap implementation provides:
|
|
|
|
- `geth init`
|
|
- `geth daemon run`
|
|
- `geth daemon service install|uninstall|start|stop|status|print`
|
|
- `geth status`
|
|
- `geth node id`
|
|
- `geth resource list`
|
|
- `geth resource create <kind> <name>`
|
|
- `geth keychain init [--admin-key <path>]`
|
|
- `geth keychain status`
|
|
- `geth secret status`
|
|
- `geth secret create <resource>`
|
|
- `geth secret rotate <resource>`
|
|
- `geth secret bearer create <resource> --capability <capability>`
|
|
- `geth secret bearer list`
|
|
- `geth secret bearer revoke <resource> <secret>`
|
|
- `geth auth explain <subject> <resource> <capability>`
|
|
- `geth auth grant <subject> <resource> <capability> [--grant-id <id>]`
|
|
- `geth auth revoke <resource> <grant-id>`
|
|
- local filesystem CAS commands: `add`, `get`, `hash`, `has`, `pin`, `unpin`,
|
|
`cleanup`, `list`
|
|
- local DB resource registration: `geth db add <name> <path>` and
|
|
`geth db status <name>` with schema and `crsql_changes` metadata; the DB
|
|
crate and daemon can extract typed local `crsql_changes` batches through
|
|
`geth db changes <name>` for future sync
|
|
- local SQLite-backed KV commands: `geth kv create/set/get`
|
|
- local JSON document commands: `geth document create/status/set/get`
|
|
- local daemon-lifetime pubsub snapshots: `geth pubsub pub/sub`
|
|
- SSH certificate flow metadata:
|
|
- `geth ssh cert request --public-key <path> --principal <name>`
|
|
- `geth ssh cert requests`
|
|
- `geth ssh cert approve <request-id> --ca-key <path>`
|
|
- `geth ssh cert import <request-id> --cert <path>`
|
|
- `geth ssh cert list`
|
|
- `geth ssh revocation add <kind> <target>`
|
|
- `geth ssh revocation list`
|
|
- `geth ssh revocation export --out <path> [--format jsonl|openssh-krl-spec]`
|
|
- local pipe registry commands: `geth pipe listen/connect`
|
|
|
|
Other command groups exist as explicit stubs: `ssh`.
|
|
|
|
## Resource Modules
|
|
|
|
Everything meaningful is modeled as a resource. Planned resource kinds are:
|
|
|
|
- `db`: SQLite/cr-sqlite synchronization
|
|
- `kv`: Iroh Documents backed key-value stores
|
|
- `pipe`: dumbpipe-like byte streams over Iroh; the bootstrap has a local
|
|
daemon registry only
|
|
- `document`: Automerge documents over Iroh streams
|
|
- `pubsub`: lossy notifications, not authoritative storage; the bootstrap
|
|
keeps only an in-memory daemon-lifetime ring buffer
|
|
- `cas`: content-addressed blob storage and distribution
|
|
- `ssh-proxy`: authorized SSH proxy/admin access over Iroh
|
|
|
|
Authorization is resource-scoped and capability-based. Bearer secrets may grant
|
|
specific resource capabilities but do not create trusted node identity. The auth
|
|
evaluator supports scoped KV write grants such as `kv.write_prefix:apps/foo/`
|
|
for `kv.write_key:apps/foo/config` explain checks; command-level KV enforcement
|
|
is still future work.
|
|
|
|
## Local State
|
|
|
|
If `GETH_HOME` is set, geth uses it. Otherwise it uses an OS-specific data
|
|
directory. The bootstrap layout is:
|
|
|
|
```text
|
|
$GETH_HOME/
|
|
geth.sqlite
|
|
config.toml
|
|
identity/agent.ed25519
|
|
identity/iroh.ed25519
|
|
cas/blobs/
|
|
run/geth.sock
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
In one shell:
|
|
|
|
```sh
|
|
export GETH_HOME="$(mktemp -d)"
|
|
cargo run -p geth -- init
|
|
cargo run -p geth -- daemon run
|
|
```
|
|
|
|
In another shell:
|
|
|
|
```sh
|
|
export GETH_HOME="<same dir>"
|
|
cargo run -p geth -- status
|
|
cargo run -p geth -- node id
|
|
echo "hello geth" > /tmp/hello-geth.txt
|
|
cargo run -p geth -- cas add /tmp/hello-geth.txt
|
|
cargo run -p geth -- cas list
|
|
```
|
|
|
|
## Authorization Direction
|
|
|
|
The MVP defines the split between:
|
|
|
|
- keychain: SSH-rooted users, devices, nodes, agents, and endpoint bindings
|
|
- auth: resource-local signed authorization operations and capability grants
|
|
- secrets: resource master secrets, epochs, envelopes, and bearer access
|
|
|
|
The current code does not implement Keyhive, BeeKEM, strong forward secrecy, or
|
|
post-compromise security. It leaves room for future local-first, replicated auth
|
|
logs and BeeKEM/CGKA-style group key evolution.
|