Metadata-Version: 2.5
Name: q-armor-lib
Version: 0.1.2
Summary: QArmor post-quantum protection core: VQS scoring, TLS and sector scanners, CBOM, ML-KEM-768 sessions, proofs, canary tokens and the control-plane client.
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: q-armor-pqc==0.1.2
Description-Content-Type: text/markdown

# q-armor-lib

**The post-quantum protection core of QArmor: score a validator, scan an endpoint, catch a harvester.**

[![PyPI](https://img.shields.io/pypi/v/q-armor-lib.svg)](https://pypi.org/project/q-armor-lib/)
[![Python](https://img.shields.io/pypi/pyversions/q-armor-lib.svg)](https://pypi.org/project/q-armor-lib/)
[![Licence](https://img.shields.io/badge/licence-proprietary-1f6feb.svg)](https://idenq.io)
[![FIPS 203](https://img.shields.io/badge/NIST-ML--KEM--768-000000.svg)](https://csrc.nist.gov/pubs/fips/203/final)
[![FIPS 204](https://img.shields.io/badge/NIST-ML--DSA--65-000000.svg)](https://csrc.nist.gov/pubs/fips/204/final)

> Blockchain bridges have lost more than **$2.8B** to exploits: Ronin $625M, Wormhole $320M, Multichain $130M. Three causes repeat, and the third one has not happened yet: traffic captured today, decrypted the day a cryptographically relevant quantum computer exists. That is **Harvest Now, Decrypt Later**, and it is the attack whose damage is already done by the time anyone can detect it.

`q-armor-lib` is the library that measures the exposure. It is the detection
and scoring logic of [QArmor](https://idenq.io), separated from the runtimes
that consume it (the protection proxy, the dashboard, the canary network and
the DVN worker), so that one implementation produces one answer.

## Three lines, and a number that means something

```bash
pip install q-armor-lib
```

```python
from q_armor_lib.tls_scanner import scan_tls_endpoint

r = scan_tls_endpoint("example.com")
print(r.key_exchange_group, r.vqs.score, r.vqs.tier)
```

```
x25519 80 RiskTier.DENY
```

An endpoint that negotiates **x25519** is doing a classical key exchange:
everything on that wire is harvestable today and readable the day the quantum
computer arrives. VQS is **exposure**, so 0 is safe, 80 is not, and above 75
the tier is `DENY`.

## What VQS actually decides

The score is not a badge. It is the validator's weight in weighted BFT
consensus, so posture changes what a vote is worth:

| Tier | VQS (exposure) | Effective weight |
|---|---|---|
| `PERMIT` | under 25 | full |
| `STEP_UP` | 25 to 75 | halved, until posture improves |
| `DENY` | over 75 | one tenth, and excluded from critical quorum |

Signing algorithm and session algorithm weigh 0.4 each, and the canary capture
rate weighs 0.2. ECDSA, RSA and Ed25519 all score 100 exposure, because Shor
breaks all three and pretending otherwise would only make the label lie.

## Why this, and not a hardware programme

- **No QKD hardware.** ML-KEM-768 runs on the server you already have.
- **Active HNDL detection, not only prevention.** Canary tokens embedded in
  proofs turn a silent harvest into an event with a timestamp.
- **Posture, not just stake.** A validator with a large stake and classical
  keys is a large hole, and VQS is what prices it.
- **One axis, one producer.** `key_establishment_class` is computed here and
  nowhere else, so the CLI, the proxy and the dashboard cannot disagree.
- **It says "unknown" when it does not know.** The class is asserted only when
  the negotiated group was actually observed; a TLS version alone is a guess,
  and a guess is not evidence.

## What is inside

| Module | What it does |
|---|---|
| `vqs_engine` | VQS, the Validator Quantum Score: scoring of cryptographic posture |
| `tls_scanner` | Scanning of TLS endpoints and certificates |
| `sector_scanner` | VQS aggregation at network and sector level |
| `cbom` | Cryptographic bill of materials built from what a scan observed |
| `quantum_scanner_client` | HTTP client of the external QuantumScanner (idenq.io), enriches scans with QES |
| `session.key_exchange` | ML-KEM-768 peer-to-peer session exchange between validators |
| `proofs.aggregator` | Proof aggregation with an ML-DSA-65 signature and canary embedding, weighted by VQS |
| `identity.canary_tokens` | Canary tokens for active detection of HNDL attacks |
| `control_plane` | Client of the QArmor control plane, shared by the CLI and the proxy |

It depends on [`q-armor-pqc`](https://pypi.org/project/q-armor-pqc/) (interim,
see its README) for ML-DSA-65; ML-KEM-768 arrives through that same package
from the `iden-q-post-quantum` emission.

## The QArmor family

Five packages, one version, published together from a single tag.

| Package | What it is |
|---|---|
| [`q-armor-lib`](https://pypi.org/project/q-armor-lib/) | This one: detection, scoring and the control-plane client |
| [`q-armor-cli`](https://pypi.org/project/q-armor-cli/) | `q-armor`, the operator's command line |
| [`q-armor-proxy`](https://pypi.org/project/q-armor-proxy/) | Enterprise runtime: protection proxy, firewall, SIEM webhook |
| [`q-armor-chain`](https://pypi.org/project/q-armor-chain/) | DVN worker and `QArmorDVN.sol` |
| [`q-armor-pqc`](https://pypi.org/project/q-armor-pqc/) | Interim ML-DSA-65 primitive |

## Installing inside the workspace

Within `iden-q-quantum-armor` it is installed editable from the root
`requirements.txt`, which asks for all five with `-e` in ONE pip command: the
exact pin to `q-armor-pqc` is satisfied by the editable requested in that same
command. Standalone, the two together for the same reason:

```bash
pip install -e packages/q-armor-pqc -e packages/q-armor-lib
```

## Tests

The package's own tests live in `tests/` of this directory
(`test_vqs_engine.py`, `test_tls_scanner.py`, `test_session.py`,
`test_proofs.py`, `test_canary_tokens.py`) and do not depend on the runtime,
only on `q_armor_lib` and `q_armor_pqc`. They run with `pytest` from the
repository root like the rest of the suite (there is no restrictive
`testpaths` in `pytest.ini`).

The tests that exercise how the runtime *uses* this library (the
`/endpoint/scan` endpoints, the dashboard, the DVN worker, keypair
persistence) stay in `tests/` at the repository root: they are integration
tests, not tests of the library itself.

## Extraction status

It is a self-contained Python package, published to PyPI with the rest of the
workspace from a tag (`release.yml`; CI builds and verifies it on every pull
request). The licence decision is taken: proprietary
(`LicenseRef-Proprietary` as the SPDX expression in `pyproject.toml`, the
owner's decision of 2026-09-02) and with `LICENSE` inside the wheel. What is
worth knowing when consuming it:

- `quantum_scanner_client.probe_domain` takes the QuantumScanner URL as a
  parameter and does not read global configuration: the runtime that calls it
  decides where that value comes from.

## Next

The local daemon and the VQS dashboard are free. The collective canary
network, real-time alerting and on-premise deployment are the paid tiers:
[idenq.io](https://idenq.io)
