feat(storage): enable default CRC32C checksum validation for object downloads

Storage/src/Connection/Rest.php

@@ -27,6 +27,7 @@
 use Google\Cloud\Core\Upload\ResumableUploader;
 use Google\Cloud\Core\Upload\StreamableUploader;
 use Google\Cloud\Core\UriTrait;
+use Google\Cloud\Storage\HashValidatingStream;
 use Google\Cloud\Storage\StorageClient;
 use GuzzleHttp\Exception\RequestException;
 use GuzzleHttp\Psr7\MimeType;
@@ -383,30 +384,91 @@ public function downloadObject(array $args = [])
             }
         };
 
-        $fetchedStream = $this->requestWrapper->send(
+        $response = $this->requestWrapper->send(
             $request,
             $requestOptions
-        )->getBody();
+        );
+        $fetchedStream = $response->getBody();
 
         // If no retry attempt was made, then we can return the stream as is.
         // This is important in the case where downloadObject is called to open
         // the file but not to read from it yet.
         if ($attempt === null) {
-            return $fetchedStream;
+            return $this->maybeWrapWithHashValidatingStream($fetchedStream, $args, $response);
         }
 
         // If our object is a transcoded object, then Range headers are not honoured.
         // That means even if we had a partial download available, the final obj
         // that was fetched will contain the complete object. So, we don't need to copy
         // the partial stream, we can just return the stream we fetched.
         if ($transcodedObj) {
-            return $fetchedStream;
+            return $this->maybeWrapWithHashValidatingStream($fetchedStream, $args, $response);
         }
 
         Utils::copyToStream($fetchedStream, $resultStream);
 
         $resultStream->seek(0);
-        return $resultStream;
+        return $this->maybeWrapWithHashValidatingStream($resultStream, $args, $response);
+    }
+
+    /**
+     * Wrap the download stream in a HashValidatingStream if validation is enabled.
+     */
+    private function maybeWrapWithHashValidatingStream(
+        StreamInterface $stream,
+        array $args,
+        ResponseInterface $response
+    ) {
+        $validate = $args['validate'] ?? 'crc32';
+        if ($validate === false || $validate === 'none') {
+            return $stream;
+        }
+
+        // Skip validation if the user requested a subrange of the object
+        $requestedBytes = $this->getRequestedBytes($args);
+        if ($requestedBytes['startByte'] > 0 || $requestedBytes['endByte'] !== '') {
+            return $stream;
+        }
+
+        // Skip validation if the response status is Partial Content (unless it's a library-driven retry)
+        if ($response->getStatusCode() === 206 && !isset($args['retryHeaders'])) {
+            return $stream;
+        }
+
+        $hashHeader = $response->getHeaderLine('X-Goog-Hash');
+        if (!$hashHeader) {
+            return $stream;
+        }
+
+        $hashes = [];
+        $parts = explode(',', $hashHeader);
+        foreach ($parts as $part) {
+            $kv = explode('=', trim($part), 2);
+            if (count($kv) === 2) {
+                $hashes[$kv[0]] = $kv[1];
+            }
+        }
+
+        $options = [];
+        $crc32cSupported = in_array('crc32c', hash_algos());
+
+        if ($validate === 'md5') {
+            if (isset($hashes['md5'])) {
+                $options['expectedMd5'] = $hashes['md5'];
+            }
+        } elseif ($validate === 'crc32' || $validate === 'crc32c' || $validate === true) {
+            if ($crc32cSupported && isset($hashes['crc32c'])) {
+                $options['expectedCrc32c'] = $hashes['crc32c'];
+            } elseif (isset($hashes['md5'])) {
+                $options['expectedMd5'] = $hashes['md5'];
+            }
+        }
+
+        if (empty($options)) {
+            return $stream;
+        }
+
+        return new HashValidatingStream($stream, $options);
     }
 
     /**
@@ -423,8 +485,12 @@ public function downloadObjectAsync(array $args = [])
         return $this->requestWrapper->sendAsync(
             $request,
             $requestOptions
-        )->then(function (ResponseInterface $response) {
-            return $response->getBody();
+        )->then(function (ResponseInterface $response) use ($args) {
+            return $this->maybeWrapWithHashValidatingStream(
+                $response->getBody(),
+                $args,
+                $response
+            );
         });
     }
 

Storage/src/HashValidatingStream.php

@@ -0,0 +1,176 @@
+<?php
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Storage;
+
+use GuzzleHttp\Psr7\StreamDecoratorTrait;
+use Psr\Http\Message\StreamInterface;
+use RuntimeException;
+use UnexpectedValueException;
+
+/**
+ * A Guzzle stream decorator that computes CRC32C and MD5 hashes on the fly
+ * and validates them when the end of the stream is reached.
+ */
+class HashValidatingStream implements StreamInterface
+{
+    use StreamDecoratorTrait;
+
+    private $stream;
+    private $expectedCrc32c;
+    private $expectedMd5;
+    private $crc32cContext;
+    private $md5Context;
+    private $crc32cEnabled = false;
+    private $md5Enabled = false;
+
+    /**
+     * @param StreamInterface $stream The underlying stream to wrap.
+     * @param array $options {
+     *     Configuration options.
+     *
+     *     @type string $expectedCrc32c Base64-encoded expected CRC32C checksum.
+     *     @type string $expectedMd5 Base64-encoded expected MD5 checksum.
+     * }
+     * @throws RuntimeException If a requested hashing algorithm is not supported on the platform.
+     */
+    public function __construct(StreamInterface $stream, array $options = [])
+    {
+        $this->stream = $stream;
+        $this->expectedCrc32c = $options['expectedCrc32c'] ?? null;
+        $this->expectedMd5 = $options['expectedMd5'] ?? null;
+
+        if ($this->expectedCrc32c !== null) {
+            if (!in_array('crc32c', hash_algos())) {
+                throw new RuntimeException('CRC32C hashing algorithm is not supported on this platform.');
+            }
+            $this->crc32cContext = hash_init('crc32c');
+            $this->crc32cEnabled = true;
+        }
+
+        if ($this->expectedMd5 !== null) {
+            $this->md5Context = hash_init('md5');
+            $this->md5Enabled = true;
+        }
+    }
+
+    /**
+     * Validating streams are not seekable since hash calculations are done on-the-fly.
+     *
+     * @return bool
+     */
+    public function isSeekable(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Seek operations are not supported on validating streams.
+     *
+     * @param int $offset
+     * @param int $whence
+     * @throws RuntimeException
+     */
+    public function seek($offset, $whence = SEEK_SET): void
+    {
+        throw new RuntimeException('Seeking is not supported on a validating stream.');
+    }
+
+    /**
+     * Read from the stream and update hash calculations.
+     *
+     * @param int $length
+     * @return string
+     */
+    public function read($length): string
+    {
+        $data = $this->stream->read($length);
+        $this->updateHashes($data);
+
+        if ($this->stream->eof()) {
+            $this->validate();
+        }
+
+        return $data;
+    }
+
+    /**
+     * Get the entire remaining contents of the stream and validate.
+     *
+     * @return string
+     */
+    public function getContents(): string
+    {
+        $data = $this->stream->getContents();
+        $this->updateHashes($data);
+        $this->validate();
+        return $data;
+    }
+
+    /**
+     * Update hash contexts with the new chunk of data.
+     */
+    private function updateHashes(string $data)
+    {
+        if ($data === '') {
+            return;
+        }
+
+        if ($this->crc32cEnabled) {
+            hash_update($this->crc32cContext, $data);
+        }
+
+        if ($this->md5Enabled) {
+            hash_update($this->md5Context, $data);
+        }
+    }
+
+    /**
+     * Validate the accumulated checksums against expected values.
+     *
+     * @throws UnexpectedValueException If checksum validation fails.
+     */
+    private function validate()
+    {
+        if ($this->crc32cEnabled) {
+            $crc32cHash = hash_final($this->crc32cContext, true);
+            $calculatedCrc32c = base64_encode($crc32cHash);
+            $this->crc32cEnabled = false; // Prevent double validation
+            if ($calculatedCrc32c !== $this->expectedCrc32c) {
+                throw new UnexpectedValueException(sprintf(
+                    'CRC32C checksum mismatch. Expected: %s, Calculated: %s',
+                    $this->expectedCrc32c,
+                    $calculatedCrc32c
+                ));
+            }
+        }
+
+        if ($this->md5Enabled) {
+            $md5Hash = hash_final($this->md5Context, true);
+            $calculatedMd5 = base64_encode($md5Hash);
+            $this->md5Enabled = false; // Prevent double validation
+
+            if ($calculatedMd5 !== $this->expectedMd5) {
+                throw new UnexpectedValueException(sprintf(
+                    'MD5 checksum mismatch. Expected: %s, Calculated: %s',
+                    $this->expectedMd5,
+                    $calculatedMd5
+                ));
+            }
+        }
+    }
+}

Storage/tests/System/ManageObjectsTest.php

@@ -832,6 +832,72 @@ public function testStringNormalization()
         }
     }
 
