synapse-mcp 1.0.0 → 1.0.2

package/dist/middleware/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":""}

package/dist/schemas/common.d.ts

@@ -10,7 +10,10 @@ import { ResponseFormat } from "../types.js";
  * Response format schema for output formatting
  * Defaults to markdown for human-readable output
  */
-export declare const responseFormatSchema: z.ZodDefault<z.ZodEnum<typeof ResponseFormat>>;
+export declare const responseFormatSchema: z.ZodDefault<z.ZodEnum<{
+    json: ResponseFormat.JSON;
+    markdown: ResponseFormat.MARKDOWN;
+}>>;
 /**
  * Pagination schema for list operations
  * Used to control result set size and implement pagination
@@ -25,8 +28,55 @@ export declare const paginationSchema: z.ZodObject<{
  */
 export declare const hostSchema: z.ZodString;
 /**
- * Container ID or name schema
- * Validates non-empty string for container identification
+ * Container ID or name schema with comprehensive validation
+ *
+ * SECURITY: Prevents command injection (CWE-78) by validating Docker container identifiers.
+ * Docker API accepts three formats for container identification:
+ *
+ * 1. **Container Name**: User-defined name assigned with `--name` flag
+ *    - Must start with alphanumeric character (prevents option injection like `-evil`)
+ *    - Allowed characters: alphanumeric, underscore, hyphen, dot
+ *    - Examples: `nginx`, `my-web-app`, `app_service_1`, `plex.v2`
+ *    - Max length: 256 characters (practical limit for Docker names)
+ *
+ * 2. **Short ID**: First 12 characters of the full container ID
+ *    - Exactly 12 lowercase hexadecimal characters
+ *    - Examples: `abc123def456`, `0123456789ab`
+ *
+ * 3. **Full ID**: Complete 64-character SHA256 hash
+ *    - Exactly 64 lowercase hexadecimal characters
+ *    - Examples: `abc123def456...` (64 chars total)
+ *
+ * @note Docker IDs are always lowercase. Uppercase hex is rejected to prevent
+ * ambiguity with container names and ensure consistent identification.
+ *
+ * @note This schema is used with Docker's `getContainer()` API which accepts
+ * any of these three formats. The API handles the lookup internally.
+ *
+ * @example Valid container names
+ * ```typescript
+ * containerIdSchema.parse("nginx");           // Simple name
+ * containerIdSchema.parse("my-web-app");      // Name with hyphens
+ * containerIdSchema.parse("app_service_1");   // Compose generated name
+ * containerIdSchema.parse("plex.v2");         // Name with dots
+ * ```
+ *
+ * @example Valid Docker IDs
+ * ```typescript
+ * containerIdSchema.parse("abc123def456");    // Short ID (12 hex)
+ * containerIdSchema.parse("a".repeat(64));    // Full ID (64 hex)
+ * ```
+ *
+ * @example Invalid formats (throw ZodError)
+ * ```typescript
+ * containerIdSchema.parse("-evil");           // Starts with hyphen
+ * containerIdSchema.parse("app; rm -rf /");   // Shell metacharacters
+ * containerIdSchema.parse("ABC123DEF456");    // Uppercase hex rejected
+ * containerIdSchema.parse("abc123def45");     // 11 chars (invalid ID length)
+ * containerIdSchema.parse("xyz123456789");    // VALID as container name (not a hex ID)
+ * ```
+ *
+ * @see {@link https://docs.docker.com/engine/api/v1.43/#tag/Container}
  */
 export declare const containerIdSchema: z.ZodString;
 /**
@@ -38,11 +88,158 @@ export declare const projectSchema: z.ZodString;
  */
 export declare const imageSchema: z.ZodString;
 /**
- * Preprocessor to inject composite discriminator key
- * Used by Flux tool to create action_subaction from action + subaction
+ * Schema for grep patterns passed to shell commands.
+ *
+ * @description Strict validation that blocks shell metacharacters to prevent
+ * command injection (CWE-78). Use this ONLY for patterns passed to shell
+ * commands like `grep`, `awk`, or other CLI tools via SSH or exec.
+ *
+ * This schema intentionally rejects common log message characters like
+ * brackets `[]`, quotes `'"`, and parentheses `()` because these have
+ * special meaning in shell contexts and could enable injection attacks.
+ *
+ * @example
+ * // CORRECT - For shell grep commands (scout-logs)
+ * const scoutLogsSchema = z.object({
+ *   host: hostSchema,
+ *   grep: shellGrepSchema.optional()  // Passed to: grep -E "${pattern}"
+ * });
+ *
+ * @example
+ * // Valid patterns for shell grep
+ * shellGrepSchema.parse("error");           // Simple word
+ * shellGrepSchema.parse("connection reset"); // Words with spaces
+ * shellGrepSchema.parse("nginx.*failed");   // Basic regex
+ * shellGrepSchema.parse("status: 5..");     // Numbers and punctuation
+ *
+ * @example
+ * // INVALID - These throw ZodError
+ * shellGrepSchema.parse("[ERROR]");    // Brackets are shell metacharacters
+ * shellGrepSchema.parse("'admin'");    // Quotes are shell metacharacters
+ * shellGrepSchema.parse("$(whoami)");  // Command substitution attempt
+ * shellGrepSchema.parse("foo; rm -rf"); // Command chaining attempt
+ *
+ * @example
+ * // INCORRECT - Don't use for JavaScript filtering
+ * // For client-side String.includes() matching, use jsFilterSchema instead
+ * // which allows brackets, quotes, and other common log characters
+ *
+ * @see {@link jsFilterSchema} for JavaScript-side filtering with String.includes()
+ */
+export declare const shellGrepSchema: z.ZodString;
+/**
+ * Backwards-compatible alias for existing schema imports.
+ */
+export declare const safeGrepSchema: z.ZodString;
+/**
+ * Schema for filter patterns used in JavaScript String.includes() matching.
+ *
+ * @description Relaxed validation for patterns that are ONLY used client-side
+ * in JavaScript with `String.includes()`. These patterns are never passed to
+ * shell commands, so shell metacharacters are safe to allow.
+ *
+ * This schema allows characters commonly found in log messages that would be
+ * rejected by shellGrepSchema:
+ * - Brackets: `[ERROR]`, `[INFO]`, `[2024-01-15]`
+ * - Quotes: `User 'admin'`, `key="value"`
+ * - Parentheses: `(deprecated)`, `method(arg)`
+ * - Special chars: `$PATH`, `a|b`, `foo;bar`
+ *
+ * Only control characters (0x00-0x1F) are rejected to prevent log injection
+ * and display corruption.
+ *
+ * @example
+ * // CORRECT - For JavaScript String.includes() filtering
+ * const containerLogsSchema = z.object({
+ *   container: containerIdSchema,
+ *   filter: jsFilterSchema.optional()  // Used with: line.includes(filter)
+ * });
+ *
+ * @example
+ * // Valid patterns for JS filtering (allows log message syntax)
+ * jsFilterSchema.parse("[ERROR]");           // Brackets allowed
+ * jsFilterSchema.parse("User 'admin'");      // Quotes allowed
+ * jsFilterSchema.parse("status=(failed)");   // Parentheses allowed
+ * jsFilterSchema.parse("key=\"value\"");     // Escaped quotes allowed
+ * jsFilterSchema.parse("path: /var/log");    // Forward slashes allowed
+ *
+ * @example
+ * // INVALID - These throw ZodError
+ * jsFilterSchema.parse("line\ninjection");   // Newlines are control chars
+ * jsFilterSchema.parse("has\ttab");          // Tabs are control chars
+ * jsFilterSchema.parse("null\x00byte");      // Null bytes rejected
+ *
+ * @example
+ * // INCORRECT - Don't use for shell commands
+ * // For patterns passed to grep/awk via SSH, use shellGrepSchema instead
+ * // which blocks shell metacharacters for security
+ *
+ * @see {@link shellGrepSchema} for shell-safe grep patterns
+ */
+export declare const jsFilterSchema: z.ZodString;
+/**
+ * ZFS pool name schema with security validation
+ * SECURITY: Prevents command injection (CWE-78) by rejecting shell metacharacters
+ * Valid characters: alphanumeric, underscore, hyphen, period
+ * Must start with a letter (per ZFS naming requirements)
+ * Does NOT allow forward slash (pools are top-level only)
+ */
+export declare const zfsPoolSchema: z.ZodString;
+/**
+ * ZFS dataset name schema with security validation
+ * SECURITY: Prevents command injection (CWE-78) by rejecting shell metacharacters
+ * Valid characters: alphanumeric, underscore, hyphen, period, forward slash, @, #
+ * Must start with a letter (per ZFS naming requirements)
+ * Allows hierarchical paths like tank/data/backup
+ * Allows snapshot notation like tank/data@snap
+ * Allows bookmark notation like tank/data#bookmark
+ *
+ * Note: Colon (:) is intentionally excluded. While ZFS allows it for user properties
+ * (e.g., com.example:property), this schema is for dataset/snapshot/bookmark paths only.
+ * If user property support is needed, create a separate zfsPropertySchema.
+ */
+export declare const zfsDatasetSchema: z.ZodString;
+/**
+ * Exec user schema with security validation
+ * SECURITY: Prevents command injection by validating Docker exec user format
+ * Valid formats:
+ *   - Simple username: root, www-data, app_user
+ *   - Numeric UID: 1000
+ *   - UID:GID: 1000:1000
+ *   - username:groupname: www-data:www-data
+ * Must start with alphanumeric or underscore (not hyphen to prevent option injection)
+ */
+export declare const execUserSchema: z.ZodString;
+/**
+ * Exec workdir schema with security validation
+ * SECURITY: Prevents path traversal and command injection
+ * Requirements:
+ *   - Must be an absolute path (starts with /)
+ *   - Only allows safe characters: alphanumeric, underscore, hyphen, period, forward slash
+ *   - Does NOT allow: shell metacharacters, directory traversal (..), variable expansion ($)
+ *
+ * @note The root path `/` is intentionally allowed. Some Docker containers
+ * (especially minimal/distroless or scratch-based images) have very minimal
+ * filesystems where `/` may be the only valid working directory. Additionally,
+ * many official images use `/` as the default WORKDIR. Restricting this would
+ * break legitimate use cases.
+ *
+ * @example Valid paths
+ * ```typescript
+ * execWorkdirSchema.parse("/")              // Root path (allowed for minimal containers)
+ * execWorkdirSchema.parse("/app")           // Simple absolute path
+ * execWorkdirSchema.parse("/var/lib/data")  // Nested path
+ * execWorkdirSchema.parse("/app-v1.0")      // Path with dashes and dots
+ * ```
  *
- * Transforms: { action: "container", subaction: "list" }
- * To: { action: "container", subaction: "list", action_subaction: "container:list" }
+ * @example Invalid paths
+ * ```typescript
+ * execWorkdirSchema.parse("app")            // Relative path (no leading /)
+ * execWorkdirSchema.parse("/app/../etc")    // Directory traversal
+ * execWorkdirSchema.parse("/app; rm -rf /") // Shell metacharacters
+ * execWorkdirSchema.parse("/app/$HOME")     // Variable expansion
+ * execWorkdirSchema.parse("/path with spaces") // Spaces not allowed
+ * ```
  */
