<?php
/**
 * The authenticated principal behind an MCP request.
 *
 * @package HandyMCP
 */

namespace HandyMCP\Auth;

defined( 'ABSPATH' ) || exit;

/**
 * Immutable identity value object.
 */
final class Identity {

	/** @var int */
	public $user_id;

	/** @var string pat | oauth | app_password | admin_console | system */
	public $method;

	/** @var int */
	public $token_id;

	/** @var string[] */
	public $scopes;

	/** @var string */
	public $client;

	/**
	 * Constructor.
	 *
	 * @param int      $user_id  WP user id.
	 * @param string   $method   Auth method.
	 * @param int      $token_id Token id (0 when not token based).
	 * @param string[] $scopes   Granted scopes.
	 * @param string   $client   Client label.
	 */
	public function __construct( int $user_id, string $method, int $token_id, array $scopes, string $client = '' ) {
		$this->user_id  = $user_id;
		$this->method   = $method;
		$this->token_id = $token_id;
		$this->scopes   = $scopes;
		$this->client   = $client;
	}

	/**
	 * Scope check.
	 *
	 * @param string $scope Scope.
	 */
	public function has_scope( string $scope ): bool {
		return in_array( $scope, $this->scopes, true );
	}

	/**
	 * Stable non-secret label for logs, e.g. "pat#12" or "app_password#1".
	 */
	public function label(): string {
		return $this->method . '#' . ( $this->token_id ? $this->token_id : $this->user_id );
	}

	/**
	 * Rate-limit key.
	 */
	public function rate_key(): string {
		return $this->method . ':' . $this->token_id . ':' . $this->user_id;
	}
}