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