-export declare function preprocessWithDiscriminator(data: unknown): unknown;
+export declare const execWorkdirSchema: z.ZodString;
 //# sourceMappingURL=common.d.ts.map

package/dist/schemas/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C;;;GAGG;AACH,eAAO,MAAM,oBAAoB,gDAGiB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;iBAS3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,aAIU,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAAqD,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,aAAa,aAA4D,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,WAAW,aAA6D,CAAC;AAEtF;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAMlE"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;GAGiB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;iBAS3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,aAIU,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,iBAAiB,aA8CK,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,aAAa,aAIgB,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,WAAW,aAA6D,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,eAAe,aAK6C,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,cAAc,aAAkB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,cAAc,aAc4C,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,aAQE,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,aAQkE,CAAC;AAEhG;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,aAQwC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB,aAWoB,CAAC"}

package/dist/schemas/common.js

@@ -6,14 +6,14 @@
  * All schemas here are designed to be composable and reusable.
  */
 import { z } from "zod";
-import { ResponseFormat } from "../types.js";
 import { DEFAULT_LIMIT, MAX_LIMIT } from "../constants.js";
+import { ResponseFormat } from "../types.js";
 /**
  * Response format schema for output formatting
  * Defaults to markdown for human-readable output
  */
 export const responseFormatSchema = z
