# 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 status
geth node id
geth resource list
geth cas add ./file
```

The daemon owns local identity, the future 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`.

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

SSH keys are used as admin trust anchors and ecosystem integration points.
OpenSSH, FIDO, and YubiKey-backed keys can sign geth trust objects through
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.

## MVP Features

The bootstrap implementation provides:

- `geth init`
- `geth daemon run`
- `geth status`
- `geth node id`
- `geth resource list`
- `geth resource create <kind> <name>`
- `geth keychain status`
- `geth auth explain <subject> <resource> <capability>`
- local filesystem CAS commands: `add`, `get`, `hash`, `has`, `list`

Other command groups exist as explicit stubs: `db`, `kv`, `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
  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.