Harden release packaging and recoverable installation after review

This commit is contained in:
bholman committed 2026-11-18 16:26:25 -07:00
1 parent cb40fed3b9
commit 8088c1fbf6
14 files changed
+933 -101

No files matched your search

+280 -52
View File
@@ -1,54 +1,282 @@
#!/usr/bin/env python3
"""Install a verified overlay using existing passwordless OpenSSH access."""
import argparse,datetime,json,re,shlex,subprocess
from pathlib import Path,PurePosixPath
from release import ROOT,make_release,sha
def q(s):return shlex.quote(str(s))
def main():
p=argparse.ArgumentParser(description=__doc__)
p.add_argument('--host',help='IP or DNS hostname; prompted when omitted')
p.add_argument('--user',default='root')
p.add_argument('--release',type=Path,help='Existing tools/release.py output; otherwise package defaults')
p.add_argument('--without-ssc',action='store_true')
p.add_argument('--load',action='store_true',help='Return to MENU then load the new launcher')
a=p.parse_args();a.host=a.host or input('MiSTer IP address or hostname: ').strip()
if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*',a.host) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_-]*',a.user):p.error('Use a plain hostname/IP and Unix username')
stamp=datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
release=a.release.resolve() if a.release else ROOT/'dist'/('install-'+stamp)
if not a.release:make_release(release,ROOT/'build/fpga',ROOT/'build/roms',ROOT/'roms/ssc',a.without_ssc)
manifest=json.loads((release/'manifest.json').read_text());fat=release/'fat'
if manifest.get('public_package'):raise RuntimeError('Public core/source package omits required ROMs. Build a complete local package with your verified ROM inputs; see docs/INSTALL.md.')
for n,v in manifest['files'].items():
path=PurePosixPath(n)
if path.is_absolute() or '..' in path.parts or '\\' in n:raise RuntimeError('Unsafe manifest path')
file=fat/n
if not file.is_file() or file.stat().st_size!=v['bytes'] or sha(file)!=v['sha256']:raise RuntimeError('Release changed: '+n)
args=['-o','BatchMode=yes','-o','StrictHostKeyChecking=yes','-o','ConnectTimeout=10']
target=a.user+'@'+a.host
def ssh(script):return subprocess.check_output(['ssh',*args,target,'sh -s'],input=script.encode(),stderr=subprocess.STDOUT).decode()
# No target writes before all local hashes and this read-only preflight pass.
print(ssh('set -eu\ntest -d /media/fat\ntest -w /media/fat\ntest -e /dev/MiSTer_cmd\ncommand -v sha256sum\nid\n').strip())
remote='/media/fat/.coco3plus/install-'+stamp;backup=remote+'/backup';stage=remote+'/stage'
ssh('set -eu\nmkdir -p '+q(stage)+' '+q(backup)+'\n')
# Raw argv paths are intentional: OpenSSH SFTP handles spaces without shell quoting.
subprocess.run(['scp',*args,'-r',str(fat),target+':'+stage+'/'],check=True)
lines=['set -eu']
for n,v in manifest['files'].items():lines.append('test "$(sha256sum '+q(stage+'/fat/'+n)+' | cut -d " " -f 1)" = '+q(v['sha256']))
lines.append("printf 'load_core /media/fat/menu.rbf\\n' > /dev/MiSTer_cmd")
lines.append('sleep 2')
for n,v in manifest['files'].items():
src=stage+'/fat/'+n;dest='/media/fat/'+n;old=backup+'/'+n
lines.append('mkdir -p '+q(str(PurePosixPath(dest).parent))+' '+q(str(PurePosixPath(old).parent)))
if v['policy']=='create-if-missing':lines.append('if [ ! -e '+q(dest)+' ]; then cp '+q(src)+' '+q(dest)+'; fi')
"""Install a verified overlay using existing passwordless OpenSSH access.
Original Coco 3 Plus contributions: Copyright (c) 2026 Brian K. Holman.
Original component notices/terms retained; see COPYRIGHT.md and LICENSING.md.
"""
import argparse
import datetime
import json
import os
from pathlib import Path, PurePosixPath
import re
import shlex
import subprocess
import sys
import uuid
from release import ROOT, make_release, sha
LAUNCHER = '_Computer/Coco 3 Plus.mgl'
def q(value):
return shlex.quote(str(value))
def atomic_json(path, value):
"""Keep the last complete receipt if a local update itself is interrupted."""
temporary = path.with_name(path.name + '.' + uuid.uuid4().hex + '.tmp')
with temporary.open('x', encoding='utf-8', newline='\n') as file:
json.dump(value, file, indent=2)
file.write('\n')
file.flush()
os.fsync(file.fileno())
os.replace(temporary, path)
class OpenSshTarget:
def __init__(self, host, user):
self.options = ['-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes',
'-o', 'ConnectTimeout=10']
self.target = user + '@' + host
def run(self, script):
return subprocess.check_output(
['ssh', *self.options, self.target, 'sh -s'],
input=('set -eu\n' + script + '\n').encode(),
stderr=subprocess.STDOUT).decode()
def preflight(self):
return self.run('test -d /media/fat\ntest -w /media/fat\n'
'test -e /dev/MiSTer_cmd\ncommand -v sha256sum\nid')
def prepare(self, stage, backup):
self.run('test ! -e ' + q(PurePosixPath(stage).parent) +
'\nmkdir -p ' + q(stage) + ' ' + q(backup))
def upload(self, fat, stage):
# Raw argv paths are intentional: SFTP handles spaces without shell quotes.
subprocess.run(['scp', *self.options, '-r', str(fat),
self.target + ':' + stage + '/'], check=True)
def verify(self, files):
lines = []
for name, digest in files.items():
lines.append('test "$(sha256sum ' + q(name) +
' | cut -d " " -f 1)" = ' + q(digest))
self.run('\n'.join(lines))
def enter_menu(self):
self.run("printf 'load_core /media/fat/menu.rbf\\n' > /dev/MiSTer_cmd\nsleep 2")
def install_file(self, source, destination, backup, entry, temporary):
# Copy/verify beside the destination, then rename within the same FAT
# filesystem. The staged original remains available for recovery.
lines = [
'mkdir -p ' + q(PurePosixPath(destination).parent) + ' ' +
q(PurePosixPath(backup).parent),
'if [ -e ' + q(destination) + ' ]; then',
' test -f ' + q(destination),
]
if entry['policy'] == 'create-if-missing':
lines += [" printf 'preserved\\n'", ' exit 0']
else:
lines.append('if [ -e '+q(dest)+' ]; then cp '+q(dest)+' '+q(old)+'; fi')
lines.append('cp '+q(src)+' '+q(dest))
lines.append('test "$(sha256sum '+q(dest)+' | cut -d " " -f 1)" = '+q(v['sha256']))
lines.append('sync')
if a.load:lines.append("printf 'load_core /media/fat/_Computer/Coco 3 Plus.mgl\\n' > /dev/MiSTer_cmd")
result=ssh('\n'.join(lines)+'\n')
receipt=dict(host=a.host,user=a.user,backup=backup,manifest=manifest,loaded=a.load,remote_output=result)
(release/'install-receipt.json').write_text(json.dumps(receipt,indent=2)+'\n')
print('Installed Coco 3 Plus; backup: '+backup+'; RBF '+manifest['rbf_sha256'])
print('Receipt: '+str(release/'install-receipt.json'))
if __name__=='__main__':main()
lines += [' cp ' + q(destination) + ' ' + q(backup)]
lines += [
'fi',
'test ! -e ' + q(temporary),
'cp ' + q(source) + ' ' + q(temporary),
'test "$(sha256sum ' + q(temporary) + ' | cut -d " " -f 1)" = ' +
q(entry['sha256']),
'mv -f ' + q(temporary) + ' ' + q(destination),
'test "$(sha256sum ' + q(destination) + ' | cut -d " " -f 1)" = ' +
q(entry['sha256']),
"printf 'installed\\n'",
]
result = self.run('\n'.join(lines)).splitlines()
if not result or result[-1] not in ('installed', 'preserved'):
raise RuntimeError('Missing remote install result: ' + destination)
return result[-1]
def activate_launcher(self, source, destination, backup, entry, temporary):
return self.install_file(source, destination, backup, entry, temporary)
def sync(self):
self.run('sync')
def load(self):
self.run("printf 'load_core /media/fat/_Computer/Coco 3 Plus.mgl\\n' > /dev/MiSTer_cmd")
def validated_manifest(package):
manifest = json.loads((package / 'manifest.json').read_text())
if manifest.get('public_package'):
raise RuntimeError('Public core/source package omits required ROMs. '
'Build a complete local package with your verified '
'ROM inputs; see docs/INSTALL.md.')
for name, entry in manifest['files'].items():
path = PurePosixPath(name)
if path.is_absolute() or '..' in path.parts or '\\' in name:
raise RuntimeError('Unsafe manifest path')
if entry['policy'] not in ('create-if-missing', 'backup-and-replace'):
raise RuntimeError('Unsupported install policy: ' + name)
file = package / 'fat' / name
if (not file.is_file() or file.stat().st_size != entry['bytes'] or
sha(file) != entry['sha256']):
raise RuntimeError('Release changed: ' + name)
if (LAUNCHER not in manifest['files'] or
manifest['files'][LAUNCHER]['policy'] != 'backup-and-replace'):
raise RuntimeError('A replaceable Coco 3 Plus launcher is required')
return manifest
def install_release(package, host, user='root', load=False, *, target=None, stamp=None):
"""Install support first and activate last; target injection is for tests."""
package = Path(package).resolve()
manifest = validated_manifest(package)
if (not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*', host) or
not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_-]*', user)):
raise ValueError('Use a plain hostname/IP and Unix username')
stamp = stamp or datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
if not re.fullmatch(r'[A-Za-z0-9_-]{1,80}', stamp):
raise ValueError('Invalid installation attempt identifier')
remote = '/media/fat/.coco3plus/install-' + stamp
backup, stage = remote + '/backup', remote + '/stage'
receipt_path = package / ('install-receipt-' + stamp + '.json')
latest_path = package / 'install-receipt.json'
if receipt_path.exists():
raise RuntimeError('Preserve existing installation attempt: ' + str(receipt_path))
previous = None
if latest_path.exists():
previous = package / ('install-receipt-before-' + stamp + '.json')
with previous.open('xb') as file:
file.write(latest_path.read_bytes())
plans = {
name: dict(source=stage + '/fat/' + name,
destination='/media/fat/' + name,
backup=backup + '/' + name,
temporary='/media/fat/' + name + '.install-' + stamp + '.tmp',
policy=entry['policy'])
for name, entry in manifest['files'].items()
}
receipt = dict(
host=host, user=user, attempt=stamp, status='planned', phase='planned',
remote=remote, stage=stage, backup=backup, manifest=manifest,
receipt=str(receipt_path), previous_receipt=str(previous) if previous else None,
launcher='/media/fat/' + LAUNCHER,
launcher_temporary='/media/fat/' + LAUNCHER + '.install-' + stamp + '.tmp',
activation_attempted=False, launcher_activated=False, load_requested=load,
loaded=False, planned_files=plans, active_file=None,
completed_files=[], history=['planned'],
recovery='Preserve stage and backup. Before activation the old launcher '
'remains, but supporting files may already have changed. Restore '
'their backed-up copies if rollback is needed. If activation '
'was attempted but not confirmed, inspect the launcher before '
'loading; restore the backed-up launcher if needed.')
def save():
atomic_json(receipt_path, receipt)
atomic_json(latest_path, receipt)
def phase(name):
receipt['status'] = 'in-progress'
receipt['phase'] = name
receipt['history'].append(name)
save()
# A durable local plan names all recovery locations before target mutation.
save()
print('Planned receipt: ' + str(receipt_path), flush=True)
print('Remote stage: ' + stage, flush=True)
print('Remote backup: ' + backup, flush=True)
client = target if target is not None else OpenSshTarget(host, user)
try:
phase('preflight')
receipt['preflight_output'] = client.preflight()
phase('staging')
client.prepare(stage, backup)
client.upload(package / 'fat', stage)
phase('staged-verification')
client.verify({stage + '/fat/' + n: v['sha256']
for n, v in manifest['files'].items()})
phase('returning-to-menu')
client.enter_menu()
phase('supporting-assets')
installed = {}
for name in sorted(n for n in manifest['files'] if n != LAUNCHER):
entry = manifest['files'][name]
receipt['active_file'] = name
save()
destination = '/media/fat/' + name
result = client.install_file(
stage + '/fat/' + name, destination, backup + '/' + name, entry,
destination + '.install-' + stamp + '.tmp')
receipt['completed_files'].append(dict(path=name, result=result))
receipt['active_file'] = None
if result == 'installed':
installed[destination] = entry['sha256']
save()
client.verify(installed)
client.sync()
phase('activating-launcher')
receipt['activation_attempted'] = True
receipt['active_file'] = LAUNCHER
# A transport failure during rename can leave activation uncertain.
receipt['launcher_activated'] = None
save()
client.activate_launcher(
stage + '/fat/' + LAUNCHER, receipt['launcher'],
backup + '/' + LAUNCHER, manifest['files'][LAUNCHER],
receipt['launcher_temporary'])
receipt['launcher_activated'] = True
receipt['active_file'] = None
phase('launcher-activated')
client.sync()
if load:
phase('loading')
receipt['loaded'] = None
save()
client.load()
receipt['loaded'] = True
receipt['status'] = 'complete'
receipt['phase'] = 'complete'
receipt['history'].append('complete')
save()
except BaseException as error:
receipt['status'] = 'failed'
receipt['history'].append('failed')
receipt['error'] = dict(type=type(error).__name__, message=str(error))
output = getattr(error, 'output', None)
if output:
receipt['error']['output'] = (
output.decode(errors='replace') if isinstance(output, bytes) else str(output))[-8192:]
try:
save()
except Exception as save_error:
print('Could not update failure receipt; prior plan remains at ' +
str(receipt_path) + ': ' + str(save_error), file=sys.stderr)
raise
print('Installed Coco 3 Plus; backup: ' + backup + '; RBF ' + manifest['rbf_sha256'])
print('Receipt: ' + str(receipt_path))
return receipt
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--host', help='IP or DNS hostname; prompted when omitted')
parser.add_argument('--user', default='root')
parser.add_argument('--release', type=Path, help='Existing tools/release.py output; otherwise package defaults')
parser.add_argument('--without-ssc', action='store_true')
parser.add_argument('--load', action='store_true', help='Return to MENU then load the new launcher')
args = parser.parse_args()
args.host = args.host or input('MiSTer IP address or hostname: ').strip()
stamp = datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
package = args.release.resolve() if args.release else ROOT / 'dist' / ('install-' + stamp)
if not args.release:
make_release(package, ROOT / 'build/fpga', ROOT / 'build/roms',
ROOT / 'roms/ssc', args.without_ssc)
install_release(package, args.host, args.user, args.load, stamp=stamp)
if __name__ == '__main__':
main()