claude-flow-novice 2.15.11 → 2.16.0

package/dist/integration/trigger-dev-webhooks.js

@@ -0,0 +1,362 @@
+/**
+ * Trigger.dev Webhook Handlers for CFN Loop Integration
+ *
+ * Express router providing secure webhook endpoints for:
+ * - Agent completion events
+ * - Gate check results
+ * - Consensus collection results
+ * - Product Owner decisions
+ *
+ * Configuration:
+ * - WEBHOOK_SECRET: Shared secret for HMAC signature verification
+ * - WEBHOOK_ALGORITHM: Hash algorithm (default: sha256)
+ */ import { Router } from 'express';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Webhook validation error class
+ */ export class WebhookValidationError extends Error {
+    reason;
+    statusCode;
+    constructor(message, reason, statusCode = 401){
+        super(message), this.reason = reason, this.statusCode = statusCode;
+        this.name = 'WebhookValidationError';
+    }
+}
+/**
+ * TriggerDevWebhooks - Express router for secure webhook handling
+ *
+ * Provides endpoints:
+ * - POST /webhooks/agent-complete
+ * - POST /webhooks/gate-result
+ * - POST /webhooks/consensus-result
+ * - POST /webhooks/po-decision
+ */ export class TriggerDevWebhooks {
+    router;
+    config;
+    verificationOptions;
+    // Handler maps for dependency injection
+    agentCompleteHandler;
+    gateResultHandler;
+    consensusResultHandler;
+    poDecisionHandler;
+    constructor(config){
+        this.router = Router();
+        this.config = {
+            secret: config?.secret || process.env.WEBHOOK_SECRET || 'default-secret',
+            algorithm: config?.algorithm || process.env.WEBHOOK_ALGORITHM || 'sha256',
+            verifySignature: config?.verifySignature !== false
+        };
+        this.verificationOptions = {
+            algorithmType: this.config.algorithm || 'sha256',
+            headerName: 'x-trigger-signature'
+        };
+        this.setupRoutes();
+    }
+    /**
+   * Register handler for agent completion events
+   */ onAgentComplete(handler) {
+        this.agentCompleteHandler = handler;
+        return this;
+    }
+    /**
+   * Register handler for gate result events
+   */ onGateResult(handler) {
+        this.gateResultHandler = handler;
+        return this;
+    }
+    /**
+   * Register handler for consensus result events
+   */ onConsensusResult(handler) {
+        this.consensusResultHandler = handler;
+        return this;
+    }
+    /**
+   * Register handler for Product Owner decision events
+   */ onPODecision(handler) {
+        this.poDecisionHandler = handler;
+        return this;
+    }
+    /**
+   * Get Express router for mounting
+   */ getRouter() {
+        return this.router;
+    }
+    /**
+   * Setup all webhook routes
+   *
+   * @private
+   */ setupRoutes() {
+        // Middleware for signature verification
+        this.router.use(this.signatureVerificationMiddleware.bind(this));
+        // Agent completion endpoint
+        this.router.post('/agent-complete', this.handleAgentComplete.bind(this));
+        // Gate result endpoint
+        this.router.post('/gate-result', this.handleGateResult.bind(this));
+        // Consensus result endpoint
+        this.router.post('/consensus-result', this.handleConsensusResult.bind(this));
+        // PO decision endpoint
+        this.router.post('/po-decision', this.handlePODecision.bind(this));
+        // Error handling middleware
+        this.router.use(this.errorHandler.bind(this));
+    }
+    /**
+   * Signature verification middleware
+   *
+   * TODO: RUNTIME_TEST: Verify HMAC signature validation with valid/invalid keys
+   *
+   * @private
+   */ async signatureVerificationMiddleware(req, res, next) {
+        try {
+            if (!this.config.verifySignature) {
+                return next();
+            }
+            const signature = req.headers[this.verificationOptions.headerName];
+            if (!signature) {
+                throw new WebhookValidationError('Missing webhook signature', 'MISSING_SIGNATURE');
+            }
+            const body = JSON.stringify(req.body);
+            const isValid = await this.verifySignature(body, signature);
+            if (!isValid) {
+                throw new WebhookValidationError('Invalid webhook signature', 'INVALID_SIGNATURE');
+            }
+            next();
+        } catch (error) {
+            if (error instanceof WebhookValidationError) {
+                return res.status(error.statusCode).json({
+                    success: false,
+                    message: error.message,
+                    reason: error.reason
+                });
+            }
+            return res.status(500).json({
+                success: false,
+                message: 'Signature verification failed',
+                reason: 'INTERNAL_ERROR'
+            });
+        }
+    }
+    /**
+   * Handle agent completion webhook
+   *
+   * @private
+   */ async handleAgentComplete(req, res) {
+        try {
+            const payload = req.body;
+            // Validate required fields
+            if (!payload.agentId || !payload.taskId) {
+                return res.status(400).json({
+                    success: false,
+                    message: 'Missing required fields',
+                    data: null
+                });
+            }
+            const context = {
+                payload,
+                isVerified: this.config.verifySignature,
+                timestamp: Date.now(),
+                signature: req.headers[this.verificationOptions.headerName]
+            };
+            if (this.agentCompleteHandler) {
+                const result = await this.agentCompleteHandler(context);
+                return res.status(200).json(result);
+            }
+            res.status(200).json({
+                success: true,
+                message: 'Agent completion event received',
+                data: {
+                    agentId: payload.agentId
+                }
+            });
+        } catch (error) {
+            return res.status(500).json({
+                success: false,
+                message: 'Failed to handle agent completion',
+                data: null
+            });
+        }
+    }
+    /**
+   * Handle gate result webhook
+   *
+   * @private
+   */ async handleGateResult(req, res) {
+        try {
+            const payload = req.body;
+            if (!payload.taskId || payload.gateType === undefined) {
+                return res.status(400).json({
+                    success: false,
+                    message: 'Missing required fields',
+                    data: null
+                });
+            }
+            const context = {
+                payload,
+                isVerified: this.config.verifySignature,
+                timestamp: Date.now(),
+                signature: req.headers[this.verificationOptions.headerName]
+            };
+            if (this.gateResultHandler) {
+                const result = await this.gateResultHandler(context);
+                return res.status(200).json(result);
+            }
+            res.status(200).json({
+                success: true,
+                message: 'Gate result received',
+                data: {
+                    taskId: payload.taskId,
+                    passed: payload.passed
+                }
+            });
+        } catch (error) {
+            return res.status(500).json({
+                success: false,
+                message: 'Failed to handle gate result',
+                data: null
+            });
+        }
+    }
+    /**
+   * Handle consensus result webhook
+   *
+   * @private
+   */ async handleConsensusResult(req, res) {
+        try {
+            const payload = req.body;
+            if (!payload.taskId || payload.validatorCount === undefined) {
+                return res.status(400).json({
+                    success: false,
+                    message: 'Missing required fields',
+                    data: null
+                });
+            }
+            const context = {
+                payload,
+                isVerified: this.config.verifySignature,
+                timestamp: Date.now(),
+                signature: req.headers[this.verificationOptions.headerName]
+            };
+            if (this.consensusResultHandler) {
+                const result = await this.consensusResultHandler(context);
+                return res.status(200).json(result);
+            }
+            res.status(200).json({
+                success: true,
+                message: 'Consensus result received',
+                data: {
+                    taskId: payload.taskId,
+                    consensusScore: payload.consensusScore
+                }
+            });
+        } catch (error) {
+            return res.status(500).json({
+                success: false,
+                message: 'Failed to handle consensus result',
+                data: null
+            });
+        }
+    }
+    /**
+   * Handle Product Owner decision webhook
+   *
+   * @private
+   */ async handlePODecision(req, res) {
+        try {
+            const payload = req.body;
+            if (!payload.taskId || !payload.decision) {
+                return res.status(400).json({
+                    success: false,
+                    message: 'Missing required fields',
+                    data: null
+                });
+            }
+            // Validate decision enum
+            if (![
+                'PROCEED',
+                'ITERATE',
+                'ABORT'
+            ].includes(payload.decision)) {
+                return res.status(400).json({
+                    success: false,
+                    message: 'Invalid decision value',
+                    data: null
+                });
+            }
+            const context = {
+                payload,
+                isVerified: this.config.verifySignature,
+                timestamp: Date.now(),
+                signature: req.headers[this.verificationOptions.headerName]
+            };
+            if (this.poDecisionHandler) {
+                const result = await this.poDecisionHandler(context);
+                return res.status(200).json(result);
+            }
+            res.status(200).json({
+                success: true,
+                message: 'PO decision received',
+                data: {
+                    taskId: payload.taskId,
+                    decision: payload.decision
+                }
+            });
+        } catch (error) {
+            return res.status(500).json({
+                success: false,
+                message: 'Failed to handle PO decision',
+                data: null
+            });
+        }
+    }
+    /**
+   * Verify HMAC signature of webhook payload
+   *
+   * @private
+   * @param payload Raw request body as string
+   * @param signature Signature header value
+   * @returns Promise resolving to true if signature is valid
+   */ async verifySignature(payload, signature) {
+        try {
+            const hmac = createHmac(this.verificationOptions.algorithmType, this.config.secret);
+            hmac.update(payload, 'utf8');
+            const expectedSignature = hmac.digest('hex');
+            // Use timing-safe comparison
+            return timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+        } catch (error) {
+            console.error('Signature verification error:', error);
+            return false;
+        }
+    }
+    /**
+   * Error handling middleware
+   *
+   * @private
+   */ errorHandler(error, req, res, next) {
+        console.error('Webhook error:', error);
+        res.status(500).json({
+            success: false,
+            message: 'Internal server error',
+            data: null
+        });
+    }
+}
+/**
+ * Create webhook router with optional handlers
+ */ export const createWebhookRouter = (config, handlers)=>{
+    const webhooks = new TriggerDevWebhooks(config);
+    if (handlers?.onAgentComplete) {
+        webhooks.onAgentComplete(handlers.onAgentComplete);
+    }
+    if (handlers?.onGateResult) {
+        webhooks.onGateResult(handlers.onGateResult);
+    }
+    if (handlers?.onConsensusResult) {
+        webhooks.onConsensusResult(handlers.onConsensusResult);
+    }
+    if (handlers?.onPODecision) {
+        webhooks.onPODecision(handlers.onPODecision);
+    }
+    return webhooks.getRouter();
+};
+export default TriggerDevWebhooks;
+
+//# sourceMappingURL=trigger-dev-webhooks.js.map

