@mindpeeker/entropy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mindpeeker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,496 @@
+# @mindpeeker/entropy
+
+Provider-pluggable **quantum (QRNG)** and **true (TRNG)** randomness for web and Node.js.
+
+Eleven entropy backends behind one tiny interface, with composable combining strategies
+(fallback chains, XOR mixing, racing), request/response *and* streaming access, and honest
+source attribution — every result tells you where its bytes actually came from.
+
+- **Runtime-agnostic**: standard `fetch`, `WebSocket`, `globalThis.crypto` only. Zero dependencies. ESM. Node ≥ 20.3 and evergreen browsers.
+- **Exactly-n-or-throw**: `getBytes(n)` always resolves with exactly `n` bytes or throws a typed `EntropyError` — per-request caps and chunking are each provider's internal concern.
+- **Honest metadata**: providers are classified by `kind` (`qrng` / `trng` / `beacon` / `csprng`) and `privacy` (`private` / `public`) so you can't accidentally seed a secret from a public beacon.
+
+```sh
+npm install @mindpeeker/entropy    # or bun add @mindpeeker/entropy
+```
+
+Three entry points:
+
+| Import | Contents |
+|---|---|
+| `@mindpeeker/entropy` | the core: types, `EntropyError`, strategies (`fallback`/`xorMix`/`race`), `defineProvider` |
+| `@mindpeeker/entropy/providers` | **all providers** (cloud, beacons, local sensors/hardware) |
+| `@mindpeeker/entropy/node` | Node-only adapters (`nodeSerialSource`, ffmpeg, `hwRng`, `rtlSdrSource`) — browser bundlers cannot resolve this on purpose |
+
+## Quick start
+
+```ts
+import { fallback } from '@mindpeeker/entropy'
+import { anuLegacy, cryptoProvider } from '@mindpeeker/entropy/providers'
+
+// The classic: try quantum first, fall back to the local CSPRNG — and know which one served.
+const entropy = fallback([anuLegacy(), cryptoProvider()])
+
+const { bytes, sources } = await entropy.getBytes(32)
+console.log(sources.map((s) => s.name)) // ['anu-legacy'] … or ['crypto'] if ANU was down
+```
+
+## Providers
+
+| Factory | Source | Kind | Privacy | Auth | Notes |
+|---|---|---|---|---|---|
+| `cryptoProvider()` | runtime CSPRNG | csprng | private | — | always available; last link of every good fallback chain |
+| `anu({ apiKey })` | ANU quantum vacuum | qrng | private | `x-api-key` (AWS Marketplace) | ≤1024 numbers/request (chunked automatically) |
+| `anuLegacy()` | ANU quantum vacuum | qrng | private | none | **1 request/minute** (client-side gate built in); retirement announced |
+| `qrandomIo()` | IDQ Quantis photonics | qrng | private | none | free; Falcon-512-signed responses (not verified in v1) |
+| `lfdr()` | IDQ Quantis PCIe | qrng | private | none | hobby-grade lab service, no SLA |
+| `outshift({ apiKey })` | Cisco photonic QRNG | qrng | private | `x-id-api-key` (free signup) | 100k bits/day free tier |
+| `qci({ apiToken })` | QCi photonic uQRNG | qrng | private | OAuth2 token exchange | bearer token cached; auto re-auth on 401 |
+| `randomOrg({ apiKey })` | atmospheric radio noise | trng | private | JSON-RPC apiKey | honors `advisoryDelay`; 250k bits/day free |
+| `superRand({ apiKey })` | EM background noise | trng | private | key in query | **WebSocket streaming**; ≤256 values/request; wire format live-verified |
+| `drand()` | League of Entropy (threshold BLS) | beacon | **public** | none | 3 s rounds, 32 B each; mirror failover built in |
+| `nistBeacon()` | NIST full-entropy source | beacon | **public** | none | 512 bits/min; NIST: *never use as secret keys* |
+| `nqsn()` | NQSN Singapore quantum beacon | beacon | **public** | none | NIST-2.0 format, 60 s pulses |
+| `uchile()` | Random UChile hybrid beacon | beacon | **public** | none | quantum device + seismic/radio mixers, 60 s |
+| `inmetro()` | Inmetro Brazil beacon | beacon | **public** | none | `variant: 'combination'` = 10-min multi-beacon VDF mix |
+| `curby()` | CURBy (CU Boulder + NIST) | beacon | **public** | none | Twine chain, freshness guard built in |
+| `padova()` | Univ. of Padova QRNG (VSIX) | qrng | private | none | keyless PRIVATE quantum draws — the simplest QRNG API alive |
+| `qbck({apiKey})` | Quantum Blockchains aggregator (IDQ/qStream/SeQRNG/Tropos) | qrng | private | email-registration key | response parse marked VERIFY-WITH-KEY |
+| `randao()` | Ethereum RANDAO | beacon | **public** | none | 12 s slots; proposer-biasable ~1 bit — see caveats |
+| `bitcoinBeacon()` | Bitcoin block hashes | beacon | **public** | none | ~10 min cadence; miner-grindable at high cost |
+| `solanaBeacon()` | Solana blockhashes | beacon | **public** | none | ~400 ms slots; leader-influenced |
+| `tezosBeacon()` | Tezos block hashes | beacon | **public** | none | via the TzKT indexer (extra third-party trust) |
+| `flowBeacon()` | Flow protocol randomness | beacon | **public** | none | 8 B per script execution |
+| `cameraEntropy()` | camera sensor noise (shot/thermal) | trng | private | camera permission | frame-diff sign bits (AetherOnePi-style); browser or injected frames |
+| `micEntropy()` | microphone ADC noise | trng | private | mic permission | sample LSBs; browser or injected PCM |
+| `serialEntropy({...})` | ESP32 / TrueRNG / OneRNG over serial | trng | private | — | Web Serial `port` or any injected byte `source` |
+| `sensorEntropy()` | phone/tablet motion sensors | trng | private | motion permission | quantized readings → tiny credit; breadth source |
+| `sdrEntropy({source})` | RTL-SDR radio noise | trng | private | — | community-verified tier; `rtlSdrSource` from `/node` |
+| `jitterEntropy()` | CPU timing jitter | trng | private | — | Node `hrtime` (credited 1/16 bit/delta); browser only via `allowCoarseClock` |
+
+All network providers accept `fetch` (dependency injection / proxying) and a base-URL override.
+
+## Randomness classes — what you're actually getting
+
+"Random" hides four very different claims. Every provider's class, physical process and the
+actual basis of its unpredictability:
+
+| Source | Class | Physical process | Why it's unpredictable |
+|---|---|---|---|
+| `cryptoProvider` | **CSPRNG** (deterministic) | none — an algorithm seeded from OS entropy | computational hardness only; predictable to anyone holding the state |
+| `anu`, `anuLegacy` | **Quantum** (QRNG) | vacuum fluctuations of the electromagnetic field | quantum measurement — non-deterministic by the laws of physics |
+| `qrandomIo`, `lfdr` | **Quantum** (QRNG) | photon detection (ID Quantique Quantis) | quantum shot noise |
+| `outshift`, `qci`, `padova` | **Quantum** (QRNG) | photonic hardware (Cisco / QCi / Univ. Padova) | quantum optics |
+| `qbck` | **Quantum** (QRNG) | aggregated IDQ/qStream/SeQRNG/Tropos hardware | quantum optics, multi-vendor |
+| `cameraEntropy` | **Hybrid** quantum + classical | photon shot noise (lit scene — quantum) and sensor thermal noise (covered lens — classical) | photon-arrival statistics / Johnson noise |
+| `randomOrg` | **Classical TRNG** | atmospheric radio noise | chaotic macroscopic physics — deterministic in principle, unmeasurable in practice |
+| `superRand` | **Classical TRNG** | electromagnetic background noise | chaotic macroscopic physics |
+| `serialEntropy` (ESP32) | **Classical TRNG** | SAR-ADC thermal/RF noise (`bootloader_random`) | thermal noise |
+| `micEntropy` | **Classical TRNG** | microphone ADC / Johnson noise | thermal noise |
+| `sensorEntropy` | **Classical TRNG** | accelerometer/gyroscope MEMS noise | thermal/mechanical noise (heavily quantized in browsers) |
+| `sdrEntropy` | **Classical TRNG** | radio front-end thermal noise (RTL-SDR) | thermal noise; RF-injectable — mixing tier |
+| `hwRng` | varies | whatever the kernel's `/dev/hwrng` driver trusts | device-dependent |
+| `jitterEntropy` | **Software/physical hybrid** | CPU micro-architectural timing chaos | system state too complex to model — weakest physical claim |
+| `drand` | **Cryptographic beacon** | none per round — threshold BLS signatures | cryptography + distributed trust; **PUBLIC** values |
+| `nistBeacon`, `nqsn`, `uchile`, `inmetro`, `curby` | **TRNG/QRNG-backed beacons** | operator-run physical sources | operator trust; **PUBLIC** values |
+| `randao`, `bitcoinBeacon`, `solanaBeacon`, `tezosBeacon`, `flowBeacon` | **Chain beacons** | none — consensus artifacts | economic cost of bias; **PUBLIC** and participant-influenceable |
+
+Rules of thumb: only the quantum sources are non-deterministic *in principle*; classical TRNGs
+are practically unpredictable but not fundamentally so; a CSPRNG is pure math; beacons are not
+private entropy at all — they are shared, verifiable randomness.
+
+### Chain-beacon caveats (read before using `randao`/`bitcoinBeacon`/…)
+
+Blockchain values are **public and participant-influenceable**: an Ethereum proposer can bias
+RANDAO by roughly one bit per slot by withholding a block (and more with forking strategies —
+eprint 2025/037); Bitcoin miners can discard unfavourable blocks, though at a cost estimated in
+six figures per bit (Bonneau et al., eprint 2015/1015); Solana values pass through the slot
+leader, and `tezosBeacon` additionally trusts the TzKT indexer. Use them for commitments,
+audits and `xorMix` transparency inputs. For well-engineered public randomness with distributed
+trust, prefer `drand`.
+
+## Local physical entropy
+
+The four local providers share one pipeline: raw physical samples → **continuous NIST SP 800-90B
+health tests** (Repetition Count + Adaptive Proportion, always on) → **SHA-256 extraction** with a
+conservative per-source entropy credit — or, with `conditioning: 'raw'`, a health-tested
+passthrough of the unwhitened physical bits (the provider then reports itself as `name(raw)` in
+attribution, so results are always traceable). A failing source throws
+`EntropyError('health_test')` — it never silently degrades to pseudo-randomness.
+
+```ts
+import { xorMix } from '@mindpeeker/entropy'
+import { cameraEntropy, cryptoProvider, serialEntropy } from '@mindpeeker/entropy/providers'
+
+// Browser webcam, whitened:
+const cam = cameraEntropy() // getUserMedia; cover the lens for pure thermal noise
+
+// Raw hotbits for oracle/radionics workflows — unwhitened frame-diff sign bits:
+const rawCam = cameraEntropy({ conditioning: 'raw' })
+
+// Defense in depth stays available:
+const belt = xorMix([cam, cryptoProvider()])
+```
+
+### Serial hardware in the BROWSER (Web Serial)
+
+The `serialEntropy` provider works in Chromium (89+, Android 148) and Firefox (151+) today —
+no adapter needed, just a user gesture on an HTTPS page:
+
+```ts
+const port = await navigator.serial.requestPort() // user picks the ESP32/TrueRNG
+const hw = serialEntropy({ port, name: 'esp32' })
+```
+
+### More boards: the firmware collection
+
+[`firmware/`](firmware/) ships ready-to-flash sketches speaking the same raw-serial contract:
+**Raspberry Pi Pico 2** (⭐ $5, real TRNG), **STM32F405/407** (⭐ best quality — but beware:
+F401/F411 "Black Pill" and F446 have NO RNG peripheral), nRF52840, Arduino+avalanche-diode
+(DIY tier, parts list included) and ESP8266 (compat-only). See `firmware/README.md` for the
+full comparison table.
+
+### Motion sensors (phones/tablets)
+
+```ts
+import { sensorEntropy } from '@mindpeeker/entropy/providers'
+const motion = sensorEntropy() // Generic Sensor API, DeviceMotion fallback (iOS asks permission)
+```
+
+Browsers quantize readings (0.1 m/s² / 0.1 °/s), so the credited entropy is deliberately tiny
+(≤1 bit per reading; a 32-byte block takes several seconds even in motion). A frozen device
+trips the health tests instead of producing fake entropy. Breadth source — mix it, don't rely
+on it.
+
+### RTL-SDR radio noise (community-verified tier)
+
+```ts
+import { sdrEntropy } from '@mindpeeker/entropy/providers'
+import { rtlSdrSource } from '@mindpeeker/entropy/node'
+
+const radio = sdrEntropy({ source: await rtlSdrSource() }) // 70 MHz, max manual gain
+```
+
+Follows the rtl-entropy pipeline (6 LSBs per IQ sample, von Neumann, health tests on raw).
+Needs the `rtl_sdr` CLI + a ~$35–45 dongle; **RTL-SDR Blog V4 requires the rtlsdrblog driver
+fork** — stock drivers silently corrupt V4 output, which the raw health tests are there to
+catch. RF injection attacks on TRNGs are demonstrated in the literature: treat radio noise as
+a mixing source, never a sole root of trust. This provider is community-verified (built from
+documented behavior, no hardware on the author's desk).
+
+### ESP32 (AetherOnePi firmware)
+
+Flash the [AetherOnePi ESP32 sketch](https://github.com/isuretpolos/AetherOnePi) (streams raw
+`esp_fill_random` bytes at 921 600 baud — keep `bootloader_random_enable()` on) and read it:
+
+```ts
+// Browser (Chromium, Web Serial):
+const port = await navigator.serial.requestPort()
+const esp32 = serialEntropy({ port, name: 'esp32' })
+
+// Node (macOS/Linux, zero deps — stty + fs):
+import { nodeSerialSource } from '@mindpeeker/entropy/node'
+const esp32 = serialEntropy({
+  source: await nodeSerialSource({ path: '/dev/cu.usbserial-110' }),
+  name: 'esp32',
+})
+```
+
+TrueRNG v3 works the same way (plain CDC read); OneRNG needs its init command via the
+`init` option (check onerng.info for your firmware).
+
+### Node camera & microphone
+
+Node has no `getUserMedia`; inject frames/PCM — the built-in adapters spawn `ffmpeg`
+(must be installed) with zero npm dependencies:
+
+```ts
+import { ffmpegFrameSource, ffmpegSampleSource, hwRng } from '@mindpeeker/entropy/node'
+
+cameraEntropy({ source: ffmpegFrameSource({ device: '0' }) })        // avfoundation index / /dev/video0
+micEntropy({ source: ffmpegSampleSource({ device: ':0' }) })         // ':0' avfoundation / 'default' alsa
+hwRng()                                                              // /dev/hwrng (usually root-only)
+```
+
+## Measured performance
+
+Real measurements from `bun scripts/bench.ts` (Apple Silicon macOS, Bun 1.3, residential
+connection, 2026-07-07 — rerun it yourself; results vary with network, hardware and light):
+
+| Rank | Provider | Kind | Transport | Request | Latency | Effective rate | Notes |
+|---|---|---|---|---|---|---|---|
+| 1 | `crypto` | csprng | in-process | 1 MiB | 1 ms | ~870 MiB/s | baseline, not physical entropy |
+| 2 | `esp32` (raw) | trng | USB serial 921600 | 16 KiB | 233 ms | **~69 KiB/s** | AetherOnePi firmware, near wire speed |
+| 3 | `esp32` (conditioned) | trng | USB serial 921600 | 2 KiB | 65 ms | ~31 KiB/s | SHA-256, 2× credit |
+| 4 | `jitter` | trng | in-process | 1 KiB | 112 ms | ~9 KiB/s | hrtime deltas, conditioned |
+| 5 | `camera` (raw) | trng | ffmpeg avfoundation | 1 KiB | 1.9 s | ~540 B/s | debiased sign bits |
+| 6 | `lfdr.de` | qrng | https | 64 B | 139 ms | ~460 B/s | free, keyless |
+| 7 | `random.org` | trng | https | 64 B | 196 ms | ~330 B/s | 250k bits/day |
+| 8 | `qrandom.io` | qrng | https | 64 B | 232 ms | ~280 B/s | free, keyless |
+| 9 | `outshift` | qrng | https | 64 B | 475 ms | ~135 B/s | 100k bits/day |
+| 10 | `nist-beacon` | beacon | https | 64 B | 677 ms | ~95 B/s | PUBLIC bits |
+| 11 | `drand` | beacon | https | 64 B | 890 ms | ~72 B/s | PUBLIC bits, 2 rounds |
+| 12 | `anu` (keyed) | qrng | https | 64 B | 980 ms | ~65 B/s | quantum vacuum |
+| 13 | `superrand` (REST) | trng | https | 64 B | 1.3 s | ~51 B/s | ≤256 values/request |
+| 14 | `camera` (conditioned) | trng | ffmpeg | 64 B | 3.6 s | ~18 B/s | warmup + 8× credit dominate |
+| 15 | `anu-legacy` | qrng | https | 16 B | 1.1 s | ~14 B/s | hard 1 req/min limit |
+
+Reading the numbers:
+
+- **Cloud rates are latency-bound**, not throughput limits — a 64-byte request costs one round
+  trip, so bigger requests amortize much better (e.g. `random.org` serves up to 128 KiB per call).
+- **The ESP32 is by far the fastest physical source** — orders of magnitude ahead of any cloud
+  QRNG — which is exactly why local hardware is worth the USB cable.
+- **Camera small reads pay fixed costs** (auto-exposure warmup + the deliberately paranoid 8×
+  extraction credit). Streaming or raw mode is where it shines; covered-lens thermal mode works too.
+- For **bulk + strongest-source guarantees**, mix fast local with a cloud QRNG:
+  `xorMix([serialEntropy({...}), anu({...})])` costs one round trip regardless of size.
+
+## Entropy quality (measured)
+
+`bun scripts/quality.ts` collects RAW output from each local source and runs Shannon entropy,
+NIST SP 800-90B estimators (most-common-value, binary Markov), chi-square, serial correlation,
+monobit/runs, Monte-Carlo π and gzip compressibility. **Statistical tests can only fail a
+source, never certify one** — whitened output (all cloud providers, anything conditioned)
+passes everything by construction, so the honest subjects are the raw local sources:
+
+| Source | Sample | Shannon (b/B) | 90B MCV (b/B) | 90B Markov (b/bit) | χ² p | Serial corr | Runs z | gzip |
+|---|---|---|---|---|---|---|---|---|
+| `crypto` (baseline) | 1 MiB | 8.000 | 7.88 | 0.999 | 0.43 | 0.0013 | −1.6 | 1.000 |
+| `microphone` raw | 32 KiB | 7.994 | 7.40 | 0.996 | 0.57 | 0.0110 | 1.3 | 1.001 |
+| `esp32` raw | 1 MiB | 7.880 | 7.06 | 0.932 | 0.00 | −0.0805 | 143.7 | 0.992 |
+| `camera` raw | 64 KiB | 7.969 | 7.02 | 0.896 | 0.00 | −0.0003 | 54.7 | 1.001 |
+| `jitter` raw | 512 KiB | 2.211 | 1.29 | 0.432 | 0.00 | 0.2196 | 1024 | 0.100 |
+
+What the numbers say (and why the credited H values hold up):
+
+- **`esp32` raw measures 7.06 b/B against a credited 7 b/B** — almost exactly on target. Note
+  it is *not* perfectly white (visible serial correlation and run structure), which is precisely
+  why the library still conditions it by default instead of trusting `esp_fill_random` blindly.
+- **`camera` raw (post-von-Neumann) measures 7.02 b/B against a credited 1 b/B** — a 7× safety
+  margin. The χ²/runs failures show real residual structure; the 8× extraction credit absorbs it.
+- **`microphone` raw measures 7.40 b/B against a credited 2 b/B** — the MacBook mic's ADC noise
+  LSBs are surprisingly clean; the 4× credit leaves a comfortable margin for worse microphones.
+- **`jitter` raw is heavily structured** (Shannon 2.2, gzip-compressible to 10%!) — validating
+  the ultra-conservative 1/16 b credit (measured MCV 1.29 → 20× margin).
+- `crypto` aces everything, as any CSPRNG must — which is exactly why passing proves nothing.
+
+### Whitened sources (sanity check, not a ranking)
+
+The same battery over the cloud providers, with quota-polite sample sizes. All of these are
+whitened server-side, so differences here are **sample-size artifacts, not quality differences**
+— the 90B MCV estimator subtracts a confidence penalty that shrinks with √N, which is why
+smaller samples score lower. The value of this table is catching a *broken* source (none were):
+
+| Source | Sample | Shannon (b/B) | 90B MCV (b/B) | χ² p | Serial corr | Quota spent |
+|---|---|---|---|---|---|---|
+| `qrandom.io` | 32 KiB | 7.994 | 7.44 | 0.40 | 0.0037 | fair-use |
+| `lfdr.de` | 32 KiB | 7.994 | 7.44 | 0.26 | −0.0072 | fair-use |
+| `random.org` | 16 KiB | 7.989 | 7.22 | 0.43 | 0.0025 | ~52% of daily bits |
+| `superrand` | 8 KiB | 7.972 | 6.91 | 0.01 | −0.0142 | ~1.6% of free allowance |
+| `drand` | 8 KiB | 7.980 | 6.91 | 0.89 | 0.0026 | free (256 rounds) |
+| `anu` | 8 KiB | 7.976 | 6.88 | 0.18 | 0.0125 | 8 requests |
+| `nist-beacon` | 4 KiB | 7.959 | 6.67 | 0.80 | 0.0006 | free (64 pulses) |
+| `outshift` | 4 KiB | 7.954 | 6.54 | 0.46 | 0.0010 | ~33% of daily bits |
+
+(`anu-legacy` is skipped by design: at 1 request/minute a meaningful sample would take hours,
+and the keyed `anu` endpoint reads the same physical source.)
+
+### In plain English — what do these numbers mean?
+
+Entropy quality = **how hard it is to guess the next byte**. A perfect source gives 8 bits of
+surprise per byte; a broken source repeats itself. What each measure tells you:
+
+| Measure | Good | Bad | In simple words |
+|---|---|---|---|
+| Shannon (b/B) | close to 8 | low | how much *surprise* each byte carries on average |
+| 90B MCV (b/B) | close to 8 | low | how hard the *best possible guesser* finds the next byte — the strictest measure |
+| 90B Markov (b/bit) | close to 1 | low | does the next bit depend on the previous one? low = it has "memory" |
+| χ² p | 0.01 – 0.99 | ≈ 0 | are all 256 byte values used equally often? p ≈ 0 = suspiciously uneven |
+| Serial corr | ≈ 0 | far from 0 | does one byte predict the next? |
+| Runs z | between −3 and 3 | large | are there too many (or too few) streaks of same bits? |
+| gzip | ≈ 1.0 | low | randomness cannot be compressed — if zip makes it smaller, it has patterns |
+
+**Simple quality ranking of your real (raw) sources:**
+
+| Rank | Source | Grade | In simple words |
+|---|---|---|---|
+| 🥇 | `esp32` raw | **excellent** | almost perfect randomness at high speed — the best real source you own. Tiny patterns exist, so we still clean it up by default |
+| 🥇 | `camera` raw | **excellent** | real physical noise, ~7 of 8 bits are genuinely unguessable — and we only "count" 1 of them, a 7× safety margin |
+| 🥈 | `microphone` raw | **excellent** | surprisingly clean noise from the mic; also runs with a big safety margin |
+| 🥉 | `jitter` raw | **weak** | full of patterns (you can zip it to 10%!) — only safe because we squeeze 32 raw bytes into every 1 output byte |
+| — | `crypto` | perfect but *fake* | flawless numbers, but from math, not physics — a very good magician, not nature |
+| — | all cloud sources | pass | cleaned up (whitened) before they reach you, so tests cannot tell them apart — choose them by *trust and physics class*, not by these numbers |
+
+Machine-readable version of all results: [`docs/quality.json`](docs/quality.json)
+(regenerated on every `bun run quality`).
+
+### Noise bitmaps
+
+Raw bytes rendered as 256×256 grayscale (`docs/noise/`) — human eyes are ruthless pattern
+detectors. The ESP32 is clean white noise; jitter shows its timer-quantization banding:
+
+| `esp32` raw | `camera` raw | `jitter` raw | `crypto` |
+|---|---|---|---|
+| ![esp32 raw noise](docs/noise/esp32-raw.png) | ![camera raw noise](docs/noise/camera-raw.png) | ![jitter raw noise](docs/noise/jitter-raw.png) | ![crypto noise](docs/noise/crypto.png) |
+
+### Sustained streaming (steady state)
+
+`bun scripts/stream-bench.ts` measures `stream()` throughput after the first chunk — i.e.
+without session setup, permissions or warmup:
+
+| Source | Steady-state rate | Notes |
+|---|---|---|
+| `esp32` raw | 68.8 KiB/s | wire-speed passthrough |
+| `esp32` conditioned | 29.7 KiB/s | SHA-256, 2× credit |
+| `jitter` conditioned | 8.6 KiB/s | |
+| `camera` conditioned | 0.28 KiB/s | 15× the single-call figure — warmup dominates small reads |
+| `superrand` WebSocket | 0.09 KiB/s | round-trip bound (one 32 B request in flight) |
+| `drand` beacon | 0.01 KiB/s | by design: one public 32 B round every 3 s |
+
+### Honest labels
+
+- `jitterEntropy()` in the browser requires `allowCoarseClock: true` and is named
+  `jitter(coarse)`: real but **unquantified** entropy — only ever mix it via `xorMix`,
+  never use it alone. The Node variant (nanosecond `hrtime`) is credited very
+  conservatively at 1/16 bit per timing delta.
+- Camera/mic quality varies wildly with device DSP (auto-exposure, noise suppression);
+  the health tests are the guard, and cheap sensors are often *better* entropy sources.
+
+## Combining strategies
+
+Strategies implement the same `EntropyProvider` interface, so they nest arbitrarily.
+
+```ts
+import { fallback, race, xorMix } from '@mindpeeker/entropy'
+import { anu, cryptoProvider, drand, randomOrg } from '@mindpeeker/entropy/providers'
+
+// Priority order, first success wins:
+fallback([anu({ apiKey }), randomOrg({ apiKey }), cryptoProvider()])
+
+// Defense in depth: XOR of independent sources is as strong as the STRONGEST one.
+// Fails closed — if any member fails, the call fails (wrap in fallback to degrade).
+xorMix([anu({ apiKey }), cryptoProvider()])
+
+// Latency-critical: all providers start, fastest response wins, losers are aborted.
+race([anu({ apiKey }), randomOrg({ apiKey })])
+
+// Composition: auditable-but-private, and never fails:
+fallback([xorMix([drand(), cryptoProvider()]), cryptoProvider()])
+```
+
+**XOR privacy rule**: mixing a *public* beacon with at least one *independent private* source
+yields a **private** result (`xorMix` reports `privacy: 'private'` if any member is private) —
+the beacon adds public auditability without exposing the output. The independence of the
+sources is your assumption to keep: don't feed the same upstream in twice.
+
+`fallback` and `race` report the *pessimistic* privacy (public if any member is public),
+because you can't know statically which member will serve.
+
+## Streaming
+
+Every provider has a lazy, pull-based `stream()` (`AsyncIterable<Uint8Array>`):
+
+```ts
+for await (const chunk of drand().stream()) {
+  // one 32-byte value per new drand round (every ~3 s), deduplicated
+}
+
+// SuperRand streams over its WebSocket API with tagged in-flight requests,
+// transparent reconnects (3 attempts, exponential backoff) and clean teardown:
+for await (const chunk of superRand({ apiKey }).stream({ chunkBytes: 64 })) { /* … */ }
+```
+
+Default streams poll `getBytes` per pull, so provider rate limits are honored automatically
+(`anuLegacy().stream()` naturally emits at most one chunk per minute). Stop a stream with
+`break` / `return()` or an `AbortSignal`.
+
+## Errors
+
+Everything throws `EntropyError` with a `code`:
+`rate_limited` (with `retryAfterMs` when known) · `auth` · `network` · `bad_response` ·
+`insufficient_entropy` · `timeout` · `aborted` · `invalid_request` · `health_test`
+(a local source failed its continuous NIST health tests).
+
+When a strategy exhausts all members, you get `insufficient_entropy` whose `cause` is an
+`AggregateError` holding each member's error in attempt order.
+
+```ts
+try {
+  await provider.getBytes(64, { timeoutMs: 5000, signal })
+} catch (error) {
+  if (error instanceof EntropyError && error.code === 'rate_limited') {
+    console.log(`retry in ${error.retryAfterMs}ms`)
+  }
+}
+```
+
+## Custom providers
+
+```ts
+import { defineProvider } from '@mindpeeker/entropy'
+
+const myQrng = defineProvider({
+  name: 'my-hardware',
+  kind: 'qrng',
+  privacy: 'private',
+  async getBytes(n, { signal } = {}) {
+    const bytes = await readFromMyDevice(n, signal)
+    return { bytes, sources: [{ name: 'my-hardware', kind: 'qrng', privacy: 'private' }] }
+  },
+})
+```
+
+`defineProvider` gives you length validation, abort handling, whole-call timeouts and a
+default poll-based `stream()` for free.
+
+## Browser caveats
+
+- **API keys in browser code are public.** For keyed providers, proxy server-side and point
+  the provider at your proxy via `baseUrl` — or use only keyless providers client-side.
+- CORS support is unverified for several keyless services (lfdr, qrandom.io); if a provider
+  is blocked by CORS in the browser, route it through a small proxy.
+- Node 20 has no global `WebSocket` (Node ≥ 21 does): pass `superRand({ WebSocketCtor })`,
+  e.g. from the `ws` package.
+
+## Sources we evaluated — and why they're NOT providers
+
+Researched (mid-2026), rejected, and documented so nobody re-litigates them:
+
+| Candidate | Why not |
+|---|---|
+| Network RTT jitter | attacker-observable and manipulable — RFC 4086 §3.5 says such input "must not be trusted as a source of entropy"; the Linux kernel removed exactly this source (`IRQF_SAMPLE_RANDOM`, gone since 3.6). Mix-don't-credit is the only defensible pattern, so we don't ship it |
+| `/proc` interrupt/stat sampling | the kernel sees those events first and better; read-timing is our existing CPU-jitter source in disguise (no independent entropy) |
+| Disk seek timing | the classic CRYPTO'94 air-turbulence source died with spinning platters; NVMe latency is engineered for *consistency* |
+| macOS `powermetrics` / battery `ioreg` | needs root / high-inertia sensors with ≪1 bit per sample |
+| Linux thermal zones | millidegree *units*, 0.5–1 °C actual quantization — near-zero entropy |
+| RDRAND/RDSEED from JS | needs a native addon (zero-dep violation); the OS CSPRNG already mixes it |
+| BLE heart-rate straps etc. | ~1 Hz and the literature is titled "Heartbeats Do Not Make Good PRNGs" |
+| WebGPU races, DRAM (D-RaNGe), SGX | not reachable from JS/Node — speculative research |
+| CURBy-Q quantum chain | stalled since 2025-08 (same round for months) — we use the fresh CURBy-RNG chain instead |
+| USTC Jinan DIQRNG beacon | expired TLS + data stale since 2025-09 |
+| LizaOnAir "QRNG" | an ANU-*seeded PRNG* (its own metadata admits hours-old seeds) |
+| Tsotchke "Quantum RNG" | unverifiable marketing claims from a software vendor |
+| csrng.net | a CSPRNG service — out of scope |
+| beaconcha.in, Aptos/Sui/ICP randomness | now key-gated / not readable over plain HTTP |
+| WebUSB RTL-SDR in the browser | possible in principle, stale pre-V4 libraries — documented as experimental only |
+
+## Verifying against live APIs
+
+Mocked tests are authoritative for CI. To exercise real endpoints:
+
+```sh
+LIVE=1 bun test live                      # keyless providers
+LIVE=1 ANU_API_KEY=… RANDOM_ORG_API_KEY=… bun test live   # + keyed ones
+```
+
+Instead of exporting keys inline, copy the workspace's `.env.example` to `.env` (git-ignored)
+and fill in what you have — Bun loads it automatically, and each keyed provider's live test
+runs only when its variable is set.
+
+The live suite loads the nearest `.env` itself (walking up from the test file), so it works
+from the workspace root and from inside `packages/entropy` alike.
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export type EntropyErrorCode = 'rate_limited' | 'auth' | 'network' | 'bad_response' | 'insufficient_entropy' | 'timeout' | 'aborted' | 'invalid_request' | 'health_test';
+export interface EntropyErrorOptions {
+    provider?: string;
+    retryAfterMs?: number;
+    cause?: unknown;
+}
+export declare class EntropyError extends Error {
+    readonly code: EntropyErrorCode;
+    readonly provider?: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+    constructor(code: EntropyErrorCode, message: string, opts?: EntropyErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,MAAM,GACN,SAAS,GACT,cAAc,GACd,sBAAsB,GACtB,SAAS,GACT,SAAS,GACT,iBAAiB,GACjB,aAAa,CAAA;AAEjB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,SAAiB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEpB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB;CAOpF"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+export class EntropyError extends Error {
+    code;
+    provider;
+    retryAfterMs;
+    constructor(code, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = 'EntropyError';
+        this.code = code;
+        this.provider = opts.provider;
+        this.retryAfterMs = opts.retryAfterMs;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAkB;IACtB,QAAQ,CAAS;IACjB,YAAY,CAAS;IAG9B,YAAY,IAAsB,EAAE,OAAe,EAAE,OAA4B,EAAE;QACjF,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAC5E,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;IACvC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { EntropyErrorCode, EntropyErrorOptions } from './errors.js';
+export { EntropyError } from './errors.js';
+export type { ByteSource } from './internal/byte-source.js';
+export type { ConditioningMode, ConditioningOptions } from './internal/condition.js';
+export type { NistFamilyOptions } from './internal/nist-pulse.js';
+export type { ProviderSpec } from './internal/provider.js';
+export { defineProvider } from './internal/provider.js';
+export type { FallbackOptions } from './strategies/fallback.js';
+export { fallback } from './strategies/fallback.js';
+export { race } from './strategies/race.js';
+export { xorMix } from './strategies/xor.js';
+export type { EntropyKind, EntropyPrivacy, EntropyProvider, EntropyRequestOptions, EntropyResult, EntropySourceInfo, EntropyStreamOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,YAAY,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAC3D,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AACpF,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AACjE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEvD,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,YAAY,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Core of @mindpeeker/entropy: types, errors, combining strategies and the
+// custom-provider building blocks. The providers themselves live behind
+// '@mindpeeker/entropy/providers'; Node-only adapters behind
+// '@mindpeeker/entropy/node'.
+export { EntropyError } from './errors.js';
+export { defineProvider } from './internal/provider.js';
+export { fallback } from './strategies/fallback.js';
+export { race } from './strategies/race.js';
+export { xorMix } from './strategies/xor.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wEAAwE;AACxE,6DAA6D;AAC7D,8BAA8B;AAG9B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAM1C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAGvD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/internal/bits.d.ts

@@ -0,0 +1,9 @@
+/** Pack 0/1 samples into bytes, MSB first. Returns the packed bytes and any trailing bits (<8). */
+export declare function packBits(bits: readonly number[]): [Uint8Array, number[]];
+/**
+ * Von Neumann debiasing: consume bit pairs, 01→0, 10→1, 00/11 discarded.
+ * Removes bias exactly when bits are independent; yield is at most 25%.
+ * A trailing unpaired bit is dropped.
+ */
+export declare function vonNeumann(bits: readonly number[]): number[];
+//# sourceMappingURL=bits.d.ts.map

package/dist/internal/bits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.d.ts","sourceRoot":"","sources":["../../src/internal/bits.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAWxE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ5D"}

package/dist/internal/bits.js

@@ -0,0 +1,29 @@
+/** Pack 0/1 samples into bytes, MSB first. Returns the packed bytes and any trailing bits (<8). */
+export function packBits(bits) {
+    const byteCount = Math.floor(bits.length / 8);
+    const out = new Uint8Array(byteCount);
+    for (let i = 0; i < byteCount; i++) {
+        let value = 0;
+        for (let j = 0; j < 8; j++) {
+            value = (value << 1) | (bits[i * 8 + j] & 1);
+        }
+        out[i] = value;
+    }
+    return [out, bits.slice(byteCount * 8)];
+}
+/**
+ * Von Neumann debiasing: consume bit pairs, 01→0, 10→1, 00/11 discarded.
+ * Removes bias exactly when bits are independent; yield is at most 25%.
+ * A trailing unpaired bit is dropped.
+ */
+export function vonNeumann(bits) {
+    const out = [];
+    for (let i = 0; i + 1 < bits.length; i += 2) {
+        const a = bits[i];
+        const b = bits[i + 1];
+        if (a !== b)
+            out.push(a === 1 ? 1 : 0);
+    }
+    return out;
+}
+//# sourceMappingURL=bits.js.map

package/dist/internal/bits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.js","sourceRoot":"","sources":["../../src/internal/bits.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,UAAU,QAAQ,CAAC,IAAuB;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC7C,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,SAAS,CAAC,CAAA;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAE,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAY,GAAG,CAAC,CAAC,CAAA;QAC1D,CAAC;QACD,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAa,CAAC,CAAA;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACrB,IAAI,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}