powershell-utils 0.2.0 → 0.2.1

package/index.d.ts

@@ -1,21 +1,31 @@
 import type {ExecFileOptions, ExecFileSyncOptions} from 'node:child_process';
 
-export type ExecutePowerShellOptions = ExecFileOptions & {
+export type ExecutePowerShellOptions = Omit<ExecFileOptions, 'shell'> & {
 	/**
 	Path to PowerShell executable.
 
 	@default powerShellPath()
 	*/
 	readonly powerShellPath?: string;
+
+	/**
+	Not supported. PowerShell is always executed directly to prevent shell injection.
+	*/
+	readonly shell?: never;
 };
 
-export type ExecutePowerShellSyncOptions = ExecFileSyncOptions & {
+export type ExecutePowerShellSyncOptions = Omit<ExecFileSyncOptions, 'shell'> & {
 	/**
 	Path to PowerShell executable.
 
 	@default powerShellPath()
 	*/
 	readonly powerShellPath?: string;
+
+	/**
+	Not supported. PowerShell is always executed directly to prevent shell injection.
+	*/
+	readonly shell?: never;
 };
 
 export type ExecutePowerShellResult = {
@@ -105,6 +115,10 @@ export namespace executePowerShell {
 	/**
 	Escape a string argument for use in PowerShell single-quoted strings.
 
+	This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
+
+	Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
+
 	@param value - The value to escape.
 	@returns Escaped and quoted string ready for PowerShell.
 

package/index.js

@@ -34,10 +34,19 @@ const argumentsPrefix = [
 
 const encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
 
-const escapeArgument = value => `'${String(value).replaceAll('\'', '\'\'')}'`;
+/*
+PowerShell's tokenizer treats the typographic single quotes U+2018, U+2019, U+201A, and U+201B as string delimiters, exactly like the ASCII one, and it does not require the closing quote to match the opening quote. Escaping only the ASCII quote would let any of the others terminate the string and inject a statement. Doubling works for all of them.
+*/
+const escapeArgument = value => `'${String(value).replaceAll(/['‘’‚‛]/g, match => match + match)}'`;
 
 const createArguments = command => [...argumentsPrefix, encodeCommand(command)];
 
+const createExecFileOptions = options => ({
+	encoding: 'utf8',
+	...options,
+	shell: false,
+});
+
 export const executePowerShell = async (command, options = {}) => {
 	const {
 		powerShellPath: psPath,
@@ -47,10 +56,7 @@ export const executePowerShell = async (command, options = {}) => {
 	return execFile(
 		psPath ?? powerShellPath(),
 		createArguments(command),
-		{
-			encoding: 'utf8',
-			...execFileOptions,
-		},
+		createExecFileOptions(execFileOptions),
 	);
 };
 
@@ -68,9 +74,6 @@ export const executePowerShellSync = (command, options = {}) => {
 	return childProcess.execFileSync(
 		psPath ?? powerShellPath(),
 		createArguments(command),
-		{
-			encoding: 'utf8',
-			...execFileOptions,
-		},
+		createExecFileOptions(execFileOptions),
 	);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "powershell-utils",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Utilities for executing PowerShell commands",
 	"license": "MIT",
 	"repository": "sindresorhus/powershell-utils",

package/readme.md

@@ -76,7 +76,7 @@ The PowerShell command to execute.
 
 Type: `object`
 
-The below option and also all options in Node.js [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback) are supported.
+The below option and all options except `shell` in Node.js [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback) are supported. PowerShell is always executed directly to prevent shell injection.
 
 ##### powerShellPath
 
@@ -126,6 +126,11 @@ Returns: `string`
 
 Escape a string argument for use in PowerShell single-quoted strings.
 
+> [!IMPORTANT]
+> This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
+>
+> Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
+
 #### value
 
 Type: `unknown`
@@ -187,7 +192,7 @@ The PowerShell command to execute.
 
 Type: `object`
 
-The below option and also all options in Node.js [`child_process.execFileSync()`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options) are supported.
+The below option and all options except `shell` in Node.js [`child_process.execFileSync()`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options) are supported. PowerShell is always executed directly to prevent shell injection.
 
 ##### powerShellPath