test: make authoritative transaction fixtures hermetic

Author: BitHighlander

.github/workflows/ci.yml

@@ -76,6 +76,9 @@ jobs:
             tests/test_clearsign_abi.py \
             tests/test_token_table_generators.py
 
+      - name: Verify offline transaction fixture manifest
+        run: python tests/tx_fixture_manifest.py --check
+
       - name: Lint summary
         run: |
           echo "## 🔑 KeepKey python-keepkey — Lint" >> "$GITHUB_STEP_SUMMARY"
@@ -86,6 +89,10 @@ jobs:
           echo "| Zcash PCZT contract | ✅ PASS |" >> "$GITHUB_STEP_SUMMARY"
           echo "| ABI encoder | ✅ PASS |" >> "$GITHUB_STEP_SUMMARY"
           echo "| Token-table generators | ✅ PASS |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Offline fixture integrity | ✅ PASS |" >> "$GITHUB_STEP_SUMMARY"
+          FIXTURE_SHA=$(sha256sum tests/txcache/manifest.json | cut -d' ' -f1)
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Fixture manifest SHA-256: `$FIXTURE_SHA`" >> "$GITHUB_STEP_SUMMARY"
 
   # ═══════════════════════════════════════════════════════════
   # STAGE 2: TEST — pull published emulator, run pytest
@@ -245,15 +252,27 @@ jobs:
           # firmware and they resolve; run them standalone and they fail
           # claiming the sources are missing.
           cd keepkey-firmware/deps/python-keepkey/tests
+          python tx_fixture_manifest.py --check
+          sudo iptables -I OUTPUT 1 ! -o lo -m conntrack --ctstate NEW -j REJECT
+          cleanup_network_gate() {
+            sudo iptables -D OUTPUT ! -o lo -m conntrack --ctstate NEW -j REJECT
+          }
+          trap cleanup_network_gate EXIT
           pytest -v --junitxml=junit.xml 2>&1 | tee pytest-output.txt
           echo "${PIPESTATUS[0]}" > status
 
       - name: Test summary
         if: always()
         run: |
           XML="keepkey-firmware/deps/python-keepkey/tests/junit.xml"
+          MANIFEST="keepkey-firmware/deps/python-keepkey/tests/txcache/manifest.json"
           echo "## 🔑 KeepKey python-keepkey — Integration Tests" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
+          if [ -f "$MANIFEST" ]; then
+            FIXTURE_SHA=$(sha256sum "$MANIFEST" | cut -d' ' -f1)
+            echo "Fixture manifest SHA-256: `$FIXTURE_SHA`" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+          fi
 
           if [ ! -f "$XML" ]; then
             echo "❌ **No test results found** — suite may have crashed before completion." >> "$GITHUB_STEP_SUMMARY"
@@ -448,17 +467,29 @@ jobs:
           KK_UDP_TIMEOUT: "45"
         run: |
           cd keepkey-firmware/deps/python-keepkey/tests
+          python tx_fixture_manifest.py --check
+          sudo iptables -I OUTPUT 1 ! -o lo -m conntrack --ctstate NEW -j REJECT
+          cleanup_network_gate() {
+            sudo iptables -D OUTPUT ! -o lo -m conntrack --ctstate NEW -j REJECT
+          }
+          trap cleanup_network_gate EXIT
           pytest -v --junitxml=junit-rc18.xml 2>&1 | tee pytest-rc18-output.txt
           echo "${PIPESTATUS[0]}" > status-rc18
 
       - name: RC18 summary
         if: always()
         run: |
           XML="keepkey-firmware/deps/python-keepkey/tests/junit-rc18.xml"
+          MANIFEST="keepkey-firmware/deps/python-keepkey/tests/txcache/manifest.json"
           echo "## 🔑 python-keepkey — RC18 / 7.15.0" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
           echo "Blocking release-target compatibility gate." >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
+          if [ -f "$MANIFEST" ]; then
+            FIXTURE_SHA=$(sha256sum "$MANIFEST" | cut -d' ' -f1)
+            echo "Fixture manifest SHA-256: `$FIXTURE_SHA`" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+          fi
           if [ ! -f "$XML" ]; then
             echo "❌ **No test results** — the suite crashed before completion." >> "$GITHUB_STEP_SUMMARY"
           else
@@ -657,6 +688,12 @@ jobs:
           KK_UDP_TIMEOUT: "45"
         run: |
           cd keepkey-firmware/deps/python-keepkey/tests
