registry = $registry; $this->policy = $policy; } /** * Returns the tokens that may safely be used in an HTTP-level block. * * @return string[] Safe user-agent tokens. */ public function get_enforceable_tokens(): array { $tokens = array(); foreach ( $this->policy->agents_to_enforce() as $agent ) { if ( $this->is_safe_token( $agent['ua'] ) ) { $tokens[] = $agent['ua']; } } return array_values( array_unique( $tokens ) ); } /** * Returns tokens that were rejected, with the reason for each. * * @return array List of arrays with 'token', 'reason' and 'detail' keys. */ public function get_rejected_tokens(): array { $rejected = array(); foreach ( $this->policy->agents_to_enforce() as $agent ) { $rejection = $this->get_rejection( $agent['ua'] ); if ( null !== $rejection ) { $rejected[] = array_merge( array( 'token' => $agent['ua'] ), $rejection ); } } return $rejected; } /** * Whether a token can safely be used in an HTTP-level rule. * * @param string $token Candidate user-agent token. * @return bool True when safe to use. */ public function is_safe_token( string $token ): bool { return null === $this->get_rejection( $token ); } /** * Returns why a token may not be used, or null when it is safe. * * @param string $token Candidate user-agent token. * @return array|null Array with 'reason' and 'detail', or null when safe. */ public function get_rejection( string $token ): ?array { $token = trim( $token ); if ( strlen( $token ) < self::MIN_TOKEN_LENGTH ) { return array( 'reason' => 'too_short', 'detail' => __( 'The token is too short to identify a crawler reliably and would match ordinary visitors.', 'ai-blackout' ), ); } $lower = strtolower( $token ); foreach ( self::GENERIC_TOKENS as $generic ) { if ( $lower === $generic || false !== strpos( $generic, $lower ) ) { return array( 'reason' => 'too_generic', 'detail' => __( 'The token appears in ordinary browser user agents and would block real visitors.', 'ai-blackout' ), ); } } $collision = $this->find_collision( $token ); if ( null !== $collision ) { return array( 'reason' => 'protected_collision', 'detail' => sprintf( /* translators: %s: Name of a protected crawler, e.g. Googlebot. */ __( 'A rule for this token would also match %s, which this plugin never blocks.', 'ai-blackout' ), $collision ), ); } return null; } /** * Returns the protected agent a token would wrongly match, if any. * * @param string $token Candidate user-agent token. * @return string|null Protected agent name, or null when there is no collision. */ public function find_collision( string $token ): ?string { $token = trim( $token ); if ( '' === $token ) { return null; } foreach ( $this->registry->get_protected_agents() as $protected ) { if ( 0 === strcasecmp( $protected, $token ) ) { return $protected; } if ( false !== stripos( $protected, $token ) ) { return $protected; } } return null; } /** * Matches a user-agent string against the enforceable tokens. * * @param string $user_agent Raw User-Agent header value. * @return string|null The token that matched, or null when nothing matched. */ public function match_agent( string $user_agent ): ?string { $user_agent = trim( $user_agent ); if ( '' === $user_agent ) { return null; } // A protected agent is never blocked, whatever else is configured. foreach ( $this->registry->get_protected_agents() as $protected ) { if ( false !== stripos( $user_agent, $protected ) ) { return null; } } foreach ( $this->get_enforceable_tokens() as $token ) { if ( false !== stripos( $user_agent, $token ) ) { return $token; } } return null; } }