<?php

declare(strict_types=1);

namespace KTXF\Security\Authentication;

/**
 * Provider Context
 * 
 * Immutable context passed to authentication providers.
 * Contains all information a provider needs to perform authentication.
 */
readonly class ProviderContext
{
    public function __construct(
        /** Tenant identifier */
        public string $tenantId,
        
        /** User's internal identifier (after lookup) */
        public ?string $userIdentifier = null,
        
        /** User's identity input (email/username) */
        public ?string $userIdentity = null,
        
        /** Provider-specific metadata from session */
        public array $metadata = [],
        
        /** Provider configuration */
        public array $config = [],
    ) {}

    /**
     * Get metadata value
     */
    public function getMeta(string $key, mixed $default = null): mixed
    {
        return $this->metadata[$key] ?? $default;
    }

    /**
     * Get config value
     */
    public function getConfig(string $key, mixed $default = null): mixed
    {
        return $this->config[$key] ?? $default;
    }

    /**
     * Create context with updated metadata
     */
    public function withMetadata(array $metadata): self
    {
        return new self(
            tenantId: $this->tenantId,
            userIdentifier: $this->userIdentifier,
            userIdentity: $this->userIdentity,
            metadata: $metadata,
            config: $this->config,
        );
    }

    /**
     * Create context with user identifier set
     */
    public function withUserIdentifier(string $userIdentifier): self
    {
        return new self(
            tenantId: $this->tenantId,
            userIdentifier: $userIdentifier,
            userIdentity: $this->userIdentity,
            metadata: $this->metadata,
            config: $this->config,
        );
    }
}