Feature add reproducible build steps (#19)

* reproducible build first step * update xcode version for CI runner * update README.md
2026-04-08 20:53:52 -04:00 · 2026-04-08 20:53:52 -04:00 · 3c3478b7e8
commit 3c3478b7e8
parent 50f870faa4
13 changed files with 701 additions and 168 deletions
--- a/.github/workflows/Xcode-build-analyze.yml
+++ b/.github/workflows/Xcode-build-analyze.yml
@ -14,7 +14,24 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v5
-      
+
+      - name: Pin Xcode version
+        run: |
+          XCODE_VERSION=$(cat .xcode-version)
+          sudo xcode-select -s "/Applications/Xcode_${XCODE_VERSION}.app/Contents/Developer"
+          xcodebuild -version
+
+      - name: Resolve packages
+        run: xcodebuild -resolvePackageDependencies -project hellbender.xcodeproj -scheme hellbender
+
+      - name: Validate Package.resolved
+        run: |
+          if ! git diff --quiet hellbender.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved; then
+            echo "::error::Package.resolved has uncommitted changes after resolution. Commit the updated Package.resolved."
+            git diff hellbender.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
+            exit 1
+          fi
+
      - name: Build
        env:
          scheme: hellbender
--- a/.github/workflows/reproducible-build-check.yml
+++ b/.github/workflows/reproducible-build-check.yml
@ -0,0 +1,63 @@
+name: Reproducible Build Check
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  reproducibility:
+    name: Verify build reproducibility
+    runs-on: macos-26
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Pin Xcode version
+        run: |
+          XCODE_VERSION=$(cat .xcode-version)
+          sudo xcode-select -s "/Applications/Xcode_${XCODE_VERSION}.app/Contents/Developer"
+          xcodebuild -version
+
+      - name: Build 1
+        run: |
+          DERIVED_DATA="/tmp/hellbender-build-1"
+          rm -rf "$DERIVED_DATA"
+          xcodebuild archive \
+            -scheme hellbender \
+            -project hellbender.xcodeproj \
+            -archivePath "$DERIVED_DATA/hellbender.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -configuration Release \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGN_IDENTITY="" \
+            | xcpretty && exit ${PIPESTATUS[0]}
+
+      - name: Build 2
+        run: |
+          DERIVED_DATA="/tmp/hellbender-build-2"
+          rm -rf "$DERIVED_DATA"
+          xcodebuild archive \
+            -scheme hellbender \
+            -project hellbender.xcodeproj \
+            -archivePath "$DERIVED_DATA/hellbender.xcarchive" \
+            -derivedDataPath "$DERIVED_DATA" \
+            -configuration Release \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGN_IDENTITY="" \
+            | xcpretty && exit ${PIPESTATUS[0]}
+
+      - name: Normalize both builds
+        run: |
+          APP1="/tmp/hellbender-build-1/hellbender.xcarchive/Products/Applications/hellbender.app"
+          APP2="/tmp/hellbender-build-2/hellbender.xcarchive/Products/Applications/hellbender.app"
+          ./scripts/normalize-app.sh "$APP1"
+          ./scripts/normalize-app.sh "$APP2"
+
+      - name: Compare builds
+        run: |
+          APP1="/tmp/hellbender-build-1/hellbender.xcarchive/Products/Applications/hellbender.app"
+          APP2="/tmp/hellbender-build-2/hellbender.xcarchive/Products/Applications/hellbender.app"
+          ./scripts/compare-builds.sh "$APP1" "$APP2"
--- a/.xcode-version
+++ b/.xcode-version
@ -0,0 +1 @@
+26.4
--- a/Config/Base.xcconfig
+++ b/Config/Base.xcconfig
@ -0,0 +1,61 @@
+// Base.xcconfig — Shared build settings for all configurations
+
+ALWAYS_SEARCH_USER_PATHS = NO
+ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES
+
+// Static analysis
+CLANG_ANALYZER_NONNULL = YES
+CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE
+
+// Language standards
+CLANG_CXX_LANGUAGE_STANDARD = gnu++20
+GCC_C_LANGUAGE_STANDARD = gnu17
+
+// Modules and ARC
+CLANG_ENABLE_MODULES = YES
+CLANG_ENABLE_OBJC_ARC = YES
+CLANG_ENABLE_OBJC_WEAK = YES
+
+// Warnings — Clang
+CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES
+CLANG_WARN_BOOL_CONVERSION = YES
+CLANG_WARN_COMMA = YES
+CLANG_WARN_CONSTANT_CONVERSION = YES
+CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES
+CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR
+CLANG_WARN_DOCUMENTATION_COMMENTS = YES
+CLANG_WARN_EMPTY_BODY = YES
+CLANG_WARN_ENUM_CONVERSION = YES
+CLANG_WARN_INFINITE_RECURSION = YES
+CLANG_WARN_INT_CONVERSION = YES
+CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES
+CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES
+CLANG_WARN_OBJC_LITERAL_CONVERSION = YES
+CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR
+CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES
+CLANG_WARN_RANGE_LOOP_ANALYSIS = YES
+CLANG_WARN_STRICT_PROTOTYPES = YES
+CLANG_WARN_SUSPICIOUS_MOVE = YES
+CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE
+CLANG_WARN_UNREACHABLE_CODE = YES
+CLANG_WARN__DUPLICATE_METHOD_MATCH = YES
+
+// Warnings — GCC
+GCC_NO_COMMON_BLOCKS = YES
+GCC_WARN_64_TO_32_BIT_CONVERSION = YES
+GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR
+GCC_WARN_UNDECLARED_SELECTOR = YES
+GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE
+GCC_WARN_UNUSED_FUNCTION = YES
+GCC_WARN_UNUSED_VARIABLE = YES
+
+// Build settings
+COPY_PHASE_STRIP = NO
+DEVELOPMENT_TEAM = ZW85AH743B
+ENABLE_STRICT_OBJC_MSGSEND = YES
+ENABLE_USER_SCRIPT_SANDBOXING = YES
+IPHONEOS_DEPLOYMENT_TARGET = 26.0
+LOCALIZATION_PREFERS_STRING_CATALOGS = YES
+MTL_FAST_MATH = YES
+SDKROOT = iphoneos
+STRING_CATALOG_GENERATE_SYMBOLS = YES
--- a/Config/Debug.xcconfig
+++ b/Config/Debug.xcconfig
@ -0,0 +1,13 @@
+// Debug.xcconfig — Debug-specific build settings
+#include "Base.xcconfig"
+
+DEBUG_INFORMATION_FORMAT = dwarf
+ENABLE_PREVIEWS = YES
+ENABLE_TESTABILITY = YES
+GCC_DYNAMIC_NO_PIC = NO
+GCC_OPTIMIZATION_LEVEL = 0
+GCC_PREPROCESSOR_DEFINITIONS = DEBUG=1 $(inherited)
+MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE
+ONLY_ACTIVE_ARCH = YES
+SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG $(inherited)
+SWIFT_OPTIMIZATION_LEVEL = -Onone
--- a/Config/Hellbender.xcconfig
+++ b/Config/Hellbender.xcconfig
@ -0,0 +1,17 @@
+// Hellbender.xcconfig — Target-level settings for the hellbender app target
+
+ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon
+ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor
+CODE_SIGN_STYLE = Automatic
+CURRENT_PROJECT_VERSION = 23
+DEVELOPMENT_ASSET_PATHS = "hellbender/Preview Content"
+GENERATE_INFOPLIST_FILE = NO
+INFOPLIST_FILE = hellbender/Info.plist
+IPHONEOS_DEPLOYMENT_TARGET = 18.6
+LD_RUNPATH_SEARCH_PATHS = $(inherited) @executable_path/Frameworks
+MARKETING_VERSION = 0.1.2
+PRODUCT_BUNDLE_IDENTIFIER = com.klockenga.Hellbender
+PRODUCT_NAME = $(TARGET_NAME)
+SWIFT_EMIT_LOC_STRINGS = YES
+SWIFT_VERSION = 5.0
+TARGETED_DEVICE_FAMILY = 1,2
--- a/Config/Release.xcconfig
+++ b/Config/Release.xcconfig
@ -0,0 +1,13 @@
+// Release.xcconfig — Release-specific build settings + reproducibility
+#include "Base.xcconfig"
+
+DEBUG_INFORMATION_FORMAT = dwarf-with-dsym
+ENABLE_NS_ASSERTIONS = NO
+ENABLE_PREVIEWS = NO
+MTL_ENABLE_DEBUG_INFO = NO
+SWIFT_COMPILATION_MODE = wholemodule
+VALIDATE_PRODUCT = YES
+
+// Reproducibility: remap absolute paths in debug info
+OTHER_SWIFT_FLAGS = $(inherited) -debug-prefix-map $(SRCROOT)=. -debug-prefix-map $(HOME)=~
+OTHER_CFLAGS = $(inherited) -fdebug-prefix-map=$(SRCROOT)=. -fdebug-prefix-map=$(HOME)=~
--- a/README.md
+++ b/README.md
@ -38,7 +38,7 @@ Hellbender is an iOS Bitcoin multisig coordinator written in Swift. It operates

 ### Requirements

- Xcode 16.2+
+- Xcode 26.2+
 - iOS 18.6+ deployment target
 - Swift 5.0

@ -64,9 +64,45 @@ All dependencies are managed via Swift Package Manager and resolve automatically
 3. SPM dependencies resolve automatically on first open
 4. Build and run on a simulator or device

+For reproducible release builds, see [Reproducible Builds](#reproducible-builds) below.
+
 ### CI

-GitHub Actions runs `xcodebuild clean build analyze` on every push and pull request to `main`.
+GitHub Actions runs `xcodebuild clean build analyze` on every push and pull request to `main`. A separate [reproducibility verification workflow](.github/workflows/reproducible-build-check.yml) builds the project twice, normalizes both outputs, and compares them to catch non-determinism regressions.
+
+### Reproducible Builds
+
+Hellbender supports **functionally equivalent** reproducible builds. Given the same source code and Xcode version, two independent builds will produce the same compiled logic after normalization. Certain metadata bytes (Mach-O UUIDs, timestamps, build-machine identifiers) are expected to differ and are zeroed by the normalization step.
+
+**What IS reproducible** (after normalization): all code-bearing sections, resources, and application logic.
+
+**What is NOT reproducible**: code signing timestamps, Mach-O LC_UUID values, Xcode build-machine metadata, App Store .ipa files (Apple re-signs and applies FairPlay DRM).
+
+#### Prerequisites
+
+- Exact Xcode version matching `.xcode-version` (currently 26.4)
+- macOS with the matching SDK
+
+#### Producing a verifiable build
+
+```bash
+./scripts/build-release.sh
+```
+
+This creates an unsigned archive at `/tmp/hellbender-build/hellbender.xcarchive`.
+
+#### Verifying two builds
+
+```bash
+# Normalize both builds
+./scripts/normalize-app.sh /path/to/build1.app
+./scripts/normalize-app.sh /path/to/build2.app
+
+# Compare
+./scripts/compare-builds.sh /path/to/build1.app /path/to/build2.app
+```
+
+The comparison exits 0 if the builds are functionally equivalent, 1 if code differences are found.

 ## Links

--- a/hellbender.xcodeproj/project.pbxproj
+++ b/hellbender.xcodeproj/project.pbxproj
@ -35,11 +35,28 @@
 		3C9ACE242F5DED94009B00D0 /* hellbender.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = hellbender.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		3C9ACE342F5DED95009B00D0 /* hellbenderTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = hellbenderTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 		3C9ACE3E2F5DED95009B00D0 /* hellbenderUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = hellbenderUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		CC0000010000000000000001 /* Base.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = Base.xcconfig; sourceTree = "<group>"; };
+		CC0000010000000000000002 /* Debug.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = Debug.xcconfig; sourceTree = "<group>"; };
+		CC0000010000000000000003 /* Release.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = Release.xcconfig; sourceTree = "<group>"; };
+		CC0000010000000000000004 /* Hellbender.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = Hellbender.xcconfig; sourceTree = "<group>"; };
 /* End PBXFileReference section */

+/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
+		CC0000010000000000000006 /* PBXFileSystemSynchronizedBuildFileExceptionSet */ = {
+			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
+			membershipExceptions = (
+				Info.plist,
+			);
+			target = 3C9ACE232F5DED94009B00D0 /* hellbender */;
+		};
+/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
+
 /* Begin PBXFileSystemSynchronizedRootGroup section */
 		3C9ACE262F5DED94009B00D0 /* hellbender */ = {
 			isa = PBXFileSystemSynchronizedRootGroup;
+			exceptions = (
+				CC0000010000000000000006 /* PBXFileSystemSynchronizedBuildFileExceptionSet */,
+			);
 			path = hellbender;
 			sourceTree = "<group>";
 		};
@ -88,6 +105,7 @@
 		3C9ACE1B2F5DED94009B00D0 = {
 			isa = PBXGroup;
 			children = (
+				CC0000010000000000000005 /* Config */,
 				3C9ACE262F5DED94009B00D0 /* hellbender */,
 				3C9ACE372F5DED95009B00D0 /* hellbenderTests */,
 				3C9ACE412F5DED95009B00D0 /* hellbenderUITests */,
@ -105,6 +123,17 @@
 			name = Products;
 			sourceTree = "<group>";
 		};
+		CC0000010000000000000005 /* Config */ = {
+			isa = PBXGroup;
+			children = (
+				CC0000010000000000000001 /* Base.xcconfig */,
+				CC0000010000000000000002 /* Debug.xcconfig */,
+				CC0000010000000000000004 /* Hellbender.xcconfig */,
+				CC0000010000000000000003 /* Release.xcconfig */,
+			);
+			path = Config;
+			sourceTree = "<group>";
+		};
 /* End PBXGroup section */

 /* Begin PBXNativeTarget section */
@ -295,190 +324,29 @@
 /* Begin XCBuildConfiguration section */
 		3C9ACE462F5DED95009B00D0 /* Debug */ = {
 			isa = XCBuildConfiguration;
+			baseConfigurationReference = CC0000010000000000000002 /* Debug.xcconfig */;
 			buildSettings = {
-				ALWAYS_SEARCH_USER_PATHS = NO;
-				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
-				CLANG_ANALYZER_NONNULL = YES;
-				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
-				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
-				CLANG_ENABLE_MODULES = YES;
-				CLANG_ENABLE_OBJC_ARC = YES;
-				CLANG_ENABLE_OBJC_WEAK = YES;
-				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
-				CLANG_WARN_BOOL_CONVERSION = YES;
-				CLANG_WARN_COMMA = YES;
-				CLANG_WARN_CONSTANT_CONVERSION = YES;
-				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
-				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
-				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
-				CLANG_WARN_EMPTY_BODY = YES;
-				CLANG_WARN_ENUM_CONVERSION = YES;
-				CLANG_WARN_INFINITE_RECURSION = YES;
-				CLANG_WARN_INT_CONVERSION = YES;
-				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
-				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
-				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
-				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
-				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
-				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
-				CLANG_WARN_STRICT_PROTOTYPES = YES;
-				CLANG_WARN_SUSPICIOUS_MOVE = YES;
-				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
-				CLANG_WARN_UNREACHABLE_CODE = YES;
-				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
-				COPY_PHASE_STRIP = NO;
-				DEBUG_INFORMATION_FORMAT = dwarf;
-				DEVELOPMENT_TEAM = ZW85AH743B;
-				ENABLE_STRICT_OBJC_MSGSEND = YES;
-				ENABLE_TESTABILITY = YES;
-				ENABLE_USER_SCRIPT_SANDBOXING = YES;
-				GCC_C_LANGUAGE_STANDARD = gnu17;
-				GCC_DYNAMIC_NO_PIC = NO;
-				GCC_NO_COMMON_BLOCKS = YES;
-				GCC_OPTIMIZATION_LEVEL = 0;
-				GCC_PREPROCESSOR_DEFINITIONS = (
-					"DEBUG=1",
-					"$(inherited)",
-				);
-				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
-				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
-				GCC_WARN_UNDECLARED_SELECTOR = YES;
-				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
-				GCC_WARN_UNUSED_FUNCTION = YES;
-				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 26.0;
-				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
-				MTL_FAST_MATH = YES;
-				ONLY_ACTIVE_ARCH = YES;
-				SDKROOT = iphoneos;
-				STRING_CATALOG_GENERATE_SYMBOLS = YES;
-				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
-				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 			};
 			name = Debug;
 		};
 		3C9ACE472F5DED95009B00D0 /* Release */ = {
 			isa = XCBuildConfiguration;
+			baseConfigurationReference = CC0000010000000000000003 /* Release.xcconfig */;
 			buildSettings = {
-				ALWAYS_SEARCH_USER_PATHS = NO;
-				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
-				CLANG_ANALYZER_NONNULL = YES;
-				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
-				CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
-				CLANG_ENABLE_MODULES = YES;
-				CLANG_ENABLE_OBJC_ARC = YES;
-				CLANG_ENABLE_OBJC_WEAK = YES;
-				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
-				CLANG_WARN_BOOL_CONVERSION = YES;
-				CLANG_WARN_COMMA = YES;
-				CLANG_WARN_CONSTANT_CONVERSION = YES;
-				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
-				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
-				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
-				CLANG_WARN_EMPTY_BODY = YES;
-				CLANG_WARN_ENUM_CONVERSION = YES;
-				CLANG_WARN_INFINITE_RECURSION = YES;
-				CLANG_WARN_INT_CONVERSION = YES;
-				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
-				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
-				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
-				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
-				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
-				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
-				CLANG_WARN_STRICT_PROTOTYPES = YES;
-				CLANG_WARN_SUSPICIOUS_MOVE = YES;
-				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
-				CLANG_WARN_UNREACHABLE_CODE = YES;
-				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
-				COPY_PHASE_STRIP = NO;
-				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
-				DEVELOPMENT_TEAM = ZW85AH743B;
-				ENABLE_NS_ASSERTIONS = NO;
-				ENABLE_STRICT_OBJC_MSGSEND = YES;
-				ENABLE_USER_SCRIPT_SANDBOXING = YES;
-				GCC_C_LANGUAGE_STANDARD = gnu17;
-				GCC_NO_COMMON_BLOCKS = YES;
-				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
-				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
-				GCC_WARN_UNDECLARED_SELECTOR = YES;
-				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
-				GCC_WARN_UNUSED_FUNCTION = YES;
-				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 26.0;
-				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MTL_ENABLE_DEBUG_INFO = NO;
-				MTL_FAST_MATH = YES;
-				SDKROOT = iphoneos;
-				STRING_CATALOG_GENERATE_SYMBOLS = YES;
-				SWIFT_COMPILATION_MODE = wholemodule;
-				VALIDATE_PRODUCT = YES;
 			};
 			name = Release;
 		};
 		3C9ACE492F5DED95009B00D0 /* Debug */ = {
 			isa = XCBuildConfiguration;
+			baseConfigurationReference = CC0000010000000000000004 /* Hellbender.xcconfig */;
 			buildSettings = {
-				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
-				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 23;
-				DEVELOPMENT_ASSET_PATHS = "\"hellbender/Preview Content\"";
-				ENABLE_PREVIEWS = YES;
-				GENERATE_INFOPLIST_FILE = YES;
-				INFOPLIST_KEY_CFBundleDisplayName = Hellbender;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.finance";
-				INFOPLIST_KEY_NSCameraUsageDescription = "Hellbender needs camera access to scan QR codes for importing cosigner keys and signed PSBTs from hardware wallets.";
-				INFOPLIST_KEY_NSFaceIDUsageDescription = "Hellbender uses Face ID to securely unlock your wallet.";
-				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
-				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
-				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
-				INFOPLIST_KEY_UISupportedInterfaceOrientations = UIInterfaceOrientationPortrait;
-				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown";
-				IPHONEOS_DEPLOYMENT_TARGET = 18.6;
-				LD_RUNPATH_SEARCH_PATHS = (
-					"$(inherited)",
-					"@executable_path/Frameworks",
-				);
-				MARKETING_VERSION = 0.1.2;
-				PRODUCT_BUNDLE_IDENTIFIER = com.klockenga.Hellbender;
-				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_EMIT_LOC_STRINGS = YES;
-				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
 			};
 			name = Debug;
 		};
 		3C9ACE4A2F5DED95009B00D0 /* Release */ = {
 			isa = XCBuildConfiguration;
+			baseConfigurationReference = CC0000010000000000000004 /* Hellbender.xcconfig */;
 			buildSettings = {
-				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
-				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 23;
-				DEVELOPMENT_ASSET_PATHS = "\"hellbender/Preview Content\"";
-				ENABLE_PREVIEWS = YES;
-				GENERATE_INFOPLIST_FILE = YES;
-				INFOPLIST_KEY_CFBundleDisplayName = Hellbender;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.finance";
-				INFOPLIST_KEY_NSCameraUsageDescription = "Hellbender needs camera access to scan QR codes for importing cosigner keys and signed PSBTs from hardware wallets.";
-				INFOPLIST_KEY_NSFaceIDUsageDescription = "Hellbender uses Face ID to securely unlock your wallet.";
-				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
-				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
-				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
-				INFOPLIST_KEY_UISupportedInterfaceOrientations = UIInterfaceOrientationPortrait;
-				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown";
-				IPHONEOS_DEPLOYMENT_TARGET = 18.6;
-				LD_RUNPATH_SEARCH_PATHS = (
-					"$(inherited)",
-					"@executable_path/Frameworks",
-				);
-				MARKETING_VERSION = 0.1.2;
-				PRODUCT_BUNDLE_IDENTIFIER = com.klockenga.Hellbender;
-				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_EMIT_LOC_STRINGS = YES;
-				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
 			};
 			name = Release;
 		};
--- a/hellbender/Info.plist
+++ b/hellbender/Info.plist
@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>Hellbender</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(MARKETING_VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>LSApplicationCategoryType</key>
+	<string>public.app-category.finance</string>
+	<key>NSCameraUsageDescription</key>
+	<string>Hellbender needs camera access to scan QR codes for importing cosigner keys and signed PSBTs from hardware wallets.</string>
+	<key>NSFaceIDUsageDescription</key>
+	<string>Hellbender uses Face ID to securely unlock your wallet.</string>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict/>
+	</dict>
+	<key>UIApplicationSupportsIndirectInputEvents</key>
+	<true/>
+	<key>UILaunchScreen</key>
+	<dict/>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+	</array>
+	<key>UISupportedInterfaceOrientations~ipad</key>
+	<array>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+	</array>
+</dict>
+</plist>
--- a/scripts/build-release.sh
+++ b/scripts/build-release.sh
@ -0,0 +1,25 @@
+#!/bin/bash
+set -euo pipefail
+
+# build-release.sh — Produce a verifiable unsigned release archive.
+# Usage: ./scripts/build-release.sh
+#
+# Output: /tmp/hellbender-build/hellbender.xcarchive
+
+DERIVED_DATA="/tmp/hellbender-build"
+
+echo "==> Cleaning previous build artifacts..."
+rm -rf "$DERIVED_DATA"
+
+echo "==> Archiving (unsigned, Release configuration)..."
+xcodebuild archive \
+  -scheme hellbender \
+  -project hellbender.xcodeproj \
+  -archivePath "$DERIVED_DATA/hellbender.xcarchive" \
+  -derivedDataPath "$DERIVED_DATA" \
+  -configuration Release \
+  CODE_SIGNING_ALLOWED=NO \
+  CODE_SIGN_IDENTITY="" \
+  | xcpretty && exit ${PIPESTATUS[0]}
+
+echo "==> Archive complete: $DERIVED_DATA/hellbender.xcarchive"
--- a/scripts/compare-builds.sh
+++ b/scripts/compare-builds.sh
@ -0,0 +1,97 @@
+#!/bin/bash
+set -euo pipefail
+
+# compare-builds.sh — Compare two normalized .app bundles for functional equivalence.
+# Both bundles should have been processed by normalize-app.sh first.
+#
+# Usage: ./scripts/compare-builds.sh <path/to/build1.app> <path/to/build2.app>
+#
+# Exit codes:
+#   0 — Functionally equivalent (no code differences)
+#   1 — Code differences found
+
+APP1="${1:?Usage: compare-builds.sh <build1.app> <build2.app>}"
+APP2="${2:?Usage: compare-builds.sh <build1.app> <build2.app>}"
+
+if [ ! -d "$APP1" ]; then
+  echo "Error: $APP1 is not a directory" >&2
+  exit 1
+fi
+if [ ! -d "$APP2" ]; then
+  echo "Error: $APP2 is not a directory" >&2
+  exit 1
+fi
+
+echo "==> Comparing builds:"
+echo "    Build 1: $APP1"
+echo "    Build 2: $APP2"
+echo ""
+
+IDENTICAL=0
+DIFFERENT=0
+ONLY_IN_1=0
+ONLY_IN_2=0
+DIFF_FILES=()
+
+# Get sorted file lists relative to the .app root
+FILES1=$(cd "$APP1" && find . -type f | sort)
+FILES2=$(cd "$APP2" && find . -type f | sort)
+
+# Check for files only in one build
+ONLY1=$(comm -23 <(echo "$FILES1") <(echo "$FILES2"))
+ONLY2=$(comm -13 <(echo "$FILES1") <(echo "$FILES2"))
+
+if [ -n "$ONLY1" ]; then
+  ONLY_IN_1=$(echo "$ONLY1" | wc -l | tr -d ' ')
+  echo "--- Files only in Build 1 ($ONLY_IN_1):"
+  echo "$ONLY1" | sed 's/^/    /'
+  echo ""
+fi
+
+if [ -n "$ONLY2" ]; then
+  ONLY_IN_2=$(echo "$ONLY2" | wc -l | tr -d ' ')
+  echo "--- Files only in Build 2 ($ONLY_IN_2):"
+  echo "$ONLY2" | sed 's/^/    /'
+  echo ""
+fi
+
+# Compare common files
+COMMON=$(comm -12 <(echo "$FILES1") <(echo "$FILES2"))
+
+while IFS= read -r relpath; do
+  [ -z "$relpath" ] && continue
+  if cmp -s "$APP1/$relpath" "$APP2/$relpath"; then
+    IDENTICAL=$((IDENTICAL + 1))
+  else
+    DIFFERENT=$((DIFFERENT + 1))
+    DIFF_FILES+=("$relpath")
+  fi
+done <<< "$COMMON"
+
+# Report
+echo "==> Results:"
+echo "    Identical files:    $IDENTICAL"
+echo "    Different files:    $DIFFERENT"
+echo "    Only in Build 1:    $ONLY_IN_1"
+echo "    Only in Build 2:    $ONLY_IN_2"
+
+if [ "$DIFFERENT" -gt 0 ]; then
+  echo ""
+  echo "--- Files with differences ($DIFFERENT):"
+  for f in "${DIFF_FILES[@]}"; do
+    SIZE1=$(stat -f%z "$APP1/$f" 2>/dev/null || echo "?")
+    SIZE2=$(stat -f%z "$APP2/$f" 2>/dev/null || echo "?")
+    echo "    $f  (${SIZE1}B vs ${SIZE2}B)"
+  done
+fi
+
+TOTAL_DIFF=$((DIFFERENT + ONLY_IN_1 + ONLY_IN_2))
+if [ "$TOTAL_DIFF" -eq 0 ]; then
+  echo ""
+  echo "==> PASS: Builds are functionally equivalent."
+  exit 0
+else
+  echo ""
+  echo "==> FAIL: Builds differ in $TOTAL_DIFF file(s)."
+  exit 1
+fi
--- a/scripts/normalize-app.sh
+++ b/scripts/normalize-app.sh
@ -0,0 +1,270 @@
+#!/bin/bash
+set -euo pipefail
+
+# normalize-app.sh — Normalize an unsigned .app bundle for reproducible comparison.
+# Zeros non-deterministic metadata (UUIDs, timestamps, build-machine info, code
+# signatures, temp paths) so that two builds from the same source produce identical
+# normalized output.
+#
+# Usage: ./scripts/normalize-app.sh <path/to/hellbender.app>
+#
+# Operates in-place on the .app bundle. Make a copy first if you need the original.
+
+APP_PATH="${1:?Usage: normalize-app.sh <path/to/hellbender.app>}"
+
+if [ ! -d "$APP_PATH" ]; then
+  echo "Error: $APP_PATH is not a directory" >&2
+  exit 1
+fi
+
+echo "==> Normalizing: $APP_PATH"
+
+# ---------------------------------------------------------------------------
+# 1. Canonicalize Assets.car files
+#    Replace binary .car with sorted JSON dump (content-equivalent, order-
+#    independent). Must happen BEFORE any binary zeroing that would corrupt
+#    the BOM header.
+# ---------------------------------------------------------------------------
+echo "  - Canonicalizing Assets.car..."
+find "$APP_PATH" -name "Assets.car" -type f | while read -r car_file; do
+  json_file="${car_file}.json"
+  if xcrun assetutil --info "$car_file" > "$json_file" 2>/dev/null; then
+    # Sort JSON keys and strip non-deterministic fields for canonical representation
+    python3 << PYEOF
+import json
+
+path = """$json_file"""
+with open(path) as f:
+    data = json.load(f)
+
+def strip_timestamps(obj):
+    if isinstance(obj, dict):
+        return {k: strip_timestamps(v) for k, v in obj.items()
+                if k not in ("Timestamp",)}
+    elif isinstance(obj, list):
+        return [strip_timestamps(item) for item in obj]
+    return obj
+
+data = strip_timestamps(data)
+
+# Sort the list of asset entries by a stable key
+if isinstance(data, list):
+    data.sort(key=lambda x: json.dumps(x, sort_keys=True))
+
+with open(path, 'w') as f:
+    json.dump(data, f, sort_keys=True, indent=2)
+PYEOF
+    # Replace .car with canonical JSON
+    mv "$json_file" "$car_file"
+  else
+    rm -f "$json_file"
+    echo "    Warning: assetutil failed for $car_file, zeroing known variable fields instead"
+    # Fallback: zero the BOM tree ordering section
+    python3 << PYEOF
+import struct
+
+path = """$car_file"""
+with open(path, 'rb') as f:
+    data = bytearray(f.read())
+
+# Zero BOM tree metadata at known offsets
+# BOM header timestamp (offset 0x18)
+if len(data) > 0x1C:
+    struct.pack_into('<I', data, 0x18, 0)
+
+with open(path, 'wb') as f:
+    f.write(data)
+PYEOF
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# 2. Strip code signatures from all Mach-O binaries
+#    Ad-hoc signatures are non-deterministic. Must be done before other
+#    Mach-O modifications to avoid signature-related size differences.
+# ---------------------------------------------------------------------------
+echo "  - Stripping code signatures from Mach-O binaries..."
+find "$APP_PATH" -type f | while read -r file; do
+  if file "$file" | grep -q "Mach-O"; then
+    codesign --remove-signature "$file" 2>/dev/null || true
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# 3. Zero LC_UUID in all Mach-O binaries
+# ---------------------------------------------------------------------------
+echo "  - Zeroing LC_UUID in Mach-O binaries..."
+find "$APP_PATH" -type f | while read -r file; do
+  if file "$file" | grep -q "Mach-O"; then
+    python3 << PYEOF
+import struct, sys
+
+path = """$file"""
+with open(path, 'rb') as f:
+    data = bytearray(f.read())
+
+def get_slice_offsets(data):
+    magic = struct.unpack_from('<I', data, 0)[0]
+    if magic in (0xCAFEBABE, 0xBEBAFECA):
+        nfat = struct.unpack_from('>I', data, 4)[0]
+        return [struct.unpack_from('>I', data, 8 + i * 20 + 8)[0] for i in range(nfat)]
+    elif magic in (0xFEEDFACE, 0xFEEDFACF, 0xCEFAEDFE, 0xCFFAEDFE):
+        return [0]
+    return []
+
+def zero_uuids(data, base):
+    m = struct.unpack_from('<I', data, base)[0]
+    if m in (0xFEEDFACF, 0xCFFAEDFE):
+        hdr_size = 32
+    elif m in (0xFEEDFACE, 0xCEFAEDFE):
+        hdr_size = 28
+    else:
+        return
+    ncmds = struct.unpack_from('<I', data, base + 16)[0]
+    pos = base + hdr_size
+    for _ in range(ncmds):
+        if pos + 8 > len(data):
+            break
+        cmd = struct.unpack_from('<I', data, pos)[0]
+        cmdsize = struct.unpack_from('<I', data, pos + 4)[0]
+        if cmdsize == 0:
+            break
+        if cmd == 0x1B:  # LC_UUID
+            for j in range(16):
+                data[pos + 8 + j] = 0
+        pos += cmdsize
+
+for base in get_slice_offsets(data):
+    zero_uuids(data, base)
+
+with open(path, 'wb') as f:
+    f.write(data)
+PYEOF
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# 4. Zero Mach-O timestamps in load commands
+# ---------------------------------------------------------------------------
+echo "  - Zeroing Mach-O timestamps..."
+find "$APP_PATH" -type f | while read -r file; do
+  if file "$file" | grep -q "Mach-O"; then
+    python3 << PYEOF
+import struct
+
+path = """$file"""
+with open(path, 'rb') as f:
+    data = bytearray(f.read())
+
+def get_slice_offsets(data):
+    magic = struct.unpack_from('<I', data, 0)[0]
+    if magic in (0xCAFEBABE, 0xBEBAFECA):
+        nfat = struct.unpack_from('>I', data, 4)[0]
+        return [struct.unpack_from('>I', data, 8 + i * 20 + 8)[0] for i in range(nfat)]
+    elif magic in (0xFEEDFACE, 0xFEEDFACF, 0xCEFAEDFE, 0xCFFAEDFE):
+        return [0]
+    return []
+
+for base in get_slice_offsets(data):
+    m = struct.unpack_from('<I', data, base)[0]
+    if m in (0xFEEDFACF, 0xCFFAEDFE):
+        hdr_size = 32
+    elif m in (0xFEEDFACE, 0xCEFAEDFE):
+        hdr_size = 28
+    else:
+        continue
+    ncmds = struct.unpack_from('<I', data, base + 16)[0]
+    pos = base + hdr_size
+    for _ in range(ncmds):
+        if pos + 8 > len(data):
+            break
+        cmd = struct.unpack_from('<I', data, pos)[0]
+        cmdsize = struct.unpack_from('<I', data, pos + 4)[0]
+        if cmdsize == 0:
+            break
+        # LC_ID_DYLIB (0xD), LC_LOAD_DYLIB (0xC), LC_LOAD_WEAK_DYLIB (0x80000018)
+        if cmd in (0xC, 0xD, 0x80000018):
+            struct.pack_into('<I', data, pos + 16, 0)
+        pos += cmdsize
+
+with open(path, 'wb') as f:
+    f.write(data)
+PYEOF
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# 5. Zero non-deterministic temp paths in Mach-O string tables
+#    Xcode embeds random temp paths like swbuild.tmp.XXXXXXXX when injecting
+#    stub binaries into codeless frameworks.
+# ---------------------------------------------------------------------------
+echo "  - Zeroing non-deterministic temp paths in Mach-O binaries..."
+find "$APP_PATH" -type f | while read -r file; do
+  if file "$file" | grep -q "Mach-O"; then
+    python3 << PYEOF
+import re
+
+path = """$file"""
+with open(path, 'rb') as f:
+    data = bytearray(f.read())
+
+# Replace random temp directory names: swbuild.tmp.XXXXXXXX
+# The 8 chars after 'swbuild.tmp.' are random alphanumeric
+pattern = b'swbuild.tmp.'
+i = 0
+while i < len(data) - 20:
+    pos = data.find(pattern, i)
+    if pos == -1:
+        break
+    # Zero the 8 random characters after the pattern
+    start = pos + len(pattern)
+    for j in range(8):
+        if start + j < len(data):
+            data[start + j] = 0
+    i = pos + 1
+
+# Also zero /var/folders random paths (DerivedData-like paths)
+# Pattern: /var/folders/XX/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/
+pattern2 = b'/var/folders/'
+i = 0
+while i < len(data) - 60:
+    pos = data.find(pattern2, i)
+    if pos == -1:
+        break
+    # Zero from /var/folders/ to the next null byte or path separator after T/
+    end = pos + len(pattern2)
+    while end < len(data) and data[end] != 0:
+        end += 1
+    for j in range(pos, end):
+        data[j] = 0
+    i = pos + 1
+
+with open(path, 'wb') as f:
+    f.write(data)
+PYEOF
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# 6. Strip build-machine metadata from Info.plist
+# ---------------------------------------------------------------------------
+echo "  - Stripping build-machine metadata from Info.plist..."
+INFO_PLIST="$APP_PATH/Info.plist"
+if [ -f "$INFO_PLIST" ]; then
+  KEYS_TO_REMOVE=(
+    DTXcodeBuild
+    DTCompiler
+    BuildMachineOSBuild
+    DTXcode
+    DTSDKBuild
+    DTSDKName
+    DTPlatformBuild
+    DTPlatformName
+    DTPlatformVersion
+  )
+  for key in "${KEYS_TO_REMOVE[@]}"; do
+    /usr/libexec/PlistBuddy -c "Delete :$key" "$INFO_PLIST" 2>/dev/null || true
+  done
+fi
+
+echo "==> Normalization complete: $APP_PATH"