Formal security package (api-billing-v2)
QuantZK includes a formal security package designed to support an independent review. It documents the threat model, trust assumptions, adversarial test coverage, parser behavior, circuit inventory, canonicalization approach, and known limitations.
This is not a third-party audit letter, penetration-test report, or a claim that “QuantZK has been security audited.” It is the protocol owner’s reproducible harness: scope, adversary model, executable vector catalog, and production-scale methodology.
Package vs code review
| Code review | Formal security package (this track) |
|---|---|
| Reads source for intent and style | Executes fail-closed vectors with expected outcomes |
| Subjective severity | Pass/fail per catalog ID (BV2-*, ADV-*) |
| Point-in-time | Reproducible from pinned artifacts + conformance JSON |
| May miss parser edges | Targets serialization, canonicalization, malformed proofs |
| Line-coverage % as a proxy | Behavioral coverage: primary threat-model scenarios have executable tests |
Adversary model
- Power: PPT attacker; can craft HTTP bodies, reorder JSON, swap proof fields, race concurrent attests, forge transparency proofs, and supply stale revocation snapshots.
- Cannot: Break Ed25519 EUF-CMA, Groth16 soundness, or SHA-256 collision resistance except with negligible probability.
- Goal: Forge a valid billing receipt, double-spend usage, bypass charge bounds, or verify a tampered bundle as valid.
Audit domains
| Domain | Question | Primary evidence |
|---|---|---|
| Circuit correctness | Does apiBillingV2 bind the published commitment relation? | Phase-2 in-circuit tests + artifact pins |
| Serialization edge cases | Do unsafe integers / overflow paths fail closed? | ADV-CHARGE-01, ADV-EVAL-01 |
| Parser ambiguity | Are digests independent of JSON key order? | ADV-CANON-01, meter envelope tests |
| Signature verification | Do tampered meter + attestation signatures reject? | ADV-SIG-01, ADV-METER-01 |
| Canonicalization | Is RFC 8785-style canonical JSON single-sourced? | protocol/lib/canonicalize.js + ADV-CANON-* |
| Replay logic | Is (tenant, window, event_id) double-spend blocked? | BV2-REPLAY-01/02/03 |
| API abuse | Do strict profiles enforce revocation freshness? | ADV-REVOC-01/02 |
| Malformed proofs | Do swapped/truncated proofs fail verification? | ADV-PROOF-01/02/03 |
| Denial of service | Do oversized payloads reject without wedging? | ADV-PAYLOAD-01, BV2-PERF-01 |
Evidence gates (run in order)
Gate 1 — Artifact integrity
bash
bash scripts/verify-artifact-hashes.shPins WASM, zkey, canonical vkey hash; runs offline conformance.
Gate 2 — Deterministic evaluator + canonicalization
bash
cd protocol && node --test test/conformance-billing-v2.test.js
cd protocol && node --test test/adversarial-billing-v2.test.jsGate 3 — Functional + adversarial integration (PostgreSQL)
bash
cd verifier-api && npm run test:billing-pilot
cd verifier-api && npm run test:billing-adversarialExpect 15/15 pilot + 12/12 adversarial (release bar).
Gate 4 — Full formal audit runner
bash
bash scripts/run-formal-security-audit.shRuns gates 1–3 and writes audit-logs/formal-security-audit-<timestamp>.json.
Gate 5 — Production smoke (live, optional)
bash
API=https://api.quantzk.com VDI_ATTEST_SECRET=<secret> bash scripts/smoke-billing-phase2.shGate 6 — Production scale (load methodology)
bash
# Quick local sample (100 attest+verify pairs)
node scripts/production-scale-audit.mjs --total 100
# Sustained verify-only throughput (uses cached attestation)
node scripts/production-scale-audit.mjs --mode verify-only --total 10000 --concurrency 20
# Production target profile (documented; run on dedicated hardware)
SCALE_TOTAL=10000000 node scripts/production-scale-audit.mjs --mode verify-only --concurrency 50See Production scale methodology below.
Adversarial catalog
Machine-readable: protocol/conformance/billing-v2-adversarial.json
Human matrix: Billing v2 attack matrix
Determined reviewer questions → vectors
| Reviewer question | Vector ID | Expected result |
|---|---|---|
| Proof fields swapped? | ADV-PROOF-01 | verification.valid: false |
| Timestamps overflow / expired? | ADV-TIME-01 | verification.valid: false |
| JSON reordered? | ADV-CANON-01 | Same digest; meter resign invariant |
| Malformed public signals? | ADV-PROOF-02 | commitment_binding_verification.valid: false |
| Replay attempts? | BV2-REPLAY-01/03 | HTTP 400 or race 200+400 |
| Stale revocation cache? | ADV-REVOC-02 | Strict verify fails revocation_status when snapshotTime predates issued_at (pass revocation inline on verify body; env feed clamps stale times to now) |
| Concurrent requests? | BV2-REPLAY-03 | Exactly one success |
| Malformed signatures? | ADV-SIG-01, ADV-METER-01 | Verify/attest fail closed |
| Invalid transparency checkpoints? | ADV-LOG-01/02 | log_proof_verification.valid: false |
| Canonicalization mismatch? | ADV-METER-01 | Attest HTTP 400 |
| Oversized payloads? | ADV-PAYLOAD-01 | HTTP ≥ 400 |
Production scale methodology
What we show today: Correctness under adversarial vectors + CI perf budget (single warm attest ≤ 8s).
What production scale proves: Sustained verify throughput, zero verification mismatches on honest bundles, and operational error rate under load.
The harness (scripts/production-scale-audit.mjs) reports:
| Metric | Definition |
|---|---|
attest_success | HTTP 200 attest count |
verify_success | HTTP 200 verify count |
verification_mismatches | Honest bundle where verification.valid !== true |
billing_check_mismatches | Honest bundle where billing_check.valid !== true |
error_rate | (failures) / (attempts) |
uptime_ratio | 1 - error_rate over the run window |
latency_p50_ms / latency_p99_ms | End-to-end per operation |
Target profile (design partner / auditor disclosure)
These are methodology targets, not marketing guarantees until measured on your production environment:
| Target | Method |
|---|---|
| 10M attestations processed | Batch attest with unique event_id; replay guard prevents duplicates |
| 0 verification mismatches | Every honest attest→verify must pass all checks |
| 99.99% uptime | uptime_ratio ≥ 0.9999 over sustained window |
| Sustained load | --concurrency + --duration-sec or --total |
Honest limits:
- Full attest+verify at 10M scale requires production PostgreSQL, meter keys, and hours of wall time — use
verify-onlymode with a cached attestation to stress cryptographic verification path. - 99.99% uptime is measured over the audit window against the configured API base URL, not a historical SLA unless backed by external monitoring.
- Groth16 proving dominates attest latency; scale tests separate prove path (attest) from verify path (cheap).
Auditor deliverables
After running Gate 4, attach to your report:
audit-logs/formal-security-audit-*.json— gate results + git SHAprotocol/conformance/billing-v2-conformance.json— artifact pinsprotocol/conformance/billing-v2-adversarial.json— adversarial catalog- Production scale JSON (if Gate 6 run):
audit-logs/production-scale-*.json