<?php
/**
 * Conceptual explanation of TOTP principles, no executable code required for this foundational part.
 * The core idea revolves around a shared secret, the current time, and a hashing algorithm.
 *
 * Shared Secret: A unique, randomly generated string known only to the user and the server.
 * Time Step: A fixed interval (e.g., 30 seconds) during which an OTP is valid.
 * Counter: Derived from (current_time / time_step).
 * Hashing Algorithm: Typically HMAC-SHA1 or HMAC-SHA256, applied to the secret and the counter.
 *
 * Formula (simplified): OTP = Truncate(HMAC-SHA1(SharedSecret, TimeCounter))
 *
 * Example (not executable, for illustration): 
 * Imagine secret 'JBSWY3DPEHPK3PXP'
 * Time counter for a 30-sec step at 1678886400 (March 15, 2023 12:00:00 PM UTC) is 1678886400 / 30 = 55962880.
 * The OTP is generated based on this secret and counter.
 */

<?php
// Step 1: Install the library via Composer.
// Execute in your project root: composer require spomky-labs/otphp

require 'vendor/autoload.php';

use OTPHP\TOTP;

/**
 * Step 2: Generate a new TOTP secret for a user.
 * This secret must be securely stored in your database, associated with the user.
 * DO NOT store it in plaintext. Encrypt it using a strong encryption key.
 */
function generateTotpSecret(): string
{
    // Generate a secure, base32 encoded secret key.
    // Length is typically 16 characters (10 bytes), which gives ~80 bits of security.
    // spomky-labs/otphp handles base32 encoding automatically.
    $totp = TOTP::create();
    return $totp->getSecret();
}

/**
 * Step 3: Generate the provisioning URI (for QR code).
 * This URI will be encoded into a QR code for the user to scan with their authenticator app.
 */
function getProvisioningUri(string $secret, string $username, string $issuer): string
{
    $totp = TOTP::create($secret);
    $totp->setLabel($username);
    $totp->setIssuer($issuer);
    
    // You can customize algorithm (SHA1, SHA256, SHA512), digits (6 or 8), period (30 or 60).
    // $totp->setDigest('sha256');
    // $totp->setDigits(8);
    // $totp->setPeriod(60);

    return $totp->getProvisioningUri();
}

// --- Example Usage ---
$username = 'john.doe@example.com';
$issuer = 'YourAppCorp';

// 1. Generate secret (occurs once during 2FA setup)
$userSecret = generateTotpSecret();
echo "Generated Secret: " . $userSecret . "\n";

// In a real application, persist $userSecret to the database securely.
// e.g., saveUserSecret($userId, encrypt($userSecret, $appEncryptionKey));

// 2. Get provisioning URI for QR code display
$provisioningUri = getProvisioningUri($userSecret, $username, $issuer);
echo "Provisioning URI: " . $provisioningUri . "\n";

// You would then use a QR code library (e.g., chillerlan/php-qrcode) 
// or a service (e.g., Google Charts API) to render this URI as an image.
// For example, Google Charts (no longer actively maintained, prefer local library):
// $qrCodeUrl = 'https://chart.googleapis.com/chart?chs=200x200&chld=M|0&cht=qr&chl=' . urlencode($provisioningUri);
// echo "QR Code URL (Google Charts - deprecated): " . $qrCodeUrl . "\n";

// Recommended: Use a PHP QR code library to generate images locally.
// Example with chillerlan/php-qrcode (install: composer require chillerlan/php-qrcode)
/*
use chillerlan\QRCode\QRCode;
use chillerlan\QRCode\QROptions;

$options = new QROptions([
    'outputType' => QRCode::OUTPUT_IMAGE_PNG,
    'eccLevel' => QRCode::ECC_L_MASK,
]);
$qrcode = (new QRCode($options))->render($provisioningUri);
// Store or display $qrcode (raw PNG data) to the user.
// header('Content-type: image/png');
// echo $qrcode;
*/
?>

<?php
require 'vendor/autoload.php';

use OTPHP\TOTP;

