photorand 1.0.2__tar.gz

photorand-1.0.2/.editorconfig

@@ -0,0 +1,6 @@
+# .editorconfig
+root = true
+
+[*.py]
+indent_style = tabs
+quote_type = double

photorand-1.0.2/.gitattributes

@@ -0,0 +1,3 @@
+*.ARW filter=lfs diff=lfs merge=lfs -text
+*.CR2 filter=lfs diff=lfs merge=lfs -text
+examples/**/*.png filter=lfs diff=lfs merge=lfs -text

photorand-1.0.2/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.vscode/settings.json

photorand-1.0.2/.python-version

@@ -0,0 +1 @@
+3.14.2

photorand-1.0.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: photorand
+Version: 1.0.2
+Summary: A True Random Number Generator using raw camera sensor data.
+Project-URL: Homepage, https://github.com/illescasDaniel/photorand
+Author-email: Daniel Illescas Romero <dev@daniel-ir.eu>
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: rawpy>=0.26.1
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: imageio; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: vermin; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# photorand
+
+A True Random Number Generator (TRNG) using raw camera sensor data to extract physical entropy.
+
+## Project Structure
+
+- `src/photorand/` - Main package source code.
+	- `low_level/` - Modular primitives (ingest, sample, hash, csprng).
+	- `high_level/` - Clean OO abstractions (`PhotoRandSeed`, `PhotoRandEngine`).
+	- `cli/` - Command-line interface logic.
+- `docs/` - Technical and scientific documentation detailing the [entropy extraction](docs/entropy-extraction.md) and [entropy expansion](docs/entropy-expansion.md) mechanisms.
+- `tests/` - Comprehensive test suite organized by architectural layer.
+
+## Installation
+
+This project uses `pyproject.toml` for managing dependencies.
+
+1. **Create and activate a virtual environment** (recommended):
+	```bash
+	python -m venv .venv
+	source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
+	```
+
+2. **Install the project in editable mode**:
+	```bash
+	pip install -e .
+	# or this one for also installing the dev tools
+	pip install -e ".[dev]"
+	```
+
+---
+
+### 1. High-Level Classes (Recommended)
+
+The high-level classes provide a stateful and convenient interface for both TRNG and CSPRNG operations.
+
+#### `PhotoRandSeed` (TRNG)
+Encapsulates the process of extracting entropy from a RAW image. It is perfect for generating one-off secure seeds, keys, or dice rolls directly from physical noise.
+
+```python
+from photorand.high_level.seed import PhotoRandSeed
+
+# 1. Extract entropy from a RAW image
+seed = PhotoRandSeed("path/to/image.raw")
+
+# 2. Access as bytes, hex, or large integer
+print(seed.to_hex_string())
+print(seed.to_int())
+
+# 3. Roll a D100 using physical entropy (Rejection Sampling)
+luck = seed.to_int_range(1, 100)
+```
+
+#### `PhotoRandEngine` (CSPRNG)
+An infinite stream generator powered by ChaCha20, seeded by a `PhotoRandSeed`. It handles salting (Time + PID) automatically to ensure that even consecutive runs with the same image produce unique streams.
+
+```python
+from photorand.high_level.engine import PhotoRandEngine
+
+# 1. Initialize from image or existing Seed object
+engine = PhotoRandEngine("path/to/image.raw")
+
+# 2. Pull arbitrary amounts of secure data
+key = engine.next_bytes(32)
+pin = engine.next_string(length=6, charset='numeric')
+dice = engine.next_int_range(1, 20)
+
+# 3. Batch generation
+multiple_passwords = engine.generate_batch(engine.next_string, count=5, length=16)
+```
+
+#### CLI (Command Line Interface)
+
+The package includes a powerful CLI to use these classes directly from your terminal.
+
+```bash
+# Extract 64-byte photorand seed (hex)
+python -m photorand extract path/to/raw_image.ARW
+
+# Roll a D20
+python -m photorand extract path/to/raw_image.ARW --format range --min 1 --max 20
+
+# Generate 5 random 16-char alphanumeric passwords
+python -m photorand generate path/to/raw_image.ARW --type string -n 5 -l 16 --charset alpha
+```
+
+*For more details, run:* `python -m photorand --help`
+
+---
+
+### 2. Low-Level Modular Functions
+
+For maximum control or research, you can use the modular primitives directly.
+
+```python
+from photorand.low_level.ingest import ingest_raw_image
+from photorand.low_level.sample import sample_entropy_grid
+from photorand.low_level.hash import hash_entropy_pool
+
+# 1. Ingest raw sensor data
+raw_data = ingest_raw_image("path/to/image.raw")
+
+# 2. Extract raw LSB bits
+entropy_pool = sample_entropy_grid(raw_data)
+
+# 3. Condition entropy into uniform bytes
+seed_bytes = hash_entropy_pool(entropy_pool)
+```
+
+Alternatively, use the functional pipeline. It accepts custom functions for each part of the algorithm (ingest_fn, sample_fn and hash_fn) although we already provide the values as default parameters:
+```python
+from photorand.low_level.generate import generate_true_random_number
+seed = generate_true_random_number("path/to/image.raw")
+```
+
+---
+
+## Development
+
+### Running the Tests
+```bash
+python -m pytest -v --log-cli-level=INFO
+# or just this one to skip logs
+pytest
+```
+
+### Formatting
+```bash
+ruff check --fix src tests examples
+```

