Merge branch 'develop' into release/7.14.2-rc31

Three conflicts, plus one semantic clash the auto-merge hid.

.github/workflows/ci.yml -- took develop's pipeline (PR #474 cut it from
~7:20 to ~2:00 and folded check-submodules, build-emulator, unit-tests and
python-integration-tests into build-and-test) and re-applied what this branch
adds on top:

  - permissions: contents: read at the workflow level. develop has no
    permissions block, so code-scanning rule
    actions/missing-workflow-permissions had one alert open per job.
  - generate-test-report restored as its OWN job rather than folded into
    build-and-test. develop's fold is correct for develop's report script,
    which only needs directories that job already has. This branch's
    generate-test-report.py also consumes test-reports/dylib-junit.xml and the
    ARM manifest -- produced by other jobs, on other runners -- and fail()s
    hard when either is missing. Folded, the report could never succeed.
  - the report's provenance env (both source SHAs, run URL, both PR URLs).
    develop passes only KK_BUILD_LABEL, which this branch's script does not
    read; the fields it does read are release gates for 7.14.2.
  - the report artifact is a directory again. The script emits
    test-report/test-report.pdf beside test-report-manifest.json and
    test-report.pdf.sha256; develop uploaded a bare test-report.pdf, which
    would have found no files.
  - release-evidence-gate, rewired to develop's folded job names, so a release
    still has one required check that every evidence-producing job succeeded.

.gitleaks.toml -- union. Kept develop's header and its docs-SHA allowlist,
which is broader than and subsumes this branch's python-keepkey-pin rule, plus
this branch's U2F/vendored-deps allowlist and the note recording why no
first-party test tree is exempted.

scripts/emulator/python-keepkey.Dockerfile -- took develop's parameterised
deps-stage version wholesale.

scripts/emulator/Dockerfile did NOT conflict: only this branch had changed it
(base -> digest), so git kept the digest silently. That defeats develop's GHCR
mirror, which tags the mirrored image as kktech/firmware:v15 -- a digest FROM
ignores that tag and pulls from Docker Hub on the heaviest job in the run.
Parameterised it the way python-keepkey.Dockerfile already is, defaulting to
the digest so a release build still names an immutable base, with CI passing
the resolved mirror. kktech/firmware:v15 resolves to exactly that digest today.

Verified: emulator image builds both with the default and with an explicit
--build-arg; 153/153 unit tests pass; gitleaks 8.30.1 finds no leaks with the
merged config; clang-format clean.

Author: pastaghost

