diff --git a/.github/workflows/lab-instance-tools.yml b/.github/workflows/lab-instance-tools.yml new file mode 100644 index 0000000000..ebf48e6600 --- /dev/null +++ b/.github/workflows/lab-instance-tools.yml @@ -0,0 +1,21 @@ +name: Lab instance tools +on: + pull_request: + paths: + - 'devtools/lab/**' + - 'SerialPrograms/cmake/LabBuildReceipt.cmake' + - 'SerialPrograms/CMakeLists.txt' + - '.github/workflows/lab-instance-tools.yml' + workflow_dispatch: +jobs: + offline-preparation: + strategy: + matrix: + os: [ubuntu-latest, macos-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + - run: python3 -m unittest discover -s devtools/lab -p 'test_lab_instance.py' -v diff --git a/SerialPrograms/CMakeLists.txt b/SerialPrograms/CMakeLists.txt index 812564bcff..077a2d8def 100644 --- a/SerialPrograms/CMakeLists.txt +++ b/SerialPrograms/CMakeLists.txt @@ -212,6 +212,18 @@ if (APPLE) target_compile_definitions(SerialPrograms PRIVATE PA_LAB_PROFILE="${PA_LAB_PROFILE}") endif() + # Receipt binds packaging to the linked binary, not just a CMake cache value. + set_property(TARGET SerialPrograms APPEND PROPERTY LINK_DEPENDS + "${CMAKE_CURRENT_SOURCE_DIR}/cmake/LabBuildReceipt.cmake") + add_custom_command(TARGET SerialPrograms POST_BUILD + COMMAND "${CMAKE_COMMAND}" + "-DBINARY=$" + "-DPROFILE=${PA_LAB_PROFILE}" + "-DSOURCE=${CMAKE_CURRENT_SOURCE_DIR}/.." + -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/LabBuildReceipt.cmake" + VERBATIM + ) + set_target_properties(SerialPrograms PROPERTIES BUNDLE True MACOSX_BUNDLE_GUI_IDENTIFIER PokemonAutomation.SerialPrograms diff --git a/SerialPrograms/cmake/LabBuildReceipt.cmake b/SerialPrograms/cmake/LabBuildReceipt.cmake new file mode 100644 index 0000000000..c2817753cf --- /dev/null +++ b/SerialPrograms/cmake/LabBuildReceipt.cmake @@ -0,0 +1,21 @@ +# Called after linking a lab executable; never invokes that executable. +set(receipt "${BINARY}.lab-build.json") +if(PROFILE STREQUAL "") + file(REMOVE "${receipt}") + return() +endif() +if(NOT PROFILE MATCHES "^[A-Za-z0-9_][A-Za-z0-9_-]*$") + message(FATAL_ERROR "Invalid lab profile") +endif() +find_package(Git REQUIRED) +execute_process(COMMAND "${GIT_EXECUTABLE}" rev-parse HEAD + WORKING_DIRECTORY "${SOURCE}" OUTPUT_VARIABLE revision + OUTPUT_STRIP_TRAILING_WHITESPACE COMMAND_ERROR_IS_FATAL ANY) +execute_process(COMMAND "${GIT_EXECUTABLE}" status --porcelain --untracked-files=normal + WORKING_DIRECTORY "${SOURCE}" OUTPUT_VARIABLE changes COMMAND_ERROR_IS_FATAL ANY) +set(clean false) +if(changes STREQUAL "") + set(clean true) +endif() +file(SHA256 "${BINARY}" digest) +file(WRITE "${receipt}" "{\"schema\":1,\"profile\":\"${PROFILE}\",\"source_revision\":\"${revision}\",\"source_clean\":${clean},\"binary_sha256\":\"${digest}\"}\n") diff --git a/devtools/lab/INSTANCE_PREPARATION.md b/devtools/lab/INSTANCE_PREPARATION.md new file mode 100644 index 0000000000..88a7d38161 --- /dev/null +++ b/devtools/lab/INSTANCE_PREPARATION.md @@ -0,0 +1,113 @@ +# Preparing two lab instances + +Use a dedicated profile and app identity for each console. Default remains the +normal-use profile. This tooling prepares files offline; it never launches an +app, sends a command, changes permissions, or opens a controller or capture device. + +## Seed profiles without copying live state + +Work from an offline snapshot containing `UserSettings/SerialPrograms-Settings.json`, taken while the +source app is closed. Keep that snapshot as the backup; do not seed from a file +being rewritten by a running app. For example, using a scratch root first: + +```sh +python3 devtools/lab/lab_instance.py seed \ + --source /offline/default-snapshot --root /offline/application-support --profile lab-A +python3 devtools/lab/lab_instance.py seed \ + --source /offline/default-snapshot --root /offline/application-support --profile lab-B +``` + +Each destination is `ROOT/Profiles/lab-NAME`. Existing destinations, including +empty directories, are refused. The source is never written. The new directory +is private to its owner. Only theme, window geometry and console-settings collapse +preferences are retained; panels are empty. Saved controller/camera/audio bindings, +device aliases, program options, selected panels, developer credentials, Discord +settings, test settings, statistics/temp paths, logs and channel queues are omitted. +Output-window startup and Rich Presence are disabled. Unknown future settings are +omitted. This is preference seeding, not a full profile clone. Application defaults +still apply to omitted settings; this does not promise a network-free GUI launch. + +After reviewing the scratch output, the same command can seed under +`~/Library/Application Support/SerialPrograms`. Do not rename the executable: +its basename participates in the application's settings path. Do not configure +real devices until the assigned console and device identities have been checked. +`lab-profile.json` deliberately records `hardware_configured: false`; it is a +preparation note, not a runtime device lease. + +## Bind and stage each build + +The lab integration branch merges `lab/main` and the feature under test (MaxLair, +for example). The upstream feature branch never merges lab tooling. Build each +slot with its matching profile, using the existing build/signing setup: + +```sh +cmake -S SerialPrograms -B /build/slot-A -DPA_LAB_PROFILE=lab-A +# Build via the existing lab procedure; use a clean committed source tree. +``` + +macOS linking writes `SerialPrograms.lab-build.json` beside the executable. It +records the compiled profile, executable SHA-256, source revision and whether the +source checkout was clean at link time. Unbound linking removes an old receipt. +This is accidental-mixup detection, not a signed source/build attestation; it +records the checkout observed at link time, and cannot prove when every object +was compiled. Use a clean committed checkout and the normal dependency-tracked +build. Do not edit or regenerate receipts manually to accept a changed binary. + +```sh +python3 devtools/lab/lab_instance.py preflight \ + --app /build/slot-A/SerialPrograms.app --profile lab-A +python3 devtools/lab/lab_instance.py stage \ + --app /build/slot-A/SerialPrograms.app --out /staging/slot-A \ + --profile lab-A --console A --bundle-id com.dayfine.pokemonautomation.labA \ + --signing-identity 'PokemonAutomation Local Development' +``` + +Stage requires a matching linked-build receipt and unused output directory. It +copies the app, sets a distinct lab identifier/display name, signs and verifies +it, then writes `lab-deployment.json` outside the bundle with final executable +and plist hashes. The source app is unchanged. Failure removes only the new +staging directory. No active deployment is replaced and no permissions are reset. +Keep the manifest next to the staged app. The build receipt inside the signed app +describes the pre-packaging artifact; use `verify` for the final signed package. + +Prepare B with `lab-B`, console `B`, a different bundle ID and +`--peer /staging/slot-A/lab-deployment.json`. Peer manifests reject reuse of a +profile, console or bundle ID. Before deployment, cross-check both packages: + +```sh +python3 devtools/lab/lab_instance.py verify \ + --manifest /staging/slot-A/lab-deployment.json --profile lab-A \ + --peer /staging/slot-B/lab-deployment.json +python3 devtools/lab/lab_instance.py verify \ + --manifest /staging/slot-B/lab-deployment.json --profile lab-B \ + --peer /staging/slot-A/lab-deployment.json +``` + +Use this staging entry point instead of editing/signing bundles with the older +local deploy scripts. Those external scripts have not been modified automatically +and can bypass this check. No production/default profile is accepted by this +tool: preparation requires a `lab-` prefix. The existing startup policy additionally +rejects a profile conflicting with the compiled binding, before loading settings. + +## Remaining device boundary + +Two profiles do not reserve two physical devices. A misconfigured profile can +still open another console's serial port, which can disturb that console before +commands are sent. Shell locks and channel ownership do not prevent that. +Before concurrent hardware validation, add an explicit per-slot device allowlist +and exclusive lease checked before serial/capture open, with native tests for +wrong-device access and competing owners. These packages explicitly report +`hardware_ownership_enforced: false`. They are not authorization to start a run. + +## Offline verification + +```sh +python3 -m unittest discover -s devtools/lab -p test_lab_instance.py -v +``` + +Tests use temporary settings, fake executable files and an injected signer. They +exercise the real receipt CMake script without configuring the full application. +They cover sanitization, existing destinations, default/path names, symlink escape, +missing/mismatched/stale/dirty receipts, slot collisions, post-signing hashes, +modified packages and signing failure. They do not validate real certificates, +macOS permission persistence or physical-device exclusion. CI runs on macOS/Linux. diff --git a/devtools/lab/README.md b/devtools/lab/README.md index 8dc1560664..7b3b7ec4b5 100644 --- a/devtools/lab/README.md +++ b/devtools/lab/README.md @@ -77,6 +77,11 @@ unsupported and rejected. ## Startup isolation and tests +For safe preference seeding and checked packaging of two lab apps, see +[INSTANCE_PREPARATION.md](INSTANCE_PREPARATION.md). Its staging tool validates the +linked build's profile receipt before signing and records the final package hashes. +Physical-device ownership remains a separate required boundary. + Bind each deployed macOS lab binary to its console when configuring its existing build directory, for example: diff --git a/devtools/lab/lab_instance.py b/devtools/lab/lab_instance.py new file mode 100644 index 0000000000..99e232d049 --- /dev/null +++ b/devtools/lab/lab_instance.py @@ -0,0 +1,54 @@ +"""Prepare isolated macOS lab instances; never launch apps or open devices. + +Examples (run from repository root): + python3 devtools/lab/lab_instance.py seed --source /offline/default-copy --root /offline/root --profile lab-A + python3 devtools/lab/lab_instance.py preflight --app /build/SerialPrograms.app --profile lab-A + python3 devtools/lab/lab_instance.py stage --app /build/SerialPrograms.app --out /staging/A --profile lab-A --console A --bundle-id com.dayfine.pokemonautomation.labA --signing-identity 'PokemonAutomation Local Development' + python3 devtools/lab/lab_instance.py verify --manifest /staging/A/lab-deployment.json --profile lab-A --peer /staging/B/lab-deployment.json +""" + +import argparse +import subprocess + +from lab_package import preflight, stage, verify +from lab_profiles import seed + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + commands = parser.add_subparsers(dest="command", required=True) + seeder = commands.add_parser("seed", help="Create an unused sanitized profile") + seeder.add_argument("--source", required=True) + seeder.add_argument("--root", required=True, help="Application support root containing Profiles/") + for command in (seeder, commands.add_parser("preflight"), commands.add_parser("stage"), commands.add_parser("verify")): + command.add_argument("--profile", required=True) + if command.prog.endswith(("preflight", "stage")): + command.add_argument("--app", required=True) + if command.prog.endswith(("stage", "verify")): + command.add_argument("--peer", action="append", default=[]) + if command.prog.endswith("stage"): + command.add_argument("--out", required=True) + command.add_argument("--console", choices=("A", "B"), required=True) + command.add_argument("--bundle-id", required=True) + command.add_argument("--signing-identity", required=True) + if command.prog.endswith("verify"): + command.add_argument("--manifest", required=True) + args = parser.parse_args() + try: + if args.command == "seed": + print(seed(args.source, args.root, args.profile)) + elif args.command == "preflight": + preflight(args.app, args.profile) + print("Linked build matches " + args.profile) + elif args.command == "stage": + print(stage(args.app, args.out, args.profile, args.console, args.bundle_id, args.signing_identity, args.peer)) + else: + verify(args.manifest, args.profile, args.peer) + print("Staged package matches " + args.profile + "; hardware ownership is not enforced yet.") + except (OSError, ValueError, KeyError, TypeError, subprocess.CalledProcessError) as error: + detail = str(error) if isinstance(error, ValueError) else type(error).__name__ + parser.exit(2, "Lab preparation refused: " + detail + "\n") + + +if __name__ == "__main__": + main() diff --git a/devtools/lab/lab_package.py b/devtools/lab/lab_package.py new file mode 100644 index 0000000000..8ef6cc04a0 --- /dev/null +++ b/devtools/lab/lab_package.py @@ -0,0 +1,126 @@ +"""Stage and validate macOS lab apps without launching them or opening devices.""" + +import hashlib +from pathlib import Path +import plistlib +import re +import shutil +import subprocess + +from lab_profiles import lab_profile, read_json, write_json + + +def sha256(path): + with Path(path).open("rb") as stream: + digest = hashlib.sha256() + for block in iter(lambda: stream.read(1024 * 1024), b""): + digest.update(block) + return digest.hexdigest() + + +def app_files(app): + """Require the executable basename used by the existing macOS profiles.""" + app = Path(app) + plist = app / "Contents" / "Info.plist" + with plist.open("rb") as stream: + info = plistlib.load(stream) + if info.get("CFBundleExecutable") != "SerialPrograms": + raise ValueError("Expected executable SerialPrograms; renaming it changes settings paths.") + binary = app / "Contents" / "MacOS" / "SerialPrograms" + if binary.is_symlink() or plist.is_symlink() or not binary.is_file(): + raise ValueError("Executable and plist must be regular files inside the app.") + if binary.resolve().parent != app.resolve() / "Contents" / "MacOS": + raise ValueError("Executable directory must not redirect outside the app.") + return plist, binary, info + + +def preflight(app, profile): + """Check the original linked artifact before any packaging/signature modifications.""" + profile = lab_profile(profile) + _, binary, _ = app_files(app) + receipt = read_json(str(binary) + ".lab-build.json") + if receipt.get("schema") != 1 or receipt.get("profile") != profile: + raise ValueError("Missing or mismatched compiled lab profile receipt.") + if receipt.get("source_clean") is not True: + raise ValueError("Build receipt requires a clean committed source tree.") + if not re.fullmatch(r"[0-9a-f]{40}", receipt.get("source_revision", "")): + raise ValueError("Build receipt requires a full source revision.") + if sha256(binary) != receipt.get("binary_sha256"): + raise ValueError("Binary differs from the build receipt; rebuild before staging.") + return receipt + + +def run_codesign(arguments): + subprocess.run(["/usr/bin/codesign", *arguments], check=True, capture_output=True) + + +def distinct_slots(candidate, peers): + """Reject collisions with the deployment manifests supplied by the caller.""" + for peer in peers: + for field in ("profile", "console", "bundle_id"): + if candidate[field] == read_json(peer)[field]: + raise ValueError("Lab deployment conflicts with peer: " + field) + + +def stage(app, output, profile, console, bundle_id, signing_identity, peers=(), signer=run_codesign): + """Create an unused staging directory and signed app; never replace an active app.""" + receipt = preflight(app, profile) + if not re.fullmatch(r"com\.dayfine\.pokemonautomation\.lab[A-Za-z0-9_-]*", bundle_id): + raise ValueError("Use a dedicated com.dayfine.pokemonautomation.lab... bundle ID.") + if console not in ("A", "B") or not signing_identity.strip() or signing_identity == "-": + raise ValueError("Select console A/B and a persistent signing identity, not ad-hoc '-'.") + manifest = { + "schema": 1, "profile": profile, "console": console, "bundle_id": bundle_id, + "source_revision": receipt["source_revision"], "app": "SerialPrograms.app", + "hardware_ownership_enforced": False, + } + distinct_slots(manifest, peers) + output = Path(output) + if output.resolve() == Path(app).resolve() or Path(app).resolve() in output.resolve().parents: + raise ValueError("Staging directory must be separate from the source app.") + output.mkdir(mode=0o700) # Exclusive; an existing deployment is never overwritten. + try: + staged = output / manifest["app"] + shutil.copytree(app, staged, symlinks=True) + plist, binary, info = app_files(staged) + info.update({ + "CFBundleIdentifier": bundle_id, + "CFBundleName": "PokemonAutomation Lab " + console, + "CFBundleDisplayName": "PokemonAutomation Lab " + console + " (" + profile + ")", + }) + with plist.open("wb") as stream: + plistlib.dump(info, stream) + signer(["--force", "--deep", "--sign", signing_identity, str(staged)]) + signer(["--verify", "--deep", "--strict", str(staged)]) + # Signing can change Mach-O bytes: bind the final artifact separately. + manifest["binary_sha256"] = sha256(binary) + manifest["plist_sha256"] = sha256(plist) + write_json(output / "lab-deployment.json", manifest) + except BaseException: + shutil.rmtree(output) + raise + return output / "lab-deployment.json" + + +def verify(manifest_path, profile, peers=(), signer=run_codesign): + """Validate a staged package's identity, hashes and signature without launching it.""" + manifest_path = Path(manifest_path) + manifest = read_json(manifest_path) + if manifest.get("schema") != 1 or manifest.get("profile") != lab_profile(profile): + raise ValueError("Deployment profile does not match the requested lab.") + if manifest.get("app") != "SerialPrograms.app": + raise ValueError("Unexpected app path in deployment manifest.") + app = manifest_path.parent / manifest["app"] + plist, binary, info = app_files(app) + receipt = read_json(str(binary) + ".lab-build.json") + if (receipt.get("schema") != 1 or receipt.get("profile") != manifest["profile"] + or receipt.get("source_revision") != manifest.get("source_revision") + or receipt.get("source_clean") is not True): + raise ValueError("Deployment identity differs from the packaged build receipt.") + if info.get("CFBundleIdentifier") != manifest["bundle_id"]: + raise ValueError("Bundle identifier differs from the deployment manifest.") + if sha256(binary) != manifest["binary_sha256"] or sha256(plist) != manifest["plist_sha256"]: + raise ValueError("Staged app changed after packaging.") + distinct_slots(manifest, peers) + signer(["--verify", "--deep", "--strict", str(app)]) + return manifest diff --git a/devtools/lab/lab_profiles.py b/devtools/lab/lab_profiles.py new file mode 100644 index 0000000000..6593d9a91a --- /dev/null +++ b/devtools/lab/lab_profiles.py @@ -0,0 +1,70 @@ +"""Seed a new lab profile from display preferences, never a full settings clone.""" + +import json +import os +from pathlib import Path +import re +import shutil +import tempfile + + +SETTINGS = "UserSettings/SerialPrograms-Settings.json" +PREFERENCES = {"THEME", "WINDOW_SIZE", "LOG_WINDOW_SIZE", "CONSOLE_SETTINGS_COLLAPSED"} + + +def lab_profile(name): + """Require an explicit lab name, distinct from default and unit-test profiles.""" + if not re.fullmatch(r"lab-[A-Za-z0-9_][A-Za-z0-9_-]*", name): + raise ValueError("Profile must be named lab-NAME (for example lab-A).") + return name + + +def read_json(path): + with Path(path).open(encoding="utf-8") as stream: + value = json.load(stream) + if not isinstance(value, dict): + raise ValueError("Expected a JSON object.") + return value + + +def write_json(path, value): + with Path(path).open("x", encoding="utf-8") as stream: + json.dump(value, stream, indent=2, sort_keys=True) + stream.write("\n") + + +def seed(source, root, profile): + """Create an unused Profiles/lab-NAME; leave the source and existing profiles alone.""" + profile = lab_profile(profile) + source, root = Path(source).resolve(), Path(root).resolve() + destination = root / "Profiles" / profile + if destination.exists() or destination.is_symlink(): + raise ValueError("Destination profile already exists; refusing to overwrite it.") + original = read_json(source / SETTINGS) + if not isinstance(original, dict): + raise ValueError("Settings root must be an object.") + settings = original.get("20-GlobalSettings", {}) + if not isinstance(settings, dict): + raise ValueError("Global settings must be an object.") + # Allowlist rather than deleting known device keys: future settings default to omitted. + safe = {key: value for key, value in settings.items() if key in PREFERENCES} + safe.update({"LOG_WINDOW_STARTUP": False, "RICH_PRESENCE": False}) + destination.parent.mkdir(parents=True, exist_ok=True) + if destination.parent.resolve() != root / "Profiles": + raise ValueError("Profiles must not redirect outside the requested root.") + temporary = Path(tempfile.mkdtemp(prefix=".seed-", dir=destination.parent)) + os.chmod(temporary, 0o700) + try: + (temporary / "UserSettings").mkdir() + write_json(temporary / SETTINGS, {"20-GlobalSettings": safe, "99-Panels": {}}) + write_json(temporary / "lab-profile.json", { + "schema": 1, "profile": profile, "hardware_configured": False, + "seed_policy": "display-preferences-only", + }) + # mkdir is exclusive, including against an empty destination created concurrently. + destination.mkdir(mode=0o700) + for child in temporary.iterdir(): + child.rename(destination / child.name) + finally: + shutil.rmtree(temporary) + return destination diff --git a/devtools/lab/test_lab_instance.py b/devtools/lab/test_lab_instance.py new file mode 100644 index 0000000000..177ece5a5a --- /dev/null +++ b/devtools/lab/test_lab_instance.py @@ -0,0 +1,218 @@ +"""Offline tool tests: temporary profiles, fake bundles and injected signing only.""" + +import json +from pathlib import Path +import plistlib +import shutil +import subprocess +import tempfile +import unittest + +from lab_package import preflight, sha256, stage, verify +from lab_profiles import SETTINGS, read_json, seed, write_json + + +class ProfileTests(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = Path(self.temporary.name) + self.source = self.root / "default" + self.source.mkdir() + (self.source / "UserSettings").mkdir() + self.original = { + "20-GlobalSettings": { + "THEME": "dark", "CONSOLE_SETTINGS_COLLAPSED": False, + "DEVICE_ALIASES": {"serial": "console-A"}, "STATS_FILE": "/live/stats", + "COMMAND_LINE_TESTS": {"RUN": True}, "DEBUG": {"SelectedPanel": "MaxLair"}, + "DISCORD": {"secret": "do-not-copy"}, "FUTURE_SETTING": {"port": "live"}, + }, + "99-Panels": {"MaxLair": {"ConsoleSetup": {"Controller": "live-port"}}}, + "future": {"hardware": "do-not-copy"}, + } + write_json(self.source / SETTINGS, self.original) + + def test_two_profiles_copy_preferences_without_live_state(self): + before = (self.source / SETTINGS).read_bytes() + for name in ("lab-A", "lab-B"): + with self.subTest(profile=name): + destination = seed(self.source, self.root, name) + self.assertEqual(read_json(destination / SETTINGS), { + "20-GlobalSettings": { + "THEME": "dark", "CONSOLE_SETTINGS_COLLAPSED": False, + "LOG_WINDOW_STARTUP": False, "RICH_PRESENCE": False, + }, "99-Panels": {}, + }) + self.assertFalse(read_json(destination / "lab-profile.json")["hardware_configured"]) + self.assertEqual((self.source / SETTINGS).read_bytes(), before) + + def test_refuses_existing_profile_without_changing_it(self): + destination = seed(self.source, self.root, "lab-A") + original = (destination / SETTINGS).read_bytes() + with self.assertRaisesRegex(ValueError, "already exists"): + seed(self.source, self.root, "lab-A") + self.assertEqual((destination / SETTINGS).read_bytes(), original) + + def test_invalid_or_default_names_are_refused(self): + for name in ("", "default", "unit-tests", "../lab-A", "lab-", "lab-A/B", "lab-é"): + with self.subTest(profile=name), self.assertRaises(ValueError): + seed(self.source, self.root, name) + + def test_symlink_profile_directory_does_not_escape_root(self): + outside = self.root / "outside" + outside.mkdir() + (self.root / "Profiles").symlink_to(outside, target_is_directory=True) + with self.assertRaisesRegex(ValueError, "redirect"): + seed(self.source, self.root, "lab-A") + self.assertEqual(list(outside.iterdir()), []) + + +class PackageTests(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = Path(self.temporary.name) + self.app = self.root / "original.app" + self.binary = self.app / "Contents/MacOS/SerialPrograms" + self.binary.parent.mkdir(parents=True) + self.binary.write_bytes(b"fake executable: must never be run") + self.plist = self.app / "Contents/Info.plist" + with self.plist.open("wb") as stream: + plistlib.dump({"CFBundleExecutable": "SerialPrograms", "CFBundleIdentifier": "original"}, stream) + self.receipt_path = Path(str(self.binary) + ".lab-build.json") + self.receipt = { + "schema": 1, "profile": "lab-A", "source_revision": "a" * 40, + "source_clean": True, "binary_sha256": sha256(self.binary), + } + write_json(self.receipt_path, self.receipt) + self.calls = [] + + def signing(self, arguments): + self.calls.append(arguments) + if "--sign" in arguments: + binary = Path(arguments[-1]) / "Contents/MacOS/SerialPrograms" + binary.write_bytes(binary.read_bytes() + b":signed") + + def package(self, output="slot-A", peers=(), signer=None): + return stage(self.app, self.root / output, "lab-A", "A", + "com.dayfine.pokemonautomation.labA", "test identity", peers, + signer or self.signing) + + def replace_receipt(self, receipt): + self.receipt_path.write_text(json.dumps(receipt), encoding="utf-8") + + def test_round_trip_checks_post_signing_hash_and_preserves_original(self): + original = self.binary.read_bytes(), self.plist.read_bytes() + manifest = self.package() + deployed = verify(manifest, "lab-A", signer=self.signing) + self.assertEqual(deployed["source_revision"], "a" * 40) + self.assertFalse(deployed["hardware_ownership_enforced"]) + self.assertNotEqual(deployed["binary_sha256"], self.receipt["binary_sha256"]) + self.assertEqual((self.binary.read_bytes(), self.plist.read_bytes()), original) + self.assertEqual(len(self.calls), 3) + + def test_missing_receipt_is_refused_without_signing(self): + self.receipt_path.unlink() + with self.assertRaises(FileNotFoundError): + self.package() + self.assertEqual(self.calls, []) + self.assertFalse((self.root / "slot-A").exists()) + + def test_wrong_unbound_dirty_or_stale_receipt_is_refused(self): + cases = [ + {"profile": ""}, {"profile": "lab-B"}, {"source_clean": False}, + {"source_revision": "short"}, {"binary_sha256": "0" * 64}, {"schema": 2}, + ] + for changes in cases: + with self.subTest(changes=changes), self.assertRaises(ValueError): + self.replace_receipt(dict(self.receipt, **changes)) + self.package() + self.assertEqual(self.calls, []) + + def test_binary_changed_after_build_is_refused(self): + self.binary.write_bytes(b"a different build") + with self.assertRaisesRegex(ValueError, "differs"): + preflight(self.app, "lab-A") + + def test_peer_collision_on_each_identity_is_refused(self): + peer = {"profile": "lab-B", "console": "B", "bundle_id": "com.dayfine.pokemonautomation.labB"} + for field, value in (("profile", "lab-A"), ("console", "A"), ("bundle_id", "com.dayfine.pokemonautomation.labA")): + with self.subTest(field=field), self.assertRaisesRegex(ValueError, field): + path = self.root / (field + ".json") + write_json(path, dict(peer, **{field: value})) + self.package(peers=[path]) + self.assertEqual(self.calls, []) + + def test_existing_output_is_not_replaced(self): + path = self.root / "slot-A" + path.mkdir() + (path / "keep").write_text("untouched") + with self.assertRaises(FileExistsError): + self.package() + self.assertEqual((path / "keep").read_text(), "untouched") + + def test_sign_failure_removes_only_new_staging_directory(self): + def failure(arguments): + raise subprocess.CalledProcessError(1, "codesign") + with self.assertRaises(subprocess.CalledProcessError): + self.package(signer=failure) + self.assertFalse((self.root / "slot-A").exists()) + self.assertTrue(self.binary.is_file()) + + def test_package_change_or_wrong_profile_is_refused(self): + manifest = self.package() + with self.assertRaises(ValueError): + verify(manifest, "lab-B", signer=self.signing) + binary = manifest.parent / "SerialPrograms.app/Contents/MacOS/SerialPrograms" + binary.write_bytes(b"changed after deployment") + with self.assertRaisesRegex(ValueError, "changed"): + verify(manifest, "lab-A", signer=self.signing) + + def test_signature_failure_is_not_ignored(self): + manifest = self.package() + def failure(arguments): + raise subprocess.CalledProcessError(1, "codesign") + with self.assertRaises(subprocess.CalledProcessError): + verify(manifest, "lab-A", signer=failure) + + def test_relabeling_manifest_cannot_change_compiled_profile(self): + manifest = self.package() + data = read_json(manifest) + data["profile"] = "lab-B" + manifest.write_text(json.dumps(data), encoding="utf-8") + with self.assertRaisesRegex(ValueError, "build receipt"): + verify(manifest, "lab-B", signer=self.signing) + + def test_cli_rejects_old_or_unbound_build_without_launching_it(self): + import sys + self.receipt_path.unlink() + tool = Path(__file__).with_name("lab_instance.py") + result = subprocess.run([sys.executable, str(tool), "preflight", "--app", str(self.app), + "--profile", "lab-A"], capture_output=True, text=True) + self.assertEqual(result.returncode, 2) + self.assertIn("refused", result.stderr) + + @unittest.skipUnless(shutil.which("cmake") and shutil.which("git"), "CMake and Git required") + def test_actual_cmake_receipt_matches_binary_and_clears_unbound_receipt(self): + source = self.root / "source" + source.mkdir() + def git(*arguments): + return subprocess.run(["git", *arguments], cwd=source, check=True, capture_output=True) + git("init") + git("-c", "user.name=Test", "-c", "user.email=test@example.invalid", "commit", "--allow-empty", "-m", "fixture") + script = Path(__file__).resolve().parents[2] / "SerialPrograms/cmake/LabBuildReceipt.cmake" + def receipt(profile): + subprocess.run(["cmake", "-DBINARY=" + str(self.binary), "-DPROFILE=" + profile, + "-DSOURCE=" + str(source), "-P", str(script)], check=True, capture_output=True) + receipt("lab-A") + self.assertEqual(preflight(self.app, "lab-A")["source_revision"], git("rev-parse", "HEAD").stdout.decode().strip()) + (source / "untracked").write_text("dirty") + receipt("lab-A") + with self.assertRaisesRegex(ValueError, "clean"): + preflight(self.app, "lab-A") + receipt("") + self.assertFalse(self.receipt_path.exists()) + + +if __name__ == "__main__": + unittest.main()