Qeaas MCP

Quantum Entropy-as-a-Service (Q-EaaS) — API Reference

Want an API key? Email peter.jas@cnl.sk.

FastAPI service that turns preloaded QRNG (quantum random number generator) bits into served randomness, dice rolls, cryptographic seeds, and post-quantum ML-KEM key material — each issue carrying a signed, offline-verifiable provenance receipt.

Monorepo layout: api/ (this document — FastAPI service), web/ (Next.js explainer + demo), shared/ (docs, spikes), claude/ (epic build plans). The web app is a thin client over the API; everything substantive happens here.

Honest framing, stated once and meant everywhere. QRNG does not "defeat quantum

attackers." Raw QRNG bits are *never served*. They are entropy that **seeds a standards

HMAC-DRBG** (NIST SP 800-90A). Every byte this API returns — /random, /dice, /v1/random/bytes,

ML-KEM seeds — is DRBG output. The quantum part is the *entropy source*; any quantum

*resistance* comes from ML-KEM-768 (FIPS 203), not from the randomness being "quantum."

---

1. Architecture at a glance

             ┌──────────── admin (X-Admin-Token) ────────────┐

│ │ QRNG .txt │ POST /admin/ingest │ POST /admin/keys (0/1 bits) ▼ ▼ POST /admin/keys/revoke ┌─────────────┐ AES-256-GCM ┌───────────────────────────────┐ │ pool.parse │ ───────────────▶ │ Postgres (Neon) │ │ + encrypt │ │ entropy_pool (ciphertext) │ └─────────────┘ │ drbg_root (ciphertext) │ │ api_keys / usage_log / │ │ issue_log │ └───────────────┬───────────────┘ │ decrypt slice on reseed ▼ client ┌───────────────────────────────────────┐ ─────────▶ entropy gate │ keyed_drbg.output(n) │ request (503 if low) │ root_key ← reseeded from pool │

• rate limit ──▶│ counter ← Redis atomic INCR │──▶ HMAC-DRBG(SHA-256)
• API key │ HMAC-DRBG(root_key, counter) → bytes │ = served bytes └───────────────────────────────────────┘ │ ┌───────────────────────────┴───────────┐ │ Redis (Upstash) │ │ drbg:counter (output uniqueness) │ │ rl:* / quota:* / anon:* (throttling) │ └────────────────────────────────────────┘

• Stateless / serverless. Each request opens a Postgres connection and closes it (db.connect); there is no long-lived pool object. DRBG state is never read-modify-written per request — see §4.
• Two datastores, two different jobs — see §3.
• CORS is locked to the origins in WEB_ORIGIN (comma-separated).
• Every response carries an `X-Quantum-Entropy: healthy|degraded` header (added by middleware in main.py).

Source map (api/qeaas/):

---

2. The randomness pipeline (what fires, in order)

Every served byte flows through one choke point, generation.random_bytes(n) → keyed_drbg.output(n). Nothing bypasses it.

A. Ingest (admin, offline of the request path). POST /admin/ingest → pool.ingest_bits_bytes() → pool.parse_bits_bytes() packs the 0/1 text MSB-first into bytes (discarding a trailing partial byte, rejecting any non-0/1 char) → pool.encrypt_chunk() AES-256-GCM-encrypts it → db.insert_pool_chunk() stores (ciphertext, nonce, tag, plaintext_len, source_label) in `entropy_pool`. Plaintext never touches disk; the upload buffer is burn()-ed.

B. Serve (per request). keyed_drbg.output(n):

1. maybe_reseed() — loads the warm root-key cache (_load_cache), bootstrapping the root key from the pool on very first use (_bootstrap_root_key). If the reseed schedule is due (§4), pool.pull_reseed_material(32) decrypts the next unconsumed 32-byte slice from entropy_pool, encrypts it as the new drbg_root row, advances consumed_offset, and burn()s the plaintext.
2. redis_client.incr_counter() — atomic INCR drbg:counter, returns a globally unique integer.
3. A fresh HmacDrbg is instantiated with the decrypted root_key and generate(n, additional = counter.to_bytes(8) + additional) is called — the counter guarantees two concurrent requests can never produce identical output even with identical root key.
4. db.bump_outputs_since_reseed() increments the reseed odometer.

