Entropy Lab

Expose a machine-discoverable physical-entropy contract, its pinned Ed25519 verification key, and bounded bearer-authorized source-signed samples without misrepresenting samples as keys, beacons, fairness proofs, or downstream authority.

BUSINESS CASES

Where this module fits

bounded entropy acquisition
validation-noise sampling
independent source-signature verification
source-record continuity checks
application-specific derivation input

PRIMARY CONSUMERS

Who integrates it

cryptographic protocol developers
verification and testing agents
security engineers
researchers

PREREQUISITES

What must exist first

an exact required byte count and supported encoding
entropy:write authority for generation
an implementation of hybrid-json-v1 canonicalization and Ed25519 verification
an application-specific threat, derivation, health-test, and failure model

RECOMMENDED WORKFLOW

Compose the module safely.

01
fetch current limits and endpoint discovery
02
fetch and pin the current source identity and Ed25519 public key
03
create a fresh caller nonce and stable logical-request idempotency key
04
request the minimum bounded source-signed sample
05
decode and verify length, digest, identities, canonical signature, and record commitment
06
apply the downstream protocol's domain separation, derivation, health, contributor, and failure model

AGENT INTEGRATION

Machine-use boundaries

Never use sample bytes directly as a private key and never represent source_signed as proof of suitability, uniqueness, secrecy, unbiased downstream use, lottery fairness, or oracle truth.
Match request ID and caller nonce, source ID and both key IDs, decoded byte count, sample SHA-256, canonical data signature, and record SHA-256 before accepting a sample.
sequence and previous_record_sha256 support continuity checks only; they are not public-beacon rounds and do not prove that records were not withheld.
Fetch the current source-key document on key-ID or catalog change; the current-key endpoint does not publish historical rotation or revocation policy.
Keep sample values, idempotency keys, caller nonces, and application decisions out of URLs, prompts, logs, analytics, and shared caches; responses are no-store.
Beacon rounds, account Transit keys, and legacy 1k compatibility reads remain non-executable until their independent owner models and live OpenAPI contracts exist.

Register only production-listed routes as executable tools, and re-fetch the deployed OpenAPI before generating or sending a request. Source-ready routes awaiting deployment are preparation references; planned contracts are non-executable.

MODULE CONTRACTS

Every mapped endpoint

Each operation states whether its request shape is authoritative in OpenAPI, reviewed as a planning profile, or intentionally left as an outline pending an owner schema.

GETGet service catalog/api/v2/entropyReturn supported physical sample classes, byte limits, source-signature assurance, and the current generation and source-key discovery paths.›GETList beacon rounds/api/v2/entropy/beaconsPlanned capability: list public entropy beacon rounds and verification material.›GETGet beacon round/api/v2/entropy/beacons/{round_uuid}Planned capability: return one public beacon output, commitments, contributors, and verification result.›POSTRequest protected sample/api/v2/entropy/samplesRequest a bearer-authorized entropy or noise sample carrying an Ed25519 proof from the physical entropy source.›GETGet source verification key/api/v2/entropy/source-keyReturn the gateway-pinned Ed25519 public JWK used to verify physical-source sample envelopes without exposing source credentials or private key material.›GETList transit keys/api/v2/entropy/transit-keysPlanned capability: list the authenticated account's active Transit RSA public-key identifiers and fingerprints without exposing private keys.›GETGet quantum resilient entropy bytes/api/v2/quantum/entropy/random/1kPlanned capability: list quantum resilient entropy bytes through the authoritative trust service boundary.›GETGet quantum resilient noise proof/api/v2/quantum/noise/proof/1kPlanned capability: return the assurance state for quantum resilient noise proof through the authoritative trust service boundary.›