.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# Copilot code review instructions
+
+How reviews on this repository should be conducted. These govern the review
+process itself, not what counts as good code.
+
+## Report everything in one pass
+
+Report every finding you have in a single review. Do not hold findings back for a
+later round.
+
+- Review the complete diff — every changed file, every changed hunk. Do not stop
+  partway through.
+- Finding several problems early is not a reason to end the review. It is a reason
+  to keep going.
+- Do not sample. If a file has twelve problems, report twelve.
+- Comment on every instance of a repeated problem, not just the first. If the same
+  mistake appears in six places, mark all six — the author fixes what is marked, so
+  "and similar issues elsewhere" leaves five defects in the branch.
+
+## Include minor and uncertain findings
+
+Do not filter down to only the findings you are most confident about.
+
+- Report low-severity and minor issues alongside significant ones.
+- Report a finding you are less than certain about, and say plainly what you are
+  unsure of. A finding the author dismisses in ten seconds costs far less than an
+  entire extra review cycle.
+- Label each finding's severity so the author can triage quickly instead of having
+  to weigh every comment equally.
+
+## Converge in as few rounds as possible
+
+Every additional review round costs the author a full cycle. Target:
+
+- **One round** — ideal. Everything surfaced on the first review.
+- **Two or three rounds** — acceptable.
+- **Five rounds** — the absolute ceiling.
+
+A later round should raise only problems introduced by the previous round's fixes.
+A problem that was present in the original diff and went unmentioned until round
+three is a review failure, not a thorough review.
+
+## Do not trade thoroughness for brevity
+
+None of the above is a reason to scrutinize less carefully. The goal is more
+findings per review, not faster reviews. Depth of analysis stays the same; what
+changes is that all of it arrives at once.

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+# Mirrors the firmware build base image from Docker Hub into this org's GHCR.
+#
+# Why: every CI job that compiles anything starts by pulling ~650 MB of base
+# image. Served from Docker Hub that measured ~34s per job; GHCR serves it to
+# GitHub-hosted runners over the same network and does not apply Docker Hub's
+# anonymous pull limits.
+#
+# CI treats the mirror as optional -- ci.yml falls back to Docker Hub with a
+# warning if the pull fails -- so this workflow never becomes a hard
+# dependency of the build. Run it once to populate the mirror, and again
+# whenever BASE_IMAGE in ci.yml is bumped.
+name: Mirror base image
+
+on:
+  workflow_dispatch:
+    inputs:
+      source_image:
+        description: 'Docker Hub image to mirror (must match BASE_IMAGE in ci.yml)'
+        required: true
+        type: string
+        default: 'kktech/firmware:v15'
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Pull, tag and push
+        env:
+          SOURCE: ${{ inputs.source_image }}
+        run: |
+          set -euo pipefail
+
+          # The source is constrained to the upstream base image, and the
+          # destination name is fixed rather than derived from the input.
+          #
+          # Both matter. ci.yml pulls BASE_IMAGE_MIRROR and builds firmware
+          # from it, so whatever lands at ghcr.io/<owner>/firmware:<tag> is
+          # trusted by every subsequent build. Deriving the destination from
+          # the input -- as this previously did, via ${SOURCE##*/} -- meant a
+          # dispatch of `anyone/firmware:v15` would resolve to that same
+          # destination and overwrite the image CI trusts. Dispatch needs
+          # write access, but "a writer can typo" and "a writer can silently
+          # replace the firmware build base" are different blast radii.
+          if [[ ! "${SOURCE}" =~ ^kktech/firmware:[A-Za-z0-9._-]+$ ]]; then
+            echo "::error::refusing to mirror '${SOURCE}'. This workflow only mirrors kktech/firmware:<tag>, because ci.yml builds firmware from whatever it publishes."
+            exit 1
+          fi
+
+          TAG="${SOURCE##*:}"
+          DEST="ghcr.io/${{ github.repository_owner }}/firmware:${TAG}"
+          echo "mirroring ${SOURCE} -> ${DEST}"
+          docker pull "${SOURCE}"
+          docker tag  "${SOURCE}" "${DEST}"
+          docker push "${DEST}"
+          echo "::notice::Mirrored ${SOURCE} to ${DEST}"
+          echo "Set BASE_IMAGE_MIRROR in ci.yml to ${DEST} if it differs."

.github/workflows/mirror-base-image.yml

@@ -3,3 +3,8 @@ build
 .DS_Store
 .vscode/
 
+.claude/
+
+# cppcheck output (static-analysis writes this at repo root in CI)
+cppcheck_report.txt
+cppcheck_annotations.txt

.gitignore

@@ -1,17 +1,24 @@
-title = "KeepKey firmware gitleaks configuration"
+# gitleaks configuration for keepkey-firmware
+#
+# Extends the stock gitleaks rule set — every default rule stays active. This
+# file only adds narrowly-scoped allowlists for false positives that recur
+# across commits, which .gitleaksignore cannot express: its entries are keyed
+# by commit SHA, so a rebased, cherry-picked, or merged commit reintroduces the
+# same finding under a new fingerprint. Prefer .gitleaksignore for a genuine
+# one-off; add here only when the same content keeps coming back.
 
 [extend]
 useDefault = true
 
 # Published U2F attestation material and vendored third-party code.
 #
 # Deliberately NOT allowlisted: any first-party test tree. An earlier revision
