Metadata-Version: 2.4
Name: determinist
Version: 0.5.2
Summary: A deterministic password generator
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: click>=8.5.0
Requires-Dist: cryptography>=50.0.0
Requires-Dist: platformdirs>=4.11.0
Requires-Dist: setuptools>=83.0.0
Requires-Dist: setuptools-scm>=10.2.1
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.27.0

# Determinist
A deterministic password generator so you never forget your passwords!

## What Determinist is
> IMPORTANT: Your **master password** and **generated password** are *not* the same!

Determinist is a **password generator** designed with ease of recovery in mind. Enter a master password, tweak the settings as you'd like, and you'll have a strong password you can use! Determinist doesn't save or send your passwords anywhere, it is completely local on both the CLI and web versions.

### Recommended algorithm: v3
For new passwords, v3 is recommended as it contains the latest improvements and fixes. Versions 1 an 2 remain available for compatibility with previously generated passwords.

> Note: Determinist is fully deterministic, meaning the same inputs will always yield the same outputs. This is how you can recover lost **passwords**. You *cannot* recover lost **master passwords** or any other settings.

## What Determinist is NOT and CANNOT do
> Glossary:
> - Password: The **output** password generated by Determinist
> - Master password: The password **you** create and enter to generate and recover your passwords
> - Settings: The rest of the parameters you input into Determinist when generating a password
- Determinist is *not* a password manager, it does not save your passwords, send them anywhere or sync them across devices
- Determinist *cannot* recover forgotten **master passwords** or generation **settings**
- **You** are responsible for keeping your master password and settings safe, and remembering them

## Who Determinist is for
Determinist was made to solve my problem of having a password saved on one device but not the other when I really needed it. Now you might ask why not just use a password manager? That's a great idea, and I do **recommend** using one with Determinist. This also has the benefit of being able to recover your password if you forgot to save it and lost it, provided that you remember your settings or have a preset you generated your password with.

## Features
- Deterministic output
- Fast generation
- Secure master password encryption using Argon2
- Easy **password** recovery
- TOML preset support

## How Determinist works
Determinist takes your inputs and passes them to the chosen algorithm. In case of the v3 algorithm, the following are passed:
- Your master password
- The name of the website
- The length of the password
- The character types
- How many characters you want of each type at minimum
- The password differentiator

The algorithm then turns the settings into a string that Argon2 uses as the salt to then deterministically hash the provided master password. This string of settings is also used as the random seed for shuffling character sets and the final password.

You can read more about how the individual algorithms work [here](https://github.com/szentpeterimate/determinist/blob/main/docs/PROCESS.md).

## Installation
### pipx (Recommended):
1. If you don't have pipx installed yet, follow the official [installation guide](https://pipx.pypa.io/stable/how-to/install-pipx.html)
2. Install Determinist with `pipx install determinist`
> Important! Determinist was built with pipx version **1.16.5**. Make sure you have the latest version installed.
### pip:
- Install Determinist with `pip install determinist`
> This tool is meant to be used from the terminal. Only install using pip if you know what you're doing!

## How to use
### Web
Just enter your master password, the name of the site you'd like to generate a password for, and optionally customize the other settings as you wish, and click generate! 

> Note: The Determinist website does NOT connect to any servers other than GitHub and Google Fonts. All your information is safe, and is not stored locally or on any server (with the exception of saved presets which are locally on your machine/browser), as the entire generation process is client-side.

### CLI
- `generate`: This will run the generation, you can use the options below with it. You can also omit the master and site, as Determinist will prompt you for them if you do
    - `generate prompt`: The `prompt` subcommand will prompt you for every option, no need to write them yourself

- `presets`: Lists all presets (and invalid files) saved in the configuration directory
    - `presets save [PATH]`: Saves a preset to the config directory
    - `presets delete [PRESET NAME]`: Permanently deletes a preset (or any invalid file in the presets directory)
    - `presets default [PRESET NAME]`: Sets a preset as default
    - `presets create`: Creates a preset with the given parameters
    

    ### Options
    - `--master` / `-M`: The the master password you input into Determinist, used for generating and recovering passwords
    - `--site` / `-n`: The URL of the website you want to generate a password for. In practice, it can be any string. When using the v1 algorithm, this must be *at least* 8 characters long
    - `--preset` / `-p`: The saved preset to use. You can overwrite the parameters in the preset by using any of the following options as well.
    - `--version` / `-v`: The algorithm version you'd like to use
    - `--length` / `-l`: The desired length of your password
    #### Algorithm Specific
    These can be omitted (left default) if you're using one version over the other.
    #### V1
    - `--mode` / `-m`: The mode that decides how special characters are put into your password
        - `replace`: Replaces a character with a special character according to the `--map`
            - `--map`: The character map. Enter in JSON format (e.g. `{'a': '.', 'b': ','}`)
        - `insert`: Inserts a special character from a list (see `--special`) every nth character
            - `--special` / `-s`: The list of special characters used without separation, or omit for default value (e.g. `,.-'"+!%/`)
            - `--frequency` / `f`: The frequency of inserted characters
    #### V2
    - `--chars` / `-c`: The desired character types you'd like in your password. Enter them with a comma as separation (e.g. `digits,lowercase,uppercase,special`)
    #### V3
    - Character types (Enter 0 to remove a character type)
        - `--lowercase` / `-L`: The minimum amount of lowercase characters to use
        - `--uppercase` / `-U`: The minimum amount of uppercase characters to use
        - `--special` / `-S`: The minimum amount of special characters to use
        - `--digits` / `-D`: The minimum amount of digits to use
    - `--differentiator` / `-d`: A string used to differentiate between two accounts on the same site, or for any other reason

## Examples
1. Using `generate`:
<img src="https://github.com/szentpeterimate/determinist/blob/main/docs/demos/demo_generate.gif"></img>

2. Using `prompt`:
<img src="https://github.com/szentpeterimate/determinist/blob/main/docs/demos/demo_prompt.gif"></img>
