2faauth by sheetung

# 2faauth

[中文](./readme/README_zh_Hans.md)|

2faauth adds private-chat TOTP management for LangBot. It can save named TOTP entries, query saved entries directly, and export or clear the stored data.

All commands are intended for private chat only. Enable/disable is controlled from the plugin WebUI configuration, not from user chat commands.

## WebUI Configuration

- `enabled`: Turns 2faauth on or off.
- `allowed_user_ids`: Optional private user allowlist. Separate multiple IDs with commas, spaces, semicolons, or new lines. When empty, all private-chat users are allowed.

After `enabled` is turned on, the first authorized private-chat use initializes a random Fernet user key and a derived user ID.

The first initialization reply includes:

- `user_id`: the unique user identifier derived from the key.
- `key`: the encryption/decryption key used for saved 2FA entries.

Save this key somewhere safe. It is shown when first generated and is not shown again by normal status checks.

## Commands

- `!lb2fa`: Show all saved authenticator names with current TOTP codes and countdowns.
- `!lb2fa <name>`: Query a saved entry directly and generate its current TOTP code.
  - Example: `!lb2fa gmail`
- `!lb2fa status`: Show WebUI enable state, current private user ID, allowlist state, and user ID.
- `!lb2fa add <name> <secret>`: Add or update a named TOTP entry with the default 6-digit, 30-second settings. Entry names cannot use reserved command words such as `add`, `remove`, `list`, `status`, `export`, `clear`, `reset`, `help`, `cleanup`, or `purge`.
  - Example: `!lb2fa add gmail JBSWY3DPEHPK3PXP`
- `!lb2fa remove <name>`: Remove a saved entry.
- `!lb2fa list`: List saved entries and their types.
- `!lb2fa export`: Export all saved entries as structured JSON containing `type` and `secret`.
- `!lb2fa clear`: Remove all saved entries. The user key and user ID are kept. Enable state is still controlled by WebUI.
- `!lb2fa reset`: Fully remove entries, the user key, and the user ID. Aliases: `cleanup`, `purge`. Enable state is still controlled by WebUI.
- `!lb2fa help`: Show command help.

## Security Notes

Saved entries are encrypted with the automatically generated Fernet user key after the key is initialized. The key is stored in plugin storage so the plugin can decrypt entries later, and the first generated copy is returned to the user for safekeeping.

For compatibility with older data, `encryption_key` or `enc_key` from plugin configuration is still accepted as a fallback decryption key. New saves prefer the automatically generated user key once it exists.

Example exported JSON:

```json
{
  "gmail": {
    "type": "totp",
    "secret": "JBSWY3DPEHPK3PXP"
  }
}
```

## Questions and Feedback

[![QQ Group](https://img.shields.io/badge/QQ群-965312424-green)](https://qm.qq.com/cgi-bin/qm/qr?k=en97YqjfYaLpebd9Nn8gbSvxVrGdIXy2&jump_from=webapi&authKey=41BmkEjbGeJ81jJNdv7Bf5EDlmW8EHZeH7/nktkXYdLGpZ3ISOS7Ur4MKWXC7xIx)