photorand-1.0.2/README.md

@@ -0,0 +1,130 @@
+# photorand
+
+A True Random Number Generator (TRNG) using raw camera sensor data to extract physical entropy.
+
+## Project Structure
+
+- `src/photorand/` - Main package source code.
+	- `low_level/` - Modular primitives (ingest, sample, hash, csprng).
+	- `high_level/` - Clean OO abstractions (`PhotoRandSeed`, `PhotoRandEngine`).
+	- `cli/` - Command-line interface logic.
+- `docs/` - Technical and scientific documentation detailing the [entropy extraction](docs/entropy-extraction.md) and [entropy expansion](docs/entropy-expansion.md) mechanisms.
+- `tests/` - Comprehensive test suite organized by architectural layer.
+
+## Installation
+
+This project uses `pyproject.toml` for managing dependencies.
+
+1. **Create and activate a virtual environment** (recommended):
+	```bash
+	python -m venv .venv
+	source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
+	```
+
+2. **Install the project in editable mode**:
+	```bash
+	pip install -e .
+	# or this one for also installing the dev tools
+	pip install -e ".[dev]"
+	```
+
+---
+
+### 1. High-Level Classes (Recommended)
+
+The high-level classes provide a stateful and convenient interface for both TRNG and CSPRNG operations.
+
+#### `PhotoRandSeed` (TRNG)
+Encapsulates the process of extracting entropy from a RAW image. It is perfect for generating one-off secure seeds, keys, or dice rolls directly from physical noise.
+
+```python
+from photorand.high_level.seed import PhotoRandSeed
+
+# 1. Extract entropy from a RAW image
+seed = PhotoRandSeed("path/to/image.raw")
+
+# 2. Access as bytes, hex, or large integer
+print(seed.to_hex_string())
+print(seed.to_int())
+
+# 3. Roll a D100 using physical entropy (Rejection Sampling)
+luck = seed.to_int_range(1, 100)
+```
+
+#### `PhotoRandEngine` (CSPRNG)
+An infinite stream generator powered by ChaCha20, seeded by a `PhotoRandSeed`. It handles salting (Time + PID) automatically to ensure that even consecutive runs with the same image produce unique streams.
+
+```python
+from photorand.high_level.engine import PhotoRandEngine
+
+# 1. Initialize from image or existing Seed object
+engine = PhotoRandEngine("path/to/image.raw")
+
+# 2. Pull arbitrary amounts of secure data
+key = engine.next_bytes(32)
+pin = engine.next_string(length=6, charset='numeric')
+dice = engine.next_int_range(1, 20)
+
+# 3. Batch generation
+multiple_passwords = engine.generate_batch(engine.next_string, count=5, length=16)
+```
+
+#### CLI (Command Line Interface)
+
+The package includes a powerful CLI to use these classes directly from your terminal.
+
+```bash
+# Extract 64-byte photorand seed (hex)
+python -m photorand extract path/to/raw_image.ARW
+
+# Roll a D20
+python -m photorand extract path/to/raw_image.ARW --format range --min 1 --max 20
+
+# Generate 5 random 16-char alphanumeric passwords
+python -m photorand generate path/to/raw_image.ARW --type string -n 5 -l 16 --charset alpha
+```
+
+*For more details, run:* `python -m photorand --help`
+
+---
+
+### 2. Low-Level Modular Functions
+
+For maximum control or research, you can use the modular primitives directly.
+
+```python
+from photorand.low_level.ingest import ingest_raw_image
+from photorand.low_level.sample import sample_entropy_grid
+from photorand.low_level.hash import hash_entropy_pool
+
+# 1. Ingest raw sensor data
+raw_data = ingest_raw_image("path/to/image.raw")
+
+# 2. Extract raw LSB bits
+entropy_pool = sample_entropy_grid(raw_data)
+
+# 3. Condition entropy into uniform bytes
+seed_bytes = hash_entropy_pool(entropy_pool)
+```
+
+Alternatively, use the functional pipeline. It accepts custom functions for each part of the algorithm (ingest_fn, sample_fn and hash_fn) although we already provide the values as default parameters:
+```python
+from photorand.low_level.generate import generate_true_random_number
+seed = generate_true_random_number("path/to/image.raw")
+```
+
+---
+
+## Development
+
+### Running the Tests
+```bash
+python -m pytest -v --log-cli-level=INFO
+# or just this one to skip logs
+pytest
+```
+
+### Formatting
+```bash
+ruff check --fix src tests examples
+```

