feat: add package checksum validation

src/Package/PackageChecksum.php

@@ -0,0 +1,60 @@
+<?php
+/**
+ * Package checksum utility.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Package;
+
+final class PackageChecksum {
+	/**
+	 * @param array<string, mixed> $records Package records.
+	 */
+	public static function records( array $records ): string {
+		return 'sha256:' . hash( 'sha256', self::canonicalJson( $records ) );
+	}
+
+	/**
+	 * @param array<string, mixed> $records  Package records.
+	 * @param string               $checksum Expected checksum.
+	 */
+	public static function verifyRecords( array $records, string $checksum ): bool {
+		return hash_equals( self::records( $records ), $checksum );
+	}
+
+	/**
+	 * @param mixed $value Value to encode.
+	 */
+	private static function canonicalJson( $value ): string {
+		$normalized = self::sortKeys( $value );
+		$json       = wp_json_encode( $normalized );
+
+		if ( false === $json ) {
+			throw new \RuntimeException( 'Unable to encode package records for checksum.' );
+		}
+
+		return $json;
+	}
+
+	/**
+	 * @param mixed $value Value to normalize.
+	 *
+	 * @return mixed
+	 */
+	private static function sortKeys( $value ) {
+		if ( ! is_array( $value ) ) {
+			return $value;
+		}
+
+		if ( array_keys( $value ) !== range( 0, count( $value ) - 1 ) ) {
+			ksort( $value );
+		}
+
+		foreach ( $value as $key => $child ) {
+			$value[ $key ] = self::sortKeys( $child );
+		}
+
+		return $value;
+	}
+}

src/Package/PackageValidator.php

@@ -51,8 +51,21 @@ final class PackageValidator {
 			$errors[] = 'checksums must be an object.';
 		}
 
+		$record_bucket_errors = array();
+
 		if ( isset( $data['manifest'], $data['records'] ) && is_array( $data['manifest'] ) && is_array( $data['records'] ) ) {
-			$errors = array_merge( $errors, $this->validateRecordBuckets( $data['manifest'], $data['records'] ) );
+			$record_bucket_errors = $this->validateRecordBuckets( $data['manifest'], $data['records'] );
+			$errors               = array_merge( $errors, $record_bucket_errors );
+		}
+
+		if (
+			array() === $record_bucket_errors
+			&& isset( $data['records'], $data['checksums']['records'] )
+			&& is_array( $data['records'] )
+			&& is_string( $data['checksums']['records'] )
+			&& ! PackageChecksum::verifyRecords( $data['records'], $data['checksums']['records'] )
+		) {
+			$errors[] = 'checksums.records does not match records payload.';
 		}
 
 		return array() === $errors ? PackageValidationResult::valid() : PackageValidationResult::invalid( $errors );