# BitBop.dev — Hardware Quantum Entropy & Post-Quantum Provenance API (v2.1)

> BitBop provides physical hardware entropy (`rf-thermal-noise` on `trng-device-01`) from a physically secured hardware appliance across an end-to-end Quantum-Safe pipeline with zero plaintext at rest, encapsulated in transit with **`NIST FIPS 203 ML-KEM-768`**, and signed exclusively with **`NIST FIPS 204 ML-DSA-44`** on all client receipts (`<50ms` edge latency). Ephemeral `ML-KEM-768` key generation and decapsulation are 100% automated in `@bitbop/sdk` (Node.js/TS), `bitbop` (Python), the `bitbop` CLI, and the Web UI.

## Base URLs & Authentication

- **Production Edge API**: `https://api.bitbop.dev`
- **Web Portal & Interactive Sandbox**: `https://www.bitbop.dev/demo`
- **Self-Serve Free Tier API Key Minting (500 req/day, 60-day TTL, $0)**: `POST https://api.bitbop.dev/api/keys/free` with `{"kyber_public_key": "<2368-hex ML-KEM-768 pk>"}` (automated via `Bitbop.provisionFreeKey()`, `bitbop key mint`, or `Mint Instant Free Key (500/day) →` on `https://www.bitbop.dev/get-key`)
- **Public Sandbox API Key (Immediate Evaluation, 100 req/day/IP)**: `Authorization: Bearer test-key-1`
- **Public Endpoints (No API Key Required)**:
  - `POST https://api.bitbop.dev/api/keys/free` (Mint dedicated `bb_free_...` key; max 10 keys/IP/UTC day)
  - `GET https://api.bitbop.dev/health`
  - `GET https://api.bitbop.dev/beacon`
  - `POST https://api.bitbop.dev/escrow/reveal`
  - `POST https://api.bitbop.dev/verify`
  - `POST https://api.bitbop.dev/verify/escrow_receipt`
  - `POST https://api.bitbop.dev/api/support/ticket` (Self-auditing PoW encrypted support & billing ticket submission; max 5/IP/UTC day)
- **Authenticated Endpoints (`Authorization: Bearer <API_KEY>`)**:
  - `GET https://api.bitbop.dev/api/keys/status` (Inspect tier, remaining quota, and expiry; consumes 0 quota)
  - `POST https://api.bitbop.dev/consume`
  - `POST https://api.bitbop.dev/order`
  - `POST https://api.bitbop.dev/escrow/commit`

## Machine-Readable Documentation & Official SDK Downloads

