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..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, 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,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. 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 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..7613de7 100755 --- a/bin/python/entropy.py +++ b/bin/python/entropy.py @@ -5,9 +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 the local simulator). +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 a95f2c6..bc1154d 100644 --- a/src/Contracts/QuantumDevice.php +++ b/src/Contracts/QuantumDevice.php @@ -18,7 +18,14 @@ 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 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; } 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 {