{"id":20126705,"url":"https://github.com/cc-d/open2fa","last_synced_at":"2025-05-06T17:35:33.603Z","repository":{"id":216923663,"uuid":"741127681","full_name":"cc-d/open2fa","owner":"cc-d","description":"A 2FA CLI tool for generating 2FA codes using TOTP secrets, with an optional SECURE remote api, and an optional web ui enabling 2FA code generation from any device","archived":false,"fork":false,"pushed_at":"2024-04-12T18:25:35.000Z","size":136,"stargazers_count":28,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-13T02:28:23.192Z","etag":null,"topics":["2fa","encryption","open2fa","pip","python","totp"],"latest_commit_sha":null,"homepage":"https://open2fa.liberfy.ai","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/cc-d.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-01-09T18:50:06.000Z","updated_at":"2024-04-14T19:37:41.493Z","dependencies_parsed_at":"2024-03-31T03:26:31.522Z","dependency_job_id":"fe314e64-2f90-4fd8-b6ec-d08de1f4cdf0","html_url":"https://github.com/cc-d/open2fa","commit_stats":null,"previous_names":["cc-d/open2fa"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-d%2Fopen2fa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-d%2Fopen2fa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-d%2Fopen2fa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-d%2Fopen2fa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cc-d","download_url":"https://codeload.github.com/cc-d/open2fa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224517277,"owners_count":17324409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","encryption","open2fa","pip","python","totp"],"created_at":"2024-11-13T20:17:19.832Z","updated_at":"2024-11-13T20:17:20.520Z","avatar_url":"https://github.com/cc-d.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# open2fa\n\n[open2fa.liberfy.ai](https://open2fa.liberfy.ai) NOW LIVE\n\nOpen2FA is a 100% LIBRE tool for generating Two-Factor Authentication (2FA) (TOTP) codes, with optional, secure, remote sync/restore/etc capabilities, as well as optional webui 2FA code generation.\n\nAll code can be found at:\n\n[CLI repo](https://github.com/cc-d/open2fa)\n\n[API/WebUI repo](https://github.com/cc-d/open2fa-server)\n\nFor information as to how the remote capabilities work, see [open2fa.liberfy.ai](https://open2fa.liberfy.ai)\n\nSee the [changelog](https://github.com/cc-d/open2fa/blob/main/CHANGELOG.md) to follow ongoing development.\n\n## Features\n\n- **CLI 2FA Code Generation**: Generate 2FA codes from the command line from TOTP secret keys stored either locally or remotely.\n- **Secure Remote Capabilitites**: All remotely stored TOTP secrets are stored encrypted and are only decrypted client side.\n- **Easily restore TOTP secrets**: Easily transfer and restore TOTP secrets from any device from only a UUID\n- **WebUI 2FA Code Generation**: Generate 2FA codes from the webui using the remotely stored encrypted TOTP secret keys from any device, even if the device does not have either the open2fa CLI or the TOTP secrets stored locally.\n- **Host your own API**: You can easily choose to host your own open2fa server and use it with the open2fa CLI.\n- **Open Source**: Open2FA is 100% open source and is both free as in freedom and free as in beer.\n\n## Installation\n\nInstall the CLI using `pip`:\n\n```bash\npip install open2fa\n```\n\nIf wanting to do development work, install with dev dependencies:\n\n```bash\npip install 'open2fa[dev]'\n```\n\n## Configuration\n\n**Environment Variables**:\n\n- `OPEN2FA_DIR`: The directory where TOTP secrets and the Open2FA UUID are stored. Defaults to `.open2fa` in the user's home directory.\n\n- `OPEN2FA_API_URL`: The URL of the Open2FA API instance to use. Defaults to `https://open2fa.liberfy.ai`.\n\n- `OPEN2FA_UUID` (Optional): Instead of using the `open2fa.uuid` file stored in `OPEN2FA_DIR`, you can set the `OPEN2FA_UUID` environment variable to the UUID you wish to use.\n\n## Default File Locations\n\n- **Secrets File**: The TOTP secrets are stored in `OPEN2FA_DIR/secrets.json`.\n- **UUID File**: The Open2FA UUID is stored in `OPEN2FA_DIR/open2fa.uuid`, but can also be set using the `OPEN2FA_UUID` environment variable. This UUID is used to identify the user and encrypt/decrypt their remotely stored secrets.\n\n## CLI Usage ( local )\n\nYou can see the full list of commands and options by running `open2fa -h` or `open2fa --help`.\n\n### Add a TOTP Secret\n\nThere aere two different ways to add a TOTP secret. The first is to add a secret from args passed to the add command. The second is to simply run `open2fa add` and then enter the appropriate information when prompted.\n\nAs of 1.3.0, the add command can now autodetect the name/secret from the input, by checking which input is a valid TOTP secret key. This means that input order is no longer important outside of the scenario that a valid TOTP secret is being used as a name for some reason.\n\n#### With args:\n\nv1.3.0+:\n\n```bash\nopen2fa add I65VU7K5ZQL7WB4E abc123\n\nADDED NEW SECRET: abc123 I...E\n```\n\nbefore 1.3.0:\n\n```bash\nopen2fa add I65VU7K5ZQL7WB4E -n abc123\n\nADDED NEW SECRET: abc123 I...E\n```\n\n#### Without args:\n\n```bash\nopen2fa add\n\nEnter TOTP secret: I65VU7K5ZQL7WB4E\nEnter name for secret: test15\n\nADDED NEW SECRET: test15 I...E\n```\n\n### Delete a TOTP Secret\n\n```bash\nopen2fa delete -n TESTKEY123\n```\n\n### List All TOTP Secrets\n\n```bash\nopen2fa list\n```\n\nExample Output:\n\n```\nName         Secret\n-------      -----\nSecret1      I...E\nSecret2      I...E\nSecret3      A...B\n```\n\nTo show the secret keys, use the `-s` flag:\n\n```bash\nopen2fa list -s\n\nName       Secret\n-------    ------\nSecret1    I65VU7K5ZQL7WB4E\nSecret2    I65VU7K5ZQL7WB4E\nSecret3    I65VU7K5ZQL7WB4E\n```\n\n### Generate 2FA Codes\n\nGenerate codes for keys saved in `OPEN2FA_DIR/secrets.json`:\n\n```bash\nopen2fa % py3 -m open2fa.cli g -n TEST\n\nName                               Code      Next\n-------------------------------    ------    -----\naTESTTESTTESTTESTTESTTEST3         919513    27.29\naTESTTESTTESTTESTTESTTEST33        919513    27.29\naTESTTESTTESTTESTTESTTEST334       919513    27.29\naTESTTESTTESTTESTTESTTEST3344      919513    27.29\naTESTTESTTESTTESTTESTTEST334434    919513    27.29\nTESTTESTTESTTESTTESTTEST           919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\nTESTTESTTESTTESTTESTTEST2          919513    27.29\n```\n\nTokens will continue to be generated until the user exits the program with `Ctrl+C`.\n\nAs of v1.1.0+, the `open2fa generate` command will automatically adjust the height/width of the generated codes to fit the terminal window.\n\n```bash\nopen2fa g\n\nName                   Code      Next\n-------------------    ------    -----\nabc123                 450939    0.81\nabc123                 450939    0.81\nDefaultSecret          450939    0.81\nDefaultSecretunique    450939    0.81\nirc                    771544    0.81\nirs2                   789798    0.81\nnewtest                450939    0.81\npypi                   771052    0.81\ntest10                 450939    0.81\ntest11                 450939    0.81\ntest12                 450939    0.81\ntest123                450939    0.81\ntest15                 450939    0.81\n... [10] codes not shown ...\n```\n\n### Show Open2FA Info/Status/Secrets\n\n```bash\nopen2fa info\n```\n\nExample Output:\n\n```\n========== Open2FA INFO/STATUS ==========\n(add -s to show uncensored secrets)\n\nOpen2FA Directory: /Users/mym2/.open2fa\nOpen2FA Remote API URL: http://localhost:8000/api/v1\nNumber of secrets: 11\nOpen2FA UUID: 0...\nOpen2FA ID: X...\nOpen2FA Secret: Q...\n```\n\n## CLI Usage ( remote )\n\nWhen initializing the remote capabilities of the open2fa CLI, a UUID will be generated and stored in `OPEN2FA_DIR/open2fa.uuid`. This UUID is used to identify the user and encrypt/decrypt their remotely stored secrets. As long as the user has access to this UUID, they can restore their TOTP secrets from any device, as well as generate 2FA codes from the webui.\n\nFor usage with the webui, both the Open2FA ID and the Open2FA Secret are required. These can be determined from `open2fa info` after initializing the remote capabilities of the open2fa CLI.\n\n### Initialize the Remote Capabilities of the Open2FA Client\n\n```bash\nopen2fa remote init\n```\n\nExample Output:\n\n```\nopen2fa remote init\n\nDo you want to initialize remote capabilities of Open2FA? (y/n): y\n\nRemote capabilities initialized with UUID: 0e4742ef-780b-406d-8651-7766cf67be3f\nIt is recommended to save this UUID somewhere safe and use as an environment variable OPEN2FA_UUID.\n\n========== Open2FA INFO/STATUS ==========\n\nOpen2FA Directory: /Users/mym2/.open2fa\nOpen2FA Remote API URL: http://localhost:8000/api/v1\nNumber of secrets: 11\nOpen2FA UUID: 0e4742ef-780b-406d-8651-7766cf67be3f\nOpen2FA ID: XF1628BGJeibVv8C9UacG4\nOpen2FA Secret: QGcst74V9JXnyBnQmWSoCx\n```\n\nIn this example:\n\n- The Open2FA UUID is `0e4742ef-780b-406d-8651-7766cf67be3f`\n- The Open2FA ID is `XF1628BGJeibVv8C9UacG4`\n- The Open2FA Secret is `QGcst74V9JXnyBnQmWSoCx`\n\n## Remote Commands\n\n### Push TOTP Secrets to the remote server:\n\n```bash\nopen2fa remote push\n```\n\n### Pull TOTP Secrets from the remote server:\n\n```bash\nopen2fa remote pull\n```\n\n### Delete a TOTP Secret from the remote server\n\n```bash\nopen2fa remote delete -n TESTKEY123\n```\n\n### List all TOTP Secrets stored remotely\n\n```bash\nopen2fa remote list\n\nName           Secret\n-----------    -----\ntest_secret    I...E\n\n```\n\n## Testing\n\nYou can run the tests by running `pytest tests.py` in the root directory of the project\nor by running the vscode pytest launch configuration with f5.\n\n```\n---------- coverage: platform darwin, python 3.11.7-final-0 ----------\nName                   Stmts   Miss  Cover   Missing\n----------------------------------------------------\nopen2fa/__init__.py        3      0   100%\nopen2fa/cli.py           102      7    93%   230-231, 237-238, 286-287, 298\nopen2fa/cli_utils.py      63      0   100%\nopen2fa/common.py         70      1    99%   123\nopen2fa/config.py         12      0   100%\nopen2fa/ex.py             15      2    87%   3, 19\nopen2fa/main.py          203     22    89%   81, 114-118, 126, 180, 195-199, 243-244, 284, 327-328, 384-385, 388-390, 404\nopen2fa/msgs.py           21      0   100%\nopen2fa/totp.py           30      0   100%\nopen2fa/utils.py          31     14    55%   20-25, 28, 52-63\nopen2fa/version.py         1      0   100%\n----------------------------------------------------\nTOTAL                    551     46    92%\n\n==================================================================== 21 passed in 2.29s\n```\n\nThe tests are not complete, and need to be expanded.\n\n## Contributing\n\nFeel free to open an issue or pull request. If you are opening a pull request, please make sure to run the tests and ensure that the coverage does not decrease, and any new code is covered by tests.\n\nRemember to update the [changelog](https://github.com/cc-d/open2fa/blob/main/CHANGELOG.md) with any changes and to update the version in `open2fa/version.py` and `pyproject.toml` (can use the `set_version.sh` script).\n\n## License\n\nMIT\n\n## Contact\n\nccarterdev@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-d%2Fopen2fa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcc-d%2Fopen2fa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-d%2Fopen2fa/lists"}