<?php
/**
 * THE scope check (PLAN.md §5.4 rule 1). Every channel — REST, MCP, the
 * operations endpoint, Company Agent tools, the web guard — asks this one
 * function whether a context may use a capability. An unknown capability is
 * refused: an unimplemented check must fail CLOSED (FACTORY.md §9.4).
 *
 * @package AgentAdapt
 */

defined( 'ABSPATH' ) || exit;

/**
 * Access gate.
 */
final class AgentAdapt_Gate {

	/**
	 * May this context use this capability?
	 *
	 * @param AgentAdapt_Context $context       Who is asking.
	 * @param string            $capability_id Registered capability id.
	 * @return true|WP_Error sign_in_required / insufficient_scope (403), or unknown_capability.
	 */
	public static function check( AgentAdapt_Context $context, string $capability_id ) {
		$cap = AgentAdapt_Capabilities::get( $capability_id );
		if ( null === $cap ) {
			return new WP_Error( 'insufficient_scope', 'unknown capability', array( 'status' => 403 ) );
		}
		$needed = (array) $cap['scopes'];
		// An empty list is a guest capability: what a signed-out visitor could do.
		if ( $needed ) {
			if ( ! $context->signed_in() ) {
				return new WP_Error( 'sign_in_required', 'this needs a signed-in Session', array( 'status' => 403 ) );
			}
			$missing = array_values( array_filter( $needed, static fn( $s ) => ! $context->has_scope( $s ) ) );
			if ( $missing ) {
				return new WP_Error( 'insufficient_scope', 'this needs more account access', array( 'status' => 403, 'scope' => implode( ' ', $needed ) ) );
			}
		}
		/**
		 * Refuse a request the checks above allowed (merchant policy). The
		 * filter runs only AFTER the scope checks pass and only a WP_Error
		 * changes the answer, so nothing hooked here can widen access.
		 *
		 * @param true                $allowed True.
		 * @param AgentAdapt_Context  $context Who is asking.
		 * @param array<string,mixed> $cap     The capability.
		 */
		$verdict = apply_filters( 'agentadapt_gate_restrict', true, $context, $cap );
		return is_wp_error( $verdict ) ? $verdict : true;
	}
}