diff --git a/cli/README.md b/cli/README.md index 741fb30..95c3865 100644 --- a/cli/README.md +++ b/cli/README.md @@ -1,121 +1,108 @@ # zkac-node CLI -Command-line interface for [ZKAC](../README.md) using the **Python bindings only** (`zkac` package). It runs a **registry-capable server** (management + client-managed registries + optional issuance relay) and **per-user** material under `~/.zkac/` (or `$ZKAC_HOME`). - -## Prerequisites - -- Python ≥ 3.9 -- The **`zkac`** extension built and installed from the repository root, for example: - - ```bash - cd /path/to/ZKAC - maturin develop - # or: pip install -e . - ``` - -## Installation +Install the `zkac` wheel from the repo root first (`maturin develop` or `pip install .`), then: ```bash -cd /path/to/ZKAC/cli -pip install -e . +pip install -e ./cli +zkac-node --help ``` -This installs the **`zkac-node`** console script. +## Quick start -## Environment +```bash +# 1. Create identities (one per machine / actor) +zkac-node identity init # on admin machine +zkac-node identity init # on recipient machine (separate ~/.zkac) -| Variable | Meaning | -|------------|---------| -| `ZKAC_HOME` | Base directory for users (default: `~/.zkac`). Each user lives at `$ZKAC_HOME//`. | +# Recipient shares their issuance public key out-of-band: +zkac-node identity show # prints issuance pk (hex) -## Server vs client +# 2. Start the server (separate machine or same, different data-dir) +zkac-node serve --data-dir /var/lib/zkac --port 9800 & -- **Server** (`zkac-node serve`): a node that can **accept registry create/update** from an operator with the **`zkac.mgmt`** credential. It also serves **managed** sessions (BBS+ auth against stored client-managed registries) and optionally a **relay** port for blind issuance queues. -- **Client**: a **userid** with files under `$ZKAC_HOME//` (transport key, registries, credentials). +# 3. Pin the server's public key (printed at startup) +zkac-node server pin localhost:9800 --key -## Ports (defaults) +# 4. Create a registry (admin side) +zkac-node registry create localhost:9800 --roles analyst,operator -| Port role | Default | Purpose | -|------------|---------|---------| -| Management | 7400 | ZKAC + static role `zkac.mgmt`; JSON commands (create/update registry, issuance peek/grant). | -| Managed | 7401 | ZKAC + `RegistryManager`; member proves a role in a client-managed registry. | -| Relay | 7402 | Optional **plaintext** JSON line protocol for enqueue/poll of issuance requests. Use `--relay-port 0` on `serve` to disable. Binds with `--relay-bind` (default `127.0.0.1`). | +# 5. Grant recipient the 'analyst' role (only needs their public key) +zkac-node grant --server localhost:9800 \ + --registry --role analyst --to -## Layout on disk +# 6. Recipient lists pending credentials +zkac-node credentials list --server localhost:9800 -**Per user** (`$ZKAC_HOME//`): +# 7. Recipient collects (host:port:registry_id:role) +zkac-node collect localhost:9800::analyst -- `transport.json` — Ristretto **client** transport keypair (`zkac.Keypair`). -- `profile.json` — `userid` and metadata. -- `registries//` — one directory per logical registry: - - `admin.json` / `registry.json` — produced by `registry-init` (admin issuer material + public state + state cert). - - `roles/.json` — member credential payloads for `connect`. - - `issued/` — files from `issue-member` (handoff). -- `pending/.json` — saved by `issuance-request` until `issuance-poll` finalizes. -- `servers/