Metadata-Version: 2.5
Name: lib2fas
Version: 1.0.0
Summary: Unofficial implementation of 2fas for Python (as a library)
Project-URL: Documentation, https://github.com/robinvandernoord/lib2fas-python#readme
Project-URL: Issues, https://github.com/robinvandernoord/lib2fas-python/issues
Project-URL: Source, https://github.com/robinvandernoord/lib2fas-python
Author-email: Robin van der Noord <robinvandernoord@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: configuraptor>=1.26.1
Requires-Dist: cryptography
Requires-Dist: keyring
Requires-Dist: pyjson5
Requires-Dist: pyotp
Requires-Dist: rapidfuzz
Provides-Extra: dev
Requires-Dist: edwh; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest-mypy-testing; extra == 'dev'
Requires-Dist: su6[all]; extra == 'dev'
Description-Content-Type: text/markdown

# lib2fas Python

Unofficial implementation of 2fas for Python (as a library).
This library serves as the backend for
the [robinvandernoord/2fas-python](https://github.com/robinvandernoord/2fas-python) CLI, a command-line tool that
provides an easy interface to interact with the 2fas TOTP.

## Installation

To install this project, use pip:

```bash
pip install lib2fas
# or to also install the cli tool:
pip install 2fas
```

## Usage

After installing the package, you can import it in your Python scripts as follows:

```python
import lib2fas

services = lib2fas.load_services("/path/to/file.2fas", passphrase="optional")  # -> TwoFactorStorage

services.generate()  # generate all TOTP keys

gmail = services["gmail"]  # exact match (case-insensitive), returns a list of 'TwoFactorAuthDetails' instances.

github = services.find("githbu")  # fuzzy match should find GitHub, returns a new TwoFactorStorage.

for label, services in github.items():
    # one label can have multiple services!
    for service in services:  # 'service' is a TwoFactorAuthDetails instance
        # Print label, service name, and TOTP code
        print("Label:", label)
        print("Service Name:", service.name)
        print("TOTP Code:", service.generate())  # or .generate_int() to get the code as a number.
```

The `passphrase` option of `load_services` is optional.
If you don't provide a passphrase and your file is encrypted, you will be prompted for one.
When available, the OS keyring stores it under a per-session name. After a reboot it is no longer
retrieved, although its stale keyring item may remain until it is cleaned up.

Storing the passphrase in the login keyring is a cache-expiry mechanism, not access control. Do not
assume it protects the passphrase from other processes in your unlocked login session; the exact
protection depends on the keyring backend.

> **Note:** only the "Secret Storage" keychain backend on Debian-based Linux has been tested.

### Unlocking with a key instead of a passphrase

A `.2fas` file is encrypted with AES-GCM under a key that PBKDF2 derives from your passphrase and a
salt stored inside the file itself. You can work with that key directly instead of the passphrase:

```python
import json

import lib2fas

with open("/path/to/file.2fas") as f:
    encrypted_block = json.load(f)["servicesEncrypted"]

salt = lib2fas.extract_salt(encrypted_block)  # the PBKDF2 salt embedded in the file
key = lib2fas.derive_key("my passphrase", salt)  # 32 bytes

services = lib2fas.load_services("/path/to/file.2fas", key=key)
```

For interactive unlocking you can inject your own `UnlockerProtocol` instead, which lets the caller
decide where a key comes from and how long it is cached. For example, unlocking with a key stored on
a hardware token instead of typing a passphrase:

```python
import lib2fas


class HardwareKeyUnlocker(lib2fas.UnlockerProtocol):
    def unlock(self, filename: str, salt: bytes) -> bytes | None:
        return my_hardware_token.derive_key(salt)

    def invalidate(self, filename: str, salt: bytes) -> None: ...

    def cleanup(self) -> int:
        return -1  # number of stale items removed, or -1 if unknown


services = lib2fas.load_services("/path/to/file.2fas", unlocker=HardwareKeyUnlocker())
```

`invalidate` is called automatically when a key fails to decrypt, so the unlocker can evict a bad
cached entry before the next retry. `load_services` retries until `unlock()` returns `None` (in which
case it returns `None` too); pass `max_retries=N` to tolerate `N` failures and raise the
`PermissionError` on the next one. The default unlocker is `lib2fas.PassphraseUnlocker`, which
reproduces the keyring behaviour described above.

## License

This project is licensed under the MIT License.
