{"id":35127398,"url":"https://github.com/luqastw/passtw","last_synced_at":"2026-03-17T11:34:15.377Z","repository":{"id":325169334,"uuid":"1100010717","full_name":"luqastw/passtw","owner":"luqastw","description":"passtw is a Python-based random password generator + encrypted local vault, using AES‑128 encryption and a cryptographic key.","archived":false,"fork":false,"pushed_at":"2026-03-02T01:04:29.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-02T04:39:43.905Z","etag":null,"topics":["cli","cryptography","password","password-generator","python","security","security-tools","terminal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luqastw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-19T18:12:30.000Z","updated_at":"2026-03-02T01:04:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luqastw/passtw","commit_stats":null,"previous_names":["luqastw/passtw"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/luqastw/passtw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luqastw%2Fpasstw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luqastw%2Fpasstw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luqastw%2Fpasstw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luqastw%2Fpasstw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luqastw","download_url":"https://codeload.github.com/luqastw/passtw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luqastw%2Fpasstw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30622758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T11:26:08.186Z","status":"ssl_error","status_checked_at":"2026-03-17T11:24:37.311Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cryptography","password","password-generator","python","security","security-tools","terminal"],"created_at":"2025-12-28T03:32:55.344Z","updated_at":"2026-03-17T11:34:15.372Z","avatar_url":"https://github.com/luqastw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# passtw\n\nA command-line password manager that generates cryptographically secure passwords and stores them in an encrypted local vault. Built with Python, designed for developers and system administrators who prefer offline, terminal-native tooling.\n\n![Python](https://img.shields.io/badge/Python-3.10+-3776ab?logo=python\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-green)\n![CI](https://github.com/luqastw/passtw/actions/workflows/ci.yml/badge.svg)\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Security Model](#security-model)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\npasstw is a single-binary CLI tool that combines password generation with encrypted local storage. It requires no external services, no cloud accounts, and no background processes. All data stays on disk, encrypted at rest.\n\n**Key characteristics:**\n\n- Cryptographically secure password generation using Python's `secrets` module\n- AES-128-CBC encryption with HMAC-SHA256 integrity verification (Fernet)\n- Cross-platform data storage following OS conventions (XDG on Linux, `~/Library` on macOS, `%APPDATA%` on Windows)\n- Zero network dependencies -- fully offline operation\n\n---\n\n## Architecture\n\n```\nsrc/passtw/\n  cli.py              CLI entry point and command routing (Click)\n  generator.py        Password generation engine\n  crypto_manager.py   Fernet-based encryption and vault I/O\n  config_loader.py    JSON configuration persistence\n  keygen.py           Cryptographic key generation with file permission enforcement\n  paths.py            Platform-aware data directory resolution\n  preferences.py      Password policy dataclass\n```\n\nThe project follows a layered design where each module encapsulates a single responsibility:\n\n| Layer | Module | Responsibility |\n|-------|--------|----------------|\n| Interface | `cli.py` | Parses commands, orchestrates workflows, handles user interaction |\n| Generation | `generator.py` | Builds character pools, applies Fisher-Yates shuffle via `secrets.randbelow()` |\n| Storage | `crypto_manager.py` | Encrypts passwords with Fernet, reads/writes `vault.json` |\n| Configuration | `config_loader.py` | Manages `config.json`, validates policy constraints |\n| Infrastructure | `paths.py`, `keygen.py` | Resolves OS-specific paths via `platformdirs`, generates keys with restricted permissions |\n\n### Data Flow\n\n```\nUser command --\u003e cli.py --\u003e generator.py (generate password)\n                       --\u003e crypto_manager.py (encrypt + store)\n                       --\u003e config_loader.py (read policy)\n                       --\u003e paths.py (resolve file locations)\n```\n\n### Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `cryptography` | Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256) |\n| `click` | Command-line interface framework |\n| `platformdirs` | OS-native data directory resolution |\n| `pyperclip` | Clipboard integration for password retrieval |\n| `pygments` | Syntax-highlighted output |\n\n---\n\n## Security Model\n\n### Password Generation\n\nPasswords are generated using `secrets.SystemRandom`, which draws from the operating system's cryptographic random number generator (`/dev/urandom` on Linux, `CryptGenRandom` on Windows). The generation process:\n\n1. Builds a character pool from the active policy (uppercase, lowercase, digits, symbols)\n2. Guarantees at least one character from each enabled category\n3. Fills remaining positions with uniformly random selections from the full pool\n4. Applies a Fisher-Yates shuffle using `secrets.randbelow()` to eliminate positional bias\n\n### Encryption\n\nPasswords are encrypted using **Fernet**, which provides authenticated encryption:\n\n- **Cipher:** AES-128 in CBC mode\n- **Integrity:** HMAC-SHA256\n- **Key derivation:** Fernet key generated via `Fernet.generate_key()` (128-bit, URL-safe base64 encoded)\n- **Storage:** Encrypted tokens stored as base64 strings in `vault.json`\n\n### File Permissions\n\nThe encryption key file (`secret.key`) is created with `0600` permissions (owner read/write only), enforced programmatically via `os.chmod()` using `stat.S_IRUSR | stat.S_IWUSR`.\n\n### Threat Model\n\npasstw is designed for local, single-user password management. It protects against:\n\n- Plaintext password exposure on disk\n- Unauthorized file access (via OS-level permissions)\n- Tampered ciphertext (via HMAC verification)\n\nIt does not protect against:\n\n- Keyloggers or memory-scraping malware on a compromised host\n- Attackers with root/admin access to the machine\n\n---\n\n## Installation\n\n**Prerequisites:** Python 3.10+ and [pipx](https://pypa.github.io/pipx/).\n\n### Linux / macOS\n\n```bash\ngit clone https://github.com/luqastw/passtw.git\ncd passtw\nsh install.sh\n```\n\n### Windows (PowerShell)\n\n```powershell\ngit clone https://github.com/luqastw/passtw.git\ncd passtw\n.\\install.ps1\n```\n\n### Manual Installation\n\n```bash\npipx install .\npasstw init\n```\n\nAfter installation, run `passtw init` to generate the encryption key and create the vault.\n\n---\n\n## Usage\n\n```bash\npasstw gen \u003cname\u003e           # Generate a new password and store it\npasstw get \u003cname\u003e           # Retrieve a password from the vault\npasstw get \u003cname\u003e -c        # Retrieve and copy to clipboard\npasstw ls                   # List all stored password entries\npasstw rm \u003cname\u003e            # Remove a password (with confirmation)\npasstw set \u003coption\u003e         # Enable a character type in the policy\npasstw unset \u003coption\u003e       # Disable a character type in the policy\npasstw conf                 # Display current configuration\npasstw keygen               # Generate a new encryption key\npasstw --help               # Show all commands and options\n```\n\n### Examples\n\n```bash\n# Generate a password for a GitHub account\npasstw gen github\n\n# Copy the password to clipboard\npasstw get github -c\n\n# Disable symbols in generated passwords\npasstw unset sims\n\n# Check current policy\npasstw conf\n```\n\n---\n\n## Configuration\n\nConfiguration is stored in `config.json` within the platform-specific data directory:\n\n| OS | Path |\n|----|------|\n| Linux | `~/.local/share/passtw/config.json` |\n| macOS | `~/Library/Application Support/passtw/config.json` |\n| Windows | `%APPDATA%\\passtw\\config.json` |\n\nThe policy controls which character classes are included in generated passwords:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `upper` | Uppercase letters (A-Z) | Enabled |\n| `lower` | Lowercase letters (a-z) | Enabled |\n| `nums` | Digits (0-9) | Enabled |\n| `sims` | Symbols (!@#$%...) | Enabled |\n\nAt least one character class must remain enabled at all times.\n\nFor development, set `PASSTW_ENV=dev` to use a local `./data` directory instead of the system path.\n\n---\n\n## Development\n\nThe project uses [Poetry](https://python-poetry.org/) for dependency management and packaging.\n\n```bash\n# Install dependencies\nmake install\n\n# Run in development mode\nmake run ARGS='init'\nmake run ARGS='gen test'\n\n# Build the package\nmake build\n\n# Clean build artifacts\nmake clean\n```\n\n### Dev Dependencies\n\n| Tool | Purpose |\n|------|---------|\n| `pytest` | Test runner |\n| `ruff` | Linter |\n| `black` | Code formatter |\n| `bandit` | Security static analysis (SAST) |\n| `pip-audit` | Dependency vulnerability scanning |\n| `pyfakefs` | Filesystem isolation for tests |\n\n---\n\n## Testing\n\n```bash\nmake test       # Run unit tests\nmake sec        # Run security checks (Bandit + pip-audit)\n```\n\nThe test suite covers the three core modules:\n\n| Module | Tests | Coverage |\n|--------|-------|----------|\n| `generator.py` | Password structure, character pool constraints, shuffle correctness, factory wrappers | 7 tests |\n| `crypto_manager.py` | Encrypt/decrypt roundtrip, duplicate detection, missing key/vault errors | 8 tests |\n| `config_loader.py` | Default creation, config loading, validation constraints, directory setup | 4 tests |\n\nTests use `pyfakefs` for filesystem isolation, ensuring no test touches the real filesystem. Mock objects are used to inject dependencies and verify behavior without side effects.\n\n### CI/CD\n\nA GitHub Actions pipeline runs on every push and pull request to `main` and `develop`:\n\n1. Install dependencies via Poetry\n2. Initialize the application\n3. Run the full test suite\n4. Run security scans (Bandit for SAST, pip-audit for dependency vulnerabilities, Safety for known CVEs)\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Write tests for new functionality\n4. Ensure all checks pass (`make test \u0026\u0026 make sec`)\n5. Submit a pull request\n\nPlease follow the existing code style. The project uses `black` for formatting and `ruff` for linting.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluqastw%2Fpasstw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluqastw%2Fpasstw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluqastw%2Fpasstw/lists"}