alimiracle/php-totp-auth

A simple TOTP (Time-based One-Time Password) generator and validator.

1.0.1 2025-05-14 04:51 UTC

Requires

• php: >=7.0

Requires (Dev)

• phpunit/phpunit: ^12.1

LGPL-3.0

• Ali Miracle

README

A simple PHP library for generating and verifying Time-based One-Time Passwords (TOTP), compatible with authenticator apps like Google Authenticator, FreeOTP, and more.

Features

• TOTP generation and verification
• Compatible with PHP 7.0 and above
• Lightweight and framework-agnostic
• Can be integrated with Laravel, Symfony, and other frameworks

Installation

To install PHP TOTP Auth, use Composer, which is the recommended method:

composer require alimiracle/php-totp-auth

Once the installation is complete, you can start using the library in your PHP projects.

Usage

Basic Example

use TotpAuth\Totp;

$secret = 'mySuperSecretKey123!';

// Generate TOTP
$otp = Totp::generate($secret);
echo "Generated OTP: $otp\n";

// Verify TOTP (e.g., from user input)
$userInput = trim(fgets(STDIN));

if (Totp::verify($userInput, $secret)) {
    echo "? Valid OTP\n";
} else {
    echo "? Invalid OTP\n";
}

API Methods

The core functionality of the library revolves around two main methods: generate and verify. These methods can be accessed through the Totp class.

1. Totp::generate($secret, $digits = 6, $period = 40, $timestamp = null)

This method generates a Time-based One-Time Password (TOTP) based on a shared secret key.

Parameters:

• $secret (string): The shared secret key between the server and the client. This key is unique to each user and should be kept secure.
• $digits (integer, default: 6): The number of digits in the generated OTP. Common values are 6 or 8 digits.
• $period (integer, default: 40): The validity period in seconds. This defines how often a new OTP should be generated (default is 40 seconds).
• $timestamp (integer, optional): An optional UNIX timestamp for custom timing. If not provided, the current time is used.

Returns:

• (string): The generated TOTP code, which can be used for authentication.

Example Usage:

use TotpAuth\Totp;

$secret = 'mySuperSecretKey123!';

// Generate TOTP
$otp = Totp::generate($secret);
echo "Generated OTP: $otp\n";

2. Totp::verify($userInput, $secret, $digits = 6, $period = 40, $timestamp = null)

This method verifies a TOTP against the expected OTP generated using the same shared secret key.

Parameters:

• $userInput (string): The OTP provided by the user.
• $secret (string): The shared secret key used to generate the OTP.
• $digits (integer, default: 6): The number of digits expected in the OTP.
• $period (integer, default: 40): The validity period of the OTP.
• $timestamp (integer, optional): An optional UNIX timestamp for custom timing.
• $window (integer, default: 1): The time window (in periods) of tolerance. The window specifies how many periods before or after the current period the OTP is considered valid.

Returns:

• (bool): Returns true if the OTP is valid, false if it is invalid.

Example Usage:

use TotpAuth\Totp;

$userInput = trim(fgets(STDIN));  // User input from terminal or form
$secret = 'mySuperSecretKey123!';

// Verify TOTP
if (Totp::verify($userInput, $secret)) {
    echo "? Valid OTP\n";
} else {
    echo "? Invalid OTP\n";
}

Laravel Integration

To use this package in a Laravel project:

1. Require the package via Composer:

   composer require alimiracle/php-totp-auth
   

2. You can use it in your controller or service:

   use TotpAuth\Totp;
   
   class AuthController extends Controller
   {
       public function verifyTotp(Request $request)
       {
           $secret = auth()->user()->totp_secret;
           $code = $request->input('code');
   
           if (Totp::verify($code, $secret)) {
               return response()->json(['message' => 'OTP verified successfully.']);
           }
   
           return response()->json(['message' => 'Invalid OTP.'], 401);
       }
   }
   

Testing

The PHP TOTP Auth package includes unit tests that cover a variety of scenarios:

• Valid and invalid OTP generation and verification
• Custom OTP lengths and validity periods
• OTP expiration handling
• Handling custom timestamps and invalid secret keys
• Edge cases such as an empty secret key

You can run the tests with the following command:

composer test

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).

See the LICENSE file for more details.

Author

Ali Miracle Email: [e-mail]