@skrr-ai/cli 0.1.94 → 0.1.96

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/firstPartyHarnessUpdater.js

@@ -0,0 +1,923 @@
+/**
+ * One signed engine installation transaction for CLI, Daemon and Desktop.
+ * Releases contain both executable and provenance; replacing `current` is the
+ * only activation operation. Existing sessions keep their immutable executable.
+ * The signing identity is independent of the daemon release identity.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { FIRST_PARTY_HARNESS, FIRST_PARTY_HARNESS_ENV, firstPartyHarnessArtifactSpellings, firstPartyHarnessBinaryName, readFirstPartyHarnessEnv, } from './firstPartyHarness.js';
+import { FIRST_PARTY_HARNESS_PREVIOUS_SUFFIX, FIRST_PARTY_HARNESS_PROVENANCE_SUFFIX, firstPartyHarnessBinDir, firstPartyHarnessHomeDir, firstPartyHarnessInstalledBinaryPath, migrateFirstPartyHarnessHome, } from './firstPartyHarnessHome.js';
+import { FIRST_PARTY_HARNESS_CHANNELS, firstPartyHarnessFeedCandidates, resolveChannelManifestUrl, resolveFirstPartyHarnessChannel, } from './firstPartyHarnessChannels.js';
+import { verifyArtifact, verifyManifest, } from './releaseManifest.js';
+import { FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS } from './firstPartyHarnessReleaseKeys.js';
+import { compareReleaseVersions } from './releaseVersions.js';
+import { assessReleasePolicy, verifyReleasePolicy, } from './releasePolicy.js';
+export { FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS } from './firstPartyHarnessReleaseKeys.js';
+export { firstPartyHarnessFeedBase, firstPartyHarnessFeedCandidates, } from './firstPartyHarnessChannels.js';
+export { firstPartyHarnessManifestFile } from './firstPartyHarness.js';
+export const PREVIOUS_SUFFIX = FIRST_PARTY_HARNESS_PREVIOUS_SUFFIX;
+export const PROVENANCE_SUFFIX = FIRST_PARTY_HARNESS_PROVENANCE_SUFFIX;
+export const MAX_ARTIFACT_BYTES = 400 * 1024 * 1024;
+const MANIFEST_FETCH_TIMEOUT_MS = 30_000;
+const ARTIFACT_FETCH_TIMEOUT_MS = 10 * 60_000;
+const LOCK_STALE_MS = 120_000;
+function fail(code, error) {
+    return { ok: false, code, error };
+}
+function fetchSignal(options, timeout) {
+    return options.signal
+        ? AbortSignal.any([options.signal, AbortSignal.timeout(timeout)])
+        : AbortSignal.timeout(timeout);
+}
+export function firstPartyHarnessInstallDir(env = process.env) {
+    return firstPartyHarnessBinDir(env);
+}
+export function firstPartyHarnessBinaryPath(env = process.env) {
+    return firstPartyHarnessInstalledBinaryPath(env);
+}
+export function firstPartyHarnessPlatformKey(platform = process.platform, arch = process.arch) {
+    const cpu = arch === 'arm64' || arch === 'aarch64'
+        ? 'arm64'
+        : arch === 'x64' || arch === 'x86_64'
+            ? 'x64'
+            : null;
+    if (!cpu ||
+        !['darwin', 'linux', 'win32'].includes(platform) ||
+        (platform === 'win32' && cpu !== 'x64'))
+        return null;
+    return `${platform}-${cpu}`;
+}
+export async function fetchVerifiedManifest(options = {}) {
+    const env = options.env ?? process.env;
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const rawFetch = options.fetchImpl ?? globalThis.fetch;
+    if (options.version && compareReleaseVersions(options.version, options.version) === null)
+        return fail('version-invalid', 'requested version is not a semantic release version');
+    if (!keys || keys.length === 0) {
+        // See the header: unlike the daemon's self-update, an unverifiable harness
+        // is refused rather than installed. Provisioning the keypair must never be
+        // the thing that REDUCES what the daemon accepts.
+        return fail('no-pinned-keys', `no pinned ${FIRST_PARTY_HARNESS.displayName} release keys — refusing to install`);
+    }
+    if (typeof rawFetch !== 'function') {
+        return fail('feed-unreachable', 'no fetch implementation available');
+    }
+    // A host the egress policy blocks must say so, not read as a certificate
+    // error (OSK-11947; see fetch-failure.ts).
+    const doFetch = rawFetch;
+    // WL-6.6 — the channel decides WHICH signed manifest, and nothing else.
+    //
+    // `latest/` was the only path this installer could read, which left the
+    // channel prefixes provisioned in terraform unreachable by any client. The
+    // channel is resolved here and nowhere else: artifact urls come from INSIDE
+    // the manifest and are never rewritten, because a channel in an artifact url
+    // would enter the signed message and turn every promotion into a re-signing
+    // ceremony.
+    //
+    // An unrecognised channel resolves to `stable` and reports rather than
+    // throwing. A typo must not leave a machine unable to install anything —
+    // that turns a harmless mistake into the outage this installer exists to
+    // avoid.
+    const { channel, invalid, source } = resolveFirstPartyHarnessChannel(env);
+    if (invalid) {
+        options.onProgress?.(`unknown update channel ${JSON.stringify(invalid)} in ${source ?? FIRST_PARTY_HARNESS_ENV.channel.name}; ` +
+            `using ${channel}. Valid: ${FIRST_PARTY_HARNESS_CHANNELS.join(', ')}.`);
+    }
+    // Every place the manifest may be published, canonical spelling first.
+    //
+    // Which spellings depends on what is read. A CHANNEL pointer is current state,
+    // so only the accepted spellings are tried: a former spelling's pointer stopped
+    // moving when publishing stopped writing it, and falling back to one would
+    // install whatever it named on the day of contract. A PINNED release is an
+    // immutable artifact, so former spellings are tried too: a release published
+    // before the canonical prefix existed lives only under the old one, with the
+    // same signed bytes it would have anywhere.
+    //
+    // Move to the next candidate ONLY when this one is not there. A candidate that
+    // answers with a manifest ends the search, whatever that manifest turns out to
+    // be: falling through on a malformed or badly signed canonical manifest would
+    // let anyone who can make the canonical object fail verification steer the
+    // install onto an older spelling's feed — a downgrade by denial.
+    //
+    // "Not there" is 403 as well as 404. A prefix with no manifest answers 403 (the
+    // bucket denies ListBucket, so a missing key cannot be reported as 404).
+    const notFound = [];
+    let body;
+    for (const candidate of firstPartyHarnessFeedCandidates(env, {
+        pinnedRelease: Boolean(options.version),
+    })) {
+        const url = resolveChannelManifestUrl({
+            base: candidate.base,
+            manifestFilename: candidate.manifestFilename,
+            channel,
+            pinnedVersion: options.version ?? null,
+        });
+        try {
+            const res = await doFetch(url, {
+                signal: fetchSignal(options, options.manifestTimeoutMs ?? MANIFEST_FETCH_TIMEOUT_MS),
+                redirect: 'follow',
+            });
+            if (res.status === 403 || res.status === 404) {
+                notFound.push(`HTTP ${res.status} for ${url}`);
+                continue;
+            }
+            if (!res.ok) {
+                return fail('feed-unreachable', `manifest fetch failed: HTTP ${res.status} for ${url}`);
+            }
+            body = await res.text();
+            break;
+        }
+        catch (err) {
+            return fail('feed-unreachable', `manifest fetch failed: ${err.message}`);
+        }
+    }
+    if (body === undefined) {
+        // Name the CHANNEL when the object simply is not there anywhere.
+        //
+        // A 403 reads as "you are not allowed" — the one thing it does not mean,
+        // since this feed is public. A user on the default channel with nothing
+        // published yet would otherwise see a permissions error for a
+        // release-management state, and go looking at their credentials. A PINNED
+        // version keeps the raw failure: `releases/<v>/` missing means that exact
+        // release does not exist, and a channel setting has nothing to do with it.
+        const tried = notFound.join('; ');
+        if (!options.version) {
+            return fail('feed-unreachable', `no ${FIRST_PARTY_HARNESS.displayName} release published on the '${channel}' channel (${tried}). ` +
+                `Set ${FIRST_PARTY_HARNESS_ENV.channel.name} to a channel that has one, or pin a version.`);
+        }
+        return fail('feed-unreachable', `manifest fetch failed: ${tried}`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(body);
+    }
+    catch (err) {
+        return fail('manifest-malformed', `manifest is not JSON: ${err.message}`);
+    }
+    if (!manifest ||
+        typeof manifest.version !== 'string' ||
+        !manifest.platforms ||
+        typeof manifest.platforms !== 'object' ||
+        Array.isArray(manifest.platforms) ||
+        compareReleaseVersions(manifest.version, manifest.version) === null) {
+        return fail('manifest-malformed', 'manifest is missing version or platforms');
+    }
+    const verdict = verifyManifest(manifest, keys);
+    if (!('ok' in verdict) || verdict.ok !== true) {
+        const reason = 'reason' in verdict ? verdict.reason : 'verification disabled';
+        return fail('manifest-unverified', `manifest signature rejected: ${reason}`);
+    }
+    if (options.version && manifest.version !== options.version) {
+        return fail('manifest-malformed', 'pinned manifest version does not match requested version');
+    }
+    if (compareReleaseVersions(manifest.minimum, manifest.version) === null ||
+        compareReleaseVersions(manifest.minimum, manifest.version) > 0) {
+        return fail('manifest-malformed', 'manifest minimum is invalid or newer than its release');
+    }
+    try {
+        const policy = validateEnginePolicy(manifest, options);
+        if (policy)
+            return policy;
+    }
+    catch (error) {
+        return fail('policy-rejected', `engine release policy is malformed: ${describe(error)}`);
+    }
+    return { ok: true, manifest };
+}
+/** A present policy must explicitly describe this component, never the daemon. */
+function validateEnginePolicy(manifest, options) {
+    if (!manifest.policy)
+        return null;
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const policy = manifest.policy;
+    const verdict = verifyReleasePolicy(policy, keys);
+    if (!('ok' in verdict) || !verdict.ok)
+        return fail('policy-rejected', 'engine release policy signature/shape rejected');
+    const component = [FIRST_PARTY_HARNESS.provider, 'firstPartyHarness'].find((name) => policy.components[name]);
+    if (!component)
+        return fail('policy-rejected', 'release policy has no first-party engine component');
+    const assessment = assessReleasePolicy({
+        policy,
+        targetDaemonVersion: manifest.version,
+        targetComponent: component,
+        channel: resolveFirstPartyHarnessChannel(options.env).channel,
+        contracts: options.contracts ?? {},
+        cohortSubject: options.cohortSubject ?? '',
+        autonomous: options.autonomous === true,
+        now: options.now,
+    });
+    if (!assessment.valid || !assessment.eligible)
+        return fail('policy-rejected', assessment.reason ?? 'engine release is not eligible for this policy');
+    const minimum = policy.components[component].minimumVersion;
+    if (minimum &&
+        (compareReleaseVersions(manifest.version, minimum) === null ||
+            compareReleaseVersions(manifest.version, minimum) < 0))
+        return fail('minimum-version', 'engine release is below its signed policy minimum');
+    return null;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function paths(env) {
+    const home = firstPartyHarnessHomeDir(env);
+    return {
+        home,
+        releases: path.join(home, 'releases'),
+        current: path.join(home, 'current'),
+        previous: path.join(home, 'previous'),
+        state: path.join(home, 'update-state.json'),
+        floor: path.join(home, 'minimum-manifest.json'),
+        lock: path.join(path.dirname(home), `.${FIRST_PARTY_HARNESS.provider}-update`),
+    };
+}
+function prepareLock(env) {
+    const target = paths(env).lock;
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, '', { flag: 'a', mode: 0o600 });
+    return target;
+}
+function atomicJson(file, data) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const staging = `${file}.tmp-${randomUUID()}`;
+    try {
+        writeFileSync(staging, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+        renameSync(staging, file);
+    }
+    finally {
+        rmSync(staging, { force: true });
+    }
+}
+function atomicLink(target, link) {
+    const staging = `${link}.tmp-${randomUUID()}`;
+    try {
+        symlinkSync(target, staging);
+        renameSync(staging, link);
+    }
+    finally {
+        rmSync(staging, { force: true });
+    }
+}
+function readLink(file) {
+    try {
+        return readlinkSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+function hasEntry(file) {
+    try {
+        lstatSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isManagedFirstPartyHarnessReleasePath(binaryPath, env = process.env) {
+    const canonical = firstPartyHarnessBinaryPath(env);
+    return (path.resolve(binaryPath) === path.resolve(canonical) &&
+        readLink(canonical) === `../current/${path.basename(canonical)}`);
+}
+/** Read a single immutable binary/sidecar pair, never two different `current` targets. */
+export function getVerifiedInstalledFirstPartyHarness(options = {}) {
+    const canonical = firstPartyHarnessBinaryPath(options.env);
+    return inspectBinary(canonical, options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS, firstPartyHarnessPlatformKey(options.platform, options.arch));
+}
+function inspectBinary(binaryPath, keys, expectedPlatform = firstPartyHarnessPlatformKey()) {
+    const result = {
+        binaryPath,
+        version: null,
+        verified: false,
+        exists: existsSync(binaryPath),
+        provenance: null,
+    };
+    if (!result.exists || !keys.length)
+        return result;
+    try {
+        const resolved = realpathSync(binaryPath);
+        const size = statSync(resolved).size;
+        if (size > MAX_ARTIFACT_BYTES)
+            return result;
+        const record = JSON.parse(readFileSync(resolved + PROVENANCE_SUFFIX, 'utf8'));
+        if (!record ||
+            compareReleaseVersions(record.version, record.version) === null ||
+            typeof record.platform !== 'string' ||
+            typeof record.sha256 !== 'string' ||
+            typeof record.url !== 'string' ||
+            typeof record.sig !== 'string')
+            return result;
+        record.sha256 = record.sha256.toLowerCase();
+        result.provenance = record;
+        if (record.platform !== expectedPlatform)
+            return result;
+        const verdict = verifyArtifact(record.platform, record.version, { ...record, file: path.basename(binaryPath), size }, keys);
+        if (!('ok' in verdict) ||
+            !verdict.ok ||
+            createHash('sha256').update(readFileSync(resolved)).digest('hex') !==
+                record.sha256.toLowerCase())
+            return result;
+        result.version = record.version;
+        result.verified = true;
+    }
+    catch {
+        /* absent/malformed/tampered provenance is not a version authority */
+    }
+    return result;
+}
+export function readFirstPartyHarnessUpdateState(env = process.env) {
+    try {
+        const value = JSON.parse(readFileSync(paths(env).state, 'utf8'));
+        if (!value ||
+            !['install', 'rollback'].includes(value.operation) ||
+            !['running', 'succeeded', 'failed'].includes(value.status) ||
+            !Number.isFinite(value.attemptedAt))
+            return null;
+        // A killed updater cannot finalize its durable running record. Diagnose it
+        // without writing during a status/check command; live lock heartbeats keep
+        // long downloads distinguishable from interrupted transactions.
+        if (value.status === 'running' &&
+            !lockfile.checkSync(paths(env).lock, { realpath: false, stale: LOCK_STALE_MS })) {
+            return {
+                ...value,
+                status: 'failed',
+                code: 'install-failed',
+                error: 'The previous update was interrupted. Run `skrr code update` to retry.',
+            };
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function finishState(env, operation, attemptedAt, result, targetVersion, keys = FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS) {
+    atomicJson(paths(env).state, {
+        operation,
+        status: result.ok ? 'succeeded' : 'failed',
+        attemptedAt,
+        completedAt: Date.now(),
+        targetVersion,
+        installedVersion: result.version ?? getVerifiedInstalledFirstPartyHarness({ env, keys }).version ?? undefined,
+        code: result.code,
+        error: result.error,
+        changed: result.changed,
+    });
+}
+function retainedManifest(env, keys) {
+    try {
+        const manifest = JSON.parse(readFileSync(paths(env).floor, 'utf8'));
+        const verdict = verifyManifest(manifest, keys);
+        if (!('ok' in verdict) ||
+            !verdict.ok ||
+            compareReleaseVersions(manifest.minimum, manifest.version) === null ||
+            compareReleaseVersions(manifest.minimum, manifest.version) > 0)
+            throw new Error('retained minimum manifest is invalid; refusing to discard the signed floor');
+        return manifest;
+    }
+    catch (error) {
+        if (hasEntry(paths(env).floor))
+            throw error;
+        return null;
+    }
+}
+function effectiveMinimum(manifest, keys) {
+    let minimum = manifest.minimum;
+    if (manifest.policy) {
+        const policy = manifest.policy;
+        const verdict = verifyReleasePolicy(policy, keys);
+        if (!('ok' in verdict) || !verdict.ok)
+            throw new Error('retained signed policy is invalid');
+        const component = [FIRST_PARTY_HARNESS.provider, 'firstPartyHarness'].find((name) => policy.components[name]);
+        const floor = component ? policy.components[component].minimumVersion : undefined;
+        if (floor && compareReleaseVersions(floor, minimum) === null)
+            throw new Error('signed policy minimum is invalid');
+        if (floor && compareReleaseVersions(floor, minimum) === 1)
+            minimum = floor;
+    }
+    return minimum;
+}
+function retainedMinimum(env, keys) {
+    const manifest = retainedManifest(env, keys);
+    return manifest ? effectiveMinimum(manifest, keys) : null;
+}
+function preserveMinimum(env, keys, manifest) {
+    if (!manifest)
+        return;
+    const previous = retainedManifest(env, keys);
+    if (!previous ||
+        compareReleaseVersions(effectiveMinimum(manifest, keys), effectiveMinimum(previous, keys)) === 1)
+        atomicJson(paths(env).floor, manifest);
+}
+function createAliases(env) {
+    const canonical = firstPartyHarnessBinaryPath(env);
+    for (const spelling of firstPartyHarnessArtifactSpellings()) {
+        const alias = path.join(path.dirname(canonical), firstPartyHarnessBinaryName(spelling));
+        if (alias === canonical)
+            continue;
+        for (const suffix of [PROVENANCE_SUFFIX, '']) {
+            if (!hasEntry(alias + suffix)) {
+                try {
+                    symlinkSync(path.basename(canonical) + suffix, alias + suffix);
+                }
+                catch {
+                    /* compatibility aliases must not invalidate an activated release */
+                }
+            }
+        }
+    }
+}
+function stableLinks(env) {
+    const binary = firstPartyHarnessBinaryPath(env);
+    mkdirSync(path.dirname(binary), { recursive: true, mode: 0o700 });
+    for (const suffix of [PROVENANCE_SUFFIX, '']) {
+        const target = `../current/${path.basename(binary)}${suffix}`;
+        if (readLink(binary + suffix) !== target)
+            atomicLink(target, binary + suffix);
+    }
+    if (hasEntry(paths(env).previous)) {
+        for (const suffix of [PROVENANCE_SUFFIX, '']) {
+            const target = `../previous/${path.basename(binary)}${suffix}`;
+            if (readLink(binary + PREVIOUS_SUFFIX + suffix) !== target)
+                atomicLink(target, binary + PREVIOUS_SUFFIX + suffix);
+        }
+    }
+    createAliases(env);
+}
+function migrateFlatLayout(env, _progress) {
+    const p = paths(env);
+    const binary = firstPartyHarnessBinaryPath(env);
+    mkdirSync(p.releases, { recursive: true, mode: 0o700 });
+    if (isManagedFirstPartyHarnessReleasePath(binary, env) || !existsSync(binary))
+        return;
+    // Adopt flat bytes without pretending an unsigned legacy binary is trusted.
+    // Copies leave the original runnable throughout the one-time layout change.
+    const dir = path.join(p.releases, `legacy-${randomUUID()}`);
+    mkdirSync(dir, { mode: 0o700 });
+    const adopted = path.join(dir, path.basename(binary));
+    copyFileSync(binary, adopted);
+    chmodSync(adopted, 0o555);
+    if (existsSync(binary + PROVENANCE_SUFFIX)) {
+        copyFileSync(binary + PROVENANCE_SUFFIX, adopted + PROVENANCE_SUFFIX);
+        chmodSync(adopted + PROVENANCE_SUFFIX, 0o444);
+    }
+    chmodSync(dir, 0o700);
+    const outgoing = readLink(p.current);
+    if (outgoing)
+        atomicLink(outgoing, p.previous);
+    atomicLink(path.relative(p.home, dir), p.current);
+    stableLinks(env);
+}
+function validateArtifact(options) {
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const record = options.provenance;
+    if (!record ||
+        typeof record !== 'object' ||
+        typeof record.version !== 'string' ||
+        typeof record.platform !== 'string' ||
+        typeof record.sha256 !== 'string' ||
+        !/^[a-fA-F0-9]{64}$/.test(record.sha256) ||
+        typeof record.url !== 'string' ||
+        typeof record.sig !== 'string' ||
+        !Buffer.isBuffer(options.binary))
+        return fail('artifact-unverified', 'artifact provenance is malformed');
+    if (!keys.length)
+        return fail('no-pinned-keys', 'no pinned engine release keys; refusing activation');
+    if (compareReleaseVersions(record.version, record.version) === null)
+        return fail('version-invalid', 'artifact version is not a semantic release version');
+    if (record.platform !== firstPartyHarnessPlatformKey(options.platform, options.arch))
+        return fail('unsupported-platform', `artifact ${record.platform} does not match this host`);
+    if ((options.platform ?? process.platform) === 'win32')
+        return fail('unsupported-platform', 'managed engine release activation currently requires macOS or Linux');
+    const verdict = verifyArtifact(record.platform, record.version, {
+        ...record,
+        file: firstPartyHarnessBinaryName(),
+        size: options.binary.length,
+    }, keys);
+    if (!('ok' in verdict) || !verdict.ok)
+        return fail('artifact-unverified', 'artifact provenance signature rejected');
+    if (options.binary.length > MAX_ARTIFACT_BYTES)
+        return fail('too-large', 'artifact exceeds the download ceiling');
+    if (createHash('sha256').update(options.binary).digest('hex') !== record.sha256.toLowerCase())
+        return fail('hash-mismatch', 'artifact bytes do not match signed provenance');
+    if (options.manifest) {
+        const policyFailure = validateEnginePolicy(options.manifest, options);
+        if (policyFailure)
+            return policyFailure;
+        const manifestVerdict = verifyManifest(options.manifest, keys);
+        const artifact = options.manifest.platforms?.[record.platform];
+        if (!('ok' in manifestVerdict) ||
+            !manifestVerdict.ok ||
+            options.manifest.version !== record.version ||
+            artifact?.sha256?.toLowerCase() !== record.sha256.toLowerCase() ||
+            compareReleaseVersions(options.manifest.minimum, record.version) === null)
+            return fail('manifest-unverified', 'activation manifest does not authenticate this artifact');
+    }
+    return null;
+}
+function activateLocked(options) {
+    const env = options.env ?? process.env;
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const progress = options.onProgress ?? (() => { });
+    const p = paths(env);
+    const binary = firstPartyHarnessBinaryPath(env);
+    const canonicalLink = readLink(binary);
+    // Older spelling links are migration inputs; arbitrary symlinks belong to
+    // an external install and are never followed for writes.
+    const legacyLinks = firstPartyHarnessArtifactSpellings().map((spelling) => firstPartyHarnessBinaryName(spelling));
+    if (canonicalLink &&
+        !isManagedFirstPartyHarnessReleasePath(binary, env) &&
+        !legacyLinks.includes(canonicalLink)) {
+        return options.preserveExternalLink
+            ? {
+                ok: true,
+                changed: false,
+                binaryPath: binary,
+                reason: 'canonical engine is an externally owned symlink',
+            }
+            : fail('install-failed', 'managed engine path is an external symlink; update its owning installation');
+    }
+    if (options.preserveExternalLink && !hasEntry(binary)) {
+        for (const spelling of firstPartyHarnessArtifactSpellings()) {
+            const alias = path.join(path.dirname(binary), firstPartyHarnessBinaryName(spelling));
+            const aliasLink = readLink(alias);
+            if (aliasLink && aliasLink !== path.basename(binary))
+                return {
+                    ok: true,
+                    changed: false,
+                    binaryPath: binary,
+                    reason: `legacy engine at ${alias} is an externally owned symlink`,
+                };
+        }
+    }
+    const migration = migrateFirstPartyHarnessHome({ env });
+    for (const change of migration.moved)
+        progress(`engine home migration: ${change}`);
+    for (const error of migration.errors)
+        progress(`engine home migration: ${error}`);
+    const installed = getVerifiedInstalledFirstPartyHarness({
+        env,
+        keys,
+        platform: options.platform,
+        arch: options.arch,
+    });
+    const record = { ...options.provenance, sha256: options.provenance.sha256.toLowerCase() };
+    const floor = retainedMinimum(env, keys);
+    if (floor && compareReleaseVersions(record.version, floor) < 0)
+        return fail('minimum-version', `release ${record.version} is below the retained signed minimum ${floor}`);
+    if (options.manifest && compareReleaseVersions(record.version, options.manifest.minimum) < 0)
+        return fail('minimum-version', 'release is below its signed minimum');
+    if (installed.exists && !installed.verified && options.preserveUnknownInstalled)
+        return {
+            ok: true,
+            changed: false,
+            binaryPath: binary,
+            reason: 'installed engine has no verified provenance',
+        };
+    if (installed.version) {
+        const comparison = compareReleaseVersions(record.version, installed.version);
+        if (comparison === 0 && installed.provenance?.sha256 !== record.sha256)
+            return fail('manifest-malformed', 'release version is immutable but signed artifact digest changed');
+        if (comparison === 0 || (comparison < 0 && !options.allowDowngrade)) {
+            preserveMinimum(env, keys, options.manifest);
+            return {
+                ok: true,
+                changed: false,
+                replaced: true,
+                version: installed.version,
+                platform: installed.provenance?.platform,
+                binaryPath: binary,
+            };
+        }
+    }
+    migrateFlatLayout(env, progress);
+    const slot = path.join(p.releases, `${record.version}-${record.sha256.toLowerCase()}`);
+    const slotBinary = path.join(slot, path.basename(binary));
+    if (hasEntry(slot)) {
+        if (lstatSync(slot).isSymbolicLink())
+            return fail('install-failed', 'release directory must be locally owned, not a symlink');
+        const existing = inspectBinary(slotBinary, keys, firstPartyHarnessPlatformKey(options.platform, options.arch));
+        if (!existing.verified || existing.provenance?.sha256 !== record.sha256)
+            return fail('install-failed', 'immutable release directory already exists with invalid bytes');
+    }
+    else {
+        const staging = path.join(p.releases, `.staging-${randomUUID()}`);
+        mkdirSync(staging, { mode: 0o700 });
+        try {
+            writeFileSync(path.join(staging, path.basename(binary)), options.binary, { mode: 0o755 });
+            writeFileSync(path.join(staging, path.basename(binary) + PROVENANCE_SUFFIX), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+            chmodSync(path.join(staging, path.basename(binary)), 0o555);
+            chmodSync(path.join(staging, path.basename(binary) + PROVENANCE_SUFFIX), 0o444);
+            chmodSync(staging, 0o700);
+            renameSync(staging, slot);
+        }
+        finally {
+            if (hasEntry(staging)) {
+                chmodSync(staging, 0o700);
+                rmSync(staging, { recursive: true, force: true });
+            }
+        }
+    }
+    const previous = readLink(p.current);
+    const target = path.relative(p.home, slot);
+    if (previous && previous !== target)
+        atomicLink(previous, p.previous);
+    // Prepare the stable entry points while the original release still runs.
+    // Subsequent installations only change this ONE pointer.
+    stableLinks(env);
+    preserveMinimum(env, keys, options.manifest);
+    atomicLink(target, p.current);
+    progress(`${FIRST_PARTY_HARNESS.displayName} ${record.version} installed; existing sessions keep their current release.`);
+    return {
+        ok: true,
+        changed: true,
+        replaced: installed.exists,
+        version: record.version,
+        platform: record.platform,
+        binaryPath: binary,
+    };
+}
+/** Desktop's already-downloaded signed artifact uses the exact same transaction. */
+export function activateVerifiedFirstPartyHarnessArtifact(options) {
+    const invalid = validateArtifact(options);
+    const env = options.env ?? process.env;
+    const attemptedAt = Date.now();
+    let release;
+    try {
+        release = lockfile.lockSync(prepareLock(env), { realpath: false, stale: LOCK_STALE_MS });
+        const result = invalid ?? activateLocked(options);
+        finishState(env, 'install', attemptedAt, result, options.provenance?.version, options.keys);
+        return result;
+    }
+    catch (error) {
+        const result = fail(error.code === 'ELOCKED' ? 'lock-busy' : 'install-failed', describe(error));
+        if (release) {
+            try {
+                finishState(env, 'install', attemptedAt, result, options.provenance?.version, options.keys);
+            }
+            catch {
+                // Preserve the activation failure if its diagnostic journal is also unwritable.
+            }
+        }
+        return result;
+    }
+    finally {
+        release?.();
+    }
+}
+/** Signed-manifest check reads only; no lock, migration, state writes or login. */
+export async function checkFirstPartyHarnessUpdate(options = {}) {
+    const fetched = await fetchVerifiedManifest(options);
+    if (!fetched.ok)
+        return fetched;
+    const env = options.env ?? process.env;
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const platform = firstPartyHarnessPlatformKey(options.platform, options.arch);
+    if (!platform || (options.platform ?? process.platform) === 'win32')
+        return fail('unsupported-platform', 'this host has no managed engine artifact');
+    const artifact = fetched.manifest.platforms[platform];
+    if (!artifact)
+        return fail('artifact-missing', `release has no ${platform} artifact`);
+    const verdict = verifyArtifact(platform, fetched.manifest.version, artifact, keys);
+    if (!('ok' in verdict) || !verdict.ok)
+        return fail('artifact-unverified', 'offered artifact signature rejected');
+    let minimum = effectiveMinimum(fetched.manifest, keys);
+    try {
+        const floor = retainedMinimum(env, keys);
+        if (floor && compareReleaseVersions(fetched.manifest.version, floor) < 0)
+            return fail('minimum-version', 'offered release is below the retained signed minimum');
+        if (floor && compareReleaseVersions(floor, minimum) === 1)
+            minimum = floor;
+    }
+    catch (error) {
+        return fail('minimum-version', describe(error));
+    }
+    const installed = getVerifiedInstalledFirstPartyHarness(options);
+    if (installed.version === fetched.manifest.version &&
+        installed.provenance?.sha256 !== artifact.sha256.toLowerCase())
+        return fail('manifest-malformed', 'same release version offers a different signed artifact digest');
+    const override = readFirstPartyHarnessEnv(env, 'path').value;
+    return {
+        ok: true,
+        installedVersion: installed.version,
+        latestVersion: fetched.manifest.version,
+        channel: resolveFirstPartyHarnessChannel(env).channel,
+        updateAvailable: !installed.version ||
+            compareReleaseVersions(installed.version, fetched.manifest.version) === -1,
+        binaryPath: installed.binaryPath,
+        owner: override && path.resolve(override) !== path.resolve(installed.binaryPath)
+            ? 'external'
+            : 'managed',
+        installedVerified: installed.verified,
+        minimumVersion: minimum,
+        lastUpdate: readFirstPartyHarnessUpdateState(env),
+    };
+}
+export async function installFirstPartyHarness(options = {}) {
+    const env = options.env ?? process.env;
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const progress = options.onProgress ?? (() => { });
+    const platform = firstPartyHarnessPlatformKey(options.platform, options.arch);
+    if (!platform || (options.platform ?? process.platform) === 'win32')
+        return fail('unsupported-platform', 'no managed engine activation for this platform');
+    if (options.version && compareReleaseVersions(options.version, options.version) === null)
+        return fail('version-invalid', 'requested version is not a semantic release version');
+    if (options.allowDowngrade && !options.version)
+        return fail('downgrade-refused', 'a downgrade requires an explicit pinned version');
+    const attemptedAt = Date.now();
+    let release;
+    let result;
+    try {
+        release = await lockfile.lock(prepareLock(env), {
+            realpath: false,
+            stale: LOCK_STALE_MS,
+            update: 10_000,
+            retries: { retries: 20, minTimeout: 100, maxTimeout: 500, factor: 1.2 },
+        });
+        atomicJson(paths(env).state, {
+            operation: 'install',
+            status: 'running',
+            attemptedAt,
+            targetVersion: options.version,
+        });
+        result = await downloadAndActivate();
+        finishState(env, 'install', attemptedAt, result, result.version ?? options.version, keys);
+        return result;
+    }
+    catch (error) {
+        result = fail(error.code === 'ELOCKED' ? 'lock-busy' : 'install-failed', describe(error));
+        if (release) {
+            try {
+                finishState(env, 'install', attemptedAt, result, options.version, keys);
+            }
+            catch {
+                /* preserve original error */
+            }
+        }
+        return result;
+    }
+    finally {
+        await release?.();
+    }
+    async function downloadAndActivate() {
+        progress('Fetching signed release manifest…');
+        const fetched = await fetchVerifiedManifest(options);
+        if (!fetched.ok)
+            return fetched;
+        const { manifest } = fetched;
+        const artifact = manifest.platforms[platform];
+        if (!artifact)
+            return fail('artifact-missing', `release ${manifest.version} has no ${platform} artifact`);
+        const verdict = verifyArtifact(platform, manifest.version, artifact, keys);
+        if (!('ok' in verdict) || !verdict.ok)
+            return fail('artifact-unverified', 'artifact signature rejected');
+        if (typeof artifact.size === 'number' && artifact.size > MAX_ARTIFACT_BYTES)
+            return fail('too-large', 'artifact declares bytes above the ceiling');
+        const installed = getVerifiedInstalledFirstPartyHarness({
+            env,
+            keys,
+            platform: options.platform,
+            arch: options.arch,
+        });
+        const floor = retainedMinimum(env, keys);
+        if (floor && compareReleaseVersions(manifest.version, floor) < 0)
+            return fail('minimum-version', `offered release is below the retained signed minimum ${floor}`);
+        if (installed.version &&
+            compareReleaseVersions(manifest.version, installed.version) < 0 &&
+            !options.allowDowngrade) {
+            return fail('downgrade-refused', `offered ${manifest.version} is older than installed ${installed.version}; pin a version and use --allow-downgrade for recovery`);
+        }
+        if (installed.version === manifest.version) {
+            if (installed.provenance?.sha256 !== artifact.sha256.toLowerCase())
+                return fail('manifest-malformed', 'same release version offers a different signed artifact digest');
+            preserveMinimum(env, keys, manifest);
+            return {
+                ok: true,
+                changed: false,
+                version: installed.version,
+                binaryPath: installed.binaryPath,
+                platform: installed.provenance?.platform,
+                replaced: true,
+            };
+        }
+        progress(`Downloading ${FIRST_PARTY_HARNESS.displayName} ${manifest.version} (${platform})…`);
+        let binary;
+        try {
+            const response = await (options.fetchImpl ?? globalThis.fetch)(artifact.url, {
+                signal: fetchSignal(options, ARTIFACT_FETCH_TIMEOUT_MS),
+                redirect: 'follow',
+            });
+            if (!response.ok)
+                return fail('download-failed', `HTTP ${response.status} for ${artifact.url}`);
+            const contentLength = Number(response.headers.get('content-length'));
+            if (Number.isFinite(contentLength) && contentLength > MAX_ARTIFACT_BYTES)
+                return fail('too-large', 'response declares bytes above the ceiling');
+            const chunks = [];
+            let size = 0;
+            if (!response.body)
+                return fail('download-failed', 'artifact response has no body');
+            const reader = response.body.getReader();
+            try {
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    size += part.value.byteLength;
+                    if (size > MAX_ARTIFACT_BYTES) {
+                        await reader.cancel();
+                        return fail('too-large', 'download exceeds the ceiling');
+                    }
+                    chunks.push(part.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            binary = Buffer.concat(chunks, size);
+        }
+        catch (error) {
+            return fail('download-failed', `download failed: ${describe(error)}`);
+        }
+        const provenance = {
+            version: manifest.version,
+            platform: platform,
+            sha256: artifact.sha256.toLowerCase(),
+            url: artifact.url,
+            sig: artifact.sig,
+            ...(artifact.sigs ? { sigs: artifact.sigs } : {}),
+            ...(manifest.keyId ? { keyId: manifest.keyId } : {}),
+        };
+        const activation = { ...options, binary, provenance, manifest };
+        const invalid = validateArtifact(activation);
+        return invalid ?? activateLocked(activation);
+    }
+}
+/** Rollback validates the retained immutable release and preserves its signature. */
+export function rollbackFirstPartyHarness(env = process.env, options = {}) {
+    const keys = options.keys ?? FIRST_PARTY_HARNESS_RELEASE_PUBLIC_KEYS;
+    const p = paths(env);
+    const attemptedAt = Date.now();
+    let release;
+    try {
+        release = lockfile.lockSync(prepareLock(env), { realpath: false, stale: LOCK_STALE_MS });
+        const result = performRollback();
+        finishState(env, 'rollback', attemptedAt, result, result.version, keys);
+        return result;
+    }
+    catch (error) {
+        const result = fail(error.code === 'ELOCKED' ? 'lock-busy' : 'install-failed', `rollback failed: ${describe(error)}`);
+        if (release) {
+            try {
+                finishState(env, 'rollback', attemptedAt, result, undefined, keys);
+            }
+            catch {
+                // Preserve the rollback failure if its diagnostic journal is also unwritable.
+            }
+        }
+        return result;
+    }
+    finally {
+        release?.();
+    }
+    function performRollback() {
+        if (!isManagedFirstPartyHarnessReleasePath(firstPartyHarnessBinaryPath(env), env))
+            return fail('install-failed', 'active engine is outside the managed release store; install an explicitly pinned signed release before rolling back');
+        const previous = readLink(p.previous);
+        const current = readLink(p.current);
+        if (!previous ||
+            !current ||
+            !previous.startsWith('releases/') ||
+            path.resolve(p.home, previous).startsWith(p.releases + path.sep) === false)
+            return fail('install-failed', 'no managed previous release to roll back to');
+        const restored = inspectBinary(path.join(p.home, previous, path.basename(firstPartyHarnessBinaryPath(env))), keys);
+        if (!restored.verified || !restored.version)
+            return fail('artifact-unverified', 'previous release provenance is missing or invalid; install an explicitly pinned signed release for recovery');
+        const floor = retainedMinimum(env, keys);
+        if (floor && compareReleaseVersions(restored.version, floor) < 0)
+            return fail('minimum-version', `previous release is below the retained signed minimum ${floor}`);
+        // Preserve the outgoing target only after activation. A crash between these
+        // operations still leaves `current` on a complete verified release.
+        atomicLink(previous, p.current);
+        atomicLink(current, p.previous);
+        stableLinks(env);
+        return {
+            ok: true,
+            changed: true,
+            replaced: true,
+            binaryPath: firstPartyHarnessBinaryPath(env),
+            version: restored.version,
+            platform: restored.provenance?.platform,
+        };
+    }
+}
+export function installedFirstPartyHarnessSize(env = process.env) {
+    try {
+        return statSync(firstPartyHarnessBinaryPath(env)).size;
+    }
+    catch {
+        return null;
+    }
+}