// Assume these are retrieved from a secure user session or database query.
// In a real application, ensure the secret is decrypted upon retrieval.
$userId = 123;
$username = 'john.doe@example.com';
$issuer = 'YourAppCorp';
$userSecret = 'JBSWY3DPEHPK3PXP'; // Example secret (should be stored securely and decrypted)

/**
 * Function to simulate saving the secret to a user's profile.
 * In production, you would encrypt this secret before storing.
 */
function saveUserTotpSecret(int $userId, string $secret): bool
{
    // Example: Update user_settings table for $userId
    // UPDATE user_settings SET totp_secret = ENCRYPT('$secret', 'your_app_key') WHERE user_id = $userId;
    echo "Simulating saving secret for user {$userId}: {$secret}\n";
    return true;
}

/**
 * Function to simulate retrieving the secret for a user.
 * In production, you would decrypt this secret after retrieval.
 */
function getUserTotpSecret(int $userId): ?string
{
    // Example: SELECT DECRYPT(totp_secret, 'your_app_key') FROM user_settings WHERE user_id = $userId;
    // For this example, we return the hardcoded secret.
    global $userSecret;
    return $userSecret;
}

/**
 * Step 1 (Registration): Generate Secret and Provisioning URI for a new 2FA setup.
 * This typically happens on a dedicated 'Enable 2FA' page.
 */
function handle2FARegistration(string $username, string $issuer):
    array // Returns ['secret' => string, 'provisioningUri' => string]
{
    $totp = TOTP::create(); // Generates a new random secret
    $secret = $totp->getSecret();
    
    $totp->setLabel($username);
    $totp->setIssuer($issuer);
    $provisioningUri = $totp->getProvisioningUri();
    
    // In a real app, save this $secret to the user's record (encrypted).
    // saveUserTotpSecret($userId, $secret);

    return [
        'secret' => $secret,
        'provisioningUri' => $provisioningUri
    ];
}

/**
 * Step 2 (Verification): Verify an OTP provided by the user.
 * This happens after password verification on the login flow, or during 2FA setup confirmation.
 */
function verifyTotpCode(string $userProvidedOtp, string $storedSecret): bool
{
    // Set accepted time drift in seconds. A common value is 1 (30 seconds before or after).
    // This accounts for slight clock differences between server and client.
    $acceptedDrift = 1;
    
    // Create TOTP object from the stored secret
    $totp = TOTP::create($storedSecret);

    // Verify the code
    // The verify() method takes the user's OTP and optionally the accepted time drift.
    return $totp->verify($userProvidedOtp, $acceptedDrift);
}

// --- Example Scenario --- 
echo "--- 2FA Registration Flow ---\n";
$registrationData = handle2FARegistration($username, $issuer);
$newSecret = $registrationData['secret'];
$newProvisioningUri = $registrationData['provisioningUri'];

echo "New Secret for Registration: " . $newSecret . "\n";
echo "New Provisioning URI: " . $newProvisioningUri . "\n";

// Simulate saving this new secret to the user's account for subsequent verifications.
saveUserTotpSecret($userId, $newSecret);

echo "\n--- 2FA Verification Flow ---\n";
// After user enters password, prompt for OTP.
$otpCodeFromUser = '123456'; // User inputs this code from their authenticator app

// In a real scenario, retrieve the stored secret for the current user.
$retrievedSecret = getUserTotpSecret($userId);

if ($retrievedSecret) {
    if (verifyTotpCode($otpCodeFromUser, $retrievedSecret)) {
        echo "OTP Verified Successfully! User logged in.\n";
    } else {
        echo "OTP Verification Failed! Invalid code or time drift.\n";
    }
} else {
    echo "Error: 2FA not set up for this user or secret not found.\n";
}

// --- How to test the verification (requires a real TOTP app) ---
// 1. Take the '$newProvisioningUri' from the registration output.
// 2. Generate a QR code from it (e.g., using a QR code generator website if not using a local library).
// 3. Scan the QR code with Google Authenticator/Authy.
// 4. Enter the current OTP shown in the app into '$otpCodeFromUser' above and re-run.
// This will demonstrate successful verification.

?>

<?php
require 'vendor/autoload.php';

use OTPHP\TOTP;

// Assume these are available (e.g., from user session or database)
$userId = 123;
$userSecret = 'JBSWY3DPEHPK3PXP'; // Decrypted secret from database

