up readme
This commit is contained in:
everbarry
parent
2551cfb44e
commit
89706607e0
95
README.md
95
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/<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 repository license file (if present).
|
||||
See the repository license file (if present).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user