@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/acp/managedPatches.js

@@ -1,11 +1,16 @@
-/** Automatic adapter patches, owned by Axom, never written into npm's shared cache. */
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+/**
+ * Automatic adapter patches, owned by Axom, applied only at **install** time to a copy of the
+ * daemon-owned pristine tree (spec §6.2/§3.3). The pristine tree is never patched in place, and
+ * nothing here ever runs at launch except {@link verifyPatchedFiles}, the tamper check.
+ */
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { cp, lstat, mkdir, open, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { installNpxPackage, npmCacheDir, npmPackageName, npmPackageVersion } from './installProbe.js';
-import { packagePatchMatch, packagePatches } from './patchAssets.js';
+import { fileURLToPath } from 'node:url';
+import { assertSafePackageName, inside } from './builds/model.js';
+import { packagePatchMatch, packagePatches, patchAssetRoot, validatePackagePatch, validatePatchPath } from './patchAssets.js';
 const sha = (content) => createHash('sha256').update(content).digest('hex');
-const pending = new Map();
 const warned = new Set();
 function warnOnce(key, message) {
     if (warned.has(key))
@@ -13,31 +18,150 @@ function warnOnce(key, message) {
     warned.add(key);
     console.warn(message);
 }
-function inside(root, relative) {
+function within(root, relative) {
+    validatePatchPath(relative);
     const target = path.resolve(root, relative);
     if (!target.startsWith(path.resolve(root) + path.sep))
         throw new Error('Axom patch path escapes its package');
     return target;
 }
+/**
+ * Check every component, including the supplied root and its ancestors, without following links.
+ * The one links crossed are root-owned system symlinks (`/var -> /private/var` on macOS): stock
+ * macOS hands out per-user tmp dirs behind one, and refusing it would reject every tmp-scoped
+ * tree. A root-owned link to a root-owned, non-group-writable directory is not plantable by the
+ * running user; every user-owned symlink is still refused.
+ */
+async function noSymlinks(filename, missing = false) {
+    const absolute = path.resolve(filename);
+    let current = path.parse(absolute).root;
+    const systemSymlink = async (uid) => {
+        if (uid !== 0 || process.getuid?.() === 0)
+            return false;
+        try {
+            const target = await realpath(current);
+            const stat = await lstat(target);
+            return stat.isDirectory() && stat.uid === 0 && (stat.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const part of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink() && !(await systemSymlink(info.uid)))
+                throw new Error(`Axom patch symlink is forbidden: ${current}`);
+        }
+        catch (error) {
+            if (missing && error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+}
+async function readOwnedFile(filename) {
+    await noSymlinks(filename);
+    const handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error(`Axom patch requires a regular file: ${filename}`);
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function makeOwnedDirectories(directory) {
+    await noSymlinks(directory, true);
+    const parent = path.dirname(directory);
+    if (parent !== directory) {
+        try {
+            await lstat(directory);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await makeOwnedDirectories(parent);
+            try {
+                await mkdir(directory);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+    }
+    await noSymlinks(directory);
+    if (!(await lstat(directory)).isDirectory())
+        throw new Error(`Axom patch parent is not a directory: ${directory}`);
+}
 /** A matching version and exact original bytes; already-patched or changed originals are rejected. */
-export async function applyPackagePatches(packageDir, recipes) {
+export async function applyPackagePatches(nodeModulesDir, recipes, assetRoot = patchAssetRoot) {
     const output = {};
+    // Validate the complete declaration and asset closure before any writes.
+    expectedPatchedFiles(recipes);
+    const assets = new Map();
     for (const recipe of recipes) {
-        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+        const packageDir = inside(nodeModulesDir, recipe.package);
+        const metadata = JSON.parse((await readOwnedFile(path.join(packageDir, 'package.json'))).toString('utf8'));
         if (metadata.name !== recipe.package || !packagePatchMatch(recipe, metadata.version)) {
             throw new Error(`Axom patch '${recipe.id}' does not support ${metadata.name}@${metadata.version}`);
         }
+        for (const edit of recipe.edits)
+            await noSymlinks(within(packageDir, edit.file));
+        for (const asset of recipe.assets ?? []) {
+            const filename = within(packageDir, asset.target);
+            await noSymlinks(filename, true);
+            try {
+                await lstat(filename);
+                throw new Error(`Axom patch asset collision: target already exists: ${asset.target}`);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const bytes = await readOwnedFile(within(assetRoot instanceof URL ? fileURLToPath(assetRoot) : assetRoot, asset.source));
+            if (sha(bytes) !== asset.sha256)
+                throw new Error(`Axom patch asset hash mismatch: ${asset.source}`);
+            assets.set(`${recipe.package}/${asset.target}`, bytes);
+        }
+    }
+    for (const recipe of recipes) {
+        const packageDir = inside(nodeModulesDir, recipe.package);
         for (const edit of recipe.edits) {
-            const filename = inside(packageDir, edit.file);
-            const original = await readFile(filename, 'utf8');
+            const filename = within(packageDir, edit.file);
+            const original = (await readOwnedFile(filename)).toString('utf8');
             if (sha(original) !== edit.before_sha256 || !edit.before || original.split(edit.before).length !== 2) {
                 throw new Error(`Axom patch '${recipe.id}': original bytes changed in ${edit.file}`);
             }
             const patched = original.replace(edit.before, edit.after);
             if (sha(patched) !== edit.after_sha256)
                 throw new Error(`Axom patch '${recipe.id}': invalid expected output`);
-            await writeFile(filename, patched, 'utf8');
-            output[edit.file] = sha(patched);
+            await noSymlinks(filename);
+            const handle = await open(filename, constants.O_WRONLY | constants.O_NOFOLLOW);
+            try {
+                await handle.truncate(0);
+                await handle.writeFile(patched, 'utf8');
+            }
+            finally {
+                await handle.close();
+            }
+            output[`${recipe.package}/${edit.file}`] = sha(patched);
+        }
+        for (const asset of recipe.assets ?? []) {
+            const filename = within(packageDir, asset.target);
+            await makeOwnedDirectories(path.dirname(filename));
+            await noSymlinks(filename, true);
+            const handle = await open(filename, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+            try {
+                await handle.writeFile(assets.get(`${recipe.package}/${asset.target}`));
+            }
+            finally {
+                await handle.close();
+            }
+            output[`${recipe.package}/${asset.target}`] = asset.sha256;
         }
     }
     return output;
@@ -49,7 +173,7 @@ async function originalsFit(packageDir, recipe) {
         let content = files.get(edit.file);
         if (content === undefined) {
             try {
-                content = await readFile(inside(packageDir, edit.file), 'utf8');
+                content = (await readOwnedFile(within(packageDir, edit.file))).toString('utf8');
             }
             catch {
                 return false;
@@ -61,168 +185,124 @@ async function originalsFit(packageDir, recipe) {
     }
     return true;
 }
-async function cachedModules(name, version, probe) {
-    const root = path.join(npmCacheDir(probe), '_npx');
-    let entries;
-    try {
-        entries = await readdir(root, { withFileTypes: true });
-    }
-    catch {
-        return undefined;
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const modules = path.join(root, entry.name, 'node_modules');
-        try {
-            const metadata = JSON.parse(await readFile(inside(modules, name + '/package.json'), 'utf8'));
-            if (metadata.name === name && metadata.version === version)
-                return modules;
-        }
-        catch { /* Interrupted/other version of npm's cache. */ }
-    }
-    return undefined;
-}
-/** Called by Install/Update and every real launch, including adapters installed before this CLI. */
-export async function preparePatchedLaunch(agent, launch, adapterRoot, probe, options = {}) {
-    const distribution = agent.distribution.npx;
-    if (!distribution)
-        return launch;
-    const name = npmPackageName(distribution.package);
-    const version = npmPackageVersion(distribution.package);
-    const candidates = (options.recipes ?? packagePatches).filter((patch) => patch.package === name);
+/**
+ * The recipes this CLI applies to `name@version`, read against the **pristine** package at
+ * `pristinePackageDir`: exact-version recipes always (their bytes are a promise — a mismatch fails the
+ * patch step loudly), range recipes only when the pristine bytes fit (otherwise upstream runs, with a
+ * warning). An empty answer means the build is the pristine tree itself.
+ */
+export async function selectPackagePatches(name, version, pristinePackageDir, recipes = packagePatches, dependencies = {}) {
+    const candidates = recipes.filter((patch) => patch.package === name || Object.hasOwn(dependencies, patch.package));
     const matched = candidates.flatMap((recipe) => {
-        const match = version ? packagePatchMatch(recipe, version) : undefined;
+        const match = packagePatchMatch(recipe, recipe.package === name ? version : dependencies[recipe.package]);
         return match ? [{ recipe, match }] : [];
     });
-    if (matched.length && (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) || !version || !/^[0-9a-z.+-]+$/i.test(version))) {
+    if (matched.length && (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) || !/^[0-9a-z.+-]+$/i.test(version))) {
         throw new Error('Invalid package identity for Axom adapter patch');
     }
-    // A range only says a recipe may fit; the pristine package's bytes decide.
-    const fitting = new Set();
-    if (matched.some(({ match }) => match === 'range')) {
-        const modules = await pristineModules();
-        for (const { recipe, match } of matched) {
-            if (match !== 'range')
-                continue;
-            if (await originalsFit(inside(modules, name), recipe))
-                fitting.add(recipe);
-            else
-                warnOnce(`${recipe.id}@${distribution.package}`, `[axom-patch] ${recipe.id} does not fit ${distribution.package}; using the upstream package. Review the patch inventory.`);
-        }
-    }
-    const recipes = matched.filter(({ recipe, match }) => match === 'exact' || fitting.has(recipe)).map(({ recipe }) => recipe);
-    if (!recipes.length) {
-        if (candidates.length && !matched.length) {
-            warnOnce(distribution.package, `[axom-patch] No verified patch for ${distribution.package}; using the upstream package. Review the patch inventory.`);
+    const selected = [];
+    const nodeModulesDir = path.resolve(pristinePackageDir, ...name.split('/').map(() => '..'));
+    for (const { recipe, match } of matched) {
+        assertSafePackageName(recipe.package);
+        const packageDir = recipe.package === name ? pristinePackageDir : inside(nodeModulesDir, recipe.package);
+        if (match === 'exact') {
+            selected.push(recipe);
+            continue;
         }
-        return launch;
+        if (await originalsFit(packageDir, recipe))
+            selected.push(recipe);
+        else
+            warnOnce(`${recipe.id}@${name}@${version}`, `[axom-patch] ${recipe.id} does not fit ${name}@${version}; using the upstream package. Review the patch inventory.`);
     }
-    const digest = sha(JSON.stringify(recipes));
-    const target = path.join(adapterRoot, 'patched-npm', sha(name).slice(0, 16), version, digest);
-    const existing = pending.get(target);
-    if (existing) {
-        await existing;
-        return makeLaunch();
+    if (!selected.length && candidates.length && !matched.length) {
+        warnOnce(`${name}@${version}`, `[axom-patch] No verified patch for ${name}@${version}; using the upstream package. Review the patch inventory.`);
     }
-    const preparation = prepare();
-    pending.set(target, preparation);
-    try {
-        await preparation;
-        return await makeLaunch();
-    }
-    finally {
-        pending.delete(target);
+    return selected;
+}
+/** The identity of a recipe set: any recipe change is a new digest, hence a new build. */
+export function patchDigest(recipes) {
+    return sha(JSON.stringify(recipes));
+}
+/**
+ * Copy the pristine `node_modules` (reflink where the filesystem supports it — `COPYFILE_FICLONE`
+ * falls back to an ordinary copy by itself; relative symlinks such as `.bin/*` are kept relative so
+ * the copy never points back into pristine) into `stagedRoot`, patch the copy, and write a receipt.
+ * Returns the sha256 of every patched file, qualified by its package name under node_modules.
+ */
+export async function createPatchedTree(pristineRoot, stagedRoot, name, version, recipes, assetRoot = patchAssetRoot) {
+    const original = path.resolve(pristineRoot, 'node_modules');
+    const copy = path.resolve(stagedRoot, 'node_modules');
+    if (original === copy || original.startsWith(copy + path.sep) || copy.startsWith(original + path.sep)) {
+        throw new Error('Axom patch staged tree must not overlap pristine');
     }
-    async function prepare() {
-        const packageDir = inside(path.join(target, 'node_modules'), name);
-        const receiptFile = path.join(target, 'axom-patches.json');
-        let receipt;
+    await noSymlinks(original);
+    const receipt = path.join(stagedRoot, 'axom-patches.json');
+    for (const destination of [copy, receipt]) {
+        await noSymlinks(destination, true);
         try {
-            receipt = JSON.parse(await readFile(receiptFile, 'utf8'));
+            await lstat(destination);
+            throw new Error(`Axom patch staged target already exists: ${destination}`);
         }
         catch (error) {
             if (error.code !== 'ENOENT')
                 throw error;
         }
-        if (receipt) {
-            if (receipt.digest !== digest)
-                throw new Error('Axom adapter patch receipt does not match this CLI');
-            // Derive expected files from the shipped recipe, never from a writable receipt alone.
-            const expected = Object.fromEntries(recipes.flatMap((recipe) => recipe.edits.map((edit) => [edit.file, edit.after_sha256])));
-            if (JSON.stringify(receipt.files) !== JSON.stringify(expected))
-                throw new Error('Incomplete Axom adapter patch receipt');
-            for (const [file, hash] of Object.entries(expected)) {
-                if (sha(await readFile(inside(packageDir, file))) !== hash)
-                    throw new Error(`Axom patched adapter was modified: ${file}`);
-            }
+    }
+    await cp(path.join(pristineRoot, 'node_modules'), path.join(stagedRoot, 'node_modules'), {
+        recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE,
+    });
+    const files = await applyPackagePatches(path.join(stagedRoot, 'node_modules'), recipes, assetRoot);
+    const expected = expectedPatchedFiles(recipes);
+    if (JSON.stringify(sortKeys(files)) !== JSON.stringify(sortKeys(expected)))
+        throw new Error('Incomplete Axom adapter patch');
+    await noSymlinks(receipt, true);
+    await writeFile(receipt, JSON.stringify({
+        patchedFilesBase: 'node_modules', digest: patchDigest(recipes), package: name, version, patches: recipes.map((recipe) => recipe.id), files,
+    }) + '\n', { flag: 'wx' });
+    console.info(`[axom-patch] Applied ${recipes.map((recipe) => recipe.id).join(', ')} to ${name}@${version}`);
+    return files;
+}
+/** The files a recipe set rewrites and their expected sha256, derived from the shipped recipes. */
+export function expectedPatchedFiles(recipes) {
+    const files = {};
+    const assetTargets = new Set();
+    const editTargets = new Set();
+    for (const recipe of recipes) {
+        assertSafePackageName(recipe.package);
+        validatePackagePatch(recipe);
+        for (const edit of recipe.edits) {
+            const key = `${recipe.package}/${edit.file}`;
+            editTargets.add(key);
+            files[key] = edit.after_sha256;
         }
-        else {
-            try {
-                await stat(target);
-                throw new Error('Incomplete Axom patched adapter directory; refusing to use it');
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
-            }
-            const modules = await pristineModules();
-            await mkdir(path.dirname(target), { recursive: true });
-            const temporary = target + '.staging-' + randomUUID();
-            try {
-                // Dependencies and .bin are part of the adapter environment; clone them as well.
-                await cp(modules, path.join(temporary, 'node_modules'), { recursive: true, dereference: true });
-                const files = await applyPackagePatches(inside(path.join(temporary, 'node_modules'), name), recipes);
-                await writeFile(path.join(temporary, 'axom-patches.json'), JSON.stringify({
-                    digest, package: name, version, patches: recipes.map((recipe) => recipe.id), files,
-                }) + '\n');
-                try {
-                    await rename(temporary, target);
-                }
-                catch (error) {
-                    // A second daemon may have published the same immutable copy while we built ours.
-                    if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
-                        throw error;
-                    return prepare();
-                }
-                console.info(`[axom-patch] Applied ${recipes.map((recipe) => recipe.id).join(', ')} to ${name}@${version}`);
-            }
-            finally {
-                await rm(temporary, { recursive: true, force: true });
+    }
+    for (const recipe of recipes)
+        for (const asset of recipe.assets ?? []) {
+            const key = `${recipe.package}/${asset.target}`;
+            if ([...assetTargets, ...editTargets].some(other => other === key || other.startsWith(key + '/') || key.startsWith(other + '/'))) {
+                throw new Error(`Axom patch asset collision: ${key}`);
             }
+            assetTargets.add(key);
+            files[key] = asset.sha256;
         }
-    }
-    async function pristineModules() {
-        let modules = await cachedModules(name, version, probe);
-        if (!modules) {
-            const installed = await installNpxPackage(distribution.package, {
-                env: probe, timeoutMs: options.timeoutMs, npxCommand: options.npxCommand,
-            });
-            if (!installed.ok)
-                throw new Error(installed.error);
-            modules = await cachedModules(name, version, probe);
-        }
-        if (!modules)
-            throw new Error(`Installed package ${distribution.package} is absent from npm's cache`);
-        return modules;
-    }
-    async function makeLaunch() {
-        const packageDir = inside(path.join(target, 'node_modules'), name);
-        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
-        if (metadata.name !== name || metadata.version !== version)
-            throw new Error('Patched adapter package identity changed');
-        const selectedBins = [...new Set(recipes.map(recipe => recipe.bin).filter((bin) => bin !== undefined))];
-        if (selectedBins.length > 1)
-            throw new Error('Axom patches disagree about the adapter executable');
-        const binaries = selectedBins.length ? [metadata.bin?.[selectedBins[0]]] :
-            typeof metadata.bin === 'string' ? [metadata.bin] : Object.values(metadata.bin ?? {});
-        if (binaries.length !== 1 || typeof binaries[0] !== 'string')
-            throw new Error('Patched adapter has no unambiguous executable');
-        const entry = inside(packageDir, binaries[0]);
-        if (!(await stat(entry)).isFile())
-            throw new Error('Patched adapter executable is missing');
-        const env = { ...launch.env };
-        env.PATH = path.join(target, 'node_modules', '.bin') + path.delimiter + (env.PATH ?? probe.path ?? process.env.PATH ?? '');
-        return { command: process.execPath, args: [entry, ...(distribution.args ?? [])], env };
+    return files;
+}
+function sortKeys(record) {
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** Tamper check against an explicit base: node_modules for qualified keys, adapter package for legacy keys. */
+export async function verifyPatchedFiles(packageDir, files) {
+    for (const [file, hash] of Object.entries(files)) {
+        let content;
+        try {
+            content = await readOwnedFile(within(packageDir, file));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new Error(`Axom patched adapter is missing ${file}`);
+            throw new Error(`Axom patched adapter was modified: ${file} (${error.message})`);
+        }
+        if (sha(content) !== hash)
+            throw new Error(`Axom patched adapter was modified: ${file}`);
     }
 }