photorand-1.0.2/docs/entropy-expansion.md

@@ -0,0 +1,39 @@
+# The CSPRNG Mechanism: Entropy Expansion
+
+This document explains how the physical seed generated via [`photorand`'s extraction process](entropy-extraction.md) is expanded into a continuous, high-volume stream of cryptographically secure random data.
+
+## The Need for Expansion
+
+While direct physical extraction produces high-quality true randomness, harvesting large volumes (megabytes or gigabytes) directly from a camera sensor is slow and computationally expensive.
+
+To solve this, we use a **CSPRNG** (Cryptographically Secure Pseudo-Random Number Generator). The CSPRNG takes a small, high-entropy "seed" from the photorand and expands it into an effectively infinite stream of bytes that is computationally indistinguishable from true randomness.
+
+## The Expansion Engine: ChaCha20
+
+This project uses the **ChaCha20** stream cipher as its expansion core.
+
+### Why ChaCha20?
+*   **Security**: ChaCha20 is a modern, high-security cipher designed by Daniel J. Bernstein. It is widely used in protocols like TLS 1.3 and SSH.
+*   **Performance**: It is exceptionally fast in software implementations and does not require specialized hardware acceleration (like AES-NI) to be efficient.
+*   **No State Leakage**: Unlike some older PRNGs, a CSPRNG based on a modern stream cipher ensures that even if part of the output is compromised, it is computationally impossible to determine past or future outputs.
+
+## Implementation Details (`low_level/csprng.py`)
+
+1.  **Seeding**: The 64-byte output from the photorand is used to initialize the cipher.
+    *   The first **32 bytes** (256 bits) are used as the **Key**.
+    *   The next **16 bytes** (128 bits) are used as the **Nonce** (Initialization Vector).
+2.  **Keystream Generation**: To generate random bytes, we encrypt a stream of null bytes (`0x00`).
+3.  **Result**: The resulting "encrypted" output is a pure keystream of cryptographically secure pseudo-random bytes.
+
+## Usage in the CLI
+
+When you run the `generate` command:
+```bash
+python -m photorand generate <image_path> [options]
+```
+The tool first runs the photorand process to get a fresh 64-byte seed and then uses this seed to drive the ChaCha20 expander to provide as much data as requested.
+
+## Security Properties
+
+*   **Prediction Resistance**: Given any amount of output from the generator, an adversary with unlimited time but limited classical computing power cannot predict the next bit better than a coin flip (50/50).
+*   **Backtracking Resistance**: If the internal state of the generator is compromised at a certain point, previous outputs remain secure.

photorand-1.0.2/docs/entropy-extraction.md

@@ -0,0 +1,38 @@
+# The `photorand` Mechanism: Physical Entropy Extraction
+
+This document outlines the scientific and technical architecture of `photorand`. It details how the system leverages raw camera sensor data to extract physical entropy, functioning as a True Random Number Generator (TRNG).
+
+## Overview
+
+The photorand extracts physical entropy from raw camera sensor data. Unlike typical pseudo-random number generators (PRNGs) that rely on mathematical algorithms starting from a seed, this photorand leverages the inherent physical noise present in digital image sensors.
+
+## Entropy Source: Raw Sensor Noise
+
+Digital image sensors (CMOS/CCD) are subject to various forms of physical noise, even when no light is present or when capturing a static scene. Key sources of this noise include:
+
+*   **Shot Noise**: Random fluctuations in the number of photons hitting the sensor.
+*   **Read Noise**: Electronic noise introduced during the digitization of the analog signal.
+*   **Thermal Noise (Dark Current)**: Noise caused by the thermal agitation of electrons within the sensor.
+
+By reading the **RAW** data (before any processing like denoising, demosaicing, or compression), we can isolate these tiny, unpredictable fluctuations.
+
+## Implementation Details
+
+### 1. Data Ingestion (`low_level/ingest.py`)
+We use the `rawpy` library to access the unprocessed sensor grid. This ensures we are working with the "pure" values captured by the hardware, which contain the most entropy.
+
+### 2. Sampling and Isolation (`low_level/sample.py`)
+To extract the most random components and reduce spatial correlation (where neighboring pixels might share similar noise characteristics), we perform two steps:
+
+*   **Grid Sampling**: We sample pixels at a fixed stride (e.g., every 64th pixel). This spreads the sampling across the entire sensor surface.
+*   **LSB Extraction**: We isolate the 4 **Least Significant Bits (LSBs)** of each sampled pixel value. The higher-order bits represent the actual image content (which is predictable), while the LSBs are dominated by the physical noise floor.
+
+### 3. Entropy Conditioning (`low_level/hash.py`)
+The raw "lsb-pool" extracted from the sensor might still have small statistical biases. To produce a perfectly uniform output, we pass the extracted bytes through a **cryptographic hash function**.
+
+*   **Algorithm**: SHA3-512
+*   **Purpose**: SHA3-512 acts as an "entropy blender." It compresses the large pool of harvested noise into a 64-byte (512-bit) digest. The avalanche effect of the hash ensures that any small amount of entropy in the input is distributed uniformly across the entire output block.
+
+## Conclusion
+
+The result is a 64-byte "seed" of true randomness, rooted in the physical reality of the camera sensor's environment. This seed is highly secure and suitable for use in cryptographic applications or as a source for a CSPRNG.

photorand-1.0.2/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "photorand"
+version = "1.0.2"
+authors = [{ name = "Daniel Illescas Romero", email = "dev@daniel-ir.eu" }]
+description = "A True Random Number Generator using raw camera sensor data."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["rawpy>=0.26.1", "numpy>=2.0.0", "cryptography>=46.0.0"]
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"License :: OSI Approved :: MIT License",
+	"Operating System :: OS Independent",
+]
+
+[project.scripts]
+photorand = "photorand.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/illescasDaniel/photorand"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "vermin", "build", "imageio", "matplotlib"]
+
+# --- RUFF (Linter & Import Sorter) ---
+[tool.ruff]
+line-length = 160
+target-version = 'py312'
+src = ['src']
+
+[tool.ruff.lint]
+# Enable specific rules:
+# F = Pyflakes (Finds unused imports/variables)
+# I = isort (Sorts imports)
+# E = pycodestyle errors
+select = ['F', 'I', 'E']
+# Allow fixing for all enabled rules (imports will be removed/sorted automatically)
+fixable = ['ALL']
+# --- RUFF end ---
+
+[tool.ruff.lint.isort]
+# Ensure compatibility with YAPF's vertical style
+combine-as-imports = true
+lines-after-imports = 2
+
+[tool.pytest.ini_options]
+log_cli = true
+log_cli_level = "WARNING"
+log_cli_format = "[%(levelname)s] %(message)s"
+
+[tool.hatch.build]
+exclude = ["examples", "tests/data"]

