server/core/lib/Security/Authentication/AuthenticationRequest.php

<?php

declare(strict_types=1);

namespace KTXC\Security\Authentication;

/**
 * Authentication Request
 * 
 * Request DTO from controller to AuthenticationManager.
 * Encapsulates all input data for authentication operations.
 */
readonly class AuthenticationRequest
{
    // Action types
    public const ACTION_START = 'start';
    public const ACTION_IDENTIFY = 'identify';
    public const ACTION_VERIFY = 'verify';
    public const ACTION_CHALLENGE = 'challenge';
    public const ACTION_REDIRECT = 'redirect';
    public const ACTION_CALLBACK = 'callback';
    public const ACTION_STATUS = 'status';
    public const ACTION_CANCEL = 'cancel';
    public const ACTION_REFRESH = 'refresh';
    public const ACTION_LOGOUT = 'logout';

    public function __construct(
        /** Action to perform */
        public string $action,
        
        /** Session ID (for ongoing auth flows) */
        public ?string $sessionId = null,
        
        /** User identity (email/username) */
        public ?string $identity = null,
        
        /** Authentication method/provider ID */
        public ?string $method = null,
        
        /** Secret/code/password */
        public ?string $secret = null,
        
        /** Callback URL for redirect flows */
        public ?string $callbackUrl = null,
        
        /** Return URL after authentication */
        public ?string $returnUrl = null,
        
        /** Additional parameters (OIDC callback params, etc.) */
        public array $params = [],
        
        /** Token for refresh/logout operations */
        public ?string $token = null,
    ) {}

    // =========================================================================
    // Factory Methods
    // =========================================================================

    /**
     * Create a start request
     */
    public static function start(): self
    {
        return new self(action: self::ACTION_START);
    }

    /**
     * Create an identify request
     */
    public static function identify(string $sessionId, string $identity): self
    {
        return new self(
            action: self::ACTION_IDENTIFY,
            sessionId: $sessionId,
            identity: $identity,
        );
    }

    /**
     * Create a verify request (password, TOTP code, etc.)
     */
    public static function verify(string $sessionId, string $method, string $secret): self
    {
        return new self(
            action: self::ACTION_VERIFY,
            sessionId: $sessionId,
            method: $method,
            secret: $secret,
        );
    }

    /**
     * Create a begin challenge request
     */
    public static function challenge(string $sessionId, string $method): self
    {
        return new self(
            action: self::ACTION_CHALLENGE,
            sessionId: $sessionId,
            method: $method,
        );
    }

    /**
     * Create a begin redirect request
     */
    public static function redirect(
        string $sessionId,
        string $method,
        string $callbackUrl,
        ?string $returnUrl = null
    ): self {
        return new self(
            action: self::ACTION_REDIRECT,
            sessionId: $sessionId,
            method: $method,
            callbackUrl: $callbackUrl,
            returnUrl: $returnUrl,
        );
    }

    /**
     * Create a callback request (OIDC/SAML return)
     */
    public static function callback(string $sessionId, string $method, array $params): self
    {
        return new self(
            action: self::ACTION_CALLBACK,
            sessionId: $sessionId,
            method: $method,
            params: $params,
        );
    }

    /**
     * Create a status request
     */
    public static function status(string $sessionId): self
    {
        return new self(
            action: self::ACTION_STATUS,
            sessionId: $sessionId,
        );
    }

    /**
     * Create a cancel request
     */
    public static function cancel(string $sessionId): self
    {
        return new self(
            action: self::ACTION_CANCEL,
            sessionId: $sessionId,
        );
    }

    /**
     * Create a refresh token request
     */
    public static function refresh(string $token): self
    {
        return new self(
            action: self::ACTION_REFRESH,
            token: $token,
        );
    }

    /**
     * Create a logout request
     */
    public static function logout(?string $token = null, bool $allDevices = false): self
    {
        return new self(
            action: self::ACTION_LOGOUT,
            token: $token,
            params: ['all_devices' => $allDevices],
        );
    }
}