{"id":35132103,"url":"https://github.com/wrogistefan/desktop-2fa","last_synced_at":"2026-01-13T22:59:10.185Z","repository":{"id":331127111,"uuid":"1123798604","full_name":"wrogistefan/desktop-2fa","owner":"wrogistefan","description":"A secure offline desktop application for generating and managing TOTP 2FA codes. Features encrypted vault storage, modern cryptography (Argon2 + AES‑GCM), modular architecture, and a local‑first approach with no cloud dependencies. Designed for reliability, extensibility, and future cross‑platform UI.","archived":false,"fork":false,"pushed_at":"2026-01-13T12:10:40.000Z","size":632,"stargazers_count":26,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T22:58:53.419Z","etag":null,"topics":["2fa","aes-gcm","argon2","authenticator","cryptography","desktop-app","local-first","offline","open-source","privacy","security","totp","vault"],"latest_commit_sha":null,"homepage":"https://desktop-2fa.lukasz-perek.workers.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wrogistefan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"lukaszperek","buy_me_a_coffee":"lukaszperek"}},"created_at":"2025-12-27T16:40:35.000Z","updated_at":"2026-01-13T05:52:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wrogistefan/desktop-2fa","commit_stats":null,"previous_names":["wrogistefan/desktop-2fa"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/wrogistefan/desktop-2fa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrogistefan%2Fdesktop-2fa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrogistefan%2Fdesktop-2fa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrogistefan%2Fdesktop-2fa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrogistefan%2Fdesktop-2fa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wrogistefan","download_url":"https://codeload.github.com/wrogistefan/desktop-2fa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrogistefan%2Fdesktop-2fa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["2fa","aes-gcm","argon2","authenticator","cryptography","desktop-app","local-first","offline","open-source","privacy","security","totp","vault"],"created_at":"2025-12-28T06:07:19.041Z","updated_at":"2026-01-13T22:59:10.178Z","avatar_url":"https://github.com/wrogistefan.png","language":"Python","funding_links":["https://ko-fi.com/lukaszperek","https://buymeacoffee.com/lukaszperek"],"categories":[],"sub_categories":[],"readme":"# 🛡️ Desktop-2FA\n\nA secure, offline two-factor authentication (2FA) manager for desktop environments. Built with Python, featuring strong encryption and no cloud dependencies.\n\n🌐 **Landing Page**: [desktop-2fa.lukasz-perek.workers.dev](https://desktop-2fa.lukasz-perek.workers.dev/)\n\n![PyPI - Downloads](https://img.shields.io/pypi/dm/desktop-2fa)\n[![PyPI version](https://img.shields.io/pypi/v/desktop-2fa.svg)](https://pypi.org/project/desktop-2fa/)\n![Python versions](https://img.shields.io/pypi/pyversions/desktop-2fa.svg)\n![License](https://img.shields.io/github/license/wrogistefan/desktop-2fa)\n![Build](https://github.com/wrogistefan/desktop-2fa/actions/workflows/ci.yml/badge.svg)\n[![codecov](https://codecov.io/gh/wrogistefan/desktop-2fa/branch/main/graph/badge.svg)](https://codecov.io/gh/wrogistefan/desktop-2fa)\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔐 **Vault Security** | AES-256-GCM encryption with Argon2id key derivation |\n| ⏱️ **TOTP Generation** | RFC 6238 compliant code generation |\n| 💻 **Full CLI** | Complete command-line interface for managing tokens |\n| 🔓 **Stateless Design** | Every command requires explicit password authentication |\n| 🛡️ **Password Policy** | Configurable password strength enforcement |\n| 🧪 **Well Tested** | 180+ tests passing with comprehensive coverage |\n\n---\n\n## 📸 Screenshots\n\n![Add entry interactively](https://raw.githubusercontent.com/wrogistefan/desktop-2fa/main/assets/screenshots/add_interactive.png)\n*Adding a new TOTP entry interactively*\n\n![Code generation](https://raw.githubusercontent.com/wrogistefan/desktop-2fa/main/assets/screenshots/codegen_ss.png)\n*Generating a TOTP code for an entry*\n\n![Rename and duplicate error](https://raw.githubusercontent.com/wrogistefan/desktop-2fa/main/assets/screenshots/rename_add_duplicate.png)\n*Renaming an entry with duplicate detection*\n\n![Version and list](https://raw.githubusercontent.com/wrogistefan/desktop-2fa/main/assets/screenshots/version_list_ss.png)\n*Viewing version info and listing all entries*\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\npip install desktop-2fa\n```\n\nVerify installation:\n\n```bash\npython -c \"import desktop_2fa; print(desktop_2fa.__version__)\"\n# Output: 0.7.3\n```\n\n### Basic Usage\n\n```bash\n# Add a new TOTP token\nd2fa add GitHub GitHub JBSWY3DPEHPK3PXP\n\n# List all entries\nd2fa list\n\n# Generate a code\nd2fa code GitHub\n\n# Initialize a new vault\nd2fa init-vault\n```\n\n### Non-Interactive Usage\n\n```bash\n# Provide password via command line\nd2fa --password mypassphrase add GitHub GitHub JBSWY3DPEHPK3PXP\n\n# Provide password via file\nd2fa --password-file /path/to/passphrase.txt add GitHub GitHub JBSWY3DPEHPK3PXP\n```\n\n---\n\n## 📁 Vault Lifecycle\n\nThe vault is an encrypted storage file located at `~/.desktop-2fa/vault`.\n\n### Vault Creation\n\nWhen a command requires a vault and none exists:\n\n1. The CLI prompts for a new password (interactive mode) or requires `--password`/`--password-file` (non-interactive mode)\n2. An empty encrypted vault is created\n3. **A confirmation message is always printed:** `Vault created at \u003cpath\u003e`\n\n### Vault Loading\n\nWhen a command requires a vault and it exists:\n\n1. The CLI prompts for the existing password (interactive mode) or requires credentials (non-interactive mode)\n2. The vault is decrypted and loaded\n3. If the password is invalid, the CLI exits with `typer.Exit(1)`\n\n### Duplicate Entry Handling\n\nThe `rename` command enforces deterministic behavior when multiple entries match the target name:\n\n- If **multiple entries** match the provided name (issuer or account_name), the rename is **aborted**\n- Error message: `Error: Multiple entries named '\u003cname\u003e' exist. Operation aborted. Resolve duplicates first.`\n- No entry is renamed in this case\n- This check occurs **before** any mutation\n\n---\n\n## 📖 CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `d2fa add \u003cname\u003e \u003cissuer\u003e \u003csecret\u003e` | Add a new TOTP entry |\n| `d2fa list` | List all entries |\n| `d2fa code \u003cname\u003e` | Generate TOTP code |\n| `d2fa rename \u003cold\u003e \u003cnew\u003e` | Rename an entry |\n| `d2fa remove \u003cname\u003e` | Remove an entry |\n| `d2fa export \u003cpath\u003e` | Export vault to JSON |\n| `d2fa import \u003cpath\u003e` | Import from JSON |\n| `d2fa backup` | Create a backup |\n| `d2fa init-vault` | Initialize new vault |\n\n---\n\n## 🔒 Security\n\nThe vault uses:\n- **AES-256-GCM** for authenticated encryption\n- **Argon2id** for key derivation (time_cost=4, memory_cost=128MiB, parallelism=2)\n- **Versioned header** for forward compatibility\n\nEvery command requires explicit password authentication. No session-based access.\n\n### Security Hardening (v0.7.3)\nVersion 0.7.3 includes additional DEF-02 fixes that ensure PermissionDenied exceptions are properly caught during vault creation:\n- Empty passwords are immediately rejected with a clear error message\n- Permission errors are distinguished from missing vault files\n- No Python stack traces are shown to users\n- User-friendly error messages for filesystem permission issues\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [User Manual](docs/user_manual.md) | Complete usage guide |\n| [CLI UX Specification](docs/ux.md) | UX contract and behavior |\n| [Cryptography](docs/crypto.md) | Security details |\n\n---\n\n## 🧪 Testing\n\n```bash\npytest tests/              # Run all tests\npytest --cov=src/desktop_2fa  # Run with coverage\n```\n\n---\n\n## 🏗️ Project Structure\n\n```\nsrc/desktop_2fa/\n├── cli/           # Command-line interface\n├── crypto/        # Encryption utilities\n├── totp/          # TOTP generation\n├── vault/         # Vault management\n├── ui/            # Desktop GUI\n└── utils/         # Utilities\n```\n\n---\n\n## 📄 License\n\nApache License 2.0. See [LICENSE](LICENSE) file.\n\n---\n\n## 👤 Author\n\nŁukasz Perek\n\n---\n\n## 💖 Support the Project\n\nDesktop‑2FA is an independent open‑source tool built with a focus on autonomy, transparency, and offline security.\nIf you find it useful and want to support ongoing development, you can do so through the platforms below:\n\n- **Ko‑fi**: https://ko-fi.com/lukaszperek\n- **Buy Me a Coffee**: https://buymeacoffee.com/lukaszperek\n- **AirTM**: https://airtm.me/lukper\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrogistefan%2Fdesktop-2fa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwrogistefan%2Fdesktop-2fa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrogistefan%2Fdesktop-2fa/lists"}