/**
 * Recovery Code Generation and Management.
 * These codes allow users to regain access if they lose their 2FA device.
 * Each code should be single-use and immediately invalidated upon use.
 */
function generateRecoveryCodes(int $userId, int $count = 10): array
{
    $codes = [];
    for ($i = 0; $i < $count; $i++) {
        $code = bin2hex(random_bytes(16)); // Generate 32-char hex string
        $codes[] = $code;
        // In a real application, securely hash and store these codes in the database
        // hashRecoveryCodeAndStore($userId, password_hash($code, PASSWORD_DEFAULT));
    }
    return $codes;
}

/**
 * Verify a recovery code.
 * Each code should be consumed (marked as used) after a single successful verification.
 */
function verifyAndConsumeRecoveryCode(int $userId, string $providedCode): bool
{
    // In a real application, retrieve stored hashed recovery codes for $userId
    // $hashedCodes = getStoredHashedRecoveryCodes($userId);
    // For this example, let's simulate with a generated set and a simple check.
    $generatedCodes = generateRecoveryCodes($userId, 3); // Simulate initial generation

    foreach ($generatedCodes as $code) {
        // In real app: if (password_verify($providedCode, $hashedCodeFromDB) && isCodeNotUsed($codeId)) {
        if ($providedCode === $code) { // Simplified for example, use password_verify in production!
            // Mark code as used in DB to prevent reuse
            echo "Recovery code '{$providedCode}' consumed for user {$userId}.\n";
            return true;
        }
    }
    return false;
}

/**
 * Basic Rate Limiting for OTP Verification attempts.
 * Prevents brute-forcing of 2FA codes.
 */
function isOtpRateLimited(int $userId, int $maxAttempts = 3, int $lockoutTimeMinutes = 5): bool
{
    // In a real application, use a persistent storage (database, Redis) to track attempts.
    // Example using a session (not persistent enough for production, for illustration).
    session_start();
    $key = 'otp_attempts_' . $userId;
    $lockoutKey = 'otp_lockout_' . $userId;

    if (isset($_SESSION[$lockoutKey]) && $_SESSION[$lockoutKey] > time()) {
        echo "User {$userId} is currently locked out for OTP attempts.\n";
        return true; // Still locked out
    }

    $_SESSION[$key] = ($_SESSION[$key] ?? 0) + 1;

    if ($_SESSION[$key] > $maxAttempts) {
        $_SESSION[$lockoutKey] = time() + ($lockoutTimeMinutes * 60);
        unset($_SESSION[$key]); // Reset attempts after lockout
        echo "User {$userId} exceeded OTP attempts. Locked out for {$lockoutTimeMinutes} minutes.\n";
        return true;
    }
    return false;
}

// --- Example Usage ---
echo "--- Recovery Code Generation ---\n";
$recoveryCodes = generateRecoveryCodes($userId);
echo "Generated Recovery Codes: " . implode(', ', $recoveryCodes) . "\n";
// Present these to the user, instructing them to store securely.

echo "\n--- Recovery Code Verification ---\n";
$lostDevice = true; // Simulate user losing their device
$providedRecoveryCode = $recoveryCodes[0]; // User enters one of their codes

if ($lostDevice) {
    if (verifyAndConsumeRecoveryCode($userId, $providedRecoveryCode)) {
        echo "User {$userId} successfully recovered via code. Prompt for new 2FA setup or temporary access.\n";
    } else {
        echo "Invalid recovery code provided.\n";
    }
}

echo "\n--- OTP Rate Limiting Simulation ---\n";
// Simulate multiple failed OTP attempts
for ($i = 1; $i <= 5; $i++) {
    echo "Attempt {$i}: ";
    if (isOtpRateLimited($userId)) {
        echo "OTP attempt blocked.\n";
        break; // Stop simulating if locked out
    } else {
        echo "OTP attempt allowed.\n";
        // In a real scenario, proceed with TOTP verification here
    }
}

// Reset session for clean re-run of script for testing rate limiting
// unset($_SESSION['otp_attempts_' . $userId]);
// unset($_SESSION['otp_lockout_' . $userId]);

?>