README

Yamato is a PHP package for generating and validating One-Time Passwords (OTPs) with Redis rate limiting. It’s ideal for adding secure, time-limited authentication flows to your PHP application.

Features

Generates and validates OTPs.
Enforces rate limiting using Redis to prevent OTP abuse.
Configurable OTP expiration time and rate limits.

Installation

Install Yamato via Composer:

composer require esakian/yamato

Make sure to install Predis or any other Redis client compatible with your PHP setup, as it’s required for rate limiting.

Usage

Setup Initialize a Redis client and pass it to the package:

require 'vendor/autoload.php';

use Predis\Client;
use YourVendor\OTPAuth\OTPAuth;
use YourVendor\OTPAuth\RedisRateLimiter;

// Initialize Redis client
$redis = new Client();

// Configure Redis rate limiter (5 attempts per minute)
$rateLimiter = new RedisRateLimiter($redis, 5, 60);

// Configure OTP authentication with a 5-minute OTP expiration
$otpAuth = new OTPAuth($rateLimiter, 300);

Generating an OTP To generate an OTP for a given identifier (e.g., an email or user ID):

try {
    $identifier = 'user@example.com';
    $otp = $otpAuth->generateOTP($identifier);
    echo "Your OTP is: {$otp}\n";
} catch (Exception $e) {
    echo $e->getMessage(); // Handle rate limit exceptions
}

Validating an OTP To validate an OTP provided by the user:

$isValid = $otpAuth->validateOTP('user@example.com', $otp);
if ($isValid) {
    echo "OTP is valid.\n";
} else {
    echo "OTP is invalid or expired.\n";
}

Configuration

You can customize the OTP expiration time and rate limit as shown below:

// RedisRateLimiter configuration
$rateLimit = 5; // maximum 5 attempts
$rateLimitPeriod = 60; // within 60 seconds
$rateLimiter = new RedisRateLimiter($redis, $rateLimit, $rateLimitPeriod);

// OTPAuth configuration
$otpExpiration = 300; // OTP expires in 5 minutes
$otpAuth = new OTPAuth($rateLimiter, $otpExpiration);

Unit Tests

To run the unit tests:

Install development dependencies:

composer install --dev

Run PHPUnit:

vendor/bin/phpunit

Requirements

PHP >= 7.4
Redis server
Predis (or equivalent Redis client)

License

This package is open-source software licensed under the MIT license.

esakian / yamato

Maintainers

Details