multirandom 0.0.7__tar.gz → 0.0.8__tar.gz

{multirandom-0.0.7 → multirandom-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multirandom
-Version: 0.0.7
+Version: 0.0.8
 Summary: 🎲 The truth external PyPI random package, have trng (true randomness), prng_unsecure, csprng, ...
 Author-email: BlackCatOfficialytb <quanvm0501@gmail.com>
 License: Apache-2.0
@@ -30,6 +30,20 @@ A comprehensive library for exploring and generating randomness across the spect
 
 ---
 
+## 📚 Full Documentation
+
+Deep-dive docs live in [`docs/`](docs/):
+
+| Page | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | installation, quickstart, which generator to pick |
+| [True randomness (`trng`)](docs/trng.md) | mouse clicks, quantum APIs, microphone, weather |
+| [Cryptographic randomness (`csprng`)](docs/csprng.md) | OS CSPRNGs, NIST DRBGs, the Dual_EC backdoor demo, Fortuna/ISAAC |
+| [Unsecure PRNGs (`prng_unsecure`)](docs/prng_unsecure.md) | XorShift/Xoshiro, LCGs, and their reversal attacks |
+| [Self-checks](docs/self-checks.md) | the assert batteries verifying every generator |
+
+---
+
 ## 🏗 Project Structure
 
 ```text
@@ -40,7 +54,7 @@ multirandom/
         │   ├── 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
+        │   └── weather_rand.py           # Open-Meteo weather entropy (large unhashed seeds)
         ├── 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

{multirandom-0.0.7 → multirandom-0.0.8}/README.md

@@ -11,6 +11,20 @@ A comprehensive library for exploring and generating randomness across the spect
 
 ---
 
+## 📚 Full Documentation
+
+Deep-dive docs live in [`docs/`](docs/):
+
+| Page | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | installation, quickstart, which generator to pick |
+| [True randomness (`trng`)](docs/trng.md) | mouse clicks, quantum APIs, microphone, weather |
+| [Cryptographic randomness (`csprng`)](docs/csprng.md) | OS CSPRNGs, NIST DRBGs, the Dual_EC backdoor demo, Fortuna/ISAAC |
+| [Unsecure PRNGs (`prng_unsecure`)](docs/prng_unsecure.md) | XorShift/Xoshiro, LCGs, and their reversal attacks |
+| [Self-checks](docs/self-checks.md) | the assert batteries verifying every generator |
+
+---
+
 ## 🏗 Project Structure
 
 ```text
@@ -21,7 +35,7 @@ multirandom/
         │   ├── 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
+        │   └── weather_rand.py           # Open-Meteo weather entropy (large unhashed seeds)
         ├── 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

{multirandom-0.0.7 → multirandom-0.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "multirandom"
-version = "0.0.7"
+version = "0.0.8"
 authors = [
   { name="BlackCatOfficialytb", email="quanvm0501@gmail.com" },
 ]

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/__init__.py

@@ -1,8 +1,14 @@
-"""multirandom - one random-number package, several philosophies of chance.
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom
+Description:
+One random-number package, several philosophies of chance:
 
-* ``prng_unsecure/`` - educational PRNGs that must never guard anything (LCGs, xorshift).
-* ``csprng/``       - cryptographically strong generators (OS entropy, NIST DRBGs, stream ciphers).
 * ``trng/``         - true/hardware entropy sources (microphones, weather, clicks, online APIs).
+* ``csprng/``       - cryptographically strong generators (OS entropy, NIST DRBGs, stream ciphers).
+* ``prng_unsecure/`` - educational PRNGs that must never guard anything (LCGs, xorshift).
 
 Everything in ``prng_unsecure/`` and the deliberately broken ``Dual_EC_DRBG`` warns the
 first time it is used. Those warnings are controlled by ONE global variable::

multirandom-0.0.8/src/multirandom/csprng/__init__.py

@@ -0,0 +1,13 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng
+Description:
+Cryptographically strong randomness: OS-level CSPRNGs (secrets / os.urandom /
+getrandom(2) / BCryptGenRandom / SecRandomCopyBytes), NIST SP 800-90A DRBGs
+(CTR, HMAC, Hash, plus the deliberately backdoored Dual_EC_DRBG with a working
+reversal demo), ChaCha20/Salsa20 counter-mode DRBGs, Fortuna and Yarrow
+accumulators, Jenkins' ISAAC, hash-based counter-mode generators (MD5, SHA-1/2/3,
+SHAKE, BLAKE2) and a passthrough wrapper for Python's random module.
+"""

multirandom-0.0.8/src/multirandom/csprng/original_random.py

@@ -0,0 +1,11 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng.original_random
+Description:
+Passthrough for Python's built-in random module (`from random import *`), kept
+so the csprng package can be imported wholesale when bundling "everything
+random". The Mersenne Twister behind it is NOT cryptographically secure.
+"""
+from random import *

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/csprng/secure_rand.py

@@ -1,4 +1,10 @@
-"""Cryptographic random generators ("csprng").
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng.secure_rand
+Description:
+Cryptographic random generators ("csprng").
 
 Three families live in this module:
 

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/csprng/sha_rand.py

@@ -1,4 +1,10 @@
-"""Hash-based pseudo-random generators.
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng.sha_rand
+Description:
+Hash-based pseudo-random generators.
 
 Each generator runs a counter through a cryptographic hash: H(seed || counter).
 This is the classic counter-mode hash DRBG construction (the same idea as NIST's

multirandom-0.0.8/src/multirandom/prng_unsecure/__init__.py

@@ -0,0 +1,12 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.prng_unsecure
+Description:
+Educational pseudo-randomness, deliberately insecure: the XorShift/Xoshiro
+family (18 generators, reference vectors included, four equivalent reversal
+attacks on Xorshift32) and classic Linear Congruential Generators with
+user-supplied forward/inverse formulas. Never use these for cryptography; every
+constructor warns once per process via the package's global warning flag.
+"""

multirandom-0.0.8/src/multirandom/prng_unsecure/flash_rand_and_reverse.py

@@ -0,0 +1,10 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.prng_unsecure.flash_rand_and_reverse
+Description:
+Placeholder for specialized PRNGs and their reversal techniques (coming soon).
+Currently prints a friendly reminder on import.
+"""
+print("coming soon :/")

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/prng_unsecure/rand_using_virt_lcg.py

@@ -1,3 +1,21 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.prng_unsecure.rand_using_virt_lcg
+Description:
+Linear Congruential Generators exactly as the textbooks write them. The class
+`LCGs` takes user-supplied formulas acting on the state s: `rules` for the
+forward step (e.g. "(s * a + c) % d") and the optional `reverse_rules` for the
+inverse step (e.g. "((s - c) * pow(a, -1, d)) % d"), with parameters a/b/c/d
+(defaults 10 / 3 / 5 / 25565) and a randomised state by default. roll()
+advances the state, reverse_roll() walks it backwards -- demonstrating the
+insecurity of simple modular arithmetic: with a few consecutive outputs, state
+(and every past and future output) is recoverable via the modular
+multiplicative inverse, so a and d must be coprime for reversal to exist.
+Intended for offline games/education, NOT cryptography; the class warns once
+per process, governed by the package's global warning flag.
+"""
 import random
 import warnings
 

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/prng_unsecure/xor_shift.py

@@ -1,3 +1,27 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.prng_unsecure.xor_shift
+Description:
+The 18-generator XorShift / Xoshiro / Xoroshiro family (Marsaglia, Vigna):
+Xorshift32/64/128, Xorwow (CUDA), XorshiftStar & Xorshift1024Star (Vigna),
+XorshiftPlus (V8/WebKit), the Xoshiro256* / Xoshiro128* variants, and the
+Xoroshiro64* / Xoroshiro128* variants (Minecraft Java 1.18+ uses Xoroshiro128++).
+Core method ``roll()`` -- one register step, one output. Register-width classes
+take a ``seed`` int; the multi-word classes take a ``seeds`` list (OS entropy
+generates one when omitted). The module's assert battery reproduces the output
+of the official C reference implementations for fixed seeds.
+
+Because every step is linear over GF(2), the state is fully reversible. Xorshift32
+ships four equivalent attacks side by side -- reverse_roll() (fixed-shift
+feedback), reverse_roll_increments() (XOR the final value at s, 2s, 3s, ...),
+reverse_roll_doubling() (XOR the intermediate value at s, 2s, 4s, ...) and
+reverse_roll_matrix() (GF(2) matrix inversion) -- plus standalone helpers
+reverse_xor_lshift/rshift, increments_xor_lshift/rshift, doubling_xor_lshift/rshift
+and gf2_inverse_matrix. Insecure for cryptography: constructing any generator
+warns once per process via the package's global warning flag.
+"""
 import functools
 import inspect
 import random

multirandom-0.0.8/src/multirandom/trng/__init__.py

@@ -0,0 +1,12 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.trng
+Description:
+True / physical entropy sources: sub-millisecond mouse-click timing jitter and
+cursor positions (Win32 + pyautogui), online quantum & hardware APIs
+(Random.org, ANU QRNG, Roll-API), ambient microphone noise via the optional
+real-random extra, and Open-Meteo weather entropy folded into large unhashed
+seeds.
+"""

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/trng/rand_using_online_api.py

@@ -1,3 +1,17 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.trng.rand_using_online_api
+Description:
+True randomness from remote physical processes, over aiohttp:
+fetch_random_org_integers() - random.org atmospheric noise (plain-text API,
+range-filterable integers); fetch_qrng_anu_integers() - the Australian National
+University QRNG, quantum vacuum shot noise returning uint8 values;
+fetch_roll_api_result() - TheLastGimbus Roll-API, a physical dice-rolling
+robot. Plain Python return values (no random.Random wrapper); every endpoint
+is best-effort and may return [] / None when unreachable.
+"""
 import aiohttp
 import asyncio
 

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/trng/rand_using_real_random.py

@@ -1,5 +1,10 @@
-"""Ambient-microphone entropy via the optional `real-random` package.
-
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.trng.rand_using_real_random
+Description:
+Ambient-microphone entropy via the optional `real-random` package.
 `real-random` (https://pypi.org/project/real-random/) records 1-2 seconds of
 microphone audio, hashes it with SHA-256 and turns the hash into random values.
 Install the optional dependency with:

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom/trng/rand_via_clicks.py

@@ -1,3 +1,19 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.trng.rand_via_clicks
+Description:
+Human-in-the-loop entropy: seeds a Mersenne Twister from the nanosecond-scale
+timing jitter between mouse clicks plus the cursor positions at click time
+(Win32 GetAsyncKeyState button polling + pyautogui cursor reading).
+RealRandomUsingBetweenLeftClicks / ...BetweenRightClicks / ...BetweenMiddleClicks
+need two clicks of their button to seed; RealRandomUsingBetweenMixedClicks needs
+a Left -> Right -> Middle sequence. Construction blocks until you click them;
+passing an explicit seed skips the interaction. Helpers is_left_click_pressed /
+is_right_click_pressed / is_middle_click_pressed and
+get_click_data(button_check_func) -> (perf_counter timestamp, cursor position).
+"""
 import pyautogui
 import time
 import ctypes

multirandom-0.0.8/src/multirandom/trng/weather_rand.py

@@ -0,0 +1,539 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.trng.weather_rand
+Description:
+A random source using the Open-Meteo weather API. Not fully random by itself,
+usable once blended with OS entropy, and no cryptographic hash touches the data.
+
+Each fetch harvests *much* more information than the original single-hour
+snapshot: the complete hourly arrays (29 variables) and daily aggregates
+(19 variables) of a rolling window (``past_days`` + ``forecast_days`` days)
+for every sampled location and moment -- thousands of real-world readings per
+call. The readings are combined WITHOUT hashing, by three techniques:
+1. *Lossless packing* -- every measurement contributes its exact IEEE-754
+   bytes to the "tape", so no information is thrown into one digest.
+2. *Von Neumann conditioning* -- tape bits are debiased pairwise
+   (01 -> 1, 10 -> 0, 00/11 dropped), the classic technique for real physical
+   noise (repeated identical readings are simply discarded).
+3. *Wide reversible fold* -- tape and reservoir chunks are folded into a
+   big-integer state with a splitmix64-derived odd multiplier and a
+   chunk-dependent bit rotation per step. The fold keeps every chunk reachable
+   (it is invertible, not a hash) and stops any single bit position from
+   dominating.
+
+The returned seed is configurable-large: 512 bits (64 bytes) by default, up to
+8192 bits (1024 bytes). Failures on every weather fetch fall back to a plain
+``os.urandom`` seed -- never a hash of the time.
+"""
+import aiohttp
+import asyncio
+import os
+import random
+import struct
+import time
+from datetime import datetime, timedelta, timezone
+from typing import List, Optional, Sequence, Tuple
+
+# --- Von Neumann table: byte -> (packed output bits, number of bits produced) ---
+# For each of the four bit pairs of a byte: 01 -> emit 1, 10 -> emit 0, 00/11 drop.
+_VN_TABLE = []
+for _byte in range(256):
+    _bits = [(_byte >> _i) & 1 for _i in range(8)]
+    _out, _k = 0, 0
+    for _i in range(0, 8, 2):
+        _b1, _b2 = _bits[_i], _bits[_i + 1]
+        if _b1 != _b2:
+            _out = (_out << 1) | _b2
+            _k += 1
+    _VN_TABLE.append((_out, _k))
+
+_SPLITMIX_MUL = 0xBF58476D1CE4E5B9
+_SPLITMIX_ADD = 0x94D049BB133111EB
+_GOLDEN = 0x9E3779B97F4A7C15
+
+
+def _von_neumann_pool(src: bytes) -> bytes:
+    """Debias *src* with the von Neumann technique and return the pool bytes.
+
+    Pairs of consecutive input bits are only used when they differ
+    (01 -> 1, 10 -> 0); equal pairs are discarded, which removes systematic
+    single-bit bias at the cost of output length (about 25 % of the input).
+    Widely used for conditioning true-RNG sensor data -- no hashing involved.
+    """
+    acc = accn = 0
+    pool = bytearray()
+    for byte in src:
+        out, k = _VN_TABLE[byte]
+        if k:
+            acc = (acc << k) | out
+            accn += k
+            while accn >= 8:
+                accn -= 8
+                pool.append((acc >> accn) & 0xFF)
+                acc &= (1 << accn) - 1
+    if accn:
+        pool.append((acc << (8 - accn)) & 0xFF)
+    return bytes(pool)
+
+
+class OpenMeteoAPI:
+    """
+    Entropy source using Open-Meteo weather API data.
+
+    Each fetch harvests the full hourly and daily series of a rolling window
+    for one location; ``get_seed`` samples several random locations and
+    moments, folds all those readings into one large seed.
+
+    Only provides entropy - use RandomUsingOpenMeteoAPI for the full random
+    interface.
+    """
+
+    BASE_URL = "https://api.open-meteo.com/v1/forecast"
+
+    # The full harvest: every hourly series the best-match model publishes.
+    HOURLY_VARIABLES = [
+        "temperature_2m",
+        "relative_humidity_2m",
+        "dew_point_2m",
+        "apparent_temperature",
+        "precipitation",
+        "rain",
+        "showers",
+        "snowfall",
+        "snow_depth",
+        "freezing_level_height",
+        "pressure_msl",
+        "surface_pressure",
+        "cloud_cover",
+        "cloud_cover_low",
+        "cloud_cover_mid",
+        "cloud_cover_high",
+        "visibility",
+        "cape",
+        "wind_speed_10m",
+        "wind_direction_10m",
+        "wind_gusts_10m",
+        "temperature_80m",
+        "soil_temperature_0_to_7cm",
+        "soil_moisture_0_to_1cm",
+        "shortwave_radiation",
+        "direct_radiation",
+        "diffuse_radiation",
+        "vapour_pressure_deficit",
+        "uv_index",
+    ]
+
+    # Daily aggregates: one row per day, still many real numbers per location.
+    DAILY_VARIABLES = [
+        "weather_code",
+        "temperature_2m_max",
+        "temperature_2m_min",
+        "apparent_temperature_max",
+        "apparent_temperature_min",
+        "precipitation_sum",
+        "rain_sum",
+        "showers_sum",
+        "snowfall_sum",
+        "precipitation_hours",
+        "precipitation_probability_max",
+        "daylight_duration",
+        "sunshine_duration",
+        "wind_speed_10m_max",
+        "wind_gusts_10m_max",
+        "wind_direction_10m_dominant",
+        "shortwave_radiation_sum",
+        "uv_index_max",
+        "et0_fao_evapotranspiration",
+    ]
+
+    # Lean retry set: the original single-snapshot variable list, in case a
+    # model/location rejects parts of the full harvest.
+    LEGACY_HOURLY_VARIABLES = [
+        "temperature_2m",
+        "relative_humidity_2m",
+        "precipitation",
+        "surface_pressure",
+        "wind_speed_10m",
+        "wind_direction_10m",
+        "cloud_cover",
+    ]
+
+    DEFAULT_SEED_BYTES = 64
+
+    def __init__(
+        self,
+        seed: Optional[int] = None,
+        forecast_days: int = 3,
+        past_days: int = 2,
+    ):
+        forecast_days = int(forecast_days)
+        past_days = int(past_days)
+        if not 1 <= forecast_days <= 16:
+            raise ValueError("forecast_days must be between 1 and 16")
+        if not 0 <= past_days <= 92:
+            raise ValueError("past_days must be between 0 and 92")
+        self._rng = random.Random(seed)
+        self._forecast_days = forecast_days
+        self._past_days = past_days
+        self._current_location: Optional[Tuple[float, float]] = None
+
+    def set_current_location(self, latitude: float, longitude: float):
+        """Set the current location for weather-based entropy."""
+        self._current_location = (latitude, longitude)
+
+    def _generate_random_location(self) -> Tuple[float, float]:
+        """Generate a random latitude and longitude."""
+        latitude = self._rng.uniform(-60, 70)
+        longitude = self._rng.uniform(-180, 180)
+        return (latitude, longitude)
+
+    def _generate_random_time(self, days_back: int = 7) -> datetime:
+        """Generate a random time within the past few days."""
+        now = datetime.now(timezone.utc)
+        random_hours = self._rng.randint(0, days_back * 24)
+        return now - timedelta(hours=random_hours)
+
+    async def _fetch_weather_data(
+        self,
+        latitude: float,
+        longitude: float,
+        target_time: Optional[datetime] = None,
+    ) -> Optional[dict]:
+        """Fetch the full hourly + daily arrays from Open-Meteo.
+
+        The full variable list is requested first; if the API rejects it for
+        this model/location (HTTP 400), the request is retried once with the
+        lean legacy list. Returns the JSON payload (may be missing variables)
+        or None.
+        """
+        params = {
+            "latitude": latitude,
+            "longitude": longitude,
+            "hourly": ",".join(self.HOURLY_VARIABLES),
+            "daily": ",".join(self.DAILY_VARIABLES),
+            "timezone": "UTC",
+            "forecast_days": str(self._forecast_days),
+            "past_days": str(self._past_days),
+        }
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(self.BASE_URL, params=params) as response:
+                    if response.status == 200:
+                        return await response.json()
+            except Exception:
+                pass
+        # Retry leaner: the full hourly list may be unsupported here.
+        lean = dict(params)
+        lean["hourly"] = ",".join(self.LEGACY_HOURLY_VARIABLES)
+        lean.pop("daily", None)
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(self.BASE_URL, params=lean) as response:
+                    if response.status == 200:
+                        return await response.json()
+            except Exception:
+                pass
+        return None
+
+    async def _fetch_current_location(self) -> Optional[Tuple[float, float]]:
+        """Fetch approximate current location via ipinfo.io (geopy fallback)."""
+        try:
+            # Free, no key needed.
+            async with aiohttp.ClientSession() as session:
+                async with session.get("https://ipinfo.io/json") as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        loc = data.get("loc", "")
+                        if loc:
+                            lat, lon = loc.split(",")
+                            return (float(lat), float(lon))
+
+            # Fallback: geocode a random major city for coarse entropy.
+            from geopy.geocoders import Nominatim
+
+            geolocator = Nominatim(user_agent="multirandom_weather")
+            cities = ["Tokyo", "New York", "London", "Sydney", "Mumbai", "São Paulo"]
+            city = self._rng.choice(cities)
+            location = geolocator.geocode(city)
+            if location:
+                return (location.latitude, location.longitude)
+            return None
+        except Exception:
+            return None
+
+    def _collect_measurements(
+        self,
+        weather_data: dict,
+        target_time: Optional[datetime] = None,
+    ) -> List[float]:
+        """Pull every real number out of a weather response (no hashing).
+
+        Gathers the complete hourly series, the daily aggregates and the
+        response metadata, plus the chosen time and the wall clock as
+        floats -- the caller packs them losslessly.
+        """
+        measurements: List[float] = []
+        hourly = weather_data.get("hourly") or {}
+        for var in self.HOURLY_VARIABLES:
+            values = hourly.get(var)
+            if isinstance(values, list):
+                measurements.extend(float(v) for v in values if v is not None)
+        daily = weather_data.get("daily") or {}
+        for var in self.DAILY_VARIABLES:
+            values = daily.get(var)
+            if isinstance(values, list):
+                measurements.extend(float(v) for v in values if v is not None)
+        for key in ("latitude", "longitude", "elevation",
+                    "generationtime_ms", "utc_offset_seconds"):
+            try:
+                measurements.append(float(weather_data[key]))
+            except (KeyError, TypeError, ValueError):
+                pass
+        if target_time is not None:
+            measurements.append(float(target_time.timestamp()))
+        measurements.append(time.time_ns() / 1e9)
+        return measurements
+
+    def _fold_odd(self, seed_bytes: int) -> int:
+        """Splitmix64-derived odd multiplier, fresh per seed width."""
+        x = _GOLDEN
+        raw = bytearray()
+        while len(raw) < seed_bytes:
+            x = (x * _SPLITMIX_MUL + _SPLITMIX_ADD) & 0xFFFFFFFFFFFFFFFF
+            raw += x.to_bytes(8, "big")
+        return int.from_bytes(bytes(raw[:seed_bytes]), "big") | 1
+
+    def _assemble_seed(self, measurements: Sequence[float], seed_bytes: int) -> int:
+        """Fold every measurement into one large integer -- hash-free.
+
+        1. exact IEEE-754 bytes of each measurement -> the "tape";
+        2. the tape's bits get von Neumann-debiased into a second stream;
+        3. both streams are folded (multiply-add + chunk-dependent rotation)
+           into a seed_bytes-wide big integer, which is returned.
+        """
+        tape = bytearray()
+        for value in measurements:
+            tape += struct.pack("<d", float(value))
+
+        pool = _von_neumann_pool(bytes(tape))
+
+        nbits = seed_bytes * 8
+        mask = (1 << nbits) - 1
+        odd = self._fold_odd(seed_bytes)
+        state = 1
+        for src in (bytes(tape), pool):
+            if not src:
+                continue
+            src += b"\x00" * (-len(src) % 8)
+            for off in range(0, len(src), 8):
+                chunk = int.from_bytes(src[off:off + 8], "big")
+                state = (state * odd + chunk) & mask
+                rot = 1 + chunk % (nbits - 1)
+                state = ((state >> rot) | ((state << (nbits - rot)) & mask)) & mask
+        return state
+
+    async def get_seed(
+        self,
+        use_random_location: bool = True,
+        use_current_location: bool = False,
+        use_random_time: bool = True,
+        num_random_locations: int = 3,
+        seed_bytes: int = DEFAULT_SEED_BYTES,
+    ) -> int:
+        """
+        Get a large seed value from weather entropy.
+
+        Args:
+            use_random_location: Fetch weather from random locations
+            use_current_location: Fetch weather from current location
+            use_random_time: Sample random moments (up to a week back)
+            num_random_locations: Number of random locations to sample (0-12)
+            seed_bytes: Seed width in bytes, 16..1024 (128..8192 bits)
+
+        Returns:
+            A big integer ``0 <= seed < 2^(8*seed_bytes)`` built from the raw
+            measurement bytes, WITHOUT cryptographic hashing (lossless tape +
+            von Neumann conditioning + reversible fold). If every fetch fails,
+            returns fresh ``os.urandom`` bytes as an int -- never a time hash.
+        """
+        seed_bytes = int(seed_bytes)
+        if not 16 <= seed_bytes <= 1024:
+            raise ValueError("seed_bytes must be between 16 and 1024")
+        num_random_locations = int(num_random_locations)
+        if not 0 <= num_random_locations <= 12:
+            raise ValueError("num_random_locations must be between 0 and 12")
+
+        targets: List[Tuple[float, float, Optional[datetime]]] = []
+        if use_random_location:
+            for _ in range(num_random_locations):
+                lat, lon = self._generate_random_location()
+                target_time = self._generate_random_time() if use_random_time else None
+                targets.append((lat, lon, target_time))
+
+        if use_current_location:
+            if self._current_location:
+                lat, lon = self._current_location
+            else:
+                location = await self._fetch_current_location()
+                if location:
+                    lat, lon = location
+                    self._current_location = location
+                else:
+                    lat, lon = 0.0, 0.0
+            target_time = self._generate_random_time() if use_random_time else None
+            targets.append((lat, lon, target_time))
+
+        measurements: List[float] = []
+        if targets:
+            results = await asyncio.gather(*(
+                self._fetch_weather_data(lat, lon, tt)
+                for lat, lon, tt in targets))
+            for data, (_lat, _lon, tt) in zip(results, targets):
+                if data:
+                    measurements.extend(self._collect_measurements(data, tt))
+
+        if not measurements:
+            return int.from_bytes(os.urandom(seed_bytes), "big")
+        return self._assemble_seed(measurements, seed_bytes)
+
+
+class RandomUsingOpenMeteoAPI(random.Random):
+    """
+    A random.Random subclass seeded with a large, unhashed weather seed.
+
+    The weather seed (64 bytes / 512 bits by default; see OpenMeteoAPI.get_seed)
+    is XORed term-to-term with fresh os.urandom noise of the same width -- a
+    perfect blend that needs no hashing -- and handed whole to Mersenne
+    Twister's state loader, which consumes the entire integer.
+    """
+
+    def __init__(
+        self,
+        auto_seed: bool = True,
+        seed_bytes: int = OpenMeteoAPI.DEFAULT_SEED_BYTES,
+    ):
+        """
+        Initialize the random generator.
+
+        Args:
+            auto_seed: If True, automatically seeds with weather entropy.
+            seed_bytes: Weather seed width in bytes, 16..1024 (default 64 =>
+                a 512-bit seed, three scales larger than the old 256-bit one).
+        """
+        self._seed_bytes = int(seed_bytes)
+        if not 16 <= self._seed_bytes <= 1024:
+            raise ValueError("seed_bytes must be between 16 and 1024")
+        self._api = OpenMeteoAPI()
+        # random.Random.__init__ calls self.seed(x); with x=None our override
+        # would trigger a weather fetch, so hand it OS entropy directly and
+        # reserve the (auto) weather seed for the explicit step below.
+        super().__init__(int.from_bytes(os.urandom(32), "big"))
+
+        if auto_seed:
+            self.seed_from_weather()
+
+    def _run_async(self, coro):
+        """Helper to run async code synchronously."""
+        try:
+            asyncio.get_running_loop()
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, coro)
+                return future.result()
+        except RuntimeError:
+            return asyncio.run(coro)
+
+    def seed_from_weather(
+        self,
+        use_random_location: bool = True,
+        use_current_location: bool = True,
+        use_random_time: bool = True,
+    ):
+        """Seed with a large weather seed XOR fresh OS noise (no hashing)."""
+        try:
+            weather_seed = self._run_async(self._api.get_seed(
+                use_random_location=use_random_location,
+                use_current_location=use_current_location,
+                use_random_time=use_random_time,
+                seed_bytes=self._seed_bytes,
+            ))
+        except Exception:
+            weather_seed = 0
+        width = max((weather_seed.bit_length() + 7) // 8, self._seed_bytes)
+        noise = int.from_bytes(os.urandom(width), "big")
+        combined = weather_seed ^ noise
+        # Feed the whole wide integer to Mersenne Twister's state loader.
+        super().seed(combined)
+
+    def seed(self, a=None, version=2):
+        """Seed the generator. If a is None, seeds from weather."""
+        if a is None:
+            self.seed_from_weather()
+        else:
+            super().seed(a, version)
+
+    def reseed_from_weather(self):
+        """Force a reseed from fresh weather data."""
+        self.seed_from_weather()
+
+
+if __name__ == "__main__":
+    api = OpenMeteoAPI(seed=1234)
+
+    # --- offline: determinism, sensitivity, configurability of the fold ---
+    tape = [api._rng.uniform(-40, 40) for _ in range(3000)]
+    s1 = api._assemble_seed(tape, 64)
+    assert s1.bit_length() <= 512, "64-byte seed overflowed 512 bits"
+    assert s1 == api._assemble_seed(list(tape), 64), "fold is not deterministic"
+    tape2 = list(tape)
+    tape2[0] += 1e-9
+    assert s1 != api._assemble_seed(tape2, 64), "seed ignores its measurements"
+    big = api._assemble_seed(tape, 128)
+    assert big.bit_length() <= 1024 and big != s1, "wider fold misbehaves"
+    tiny = api._assemble_seed(tape, 16)
+    assert tiny.bit_length() <= 128, "16-byte seed overflowed 128 bits"
+    print("OpenMeteoAPI fold: deterministic, sensitive, width-configurable: OK")
+
+    # --- offline: von Neumann conditioning really de-biases ---
+    rng = random.Random(9)
+    buf = bytearray(1 << 16)
+    # Build 65536 bytes whose bits are iid with P(1) = 0.75 (heavily biased).
+    for i in range(1 << 16):
+        acc = 0
+        for j in range(8):
+            if rng.random() < 0.75:
+                acc |= 1 << j
+        buf[i] = acc
+    raw_ratio = sum(bin(b).count("1") for b in buf) / (8 * len(buf))
+    pool = _von_neumann_pool(bytes(buf))
+    assert pool, "von Neumann pool came out empty"
+    pool_ratio = sum(bin(b).count("1") for b in pool) / (8 * len(pool))
+    assert 0.4 < pool_ratio < 0.6, \
+        f"von Neumann conditioning failed ({raw_ratio:.3f} -> {pool_ratio:.3f})"
+    print(f"Von Neumann conditioning: {raw_ratio:.3f} -> {pool_ratio:.3f} ones ratio: OK")
+
+    # --- the random.Random wrapper itself (no network needed) ---
+    g = RandomUsingOpenMeteoAPI(auto_seed=False, seed_bytes=64)
+    g.seed(42)
+    assert all(0.0 <= g.random() < 1.0 for _ in range(200))
+    assert 0 <= g.choice(range(50)) < 50
+    print("RandomUsingOpenMeteoAPI API (fixed seed): OK")
+
+    # --- live weather fetch (network guard; falls back to os.urandom) ---
+    try:
+        seed = asyncio.run(api.get_seed(num_random_locations=1, seed_bytes=64))
+        assert 0 <= seed < (1 << 512), "get_seed broke its width contract"
+        other = asyncio.run(OpenMeteoAPI(seed=5678).get_seed(num_random_locations=1))
+        assert seed != other, "two live harvests gave identical seeds"
+        g2 = RandomUsingOpenMeteoAPI(auto_seed=False, seed_bytes=64)
+        g2.reseed_from_weather()
+        assert 0.0 <= g2.random() < 1.0
+        print(f"Weather harvest + XOR-urandom reseed: OK "
+              f"(seed {seed.bit_length()} bits, top hex {hex(seed)[:10]}…)")
+    except Exception as exc:  # noqa: BLE001 - offline environment / network down
+        fallback = int.from_bytes(os.urandom(64), "big")
+        assert 0 <= fallback < (1 << 512)
+        print(f"Live weather fetch skipped ({type(exc).__name__}: {exc}); "
+              "os.urandom fallback path OK")

{multirandom-0.0.7 → multirandom-0.0.8}/src/multirandom.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multirandom
-Version: 0.0.7
+Version: 0.0.8
 Summary: 🎲 The truth external PyPI random package, have trng (true randomness), prng_unsecure, csprng, ...
 Author-email: BlackCatOfficialytb <quanvm0501@gmail.com>
 License: Apache-2.0
@@ -30,6 +30,20 @@ A comprehensive library for exploring and generating randomness across the spect
 
 ---
 
+## 📚 Full Documentation
+
+Deep-dive docs live in [`docs/`](docs/):
+
+| Page | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | installation, quickstart, which generator to pick |
+| [True randomness (`trng`)](docs/trng.md) | mouse clicks, quantum APIs, microphone, weather |
+| [Cryptographic randomness (`csprng`)](docs/csprng.md) | OS CSPRNGs, NIST DRBGs, the Dual_EC backdoor demo, Fortuna/ISAAC |
+| [Unsecure PRNGs (`prng_unsecure`)](docs/prng_unsecure.md) | XorShift/Xoshiro, LCGs, and their reversal attacks |
+| [Self-checks](docs/self-checks.md) | the assert batteries verifying every generator |
+
+---
+
 ## 🏗 Project Structure
 
 ```text
@@ -40,7 +54,7 @@ multirandom/
         │   ├── 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
+        │   └── weather_rand.py           # Open-Meteo weather entropy (large unhashed seeds)
         ├── 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

multirandom-0.0.7/src/multirandom/csprng/original_random.py

@@ -1 +0,0 @@
-from random import *

multirandom-0.0.7/src/multirandom/prng_unsecure/flash_rand_and_reverse.py

@@ -1 +0,0 @@
-print("coming soon :/")

multirandom-0.0.7/src/multirandom/trng/weather_rand.py

@@ -1,281 +0,0 @@
-import aiohttp
-import asyncio
-import random
-import hashlib
-from datetime import datetime, timedelta
-from typing import Optional, Tuple
-
-"""
-A random source using Open-Meteo weather API data.
-While still not fully random and can be spoofed, it's much more reliable than any others cuz it uses hash random from random() too.
-"""
-
-class OpenMeteoAPI:
-    """
-    Entropy source using Open-Meteo weather API data.
-    
-    Fetches weather data from random locations and times to generate entropy
-    for seeding random.Random. Only provides entropy - use RandomUsingOpenMeteoAPI
-    for the full random interface.
-    """
-    
-    BASE_URL = "https://api.open-meteo.com/v1/forecast"
-    
-    WEATHER_VARIABLES = [
-        "temperature_2m",
-        "relative_humidity_2m", 
-        "precipitation",
-        "surface_pressure",
-        "wind_speed_10m",
-        "wind_direction_10m",
-        "cloud_cover"
-    ]
-    
-    def __init__(self, seed: Optional[int] = None):
-        self._rng = random.Random(seed)
-        self._current_location: Optional[Tuple[float, float]] = None
-    
-    def set_current_location(self, latitude: float, longitude: float):
-        """Set the current location for weather-based entropy."""
-        self._current_location = (latitude, longitude)
-    
-    def _generate_random_location(self) -> Tuple[float, float]:
-        """Generate a random latitude and longitude."""
-        latitude = self._rng.uniform(-60, 70)
-        longitude = self._rng.uniform(-180, 180)
-        return (latitude, longitude)
-    
-    def _generate_random_time(self, days_back: int = 7) -> datetime:
-        """Generate a random time within the past few days."""
-        now = datetime.utcnow()
-        random_hours = self._rng.randint(0, days_back * 24)
-        return now - timedelta(hours=random_hours)
-    
-    async def _fetch_weather_data(
-        self, 
-        latitude: float, 
-        longitude: float,
-        target_time: Optional[datetime] = None
-    ) -> Optional[dict]:
-        """Fetch weather data from Open-Meteo API."""
-        params = {
-            "latitude": latitude,
-            "longitude": longitude,
-            "hourly": ",".join(self.WEATHER_VARIABLES),
-            "timezone": "UTC"
-        }
-        
-        if target_time:
-            date_str = target_time.strftime("%Y-%m-%d")
-            params["start_date"] = date_str
-            params["end_date"] = date_str
-        
-        async with aiohttp.ClientSession() as session:
-            try:
-                async with session.get(self.BASE_URL, params=params) as response:
-                    if response.status == 200:
-                        return await response.json()
-                    return None
-            except Exception:
-                return None
-    
-    async def _fetch_current_location(self) -> Optional[Tuple[float, float]]:
-        """Fetch approximate current location using IP geolocation via geopy."""
-        try:
-            from geopy.geocoders import Nominatim
-            
-            # First get public IP location using ipinfo.io (free, no key needed)
-            async with aiohttp.ClientSession() as session:
-                async with session.get("https://ipinfo.io/json") as response:
-                    if response.status == 200:
-                        data = await response.json()
-                        loc = data.get("loc", "")
-                        if loc:
-                            lat, lon = loc.split(",")
-                            return (float(lat), float(lon))
-            
-            # Fallback: use geopy to geocode a random city for entropy
-            geolocator = Nominatim(user_agent="multirandom_weather")
-            # Pick a random major city for location entropy
-            cities = ["Tokyo", "New York", "London", "Sydney", "Mumbai", "São Paulo"]
-            city = self._rng.choice(cities)
-            location = geolocator.geocode(city)
-            if location:
-                return (location.latitude, location.longitude)
-            
-            return None
-        except Exception:
-            return None
-    
-    def _extract_entropy(self, weather_data: dict, target_time: Optional[datetime] = None) -> bytes:
-        """Extract entropy bytes from weather data."""
-        entropy_values = []
-        hourly = weather_data.get("hourly", {})
-        
-        hour_index = 0
-        if target_time and "time" in hourly:
-            times = hourly.get("time", [])
-            target_hour = target_time.strftime("%Y-%m-%dT%H:00")
-            if target_hour in times:
-                hour_index = times.index(target_hour)
-            else:
-                hour_index = self._rng.randint(0, max(0, len(times) - 1))
-        elif "time" in hourly:
-            times = hourly.get("time", [])
-            hour_index = self._rng.randint(0, max(0, len(times) - 1))
-        
-        for var in self.WEATHER_VARIABLES:
-            values = hourly.get(var, [])
-            if values and hour_index < len(values) and values[hour_index] is not None:
-                entropy_values.append(values[hour_index])
-        
-        entropy_values.extend([
-            weather_data.get("latitude", 0),
-            weather_data.get("longitude", 0),
-            weather_data.get("elevation", 0),
-            datetime.utcnow().timestamp()
-        ])
-        
-        entropy_str = "|".join(str(v) for v in entropy_values)
-        return hashlib.sha256(entropy_str.encode()).digest()
-    
-    async def get_seed(
-        self,
-        use_random_location: bool = True,
-        use_current_location: bool = False,
-        use_random_time: bool = True,
-        num_random_locations: int = 2
-    ) -> int:
-        """
-        Get a seed value from weather entropy.
-        
-        Args:
-            use_random_location: Fetch weather from random locations
-            use_current_location: Fetch weather from current location
-            use_random_time: Use random times for weather data
-            num_random_locations: Number of random locations to sample
-            
-        Returns:
-            Integer seed derived from weather data
-        """
-        entropy_pool = b""
-        tasks = []
-        
-        # Random locations
-        if use_random_location:
-            for _ in range(num_random_locations):
-                lat, lon = self._generate_random_location()
-                target_time = self._generate_random_time() if use_random_time else None
-                tasks.append((self._fetch_weather_data(lat, lon, target_time), target_time))
-        
-        # Current location
-        if use_current_location:
-            if self._current_location:
-                lat, lon = self._current_location
-            else:
-                location = await self._fetch_current_location()
-                if location:
-                    lat, lon = location
-                    self._current_location = location
-                else:
-                    lat, lon = 0, 0
-            
-            target_time = self._generate_random_time() if use_random_time else None
-            tasks.append((self._fetch_weather_data(lat, lon, target_time), target_time))
-        
-        # Gather all weather data
-        for task, target_time in tasks:
-            weather_data = await task
-            if weather_data:
-                entropy = self._extract_entropy(weather_data, target_time)
-                entropy_pool = hashlib.sha256(entropy_pool + entropy).digest()
-        
-        # Fallback if no data gathered
-        if not entropy_pool:
-            entropy_pool = hashlib.sha256(str(datetime.utcnow().timestamp()).encode()).digest()
-        
-        return int.from_bytes(entropy_pool, 'big')
-
-
-class RandomUsingOpenMeteoAPI(random.Random):
-    """
-    A random.Random subclass seeded with weather entropy from Open-Meteo API.
-    
-    Uses weather data to generate a seed, then delegates all random generation
-    to the standard Mersenne Twister (random.Random).
-    """
-    
-    def __init__(self, auto_seed: bool = True):
-        """
-        Initialize the random generator.
-        
-        Args:
-            auto_seed: If True, automatically seeds with weather entropy.
-        """
-        super().__init__()
-        self._api = OpenMeteoAPI()
-        
-        if auto_seed:
-            self.seed_from_weather()
-    
-    def _run_async(self, coro):
-        """Helper to run async code synchronously."""
-        try:
-            asyncio.get_running_loop()
-            import concurrent.futures
-            with concurrent.futures.ThreadPoolExecutor() as pool:
-                future = pool.submit(asyncio.run, coro)
-                return future.result()
-        except RuntimeError:
-            return asyncio.run(coro)
-    
-    def seed_from_weather(
-        self,
-        use_random_location: bool = True,
-        use_current_location: bool = True,
-        use_random_time: bool = True
-    ):
-        """Seed the random generator using weather entropy mixed with hash random."""
-        try:
-            # Get weather-based seed
-            weather_seed = self._run_async(self._api.get_seed(
-                use_random_location=use_random_location,
-                use_current_location=use_current_location,
-                use_random_time=use_random_time
-            ))
-            
-            # Mix with original random module's entropy via SHA256
-            from ..csprng.sha_rand import SHA256Random
-            import time
-            import os
-            
-            # Create SHA256 random seeded with os.urandom + time
-            sha_seed = int.from_bytes(os.urandom(32), 'big') ^ int(time.time() * 1000000)
-            sha_rng = SHA256Random(seed=sha_seed)
-            sha_entropy = int.from_bytes(sha_rng.getrandbytes(32), 'big')
-            
-            # Also get some entropy from Python's random module
-            orig_entropy = int.from_bytes(os.urandom(16), 'big')
-            
-            # Combine all entropy sources with XOR and hash
-            combined = weather_seed ^ sha_entropy ^ orig_entropy
-            final_seed = int.from_bytes(
-                hashlib.sha256(combined.to_bytes(64, 'big')).digest(),
-                'big'
-            )
-            
-            super().seed(final_seed)
-        except Exception:
-            import time
-            super().seed(int(time.time() * 1000000))
-    
-    def seed(self, a=None, version=2):
-        """Seed the generator. If a is None, seeds from weather."""
-        if a is None:
-            self.seed_from_weather()
-        else:
-            super().seed(a, version)
-    
-    def reseed_from_weather(self):
-        """Force a reseed from fresh weather data."""
-        self.seed_from_weather()