83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# zkac-node CLI
|
|
|
|
Install the `zkac` wheel from the repo root first (`maturin develop` or `pip install .`), then:
|
|
|
|
```bash
|
|
pip install -e ./cli
|
|
zkac-node --help
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 1. Create identities (one directory per user under ~/.zkac/<userid>/)
|
|
zkac-node user create alice
|
|
zkac-node user create bob
|
|
|
|
# Bob shares his issuance public key with Alice out-of-band:
|
|
# zkac-node user show bob → copy issuance pk
|
|
|
|
# 2. Alice runs a server; pin its public key for clients
|
|
zkac-node serve alice --port 9800 &
|
|
zkac-node server pin alice localhost:9800 --key <SERVER_PK_HEX>
|
|
zkac-node server pin bob localhost:9800 --key <SERVER_PK_HEX>
|
|
|
|
# 3. Alice creates a registry and grants Bob a role (needs Bob's issuance pk hex)
|
|
zkac-node registry create alice localhost:9800 --roles analyst,operator
|
|
zkac-node grant alice --server localhost:9800 \
|
|
--registry <REGISTRY_ID> --role analyst --to $BOB_PK_HEX
|
|
# (prints pool_index for Bob's collect)
|
|
|
|
# 4. Bob lists local creds + pending grants (single-server PIR, no second replica needed)
|
|
zkac-node credentials list bob
|
|
zkac-node credentials list bob --server localhost:9800
|
|
|
|
# 5. Bob collects (auto-discovers via detection tags; --pool-index is optional)
|
|
zkac-node collect bob localhost:9800:<REGISTRY_ID>:analyst
|
|
# or with explicit index:
|
|
zkac-node collect bob localhost:9800:<REGISTRY_ID>:analyst --pool-index <POOL_INDEX>
|
|
|
|
# 6. Bob authenticates
|
|
zkac-node auth bob --registry <REGISTRY_ID> --role analyst --server localhost:9800
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `user create <id>` | Generate issuance keypair under `~/.zkac/<id>/` |
|
|
| `user list` | List all local user ids |
|
|
| `user show <id>` | Show issuance pk + owned registries + credentials |
|
|
| `serve <id> [--data-dir D]` | Run server; default data dir is `~/.zkac/<id>/server/` |
|
|
| `server pin <id> <host:port> --key <hex>` | Pin server public key for that user |
|
|
| `registry create <id> <server> --roles …` | Create registry on server |
|
|
| `registry update <id> <server> --registry R --add-roles …` | Add roles |
|
|
| `registry get <id> <server> --registry R` | Fetch registry state |
|
|
| `registry list <id>` | List registries this user owns locally |
|
|
| `grant <id> --server S --registry R --role X --to <pk>` | Admin grant (encrypted to recipient pk) |
|
|
| `credentials list <id> [--server S …]` | Pending grants: tags + SimplePIR (full encrypted row) + decrypt |
|
|
| `collect <id> <spec> [--pool-index N]` | Same retrieval path, then local credential finalize |
|
|
| `auth <id> --registry R --role X [--server S]` | Authenticated session |
|
|
|
|
## Protocol & threat model
|
|
|
|
See [docs/SECURITY.md](../docs/SECURITY.md) in the repo root for the full model, including PIR and detection tags.
|
|
|
|
**Custom clients:** Encrypted management JSON supports `pool_tags`, `pir_hints`, and `pir_query`. Mailbox retrieval is single-hop: decode a full encrypted row from PIR and decrypt locally.
|
|
|
|
**Operational scaling:** The server grant pool is append-only, so pool length grows with every grant. Large pools increase discovery traffic, PIR query size, and server work per retrieval (all linear in pool length). Treat unbounded growth as a potential DoS and capacity risk; mitigations are listed under *Known limitations* and *Future work* in `docs/SECURITY.md`. Transport, BBS+ auth, registry state updates, and issuance queues have separate scaling profiles (CPU dominated by BBS+, state size linear in role count, queue memory); see **Scaling and complexity (transport, credentials, registries)** in the same doc.
|
|
|
|
## Storage layout
|
|
|
|
Per user `~/.zkac/<userid>/`:
|
|
|
|
```
|
|
identity.json issuance keypair
|
|
admin/<registry_id>.json BBS+ admin material for owned registries
|
|
credentials/<rid>_<role>.json received credentials
|
|
servers/<host_port>.json pinned server public keys
|
|
pir_cache/<server>.json PIR hint metadata (pool_version, n_records)
|
|
pir_cache/<server>.bin PIR hint data (cached, keyed by pool_version)
|
|
server/ (only if you run `serve <userid>`) server_key.json, registries/, mailbox/grants_pool.json
|
|
```
|