Metadata-Version: 2.4
Name: quantumvault
Version: 4.2.0
Summary: Post-quantum (ML-DSA-87 / Falcon) cryptographic tokens — Python client for the QuantumVault REST server.
Project-URL: Homepage, https://github.com/007krcs/quantum-vault
Project-URL: Repository, https://github.com/007krcs/quantum-vault
Project-URL: Issues, https://github.com/007krcs/quantum-vault/issues
Project-URL: Documentation, https://github.com/007krcs/quantum-vault#readme
Author: QuantumVault contributors
License: Apache-2.0
License-File: LICENSE
Keywords: crypto,dilithium,falcon,jwt,ml-dsa,post-quantum,pqc,tokens
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# quantumvault

[![PyPI](https://img.shields.io/pypi/v/quantumvault.svg)](https://pypi.org/project/quantumvault/)
[![Python versions](https://img.shields.io/pypi/pyversions/quantumvault.svg)](https://pypi.org/project/quantumvault/)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/007krcs/quantum-vault/blob/main/LICENSE)

Python client for **[QuantumVault](https://github.com/007krcs/quantum-vault)** — post-quantum
(ML-DSA-87, Falcon-512/1024) cryptographic tokens over a zero-dependency REST API.

- **Stdlib-only.** No `requests`, no `httpx`, no compiled wheels. One universal
  wheel, works on Python 3.8+ everywhere (Linux, macOS, Windows, WASM, Alpine).
- **Talks to `qv-server`** — the same sovereign Node server available as a Docker
  image at `ghcr.io/007krcs/qv-server:4.2`.

## Install

```bash
pip install quantumvault
```

## Run the server

```bash
docker run -p 7433:7433 \
  -e QV_MASTER_KEY_HEX=$(openssl rand -hex 32) \
  ghcr.io/007krcs/qv-server:4.2
```

## 30-second demo

```python
from quantumvault import QVClient

qv = QVClient("http://localhost:7433")

key = qv.keygen(label="demo")
iss = qv.issue(
    key_id=key["keyId"],
    claims={"sub": "user-123", "role": "admin"},
    ttl=3600,
)

out = qv.verify(key_id=key["keyId"], token=iss["token"])
assert out["claims"]["sub"] == "user-123"
```

## Error handling

```python
from quantumvault import QVClient, QVVerifyError, QVHTTPError

qv = QVClient("http://localhost:7433")
try:
    qv.verify(key_id=key_id, token=tampered_token)
except QVVerifyError as e:
    # Signature / expiry / replay / revocation failure.
    ...
except QVHTTPError as e:
    # Server returned 4xx/5xx for non-verification reasons.
    print(e.status, e.code, e.message)
```

## License

Apache-2.0.