-    .nativeEnum(ResponseFormat)
+    .enum(Object.values(ResponseFormat))
     .default(ResponseFormat.MARKDOWN)
     .describe("Output format: 'markdown' or 'json'");
 /**
@@ -28,7 +28,7 @@ export const paginationSchema = z.object({
         .max(MAX_LIMIT)
         .default(DEFAULT_LIMIT)
         .describe("Maximum results to return"),
-    offset: z.number().int().min(0).default(0).describe("Number of results to skip for pagination")
+    offset: z.number().int().min(0).default(0).describe("Number of results to skip for pagination"),
 });
 /**
  * Host name schema with validation
@@ -40,30 +40,303 @@ export const hostSchema = z
     .regex(/^[a-zA-Z0-9_-]+$/, "Host must be alphanumeric with dashes/underscores")
     .describe("Target Docker host");
 /**
- * Container ID or name schema
- * Validates non-empty string for container identification
+ * Container ID or name schema with comprehensive validation
+ *
+ * SECURITY: Prevents command injection (CWE-78) by validating Docker container identifiers.
+ * Docker API accepts three formats for container identification:
+ *
+ * 1. **Container Name**: User-defined name assigned with `--name` flag
+ *    - Must start with alphanumeric character (prevents option injection like `-evil`)
+ *    - Allowed characters: alphanumeric, underscore, hyphen, dot
+ *    - Examples: `nginx`, `my-web-app`, `app_service_1`, `plex.v2`
+ *    - Max length: 256 characters (practical limit for Docker names)
+ *
+ * 2. **Short ID**: First 12 characters of the full container ID
+ *    - Exactly 12 lowercase hexadecimal characters
+ *    - Examples: `abc123def456`, `0123456789ab`
+ *
+ * 3. **Full ID**: Complete 64-character SHA256 hash
+ *    - Exactly 64 lowercase hexadecimal characters
+ *    - Examples: `abc123def456...` (64 chars total)
+ *
+ * @note Docker IDs are always lowercase. Uppercase hex is rejected to prevent
+ * ambiguity with container names and ensure consistent identification.
+ *
+ * @note This schema is used with Docker's `getContainer()` API which accepts
+ * any of these three formats. The API handles the lookup internally.
+ *
+ * @example Valid container names
+ * ```typescript
+ * containerIdSchema.parse("nginx");           // Simple name
+ * containerIdSchema.parse("my-web-app");      // Name with hyphens
+ * containerIdSchema.parse("app_service_1");   // Compose generated name
+ * containerIdSchema.parse("plex.v2");         // Name with dots
+ * ```
+ *
+ * @example Valid Docker IDs
+ * ```typescript
+ * containerIdSchema.parse("abc123def456");    // Short ID (12 hex)
+ * containerIdSchema.parse("a".repeat(64));    // Full ID (64 hex)
+ * ```
+ *
+ * @example Invalid formats (throw ZodError)
+ * ```typescript
+ * containerIdSchema.parse("-evil");           // Starts with hyphen
+ * containerIdSchema.parse("app; rm -rf /");   // Shell metacharacters
+ * containerIdSchema.parse("ABC123DEF456");    // Uppercase hex rejected
+ * containerIdSchema.parse("abc123def45");     // 11 chars (invalid ID length)
+ * containerIdSchema.parse("xyz123456789");    // VALID as container name (not a hex ID)
+ * ```
+ *
+ * @see {@link https://docs.docker.com/engine/api/v1.43/#tag/Container}
  */