- [Complete LLM Context & API Schemas (/llms-full.txt)](https://www.bitbop.dev/llms-full.txt): Full single-file reference containing request/response JSON schemas, SDK/CLI commands, TypeScript/JavaScript examples, and cryptographic verification steps.
- [v2.1 API Specification (/docs/API_SPEC.md)](https://www.bitbop.dev/docs/API_SPEC.md): Detailed endpoint specifications, rate-limit headers, error status codes (`400`, `401`, `403`, `409`, `410`, `413`, `425`, `429`), and payload limits.
- **Official Node.js / TypeScript SDK & CLI (`@bitbop/sdk` v2.1.0)**: `npm install https://www.bitbop.dev/downloads/bitbop-sdk-2.1.0.tgz`
- **Official Python SDK & CLI (`bitbop` v2.1.0)**: `pip install https://www.bitbop.dev/downloads/bitbop-2.1.0-py3-none-any.whl`
- [SDK Checksums Manifest (/downloads/SHA256SUMS.txt)](https://www.bitbop.dev/downloads/SHA256SUMS.txt): SHA-256 checksums for all official SDK tarballs and wheels.

## Core Interactive Pages

- [Live Wire & Browser JS Sandbox (/demo)](https://www.bitbop.dev/demo): Interactive 6-card test environment with an editable browser JS runner, active API key quota checker, and W3C `PerformanceResourceTiming` + `cf-ray` packet inspector.
- [Public Provenance & Receipt Verifier (/provenance)](https://www.bitbop.dev/provenance): Verify any `/consume`, `/order`, `/escrow/commit`, or `/escrow/reveal` receipt or inspect the live sealed beacon block. Supports deep-links: `https://www.bitbop.dev/provenance?sequence=<beacon_sequence>`, `https://www.bitbop.dev/provenance?escrow_id=<escrow_id>`, and `https://www.bitbop.dev/provenance?receipt=<urlEncodedReceiptJson>`.
- [Live Hardware & Edge Status (/status)](https://www.bitbop.dev/status): Real-time edge RTT, active beacon sequence, NIST SP 800-90B continuous health tests, and 256-bin Shannon entropy histogram.
- [API Key Provisioning (/get-key)](https://www.bitbop.dev/get-key): 1-click self-serve Free Tier key minting (`POST /api/keys/free`, 500 req/day, 60-day TTL, zero plaintext at rest) or Stripe Builder Tier ($5/mo for 50,000 req/month).
- [Self-Auditing Encrypted Helpdesk (/support)](https://www.bitbop.dev/support): Submit billing/key recovery, subscription cancellation, Enterprise custom quota, technical support, or security vulnerability tickets protected by 16-bit WebCrypto `SHA-256` Proof-of-Work, `AES-256-GCM` encryption, and `ML-DSA-44` signed ticket receipts.

## Use-Case & Test Environment Guide (`/demo` & `/get-key`)

1. **Auditing Sealed Hardware Entropy at Rest**:
   - **Approach**: Query `GET /beacon` to verify that 1 MiB hardware blocks are Quantum-Safe sealed (`entropy.sealed: true`, zero plaintext `bytes_hex` at rest) and signed with `ML-DSA-44`.
   - **Test on `/demo`**: Run **Card 1 (`1. Sealed Beacon Block Inspector`)** by clicking `Fetch Live Sealed Block (GET /beacon)`.
2. **Quantum Dice & Cryptographic Key Generation**:
   - **Approach**: Call `POST /consume` to draw physical quantum bytes and `POST /verify` to cryptographically validate the receipt and detect any byte tampering.
   - **Test on `/demo`**: Run **Card 2 (`2. Quantum Dice Roller & Key Forge`)** — click `Step 1: Roll Quantum Dice (POST /consume)`, then click `Step 2: Send Edited Receipt Above to POST /verify`.
3. **Securing a Random Draw for a Raffle / Giveaway**:
   - **Approach**: Submit the participant list to `POST /order` for an unbiased 32-bit rejection-sampled Fisher-Yates shuffle, then verify the signed receipt and `original_items` via `POST /verify`.
   - **Test on `/demo`**: Run **Card 3 (`3. Provably Fair Raffle / Giveaway Draw`)** — click `Step 1: Draw Winners (POST /order)`, then click `Step 2: Verify Boxes Above on POST /verify`.
4. **Sealing a Pre-Generated Game Run Sheet (Zero-Storage)**:
   - **Approach**: Seal the run sheet with zero payload storage via `POST /escrow/commit` (`store_sealed_envelope: false`, `reveal_policy: "forever"`), keep the ciphertext bundle locally, then unseal via public `POST /escrow/reveal` + WebCrypto `AES-256-GCM` and verify via `POST /verify`.
   - **Test on `/demo`**: Run **Card 4 (`4. Game Run Sheet (Keep Sealed Locally, forever)`)** — click `Step 1: Commit & Seal Run Sheet`, then `Step 2: Public Reveal`, then `Step 3: Decrypt Local Bundle (WebCrypto) + Verify Receipt (/verify)`.
5. **One-Time Password / Shortcode Delivery (PIN + Burn-on-Read)**:
   - **Approach**: Commit a short secret (`≤512B`) via `POST https://api.bitbop.dev/escrow/commit` (`Authorization: Bearer <API_KEY>`, `context_hash: "sha256:<64hex>"`, `seal_payload_b64: "<base64>"`, `store_sealed_envelope: true`, `reveal_policy: "once"`, `unlock_key: "<PIN>"`, `signature_scheme: "ml-dsa-44"`), then unseal via public `POST https://api.bitbop.dev/escrow/reveal` (`escrow_id`, `unlock_key`, `kyber_public_key: "<2368-hex ML-KEM-768 pk>"`, `signature_scheme: "ml-dsa-44"`). Returns `403` on wrong PIN (without burning), `200` on valid PIN (returning `cipher` + `sealed_envelope` and permanently burning the record), and `409` on any subsequent read.
   - **Decryption Formula (`POST /escrow/reveal` -> Plaintext)**:
     1. In Node.js (`npm install mlkem`), instantiate `import { MlKem768 } from 'mlkem'; const kem = new MlKem768(); const [publicKey, secretKey] = await kem.generateKeyPair();` (pass `Buffer.from(publicKey).toString('hex')` as `kyber_public_key` in `POST https://api.bitbop.dev/escrow/reveal`).
     2. Decapsulate `cipher.kyber_ciphertext_hex` with `secretKey`: `const sharedSecret = await kem.decap(Buffer.from(cipher.kyber_ciphertext_hex, 'hex'), secretKey);` (raw 32 bytes).
     3. Use the raw 32-byte `Buffer.from(sharedSecret)` directly as an `AES-256-GCM` key (do NOT hash `sharedSecret`) with `iv = Buffer.from(cipher.aes_iv_hex, 'hex')` to decrypt `Buffer.from(cipher.aes_ciphertext_hex, 'hex')` (last 16 bytes are the GCM authTag). Convert the decrypted 32 raw bytes to hex: `const entropyHex = plainBytes.toString('hex')` (64 lowercase hex chars).
     4. Derive the envelope key via `const envKey = crypto.createHash('sha256').update(entropyHex, 'utf8').digest()`, and use `AES-256-GCM` with `iv = Buffer.from(sealed_envelope.iv_hex, 'hex')` to decrypt `Buffer.from(sealed_envelope.ciphertext_b64, 'base64')` (last 16 bytes are the GCM authTag) into UTF-8 plaintext! (Or use `@bitbop/sdk`: `await client.escrowCommit(...)` and `await client.escrowReveal(escrowId, { unlockKey })` which automates steps 1–4.)
     5. **Receipt & Provenance Verification**: Both `POST /escrow/commit` and `POST /escrow/reveal` return the signed receipt fields (`escrow_id`, `commitment_hash`, `beacon_sequence`, `beacon_hash`, `signature`, `signature_scheme`) at the **top level** of the JSON response (`data` itself is the receipt — NOT nested under `data.receipt`). Verify by POSTing the response JSON directly to `POST https://api.bitbop.dev/verify` (`body: JSON.stringify(data)`) or `POST https://api.bitbop.dev/verify/escrow_receipt`, and link users to `https://www.bitbop.dev/provenance?sequence=${data.beacon_sequence}&escrow_id=${data.escrow_id}`.
   - **Test on `/demo`**: Run **Card 5 (`5. One-Time Password / Shortcode`)** — click the button `Step 1: Commit Hosted Secret (POST /escrow/commit)` (this pre-fills the reveal request box with `"wrong-pin-try-me"`), then immediately click the button `Step 2: Send Editable Reveal Request Above to POST /escrow/reveal` (verifies `HTTP 403 Forbidden` on wrong PIN), then click the button `✏️ Set PIN in Box to "rosebud-42"`, and click `Step 2: Send Editable Reveal Request Above to POST /escrow/reveal` again (verifies `HTTP 200 OK` unseal).
6. **Time-Capsule Sealed Prediction (Embargo Lock)**:
   - **Approach**: Commit a prediction with `unlock_after_seconds` via `POST /escrow/commit`; calling `POST /escrow/reveal` before `unlock_at` returns `HTTP 425 Too Early`.
   - **Test on `/demo`**: Run **Card 6 (`6. Time-Capsule Sealed Prediction`)** — click the button `Step 1: Lock Time-Capsule (POST /escrow/commit)` (locks for 30s), then immediately click the button `Step 2: Send Reveal Request Above to POST /escrow/reveal` while the timer is counting down to verify `HTTP 425 Too Early`.
7. **Self-Serve Free Tier API Key Provisioning & Live Wire Verification**:
   - **Approach**: Navigate to `/get-key` (or call `POST /api/keys/free`) to mint a dedicated `bb_free_...` hardware-TRNG API key (500 req/day, 60-day TTL, zero plaintext at rest), load it into `/demo`, verify its active quota via `GET /api/keys/status`, and consume signed quantum entropy using the new key.
   - **Test on `/get-key` & `/demo`**: On `/get-key`, click `Mint Instant Free Key (500/day) →`, then click `Load Key into Live Wire (/demo) →`, then on `/demo` click `Check Key Quota` (verifies `ACTIVE KEY (FREE)` with `500 / 500 remaining`), and click `Step 1: Roll Quantum Dice (POST /consume)` on Card 2.