@herdctl/core 2.1.0 → 3.0.1

package/dist/state/utils/path-safety.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Path safety utilities for state file operations
+ *
+ * Provides defense-in-depth protection against path traversal attacks
+ * when constructing file paths from user-controlled identifiers.
+ */
+/**
+ * Error thrown when a path traversal attempt is detected
+ */
+export declare class PathTraversalError extends Error {
+    readonly baseDir: string;
+    readonly identifier: string;
+    readonly resultPath: string;
+    constructor(baseDir: string, identifier: string, resultPath: string);
+}
+/**
+ * Pattern for valid identifiers (agent names, etc.)
+ * Must start with alphanumeric, can contain alphanumeric, underscore, hyphen
+ */
+export declare const SAFE_IDENTIFIER_PATTERN: RegExp;
+/**
+ * Validate that an identifier is safe for use in file paths
+ *
+ * @param identifier - The identifier to validate (agent name, etc.)
+ * @returns true if valid, false if not
+ */
+export declare function isValidIdentifier(identifier: string): boolean;
+/**
+ * Build a safe file path within a base directory
+ *
+ * This function provides defense-in-depth by:
+ * 1. Checking the identifier against a safe pattern
+ * 2. Resolving the final path and verifying it stays within the base directory
+ *
+ * @param baseDir - The base directory that the file must stay within
+ * @param identifier - The user-provided identifier (agent name, etc.)
+ * @param extension - File extension including the dot (e.g., ".json", ".yaml")
+ * @returns The safe, resolved file path
+ * @throws PathTraversalError if the path would escape the base directory
+ *
+ * @example
+ * ```typescript
+ * const filePath = buildSafeFilePath("/home/user/.herdctl/sessions", "my-agent", ".json");
+ * // Returns: "/home/user/.herdctl/sessions/my-agent.json"
+ *
+ * // This would throw PathTraversalError:
+ * buildSafeFilePath("/home/user/.herdctl/sessions", "../../../etc/passwd", ".json");
+ * ```
+ */
+export declare function buildSafeFilePath(baseDir: string, identifier: string, extension: string): string;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/state/utils/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../../src/state/utils/path-safety.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CASpE;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAgC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAuBR"}

package/dist/state/utils/path-safety.js

@@ -0,0 +1,75 @@
+/**
+ * Path safety utilities for state file operations
+ *
+ * Provides defense-in-depth protection against path traversal attacks
+ * when constructing file paths from user-controlled identifiers.
+ */
+import { resolve, join } from "node:path";
+/**
+ * Error thrown when a path traversal attempt is detected
+ */
+export class PathTraversalError extends Error {
+    baseDir;
+    identifier;
+    resultPath;
+    constructor(baseDir, identifier, resultPath) {
+        super(`Path traversal detected: identifier "${identifier}" would resolve to "${resultPath}" which is outside base directory "${baseDir}"`);
+        this.name = "PathTraversalError";
+        this.baseDir = baseDir;
+        this.identifier = identifier;
+        this.resultPath = resultPath;
+    }
+}
+/**
+ * Pattern for valid identifiers (agent names, etc.)
+ * Must start with alphanumeric, can contain alphanumeric, underscore, hyphen
+ */
+export const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/**
+ * Validate that an identifier is safe for use in file paths
+ *
+ * @param identifier - The identifier to validate (agent name, etc.)
+ * @returns true if valid, false if not
+ */
+export function isValidIdentifier(identifier) {
+    return SAFE_IDENTIFIER_PATTERN.test(identifier);
+}
+/**
+ * Build a safe file path within a base directory
+ *
+ * This function provides defense-in-depth by:
+ * 1. Checking the identifier against a safe pattern
+ * 2. Resolving the final path and verifying it stays within the base directory
+ *
+ * @param baseDir - The base directory that the file must stay within
+ * @param identifier - The user-provided identifier (agent name, etc.)
+ * @param extension - File extension including the dot (e.g., ".json", ".yaml")
+ * @returns The safe, resolved file path
+ * @throws PathTraversalError if the path would escape the base directory
+ *
+ * @example
+ * ```typescript
+ * const filePath = buildSafeFilePath("/home/user/.herdctl/sessions", "my-agent", ".json");
+ * // Returns: "/home/user/.herdctl/sessions/my-agent.json"
+ *
+ * // This would throw PathTraversalError:
+ * buildSafeFilePath("/home/user/.herdctl/sessions", "../../../etc/passwd", ".json");
+ * ```
+ */
+export function buildSafeFilePath(baseDir, identifier, extension) {
+    // First line of defense: validate identifier format
+    if (!isValidIdentifier(identifier)) {
+        throw new PathTraversalError(baseDir, identifier, `(invalid identifier: must match ${SAFE_IDENTIFIER_PATTERN})`);
+    }
+    // Construct the file path
+    const fileName = `${identifier}${extension}`;
+    const filePath = join(baseDir, fileName);
+    // Second line of defense: verify the resolved path stays within baseDir
+    const resolvedBase = resolve(baseDir);
+    const resolvedPath = resolve(filePath);
+    if (!resolvedPath.startsWith(resolvedBase + "/") && resolvedPath !== resolvedBase) {
+        throw new PathTraversalError(baseDir, identifier, resolvedPath);
+    }
+    return filePath;
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/state/utils/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../../src/state/utils/path-safety.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3B,OAAO,CAAS;IAChB,UAAU,CAAS;IACnB,UAAU,CAAS;IAEnC,YAAY,OAAe,EAAE,UAAkB,EAAE,UAAkB;QACjE,KAAK,CACH,wCAAwC,UAAU,uBAAuB,UAAU,sCAAsC,OAAO,GAAG,CACpI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAErE;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,OAAO,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,UAAkB,EAClB,SAAiB;IAEjB,oDAAoD;IACpD,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,kBAAkB,CAC1B,OAAO,EACP,UAAU,EACV,mCAAmC,uBAAuB,GAAG,CAC9D,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,MAAM,QAAQ,GAAG,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAEzC,wEAAwE;IACxE,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,GAAG,GAAG,CAAC,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;QAClF,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herdctl/core",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Core library for herdctl fleet management",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "zod": "^3.22.0"
   },
   "peerDependencies": {
-    "@herdctl/discord": "0.1.7"
+    "@herdctl/discord": "0.1.9"
   },
   "peerDependenciesMeta": {
     "@herdctl/discord": {