Metadata-Version: 2.4
Name: otp-cli-utils
Version: 1.5.0
Summary: A Python CLI tool to validate OTP codes
Author: Dilanka Rathnasiri
Maintainer: Dilanka Rathnasiri
Project-URL: Homepage, https://github.com/dilanka-rathnasiri/otp-cli-utils
Project-URL: Documentation, https://github.com/dilanka-rathnasiri/otp-cli-utils
Project-URL: Source, https://github.com/dilanka-rathnasiri/otp-cli-utils
Keywords: OTP
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: pyotp
Requires-Dist: qrcode[pil]
Dynamic: license-file

# OTP CLI Utils

A command-line utility for working with TOTP (Time-based One-Time Password) codes. This tool helps you generate, validate, and manage OTP secrets with ease.

## Features

- 🔑 Generate current TOTP codes from a secret
- ✅ Validate OTP codes against a secret
- 🔄 Generate secure random OTP secrets
- 📱 Create Google Authenticator compatible QR codes
- 🛠️ Simple and intuitive command-line interface

## Installation

Install the package using pip:

```bash
pip install otp-cli-utils
```

## Usage

### Get Current OTP Code

Get the current OTP code for a given secret:

```bash
otp-cli-utils get-otp <secret>
```

Example:
```bash
otp-cli-utils get-otp ABCDEF1234567890
```

### Validate an OTP

Validate if an OTP code matches the expected value for a given secret:

```bash
otp-cli-utils validate <secret> <otp> [--window-count <count>] [--time-period <seconds>]
```

Options:
- `--window-count`, `-w`: Tokens in the previous 30s time windows that should be considered valid (default: 0)
- `--time-period`, `-t`: OTP valid time period in seconds (default: 30)

Example:
- Without window count or time period option
```bash
otp-cli-utils validate ABCDEF1234567890 123456
```

- With window count option
```bash
otp-cli-utils validate ABCDEF1234567890 123456 --window-count 2
```

- With time period option
```bash
otp-cli-utils validate ABCDEF1234567890 123456 --time-period 120
```

### Generate a New OTP Secret

Generate a new secure random secret key for OTP generation:

```bash
otp-cli-utils generate-secret
```

### Generate QR Code for Authenticator Apps

- Generate a QR code that can be scanned by Google Authenticator or similar apps
- QR code will be generated with a new secure random secret key
- Generated QR code will be saved as a png image file

```bash
otp-cli-utils generate-secret-qr-code <label> <issuer> [filename]
```

Arguments:
- `label`: Account name (e.g., user@example.com)
- `issuer`: Service or provider name (e.g., GitHub)
- `filename`: (Optional) Output filename without extension (default: otp_secret_qr)

Example:
```bash
otp-cli-utils generate-secret-qr-code "user@example.com" "GitHub" github_2fa
```

## Exit Codes

- `0`: Command executed successfully
- `1`: Invalid OTP (for validate command) or error occurred

## Input Validation

The tool performs the following validations on the inputs:

- **OTP Secret**:
  - Must be a valid Base32 encoded string.
  - The length of the secret must be a multiple of 8.
  - It can only contain uppercase letters (`A-Z`), digits from `2` to `7`, and the padding character (`=`).

- **OTP Code**:
  - Must be a 6-digit number.

- **Window Count (`--window-count`, `-w`)**:
  - Must be an integer.
  - Must be a non-negative number (0 or greater).

- **Time Period (`--time-period`, `-t`)**:
  - Must be an integer.
  - Must be 30 seconds or greater.
  - Must be a multiple of 30.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
