<?php

[0] Fix | Delete

/**

[1] Fix | Delete

* ApiClient class file.

[2] Fix | Delete

*/

[3] Fix | Delete

[4] Fix | Delete

declare( strict_types=1 );

[5] Fix | Delete

[6] Fix | Delete

namespace Automattic\WooCommerce\Internal\FraudProtection;

[7] Fix | Delete

[8] Fix | Delete

use Automattic\Jetpack\Connection\Client as Jetpack_Connection_Client;

[9] Fix | Delete

[10] Fix | Delete

defined( 'ABSPATH' ) || exit;

[11] Fix | Delete

[12] Fix | Delete

/**

[13] Fix | Delete

* Handles communication with the Blackbox fraud protection API.

[14] Fix | Delete

*

[15] Fix | Delete

* Uses Jetpack Connection for authenticated requests to the Blackbox API

[16] Fix | Delete

* to verify sessions and report fraud events. The API returns fraud protection

[17] Fix | Delete

* decisions (allow, block, or challenge).

[18] Fix | Delete

*

[19] Fix | Delete

* This class implements a fail-open pattern: if the endpoint is unreachable,

[20] Fix | Delete

* times out, or returns an error, it returns an "allow" decision to ensure

[21] Fix | Delete

* legitimate transactions are never blocked due to service issues.

[22] Fix | Delete

*

[23] Fix | Delete

* @since 10.5.0

[24] Fix | Delete

* @internal This class is part of the internal API and is subject to change without notice.

[25] Fix | Delete

*/

[26] Fix | Delete

