<?php
/**
 * Authenticator Interface
 * Defines the contract for all authentication methods in WP OAuth Server CE
 *
 * @package WPOAuth2Server
 * @subpackage Auth
 * @version 1.0.0
 */

namespace WPOAuth2Server\Auth;

defined('ABSPATH') or die('Direct access forbidden.');

interface AuthenticatorInterface {
    
    /**
     * Get the unique name/identifier for this authenticator
     * Used for logging, configuration, and registration
     */
    public function get_name(): string;
    
    /**
     * Get human-readable display name for admin interface
     */
    public function get_display_name(): string;
    
    /**
     * Get description of this authentication method
     */
    public function get_description(): string;
    
    /**
     * Check if this authenticator can handle the current request
     * This allows multiple authenticators to coexist and only activate when appropriate
     */
    public function can_authenticate(): bool;
    
    /**
     * Perform authentication and return WordPress user ID
     * 
     * @return int|null WordPress user ID if authentication successful, null if failed
     * @throws \Exception If authentication fails with specific error
     */
    public function authenticate(): ?int;
    
    /**
     * Validate the authentication credentials without actually authenticating
     * Useful for token validation, API key verification, etc.
     */
    public function validate_credentials(): bool;
    
    /**
     * Get authentication priority (lower = higher priority)
     * Allows controlling the order in which authenticators are tried
     */
    public function get_priority(): int;
    
    /**
     * Check if this authenticator requires HTTPS
     */
    public function requires_https(): bool;
    
    /**
     * Get allowed HTTP methods for this authenticator
     * @return array Array of allowed methods (e.g., ['GET', 'POST'])
     */
    public function get_allowed_methods(): array;
    
    /**
     * Get any additional headers this authenticator needs to set
     * @return array Associative array of header_name => header_value
     */
    public function get_response_headers(): array;
}