photorand-1.0.2/pyrefly.toml

@@ -0,0 +1,3 @@
+[pyrefly]
+source_directories = ["src", "tests", "examples"]
+exclude = [".venv", ".git", "**/__pycache__"]

photorand-1.0.2/src/photorand/__init__.py

@@ -0,0 +1,33 @@
+from .high_level import PhotoRandEngine as PhotoRandEngine, PhotoRandSeed as PhotoRandSeed
+from .low_level import (
+	csprng_format_bytes as csprng_format_bytes,
+	csprng_format_int as csprng_format_int,
+	csprng_format_range as csprng_format_range,
+	csprng_format_string as csprng_format_string,
+	expand_entropy_chacha20 as expand_entropy_chacha20,
+	generate_true_random_number as generate_true_random_number,
+	hash_entropy_pool as hash_entropy_pool,
+	ingest_raw_image as ingest_raw_image,
+	sample_entropy_grid as sample_entropy_grid,
+	trng_format_hex as trng_format_hex,
+	trng_format_int as trng_format_int,
+	trng_format_range as trng_format_range,
+)
+
+
+__all__ = [
+	"PhotoRandEngine",
+	"PhotoRandSeed",
+	"csprng_format_bytes",
+	"csprng_format_int",
+	"csprng_format_range",
+	"csprng_format_string",
+	"expand_entropy_chacha20",
+	"generate_true_random_number",
+	"hash_entropy_pool",
+	"ingest_raw_image",
+	"sample_entropy_grid",
+	"trng_format_hex",
+	"trng_format_int",
+	"trng_format_range",
+]

photorand-1.0.2/src/photorand/__main__.py

@@ -0,0 +1,5 @@
+from .cli.main import main
+
+
+if __name__ == "__main__":
+	main()