fix(testing): pin and verify the key archive, stamp the key-set digest (leanEthereum#857)

The key archives were fetched from a mutable release tag with no
integrity check. A re-cut release silently changes every signature
and every state root, since validator public keys are merkleized
into the state. That risk is live: the current release carries a
different test key set than the one committed to this repository.

Changes:

- the download verifies the archive against a pinned SHA-256 before
  extraction; the release tag stays mutable, so the checksum is the
  real pin and a re-cut release fails loudly
- extraction lands in a scratch directory and the extracted key set
  is verified against a pinned digest before replacing the live keys,
  so a rejected archive never destroys a working key set
- a key-set digest function hashes every validator's public keys in
  index order; the fill startup re-downloads when the local keys
  disagree with the pin, and the digest pins encode today's reality:
  the committed test keys and the released prod keys
- every fixture's info block now carries the key-set digest, letting
  consumers detect vectors generated from a different key set

Verified live: downloading the drifted release archive passes the
checksum, fails the digest verification, and leaves the committed
keys untouched.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tcoratger

packages/testing/src/consensus_testing/keys.py

@@ -18,6 +18,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 from collections.abc import Iterator, Mapping
 from pathlib import Path
@@ -121,6 +122,29 @@ def get_keys_directory(scheme_name: str) -> Path:
     return Path(__file__).parent / "test_keys" / f"{scheme_name}_scheme"
 
 
+def compute_key_set_digest(keys_directory: Path) -> str:
+    """
+    Compute the SHA-256 digest identifying a directory's key set.
+
+    Hashes every validator's public keys in ascending index order.
+    Two fills agree on vectors only if they agree on this digest.
+
+    Args:
+        keys_directory: Directory holding per-validator key files.
+
+    Returns:
+        Hex digest prefixed with 0x.
+    """
+    digest = hashlib.sha256()
+    key_files = sorted(keys_directory.glob("*.json"), key=lambda key_file: int(key_file.stem))
+    for key_file in key_files:
+        key_data = json.loads(key_file.read_text())
+        digest.update(key_file.stem.encode())
+        digest.update(bytes.fromhex(key_data["attestation_keypair"]["public_key"]))
+        digest.update(bytes.fromhex(key_data["proposal_keypair"]["public_key"]))
+    return f"0x{digest.hexdigest()}"
+
+
 class XmssKeyManager:
     """
     Stateful manager for XMSS signing in tests.
@@ -146,6 +170,7 @@ class XmssKeyManager:
         "_public_cache",
         "_available_indices",
         "_secret_state",
+        "_key_set_digest",
     )
 
     _cache: ClassVar[dict[str, XmssKeyManager]] = {}
@@ -224,6 +249,9 @@ def __init__(
         # Advanced secret-key state held as live Python objects.
         self._secret_state: dict[tuple[ValidatorIndex, KeyRole], SecretKey] = {}
 
+        # Computed lazily on first request.
+        self._key_set_digest: str | None = None
+
     def _scan_indices(self) -> set[ValidatorIndex]:
         """
         Discover which validator indices have key files on disk.
@@ -328,6 +356,16 @@ def __iter__(self) -> Iterator[ValidatorIndex]:
         """Iterate over validator indices in ascending order."""
         return iter(sorted(self._scan_indices()))
 
+    def key_set_digest(self) -> str:
+        """
+        Return the digest identifying this manager's on-disk key set.
+
+        Computed once and cached for the manager's lifetime.
+        """
+        if self._key_set_digest is None:
+            self._key_set_digest = compute_key_set_digest(self._keys_directory)
+        return self._key_set_digest
+
     def get_public_keys(self, index: ValidatorIndex) -> tuple[PublicKey, PublicKey]:
         """
         Return attestation and proposal public keys without touching secrets.

packages/testing/src/consensus_testing/keys_cli.py

@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import os
 import shutil
 import sys
@@ -27,7 +28,11 @@
 from functools import partial
 from pathlib import Path
 
-from consensus_testing.keys import LEAN_ENV_TO_SCHEMES, get_keys_directory
+from consensus_testing.keys import (
+    LEAN_ENV_TO_SCHEMES,
+    compute_key_set_digest,
+    get_keys_directory,
+)
 from lean_spec.spec.crypto.xmss.containers import ValidatorKeyPair
 from lean_spec.spec.crypto.xmss.interface import GeneralizedXmssScheme
 from lean_spec.spec.forks import Slot
@@ -44,6 +49,31 @@
 Each URL points to a tar.gz containing per-validator JSON files.
 """
 
+PINNED_KEY_ARCHIVE_SHA256 = {
+    "test": "2d616857f4936cde4e2720fa95a76f2644015390f4b8c188acbaa756f521dac8",
+    "prod": "a40aa60fc0c0d1b4c761f19fb1678039400ae318da85f782dd57bc8cc0eb617d",
+}
+"""
+SHA-256 of each scheme's key archive.
+
+The release tag is mutable, so these checksums are the real pin.
+A re-cut release fails the download instead of silently changing vectors.
+Update together with the key-set digests when adopting a new release.
+"""
+
+PINNED_KEY_SET_DIGESTS = {
+    "test": "0x49306dfdb6dddd72afe265ec3b20a1901834dde9b3dfe4fee6b4f7ca58c7aa43",
+    "prod": "0xc2b5fc4c1f1fbc181ddf07db3df985f79e1dcedcfb7df732ef20863d7cbcf491",
+}
+"""
+Expected key-set digest per scheme.
+
+Guards the on-disk keys, which the archive checksum cannot see.
+
+- test: the key set committed to this repository.
+- prod: the key set served by the current release.
+"""
+
 NUM_VALIDATORS: int = 8
 """
 Default number of validator key pairs.
@@ -176,16 +206,46 @@ def download_keys(scheme: str) -> None:
         with urllib.request.urlopen(url) as response, tmp_path.open("wb") as out:
             shutil.copyfileobj(response, out)
 
-        # Remove any existing keys for this scheme before extracting.
-        target_directory = base_directory / f"{scheme}_scheme"
-        if target_directory.exists():
-            shutil.rmtree(target_directory)
-        base_directory.mkdir(parents=True, exist_ok=True)
+        # Verify the archive against the pinned checksum before extracting.
+        # The release tag is mutable, so the checksum is the real pin.
+        with tmp_path.open("rb") as archive_handle:
+            archive_sha256 = hashlib.file_digest(archive_handle, "sha256").hexdigest()
+        if archive_sha256 != PINNED_KEY_ARCHIVE_SHA256[scheme]:
+            raise RuntimeError(
+                f"downloaded {scheme} key archive does not match the pinned checksum\n"
+                f"  expected: {PINNED_KEY_ARCHIVE_SHA256[scheme]}\n"
+                f"  actual:   {archive_sha256}\n"
+                "The release was re-cut upstream. Adopting the new key set requires "
+                "updating the pinned checksum and key-set digest on purpose."
+            )
 
-        # Extract the archive into the base directory.
+        # Extract into a scratch directory and verify there first.
+        # A rejected archive must never destroy working keys.
         # The archive root is the scheme directory itself.
-        with tarfile.open(tmp_path, "r:gz") as tar:
-            tar.extractall(path=base_directory, filter="data")
+        with tempfile.TemporaryDirectory() as scratch_name:
+            scratch_directory = Path(scratch_name)
+            with tarfile.open(tmp_path, "r:gz") as tar:
+                tar.extractall(path=scratch_directory, filter="data")
+
+            # Verify the extracted key set against the pinned digest.
+            # Catches content drift the checksum pin alone would miss.
+            extracted_directory = scratch_directory / f"{scheme}_scheme"
+            extracted_digest = compute_key_set_digest(extracted_directory)
+            if extracted_digest != PINNED_KEY_SET_DIGESTS[scheme]:
+                raise RuntimeError(
+                    f"extracted {scheme} key set does not match the pinned digest\n"
+                    f"  expected: {PINNED_KEY_SET_DIGESTS[scheme]}\n"
+                    f"  actual:   {extracted_digest}\n"
+                    "The archive carries a different key set than the canonical one. "
+                    "For the test scheme, restore the committed keys from version control."
+                )
+
+            # Replace the live key set only after both verifications pass.
+            target_directory = base_directory / f"{scheme}_scheme"
+            if target_directory.exists():
+                shutil.rmtree(target_directory)
+            base_directory.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(extracted_directory), str(target_directory))
 
         print(f"Extracted {scheme} keys to {target_directory}/")
     finally:

packages/testing/src/consensus_testing/test_fixtures/base.py

@@ -8,6 +8,7 @@
 from framework.forks import BaseFork
 from pydantic import Field
 
+from consensus_testing.keys import XmssKeyManager
 from lean_spec.base import CamelModel
 from lean_spec.config import LEAN_ENV
 from lean_spec.spec.forks import RejectionReason
@@ -156,5 +157,9 @@ def fill_info(
         self.info["testId"] = test_id
         self.info["description"] = description
         self.info["fixtureFormat"] = self.format_name
+
+        # Why: consumers can detect vectors generated from a different key set.
+        self.info["keySetDigest"] = XmssKeyManager.shared().key_set_digest()
+
         # Set network field on the fixture itself
         self.network = fork.name()

packages/testing/src/framework/cli/fill.py

@@ -64,15 +64,19 @@ def fill(
 
     # Check and download keys if needed
     # Import here to avoid loading leanSpec modules before LEAN_ENV is set
-    from consensus_testing.keys import get_keys_directory
-    from consensus_testing.keys_cli import download_keys
+    from consensus_testing.keys import compute_key_set_digest, get_keys_directory
+    from consensus_testing.keys_cli import PINNED_KEY_SET_DIGESTS, download_keys
 
     keys_directory = get_keys_directory(scheme.lower())
 
     # Check if keys already exist, if not, download them
     if not (keys_directory.exists() and any(keys_directory.glob("*.json"))):
         click.echo(f"Test keys for '{scheme}' scheme not found. Downloading...")
         download_keys(scheme.lower())
+    # Why: stale or modified local keys would silently change every vector.
+    elif compute_key_set_digest(keys_directory) != PINNED_KEY_SET_DIGESTS[scheme.lower()]:
+        click.echo(f"Local '{scheme}' keys do not match the pinned key set. Re-downloading...")
+        download_keys(scheme.lower())
 
     config_path = Path(__file__).parent / "pytest_ini_files" / "pytest-fill.ini"
     # Find project root by looking for pyproject.toml with [tool.uv.workspace]