ZKAC/cli/README.md

zkac-node CLI

Install the zkac wheel from the repo root first (maturin develop or pip install .), then:

pip install -e ./cli
zkac-node --help

Quick start

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