92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# 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](docs/WHITEPAPER.md) for goals, architecture, and comparisons.
|
||
|
||
## Documentation
|
||
|
||
| Doc | Description |
|
||
|-----|-------------|
|
||
| **[Whitepaper](docs/WHITEPAPER.md)** | Goals, architecture, cryptography, adversary games |
|
||
| **[Security](docs/SECURITY.md)** | Threat model, assumptions, operational guidance |
|
||
| **[CLI guide](docs/CLI.md)** | `zkac-node` workflows, I2P, storage layout |
|
||
| **[Python API](docs/PYTHON_API.md)** | `import zkac` types and usage |
|
||
| **[Fuzzing](docs/FUZZING.md)** | `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](https://www.maturin.rs/) builds the `zkac` extension.
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`](cli/) package so `zkac-node` is on your `PATH` (`uv sync --extra dev` or `uv sync --extra cli` as above). Then:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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](docs/CLI.md)** and **[cli/README.md](cli/README.md)**.
|
||
|
||
## Demo
|
||
|
||
The **[file-share demo](demo/README.md)** 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.
|
||
|
||
```bash
|
||
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](wasm/README.md)** (Rust **wasm32-unknown-unknown**, [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)).
|
||
|
||
## License
|
||
|
||
See the repository license file (if present).
|