$ cat /dev/goals▍

Goal & user stories.

urandom.ai is a modern /dev/urandom for the post-quantum era — one trustworthy source of randomness and keys, reachable as a Rust library, an HTTP API, a CLI, or an MCP server. OS-seeded, health-tested SP 800-90A randomness; crypto-agile post-quantum keys (ML-KEM-768, ML-DSA-65, hybrid X25519MLKEM768); a privacy-preserving “is anybody using this key?” check built on a verifiable OPRF (RFC 9497) that reveals nothing about the key; and a lab that shows why “never repeats” is not “random.”

Who it serves

Core randomness · urandom.ai

A1 · Secure random bytesDEV

As a developer, I want N cryptographically secure bytes as hex, so that I can seed keys/nonces without trusting a weak local RNG.

  • GET /v1/random/bytes?n=32 → 64 hex chars; out-of-range → 400.
A2 · Unbiased integerDEV

As a developer, I want a uniform integer in an inclusive range, so that I can sample without modulo bias.

  • GET /v1/random/int?min=1&max=6 → value in [1,6]; min>max → 400.
A3 · UUID v4DEV

As a developer, I want a v4 UUID from the same trusted source.

  • GET /v1/random/uuid → well-formed v4.
A4 · High-entropy passwordDEV

As a developer, I want a password over an unambiguous charset, so that I avoid home-rolled logic.

  • GET /v1/random/password?length=24 → 24 chars.
A5 · Entropy healthSEC · RES

As a security engineer, I want SP 800-90B health tests over a sample, so that I can confirm the source before relying on it.

  • GET /v1/entropy/health?samples=8192 → rct_passed, apt_passed, ones_fraction (~0.5).

Post-quantum · pqc.urandom.ai

B1 · ML-KEM-768 keypairDEV · SEC

As a developer, I want an ML-KEM-768 (FIPS 203) keypair, so that I can do post-quantum key encapsulation.

  • POST /v1/pqc/ml-kem-768/keypair → labeled keypair (hex).
B2–B4 · ML-DSA-65 keypair / sign / verifyDEV · SEC

As a developer, I want to generate, sign, and verify with ML-DSA-65 (FIPS 204), so that signatures are quantum-resistant.

  • POST /v1/pqc/ml-dsa-65/{keypair,sign,verify}; verify → {valid:true|false}.
B5 · Crypto-agilitySEC

As a security engineer, I want every key tagged with its algorithm, so that I can retire a broken primitive without changing call sites.

  • Every keypair/sign response carries an explicit algorithm field.
B6 · Hybrid X25519MLKEM768 (library)SEC · DEV

As a security engineer, I want hybrid key agreement that holds if either the classical or PQC half survives.

  • urandom-pqc::hybrid::combine (HKDF-SHA256). Library only — not an HTTP endpoint.
B7 · Register a generated keySEC

As a security engineer, I want to opt a freshly generated key into the seen-key registry at creation.

  • POST /v1/pqc/.../keypair?register=true → {registered}.

Privacy-preserving check · check.urandom.ai

C1 · Browser check, reveal nothingDEV · SEC

As anyone with a key, I want to check it from a web page without ever transmitting it.

  • At /check, fingerprint + blinding run in-browser (WASM); only the blinded point is sent.
  • Seen → “rotate it”; unseen → “not seen (absence ≠ safety).”
C2 · Verifiable honesty (DLEQ)SEC · RES

As a security engineer, I want the server to prove it answered with the committed key, so a cheating server can’t fake “not seen.”

  • Client verifies the DLEQ proof in finalize; GET /v1/check/params publishes ciphersuite, mode, public_key, epoch.
C3 · Check via APIDEV · AGENT

As a developer, I want the raw OPRF endpoints to run the same check from any client.

  • POST /v1/check/evaluate → {evaluated, proof, public_key}; GET /v1/check/set (ETag/304).
C4 · Register as seenSEC

As a security engineer, I want to add a key’s finalized output to the registry, warning others without revealing it.

  • POST /v1/check/register {y} → {added, size}.
C5 · Check via CLIDEV · OPS

As an operator, I want urandom check <key|file> to screen secrets from a shell or CI.

  • Reads a file or treats the arg as the literal secret; --api / URANDOM_API_URL retargets.
C6 · Check via MCPAGENT

As an AI agent, I want a check_key_exposure tool to warn a user about a compromised secret without leaking it.

  • Disabled unless URANDOM_CHECK_ENABLE=1 (the only networked tool).

Lab · lab.urandom.ai

D1 · Aperiodic ≠ randomRES · DEV

As a researcher, I want a never-repeating sequence that still fails randomness tests, so that I can show aperiodicity is not randomness.

  • GET /v1/lab/aperiodic?n=10000 → proportion_of_ones, monobit_statistic, predictable:true, note.
D2–D3 · Stats & physical sourcesRES

As a researcher, I want SP 800-22 statistics and documented physical sources, so that I understand what feeds — and what does not feed — fill_secure.

  • Honesty: fill_secure() = OS CSPRNG (trust root) + CPU jitter + x86 RDSEED, mixed via SHA-256 → Hash_DRBG (M13's "wall of entropy"). Von Neumann debiasing exists in urandom-core but isn't wired into this path; no remote/client timing is ever folded in.

MCP server & CLI

E1–E3 · MCP over stdioAGENT · SEC

As an agent developer, I want a stdio JSON-RPC MCP server with no network port and safe-by-default egress.

  • 10 tools; all local except check_key_exposure, which is off unless URANDOM_CHECK_ENABLE=1. See /mcp.
F1 · CLI bytesDEV · OPS

As an operator, I want urandom [N] [--hex|--raw] to pipe trusted entropy in scripts.

  • Default 32 bytes hex; --raw writes raw bytes; bad args exit 2.

Operations

G1–G4 · Run it safelyOPS · SEC

As an operator, I want one host-routed service with auth, CORS, security headers, persistence, health, and graceful shutdown — TLS terminating at the edge.

  • /v1 (non-check) requires an API key; /v1/check/* is public but rate-limited.
  • The check key and seen-key registry persist across restarts in production.