-export const containerIdSchema = z.string().min(1).describe("Container name or ID");
+export const containerIdSchema = z
+    .string()
+    .trim()
+    .min(1, "Container ID or name cannot be empty")
+    .max(256, "Container name too long (max 256 characters)")
+    .refine((val) => {
+    // Pattern 1: Short ID (exactly 12 lowercase hex chars)
+    const shortIdPattern = /^[a-f0-9]{12}$/;
+    if (shortIdPattern.test(val))
+        return true;
+    // Pattern 2: Full ID (exactly 64 lowercase hex chars)
+    const fullIdPattern = /^[a-f0-9]{64}$/;
+    if (fullIdPattern.test(val))
+        return true;
+    // Pattern 3: Container Name
+    // Must start with alphanumeric, then alphanumeric/underscore/hyphen/dot
+    const namePattern = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+    if (!namePattern.test(val))
+        return false;
+    // Additional validation: reject strings that look like malformed IDs
+    // If string is ONLY hex chars (no separators) and looks like a malformed ID, reject it
+    const onlyHexPattern = /^[a-fA-F0-9]+$/;
+    if (onlyHexPattern.test(val)) {
+        // Reject if it's close to valid ID lengths (potential typo/malformed ID)
+        const len = val.length;
+        if ((len >= 11 && len <= 13) || (len >= 63 && len <= 65)) {
+            return false; // Likely a malformed ID
+        }
+        // Reject uppercase hex (Docker IDs are always lowercase)
+        if (/[A-F]/.test(val) && len >= 11) {
+            return false; // Uppercase hex that looks like an ID
+        }
+    }
+    // Valid container name
+    return true;
+}, {
+    message: "Container identifier must be either:\n" +
+        "  • Container name (alphanumeric with _-. allowed, must start with alphanumeric)\n" +
+        "  • Short ID (exactly 12 lowercase hex characters)\n" +
+        "  • Full ID (exactly 64 lowercase hex characters)",
+})
+    .describe("Container name or ID");
 /**
  * Project name schema for Docker Compose
  */
