Support for flags & options protection

index.d.ts

@@ -14,6 +14,15 @@ type ShellOption = boolean | string | undefined;
  * Options for {@link escape} and {@link escapeAll}.
  */
 interface EscapeOptions {
+  /**
+   * Whether or not to protect against flag and option (such as `--verbose`)
+   * injection
+   *
+   * @default false
+   * @since 1.7.0
+   */
+  readonly flagProtection?: boolean;
+
   /**
    * Is interpolation enabled.
    *
@@ -35,6 +44,15 @@ interface EscapeOptions {
  * Options for {@link quote} and {@link quoteAll}.
  */
 interface QuoteOptions {
+  /**
+   * Whether or not to protect against flag and option (such as `--verbose`)
+   * injection.
+   *
+   * @default false
+   * @since 1.7.0
+   */
+  readonly flagProtection?: boolean;
+
   /**
    * The shell to escape for.
    *
@@ -58,6 +76,7 @@ interface QuoteOptions {
  * );
  * @param {string} arg The argument to escape.
  * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean} [options.interpolation=false] Is interpolation enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string} The escaped argument.
@@ -82,6 +101,7 @@ export function escape(arg: string, options?: EscapeOptions): string;
  * );
  * @param {string[]} args The arguments to escape.
  * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean} [options.interpolation=false] Is interpolation enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string[]} The escaped arguments.
@@ -115,6 +135,7 @@ export function escapeAll(args: string[], options?: EscapeOptions): string[];
  * );
  * @param {string} arg The argument to quote and escape.
  * @param {object} [options] The escape and quote options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string} The quoted and escaped argument.
  * @throws {TypeError} The argument is not stringable.
@@ -140,6 +161,7 @@ export function quote(arg: string, options?: QuoteOptions): string;
  * );
  * @param {string[]} args The arguments to quote and escape.
  * @param {object} [options] The escape and quote options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string[]} The quoted and escaped arguments.
  * @throws {TypeError} One of the arguments is not stringable.

index.js

@@ -43,6 +43,7 @@ function getPlatformHelpers() {
  * );
  * @param {string} arg The argument to escape.
  * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean} [options.interpolation=false] Is interpolation enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string} The escaped argument.
@@ -70,6 +71,7 @@ export function escape(arg, options = {}) {
  * );
  * @param {string[]} args The arguments to escape.
  * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean} [options.interpolation=false] Is interpolation enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string[]} The escaped arguments.
@@ -106,6 +108,7 @@ export function escapeAll(args, options = {}) {
  * );
  * @param {string} arg The argument to quote and escape.
  * @param {object} [options] The escape and quote options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string} The quoted and escaped argument.
  * @throws {TypeError} The argument is not stringable.
@@ -134,6 +137,7 @@ export function quote(arg, options = {}) {
  * );
  * @param {string[]} args The arguments to quote and escape.
  * @param {object} [options] The escape and quote options.
+ * @param {boolean} [options.flagProtection=false] Is flag protection enabled.
  * @param {boolean | string} [options.shell] The shell to escape for.
  * @returns {string[]} The quoted and escaped arguments.
  * @throws {TypeError} One of the arguments is not stringable.

src/main.js

@@ -37,8 +37,9 @@ function checkedToString(value) {
  *
  * @param {object} args The arguments for this function.
  * @param {object} args.options The options for escaping.
- * @param {boolean | string} [args.options.shell] The shell to escape for.
+ * @param {boolean} [args.options.flagProtection] Is flag protection enabled.
  * @param {boolean} [args.options.interpolation] Is interpolation enabled.
+ * @param {boolean | string} [args.options.shell] The shell to escape for.
  * @param {object} args.process The `process` values.
  * @param {object} args.process.env The environment variables.
  * @param {object} deps The dependencies for this function.
@@ -47,51 +48,79 @@ function checkedToString(value) {
  * @returns {object} The parsed arguments.
  */
 function parseOptions(
-  { options: { interpolation, shell }, process: { env } },
+  { options: { flagProtection, interpolation, shell }, process: { env } },
   { getDefaultShell, getShellName }
 ) {
+  flagProtection = flagProtection ? true : false;
   interpolation = interpolation ? true : false;
   shell = isString(shell) ? shell : getDefaultShell({ env });
 
   const shellName = getShellName({ shell }, { resolveExecutable });
-  return { interpolation, shellName };
+  return { flagProtection, interpolation, shellName };
 }
 
 /**
  * Escapes an argument for the given shell.
  *
  * @param {object} args The arguments for this function.
  * @param {string} args.arg The argument to escape.
+ * @param {boolean} args.flagProtection Is flag protection enabled.
  * @param {boolean} args.interpolation Is interpolation enabled.
  * @param {string} args.shellName The name of the shell to escape `arg` for.
  * @param {object} deps The dependencies for this function.
  * @param {Function} deps.getEscapeFunction Get the escape function for a shell.
+ * @param {Function} deps.stripFlagPrefix A function to strip flag prefixes.
  * @returns {string} The escaped argument.
  * @throws {TypeError} The argument to escape is not stringable.
  */
-function escape({ arg, interpolation, shellName }, { getEscapeFunction }) {
+function escape(
+  { arg, flagProtection, interpolation, shellName },
+  { getEscapeFunction, stripFlagPrefix }
+) {
   const argAsString = checkedToString(arg);
   const escape = getEscapeFunction(shellName, { interpolation });
   const escapedArg = escape(argAsString);
-  return escapedArg;
+  if (flagProtection) {
+    return stripFlagPrefix(escapedArg);
+  } else {
+    return escapedArg;
+  }
 }
 
 /**
  * Quotes and escape an argument for the given shell.
  *
  * @param {object} args The arguments for this function.
  * @param {string} args.arg The argument to escape.
+ * @param {boolean} args.flagProtection Is flag protection enabled.
  * @param {string} args.shellName The name of the shell to escape `arg` for.
  * @param {object} deps The dependencies for this function.
  * @param {Function} deps.getQuoteFunction Get the quote function for a shell.
+ * @param {Function} deps.stripFlagPrefix A function to strip flag prefixes.
  * @returns {string} The quoted and escaped argument.
  * @throws {TypeError} The argument to escape is not stringable.
  */
-function quote({ arg, shellName }, { getQuoteFunction }) {
+function quote(
+  { arg, flagProtection, shellName },
+  { getQuoteFunction, stripFlagPrefix }
+) {
   const argAsString = checkedToString(arg);
   const quote = getQuoteFunction(shellName);
   const escapedAndQuotedArg = quote(argAsString);
-  return escapedAndQuotedArg;
+  if (flagProtection) {
+    return (
+      escapedAndQuotedArg.substring(0, 1) +
+      stripFlagPrefix(
+        escapedAndQuotedArg.substring(1, escapedAndQuotedArg.length - 1)
+      ) +
+      escapedAndQuotedArg.substring(
+        escapedAndQuotedArg.length - 1,
+        escapedAndQuotedArg.length
+      )
+    );
+  } else {
+    return escapedAndQuotedArg;
+  }
 }
 
 /**
@@ -100,6 +129,7 @@ function quote({ arg, shellName }, { getQuoteFunction }) {
  * @param {object} args The arguments for this function.
  * @param {string} args.arg The argument to escape.
  * @param {object} args.options The options for escaping `arg`.
+ * @param {boolean} [args.options.flagProtection] Is flag protection enabled.
  * @param {boolean} [args.options.interpolation] Is interpolation enabled.
  * @param {boolean | string} [args.options.shell] The shell to escape `arg` for.
  * @param {object} args.process The `process` values.
@@ -108,23 +138,25 @@ function quote({ arg, shellName }, { getQuoteFunction }) {
  * @param {Function} deps.getDefaultShell Function to get the default shell.
  * @param {Function} deps.getEscapeFunction Get an escape function for a shell.
  * @param {Function} deps.getShellName Function to get the name of a shell.
+ * @param {Function} deps.stripFlagPrefix A function to strip flag prefixes.
  * @returns {string} The escaped argument.
  */
 export function escapeShellArg(
-  { arg, options: { interpolation, shell }, process: { env } },
-  { getDefaultShell, getEscapeFunction, getShellName }
+  { arg, options: { flagProtection, interpolation, shell }, process: { env } },
+  { getDefaultShell, getEscapeFunction, getShellName, stripFlagPrefix }
 ) {
   const options = parseOptions(
-    { options: { interpolation, shell }, process: { env } },
+    { options: { flagProtection, interpolation, shell }, process: { env } },
     { getDefaultShell, getShellName }
   );
   return escape(
     {
       arg,
+      flagProtection: options.flagProtection,
       interpolation: options.interpolation,
       shellName: options.shellName,
     },
-    { getEscapeFunction }
+    { getEscapeFunction, stripFlagPrefix }
   );
 }
 
@@ -134,22 +166,31 @@ export function escapeShellArg(
  * @param {object} args The arguments for this function.
  * @param {string} args.arg The argument to escape.
  * @param {object} args.options The options for escaping `arg`.
+ * @param {boolean} [args.options.flagProtection] Is flag protection enabled.
  * @param {boolean | string} [args.options.shell] The shell to escape `arg` for.
  * @param {object} args.process The `process` values.
  * @param {object} args.process.env The environment variables.
  * @param {object} deps The dependencies for this function.
  * @param {Function} deps.getDefaultShell Function to get the default shell.
  * @param {Function} deps.getQuoteFunction Get a quote function for a shell.
  * @param {Function} deps.getShellName Function to get the name of a shell.
+ * @param {Function} deps.stripFlagPrefix A function to strip flag prefixes.
  * @returns {string} The quoted and escaped argument.
  */
 export function quoteShellArg(
-  { arg, options: { shell }, process: { env } },
-  { getDefaultShell, getQuoteFunction, getShellName }
+  { arg, options: { flagProtection, shell }, process: { env } },
+  { getDefaultShell, getQuoteFunction, getShellName, stripFlagPrefix }
 ) {
   const options = parseOptions(
-    { options: { shell }, process: { env } },
+    { options: { flagProtection, shell }, process: { env } },
     { getDefaultShell, getShellName }
   );
-  return quote({ arg, shellName: options.shellName }, { getQuoteFunction });
+  return quote(
+    {
+      arg,
+      flagProtection: options.flagProtection,
+      shellName: options.shellName,
+    },
+    { getQuoteFunction, stripFlagPrefix }
+  );
 }

src/unix/index.js

@@ -129,3 +129,14 @@ export function getShellName({ shell }, { resolveExecutable }) {
 
   return shellName;
 }
+
+/**
+ * Remove any prefix from the provided argument that might be interpreted as a
+ * flag on Unix systems.
+ *
+ * @param {string} arg The argument to update.
+ * @returns {string} The updated argument.
+ */
+export function stripFlagPrefix(arg) {
+  return arg.replace(/^-+/gu, "");
+}

src/win/index.js

@@ -110,3 +110,14 @@ export function getShellName({ shell }, { resolveExecutable }) {
 
   return shellName;
 }
+
+/**
+ * Remove any prefix from the provided argument that might be interpreted as a
+ * flag on Windows systems.
+ *
+ * @param {string} arg The argument to update.
+ * @returns {string} The updated argument.
+ */
+export function stripFlagPrefix(arg) {
+  return arg.replace(/^(?:-+|\/+)/gu, "");
+}

test/_arbitraries.js

@@ -192,7 +192,13 @@ export const shescapeOptions = () =>
     fc.object({
       key: fc.oneof(
         fc.string(),
-        fc.constantFrom("interpolation", "quoted", "shell", "shellName")
+        fc.constantFrom(
+          "flagProtection",
+          "interpolation",
+          "quoted",
+          "shell",
+          "shellName"
+        )
       ),
       values: [
         fc.boolean(),