@leera.io/qa-runner 1.0.0

package/dist/src/session/loop.js

@@ -0,0 +1,148 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ApiError } from '../client.js';
+import { redactor } from '../template.js';
+import { DEFAULT_COMMAND_TIMEOUT_MS } from './commands.js';
+import { SessionExecutor } from './execute.js';
+/** The long-poll never asks for more than the server allows (plan §4). */
+const MAX_WAIT_SECONDS = 25;
+/**
+ * Runs one device session (plan §7.5): launches the app on the leased device, takes an
+ * initial snapshot, then long-polls commands, executes each (default 30 s timeout,
+ * `wait_for` ≤ 60 s) and posts its result with a screenshot. Ends on an `end` command,
+ * 410 from the server, idle timeout, maximum lifetime, runner shutdown or a device/driver
+ * failure; the driver is always disposed. The caller releases the device lease.
+ */
+export async function runSession(session, deps) {
+    const { client, log } = deps;
+    const now = deps.now ?? Date.now;
+    const retryDelayMs = deps.retryDelayMs ?? 2_000;
+    const redact = redactor([session.credential?.password]);
+    const started = now();
+    const idleMs = Math.max(1, session.idle_timeout_seconds) * 1_000;
+    const maxMs = Math.max(1, session.max_seconds) * 1_000;
+    const unreachableMs = Math.max(30, session.lease_seconds) * 1_000;
+    let lastActivity = started;
+    let commands = 0;
+    let serverEnded = false;
+    let outcome = null;
+    let driver = null;
+    const finish = (reason, detail = reason) => ({ reason, detail, commands });
+    log.info('session started', { session_id: session.id, platform: session.platform, device: session.device?.id ?? null });
+    try {
+        driver = await deps.createDriver();
+        await driver.launch();
+        const executor = new SessionExecutor(driver, {
+            commandTimeoutMs: session.command_timeout_seconds > 0 ? session.command_timeout_seconds * 1_000 : DEFAULT_COMMAND_TIMEOUT_MS,
+            redact,
+        });
+        await executor.prime().catch((error) => log.debug('initial snapshot failed', { session_id: session.id, error: redact(message(error)) }));
+        let failingSince = null;
+        while (!outcome) {
+            if (deps.shouldStop()) {
+                outcome = finish('runner_stopping');
+                break;
+            }
+            const t = now();
+            if (t - started >= maxMs) {
+                outcome = finish('expired');
+                break;
+            }
+            if (t - lastActivity >= idleMs) {
+                outcome = finish('idle');
+                break;
+            }
+            const remaining = Math.min(idleMs - (t - lastActivity), maxMs - (t - started));
+            const wait = Math.max(1, Math.min(session.poll_wait_seconds || MAX_WAIT_SECONDS, MAX_WAIT_SECONDS, Math.ceil(remaining / 1_000)));
+            let next;
+            try {
+                next = await client.nextCommand(session.id, deps.runnerId, wait, deps.stopSignal);
+                failingSince = null;
+            }
+            catch (error) {
+                if (deps.shouldStop())
+                    continue;
+                if (error instanceof ApiError && [401, 403, 404].includes(error.status)) {
+                    outcome = finish('ended_by_server', error.message);
+                    serverEnded = true;
+                    break;
+                }
+                failingSince ??= now();
+                if (now() - failingSince >= unreachableMs) {
+                    outcome = finish('server_unreachable');
+                    break;
+                }
+                log.warn('session poll failed, retrying', { session_id: session.id, error: redact(message(error)) });
+                await sleep(retryDelayMs);
+                continue;
+            }
+            if (next.kind === 'gone') {
+                serverEnded = true;
+                outcome = finish('ended_by_server', next.reason ?? next.status);
+                break;
+            }
+            if (next.kind === 'none')
+                continue;
+            const command = next.command;
+            commands += 1;
+            lastActivity = now();
+            const executed = await executor.execute(command);
+            log.debug('session command', {
+                session_id: session.id,
+                command_id: command.id,
+                type: command.type,
+                ok: executed.result.ok,
+                error: executed.result.error?.code ?? null,
+            });
+            const posted = await postResult(client, session.id, command.id, executed.result, executed.screenshot, retryDelayMs, log);
+            lastActivity = now();
+            if (posted === 'gone') {
+                serverEnded = true;
+                outcome = finish('ended_by_server', 'the session ended while a command ran');
+                break;
+            }
+            if (executed.end)
+                outcome = finish('end_command');
+        }
+    }
+    catch (error) {
+        const detail = redact(message(error)).slice(0, 500);
+        log.error('session failed', { session_id: session.id, error: detail });
+        outcome = finish('failed', `failed: ${detail}`);
+    }
+    finally {
+        const final = outcome ?? finish('failed');
+        if (!serverEnded) {
+            await client
+                .endSession(session.id, final.detail)
+                .catch((error) => log.warn('could not end the session', { session_id: session.id, error: redact(message(error)) }));
+        }
+        if (driver) {
+            await driver.stopRecording().catch(() => undefined);
+            await driver.dispose().catch(() => undefined);
+        }
+        log.info('session ended', { session_id: session.id, reason: final.reason, commands: final.commands });
+    }
+    return outcome ?? finish('failed');
+}
+async function postResult(client, sessionId, commandId, result, screenshot, retryDelayMs, log) {
+    const shot = screenshot ? { bytes: screenshot, contentType: 'image/png' } : null;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await client.postCommandResult(sessionId, commandId, result, shot);
+            return 'ok';
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 410)
+                return 'gone';
+            const permanent = error instanceof ApiError && error.status >= 400 && error.status < 500;
+            if (permanent || attempt >= 3) {
+                log.warn('could not send a command result', { session_id: sessionId, command_id: commandId, error: message(error) });
+                return 'dropped';
+            }
+            await sleep(retryDelayMs * attempt);
+        }
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/template.js

