TimeRelease 1.0.0__tar.gz

timerelease-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leo Pagano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timerelease-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE.txt

timerelease-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: TimeRelease
+Version: 1.0.0
+Summary: Python utility to cryptographically lock secrets for a preset amount of time.
+Author-email: Leo Pagano <leo@leoapagano.com>
+Maintainer-email: Leo Pagano <leo@leoapagano.com>
+License: MIT License
+        
+        Copyright (c) 2025 Leo Pagano
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/leoapagano/TimeRelease
+Project-URL: Documentation, https://github.com/leoapagano/TimeRelease/blob/main/README.md
+Keywords: TimeRelease,Time,Release,Encryption,Crypto,Cryptography,Pagano
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mpmath~=1.0
+Requires-Dist: pycryptodome~=3.0
+Requires-Dist: sympy~=1.0
+Requires-Dist: tqdm~=4.0
+Provides-Extra: dev
+Requires-Dist: build==1.4.0; extra == "dev"
+Requires-Dist: pre-commit==4.5.1; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: ruff==0.15.5; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Requires-Dist: ty==0.0.21; extra == "dev"
+Dynamic: license-file
+
+# TimeRelease
+
+## Introduction
+
+A simple Python utility to lock (or encrypt) secrets, such that they require a preset amount of compute to unlock (or decrypt) them later.
+
+Since each cryptographic step requires the last, it (by design) cannot be parallelized.
+
+This could potentially be useful if you want to wait, for example, an hour, before being able to access a password; as a form of stolen device protection.
+
+## WARNING!
+
+Always keep your "encrypted" file secret, treating it as if it were a password. It is effectively unencrypted as it can be used to decrypt the secret (if such an attacker has sufficient time to complete the puzzle) without any other knowledge of the secret or the individual who encrypted it.
+
+## Table of Contents
+
+- [Interactive Usage](#interactive-usage)
+	- [Setup](#setup)
+	- [Encryption](#encryption)
+	- [Decryption](#decryption)
+- [Module API](#module-api)
+- [Development Usage](#development-usage)
+
+---
+
+## Interactive Usage
+
+### Setup
+
+Install the package and its dependencies in a venv:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install TimeRelease
+```
+
+### Encryption
+
+To encrypt a file `somefile.txt` -> `somefile.txt.timerelease`:
+
+```bash
+# Specify # of seconds it should take to unlock on your machine
+timerelease --encrypt somefile.txt somefile.txt.timerelease --time 3600
+# Or, specify raw # of iterations needed to unlock the file
+timerelease --encrypt somefile.txt somefile.txt.timerelease --iters 1073741824
+```
+
+You can use this to determine how long (on your hardware) the decryption process will take. Encryption should be nearly instant for most settings, even for comically large numbers of iterations.
+
+### Decryption
+
+To decrypt a file `somefile.txt.timerelease` -> `somefile.txt`:
+
+```bash
+timerelease --decrypt somefile.txt.timerelease somefile.txt
+```
+
+It will take however long the person who encrypted the file dictates. The only way to speed it up is to find a CPU with really, really fast single-core performance.
+
+## Module API
+
+Like any module, TimeRelease can be installed via pip (`pip install TimeRelease`) and imported (`import TimeRelease`). The API for the TimeRelease module is as follows:
+
+#### `TimeRelease.decrypt_secret(enc_package)`
+
+* Given a dictionary which was generated by encrypt_secret(), decrypt_secret() decrypts it and returns the secret as a byte string.
+* If `logging` (defaults to True) is set to True, a progress bar is printed, along with extra debug information.
+
+#### `TimeRelease.encrypt_secret()`
+
+* Given a byte string `secret`, encrypt_secret() applies `iterations` iterations to it, "encrypting" it.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_single_benchmark()`
+
+* Determines how long it takes for the CPU to run a fixed number of `iterations`.
+* Amount of time elapsed is returned in seconds as a float.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_benchmark()`
+
+* Determines how many iterations a single core of the user's CPU is capable of processing, on average, per second (as an integer).
+* `benches` (defaults to 10) describes the number of times the benchmark will be run.
+* Higher values of `benches` = greater certainty in running time, but more time is spent benchmarking.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+## Development Usage
+
+To install development versions of this package, clone this repo and `cd` into it, then run:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install -e .[dev]
+pre-commit install 
+```
+
+To test the codebase, simply run `pytest`. To apply proper formatting to the codebase, run `ruff format .`. To ensure that the code has no other issues with PEP8 compliance, run `ruff check`. And to ensure that there  are no type errors, please run `ty check TimeRelease`. Please do all of these things before you commit, and not after!
+
+To build a distribution package, first update the version number in `pyproject.toml`, and make a tag for that release version at the current commit. Then:
+
+```bash
+python3 -m build
+```
+
+To upload this build to PyPI, run:
+
+```bash
+python3 -m twine upload dist/* --skip-existing
+```

timerelease-1.0.0/README.md

@@ -0,0 +1,111 @@
+# TimeRelease
+
+## Introduction
+
+A simple Python utility to lock (or encrypt) secrets, such that they require a preset amount of compute to unlock (or decrypt) them later.
+
+Since each cryptographic step requires the last, it (by design) cannot be parallelized.
+
+This could potentially be useful if you want to wait, for example, an hour, before being able to access a password; as a form of stolen device protection.
+
+## WARNING!
+
+Always keep your "encrypted" file secret, treating it as if it were a password. It is effectively unencrypted as it can be used to decrypt the secret (if such an attacker has sufficient time to complete the puzzle) without any other knowledge of the secret or the individual who encrypted it.
+
+## Table of Contents
+
+- [Interactive Usage](#interactive-usage)
+	- [Setup](#setup)
+	- [Encryption](#encryption)
+	- [Decryption](#decryption)
+- [Module API](#module-api)
+- [Development Usage](#development-usage)
+
+---
+
+## Interactive Usage
+
+### Setup
+
+Install the package and its dependencies in a venv:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install TimeRelease
+```
+
+### Encryption
+
+To encrypt a file `somefile.txt` -> `somefile.txt.timerelease`:
+
+```bash
+# Specify # of seconds it should take to unlock on your machine
+timerelease --encrypt somefile.txt somefile.txt.timerelease --time 3600
+# Or, specify raw # of iterations needed to unlock the file
+timerelease --encrypt somefile.txt somefile.txt.timerelease --iters 1073741824
+```
+
+You can use this to determine how long (on your hardware) the decryption process will take. Encryption should be nearly instant for most settings, even for comically large numbers of iterations.
+
+### Decryption
+
+To decrypt a file `somefile.txt.timerelease` -> `somefile.txt`:
+
+```bash
+timerelease --decrypt somefile.txt.timerelease somefile.txt
+```
+
+It will take however long the person who encrypted the file dictates. The only way to speed it up is to find a CPU with really, really fast single-core performance.
+
+## Module API
+
+Like any module, TimeRelease can be installed via pip (`pip install TimeRelease`) and imported (`import TimeRelease`). The API for the TimeRelease module is as follows:
+
+#### `TimeRelease.decrypt_secret(enc_package)`
+
+* Given a dictionary which was generated by encrypt_secret(), decrypt_secret() decrypts it and returns the secret as a byte string.
+* If `logging` (defaults to True) is set to True, a progress bar is printed, along with extra debug information.
+
+#### `TimeRelease.encrypt_secret()`
+
+* Given a byte string `secret`, encrypt_secret() applies `iterations` iterations to it, "encrypting" it.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_single_benchmark()`
+
+* Determines how long it takes for the CPU to run a fixed number of `iterations`.
+* Amount of time elapsed is returned in seconds as a float.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_benchmark()`
+
+* Determines how many iterations a single core of the user's CPU is capable of processing, on average, per second (as an integer).
+* `benches` (defaults to 10) describes the number of times the benchmark will be run.
+* Higher values of `benches` = greater certainty in running time, but more time is spent benchmarking.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+## Development Usage
+
+To install development versions of this package, clone this repo and `cd` into it, then run:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install -e .[dev]
+pre-commit install 
+```
+
+To test the codebase, simply run `pytest`. To apply proper formatting to the codebase, run `ruff format .`. To ensure that the code has no other issues with PEP8 compliance, run `ruff check`. And to ensure that there  are no type errors, please run `ty check TimeRelease`. Please do all of these things before you commit, and not after!
+
+To build a distribution package, first update the version number in `pyproject.toml`, and make a tag for that release version at the current commit. Then:
+
+```bash
+python3 -m build
+```
+
+To upload this build to PyPI, run:
+
+```bash
+python3 -m twine upload dist/* --skip-existing
+```

timerelease-1.0.0/TimeRelease/__init__.py

@@ -0,0 +1,5 @@
+from .bench import run_benchmark, run_single_benchmark
+from .decrypt import decrypt_secret
+from .encrypt import encrypt_secret
+
+__all__ = ["decrypt_secret", "encrypt_secret", "run_single_benchmark", "run_benchmark"]

timerelease-1.0.0/TimeRelease/__main__.py

@@ -0,0 +1,104 @@
+import argparse
+import json
+from pathlib import Path
+
+from .bench import run_benchmark
+from .decrypt import decrypt_secret
+from .encrypt import encrypt_secret
+
+
+def main(argv: list[str] | None = None) -> int | None:
+	# Read arguments
+	parser = argparse.ArgumentParser(prog="TimeRelease")
+	group = parser.add_mutually_exclusive_group(required=True)
+	group.add_argument(
+		"--encrypt",
+		nargs=2,
+		metavar=("INFILE", "OUTFILE"),
+		help="Encrypt input file to output file path",
+	)
+	group.add_argument(
+		"--decrypt",
+		nargs=2,
+		metavar=("INFILE", "OUTFILE"),
+		help="Decrypt input file to output file path",
+	)
+	iters_group = parser.add_mutually_exclusive_group()
+	iters_group.add_argument(
+		"--iters",
+		type=int,
+		metavar="N",
+		help="Number of iterations for encryption (required with --encrypt)",
+	)
+	iters_group.add_argument(
+		"--time",
+		type=float,
+		metavar="SECONDS",
+		help="Target decryption time in seconds; benchmarks your CPU to compute iterations (required with --encrypt)",
+	)
+	args = parser.parse_args(argv)
+
+	# Validate --iters/--time usage
+	if args.encrypt and args.iters is None and args.time is None:
+		parser.error("--encrypt requires either --iters or --time")
+	if (args.iters is not None or args.time is not None) and not args.encrypt:
+		parser.error("--iters and --time can only be used with --encrypt")
+
+	# Determine and validate infile and outfile
+	if args.encrypt:
+		infile, outfile = Path(args.encrypt[0]), Path(args.encrypt[1])
+	elif args.decrypt:
+		infile, outfile = Path(args.decrypt[0]), Path(args.decrypt[1])
+	if not infile.is_file():
+		print(f"{infile} does not exist or is not a file")
+		return -1
+	if outfile.is_file():
+		print(f"{outfile} will be overwritten! Proceed anyway? [y/n]")
+		if input(">>> ").strip().lower() != "y":
+			print("Exiting.")
+			return -1
+	if outfile.is_dir():
+		print(f"{outfile} cannot be overwritten: is a directory")
+		return -1
+
+	# ENCRYPTION
+	if args.encrypt:
+		# Determine # of iterations
+		if args.iters is not None:
+			iters = args.iters
+		else:
+			print("TimeRelease is benchmarking your CPU. This may take up to a minute.")
+			ips = run_benchmark(logging=False)
+			iters = int(args.time * ips)
+
+		print(f"Encrypting {infile} -> {outfile}:")
+
+		# Read infile
+		with open(infile, "rb") as f:
+			secret = f.read()
+
+		# Encrypt secret & get JSON package
+		enc_package = encrypt_secret(secret, iters)
+
+		# Write outfile
+		with open(outfile, "w") as f:
+			json.dump(enc_package, f, indent=4)
+
+	# DECRYPTION
+	elif args.decrypt:
+		print(f"Decrypting {infile} -> {outfile}:")
+
+		# Read infile
+		with open(infile, "r") as f:
+			enc_package = json.load(f)
+
+		# Decrypt
+		decrypted = decrypt_secret(enc_package)
+
+		# Write outfile
+		with open(outfile, "wb") as f:
+			f.write(decrypted)
+
+
+if __name__ == "__main__":
+	main()

timerelease-1.0.0/TimeRelease/b64utils.py

@@ -0,0 +1,11 @@
+import base64
+
+
+def base64_to_byte_str(base64_string: str) -> bytes:
+	"""Converts a base64 string to its byte string representation."""
+	return base64.b64decode(base64_string.encode("ASCII"))
+
+
+def byte_str_to_base64(byte_string: bytes | bytearray | memoryview) -> str:
+	"""Converts a byte string to its base64 (non-byte string) representation."""
+	return base64.b64encode(byte_string).decode("ASCII")

timerelease-1.0.0/TimeRelease/bench.py

@@ -0,0 +1,57 @@
+import random
+import time
+
+from sympy import nextprime
+
+
+def run_single_benchmark(iterations: int, logging: bool = True) -> float:
+	"""
+	Determines how long it takes for the CPU to run a fixed number of `iterations`.
+	Amount of time elapsed is returned in seconds as a float.
+	If `logging` (defaults to True) is set to True, extra debug information is printed.
+	"""
+	# Setup dummy puzzle parameters
+	if logging:
+		print("Preparing time lock...")
+	p = nextprime(random.getrandbits(512))
+	q = nextprime(random.getrandbits(512))
+	modulus = p * q
+
+	# Execute & time it
+	if logging:
+		print("Running benchmark...")
+	start_time = time.time()
+	r = random.randint(2, modulus - 1)
+	for _ in range(iterations):
+		r = pow(r, 2, modulus)
+	end_time = time.time()
+
+	return end_time - start_time
+
+
+def run_benchmark(benches: int = 10, logging: bool = True) -> int:
+	"""
+	Determines how many iterations a single core of the user's CPU is capable of processing, on average, per second (as an integer).
+	`benches` (defaults to 10) describes the number of times the benchmark will be run.
+	Higher values of `benches` = greater certainty in running time, but more time is spent benchmarking.
+	If `logging` (defaults to True) is set to True, extra debug information is printed.
+	"""
+	# Repeat single benchmarks, doubling iterations until the time per benchmark is less than 1 second
+	iterations = 1
+	execution_time = 0
+	while execution_time < 1:
+		iterations *= 2
+		if logging:
+			print(f"Running benchmark @ iterations={iterations}")
+		execution_time = run_single_benchmark(iterations, logging=logging)
+
+	# Run benches (default: 10) benchmarks with this number of iterations
+	results = []
+	for i in range(benches):
+		if logging:
+			print(f"Running standard benchmark {i + 1} / {benches}")
+		results.append(run_single_benchmark(iterations, logging=logging))
+
+	# Determine average iterations/sec and return
+	avg = sum(results) / benches
+	return int(iterations // avg)

timerelease-1.0.0/TimeRelease/decrypt.py

@@ -0,0 +1,56 @@
+import hashlib
+import time
+from typing import Any
+
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import unpad
+from tqdm import tqdm
+
+from .b64utils import base64_to_byte_str
+
+
+def decrypt_secret(enc_package: dict[str, Any], logging: bool = True) -> bytes:
+	"""
+	Given a dictionary which was generated by encrypt_secret(), decrypt_secret() decrypts it and returns the secret as a byte string.
+	If `logging` (defaults to True) is set to True, a progress bar is printed, along with extra debug information.
+	"""
+	base = enc_package["base"]
+	modulus = enc_package["modulus"]
+	iterations = enc_package["iterations"]
+	secret_iv = base64_to_byte_str(enc_package["secret_iv"])
+	encrypted_secret = base64_to_byte_str(enc_package["encrypted_secret"])
+	key_iv = base64_to_byte_str(enc_package["key_iv"])
+	encrypted_key = base64_to_byte_str(enc_package["encrypted_key"])
+
+	# Compute puzzle result r
+	if logging:
+		print("Unlocking encryption key...")
+	start_time = time.time()
+	r = base
+	if logging:
+		for _ in tqdm(range(iterations), desc="Unlocking", unit="iters"):
+			r = pow(r, 2, modulus)
+	else:
+		for _ in range(iterations):
+			r = pow(r, 2, modulus)
+	end_time = time.time()
+	if logging:
+		print(f"Completed in {end_time - start_time:.2f} seconds")
+
+	# Derive AES key from r
+	if logging:
+		print("Deriving AES key...")
+	derived_key = hashlib.sha256(str(r).encode()).digest()[:16]
+
+	# Decrypt AES key
+	if logging:
+		print("Decrypting AES key...")
+	cipher2 = AES.new(derived_key, AES.MODE_CBC, iv=key_iv)
+	aes_key = unpad(cipher2.decrypt(encrypted_key), AES.block_size)
+
+	# Decrypt secret
+	if logging:
+		print("Decrypting secret...")
+	cipher = AES.new(aes_key, AES.MODE_CBC, iv=secret_iv)
+	secret = unpad(cipher.decrypt(encrypted_secret), AES.block_size)
+	return secret

timerelease-1.0.0/TimeRelease/encrypt.py

@@ -0,0 +1,61 @@
+import hashlib
+import random
+from typing import Any
+
+from Crypto.Cipher import AES
+from Crypto.Random import get_random_bytes
+from Crypto.Util.Padding import pad
+from sympy import nextprime
+
+from .b64utils import byte_str_to_base64
+
+
+def encrypt_secret(
+	secret: bytes, iterations: int, logging: bool = True
+) -> dict[str, Any]:
+	"""
+	Given a byte string `secret`, encrypt_secret() applies `iterations` iterations to it, "encrypting" it.
+	If `logging` (defaults to True) is set to True, extra debug information is printed.
+	"""
+	# Create new (symmetric) AES key and encrypt secret with it
+	if logging:
+		print("Generating encryption key...")
+	aes_key = get_random_bytes(16)
+	cipher = AES.new(aes_key, AES.MODE_CBC)
+	secret_iv = cipher.iv
+	encrypted_secret = cipher.encrypt(pad(secret, AES.block_size))
+
+	# Time-lock puzzle setup
+	# Generate N = p * q
+	if logging:
+		print("Preparing time lock...")
+	p = nextprime(random.getrandbits(512))
+	q = nextprime(random.getrandbits(512))
+	modulus = p * q
+
+	# Puzzle: compute r = base^(2^iterations) mod modulus
+	base = random.randint(2, modulus - 1)
+	r = pow(base, pow(2, iterations, (p - 1) * (q - 1)), modulus)
+
+	# Derive AES key from r (e.g. using SHA256)
+	if logging:
+		print("Deriving AES key from time lock...")
+	derived_key = hashlib.sha256(str(r).encode()).digest()[:16]
+
+	# Encrypt AES key with derived key
+	if logging:
+		print("Encrypting derived key...")
+	cipher2 = AES.new(derived_key, AES.MODE_CBC)
+	key_iv = cipher2.iv
+	encrypted_key = cipher2.encrypt(pad(aes_key, AES.block_size))
+
+	# Stash stuff needed to decrypt later
+	return {
+		"base": base,
+		"modulus": modulus,
+		"iterations": iterations,
+		"secret_iv": byte_str_to_base64(secret_iv),
+		"encrypted_secret": byte_str_to_base64(encrypted_secret),
+		"key_iv": byte_str_to_base64(key_iv),
+		"encrypted_key": byte_str_to_base64(encrypted_key),
+	}

timerelease-1.0.0/TimeRelease.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: TimeRelease
+Version: 1.0.0
+Summary: Python utility to cryptographically lock secrets for a preset amount of time.
+Author-email: Leo Pagano <leo@leoapagano.com>
+Maintainer-email: Leo Pagano <leo@leoapagano.com>
+License: MIT License
+        
+        Copyright (c) 2025 Leo Pagano
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/leoapagano/TimeRelease
+Project-URL: Documentation, https://github.com/leoapagano/TimeRelease/blob/main/README.md
+Keywords: TimeRelease,Time,Release,Encryption,Crypto,Cryptography,Pagano
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mpmath~=1.0
+Requires-Dist: pycryptodome~=3.0
+Requires-Dist: sympy~=1.0
+Requires-Dist: tqdm~=4.0
+Provides-Extra: dev
+Requires-Dist: build==1.4.0; extra == "dev"
+Requires-Dist: pre-commit==4.5.1; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: ruff==0.15.5; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Requires-Dist: ty==0.0.21; extra == "dev"
+Dynamic: license-file
+
+# TimeRelease
+
+## Introduction
+
+A simple Python utility to lock (or encrypt) secrets, such that they require a preset amount of compute to unlock (or decrypt) them later.
+
+Since each cryptographic step requires the last, it (by design) cannot be parallelized.
+
+This could potentially be useful if you want to wait, for example, an hour, before being able to access a password; as a form of stolen device protection.
+
+## WARNING!
+
+Always keep your "encrypted" file secret, treating it as if it were a password. It is effectively unencrypted as it can be used to decrypt the secret (if such an attacker has sufficient time to complete the puzzle) without any other knowledge of the secret or the individual who encrypted it.
+
+## Table of Contents
+
+- [Interactive Usage](#interactive-usage)
+	- [Setup](#setup)
+	- [Encryption](#encryption)
+	- [Decryption](#decryption)
+- [Module API](#module-api)
+- [Development Usage](#development-usage)
+
+---
+
+## Interactive Usage
+
+### Setup
+
+Install the package and its dependencies in a venv:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install TimeRelease
+```
+
+### Encryption
+
+To encrypt a file `somefile.txt` -> `somefile.txt.timerelease`:
+
+```bash
+# Specify # of seconds it should take to unlock on your machine
+timerelease --encrypt somefile.txt somefile.txt.timerelease --time 3600
+# Or, specify raw # of iterations needed to unlock the file
+timerelease --encrypt somefile.txt somefile.txt.timerelease --iters 1073741824
+```
+
+You can use this to determine how long (on your hardware) the decryption process will take. Encryption should be nearly instant for most settings, even for comically large numbers of iterations.
+
+### Decryption
+
+To decrypt a file `somefile.txt.timerelease` -> `somefile.txt`:
+
+```bash
+timerelease --decrypt somefile.txt.timerelease somefile.txt
+```
+
+It will take however long the person who encrypted the file dictates. The only way to speed it up is to find a CPU with really, really fast single-core performance.
+
+## Module API
+
+Like any module, TimeRelease can be installed via pip (`pip install TimeRelease`) and imported (`import TimeRelease`). The API for the TimeRelease module is as follows:
+
+#### `TimeRelease.decrypt_secret(enc_package)`
+
+* Given a dictionary which was generated by encrypt_secret(), decrypt_secret() decrypts it and returns the secret as a byte string.
+* If `logging` (defaults to True) is set to True, a progress bar is printed, along with extra debug information.
+
+#### `TimeRelease.encrypt_secret()`
+
+* Given a byte string `secret`, encrypt_secret() applies `iterations` iterations to it, "encrypting" it.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_single_benchmark()`
+
+* Determines how long it takes for the CPU to run a fixed number of `iterations`.
+* Amount of time elapsed is returned in seconds as a float.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+#### `TimeRelease.run_benchmark()`
+
+* Determines how many iterations a single core of the user's CPU is capable of processing, on average, per second (as an integer).
+* `benches` (defaults to 10) describes the number of times the benchmark will be run.
+* Higher values of `benches` = greater certainty in running time, but more time is spent benchmarking.
+* If `logging` (defaults to True) is set to True, extra debug information is printed.
+
+## Development Usage
+
+To install development versions of this package, clone this repo and `cd` into it, then run:
+
+```bash
+python3 -m venv ./venv
+source ./venv/bin/activate
+pip install -e .[dev]
+pre-commit install 
+```
+
+To test the codebase, simply run `pytest`. To apply proper formatting to the codebase, run `ruff format .`. To ensure that the code has no other issues with PEP8 compliance, run `ruff check`. And to ensure that there  are no type errors, please run `ty check TimeRelease`. Please do all of these things before you commit, and not after!
+
+To build a distribution package, first update the version number in `pyproject.toml`, and make a tag for that release version at the current commit. Then:
+
+```bash
+python3 -m build
+```
+
+To upload this build to PyPI, run:
+
+```bash
+python3 -m twine upload dist/* --skip-existing
+```

timerelease-1.0.0/TimeRelease.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+TimeRelease/__init__.py
+TimeRelease/__main__.py
+TimeRelease/b64utils.py
+TimeRelease/bench.py
+TimeRelease/decrypt.py
+TimeRelease/encrypt.py
+TimeRelease.egg-info/PKG-INFO
+TimeRelease.egg-info/SOURCES.txt
+TimeRelease.egg-info/dependency_links.txt
+TimeRelease.egg-info/entry_points.txt
+TimeRelease.egg-info/requires.txt
+TimeRelease.egg-info/top_level.txt
+tests/test_encrypt_decrypt.py

timerelease-1.0.0/TimeRelease.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

timerelease-1.0.0/TimeRelease.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timerelease = TimeRelease.__main__:main

timerelease-1.0.0/TimeRelease.egg-info/requires.txt

@@ -0,0 +1,12 @@
+mpmath~=1.0
+pycryptodome~=3.0
+sympy~=1.0
+tqdm~=4.0
+
+[dev]
+build==1.4.0
+pre-commit==4.5.1
+pytest==9.0.2
+ruff==0.15.5
+twine==6.2.0
+ty==0.0.21

timerelease-1.0.0/TimeRelease.egg-info/top_level.txt

@@ -0,0 +1 @@
+TimeRelease

timerelease-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "TimeRelease"
+version = "1.0.0"
+requires-python = ">=3.13"
+description = "Python utility to cryptographically lock secrets for a preset amount of time."
+readme = "README.md"
+authors = [
+	{ name = "Leo Pagano", email = "leo@leoapagano.com" }
+]
+maintainers = [
+	{ name = "Leo Pagano", email = "leo@leoapagano.com" }
+]
+license = { file = "LICENSE" }
+keywords = [
+	"TimeRelease",
+	"Time",
+	"Release",
+	"Encryption",
+	"Crypto",
+	"Cryptography",
+	"Pagano"
+]
+classifiers = [
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: Implementation :: CPython",
+	"License :: OSI Approved :: MIT License",
+	"Intended Audience :: Developers",
+	"Operating System :: POSIX :: Linux",
+	"Operating System :: Microsoft :: Windows",
+	"Operating System :: MacOS",
+	"Operating System :: MacOS :: MacOS X",
+]
+dependencies = [
+	"mpmath~=1.0",
+	"pycryptodome~=3.0",
+	"sympy~=1.0",
+	"tqdm~=4.0"
+]
+
+[project.optional-dependencies]
+dev = [
+	"build==1.4.0",
+	"pre-commit==4.5.1",
+	"pytest==9.0.2",
+	"ruff==0.15.5",
+	"twine==6.2.0",
+	"ty==0.0.21"
+]
+
+[project.urls]
+Homepage = "https://github.com/leoapagano/TimeRelease"
+Documentation = "https://github.com/leoapagano/TimeRelease/blob/main/README.md"
+
+[project.scripts]
+timerelease = "TimeRelease.__main__:main"
+
+[tool.ruff.format]
+indent-style = "tab"

timerelease-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

timerelease-1.0.0/tests/test_encrypt_decrypt.py

@@ -0,0 +1,12 @@
+from TimeRelease import decrypt_secret, encrypt_secret
+
+
+def test_hello_world():
+	"""
+	Very basic test case. Just ensures that an input, when encrypted and decrypted,
+	produces the same output that it started with.
+	"""
+	input = b"hello world"
+	encrypted = encrypt_secret(input, 2**16, logging=False)
+	decrypted = decrypt_secret(encrypted, logging=False)
+	assert decrypted == b"hello world"