[ '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";