@@ -0,0 +1,62 @@
+import { randomBytes, randomInt } from 'node:crypto';
+export class TemplateError extends Error {
+}
+const PLACEHOLDER = /\{\{\s*([a-z_.]+)\s*\}\}/g;
+export function renderTemplate(text, ctx) {
+    return text.replace(PLACEHOLDER, (_match, name) => placeholderValue(name, ctx));
+}
+export function resolveUrl(url, baseUrl) {
+    if (url.startsWith('/') && !url.startsWith('//'))
+        return trimSlash(baseUrl) + url;
+    return url;
+}
+/** Replaces every secret in `text`; secrets under 4 characters are skipped because they would mangle ordinary words. */
+export function redactor(secrets) {
+    const values = secrets
+        .filter((secret) => typeof secret === 'string' && secret.length >= 4)
+        .sort((a, b) => b.length - a.length);
+    return (text) => values.reduce((out, secret) => out.split(secret).join('[redacted]'), text);
+}
+function placeholderValue(name, ctx) {
+    switch (name) {
+        case 'env.base_url':
+            return trimSlash(ctx.baseUrl);
+        case 'credential.username':
+            return present(ctx.username, name);
+        case 'credential.password':
+            return present(ctx.password, name);
+        case 'run.id':
+            return String(ctx.runId);
+        case 'app.id':
+            if (!ctx.appId)
+                throw new TemplateError('the script uses {{app.id}} but the job has no app');
+            return ctx.appId;
+        case 'random.email':
+            return remembered(ctx, name, () => `qa.${token(10)}@example.com`);
+        case 'random.string':
+            return remembered(ctx, name, () => token(12));
+        case 'random.number':
+            return remembered(ctx, name, () => String(randomInt(100_000, 1_000_000)));
+        default:
+            throw new TemplateError(`unknown placeholder {{${name}}}`);
+    }
+}
+function present(value, name) {
+    if (value === null)
+        throw new TemplateError(`the script uses {{${name}}} but the job has no credential`);
+    return value;
+}
+function remembered(ctx, name, make) {
+    let value = ctx.random.get(name);
+    if (value === undefined) {
+        value = make();
+        ctx.random.set(name, value);
+    }
+    return value;
+}
+function token(length) {
+    return randomBytes(length).toString('hex').slice(0, length);
+}
+function trimSlash(url) {
+    return url.replace(/\/+$/, '');
+}

