Files
VCCPlusOSS/tools/roms/stage.py
T

320 lines
14 KiB
Python

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Stage an optional explicitly built ROM bundle for source-profile Mac builds.
Validation establishes byte identity and a safe copy boundary, not redistribution
permission or hardware compatibility. No maintainer ROM or media path is probed.
Isolated UI-test products omit all bundles without inspecting their input paths.
"""
import argparse
import ctypes
import errno
import hashlib
import json
import os
from pathlib import Path
import re
import shutil
import stat
import sys
import tempfile
ROM_SIZES = {'coco3.rom': 32768, 'disk11.rom': 8192}
BUNDLE_FILES = set(ROM_SIZES) | {'ROMBuild.json', 'ROM_SOURCE_NOTICE.txt'}
STARTER_FILES = ('Hello World.dsk', 'Hello World.cas', 'Blank Disk.dsk',
'Hello Hard Disk.dsk', 'Blank OS9 Header.bin')
HASH = re.compile(r'^[0-9a-f]{64}$')
MANIFEST_LIMIT = 256 * 1024
NOTICE_LIMIT = 64 * 1024
STARTER_LIMIT = 2 * 1024 * 1024
def absolute(path):
value = Path(path)
if '..' in value.parts:
raise ValueError('Staging paths must not contain parent traversal')
return value if value.is_absolute() else Path.cwd() / value
def check_ancestors(path, description):
"""Reject redirected inputs/outputs, except the two public macOS aliases."""
aliases = {Path('/tmp'): Path('/private/tmp'), Path('/var'): Path('/private/var')}
for parent in path.parents:
try:
info = parent.lstat()
except FileNotFoundError:
continue
if stat.S_ISLNK(info.st_mode):
if parent in aliases and parent.resolve() == aliases[parent]:
continue
raise ValueError(description + ' must not have a linked ancestor')
if not stat.S_ISDIR(info.st_mode):
raise ValueError(description + ' must have directory ancestors')
def directory(path, description, optional=False):
check_ancestors(path, description)
try:
info = path.lstat()
except FileNotFoundError:
if optional:
return False
raise ValueError(description + ' is missing')
if not stat.S_ISDIR(info.st_mode):
raise ValueError(description + ' must be an unlinked directory')
return True
def signature(info):
return (info.st_dev, info.st_ino, info.st_mode, info.st_nlink,
info.st_size, info.st_mtime_ns, info.st_ctime_ns)
def read_regular(path, maximum, description, expected_size=None):
check_ancestors(path, description)
try:
before = path.lstat()
except FileNotFoundError:
raise ValueError(description + ' is missing')
if not stat.S_ISREG(before.st_mode) or before.st_nlink != 1:
raise ValueError(description + ' must be a regular file without links')
if not 0 < before.st_size <= maximum or (expected_size is not None and before.st_size != expected_size):
raise ValueError(description + ' has an invalid size')
flags = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_CLOEXEC', 0)
with os.fdopen(os.open(path, flags), 'rb') as stream:
if signature(os.fstat(stream.fileno())) != signature(before):
raise ValueError(description + ' changed before it could be read')
data = stream.read(maximum + 1)
after = os.fstat(stream.fileno())
if signature(before) != signature(after) or len(data) != before.st_size:
raise ValueError(description + ' changed while it was read')
# A concurrently replaced pathname must not be accepted as the same input.
if signature(path.lstat()) != signature(before):
raise ValueError(description + ' was replaced while it was read')
return data
def unique_object(pairs):
value = {}
for key, item in pairs:
if key in value:
raise ValueError('ROM build manifest contains a duplicate field')
value[key] = item
return value
def read_bundle(source):
if set(item.name for item in source.iterdir()) != BUNDLE_FILES:
raise ValueError('Source ROM bundle must contain exactly the manifest, notice, and two required ROMs')
manifest_bytes = read_regular(source / 'ROMBuild.json', MANIFEST_LIMIT, 'ROM build manifest')
try:
record = json.loads(manifest_bytes.decode('utf-8'), object_pairs_hook=unique_object)
except RecursionError:
raise ValueError('ROM build manifest nesting is excessive')
if not isinstance(record, dict) or type(record.get('schemaVersion')) is not int or record['schemaVersion'] != 1:
raise ValueError('Unsupported ROM build manifest schema')
if record.get('generator') != 'vccplus-rom-build':
raise ValueError('Unsupported ROM bundle generator')
if not isinstance(record.get('source'), dict) or not record['source']:
raise ValueError('ROM build manifest requires source metadata')
roms = record.get('roms')
if not isinstance(roms, dict) or set(roms) != set(ROM_SIZES):
raise ValueError('ROM build manifest must identify both required ROMs only')
payload = {'ROMBuild.json': manifest_bytes}
notice = read_regular(source / 'ROM_SOURCE_NOTICE.txt', NOTICE_LIMIT, 'ROM source notice')
if not notice.decode('utf-8').strip() or b'\0' in notice:
raise ValueError('ROM source notice must be nonempty UTF-8 text')
payload['ROM_SOURCE_NOTICE.txt'] = notice
for name, size in ROM_SIZES.items():
entry = roms[name]
if (not isinstance(entry, dict) or type(entry.get('bytes')) is not int or entry['bytes'] != size
or not isinstance(entry.get('sha256'), str) or not HASH.fullmatch(entry['sha256'])):
raise ValueError('Invalid ROM manifest entry: ' + name)
data = read_regular(source / name, size, name, expected_size=size)
if hashlib.sha256(data).hexdigest() != entry['sha256']:
raise ValueError('ROM bytes do not match their build manifest: ' + name)
payload[name] = data
return payload
def check_resources(resources):
if (resources.name != 'Resources' or resources.parent.name != 'Contents'
or resources.parent.parent.suffix != '.app'):
raise ValueError('Destination must be APP.app/Contents/Resources')
directory(resources, 'App Resources destination', optional=True)
def check_kit(kit):
if not directory(kit, 'Build-owned StarterKit', optional=True):
return False
# Cleanup is confined to this build-owned directory. Reject redirected files
# before either swapping an existing kit or removing an obsolete payload.
for folder, names, files in os.walk(kit, followlinks=False):
for name in names:
directory(Path(folder) / name, 'StarterKit member directory')
for name in files:
info = (Path(folder) / name).lstat()
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
raise ValueError('StarterKit members must be regular files without links')
return True
def overlaps(first, second):
# Ancestors were checked before canonicalizing the accepted /tmp,/var aliases.
first, second = first.resolve(), second.resolve()
return first == second or first in second.parents or second in first.parents
def atomic_file(destination, data):
check_ancestors(destination, 'Build resource')
if destination.exists() or destination.is_symlink():
info = destination.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
raise ValueError('Build resource must be a regular file without links')
if info.st_size == len(data) and read_regular(destination, STARTER_LIMIT, 'Existing build resource') == data:
return
temporary = None
try:
with tempfile.NamedTemporaryFile(prefix='.source-rom-resource-', dir=destination.parent, delete=False) as stream:
temporary = Path(stream.name)
stream.write(data)
os.chmod(temporary, 0o644)
# Recheck the owned output boundary immediately before replacement.
check_ancestors(destination, 'Build resource')
if destination.exists() or destination.is_symlink():
info = destination.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
raise ValueError('Build resource changed to a linked or nonregular file')
os.replace(temporary, destination)
finally:
if temporary is not None:
temporary.unlink(missing_ok=True)
def exchange_directories(first, second):
"""Atomically exchange complete directories; never expose a partial kit."""
library = ctypes.CDLL(None, use_errno=True)
if sys.platform == 'darwin':
operation = getattr(library, 'renamex_np', None)
if operation is not None:
operation.argtypes = (ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint)
operation.restype = ctypes.c_int
result = operation(os.fsencode(first), os.fsencode(second), 2) # RENAME_SWAP
else:
raise OSError(errno.ENOTSUP, 'Atomic directory exchange is unavailable')
elif sys.platform.startswith('linux'):
operation = getattr(library, 'renameat2', None)
if operation is not None:
operation.argtypes = (ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint)
operation.restype = ctypes.c_int
result = operation(-100, os.fsencode(first), -100, os.fsencode(second), 2) # RENAME_EXCHANGE
else:
raise OSError(errno.ENOTSUP, 'Atomic directory exchange is unavailable')
else:
raise OSError(errno.ENOTSUP, 'Atomic directory exchange is unavailable')
if result:
error = ctypes.get_errno()
raise OSError(error, os.strerror(error))
def selected_source(srcroot, explicit=None, environ=None):
environment = os.environ if environ is None else environ
return absolute(explicit if explicit is not None else
environment.get('VCC_SOURCE_ROM_DIR') or srcroot / 'LocalResources/SourceROMBundle')
def isolated_ui_testing(environment):
if environment.get('CONFIGURATION') == 'UITesting':
return True
swift_conditions = environment.get('SWIFT_ACTIVE_COMPILATION_CONDITIONS', '').split()
if 'VCC_UI_TESTING' in swift_conditions:
return True
definitions = environment.get('GCC_PREPROCESSOR_DEFINITIONS', '').split()
return any(value in ('VCC_UI_TESTING', 'VCC_UI_TESTING=1') for value in definitions)
def remove_interrupted_staging(resources):
# After an exchange, the temporary pathname contains the former StarterKit.
# A killed build must not leave that old profile's payload in the next app.
# Match only this helper's generated eight-character temporary names.
for path in resources.iterdir():
if re.fullmatch(r'\.source-rom-starter-[a-z0-9_]{8}', path.name):
check_kit(path)
shutil.rmtree(path)
elif re.fullmatch(r'\.source-rom-resource-[a-z0-9_]{8}', path.name):
info = path.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
raise ValueError('Interrupted build resource must be a regular file without links')
path.unlink()
def stage_source_roms(srcroot, resources, source=None, environ=None):
srcroot, resources = absolute(srcroot), absolute(resources)
directory(srcroot, 'Mac source directory')
check_resources(resources)
environment = os.environ if environ is None else environ
ui_testing = isolated_ui_testing(environment)
# Do not even resolve or inspect an explicit/generated ROM location for the
# isolated UI app. Only its build-owned output and authored header are used.
bundle = None if ui_testing else selected_source(srcroot, source, environment)
present = directory(bundle, 'Source ROM bundle', optional=True) if bundle is not None else False
starter = srcroot / 'Resources/StarterMedia'
directory(starter, 'Authored starter media')
if (bundle is not None and overlaps(bundle, resources)) or overlaps(starter, resources):
raise ValueError('Build resources must not overlap source inputs')
kit = resources / 'StarterKit'
check_kit(kit)
# Validate all selected inputs before creating or changing a build resource.
payload = read_bundle(bundle) if present else None
header = read_regular(starter / 'Blank OS9 Header.bin', STARTER_LIMIT, 'Authored OS-9 header', expected_size=8192)
if payload is not None:
for name in STARTER_FILES:
payload[name] = read_regular(starter / name, STARTER_LIMIT, 'Authored starter media: ' + name)
resources.mkdir(parents=True, exist_ok=True)
check_resources(resources)
remove_interrupted_staging(resources)
atomic_file(resources / 'Blank OS9 Header.bin', header)
if payload is None:
if check_kit(kit):
shutil.rmtree(kit)
return {'staged': False, 'roms': {}, 'ui_testing': ui_testing}
staging = Path(tempfile.mkdtemp(prefix='.source-rom-starter-', dir=resources))
try:
for name, data in payload.items():
(staging / name).write_bytes(data)
os.chmod(staging / name, 0o644)
os.chmod(staging, 0o755)
check_resources(resources)
if check_kit(kit):
exchange_directories(staging, kit)
# The staging pathname now contains only the previous owned kit.
else:
os.rename(staging, kit)
return {'staged': True, 'roms': {name: {'bytes': len(payload[name]), 'sha256': hashlib.sha256(payload[name]).hexdigest()}
for name in ROM_SIZES}}
finally:
if staging.exists():
shutil.rmtree(staging)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--srcroot', type=Path, required=True, help='Mac project directory (platforms/macos)')
parser.add_argument('--resources', type=Path, required=True, help='Build-owned APP.app/Contents/Resources')
parser.add_argument('--source', type=Path, help='Explicit source ROM bundle; overrides VCC_SOURCE_ROM_DIR')
args = parser.parse_args()
try:
result = stage_source_roms(args.srcroot, args.resources, args.source)
except (OSError, ValueError, UnicodeError) as error:
parser.error(str(error))
if result['staged']:
print('Included explicitly built source ROMs, original source notice, and authored starter media.')
elif result.get('ui_testing'):
print('Isolated UI-test build omits ROM bundles and retains only the authored standalone header.')
else:
print('Optional source ROM bundle is absent; building without bundled ROMs.')
if __name__ == '__main__':
main()