ZKAC

Zero-Knowledge Access Control — anonymous authorization with BBS+ credentials on BLS12-381, over an encrypted session layer (X25519, ChaCha20-Poly1305, replay-safe records).

Philosophy

ZKAC is built around trustless federation: registries and services can live on ordinary network hosts, but the protocol limits what a malicious or curious node can learn or forge. Authorization is proved with transcript-bound zero-knowledge credentials, credential transfer is end-to-end encrypted, and policy state can be verified by clients instead of trusting the host’s view alone. The design sits between conventional client-server trust and heavy global blockchain consensus — see the whitepaper for goals, architecture, and comparisons.

Documentation

Doc	Description
Whitepaper	Goals, architecture, cryptography, adversary games
Security	Threat model, assumptions, operational guidance
CLI guide	`zkac-node` workflows, I2P, storage layout
Python API	`import zkac` types and usage
Fuzzing	`cargo-fuzz` harnesses

Rust crate API (e.g. zkac::Node, zkac::Credential, zkac::RoleRegistry, zkac::IssuerKeyPair, zkac::MAX_BBS_AUTH_PROOF_BYTES) is documented in code and the whitepaper; Python wraps the same core.

Quick start (Python + CLI)

Requires a Rust toolchain. maturin builds the zkac extension.

cd /path/to/ZKAC
uv venv && source .venv/bin/activate
uv sync --extra dev          # maturin + zkac-node CLI
maturin develop              # builds the Python extension (see [tool.maturin] in pyproject.toml)

Smoke-test the library:

python -c "import zkac; print(zkac.role_id('admin').hex())"

Run tests: cargo test and pytest tests/test_zkac.py.

CLI examples

Install the cli package so zkac-node is on your PATH (uv sync --extra dev or uv sync --extra cli as above). Then:

# Identities live under ~/.zkac/<userid>/
zkac-node user create alice
zkac-node user create bob

# Alice hosts the node; everyone pins the server’s transport public key (from server logs or ops).
zkac-node serve alice --host 127.0.0.1 --port 9800
zkac-node server pin alice localhost:9800 --key <SERVER_PUBLIC_KEY_HEX>
zkac-node server pin bob localhost:9800 --key <SERVER_PUBLIC_KEY_HEX>

# Bob publishes a contact bundle (share out-of-band with Alice)
zkac-node user show bob --peer 127.0.0.1:9810

# Alice defines roles on a registry, then grants Bob directly
zkac-node registry create alice localhost:9800 --roles analyst,operator
zkac-node p2p-listen bob --host 127.0.0.1 --port 9810   # Bob listens for one grant
zkac-node grant alice --server localhost:9800 --registry <REGISTRY_ID> \
  --role analyst --to "<BOB_CONTACT_BUNDLE>"

zkac-node credentials list bob
zkac-node auth bob --registry <REGISTRY_ID> --role analyst --server localhost:9800

Connectivity and handshake check:

zkac-node net check 127.0.0.1:9800 --handshake --userid alice

More commands (registry, revoke, I2P, zkac-node-i2p-server) are in docs/CLI.md and cli/README.md.

Demo

The file-share demo is a self-contained Textual UI that exercises registries, P2P credential grant, buckets, and permissions — isolated from your default ZKAC home via ZKAC_HOME=~/.ZKAC-FS by default.

uv sync --extra demo
uv run python demo/file_share_server.py --port 9879
uv run python demo/file_share_tui.py

Verification: uv run python demo/file_share_smoke.py and pytest demo/test_demo_privacy_guardrails.py.

Optional: browser-side WASM that mirrors parts of the Rust library — build and integration notes are in wasm/README.md (Rust wasm32-unknown-unknown, wasm-pack).

License

See the repository license file (if present).

4.0 KiB Raw Blame History Unescape Escape