package/dist/integration/trigger-dev-webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integration/trigger-dev-webhooks.ts"],"sourcesContent":["/**\r\n * Trigger.dev Webhook Handlers for CFN Loop Integration\r\n *\r\n * Express router providing secure webhook endpoints for:\r\n * - Agent completion events\r\n * - Gate check results\r\n * - Consensus collection results\r\n * - Product Owner decisions\r\n *\r\n * Configuration:\r\n * - WEBHOOK_SECRET: Shared secret for HMAC signature verification\r\n * - WEBHOOK_ALGORITHM: Hash algorithm (default: sha256)\r\n */\r\n\r\nimport { Router } from 'express';\r\nimport type { Request, Response, NextFunction } from 'express';\r\nimport { createHmac, timingSafeEqual } from 'node:crypto';\r\n\r\nimport type {\r\n  AgentCompletePayload,\r\n  GateResultPayload,\r\n  ConsensusResultPayload,\r\n  PODecisionPayload,\r\n  WebhookContext,\r\n  WebhookHandlerResult,\r\n  WebhookVerificationOptions,\r\n} from '../types/trigger-dev-events.d.js';\r\n\r\n/**\r\n * Webhook validation error class\r\n */\r\nexport class WebhookValidationError extends Error {\r\n  constructor(\r\n    message: string,\r\n    public readonly reason: string,\r\n    public readonly statusCode: number = 401\r\n  ) {\r\n    super(message);\r\n    this.name = 'WebhookValidationError';\r\n  }\r\n}\r\n\r\n/**\r\n * Webhook handler type\r\n */\r\nexport type WebhookHandler<T> = (\r\n  context: WebhookContext<T>\r\n) => Promise<WebhookHandlerResult>;\r\n\r\n/**\r\n * Configuration for webhook handlers\r\n */\r\nexport interface WebhookConfig {\r\n  secret?: string;\r\n  algorithm?: string;\r\n  verifySignature?: boolean;\r\n}\r\n\r\n/**\r\n * TriggerDevWebhooks - Express router for secure webhook handling\r\n *\r\n * Provides endpoints:\r\n * - POST /webhooks/agent-complete\r\n * - POST /webhooks/gate-result\r\n * - POST /webhooks/consensus-result\r\n * - POST /webhooks/po-decision\r\n */\r\nexport class TriggerDevWebhooks {\r\n  private readonly router: Router;\r\n  private readonly config: Required<WebhookConfig>;\r\n  private readonly verificationOptions: WebhookVerificationOptions;\r\n\r\n  // Handler maps for dependency injection\r\n  private agentCompleteHandler?: WebhookHandler<AgentCompletePayload>;\r\n  private gateResultHandler?: WebhookHandler<GateResultPayload>;\r\n  private consensusResultHandler?: WebhookHandler<ConsensusResultPayload>;\r\n  private poDecisionHandler?: WebhookHandler<PODecisionPayload>;\r\n\r\n  constructor(config?: WebhookConfig) {\r\n    this.router = Router();\r\n    this.config = {\r\n      secret: config?.secret || process.env.WEBHOOK_SECRET || 'default-secret',\r\n      algorithm: config?.algorithm || process.env.WEBHOOK_ALGORITHM || 'sha256',\r\n      verifySignature: config?.verifySignature !== false,\r\n    };\r\n\r\n    this.verificationOptions = {\r\n      algorithmType: (this.config.algorithm as 'sha256' | 'sha512') || 'sha256',\r\n      headerName: 'x-trigger-signature',\r\n    };\r\n\r\n    this.setupRoutes();\r\n  }\r\n\r\n  /**\r\n   * Register handler for agent completion events\r\n   */\r\n  onAgentComplete(handler: WebhookHandler<AgentCompletePayload>): this {\r\n    this.agentCompleteHandler = handler;\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Register handler for gate result events\r\n   */\r\n  onGateResult(handler: WebhookHandler<GateResultPayload>): this {\r\n    this.gateResultHandler = handler;\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Register handler for consensus result events\r\n   */\r\n  onConsensusResult(handler: WebhookHandler<ConsensusResultPayload>): this {\r\n    this.consensusResultHandler = handler;\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Register handler for Product Owner decision events\r\n   */\r\n  onPODecision(handler: WebhookHandler<PODecisionPayload>): this {\r\n    this.poDecisionHandler = handler;\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Get Express router for mounting\r\n   */\r\n  getRouter(): Router {\r\n    return this.router;\r\n  }\r\n\r\n  /**\r\n   * Setup all webhook routes\r\n   *\r\n   * @private\r\n   */\r\n  private setupRoutes(): void {\r\n    // Middleware for signature verification\r\n    this.router.use(this.signatureVerificationMiddleware.bind(this));\r\n\r\n    // Agent completion endpoint\r\n    this.router.post('/agent-complete', this.handleAgentComplete.bind(this));\r\n\r\n    // Gate result endpoint\r\n    this.router.post('/gate-result', this.handleGateResult.bind(this));\r\n\r\n    // Consensus result endpoint\r\n    this.router.post('/consensus-result', this.handleConsensusResult.bind(this));\r\n\r\n    // PO decision endpoint\r\n    this.router.post('/po-decision', this.handlePODecision.bind(this));\r\n\r\n    // Error handling middleware\r\n    this.router.use(this.errorHandler.bind(this));\r\n  }\r\n\r\n  /**\r\n   * Signature verification middleware\r\n   *\r\n   * TODO: RUNTIME_TEST: Verify HMAC signature validation with valid/invalid keys\r\n   *\r\n   * @private\r\n   */\r\n  private async signatureVerificationMiddleware(\r\n    req: Request,\r\n    res: Response,\r\n    next: NextFunction\r\n  ): Promise<void> {\r\n    try {\r\n      if (!this.config.verifySignature) {\r\n        return next();\r\n      }\r\n\r\n      const signature = req.headers[this.verificationOptions.headerName];\r\n\r\n      if (!signature) {\r\n        throw new WebhookValidationError(\r\n          'Missing webhook signature',\r\n          'MISSING_SIGNATURE'\r\n        );\r\n      }\r\n\r\n      const body = JSON.stringify(req.body);\r\n      const isValid = await this.verifySignature(body, signature as string);\r\n\r\n      if (!isValid) {\r\n        throw new WebhookValidationError(\r\n          'Invalid webhook signature',\r\n          'INVALID_SIGNATURE'\r\n        );\r\n      }\r\n\r\n      next();\r\n    } catch (error) {\r\n      if (error instanceof WebhookValidationError) {\r\n        return res.status(error.statusCode).json({\r\n          success: false,\r\n          message: error.message,\r\n          reason: error.reason,\r\n        });\r\n      }\r\n\r\n      return res.status(500).json({\r\n        success: false,\r\n        message: 'Signature verification failed',\r\n        reason: 'INTERNAL_ERROR',\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Handle agent completion webhook\r\n   *\r\n   * @private\r\n   */\r\n  private async handleAgentComplete(\r\n    req: Request,\r\n    res: Response\r\n  ): Promise<void> {\r\n    try {\r\n      const payload = req.body as AgentCompletePayload;\r\n\r\n      // Validate required fields\r\n      if (!payload.agentId || !payload.taskId) {\r\n        return res.status(400).json({\r\n          success: false,\r\n          message: 'Missing required fields',\r\n          data: null,\r\n        });\r\n      }\r\n\r\n      const context: WebhookContext<AgentCompletePayload> = {\r\n        payload,\r\n        isVerified: this.config.verifySignature,\r\n        timestamp: Date.now(),\r\n        signature: req.headers[this.verificationOptions.headerName] as string,\r\n      };\r\n\r\n      if (this.agentCompleteHandler) {\r\n        const result = await this.agentCompleteHandler(context);\r\n        return res.status(200).json(result);\r\n      }\r\n\r\n      res.status(200).json({\r\n        success: true,\r\n        message: 'Agent completion event received',\r\n        data: { agentId: payload.agentId },\r\n      });\r\n    } catch (error) {\r\n      return res.status(500).json({\r\n        success: false,\r\n        message: 'Failed to handle agent completion',\r\n        data: null,\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Handle gate result webhook\r\n   *\r\n   * @private\r\n   */\r\n  private async handleGateResult(req: Request, res: Response): Promise<void> {\r\n    try {\r\n      const payload = req.body as GateResultPayload;\r\n\r\n      if (!payload.taskId || payload.gateType === undefined) {\r\n        return res.status(400).json({\r\n          success: false,\r\n          message: 'Missing required fields',\r\n          data: null,\r\n        });\r\n      }\r\n\r\n      const context: WebhookContext<GateResultPayload> = {\r\n        payload,\r\n        isVerified: this.config.verifySignature,\r\n        timestamp: Date.now(),\r\n        signature: req.headers[this.verificationOptions.headerName] as string,\r\n      };\r\n\r\n      if (this.gateResultHandler) {\r\n        const result = await this.gateResultHandler(context);\r\n        return res.status(200).json(result);\r\n      }\r\n\r\n      res.status(200).json({\r\n        success: true,\r\n        message: 'Gate result received',\r\n        data: { taskId: payload.taskId, passed: payload.passed },\r\n      });\r\n    } catch (error) {\r\n      return res.status(500).json({\r\n        success: false,\r\n        message: 'Failed to handle gate result',\r\n        data: null,\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Handle consensus result webhook\r\n   *\r\n   * @private\r\n   */\r\n  private async handleConsensusResult(\r\n    req: Request,\r\n    res: Response\r\n  ): Promise<void> {\r\n    try {\r\n      const payload = req.body as ConsensusResultPayload;\r\n\r\n      if (!payload.taskId || payload.validatorCount === undefined) {\r\n        return res.status(400).json({\r\n          success: false,\r\n          message: 'Missing required fields',\r\n          data: null,\r\n        });\r\n      }\r\n\r\n      const context: WebhookContext<ConsensusResultPayload> = {\r\n        payload,\r\n        isVerified: this.config.verifySignature,\r\n        timestamp: Date.now(),\r\n        signature: req.headers[this.verificationOptions.headerName] as string,\r\n      };\r\n\r\n      if (this.consensusResultHandler) {\r\n        const result = await this.consensusResultHandler(context);\r\n        return res.status(200).json(result);\r\n      }\r\n\r\n      res.status(200).json({\r\n        success: true,\r\n        message: 'Consensus result received',\r\n        data: {\r\n          taskId: payload.taskId,\r\n          consensusScore: payload.consensusScore,\r\n        },\r\n      });\r\n    } catch (error) {\r\n      return res.status(500).json({\r\n        success: false,\r\n        message: 'Failed to handle consensus result',\r\n        data: null,\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Handle Product Owner decision webhook\r\n   *\r\n   * @private\r\n   */\r\n  private async handlePODecision(req: Request, res: Response): Promise<void> {\r\n    try {\r\n      const payload = req.body as PODecisionPayload;\r\n\r\n      if (!payload.taskId || !payload.decision) {\r\n        return res.status(400).json({\r\n          success: false,\r\n          message: 'Missing required fields',\r\n          data: null,\r\n        });\r\n      }\r\n\r\n      // Validate decision enum\r\n      if (!['PROCEED', 'ITERATE', 'ABORT'].includes(payload.decision)) {\r\n        return res.status(400).json({\r\n          success: false,\r\n          message: 'Invalid decision value',\r\n          data: null,\r\n        });\r\n      }\r\n\r\n      const context: WebhookContext<PODecisionPayload> = {\r\n        payload,\r\n        isVerified: this.config.verifySignature,\r\n        timestamp: Date.now(),\r\n        signature: req.headers[this.verificationOptions.headerName] as string,\r\n      };\r\n\r\n      if (this.poDecisionHandler) {\r\n        const result = await this.poDecisionHandler(context);\r\n        return res.status(200).json(result);\r\n      }\r\n\r\n      res.status(200).json({\r\n        success: true,\r\n        message: 'PO decision received',\r\n        data: { taskId: payload.taskId, decision: payload.decision },\r\n      });\r\n    } catch (error) {\r\n      return res.status(500).json({\r\n        success: false,\r\n        message: 'Failed to handle PO decision',\r\n        data: null,\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Verify HMAC signature of webhook payload\r\n   *\r\n   * @private\r\n   * @param payload Raw request body as string\r\n   * @param signature Signature header value\r\n   * @returns Promise resolving to true if signature is valid\r\n   */\r\n  private async verifySignature(\r\n    payload: string,\r\n    signature: string\r\n  ): Promise<boolean> {\r\n    try {\r\n      const hmac = createHmac(\r\n        this.verificationOptions.algorithmType,\r\n        this.config.secret\r\n      );\r\n      hmac.update(payload, 'utf8');\r\n      const expectedSignature = hmac.digest('hex');\r\n\r\n      // Use timing-safe comparison\r\n      return timingSafeEqual(\r\n        Buffer.from(signature),\r\n        Buffer.from(expectedSignature)\r\n      );\r\n    } catch (error) {\r\n      console.error('Signature verification error:', error);\r\n      return false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Error handling middleware\r\n   *\r\n   * @private\r\n   */\r\n  private errorHandler(\r\n    error: Error,\r\n    req: Request,\r\n    res: Response,\r\n    next: NextFunction\r\n  ): void {\r\n    console.error('Webhook error:', error);\r\n\r\n    res.status(500).json({\r\n      success: false,\r\n      message: 'Internal server error',\r\n      data: null,\r\n    });\r\n  }\r\n}\r\n\r\n/**\r\n * Create webhook router with optional handlers\r\n */\r\nexport const createWebhookRouter = (\r\n  config?: WebhookConfig,\r\n  handlers?: {\r\n    onAgentComplete?: WebhookHandler<AgentCompletePayload>;\r\n    onGateResult?: WebhookHandler<GateResultPayload>;\r\n    onConsensusResult?: WebhookHandler<ConsensusResultPayload>;\r\n    onPODecision?: WebhookHandler<PODecisionPayload>;\r\n  }\r\n): Router => {\r\n  const webhooks = new TriggerDevWebhooks(config);\r\n\r\n  if (handlers?.onAgentComplete) {\r\n    webhooks.onAgentComplete(handlers.onAgentComplete);\r\n  }\r\n  if (handlers?.onGateResult) {\r\n    webhooks.onGateResult(handlers.onGateResult);\r\n  }\r\n  if (handlers?.onConsensusResult) {\r\n    webhooks.onConsensusResult(handlers.onConsensusResult);\r\n  }\r\n  if (handlers?.onPODecision) {\r\n    webhooks.onPODecision(handlers.onPODecision);\r\n  }\r\n\r\n  return webhooks.getRouter();\r\n};\r\n\r\nexport default TriggerDevWebhooks;\r\n"],"names":["Router","createHmac","timingSafeEqual","WebhookValidationError","Error","message","reason","statusCode","name","TriggerDevWebhooks","router","config","verificationOptions","agentCompleteHandler","gateResultHandler","consensusResultHandler","poDecisionHandler","secret","process","env","WEBHOOK_SECRET","algorithm","WEBHOOK_ALGORITHM","verifySignature","algorithmType","headerName","setupRoutes","onAgentComplete","handler","onGateResult","onConsensusResult","onPODecision","getRouter","use","signatureVerificationMiddleware","bind","post","handleAgentComplete","handleGateResult","handleConsensusResult","handlePODecision","errorHandler","req","res","next","signature","headers","body","JSON","stringify","isValid","error","status","json","success","payload","agentId","taskId","data","context","isVerified","timestamp","Date","now","result","gateType","undefined","passed","validatorCount","consensusScore","decision","includes","hmac","update","expectedSignature","digest","Buffer","from","console","createWebhookRouter","handlers","webhooks"],"mappings":"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"}

package/dist/lib/path-validator.js

@@ -60,9 +60,15 @@ import { StandardError } from './errors';
         try {
             decoded = decodeURIComponent(decoded);
         } catch (error) {
-            // Invalid URL encoding (including malformed UTF-8) indicates attack
-            // e.g., %c0%ae is malformed UTF-8 for overlong encoding
-            invalidEncodingDetected = true;
+            // Invalid URL encoding can be legitimate (e.g., file100%, %PATH%)
+            // These are literal percent signs in filenames, not attacks
+            // Only flag as attack if it's malformed UTF-8 (overlong encoding)
+            const errorMessage = error.message || '';
+            // Malformed UTF-8 sequences like %c0%ae are attacks
+            if (decoded.match(/%[cC][0-9a-fA-F]/) || decoded.match(/%[eE][0-9a-fA-F]/)) {
+                invalidEncodingDetected = true;
+                break;
+            }
             break;
         }
         iterations++;
@@ -85,8 +91,11 @@ import { StandardError } from './errors';
             reason: 'INVALID_ENCODING_DETECTED'
         });
     }
