From c6a7bf228da847589f3c680e452f8718efbe13bb Mon Sep 17 00:00:00 2001 From: corgab Date: Tue, 8 Sep 2026 17:41:51 +0000 Subject: [PATCH 1/2] docs: state that only hardware-backed entropy is genuinely random The QuantumDevice contract promised cryptographically strong entropy for every driver, while entropy.py itself describes the local simulator's bits as pseudorandom. The contract, the EntropyGenerator class docblock, the README entropy section, the Python module docstring and CLAUDE.md now say the same thing: a QPU measures genuinely random bits, the local and managed simulators draw them from a classical pseudorandom generator, and only hardware-backed entropy belongs in keys, tokens and nonces. Closes #47 --- CLAUDE.md | 1 + README.md | 4 +++- bin/python/entropy.py | 3 ++- src/Contracts/QuantumDevice.php | 8 +++++++- src/Entropy/EntropyGenerator.php | 5 +++++ 5 files changed, 18 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bdc8121..e2df8e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,6 +53,7 @@ Quantum (Facade) - **PythonBridge** only passes non-null env vars to preserve boto3 credential chain (IAM Roles). - **QPU safety:** Drivers with `synchronous_safe: false` throw on `->run()` to prevent HTTP timeouts. - **EntropyGenerator::integer()** uses rejection sampling on a 256-bit batch buffer — never modulo. +- **Entropy strength is the device's:** only a QPU yields genuinely random bits; the local and managed simulators are pseudorandom. Docblocks and README must never call simulator entropy cryptographically strong. ## Config diff --git a/README.md b/README.md index a59f1ac..bcd8773 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Laravel package for quantum computing via AWS Braket and local simulators. -Build quantum circuits, generate hardware-grade entropy, and swap backends with a single config change — all with a fluent, Laravel-native API. +Build quantum circuits, generate hardware-grade entropy from real QPUs, and swap backends with a single config change — all with a fluent, Laravel-native API. ## Requirements @@ -109,6 +109,8 @@ $hex = $entropy->hex(128); // 32-char hex string $roll = $entropy->integer(1, 6); // unbiased die roll (rejection sampling) ``` +> **Where the randomness comes from.** The bits are the measurement outcomes of qubits placed in superposition, so their quality is the device's. On a real QPU (`aws` driver with a QPU ARN) they are genuinely random. On the `local` simulator, and on the managed simulators such as SV1, the circuit is simulated classically and the outcomes come from a pseudorandom number generator: fine for development and for statistical use, not for keys, tokens or nonces. Point `Quantum::entropy('aws')` at a QPU before relying on it for anything security-sensitive. + ### Batch Execution Run several circuits in a single Python process instead of paying the interpreter start-up cost once per circuit. The results come back as a `BatchResult`, ordered like the input, which is arrayable, jsonable, countable and iterable over the individual `CircuitResult` objects. diff --git a/bin/python/entropy.py b/bin/python/entropy.py index ea13427..e913e9e 100755 --- a/bin/python/entropy.py +++ b/bin/python/entropy.py @@ -7,7 +7,8 @@ The randomness is quantum in origin: each qubit is placed in an equal superposition by a Hadamard gate and then measured, producing truly random bits -per qubit (on real hardware) or pseudorandom bits (on the local simulator). +per qubit on real hardware, or pseudorandom bits on any simulator (the local +one as well as the managed Braket simulators such as SV1). Multi-shot support allows generating longer bitstrings efficiently by running the circuit multiple times and concatenating all measurement results. diff --git a/src/Contracts/QuantumDevice.php b/src/Contracts/QuantumDevice.php index a95f2c6..60240e9 100644 --- a/src/Contracts/QuantumDevice.php +++ b/src/Contracts/QuantumDevice.php @@ -18,7 +18,13 @@ interface QuantumDevice public function executeCircuit(CircuitBuilder $circuit): CircuitResult; /** - * Generate a cryptographically strong random bit-string of the requested length. + * Generate random bytes covering the requested bit count. + * + * The strength of the randomness is the driver's, not the contract's: + * measuring qubits on real hardware (the aws driver against a QPU) yields + * genuinely random bits, while the local simulator and the aws managed + * simulators produce a classical pseudorandom simulation of the same + * circuit. Use only hardware-backed entropy for keys, tokens and nonces. */ public function generateEntropy(int $bits): string; } diff --git a/src/Entropy/EntropyGenerator.php b/src/Entropy/EntropyGenerator.php index 5d19e47..62bb2d6 100644 --- a/src/Entropy/EntropyGenerator.php +++ b/src/Entropy/EntropyGenerator.php @@ -9,6 +9,11 @@ /** * High-level entropy generator backed by a quantum device. + * + * The quality of the output is the device's: a QPU measures genuinely + * random bits, a simulator (local or managed) draws them from a classical + * pseudorandom number generator. Only hardware-backed entropy is suitable + * for security-sensitive material such as keys, tokens and nonces. */ class EntropyGenerator { From 166112002faf71c283157d0d58f8ad26efc8300f Mon Sep 17 00:00:00 2001 From: corgab Date: Tue, 8 Sep 2026 17:45:55 +0000 Subject: [PATCH 2/2] docs: stop recommending QPU-backed entropy the package cannot produce yet Entropy generation is synchronous and synchronous runs against a QPU are refused, so EntropyGenerator can only reach simulators today; the README now says to treat its output as pseudorandom and to use the platform CSPRNG for secrets. The Python docstring leads with the hardware case instead of an unqualified "quantum in origin", the aws driver comment in config no longer claims real hardware while defaulting to SV1, and the contract states the rule for any implementation rather than for the two built-in drivers. --- README.md | 4 ++-- bin/python/entropy.py | 9 +++++---- config/aether.php | 2 +- src/Contracts/QuantumDevice.php | 11 ++++++----- 4 files changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bcd8773..481891c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Laravel package for quantum computing via AWS Braket and local simulators. -Build quantum circuits, generate hardware-grade entropy from real QPUs, and swap backends with a single config change — all with a fluent, Laravel-native API. +Build quantum circuits, generate entropy from quantum measurements, and swap backends with a single config change — all with a fluent, Laravel-native API. ## Requirements @@ -109,7 +109,7 @@ $hex = $entropy->hex(128); // 32-char hex string $roll = $entropy->integer(1, 6); // unbiased die roll (rejection sampling) ``` -> **Where the randomness comes from.** The bits are the measurement outcomes of qubits placed in superposition, so their quality is the device's. On a real QPU (`aws` driver with a QPU ARN) they are genuinely random. On the `local` simulator, and on the managed simulators such as SV1, the circuit is simulated classically and the outcomes come from a pseudorandom number generator: fine for development and for statistical use, not for keys, tokens or nonces. Point `Quantum::entropy('aws')` at a QPU before relying on it for anything security-sensitive. +> **Where the randomness comes from.** The bits are the measurement outcomes of qubits placed in superposition, so their quality is the device's. Only a real QPU measures genuinely random bits; the `local` simulator and the managed Braket simulators such as SV1 simulate the circuit classically, and their outcomes come from a pseudorandom number generator. Entropy generation is synchronous, and synchronous runs against a QPU are refused by the synchronous-safety rules, so as shipped `EntropyGenerator` can only reach simulators: treat everything it returns as pseudorandom, fine for development and statistical use, not for keys, tokens or nonces. Use your platform's CSPRNG (`random_bytes()`) for secrets until an asynchronous entropy path exists. ### Batch Execution diff --git a/bin/python/entropy.py b/bin/python/entropy.py index e913e9e..7613de7 100755 --- a/bin/python/entropy.py +++ b/bin/python/entropy.py @@ -5,10 +5,11 @@ runs it with configurable shot count, and writes the resulting random bitstring to stdout. -The randomness is quantum in origin: each qubit is placed in an equal -superposition by a Hadamard gate and then measured, producing truly random bits -per qubit on real hardware, or pseudorandom bits on any simulator (the local -one as well as the managed Braket simulators such as SV1). +Each qubit is placed in an equal superposition by a Hadamard gate and then +measured. On real hardware the randomness is quantum in origin and the bits +are truly random; on any simulator (the local one as well as the managed +Braket simulators such as SV1) the circuit is simulated classically and the +bits are pseudorandom. Multi-shot support allows generating longer bitstrings efficiently by running the circuit multiple times and concatenating all measurement results. diff --git a/config/aether.php b/config/aether.php index 4fff7db..bafda5e 100644 --- a/config/aether.php +++ b/config/aether.php @@ -100,7 +100,7 @@ | | Here you may configure each quantum computing driver. The "local" | driver uses the Braket local simulator (no AWS costs). The "aws" - | driver connects to AWS Braket for real quantum hardware. + | driver connects to AWS Braket for QPUs and managed simulators (the default device_arn is the SV1 simulator). | | Any driver may declare an optional "python_provider" key pointing at a | Python provider module — either a filesystem path to a ".py" file or diff --git a/src/Contracts/QuantumDevice.php b/src/Contracts/QuantumDevice.php index 60240e9..bc1154d 100644 --- a/src/Contracts/QuantumDevice.php +++ b/src/Contracts/QuantumDevice.php @@ -20,11 +20,12 @@ public function executeCircuit(CircuitBuilder $circuit): CircuitResult; /** * Generate random bytes covering the requested bit count. * - * The strength of the randomness is the driver's, not the contract's: - * measuring qubits on real hardware (the aws driver against a QPU) yields - * genuinely random bits, while the local simulator and the aws managed - * simulators produce a classical pseudorandom simulation of the same - * circuit. Use only hardware-backed entropy for keys, tokens and nonces. + * The strength of the randomness is whatever the implementing backend + * measures, not a guarantee of this contract: real quantum hardware + * yields genuinely random bits, a simulated backend yields pseudorandom + * ones. Implementations must not present simulated bits as hardware + * entropy, and callers must rely only on hardware-backed implementations + * for keys, tokens and nonces. */ public function generateEntropy(int $bits): string; }