-# carried '''^tests/''' here, which turned off secret detection for every
-# first-party test present or future -- a real credential committed under it
-# would have passed CI. No such directory exists in this repository, so the
-# entry exempted nothing and only stood ready to exempt something later. If a
-# fixture ever does trip a rule, allowlist that path or its fingerprint, not
-# the tree above it.
+# of this branch carried '''^tests/''' here, which turned off secret detection
+# for every first-party test present or future -- a real credential committed
+# under it would have passed CI. No such directory exists in this repository,
+# so the entry exempted nothing and only stood ready to exempt something later.
+# If a fixture ever does trip a rule, allowlist that path or its fingerprint,
+# not the tree above it.
 [[allowlists]]
 description = "Public device material and vendored third-party code"
 paths = [
@@ -20,10 +27,17 @@ paths = [
   '''^deps/''',
 ]
 
+# Release/security docs record the exact submodule commits a build pins, e.g.
+#   - python-keepkey: `c406a1ba9120da410c356dbff7f4d4bd1e1758fa`;
+# A 40-char lowercase hex git SHA has enough entropy to trip generic-api-key.
+# Scoped with condition = "AND" so this only exempts SHA-shaped strings inside
+# markdown docs — a real credential in docs/ is still reported.
+#
+# This supersedes an earlier, narrower rule on the release branch that matched
+# only python-keepkey pins under generic-api-key; every string that one
+# exempted is a subset of this one.
 [[allowlists]]
-description = "Documented python-keepkey commit pins"
-targetRules = ["generic-api-key"]
+description = "Git commit SHAs quoted in markdown docs"
 condition = "AND"
-paths = ['''^docs/''']
-regexes = ['''python-keepkey[^\n]{0,16}`[0-9a-f]{40}`''']
-regexTarget = "match"
+paths = ['''(^|/)docs/.*\.md$''']
+regexes = ['''\b[0-9a-f]{40}\b''']

.gitleaks.toml

@@ -1,4 +1,14 @@
-FROM kktech/firmware@sha256:7438e53933d47d53157ed6d96d864cb208597e62dce26235ace09d1063427fa2
+# Parameterised for the same reason as python-keepkey.Dockerfile: CI resolves
+# the base through a GHCR mirror and must be able to point FROM at it, while a
+# plain `docker build` keeps working unchanged.
+#
+# The DEFAULT is a digest, not the :v15 tag develop carries. A release build
+# has to name an immutable base -- kktech/firmware:v15 resolves to exactly this
+# digest today, but a tag can be moved and a signed release should not depend
+# on that. CI overrides it with the mirror it resolved, which is the same image
+# either way.
+ARG BASE_IMAGE=kktech/firmware@sha256:7438e53933d47d53157ed6d96d864cb208597e62dce26235ace09d1063427fa2
+FROM ${BASE_IMAGE}
 
 WORKDIR /kkemu
 COPY ./ /kkemu

scripts/emulator/Dockerfile

@@ -13,11 +13,22 @@ services:
       - "127.0.0.1:5000:5000"
     healthcheck:
       test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:5000/health')\" || exit 1"]
-      interval: 3s
+      # The emulator is listening well inside a second; a 3s interval meant
+      # the integration suite sat waiting on poll granularity, not on the
+      # service. retries is raised alongside so shortening the interval does
+      # not also shorten how long a slow start is tolerated -- a failing check
+      # can burn up to `timeout` before the next `interval`, so the ceiling is
+      # roughly start_period + retries * (timeout + interval), not
+      # retries * interval.
+      interval: 1s
       timeout: 3s
-      retries: 20
-      start_period: 10s
+      retries: 40
+      start_period: 3s
   python-keepkey:
+    # Named so CI can build it once (`docker compose build python-keepkey`)
+    # and then `up` without --build, which would otherwise also force a
+    # rebuild of kkemu — the expensive one.
+    image: kktech/kkemu-tests:latest
     build:
       context: '../../'
       dockerfile: 'scripts/emulator/python-keepkey.Dockerfile'
@@ -29,6 +40,9 @@ services:
       kkemu:
         condition: service_healthy
   firmware-unit:
+    # Local-dev convenience only — CI runs `make xunit` directly against the
+    # image it just built, rather than paying for a second compose build.
+    image: kktech/kkemu:latest
     build:
       context: '../../'
       dockerfile: 'scripts/emulator/Dockerfile'

scripts/emulator/docker-compose.yml

@@ -1,4 +1,13 @@
-FROM kktech/firmware@sha256:7438e53933d47d53157ed6d96d864cb208597e62dce26235ace09d1063427fa2
+# Split into a `deps` stage on purpose. The dependency layers below are
+# stable across commits and worth caching; the COPY layer beneath them ships
+# the whole build context and is invalidated by every commit, so exporting it
+# to a layer cache is pure cost with no possible hit. CI caches `deps` only.
+# Parameterised because buildx's docker-container driver resolves FROM
+# against a registry rather than the local daemon, so CI must be able to
+# point it at the GHCR mirror explicitly. The default keeps plain
+# `docker build` and local use working unchanged.
+ARG BASE_IMAGE=kktech/firmware:v15
+FROM ${BASE_IMAGE} AS deps
 
 # Extra Python deps needed by tests that aren't in the shared base image.
 # - rlp + eth-keys + eth-utils: build the canonical EIP-1559 type-2 pre-image
@@ -10,6 +19,8 @@ FROM kktech/firmware@sha256:7438e53933d47d53157ed6d96d864cb208597e62dce26235ace0
 RUN apk add --no-cache python3-dev gcc musl-dev
 RUN python3 -m pip install --no-cache-dir rlp eth-keys eth-utils pycryptodome
 
+FROM deps
+
 WORKDIR /kkemu
 COPY ./ /kkemu