+          python tx_fixture_manifest.py --check
+          sudo iptables -I OUTPUT 1 ! -o lo -m conntrack --ctstate NEW -j REJECT
+          cleanup_network_gate() {
+            sudo iptables -D OUTPUT ! -o lo -m conntrack --ctstate NEW -j REJECT
+          }
+          trap cleanup_network_gate EXIT
           pytest -v --junitxml=junit-btc.xml test_msg_bitcoin_only_variant.py \
             2>&1 | tee pytest-btc-output.txt
           echo "${PIPESTATUS[0]}" > status-btc
@@ -693,8 +730,14 @@ jobs:
         if: always()
         run: |
           XML="keepkey-firmware/deps/python-keepkey/tests/junit-btc.xml"
+          MANIFEST="keepkey-firmware/deps/python-keepkey/tests/txcache/manifest.json"
           echo "## 🔑 KeepKey python-keepkey — Bitcoin-only product boundary" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
+          if [ -f "$MANIFEST" ]; then
+            FIXTURE_SHA=$(sha256sum "$MANIFEST" | cut -d' ' -f1)
+            echo "Fixture manifest SHA-256: `$FIXTURE_SHA`" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+          fi
           if [ ! -f "$XML" ]; then
             echo "❌ **No test results found** — suite may have crashed." >> "$GITHUB_STEP_SUMMARY"
           else

docs/handoff-python-test-hermeticity.md

@@ -0,0 +1,114 @@
+# Handoff: authoritative python-keepkey tests must be fully offline
+
+## Non-negotiable release rule
+
+The authoritative Python suite must never depend on an explorer, RPC service,
+DNS, TLS, remote retention, or the caller's working directory. A missing input
+is a named fixture failure, not permission to fetch mutable data. Optional live
+compatibility probes may exist only in a separate, non-authoritative workflow;
+they must never contribute release JUnit, report totals, artifacts, or a
+GO/NO-GO decision.
+
+This work must be ported to the upstream keepkey/python-keepkey repository by
+reviewed PR. The fork implementation is the reference; no upstream branch was
+modified while preparing it.
+
+## Fork reference implementation
+
+Branch: BitHighlander/python-keepkey:fix/hermetic-release-tests
+
+The implementation is intentionally isolated from the 7.14.2 Solana/TON
+disclosure and PDF-report branches. Reconcile those branches only after this
+one is reviewed, then repin firmware to the durable Python merge commit.
+
+Affected surfaces:
+
+- keepkeylib/tx_api.py adds configure_offline_fixtures(path), resolves a fixed
+  absolute fixture root, and raises OfflineFixtureError naming the complete key
+  instead of falling through to HTTP.
+- tests/common.py makes tests/txcache module-relative and enables offline-only
+  mode for every KeepKeyTest.
+- tests/conftest.py rejects external DNS, socket, and HTTP access per test while
+  permitting only loopback emulator traffic and Unix-domain sockets.
+- .github/workflows/ci.yml checks fixture integrity, adds a kernel outbound-new-
+  connection deny rule during authoritative pytest, and records the manifest
+  SHA-256 in every summary.
+- tests/tx_fixture_manifest.py and tests/test_tx_fixture_integrity.py account
+  for every fixture, reconstruct canonical transactions, recompute every txid,
+  test cwd independence and fail-closed misses, and statically reject new
+  network-capable helpers even when pytest would not collect them.
+- tests/test_sign_typed_data.py and tests/test_verify_typed_data.py resolve JSON
+  fixtures from their module directory.
+- The unused tests/zcash_rpc.py live-node helper was removed. It was not
+  collected by pytest, contained a fixed private-node endpoint and embedded
+  RPC credentials, and had no place in authoritative test infrastructure.
+
+## Fixture rules
+
+Each manifest entry records:
+
+- source network and transaction ID;
+- response filename and SHA-256;
+- raw-response filename and SHA-256 where Zcash JoinSplit reconstruction needs
+  it;
+- canonical serialized bytes and their SHA-256;
+- transaction-ID algorithm;
+- every authoritative test file that references it.
+
+Bitcoin, Testnet, Bitcoin Gold, Dash, and pre-Overwinter Zcash transaction IDs
+use double SHA-256. Groestlcoin transaction IDs use one SHA-256 round, matching
+the current Groestlcoin Core HashWriter::GetHash() implementation:
+https://github.com/Groestlcoin/groestlcoin/blob/master/src/hash.h
+
+Do not accept a fixture merely because its JSON txid field agrees with its
+filename. The canonical serialization must independently hash to the same ID.
+
+The fork audit found and corrected one latent synthetic-fixture defect:
+6e320339...a6ee37 advertised a txid computed with the null outpoint index
+0xffffffff, while its decoded fixture said index 0. The corrected decoded
+fixture now agrees with its canonical bytes and txid. Two cache files with no
+authoritative references were removed.
+
+## Required upstream migration
+
+1. Port the fork commits without weakening the fail-closed behavior.
+2. Preserve public live TxApi clients for non-test callers, but ensure
+   authoritative tests enable offline-only mode before constructing clients.
+3. Run python tests/tx_fixture_manifest.py --check as an early CI gate.
+4. Run all authoritative emulator suites with both the pytest network-denial
+   control and OS-level outbound-new-connection denial.
+5. Treat a new transaction input as a fixture change requiring canonical-byte,
+   response-hash, txid, reference, and manifest review.
+6. Feed the exact manifest SHA-256 into the release evidence/report pipeline.
+   The report job must fail if the manifest is missing, stale, mutated, or not
+   listed in provenance.
+7. Keep optional explorer/RPC probes in a separately named workflow that
+   cannot satisfy or influence a required release check. Store them outside
+   tests/ and obtain endpoints and credentials from the workflow environment;
+   never commit either value.
+
+## Acceptance criteria
+
+- A clean checkout with an empty user cache runs the authoritative suite while
+  outbound networking is denied.
+- Zero DNS, external socket, HTTP, explorer, or RPC attempt occurs.
+- A missing network/txid fixture fails immediately and names the requesting
+  key; no HTTP fallback is possible.
+- Running from the repository root and from tests/ produces identical test
+  counts, statuses, signed outputs, and manifest digest.
+- Every fixture source is content-hashed, every canonical transaction is
+  retained, every txid is independently recomputed, and every fixture has at
+  least one authoritative test reference.
+- No test is skipped or xfailed because a live service or fixture is
+  unavailable.
+- Full Python JUnit is green before the Python commit is eligible for a
+  firmware submodule repin.
+- The release report and provenance manifest contain the exact transaction
+  fixture-manifest SHA-256.
+
+## Upstream handback
+
+Return the upstream PR URL, exact head and merge commits, full offline JUnit
+totals, fixture-manifest SHA-256, the network-denial result, CI run URL, and
+git diff --check. Call out any historical response that cannot be reconstructed
+exactly; do not silently replace, weaken, delete, or skip it.

