geth/README.md

# 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 for
distribution. 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 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>`
- local SQLite-backed KV commands: `geth kv create/set/get`
- 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>`

Other command groups exist as explicit stubs: `pipe`, `document`, `pubsub`,
`secret`, and `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
- `document`: Automerge documents over Iroh streams
- `pubsub`: lossy notifications, not authoritative storage
- `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.

## 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.