Add actionable roadmap and agent guidance
This commit is contained in:
parent
f302342b1c
commit
b892dc6165
2 changed files with 392 additions and 48 deletions
323
docs/roadmap.md
323
docs/roadmap.md
|
|
@ -1,64 +1,299 @@
|
|||
# Roadmap
|
||||
|
||||
This roadmap is intended to be checkable. Each item should either be completed
|
||||
with tests/docs or split into smaller items before implementation.
|
||||
|
||||
Status markers:
|
||||
|
||||
- `[ ]` Not started
|
||||
- `[~]` In progress
|
||||
- `[x]` Done
|
||||
|
||||
## Phase 0: Bootstrap
|
||||
|
||||
- single CLI
|
||||
- local daemon
|
||||
- local store
|
||||
- local identity
|
||||
- local CAS
|
||||
- user service installer for systemd, launchd, and Windows scheduled tasks
|
||||
- docs and ADRs
|
||||
Goal: establish a compiling single-binary local runtime with local state, local
|
||||
control, local CAS, service installation, and written architecture decisions.
|
||||
|
||||
- `[x]` Single `geth` binary with daemon and control modes.
|
||||
Acceptance criteria:
|
||||
- `cargo run -p geth -- init` initializes a temp `GETH_HOME`.
|
||||
- `cargo run -p geth -- daemon run` starts one local daemon.
|
||||
- No `gethd` or `gethctl` binaries exist in the workspace.
|
||||
|
||||
- `[x]` Local daemon control socket.
|
||||
Acceptance criteria:
|
||||
- Control request/response types roundtrip through JSONL serialization.
|
||||
- `geth status` and `geth node id` talk to a running daemon.
|
||||
- Control decoding treats input as untrusted and returns structured errors.
|
||||
|
||||
- `[x]` Local metadata store and identity.
|
||||
Acceptance criteria:
|
||||
- SQLite migrations are idempotent.
|
||||
- Agent identity persists across repeated opens of the same `GETH_HOME`.
|
||||
- Store schema includes resources, auth/keychain logs, CAS, peers, modules,
|
||||
SSH cert requests, certificates, and revocations.
|
||||
|
||||
- `[x]` Local filesystem CAS.
|
||||
Acceptance criteria:
|
||||
- `geth cas add/hash/has/get/list` work through the daemon.
|
||||
- Blob paths use BLAKE3 hashes under `cas/blobs/<aa>/<bb>/<hash>`.
|
||||
- Unit or integration tests verify bytes roundtrip unchanged.
|
||||
|
||||
- `[x]` User service installer.
|
||||
Acceptance criteria:
|
||||
- `geth daemon service print --manager systemd|launchd|windows-task` prints
|
||||
the expected user-level service definition or command.
|
||||
- Linux install targets a systemd user unit, not a system service.
|
||||
- macOS install targets a launchd user agent.
|
||||
- Windows install targets a per-user scheduled task.
|
||||
- Tests verify generated definitions do not target privileged system services.
|
||||
|
||||
- `[x]` Bootstrap docs and ADRs.
|
||||
Acceptance criteria:
|
||||
- README explains what geth is and what it is not.
|
||||
- Architecture docs state Iroh-only remote communication and SSH trust role.
|
||||
- ADRs cover single binary, Iroh-only transport, resources, auth, SSH, CAS,
|
||||
synchronized structures, service installation, and SSH certificate flows.
|
||||
|
||||
## Phase 1: Iroh Foundation
|
||||
|
||||
- Iroh endpoint
|
||||
- peer cards
|
||||
- peer discovery
|
||||
- peer exchange
|
||||
- basic authenticated peer connection
|
||||
- additional user service manager backends where useful
|
||||
Goal: make the daemon own a real Iroh endpoint and establish authenticated
|
||||
geth-to-geth connections without granting trust from discovery alone.
|
||||
|
||||
- `[ ]` Pin and compile Iroh dependencies.
|
||||
Acceptance criteria:
|
||||
- `iroh` is added only after APIs are pinned and `cargo check --workspace`
|
||||
passes.
|
||||
- `geth-iroh` exposes endpoint startup/shutdown wrappers.
|
||||
- Docs note exact crate versions and any API assumptions.
|
||||
|
||||
- `[ ]` Daemon-owned Iroh endpoint.
|
||||
Acceptance criteria:
|
||||
- The daemon creates one shared Iroh endpoint on startup.
|
||||
- `geth status --json` reports endpoint status and EndpointID.
|
||||
- Endpoint identity is bound to agent/node identity in local metadata.
|
||||
- Restarting the daemon preserves higher-level node identity.
|
||||
|
||||
- `[ ]` Protocol/router scaffold.
|
||||
Acceptance criteria:
|
||||
- ALPN constants are registered through one module router.
|
||||
- Unknown ALPNs are rejected explicitly.
|
||||
- Tests cover registration collisions and unknown protocol handling.
|
||||
|
||||
- `[ ]` Peer cards.
|
||||
Acceptance criteria:
|
||||
- A peer card contains node ID, agent ID, endpoint candidates, timestamp, and
|
||||
signature metadata.
|
||||
- Peer cards are stored in `peer_cards`.
|
||||
- Invalid or unsigned peer cards do not update trust state.
|
||||
|
||||
- `[ ]` Untrusted discovery backend trait.
|
||||
Acceptance criteria:
|
||||
- Discovery returns candidate peer cards only.
|
||||
- No discovery result grants capabilities or trust.
|
||||
- `auth explain` can distinguish "discovered" from "trusted".
|
||||
|
||||
- `[ ]` Basic authenticated peer connection.
|
||||
Acceptance criteria:
|
||||
- A node can dial another node over Iroh using an EndpointID from a peer card.
|
||||
- The remote side proves an agent/node binding before module access.
|
||||
- Knowing only an EndpointID is insufficient to access a protected module.
|
||||
|
||||
## Phase 2: Trust And Authorization
|
||||
|
||||
- SSH-admin-rooted keychain
|
||||
- SSH certificate request and renewal queues
|
||||
- CA/YubiKey approval workflow
|
||||
- certificate and key revocation-list records
|
||||
- signed keychain ops
|
||||
- resource auth ops
|
||||
- grants and revocations
|
||||
- auth explain
|
||||
- resource secrets
|
||||
- bearer invites
|
||||
Goal: replace stubs with signed, reducible keychain/auth operation logs and
|
||||
resource-scoped capability decisions.
|
||||
|
||||
## Phase 3: CAS/KV/Pubsub
|
||||
- `[ ]` Canonical signed operation envelope.
|
||||
Acceptance criteria:
|
||||
- Keychain and auth ops use deterministic canonical encoding for signatures.
|
||||
- JSON is not used as the signed representation.
|
||||
- Tests verify equivalent operations hash/sign identically across runs.
|
||||
|
||||
- iroh-blobs CAS
|
||||
- iroh-docs KV
|
||||
- iroh-gossip pubsub
|
||||
- private topics and encrypted values
|
||||
- `[ ]` SSH-admin-rooted keychain initialization.
|
||||
Acceptance criteria:
|
||||
- `geth keychain init` records a signed `KeychainInit`.
|
||||
- OpenSSH signature namespaces are explicit.
|
||||
- Missing `ssh-keygen` or unavailable hardware keys produce clear errors.
|
||||
|
||||
## Phase 4: Pipes And SSH Proxy
|
||||
- `[ ]` Keychain operation reducer.
|
||||
Acceptance criteria:
|
||||
- Admin keys, users, devices, nodes, agents, and endpoint bindings reduce into
|
||||
a current keychain view.
|
||||
- Revoked keys/devices/nodes are excluded from active views.
|
||||
- Tests cover add, rename, revoke, and endpoint rotation.
|
||||
|
||||
- dumbpipe-style streams
|
||||
- TCP and Unix socket forwarding
|
||||
- SSH proxy over Iroh
|
||||
- SSH certificate and revocation distribution over Iroh
|
||||
- OpenSSH KRL export/import support
|
||||
- restricted geth admin shell
|
||||
- `[ ]` Resource auth operation reducer.
|
||||
Acceptance criteria:
|
||||
- Resource create, authority set, grants, revocations, and groups reduce into
|
||||
a current permission view.
|
||||
- Capabilities are strings, including scoped forms such as
|
||||
`kv.write_prefix:apps/foo/`.
|
||||
- Tests cover grant, revoke, group membership, and denied access.
|
||||
|
||||
- `[ ]` `auth explain` real decision path.
|
||||
Acceptance criteria:
|
||||
- `geth auth explain <subject> <resource> <capability>` reports allowed/denied.
|
||||
- Output includes the operation chain or missing grant that caused the result.
|
||||
- JSON output is stable enough for tests and scripts.
|
||||
|
||||
- `[ ]` Resource secrets and bearer invites.
|
||||
Acceptance criteria:
|
||||
- Bearer secrets grant only resource-scoped capabilities.
|
||||
- Bearer principals cannot mutate trust graph state by default.
|
||||
- Secret epoch rotation is represented in durable metadata.
|
||||
- Tests verify bearer access does not imply node identity.
|
||||
|
||||
- `[~]` SSH certificate and revocation lifecycle.
|
||||
Acceptance criteria:
|
||||
- `geth ssh cert request/requests/approve/import/list` persist local metadata.
|
||||
- Approval emits an explicit `ssh-keygen -s ...` command for CA/YubiKey use.
|
||||
- `geth ssh revocation add/list/export` persists and exports revocations.
|
||||
- Future completion requires auth checks for request, approve, import, publish,
|
||||
and read capabilities.
|
||||
|
||||
## Phase 3: CAS, KV, And Pubsub
|
||||
|
||||
Goal: turn local CAS and stubs into Iroh-backed replicated modules while keeping
|
||||
authorization and durable-state boundaries clear.
|
||||
|
||||
- `[ ]` Iroh-blobs CAS integration.
|
||||
Acceptance criteria:
|
||||
- Local CAS can provide and fetch blobs over Iroh.
|
||||
- Provider tracking is recorded locally.
|
||||
- Local add/get/hash/has/list behavior remains backward compatible.
|
||||
|
||||
- `[ ]` CAS pin and cache policy.
|
||||
Acceptance criteria:
|
||||
- Pinned blobs are retained across cache cleanup.
|
||||
- Unpinned cached blobs can be evicted by policy.
|
||||
- Tests cover pin, unpin, list, and attempted eviction of pinned data.
|
||||
|
||||
- `[ ]` Encrypted private blobs.
|
||||
Acceptance criteria:
|
||||
- Private blob payloads are encrypted before network distribution.
|
||||
- Access is gated by resource secret epoch material.
|
||||
- Docs explicitly avoid claiming forward secrecy or PCS.
|
||||
|
||||
- `[ ]` Iroh-docs KV integration.
|
||||
Acceptance criteria:
|
||||
- `geth kv create/set/get` works against a named KV resource.
|
||||
- Prefix-scoped capabilities can allow or deny writes.
|
||||
- KV metadata is durable and replicated through Iroh Documents.
|
||||
|
||||
- `[ ]` Iroh-gossip pubsub integration.
|
||||
Acceptance criteria:
|
||||
- `geth pubsub pub/sub` works for local test nodes.
|
||||
- Pubsub messages are lossy notifications, not durable facts.
|
||||
- Docs and tests keep durable state in CAS/KV/document/db instead.
|
||||
|
||||
## Phase 4: Pipes, SSH Proxy, And SSH Distribution
|
||||
|
||||
Goal: add authorized stream-oriented management workflows over Iroh.
|
||||
|
||||
- `[ ]` Dumbpipe-style Iroh streams.
|
||||
Acceptance criteria:
|
||||
- `geth pipe listen/connect` can connect two local test nodes.
|
||||
- Pipe access requires `pipe.listen` or `pipe.connect`.
|
||||
- Streams close cleanly and propagate errors.
|
||||
|
||||
- `[ ]` TCP forwarding.
|
||||
Acceptance criteria:
|
||||
- A local TCP listener can forward over an authorized Iroh pipe.
|
||||
- Tests cover basic request/response forwarding.
|
||||
- Forwarding is resource-scoped and can be disabled by auth.
|
||||
|
||||
- `[ ]` Unix socket forwarding where supported.
|
||||
Acceptance criteria:
|
||||
- Unix socket forwarding is available on Unix platforms.
|
||||
- Unsupported platforms return clear errors.
|
||||
- Tests skip or use cfg guards where sockets are unavailable.
|
||||
|
||||
- `[ ]` SSH proxy over Iroh.
|
||||
Acceptance criteria:
|
||||
- `geth ssh proxy <node>` opens an authorized Iroh stream.
|
||||
- Remote daemon checks `ssh_proxy.connect` before connecting to local sshd or
|
||||
admin shell.
|
||||
- Knowing an EndpointID alone cannot reach sshd.
|
||||
|
||||
- `[ ]` SSH certificate and revocation distribution.
|
||||
Acceptance criteria:
|
||||
- Issued cert records and revocation records replicate over Iroh.
|
||||
- Consumers can list current certs/revocations from local state while offline.
|
||||
- Conflicting or unsigned records are rejected or quarantined.
|
||||
|
||||
- `[ ]` OpenSSH KRL import/export.
|
||||
Acceptance criteria:
|
||||
- Revocation records can produce an OpenSSH KRL file.
|
||||
- Existing KRL files can be imported into revocation metadata where possible.
|
||||
- Tests cover serial, key ID, public key, and certificate revocations.
|
||||
|
||||
## Phase 5: DB And Documents
|
||||
|
||||
- cr-sqlite sync
|
||||
- Automerge sync
|
||||
- resource-attached authorization
|
||||
- secret-derived encryption
|
||||
Goal: add durable synchronized data structures for SQLite/cr-sqlite and
|
||||
Automerge documents.
|
||||
|
||||
- `[ ]` DB resource registration.
|
||||
Acceptance criteria:
|
||||
- `geth db add <name> <path>` records DB metadata.
|
||||
- `geth db status <name>` reports local path, schema metadata, and sync state.
|
||||
- Nonexistent paths and invalid names produce clear errors.
|
||||
|
||||
- `[ ]` cr-sqlite change extraction.
|
||||
Acceptance criteria:
|
||||
- The module can read changes from `crsql_changes`.
|
||||
- Schema hash/version metadata is included in sync batches.
|
||||
- Tests use a temp SQLite DB and deterministic fixture changes.
|
||||
|
||||
- `[ ]` DB sync over Iroh.
|
||||
Acceptance criteria:
|
||||
- Two local test nodes can exchange and apply DB changes.
|
||||
- Schema mismatch is detected before applying changes.
|
||||
- Optional CAS-backed snapshots or batches are documented if used.
|
||||
|
||||
- `[ ]` Automerge document resource.
|
||||
Acceptance criteria:
|
||||
- `geth document create/status` works for local documents.
|
||||
- Document state is stored durably.
|
||||
- Tests cover create, update, save, and reload.
|
||||
|
||||
- `[ ]` Automerge sync over Iroh.
|
||||
Acceptance criteria:
|
||||
- Two local test nodes can synchronize document changes.
|
||||
- Resource authorization gates read/write sync.
|
||||
- Conflicts converge according to Automerge semantics.
|
||||
|
||||
## Phase 6: File Sync And Advanced Local-First Auth
|
||||
|
||||
- CAS tree objects
|
||||
- file roots
|
||||
- conflict handling
|
||||
- Keyhive-like convergent capabilities
|
||||
- BeeKEM/CGKA-inspired group key evolution
|
||||
Goal: build higher-level local-first collaboration on CAS trees, resource auth,
|
||||
and future group key evolution.
|
||||
|
||||
- `[ ]` CAS tree objects.
|
||||
Acceptance criteria:
|
||||
- Tree objects describe directories, files, executable bits, and blob hashes.
|
||||
- Tree objects are content-addressed and stored in CAS.
|
||||
- Tests cover deterministic tree hashing.
|
||||
|
||||
- `[ ]` File roots.
|
||||
Acceptance criteria:
|
||||
- A file root maps a local path to a CAS tree resource.
|
||||
- Scan detects create/update/delete/rename changes.
|
||||
- Sync never silently overwrites local changes without a recorded decision.
|
||||
|
||||
- `[ ]` Conflict handling.
|
||||
Acceptance criteria:
|
||||
- Conflicts are represented as durable metadata.
|
||||
- CLI can list conflicts and choose a resolution.
|
||||
- Tests cover concurrent edit, delete/edit, and rename conflicts.
|
||||
|
||||
- `[ ]` Keyhive-like convergent capabilities.
|
||||
Acceptance criteria:
|
||||
- Capability state is represented as local-first replicated auth data.
|
||||
- Convergent grant/revoke semantics are documented and tested.
|
||||
- Migration from current auth ops is documented.
|
||||
|
||||
- `[ ]` BeeKEM/CGKA-inspired group key evolution.
|
||||
Acceptance criteria:
|
||||
- Design doc states exact security properties and non-properties.
|
||||
- Prototype is behind explicit experimental module boundaries.
|
||||
- Current resource secret epoch model remains compatible or has a migration.
|
||||
|
|
|
|||
Loading…
Reference in a new issue