@open-audio-stack/core 0.1.53 → 0.1.54

package/README.md

@@ -27,6 +27,14 @@
 
 Common package shared across Open Audio Stack compatible registries, command-line tools, apps and websites for handling installing DAW VST plugin dependencies.
 
+## Who is this for
+
+This library is built for **audio software developers**. If you are building a plugin manager, DAW, app, command-line tool or website, use `@open-audio-stack/core` to search a registry and download/install packages without writing the distribution and install logic yourself.
+
+The end beneficiaries are the audio software developers'  customers: **musicians and music producers**, who get a more consistent experience installing audio software.
+
+For the wider project context and strategy, see [Open Audio Stack](https://github.com/open-audio-stack).
+
 ## Features
 
 High-level classes enable use without writing business-logic:

package/build/classes/ManagerLocal.js

@@ -2,7 +2,7 @@ import path from 'path';
 import { Package } from './Package.js';
 import { Manager } from './Manager.js';
 import { archiveExtract, dirCreate, dirDelete, dirEmpty, dirIs, dirMove, dirRead, fileCreate, fileCreateJson, fileCreateYaml, fileExec, fileExists, fileHash, fileInstall, fileOpen, fileReadJson, fileReadYaml, filesMove, isAdmin, runCliAsAdmin, } from '../helpers/file.js';
-import { isValidVersion, pathGetSlug, pathGetVersion, toSlug } from '../helpers/utils.js';
+import { isValidSlug, isValidVersion, pathGetSlug, pathGetVersion, toSlug } from '../helpers/utils.js';
 import { commandExists, getArchitecture, getSystem, isTests } from '../helpers/utilsLocal.js';
 import { apiBuffer } from '../helpers/api.js';
 import { FileType } from '../types/FileType.js';
@@ -161,6 +161,14 @@ export class ManagerLocal extends Manager {
     }
     async install(slug, version) {
         this.log('install', slug, version);
+        // slug/version can originate from remote registry JSON (via sync(), e.g. through
+        // installAll() iterating every synced package) or from a local project file - never from a
+        // value the caller has already validated. Reject anything malformed before it can reach the
+        // elevated command payload built below.
+        if (!isValidSlug(slug))
+            throw new Error(`Invalid package slug: ${slug}`);
+        if (version && !isValidVersion(version))
+            throw new Error(`Invalid package version: ${version}`);
         // Get package information from registry.
         const pkg = this.getPackage(slug);
         if (!pkg)
@@ -196,12 +204,14 @@ export class ManagerLocal extends Manager {
             throw new Error(`No compatible files found for ${slug}`);
         // Elevate permissions if not running as admin.
         if (!isAdmin() && !isTests()) {
-            let command = `--appDir "${this.config.get('appDir')}" --operation "install" --type "${this.type}" --id "${slug}"`;
-            if (version)
-                command += ` --ver "${version}"`;
-            if (this.debug)
-                command += ` --log`;
-            await runCliAsAdmin(command);
+            await runCliAsAdmin({
+                appDir: this.config.get('appDir'),
+                operation: 'install',
+                type: this.type,
+                id: slug,
+                version,
+                log: this.debug,
+            });
             const returnedPkg = this.getPackage(slug)?.getVersion(versionNum);
             if (returnedPkg) {
                 if (this.isPackageInstalled(slug, versionNum))
@@ -348,10 +358,13 @@ export class ManagerLocal extends Manager {
     async installAll() {
         // Elevate permissions if not running as admin.
         if (!isAdmin() && !isTests()) {
-            let command = `--appDir "${this.config.get('appDir')}" --operation "installAll" --type "${this.type}"`;
-            if (this.debug)
-                command += ` --log`;
-            await runCliAsAdmin(command);
+            await runCliAsAdmin({
+                appDir: this.config.get('appDir'),
+                operation: 'installAll',
+                type: this.type,
+                id: '',
+                log: this.debug,
+            });
             return this.listPackages();
         }
         // Loop through all packages and install each one.
@@ -460,6 +473,10 @@ export class ManagerLocal extends Manager {
         }
     }
     async uninstall(slug, version) {
+        if (!isValidSlug(slug))
+            throw new Error(`Invalid package slug: ${slug}`);
+        if (version && !isValidVersion(version))
+            throw new Error(`Invalid package version: ${version}`);
         // Get package information from registry.
         const pkg = this.getPackage(slug);
         if (!pkg)
@@ -472,12 +489,14 @@ export class ManagerLocal extends Manager {
             throw new Error(`Package ${slug} version ${versionNum} not installed`);
         // Elevate permissions if not running as admin.
         if (!isAdmin() && !isTests()) {
-            let command = `--appDir "${this.config.get('appDir')}" --operation "uninstall" --type "${this.type}" --id "${slug}"`;
-            if (version)
-                command += ` --ver "${version}"`;
-            if (this.debug)
-                command += ` --log`;
-            await runCliAsAdmin(command);
+            await runCliAsAdmin({
+                appDir: this.config.get('appDir'),
+                operation: 'uninstall',
+                type: this.type,
+                id: slug,
+                version,
+                log: this.debug,
+            });
             const returnedPkg = this.getPackage(slug)?.getVersion(versionNum);
             if (returnedPkg) {
                 if (this.isPackageInstalled(slug, versionNum))

package/build/helpers/admin.js

@@ -1,6 +1,11 @@
 // Run when Electron needs elevated privileges
 // npm run build && node ./build/helpers/admin.js --operation install --type plugins --id surge-synthesizer/surge
 // npm run build && node ./build/helpers/admin.js --operation uninstall --type plugins --id surge-synthesizer/surge
+//
+// runCliAsAdmin() (helpers/file.ts) invokes this via `--payload <base64url JSON>` rather than
+// individual flags, since the values it carries (appDir/id/version) originate from registry
+// metadata or local project files and must never be interpolated into a shell command as text.
+// The individual --flag form above is still accepted for manual/developer invocation only.
 import { RegistryType } from '../types/Registry.js';
 import { ManagerLocal } from '../classes/ManagerLocal.js';
 import { dirApp } from './file.js';
@@ -11,6 +16,11 @@ export function adminArguments() {
         type: RegistryType.Plugins,
         id: 'surge-synthesizer/surge',
     };
+    const payloadIndex = process.argv.indexOf('--payload');
+    if (payloadIndex !== -1 && process.argv[payloadIndex + 1]) {
+        const decoded = JSON.parse(Buffer.from(process.argv[payloadIndex + 1], 'base64url').toString('utf8'));
+        return { ...args, ...decoded };
+    }
     for (let i = 0; i < process.argv.length; i++) {
         const arg = process.argv[i];
         if (arg === '--appDir') {

package/build/helpers/file.d.ts

@@ -5,6 +5,7 @@ import { PresetFile } from '../types/Preset.js';
 import { ProjectFile } from '../types/Project.js';
 import { ZodIssue } from 'zod';
 import { SystemType } from '../types/SystemType.js';
+export declare function isSafeArchiveEntryPath(entryName: string, targetRoot: string): boolean;
 export declare function archiveExtract(filePath: string, dirPath: string): Promise<void>;
 export declare function dirApp(dirName?: string): string;
 export declare function dirContains(parentDir: string, childDir: string): boolean;
@@ -42,5 +43,13 @@ export declare function fileSize(filePath: string): number;
 export declare function isAdmin(): boolean;
 export declare function fileValidateMetadata(filePath: string, fileMetadata: PluginFile | PresetFile | ProjectFile): Promise<ZodIssue[]>;
 export declare function getPlatform(): SystemType;
-export declare function runCliAsAdmin(args: string): Promise<void>;
+export interface AdminPayload {
+    appDir: string;
+    operation: string;
+    type: string;
+    id: string;
+    version?: string;
+    log?: boolean;
+}
+export declare function runCliAsAdmin(payload: AdminPayload): Promise<void>;
 export declare function zipCreate(filesPath: string, zipPath: string): void;

package/build/helpers/file.js

@@ -1,8 +1,8 @@
 import AdmZip from 'adm-zip';
-import { execFileSync, execSync, spawn } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import { createReadStream, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'fs';
 import { createHash } from 'crypto';
-import { unpack } from '7zip-min';
+import { list, unpack } from '7zip-min';
 import stream from 'stream/promises';
 import { globSync } from 'glob';
 import { moveSync } from 'fs-extra/esm';
@@ -17,16 +17,25 @@ import sudoPrompt from '@vscode/sudo-prompt';
 import { getSystem } from './utilsLocal.js';
 import { log } from './utils.js';
 import mime from 'mime-types';
+// Rejects the "zip slip" pattern: an archive entry name like `../../../etc/passwd` or an
+// absolute path that, once joined to the extraction directory, resolves outside of it.
+export function isSafeArchiveEntryPath(entryName, targetRoot) {
+    return dirContains(targetRoot, path.resolve(targetRoot, entryName));
+}
 export async function archiveExtract(filePath, dirPath) {
     log('⎋', dirPath);
     const fileName = path.basename(filePath).toLowerCase();
     const ext = path.extname(filePath).trim().toLowerCase();
+    const targetRoot = path.resolve(dirPath);
     const tarExtensions = ['.tar', '.gz', '.tgz', '.xz', '.bz2', '.tbz2'];
     const tarCompoundExtensions = ['.tar.gz', '.tar.xz', '.tar.bz2'];
     const isTarFile = tarExtensions.includes(ext) || tarCompoundExtensions.some(compoundExt => fileName.endsWith(compoundExt));
     if (ext === '.zip') {
         const zip = new AdmZip(filePath);
         try {
+            // adm-zip's extractAllTo already guards against zip-slip internally (its sanitize()/
+            // canonical() helpers fall back to the entry's basename if it would otherwise resolve
+            // outside the target directory) - this is the normal, non-fallback path.
             return zip.extractAllTo(dirPath);
         }
         catch (error) {
@@ -36,13 +45,19 @@ export async function archiveExtract(filePath, dirPath) {
                 const entries = zip.getEntries();
                 entries.forEach(entry => {
                     const sanitizedName = entry.entryName.replace(/[<>:"|?*]/g, '_').replace(/[\r\n]/g, '');
+                    // This manual path builds destinations by hand instead of going through adm-zip's own
+                    // sanitize(), so it must enforce the same containment itself - stripping `<>:"|?*` and
+                    // newlines does nothing to stop a `..`-based traversal.
+                    if (!isSafeArchiveEntryPath(sanitizedName, targetRoot)) {
+                        throw new Error(`Archive entry escapes extraction directory: ${entry.entryName}`);
+                    }
+                    const outputPath = path.join(dirPath, sanitizedName);
                     if (!entry.isDirectory) {
-                        const outputPath = path.join(dirPath, sanitizedName);
                         dirCreate(path.dirname(outputPath));
                         writeFileSync(outputPath, entry.getData());
                     }
                     else {
-                        dirCreate(path.join(dirPath, sanitizedName));
+                        dirCreate(outputPath);
                     }
                 });
                 return;
@@ -50,12 +65,25 @@ export async function archiveExtract(filePath, dirPath) {
         }
     }
     else if (isTarFile) {
+        // node-tar rejects '..' path segments and relativizes absolute paths by default
+        // (preservePaths is false unless explicitly opted into), so no extra check is needed here.
         return await tar.extract({
             file: filePath,
             cwd: dirPath,
         });
     }
     else if (ext === '.7z') {
+        // Unlike adm-zip/node-tar, 7zip-min just shells out to the 7za binary with no per-entry
+        // containment logic of its own, and there's no way to sanitize an entry's destination
+        // mid-extraction. List the archive's contents first and refuse to extract at all if any
+        // entry would escape the target directory.
+        const entries = await new Promise((resolve, reject) => {
+            list(filePath, (err, result) => (err ? reject(err) : resolve(result || [])));
+        });
+        const unsafeEntry = entries.find(entry => entry.name && !isSafeArchiveEntryPath(entry.name, targetRoot));
+        if (unsafeEntry) {
+            throw new Error(`Archive entry escapes extraction directory: ${unsafeEntry.name}`);
+        }
         return new Promise((resolve, reject) => {
             unpack(filePath, dirPath, (err2) => {
                 if (err2)
@@ -73,7 +101,12 @@ export function dirApp(dirName = 'open-audio-stack') {
     return path.join(os.homedir(), '.local', 'share', dirName);
 }
 export function dirContains(parentDir, childDir) {
-    return path.normalize(childDir).startsWith(path.normalize(parentDir));
+    const normalizedParent = path.normalize(parentDir);
+    const normalizedChild = path.normalize(childDir);
+    // A trailing separator is required before the prefix check, otherwise a sibling directory
+    // that merely shares a prefix (e.g. parent "/foo/bar" vs child "/foo/barbaz") would
+    // incorrectly count as contained.
+    return normalizedChild === normalizedParent || normalizedChild.startsWith(normalizedParent + path.sep);
 }
 export function dirCreate(dir) {
     if (!dirExists(dir)) {
@@ -109,17 +142,20 @@ export function dirMove(dir, dirNew) {
     return false;
 }
 export function dirOpen(dir) {
-    let command = '';
     if (process.env.CI)
         return Buffer.from('');
-    if (getSystem() === SystemType.Win)
-        command = 'start ""';
-    else if (getSystem() === SystemType.Mac)
-        command = 'open';
-    else
-        command = 'xdg-open';
-    log('⎋', `${command} "${dir}"`);
-    return execSync(`${command} "${dir}"`);
+    // execFileSync never invokes a shell, so `dir` can't break out into a second command
+    // regardless of its contents.
+    if (getSystem() === SystemType.Win) {
+        log('⎋', `cmd.exe /c start "" "${dir}"`);
+        return execFileSync('cmd.exe', ['/c', 'start', '""', dir]);
+    }
+    else if (getSystem() === SystemType.Mac) {
+        log('⎋', `open "${dir}"`);
+        return execFileSync('open', [dir]);
+    }
+    log('⎋', `xdg-open "${dir}"`);
+    return execFileSync('xdg-open', [dir]);
 }
 export function dirPackage(pkg) {
     const parts = pkg.slug.split('/');
@@ -216,35 +252,77 @@ export async function fileHash(filePath, algorithm = 'sha256') {
     await stream.pipeline(input, hash);
     return hash.digest('hex');
 }
+// Mounts to an explicit, freshly created mountpoint (rather than scanning /Volumes for
+// whatever showed up) so a concurrently mounted, unrelated disk image can't be picked up
+// instead, and so we know exactly what to detach afterwards.
+function installDmg(filePath) {
+    const mountPoint = path.join(os.tmpdir(), `oas-dmg-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(mountPoint, { recursive: true });
+    try {
+        log('⎋', `hdiutil attach -nobrowse -mountpoint "${mountPoint}" "${filePath}"`);
+        execFileSync('hdiutil', ['attach', '-nobrowse', '-mountpoint', mountPoint, filePath]);
+        const pkgs = dirRead(path.join(mountPoint, '**', '*.pkg'));
+        if (pkgs.length === 0)
+            throw new Error(`No .pkg found inside ${filePath}`);
+        log('⎋', `sudo installer -pkg "${pkgs[0]}" -target /`);
+        return execFileSync('sudo', ['installer', '-pkg', pkgs[0], '-target', '/'], { stdio: 'inherit' });
+    }
+    finally {
+        try {
+            execFileSync('hdiutil', ['detach', mountPoint, '-force']);
+        }
+        catch {
+            /* best-effort unmount */
+        }
+    }
+}
+// Every branch below uses execFileSync (no shell) rather than building a command string for
+// execSync. This is the actual fix, not just a hardening pass: file paths here are derived
+// from community-submitted registry metadata (file.url), so a shell string built via template
+// literal is a command injection vector regardless of how strictly the url is validated
+// upstream - execFileSync passes each argument as its own argv entry, so shell metacharacters
+// in filePath (`$(...)`, backticks, `;`, `|`, `&&`, ...) can never be interpreted.
 export function fileInstall(filePath) {
     if (process.env.CI)
         return Buffer.from('');
     const ext = path.extname(filePath).toLowerCase();
-    let command = null;
     switch (ext) {
         case '.dmg':
-            command = `hdiutil attach -nobrowse "${filePath}" && sudo installer -pkg "$(find /Volumes -name '*.pkg' -maxdepth 2 | head -n 1)" -target / && hdiutil detach "$(dirname "$(find /Volumes -name '*.pkg' -maxdepth 2 | head -n 1)")"`;
-            break;
+            return installDmg(filePath);
         case '.pkg':
-            command = `sudo installer -pkg "${filePath}" -target /`;
-            break;
+            log('⎋', `sudo installer -pkg "${filePath}" -target /`);
+            return execFileSync('sudo', ['installer', '-pkg', filePath, '-target', '/'], { stdio: 'inherit' });
         case '.deb':
-            command = `sudo dpkg -i "${filePath}" || sudo apt-get install -f -y`;
-            break;
+            log('⎋', `sudo dpkg -i "${filePath}" || sudo apt-get install -f -y`);
+            try {
+                return execFileSync('sudo', ['dpkg', '-i', filePath], { stdio: 'inherit' });
+            }
+            catch {
+                return execFileSync('sudo', ['apt-get', 'install', '-f', '-y'], { stdio: 'inherit' });
+            }
         case '.rpm':
-            command = `sudo rpm -i --nodigest --nofiledigest --nosignature --force "${filePath}" || sudo dnf install -y "${filePath}" || sudo yum install -y "${filePath}"`;
-            break;
+            log('⎋', `sudo rpm -i --nodigest --nofiledigest --nosignature --force "${filePath}" || sudo dnf install -y "${filePath}" || sudo yum install -y "${filePath}"`);
+            try {
+                return execFileSync('sudo', ['rpm', '-i', '--nodigest', '--nofiledigest', '--nosignature', '--force', filePath], { stdio: 'inherit' });
+            }
+            catch {
+                try {
+                    return execFileSync('sudo', ['dnf', 'install', '-y', filePath], { stdio: 'inherit' });
+                }
+                catch {
+                    return execFileSync('sudo', ['yum', 'install', '-y', filePath], { stdio: 'inherit' });
+                }
+            }
         case '.exe':
-            command = `start /wait "" "${filePath}" /quiet /norestart`;
-            break;
+            // Run the downloaded installer directly - no shell/`start` wrapper needed at all.
+            log('⎋', `"${filePath}" /quiet /norestart`);
+            return execFileSync(filePath, ['/quiet', '/norestart'], { stdio: 'inherit' });
         case '.msi':
-            command = `msiexec /i "${filePath}" /quiet /norestart`;
-            break;
+            log('⎋', `msiexec /i "${filePath}" /quiet /norestart`);
+            return execFileSync('msiexec', ['/i', filePath, '/quiet', '/norestart'], { stdio: 'inherit' });
         default:
             throw new Error(`Unsupported file format: ${ext}`);
     }
-    log('⎋', command);
-    return execSync(command, { stdio: 'inherit' });
 }
 export function fileMove(filePath, newPath) {
     if (fileExists(filePath)) {
@@ -323,6 +401,9 @@ export function filesMove(dirSource, dirTarget, dirSub, formatDir) {
     });
     return filesMoved;
 }
+// filePath (and, for the Windows/Linux branches, the surrounding options) ultimately come from
+// a package's `open` field in registry metadata, so this is the same command-injection surface
+// as fileInstall - execFileSync (no shell) rather than execSync everywhere below.
 export function fileOpen(filePath, options = []) {
     if (process.env.CI)
         return Buffer.from('');
@@ -336,16 +417,15 @@ export function fileOpen(filePath, options = []) {
         }
         else {
             log('⎋', `open "${filePath}"`);
-            return execSync(`open "${filePath}"`);
+            return execFileSync('open', [filePath]);
         }
     }
-    let command = '';
-    if (getSystem() === SystemType.Win)
-        command = 'start ""';
-    else
-        command = 'xdg-open';
-    log('⎋', `${command} "${filePath}"`);
-    return execSync(`${command} "${filePath}"`);
+    if (getSystem() === SystemType.Win) {
+        log('⎋', `cmd.exe /c start "" "${filePath}"`);
+        return execFileSync('cmd.exe', ['/c', 'start', '""', filePath]);
+    }
+    log('⎋', `xdg-open "${filePath}"`);
+    return execFileSync('xdg-open', [filePath]);
 }
 export function fileRead(filePath) {
     log('⎋', filePath);
@@ -413,13 +493,20 @@ export function getPlatform() {
         return SystemType.Mac;
     return SystemType.Linux;
 }
-export function runCliAsAdmin(args) {
+// sudo-prompt's exec() only accepts a single command string run through a shell - there is no
+// argv-array form to escape into. `appDir`/`id`/`version` ultimately come from registry
+// metadata or local project files, so building `--flag "${value}"` text here would be the same
+// command-injection surface as fileInstall. Instead, base64url-encode the dynamic payload: its
+// alphabet is only [A-Za-z0-9_-], so whatever the payload contains, the shell only ever sees
+// characters that can't be interpreted as shell syntax.
+export function runCliAsAdmin(payload) {
     return new Promise((resolve, reject) => {
         const filename = fileURLToPath(import.meta.url).replace('src/', 'build/');
         const dirPathClean = dirname(filename).replace('app.asar', 'app.asar.unpacked');
         const script = path.join(dirPathClean, 'admin.js');
-        log(`Running as admin: node "${script}" ${args}`);
-        const cmd = `node "${script}" ${args}`;
+        const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        log(`Running as admin: node "${script}" --payload <encoded>`);
+        const cmd = `node ${JSON.stringify(script)} --payload ${encodedPayload}`;
         sudoPrompt.exec(cmd, { name: 'Open Audio Stack' }, (error, stdout, stderr) => {
             // Convert stdout/stderr buffers to strings for inspection
             const stdoutStr = stdout ? (typeof stdout === 'string' ? stdout : stdout.toString()) : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-audio-stack/core",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "description": "Open-source audio plugin management software",
   "type": "module",
   "main": "./build/index.js",