C. Wrap (per endpoint). generation.new_issue_meta(size) mints a request_id (uuid4), reads entropy_epoch (= drbg_root.reseed_counter), timestamps, and calls receipts.sign(...) to produce the Ed25519 receipt. Keyed endpoints then write db.insert_usage_log() (abuse spotting) and db.insert_issue_log() (metadata-only provenance — no output bytes are ever stored).

See the deep-dive comment at the end of this file / in the chat analysis for the exact call graph.

---

3. Why two databases

They protect against completely different failure modes and have opposite consistency needs.

Postgres (Neon) — the durable secret store & audit ledger

Holds everything that must survive and must be transactional & durable. Five tables:

Durability matters: lose the pool ciphertext or the root key and the service can no longer prove provenance or reseed. Postgres is ACID; this is where correctness lives.

Redis (Upstash) — the ephemeral atomic counter & throttle

Holds only fast, disposable, atomically-mutated counters that would be a correctness hazard in Postgres under serverless concurrency:

Why not put these in Postgres? On stateless serverless you cannot safely read-modify-write shared state per request — two concurrent requests would race. Redis INCR/INCRBY are atomic, so there is no read-modify-write. These values are *meant* to expire (per-minute, per-day) and losing them is harmless — throttling fails open on a Redis outage (logs a warning, allows the request), because the reseed-frequency floor (§4) still guarantees the pool can't be drained.

One-line summary: Postgres = durable secrets + audit that must be correct forever; Redis = ephemeral atomic counters that must be fast and race-free but are disposable.

---

4. The DRBG & bit-drain protection

• HMAC-DRBG (SHA-256), NIST SP 800-90A §10.1.2 (drbg.py). Not thread-safe — each request gets its own instance.
• Serverless-safe wrapper (keyed_drbg.py): output(n) = HMAC-DRBG(root_key, INCR(drbg:counter), n).
• Reseed schedule. root_key rotates from the pool on whichever fires first:
• a fixed 15-minute interval (RESEED_INTERVAL_SECONDS), or
• an output count ≥ RESEED_OUTPUT_LIMIT (100 000) but only if ≥ RESEED_MIN_INTERVAL_SECONDS (5 minutes) has elapsed. Each reseed pulls RESEED_PULL_BYTES (32) from the pool.
• Bit-drain is impossible via traffic. Served bytes are always DRBG output, never raw pool bits, and the 5-minute floor means no request volume can rotate the key faster than wall-clock time. Pool drain is a function of *time*, never *traffic*.
• Low-entropy gate. Below THRESHOLD (64 KiB) of unconsumed pool bytes, /health reports degraded and all gated routes 503 low_quantum_entropy (gate.require_entropy).

---

5. Cryptographic key hierarchy

One env-held MASTER_KEY (256-bit hex). pool.derive_subkey(name) (HKDF-SHA256, RFC 5869 one-block Expand) derives exactly four named sub-keys — there are no other secrets:

MASTER_KEY  (env / KMS only — never written to Postgres)

└── HKDF-SHA256 ├── "pool-encryption-key" → entropy_pool AES-256-GCM ├── "drbg-root-encryption-key" → drbg_root.root_key AES-256-GCM ├── "api-key-pepper" → API-key hashing (HMAC-SHA256) └── "receipt-signing-key" → Ed25519 receipt signing seed

AES-256-GCM is authenticated: a flipped ciphertext byte fails the tag check and decryption raises — the service fails closed on tampered storage. Sensitive plaintext (decrypted slices, the warm root-key cache, upload buffers) is held in bytearray and best-effort burn()-ed after use (CPython cannot *guarantee* zeroization; serverless teardown keeps in-process secrets short-lived by design).

---

6. Authentication

• API keys: hash_api_key(key) = HMAC-SHA256(pepper, key); only the hash is stored. require_api_key reads the row fresh every request, so revoked = true