@optique/core 0.8.0 → 0.9.0-dev.172

package/dist/completion.cjs

@@ -2,12 +2,41 @@ const require_message = require('./message.cjs');
 
 //#region src/completion.ts
 /**
+* A regular expression pattern for valid program names that can be safely
+* interpolated into shell scripts.
+*
+* This pattern allows:
+* - Letters (a-z, A-Z)
+* - Numbers (0-9)
+* - Underscore (_)
+* - Hyphen (-)
+* - Dot (.)
+*
+* @internal
+*/
+const SAFE_PROGRAM_NAME_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+/**
+* Validates a program name for safe use in shell scripts.
+*
+* Program names that contain shell metacharacters or other special characters
+* could enable command injection attacks when interpolated into shell scripts.
+* This function ensures only safe characters are used.
+*
+* @param programName The program name to validate.
+* @throws {Error} If the program name contains invalid characters.
+* @internal
+*/
+function validateProgramName(programName) {
+	if (!SAFE_PROGRAM_NAME_PATTERN.test(programName)) throw new Error(`Invalid program name for shell completion: "${programName}". Program names must contain only alphanumeric characters, underscores, hyphens, and dots.`);
+}
+/**
 * The Bash shell completion generator.
 * @since 0.6.0
 */
 const bash = {
 	name: "bash",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ");
 		return `
 function _${programName} () {
@@ -107,6 +136,7 @@ complete -F _${programName} ${programName}
 const zsh = {
 	name: "zsh",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ");
 		return `
 function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
@@ -222,6 +252,7 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 const fish = {
 	name: "fish",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "\\'")}'`).join(" ");
 		const functionName = `__${programName.replace(/[^a-zA-Z0-9]/g, "_")}_complete`;
 		return `
@@ -354,6 +385,7 @@ complete -c ${programName} -f -a '(${functionName})'
 const nu = {
 	name: "nu",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "''")}'`).join(" ");
 		const safeName = programName.replace(/[^a-zA-Z0-9]+/g, "-");
 		const functionName = `nu-complete-${safeName}`;
@@ -583,6 +615,7 @@ ${functionName}-external
 const pwsh = {
 	name: "pwsh",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "''")}'`).join(", ");
 		return `
 Register-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {

package/dist/completion.js

@@ -2,12 +2,41 @@ import { formatMessage } from "./message.js";
 
 //#region src/completion.ts
 /**
+* A regular expression pattern for valid program names that can be safely
+* interpolated into shell scripts.
+*
+* This pattern allows:
+* - Letters (a-z, A-Z)
+* - Numbers (0-9)
+* - Underscore (_)
+* - Hyphen (-)
+* - Dot (.)
+*
+* @internal
+*/
+const SAFE_PROGRAM_NAME_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+/**
+* Validates a program name for safe use in shell scripts.
+*
+* Program names that contain shell metacharacters or other special characters
+* could enable command injection attacks when interpolated into shell scripts.
+* This function ensures only safe characters are used.
+*
+* @param programName The program name to validate.
+* @throws {Error} If the program name contains invalid characters.
+* @internal
+*/
+function validateProgramName(programName) {
+	if (!SAFE_PROGRAM_NAME_PATTERN.test(programName)) throw new Error(`Invalid program name for shell completion: "${programName}". Program names must contain only alphanumeric characters, underscores, hyphens, and dots.`);
+}
+/**
 * The Bash shell completion generator.
 * @since 0.6.0
 */
 const bash = {
 	name: "bash",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ");
 		return `
 function _${programName} () {
@@ -107,6 +136,7 @@ complete -F _${programName} ${programName}
 const zsh = {
 	name: "zsh",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ");
 		return `
 function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
@@ -222,6 +252,7 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 const fish = {
 	name: "fish",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "\\'")}'`).join(" ");
 		const functionName = `__${programName.replace(/[^a-zA-Z0-9]/g, "_")}_complete`;
 		return `
@@ -354,6 +385,7 @@ complete -c ${programName} -f -a '(${functionName})'
 const nu = {
 	name: "nu",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "''")}'`).join(" ");
 		const safeName = programName.replace(/[^a-zA-Z0-9]+/g, "-");
 		const functionName = `nu-complete-${safeName}`;
