Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

os: prepare resumable Apple Silicon install targets (#947)

Dee4d463682a07c
diff --git a/os/platforms/apple-silicon/README.md b/os/platforms/apple-silicon/README.md
index 630a80d4e..c3d118c70 100644
--- a/os/platforms/apple-silicon/README.md
+++ b/os/platforms/apple-silicon/README.md
@@ -105,3 +105,38 @@ enrollment flow. The test uses a public fixture password: **never publish its di
copies**. A user installer still needs to create a unique encryption key, preserve
macOS and recovery, and handle interruption before it can offer encrypted installs.
Physical Apple keyboard, storage and recovery acceptance remain separate.
+
+## Private installation target
+
+`target.py` is the disk-preparation stage for an Asahi UEFI-media installation.
+It reads Asahi's firmware-provided EFI partition identity and uses only the
+unallocated space immediately after that partition. It never shrinks, moves,
+formats or removes existing macOS, recovery or other operating-system partitions.
+The prepared gap must hold a 1 GiB boot partition and at least 12 GiB for the
+encrypted root. This module is not yet packaged or connected to an installer UI.
+
+Before either GPT entry is written, a plan is atomically saved in a private
+directory on the owning FAT EFI partition. Mount that ESP with root ownership,
+`fmask=0177,dmask=0077`, inside the installer's private mount namespace. On every
+attempt the stage rechecks firmware ownership, disk identity, both GPT checksums,
+all existing entries, and its exact planned additions. It can resume after the
+first completed write; unrelated changes or damaged/disagreeing GPT copies stop
+installation without attempting a repair. A disk lock excludes cooperating
+partition tools and allows a brief bounded wait for udev probing.
+
+Run the native disposable-disk acceptance check on an Apple Silicon Mac:
+
+```sh
+python3 os/tests/asahi_target_vm.py \
+ --fixture /path/to/verified-arm-fixture --fixture-source FULL_FIXTURE_COMMIT \
+ --output os/test-results/asahi-target
+```
+
+The test creates an owned 4096-byte-sector GPT disk, saves the actual plan on
+FAT, interrupts after one partition write, reboots, and resumes offline. It
+checks protected partition bytes, existing GPT entries, Asahi EFI fixture files,
+kernel partition geometry, repeated execution, and refusal of changed or damaged
+metadata. QEMU injects the firmware ESP identity; its protected partitions contain
+sentinels, not macOS filesystems. These checks do not establish physical Apple
+support or recovery from a torn GPT write. Fresh encryption, payload copying,
+boot configuration and installer-media integration remain the next stages.
diff --git a/os/platforms/apple-silicon/target.py b/os/platforms/apple-silicon/target.py
new file mode 100644
index 000000000..89a30f49c
--- /dev/null
+++ b/os/platforms/apple-silicon/target.py
@@ -0,0 +1,389 @@
+"""Private Asahi installer disk preparation, restricted to its owned ESP's gap.
+
+The platform handoff identifies one EFI partition. Only the unallocated space
+immediately following it can become Harness boot/root partitions. Existing
+partitions are never removed, moved, resized or formatted by this module.
+"""
+from __future__ import annotations
+
+import hashlib
+import fcntl
+import json
+import os
+from pathlib import Path
+import platform
+import re
+import stat
+import struct
+import subprocess
+import tempfile
+import time
+import uuid
+import zlib
+
+EFI = 'c12a7328-f81f-11d2-ba4b-00a0c93ec93b'
+LINUX = '0fc63daf-8483-4772-8e79-3d69d8477de4'
+LUKS = 'ca7d7ccb-63ed-4c53-861c-1742536059cc'
+BOOT_BYTES = 1024**3
+ROOT_MIN_BYTES = 12 * 1024**3
+ALIGN_BYTES = 1024**2
+
+
+class TargetError(ValueError):
+ pass
+
+
+def identifier(value):
+ if not isinstance(value, str) or not re.fullmatch(r'[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}', value):
+ raise TargetError('Invalid partition identity.')
+ return str(uuid.UUID(value))
+
+
+def integer(value):
+ if type(value) is not int or value < 0:
+ raise TargetError('Invalid disk geometry.')
+ return value
+
+
+def partition_number(device, node):
+ if not isinstance(node, str):
+ raise TargetError('Invalid partition device.')
+ separator = 'p' if device[-1].isdigit() else ''
+ match = re.fullmatch(re.escape(device + separator) + r'([1-9][0-9]*)', node)
+ if not match or not 1 <= int(match[1]) <= 128:
+ raise TargetError('Partition is not a GPT entry on the selected disk.')
+ return int(match[1])
+
+
+def normalize(snapshot):
+ """Validate sfdisk's geometry without accepting a caller's arbitrary extents."""
+ try:
+ table = snapshot['partitiontable']
+ device = table['device']
+ if not isinstance(device, str) or not re.fullmatch(r'/dev/[a-zA-Z0-9_-]+', device):
+ raise TargetError('Use an identified whole block device.')
+ if table['label'] != 'gpt' or table['unit'] != 'sectors' or table['sectorsize'] != 4096:
+ raise TargetError('Use the Asahi 4096-byte-sector GPT layout.')
+ first, last = integer(table['firstlba']), integer(table['lastlba'])
+ if not 1 <= first < last:
+ raise TargetError('Invalid usable disk bounds.')
+ normalized = {'device': device, 'id': identifier(table['id']), 'firstlba': first,
+ 'lastlba': last, 'sectorsize': 4096, 'partitions': []}
+ numbers, identities = set(), set()
+ for part in table['partitions']:
+ # Retain all attributes reported by sfdisk, including names and GPT
+ # flags: a change outside our two new entries invalidates the plan.
+ entry = dict(part)
+ number = partition_number(device, entry['node'])
+ entry['uuid'], entry['type'] = identifier(entry['uuid']), identifier(entry['type'])
+ start, size = integer(entry['start']), integer(entry['size'])
+ if not size or start < first or start + size - 1 > last:
+ raise TargetError('A partition leaves the usable disk bounds.')
+ if number in numbers or entry['uuid'] in identities:
+ raise TargetError('Duplicate partition number or identity.')
+ numbers.add(number)
+ identities.add(entry['uuid'])
+ normalized['partitions'].append(entry)
+ normalized['partitions'].sort(key=lambda part: part['start'])
+ for left, right in zip(normalized['partitions'], normalized['partitions'][1:]):
+ if left['start'] + left['size'] > right['start']:
+ raise TargetError('Overlapping partitions.')
+ if not normalized['partitions']:
+ raise TargetError('The Asahi boot partition is missing.')
+ return normalized
+ except (KeyError, TypeError, AttributeError) as error:
+ raise TargetError('Incomplete partition inventory.') from error
+
+
+def new_plan(snapshot, esp_uuid, *, partition_ids=None):
+ table = normalize(snapshot)
+ esp_uuid = identifier(esp_uuid)
+ entries = table['partitions']
+ selected = [part for part in entries if part['uuid'] == esp_uuid]
+ if len(selected) != 1 or selected[0]['type'] != EFI:
+ raise TargetError('The current Asahi EFI partition is not on this disk.')
+ esp = selected[0]
+ sector = table['sectorsize']
+ alignment = ALIGN_BYTES // sector
+ first = (esp['start'] + esp['size'] + alignment - 1) // alignment * alignment
+ next_start = next((part['start'] for part in entries if part['start'] > esp['start']), table['lastlba'] + 1)
+ end = next_start // alignment * alignment
+ boot_size = BOOT_BYTES // sector
+ if end - first < (BOOT_BYTES + ROOT_MIN_BYTES) // sector:
+ raise TargetError('Use the Asahi installer to reserve at least 13 GiB after this EFI partition.')
+ occupied = {partition_number(table['device'], part['node']) for part in entries}
+ free_numbers = [number for number in range(1, 129) if number not in occupied]
+ if len(free_numbers) < 2:
+ raise TargetError('Two unused GPT entries are required.')
+ if partition_ids is None:
+ partition_ids = [str(uuid.uuid4()), str(uuid.uuid4())]
+ identities = [identifier(value) for value in partition_ids]
+ if len(identities) != 2 or len(set(identities)) != 2 or any(value in {p['uuid'] for p in entries} for value in identities):
+ raise TargetError('New partitions require distinct, unused identities.')
+ separator = 'p' if table['device'][-1].isdigit() else ''
+ additions = []
+ for number, identity, start, size, kind, name in [
+ (free_numbers[0], identities[0], first, boot_size, LINUX, 'Harness boot'),
+ (free_numbers[1], identities[1], first + boot_size, end - first - boot_size, LUKS, 'Harness root'),
+ ]:
+ additions.append({'node': table['device'] + separator + str(number), 'start': start,
+ 'size': size, 'type': kind, 'uuid': identity, 'name': name})
+ return {'schema': 1, 'kind': 'harness-asahi-target', 'esp_uuid': esp_uuid,
+ 'original': table, 'additions': additions}
+
+
+def validate_plan(plan):
+ try:
+ original = plan['original']
+ snapshot = {'partitiontable': {**original, 'label': 'gpt', 'unit': 'sectors'}}
+ expected = new_plan(snapshot, plan['esp_uuid'], partition_ids=[p['uuid'] for p in plan['additions']])
+ except (KeyError, TypeError) as error:
+ raise TargetError('Incomplete installation plan.') from error
+ if plan != expected:
+ raise TargetError('The installation plan no longer matches its reserved space.')
+ return expected
+
+
+def remaining(plan, snapshot):
+ """Allow only the exact original layout plus any already-written planned entries."""
+ validate_plan(plan)
+ actual = normalize(snapshot)
+ original = plan['original']
+ if {k: v for k, v in actual.items() if k != 'partitions'} != {k: v for k, v in original.items() if k != 'partitions'}:
+ raise TargetError('The selected disk identity or geometry changed.')
+ existing = {part['node']: part for part in actual['partitions']}
+ for part in original['partitions']:
+ if existing.pop(part['node'], None) != part:
+ raise TargetError('An existing partition changed. Keep this disk untouched.')
+ missing = []
+ for part in plan['additions']:
+ found = existing.pop(part['node'], None)
+ if found is None:
+ missing.append(part)
+ elif found != part:
+ raise TargetError('A new partition differs from this installation plan.')
+ if existing:
+ raise TargetError('Another partition appeared after installation was planned.')
+ return missing
+
+
+def command(*args):
+ return subprocess.check_output(list(map(str, args)), text=True, stderr=subprocess.PIPE, timeout=30).strip()
+
+
+def read_table(device):
+ return json.loads(command('sfdisk', '--json', device))
+
+
+def verify_gpt(fd, total_bytes, table):
+ """Require two intact, matching GPT copies before any partition write.
+
+ Disk utilities can silently read a backup after a torn primary write. An
+ interrupted metadata write is a recovery case, not permission to repair or
+ reinterpret the Mac's partition table during installation.
+ """
+ sector = 4096
+ if total_bytes % sector:
+ raise TargetError('Invalid physical disk size.')
+ last = total_bytes // sector - 1
+ copies = []
+ for location, alternate in [(1, last), (last, 1)]:
+ raw = os.pread(fd, sector, location * sector)
+ if len(raw) != sector:
+ raise TargetError('Cannot read both GPT headers.')
+ values = struct.unpack('<8sIIIIQQQQ16sQIII', raw[:92])
+ magic, revision, size, crc, reserved, current, backup, first, end, identity, entries, count, width, entries_crc = values
+ if (magic != b'EFI PART' or revision != 0x10000 or not 92 <= size <= sector or reserved or
+ current != location or backup != alternate or count != 128 or width != 128 or
+ first != table['firstlba'] or end != table['lastlba'] or
+ str(uuid.UUID(bytes_le=identity)) != table['id'] or
+ (location == 1 and (entries < 2 or entries + 4 > first)) or
+ (location == last and (entries <= end or entries + 4 > last))):
+ raise TargetError('The GPT headers do not match the planned disk geometry.')
+ header = bytearray(raw[:size])
+ header[16:20] = b'\0' * 4
+ data = os.pread(fd, count * width, entries * sector)
+ if zlib.crc32(header) != crc or len(data) != count * width or zlib.crc32(data) != entries_crc:
+ raise TargetError('The GPT is damaged. Recover its metadata before installation.')
+ copies.append(data)
+ if copies[0] != copies[1]:
+ raise TargetError('The GPT copies disagree. Recover its metadata before installation.')
+
+
+def platform_esp(chosen=Path('/proc/device-tree/chosen/asahi,efi-system-partition')):
+ if platform.machine() != 'aarch64' or os.sysconf('SC_PAGESIZE') != 16384:
+ raise TargetError('Use the maintained Asahi kernel on Apple Silicon.')
+ try:
+ raw = chosen.read_bytes()
+ except OSError as error:
+ raise TargetError('The Asahi firmware did not identify its EFI partition.') from error
+ if len(raw) != 37 or raw[-1:] != b'\0':
+ raise TargetError('The Asahi firmware did not identify its EFI partition.')
+ try:
+ return identifier(raw[:-1].decode('ascii'))
+ except UnicodeError as error:
+ raise TargetError('Invalid Asahi EFI identity.') from error
+
+
+def owning_disk(data, esp_uuid):
+ """Select only the internal disk containing the firmware-identified ESP."""
+ esp_uuid = identifier(esp_uuid)
+ matches = []
+ try:
+ for disk in data['blockdevices']:
+ if disk['type'] != 'disk' or disk['ro'] not in (False, 0) or disk['rm'] not in (False, 0):
+ continue
+ for part in disk.get('children', []):
+ if part.get('type') == 'part' and str(part.get('partuuid', '')).lower() == esp_uuid:
+ matches.append(disk['name'])
+ except (KeyError, TypeError, AttributeError) as error:
+ raise TargetError('Incomplete block device inventory.') from error
+ if len(matches) != 1:
+ raise TargetError('Cannot identify one writable internal disk for this Asahi installation.')
+ return matches[0]
+
+
+def inventory():
+ return json.loads(command('lsblk', '--json', '--paths', '--output', 'NAME,TYPE,PARTUUID,RO,RM'))
+
+
+def discover():
+ """Read-only platform handoff; the firmware chooses the owning ESP, never a picker."""
+ esp_uuid = platform_esp()
+ return new_plan(read_table(owning_disk(inventory(), esp_uuid)), esp_uuid)
+
+
+def private_file(fd):
+ info = os.fstat(fd)
+ if (not stat.S_ISREG(info.st_mode) or info.st_uid != os.geteuid() or
+ stat.S_IMODE(info.st_mode) != 0o600 or info.st_nlink != 1 or info.st_size > 128 * 1024):
+ raise TargetError('The saved plan must be a private, owned regular file.')
+
+
+def private_directory(fd):
+ info = os.fstat(fd)
+ if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid() or stat.S_IMODE(info.st_mode) & 0o077:
+ raise TargetError('Save the plan in a private, owned directory.')
+
+
+def save_plan(path, plan):
+ """Atomically persist before disk writes, including on the FAT boot partition.
+
+ The parent must be private and owned. A persistent advisory lock coordinates
+ installer attempts; an interrupted temporary write is never a valid plan.
+ No hard links are required, because the Asahi ESP uses FAT.
+ """
+ validate_plan(plan)
+ path = Path(path)
+ content = json.dumps(plan, sort_keys=True, indent=2).encode() + b'\n'
+ directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+ lock, temporary = None, None
+ try:
+ private_directory(directory)
+ lock = os.open(path.name + '.lock', os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK,
+ 0o600, dir_fd=directory)
+ private_file(lock)
+ fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ if os.path.lexists(path):
+ raise FileExistsError('An installation plan already exists; load it to resume.')
+ fd, temporary = tempfile.mkstemp(prefix='.' + path.name + '-', dir=path.parent)
+ with os.fdopen(fd, 'wb') as stream:
+ stream.write(content)
+ stream.flush()
+ os.fsync(stream.fileno())
+ os.rename(temporary, path)
+ temporary = None
+ os.fsync(directory)
+ finally:
+ if temporary is not None:
+ os.unlink(temporary)
+ if lock is not None:
+ os.close(lock)
+ os.close(directory)
+ return hashlib.sha256(content).hexdigest()
+
+
+def load_plan(path):
+ path = Path(path)
+ directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+ fd = None
+ try:
+ private_directory(directory)
+ fd = os.open(path.name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory)
+ private_file(fd)
+ with os.fdopen(fd, 'r') as stream:
+ fd = None
+ try:
+ return validate_plan(json.loads(stream.read(128 * 1024)))
+ except (UnicodeError, json.JSONDecodeError) as error:
+ raise TargetError('The saved installation plan is incomplete.') from error
+ finally:
+ if fd is not None:
+ os.close(fd)
+ os.close(directory)
+
+
+def lock_disk(fd, timeout=5):
+ # udev briefly takes the same lock while probing a changed table. Wait for
+ # that normal handoff, but never wait indefinitely for another installer.
+ deadline = time.monotonic() + timeout
+ while True:
+ try:
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ return
+ except BlockingIOError as error:
+ if time.monotonic() >= deadline:
+ raise TargetError('The disk is busy. Close other disk tools and try again.') from error
+ time.sleep(.05)
+
+
+def apply_plan(path):
+ """Append only the persisted plan's missing entries; safe to resume after one write.
+
+ Re-read firmware ownership on every attempt. The plan must be persisted on
+ that ESP, mounted with private root-only permissions. This function does not
+ create filesystems or update boot files.
+ """
+ if platform.system() != 'Linux' or os.geteuid() != 0:
+ raise TargetError('Partition preparation requires the Linux installer.')
+ if (os.readlink('/proc/self/ns/mnt') == os.readlink('/proc/1/ns/mnt') or
+ command('findmnt', '-nro', 'PROPAGATION', '/') != 'private'):
+ raise TargetError('Use the installer’s private mount namespace.')
+ plan = load_plan(path)
+ device = plan['original']['device']
+ esp_uuid = platform_esp()
+ if esp_uuid != plan['esp_uuid'] or owning_disk(inventory(), esp_uuid) != device:
+ raise TargetError('The plan belongs to a different Asahi installation.')
+ esp = next(part for part in plan['original']['partitions'] if part['uuid'] == esp_uuid)
+ mount = json.loads(command('findmnt', '--json', '--target', path, '--output', 'SOURCE,FSTYPE'))['filesystems'][0]
+ if mount['fstype'] != 'vfat' or os.stat(mount['source']).st_rdev != os.stat(esp['node']).st_rdev:
+ raise TargetError('Persist the installation plan on its Asahi EFI partition.')
+ fd = os.open(device, os.O_RDONLY | os.O_NOFOLLOW)
+ try:
+ if (not stat.S_ISBLK(os.fstat(fd).st_mode) or command('blockdev', '--getss', device) != '4096'
+ or command('blockdev', '--getro', device) != '0'):
+ raise TargetError('The planned disk is not a writable 4096-byte-sector block device.')
+ lock_disk(fd)
+ # Revalidate each time. Foreign changes must never be mistaken for
+ # resumable progress. The lock also excludes cooperating disk tools.
+ for part in plan['additions']:
+ snapshot = read_table(device)
+ verify_gpt(fd, int(command('blockdev', '--getsize64', device)), normalize(snapshot))
+ if part not in remaining(plan, snapshot):
+ continue
+ number = partition_number(device, part['node'])
+ command('sgdisk', f'--new={number}:{part["start"]}:{part["start"] + part["size"] - 1}',
+ f'--typecode={number}:{part["type"]}', f'--partition-guid={number}:{part["uuid"]}',
+ f'--change-name={number}:{part["name"]}', device)
+ snapshot = read_table(device)
+ verify_gpt(fd, int(command('blockdev', '--getsize64', device)), normalize(snapshot))
+ if remaining(plan, snapshot):
+ raise TargetError('The planned Linux partitions were not fully created.')
+ finally:
+ os.close(fd)
+ # An ESP mounted for the journal can prevent a whole-table kernel reread.
+ # Update only our two entries, never remove/re-add existing partitions.
+ for part in plan['additions']:
+ command('partx', '--update', '--nr', partition_number(device, part['node']), device)
+ command('udevadm', 'settle', '--timeout=10')
+ return plan
diff --git a/os/tests/asahi_target_guest.py b/os/tests/asahi_target_guest.py
new file mode 100644
index 000000000..81b954303
--- /dev/null
+++ b/os/tests/asahi_target_guest.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Owned VM-only GPT fixture; never run against a host or an existing Mac disk."""
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+spec = importlib.util.spec_from_file_location('target', '/var/tmp/harness-asahi-target.py')
+target = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(target)
+DISK = '/dev/vdb'
+ROOT = Path('/mnt/harness-asahi-target')
+PLAN = ROOT / 'asahi/harness-install/target.json'
+BASELINE = Path('/var/tmp/harness-target-baseline.json')
+RESULT = Path('/var/tmp/harness-target-result.json')
+ESP = 'e51d26b0-4c8f-41fb-9d83-a0fdd62327c0'
+APFS = '7c3457ef-0000-11aa-aa11-00306543ecac'
+RECOVERY = '52637672-7900-11aa-aa11-00306543ecac'
+GiB = 1024**3 // 4096
+MiB = 1024**2 // 4096
+PROTECTED = [1, 3, 4]
+FILES = ['m1n1/boot.bin', 'vendorfw/fixture.bin', 'asahi/stub_info.json']
+
+
+def run(*args):
+ completed = subprocess.run(list(map(str, args)), stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=60)
+ if completed.returncode:
+ raise RuntimeError(f'{args[0]}: {completed.returncode}: {completed.stderr.decode(errors="replace")}')
+ return completed.stdout.decode().strip()
+
+
+def digest(path):
+ result = hashlib.sha256()
+ with open(path, 'rb') as handle:
+ while data := handle.read(1024**2):
+ result.update(data)
+ return result.hexdigest()
+
+
+def guard():
+ assert os.geteuid() == 0 and run('uname', '-m') == 'aarch64'
+ assert run('getconf', 'PAGESIZE') == '16384'
+ assert run('findmnt', '-no', 'SOURCE', '/') == '/dev/vda'
+ assert run('lsblk', '-ndo', 'SERIAL', DISK) == 'HARNESS_ENCRYPT_TEST'
+ assert run('blockdev', '--getss', DISK) == '4096'
+ assert run('blockdev', '--getsize64', DISK) == str(24 * 1024**3)
+ assert os.readlink('/proc/self/ns/mnt') != os.readlink('/proc/1/ns/mnt')
+ assert run('findmnt', '-nro', 'PROPAGATION', '/') == 'private'
+ ROOT.mkdir(exist_ok=True)
+ # QEMU does not have Apple's firmware device-tree handoff. This is the only
+ # production dependency substituted in the native test. Portable tests cover
+ # that reader's actual format/architecture checks; hardware remains separate.
+ target.platform_esp = lambda: ESP
+
+
+def mount():
+ run('mount', '-t', 'vfat', '-o', 'rw,noatime,uid=0,gid=0,fmask=0177,dmask=0077', DISK + '2', ROOT)
+
+
+def metadata():
+ length = 24 * 1024**3
+ with open(DISK, 'rb', buffering=0) as handle:
+ return hashlib.sha256(os.pread(handle.fileno(), 6 * 4096, 0) +
+ os.pread(handle.fileno(), 5 * 4096, length - 5 * 4096)).hexdigest()
+
+
+def protected():
+ with open(DISK, 'rb', buffering=0) as handle:
+ entries = {str(n): os.pread(handle.fileno(), 128, 2 * 4096 + (n - 1) * 128).hex() for n in range(1, 5)}
+ return {'partitions': {str(n): digest(DISK + str(n)) for n in PROTECTED},
+ 'esp_files': {name: digest(ROOT / name) for name in FILES},
+ 'esp_volume_uuid': run('blkid', '-s', 'UUID', '-o', 'value', DISK + '2'),
+ 'original_gpt_entries': entries}
+
+
+def initialize():
+ assert not BASELINE.exists()
+ assert not run('lsblk', '-nro', 'MOUNTPOINTS', DISK)
+ run('sgdisk', '--zap-all', DISK)
+ run('sgdisk', '--clear',
+ f'--new=1:{MiB}:{33 * MiB - 1}', f'--typecode=1:{APFS}', '--change-name=1:macOS fixture',
+ f'--new=2:{64 * MiB}:{320 * MiB - 1}', f'--typecode=2:{target.EFI}', f'--partition-guid=2:{ESP}', '--change-name=2:Asahi',
+ f'--new=3:{20 * GiB}:{20 * GiB + 32 * MiB - 1}', f'--typecode=3:{RECOVERY}', '--change-name=3:Recovery fixture',
+ f'--new=4:{22 * GiB}:{22 * GiB + 64 * MiB - 1}', f'--typecode=4:{target.EFI}', '--change-name=4:Other OS fixture', DISK)
+ run('udevadm', 'settle', '--timeout=10')
+ for number in PROTECTED:
+ device = DISK + str(number)
+ size = int(run('blockdev', '--getsize64', device))
+ with open(device, 'r+b', buffering=0) as handle:
+ os.pwrite(handle.fileno(), bytes([number]) * 65536, 0)
+ os.pwrite(handle.fileno(), bytes([number + 32]) * 65536, size - 65536)
+ os.fsync(handle.fileno())
+ run('mkfs.vfat', '-F', '32', '-n', 'ASAHI_TEST', DISK + '2')
+ mount()
+ for name in FILES:
+ path = ROOT / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text('Existing Asahi fixture bytes: ' + name + '\n')
+ PLAN.parent.mkdir(mode=0o700)
+ baseline = protected()
+ baseline.update(table=target.read_table(DISK), started_at=time.time())
+ BASELINE.write_text(json.dumps(baseline, indent=2) + '\n')
+ target.save_plan(PLAN, target.discover())
+ assert protected() == {k: v for k, v in baseline.items() if k not in ('table', 'started_at')}
+ plan = target.load_plan(PLAN)
+ assert len(target.remaining(plan, target.read_table(DISK))) == 2
+ run('umount', ROOT)
+ return {'phase': 'prepared', 'plan': plan, 'protected': baseline}
+
+
+def interrupt():
+ mount()
+ before = metadata()
+ # The persistent record cannot be replaced by an ephemeral copy on /tmp.
+ outside_directory = Path('/var/tmp/harness-ephemeral-plan')
+ outside_directory.mkdir(mode=0o700)
+ outside = outside_directory / 'target.json'
+ outside.write_bytes(PLAN.read_bytes())
+ outside.chmod(0o600)
+ try:
+ target.apply_plan(outside)
+ raise AssertionError('Accepted an ephemeral installation plan')
+ except target.TargetError as error:
+ assert 'EFI partition' in str(error)
+ assert metadata() == before
+ command = target.command
+ def stop_after_committed_partition(*args):
+ result = command(*args)
+ if args[0] == 'sgdisk' and any(str(arg).startswith('--new=') for arg in args):
+ # Exit the actual installer process after one completed GPT write;
+ # leave its saved plan and table for the next boot to discover.
+ os._exit(75)
+ return result
+ target.command = stop_after_committed_partition
+ target.apply_plan(PLAN)
+ raise AssertionError('The interruption was not exercised')
+
+
+def resume():
+ mount()
+ baseline = json.loads(BASELINE.read_text())
+ expected = {k: v for k, v in baseline.items() if k not in ('table', 'started_at')}
+ plan = target.load_plan(PLAN)
+ missing = target.remaining(plan, target.read_table(DISK))
+ assert len(missing) == 1 and missing[0] == plan['additions'][1]
+ assert protected() == expected
+ applied = target.apply_plan(PLAN)
+ assert applied == plan and not target.remaining(plan, target.read_table(DISK))
+ assert protected() == expected
+ for part in plan['additions']:
+ block = Path('/sys/class/block') / Path(part['node']).name
+ assert int((block / 'start').read_text()) * 512 == part['start'] * 4096
+ assert int((block / 'size').read_text()) * 512 == part['size'] * 4096
+ assert run('blkid', '-s', 'PARTUUID', '-o', 'value', part['node']) == part['uuid']
+ before = metadata()
+ commands = []
+ command = target.command
+ def observe(*args):
+ commands.append(args)
+ return command(*args)
+ target.command = observe
+ target.apply_plan(PLAN)
+ target.command = command
+ assert not any(args[0] == 'sgdisk' for args in commands)
+ assert metadata() == before and protected() == expected
+ # A foreign change refuses before writing anything, even when our two
+ # partitions already exist. Restore only our disposable fixture afterwards.
+ run('sgdisk', '--change-name=1:foreign change', DISK)
+ changed = metadata()
+ try:
+ target.apply_plan(PLAN)
+ raise AssertionError('Accepted an unrelated partition change')
+ except target.TargetError as error:
+ assert 'existing partition changed' in str(error)
+ assert metadata() == changed
+ run('sgdisk', '--change-name=1:macOS fixture', DISK)
+ corruption_checks = []
+ for header in (4096, 24 * 1024**3 - 4096):
+ with open(DISK, 'r+b', buffering=0) as handle:
+ original = os.pread(handle.fileno(), 4096, header)
+ corrupted = bytearray(original)
+ corrupted[16] ^= 1
+ os.pwrite(handle.fileno(), corrupted, header)
+ os.fsync(handle.fileno())
+ damaged = metadata()
+ try:
+ target.apply_plan(PLAN)
+ raise AssertionError('Accepted a damaged GPT copy')
+ except target.TargetError as error:
+ assert 'GPT is damaged' in str(error)
+ assert metadata() == damaged
+ os.pwrite(handle.fileno(), original, header)
+ os.fsync(handle.fileno())
+ corruption_checks.append(header)
+ assert protected() == expected
+ final = target.read_table(DISK)
+ run('umount', ROOT)
+ return {'phase': 'resumed', 'partial_resume': True, 'idempotent': True,
+ 'protected': expected, 'foreign_change_refused_without_write': True,
+ 'damaged_gpt_refused_without_write': corruption_checks,
+ 'table': final, 'finished_at': time.time()}
+
+
+if __name__ == '__main__':
+ guard()
+ action = {'initialize': initialize, 'interrupt': interrupt, 'resume': resume}[sys.argv[1]]
+ result = action()
+ RESULT.write_text(json.dumps(result, indent=2) + '\n')
+ print(result['phase'], flush=True)
diff --git a/os/tests/asahi_target_vm.py b/os/tests/asahi_target_vm.py
new file mode 100644
index 000000000..b4eb2d835
--- /dev/null
+++ b/os/tests/asahi_target_vm.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Native Asahi partition-preparation test on a fresh, owned sparse VM disk."""
+import argparse
+import json
+from pathlib import Path
+import platform
+import subprocess
+import time
+
+from arm_boot import digest
+from arm_session import fixture_identity
+from asahi_encryption_vm import MaintenanceVM
+from session_vm import put
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def guest(vm, action, folder):
+ put(vm, '/var/tmp/harness-asahi-target.py', (ROOT / 'platforms/apple-silicon/target.py').read_text())
+ put(vm, '/var/tmp/harness-target-guest.py', Path(__file__).with_name('asahi_target_guest.py').read_text())
+ output, code = vm.command('unshare --mount --propagation private python3 /var/tmp/harness-target-guest.py ' + action,
+ timeout=120, check=action != 'interrupt')
+ if action == 'interrupt':
+ assert code == 75, output
+ return {'exit_code': code, 'phase': 'interrupted after first GPT write'}
+ raw = vm.read_file('/var/tmp/harness-target-result.json')
+ (folder / (action + '.json')).write_bytes(raw)
+ return json.loads(raw)
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--fixture', type=Path, required=True)
+ parser.add_argument('--fixture-source', required=True)
+ parser.add_argument('--output', type=Path, required=True)
+ args = parser.parse_args()
+ if (platform.system(), platform.machine()) != ('Darwin', 'arm64'):
+ parser.error('Use the native Apple Silicon host observer.')
+ info = fixture_identity(args.fixture, args.fixture_source)
+ output = args.output.resolve()
+ output.mkdir(parents=True, exist_ok=False)
+ maintenance = output / 'maintenance.raw'
+ disk = output / 'target.raw'
+ with disk.open('xb') as handle:
+ handle.truncate(24 * 1024**3)
+ subprocess.run(['zstd', '-d', '--sparse', args.fixture / 'guest.raw.zst', '-o', maintenance], check=True, timeout=120)
+ assert digest(maintenance) == info['raw_disk']['sha256']
+ receipt = {'status': 'running', 'started_at': time.time(), 'publication': False,
+ 'maintenance_source': args.fixture_source,
+ 'fixture_manifest_sha256': digest(args.fixture / 'manifest.json'),
+ 'limitations': ['Firmware ESP UUID is injected: QEMU has no Apple firmware handoff.',
+ 'Protected APFS/recovery partitions contain sentinel bytes, not real macOS filesystems.',
+ 'Interruption is between completed writes; torn GPT copies are refused, not auto-repaired.',
+ 'No payload copy, encryption, installer UI or physical Apple support is claimed.'],
+ 'host': {name: subprocess.check_output([name, '--version'], text=True).splitlines()[0]
+ for name in ('python3', 'qemu-system-aarch64', 'zstd')},
+ 'inputs': {str(path.relative_to(ROOT)): digest(path) for path in
+ [ROOT / 'platforms/apple-silicon/target.py', ROOT / 'tools/fedora_payload.py'] +
+ [Path(__file__).with_name(name) for name in
+ ('asahi_target_vm.py', 'asahi_target_guest.py', 'asahi_encryption_vm.py',
+ 'asahi_encryption_guest.py', 'asahi_firstboot_vm.py', 'arm_boot.py',
+ 'arm_session.py', 'fedora_session_vm.py', 'session_vm.py', 'vm.py')]}}
+ vm = None
+ try:
+ vm = MaintenanceVM(output / 'first-attempt', maintenance, args.fixture / 'Image', disk)
+ vm.start()
+ vm.command('dnf5 install -y --setopt=install_weak_deps=False --setopt=gpgcheck=True gdisk dosfstools', timeout=180)
+ receipt['guest_versions'], _ = vm.command('rpm -q gdisk dosfstools util-linux util-linux-core')
+ receipt['initialize'] = guest(vm, 'initialize', output)
+ receipt['interrupt'] = guest(vm, 'interrupt', output)
+ receipt['first_shutdown'] = vm.poweroff()
+ vm.close()
+ vm = MaintenanceVM(output / 'offline-resume', maintenance, args.fixture / 'Image', disk)
+ vm.start(offline=True)
+ receipt['resume'] = guest(vm, 'resume', output)
+ receipt['second_shutdown'] = vm.poweroff()
+ receipt.update(status='passed')
+ print('Partition preparation resumes after reboot; protected bytes unchanged; changed or damaged GPT refused.', flush=True)
+ except BaseException as error:
+ receipt.update(status='failed', error=str(error))
+ raise
+ finally:
+ try:
+ if vm:
+ vm.close()
+ finally:
+ receipt['finished_at'] = time.time()
+ (output / 'receipt.json').write_text(json.dumps(receipt, indent=2) + '\n')
+ if receipt['status'] != 'passed':
+ raise SystemExit(1)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/os/tests/test_asahi_target.py b/os/tests/test_asahi_target.py
new file mode 100644
index 000000000..15bfac734
--- /dev/null
+++ b/os/tests/test_asahi_target.py
@@ -0,0 +1,241 @@
+"""Asahi target ownership, reserved-space boundaries and resumable plan checks."""
+import copy
+import fcntl
+import importlib.util
+import json
+import os
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+
+SOURCE = Path(__file__).resolve().parents[1] / 'platforms/apple-silicon/target.py'
+spec = importlib.util.spec_from_file_location('asahi_target', SOURCE)
+target = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(target)
+GiB = 1024**3 // 4096
+MiB = 1024**2 // 4096
+ESP = 'e51d26b0-4c8f-41fb-9d83-a0fdd62327c0'
+APFS = '7c3457ef-0000-11aa-aa11-00306543ecac'
+
+
+def fixture():
+ return {'partitiontable': {'label': 'gpt', 'id': '892dba11-cce3-4b97-a3ad-fca93c1340c6',
+ 'device': '/dev/nvme0n1', 'unit': 'sectors', 'firstlba': 6, 'lastlba': 64 * GiB - 6,
+ 'sectorsize': 4096, 'partitions': [
+ {'node': '/dev/nvme0n1p1', 'start': MiB, 'size': GiB, 'type': APFS,
+ 'uuid': '0be7972c-66e7-47e6-a8aa-8043a0803c0f', 'name': 'macOS', 'attrs': 'RequiredPartition'},
+ {'node': '/dev/nvme0n1p4', 'start': 4 * GiB, 'size': GiB // 2, 'type': target.EFI,
+ 'uuid': ESP, 'name': 'Asahi'},
+ {'node': '/dev/nvme0n1p3', 'start': 20 * GiB, 'size': GiB, 'type': APFS,
+ 'uuid': '7d63c94a-e92c-4c66-ab52-cc620c9a917d', 'name': 'Recovery'},
+ ]}}
+
+
+def partial(plan, count):
+ snapshot = fixture()
+ snapshot['partitiontable']['partitions'] += copy.deepcopy(plan['additions'][:count])
+ return snapshot
+
+
+class TargetGeometry(unittest.TestCase):
+ def test_only_uses_gap_after_its_esp_not_largest_gap(self):
+ snapshot = fixture()
+ before = copy.deepcopy(snapshot)
+ plan = target.new_plan(snapshot, ESP.upper())
+ boot, root = plan['additions']
+ self.assertEqual(boot['start'], int(4.5 * GiB))
+ self.assertEqual(boot['size'], GiB)
+ self.assertEqual(root['start'], int(5.5 * GiB))
+ self.assertEqual(root['start'] + root['size'], 20 * GiB)
+ self.assertEqual([boot['node'], root['node']], ['/dev/nvme0n1p2', '/dev/nvme0n1p5'])
+ self.assertEqual(snapshot, before)
+ self.assertEqual(target.validate_plan(plan), plan)
+
+ def test_alignment_stays_inside_gap_and_honors_minimum(self):
+ snapshot = fixture()
+ snapshot['partitiontable']['partitions'][1]['size'] += 1
+ plan = target.new_plan(snapshot, ESP)
+ self.assertEqual(plan['additions'][0]['start'], int(4.5 * GiB) + MiB)
+ snapshot['partitiontable']['partitions'][2]['start'] = int(17.5 * GiB)
+ with self.assertRaisesRegex(target.TargetError, '13 GiB'):
+ target.new_plan(snapshot, ESP)
+
+ def test_last_partition_uses_only_aligned_usable_sectors(self):
+ snapshot = fixture()
+ del snapshot['partitiontable']['partitions'][2]
+ root = target.new_plan(snapshot, ESP)['additions'][1]
+ self.assertEqual(root['start'] + root['size'], 64 * GiB - MiB)
+
+ def test_refuses_invalid_ownership_geometry_and_identities(self):
+ changes = [lambda t: t.update(label='dos'), lambda t: t.update(sectorsize=512),
+ lambda t: t.update(device='/dev/disk/by-id/unknown'), lambda t: t.update(lastlba=1),
+ lambda t: t['partitions'][1].update(type=APFS),
+ lambda t: t['partitions'][1].update(size=True),
+ lambda t: t['partitions'][1].update(size=-1),
+ lambda t: t['partitions'][1].update(start=MiB),
+ lambda t: t['partitions'][1].update(size=90 * GiB),
+ lambda t: t['partitions'][1].update(node='/dev/nvme1n1p4'),
+ lambda t: t['partitions'][1].update(node=None),
+ lambda t: t['partitions'][1].update(uuid=t['partitions'][0]['uuid']),
+ lambda t: t['partitions'][1].update(uuid='not-a-uuid'),
+ lambda t: t.update(partitions=None), lambda t: t.update(partitions=[None])]
+ for change in changes:
+ snapshot = fixture()
+ change(snapshot['partitiontable'])
+ with self.subTest(snapshot=snapshot), self.assertRaises(target.TargetError):
+ target.new_plan(snapshot, ESP)
+ with self.assertRaises(target.TargetError):
+ target.new_plan(fixture(), '892dba11-cce3-4b97-a3ad-fca93c1340c6')
+ for identities in ([], [ESP, ESP], [ESP], [ESP, '892dba11-cce3-4b97-a3ad-fca93c1340c6']):
+ with self.subTest(identities=identities), self.assertRaises(target.TargetError):
+ target.new_plan(fixture(), ESP, partition_ids=identities)
+
+ def test_exact_partial_and_complete_resume(self):
+ plan = target.new_plan(fixture(), ESP)
+ for count in range(3):
+ self.assertEqual(target.remaining(plan, partial(plan, count)), plan['additions'][count:])
+
+ def test_changed_existing_or_new_partition_or_disk_refused(self):
+ plan = target.new_plan(fixture(), ESP)
+ changes = [lambda t: t.update(id='e106a700-879a-470f-8439-85a390a199ec'),
+ lambda t: t.update(lastlba=t['lastlba'] - 1),
+ lambda t: t['partitions'][0].update(name='Changed'),
+ lambda t: t['partitions'][0].update(attrs=''),
+ lambda t: t['partitions'].pop(0),
+ lambda t: t['partitions'][-1].update(size=10),
+ lambda t: t['partitions'][-1].update(type=APFS)]
+ for change in changes:
+ snapshot = partial(plan, 1)
+ change(snapshot['partitiontable'])
+ with self.subTest(snapshot=snapshot), self.assertRaises(target.TargetError):
+ target.remaining(plan, snapshot)
+ snapshot = partial(plan, 0)
+ foreign = copy.deepcopy(snapshot['partitiontable']['partitions'][0])
+ foreign.update(node='/dev/nvme0n1p8', start=30 * GiB, uuid='49579266-b21d-477f-9ff2-319c173a7096')
+ snapshot['partitiontable']['partitions'].append(foreign)
+ with self.assertRaisesRegex(target.TargetError, 'Another partition'):
+ target.remaining(plan, snapshot)
+
+ def test_plan_cannot_move_its_writes_into_macos(self):
+ plan = target.new_plan(fixture(), ESP)
+ plan['additions'][0]['start'] = MiB
+ with self.assertRaises(target.TargetError):
+ target.validate_plan(plan)
+
+ def test_disk_discovery_ignores_usb_and_readonly_and_rejects_duplicate(self):
+ disk = {'type': 'disk', 'name': '/dev/nvme0n1', 'ro': False, 'rm': False,
+ 'children': [{'type': 'part', 'partuuid': ESP.upper()}]}
+ self.assertEqual(target.owning_disk({'blockdevices': [disk]}, ESP), '/dev/nvme0n1')
+ for field in ['ro', 'rm']:
+ changed = copy.deepcopy(disk)
+ changed[field] = True
+ with self.assertRaises(target.TargetError):
+ target.owning_disk({'blockdevices': [changed]}, ESP)
+ with self.assertRaises(target.TargetError):
+ target.owning_disk({'blockdevices': [disk, disk]}, ESP)
+
+ def test_platform_requires_asahi_16k_and_valid_terminated_uuid(self):
+ with tempfile.TemporaryDirectory() as folder:
+ path = Path(folder) / 'chosen'
+ path.write_bytes(ESP.upper().encode() + b'\0')
+ with patch.object(target.platform, 'machine', return_value='aarch64'), patch.object(target.os, 'sysconf', return_value=16384):
+ self.assertEqual(target.platform_esp(path), ESP)
+ for value in [ESP.encode(), ESP.encode() + b'\n', b'x' * 36 + b'\0', b'\xff' * 36 + b'\0']:
+ path.write_bytes(value)
+ with self.assertRaises(target.TargetError):
+ target.platform_esp(path)
+ with patch.object(target.platform, 'machine', return_value='x86_64'):
+ with self.assertRaises(target.TargetError):
+ target.platform_esp(path)
+
+
+class DurablePlan(unittest.TestCase):
+ def setUp(self):
+ temporary = tempfile.TemporaryDirectory()
+ self.addCleanup(temporary.cleanup)
+ self.root = Path(temporary.name)
+ self.path = self.root / 'target.json'
+ self.plan = target.new_plan(fixture(), ESP)
+
+ def test_roundtrip_never_overwrites_existing_plan(self):
+ target.save_plan(self.path, self.plan)
+ before = self.path.read_bytes()
+ self.assertEqual(target.load_plan(self.path), self.plan)
+ with self.assertRaises(FileExistsError):
+ target.save_plan(self.path, target.new_plan(fixture(), ESP))
+ self.assertEqual(self.path.read_bytes(), before)
+
+ def test_interruption_before_rename_does_not_leave_a_partial_plan(self):
+ with patch.object(target.os, 'fsync', side_effect=OSError('simulated power interruption')):
+ with self.assertRaises(OSError):
+ target.save_plan(self.path, self.plan)
+ self.assertFalse(self.path.exists())
+ self.assertEqual(list(self.root.glob('.target.json-*')), [])
+ target.save_plan(self.path, self.plan)
+ self.assertEqual(target.load_plan(self.path), self.plan)
+
+ def test_interruption_after_rename_leaves_a_complete_resumable_record(self):
+ sync = os.fsync
+ calls = []
+ def interrupted(fd):
+ calls.append(fd)
+ if len(calls) == 2:
+ raise OSError('directory sync interrupted')
+ sync(fd)
+ with patch.object(target.os, 'fsync', side_effect=interrupted):
+ with self.assertRaises(OSError):
+ target.save_plan(self.path, self.plan)
+ self.assertEqual(target.load_plan(self.path), self.plan)
+
+ def test_private_directory_and_exclusive_writer_required(self):
+ self.root.chmod(0o755)
+ with self.assertRaises(target.TargetError):
+ target.save_plan(self.path, self.plan)
+ self.root.chmod(0o700)
+ lock = self.root / 'target.json.lock'
+ lock.touch(mode=0o600)
+ with lock.open('r+b') as handle:
+ fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ with self.assertRaises(BlockingIOError):
+ target.save_plan(self.path, self.plan)
+ self.assertFalse(self.path.exists())
+
+ def test_busy_disk_lock_is_bounded_and_succeeds_after_release(self):
+ lock = self.root / 'device-lock-fixture'
+ lock.touch(mode=0o600)
+ with lock.open('rb') as first, lock.open('rb') as second:
+ fcntl.flock(first, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ with self.assertRaisesRegex(target.TargetError, 'disk is busy'):
+ target.lock_disk(second.fileno(), timeout=0)
+ fcntl.flock(first, fcntl.LOCK_UN)
+ target.lock_disk(second.fileno(), timeout=0)
+
+ def test_symlinks_hardlinks_loose_permissions_and_fifo_refused(self):
+ target.save_plan(self.path, self.plan)
+ link = self.root / 'link'
+ link.symlink_to(self.path)
+ with self.assertRaises(OSError):
+ target.load_plan(link)
+ link.unlink()
+ os.link(self.path, link)
+ with self.assertRaises(target.TargetError):
+ target.load_plan(self.path)
+ link.unlink()
+ self.path.chmod(0o644)
+ with self.assertRaises(target.TargetError):
+ target.load_plan(self.path)
+ os.mkfifo(self.root / 'fifo', 0o600)
+ with self.assertRaises(target.TargetError):
+ target.load_plan(self.root / 'fifo')
+
+ def test_truncated_oversized_and_mutated_records_refused(self):
+ target.save_plan(self.path, self.plan)
+ for content in ['{', ' ' * (128 * 1024 + 1), json.dumps({**self.plan, 'schema': 2})]:
+ self.path.write_text(content)
+ with self.subTest(content=content[:80]), self.assertRaises(target.TargetError):
+ target.load_plan(self.path)
+
+
+if __name__ == '__main__':
+ unittest.main()