<?php
/**
 * Two-Factor Authentication Provider Interface
 *
 * Defines the contract that all two-factor authentication providers must implement.
 * This interface ensures consistent behavior across different 2FA methods such as
 * TOTP (Time-based One-Time Password), Email, SMS, and WebAuthn providers.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       1.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Interface TwoFactorProviderInterface
 *
 * All two-factor authentication providers must implement this interface to ensure
 * they can be used interchangeably within the authentication system. This provides
 * a unified API for enabling, disabling, and verifying 2FA for users.
 *
 * Example implementation:
 * ```php
 * class EmailProvider implements TwoFactorProviderInterface {
 *     public function getProviderName(): string {
 *         return 'Email Authentication';
 *     }
 *     // ... other method implementations
 * }
 * ```
 *
 * @since 1.0.0
 */
interface TwoFactorProviderInterface
{
    /**
     * Check if this 2FA provider is enabled for a specific user.
     *
     * This method determines whether the user has completed the setup process
     * for this particular 2FA method and has it currently active.
     *
     * @since 1.0.0
     *
     * @param int $userId The WordPress user ID to check.
     *
     * @return bool True if the provider is enabled for the user, false otherwise.
     */
    public function isEnabledForUser(int $userId): bool;

    /**
     * Enable this 2FA provider for a specific user.
     *
     * This method activates the 2FA provider for the given user. Depending on
     * the provider type, this may involve storing secrets, generating backup
     * codes, or registering devices.
     *
     * @since 1.0.0
     *
     * @param int $userId The WordPress user ID to enable 2FA for.
     *
     * @return bool True if successfully enabled, false on failure.
     */
    public function enableForUser(int $userId): bool;

    /**
     * Disable this 2FA provider for a specific user.
     *
     * This method deactivates the 2FA provider for the given user and should
     * clean up any stored secrets or associated data. Use with caution as this
     * reduces the user's account security.
     *
     * @since 1.0.0
     *
     * @param int $userId The WordPress user ID to disable 2FA for.
     *
     * @return bool True if successfully disabled, false on failure.
     */
    public function disableForUser(int $userId): bool;

    /**
     * Send a verification code to the user.
     *
     * For providers that require sending codes (e.g., Email, SMS), this method
     * generates and sends the code to the user. For app-based providers (TOTP),
     * this may be a no-op that returns true, as codes are generated on the device.
     *
     * @since 1.0.0
     *
     * @param int $userId The WordPress user ID to send the code to.
     *
     * @return bool True if the code was sent successfully or not required, false on failure.
     */
    public function sendCode(int $userId): bool;

    /**
     * Verify a submitted authentication code.
     *
     * Validates the code provided by the user against the expected value.
     * Implementations should handle timing-safe comparisons and rate limiting
     * to prevent brute-force attacks.
     *
     * @since 1.0.0
     *
     * @param int    $userId The WordPress user ID attempting verification.
     * @param string $code   The verification code submitted by the user.
     *
     * @return bool True if the code is valid, false otherwise.
     */
    public function verifyCode(int $userId, string $code): bool;

    /**
     * Get the human-readable name of this provider.
     *
     * Returns a user-friendly name for display in the UI, such as
     * "Email Authentication" or "Authenticator App".
     *
     * @since 1.0.0
     *
     * @return string The localized display name of the provider.
     */
    public function getProviderName(): string;

    /**
     * Get the unique slug identifier for this provider.
     *
     * Returns a machine-readable identifier used for internal references,
     * settings storage, and URL parameters. Should be lowercase alphanumeric
     * with hyphens (e.g., "email", "totp", "webauthn").
     *
     * @since 1.0.0
     *
     * @return string The unique slug for this provider.
     */
    public function getProviderSlug(): string;

    /**
     * Get the settings key used to store provider options.
     *
     * Returns the key used in the plugin's settings array to store
     * configuration options for this provider (e.g., "2fa_email", "2fa_totp").
     *
     * @since 1.0.0
     *
     * @return string The settings array key for this provider.
     */
    public function getSettingsKey(): string;
}