@@ -583,6 +615,7 @@ ${functionName}-external
 const pwsh = {
 	name: "pwsh",
 	generateScript(programName, args = []) {
+		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "''")}'`).join(", ");
 		return `
 Register-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {

package/dist/valueparser.cjs

@@ -64,6 +64,11 @@ function choice(choices, options = {}) {
 *
 * This parser validates that the input is a string and optionally checks
 * if it matches a specified regular expression pattern.
+*
+* **Security note**: When using the `pattern` option with user-defined or
+* complex patterns, be aware of potential Regular Expression Denial of Service
+* (ReDoS) attacks. See {@link StringOptions.pattern} for more details.
+*
 * @param options Configuration options for the string parser.
 * @returns A {@link ValueParser} that parses strings according to the
 *          specified options.

package/dist/valueparser.d.cts

@@ -78,6 +78,14 @@ interface StringOptions {
   readonly metavar?: string;
   /**
    * Optional regular expression pattern that the string must match.
+   *
+   * **Security note**: When using user-defined or complex patterns, be aware
+   * of potential Regular Expression Denial of Service (ReDoS) attacks.
+   * Maliciously crafted input strings can cause exponential backtracking in
+   * vulnerable patterns, leading to high CPU usage. Avoid patterns with
+   * nested quantifiers like `(a+)+` or overlapping alternations. Consider
+   * using tools like [safe-regex](https://www.npmjs.com/package/safe-regex)
+   * to validate patterns before use.
    */
   readonly pattern?: RegExp;
   /**
@@ -149,6 +157,11 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  *
  * This parser validates that the input is a string and optionally checks
  * if it matches a specified regular expression pattern.
+ *
+ * **Security note**: When using the `pattern` option with user-defined or
+ * complex patterns, be aware of potential Regular Expression Denial of Service
+ * (ReDoS) attacks. See {@link StringOptions.pattern} for more details.
+ *
  * @param options Configuration options for the string parser.
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.

package/dist/valueparser.d.ts

@@ -78,6 +78,14 @@ interface StringOptions {
   readonly metavar?: string;
   /**
    * Optional regular expression pattern that the string must match.
+   *
+   * **Security note**: When using user-defined or complex patterns, be aware
+   * of potential Regular Expression Denial of Service (ReDoS) attacks.
+   * Maliciously crafted input strings can cause exponential backtracking in
+   * vulnerable patterns, leading to high CPU usage. Avoid patterns with
+   * nested quantifiers like `(a+)+` or overlapping alternations. Consider
+   * using tools like [safe-regex](https://www.npmjs.com/package/safe-regex)
+   * to validate patterns before use.
    */
   readonly pattern?: RegExp;
   /**
@@ -149,6 +157,11 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  *
  * This parser validates that the input is a string and optionally checks
  * if it matches a specified regular expression pattern.
+ *
+ * **Security note**: When using the `pattern` option with user-defined or
+ * complex patterns, be aware of potential Regular Expression Denial of Service
+ * (ReDoS) attacks. See {@link StringOptions.pattern} for more details.
+ *
  * @param options Configuration options for the string parser.
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.

package/dist/valueparser.js

@@ -64,6 +64,11 @@ function choice(choices, options = {}) {
 *
 * This parser validates that the input is a string and optionally checks
 * if it matches a specified regular expression pattern.
+*
+* **Security note**: When using the `pattern` option with user-defined or
+* complex patterns, be aware of potential Regular Expression Denial of Service
+* (ReDoS) attacks. See {@link StringOptions.pattern} for more details.
+*
 * @param options Configuration options for the string parser.
 * @returns A {@link ValueParser} that parses strings according to the
 *          specified options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.0",
+  "version": "0.9.0-dev.172+ab781f75",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",