<?php
/**
 * Token-scope gate.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Policy;

use AgentFirewall\Model\Agent;

defined( 'ABSPATH' ) || exit;

/**
 * Whether an action falls inside an agent's declared token scopes
 * (PRD STORY-9.1, MCP02).
 *
 * This runs before policy in the live pipeline, so the dry-run has to apply it
 * too: a simulation that skipped it would report ALLOW for an action the real
 * request denies as out_of_scope, which is exactly the kind of wrong answer a
 * dry-run exists to prevent.
 */
final class ScopeGate {

	/**
	 * A scope entry is either an action category (create|update|delete|read)
	 * or an ability pattern with optional trailing wildcard. Any match wins;
	 * an empty scope list means unrestricted.
	 *
	 * @param Agent            $agent  Acting agent.
	 * @param ActionDescriptor $action Normalized action.
	 */
	public static function permits( Agent $agent, ActionDescriptor $action ): bool {
		if ( array() === $agent->scopes ) {
			return true;
		}

		foreach ( $agent->scopes as $scope ) {
			if ( $scope === $action->action_cat ) {
				return true;
			}

			if ( null === $action->ability_name ) {
				continue;
			}

			if ( str_ends_with( $scope, '*' ) ) {
				if ( str_starts_with( $action->ability_name, substr( $scope, 0, -1 ) ) ) {
					return true;
				}
			} elseif ( $scope === $action->ability_name ) {
				return true;
			}
		}

		return false;
	}
}