Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/lab-instance-tools.yml
Original file line number Diff line number Diff line change
@@ -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
12 changes: 12 additions & 0 deletions SerialPrograms/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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=$<TARGET_FILE:SerialPrograms>"
"-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
Expand Down
21 changes: 21 additions & 0 deletions SerialPrograms/cmake/LabBuildReceipt.cmake
Original file line number Diff line number Diff line change
@@ -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")
113 changes: 113 additions & 0 deletions devtools/lab/INSTANCE_PREPARATION.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions devtools/lab/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
54 changes: 54 additions & 0 deletions devtools/lab/lab_instance.py
Original file line number Diff line number Diff line change
@@ -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()
126 changes: 126 additions & 0 deletions devtools/lab/lab_package.py
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading