From 0fc3a9c56810a07ab88657d246338da79af29a8a Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 8 Nov 2026 22:36:23 +0800 Subject: [PATCH] feat(cloud): validate signed abuse observation batches --- .../Cloud/CloudAbuseObservationContract.php | 588 ++++++++++++++++++ web/app/Services/Cloud/CloudAgentClient.php | 46 ++ .../CloudAbuseObservationContractTest.php | 359 +++++++++++ 3 files changed, 993 insertions(+) create mode 100644 web/app/Services/Cloud/CloudAbuseObservationContract.php create mode 100644 web/tests/CloudAbuseObservationContractTest.php diff --git a/web/app/Services/Cloud/CloudAbuseObservationContract.php b/web/app/Services/Cloud/CloudAbuseObservationContract.php new file mode 100644 index 00000000..9510355c --- /dev/null +++ b/web/app/Services/Cloud/CloudAbuseObservationContract.php @@ -0,0 +1,588 @@ + self::MAX_WINDOWS) { + self::invalid('windows is not a bounded list'); + } + + $windows = []; + $previous = 0; + foreach ($payload['windows'] as $index => $window) { + $normalized = self::normalizeWindow( + $window, + $generation, + $capability, + "windows[{$index}]" + ); + if ($previous !== 0 && ($previous === PHP_INT_MAX + || $normalized['cursor'] !== $previous + 1)) { + self::invalid('window cursors are not contiguous'); + } + $previous = $normalized['cursor']; + $windows[] = $normalized; + } + + if (!$capability['available'] && $windows !== []) { + self::invalid('unavailable capability returned windows'); + } + if ($windows === []) { + if ($hasMore || $next !== 0 || $gapBefore) { + self::invalid('empty batch has pagination state'); + } + } else { + $first = $windows[0]['cursor']; + if ($oldest === 0 || $oldest > $first) { + self::invalid('invalid retained cursor boundary'); + } + if ($gapBefore && $oldest !== $first) { + self::invalid('gap batch does not start at retained boundary'); + } + if ($next !== $previous || ($hasMore && $next === 0)) { + self::invalid('invalid next cursor'); + } + } + + $sameGeneration = $requestedGeneration !== null + && hash_equals($requestedGeneration, $generation); + if ($windows === []) { + if (!$sameGeneration && $oldest !== 0) { + self::invalid( + 'initial or reset empty batch retained a cursor boundary' + ); + } + if ($sameGeneration && $oldest !== 0 && $oldest > $afterCursor) { + self::invalid( + 'empty batch retained a boundary after the requested cursor' + ); + } + } + if (($requestedGeneration === null || !$sameGeneration) && $gapBefore) { + self::invalid('generation reset retained an old-generation gap'); + } + if ((!$sameGeneration || $afterCursor === 0) && $windows !== [] + && $windows[0]['cursor'] !== $oldest) { + self::invalid( + 'initial or reset batch skipped the retained cursor boundary' + ); + } + if ($sameGeneration && $windows !== []) { + $first = $windows[0]['cursor']; + if ($first <= $afterCursor) { + self::invalid('batch did not advance the requested cursor'); + } + $expectedGap = $afterCursor > 0 + && $oldest > 0 + && $afterCursor < $oldest - 1; + if ($gapBefore !== $expectedGap) { + self::invalid('gap evidence disagrees with requested cursor'); + } + if (!$gapBefore && $afterCursor > 0 + && ($afterCursor === PHP_INT_MAX + || $first !== $afterCursor + 1)) { + self::invalid('batch skipped a cursor without gap evidence'); + } + } + + return [ + 'contract_version' => $version, + 'collector_generation' => $generation, + 'oldest_cursor' => $oldest, + 'gap_before' => $gapBefore, + 'next_cursor' => $next, + 'has_more' => $hasMore, + 'capability' => $capability, + 'windows' => $windows, + ]; + } + + private static function normalizeCapability(mixed $value): array + { + self::assertObject($value, [ + 'name', 'contract_version', 'available', 'no_payload', 'ipv4', + 'ipv6', 'conntrack', 'packet_accounting', 'policy_decisions', + 'bucket_seconds', + ], ['reason'], 'capability'); + $result = [ + 'name' => self::shortString($value['name'], 'capability.name'), + 'contract_version' => self::unsigned( + $value['contract_version'], 'capability.contract_version' + ), + 'available' => self::boolean( + $value['available'], 'capability.available' + ), + 'no_payload' => self::boolean( + $value['no_payload'], 'capability.no_payload' + ), + 'ipv4' => self::boolean($value['ipv4'], 'capability.ipv4'), + 'ipv6' => self::boolean($value['ipv6'], 'capability.ipv6'), + 'conntrack' => self::boolean( + $value['conntrack'], 'capability.conntrack' + ), + 'packet_accounting' => self::boolean( + $value['packet_accounting'], 'capability.packet_accounting' + ), + 'policy_decisions' => self::boolean( + $value['policy_decisions'], 'capability.policy_decisions' + ), + 'bucket_seconds' => self::unsigned( + $value['bucket_seconds'], 'capability.bucket_seconds' + ), + ]; + if ($result['name'] !== self::CAPABILITY_NAME + || $result['contract_version'] !== self::CONTRACT_VERSION + || !$result['no_payload'] + || $result['policy_decisions'] + || $result['bucket_seconds'] !== self::BUCKET_SECONDS) { + self::invalid('inconsistent capability contract'); + } + if ($result['available']) { + if (array_key_exists('reason', $value) + || !$result['conntrack'] + || (!$result['ipv4'] && !$result['ipv6'])) { + self::invalid('inconsistent available capability'); + } + } else { + if (!array_key_exists('reason', $value)) { + self::invalid('unavailable capability omitted its reason'); + } + $reason = self::shortString($value['reason'], 'capability.reason'); + if (!in_array($reason, self::CAPABILITY_REASONS, true)) { + self::invalid('unknown capability reason'); + } + $result['reason'] = $reason; + } + return $result; + } + + private static function normalizeWindow( + mixed $value, + string $generation, + array $capability, + string $path + ): array { + self::assertObject($value, [ + 'cursor', 'window_id', 'vm_uuid', 'bucket_start', + 'bucket_seconds', 'complete', 'quality_flags', 'interface', + 'ipv4', 'ipv6', + ], [], $path); + $cursor = self::positive($value['cursor'], "{$path}.cursor"); + $windowId = self::patternString( + $value['window_id'], '/^[a-f0-9]{32}$/D', "{$path}.window_id" + ); + $uuid = self::patternString( + $value['vm_uuid'], + '/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/D', + "{$path}.vm_uuid" + ); + [$bucketStart, $bucketEpoch] = self::bucketStart( + $value['bucket_start'], "{$path}.bucket_start" + ); + $bucketSeconds = self::unsigned( + $value['bucket_seconds'], "{$path}.bucket_seconds" + ); + if ($bucketSeconds !== self::BUCKET_SECONDS) { + self::invalid("{$path} uses an unsupported bucket size"); + } + $expectedId = substr(hash('sha256', $generation . "\n" . $cursor + . "\n" . $uuid . "\n" . $bucketEpoch), 0, 32); + if (!hash_equals($expectedId, $windowId)) { + self::invalid("{$path}.window_id does not match its identity"); + } + + $complete = self::boolean($value['complete'], "{$path}.complete"); + $quality = self::normalizeQualityFlags( + $value['quality_flags'], "{$path}.quality_flags" + ); + $incomplete = in_array('incomplete', $quality, true); + if ($complete === $incomplete) { + self::invalid("{$path} completeness disagrees with quality flags"); + } + if ($complete + && array_intersect($quality, self::RISK_UNSAFE_QUALITY_FLAGS) !== []) { + self::invalid("{$path} contains risk-unsafe complete evidence"); + } + + $interface = self::normalizeInterface( + $value['interface'], "{$path}.interface" + ); + $hasMissingCounter = in_array(null, $interface, true); + if ($hasMissingCounter + !== in_array('interface_unavailable', $quality, true)) { + self::invalid("{$path} interface availability is contradictory"); + } + $ipv4 = self::normalizeFamily( + $value['ipv4'], $capability['ipv4'], "{$path}.ipv4" + ); + $ipv6 = self::normalizeFamily( + $value['ipv6'], $capability['ipv6'], "{$path}.ipv6" + ); + if ($ipv4 === null && $ipv6 === null) { + self::invalid("{$path} has no supported address family"); + } + return [ + 'cursor' => $cursor, + 'window_id' => $windowId, + 'vm_uuid' => $uuid, + 'bucket_start' => $bucketStart, + 'bucket_seconds' => $bucketSeconds, + 'complete' => $complete, + 'quality_flags' => $quality, + 'interface' => $interface, + 'ipv4' => $ipv4, + 'ipv6' => $ipv6, + ]; + } + + private static function normalizeQualityFlags(mixed $value, string $path): array + { + if (!is_array($value) || !array_is_list($value) || count($value) > 16) { + self::invalid("{$path} is not a bounded list"); + } + $result = []; + foreach ($value as $flag) { + $flag = self::shortString($flag, $path); + if (!in_array($flag, self::QUALITY_FLAGS, true)) { + self::invalid("{$path} contains an unknown flag"); + } + $result[] = $flag; + } + $canonical = array_values(array_unique($result)); + sort($canonical, SORT_STRING); + if ($canonical !== $result) { + self::invalid("{$path} is not canonical"); + } + return $result; + } + + private static function normalizeInterface(mixed $value, string $path): array + { + $fields = [ + 'rx_bytes', 'tx_bytes', 'rx_packets', 'tx_packets', + 'rx_errors', 'tx_errors', 'rx_drops', 'tx_drops', + ]; + self::assertObject($value, $fields, [], $path); + $result = []; + foreach ($fields as $field) { + $result[$field] = $value[$field] === null + ? null : self::unsigned($value[$field], "{$path}.{$field}"); + } + return $result; + } + + private static function normalizeFamily( + mixed $value, + bool $supported, + string $path + ): ?array { + if (!$supported) { + if ($value !== null) { + self::invalid("{$path} is present without capability support"); + } + return null; + } + if ($value === null) { + self::invalid("{$path} is missing despite capability support"); + } + self::assertObject($value, ['inbound', 'outbound'], [], $path); + return [ + 'inbound' => self::normalizeFlowSummary( + $value['inbound'], "{$path}.inbound" + ), + 'outbound' => self::normalizeFlowSummary( + $value['outbound'], "{$path}.outbound" + ), + ]; + } + + private static function normalizeFlowSummary(mixed $value, string $path): array + { + self::assertObject($value, self::FLOW_FIELDS, [], $path); + $result = []; + foreach (self::FLOW_FIELDS as $field) { + $result[$field] = self::unsigned($value[$field], "{$path}.{$field}"); + } + if ($result['tcp_new_flows'] > $result['tcp_active_flows'] + || $result['tcp_syn_flows'] > $result['tcp_active_flows'] + || $result['tcp_unreplied_flows'] > $result['tcp_active_flows'] + || $result['udp_new_flows'] > $result['udp_active_flows']) { + self::invalid("{$path} contains an impossible flow subset"); + } + if ($result['tcp_active_flows'] > PHP_INT_MAX - $result['udp_active_flows']) { + self::invalid("{$path} active-flow population overflowed"); + } + $total = $result['tcp_active_flows'] + $result['udp_active_flows']; + if ($total > PHP_INT_MAX - $result['other_active_flows']) { + self::invalid("{$path} active-flow population overflowed"); + } + $total += $result['other_active_flows']; + if ($result['unique_remote_ips'] > $total + || $result['unique_remote_ports'] > $total + || $result['unique_local_ports'] > $total + || $result['max_remote_ports_per_remote_ip'] + > $result['unique_remote_ports'] + || $result['max_remote_ips_per_remote_port'] + > $result['unique_remote_ips'] + || $result['max_local_ports_per_remote_ip'] + > $result['unique_local_ports'] + || $result['max_remote_ips_per_local_port'] + > $result['unique_remote_ips']) { + self::invalid("{$path} contains an impossible cardinality"); + } + if (($result['unique_remote_ips'] === 0 + && ($result['max_remote_ports_per_remote_ip'] !== 0 + || $result['max_local_ports_per_remote_ip'] !== 0)) + || ($result['unique_remote_ports'] === 0 + && $result['max_remote_ips_per_remote_port'] !== 0) + || ($result['unique_local_ports'] === 0 + && $result['max_remote_ips_per_local_port'] !== 0)) { + self::invalid("{$path} relation cardinality has no population"); + } + return $result; + } + + private static function assertBoundedTree(array $payload): void + { + try { + $encoded = json_encode( + $payload, + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + ); + } catch (\JsonException) { + self::invalid('response cannot be encoded canonically'); + } + if (strlen($encoded) > self::MAX_ENCODED_BYTES) { + self::invalid('response exceeds the observation size limit'); + } + $nodes = 0; + $stack = [[$payload, 1]]; + while ($stack !== []) { + [$value, $depth] = array_pop($stack); + if (++$nodes > self::MAX_NODES || $depth > self::MAX_DEPTH) { + self::invalid('response exceeds the observation shape limit'); + } + if (!is_array($value)) { + continue; + } + foreach ($value as $child) { + $stack[] = [$child, $depth + 1]; + } + } + } + + private static function assertObject( + mixed $value, + array $required, + array $optional, + string $path + ): void { + if (!is_array($value) || $value === [] || array_is_list($value)) { + self::invalid("{$path} is not an object"); + } + $allowed = array_fill_keys(array_merge($required, $optional), true); + foreach (array_keys($value) as $key) { + if (!is_string($key) || !isset($allowed[$key])) { + self::invalid("{$path} contains an unknown field"); + } + } + foreach ($required as $key) { + if (!array_key_exists($key, $value)) { + self::invalid("{$path} omitted a required field"); + } + } + } + + private static function unsigned(mixed $value, string $path): int + { + if (!is_int($value) || $value < 0) { + self::invalid("{$path} is not an unsigned integer"); + } + return $value; + } + + private static function positive(mixed $value, string $path): int + { + $value = self::unsigned($value, $path); + if ($value === 0) { + self::invalid("{$path} must be positive"); + } + return $value; + } + + private static function boolean(mixed $value, string $path): bool + { + if (!is_bool($value)) { + self::invalid("{$path} is not a boolean"); + } + return $value; + } + + private static function shortString(mixed $value, string $path): string + { + if (!is_string($value) || $value === '' || strlen($value) > 64 + || preg_match('/[\x00-\x1f\x7f]/', $value) === 1) { + self::invalid("{$path} is not a bounded string"); + } + return $value; + } + + private static function patternString( + mixed $value, + string $pattern, + string $path + ): string { + if (!is_string($value) || preg_match($pattern, $value) !== 1) { + self::invalid("{$path} has an invalid format"); + } + return $value; + } + + private static function bucketStart(mixed $value, string $path): array + { + if (!is_string($value) + || preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:00Z$/D', $value) !== 1) { + self::invalid("{$path} is not a UTC minute"); + } + $time = \DateTimeImmutable::createFromFormat( + '!Y-m-d\TH:i:s\Z', + $value, + new \DateTimeZone('UTC') + ); + $errors = \DateTimeImmutable::getLastErrors(); + if ($time === false || ($errors !== false + && ($errors['warning_count'] !== 0 || $errors['error_count'] !== 0)) + || $time->format('Y-m-d\TH:i:s\Z') !== $value + || $time->getTimestamp() < 0 + || $time->getTimestamp() % self::BUCKET_SECONDS !== 0) { + self::invalid("{$path} is not a canonical UTC minute"); + } + return [$value, $time->getTimestamp()]; + } + + private static function invalid(string $reason): never + { + throw new CloudAgentError( + '宿主机 Agent 返回了无效的网络观测合同', + 502, + 'agent_invalid_network_observation', + true + ); + } +} diff --git a/web/app/Services/Cloud/CloudAgentClient.php b/web/app/Services/Cloud/CloudAgentClient.php index 5374351a..29c310a8 100644 --- a/web/app/Services/Cloud/CloudAgentClient.php +++ b/web/app/Services/Cloud/CloudAgentClient.php @@ -174,6 +174,52 @@ final class CloudAgentClient ); } + /** + * Read one bounded, aggregate network-observation page. + * + * This is intentionally not a cloud_jobs operation: it has no mutation, + * replay or lifecycle effect. The response crosses a dedicated strict + * parser so unknown Agent fields can never be persisted by callers. + */ + public function networkObservations( + array $actor, + ?string $generation = null, + int $afterCursor = 0, + int $limit = CloudAbuseObservationContract::MAX_WINDOWS + ): array { + if ($generation !== null + && preg_match('/^[a-f0-9]{32}$/D', $generation) !== 1) { + throw new \InvalidArgumentException( + 'Invalid network-observation generation' + ); + } + if ($afterCursor < 0 + || ($generation === null && $afterCursor !== 0) + || $limit < 1 + || $limit > CloudAbuseObservationContract::MAX_WINDOWS) { + throw new \InvalidArgumentException( + 'Invalid network-observation pagination' + ); + } + $query = []; + if ($generation !== null) { + $query['generation'] = $generation; + } + $query['after_cursor'] = (string) $afterCursor; + $query['limit'] = (string) $limit; + $target = '/v1/network-observations?' . http_build_query( + $query, + '', + '&', + PHP_QUERY_RFC3986 + ); + return CloudAbuseObservationContract::normalize( + $this->request('GET', $target, $actor), + $generation, + $afterCursor + ); + } + /** * Send one operation-bound recovery request with no human privileges. * diff --git a/web/tests/CloudAbuseObservationContractTest.php b/web/tests/CloudAbuseObservationContractTest.php new file mode 100644 index 00000000..d6545f4f --- /dev/null +++ b/web/tests/CloudAbuseObservationContractTest.php @@ -0,0 +1,359 @@ + [ + 'tcp_active_flows' => 5, + 'tcp_new_flows' => 2, + 'tcp_syn_flows' => 1, + 'tcp_unreplied_flows' => 1, + 'udp_active_flows' => 3, + 'udp_new_flows' => 1, + 'other_active_flows' => 0, + 'unique_remote_ips' => 4, + 'unique_remote_ports' => 3, + 'unique_local_ports' => 2, + 'max_remote_ports_per_remote_ip' => 2, + 'max_remote_ips_per_remote_port' => 2, + 'max_local_ports_per_remote_ip' => 1, + 'max_remote_ips_per_local_port' => 2, +]; +$valid = static function () use ( + $generation, + $uuid, + $bucket, + $bucketEpoch, + $flow +): array { + $cursor = 1; + return [ + 'contract_version' => 1, + 'collector_generation' => $generation, + 'oldest_cursor' => 1, + 'gap_before' => false, + 'next_cursor' => 1, + 'has_more' => false, + 'capability' => [ + 'name' => 'network_abuse_observation_v1', + 'contract_version' => 1, + 'available' => true, + 'no_payload' => true, + 'ipv4' => true, + 'ipv6' => false, + 'conntrack' => true, + 'packet_accounting' => true, + 'policy_decisions' => false, + 'bucket_seconds' => 60, + ], + 'windows' => [[ + 'cursor' => $cursor, + 'window_id' => substr(hash('sha256', $generation . "\n" + . $cursor . "\n" . $uuid . "\n" . $bucketEpoch), 0, 32), + 'vm_uuid' => $uuid, + 'bucket_start' => $bucket, + 'bucket_seconds' => 60, + 'complete' => true, + 'quality_flags' => [], + 'interface' => [ + 'rx_bytes' => 1000, + 'tx_bytes' => 2000, + 'rx_packets' => 10, + 'tx_packets' => 20, + 'rx_errors' => 0, + 'tx_errors' => 0, + 'rx_drops' => 0, + 'tx_drops' => 0, + ], + 'ipv4' => [ + 'inbound' => $flow(), + 'outbound' => $flow(), + ], + 'ipv6' => null, + ]], + ]; +}; + +$normalized = CloudAbuseObservationContract::normalize($valid()); +$assert($normalized['collector_generation'] === $generation + && $normalized['windows'][0]['bucket_start'] === $bucket + && $normalized['windows'][0]['ipv4']['outbound']['tcp_new_flows'] === 2, + 'A valid observation batch was not preserved canonically.'); +$encoded = json_encode($normalized, JSON_THROW_ON_ERROR); +$assert(!str_contains($encoded, '"payload":') + && !str_contains($encoded, '"remote_ip":"') + && !str_contains($encoded, 'remote_ports":['), + 'The normalized contract leaked flow identities or packet content.'); + +$reject = static function (array $payload, string $message) use ($assert): void { + try { + CloudAbuseObservationContract::normalize($payload); + throw new RuntimeException($message); + } catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation' + && $error->httpStatus === 502 + && $error->retryable, + 'Invalid network evidence lost its typed retryable failure.'); + } +}; + +$payload = $valid(); +$payload['windows'][0]['payload'] = base64_encode('private packet body'); +$reject($payload, 'Packet payload field was accepted.'); +$payload = $valid(); +$payload['windows'][0]['ipv4']['outbound']['remote_ips'] = ['203.0.113.2']; +$reject($payload, 'Remote-IP list field was accepted.'); +$payload = $valid(); +$payload['windows'][0]['ipv4']['outbound']['remote_ports'] = [22, 25]; +$reject($payload, 'Remote-port list field was accepted.'); +$payload = $valid(); +$payload['windows'][0]['ipv4']['outbound']['tcp_new_flows'] = 6; +$reject($payload, 'Impossible TCP subset was accepted.'); +$payload = $valid(); +$payload['windows'][0]['ipv4']['outbound']['unique_remote_ips'] = 9; +$reject($payload, 'Impossible remote cardinality was accepted.'); +$payload = $valid(); +$payload['windows'][0]['window_id'] = str_repeat('a', 32); +$reject($payload, 'Window identity mismatch was accepted.'); +$payload = $valid(); +$payload['windows'][0]['bucket_start'] = '2026-11-08T01:02:01Z'; +$reject($payload, 'Non-minute bucket was accepted.'); +$payload = $valid(); +$payload['windows'][0]['quality_flags'] = ['clock_regression']; +$reject($payload, 'Risk-unsafe complete window was accepted.'); +$payload = $valid(); +$payload['windows'][0]['interface']['rx_packets'] = null; +$reject($payload, 'Missing interface counter without evidence was accepted.'); +$payload = $valid(); +$payload['windows'][0]['cursor'] = '1'; +$reject($payload, 'A string cursor was accepted as an integer.'); +$payload = $valid(); +$second = $payload['windows'][0]; +$second['cursor'] = 3; +$second['window_id'] = substr(hash('sha256', $generation . "\n3\n" + . $uuid . "\n" . $bucketEpoch), 0, 32); +$payload['windows'][] = $second; +$payload['next_cursor'] = 3; +$reject($payload, 'A skipped cursor inside one batch was accepted.'); +$payload = $valid(); +$payload['windows'] = array_fill( + 0, + CloudAbuseObservationContract::MAX_WINDOWS + 1, + $payload['windows'][0] +); +$reject($payload, 'Unbounded observation window list was accepted.'); +$payload = $valid(); +$payload['oversized'] = str_repeat('x', 524289); +$reject($payload, 'An oversized observation tree was accepted.'); +$payload = $valid(); +$payload['nested'] = [ + 'a' => [ + 'b' => [ + 'c' => [ + 'd' => [ + 'e' => [ + 'f' => [ + 'g' => [ + 'h' => ['i' => true], + ], + ], + ], + ], + ], + ], + ], +]; +$reject($payload, 'An over-deep observation tree was accepted.'); + +$payload = $valid(); +$payload['windows'][0]['complete'] = false; +$payload['windows'][0]['quality_flags'] = ['incomplete', 'sampling_gap']; +$normalizedGap = CloudAbuseObservationContract::normalize($payload); +$assert($normalizedGap['windows'][0]['complete'] === false, + 'An explicit sampling gap was not retained as incomplete evidence.'); + +$payload = $valid(); +$payload['gap_before'] = true; +$resetGeneration = 'fedcba9876543210fedcba9876543210'; +$tryReset = static function () use ( + $payload, + $resetGeneration +): void { + CloudAbuseObservationContract::normalize($payload, $resetGeneration, 99); +}; +try { + $tryReset(); + throw new RuntimeException('Generation reset retained stale gap evidence.'); +} catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation', + 'Generation-reset contradiction did not fail through the contract.'); +} + +$payload = $valid(); +$payload['oldest_cursor'] = 3; +$payload['windows'][0]['cursor'] = 3; +$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n" + . $uuid . "\n" . $bucketEpoch), 0, 32); +$payload['next_cursor'] = 3; +$payload['gap_before'] = true; +$gap = CloudAbuseObservationContract::normalize($payload, $generation, 1); +$assert($gap['gap_before'] && $gap['oldest_cursor'] === 3, + 'A truthful retained-ring gap was rejected.'); + +$payload = $valid(); +$payload['windows'][0]['cursor'] = 3; +$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n" + . $uuid . "\n" . $bucketEpoch), 0, 32); +$payload['next_cursor'] = 3; +try { + CloudAbuseObservationContract::normalize($payload, $generation, 1); + throw new RuntimeException('A same-generation cursor skip was accepted.'); +} catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation', + 'A cursor skip did not fail through the strict contract.'); +} + +$payload = $valid(); +$payload['windows'][0]['cursor'] = 3; +$payload['windows'][0]['window_id'] = substr(hash('sha256', $generation . "\n3\n" + . $uuid . "\n" . $bucketEpoch), 0, 32); +$payload['next_cursor'] = 3; +$reject($payload, 'An initial batch skipped the retained boundary.'); +try { + CloudAbuseObservationContract::normalize( + $payload, + $generation, + 0 + ); + throw new RuntimeException( + 'A same-generation zero-cursor batch skipped the retained boundary.' + ); +} catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation', + 'A same-generation zero-cursor skip did not fail strictly.'); +} +try { + CloudAbuseObservationContract::normalize( + $payload, + 'fedcba9876543210fedcba9876543210', + 88 + ); + throw new RuntimeException( + 'A generation-reset batch skipped the retained boundary.' + ); +} catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation', + 'A reset boundary skip did not fail through the strict contract.'); +} + +$empty = $valid(); +$empty['windows'] = []; +$empty['next_cursor'] = 0; +$empty['oldest_cursor'] = 2; +$reject($empty, 'An initial empty batch retained an impossible boundary.'); +try { + CloudAbuseObservationContract::normalize($empty, $generation, 1); + throw new RuntimeException( + 'A same-generation empty batch retained a future boundary.' + ); +} catch (CloudAgentError $error) { + $assert($error->agentCode === 'agent_invalid_network_observation', + 'A future empty boundary did not fail through the strict contract.'); +} +$empty['oldest_cursor'] = 1; +$normalizedEmpty = CloudAbuseObservationContract::normalize( + $empty, + $generation, + 1 +); +$assert($normalizedEmpty['windows'] === [] + && $normalizedEmpty['oldest_cursor'] === 1, + 'A truthful exhausted-ring empty batch was rejected.'); + +$history = []; +$handler = new MockHandler([ + new Response(200, ['Content-Type' => 'application/json'], json_encode( + $valid(), + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + )), +]); +$stack = HandlerStack::create($handler); +$stack->push(Middleware::history($history)); +$client = new CloudAgentClient( + '42', + 'test-secret-which-is-at-least-32-bytes', + new Client(['handler' => $stack]), + 20.0, + CloudAgentGatewayEndpoint::URL, + 'test-gateway-secret-at-least-32-bytes' +); +$result = $client->networkObservations([ + 'user_id' => 1, + 'is_admin' => true, + 'is_super_admin' => true, + 'can_manage' => true, +], null, 0, 64); +$wire = json_decode( + (string) $history[0]['request']->getBody(), + true, + 16, + JSON_THROW_ON_ERROR +); +$actorValue = (string) ($wire['headers']['X-Virt-Actor'] ?? ''); +$actorValue = strtr($actorValue, '-_', '+/'); +$actorValue .= str_repeat('=', (4 - strlen($actorValue) % 4) % 4); +$signedActor = json_decode( + base64_decode($actorValue, true), + true, + 16, + JSON_THROW_ON_ERROR +); +$assert(($wire['method'] ?? null) === 'GET' + && ($wire['request_target'] ?? null) + === '/v1/network-observations?after_cursor=0&limit=64' + && ($wire['body'] ?? null) === '' + && $signedActor === [ + 'user_id' => 1, + 'is_admin' => true, + 'is_super_admin' => true, + 'can_manage' => true, + ] + && $result['windows'][0]['window_id'] + === $valid()['windows'][0]['window_id'], + 'The read-only signed observation request changed its reviewed target.'); + +foreach ([ + [null, -1, 64], + [null, 1, 64], + [null, 0, 0], + [null, 0, 65], + ['invalid', 0, 64], +] as [$requestedGeneration, $after, $limit]) { + try { + $client->networkObservations([], $requestedGeneration, $after, $limit); + throw new RuntimeException('Invalid observation pagination was accepted.'); + } catch (InvalidArgumentException $error) { + // Expected before transport. + } +} + +echo "Cloud abuse observation contract passed.\n";