multirandom 0.0.4__tar.gz → 0.0.6__tar.gz

multirandom-0.0.6/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 BlackCatOfficialytb
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

multirandom-0.0.6/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: multirandom
+Version: 0.0.6
+Summary: 🎲 The truth external PyPI random package, have trng (true randomness), prng_unsecure, csprng, ...
+Author-email: BlackCatOfficialytb <quanvm0501@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/BlackCatOfficialytb/multirandom
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp
+Requires-Dist: pyautogui
+Requires-Dist: geopy
+Provides-Extra: microphone
+Requires-Dist: real-random>=0.1.1; extra == "microphone"
+Dynamic: license-file
+
+# MultiRandom 🎲
+
+A comprehensive library for exploring and generating randomness across the spectrum—from true physical entropy to mathematical pseudo-randomness and everything in between.
+
+## 🌟 Overview
+
+**MultiRandom** is designed for developers, researchers, and hobbyists who want to understand high-quality randomness. It provides tools to fetch random data from quantum sources, physical human interaction, and modern mathematical algorithms.
+
+> [!WARNING]
+> **Security Note**: This library contains both "True" and "Pseudo" random sources. While some sources (like QRNG) are highly secure, others (like LCGs) are provided for educational purposes and include **reverse logic** to demonstrate their insecurity. Always use the appropriate generator for your use case.
+
+---
+
+## 🏗 Project Structure
+
+```text
+multirandom/
+└── src/
+    └── multirandom/
+        ├── trng/               # True / Physical Entropy
+        │   ├── rand_via_clicks.py        # Human-in-the-loop entropy
+        │   ├── rand_using_online_api.py  # Quantum & Hardware APIs (ANU QRNG, Roll-API)
+        │   ├── rand_using_real_random.py # Microphone entropy (real-random)
+        │   └── weather_rand.py           # [Coming Soon] Weather-based entropy
+        ├── csprng/             # Cryptographically Strong Randomness
+        │   ├── secure_rand.py            # OS CSPRNGs, NIST DRBGs, Fortuna/Yarrow, ISAAC
+        │   ├── sha_rand.py               # MD5, SHA-1/2/3, BLAKE2, SHAKE PRNGs
+        │   └── original_random.py        # Wrapper for Python's built-in random
+        └── prng_unsecure/      # Mathematical Randomness (UNSECURE PRNGs)
+            ├── xor_shift.py              # XorShift & Xoshiro Family
+            ├── rand_using_virt_lcg.py    # Linear Congruential Generators (LCGs)
+            └── flash_rand_and_reverse.py # [Coming Soon] Specialized PRNGs
+```
+
+---
+
+## 🛠 Features & Usage
+
+### 1. Human-in-the-loop Entropy (`trng`)
+Uses `pyautogui` and Windows API to capture sub-microsecond timing jitter and spatial coordinates from physical mouse clicks.
+
+```python
+from multirandom.trng.rand_via_clicks import RealRandomUsingBetweenMixedClicks
+
+# Requires a sequence of Left -> Right -> Middle clicks to seed
+gen = RealRandomUsingBetweenMixedClicks()
+print(gen.random())
+```
+
+### 2. Physical & Hardware APIs (`trng`)
+Fetch "True" randomness from remote physical processes.
+
+- **Australian National University (ANU)**: Quantum vacuum noise via QRNG.
+- **Random.org**: Atmospheric noise.
+- **Roll-API**: Physical dice rolling hardware.
+- **Microphone**: Ambient audio noise via [`real-random`](https://pypi.org/project/real-random/) (optional extra).
+- **Weather Entropy**: (In development) Fetching randomness from real-time weather stations.
+
+```python
+from multirandom.trng.rand_using_real_random import MicrophoneRandom
+
+gen = MicrophoneRandom()   # captures ~1-2 s of ambient audio
+print(gen.random())
+gen.reseed()               # capture fresh entropy on demand
+```
+
+### 3. Bit-Shift Generators (`prng_unsecure`)
+Implementations of the most popular mathematical generators used in modern systems.
+
+- **Original XorShift**: `Xorshift32` / `Xorshift64` / `Xorshift128`, each with `reverse_roll()` to demonstrate mathematical reversibility. `Xorshift32` also inverts via increasing increments (`reverse_roll_increments()`), shift doubling (`reverse_roll_doubling()`) and GF(2) matrix inversion (`reverse_roll_matrix()`) — all equivalent.
+- **Scrambled Variants**: Xorwow (CUDA), Xorshift\* & Xorshift1024\* (Vigna), Xorshift+ (V8/Webkit).
+- **Modern Xoshiro**: Xoshiro128 `+`/`++`/`**`, Xoshiro256 `+`/`++`/`**`, Xoroshiro64 `*`/`**`, Xoroshiro128 `+`/`++`/`**` (Minecraft Java 1.18+ uses `++`).
+
+Run `python -m multirandom.prng_unsecure.xor_shift` to check every generator against reference vectors.
+
+### 4. Mathematical LCGs (`prng_unsecure`)
+Classic Linear Congruential Generators with customizable shift parameters. Includes `reverse_roll()` methods to demonstrate the insecurity of simple modular arithmetic.
+
+### 5. Hash-based Generators (`csprng`)
+Counter-mode hash DRBGs: `H(seed || counter)` drives the full `random.Random` API.
+
+- **SHA-2**: SHA-224, SHA-256, SHA-384, SHA-512
+- **SHA-3**: SHA3-224, SHA3-256, SHA3-384, SHA3-512
+- **Extendable output**: SHAKE-128, SHAKE-256
+- **BLAKE2**: BLAKE2b, BLAKE2s
+- **Legacy (educational only)**: MD5, SHA-1
+
+```python
+from multirandom.csprng.sha_rand import BLAKE2bRandom
+
+gen = BLAKE2bRandom("my seed")
+print(gen.randbytes(16).hex(), gen.random(), gen.choice(["a", "b"]))
+```
+
+### 6. Cryptographically Strong Generators (`csprng/secure_rand`)
+The ones to actually guard things with, plus deliberately broken ones that teach.
+
+**OS-level CSPRNGs** (live entropy, behave like `random.SystemRandom` — seeding
+is a no-op and state cannot be restored):
+
+| Class | Source |
+|---|---|
+| `SecretsRandom` | the `secrets` module (+ `token_bytes` / `token_hex` / `token_urlsafe`) |
+| `OSURandom` | plain `os.urandom` |
+| `GetRandomRandom` | Linux `getrandom(2)` |
+| `BCryptGenRandomRandom` | Windows `BCryptGenRandom` |
+| `SecRandomCopyBytesRandom` | Apple `SecRandomCopyBytes` |
+
+The ctypes ones fall back to `os.urandom` (the same kernel entropy pool) when
+the native API is not reachable on the running platform.
+
+**NIST SP 800-90A DRBGs** (seedable, deterministic from an explicit seed, full
+`random.Random` API with `getrandbits` / `randbytes` / `choice` / `shuffle` ...):
+
+- `CTR_DRBG` – AES-128 with the §10.5.1 derivation function
+- `HMAC_DRBG` – HMAC-SHA-256
+- `Hash_DRBG` – SHA-256 with Hash_df (440-bit state)
+- `Dual_EC_DRBG` — *deliberately backdoored*, kept as a teaching exhibit
+
+**Stream / accumulator designs**: `ChaCha20DRBG`, `Salsa20DRBG` (counter-mode
+DRBGs on the two classic stream ciphers), `FortunaRandom` (32 seed pools +
+AES-256-CTR, rekey every 65536 blocks, `add_entropy(data, pool)`) and its
+legacy predecessor `YarrowRandom` (fast/slow pools, AES-192-CTR), plus
+`ISAACRandom` (Bob Jenkins' ISAAC, validated against his reference vectors).
+
+```python
+from multirandom.csprng.secure_rand import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
+
+gen = SecretsRandom()
+print(gen.token_hex(32))            # live kernel entropy
+
+drbg = CTR_DRBG("my secret seed")   # deterministic; also reseeds:
+drbg.reseed(b"fresh entropy")
+print(drbg.randbytes(32).hex())
+```
+
+#### The backdoor, live
+
+`Dual_EC_DRBG` reproduces the withdrawn NIST design: outputs are the high bits
+of `x(s*P)` on NIST P-256, the state advances to `x(s*Q)` — and whoever built
+`Q = d*P` knows `d`. `.reveal(one_block)` brute-forces the truncated bits and
+recovers the *next* internal state with the secret multiplier:
+
+```python
+victim = Dual_EC_DRBG("demo victim key", truncate_bits=8)
+first, second, third = victim.randbytes(31), victim.randbytes(31), victim.randbytes(31)
+
+s1 = victim.reveal(first, known_next=second)   # Shumow–Ferguson attack
+predictor = Dual_EC_DRBG.__new__(Dual_EC_DRBG)
+predictor.truncate_bits = 8
+predictor._s = s1
+assert predictor.randbytes(31) == second       # predicted the future
+assert predictor.randbytes(31) == third        # ...and the block after it
+```
+
+The default `truncate_bits=16` matches the standard (recovering a state costs
+about 2**15 curve multiplications — instant in C, slow in pure Python); the
+module ships with this demo running in its own self-checks at
+`truncate_bits=8`. It warns on first use. Never use it for real randomness.
+
+```python
+# Run its assert battery: python -m multirandom.csprng.secure_rand
+```
+
+### The global unsecure-prng warning switch
+Everything in `prng_unsecure/` and the backdoored `Dual_EC_DRBG` warns the first
+time it is constructed. One package-root variable controls those warnings:
+
+```python
+import multirandom
+
+multirandom.ignore_unsecure_prng_warning_do_not_set_to_true_unless_you_know_how_risky_it_is = True
+```
+
+- `False` (the default): every unsecure-PRNG warning goes to the console.
+- `True`: the warnings are ignored (not printed) — risk is all yours.
+
+---
+
+## 🚀 Installation & Setup
+
+### Requirements
+- Python 3.9+
+- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`)
+
+### Installation
+```bash
+pip install -r requirements.txt
+
+# Optional: microphone entropy source (adds numpy + sounddevice)
+pip install "multirandom[microphone]"
+```
+
+### Usage
+```python
+from multirandom.prng_unsecure.xor_shift import Xorshift32
+
+# Create a 32-bit XorShift generator
+gen = Xorshift32(seed=12345)
+print(gen.roll())
+```
+
+---
+
+## 📺 Educational Resources
+This project focuses on the limits of computer-generated randomness. For more context, check out:
+- [Why computers can't generate truly random numbers](https://youtu.be/XDsYPXRCXAs?si=oDaFsqZyNJWVXwEi)
+
+---
+
+## 📜 License
+Licensed under the [Apache License 2.0](LICENSE).

multirandom-0.0.6/README.md

@@ -0,0 +1,212 @@
+# MultiRandom 🎲
+
+A comprehensive library for exploring and generating randomness across the spectrum—from true physical entropy to mathematical pseudo-randomness and everything in between.
+
+## 🌟 Overview
+
+**MultiRandom** is designed for developers, researchers, and hobbyists who want to understand high-quality randomness. It provides tools to fetch random data from quantum sources, physical human interaction, and modern mathematical algorithms.
+
+> [!WARNING]
+> **Security Note**: This library contains both "True" and "Pseudo" random sources. While some sources (like QRNG) are highly secure, others (like LCGs) are provided for educational purposes and include **reverse logic** to demonstrate their insecurity. Always use the appropriate generator for your use case.
+
+---
+
+## 🏗 Project Structure
+
+```text
+multirandom/
+└── src/
+    └── multirandom/
+        ├── trng/               # True / Physical Entropy
+        │   ├── rand_via_clicks.py        # Human-in-the-loop entropy
+        │   ├── rand_using_online_api.py  # Quantum & Hardware APIs (ANU QRNG, Roll-API)
+        │   ├── rand_using_real_random.py # Microphone entropy (real-random)
+        │   └── weather_rand.py           # [Coming Soon] Weather-based entropy
+        ├── csprng/             # Cryptographically Strong Randomness
+        │   ├── secure_rand.py            # OS CSPRNGs, NIST DRBGs, Fortuna/Yarrow, ISAAC
+        │   ├── sha_rand.py               # MD5, SHA-1/2/3, BLAKE2, SHAKE PRNGs
+        │   └── original_random.py        # Wrapper for Python's built-in random
+        └── prng_unsecure/      # Mathematical Randomness (UNSECURE PRNGs)
+            ├── xor_shift.py              # XorShift & Xoshiro Family
+            ├── rand_using_virt_lcg.py    # Linear Congruential Generators (LCGs)
+            └── flash_rand_and_reverse.py # [Coming Soon] Specialized PRNGs
+```
+
+---
+
+## 🛠 Features & Usage
+
+### 1. Human-in-the-loop Entropy (`trng`)
+Uses `pyautogui` and Windows API to capture sub-microsecond timing jitter and spatial coordinates from physical mouse clicks.
+
+```python
+from multirandom.trng.rand_via_clicks import RealRandomUsingBetweenMixedClicks
+
+# Requires a sequence of Left -> Right -> Middle clicks to seed
+gen = RealRandomUsingBetweenMixedClicks()
+print(gen.random())
+```
+
+### 2. Physical & Hardware APIs (`trng`)
+Fetch "True" randomness from remote physical processes.
+
+- **Australian National University (ANU)**: Quantum vacuum noise via QRNG.
+- **Random.org**: Atmospheric noise.
+- **Roll-API**: Physical dice rolling hardware.
+- **Microphone**: Ambient audio noise via [`real-random`](https://pypi.org/project/real-random/) (optional extra).
+- **Weather Entropy**: (In development) Fetching randomness from real-time weather stations.
+
+```python
+from multirandom.trng.rand_using_real_random import MicrophoneRandom
+
+gen = MicrophoneRandom()   # captures ~1-2 s of ambient audio
+print(gen.random())
+gen.reseed()               # capture fresh entropy on demand
+```
+
+### 3. Bit-Shift Generators (`prng_unsecure`)
+Implementations of the most popular mathematical generators used in modern systems.
+
+- **Original XorShift**: `Xorshift32` / `Xorshift64` / `Xorshift128`, each with `reverse_roll()` to demonstrate mathematical reversibility. `Xorshift32` also inverts via increasing increments (`reverse_roll_increments()`), shift doubling (`reverse_roll_doubling()`) and GF(2) matrix inversion (`reverse_roll_matrix()`) — all equivalent.
+- **Scrambled Variants**: Xorwow (CUDA), Xorshift\* & Xorshift1024\* (Vigna), Xorshift+ (V8/Webkit).
+- **Modern Xoshiro**: Xoshiro128 `+`/`++`/`**`, Xoshiro256 `+`/`++`/`**`, Xoroshiro64 `*`/`**`, Xoroshiro128 `+`/`++`/`**` (Minecraft Java 1.18+ uses `++`).
+
+Run `python -m multirandom.prng_unsecure.xor_shift` to check every generator against reference vectors.
+
+### 4. Mathematical LCGs (`prng_unsecure`)
+Classic Linear Congruential Generators with customizable shift parameters. Includes `reverse_roll()` methods to demonstrate the insecurity of simple modular arithmetic.
+
+### 5. Hash-based Generators (`csprng`)
+Counter-mode hash DRBGs: `H(seed || counter)` drives the full `random.Random` API.
+
+- **SHA-2**: SHA-224, SHA-256, SHA-384, SHA-512
+- **SHA-3**: SHA3-224, SHA3-256, SHA3-384, SHA3-512
+- **Extendable output**: SHAKE-128, SHAKE-256
+- **BLAKE2**: BLAKE2b, BLAKE2s
+- **Legacy (educational only)**: MD5, SHA-1
+
+```python
+from multirandom.csprng.sha_rand import BLAKE2bRandom
+
+gen = BLAKE2bRandom("my seed")
+print(gen.randbytes(16).hex(), gen.random(), gen.choice(["a", "b"]))
+```
+
+### 6. Cryptographically Strong Generators (`csprng/secure_rand`)
+The ones to actually guard things with, plus deliberately broken ones that teach.
+
+**OS-level CSPRNGs** (live entropy, behave like `random.SystemRandom` — seeding
+is a no-op and state cannot be restored):
+
+| Class | Source |
+|---|---|
+| `SecretsRandom` | the `secrets` module (+ `token_bytes` / `token_hex` / `token_urlsafe`) |
+| `OSURandom` | plain `os.urandom` |
+| `GetRandomRandom` | Linux `getrandom(2)` |
+| `BCryptGenRandomRandom` | Windows `BCryptGenRandom` |
+| `SecRandomCopyBytesRandom` | Apple `SecRandomCopyBytes` |
+
+The ctypes ones fall back to `os.urandom` (the same kernel entropy pool) when
+the native API is not reachable on the running platform.
+
+**NIST SP 800-90A DRBGs** (seedable, deterministic from an explicit seed, full
+`random.Random` API with `getrandbits` / `randbytes` / `choice` / `shuffle` ...):
+
+- `CTR_DRBG` – AES-128 with the §10.5.1 derivation function
+- `HMAC_DRBG` – HMAC-SHA-256
+- `Hash_DRBG` – SHA-256 with Hash_df (440-bit state)
+- `Dual_EC_DRBG` — *deliberately backdoored*, kept as a teaching exhibit
+
+**Stream / accumulator designs**: `ChaCha20DRBG`, `Salsa20DRBG` (counter-mode
+DRBGs on the two classic stream ciphers), `FortunaRandom` (32 seed pools +
+AES-256-CTR, rekey every 65536 blocks, `add_entropy(data, pool)`) and its
+legacy predecessor `YarrowRandom` (fast/slow pools, AES-192-CTR), plus
+`ISAACRandom` (Bob Jenkins' ISAAC, validated against his reference vectors).
+
+```python
+from multirandom.csprng.secure_rand import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
+
+gen = SecretsRandom()
+print(gen.token_hex(32))            # live kernel entropy
+
+drbg = CTR_DRBG("my secret seed")   # deterministic; also reseeds:
+drbg.reseed(b"fresh entropy")
+print(drbg.randbytes(32).hex())
+```
+
+#### The backdoor, live
+
+`Dual_EC_DRBG` reproduces the withdrawn NIST design: outputs are the high bits
+of `x(s*P)` on NIST P-256, the state advances to `x(s*Q)` — and whoever built
+`Q = d*P` knows `d`. `.reveal(one_block)` brute-forces the truncated bits and
+recovers the *next* internal state with the secret multiplier:
+
+```python
+victim = Dual_EC_DRBG("demo victim key", truncate_bits=8)
+first, second, third = victim.randbytes(31), victim.randbytes(31), victim.randbytes(31)
+
+s1 = victim.reveal(first, known_next=second)   # Shumow–Ferguson attack
+predictor = Dual_EC_DRBG.__new__(Dual_EC_DRBG)
+predictor.truncate_bits = 8
+predictor._s = s1
+assert predictor.randbytes(31) == second       # predicted the future
+assert predictor.randbytes(31) == third        # ...and the block after it
+```
+
+The default `truncate_bits=16` matches the standard (recovering a state costs
+about 2**15 curve multiplications — instant in C, slow in pure Python); the
+module ships with this demo running in its own self-checks at
+`truncate_bits=8`. It warns on first use. Never use it for real randomness.
+
+```python
+# Run its assert battery: python -m multirandom.csprng.secure_rand
+```
+
+### The global unsecure-prng warning switch
+Everything in `prng_unsecure/` and the backdoored `Dual_EC_DRBG` warns the first
+time it is constructed. One package-root variable controls those warnings:
+
+```python
+import multirandom
+
+multirandom.ignore_unsecure_prng_warning_do_not_set_to_true_unless_you_know_how_risky_it_is = True
+```
+
+- `False` (the default): every unsecure-PRNG warning goes to the console.
+- `True`: the warnings are ignored (not printed) — risk is all yours.
+
+---
+
+## 🚀 Installation & Setup
+
+### Requirements
+- Python 3.9+
+- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`)
+
+### Installation
+```bash
+pip install -r requirements.txt
+
+# Optional: microphone entropy source (adds numpy + sounddevice)
+pip install "multirandom[microphone]"
+```
+
+### Usage
+```python
+from multirandom.prng_unsecure.xor_shift import Xorshift32
+
+# Create a 32-bit XorShift generator
+gen = Xorshift32(seed=12345)
+print(gen.roll())
+```
+
+---
+
+## 📺 Educational Resources
+This project focuses on the limits of computer-generated randomness. For more context, check out:
+- [Why computers can't generate truly random numbers](https://youtu.be/XDsYPXRCXAs?si=oDaFsqZyNJWVXwEi)
+
+---
+
+## 📜 License
+Licensed under the [Apache License 2.0](LICENSE).

{multirandom-0.0.4 → multirandom-0.0.6}/pyproject.toml

@@ -1,25 +1,30 @@
 [build-system]
-requires = ["setuptools>=61.0"]
+requires = ["setuptools>=77.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "multirandom"
-version = "0.0.4"
+version = "0.0.6"
 authors = [
   { name="BlackCatOfficialytb", email="quanvm0501@gmail.com" },
 ]
-description = "🎲 The truth external PyPI random package, have true_rand, virt_rand, hash_rand, ..."
+description = "🎲 The truth external PyPI random package, have trng (true randomness), prng_unsecure, csprng, ..."
 readme = "README.md"
 requires-python = ">=3.9"
-license = "GPL-3.0-or-later"
+license = { text = "Apache-2.0" }
 classifiers = [
     "Programming Language :: Python :: 3.9",
     "Operating System :: OS Independent",
 ]
 dependencies = [
     "aiohttp",
-	"pyautogui"
+	  "pyautogui",
+    "geopy"
 ]
 
+[project.optional-dependencies]
+# Microphone entropy source; heavy (numpy + PortAudio), so opt-in.
+microphone = ["real-random>=0.1.1"]
+
 [project.urls]
 "Homepage" = "https://github.com/BlackCatOfficialytb/multirandom"