@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/update/legacyBridge.js

@@ -0,0 +1,414 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import semver from 'semver';
+import { BindingStore } from '../control/bindingStore.js';
+import { inspectRuntime, inspectDeviceRuntime } from '../control/runtimeClient.js';
+import { normalizeWorkstationServer, workstationEndpoint } from '../control/serverIdentity.js';
+import { loadClientConfig, readKeys } from '../config.js';
+import yaml from 'js-yaml';
+import { captureStartupPackageEvidence } from './deviceHealth.js';
+import { runtimeFilesDigest } from './deviceHealthProtocol.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
+import { downloadVerified } from './artifact.js';
+import { readPrivateUpdateBytes, updateTransactionKey } from './recoveryPlan.js';
+import { writeDurablePrivateUpdate, syncPrivateRecoveryFile, ensureDurablePrivateDirectory } from './privateDurability.js';
+import { UpdateStateStore } from './stateStore.js';
+import { withPrivateLock, withWorkstationLock } from '../control/locks.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { LocalControlError } from '../control/protocol.js';
+import { pidAlive, processCommand } from '../keepers/kit/lock.js';
+import { launchWatchdogProcess } from './watchdogProcess.js';
+import { recoverAuthenticatedLegacyOwner } from './legacyOwner.js';
+const hash = (bytes) => createHash('sha512').update(bytes).digest('hex');
+const metadata = ['config.yml', 'client.key', 'server.pub', 'operation.json', 'binding-history.json', 'rd/state.json', 'desktop-provider.json', 'registrations.json', 'registration-tombstones.json', 'registrations.pending.json'];
+const planName = 'legacy-bridge.json';
+const legacyPlanSchema = z.object({ commandId: z.string().uuid(), targetVersion: z.string(), archive: z.string(), marker: z.string(), state: z.string(), npmPath: z.string(), npmPrefix: z.string(), cliPath: z.string() }).passthrough();
+const bridgeSchema = z.object({
+    schemaVersion: z.literal(3), lifecycle: z.enum(['managed', 'container']).default('managed'), root: z.string(), commandId: z.string().uuid(), version: z.string(), releaseSha512: z.string(),
+    predecessor: z.string(), server: z.string(), workstationId: z.string(), ownerUserId: z.string().nullable(),
+    runtimeDigest: z.string(), rollback: z.string(), rollbackSha512: z.string(), rollbackVersion: z.string(),
+    program: z.string(), context: z.object({ platform: z.enum(['linux', 'darwin']), username: z.string(), userId: z.number(), homeDir: z.string(), nodePath: z.string(), cliPath: z.string(), npmPath: z.string(), npmPrefix: z.string(), configDir: z.string(), pathEnv: z.string(), npmConfigPrefix: z.string().optional() }).passthrough(),
+    originals: z.record(z.string(), z.string()),
+});
+const bridgePath = (root) => path.join(root, 'update', planName);
+const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const migrationScope = new AsyncLocalStorage();
+export function withLegacyBridgeMigration(root, task) { return migrationScope.run(path.resolve(root), task); }
+export async function assertLegacyBridgeMutationAllowed(root, startup) {
+    const bridge = await readLegacyBridge(root, startup);
+    if (bridge && migrationScope.getStore() !== path.resolve(root) && !startup)
+        throw new LocalControlError('BUSY', 'The original legacy update still owns registration admission until recovery completes');
+}
+async function confirmedBridgeReady(plan) {
+    try {
+        const ready = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/legacy-bridge-ready.json'), 4096)).toString());
+        return ready.commandId === plan.commandId && ready.runtimeDigest === plan.runtimeDigest && typeof ready.generation === 'string' && ready.generation.length > 0 && ready.generation !== plan.predecessor;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function finalizeConfirmedBridge(plan) {
+    await new UpdateStateStore(plan.root).save({ phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 });
+    await fs.rename(bridgePath(plan.root), path.join(plan.root, 'update/legacy-bridge-completed.json'));
+}
+async function snapshotMetadata(root, name) {
+    if (name !== 'server.pub')
+        return readPrivateUpdateBytes(path.join(root, name), 1_048_576);
+    const handle = await fs.open(path.join(root, name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1_048_576 || stat.mode & 0o022 || process.getuid && stat.uid !== process.getuid())
+            throw Error('Unsafe legacy public key');
+        return handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function legacyDesktopContinuity(root) {
+    if (await readLegacyBridge(root))
+        return true;
+    try {
+        const plan = bridgeSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/legacy-bridge-completed.json'), 8_388_608)).toString()));
+        return plan.root === path.resolve(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function assertLegacyBridgeTransferred(plan) {
+    const marker = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/restart-ready.json'), 4096)).toString());
+    if (marker.commandId !== plan.commandId || marker.version !== plan.version || typeof marker.generation !== 'string' || !marker.generation.startsWith('legacy-bridge:'))
+        throw Error('Legacy watchdog recovery ownership has not transferred');
+    if ((await fs.readdir(path.join(plan.root, 'update'))).some(name => /^watchdog-.*\.json$/.test(name)))
+        throw Error('Legacy watchdog plans have not been archived after recovery transfer');
+}
+export async function readLegacyBridge(root, startup) {
+    let bytes;
+    try {
+        bytes = await readPrivateUpdateBytes(bridgePath(root), 8_388_608);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const plan = bridgeSchema.parse(JSON.parse(bytes.toString()));
+    if (plan.root !== path.resolve(root) || plan.context.configDir !== plan.root || plan.rollback !== path.join(root, 'update', `legacy-rollback-${updateTransactionKey(plan.commandId)}.tgz`) || plan.program !== path.join(root, 'update', `legacy-bridge-${updateTransactionKey(plan.commandId)}.mjs`))
+        throw Error('Legacy update bridge paths changed');
+    if (startup && (startup.version !== plan.version || startup.runtimeDigest !== plan.runtimeDigest))
+        throw Error('Legacy update bridge installed target inventory changed');
+    if (Object.keys(plan.originals).some(name => !metadata.includes(name)))
+        throw Error('Legacy update bridge metadata scope changed');
+    return plan;
+}
+/** The predecessor already authenticated this release; bind its private update receipt and plan
+ * to the actual installed bytes before replacing its format1-only rollback authority. */
+export async function prepareLegacyBridge(root, context, options = {}) {
+    root = path.resolve(root);
+    const installedVersion = JSON.parse(await fs.readFile(path.join(path.dirname(path.dirname(context.cliPath)), 'package.json'), 'utf8')).version;
+    const predecessor = await inspectRuntime(root);
+    const identity = await new BindingStore(root).inspect();
+    if (identity.identityState !== 'ready' || !identity.binding)
+        throw Error('The original legacy workstation owner must confirm the update');
+    if (options.container ? predecessor.state !== 'stopped' : predecessor.state !== 'running' || !predecessor.generation || !predecessor.binding || normalizeWorkstationServer(predecessor.binding.server) !== normalizeWorkstationServer(identity.binding.server) || predecessor.binding.workstationId !== identity.binding.workstationId)
+        throw Error('The original legacy workstation owner must confirm the update');
+    for (const name of ['device.json', 'legacy-migration.json', 'registrations', 'registrations.json', 'registration-tombstones.json', 'registrations.pending.json']) {
+        try {
+            await fs.lstat(path.join(root, name));
+            throw Error('Legacy bridge requires the original unmigrated root');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString());
+    if (state.phase !== 'RESTARTING' || state.version !== installedVersion || typeof state.releaseSha512 !== 'string')
+        throw Error('Legacy automatic migration requires the exact restarting release receipt');
+    const update = path.join(root, 'update');
+    const oldPlanPath = path.join(update, `watchdog-${updateTransactionKey(state.commandId)}.json`);
+    let old;
+    if (options.container) {
+        try {
+            await fs.lstat(oldPlanPath);
+            throw Error('Container update unexpectedly has an active service watchdog');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        old = { commandId: state.commandId, targetVersion: state.version, archive: path.join(update, 'last-known-good/last-known-good.tgz'), marker: path.join(update, 'restart-ready.json'), state: path.join(root, 'update-state.json'), npmPath: context.npmPath, npmPrefix: context.npmPrefix, cliPath: context.cliPath };
+    }
+    else
+        old = legacyPlanSchema.parse(JSON.parse((await readPrivateUpdateBytes(oldPlanPath, 1_048_576)).toString()));
+    if (old.commandId !== state.commandId || old.targetVersion !== state.version || old.cliPath !== context.cliPath || old.npmPath !== context.npmPath || old.npmPrefix !== context.npmPrefix || old.archive !== path.join(update, 'last-known-good/last-known-good.tgz') || old.marker !== path.join(update, 'restart-ready.json') || old.state !== path.join(root, 'update-state.json'))
+        throw Error('Legacy watchdog does not identify the exact predecessor update');
+    const config = await loadClientConfig(root);
+    const fetchImpl = options.fetch ?? fetch;
+    const response = await fetchImpl(workstationEndpoint(config.server, '/download/client/manifest.json'), { redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw Error('Cannot confirm the original release manifest');
+    const descriptor = z.object({ version: z.string(), url: z.string(), size: z.number().int().positive(), sha512: z.string().regex(/^[a-f0-9]{128}$/) });
+    const release = descriptor.extend({ legacyBridgeRollback: descriptor.optional() }).parse(await response.json());
+    if (release.version !== state.version || release.sha512 !== state.releaseSha512)
+        throw Error('The original authenticated legacy release changed');
+    const artifact = await downloadVerified(release, { server: config.server, fetch: fetchImpl });
+    let runtimeDigest;
+    try {
+        const archive = await readArchiveEvidence(artifact.path);
+        const startup = await captureStartupPackageEvidence(path.dirname(path.dirname(context.cliPath)), installedVersion);
+        runtimeDigest = runtimeFilesDigest(archive.runtimeFiles);
+        if (startup.runtimeDigest !== runtimeDigest)
+            throw Error('Installed legacy update differs from the authenticated target archive');
+    }
+    finally {
+        await artifact.cleanup();
+    }
+    try {
+        await fs.access(old.archive);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || !options.container || !release.legacyBridgeRollback)
+            throw Error('Legacy container rollback archive is unavailable; publish a verified legacyBridgeRollback descriptor');
+        const fallback = await downloadVerified(release.legacyBridgeRollback, { server: config.server, fetch: fetchImpl });
+        try {
+            await ensureDurablePrivateDirectory(path.join(update, 'last-known-good'));
+            await fs.copyFile(fallback.path, old.archive);
+            await fs.chmod(old.archive, 0o600);
+            await syncPrivateRecoveryFile(old.archive);
+            await writeDurablePrivateUpdate(path.join(update, 'last-known-good/last-known-good.json'), JSON.stringify({ name: '@platless/axom-cli', version: release.legacyBridgeRollback.version, sha512: release.legacyBridgeRollback.sha512 }));
+        }
+        finally {
+            await fallback.cleanup();
+        }
+    }
+    const rollbackBytes = await fs.readFile(old.archive);
+    const rollbackMetadata = JSON.parse((await promisify(execFile)('/usr/bin/tar', ['-xOf', old.archive, 'package/package.json'], { maxBuffer: 1_048_576 })).stdout);
+    if (rollbackMetadata.name !== '@platless/axom-cli' || !semver.valid(rollbackMetadata.version) || !semver.lt(rollbackMetadata.version, installedVersion) || rollbackMetadata.axomWorkstationRootReader?.rootFormat === 2)
+        throw Error('Legacy rollback package must identify the original earlier format1 CLI');
+    const cached = JSON.parse((await readPrivateUpdateBytes(path.join(update, 'last-known-good/last-known-good.json'), 65536)).toString());
+    if (cached.name !== rollbackMetadata.name || cached.version !== rollbackMetadata.version || cached.sha512 !== hash(rollbackBytes))
+        throw Error('Original last-known-good rollback digest changed');
+    const originals = {};
+    for (const name of metadata)
+        try {
+            originals[name] = (await snapshotMetadata(root, name)).toString('base64');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    const key = updateTransactionKey(state.commandId);
+    const plan = { schemaVersion: 3, lifecycle: options.container ? 'container' : 'managed', root, commandId: state.commandId, version: state.version, releaseSha512: state.releaseSha512, predecessor: predecessor.generation ?? `stopped-container:${state.commandId}`, server: config.server, workstationId: identity.binding.workstationId, ownerUserId: identity.binding.ownerUserId ?? null, runtimeDigest, rollback: path.join(update, `legacy-rollback-${key}.tgz`), rollbackSha512: hash(rollbackBytes), rollbackVersion: rollbackMetadata.version, program: path.join(update, `legacy-bridge-${key}.mjs`), context: { ...context }, originals };
+    await fs.writeFile(plan.rollback, rollbackBytes, { mode: 0o600, flag: 'wx' });
+    await syncPrivateRecoveryFile(plan.rollback);
+    await fs.copyFile(options.programSource ?? path.join(path.dirname(fileURLToPath(import.meta.url)), 'watchdog.js'), plan.program);
+    await fs.chmod(plan.program, 0o700);
+    await syncPrivateRecoveryFile(plan.program);
+    await writeDurablePrivateUpdate(bridgePath(root), JSON.stringify(plan));
+    await (options.arm ?? armLegacyBridge)(plan);
+    // This marker transfers rollback responsibility, not update success. Public state remains
+    // RESTARTING until an authenticated, initialized migrated successor confirms it below.
+    await writeDurablePrivateUpdate(old.marker, JSON.stringify({ commandId: plan.commandId, version: plan.version, generation: `legacy-bridge:${randomUUID()}`, readyAt: new Date().toISOString() }));
+    const history = path.join(update, 'legacy-watchdog-history');
+    await ensureDurablePrivateDirectory(history);
+    for (const name of await fs.readdir(update))
+        if (/^watchdog-.*\.json$/.test(name))
+            await fs.rename(path.join(update, name), path.join(history, name));
+    const current = await inspectRuntime(root);
+    if (options.container ? current.state !== 'stopped' : current.state !== 'running' || current.generation !== plan.predecessor)
+        throw Error('The original legacy updater changed before service handoff');
+    if (!plan.ownerUserId) {
+        // Recovery is already frozen and independently armed before any network/account recovery.
+        const owner = await (options.ownerLookup ?? recoverAuthenticatedLegacyOwner)({ server: config.server, workstationId: config.workstationId, ...await readKeys(root), version: plan.rollbackVersion, update: { ...state, remoteForcePolicy: 'drain-only' } });
+        if (!owner.trim() || owner.length > 1024 || /[\u0000-\u001f\u007f]/.test(owner))
+            throw Error('Authenticated legacy owner is invalid');
+        await withWorkstationLock(root, 'operation', async () => {
+            const bytes = await snapshotMetadata(root, 'config.yml');
+            if (bytes.toString('base64') !== plan.originals['config.yml'])
+                throw Error('Legacy configuration changed during owner verification');
+            const configuration = yaml.load(bytes.toString());
+            await writeDurablePrivateUpdate(path.join(root, 'config.yml'), yaml.dump({ ...configuration, ownerUserId: owner }));
+            plan.ownerUserId = owner;
+            await writeDurablePrivateUpdate(bridgePath(root), JSON.stringify(plan));
+        });
+    }
+    return plan;
+}
+async function armLegacyBridge(plan) {
+    const managedLinux = plan.lifecycle === 'managed' && plan.context.platform === 'linux';
+    if (!managedLinux)
+        try {
+            const previous = JSON.parse((await readPrivateUpdateBytes(path.join(plan.root, 'update/legacy-bridge-armed.json'), 4096)).toString());
+            if (previous.commandId === plan.commandId && pidAlive(previous.pid) && (await processCommand(previous.pid))?.includes(plan.program))
+                return;
+        }
+        catch { }
+    const logPath = path.join(plan.root, 'update/legacy-bridge.log'), log = await fs.open(logPath, 'a', 0o600);
+    let owner;
+    try {
+        owner = await launchWatchdogProcess({ nodePath: plan.context.nodePath, program: plan.program, plan: bridgePath(plan.root), lifecycle: managedLinux ? 'managed' : plan.lifecycle === 'container' ? 'container' : 'foreground', logPath }, { platform: plan.context.platform, spawn: (exe, args, options) => spawn(exe, args, { ...options, stdio: ['ignore', log.fd, log.fd] }) });
+    }
+    finally {
+        await log.close();
+    }
+    const armed = path.join(plan.root, 'update/legacy-bridge-armed.json');
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        try {
+            const acknowledgement = JSON.parse((await readPrivateUpdateBytes(armed, 4096)).toString());
+            if (acknowledgement.commandId === plan.commandId && acknowledgement.pid === owner.pid)
+                return;
+        }
+        catch { }
+        if (!pidAlive(owner.pid))
+            break;
+        await wait(50);
+    }
+    throw Error('Independent legacy bridge watchdog did not acknowledge recovery ownership: ' + (await fs.readFile(logPath, 'utf8')).slice(-2000));
+}
+export async function resumeLegacyManagedBridge(root, startup, options = {}) {
+    const plan = await readLegacyBridge(root, startup);
+    if (plan?.lifecycle === 'managed')
+        await (options.arm ?? armLegacyBridge)(plan);
+}
+/** Container updates replace npm then exit directly, without invoking workstation install. */
+export async function prepareLegacyContainerBridge(root, context, options = {}) {
+    const existing = await readLegacyBridge(root);
+    if (existing) {
+        if (existing.lifecycle !== 'container')
+            throw Error('Container successor cannot adopt an OS service update');
+        await (options.arm ?? armLegacyBridge)(existing);
+        return existing;
+    }
+    try {
+        await fs.lstat(path.join(root, 'device.json'));
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let state;
+    try {
+        state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString());
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (state.phase !== 'RESTARTING')
+        return;
+    return prepareLegacyBridge(root, context, { ...options, container: true });
+}
+/** Keep the original command and drain-only policy visible through recovery completion. */
+export async function legacyBridgeUpdateSnapshot(root) {
+    try {
+        await fs.lstat(path.join(root, 'update/device-transaction.json'));
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let plan = await readLegacyBridge(root);
+    if (!plan)
+        try {
+            plan = bridgeSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/legacy-bridge-completed.json'), 8_388_608)).toString()));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    const state = await new UpdateStateStore(root).load();
+    return { ...(state?.commandId === plan.commandId ? state : { phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 }), remoteForcePolicy: 'drain-only' };
+}
+/** A failed container startup keeps its process alive until the independent bundle has restored
+ * both root metadata and npm. Only then may the external supervisor restart the process. */
+export async function recoverLegacyContainer(plan) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(plan.context.nodePath, [plan.program, bridgePath(plan.root), '--rollback-now'], { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', code => code === 0 ? resolve() : reject(Error(`Independent container rollback failed (${code})`)));
+    });
+}
+export async function legacyBridgeReady(root, startup, generation) {
+    const plan = await readLegacyBridge(root, startup);
+    if (!plan)
+        return true;
+    const inspection = await inspectDeviceRuntime(root);
+    const registration = inspection.registrations.find(entry => entry.workstationId === plan.workstationId && entry.ownerUserId === plan.ownerUserId && normalizeWorkstationServer(entry.server) === normalizeWorkstationServer(plan.server));
+    return inspection.runtime.generation === generation && generation !== plan.predecessor && !!registration && registration.connection === 'online' && registration.identityState === 'ready';
+}
+export async function completeLegacyBridge(root, startup, generation) {
+    await withPrivateLock(path.join(root, 'update/legacy-bridge-recovery'), async () => {
+        const plan = await readLegacyBridge(root, startup);
+        if (!plan)
+            return;
+        if (!await legacyBridgeReady(root, startup, generation))
+            throw Error('Original migrated successor readiness changed before recovery completion');
+        await writeDurablePrivateUpdate(path.join(root, 'update/legacy-bridge-ready.json'), JSON.stringify({ commandId: plan.commandId, generation, runtimeDigest: startup.runtimeDigest }));
+        await new UpdateStateStore(root).save({ phase: 'SUCCEEDED', commandId: plan.commandId, version: plan.version, releaseSha512: plan.releaseSha512 });
+        // The daemon can finish recovery after an OS reboot even when the original copied watcher
+        // no longer exists. This uses the same lock as the watcher's last rollback decision.
+        await fs.rename(bridgePath(root), path.join(root, 'update/legacy-bridge-completed.json'));
+    });
+}
+export async function releaseLegacyBridge(root, startup, generation, release) {
+    if (!await legacyBridgeReady(root, startup, generation))
+        return false;
+    await release(() => completeLegacyBridge(root, startup, generation));
+    return true;
+}
+export async function runLegacyBridge(plan, deps) {
+    await writeDurablePrivateUpdate(path.join(plan.root, 'update/legacy-bridge-armed.json'), JSON.stringify({ commandId: plan.commandId, pid: process.pid }));
+    const now = deps.now ?? Date.now, pause = deps.wait ?? wait, deadline = now() + (deps.timeoutMs ?? 120_000);
+    while (now() < deadline) {
+        if (!await readLegacyBridge(plan.root))
+            return;
+        if (await confirmedBridgeReady(plan)) {
+            await withPrivateLock(path.join(plan.root, 'update/legacy-bridge-recovery'), async () => { if (await readLegacyBridge(plan.root) && await confirmedBridgeReady(plan))
+                await finalizeConfirmedBridge(plan); });
+            return;
+        }
+        await pause(250);
+    }
+    await withPrivateLock(path.join(plan.root, 'update/legacy-bridge-recovery'), async () => {
+        if (!await readLegacyBridge(plan.root))
+            return;
+        // Readiness can arrive during the final sleep, or before a rollback-now recovery invocation.
+        if (await confirmedBridgeReady(plan)) {
+            await finalizeConfirmedBridge(plan);
+            return;
+        }
+        // Stop only the daemon/service; keeper namespaces and their journals remain untouched.
+        await deps.stop();
+        if (hash(await fs.readFile(plan.rollback)) !== plan.rollbackSha512)
+            throw Error('Frozen legacy rollback archive changed');
+        for (const name of ['device.json', 'legacy-migration.json', 'registrations'])
+            await fs.rm(path.join(plan.root, name), { recursive: true, force: true });
+        for (const name of metadata) {
+            if (plan.originals[name])
+                await writeDurablePrivateUpdate(path.join(plan.root, name), Buffer.from(plan.originals[name], 'base64').toString());
+            else
+                await fs.rm(path.join(plan.root, name), { force: true });
+        }
+        await deps.install(plan.rollback);
+        await new UpdateStateStore(plan.root).save({ phase: 'ROLLED_BACK', commandId: plan.commandId, version: plan.version, error: 'Automatic legacy migration did not confirm authenticated successor readiness; restored the original CLI and registration' });
+        await fs.rename(bridgePath(plan.root), path.join(plan.root, 'update/legacy-bridge-rolled-back.json'));
+        await deps.restart();
+    });
+}

package/dist/workstation/update/legacyOwner.js

@@ -0,0 +1,39 @@
+import os from 'node:os';
+import { deriveSessionKey, randomBytes } from '../crypto.js';
+import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
+import { workstationChannelUrl } from '../channels/url.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_VERSION } from '../protocol/management.js';
+import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
+/** Resolve missing legacy ownership only after proving possession of the existing workstation key
+ * to its pinned Server key. The plaintext nonce challenge can never supply account identity. */
+export async function recoverAuthenticatedLegacyOwner(options) {
+    const abort = new AbortController(), timer = setTimeout(() => abort.abort(), options.timeoutMs ?? 15_000), nonce = randomBytes(16);
+    let challenge;
+    const protocols = { MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION }, COMPUTER: { min: 1, max: 6 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION } };
+    const heartbeat = (seq, sentAtEpochMs) => ({ t: 'heartbeat', seq, sentAtEpochMs, clientVersion: options.version, channels: { MANAGEMENT: 'CONNECTING', COMPUTER: 'DISCONNECTED', AGENT: 'DISCONNECTED' }, activeShellTasks: 0, activeAgentTasks: 0, update: { ...options.update, remoteForcePolicy: 'drain-only' } });
+    let channel;
+    try {
+        channel = await connectEncryptedChannel({ url: workstationChannelUrl(options.server, 'management'), signal: abort.signal, openTimeoutMs: options.timeoutMs ?? 15_000, encode: encodeManagementFrame, decode: decodeManagementFrame, decodeBytes: decodeManagementFrame, heartbeat, initialFrame: () => heartbeat(0, Date.now()), isHeartbeatAck: (frame, seq) => frame.t === 'heartbeat_ack' && frame.seq === seq, handshake: async (wire) => {
+                wire.sendText(encodeManagementFrame({ t: 'management_hello', workstationId: options.workstationId, workstation: os.hostname(), clientNonce: nonce.toString('base64'), clientVersion: options.version, clientPackage: '@platless/axom-cli', protocols }));
+                const response = await wire.receive();
+                if (response.isBinary)
+                    throw Error('Expected management nonce challenge');
+                const welcome = JSON.parse(response.data.toString());
+                if (welcome.t !== 'welcome' || typeof welcome.serverNonce !== 'string' || Buffer.from(welcome.serverNonce, 'base64').length !== 16)
+                    throw Error('Server did not authenticate this workstation identity');
+                challenge = welcome.serverNonce;
+                return deriveSessionKey(options.clientKey, options.serverPub, nonce, Buffer.from(challenge, 'base64'));
+            } });
+        for await (const frame of channel.messages)
+            if (frame.t === 'management_ready') {
+                if (frame.serverNonce !== challenge || !frame.generation || typeof frame.ownerUserId !== 'string' || !frame.ownerUserId.trim() || frame.ownerUserId.length > 1024 || /[\u0000-\u001f\u007f]/.test(frame.ownerUserId))
+                    throw Error('Authenticated Server did not supply the legacy workstation owner; a compatible Server is required');
+                return frame.ownerUserId;
+            }
+        throw Error('Authenticated management connection closed before owner verification');
+    }
+    finally {
+        clearTimeout(timer);
+        channel?.close();
+    }
+}

package/dist/workstation/update/npmInstaller.js

@@ -1,6 +1,8 @@
+import { withWorkstationLock } from '../control/locks.js';
 import { spawn as nodeSpawn } from 'node:child_process';
 import { redactPaths, redactSecrets } from './redact.js';
 import { verifyOptionalPty } from './watchdog.js';
+import { attemptGlobalInstallFallback } from './globalInstall.js';
 const STDERR_LIMIT = 4096;
 function absolute(value, field) {
     if (!value.startsWith('/') || /[\u0000-\u001f\u007f]/.test(value))
@@ -21,46 +23,70 @@ export class NpmInstaller {
         this.spawn = options.spawn ?? nodeSpawn;
     }
     async install(archive) {
+        if (this.options.configDir && !this.options.installationLockHeld)
+            return withWorkstationLock(this.options.configDir, 'installation', () => this.installUnlocked(archive));
+        return this.installUnlocked(archive);
+    }
+    async installUnlocked(archive) {
         absolute(archive, 'archive');
-        // No `--prefix`: npm installs into its own configured global prefix, which is what puts `axom`
-        // on the user's PATH. Forcing a private prefix put the binary somewhere nothing looks, so every
-        // machine needed a hand-made symlink that nothing in this package created or documented.
-        // `npmPrefix` survives for the writability pre-check, the service definition, and rollback —
-        // it is derived from where this package actually sits, so it still names npm's real prefix.
+        // Pin the already selected installation, including ordinary global npm installs.
+        const env = { ...process.env, ...this.options.env, NPM_CONFIG_PREFIX: this.options.npmPrefix };
+        delete env.npm_config_prefix;
         const args = ['install', '--global', archive, '--ignore-scripts', '--no-audit', '--no-fund'];
-        await new Promise((resolve, reject) => {
-            let stderr = '';
-            let child;
+        try {
+            await new Promise((resolve, reject) => {
+                let stderr = '';
+                let child;
+                try {
+                    child = this.spawn(this.options.npmPath, args, { env, shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+                }
+                catch (error) {
+                    reject(new Error(`npm install could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
+                    return;
+                }
+                child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
+                    stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
+                child.once('error', (error) => reject(new Error(`npm install could not start: ${sanitizeNpmError(error.message)}`)));
+                child.once('close', (code, signal) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
+                });
+            });
+        }
+        catch (primaryError) {
+            // `npm install --global` reinstalling an already-present package renames the old install
+            // directory aside and extracts the new one in its place; that sequence has been observed to
+            // fail unreliably on at least one host/filesystem combination even from an empty target (see
+            // globalInstall.ts). The fallback reproduces only the two operations proven to work there. A
+            // fallback failure surfaces the *original* error: it is the one a real npm bug report needs.
+            //
+            // Both console lines below are the only record of how often this fallback actually fires
+            // fleet-wide — there is no telemetry channel for "the primary path failed but we recovered",
+            // and a daemon's own stdout/stderr is already collected wherever this process's logs are.
+            console.warn(`npm install --global failed, attempting the tar/local-install fallback: ${sanitizeNpmError(primaryError instanceof Error ? primaryError.message : String(primaryError))}`);
             try {
-                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+                await attemptGlobalInstallFallback(this.options.npmPath, this.options.npmPrefix, archive, this.options.env, this.spawn);
             }
-            catch (error) {
-                reject(new Error(`npm install could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
-                return;
+            catch {
+                throw primaryError;
             }
-            child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
-                stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
-            child.once('error', (error) => reject(new Error(`npm install could not start: ${sanitizeNpmError(error.message)}`)));
-            child.once('close', (code, signal) => {
-                if (code === 0)
-                    resolve();
-                else
-                    reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
-            });
-        });
+            console.warn('npm install --global fallback succeeded; the global reinstall step is unreliable on this host and should be investigated');
+        }
         await verifyOptionalPty(this.options.npmPrefix, this.spawn);
     }
-    /** Packs the installed package locally; `--json` gives npm's own name/version validation input. */
+    /** Snapshots installed files, without rerunning source-only lifecycle/build scripts. */
     async pack(packageRoot, destination) {
         absolute(packageRoot, 'packageRoot');
         absolute(destination, 'destination');
-        const args = ['pack', packageRoot, '--pack-destination', destination, '--json'];
+        const args = ['pack', packageRoot, '--pack-destination', destination, '--json', '--ignore-scripts'];
         return new Promise((resolve, reject) => {
             let stdout = '';
             let stderr = '';
             let child;
             try {
-                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+                child = this.spawn(this.options.npmPath, args, { ...(this.options.env ? { env: this.options.env } : {}), shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
             }
             catch (error) {
                 reject(new Error(`npm pack could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));

package/dist/workstation/update/privateDurability.js

@@ -0,0 +1,61 @@
+import { constants, promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+async function syncDirectory(directory) {
+    const handle = await fs.open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        if (!(await handle.stat()).isDirectory())
+            throw Error('Private recovery namespace is not a directory');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function ensureDurablePrivateDirectory(directory) {
+    try {
+        await fs.mkdir(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+        throw Error('Unsafe private recovery evidence directory');
+    await syncDirectory(directory);
+    await syncDirectory(path.dirname(directory));
+}
+export async function syncPrivateRecoveryFile(file) {
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+            throw Error('Unsafe private recovery dependency');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectory(path.dirname(file));
+}
+export async function writeDurablePrivateUpdate(file, contents) {
+    const directory = path.dirname(file);
+    await ensureDurablePrivateDirectory(directory);
+    const temporary = path.join(directory, `.private-update-${randomUUID()}`);
+    try {
+        const handle = await fs.open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(contents);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+        await syncDirectory(directory);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}