diff --git a/README.md b/README.md index b741462..44d8c12 100644 --- a/README.md +++ b/README.md @@ -1,169 +1,173 @@ -# PassGen - Secure Password Generator +# ๐Ÿ” PassGen -A powerful, secure, and feature-rich password generator built with Python. Features a beautiful CLI with rich formatting and a modern web interface. +**Generate strong random passwords and memorable passphrases from a polished web interface or a practical Python CLI.** -![Python](https://img.shields.io/badge/python-3.14+-blue) -![License](https://img.shields.io/badge/license-MIT-green) -![Tests](https://img.shields.io/badge/tests-passing-success) +[![Tests](https://github.com/dk3yyyy/password-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/dk3yyyy/password-generator/actions/workflows/ci.yml) +[![Tested with Python 3.14](https://img.shields.io/badge/Tested%20with-Python%203.14-3776AB?logo=python&logoColor=white)](https://www.python.org/) +[![License: MIT](https://img.shields.io/badge/License-MIT-2E7D32.svg)](LICENSE) -## Features +PassGen uses Python's `secrets` module for cryptographically secure randomness. The web interface does not persist generated values, while CLI history is disabled unless you explicitly enable it for a generation command. -### CLI Features -- **Random Password Generation** - Generate secure passwords with customizable character sets -- **Passphrase Generation** - Create memorable passwords from wordlists -- **Interactive Mode** - User-friendly prompts for password creation -- **Opt-in History** - Save generated passwords only when explicitly requested -- **Config Management** - Save and load preferred settings -- **Export** - Export passwords to JSON or CSV -- **Categories** - Organize passwords by type (wifi, email, social, etc.) -- **Custom Wordlists** - Create and use custom wordlists for passphrases -- **Copy to Clipboard** - Cross-platform clipboard support -- **Strength Analysis** - Entropy calculation and strength detection -- **Pattern Detection** - Warns about repeated/sequential characters +## ๐Ÿ–ฅ๏ธ Web interface -### Web Interface -- Responsive, accessible interface for desktop and mobile -- Random password and passphrase modes -- Clear strength and entropy indicators -- One-click copy with inline validation feedback +![PassGen web interface showing a generated password, strength rating, entropy, and configuration controls](docs/web-ui.png) -## Installation +*The screenshot shows a generated sample; it is not a real credential.* -```bash -# Clone the repository -git clone https://github.com/dk3yyyy/password-generator.git -cd password-generator +- Random-password and passphrase modes +- Responsive layout for desktop and mobile +- Keyboard-accessible controls and inline validation +- Strength and entropy indicators +- One-click copy with a manual-copy fallback +- Generation limits aligned with backend validation -# Install dependencies -uv sync - -# Install dev dependencies for testing -uv sync --all-extras -``` +The displayed entropy is a pool-size estimate for the selected generator settings, not a guarantee of resistance to every cracking strategy. -## Usage +## โœจ Features ### CLI -```bash -# Run the CLI (starts in interactive mode by default) -uv run python main.py - -# Generate a random password -uv run python main.py --length 20 --upper --lower --digits --symbols - -# Generate a passphrase -uv run python main.py --passphrase --words 4 --capitalize +- Customizable uppercase, lowercase, number, and symbol sets +- Ambiguous-character exclusion and custom exclusions +- Memorable passphrases with configurable separators +- Interactive prompts and a quick-generation mode +- Strength analysis and weak-pattern warnings +- Optional clipboard copy +- Explicitly opt-in local history +- JSON or CSV history export +- Saved defaults, categories, and custom wordlists -# Quick generate (16-char with all character types + copy) -uv run python main.py --quick +### Security defaults -# Save your preferred settings -uv run python main.py --save-config +- Passwords are generated with Python's cryptographically secure `secrets` module. +- The web interface returns generated values only to the current page and does not write them to history. +- CLI history is written only when `--save-history` is supplied. +- History and exports receive owner-only permissions on POSIX systems. +- Custom wordlists are constrained to PassGen's local wordlist directory. -# Load saved config -uv run python main.py --config +> [!IMPORTANT] +> Saved history and exports contain plaintext passwords. Treat those files as sensitive and delete them when they are no longer needed. PassGen is a generator, not a password manager. -# View history -uv run python main.py --history - -# Explicitly save a generated password to history -uv run python main.py --length 20 --upper --lower --digits --symbols --save-history +## ๐Ÿš€ Quick start -# Export history -uv run python main.py --export json +### Requirements -# Clear history -uv run python main.py --clear-history +- Python 3.14+ +- [`uv`](https://docs.astral.sh/uv/) -# Copy to clipboard -uv run python main.py --length 16 --copy +### Install -# View version -uv run python main.py --version +```bash +git clone https://github.com/dk3yyyy/password-generator.git +cd password-generator +uv sync --all-extras ``` -### Web Interface +### Start the web interface ```bash -# Start the web server uv run python web.py ``` -Then open http://127.0.0.1:8000 in your browser. +Open [http://127.0.0.1:8000](http://127.0.0.1:8000). -## Command Line Options +### Use the CLI -| Flag | Description | Default | -|------|-------------|---------| -| `--length N` | Password length | 12 | -| `--upper` | Include uppercase letters | False | -| `--lower` | Include lowercase letters | False | -| `--digits` | Include digits | False | -| `--symbols` | Include special symbols | False | -| `--no-ambiguous` | Exclude ambiguous chars (0, O, l, 1, I) | False | -| `--exclude CHARS` | Characters to exclude | "" | -| `--count N` | Number of passwords to generate | 1 | -| `--copy` | Copy password to clipboard | False | -| `--passphrase` | Generate passphrase instead | False | -| `--words N` | Number of words for passphrase | 4 | -| `--separator SEP` | Separator for passphrase words | "-" | -| `--capitalize` | Capitalize passphrase words | False | -| `--add-number` | Append number to passphrase | False | -| `--category CAT` | Category for password | "" | -| `--wordlist NAME` | Custom wordlist for passphrase | "" | -| `--history` | Show password history | False | -| `--save-history` | Explicitly save generated passwords to local history | False | -| `--clear-history` | Clear all history | False | -| `--export FORMAT` | Export history (json/csv) | - | -| `--save-config` | Save current options as defaults | False | -| `--config` | Load saved config as defaults | False | -| `--quick` | Quick: 20-char password with copy | False | -| `--version` | Show version | - | -| `--interactive` | Force interactive mode | False | - -## Project Structure +```bash +# Interactive mode +uv run python main.py -``` -password-generator/ -โ”œโ”€โ”€ main.py # CLI application -โ”œโ”€โ”€ web.py # Web interface (FastAPI) -โ”œโ”€โ”€ pyproject.toml # Project configuration -โ”œโ”€โ”€ README.md # This file -โ”œโ”€โ”€ tests/ # Unit tests -โ”‚ โ””โ”€โ”€ test_main.py -โ””โ”€โ”€ templates/ # Web templates - โ””โ”€โ”€ index.html +# 20-character password using every character class +uv run python main.py --length 20 --upper --lower --digits --symbols + +# Four-word capitalized passphrase +uv run python main.py --passphrase --words 4 --capitalize + +# Generate and copy one strong 20-character password +uv run python main.py --quick + +# Explicitly save this result to local history +uv run python main.py --length 20 --upper --lower --digits --symbols --save-history ``` -## Security Features +## ๐Ÿงฐ CLI reference -- Uses Python's `secrets` module for cryptographically secure random generation -- Does not persist generated passwords unless `--save-history` is supplied -- Protects history and export files with owner-only permissions on POSIX systems -- Calculates password entropy for strength assessment -- Detects common weak passwords -- Warns about patterns (repeated chars, sequences, keyboard patterns) +| Flag | Description | Default | +|---|---|---:| +| `--length N` | Password length | `12` | +| `--upper` | Include uppercase letters | Off | +| `--lower` | Include lowercase letters | Off | +| `--digits` | Include numbers | Off | +| `--symbols` | Include symbols | Off | +| `--no-ambiguous` | Exclude `0`, `O`, `l`, `1`, and `I` | Off | +| `--exclude CHARS` | Exclude specific characters | `""` | +| `--count N` | Number of passwords to generate | `1` | +| `--copy` | Copy the generated value | Off | +| `--interactive` | Force interactive mode | Off | +| `--passphrase` | Generate a passphrase | Off | +| `--words N` | Number of passphrase words | `4` | +| `--separator SEP` | Separator between words | `-` | +| `--capitalize` | Capitalize passphrase words | Off | +| `--add-number` | Append a number to the passphrase | Off | +| `--category NAME` | Label a saved history entry | `""` | +| `--wordlist NAME` | Use a custom local wordlist | `""` | +| `--history` | Display saved history | โ€” | +| `--save-history` | Save generated values to local history | Off | +| `--clear-history` | Delete saved history | โ€” | +| `--export json\|csv` | Export saved history | โ€” | +| `--save-config` | Save the current options as defaults | Off | +| `--config` | Load saved defaults | Off | +| `--quick` | Generate and copy one strong 20-character password | Off | +| `--version` | Display the PassGen version | โ€” | + +## ๐Ÿ—‚๏ธ Local data + +PassGen stores optional local state under `~/.passgen/`: + +```text +~/.passgen/ +โ”œโ”€โ”€ config.json +โ”œโ”€โ”€ history.json +โ””โ”€โ”€ wordlists/ +``` -## Development +Generated values are not written there unless you explicitly use `--save-history`. -### Running Tests +## ๐Ÿงช Development ```bash +# Install project and development dependencies +uv sync --all-extras + +# Run the complete test suite uv run pytest tests/ -v + +# Compile-check the Python entry points +uv run python -m py_compile main.py web.py ``` -### Code Quality +For pull requests targeting `main`, GitHub Actions runs the test suite and a non-blocking Python compilation check. + +## ๐Ÿ“ Project structure -The project follows Python best practices with: -- Type hints -- Docstrings -- Modular design +```text +password-generator/ +โ”œโ”€โ”€ .github/workflows/ci.yml +โ”œโ”€โ”€ docs/web-ui.png +โ”œโ”€โ”€ main.py +โ”œโ”€โ”€ web.py +โ”œโ”€โ”€ templates/index.html +โ”œโ”€โ”€ tests/ +โ”‚ โ”œโ”€โ”€ test_main.py +โ”‚ โ””โ”€โ”€ test_web.py +โ”œโ”€โ”€ pyproject.toml +โ””โ”€โ”€ README.md +``` -## License +## ๐Ÿค Contributing -MIT License - See LICENSE file for details. +Bug reports and focused pull requests are welcome. Before submitting a change, run the test suite and keep security-sensitive behavior covered by regression tests. -## Contributing +## ๐Ÿ“„ License -Contributions are welcome! Please feel free to submit a Pull Request. \ No newline at end of file +Distributed under the [MIT License](LICENSE). diff --git a/docs/web-ui.png b/docs/web-ui.png new file mode 100644 index 0000000..da72ff8 Binary files /dev/null and b/docs/web-ui.png differ