stealthfirems/laravel-otp-module

v1.1 2025-06-06 13:01 UTC

Requires

• stealthfirems/laravel-audit-module: ^2.4

MIT

• Mitchell Sprintbett

README

This is the authentication module developed by StealthFireMS for authentication with the Laravel Frame Work. This module supports

1. OTP Generaton and validation
2. TOTP Generaton and validation

Installation 💽

Install via composer

composer require stealthfirems/laravel-otp-module

Run Migrations

php artisan migrate

Notes

Responses are returned as objects to the calling functions. Repsonses are listed at the end of this doc.

Usage OTP

OTP Config

'OTP_TYPE' => env('OTP_TYPE', 'alpha_numeric'), #Options, numeric or alpha_numeric

'VALIDITY_LENGTH' => env('VALIDITY_LENGTH', 600), #The length a OTP code is valid for in SECONDS.

'OTP_LENGTH' => env('OTP_LENGTH', '6'), #The length of the OTP code

If you are using a custom auth contoller use the following to call any OTP related function.

use StealthFireMS\LaravelOTPModule\Otp;

Functions

generate_otp($user_identifier);

• $user_identifier: The identity that will be tied to the OTP. E.G User ID

validate_otp($user_identifer, $otp_token);

• $otp_token: The code that is being validated for signin.

Sample

generate_otp('[e-mail]');

validate_otp('[e-mail]', '123456');

Responses

On Success

{
  "status": true,
  "message": "OTP is valid"
}

Does not exist

{
  "status": false,
  "message": "OTP does not exist"
}

Not Valid*

{
  "status": false,
  "message": "OTP is not valid"
}

Expired

{
  "status": false,
  "message": "OTP Expired"
}

Delete expired tokens

You can add this artisan command to app/Console/Kernel.php to automatically clean on scheduled

protected function schedule(Schedule $schedule)
{
    $schedule->command('otp:clean')->daily();
}

Usage TOTP

TOTP Config is in config/totp.php:

return [
    'TOTP_SECRET_LENGTH' => env('TOTP_SECRET_LENGTH', 32),
    'TOTP_PERIOD' => env('TOTP_PERIOD', 60),
    'TOTP_DIGITS' => env('TOTP_DIGITS', 6),
];

Persistence

TOTP secrets are stored in the totps table, linked to the users table by user_id.
Each user can have multiple TOTP secrets

Usage

use StealthFireMS\LaravelOTPModule\Totp;

// Generate and persist a TOTP secret for a user
$totp = new Totp();
$response = $totp->generate_totp($user_id, $totp_name); // $totp_name is optional

// Validate a TOTP code for a user
$response = $totp->validate_totp($user_id, $totp_code);

• generate_totp($user_id, $totp_name)
  • Generates a new TOTP secret for the user (and optional name), saves it, and returns the secret and provisioning URI for QR code.
• validate_totp($user_id, $totp_code)
  • Validates the provided code against all of the user’s TOTP secrets.

Sample

// Generate and store a TOTP secret for user ID 89, named "Bitwarden"
$response = $totp->generate_totp(89, 'Bitwarden');
/*
$response = (object)[
    'status' => true,
    'secret' => 'BASE32SECRET...',
    'uri' => 'otpauth://totp/...',
    'message' => 'TOTP secret generated and saved'
];
*/

// Validate a TOTP code for user
$response = $totp->validate_totp(89, '123456');
/*
$response = (object)[
    'status' => true,
    'message' => 'TOTP is valid'
];
*/

Responses

On Success

{
  "status": true,
  "message": "TOTP is valid"
}

Not Valid

{
  "status": false,
  "message": "TOTP is not valid"
}

Expired

{
  "status": false,
  "message": "TOTP Expired"
}

Note:

• TOTP secrets are stored per user for persistence and multi-device support.
• Use the returned uri to generate a QR code for authenticator apps.
• The TOTP logic is fully compatible with Google Authenticator and similar apps.