# 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. Two-server XOR PIR needs a second replica with the same server_key + grants pool.
#    Example: rsync ~/.zkac/alice/server/ to a temp dir after the grant, then:
#    zkac-node serve alice --port 9801 --data-dir /tmp/zkac-replica &
#    zkac-node server pin bob localhost:9801 --key <same SERVER_PK_HEX as step 2>

# 5. Bob lists local creds; optional pending scan (O(n) PIR queries per server)
zkac-node credentials list bob
zkac-node credentials list bob --server localhost:9800 --pir-peer localhost:9801

# 6. Bob collects (primary host in spec, second replica as --pir-peer)
zkac-node collect bob localhost:9800:<REGISTRY_ID>:analyst \
  --pir-peer localhost:9801 --pool-index <POOL_INDEX>

# 7. 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 …] [--pir-peer P]` | Local credentials; pending grants only with `--pir-peer` (PIR scan) |
| `collect <id> <spec> --pir-peer P --pool-index N` | Fetch one grant via two-server XOR PIR |
| `auth <id> --registry R --role X [--server S]` | Authenticated session |

## Protocol & threat model

See [docs/SECURITY.md](../docs/SECURITY.md) in the repo root.

## 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
server/                       (only if you run `serve <userid>`) server_key.json, registries/, mailbox/grants_pool.json
```