<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Security;

use App\Framework\LiveComponents\Attributes\RequiresPermission;
use App\Framework\LiveComponents\Contracts\LiveComponentContract;

/**
 * Authorization checker interface for LiveComponent actions
 *
 * Provides flexible authorization checking that can be implemented
 * with different authorization backends:
 * - Session-based user permissions
 * - JWT token permissions
 * - Database role checks
 * - Custom authorization logic
 *
 * Framework Integration:
 * - LiveComponentHandler checks authorization before executing actions
 * - Throws UnauthorizedActionException if check fails
 * - Can be swapped via DI for different authorization strategies
 */
interface ActionAuthorizationChecker
{
    /**
     * Check if action is authorized
     *
     * @param LiveComponentContract $component Component instance
     * @param string $method Action method name
     * @param RequiresPermission|null $permissionAttribute Permission attribute (if present)
     * @return bool True if authorized, false otherwise
     */
    public function isAuthorized(
        LiveComponentContract $component,
        string $method,
        ?RequiresPermission $permissionAttribute
    ): bool;

    /**
     * Get current user's permissions (for logging/debugging)
     *
     * @return array<string> User's permissions
     */
    public function getUserPermissions(): array;

    /**
     * Check if user has specific permission
     */
    public function hasPermission(string $permission): bool;

    /**
     * Check if user is authenticated
     */
    public function isAuthenticated(): bool;
}