package/dist/src/types.js

@@ -0,0 +1,7 @@
+/** The platform a script is written for: v1 is always web. */
+export function scriptPlatform(script) {
+    return script.version === 2 ? script.platform : 'web';
+}
+export function isSessionClaim(claim) {
+    return claim.kind === 'session';
+}

package/dist/src/update/apply.js

@@ -0,0 +1,223 @@
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve, sep } from 'node:path';
+import { writeResponseBody } from '../download.js';
+import { readJsonFile, writePrivateFile } from '../home.js';
+import { applyPlan, backendFor, execArgv, serviceSpec } from '../service/index.js';
+import { compareVersions } from '../version.js';
+import { releaseDir } from './manifest.js';
+import { sha256File } from './verify.js';
+export const NPM_PACKAGE = '@leera.io/qa-runner';
+export const BREW_CASK = 'leera-qa-runner';
+export const WINGET_ID = 'Leera.QARunner';
+export const DOCKER_IMAGE = 'ghcr.io/leera-app/leera-qa-runner';
+/** Versions kept in `versions/` after an update (the new one included). */
+export const KEEP_VERSIONS = 2;
+const VERSION_DIR = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+/** The upgrade command for a package-manager install (fixed argv), or null for other methods. */
+export function packageManagerArgv(method, version) {
+    switch (method) {
+        case 'npm':
+            return ['npm', 'install', '-g', `${NPM_PACKAGE}@${version ?? 'latest'}`];
+        case 'brew':
+            return ['brew', 'upgrade', '--cask', BREW_CASK];
+        case 'winget':
+            return ['winget', 'upgrade', '--id', WINGET_ID, '--exact', ...(version ? ['--version', version] : [])];
+        default:
+            return null;
+    }
+}
+/** Runs a package manager with inherited output; npm is a .cmd on Windows, which Node only starts through a shell (fixed, validated arguments). */
+export function runInherited(argv, platform = process.platform) {
+    return new Promise((done) => {
+        const [command, ...args] = argv;
+        const child = spawn(command, args, { stdio: 'inherit', shell: platform === 'win32' && command === 'npm', windowsHide: true });
+        child.on('error', () => done(127));
+        child.on('close', (code) => done(code ?? 1));
+    });
+}
+/** The `current` pointer: a symlink on unix, `current.txt` on Windows (read by the .cmd launcher). */
+export function currentPointer(paths, platform) {
+    return join(paths.versions, platform === 'win32' ? 'current.txt' : 'current');
+}
+/** The version `current` points at, or null. */
+export function readCurrentVersion(paths, platform) {
+    const pointer = currentPointer(paths, platform);
+    try {
+        if (platform === 'win32')
+            return readFileSync(pointer, 'utf8').trim() || null;
+        return basename(readlinkSync(pointer));
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically points `current` at `versions/<version>`. */
+export function flipCurrent(paths, version, platform) {
+    const pointer = currentPointer(paths, platform);
+    const temp = `${pointer}.${process.pid}.tmp`;
+    rmSync(temp, { force: true });
+    if (platform === 'win32') {
+        writeFileSync(temp, `${version}\r\n`);
+    }
+    else {
+        symlinkSync(version, temp);
+    }
+    renameSync(temp, pointer);
+}
+/** Removes all but the `keep` newest version directories; `target` and directories containing a `protect` path are never removed. */
+export function pruneVersions(paths, target, keep = KEEP_VERSIONS, protect = []) {
+    if (!existsSync(paths.versions))
+        return [];
+    const versions = readdirSync(paths.versions).filter((name) => {
+        if (!VERSION_DIR.test(name))
+            return false;
+        const full = join(paths.versions, name);
+        return lstatSync(full).isDirectory();
+    });
+    versions.sort((a, b) => compareVersions(b, a));
+    const kept = new Set([target]);
+    for (const version of versions) {
+        if (kept.size >= keep)
+            break;
+        kept.add(version);
+    }
+    const protectedDirs = protect.map((dir) => resolve(dir));
+    const isProtected = (dir) => protectedDirs.some((entry) => entry === dir || entry.startsWith(`${dir}${sep}`));
+    const removed = [];
+    for (const version of versions) {
+        const full = join(paths.versions, version);
+        if (kept.has(version) || isProtected(resolve(full)))
+            continue;
+        try {
+            rmSync(full, { recursive: true, force: true });
+            removed.push(version);
+        }
+        catch {
+            // In use (Windows); the next update tries again.
+        }
+    }
+    return removed;
+}
+/** The system tar: bsdtar at %SystemRoot%\System32\tar.exe on Windows (reads .zip), else `tar` on PATH. */
+export function tarArgv(archive, into, platform, env = process.env) {
+    if (platform === 'win32') {
+        return [join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe'), '-xf', archive, '-C', into];
+    }
+    return ['tar', '-xzf', archive, '-C', into];
+}
+function bundleVersion(dir) {
+    try {
+        const info = readJsonFile(join(dir, 'build-info.json'));
+        return typeof info?.version === 'string' ? info.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function launcherIn(dir, platform) {
+    return join(dir, 'bin', platform === 'win32' ? 'leera-qa-runner.cmd' : 'leera-qa-runner');
+}
+async function download(fetchImpl, url, path, maxBytes) {
+    const response = await fetchImpl(url, { redirect: 'follow', signal: AbortSignal.timeout(30 * 60_000), headers: { 'user-agent': 'leera-qa-runner' } });
+    if (!response.ok || !response.body)
+        throw new Error(`${url} answered HTTP ${response.status}`);
+    const length = Number(response.headers.get('content-length') ?? '0');
+    if (length > maxBytes)
+        throw new Error(`${url} is ${length} bytes, but the manifest says ${maxBytes}`);
+    let received = 0;
+    await writeResponseBody(response.body, path, (chunk) => {
+        received += chunk.length;
+        if (received > maxBytes)
+            throw new Error(`${url} is larger than the manifest says (${maxBytes} bytes)`);
+    });
+}
+/**
+ * Downloads a release archive, checks its size and sha256 against the (already trusted) manifest,
+ * unpacks it into `versions/<version>`, flips `current` and prunes old versions.
+ */
+export async function installArchive(options) {
+    const { paths, version, asset, platform } = options;
+    const exec = options.exec ?? execArgv;
+    if (!VERSION_DIR.test(version))
+        throw new Error(`invalid version ${JSON.stringify(version)}`);
+    mkdirSync(paths.versions, { recursive: true, mode: 0o700 });
+    const target = join(paths.versions, version);
+    let reused = false;
+    if (existsSync(target) && bundleVersion(target) === version && existsSync(launcherIn(target, platform))) {
+        reused = true;
+    }
+    else {
+        const archive = join(paths.versions, `.download-${version}-${asset.file}`);
+        const staging = join(paths.versions, `.staging-${version}-${process.pid}`);
+        rmSync(archive, { force: true });
+        rmSync(staging, { recursive: true, force: true });
+        try {
+            const url = `${releaseDir(options.base, version)}/${asset.file}`;
+            await download(options.fetch ?? fetch, url, archive, asset.size);
+            const size = statSync(archive).size;
+            if (size !== asset.size)
+                throw new Error(`${asset.file} is ${size} bytes, but the manifest says ${asset.size}; refusing to install it`);
+            const actual = await sha256File(archive);
+            if (actual !== asset.sha256)
+                throw new Error(`${asset.file} has sha256 ${actual}, but the manifest says ${asset.sha256}; refusing to install it`);
+            mkdirSync(staging, { recursive: true, mode: 0o700 });
+            const argv = tarArgv(archive, staging, platform, options.env);
+            const result = await exec(argv);
+            if (result.code !== 0)
+                throw new Error(`\`${argv.join(' ')}\` failed (exit ${result.code}): ${`${result.stdout}${result.stderr}`.trim()}`);
+            const entries = readdirSync(staging);
+            const bundle = existsSync(join(staging, 'build-info.json'))
+                ? staging
+                : entries.length === 1 && existsSync(join(staging, entries[0], 'build-info.json'))
+                    ? join(staging, entries[0])
+                    : null;
+            if (!bundle)
+                throw new Error(`${asset.file} does not contain a runner bundle (no build-info.json)`);
+            const found = bundleVersion(bundle);
+            if (found !== version)
+                throw new Error(`${asset.file} contains version ${found ?? 'unknown'}, not ${version}; refusing to install it`);
+            if (!existsSync(launcherIn(bundle, platform)))
+                throw new Error(`${asset.file} has no launcher at bin/${basename(launcherIn(bundle, platform))}`);
+            rmSync(target, { recursive: true, force: true });
+            renameSync(bundle, target);
+        }
+        finally {
+            rmSync(archive, { force: true });
+            rmSync(staging, { recursive: true, force: true });
+        }
+    }
+    flipCurrent(paths, version, platform);
+    const removed = pruneVersions(paths, version, options.keep ?? KEEP_VERSIONS, options.protect ?? []);
+    return { dir: target, removed, reused };
+}
+/** Records the new version in install.json, keeping the method and prefix the installer wrote. */
+export function recordUpdate(paths, method, version, now = new Date()) {
+    let record = null;
+    try {
+        record = readJsonFile(paths.install);
+    }
+    catch {
+        record = null;
+    }
+    const next = { ...(record ?? { method }), method: record?.method ?? method, version, updated_at: now.toISOString() };
+    writePrivateFile(paths.install, `${JSON.stringify(next)}\n`);
+}
+/** Restarts the background service when `service install` created one. */
+export async function restartServiceIfInstalled(platform, env, paths, exec = execArgv) {
+    const backend = backendFor(platform);
+    if (!backend)
+        return { restarted: false, reason: 'unsupported' };
+    const spec = serviceSpec(env, paths.root, paths.logs);
+    if (!existsSync(backend.definitionPath(spec)))
+        return { restarted: false, reason: 'not-installed' };
+    const result = await applyPlan(backend.plan('restart', spec), exec);
+    if (result.ok)
+        return { restarted: true };
+    const failed = result.failed;
+    return {
+        restarted: false,
+        reason: 'failed',
+        message: failed ? `\`${failed.argv.join(' ')}\` exited with ${failed.result.code}: ${`${failed.result.stdout}${failed.result.stderr}`.trim()}` : 'unknown error',
+    };
+}

package/dist/src/update/check.js

@@ -0,0 +1,59 @@
+import { homePaths, readJsonFile } from '../home.js';
+import { BUILD_INFO, compareVersions, PACKAGE_ROOT } from '../version.js';
+import { fetchManifest } from './manifest.js';
+export const INSTALL_METHODS = ['pkg', 'exe', 'tar', 'npm', 'brew', 'winget', 'docker'];
+function isTrue(value) {
+    return ['1', 'true', 'yes', 'on'].includes((value ?? '').trim().toLowerCase());
+}
+/** install.json, else an npm install by its path, else Docker by `RUNNER_DOCKER`, else a bundle without a record (tar). */
+export function detectInstall(options = {}) {
+    const env = options.env ?? process.env;
+    const paths = options.paths ?? homePaths(env);
+    let record = null;
+    try {
+        record = readJsonFile(paths.install);
+    }
+    catch {
+        record = null;
+    }
+    if (record && INSTALL_METHODS.includes(record.method)) {
+        return { method: record.method, source: 'install.json', record };
+    }
+    const root = (options.packageRoot ?? PACKAGE_ROOT).replaceAll('\\', '/');
+    if (root.includes('/node_modules/@leera.io/qa-runner'))
+        return { method: 'npm', source: 'npm path', record: null };
+    if (isTrue(env.RUNNER_DOCKER))
+        return { method: 'docker', source: 'docker', record: null };
+    const info = options.buildInfo ?? BUILD_INFO;
+    if (info.os && info.arch)
+        return { method: 'tar', source: 'bundle', record: null };
+    return { method: 'unknown', source: 'none', record: null };
+}
+/** The newest version: the server's `latest_version` cached in state.json, else the latest release manifest. */
+export async function checkForUpdate(options) {
+    const cached = cachedLatestVersion(options.paths);
+    if (cached) {
+        return { current: options.current, latest: cached, source: 'server', available: compareVersions(cached, options.current) > 0 };
+    }
+    const { manifest } = await fetchManifest(options.base, undefined, options.fetch);
+    return {
+        current: options.current,
+        latest: manifest.version,
+        source: 'manifest',
+        available: compareVersions(manifest.version, options.current) > 0,
+    };
+}
+export function cachedLatestVersion(paths) {
+    try {
+        const state = readJsonFile(paths.state);
+        return typeof state?.latest_version === 'string' && state.latest_version.trim() ? state.latest_version.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The local calendar day (`YYYY-MM-DD`) used to log the update notice once per day. */
+export function localDay(now = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}

package/dist/src/update/manifest.js

@@ -0,0 +1,93 @@
+/**
+ * The release manifest (`releases.json`) attached to every runner GitHub Release (contracts §N).
+ *
+ *   {"version":"0.4.7","published_at":"…","assets":{"macos-arm64":{"file":"leera-qa-runner-macos-arm64.tar.gz","sha256":"…","size":123}, …}}
+ */
+export const DEFAULT_UPDATE_BASE = 'https://github.com/leera-app/leera-qa-runner/releases';
+export const MANIFEST_FILE = 'releases.json';
+export const SIGNATURE_FILE = 'releases.json.sig';
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const FILE = /^leera-qa-runner-[a-z0-9]+-[a-z0-9]+\.(?:tar\.gz|zip)$/;
+/** Parses and validates a manifest; throws an Error naming what is wrong. */
+export function parseManifest(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`the release manifest is not JSON: ${error.message}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('the release manifest is not an object');
+    const raw = value;
+    const version = typeof raw.version === 'string' ? raw.version.replace(/^v/, '') : '';
+    if (!VERSION.test(version))
+        throw new Error(`the release manifest has an invalid version ${JSON.stringify(raw.version)}`);
+    if (!raw.assets || typeof raw.assets !== 'object' || Array.isArray(raw.assets))
+        throw new Error('the release manifest has no assets');
+    const assets = {};
+    for (const [key, entry] of Object.entries(raw.assets)) {
+        const asset = entry;
+        if (!asset || typeof asset.file !== 'string' || !FILE.test(asset.file)) {
+            throw new Error(`the release manifest asset ${key} has an invalid file name`);
+        }
+        if (typeof asset.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(asset.sha256)) {
+            throw new Error(`the release manifest asset ${key} has an invalid sha256`);
+        }
+        if (typeof asset.size !== 'number' || !Number.isInteger(asset.size) || asset.size <= 0) {
+            throw new Error(`the release manifest asset ${key} has an invalid size`);
+        }
+        assets[key] = { file: asset.file, sha256: asset.sha256, size: asset.size };
+    }
+    return { version, published_at: typeof raw.published_at === 'string' ? raw.published_at : '', assets };
+}
+/** `macos|windows|linux` for a Node platform, or null when there is no bundle for it. */
+export function bundleOs(platform) {
+    if (platform === 'darwin')
+        return 'macos';
+    if (platform === 'win32')
+        return 'windows';
+    if (platform === 'linux')
+        return 'linux';
+    return null;
+}
+/** The manifest key (`macos-arm64`) for this machine, or null when unsupported. */
+export function assetKey(platform, arch) {
+    const os = bundleOs(platform);
+    if (!os || (arch !== 'x64' && arch !== 'arm64'))
+        return null;
+    return `${os}-${arch}`;
+}
+/** The archive name a release publishes for a target. */
+export function archiveName(os, arch) {
+    return `leera-qa-runner-${os}-${arch}.${os === 'windows' ? 'zip' : 'tar.gz'}`;
+}
+/** `RUNNER_UPDATE_BASE`, else the GitHub releases page; no trailing slash. */
+export function updateBase(env) {
+    return (env.RUNNER_UPDATE_BASE?.trim() || DEFAULT_UPDATE_BASE).replace(/\/+$/, '');
+}
+/** Where a release's assets are downloaded from: `…/download/vX` or `…/latest/download`. */
+export function releaseDir(base, version) {
+    return version ? `${base}/download/v${version.replace(/^v/, '')}` : `${base}/latest/download`;
+}
+async function get(fetchImpl, url) {
+    return fetchImpl(url, { redirect: 'follow', signal: AbortSignal.timeout(60_000), headers: { 'user-agent': 'leera-qa-runner' } });
+}
+/** Downloads `releases.json` (and its signature when published) for a version, or the latest release. */
+export async function fetchManifest(base, version, fetchImpl = fetch) {
+    const dir = releaseDir(base, version);
+    const url = `${dir}/${MANIFEST_FILE}`;
+    const response = await get(fetchImpl, url);
+    if (!response.ok) {
+        throw new Error(response.status === 404 ? `no release manifest at ${url}${version ? ` (is ${version} a released version?)` : ''}` : `${url} answered HTTP ${response.status}`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const manifest = parseManifest(bytes.toString('utf8'));
+    let signature = null;
+    const sig = await get(fetchImpl, `${dir}/${SIGNATURE_FILE}`);
+    if (sig.ok)
+        signature = (await sig.text()).trim() || null;
+    else if (sig.status !== 404)
+        throw new Error(`${dir}/${SIGNATURE_FILE} answered HTTP ${sig.status}`);
+    return { manifest, bytes, signature, url };
+}

package/dist/src/update/verify.js

@@ -0,0 +1,65 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+/**
+ * Reads an Ed25519 public key: base64 SPKI DER (what `packaging/sign-manifest.mjs --public-key` prints),
+ * a PEM block, or a raw 32-byte key in base64.
+ */
+export function parsePublicKey(value) {
+    const text = value.trim();
+    if (text.startsWith('-----BEGIN'))
+        return checkEd25519(createPublicKey(text));
+    const der = Buffer.from(text, 'base64');
+    if (der.length === 32) {
+        // SubjectPublicKeyInfo prefix for Ed25519 (OID 1.3.101.112) followed by the raw key.
+        const prefix = Buffer.from('302a300506032b6570032100', 'hex');
+        return checkEd25519(createPublicKey({ key: Buffer.concat([prefix, der]), format: 'der', type: 'spki' }));
+    }
+    return checkEd25519(createPublicKey({ key: der, format: 'der', type: 'spki' }));
+}
+function checkEd25519(key) {
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error(`the release public key is ${key.asymmetricKeyType ?? 'unknown'}, not Ed25519`);
+    return key;
+}
+/** True when `signature` (base64) is a valid Ed25519 signature of `bytes` by `publicKey`. */
+export function verifySignature(bytes, signature, publicKey) {
+    const key = parsePublicKey(publicKey);
+    const sig = Buffer.from(signature.trim(), 'base64');
+    if (sig.length !== 64)
+        return false;
+    return verify(null, bytes, key, sig);
+}
+/**
+ * Applies the contract rule: with a `release_public_key` in build-info a valid signature is required;
+ * without one the manifest is trusted over HTTPS and a warning is returned.
+ */
+export function checkManifestTrust(bytes, signature, publicKey) {
+    if (publicKey?.trim()) {
+        if (!signature)
+            throw new Error('the release manifest is not signed, but this runner requires signed updates; refusing to update');
+        let valid;
+        try {
+            valid = verifySignature(bytes, signature, publicKey);
+        }
+        catch (error) {
+            throw new Error(`the release manifest signature could not be checked (${error.message}); refusing to update`);
+        }
+        if (!valid)
+            throw new Error('the release manifest signature is invalid; refusing to update');
+        return { signed: true };
+    }
+    return {
+        signed: false,
+        warning: 'this runner has no release public key: the download is checked against the manifest sha256 only (fetched over HTTPS), not a signature',
+    };
+}
+/** The sha256 (hex) of a file, streamed. */
+export function sha256File(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        createReadStream(path)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('error', reject)
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}