keepkeylib/tx_api.py

@@ -21,11 +21,24 @@
 from decimal import Decimal
 import requests
 import json
+import os
 import struct
 
 from . import types_pb2 as proto_types
 
 cache_dir = None
+offline_only = False
+
+
+class OfflineFixtureError(Exception):
+    """An authoritative transaction fixture is missing or malformed."""
+
+
+def configure_offline_fixtures(path):
+    """Make transaction lookup fail closed against a fixed fixture tree."""
+    global cache_dir, offline_only
+    cache_dir = os.path.abspath(path)
+    offline_only = True
 
 
 def pack_varint(n):
@@ -46,15 +59,38 @@ def __init__(self, network, url):
         self.url = url
 
     def fetch_json(self, url, resource, resourceid):
-        global cache_dir
+        global cache_dir, offline_only
+        cache_file = None
         if cache_dir:
-            cache_file = '%s/%s_%s_%s.json' % (cache_dir, self.network, resource, resourceid)
-            try: # looking into cache first
+            fixture_name = '%s_%s_%s.json' % (
+                self.network, resource, resourceid)
+            if os.path.basename(fixture_name) != fixture_name:
+                raise OfflineFixtureError(
+                    'Invalid fixture key: network=%s resource=%s id=%s' %
+                    (self.network, resource, resourceid))
+            cache_file = os.path.join(cache_dir, fixture_name)
+            try:  # looking into cache first
                 with open(cache_file) as f:
