@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/tools/browser.js

@@ -17,13 +17,31 @@ async function bounded(promise, timeout = TIMEOUT) {
         clearTimeout(timer);
     }
 }
-/** All ancestors are checked: mkdir recursive must never follow a planted profile symlink. */
+/**
+ * All ancestors are checked: mkdir recursive must never follow a planted profile symlink. The one
+ * symlinks allowed across are root-owned system symlinks (`/var -> /private/var` on macOS): stock
+ * macOS tmp dirs sit behind one, and refusing it would reject every per-user tmpdir. A root-owned
+ * symlink whose target is a root-owned, non-group-writable directory is not plantable by the user
+ * this runs as; anything else — every user-owned symlink — still fails the check below.
+ */
 async function ownedDirectory(dir, privateMode = false) {
     const absolute = path.resolve(dir);
     const parts = absolute.split(path.sep).filter(Boolean);
     let current = path.parse(absolute).root;
     const uid = process.getuid?.();
     let protectedByOwner = false;
+    const systemSymlink = async (stat) => {
+        if (stat.uid !== 0 || uid === 0)
+            return false;
+        try {
+            const target = await fs.realpath(current);
+            const targetStat = await fs.lstat(target);
+            return targetStat.isDirectory() && targetStat.uid === 0 && (targetStat.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    };
     for (const part of parts) {
         current = path.join(current, part);
         await fs.mkdir(current, { mode: 0o700 }).catch((e) => {
@@ -31,8 +49,14 @@ async function ownedDirectory(dir, privateMode = false) {
                 throw e;
         });
         const stat = await fs.lstat(current);
+        if (stat.isSymbolicLink()) {
+            if (!(await systemSymlink(stat)))
+                throw Error("Unsafe browser directory");
+            // Root-owned system symlink: cross it; the link itself carries no mode or ownership
+            // expectation (Linux reports links 0777), its target was just verified.
+            continue;
+        }
         if (!stat.isDirectory() ||
-            stat.isSymbolicLink() ||
             (!protectedByOwner &&
                 (stat.mode & 0o022) !== 0 &&
                 !(stat.mode & 0o1000)) ||
@@ -44,11 +68,11 @@ async function ownedDirectory(dir, privateMode = false) {
         if (uid !== undefined && stat.uid === uid && (stat.mode & 0o077) === 0)
             protectedByOwner = true;
     }
-    const stat = await fs.lstat(absolute);
+    const stat = await fs.lstat(current);
     if (process.getuid && stat.uid !== process.getuid())
         throw Error("Browser directory is not owned by this user");
     if (privateMode)
-        await fs.chmod(absolute, 0o700);
+        await fs.chmod(current, 0o700);
 }
 function allowedUrl(params) {
     const url = string(params, "url", 8192, "about:blank");

package/dist/workstation/update/artifact.js

@@ -1,3 +1,4 @@
+import { deploymentDownloadURL } from '../control/serverIdentity.js';
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { createWriteStream, promises as fs } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -16,7 +17,7 @@ function safeRelease(release, server) {
     if ((configured.protocol !== 'http:' && configured.protocol !== 'https:') || configured.username || configured.password) {
         throw new Error('Configured server URL must be an HTTP(S) origin without credentials');
     }
-    const url = new URL(release.url, configured);
+    const url = new URL(deploymentDownloadURL(server, release.url));
     // The release descriptor arrives over the authenticated management connection, but keeping the
     // download on that exact origin prevents an injected relative/absolute URL from turning the
     // client into a credentialed downloader. HTTP remains supported for private-network development

package/dist/workstation/update/globalInstall.js

@@ -0,0 +1,116 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * `npm install --global <archive>` reinstalls an already-present package by renaming the old
+ * install directory aside ("retire") and extracting the new one in its place. On at least one
+ * observed host (a container whose target directory sits on the image's read-only layers, backed
+ * by `fuse-overlayfs`) that retire-then-extract sequence is unreliable: `npm`'s own tar/arborist
+ * step intermittently reports `TAR_ENTRY_ERROR EEXIST` on the package's top-level `package.json`,
+ * immediately followed by `ENOENT` when npm reads the same path back — on the *same* path, even
+ * starting from an empty directory, and reproducibly across repeated attempts. A plain `tar`
+ * extraction of the identical archive onto the identical path, and a non-global `npm install` run
+ * inside an already-extracted directory, both succeed every time: the bug is specific to npm's
+ * own global-package retire/link machinery, not to the archive, the dependencies, or the
+ * filesystem's ability to write there at all.
+ *
+ * This is therefore a fallback, not the primary path: it only runs after a real `npm install
+ * --global` attempt has already failed, and it reimplements only what that attempt was observably
+ * unable to do reliably --- replace the target directory's contents and its `bin` entry --- using
+ * the two operations proven to work. It intentionally does not run on Windows, where npm's global
+ * `bin` entries are shim files (`.cmd`/`.ps1`), not symlinks, and this path has no evidence either
+ * way.
+ */
+export async function attemptGlobalInstallFallback(npmPath, npmPrefix, archive, env, spawn = nodeSpawn) {
+    if (process.platform === 'win32')
+        throw new Error('No tested fallback for a global npm install on Windows');
+    const manifest = await readArchivePackageJson(archive, spawn);
+    const name = manifest.name;
+    if (typeof name !== 'string' || name.length === 0)
+        throw new Error('Archive package.json has no usable "name"');
+    const bin = manifest.bin;
+    const target = path.join(npmPrefix, 'lib/node_modules', name);
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.mkdir(target, { recursive: true });
+    await run(spawn, 'tar', ['-xzf', archive, '-C', target, '--strip-components=1'], {});
+    const installEnv = { ...process.env, ...env };
+    delete installEnv.NPM_CONFIG_PREFIX;
+    delete installEnv.npm_config_prefix;
+    await run(spawn, npmPath, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: target, env: installEnv });
+    await relinkBinaries(npmPrefix, target, name, bin);
+}
+async function readArchivePackageJson(archive, spawn) {
+    const raw = await capture(spawn, 'tar', ['-xzf', archive, '-O', 'package/package.json'], {});
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Archive package.json is not valid JSON');
+    }
+}
+/** Reproduces npm's own `bin` linking: a relative symlink from `<prefix>/bin/<name>` to the script. */
+async function relinkBinaries(npmPrefix, target, packageName, bin) {
+    const entries = binEntries(packageName, bin);
+    if (entries.length === 0)
+        return;
+    const binDir = path.join(npmPrefix, 'bin');
+    await fs.mkdir(binDir, { recursive: true });
+    for (const [command, relativeScript] of entries) {
+        const script = path.join(target, relativeScript);
+        const link = path.join(binDir, command);
+        await fs.rm(link, { force: true });
+        await fs.symlink(path.relative(binDir, script), link);
+        await fs.chmod(script, 0o755).catch(() => undefined);
+    }
+}
+/** Exported for direct unit testing; same resolution npm itself applies to a package.json `bin` field. */
+export function binEntries(packageName, bin) {
+    if (typeof bin === 'string') {
+        const short = packageName.startsWith('@') ? packageName.split('/')[1] ?? packageName : packageName;
+        return [[short, bin]];
+    }
+    if (bin && typeof bin === 'object') {
+        return Object.entries(bin).filter((entry) => typeof entry[1] === 'string');
+    }
+    return [];
+}
+function run(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}
+function capture(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}

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,33 +23,57 @@ 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. */
@@ -60,7 +86,7 @@ export class NpmInstaller {
             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/rdRollback.js

@@ -0,0 +1,145 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { assertLockOwnership, withPrivateLock } from '../control/locks.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { rdStateSchema } from '../rd/state.js';
+export function rdStateDigest(value) { return createHash('sha256').update(value).digest('hex'); }
+function snapshotPath(directory, commandId) { return path.join(directory, 'update', `rd-rollback-${rdStateDigest(commandId)}.json`); }
+export async function readPrivateRdFile(file, maxBytes = 131072) {
+    let handle;
+    try {
+        handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.uid !== process.getuid?.() || info.mode & 0o077 || info.size > maxBytes)
+            throw new Error('Unsafe RD rollback state');
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writePrivate(file, contents) {
+    await privateDirectory(path.dirname(file));
+    const staging = path.join(path.dirname(file), `.rd-rollback-${randomUUID()}`);
+    try {
+        await fs.writeFile(staging, contents, { mode: 0o600, flag: 'wx' });
+        assertLockOwnership();
+        await fs.rename(staging, file);
+    }
+    finally {
+        await fs.rm(staging, { force: true });
+    }
+}
+export async function snapshotRdForRollback(directory, command) {
+    return withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        const snapshot = snapshotPath(directory, command.commandId);
+        const value = { schemaVersion: 1, commandId: command.commandId, targetVersion: command.release.version,
+            releaseSha512: command.release.sha512, previous };
+        await writePrivate(snapshot, JSON.stringify(value));
+        return { directory, snapshot };
+    });
+}
+async function pendingUpdate(directory) {
+    const contents = await readPrivateRdFile(path.join(directory, 'update-state.json'));
+    return contents === null ? null : JSON.parse(contents);
+}
+export async function guardRdActivation(directory, cliVersion, next) {
+    const update = await pendingUpdate(directory);
+    if (!update || update.version !== cliVersion || !update.commandId)
+        return;
+    if (update.phase === 'ROLLED_BACK')
+        throw new Error('The CLI update was already rolled back before RD activation');
+    if (!update.releaseSha512)
+        return;
+    const planFile = path.join(directory, 'update', `watchdog-${rdStateDigest(update.commandId)}.json`);
+    const planContents = await readPrivateRdFile(planFile);
+    if (planContents === null)
+        return;
+    const plan = JSON.parse(planContents);
+    if (plan.commandId !== update.commandId || plan.targetVersion !== update.version)
+        throw new Error('RD watchdog plan does not match the pending CLI update');
+    const current = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (current === null)
+        throw new Error('RD state disappeared before activation');
+    const guard = { commandId: update.commandId, targetVersion: update.version, releaseSha512: update.releaseSha512, previousSha256: rdStateDigest(current) };
+    if (!plan.rdRollback)
+        return await authenticatedRdActivation(directory, guard) ? undefined : guard;
+    const expected = snapshotPath(directory, update.commandId);
+    if (plan.rdRollback.directory !== directory || plan.rdRollback.snapshot !== expected)
+        throw new Error('RD rollback snapshot path does not match this update');
+    const contents = await readPrivateRdFile(expected);
+    if (contents === null)
+        throw new Error('RD rollback snapshot is missing');
+    const saved = JSON.parse(contents);
+    if (saved.schemaVersion !== 1 || saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512)
+        throw new Error('RD rollback snapshot belongs to another CLI update');
+    const nextDigest = rdStateDigest(JSON.stringify(rdStateSchema.parse(next)));
+    if (saved.previous !== current && saved.activatedSha256 !== rdStateDigest(current))
+        return guard;
+    await writePrivate(expected, JSON.stringify({ ...saved, activatedSha256: nextDigest, activatedIdentity: undefined }));
+}
+async function stateIdentity(directory) {
+    const info = await fs.lstat(path.join(directory, 'rd', 'state.json'), { bigint: true });
+    return `${info.dev}:${info.ino}:${info.birthtimeNs}:${info.mtimeNs}`;
+}
+export async function completeRdActivation(directory, cliVersion) {
+    const update = await pendingUpdate(directory);
+    if (!update?.commandId || update.version !== cliVersion)
+        return;
+    const file = snapshotPath(directory, update.commandId);
+    const contents = await readPrivateRdFile(file);
+    if (contents === null)
+        return;
+    const saved = JSON.parse(contents);
+    if (saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512 || !saved.activatedSha256)
+        return;
+    const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+        return;
+    await writePrivate(file, JSON.stringify({ ...saved, activatedIdentity: await stateIdentity(directory) }));
+}
+export async function authenticatedRdActivation(directory, guard) {
+    const update = await pendingUpdate(directory);
+    if (update?.phase !== 'SUCCEEDED' || update.commandId !== guard.commandId || update.version !== guard.targetVersion || update.releaseSha512 !== guard.releaseSha512)
+        return false;
+    const contents = await readPrivateRdFile(path.join(directory, 'update', 'restart-ready.json'));
+    if (contents === null)
+        return false;
+    const marker = JSON.parse(contents);
+    return marker.commandId === guard.commandId && marker.version === guard.targetVersion && typeof marker.generation === 'string' && marker.generation.length > 0;
+}
+export async function restoreRdAfterRollback(reference, commandId, targetVersion) {
+    const directory = reference.directory;
+    if (reference.snapshot !== snapshotPath(directory, commandId))
+        throw new Error('RD rollback snapshot path does not match this update');
+    await withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const update = await pendingUpdate(directory);
+        if (update?.commandId !== commandId || update.version !== targetVersion)
+            return;
+        const contents = await readPrivateRdFile(reference.snapshot);
+        if (contents === null)
+            throw new Error('RD rollback snapshot is missing');
+        const saved = JSON.parse(contents);
+        if (saved.schemaVersion !== 1 || saved.commandId !== commandId || saved.targetVersion !== targetVersion || saved.releaseSha512 !== update.releaseSha512)
+            throw new Error('RD rollback snapshot belongs to another CLI update');
+        if (!saved.activatedSha256)
+            return;
+        const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+            return;
+        if (saved.activatedIdentity && await stateIdentity(directory) !== saved.activatedIdentity)
+            return;
+        if (saved.previous === null)
+            throw new Error('RD activation has no previous state to restore');
+        await writePrivate(path.join(directory, 'rd', 'state.json'), saved.previous);
+    });
+}

package/dist/workstation/update/runUpdate.js

@@ -124,7 +124,7 @@ export function lifecyclePolicy(lifecycle) {
 export function createUpdateCoordinator(deps) {
     const policy = lifecyclePolicy(deps.serviceLifecycle);
     const updateContext = updateServiceContext(deps.dir);
-    const npm = new NpmInstaller(updateContext);
+    const npm = new NpmInstaller({ ...updateContext, installationLockHeld: deps.installationLockHeld });
     // This cache also resumes the restart handshake after service supervision starts a new daemon.
     const releaseCache = new LastKnownGoodCache({
         ...updateContext, runningVersion: CLIENT_VERSION, pack: (root, destination) => npm.pack(root, destination),
@@ -180,7 +180,8 @@ export function createUpdateCoordinator(deps) {
             const log = openSync(`${deps.dir}/daemon.log`, 'a');
             let child;
             try {
-                child = spawn(process.execPath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                child = spawn(updateContext.nodePath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                    ...(updateContext.env ? { env: updateContext.env } : {}),
                     detached: true,
                     stdio: ['ignore', log, log],
                 });