Add Justfile and Docker for reproducible builds

[kwsantiago]

Builds depend on local ESP-IDF installation; not reproducible across environments.

• Create Justfile with commands: build, flash, test, fuzz, docs, clean
• Add Dockerfile pinning exact ESP-IDF version and dependencies
• Support Docker and Podman (DOCKER_CMD env var)
• Add just verify-sha to compare build hashes
• Document in REPRODUCIBILITY.md how to verify firmware matches source

[kwsantiago]

Production Hardware Wallet Build Verification Patterns

User-Facing Verification Flow

Production wallets enable users to verify their device runs unmodified code:

# 1. Clone source at tagged release
git clone --branch v1.2.3 https://github.com/org/firmware
cd firmware

# 2. Build in Docker (deterministic environment)
just docker-build

# 3. Compare hash with published release
just verify-release v1.2.3

# Output:
# ✓ Build hash: a1b2c3d4...
# ✓ Matches published release v1.2.3
# ✓ Firmware is reproducible

Dockerfile Best Practices

# Pin exact base image hash, not just tag
FROM espressif/idf:v5.4.0@sha256:abc123...

# Pin all package versions
RUN apt-get update && apt-get install -y \
    python3=3.11.2-1 \
    cmake=3.25.1-1

# Set deterministic timestamp
ENV SOURCE_DATE_EPOCH=0

# Disable parallel builds for determinism
ENV MAKEFLAGS="-j1"

# Copy only necessary files (excludes .git, etc.)
COPY --chown=builder:builder . /build

# Build with reproducible flags
RUN cmake -DCMAKE_BUILD_TYPE=Release \
          -DREPRODUCIBLE=1 \
          ..

Justfile Commands

# Build firmware in Docker
docker-build:
    docker build -t keep-builder .
    docker run --rm -v $(pwd)/output:/output keep-builder

# Verify build matches release
verify-release VERSION:
    #!/usr/bin/env bash
    BUILT_HASH=$(sha256sum output/keep.bin | cut -d' ' -f1)
    RELEASE_HASH=$(curl -s https://releases.example.com/{{VERSION}}/sha256.txt)
    if [ "$BUILT_HASH" = "$RELEASE_HASH" ]; then
        echo "✓ Reproducible: $BUILT_HASH"
    else
        echo "✗ Mismatch!"
        echo "  Built:    $BUILT_HASH"
        echo "  Expected: $RELEASE_HASH"
        exit 1
    fi

# Extract firmware from device and compare
verify-device PORT="/dev/ttyACM0":
    esptool.py --port {{PORT}} read_flash 0x10000 0x300000 device.bin
    DEVICE_HASH=$(sha256sum device.bin | cut -d' ' -f1)
    BUILT_HASH=$(sha256sum output/keep.bin | cut -d' ' -f1)
    # Compare hashes...

# Run reproducibility check in CI
ci-repro:
    just docker-build
    just verify-release $(git describe --tags)

Release Process

1. Tag release in git
2. CI builds firmware in Docker
3. CI computes SHA256 of binary
4. CI signs binary with release key (Add signed bootloader verification chain #83)
5. Publish: binary, signature, SHA256, source tarball
6. Users can reproduce and verify

Timestamp Handling

Ensure all timestamps are deterministic:

# Use git commit timestamp
execute_process(
    COMMAND git log -1 --format=%ct
    OUTPUT_VARIABLE GIT_TIMESTAMP
)
add_definitions(-DBUILD_TIMESTAMP=${GIT_TIMESTAMP})

CI Integration

# .github/workflows/reproducible.yml
name: Reproducible Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build in Docker
        run: just docker-build
      - name: Verify hash
        run: |
          HASH=$(sha256sum output/keep.bin | cut -d' ' -f1)
          echo "build_hash=$HASH" >> $GITHUB_OUTPUT
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: firmware-${{ github.sha }}
          path: output/keep.bin