+    public function testDownloadsWithDefaultCrc32cValidationSuccess()
+    {
+        $object = self::$bucket->upload('system-test-data', ['name' => uniqid(self::TESTING_PREFIX)]);
+
+        // Automatic CRC32C validation runs under the hood
+        $content = $object->downloadAsString();
+        $this->assertEquals('system-test-data', $content);
+
+        $object->delete();
+    }
+
+    public function testDownloadsWithExplicitMd5ValidationSuccess()
+    {
+        $object = self::$bucket->upload('system-test-data', ['name' => uniqid(self::TESTING_PREFIX)]);
+
+        // Explicitly opt-in to MD5 validation
+        $content = $object->downloadAsString(['validate' => 'md5']);
+        $this->assertEquals('system-test-data', $content);
+
+        $object->delete();
+    }
+
+    public function testDownloadsWithValidationDisabledSuccess()
+    {
+        $object = self::$bucket->upload('system-test-data', ['name' => uniqid(self::TESTING_PREFIX)]);
+
+        // Explicitly disable validation
+        $content = $object->downloadAsString(['validate' => false]);
+        $this->assertEquals('system-test-data', $content);
+
+        $object->delete();
+    }
+
+    public function testDownloadsWithRangeBypassesValidation()
+    {
+        $data = 'system-test-range-data';
+        $object = self::$bucket->upload($data, ['name' => uniqid(self::TESTING_PREFIX)]);
+
+        // Default validate is 'crc32', but we pass a Range header inside restOptions.
+        // This should successfully download the slice 'system' without throwing a mismatch exception.
+        $content = $object->downloadAsString([
+            'restOptions' => [
+                'headers' => [
+                    'Range' => 'bytes=0-5'
+                ]
+            ]
+        ]);
+        $this->assertEquals('system', $content);
+
+        $object->delete();
+    }
+
+    public function testDownloadToFileWithDefaultValidationSuccess()
+    {
+        $data = 'system-test-to-file-data';
+        $object = self::$bucket->upload($data, ['name' => uniqid(self::TESTING_PREFIX)]);
+
+        $tempFile = tempnam(sys_get_temp_dir(), 'gcs-test');
+        $object->downloadToFile($tempFile);
+
+        $this->assertEquals($data, file_get_contents($tempFile));
+
+        unlink($tempFile);
+        $object->delete();
+    }
+
     /**
      * Asserts that a provided StorageObject exists.
      *