Metadata-Version: 2.1
Name: py2fa-cli
Version: 1.1.0
Summary: Command-line application for calculating one-time passwords for 2FA.
Home-page: https://github.com/arcctgx/py2fa-cli
Author: arcctgx
Author-email: arcctgx@o2.pl
License: GPLv3
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# py2fa-cli

[![PyPI version](https://img.shields.io/pypi/v/py2fa-cli?logo=python&label=PyPI)](https://pypi.org/project/py2fa-cli/)
[![PePy downloads](https://img.shields.io/pepy/dt/py2fa-cli?logo=python&label=Downloads&color=%230C7DBE)](https://pepy.tech/project/py2fa-cli)

Calculates and displays time-based one-time passwords (TOTP) for two-factor
authentication:

```sh
$ py2fa pypi.org
One-time password: 123456 (valid for 13.7 seconds)
```

## Installation

For typical use:

```sh
python3 -m pip install py2fa-cli
```

For development:

```sh
git clone https://github.com/arcctgx/py2fa-cli
cd py2fa-cli
python3 -m pip install --editable .
```

## Dependencies

* `pyotp`
* `pyxdg`

These dependencies will be installed automatically when `py2fa-cli` is installed
by `pip`.

## Configuration

TOTP secrets are stored in user's XDG configuration directory. Unless you
changed your `XDG_CONFIG_HOME`, that will be `.config/py2fa/secrets.json` in
your `$HOME`. The secrets file must not be world-accessible (readable, writable
or executable): in such case `py2fa` will refuse to load it.

The secrets file is a dictionary represented in JSON format, e.g.:

```json
{
    "pypi.org": "MYPYPITOTPSECRET",
    "test.pypi.org": "MYTESTPYPITOTPSECRET",
    "example.com": "otpauth://totp/ExampleLLC:you@example.com?secret=HUNTER2&issuer=ExampleLLC&period=15"
}
```

The dictionary key is what you provide in the command-line, so just use any
name that's convenient. The value is the shared TOTP secret in base32 format,
or an `otpauth://` URI.

### A note for Microsoft Authenticator users

It is not possible to extract the shared secret from the Microsoft Authenticator
application once it's been configured. You can only obtain the shared secret
during the initial setup of the authenticator app.

When setting up 2FA and presented with a QR code, **do not** scan it directly
with Microsoft Authenticator. Instead, use a generic QR code scanner app to
retrieve the `otpauth://` URI, which will look similar to the example shown
above. Store this URI in your `secrets.json` file. Afterward, you can still
scan the QR code with Microsoft Authenticator if desired - both `py2fa` and
the app will generate the same TOTP codes.

A [known issue] with `otpauth://` URIs generated by Microsoft MFA is that they
may not fully comply with the URI specification: the issuer parameter may differ
from the issuer label. To work around this, you can either manually align the
issuer parameter with the issuer label in your configuration file, or simply
remove the issuer parameter from the URI.

The example in the Configuration section above shows a compliant URI, where
the issuer label (the part immediately following `totp/` and before the colon)
matches the value of the `&issuer=` parameter.

[known issue]: https://github.com/pyauth/pyotp/issues/120


