raw member string. * Splits on top-level commas (ignores commas inside quotes, parentheses or :byte sequences:). * * @param string $header Header value. * @return array */ public static function split_dictionary( $header ) { $out = array(); $buf = ''; $depth = 0; $inq = false; $inb = false; $len = strlen( (string) $header ); for ( $i = 0; $i < $len; $i++ ) { $c = $header[ $i ]; if ( $inq ) { $buf .= $c; if ( '\\' === $c && $i + 1 < $len ) { $buf .= $header[ ++$i ]; } elseif ( '"' === $c ) { $inq = false; } continue; } if ( '"' === $c ) { $inq = true; } elseif ( ':' === $c && 0 === $depth ) { $inb = ! $inb; } elseif ( '(' === $c ) { $depth++; } elseif ( ')' === $c ) { $depth--; } elseif ( ',' === $c && 0 === $depth && ! $inb ) { self::add_member( $out, $buf ); $buf = ''; continue; } $buf .= $c; } self::add_member( $out, $buf ); return $out; } protected static function add_member( array &$out, $raw ) { $raw = trim( $raw ); if ( '' === $raw ) { return; } $eq = strpos( $raw, '=' ); if ( false === $eq ) { $out[ strtolower( $raw ) ] = '?1'; return; } $out[ strtolower( trim( substr( $raw, 0, $eq ) ) ) ] = trim( substr( $raw, $eq + 1 ) ); } /** Unquote an sf-string, or return null if not a string. */ public static function sf_string( $value ) { $value = trim( (string) $value ); if ( strlen( $value ) < 2 || '"' !== $value[0] || '"' !== substr( $value, -1 ) ) { return null; } return stripcslashes( substr( $value, 1, -1 ) ); } /** * Parse ";k=v;k2=v2" parameters into array (values unquoted / int). * * @param string $params Raw parameter string. */ public static function parse_params( $params ) { $out = array(); if ( ! preg_match_all( '/;\s*([a-z0-9_\-\.\*]+)(?:=("(?:[^"\\\\]|\\\\.)*"|[^;]*))?/i', (string) $params, $m, PREG_SET_ORDER ) ) { return $out; } foreach ( $m as $p ) { $v = isset( $p[2] ) ? trim( $p[2] ) : '?1'; $s = self::sf_string( $v ); if ( null !== $s ) { $v = $s; } elseif ( preg_match( '/^-?\d+$/', $v ) ) { $v = (int) $v; } $out[ strtolower( $p[1] ) ] = $v; } return $out; } /** * Parse one Signature-Input member: ("a" "b";key="x");created=1;keyid="..". * * @param string $raw Member value. * @return array|null [ 'components' => [ [identifier, name, params] ], 'params' => [...], 'raw' => string ] */ public static function parse_signature_input( $raw ) { $raw = trim( (string) $raw ); if ( '' === $raw || '(' !== $raw[0] ) { return null; } $close = self::matching_paren( $raw ); if ( false === $close ) { return null; } $inner = substr( $raw, 1, $close - 1 ); $params_raw = substr( $raw, $close + 1 ); $components = array(); if ( preg_match_all( '/("(?:[^"\\\\]|\\\\.)*")((?:;[a-z0-9_\-\.\*]+(?:=(?:"(?:[^"\\\\]|\\\\.)*"|[^\s;]*))?)*)/i', $inner, $m, PREG_SET_ORDER ) ) { foreach ( $m as $c ) { $components[] = array( 'identifier' => $c[1] . $c[2], 'name' => strtolower( (string) self::sf_string( $c[1] ) ), 'params' => self::parse_params( $c[2] ), ); } } return array( 'components' => $components, 'params' => self::parse_params( $params_raw ), 'raw' => $raw, ); } protected static function matching_paren( $s ) { $inq = false; $len = strlen( $s ); for ( $i = 1; $i < $len; $i++ ) { $c = $s[ $i ]; if ( $inq ) { if ( '\\' === $c ) { $i++; } elseif ( '"' === $c ) { $inq = false; } continue; } if ( '"' === $c ) { $inq = true; } elseif ( ')' === $c ) { return $i; } } return false; } /* ------------------------------------------------------------------ */ /* Helpers */ /* ------------------------------------------------------------------ */ public static function b64url_decode( $s ) { $s = strtr( (string) $s, '-_', '+/' ); $p = strlen( $s ) % 4; if ( $p ) { $s .= str_repeat( '=', 4 - $p ); } return base64_decode( $s, true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions } public static function b64url_encode( $bin ) { return rtrim( strtr( base64_encode( $bin ), '+/', '-_' ), '=' ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions } /** RFC 7638 thumbprint of an OKP/Ed25519 JWK. */ public static function jwk_thumbprint( array $jwk ) { if ( empty( $jwk['x'] ) ) { return ''; } $json = '{"crv":"' . ( isset( $jwk['crv'] ) ? $jwk['crv'] : 'Ed25519' ) . '","kty":"' . ( isset( $jwk['kty'] ) ? $jwk['kty'] : 'OKP' ) . '","x":"' . $jwk['x'] . '"}'; return self::b64url_encode( hash( 'sha256', $json, true ) ); } /** Normalise an operator URL to its https origin, or '' if not acceptable. */ public static function origin( $url ) { $parts = wp_parse_url( trim( (string) $url ) ); if ( empty( $parts['host'] ) || empty( $parts['scheme'] ) || 'https' !== strtolower( $parts['scheme'] ) ) { return ''; } $origin = 'https://' . strtolower( $parts['host'] ); if ( ! empty( $parts['port'] ) && 443 !== (int) $parts['port'] ) { $origin .= ':' . (int) $parts['port']; } return $origin; } /* ------------------------------------------------------------------ */ /* Key directory */ /* ------------------------------------------------------------------ */ /** * Return the JWKs published by an operator origin (cached). * * @param string $origin https origin. * @return array|WP_Error */ public static function directory_keys( $origin ) { /** * Short-circuit the key directory (used by the built-in self-test and unit tests). * * @param array|null $keys Keys, or null to fetch normally. * @param string $origin Operator origin. */ $pre = apply_filters( 'agentrue_pre_directory_keys', null, $origin ); if ( is_array( $pre ) ) { return $pre; } $cache_key = 'agentrue_dir_' . md5( $origin ); $cached = get_transient( $cache_key ); if ( is_array( $cached ) ) { return isset( $cached['error'] ) ? new WP_Error( 'directory_unavailable', $cached['error'] ) : $cached['keys']; } $res = wp_safe_remote_get( $origin . self::DIRECTORY_PATH, array( 'timeout' => 3, 'redirection' => 1, 'headers' => array( 'Accept' => 'application/http-message-signatures-directory+json, application/json' ), ) ); if ( is_wp_error( $res ) || 200 !== (int) wp_remote_retrieve_response_code( $res ) ) { $msg = is_wp_error( $res ) ? $res->get_error_message() : 'HTTP ' . wp_remote_retrieve_response_code( $res ); set_transient( $cache_key, array( 'error' => $msg ), 10 * MINUTE_IN_SECONDS ); return new WP_Error( 'directory_unavailable', $msg ); } $data = json_decode( wp_remote_retrieve_body( $res ), true ); $keys = ( is_array( $data ) && isset( $data['keys'] ) && is_array( $data['keys'] ) ) ? $data['keys'] : array(); $keys = array_values( array_filter( $keys, function ( $k ) { return is_array( $k ) && isset( $k['kty'], $k['x'] ) && 'OKP' === $k['kty']; } ) ); set_transient( $cache_key, array( 'keys' => $keys ), HOUR_IN_SECONDS ); return $keys; } /* ------------------------------------------------------------------ */ /* Signature base (RFC 9421 §2.5) */ /* ------------------------------------------------------------------ */ /** * Value of one covered component, or null if it cannot be resolved. * * @param array $component Parsed component. * @param array $req Request: method, authority, path, query, scheme, headers (lowercase => value). */ public static function component_value( array $component, array $req ) { $name = $component['name']; switch ( $name ) { case '@method': return strtoupper( $req['method'] ); case '@authority': return strtolower( $req['authority'] ); case '@scheme': return strtolower( $req['scheme'] ); case '@path': return '' === $req['path'] ? '/' : $req['path']; case '@query': return '?' . $req['query']; case '@target-uri': return strtolower( $req['scheme'] ) . '://' . strtolower( $req['authority'] ) . $req['path'] . ( '' !== $req['query'] ? '?' . $req['query'] : '' ); case '@request-target': return $req['path'] . ( '' !== $req['query'] ? '?' . $req['query'] : '' ); } if ( '@' === substr( $name, 0, 1 ) ) { return null; // Unsupported derived component. } if ( ! isset( $req['headers'][ $name ] ) ) { return null; } $value = trim( preg_replace( '/\s+/', ' ', (string) $req['headers'][ $name ] ) ); if ( isset( $component['params']['key'] ) ) { $dict = self::split_dictionary( $value ); $k = strtolower( (string) $component['params']['key'] ); return isset( $dict[ $k ] ) ? $dict[ $k ] : null; } return $value; } public static function signature_base( array $parsed, array $req ) { $lines = array(); foreach ( $parsed['components'] as $c ) { $v = self::component_value( $c, $req ); if ( null === $v ) { return null; } $lines[] = $c['identifier'] . ': ' . $v; } $lines[] = '"@signature-params": ' . $parsed['raw']; return implode( "\n", $lines ); } /* ------------------------------------------------------------------ */ /* Verify */ /* ------------------------------------------------------------------ */ /** * Verify a request. * * @param array $req Request description (see component_value) – headers keys lowercase. * @param array $trusted Allow-listed operator origins. * @param bool $any Fetch directories for operators not in the allow-list. * @return array { status: verified|invalid|unsigned, reason, operator, keyid } */ public static function verify( array $req, array $trusted = array(), $any = false ) { $h = $req['headers']; $result = array( 'status' => 'unsigned', 'reason' => '', 'operator' => '', 'keyid' => '', ); if ( empty( $h['signature-input'] ) || empty( $h['signature'] ) ) { return $result; } $result['status'] = 'invalid'; if ( ! function_exists( 'sodium_crypto_sign_verify_detached' ) ) { $result['reason'] = 'libsodium not available on this server'; return $result; } $inputs = self::split_dictionary( $h['signature-input'] ); $sigs = self::split_dictionary( $h['signature'] ); // Prefer the web-bot-auth tagged signature. $label = null; $parsed = null; foreach ( $inputs as $l => $raw ) { $p = self::parse_signature_input( $raw ); if ( ! $p ) { continue; } if ( null === $label || ( isset( $p['params']['tag'] ) && 'web-bot-auth' === $p['params']['tag'] ) ) { $label = $l; $parsed = $p; } } if ( ! $parsed || ! isset( $sigs[ $label ] ) ) { $result['reason'] = 'malformed signature headers'; return $result; } $params = $parsed['params']; if ( isset( $params['alg'] ) && 'ed25519' !== strtolower( (string) $params['alg'] ) ) { $result['reason'] = 'unsupported algorithm'; return $result; } $now = time(); if ( empty( $params['created'] ) || empty( $params['expires'] ) ) { $result['reason'] = 'missing created/expires'; return $result; } if ( (int) $params['created'] > $now + self::CLOCK_SKEW ) { $result['reason'] = 'signature created in the future'; return $result; } if ( (int) $params['expires'] < $now - self::CLOCK_SKEW ) { $result['reason'] = 'signature expired'; return $result; } $keyid = isset( $params['keyid'] ) ? (string) $params['keyid'] : ''; $result['keyid'] = $keyid; // Operator from Signature-Agent (sf-string, or dictionary member matching the label). $agent_raw = isset( $h['signature-agent'] ) ? (string) $h['signature-agent'] : ''; $agent_url = self::sf_string( $agent_raw ); if ( null === $agent_url ) { $dict = self::split_dictionary( $agent_raw ); $agent_url = isset( $dict[ $label ] ) ? self::sf_string( $dict[ $label ] ) : ( $dict ? self::sf_string( reset( $dict ) ) : null ); } $origin = self::origin( (string) $agent_url ); if ( '' === $origin ) { $result['reason'] = 'missing or non-https Signature-Agent'; return $result; } $result['operator'] = $origin; // Signature-Agent must itself be covered by the signature, otherwise it can be swapped. $covers_agent = false; foreach ( $parsed['components'] as $c ) { if ( 'signature-agent' === $c['name'] ) { $covers_agent = true; } } if ( ! $covers_agent ) { $result['reason'] = 'Signature-Agent not covered by signature'; return $result; } if ( ! in_array( $origin, $trusted, true ) && ! $any ) { $result['status'] = 'unknown_operator'; $result['reason'] = 'operator not in allow-list'; return $result; } $keys = self::directory_keys( $origin ); if ( is_wp_error( $keys ) ) { $result['status'] = 'unverifiable'; $result['reason'] = 'key directory unavailable: ' . $keys->get_error_message(); return $result; } $jwk = null; foreach ( $keys as $k ) { if ( ( isset( $k['kid'] ) && $k['kid'] === $keyid ) || self::jwk_thumbprint( $k ) === $keyid ) { $jwk = $k; break; } } if ( ! $jwk ) { $result['reason'] = 'key not found in operator directory'; return $result; } $pub = self::b64url_decode( $jwk['x'] ); if ( false === $pub || SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES !== strlen( $pub ) ) { $result['reason'] = 'invalid public key'; return $result; } $sig_raw = trim( $sigs[ $label ] ); if ( ! preg_match( '/^:([A-Za-z0-9+\/=]+):$/', $sig_raw, $sm ) ) { $result['reason'] = 'malformed signature value'; return $result; } $sig = base64_decode( $sm[1], true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions if ( false === $sig || SODIUM_CRYPTO_SIGN_BYTES !== strlen( $sig ) ) { $result['reason'] = 'malformed signature value'; return $result; } $base = self::signature_base( $parsed, $req ); if ( null === $base ) { $result['reason'] = 'a covered component is missing from the request'; return $result; } if ( ! sodium_crypto_sign_verify_detached( $sig, $base, $pub ) ) { $result['reason'] = 'signature does not match'; return $result; } $result['status'] = 'verified'; return $result; } /** * Sanitize a raw HTTP header or request-target value. * * Signature verification needs the exact bytes the agent signed, so the * value is not reformatted (sanitize_text_field() would strip percent * encodings and collapse spaces and break valid signatures). Instead it is * limited to what HTTP allows: valid UTF-8, no control characters, and a * maximum length. * * @param mixed $value Raw value. * @param int $max Maximum length. * @return string */ public static function sanitize_http_value( $value, $max = 8192 ) { if ( ! is_scalar( $value ) ) { return ''; } $value = wp_check_invalid_utf8( (string) $value ); $value = (string) preg_replace( '/[\x00-\x1F\x7F]/', '', $value ); return substr( $value, 0, $max ); } /** Build the request description from PHP globals (all values sanitized). */ public static function current_request() { $headers = array(); foreach ( array_keys( $_SERVER ) as $k ) { if ( ! is_string( $k ) || 0 !== strpos( $k, 'HTTP_' ) ) { continue; } $name = sanitize_key( str_replace( '_', '-', substr( $k, 5 ) ) ); if ( '' === $name || ! isset( $_SERVER[ $k ] ) || ! is_string( $_SERVER[ $k ] ) ) { continue; } $headers[ $name ] = self::sanitize_http_value( wp_unslash( $_SERVER[ $k ] ) ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- sanitized by sanitize_http_value(). } $uri = isset( $_SERVER['REQUEST_URI'] ) ? self::sanitize_http_value( wp_unslash( $_SERVER['REQUEST_URI'] ), 4096 ) : '/'; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- sanitized by sanitize_http_value(). if ( '' === $uri || '/' !== $uri[0] ) { $uri = '/'; } $qpos = strpos( $uri, '?' ); $host = isset( $_SERVER['HTTP_HOST'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_HOST'] ) ) : ''; $host = strtolower( (string) preg_replace( '/[^A-Za-z0-9.\-:\[\]]/', '', $host ) ); if ( '' === $host ) { $host = strtolower( (string) wp_parse_url( home_url(), PHP_URL_HOST ) ); } $method = isset( $_SERVER['REQUEST_METHOD'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) : 'GET'; $method = (string) preg_replace( '/[^A-Z]/', '', strtoupper( $method ) ); if ( '' === $method ) { $method = 'GET'; } return array( 'method' => substr( $method, 0, 16 ), 'authority' => $host, 'scheme' => is_ssl() ? 'https' : 'http', 'path' => false === $qpos ? $uri : substr( $uri, 0, $qpos ), 'query' => false === $qpos ? '' : substr( $uri, $qpos + 1 ), 'headers' => $headers, ); } /** * Sign a request (used by the self-test and tests). Returns headers to add. * * @param array $req Request description. * @param string $secret_key Ed25519 secret key (64 bytes). * @param string $agent Signature-Agent URL. */ public static function sign( array $req, $secret_key, $agent ) { $pub = sodium_crypto_sign_publickey_from_secretkey( $secret_key ); $keyid = self::jwk_thumbprint( array( 'kty' => 'OKP', 'crv' => 'Ed25519', 'x' => self::b64url_encode( $pub ) ) ); $now = time(); $input = '("@authority" "signature-agent");created=' . $now . ';keyid="' . $keyid . '";alg="ed25519";expires=' . ( $now + 300 ) . ';nonce="' . self::b64url_encode( random_bytes( 16 ) ) . '";tag="web-bot-auth"'; $req['headers']['signature-agent'] = '"' . $agent . '"'; $parsed = self::parse_signature_input( $input ); $base = self::signature_base( $parsed, $req ); $sig = sodium_crypto_sign_detached( $base, $secret_key ); return array( 'signature-agent' => '"' . $agent . '"', 'signature-input' => 'sig1=' . $input, 'signature' => 'sig1=:' . base64_encode( $sig ) . ':', // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions ); } }