-                    j = json.load(f)
-                    return j
-            except:
-                pass
+                    return json.load(f)
+            except OSError as exc:
+                if offline_only:
+                    raise OfflineFixtureError(
+                        'Missing offline transaction fixture: '
+                        'network=%s resource=%s id=%s path=%s' %
+                        (self.network, resource, resourceid, cache_file)
+                    ) from exc
+            except (TypeError, ValueError) as exc:
+                if offline_only:
+                    raise OfflineFixtureError(
+                        'Invalid offline transaction fixture: '
+                        'network=%s resource=%s id=%s path=%s' %
+                        (self.network, resource, resourceid, cache_file)
+                    ) from exc
+        if offline_only:
+            raise OfflineFixtureError(
+                'Offline transaction fixtures are enabled without a fixture '
+                'directory: network=%s resource=%s id=%s' %
+                (self.network, resource, resourceid))
         try:
             # print('request %s/%s/%s' % (self.url, resource, resourceid))
             r = requests.get('%s/%s/%s' % (self.url, resource, resourceid), headers={'User-agent': 'Mozilla/5.0'})

tests/common.py

@@ -30,7 +30,9 @@
 from keepkeylib.client import KeepKeyClient, KeepKeyDebuglinkClient, KeepKeyDebuglinkClientVerbose
 from keepkeylib import tx_api
 
-tx_api.cache_dir = 'txcache'
+TX_FIXTURE_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              'txcache')
+tx_api.configure_offline_fixtures(TX_FIXTURE_DIR)
 VERBOSE = False
 
 class KeepKeyTest(unittest.TestCase):

tests/conftest.py

@@ -12,7 +12,12 @@
 import pytest
 import os
 import glob
+import ipaddress
+import socket
 import sys
+from urllib.parse import urlparse
+
+import requests
 
 if os.environ.get('KEEPKEY_SCREENSHOT') == '1':
     import common
@@ -51,6 +56,73 @@ def _patched_setUp(self):
     common.KeepKeyTest.setUp = _patched_setUp
 
 
+def _is_loopback_address(address):
+    """Allow emulator traffic while rejecting every external destination."""
+    if not isinstance(address, tuple):
+        # Unix-domain sockets are local by construction.
+        return True
+    host = address[0]
+    if isinstance(host, bytes):
+        host = host.decode('ascii')
+    if host == 'localhost':
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except (TypeError, ValueError):
+        return False
+
+
+@pytest.fixture(autouse=True)
+def deny_external_network(monkeypatch, request):
+    """Fail an authoritative test at its first non-loopback network access."""
+    nodeid = request.node.nodeid
+    original_getaddrinfo = socket.getaddrinfo
+    original_connect = socket.socket.connect
+    original_connect_ex = socket.socket.connect_ex
+    original_sendto = socket.socket.sendto
+    original_request = requests.sessions.Session.request
+
+    def denied(destination):
+        raise AssertionError(
+            'authoritative test attempted external network access: '
+            'test=%s destination=%r' % (nodeid, destination))
+
+    def guarded_getaddrinfo(host, *args, **kwargs):
+        if not _is_loopback_address((host, 0)):
+            denied(host)
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    def guarded_connect(sock, address):
+        if not _is_loopback_address(address):
+            denied(address)
+        return original_connect(sock, address)
+
+    def guarded_connect_ex(sock, address):
+        if not _is_loopback_address(address):
+            denied(address)
+        return original_connect_ex(sock, address)
+
+    def guarded_sendto(sock, data, *args):
+        address = args[-1]
+        if not _is_loopback_address(address):
+            denied(address)
+        return original_sendto(sock, data, *args)
+
+    def guarded_request(session, method, url, *args, **kwargs):
+        hostname = urlparse(url).hostname
+        if not _is_loopback_address((hostname, 0)):
+            raise AssertionError(
+                'authoritative test attempted HTTP access: test=%s method=%s '
+                'url=%s' % (nodeid, method, url))
+        return original_request(session, method, url, *args, **kwargs)
+
+    monkeypatch.setattr(socket, 'getaddrinfo', guarded_getaddrinfo)
+    monkeypatch.setattr(socket.socket, 'connect', guarded_connect)
+    monkeypatch.setattr(socket.socket, 'connect_ex', guarded_connect_ex)
+    monkeypatch.setattr(socket.socket, 'sendto', guarded_sendto)
+    monkeypatch.setattr(requests.sessions.Session, 'request', guarded_request)
+
+
 def pytest_sessionfinish(session, exitstatus):
     """Fail-fast: if screenshots were requested but none captured, fail the session."""
     if os.environ.get('KEEPKEY_SCREENSHOT') != '1':