Metadata-Version: 2.4
Name: TimeRelease
Version: 2.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: gmpy2~=2.0
Requires-Dist: pycryptodome~=3.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.3; 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

- [Usage](#usage)
	- [Setup](#setup)
	- [Encryption](#encryption)
	- [Decryption](#decryption)
- [Module API](#module-api)
- [Development Usage](#development-usage)

---

## 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, logging=True)`

* 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(secret, iterations, logging=True)`

* 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(iterations, logging=True)`

* 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(benches, logging=True)`

* 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
```