class ApiClient {

[27] Fix | Delete

[28] Fix | Delete

/**

[29] Fix | Delete

* Default timeout for API requests in seconds.

[30] Fix | Delete

*

[31] Fix | Delete

* Using 10 seconds as a reasonable timeout for fraud verification during checkout.

[32] Fix | Delete

* This balances giving the API enough time to respond while not blocking

[33] Fix | Delete

* checkout for too long if the service is slow.

[34] Fix | Delete

*/

[35] Fix | Delete

private const DEFAULT_TIMEOUT = 10;

[36] Fix | Delete

[37] Fix | Delete

/**

[38] Fix | Delete

* Blackbox API base URL.

[39] Fix | Delete

*/

[40] Fix | Delete

private const BLACKBOX_API_BASE_URL = 'https://blackbox-api.wp.com/v1';

[41] Fix | Delete

[42] Fix | Delete

/**

[43] Fix | Delete

* Blackbox API verify endpoint path.

[44] Fix | Delete

*/

[45] Fix | Delete

private const VERIFY_ENDPOINT = '/verify';

[46] Fix | Delete

[47] Fix | Delete

/**

[48] Fix | Delete

* Blackbox API report endpoint path.

[49] Fix | Delete

*/

[50] Fix | Delete

private const REPORT_ENDPOINT = '/report';

[51] Fix | Delete

[52] Fix | Delete

/**

[53] Fix | Delete

* Decision type: allow session.

[54] Fix | Delete

*/

[55] Fix | Delete

public const DECISION_ALLOW = 'allow';

[56] Fix | Delete

[57] Fix | Delete

/**

[58] Fix | Delete

* Decision type: block session.

[59] Fix | Delete

*/

[60] Fix | Delete

public const DECISION_BLOCK = 'block';

[61] Fix | Delete

[62] Fix | Delete

/**

[63] Fix | Delete

* Decision type: challenge session.

[64] Fix | Delete

*/

[65] Fix | Delete

public const DECISION_CHALLENGE = 'challenge';

[66] Fix | Delete

[67] Fix | Delete

/**

[68] Fix | Delete

* Valid decision values that can be returned by the API.

[69] Fix | Delete

*

[70] Fix | Delete

* @var array<string>

[71] Fix | Delete

*/

[72] Fix | Delete

public const VALID_DECISIONS = array(

[73] Fix | Delete

self::DECISION_ALLOW,

[74] Fix | Delete

self::DECISION_BLOCK,

[75] Fix | Delete

);

[76] Fix | Delete

[77] Fix | Delete

/**

[78] Fix | Delete

* Verify a session with the Blackbox API and get a fraud decision.

[79] Fix | Delete

*

[80] Fix | Delete

* Implements fail-open pattern: if the endpoint is unreachable or times out,

[81] Fix | Delete

* returns "allow" decision and logs the error.

[82] Fix | Delete

*

[83] Fix | Delete

* @since 10.5.0

[84] Fix | Delete

*

[85] Fix | Delete

* @param string $session_id Session ID to verify.

[86] Fix | Delete

* @param array<string, mixed> $payload Event data to send to the endpoint.

[87] Fix | Delete

* @return string Decision: "allow" or "block".

[88] Fix | Delete

*/

[89] Fix | Delete

public function verify( string $session_id, array $payload ): string {

[90] Fix | Delete

FraudProtectionController::log(

[91] Fix | Delete

'info',

[92] Fix | Delete

'Verifying session with Blackbox API',

[93] Fix | Delete

array(

[94] Fix | Delete

'session_id' => $session_id,

[95] Fix | Delete

'payload' => $payload,

[96] Fix | Delete

)

[97] Fix | Delete

);

[98] Fix | Delete

[99] Fix | Delete

$response = $this->make_request( 'POST', self::VERIFY_ENDPOINT, $session_id, $payload );

[100] Fix | Delete

[101] Fix | Delete

return $this->process_decision_response( $response, $payload );

[102] Fix | Delete

}

[103] Fix | Delete

[104] Fix | Delete

/**

[105] Fix | Delete

* Report a fraud event to the Blackbox API.

[106] Fix | Delete

*

[107] Fix | Delete

* Used for reporting outcomes and feedback to improve fraud detection.

[108] Fix | Delete

* This is a fire-and-forget operation - errors are logged but do not

[109] Fix | Delete

* affect the checkout flow.

[110] Fix | Delete

*

[111] Fix | Delete

* @since 10.5.0

[112] Fix | Delete

*

[113] Fix | Delete

* @param string $session_id Session ID to report.

[114] Fix | Delete

* @param array<string, mixed> $payload Event data to send to the endpoint.

[115] Fix | Delete

* @return bool True if report was sent successfully, false otherwise.

[116] Fix | Delete

*/

[117] Fix | Delete

public function report( string $session_id, array $payload ): bool {

[118] Fix | Delete

FraudProtectionController::log(

[119] Fix | Delete

'info',

[120] Fix | Delete

'Reporting event to Blackbox API',

[121] Fix | Delete

array( 'payload' => $payload )

[122] Fix | Delete

);

[123] Fix | Delete

[124] Fix | Delete

$response = $this->make_request( 'POST', self::REPORT_ENDPOINT, $session_id, $payload );

[125] Fix | Delete

[126] Fix | Delete

if ( is_wp_error( $response ) ) {

[127] Fix | Delete

FraudProtectionController::log(

[128] Fix | Delete

'error',

[129] Fix | Delete

sprintf(

[130] Fix | Delete

'Failed to report event to Blackbox API: %s',

[131] Fix | Delete

$response->get_error_message()

[132] Fix | Delete

),

[133] Fix | Delete

array( 'error' => $response->get_error_data() )

[134] Fix | Delete

);

[135] Fix | Delete

return false;

[136] Fix | Delete

}

[137] Fix | Delete

[138] Fix | Delete

FraudProtectionController::log(

[139] Fix | Delete

'info',

[140] Fix | Delete

'Event reported successfully',

[141] Fix | Delete

array( 'response' => $response )

[142] Fix | Delete

);

[143] Fix | Delete

[144] Fix | Delete

return true;

[145] Fix | Delete

}

[146] Fix | Delete

[147] Fix | Delete

/**

[148] Fix | Delete

* Process the API response and extract the decision.

[149] Fix | Delete

*

[150] Fix | Delete

* @param array<string, mixed>|\WP_Error $response API response or WP_Error.

[151] Fix | Delete

* @param array<string, mixed> $event_data Event data for logging.

[152] Fix | Delete

* @return string Decision: "allow" or "block".

[153] Fix | Delete

*/

[154] Fix | Delete

private function process_decision_response( $response, array $event_data ): string {

[155] Fix | Delete

if ( is_wp_error( $response ) ) {

[156] Fix | Delete

$error_data = $response->get_error_data() ?? array();

[157] Fix | Delete

$error_data = is_array( $error_data ) ? $error_data : array( 'error' => $error_data );

[158] Fix | Delete

FraudProtectionController::log(

[159] Fix | Delete

'error',

[160] Fix | Delete

sprintf(

[161] Fix | Delete

'Blackbox API request failed: %s. Failing open with "allow" decision.',

[162] Fix | Delete

$response->get_error_message()

[163] Fix | Delete

),

[164] Fix | Delete

$error_data

[165] Fix | Delete

);

[166] Fix | Delete

return self::DECISION_ALLOW;

[167] Fix | Delete

}

[168] Fix | Delete

[169] Fix | Delete

if ( ! isset( $response['decision'] ) ) {

[170] Fix | Delete

FraudProtectionController::log(

[171] Fix | Delete

'error',

[172] Fix | Delete

'Response missing "decision" field. Failing open with "allow" decision.',

[173] Fix | Delete

array( 'response' => $response )

[174] Fix | Delete

);

[175] Fix | Delete

return self::DECISION_ALLOW;

[176] Fix | Delete

}

[177] Fix | Delete

[178] Fix | Delete

$decision = $response['decision'];

[179] Fix | Delete

[180] Fix | Delete

if ( ! in_array( $decision, self::VALID_DECISIONS, true ) ) {

[181] Fix | Delete

FraudProtectionController::log(

[182] Fix | Delete

'error',

[183] Fix | Delete

sprintf(

[184] Fix | Delete

'Invalid decision value "%s". Failing open with "allow" decision.',

[185] Fix | Delete

$decision

[186] Fix | Delete

),

[187] Fix | Delete

array( 'response' => $response )

[188] Fix | Delete

);

[189] Fix | Delete

return self::DECISION_ALLOW;

[190] Fix | Delete

}

[191] Fix | Delete

[192] Fix | Delete

$session = is_array( $event_data['session'] ?? null ) ? $event_data['session'] : array();

[193] Fix | Delete

$session_id = $session['session_id'] ?? 'unknown';

[194] Fix | Delete

$event_type = $event_data['event_type'] ?? 'unknown';

[195] Fix | Delete

FraudProtectionController::log(

[196] Fix | Delete

'info',

[197] Fix | Delete

sprintf(

[198] Fix | Delete

'Fraud decision received: %s | Event: %s | Session: %s',

[199] Fix | Delete

$decision,

[200] Fix | Delete

$event_type,

[201] Fix | Delete

$session_id

[202] Fix | Delete

),

[203] Fix | Delete

array( 'response' => $response )

[204] Fix | Delete

);

[205] Fix | Delete

[206] Fix | Delete

return $decision;

[207] Fix | Delete

}

[208] Fix | Delete

[209] Fix | Delete

/**

[210] Fix | Delete

* Make an HTTP request to the Blackbox API via Jetpack Connection.

[211] Fix | Delete

*

[212] Fix | Delete

* Uses Jetpack's signed request mechanism which authenticates with the

[213] Fix | Delete

* blog token scoped to the blog_id.

[214] Fix | Delete

*

[215] Fix | Delete

* @param string $method HTTP method (GET, POST, etc.).

[216] Fix | Delete

* @param string $path Endpoint path (relative to Blackbox API base URL).

[217] Fix | Delete

* @param string $session_id Session ID for the request.

[218] Fix | Delete

* @param array<string, mixed> $payload Request payload.

[219] Fix | Delete

* @return array<string, mixed>|\WP_Error Parsed JSON response or WP_Error on failure.

[220] Fix | Delete

*/

[221] Fix | Delete

private function make_request( string $method, string $path, string $session_id, array $payload ) {

[222] Fix | Delete

if ( ! class_exists( Jetpack_Connection_Client::class ) ) {

[223] Fix | Delete

return new \WP_Error(

[224] Fix | Delete

'jetpack_not_available',

[225] Fix | Delete

'Jetpack Connection is not available'

[226] Fix | Delete

);

[227] Fix | Delete

}

[228] Fix | Delete

[229] Fix | Delete

$blog_id = $this->get_blog_id();

[230] Fix | Delete

if ( ! $blog_id ) {

[231] Fix | Delete

return new \WP_Error(

[232] Fix | Delete

'no_blog_id',

[233] Fix | Delete

'Jetpack blog ID not found. Is the site connected to WordPress.com?'

[234] Fix | Delete

);

[235] Fix | Delete

}

[236] Fix | Delete

[237] Fix | Delete

$payload['blog_id'] = $blog_id;

[238] Fix | Delete

[239] Fix | Delete

$body = \wp_json_encode(

[240] Fix | Delete

array(

[241] Fix | Delete

'session_id' => $session_id,

[242] Fix | Delete

'private_key' => '', // Woo will not use private keys for now.

[243] Fix | Delete

'extra' => $payload,

[244] Fix | Delete

)

[245] Fix | Delete

);

[246] Fix | Delete

[247] Fix | Delete

if ( false === $body ) {

[248] Fix | Delete

return new \WP_Error(

[249] Fix | Delete

'json_encode_error',

[250] Fix | Delete

'Failed to encode payload',

[251] Fix | Delete

array( 'payload' => $payload )

[252] Fix | Delete

);

[253] Fix | Delete

}

[254] Fix | Delete

[255] Fix | Delete

$url = self::BLACKBOX_API_BASE_URL . $path;

[256] Fix | Delete

[257] Fix | Delete

// Use Jetpack Connection Client to make a signed request.

[258] Fix | Delete

// This authenticates with the blog token automatically.

[259] Fix | Delete

$response = Jetpack_Connection_Client::remote_request(

[260] Fix | Delete

array(

[261] Fix | Delete

'url' => $url,

[262] Fix | Delete

'method' => $method,

[263] Fix | Delete

'timeout' => self::DEFAULT_TIMEOUT,

[264] Fix | Delete

'headers' => array( 'Content-Type' => 'application/json' ),

[265] Fix | Delete

'auth_location' => 'header',

[266] Fix | Delete

),

[267] Fix | Delete

$body

[268] Fix | Delete

);

[269] Fix | Delete

[270] Fix | Delete

if ( is_wp_error( $response ) ) {

[271] Fix | Delete

return $response;

[272] Fix | Delete

}

[273] Fix | Delete

[274] Fix | Delete

/**

[275] Fix | Delete

* Type assertion for PHPStan - Jetpack returns array on success.

[276] Fix | Delete

*

[277] Fix | Delete

* @var array $response

[278] Fix | Delete

*/

[279] Fix | Delete

$response_code = wp_remote_retrieve_response_code( $response );

[280] Fix | Delete

$response_body = wp_remote_retrieve_body( $response );

[281] Fix | Delete

[282] Fix | Delete

$data = json_decode( $response_body, true );

[283] Fix | Delete

[284] Fix | Delete

if ( $response_code >= 300 ) {

[285] Fix | Delete

return new \WP_Error(

[286] Fix | Delete

'api_error',

[287] Fix | Delete

sprintf( 'Blackbox API %s %s returned status code %d', $method, $path, $response_code ),

[288] Fix | Delete

array( 'response' => JSON_ERROR_NONE === json_last_error() ? $data : $response_body )

[289] Fix | Delete

);

[290] Fix | Delete

}

[291] Fix | Delete

[292] Fix | Delete

if ( JSON_ERROR_NONE !== json_last_error() || ! is_array( $data ) ) {

[293] Fix | Delete

return new \WP_Error(

[294] Fix | Delete

'json_decode_error',

[295] Fix | Delete

sprintf( 'Failed to decode JSON response: %s', json_last_error_msg() ),

[296] Fix | Delete

array( 'response' => $response_body )

[297] Fix | Delete

);

[298] Fix | Delete

}

[299] Fix | Delete

[300] Fix | Delete

return $data;

[301] Fix | Delete

}

[302] Fix | Delete

[303] Fix | Delete

/**

[304] Fix | Delete

* Get the Jetpack blog ID.

[305] Fix | Delete

*

[306] Fix | Delete

* @return int|false Blog ID or false if not available.

[307] Fix | Delete

*/

[308] Fix | Delete

private function get_blog_id() {

[309] Fix | Delete

if ( ! class_exists( \Jetpack_Options::class ) ) {

[310] Fix | Delete

return false;

[311] Fix | Delete

}

[312] Fix | Delete

return \Jetpack_Options::get_option( 'id' );

[313] Fix | Delete

}

[314] Fix | Delete

}

[315] Fix | Delete

[316] Fix | Delete