From 5d99c2f5136a4e91976a8e02e5aee8009aafc36e Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 05:40:51 -0800 Subject: [PATCH 1/3] Lab: seed isolated profiles and validate staged app identity --- .github/workflows/lab-instance-tools.yml | 21 ++ SerialPrograms/CMakeLists.txt | 12 ++ SerialPrograms/cmake/LabBuildReceipt.cmake | 21 ++ devtools/lab/INSTANCE_PREPARATION.md | 113 +++++++++++ devtools/lab/README.md | 5 + devtools/lab/lab_instance.py | 54 +++++ devtools/lab/lab_package.py | 126 ++++++++++++ devtools/lab/lab_profiles.py | 69 +++++++ devtools/lab/test_lab_instance.py | 217 +++++++++++++++++++++ 9 files changed, 638 insertions(+) create mode 100644 .github/workflows/lab-instance-tools.yml create mode 100644 SerialPrograms/cmake/LabBuildReceipt.cmake create mode 100644 devtools/lab/INSTANCE_PREPARATION.md create mode 100644 devtools/lab/lab_instance.py create mode 100644 devtools/lab/lab_package.py create mode 100644 devtools/lab/lab_profiles.py create mode 100644 devtools/lab/test_lab_instance.py 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..b31e5ffb28 --- /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 of `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..948d528e44 --- /dev/null +++ b/devtools/lab/lab_profiles.py @@ -0,0 +1,69 @@ +"""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 = "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: + 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..f46d75b4dd --- /dev/null +++ b/devtools/lab/test_lab_instance.py @@ -0,0 +1,217 @@ +"""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.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() From 67f8dcee74fb37ca6ec147a6a3b89e7d986714c7 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 05:41:44 -0800 Subject: [PATCH 2/3] Lab: seed settings under the runtime UserSettings path --- devtools/lab/INSTANCE_PREPARATION.md | 2 +- devtools/lab/lab_profiles.py | 3 ++- devtools/lab/test_lab_instance.py | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/devtools/lab/INSTANCE_PREPARATION.md b/devtools/lab/INSTANCE_PREPARATION.md index b31e5ffb28..88a7d38161 100644 --- a/devtools/lab/INSTANCE_PREPARATION.md +++ b/devtools/lab/INSTANCE_PREPARATION.md @@ -6,7 +6,7 @@ app, sends a command, changes permissions, or opens a controller or capture devi ## Seed profiles without copying live state -Work from an offline snapshot of `SerialPrograms-Settings.json`, taken while the +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: diff --git a/devtools/lab/lab_profiles.py b/devtools/lab/lab_profiles.py index 948d528e44..6593d9a91a 100644 --- a/devtools/lab/lab_profiles.py +++ b/devtools/lab/lab_profiles.py @@ -8,7 +8,7 @@ import tempfile -SETTINGS = "SerialPrograms-Settings.json" +SETTINGS = "UserSettings/SerialPrograms-Settings.json" PREFERENCES = {"THEME", "WINDOW_SIZE", "LOG_WINDOW_SIZE", "CONSOLE_SETTINGS_COLLAPSED"} @@ -55,6 +55,7 @@ def seed(source, root, profile): 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, diff --git a/devtools/lab/test_lab_instance.py b/devtools/lab/test_lab_instance.py index f46d75b4dd..177ece5a5a 100644 --- a/devtools/lab/test_lab_instance.py +++ b/devtools/lab/test_lab_instance.py @@ -19,6 +19,7 @@ def setUp(self): 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, From 45afc7eb048b638f34a62e79c8bbf7d65a377e1e Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 06:17:01 -0800 Subject: [PATCH 3/3] Lab: enforce profile and device leases before hardware opens --- .github/workflows/lab-device-tests.yml | 19 ++ SerialPrograms/CMakeLists.txt | 9 + .../Backends/AudioPassthroughPairQt.cpp | 21 +- .../Backends/AudioPassthroughPairQt.h | 1 + .../AudioPipeline/IO/AudioInputDevice.cpp | 1 + .../AudioPipeline/IO/AudioInputDevice.h | 2 + .../Sources/AudioSource_Device.cpp | 6 +- .../CommonFramework/Devices/CMakeLists.txt | 20 ++ .../Devices/LabDeviceAccessQt.cpp | 130 +++++++ .../Devices/LabDeviceAccessQt.h | 72 ++++ .../Devices/LabDeviceAccessQt_Tests.cpp | 319 ++++++++++++++++++ .../Devices/LabDeviceAccessQt_Tests.h | 16 + .../Devices/LabDeviceRuntime.cpp | 98 ++++++ .../Devices/LabDeviceRuntime.h | 26 ++ .../Source/CommonFramework/Main.cpp | 10 + .../Backends/CameraWidgetQt6.5.cpp | 15 +- .../Backends/CameraWidgetQt6.cpp | 12 +- .../Backends/CameraWidgetQt6_QQuickWidget.cpp | 12 +- .../VideoPipeline/Backends/QCameraThread.h | 18 +- .../ComputerPrograms_UnitTestRunner.cpp | 2 + .../SerialPABotBase2_Connection.cpp | 21 +- .../PABotBase2/SerialPABotBase2_Connection.h | 8 + SerialPrograms/cmake/SourceFiles.cmake | 6 + devtools/lab/DEVICE_OWNERSHIP.md | 120 +++++++ 24 files changed, 919 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/lab-device-tests.yml create mode 100644 SerialPrograms/Source/CommonFramework/Devices/CMakeLists.txt create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.h create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.h create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.h create mode 100644 devtools/lab/DEVICE_OWNERSHIP.md diff --git a/.github/workflows/lab-device-tests.yml b/.github/workflows/lab-device-tests.yml new file mode 100644 index 0000000000..297dad2582 --- /dev/null +++ b/.github/workflows/lab-device-tests.yml @@ -0,0 +1,19 @@ +name: Lab device ownership +on: + pull_request: + workflow_dispatch: +jobs: + native-leases: + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v7 + - uses: jurplel/install-qt-action@v4 + with: + version: '6.10.2' + cache: true + - run: cmake -S SerialPrograms/Source/CommonFramework/Devices -B build-lab-devices -DCMAKE_BUILD_TYPE=Debug + - run: cmake --build build-lab-devices --config Debug -j4 + - run: ctest --test-dir build-lab-devices -C Debug --output-on-failure diff --git a/SerialPrograms/CMakeLists.txt b/SerialPrograms/CMakeLists.txt index 077a2d8def..687f85063b 100644 --- a/SerialPrograms/CMakeLists.txt +++ b/SerialPrograms/CMakeLists.txt @@ -909,3 +909,12 @@ if(COMMAND_LINE_EXE) # Add command-line executable (GUI-free) from subdirectory include(Source/CommandLine/CommandLineExecutable.cmake) endif() + +# The registered cross-process tests use this GUI-free native runner as their child. +add_subdirectory(Source/CommonFramework/Devices) +if(WIN32) + set_target_properties(LabDeviceAccessTests PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${WIN_DEPLOY_DIR}") +else() + set_target_properties(LabDeviceAccessTests PROPERTIES RUNTIME_OUTPUT_DIRECTORY "$") +endif() +add_dependencies(SerialPrograms LabDeviceAccessTests) diff --git a/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.cpp b/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.cpp index 4bb1f84370..51bfcf9936 100644 --- a/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.cpp +++ b/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.cpp @@ -406,16 +406,12 @@ void AudioPassthroughPairQt::reset( auto scope_check = m_sanitizer.check_scope(); QMetaObject::invokeMethod(this, [this, format, descriptor, output, output_volume]{ auto scope_check = m_sanitizer.check_scope(); + close_audio_source(); std::unique_ptr source; if (descriptor){ source = descriptor->make_AudioSource(m_logger, format); } WriteSpinLock lg(m_lock, PA_CURRENT_FUNCTION); - if (m_reader){ - teardown_tree(); - m_sink_device.reset(); - m_reader.reset(); - } m_input_choice = format; m_output_device = output; m_output_volume = output_volume; @@ -427,6 +423,15 @@ void AudioPassthroughPairQt::reset( } }); } +// Called on this object's Qt thread before constructing a replacement input. +void AudioPassthroughPairQt::close_audio_source(){ + WriteSpinLock lg(m_lock, PA_CURRENT_FUNCTION); + if (m_reader){ + teardown_tree(); + m_sink_device.reset(); + m_reader.reset(); + } +} void AudioPassthroughPairQt::clear_audio_source(){ auto scope_check = m_sanitizer.check_scope(); QMetaObject::invokeMethod(this, [this]{ @@ -447,16 +452,12 @@ void AudioPassthroughPairQt::set_audio_source( auto scope_check = m_sanitizer.check_scope(); QMetaObject::invokeMethod(this, [this, descriptor, format]{ auto scope_check = m_sanitizer.check_scope(); + close_audio_source(); std::unique_ptr source; if (descriptor){ source = descriptor->make_AudioSource(m_logger, format); } WriteSpinLock lg(m_lock, PA_CURRENT_FUNCTION); - if (m_reader){ - teardown_tree(); - m_sink_device.reset(); - m_reader.reset(); - } m_input_choice = format; if (source){ m_reader = std::move(source); diff --git a/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.h b/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.h index 014b9c2da7..872904e33f 100644 --- a/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.h +++ b/SerialPrograms/Source/CommonFramework/AudioPipeline/Backends/AudioPassthroughPairQt.h @@ -97,6 +97,7 @@ class AudioPassthroughPairQt final : public QObject, public AudioPassthroughPair // thread only ever sees them through the node listener sets, where // ListenerSet::remove blocks on in-flight pushes so rebuilds never // race a live push. + void close_audio_source(); void teardown_tree(); void teardown_sink_branch(); void build_tree(float input_volume); diff --git a/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.cpp b/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.cpp index 758ccc70b8..0795682ce4 100644 --- a/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.cpp +++ b/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.cpp @@ -53,6 +53,7 @@ AudioInputDevice::AudioInputDevice( RAW_BUFFER_CAPACITY ) , ObjectStreamListener(raw_output_frame_bytes(format, reinterpret_96k_mono_as_stereo)) + , m_device_lease(acquire_lab_capture(logger, LabDeviceKind::AUDIO, device.id().toHex().toStdString())) , m_sample_type(sample_format_of(format)) , m_sample_rate(format.sampleRate()) , m_channels(format.channelCount()) diff --git a/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.h b/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.h index 2ef2c7365b..fba2d91614 100644 --- a/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.h +++ b/SerialPrograms/Source/CommonFramework/AudioPipeline/IO/AudioInputDevice.h @@ -17,6 +17,7 @@ using NativeAudioSource = QAudioSource; #include "Common/Cpp/StreamConverters.h" #include "Kernels/AudioPipeline/Kernels_AudioPipeline.h" #include "CommonFramework/AudioPipeline/AudioFormat.h" +#include "CommonFramework/Devices/LabDeviceRuntime.h" class QAudioFormat; @@ -87,6 +88,7 @@ class AudioInputDevice final private: + std::unique_ptr m_device_lease; std::unique_ptr m_source; Kernels::AudioPipeline::SampleFormat m_sample_type; size_t m_sample_rate; diff --git a/SerialPrograms/Source/CommonFramework/AudioPipeline/Sources/AudioSource_Device.cpp b/SerialPrograms/Source/CommonFramework/AudioPipeline/Sources/AudioSource_Device.cpp index 18706767e7..afca55d3ba 100644 --- a/SerialPrograms/Source/CommonFramework/AudioPipeline/Sources/AudioSource_Device.cpp +++ b/SerialPrograms/Source/CommonFramework/AudioPipeline/Sources/AudioSource_Device.cpp @@ -68,7 +68,11 @@ std::unique_ptr AudioSourceDescriptor_Device::make_AudioSource( return nullptr; } // cout << "format = " << (int)format << endl; - return std::make_unique(logger, m_info, format); + try{ + return std::make_unique(logger, m_info, format); + }catch (UserSetupError&){ + return nullptr; // Refusal is logged; never throw across the Qt audio callback. + } } diff --git a/SerialPrograms/Source/CommonFramework/Devices/CMakeLists.txt b/SerialPrograms/Source/CommonFramework/Devices/CMakeLists.txt new file mode 100644 index 0000000000..dba4f55b10 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/CMakeLists.txt @@ -0,0 +1,20 @@ +# Focused native tests, without configuring/linking the GUI application: +# cmake -S SerialPrograms/Source/CommonFramework/Devices -B /path/to/test-build +# cmake --build /path/to/test-build -j4 +# ctest --test-dir /path/to/test-build --output-on-failure +cmake_minimum_required(VERSION 3.24) +if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR) + project(LabDeviceAccessTests LANGUAGES CXX) + enable_testing() + find_package(Qt6 REQUIRED COMPONENTS Core) +endif() +add_executable(LabDeviceAccessTests LabDeviceAccessQt.cpp LabDeviceAccessQt_Tests.cpp) +target_compile_features(LabDeviceAccessTests PRIVATE cxx_std_23) +target_compile_definitions(LabDeviceAccessTests PRIVATE PA_LAB_DEVICE_STANDALONE_TESTS) +target_link_libraries(LabDeviceAccessTests PRIVATE Qt6::Core) +if(MSVC) + target_compile_options(LabDeviceAccessTests PRIVATE /W4 /WX) +else() + target_compile_options(LabDeviceAccessTests PRIVATE -Wall -Wextra -Werror) +endif() +add_test(NAME LabDeviceAccess COMMAND LabDeviceAccessTests) diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.cpp b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.cpp new file mode 100644 index 0000000000..6a710003ae --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.cpp @@ -0,0 +1,130 @@ +/* Lab Device Access (Qt process-lock seam) + * + * From: https://github.com/PokemonAutomation/ + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "LabDeviceAccessQt.h" + +namespace PokemonAutomation{ +namespace{ + +QString text(std::string_view value){ + return QString::fromUtf8(value.data(), (qsizetype)value.size()); +} + +std::set read_ids(const QJsonObject& object, const char* key){ + if (!object.value(key).isArray()){ + throw std::runtime_error(std::string("Expected device array: ") + key); + } + std::set ids; + for (const QJsonValue& value : object.value(key).toArray()){ + const std::string id = value.toString().toStdString(); + if (!value.isString() || id.empty() || id.find('\0') != std::string::npos || !ids.emplace(id).second){ + throw std::runtime_error(std::string("Empty, invalid or duplicate device ID in ") + key); + } + } + return ids; +} + +bool permitted(const LabDevicePolicy& policy, const LabDeviceIdentity& device){ + switch (device.kind){ + case LabDeviceKind::SERIAL: return policy.serial.contains(device.id); + case LabDeviceKind::VIDEO: return policy.video.contains(device.id); + case LabDeviceKind::AUDIO: return policy.audio.contains(device.id); + case LabDeviceKind::PROFILE: return false; + } + return false; +} + +std::string normalize_serial_path(std::string_view path){ + if (path.starts_with("/dev/tty.")){ + return "/dev/cu." + std::string(path.substr(9)); + } + return std::string(path); +} + +} // namespace + +LabDevicePolicy parse_lab_device_policy(std::string_view json, std::string_view profile){ + QJsonParseError error; + const QJsonDocument document = QJsonDocument::fromJson(QByteArray(json.data(), (qsizetype)json.size()), &error); + const QJsonObject object = document.object(); + const std::set keys{"schema", "profile", "serial", "video", "audio"}; + for (auto it = object.begin(); it != object.end(); ++it){ + if (!keys.contains(it.key())){ + throw std::runtime_error("Unknown field in lab device policy."); + } + } + if (error.error != QJsonParseError::NoError || !document.isObject() || object.size() != 5 || + !object.value("schema").isDouble() || object.value("schema").toDouble() != 1 || + profile.empty() || object.value("profile").toString() != text(profile)){ + throw std::runtime_error("Missing, malformed or mismatched lab device policy."); + } + return {std::string(profile), read_ids(object, "serial"), read_ids(object, "video"), read_ids(object, "audio")}; +} + +std::string lab_serial_identity(unsigned vendor, unsigned product, std::string_view serial){ + if (vendor > 0xffff || product > 0xffff || serial.empty() || serial.find('\0') != std::string_view::npos){ + throw std::runtime_error("A unique USB serial, vendor and product identity are required."); + } + return std::format("{:04x}:{:04x}:{}", vendor, product, serial); +} + +std::string resolve_lab_serial_identity(std::span devices, std::string_view port){ + const std::string path = normalize_serial_path(port); + const auto selected = std::ranges::find_if(devices, [&](const LabSerialDevice& device){ + return normalize_serial_path(device.port) == path; + }); + if (selected == devices.end()){ + throw std::runtime_error("Controller has no current USB identity; hardware access is disabled."); + } + const std::string identity = lab_serial_identity(selected->vendor, selected->product, selected->serial); + for (const LabSerialDevice& other : devices){ + if (normalize_serial_path(other.port) != path && !other.serial.empty() && + lab_serial_identity(other.vendor, other.product, other.serial) == identity){ + throw std::runtime_error("Two adapters report the same USB identity; refusing ambiguous ownership."); + } + } + return identity; +} + +std::string lab_device_lock_path(std::string_view directory, const LabDeviceIdentity& device){ + if (directory.empty() || device.id.empty()){ + throw std::runtime_error("Device lease directory and identity must be nonempty."); + } + const QByteArray key = QByteArray::number((int)device.kind) + ':' + QByteArray(device.id.data(), (qsizetype)device.id.size()); + const QByteArray digest = QCryptographicHash::hash(key, QCryptographicHash::Sha256).toHex(); + return QDir(text(directory)).filePath(QString::fromLatin1(digest) + ".lock").toStdString(); +} + +LabDeviceLease::LabDeviceLease(std::string_view path) + : m_lock(text(path)) +{ + // Age alone must never evict an active multi-hour lab run. + m_lock.setStaleLockTime(std::chrono::milliseconds::zero()); + if (!m_lock.tryLock(std::chrono::milliseconds::zero())){ + throw std::runtime_error("Device/profile is already leased, or its lock cannot be created. Nothing was opened."); + } +} + +std::unique_ptr acquire_lab_device( + const LabDevicePolicy& policy, std::string_view directory, const LabDeviceIdentity& device +){ + if (!permitted(policy, device)){ + throw std::runtime_error("Device is not allowlisted for profile " + policy.profile + ". Nothing was opened."); + } + if (!QDir().mkpath(text(directory))){ + throw std::runtime_error("Cannot create shared device lease directory. Nothing was opened."); + } + return std::make_unique(lab_device_lock_path(directory, device)); +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.h b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.h new file mode 100644 index 0000000000..669ce69f9d --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt.h @@ -0,0 +1,72 @@ +/* Lab Device Access (Qt process-lock seam) + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_LabDeviceAccessQt_H +#define PokemonAutomation_LabDeviceAccessQt_H + +#include +#include +#include +#include +#include +#include + +namespace PokemonAutomation{ + +// Separate namespaces for serial, video, audio and whole-profile reservations. +enum class LabDeviceKind{ SERIAL, VIDEO, AUDIO, PROFILE }; + +// Stable hardware identity, never a display alias, ordinal or USB port pathname. +struct LabDeviceIdentity{ + LabDeviceKind kind; + std::string id; +}; + +// Immutable allowlist loaded once for the selected lab profile. +struct LabDevicePolicy{ + std::string profile; + std::set serial; + std::set video; + std::set audio; +}; + +// One currently enumerated USB port; tty/cu aliases may describe the same adapter. +struct LabSerialDevice{ + std::string port; + unsigned vendor; + unsigned product; + std::string serial; +}; + +// Resolve a selected current port, rejecting missing or ambiguous physical identity. +std::string resolve_lab_serial_identity(std::span devices, std::string_view port); + +// Parse the strict schema; malformed/mismatched input throws std::runtime_error. +LabDevicePolicy parse_lab_device_policy(std::string_view json, std::string_view profile); + +// Normalize VID/PID and a nonempty USB serial; empty identifiers are refused. +std::string lab_serial_identity(unsigned vendor, unsigned product, std::string_view serial); + +// Compute a shared lock path independent of profile, executable and display names. +std::string lab_device_lock_path(std::string_view directory, const LabDeviceIdentity& device); + +// A noncopyable process lease. Destruction releases it; dead owners are recovered by Qt. +// Keep this alive until after the native device has closed. Acquisition never waits. +class LabDeviceLease{ +public: + explicit LabDeviceLease(std::string_view path); + LabDeviceLease(const LabDeviceLease&) = delete; + LabDeviceLease& operator=(const LabDeviceLease&) = delete; +private: + QLockFile m_lock; +}; + +// Check the allowlist before acquiring a lease. A denial never touches hardware. +// Throws std::runtime_error on denied access, contention or filesystem failure. +std::unique_ptr acquire_lab_device( + const LabDevicePolicy& policy, std::string_view directory, const LabDeviceIdentity& device +); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.cpp b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.cpp new file mode 100644 index 0000000000..7cdd125946 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.cpp @@ -0,0 +1,319 @@ +/* Lab Device Access Tests + * + * From: https://github.com/PokemonAutomation/ + * + * PR #226 startup incident: a Console B test build opened Console A's controller. + * These tests never enumerate or open physical devices, or load real profiles. + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "LabDeviceAccessQt.h" +#ifndef PA_LAB_DEVICE_STANDALONE_TESTS +#include "LabDeviceAccessQt_Tests.h" +#endif + +namespace PokemonAutomation{ +namespace{ + +struct PolicyInput{ + std::string_view name; + std::string_view json; + LabDeviceIdentity requested; +}; + +struct PolicyExpectation{ + int opens = 0; +}; + +struct PolicyCase{ + PolicyInput input; + PolicyExpectation expectation; +}; + +struct SerialInput{ + std::string_view name; + std::vector devices; + std::string_view port; +}; + +struct SerialExpectation{ + std::optional identity = std::nullopt; +}; + +struct SerialCase{ + SerialInput input; + SerialExpectation expectation; +}; + +const SerialCase SERIAL_CASES[] = { + {.input = {.name = "USB serial identity", .devices = {{"/dev/cu.A", 0x10c4, 0xea60, "A"}}, .port = "/dev/cu.A"}, .expectation = {.identity = "10c4:ea60:A"}}, + {.input = {.name = "tty and cu share a key", .devices = {{"/dev/tty.A", 0x10c4, 0xea60, "A"}, {"/dev/cu.A", 0x10c4, 0xea60, "A"}}, .port = "/dev/cu.A"}, .expectation = {.identity = "10c4:ea60:A"}}, + {.input = {.name = "two adapters with duplicate serial", .devices = {{"/dev/cu.A", 0x10c4, 0xea60, "same"}, {"/dev/cu.B", 0x10c4, 0xea60, "same"}}, .port = "/dev/cu.A"}, .expectation = {}}, + {.input = {.name = "missing USB serial", .devices = {{"/dev/cu.A", 0x10c4, 0xea60, ""}}, .port = "/dev/cu.A"}, .expectation = {}}, + {.input = {.name = "unplugged adapter", .devices = {}, .port = "/dev/cu.A"}, .expectation = {}}, + {.input = {.name = "path reused by another adapter", .devices = {{"/dev/cu.A", 0x10c4, 0xea60, "B"}}, .port = "/dev/cu.A"}, .expectation = {.identity = "10c4:ea60:B"}}, +}; + +std::string check_serial(const SerialCase& test){ + std::optional identity; + try{ + identity = resolve_lab_serial_identity(test.input.devices, test.input.port); + }catch (const std::runtime_error&){} + if (identity != test.expectation.identity){ + return "Expected identity " + test.expectation.identity.value_or("") + "; read " + identity.value_or(""); + } + return {}; +} + +const PolicyCase POLICY_CASES[] = { + {.input = {.name = "matching serial", .json = R"({"schema":1,"profile":"lab-B","serial":["10c4:ea60:B"],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, "10c4:ea60:B"}}, .expectation = {.opens = 1}}, + {.input = {.name = "wrong console serial", .json = R"({"schema":1,"profile":"lab-B","serial":["10c4:ea60:B"],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, "10c4:ea60:A"}}, .expectation = {}}, + {.input = {.name = "camera allowed", .json = R"({"schema":1,"profile":"lab-B","serial":[],"video":["766964656f42"],"audio":[]})", .requested = {LabDeviceKind::VIDEO, "766964656f42"}}, .expectation = {.opens = 1}}, + {.input = {.name = "audio allowed", .json = R"({"schema":1,"profile":"lab-B","serial":[],"video":[],"audio":["617564696f42"]})", .requested = {LabDeviceKind::AUDIO, "617564696f42"}}, .expectation = {.opens = 1}}, + {.input = {.name = "camera not audio", .json = R"({"schema":1,"profile":"lab-B","serial":[],"video":["same-id"],"audio":[]})", .requested = {LabDeviceKind::AUDIO, "same-id"}}, .expectation = {}}, + {.input = {.name = "mismatched profile", .json = R"({"schema":1,"profile":"lab-A","serial":["port"],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "missing policy", .json = "", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "malformed policy", .json = "{", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "unsupported schema", .json = R"({"schema":2,"profile":"lab-B","serial":["port"],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "duplicate identity", .json = R"({"schema":1,"profile":"lab-B","serial":["port","port"],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "missing audio list", .json = R"({"schema":1,"profile":"lab-B","serial":["port"],"video":[]})", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, + {.input = {.name = "empty identity", .json = R"({"schema":1,"profile":"lab-B","serial":[""],"video":[],"audio":[]})", .requested = {LabDeviceKind::SERIAL, ""}}, .expectation = {}}, + {.input = {.name = "unknown policy field", .json = R"({"schema":1,"profile":"lab-B","serial":["port"],"video":[],"audio":[],"allow_all":true})", .requested = {LabDeviceKind::SERIAL, "port"}}, .expectation = {}}, +}; + +std::string check_policy(const PolicyCase& test){ + QTemporaryDir directory; + if (!directory.isValid()){ + return "Cannot create temporary lease directory."; + } + int opens = 0; + try{ + const auto policy = parse_lab_device_policy(test.input.json, "lab-B"); + auto lease = acquire_lab_device(policy, directory.path().toStdString(), test.input.requested); + opens++; // Scripted native open: no real port, camera or microphone exists. + }catch (const std::runtime_error&){} + if (opens != test.expectation.opens){ + return "Expected opens " + std::to_string(test.expectation.opens) + "; read " + std::to_string(opens); + } + return {}; +} + +enum class LeaseScenario{ SAME_PROCESS, DIFFERENT_DEVICE, DIFFERENT_KIND, RELEASE, FAILED_OPEN, LONG_RUNNING, LIVE_CHILD, DEAD_CHILD, PROFILE, EARLY_CHILD }; + +struct LeaseInput{ + std::string_view name; + LeaseScenario scenario; +}; + +struct LeaseExpectation{ + bool second_opens; +}; + +struct LeaseCase{ + LeaseInput input; + LeaseExpectation expectation; +}; + +const LeaseCase LEASE_CASES[] = { + {.input = {.name = "same device two profiles", .scenario = LeaseScenario::SAME_PROCESS}, .expectation = {.second_opens = false}}, + {.input = {.name = "different consoles", .scenario = LeaseScenario::DIFFERENT_DEVICE}, .expectation = {.second_opens = true}}, + {.input = {.name = "video and audio inputs", .scenario = LeaseScenario::DIFFERENT_KIND}, .expectation = {.second_opens = true}}, + {.input = {.name = "disconnect then reconnect", .scenario = LeaseScenario::RELEASE}, .expectation = {.second_opens = true}}, + {.input = {.name = "failed native open releases lease", .scenario = LeaseScenario::FAILED_OPEN}, .expectation = {.second_opens = true}}, +#if !defined(_WIN32) + // Windows' live lock prevents editing this timestamp fixture; exercise it on POSIX. + {.input = {.name = "age never steals live lease", .scenario = LeaseScenario::LONG_RUNNING}, .expectation = {.second_opens = false}}, +#endif + {.input = {.name = "live second process", .scenario = LeaseScenario::LIVE_CHILD}, .expectation = {.second_opens = false}}, + {.input = {.name = "profile reserved before Qt startup", .scenario = LeaseScenario::EARLY_CHILD}, .expectation = {.second_opens = false}}, + {.input = {.name = "killed owner recovery", .scenario = LeaseScenario::DEAD_CHILD}, .expectation = {.second_opens = true}}, + {.input = {.name = "duplicate profile", .scenario = LeaseScenario::PROFILE}, .expectation = {.second_opens = false}}, +}; + +std::string test_helper_path(){ + QString name = "LabDeviceAccessTests"; +#if defined(_WIN32) + name += ".exe"; +#endif + return QDir(QCoreApplication::applicationDirPath()).filePath(name).toStdString(); +} + +void start_lease_child(QProcess& child, const std::string& path, LeaseScenario scenario){ + const QString flag = scenario == LeaseScenario::EARLY_CHILD ? "--lease-before-qt" : "--lease-child"; + child.start(QString::fromStdString(test_helper_path()), {flag, QString::fromStdString(path)}); + if (!child.waitForStarted(5000) || !child.waitForReadyRead(5000) || child.readAllStandardOutput().trimmed() != "LOCKED"){ + throw std::runtime_error("Lease test child did not confirm ownership."); + } +} + +std::unique_ptr prepare_owner(LeaseScenario scenario, const std::string& path, QProcess& child){ + if (scenario == LeaseScenario::LIVE_CHILD || scenario == LeaseScenario::DEAD_CHILD || scenario == LeaseScenario::EARLY_CHILD){ + start_lease_child(child, path, scenario); + if (scenario == LeaseScenario::DEAD_CHILD){ + child.kill(); + if (!child.waitForFinished(5000)){ + throw std::runtime_error("Child did not exit after kill."); + } + } + return nullptr; + } + auto owner = std::make_unique(path); + if (scenario == LeaseScenario::FAILED_OPEN){ + try{ + auto opening = std::move(owner); + throw std::runtime_error("Scripted native open failed."); + }catch (const std::runtime_error&){} + } + if (scenario == LeaseScenario::RELEASE){ + owner.reset(); + } + if (scenario == LeaseScenario::LONG_RUNNING){ + QFile lock(QString::fromStdString(path)); + if (!lock.open(QIODevice::ReadOnly) || !lock.setFileTime(QDateTime::currentDateTimeUtc().addDays(-2), QFileDevice::FileModificationTime)){ + throw std::runtime_error("Could not age the lock fixture."); + } + } + return owner; +} + +std::string check_lease(const LeaseCase& test){ + QTemporaryDir directory; + if (!directory.isValid()){ + return "Cannot create temporary lease directory."; + } + LabDevicePolicy policy{"lab-B", {"port-A", "port-B"}, {"port-A"}, {}}; + LabDeviceIdentity first{LabDeviceKind::SERIAL, "port-A"}; + if (test.input.scenario == LeaseScenario::PROFILE){ + first.kind = LabDeviceKind::PROFILE; + } + const std::string root = directory.path().toStdString(); + const std::string path = lab_device_lock_path(root, first); + QProcess child; + try{ + auto owner = prepare_owner(test.input.scenario, path, child); + LabDeviceIdentity second = first; + if (test.input.scenario == LeaseScenario::DIFFERENT_DEVICE){ + second.id = "port-B"; + } + if (test.input.scenario == LeaseScenario::DIFFERENT_KIND){ + second.kind = LabDeviceKind::VIDEO; + } + bool opened = false; + try{ + auto lease = second.kind == LabDeviceKind::PROFILE + ? std::make_unique(lab_device_lock_path(root, second)) + : acquire_lab_device(policy, root, second); + opened = true; + }catch (const std::runtime_error&){} + child.kill(); + child.waitForFinished(5000); + if (opened != test.expectation.second_opens){ + return "Expected second opens " + std::to_string(test.expectation.second_opens) + "; read " + std::to_string(opened); + } + }catch (const std::runtime_error& error){ + child.kill(); + child.waitForFinished(5000); + return error.what(); + } + return {}; +} + +#ifndef PA_LAB_DEVICE_STANDALONE_TESTS +class SerialTest : public UnitTest{ +public: + explicit SerialTest(const SerialCase& test) : UnitTest("LabDevices/Serial/" + std::string(test.input.name)), m_test(test){} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_serial(m_test); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + const SerialCase& m_test; +}; + +class PolicyTest : public UnitTest{ +public: + explicit PolicyTest(const PolicyCase& test) : UnitTest("LabDevices/Policy/" + std::string(test.input.name)), m_test(test){} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_policy(m_test); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + const PolicyCase& m_test; +}; + +class LeaseTest : public UnitTest{ +public: + explicit LeaseTest(const LeaseCase& test) : UnitTest("LabDevices/Lease/" + std::string(test.input.name)), m_test(test){} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const std::string error = check_lease(m_test); + return error.empty() ? UnitTestResult(true) : UnitTestResult(error); + } +private: + const LeaseCase& m_test; +}; +#endif + +} // namespace + +#ifndef PA_LAB_DEVICE_STANDALONE_TESTS +void add_tests_LabDeviceAccess(UnitTestDatabase& database){ + for (const SerialCase& test : SERIAL_CASES){ + database.add(test); + } + for (const PolicyCase& test : POLICY_CASES){ + database.add(test); + } + for (const LeaseCase& test : LEASE_CASES){ + database.add(test); + } +} +#endif + +} // namespace PokemonAutomation + +#ifdef PA_LAB_DEVICE_STANDALONE_TESTS +// Small Qt-only runner/child process. It never links the GUI or device backends. +int main(int argc, char* argv[]){ + std::unique_ptr early_lease; + if (argc == 3 && std::string_view(argv[1]) == "--lease-before-qt"){ + early_lease = std::make_unique(argv[2]); + } + QCoreApplication application(argc, argv); + if (early_lease){ + std::cout << "LOCKED" << std::endl; + return application.exec(); + }else if (argc == 3 && std::string_view(argv[1]) == "--lease-child"){ + PokemonAutomation::LabDeviceLease lease(argv[2]); + std::cout << "LOCKED" << std::endl; + return application.exec(); + } + if (argc != 1){ + return 2; + } + int failed = 0; + for (const auto& test : PokemonAutomation::SERIAL_CASES){ + const std::string error = PokemonAutomation::check_serial(test); + std::cout << test.input.name << ": " << (error.empty() ? "PASS" : error) << std::endl; + failed += !error.empty(); + } + for (const auto& test : PokemonAutomation::POLICY_CASES){ + const std::string error = PokemonAutomation::check_policy(test); + std::cout << test.input.name << ": " << (error.empty() ? "PASS" : error) << std::endl; + failed += !error.empty(); + } + for (const auto& test : PokemonAutomation::LEASE_CASES){ + const std::string error = PokemonAutomation::check_lease(test); + std::cout << test.input.name << ": " << (error.empty() ? "PASS" : error) << std::endl; + failed += !error.empty(); + } + return failed; +} +#endif diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.h b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.h new file mode 100644 index 0000000000..73a5d516a8 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.h @@ -0,0 +1,16 @@ +/* Lab Device Access Tests + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_LabDeviceAccessQt_Tests_H +#define PokemonAutomation_LabDeviceAccessQt_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ + +// Register offline policy, lifecycle and cross-process lease regression cases. +void add_tests_LabDeviceAccess(UnitTestDatabase& database); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.cpp b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.cpp new file mode 100644 index 0000000000..d6a7d8af2c --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.cpp @@ -0,0 +1,98 @@ +/* Lab Device Runtime + * + * From: https://github.com/PokemonAutomation/ + */ +#include +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Filesystem/Filesystem.h" +#include "LabDeviceRuntime.h" + +namespace PokemonAutomation{ +namespace{ + +#if defined(__APPLE__) +// Shared by all guarded apps for this user, independent of their profile/bundle. +std::string shared_lease_directory(){ + return (QDir::homePath() + "/Library/Application Support/PokemonAutomation/LabDeviceLeases").toStdString(); +} + +std::string current_serial_identity(std::string_view port){ + const QSerialPortInfo selected(QString::fromUtf8(port.data(), (qsizetype)port.size())); + std::vector devices; + for (const QSerialPortInfo& info : QSerialPortInfo::availablePorts()){ + if (info.hasVendorIdentifier() && info.hasProductIdentifier()){ + devices.emplace_back(LabSerialDevice{ + info.systemLocation().toStdString(), info.vendorIdentifier(), + info.productIdentifier(), info.serialNumber().toStdString() + }); + } + } + return resolve_lab_serial_identity(devices, selected.systemLocation().toStdString()); +} + +const LabDevicePolicy& runtime_policy(){ + static const LabDevicePolicy policy = []{ + const auto path = Filesystem::application_scratch_path() / "lab-devices.json"; + QFile file(QString::fromStdString(path.string())); + if (!file.open(QIODevice::ReadOnly)){ + throw std::runtime_error("Cannot read lab-devices.json; hardware access is disabled."); + } + return parse_lab_device_policy(file.readAll().toStdString(), Filesystem::STARTUP_PROFILE()); + }(); + return policy; +} +#endif + +} // namespace + +std::unique_ptr reserve_lab_profile(){ +#if defined(__APPLE__) + const std::string directory = shared_lease_directory(); + if (!QDir().mkpath(QString::fromStdString(directory))){ + throw std::runtime_error("Cannot create lab profile lease directory."); + } + return std::make_unique(lab_device_lock_path( + directory, {LabDeviceKind::PROFILE, Filesystem::STARTUP_PROFILE()} + )); +#else + return nullptr; +#endif +} + +std::unique_ptr acquire_lab_serial(Logger& logger, std::string_view port){ +#if defined(__APPLE__) + try{ + // Do not trust the UI's cached port list after unplug/replug. + return acquire_lab_device(runtime_policy(), shared_lease_directory(), { + LabDeviceKind::SERIAL, current_serial_identity(port) + }); + }catch (const std::runtime_error& error){ + throw UserSetupError(logger, error.what()); + } +#else + (void)logger; + (void)port; + return nullptr; +#endif +} + +std::unique_ptr acquire_lab_capture(Logger& logger, LabDeviceKind kind, std::string_view id){ +#if defined(__APPLE__) + try{ + return acquire_lab_device(runtime_policy(), shared_lease_directory(), {kind, std::string(id)}); + }catch (const std::runtime_error& error){ + throw UserSetupError(logger, error.what()); + } +#else + (void)logger; + (void)kind; + (void)id; + return nullptr; +#endif +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.h b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.h new file mode 100644 index 0000000000..5dd5fb88ca --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Devices/LabDeviceRuntime.h @@ -0,0 +1,26 @@ +/* Lab Device Runtime + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_LabDeviceRuntime_H +#define PokemonAutomation_LabDeviceRuntime_H + +#include "Common/Cpp/Logging/AbstractLogger.h" +#include "LabDeviceAccessQt.h" + +namespace PokemonAutomation{ + +// Reserve a macOS GUI profile before loading settings; throw std::runtime_error on failure. +// The returned lease must outlive the GUI. Other platforms return no reservation. +std::unique_ptr reserve_lab_profile(); + +// Resolve a fresh USB identity and reserve it before opening the requested port. +// Missing policy/identity or contention throws UserSetupError. Non-macOS is unchanged. +std::unique_ptr acquire_lab_serial(Logger& logger, std::string_view port); + +// Reserve a camera/audio input by the lowercase hex encoding of its Qt device ID. +// Caller holds the lease until after closing the input. Non-macOS is unchanged. +std::unique_ptr acquire_lab_capture(Logger& logger, LabDeviceKind kind, std::string_view id); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 820d7cbc04..2c313231a4 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -1,5 +1,7 @@ #include +#include +#include #include #include //#include @@ -19,6 +21,7 @@ #include "Common/Cpp/ScopeExit.h" #include "Common/Qt/GlobalThreadPoolsQt.h" #include "StaticRegistration.h" +#include "CommonFramework/Devices/LabDeviceRuntime.h" #include "CommonFramework/GlobalAutoPaths.h" #include "CommonFramework/Tools/GlobalThreadPools.h" #include "CommonFramework/Panels/OptionsPanel.h" @@ -395,6 +398,13 @@ int main(int argc, char* argv[]){ #else (void)selected; #endif + std::unique_ptr profile_lease; + try{ + profile_lease = PokemonAutomation::reserve_lab_profile(); + }catch (const std::runtime_error& error){ + std::cerr << error.what() << std::endl; + return 2; + } return PokemonAutomation::run_gui_application(qt_argc, qt_argv.data()); }, .tests = [&](const PokemonAutomation::StartupPlan& selected){ diff --git a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.5.cpp b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.5.cpp index fc6ceeceaf..401dcd5425 100644 --- a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.5.cpp +++ b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.5.cpp @@ -141,21 +141,14 @@ void CameraVideoSource::init( ", FPS: " + std::to_string(m_fps) ); - m_camera.reset(new QCameraThread(m_logger, *device, format)); + m_camera = QCameraThread::try_create(m_logger, *device, format); + if (!m_camera){ + return; + } m_capture_session.reset(new QMediaCaptureSession()); m_capture_session->setCamera(&m_camera->camera()); -#if 0 - connect(m_camera.get(), &QCamera::errorOccurred, this, [&](){ - if (m_camera->error() == QCamera::NoError){ - return; - } - m_logger.log("QCamera error: " + m_camera->errorString().toStdString(), COLOR_RED); - }); - - m_camera->start(); -#endif } diff --git a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.cpp b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.cpp index 13b6dff18d..c801cb6067 100644 --- a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.cpp +++ b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6.cpp @@ -137,19 +137,15 @@ void CameraVideoSource::init( ", FPS: " + std::to_string(m_fps) ); - m_camera.reset(new QCameraThread(m_logger, *device, format)); + m_camera = QCameraThread::try_create(m_logger, *device, format); + if (!m_camera){ + return; + } m_video_sink.reset(new QVideoSink()); m_capture.reset(new QMediaCaptureSession()); m_capture->setCamera(&m_camera->camera()); m_capture->setVideoSink(m_video_sink.get()); -#if 0 - connect(m_camera.get(), &QCamera::errorOccurred, this, [&](){ - if (m_camera->error() != QCamera::NoError){ - m_logger.log("QCamera error: " + m_camera->errorString().toStdString()); - } - }); -#endif m_metaobject->connect( m_video_sink.get(), &QVideoSink::videoFrameChanged, &m_camera->camera(), [&](const QVideoFrame& frame){ diff --git a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6_QQuickWidget.cpp b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6_QQuickWidget.cpp index 5264a3aea9..0160ac7aeb 100644 --- a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6_QQuickWidget.cpp +++ b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/CameraWidgetQt6_QQuickWidget.cpp @@ -139,19 +139,15 @@ void CameraVideoSource::init( ", FPS: " + std::to_string(m_fps) ); - m_camera.reset(new QCameraThread(m_logger, *device, format)); + m_camera = QCameraThread::try_create(m_logger, *device, format); + if (!m_camera){ + return; + } m_video_sink.reset(new QVideoSink()); m_capture.reset(new QMediaCaptureSession()); m_capture->setCamera(&m_camera->camera()); m_capture->setVideoSink(m_video_sink.get()); -#if 0 - connect(m_camera.get(), &QCamera::errorOccurred, this, [&](){ - if (m_camera->error() != QCamera::NoError){ - m_logger.log("QCamera error: " + m_camera->errorString().toStdString()); - } - }); -#endif m_metaobject->connect( m_video_sink.get(), &QVideoSink::videoFrameChanged, &m_camera->camera(), [&](const QVideoFrame& frame){ diff --git a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/QCameraThread.h b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/QCameraThread.h index 9db0137e9d..2c6235f32c 100644 --- a/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/QCameraThread.h +++ b/SerialPrograms/Source/CommonFramework/VideoPipeline/Backends/QCameraThread.h @@ -8,8 +8,10 @@ #define PokemonAutomation_VideoPipeline_QCameraThread_H #include +#include "Common/Cpp/Exceptions.h" #include "Common/Cpp/Logging/AbstractLogger.h" #include "Common/Qt/GlobalThreadPoolsQt.h" +#include "CommonFramework/Devices/LabDeviceRuntime.h" //#include //using std::cout; @@ -18,14 +20,25 @@ namespace PokemonAutomation{ +// Own the camera and its device lease across the Qt event-thread lifetime. class QCameraThread : public QObject{ public: + // A denied input must not throw across run_on_main_thread_and_wait's Qt callback. + static std::unique_ptr try_create(Logger& logger, QCameraDevice device, QCameraFormat format){ + try{ + return std::make_unique(logger, std::move(device), std::move(format)); + }catch (UserSetupError&){ + return nullptr; // UserSetupError already logged the refusal. + } + } + QCameraThread( Logger& logger, QCameraDevice device, QCameraFormat format ) - : m_logger(logger) + : m_device_lease(acquire_lab_capture(logger, LabDeviceKind::VIDEO, device.id().toHex().toStdString())) + , m_logger(logger) , m_device(std::move(device)) , m_format(std::move(format)) , m_camera(nullptr) @@ -63,6 +76,7 @@ class QCameraThread : public QObject{ private: + std::unique_ptr m_device_lease; Logger& m_logger; QCameraDevice m_device; QCameraFormat m_format; @@ -71,5 +85,5 @@ class QCameraThread : public QObject{ -} +} // namespace PokemonAutomation #endif diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index c31934af2e..1ec1bdd730 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -24,6 +24,7 @@ #include "CommonFramework/Windows/LabChannel_Tests.h" #include "CommonFramework/Startup/StartupArguments_Tests.h" #include "CommonFramework/Startup/LabStartupPolicy_Tests.h" +#include "CommonFramework/Devices/LabDeviceAccessQt_Tests.h" #include "CommonTools/VisualDetectors/BlackBorderDetector.h" #include "CommonTools/OCR/OCR_Tests.h" @@ -67,6 +68,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ add_tests_LabChannel(ret); add_tests_StartupArguments(ret); add_tests_LabStartupPolicy(ret); + add_tests_LabDeviceAccess(ret); OCR::add_tests(ret); Kernels::add_tests(ret); NintendoSwitch::add_tests_CheckOnlineDetector(ret); diff --git a/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.cpp b/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.cpp index c0823750ec..5a70e2430b 100644 --- a/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.cpp +++ b/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.cpp @@ -109,6 +109,14 @@ void SerialPABotBase2_Connection::naked_wait(WallDuration duration){ std::unique_lock lg(lock); cv.wait_until(lg, deadline, [=]{ return current_time() >= deadline; }); } +void SerialPABotBase2_Connection::open_guarded_serial_port(){ +#ifdef QT_CORE_LIB + m_device_lease = acquire_lab_serial(m_logger, m_device_name); +#endif + m_unreliable_connection = std::make_unique( + GlobalThreadPools::unlimited_realtime(), m_device_name, 115200 + ); +} bool SerialPABotBase2_Connection::open_serial_port(){ { std::string text = "Opening serial port..."; @@ -162,11 +170,7 @@ bool SerialPABotBase2_Connection::open_serial_port(){ return false; } - m_unreliable_connection = std::make_unique( - GlobalThreadPools::unlimited_realtime(), - m_device_name, - 115200 - ); + open_guarded_serial_port(); return true; } @@ -327,6 +331,13 @@ void SerialPABotBase2_Connection::connect_thread_body(){ if (ok){ declare_ready(); }else{ + // Close native resources before releasing the lease on any failed open/handshake. + m_device.reset(); + m_stream_connection.reset(); + m_unreliable_connection.reset(); +#ifdef QT_CORE_LIB + m_device_lease.reset(); +#endif declare_failed(); } }); diff --git a/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.h b/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.h index 61ab4af666..81892aecfc 100644 --- a/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.h +++ b/SerialPrograms/Source/Controllers/PABotBase2/SerialPABotBase2_Connection.h @@ -10,6 +10,9 @@ #include "Common/Cpp/Concurrency/AsyncTask.h" #include "Common/Cpp/SerialConnection/SerialConnection.h" #include "Common/PABotBase2/ReliableConnectionLayer/PABotBase2CC_ReliableStreamConnection.h" +#ifdef QT_CORE_LIB +#include "CommonFramework/Devices/LabDeviceRuntime.h" +#endif #include "Controllers/SerialPort/SerialLogger.h" #include "Controllers/PABotBase2/PABotBase2_Connection.h" @@ -36,6 +39,7 @@ class SerialPABotBase2_Connection final : public PABotBase2::Connection{ private: void naked_wait(WallDuration duration); + void open_guarded_serial_port(); bool open_serial_port(); bool try_connect_to_device(WallDuration timeout); bool connect_to_device(); @@ -49,6 +53,10 @@ class SerialPABotBase2_Connection final : public PABotBase2::Connection{ std::string m_device_name; // Mutex m_lock; +#ifdef QT_CORE_LIB + // Declared before the port: release only after the physical connection closes. + std::unique_ptr m_device_lease; +#endif AsyncTask m_connect_thread; std::unique_ptr m_unreliable_connection; std::unique_ptr m_stream_connection; diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 7b51d92e21..a7e2a7b25d 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -719,6 +719,12 @@ file(GLOB LIBRARY_SOURCES Source/CommonFramework/Startup/SetupSettings.h Source/CommonFramework/Startup/StartupArguments.cpp Source/CommonFramework/Startup/StartupArguments.h + Source/CommonFramework/Devices/LabDeviceAccessQt.cpp + Source/CommonFramework/Devices/LabDeviceAccessQt.h + Source/CommonFramework/Devices/LabDeviceRuntime.cpp + Source/CommonFramework/Devices/LabDeviceRuntime.h + Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.cpp + Source/CommonFramework/Devices/LabDeviceAccessQt_Tests.h Source/CommonFramework/Startup/LabStartupPolicy.cpp Source/CommonFramework/Startup/LabStartupPolicy.h Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp diff --git a/devtools/lab/DEVICE_OWNERSHIP.md b/devtools/lab/DEVICE_OWNERSHIP.md new file mode 100644 index 0000000000..a8f5afc19e --- /dev/null +++ b/devtools/lab/DEVICE_OWNERSHIP.md @@ -0,0 +1,120 @@ +# Lab device ownership + +This is the second preparation step after #236. macOS GUI lab builds reserve +the selected profile before Qt/settings startup and check an explicit allowlist +before constructing a native serial connection, QCamera or audio input. +Without a matching policy, hardware opens are refused. An empty policy permits +the GUI for setup, but permits no devices. Native tests do not reserve live +profiles or enumerate hardware. + +## Configure the allowlist + +Create `lab-devices.json` at the profile root, alongside `UserSettings/`, using +reviewed identities for that console. Example with deliberately fictitious IDs: + +```json +{ + "schema": 1, + "profile": "lab-B", + "serial": ["10c4:ea60:EXAMPLE-USB-SERIAL-B"], + "video": ["4558414d504c452d564944454f2d42"], + "audio": ["4558414d504c452d415544494f2d42"] +} +``` + +All five fields are required; unknown fields, duplicates within a device list, +invalid JSON, wrong types, empty identities, unsupported schema and mismatched +profile names are refused. Empty lists are valid. A successfully loaded policy +is immutable for that process: restart the app after changing it. No default +profile, display alias, first-device fallback or wildcard is used. + +Serial keys are lowercase four-digit USB vendor/product IDs followed by the exact +USB serial number: `VID:PID:SERIAL`. The runtime resolves a fresh USB enumeration +immediately before opening, rather than trusting the UI's cached port record. +`/dev/tty.*` and `/dev/cu.*` aliases share a key. Two distinct current ports +reporting the same USB identity are rejected, as are adapters lacking a serial. +If a port path is reused by a different adapter, its new identity must independently +be allowlisted. VID/PID/serial cannot distinguish hardware that impersonates an +identity; this protects against accidental assignment errors, not hostile USB devices. + +Video/audio entries are the lowercase hexadecimal encoding of the exact byte IDs +reported by `QCameraDevice::id()` / `QAudioDevice::id()`. The settings UI stores +the corresponding original device ID; it does not use the hex string as a device +selector. Do not use capture descriptions, friendly names or list positions. +Audio output to speakers is outside this input-device policy. + +This PR does not generate a policy from the currently selected panel: that could +approve the very wrong-console binding we are preventing. Identity collection +and confirming A/B assignments remain a deliberate setup step. Existing profiles, +local deployment scripts, certificates and permissions are not modified. + +## Ownership and lifetime + +All guarded apps for a user use the same local directory: + +``` +~/Library/Application Support/PokemonAutomation/LabDeviceLeases/ +``` + +Lock keys hash device kind plus stable identity, independently of profile, +executable name and bundle ID. Different consoles can run concurrently; +two profiles pointing at the same input contend for one lease. A separate +profile lease prevents duplicate GUI instances from loading/writing the same +profile. Video and audio are separate input endpoints so a capture card's +camera and microphone can be used together. + +The implementation uses Qt's existing `QLockFile` backend, with nonblocking +acquisition and age-based expiration disabled. A live owner is never evicted +because a run has lasted a long time. Qt detects a dead process and recovers its +stale lock; the application never forcibly deletes another owner's lock. +Do not put the lease directory on a network filesystem or remove locks manually. +See [Qt's locking contract](https://doc.qt.io/qt-6/qlockfile.html) for platform +and cooperative-locking limits. + +The serial lease survives connection setup, command traffic and teardown until +the physical port closes. Failed setup closes resources before releasing it. +The camera lease survives Qt's synchronous destruction of the camera on its event +thread. The audio lease survives stopping and destroying its native input. +Reconfiguration closes the previous input before opening its replacement. +Capture refusals are logged and return no active input without propagating an +exception through a Qt callback. Serial refusals appear as a failed connection. + +## Scope + +Enforcement is for macOS GUI lab builds in this stack. GUI-free CoreLib and +Windows/Linux application device behavior remain outside this enforcement; +the lease engine itself has portable native tests. The shared audio replacement +ordering also applies on other GUI platforms. + +Every app touching the test devices must use the guarded build. An old/default +binary that does not participate in this locking protocol cannot be excluded by +an advisory lease. Keep it disconnected from lab devices. This is not a system +sandbox, and neither file hashes nor the allowlist replace physical-console +assignment review. #236's package metadata still says +`hardware_ownership_enforced: false`; that older preparation marker is not a +runtime capability check or evidence that a deployed binary contains this PR. +Use the deployed source revision and this stack's CI evidence. + +## Native tests + +The focused target compiles production policy/lease code, without the GUI, +controller drivers, real settings or capture hardware: + +```sh +cmake -S SerialPrograms/Source/CommonFramework/Devices -B /path/to/test-build +cmake --build /path/to/test-build -j4 +ctest --test-dir /path/to/test-build --output-on-failure +``` + +The same cases are registered in the application's native test database. The +small runner is also the subprocess used by cross-process cases and is built +beside the app executable. Tests cover policy rejection before scripted opens, +USB identity/alias resolution, duplicate USB identities, same/different devices, +duplicate profiles, release/reconnect, exception unwinding, live-process exclusion +and recovery after killing an owned test child. The aged-live-lock timestamp +fixture runs on POSIX; Windows disallows editing that live lock file. + +These tests validate real process-lock behavior and scripted opens. They do not +validate drivers' physical close completion, USB replug behavior, macOS capture +identity persistence or real permission dialogs. Live validation still needs a +separately authorized, carefully assigned two-console run.