From 89706607e038c8dfccb55fd37961612906d04b71 Mon Sep 17 00:00:00 2001 From: everbarry Date: Thu, 7 May 2026 23:53:44 +0200 Subject: [PATCH] up readme --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index eba6704..8a4b1ef 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,91 @@ # ZKAC -**Zero-Knowledge Access Control** — BBS+ anonymous credentials on BLS12-381 with an encrypted session layer (X25519, ChaCha20-Poly1305, replay protection). +**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 -- **[Changelog](CHANGELOG.md)** — releases and breaking API notes -- **[Python API](docs/PYTHON_API.md)** — types and usage for `import zkac` -- **[Security model](docs/SECURITY.md)** — threat model, assumptions, operational guidance -- **[Fuzzing](docs/FUZZING.md)** — `cargo-fuzz` harnesses +| 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 +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. -```toml -[dependencies] -zkac = { path = "..." } -``` +## Quick start (Python + CLI) -Public API highlights: `zkac::Node`, `zkac::Credential`, `zkac::RoleRegistry`, `zkac::IssuerKeyPair`, `zkac::MAX_BBS_AUTH_PROOF_BYTES`. - -## Python - -Requires a Rust toolchain. [maturin](https://www.maturin.rs/) builds the `zkac` extension; it is not on your `PATH` until you install it. +Requires a **Rust** toolchain. [maturin](https://www.maturin.rs/) builds the `zkac` extension. ```bash +cd /path/to/ZKAC uv venv && source .venv/bin/activate -# Pick one way to get the `maturin` command: -uv sync --extra dev # installs maturin into this venv -# or: uv pip install maturin -# or: uvx maturin develop # no install; runs maturin once from PyPI +uv sync --extra dev # maturin + zkac-node CLI +maturin develop # builds the Python extension (see [tool.maturin] in pyproject.toml) +``` -maturin develop # features come from [tool.maturin] in pyproject.toml -# Console script ``zkac-node`` lives in ``cli/``; install it into the venv: -uv sync --extra cli # or ``--extra demo`` (Flask demos + zkac-node) +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`. -Local web UI over the CLI: `demo/cli_web_server.py` (see `demo/README.md`). Optional in-browser WASM for the Flask demo: `wasm/README.md` and `./demo/build_wasm.sh` (needs **rustup** + `wasm32-unknown-unknown`). +## 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// +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 +zkac-node server pin bob localhost:9800 --key + +# 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 \ + --role analyst --to "" + +zkac-node credentials list bob +zkac-node auth bob --registry --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 repository license file (if present). +See the repository license file (if present).