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

<?php

declare(strict_types=1);

namespace KTXC\Security\Authentication;

/**
 * Authentication Response
 * 
 * Response DTO from AuthenticationManager to controller.
 * Contains all data needed to build the HTTP response.
 */
readonly class AuthenticationResponse
{
    // Status constants
    public const STATUS_SUCCESS = 'success';
    public const STATUS_PENDING = 'pending';
    public const STATUS_CHALLENGE = 'challenge';
    public const STATUS_REDIRECT = 'redirect';
    public const STATUS_FAILED = 'failed';
    public const STATUS_CANCELLED = 'cancelled';

    // Error codes
    public const ERROR_INVALID_REQUEST = 'invalid_request';
    public const ERROR_INVALID_CREDENTIALS = 'invalid_credentials';
    public const ERROR_INVALID_PROVIDER = 'invalid_provider';
    public const ERROR_INVALID_SESSION = 'invalid_session';
    public const ERROR_SESSION_EXPIRED = 'session_expired';
    public const ERROR_USER_NOT_FOUND = 'user_not_found';
    public const ERROR_USER_DISABLED = 'user_disabled';
    public const ERROR_ACCOUNT_LOCKED = 'account_locked';
    public const ERROR_RATE_LIMITED = 'rate_limited';
    public const ERROR_INTERNAL = 'internal_error';

    public function __construct(
        /** Response status */
        public string $status,
        
        /** Suggested HTTP status code */
        public int $httpStatus = 200,
        
        /** Session ID (for ongoing flows) */
        public ?string $sessionId = null,
        
        /** Current session state */
        public ?string $sessionState = null,
        
        /** Serialized user data (on success) */
        public ?array $user = null,
        
        /** Auth tokens (on success) */
        public ?array $tokens = null,
        
        /** Available authentication methods */
        public ?array $methods = null,
        
        /** Challenge information */
        public ?array $challenge = null,
        
        /** Redirect URL (for OIDC/SAML) */
        public ?string $redirectUrl = null,
        
        /** Return URL (after redirect auth) */
        public ?string $returnUrl = null,
        
        /** Error code */
        public ?string $errorCode = null,
        
        /** Error message */
        public ?string $errorMessage = null,
    ) {}

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

    /**
     * Session started response
     */
    public static function started(string $sessionId, array $methods): self
    {
        return new self(
            status: self::STATUS_SUCCESS,
            sessionId: $sessionId,
            methods: $methods,
        );
    }

    /**
     * User identified response
     */
    public static function identified(string $sessionId, string $state, array $methods): self
    {
        return new self(
            status: self::STATUS_SUCCESS,
            sessionId: $sessionId,
            sessionState: $state,
            methods: $methods,
        );
    }

    /**
     * Authentication successful
     */
    public static function success(array $user, array $tokens): self
    {
        return new self(
            status: self::STATUS_SUCCESS,
            user: $user,
            tokens: $tokens,
        );
    }

    /**
     * MFA/additional factor required
     */
    public static function pending(string $sessionId, array $methods): self
    {
        return new self(
            status: self::STATUS_PENDING,
            sessionId: $sessionId,
            methods: $methods,
        );
    }

    /**
     * Challenge sent (SMS, email, etc.)
     */
    public static function challenge(string $sessionId, array $challengeInfo): self
    {
        return new self(
            status: self::STATUS_CHALLENGE,
            sessionId: $sessionId,
            challenge: $challengeInfo,
        );
    }

    /**
     * Redirect required (OIDC/SAML)
     */
    public static function redirect(string $sessionId, string $redirectUrl): self
    {
        return new self(
            status: self::STATUS_REDIRECT,
            sessionId: $sessionId,
            redirectUrl: $redirectUrl,
        );
    }

    /**
     * Authentication failed
     */
    public static function failed(
        string $errorCode,
        ?string $errorMessage = null,
        int $httpStatus = 401
    ): self {
        return new self(
            status: self::STATUS_FAILED,
            httpStatus: $httpStatus,
            errorCode: $errorCode,
            errorMessage: $errorMessage,
        );
    }

    /**
     * Session cancelled
     */
    public static function cancelled(): self
    {
        return new self(
            status: self::STATUS_CANCELLED,
        );
    }

    /**
     * Status check response
     */
    public static function status(
        string $sessionId,
        string $state,
        array $methods,
        ?string $identity = null
    ): self {
        return new self(
            status: self::STATUS_SUCCESS,
            sessionId: $sessionId,
            sessionState: $state,
            methods: $methods,
            user: $identity ? ['identity' => $identity] : null,
        );
    }

    // =========================================================================
    // Status Checks
    // =========================================================================

    public function isSuccess(): bool
    {
        return $this->status === self::STATUS_SUCCESS;
    }

    public function isPending(): bool
    {
        return $this->status === self::STATUS_PENDING;
    }

    public function isRedirect(): bool
    {
        return $this->status === self::STATUS_REDIRECT;
    }

    public function isFailed(): bool
    {
        return $this->status === self::STATUS_FAILED;
    }

    public function hasTokens(): bool
    {
        return $this->tokens !== null && !empty($this->tokens);
    }

    // =========================================================================
    // Serialization
    // =========================================================================

    /**
     * Convert to array for JSON response
     */
    public function toArray(): array
    {
        $result = ['status' => $this->status];

        if ($this->sessionId !== null) {
            $result['session'] = $this->sessionId;
        }

        if ($this->sessionState !== null) {
            $result['state'] = $this->sessionState;
        }

        if ($this->user !== null) {
            $result['user'] = $this->user;
        }

        if ($this->methods !== null) {
            $result['methods'] = $this->methods;
        }

        if ($this->challenge !== null) {
            $result['challenge'] = $this->challenge;
        }

        if ($this->redirectUrl !== null) {
            $result['redirect_url'] = $this->redirectUrl;
        }

        if ($this->returnUrl !== null) {
            $result['return_url'] = $this->returnUrl;
        }

        if ($this->errorCode !== null) {
            $result['error_code'] = $this->errorCode;
        }

        if ($this->errorMessage !== null) {
            $result['error'] = $this->errorMessage;
        }

        return $result;
    }
}