-    // Detect if decoding required multiple iterations (possible double-encoding attack)
-    const encodingAttackDetected = iterations > 1;
+    // Detect double+ encoding attacks (3+ iterations = double-encoded or more)
+    // Single-level URL encoding requires 2 iterations: decode + stability check
+    // Example: subdir%2ffile.txt → subdir/file.txt → stable (2 iterations, legitimate)
+    // Example: %252e%252e%252f → %2e%2e%2f → ../ (3 iterations, attack)
+    const encodingAttackDetected = iterations > 2;
     // Unicode normalization to handle overlong UTF-8 sequences
     // e.g., %c0%ae (%c0%ae = UTF-8 overlong encoding for ".")
     let normalized = decoded;

package/dist/lib/path-validator.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/path-validator.ts"],"sourcesContent":["/**\r\n * Path Validator - Security Utility for Safe File Operations\r\n *\r\n * Provides robust path sanitization and validation to prevent path traversal attacks (CVSS 7.0+).\r\n * Enforces strict rules on file access with protection against encoding attacks:\r\n *\r\n * CRITICAL FIXES (CVSS 7.0+):\r\n * - Iterative URL decoding prevents double-encoding bypasses (%252e%252e%252f → ../)\r\n * - Unicode normalization (NFC) prevents overlong UTF-8 bypasses (%c0%ae → .)\r\n * - Null byte detection prevents null injection attacks\r\n * - All decoding performed BEFORE path normalization to prevent layered attacks\r\n * - Encoding attack detection with security logging\r\n *\r\n * Base Security Controls:\r\n * - Path normalization to resolve \"..\" and \".\" sequences\r\n * - Validation that resolved paths stay within allowed directories\r\n * - Detection and rejection of symlinks\r\n * - Rejection of absolute paths outside allowed directories\r\n * - Prevention of home directory access (\"~\")\r\n *\r\n * @module path-validator\r\n * @version 2.0.0 (SECURITY CRITICAL)\r\n */\r\n\r\nimport * as path from 'path';\r\nimport * as fs from 'fs';\r\nimport { StandardError } from './errors';\r\n\r\n/**\r\n * Path validation error - thrown when a path violates security constraints\r\n */\r\nexport class PathValidationError extends StandardError {\r\n  constructor(message: string, context?: Record<string, unknown>) {\r\n    super('PATH_VALIDATION_ERROR', message, context);\r\n    this.name = 'PathValidationError';\r\n  }\r\n}\r\n\r\n/**\r\n * Security encoding attack detection\r\n */\r\nexport interface EncodingAttackDetection {\r\n  detected: boolean;\r\n  type?: 'double_encoding' | 'unicode_encoding' | 'mixed_encoding';\r\n  originalInput: string;\r\n  decodedOutput: string;\r\n  iterationsRequired: number;\r\n}\r\n\r\n/**\r\n * Path validation result with detailed information\r\n */\r\nexport interface PathValidationResult {\r\n  valid: boolean;\r\n  resolvedPath: string;\r\n  normalizedPath: string;\r\n  isWithinBase: boolean;\r\n  isSymlink: boolean;\r\n  reason?: string;\r\n}\r\n\r\n/**\r\n * Safely decode a path with protection against encoding attacks\r\n *\r\n * Performs iterative URL decoding and Unicode normalization to prevent:\r\n * - Double encoding bypass (e.g., %252e%252e%252f → %2e%2e%2f → ../)\r\n * - Overlong UTF-8 encoding (e.g., %c0%ae%c0%ae/ → ../)\r\n * - Mixed encoding attacks\r\n *\r\n * @param inputPath - The potentially encoded path\r\n * @returns Decoded path and attack detection info\r\n * @throws PathValidationError if encoding attack detected\r\n *\r\n * @example\r\n * const { decoded, encoding } = decodePathSafely('%252e%252e%252f');\r\n * // Detects double-encoding attempt\r\n */\r\nfunction decodePathSafely(inputPath: string): {\r\n  decoded: string;\r\n  encoding: EncodingAttackDetection;\r\n} {\r\n  let decoded = inputPath;\r\n  let previous = '';\r\n  let iterations = 0;\r\n  const MAX_ITERATIONS = 5;\r\n  const originalInput = inputPath;\r\n  let invalidEncodingDetected = false;\r\n\r\n  // Iteratively decode URL-encoded characters until stable\r\n  // This prevents bypass attacks using multiple encoding layers\r\n  while (decoded !== previous && iterations < MAX_ITERATIONS) {\r\n    previous = decoded;\r\n    try {\r\n      decoded = decodeURIComponent(decoded);\r\n    } catch (error) {\r\n      // Invalid URL encoding (including malformed UTF-8) indicates attack\r\n      // e.g., %c0%ae is malformed UTF-8 for overlong encoding\r\n      invalidEncodingDetected = true;\r\n      // Treat invalid encoding as a suspicious attack indicator\r\n      // but continue with the path as-is for analysis\r\n      break;\r\n    }\r\n    iterations++;\r\n  }\r\n\r\n  // Check if we hit max iterations (indicates potential encoding attack)\r\n  if (iterations >= MAX_ITERATIONS && decoded !== previous) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: excessive encoding layers detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'ENCODING_ATTACK_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Invalid encoding like malformed UTF-8 is itself an attack indicator\r\n  if (invalidEncodingDetected) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: invalid encoding detected (possible encoding attack)',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'INVALID_ENCODING_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Detect if decoding required multiple iterations (possible double-encoding attack)\r\n  const encodingAttackDetected = iterations > 1;\r\n\r\n  // Unicode normalization to handle overlong UTF-8 sequences\r\n  // e.g., %c0%ae (%c0%ae = UTF-8 overlong encoding for \".\")\r\n  let normalized = decoded;\r\n  try {\r\n    normalized = decoded.normalize('NFC');\r\n  } catch (error) {\r\n    // Some paths may not be valid Unicode, continue with non-normalized version\r\n  }\r\n\r\n  // Check for null bytes (another common encoding attack vector)\r\n  if (normalized.includes('\\0')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: null byte injection detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: normalized,\r\n        reason: 'NULL_BYTE_INJECTION',\r\n      }\r\n    );\r\n  }\r\n\r\n  return {\r\n    decoded: normalized,\r\n    encoding: {\r\n      detected: encodingAttackDetected,\r\n      type: encodingAttackDetected ? 'double_encoding' : undefined,\r\n      originalInput,\r\n      decodedOutput: normalized,\r\n      iterationsRequired: iterations,\r\n    },\r\n  };\r\n}\r\n\r\n/**\r\n * Validate a file path to prevent directory traversal attacks\r\n *\r\n * Security checks performed (in order):\r\n * 1. CRITICAL: Iteratively decode URL encoding to handle %252e%252e%252f and similar bypasses\r\n * 2. CRITICAL: Normalize Unicode (NFC) to handle overlong UTF-8 like %c0%ae%c0%ae/\r\n * 3. CRITICAL: Detect null bytes and excessive encoding layers\r\n * 4. Check for home directory expansion (\"~\") on DECODED path\r\n * 5. Normalize path to resolve \"..\" and \".\"\r\n * 6. Verify all suspicious patterns are eliminated\r\n * 7. Check if path is within base directory\r\n * 8. Reject symlinks to prevent symlink attacks\r\n * 9. Log any encoding attacks detected for security monitoring\r\n *\r\n * @param filePath - The file path to validate (may be encoded)\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns PathValidationResult with validation details\r\n * @throws PathValidationError if path validation fails or encoding attack detected\r\n *\r\n * @example\r\n * const result = validatePath('docs/FEATURE.md', './.claude/skills');\r\n * if (!result.valid) {\r\n *   throw result; // Safe to throw, contains all context\r\n * }\r\n * // Use result.resolvedPath\r\n *\r\n * @security\r\n * Designed to prevent:\r\n * - Double-encoding bypasses: %252e%252e%252f\r\n * - Overlong UTF-8: %c0%ae%c0%ae/\r\n * - Mixed encoding: URL + Unicode combinations\r\n * - Null byte injection: file.txt%00.jpg\r\n * - Traditional path traversal: ../../../etc/passwd\r\n */\r\nexport function validatePath(filePath: string, baseDirectory: string): PathValidationResult {\r\n  // SECURITY FIX: Decode all encoding layers first before any path normalization\r\n  // This prevents double-encoding bypasses like %252e%252e%252f\r\n  const { decoded: decodedPath, encoding: pathEncoding } = decodePathSafely(filePath);\r\n  const { decoded: decodedBase } = decodePathSafely(baseDirectory);\r\n\r\n  // Log encoding attacks for security monitoring\r\n  if (pathEncoding.detected) {\r\n    // In production, this should trigger security alerts\r\n    console.warn('Security: Encoding attack detected in path input', {\r\n      originalInput: pathEncoding.originalInput,\r\n      decodedOutput: pathEncoding.decodedOutput,\r\n      iterationsRequired: pathEncoding.iterationsRequired,\r\n    });\r\n  }\r\n\r\n  // Check for home directory expansion attempts on DECODED path\r\n  if (decodedPath.startsWith('~') || decodedPath.includes('/~') || decodedPath.includes('\\\\~')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: home directory access denied',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        baseDirectory,\r\n        reason: 'HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for home directory expansion attempts in baseDirectory\r\n  if (decodedBase.startsWith('~')) {\r\n    throw new PathValidationError(\r\n      'Base directory validation failed: home directory access denied',\r\n      {\r\n        baseDirectory,\r\n        decodedBase,\r\n        reason: 'BASE_HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Normalize the base directory first\r\n  const normalizedBase = path.normalize(decodedBase);\r\n  const resolvedBase = path.resolve(normalizedBase);\r\n\r\n  // Normalize and resolve the file path relative to base\r\n  // NOW normalized on already-decoded path to prevent encoding bypasses\r\n  const normalizedPath = path.normalize(decodedPath);\r\n\r\n  // Check if path contains suspicious patterns after normalization\r\n  if (normalizedPath.includes('..') || normalizedPath === '.' || normalizedPath.includes('/./')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: path contains directory traversal patterns',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        normalizedPath,\r\n        baseDirectory,\r\n        reason: 'TRAVERSAL_PATTERN_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Resolve the path relative to base directory\r\n  const resolvedPath = path.resolve(resolvedBase, normalizedPath);\r\n\r\n  // Check if resolved path is within base directory\r\n  const isWithinBase = isPathWithinBase(resolvedPath, resolvedBase);\r\n\r\n  if (!isWithinBase) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: resolved path is outside allowed directory',\r\n      {\r\n        filePath,\r\n        resolvedPath,\r\n        baseDirectory: resolvedBase,\r\n        reason: 'PATH_OUTSIDE_BASE',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for symlinks (prevents symlink attacks)\r\n  let isSymlink = false;\r\n  try {\r\n    const stats = fs.lstatSync(resolvedPath);\r\n    isSymlink = stats.isSymbolicLink();\r\n\r\n    if (isSymlink) {\r\n      throw new PathValidationError(\r\n        'Path validation failed: symbolic links are not allowed',\r\n        {\r\n          filePath,\r\n          resolvedPath,\r\n          reason: 'SYMLINK_NOT_ALLOWED',\r\n        }\r\n      );\r\n    }\r\n  } catch (error) {\r\n    // File doesn't exist yet (expected for validation before creation)\r\n    // or it's a symlink that was rejected above\r\n    if (error instanceof PathValidationError) {\r\n      throw error;\r\n    }\r\n    // Other errors (permission denied, etc.) are not path validation failures\r\n    // The file validation happens later\r\n  }\r\n\r\n  return {\r\n    valid: true,\r\n    resolvedPath,\r\n    normalizedPath,\r\n    isWithinBase: true,\r\n    isSymlink: false,\r\n  };\r\n}\r\n\r\n/**\r\n * Check if a path is within a base directory\r\n *\r\n * Uses path resolution and string comparison to ensure the resolved path\r\n * is actually within the base directory (not just sharing a prefix).\r\n *\r\n * @param filePath - The path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if filePath is within baseDirectory\r\n *\r\n * @example\r\n * isPathWithinBase('/home/user/project/src/file.ts', '/home/user/project')  // true\r\n * isPathWithinBase('/home/user/project-evil/file.ts', '/home/user/project') // false\r\n */\r\nexport function isPathWithinBase(filePath: string, baseDirectory: string): boolean {\r\n  // Ensure both paths are normalized and absolute\r\n  const normalizedFile = path.normalize(path.resolve(filePath));\r\n  const normalizedBase = path.normalize(path.resolve(baseDirectory));\r\n\r\n  // Exact match\r\n  if (normalizedFile === normalizedBase) {\r\n    return true;\r\n  }\r\n\r\n  // Check if file is within base (use path.relative to ensure it's not going up)\r\n  const relative = path.relative(normalizedBase, normalizedFile);\r\n\r\n  // If relative path starts with \"..\", it's outside the base directory\r\n  if (relative.startsWith('..')) {\r\n    return false;\r\n  }\r\n\r\n  // If relative path is absolute, it's outside the base directory\r\n  if (path.isAbsolute(relative)) {\r\n    return false;\r\n  }\r\n\r\n  return true;\r\n}\r\n\r\n/**\r\n * Validate multiple paths within the same base directory\r\n *\r\n * Efficiently validates multiple paths, returning results for each.\r\n *\r\n * @param filePaths - Array of file paths to validate\r\n * @param baseDirectory - The base directory that all files must reside within\r\n * @returns Map of file path to validation result\r\n *\r\n * @example\r\n * const results = validatePaths(['docs/SKILL.md', 'src/index.ts'], './.claude/skills');\r\n * results.forEach((result, filePath) => {\r\n *   if (!result.valid) {\r\n *     console.error(`Invalid path: ${filePath}`, result.reason);\r\n *   }\r\n * });\r\n */\r\nexport function validatePaths(\r\n  filePaths: string[],\r\n  baseDirectory: string\r\n): Map<string, PathValidationResult> {\r\n  const results = new Map<string, PathValidationResult>();\r\n\r\n  for (const filePath of filePaths) {\r\n    try {\r\n      const result = validatePath(filePath, baseDirectory);\r\n      results.set(filePath, result);\r\n    } catch (error) {\r\n      if (error instanceof PathValidationError) {\r\n        results.set(filePath, {\r\n          valid: false,\r\n          resolvedPath: '',\r\n          normalizedPath: '',\r\n          isWithinBase: false,\r\n          isSymlink: false,\r\n          reason: error.context?.reason as string | undefined,\r\n        });\r\n      } else {\r\n        throw error;\r\n      }\r\n    }\r\n  }\r\n\r\n  return results;\r\n}\r\n\r\n/**\r\n * Get the safe path for a file (or throw if validation fails)\r\n *\r\n * Convenience function that validates and returns the resolved path,\r\n * or throws an error if validation fails.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns The resolved, validated absolute path\r\n * @throws PathValidationError if path validation fails\r\n *\r\n * @example\r\n * const safePath = getSafePath('docs/SKILL.md', './.claude/skills');\r\n * fs.readFileSync(safePath); // Safe to use\r\n */\r\nexport function getSafePath(filePath: string, baseDirectory: string): string {\r\n  const result = validatePath(filePath, baseDirectory);\r\n  return result.resolvedPath;\r\n}\r\n\r\n/**\r\n * Check if a path is considered safe for operations\r\n *\r\n * This is a non-throwing version of validatePath for conditional logic.\r\n *\r\n * @param filePath - The file path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if path is safe, false otherwise\r\n *\r\n * @example\r\n * if (isPathSafe(userInput, './.claude/skills')) {\r\n *   // Process the file\r\n * } else {\r\n *   // Reject the request\r\n * }\r\n */\r\nexport function isPathSafe(filePath: string, baseDirectory: string): boolean {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Get validation error details for a path (if invalid)\r\n *\r\n * Useful for logging and diagnostics.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory\r\n * @returns Error with details, or undefined if path is valid\r\n *\r\n * @example\r\n * const error = getPathValidationError('../../etc/passwd', './.claude/skills');\r\n * if (error) {\r\n *   logger.error(error.message, error.context);\r\n * }\r\n */\r\nexport function getPathValidationError(\r\n  filePath: string,\r\n  baseDirectory: string\r\n): PathValidationError | undefined {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return undefined;\r\n  } catch (error) {\r\n    if (error instanceof PathValidationError) {\r\n      return error;\r\n    }\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * List allowed files within a base directory (safely)\r\n *\r\n * Recursively lists all files within base directory, validating\r\n * each path to ensure it's within bounds.\r\n *\r\n * @param baseDirectory - The base directory to scan\r\n * @param options - Options for listing (maxDepth, filter)\r\n * @returns Array of validated, safe paths relative to baseDirectory\r\n *\r\n * @example\r\n * const files = safeListDirectory('./.claude/skills');\r\n * files.forEach(file => {\r\n *   // All paths are guaranteed safe\r\n *   console.log(file);\r\n * });\r\n */\r\nexport function safeListDirectory(\r\n  baseDirectory: string,\r\n  options?: {\r\n    maxDepth?: number;\r\n    filter?: (path: string) => boolean;\r\n  }\r\n): string[] {\r\n  const safeFiles: string[] = [];\r\n  const maxDepth = options?.maxDepth ?? Infinity;\r\n  const filter = options?.filter ?? (() => true);\r\n\r\n  function walkDirectory(dir: string, currentDepth: number = 0): void {\r\n    if (currentDepth > maxDepth) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const entries = fs.readdirSync(dir, { withFileTypes: true });\r\n\r\n      for (const entry of entries) {\r\n        const fullPath = path.join(dir, entry.name);\r\n        const relativePath = path.relative(baseDirectory, fullPath);\r\n\r\n        // Validate the path is still within base\r\n        if (!isPathWithinBase(fullPath, baseDirectory)) {\r\n          continue;\r\n        }\r\n\r\n        // Apply filter\r\n        if (!filter(relativePath)) {\r\n          continue;\r\n        }\r\n\r\n        safeFiles.push(relativePath);\r\n\r\n        // Recursively walk directories\r\n        if (entry.isDirectory() && !entry.isSymbolicLink()) {\r\n          walkDirectory(fullPath, currentDepth + 1);\r\n        }\r\n      }\r\n    } catch (error) {\r\n      // Silently skip directories we can't read (permission denied, etc.)\r\n    }\r\n  }\r\n\r\n  walkDirectory(baseDirectory);\r\n  return safeFiles;\r\n}\r\n"],"names":["path","fs","StandardError","PathValidationError","message","context","name","decodePathSafely","inputPath","decoded","previous","iterations","MAX_ITERATIONS","originalInput","invalidEncodingDetected","decodeURIComponent","error","decodedOutput","reason","encodingAttackDetected","normalized","normalize","includes","encoding","detected","type","undefined","iterationsRequired","validatePath","filePath","baseDirectory","decodedPath","pathEncoding","decodedBase","console","warn","startsWith","normalizedBase","resolvedBase","resolve","normalizedPath","resolvedPath","isWithinBase","isPathWithinBase","isSymlink","stats","lstatSync","isSymbolicLink","valid","normalizedFile","relative","isAbsolute","validatePaths","filePaths","results","Map","result","set","getSafePath","isPathSafe","getPathValidationError","safeListDirectory","options","safeFiles","maxDepth","Infinity","filter","walkDirectory","dir","currentDepth","entries","readdirSync","withFileTypes","entry","fullPath","join","relativePath","push","isDirectory"],"mappings":"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"}
+{"version":3,"sources":["../../src/lib/path-validator.ts"],"sourcesContent":["/**\r\n * Path Validator - Security Utility for Safe File Operations\r\n *\r\n * Provides robust path sanitization and validation to prevent path traversal attacks (CVSS 7.0+).\r\n * Enforces strict rules on file access with protection against encoding attacks:\r\n *\r\n * CRITICAL FIXES (CVSS 7.0+):\r\n * - Iterative URL decoding prevents double-encoding bypasses (%252e%252e%252f → ../)\r\n * - Unicode normalization (NFC) prevents overlong UTF-8 bypasses (%c0%ae → .)\r\n * - Null byte detection prevents null injection attacks\r\n * - All decoding performed BEFORE path normalization to prevent layered attacks\r\n * - Encoding attack detection with security logging\r\n *\r\n * Base Security Controls:\r\n * - Path normalization to resolve \"..\" and \".\" sequences\r\n * - Validation that resolved paths stay within allowed directories\r\n * - Detection and rejection of symlinks\r\n * - Rejection of absolute paths outside allowed directories\r\n * - Prevention of home directory access (\"~\")\r\n *\r\n * @module path-validator\r\n * @version 2.0.0 (SECURITY CRITICAL)\r\n */\r\n\r\nimport * as path from 'path';\r\nimport * as fs from 'fs';\r\nimport { StandardError } from './errors';\r\n\r\n/**\r\n * Path validation error - thrown when a path violates security constraints\r\n */\r\nexport class PathValidationError extends StandardError {\r\n  constructor(message: string, context?: Record<string, unknown>) {\r\n    super('PATH_VALIDATION_ERROR', message, context);\r\n    this.name = 'PathValidationError';\r\n  }\r\n}\r\n\r\n/**\r\n * Security encoding attack detection\r\n */\r\nexport interface EncodingAttackDetection {\r\n  detected: boolean;\r\n  type?: 'double_encoding' | 'unicode_encoding' | 'mixed_encoding';\r\n  originalInput: string;\r\n  decodedOutput: string;\r\n  iterationsRequired: number;\r\n}\r\n\r\n/**\r\n * Path validation result with detailed information\r\n */\r\nexport interface PathValidationResult {\r\n  valid: boolean;\r\n  resolvedPath: string;\r\n  normalizedPath: string;\r\n  isWithinBase: boolean;\r\n  isSymlink: boolean;\r\n  reason?: string;\r\n}\r\n\r\n/**\r\n * Safely decode a path with protection against encoding attacks\r\n *\r\n * Performs iterative URL decoding and Unicode normalization to prevent:\r\n * - Double encoding bypass (e.g., %252e%252e%252f → %2e%2e%2f → ../)\r\n * - Overlong UTF-8 encoding (e.g., %c0%ae%c0%ae/ → ../)\r\n * - Mixed encoding attacks\r\n *\r\n * @param inputPath - The potentially encoded path\r\n * @returns Decoded path and attack detection info\r\n * @throws PathValidationError if encoding attack detected\r\n *\r\n * @example\r\n * const { decoded, encoding } = decodePathSafely('%252e%252e%252f');\r\n * // Detects double-encoding attempt\r\n */\r\nfunction decodePathSafely(inputPath: string): {\r\n  decoded: string;\r\n  encoding: EncodingAttackDetection;\r\n} {\r\n  let decoded = inputPath;\r\n  let previous = '';\r\n  let iterations = 0;\r\n  const MAX_ITERATIONS = 5;\r\n  const originalInput = inputPath;\r\n  let invalidEncodingDetected = false;\r\n\r\n  // Iteratively decode URL-encoded characters until stable\r\n  // This prevents bypass attacks using multiple encoding layers\r\n  while (decoded !== previous && iterations < MAX_ITERATIONS) {\r\n    previous = decoded;\r\n    try {\r\n      decoded = decodeURIComponent(decoded);\r\n    } catch (error) {\r\n      // Invalid URL encoding can be legitimate (e.g., file100%, %PATH%)\r\n      // These are literal percent signs in filenames, not attacks\r\n      // Only flag as attack if it's malformed UTF-8 (overlong encoding)\r\n      const errorMessage = (error as Error).message || '';\r\n\r\n      // Malformed UTF-8 sequences like %c0%ae are attacks\r\n      if (decoded.match(/%[cC][0-9a-fA-F]/) || decoded.match(/%[eE][0-9a-fA-F]/)) {\r\n        invalidEncodingDetected = true;\r\n        break;\r\n      }\r\n\r\n      // Otherwise, it's just a literal % in the filename - OK\r\n      // Keep the path as-is and stop decoding\r\n      break;\r\n    }\r\n    iterations++;\r\n  }\r\n\r\n  // Check if we hit max iterations (indicates potential encoding attack)\r\n  if (iterations >= MAX_ITERATIONS && decoded !== previous) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: excessive encoding layers detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'ENCODING_ATTACK_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Invalid encoding like malformed UTF-8 is itself an attack indicator\r\n  if (invalidEncodingDetected) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: invalid encoding detected (possible encoding attack)',\r\n      {\r\n        originalInput,\r\n        decodedOutput: decoded,\r\n        iterations,\r\n        reason: 'INVALID_ENCODING_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Detect double+ encoding attacks (3+ iterations = double-encoded or more)\r\n  // Single-level URL encoding requires 2 iterations: decode + stability check\r\n  // Example: subdir%2ffile.txt → subdir/file.txt → stable (2 iterations, legitimate)\r\n  // Example: %252e%252e%252f → %2e%2e%2f → ../ (3 iterations, attack)\r\n  const encodingAttackDetected = iterations > 2;\r\n\r\n  // Unicode normalization to handle overlong UTF-8 sequences\r\n  // e.g., %c0%ae (%c0%ae = UTF-8 overlong encoding for \".\")\r\n  let normalized = decoded;\r\n  try {\r\n    normalized = decoded.normalize('NFC');\r\n  } catch (error) {\r\n    // Some paths may not be valid Unicode, continue with non-normalized version\r\n  }\r\n\r\n  // Check for null bytes (another common encoding attack vector)\r\n  if (normalized.includes('\\0')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: null byte injection detected',\r\n      {\r\n        originalInput,\r\n        decodedOutput: normalized,\r\n        reason: 'NULL_BYTE_INJECTION',\r\n      }\r\n    );\r\n  }\r\n\r\n  return {\r\n    decoded: normalized,\r\n    encoding: {\r\n      detected: encodingAttackDetected,\r\n      type: encodingAttackDetected ? 'double_encoding' : undefined,\r\n      originalInput,\r\n      decodedOutput: normalized,\r\n      iterationsRequired: iterations,\r\n    },\r\n  };\r\n}\r\n\r\n/**\r\n * Validate a file path to prevent directory traversal attacks\r\n *\r\n * Security checks performed (in order):\r\n * 1. CRITICAL: Iteratively decode URL encoding to handle %252e%252e%252f and similar bypasses\r\n * 2. CRITICAL: Normalize Unicode (NFC) to handle overlong UTF-8 like %c0%ae%c0%ae/\r\n * 3. CRITICAL: Detect null bytes and excessive encoding layers\r\n * 4. Check for home directory expansion (\"~\") on DECODED path\r\n * 5. Normalize path to resolve \"..\" and \".\"\r\n * 6. Verify all suspicious patterns are eliminated\r\n * 7. Check if path is within base directory\r\n * 8. Reject symlinks to prevent symlink attacks\r\n * 9. Log any encoding attacks detected for security monitoring\r\n *\r\n * @param filePath - The file path to validate (may be encoded)\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns PathValidationResult with validation details\r\n * @throws PathValidationError if path validation fails or encoding attack detected\r\n *\r\n * @example\r\n * const result = validatePath('docs/FEATURE.md', './.claude/skills');\r\n * if (!result.valid) {\r\n *   throw result; // Safe to throw, contains all context\r\n * }\r\n * // Use result.resolvedPath\r\n *\r\n * @security\r\n * Designed to prevent:\r\n * - Double-encoding bypasses: %252e%252e%252f\r\n * - Overlong UTF-8: %c0%ae%c0%ae/\r\n * - Mixed encoding: URL + Unicode combinations\r\n * - Null byte injection: file.txt%00.jpg\r\n * - Traditional path traversal: ../../../etc/passwd\r\n */\r\nexport function validatePath(filePath: string, baseDirectory: string): PathValidationResult {\r\n  // SECURITY FIX: Decode all encoding layers first before any path normalization\r\n  // This prevents double-encoding bypasses like %252e%252e%252f\r\n  const { decoded: decodedPath, encoding: pathEncoding } = decodePathSafely(filePath);\r\n  const { decoded: decodedBase } = decodePathSafely(baseDirectory);\r\n\r\n  // Log encoding attacks for security monitoring\r\n  if (pathEncoding.detected) {\r\n    // In production, this should trigger security alerts\r\n    console.warn('Security: Encoding attack detected in path input', {\r\n      originalInput: pathEncoding.originalInput,\r\n      decodedOutput: pathEncoding.decodedOutput,\r\n      iterationsRequired: pathEncoding.iterationsRequired,\r\n    });\r\n  }\r\n\r\n  // Check for home directory expansion attempts on DECODED path\r\n  if (decodedPath.startsWith('~') || decodedPath.includes('/~') || decodedPath.includes('\\\\~')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: home directory access denied',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        baseDirectory,\r\n        reason: 'HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for home directory expansion attempts in baseDirectory\r\n  if (decodedBase.startsWith('~')) {\r\n    throw new PathValidationError(\r\n      'Base directory validation failed: home directory access denied',\r\n      {\r\n        baseDirectory,\r\n        decodedBase,\r\n        reason: 'BASE_HOME_DIRECTORY_ACCESS',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Normalize the base directory first\r\n  const normalizedBase = path.normalize(decodedBase);\r\n  const resolvedBase = path.resolve(normalizedBase);\r\n\r\n  // Normalize and resolve the file path relative to base\r\n  // NOW normalized on already-decoded path to prevent encoding bypasses\r\n  const normalizedPath = path.normalize(decodedPath);\r\n\r\n  // Check if path contains suspicious patterns after normalization\r\n  if (normalizedPath.includes('..') || normalizedPath === '.' || normalizedPath.includes('/./')) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: path contains directory traversal patterns',\r\n      {\r\n        filePath,\r\n        decodedPath,\r\n        normalizedPath,\r\n        baseDirectory,\r\n        reason: 'TRAVERSAL_PATTERN_DETECTED',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Resolve the path relative to base directory\r\n  const resolvedPath = path.resolve(resolvedBase, normalizedPath);\r\n\r\n  // Check if resolved path is within base directory\r\n  const isWithinBase = isPathWithinBase(resolvedPath, resolvedBase);\r\n\r\n  if (!isWithinBase) {\r\n    throw new PathValidationError(\r\n      'Path validation failed: resolved path is outside allowed directory',\r\n      {\r\n        filePath,\r\n        resolvedPath,\r\n        baseDirectory: resolvedBase,\r\n        reason: 'PATH_OUTSIDE_BASE',\r\n      }\r\n    );\r\n  }\r\n\r\n  // Check for symlinks (prevents symlink attacks)\r\n  let isSymlink = false;\r\n  try {\r\n    const stats = fs.lstatSync(resolvedPath);\r\n    isSymlink = stats.isSymbolicLink();\r\n\r\n    if (isSymlink) {\r\n      throw new PathValidationError(\r\n        'Path validation failed: symbolic links are not allowed',\r\n        {\r\n          filePath,\r\n          resolvedPath,\r\n          reason: 'SYMLINK_NOT_ALLOWED',\r\n        }\r\n      );\r\n    }\r\n  } catch (error) {\r\n    // File doesn't exist yet (expected for validation before creation)\r\n    // or it's a symlink that was rejected above\r\n    if (error instanceof PathValidationError) {\r\n      throw error;\r\n    }\r\n    // Other errors (permission denied, etc.) are not path validation failures\r\n    // The file validation happens later\r\n  }\r\n\r\n  return {\r\n    valid: true,\r\n    resolvedPath,\r\n    normalizedPath,\r\n    isWithinBase: true,\r\n    isSymlink: false,\r\n  };\r\n}\r\n\r\n/**\r\n * Check if a path is within a base directory\r\n *\r\n * Uses path resolution and string comparison to ensure the resolved path\r\n * is actually within the base directory (not just sharing a prefix).\r\n *\r\n * @param filePath - The path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if filePath is within baseDirectory\r\n *\r\n * @example\r\n * isPathWithinBase('/home/user/project/src/file.ts', '/home/user/project')  // true\r\n * isPathWithinBase('/home/user/project-evil/file.ts', '/home/user/project') // false\r\n */\r\nexport function isPathWithinBase(filePath: string, baseDirectory: string): boolean {\r\n  // Ensure both paths are normalized and absolute\r\n  const normalizedFile = path.normalize(path.resolve(filePath));\r\n  const normalizedBase = path.normalize(path.resolve(baseDirectory));\r\n\r\n  // Exact match\r\n  if (normalizedFile === normalizedBase) {\r\n    return true;\r\n  }\r\n\r\n  // Check if file is within base (use path.relative to ensure it's not going up)\r\n  const relative = path.relative(normalizedBase, normalizedFile);\r\n\r\n  // If relative path starts with \"..\", it's outside the base directory\r\n  if (relative.startsWith('..')) {\r\n    return false;\r\n  }\r\n\r\n  // If relative path is absolute, it's outside the base directory\r\n  if (path.isAbsolute(relative)) {\r\n    return false;\r\n  }\r\n\r\n  return true;\r\n}\r\n\r\n/**\r\n * Validate multiple paths within the same base directory\r\n *\r\n * Efficiently validates multiple paths, returning results for each.\r\n *\r\n * @param filePaths - Array of file paths to validate\r\n * @param baseDirectory - The base directory that all files must reside within\r\n * @returns Map of file path to validation result\r\n *\r\n * @example\r\n * const results = validatePaths(['docs/SKILL.md', 'src/index.ts'], './.claude/skills');\r\n * results.forEach((result, filePath) => {\r\n *   if (!result.valid) {\r\n *     console.error(`Invalid path: ${filePath}`, result.reason);\r\n *   }\r\n * });\r\n */\r\nexport function validatePaths(\r\n  filePaths: string[],\r\n  baseDirectory: string\r\n): Map<string, PathValidationResult> {\r\n  const results = new Map<string, PathValidationResult>();\r\n\r\n  for (const filePath of filePaths) {\r\n    try {\r\n      const result = validatePath(filePath, baseDirectory);\r\n      results.set(filePath, result);\r\n    } catch (error) {\r\n      if (error instanceof PathValidationError) {\r\n        results.set(filePath, {\r\n          valid: false,\r\n          resolvedPath: '',\r\n          normalizedPath: '',\r\n          isWithinBase: false,\r\n          isSymlink: false,\r\n          reason: error.context?.reason as string | undefined,\r\n        });\r\n      } else {\r\n        throw error;\r\n      }\r\n    }\r\n  }\r\n\r\n  return results;\r\n}\r\n\r\n/**\r\n * Get the safe path for a file (or throw if validation fails)\r\n *\r\n * Convenience function that validates and returns the resolved path,\r\n * or throws an error if validation fails.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory that file must reside within\r\n * @returns The resolved, validated absolute path\r\n * @throws PathValidationError if path validation fails\r\n *\r\n * @example\r\n * const safePath = getSafePath('docs/SKILL.md', './.claude/skills');\r\n * fs.readFileSync(safePath); // Safe to use\r\n */\r\nexport function getSafePath(filePath: string, baseDirectory: string): string {\r\n  const result = validatePath(filePath, baseDirectory);\r\n  return result.resolvedPath;\r\n}\r\n\r\n/**\r\n * Check if a path is considered safe for operations\r\n *\r\n * This is a non-throwing version of validatePath for conditional logic.\r\n *\r\n * @param filePath - The file path to check\r\n * @param baseDirectory - The base directory\r\n * @returns True if path is safe, false otherwise\r\n *\r\n * @example\r\n * if (isPathSafe(userInput, './.claude/skills')) {\r\n *   // Process the file\r\n * } else {\r\n *   // Reject the request\r\n * }\r\n */\r\nexport function isPathSafe(filePath: string, baseDirectory: string): boolean {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Get validation error details for a path (if invalid)\r\n *\r\n * Useful for logging and diagnostics.\r\n *\r\n * @param filePath - The file path to validate\r\n * @param baseDirectory - The base directory\r\n * @returns Error with details, or undefined if path is valid\r\n *\r\n * @example\r\n * const error = getPathValidationError('../../etc/passwd', './.claude/skills');\r\n * if (error) {\r\n *   logger.error(error.message, error.context);\r\n * }\r\n */\r\nexport function getPathValidationError(\r\n  filePath: string,\r\n  baseDirectory: string\r\n): PathValidationError | undefined {\r\n  try {\r\n    validatePath(filePath, baseDirectory);\r\n    return undefined;\r\n  } catch (error) {\r\n    if (error instanceof PathValidationError) {\r\n      return error;\r\n    }\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * List allowed files within a base directory (safely)\r\n *\r\n * Recursively lists all files within base directory, validating\r\n * each path to ensure it's within bounds.\r\n *\r\n * @param baseDirectory - The base directory to scan\r\n * @param options - Options for listing (maxDepth, filter)\r\n * @returns Array of validated, safe paths relative to baseDirectory\r\n *\r\n * @example\r\n * const files = safeListDirectory('./.claude/skills');\r\n * files.forEach(file => {\r\n *   // All paths are guaranteed safe\r\n *   console.log(file);\r\n * });\r\n */\r\nexport function safeListDirectory(\r\n  baseDirectory: string,\r\n  options?: {\r\n    maxDepth?: number;\r\n    filter?: (path: string) => boolean;\r\n  }\r\n): string[] {\r\n  const safeFiles: string[] = [];\r\n  const maxDepth = options?.maxDepth ?? Infinity;\r\n  const filter = options?.filter ?? (() => true);\r\n\r\n  function walkDirectory(dir: string, currentDepth: number = 0): void {\r\n    if (currentDepth > maxDepth) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const entries = fs.readdirSync(dir, { withFileTypes: true });\r\n\r\n      for (const entry of entries) {\r\n        const fullPath = path.join(dir, entry.name);\r\n        const relativePath = path.relative(baseDirectory, fullPath);\r\n\r\n        // Validate the path is still within base\r\n        if (!isPathWithinBase(fullPath, baseDirectory)) {\r\n          continue;\r\n        }\r\n\r\n        // Apply filter\r\n        if (!filter(relativePath)) {\r\n          continue;\r\n        }\r\n\r\n        safeFiles.push(relativePath);\r\n\r\n        // Recursively walk directories\r\n        if (entry.isDirectory() && !entry.isSymbolicLink()) {\r\n          walkDirectory(fullPath, currentDepth + 1);\r\n        }\r\n      }\r\n    } catch (error) {\r\n      // Silently skip directories we can't read (permission denied, etc.)\r\n    }\r\n  }\r\n\r\n  walkDirectory(baseDirectory);\r\n  return safeFiles;\r\n}\r\n"],"names":["path","fs","StandardError","PathValidationError","message","context","name","decodePathSafely","inputPath","decoded","previous","iterations","MAX_ITERATIONS","originalInput","invalidEncodingDetected","decodeURIComponent","error","errorMessage","match","decodedOutput","reason","encodingAttackDetected","normalized","normalize","includes","encoding","detected","type","undefined","iterationsRequired","validatePath","filePath","baseDirectory","decodedPath","pathEncoding","decodedBase","console","warn","startsWith","normalizedBase","resolvedBase","resolve","normalizedPath","resolvedPath","isWithinBase","isPathWithinBase","isSymlink","stats","lstatSync","isSymbolicLink","valid","normalizedFile","relative","isAbsolute","validatePaths","filePaths","results","Map","result","set","getSafePath","isPathSafe","getPathValidationError","safeListDirectory","options","safeFiles","maxDepth","Infinity","filter","walkDirectory","dir","currentDepth","entries","readdirSync","withFileTypes","entry","fullPath","join","relativePath","push","isDirectory"],"mappings":"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"}

package/dist/lib/redis-queue-manager.js

@@ -33,7 +33,7 @@
  *   }
  */ import { v4 as uuidv4 } from 'uuid';
 import { createLogger } from './logging.js';
-import { createError, ErrorCode, isRetryableError } from './errors.js';
+import { createError, ErrorCode, isRetryableError, StandardError } from './errors.js';
 import { withRetry } from './retry.js';
 import { MessageDeduplicator } from './message-deduplicator.js';
 const logger = createLogger('redis-queue-manager');
@@ -137,6 +137,10 @@ const DEFAULT_DEQUEUE_OPTIONS = {
             }
             return message.id;
         } catch (error) {
+            // Re-throw duplicate errors without wrapping
+            if (error instanceof StandardError && error.code === ErrorCode.DB_DUPLICATE_KEY) {
+                throw error;
+            }
             logger.error('Failed to enqueue message', error instanceof Error ? error : new Error(String(error)), {
                 queue
             });