-export const projectSchema = z.string().min(1).describe("Docker Compose project name");
+export const projectSchema = z
+    .string()
+    .min(1)
+    .regex(/^[a-zA-Z0-9_-]+$/, "Project name must be alphanumeric with dashes/underscores")
+    .describe("Docker Compose project name");
 /**
  * Image name schema with optional tag
  */
 export const imageSchema = z.string().min(1).describe("Image name with optional tag");
 /**
- * Preprocessor to inject composite discriminator key
- * Used by Flux tool to create action_subaction from action + subaction
+ * Schema for grep patterns passed to shell commands.
+ *
+ * @description Strict validation that blocks shell metacharacters to prevent
+ * command injection (CWE-78). Use this ONLY for patterns passed to shell
+ * commands like `grep`, `awk`, or other CLI tools via SSH or exec.
+ *
+ * This schema intentionally rejects common log message characters like
+ * brackets `[]`, quotes `'"`, and parentheses `()` because these have
+ * special meaning in shell contexts and could enable injection attacks.
+ *
+ * @example
+ * // CORRECT - For shell grep commands (scout-logs)
+ * const scoutLogsSchema = z.object({
+ *   host: hostSchema,
+ *   grep: shellGrepSchema.optional()  // Passed to: grep -E "${pattern}"
+ * });
+ *
+ * @example
+ * // Valid patterns for shell grep
+ * shellGrepSchema.parse("error");           // Simple word
+ * shellGrepSchema.parse("connection reset"); // Words with spaces
+ * shellGrepSchema.parse("nginx.*failed");   // Basic regex
+ * shellGrepSchema.parse("status: 5..");     // Numbers and punctuation
+ *
+ * @example
+ * // INVALID - These throw ZodError
+ * shellGrepSchema.parse("[ERROR]");    // Brackets are shell metacharacters
+ * shellGrepSchema.parse("'admin'");    // Quotes are shell metacharacters
+ * shellGrepSchema.parse("$(whoami)");  // Command substitution attempt
+ * shellGrepSchema.parse("foo; rm -rf"); // Command chaining attempt
+ *
+ * @example
+ * // INCORRECT - Don't use for JavaScript filtering
+ * // For client-side String.includes() matching, use jsFilterSchema instead
+ * // which allows brackets, quotes, and other common log characters
+ *
+ * @see {@link jsFilterSchema} for JavaScript-side filtering with String.includes()
+ */
+export const shellGrepSchema = z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[^;&|`$()<>{}[\]\\"\n\r\t']+$/, "Grep pattern contains shell metacharacters")
+    .describe("Shell-safe grep pattern (shell metacharacters not allowed)");
+/**
+ * Backwards-compatible alias for existing schema imports.
+ */
+export const safeGrepSchema = shellGrepSchema;
+/**
+ * Schema for filter patterns used in JavaScript String.includes() matching.
  *
- * Transforms: { action: "container", subaction: "list" }
- * To: { action: "container", subaction: "list", action_subaction: "container:list" }
+ * @description Relaxed validation for patterns that are ONLY used client-side
+ * in JavaScript with `String.includes()`. These patterns are never passed to
+ * shell commands, so shell metacharacters are safe to allow.
+ *
+ * This schema allows characters commonly found in log messages that would be
+ * rejected by shellGrepSchema:
+ * - Brackets: `[ERROR]`, `[INFO]`, `[2024-01-15]`
+ * - Quotes: `User 'admin'`, `key="value"`
+ * - Parentheses: `(deprecated)`, `method(arg)`
+ * - Special chars: `$PATH`, `a|b`, `foo;bar`
+ *
+ * Only control characters (0x00-0x1F) are rejected to prevent log injection
+ * and display corruption.
+ *
+ * @example
+ * // CORRECT - For JavaScript String.includes() filtering
+ * const containerLogsSchema = z.object({
+ *   container: containerIdSchema,
+ *   filter: jsFilterSchema.optional()  // Used with: line.includes(filter)
+ * });
+ *
+ * @example
+ * // Valid patterns for JS filtering (allows log message syntax)
+ * jsFilterSchema.parse("[ERROR]");           // Brackets allowed
+ * jsFilterSchema.parse("User 'admin'");      // Quotes allowed
+ * jsFilterSchema.parse("status=(failed)");   // Parentheses allowed
+ * jsFilterSchema.parse("key=\"value\"");     // Escaped quotes allowed
+ * jsFilterSchema.parse("path: /var/log");    // Forward slashes allowed
+ *
+ * @example
+ * // INVALID - These throw ZodError
+ * jsFilterSchema.parse("line\ninjection");   // Newlines are control chars
+ * jsFilterSchema.parse("has\ttab");          // Tabs are control chars
+ * jsFilterSchema.parse("null\x00byte");      // Null bytes rejected
+ *
+ * @example
+ * // INCORRECT - Don't use for shell commands
+ * // For patterns passed to grep/awk via SSH, use shellGrepSchema instead
+ * // which blocks shell metacharacters for security
+ *
+ * @see {@link shellGrepSchema} for shell-safe grep patterns
  */
-export function preprocessWithDiscriminator(data) {
-    if (data && typeof data === "object" && "action" in data && "subaction" in data) {
-        const obj = data;
-        return { ...obj, action_subaction: `${obj.action}:${obj.subaction}` };
+export const jsFilterSchema = z
+    .string()
+    .min(1)
+    .max(500)
+    .refine((s) => {
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code >= 0 && code <= 31)
+            return false;
     }
-    return data;
-}
+    return true;
+}, { message: "Filter pattern contains control characters" })
+    .describe("Filter pattern for JavaScript String.includes() matching");
+/**
+ * ZFS pool name schema with security validation
+ * SECURITY: Prevents command injection (CWE-78) by rejecting shell metacharacters
+ * Valid characters: alphanumeric, underscore, hyphen, period
+ * Must start with a letter (per ZFS naming requirements)
+ * Does NOT allow forward slash (pools are top-level only)
+ */
+export const zfsPoolSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_\-.]*$/, "Pool name must start with a letter and contain only alphanumeric, dashes, underscores, or periods")
+    .describe("ZFS pool name");
+/**
+ * ZFS dataset name schema with security validation
+ * SECURITY: Prevents command injection (CWE-78) by rejecting shell metacharacters
+ * Valid characters: alphanumeric, underscore, hyphen, period, forward slash, @, #
+ * Must start with a letter (per ZFS naming requirements)
+ * Allows hierarchical paths like tank/data/backup
+ * Allows snapshot notation like tank/data@snap
+ * Allows bookmark notation like tank/data#bookmark
+ *
+ * Note: Colon (:) is intentionally excluded. While ZFS allows it for user properties
+ * (e.g., com.example:property), this schema is for dataset/snapshot/bookmark paths only.
+ * If user property support is needed, create a separate zfsPropertySchema.
+ */
+export const zfsDatasetSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_\-./@#]*$/, "Dataset name must start with a letter and contain only alphanumeric, dashes, underscores, periods, slashes, @, or #")
+    .describe("ZFS dataset name (can include path like pool/dataset, snapshot @, or bookmark #)");
+/**
+ * Exec user schema with security validation
+ * SECURITY: Prevents command injection by validating Docker exec user format
+ * Valid formats:
+ *   - Simple username: root, www-data, app_user
+ *   - Numeric UID: 1000
+ *   - UID:GID: 1000:1000
+ *   - username:groupname: www-data:www-data
+ * Must start with alphanumeric or underscore (not hyphen to prevent option injection)
+ */
+export const execUserSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z0-9_][a-zA-Z0-9_-]*(?::[a-zA-Z0-9_][a-zA-Z0-9_-]*)?$|^\d+(?::\d+)?$/, "User must be a valid username, uid, username:groupname, or uid:gid format")
+    .describe("User to run command as (e.g., root, 1000, 1000:1000)");
+/**
+ * Exec workdir schema with security validation
+ * SECURITY: Prevents path traversal and command injection
+ * Requirements:
+ *   - Must be an absolute path (starts with /)
+ *   - Only allows safe characters: alphanumeric, underscore, hyphen, period, forward slash
+ *   - Does NOT allow: shell metacharacters, directory traversal (..), variable expansion ($)
+ *
+ * @note The root path `/` is intentionally allowed. Some Docker containers
+ * (especially minimal/distroless or scratch-based images) have very minimal
+ * filesystems where `/` may be the only valid working directory. Additionally,
+ * many official images use `/` as the default WORKDIR. Restricting this would
+ * break legitimate use cases.
+ *
+ * @example Valid paths
+ * ```typescript
+ * execWorkdirSchema.parse("/")              // Root path (allowed for minimal containers)
+ * execWorkdirSchema.parse("/app")           // Simple absolute path
+ * execWorkdirSchema.parse("/var/lib/data")  // Nested path
+ * execWorkdirSchema.parse("/app-v1.0")      // Path with dashes and dots
+ * ```
+ *
+ * @example Invalid paths
+ * ```typescript
+ * execWorkdirSchema.parse("app")            // Relative path (no leading /)
+ * execWorkdirSchema.parse("/app/../etc")    // Directory traversal
+ * execWorkdirSchema.parse("/app; rm -rf /") // Shell metacharacters
+ * execWorkdirSchema.parse("/app/$HOME")     // Variable expansion
+ * execWorkdirSchema.parse("/path with spaces") // Spaces not allowed
+ * ```
+ */
+export const execWorkdirSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^\/[a-zA-Z0-9_\-./]*$/, "Working directory must be an absolute path with safe characters only")
+    .refine((path) => !path.includes(".."), {
+    message: "Working directory cannot contain directory traversal (..)",
+})
+    .describe("Absolute path for working directory");
 //# sourceMappingURL=common.js.map

package/dist/schemas/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,UAAU,CAAC,cAAc,CAAC;KAC1B,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC;KAChC,QAAQ,CAAC,qCAAqC,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,SAAS,CAAC;SACd,OAAO,CAAC,aAAa,CAAC;SACtB,QAAQ,CAAC,2BAA2B,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CAChG,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,KAAK,CAAC,kBAAkB,EAAE,mDAAmD,CAAC;KAC9E,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;AAEpF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAa;IACvD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,QAAQ,IAAI,IAAI,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QAChF,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,OAAO,EAAE,GAAG,GAAG,EAAE,gBAAgB,EAAE,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAA0C,CAAC;KAC5E,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC;KAChC,QAAQ,CAAC,qCAAqC,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,SAAS,CAAC;SACd,OAAO,CAAC,aAAa,CAAC;SACtB,QAAQ,CAAC,2BAA2B,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CAChG,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,KAAK,CAAC,kBAAkB,EAAE,mDAAmD,CAAC;KAC9E,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,EAAE,sCAAsC,CAAC;KAC9C,GAAG,CAAC,GAAG,EAAE,8CAA8C,CAAC;KACxD,MAAM,CACL,CAAC,GAAG,EAAE,EAAE;IACN,uDAAuD;IACvD,MAAM,cAAc,GAAG,gBAAgB,CAAC;IACxC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1C,sDAAsD;IACtD,MAAM,aAAa,GAAG,gBAAgB,CAAC;IACvC,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,4BAA4B;IAC5B,wEAAwE;IACxE,MAAM,WAAW,GAAG,8BAA8B,CAAC;IACnD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzC,qEAAqE;IACrE,uFAAuF;IACvF,MAAM,cAAc,GAAG,gBAAgB,CAAC;IACxC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,yEAAyE;QACzE,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;QACvB,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;YACzD,OAAO,KAAK,CAAC,CAAC,wBAAwB;QACxC,CAAC;QACD,yDAAyD;QACzD,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC,CAAC,sCAAsC;QACtD,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,OAAO,IAAI,CAAC;AACd,CAAC,EACD;IACE,OAAO,EACL,wCAAwC;QACxC,oFAAoF;QACpF,sDAAsD;QACtD,mDAAmD;CACtD,CACF;KACA,QAAQ,CAAC,sBAAsB,CAAC,CAAC;AAEpC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,KAAK,CAAC,kBAAkB,EAAE,2DAA2D,CAAC;KACtF,QAAQ,CAAC,6BAA6B,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,gCAAgC,EAAE,4CAA4C,CAAC;KACrF,QAAQ,CAAC,4DAA4D,CAAC,CAAC;AAE1E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,MAAM,CACL,CAAC,CAAC,EAAE,EAAE;IACJ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE;YAAE,OAAO,KAAK,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,EACD,EAAE,OAAO,EAAE,4CAA4C,EAAE,CAC1D;KACA,QAAQ,CAAC,0DAA0D,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CACJ,4BAA4B,EAC5B,mGAAmG,CACpG;KACA,QAAQ,CAAC,eAAe,CAAC,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CACJ,+BAA+B,EAC/B,qHAAqH,CACtH;KACA,QAAQ,CAAC,kFAAkF,CAAC,CAAC;AAEhG;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,EAAE,CAAC;KACP,KAAK,CACJ,6EAA6E,EAC7E,2EAA2E,CAC5E;KACA,QAAQ,CAAC,sDAAsD,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC;KACT,KAAK,CACJ,uBAAuB,EACvB,sEAAsE,CACvE;KACA,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;IACtC,OAAO,EAAE,2DAA2D;CACrE,CAAC;KACD,QAAQ,CAAC,qCAAqC,CAAC,CAAC"}