@nexus-cortex/core 4.26.0

package/dist/middleware/PermissionsMiddleware.js

@@ -0,0 +1,344 @@
+/**
+ * Permissions Middleware
+ *
+ * Central authorization layer for tool execution. Evaluates permission
+ * policies before allowing tools to execute, handles approval requests,
+ * and maintains audit logs.
+ *
+ * Features:
+ * - Policy-based authorization
+ * - Priority-ordered policy evaluation
+ * - Approval flow for dangerous operations
+ * - Comprehensive audit logging
+ * - Session-based permission tracking
+ *
+ * @module middleware/PermissionsMiddleware
+ */
+import { PermissionEvaluator } from './permissions/PermissionEvaluator.js';
+import { PermissionAuditLogger } from './permissions/PermissionAuditLogger.js';
+/**
+ * Permissions middleware implementation
+ *
+ * @example
+ * ```typescript
+ * const middleware = new PermissionsMiddleware({
+ *   policies: [
+ *     new WhitelistPolicy(['read_file', 'write_file']),
+ *     new FileOperationPolicy({
+ *       allowedPaths: ['/workspace'],
+ *       blockedPaths: ['/etc', '/root']
+ *     }),
+ *     new BashCommandPolicy({
+ *       allowedCommands: [],
+ *       blockedCommands: ['rm -rf /']
+ *     })
+ *   ],
+ *   approvalHandler: new CLIApprovalHandler(),
+ *   auditLogger: new PermissionAuditLogger('/path/to/audit.log')
+ * });
+ *
+ * const decision = await middleware.checkPermission(
+ *   'read_file',
+ *   { file_path: '/workspace/file.txt' },
+ *   context
+ * );
+ * ```
+ */
+export class PermissionsMiddleware {
+    evaluator;
+    approvalHandler;
+    auditLogger;
+    enableLogging;
+    bypassAll;
+    // Cache for session audit entries (in-memory)
+    sessionAuditCache = new Map();
+    /**
+     * Create a new permissions middleware
+     *
+     * @param options Middleware options
+     */
+    constructor(options = {}) {
+        this.evaluator = new PermissionEvaluator({
+            defaultPolicy: options.defaultPolicy ?? 'deny',
+            enableLogging: options.enableLogging ?? false,
+        });
+        this.approvalHandler = options.approvalHandler;
+        this.auditLogger = options.auditLogger;
+        this.enableLogging = options.enableLogging ?? false;
+        this.bypassAll = options.bypassAll ?? false;
+        // Register initial policies
+        if (options.policies) {
+            for (const policy of options.policies) {
+                this.registerPolicy(policy);
+            }
+        }
+    }
+    /**
+     * Check permission for a tool execution
+     *
+     * @param toolName The name of the tool to execute
+     * @param toolInput The input parameters for the tool
+     * @param context The middleware context
+     * @returns Permission decision with reason if denied
+     */
+    async checkPermission(toolName, toolInput, context, signal) {
+        const permissionContext = {
+            toolName,
+            toolInput,
+            sessionId: context.sessionId,
+            userId: undefined, // Could be added from context in the future
+            timestamp: new Date(),
+        };
+        // YOLO bypass — short-circuit before policy evaluation. This is the only
+        // way to override a hard-deny policy (e.g. WhitelistPolicy with
+        // canApprove: false), since approval handlers cannot rescue those.
+        if (this.bypassAll) {
+            if (this.enableLogging) {
+                console.log(`[PermissionsMiddleware] bypassAll active — allowing ${toolName} without evaluation`);
+            }
+            await this.logDecision(permissionContext, { allowed: true }, true, true);
+            return { allowed: true };
+        }
+        if (this.enableLogging) {
+            console.log(`[PermissionsMiddleware] Checking permission for ${toolName} in session ${context.sessionId}`);
+        }
+        // Evaluate policies
+        const result = await this.evaluator.evaluate(permissionContext);
+        // Log the decision
+        await this.logDecision(permissionContext, result.decision, false);
+        // Whitelist: allowed=true → execute immediately
+        if (result.decision.allowed) {
+            return { allowed: true };
+        }
+        // Graylist + auto-approve ON → auto-approve
+        if (result.decision.tier === 'graylist' &&
+            context.approvalMode?.autoApproveActions === true) {
+            if (this.enableLogging) {
+                console.log(`[PermissionsMiddleware] Graylist tool ${toolName} auto-approved (auto approve actions - ON)`);
+            }
+            await this.logDecision(permissionContext, { allowed: true }, true, true);
+            return { allowed: true };
+        }
+        // Graylist (auto-approve OFF) or Blacklist → request approval
+        if (result.decision.canApprove) {
+            if (this.approvalHandler) {
+                try {
+                    const approved = await this.requestApproval(permissionContext, result.decision.reason, signal);
+                    if (approved) {
+                        // Log the approval
+                        await this.logDecision(permissionContext, { allowed: true }, true, true);
+                        return { allowed: true };
+                    }
+                    else {
+                        // Log the denial
+                        await this.logDecision(permissionContext, result.decision, true, false);
+                    }
+                }
+                catch (error) {
+                    console.error('[PermissionsMiddleware] Error during approval request:', error);
+                    // Log the error
+                    await this.logDecision(permissionContext, {
+                        allowed: false,
+                        reason: `Approval error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        canApprove: false,
+                    }, true, false);
+                }
+            }
+            else {
+                // No approval handler - deny
+                if (this.enableLogging) {
+                    console.log('[PermissionsMiddleware] No approval handler configured - denying');
+                }
+            }
+        }
+        return result.decision;
+    }
+    /**
+     * Request approval for a denied operation
+     *
+     * @param context The permission context
+     * @param reason The reason for denial
+     * @returns True if approved, false otherwise
+     */
+    async requestApproval(context, reason, signal) {
+        if (!this.approvalHandler) {
+            return false;
+        }
+        try {
+            return await this.approvalHandler.requestApproval({
+                toolName: context.toolName,
+                toolInput: context.toolInput,
+                reason,
+                timestamp: context.timestamp,
+            }, signal);
+        }
+        catch (error) {
+            console.error('[PermissionsMiddleware] Approval request error:', error);
+            return false;
+        }
+    }
+    /**
+     * Register a permission policy
+     *
+     * @param policy The policy to register
+     */
+    registerPolicy(policy) {
+        this.evaluator.registerPolicy(policy);
+    }
+    /**
+     * Unregister a permission policy
+     *
+     * @param policyName The name of the policy to unregister
+     * @returns True if the policy was found and removed
+     */
+    unregisterPolicy(policyName) {
+        return this.evaluator.unregisterPolicy(policyName);
+    }
+    /**
+     * Get all registered policies
+     */
+    getPolicies() {
+        return this.evaluator.getPolicies();
+    }
+    /**
+     * Get audit log entries for a session
+     *
+     * @param sessionId The session ID to query
+     * @returns Array of audit entries for the session
+     */
+    getAuditLog(sessionId) {
+        // Return from in-memory cache
+        return this.sessionAuditCache.get(sessionId) || [];
+    }
+    /**
+     * Get audit log entries from persistent storage
+     *
+     * @param sessionId The session ID to query
+     * @returns Array of audit entries from storage
+     */
+    async getAuditLogFromStorage(sessionId) {
+        if (!this.auditLogger) {
+            return [];
+        }
+        return this.auditLogger.getEntriesBySession(sessionId);
+    }
+    /**
+     * Get all denied operations across all sessions
+     */
+    async getAllDeniedOperations() {
+        if (!this.auditLogger) {
+            return [];
+        }
+        return this.auditLogger.getDeniedOperations();
+    }
+    /**
+     * Get audit statistics
+     */
+    async getStatistics() {
+        if (!this.auditLogger) {
+            return null;
+        }
+        return this.auditLogger.getStatistics();
+    }
+    /**
+     * Clear audit cache for a session
+     *
+     * @param sessionId The session ID to clear
+     */
+    clearSessionCache(sessionId) {
+        this.sessionAuditCache.delete(sessionId);
+    }
+    /**
+     * Log a permission decision
+     */
+    async logDecision(context, decision, approvalRequested, approvalGranted) {
+        const entry = {
+            timestamp: context.timestamp,
+            sessionId: context.sessionId,
+            toolName: context.toolName,
+            toolInput: context.toolInput,
+            decision,
+            approvalRequested,
+            approvalGranted,
+            userId: context.userId,
+            policyName: undefined, // Could be added from evaluator result
+        };
+        // Add to in-memory cache
+        if (!this.sessionAuditCache.has(context.sessionId)) {
+            this.sessionAuditCache.set(context.sessionId, []);
+        }
+        this.sessionAuditCache.get(context.sessionId).push(entry);
+        // Log to persistent storage
+        if (this.auditLogger) {
+            try {
+                await this.auditLogger.log(entry);
+            }
+            catch (error) {
+                console.error('[PermissionsMiddleware] Failed to log audit entry:', error);
+            }
+        }
+    }
+    /**
+     * Close the middleware and cleanup resources
+     */
+    async close() {
+        if (this.auditLogger) {
+            await this.auditLogger.close();
+        }
+        this.sessionAuditCache.clear();
+    }
+    /**
+     * Set the approval handler (for switching to YOLO mode)
+     *
+     * @param handler - The new approval handler
+     */
+    setApprovalHandler(handler) {
+        this.approvalHandler = handler;
+    }
+    /**
+     * Get the current approval handler
+     */
+    getApprovalHandler() {
+        return this.approvalHandler;
+    }
+    /**
+     * Create a default permissions middleware with common policies
+     *
+     * @param workspacePath The workspace path to allow
+     * @param auditLogPath Optional path to audit log file
+     * @returns Configured permissions middleware
+     */
+    static async createDefault(workspacePath, auditLogPath) {
+        const { FileOperationPolicy } = await import('./permissions/FileOperationPolicy.js');
+        const { BashCommandPolicy } = await import('./permissions/BashCommandPolicy.js');
+        const { WhitelistPolicy } = await import('./permissions/WhitelistPolicy.js');
+        return new PermissionsMiddleware({
+            policies: [
+                new FileOperationPolicy({
+                    allowedPaths: [workspacePath],
+                    blockedPaths: ['/etc', '/root', '/.git', '/node_modules'],
+                    requireApprovalForDelete: true,
+                }),
+                new BashCommandPolicy({
+                    allowedCommands: [],
+                    blockedCommands: ['rm -rf /', 'sudo rm'],
+                    requireApprovalForDangerous: true,
+                }),
+                new WhitelistPolicy([
+                    'Read',
+                    'Write',
+                    'Edit',
+                    'Bash',
+                    'Glob',
+                    'Grep',
+                    'CreateArtifactTool',
+                ]),
+            ],
+            auditLogger: auditLogPath
+                ? new PermissionAuditLogger(auditLogPath)
+                : undefined,
+            defaultPolicy: 'deny',
+        });
+    }
+}
+//# sourceMappingURL=PermissionsMiddleware.js.map

package/dist/middleware/PermissionsMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionsMiddleware.js","sourceRoot":"","sources":["../../src/middleware/PermissionsMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AA4C/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,qBAAqB;IACxB,SAAS,CAAsB;IAC/B,eAAe,CAAmB;IAClC,WAAW,CAAyB;IACpC,aAAa,CAAU;IACvB,SAAS,CAAU;IAE3B,8CAA8C;IACtC,iBAAiB,GAAwC,IAAI,GAAG,EAAE,CAAC;IAE3E;;;;OAIG;IACH,YAAY,UAAwC,EAAE;QACpD,IAAI,CAAC,SAAS,GAAG,IAAI,mBAAmB,CAAC;YACvC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,MAAM;YAC9C,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,KAAK;SAC9C,CAAC,CAAC;QAEH,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,KAAK,CAAC;QACpD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAE5C,4BAA4B;QAC5B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACtC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CACnB,QAAgB,EAChB,SAAc,EACd,OAA0B,EAC1B,MAAoB;QAEpB,MAAM,iBAAiB,GAAsB;YAC3C,QAAQ;YACR,SAAS;YACT,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,SAAS,EAAE,4CAA4C;YAC/D,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;QAEF,yEAAyE;QACzE,gEAAgE;QAChE,mEAAmE;QACnE,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CACT,uDAAuD,QAAQ,qBAAqB,CACrF,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CACT,mDAAmD,QAAQ,eAAe,OAAO,CAAC,SAAS,EAAE,CAC9F,CAAC;QACJ,CAAC;QAED,oBAAoB;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QAEhE,mBAAmB;QACnB,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAElE,gDAAgD;QAChD,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,4CAA4C;QAC5C,IACE,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,UAAU;YACnC,OAAO,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,EACjD,CAAC;YACD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CACT,yCAAyC,QAAQ,4CAA4C,CAC9F,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,8DAA8D;QAC9D,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CACzC,iBAAiB,EACjB,MAAM,CAAC,QAAQ,CAAC,MAAM,EACtB,MAAM,CACP,CAAC;oBAEF,IAAI,QAAQ,EAAE,CAAC;wBACb,mBAAmB;wBACnB,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;wBAEzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;oBAC3B,CAAC;yBAAM,CAAC;wBACN,iBAAiB;wBACjB,MAAM,IAAI,CAAC,WAAW,CACpB,iBAAiB,EACjB,MAAM,CAAC,QAAQ,EACf,IAAI,EACJ,KAAK,CACN,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,KAAK,CACX,wDAAwD,EACxD,KAAK,CACN,CAAC;oBAEF,gBAAgB;oBAChB,MAAM,IAAI,CAAC,WAAW,CACpB,iBAAiB,EACjB;wBACE,OAAO,EAAE,KAAK;wBACd,MAAM,EAAE,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE;wBACrF,UAAU,EAAE,KAAK;qBAClB,EACD,IAAI,EACJ,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,6BAA6B;gBAC7B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;oBACvB,OAAO,CAAC,GAAG,CACT,kEAAkE,CACnE,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,eAAe,CACnB,OAA0B,EAC1B,MAAc,EACd,MAAoB;QAEpB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC;gBAChD,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,MAAM;gBACN,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,EAAE,MAAM,CAAC,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,CAAC,CAAC;YACxE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,MAAwB;QACrC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,UAAkB;QACjC,OAAO,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,SAAiB;QAC3B,8BAA8B;QAC9B,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAC1B,SAAiB;QAEjB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,SAAiB;QACjC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,WAAW,CACvB,OAA0B,EAC1B,QAA4B,EAC5B,iBAA0B,EAC1B,eAAyB;QAEzB,MAAM,KAAK,GAAyB;YAClC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,QAAQ;YACR,iBAAiB;YACjB,eAAe;YACf,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE,SAAS,EAAE,uCAAuC;SAC/D,CAAC;QAEF,yBAAyB;QACzB,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE3D,4BAA4B;QAC5B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,oDAAoD,EAAE,KAAK,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACjC,CAAC;QAED,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,OAAoC;QACrD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,aAAa,CACxB,aAAqB,EACrB,YAAqB;QAErB,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,sCAAsC,CAAC,CAAC;QACrF,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAC;QACjF,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,kCAAkC,CAAC,CAAC;QAE7E,OAAO,IAAI,qBAAqB,CAAC;YAC/B,QAAQ,EAAE;gBACR,IAAI,mBAAmB,CAAC;oBACtB,YAAY,EAAE,CAAC,aAAa,CAAC;oBAC7B,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC;oBACzD,wBAAwB,EAAE,IAAI;iBAC/B,CAAC;gBACF,IAAI,iBAAiB,CAAC;oBACpB,eAAe,EAAE,EAAE;oBACnB,eAAe,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;oBACxC,2BAA2B,EAAE,IAAI;iBAClC,CAAC;gBACF,IAAI,eAAe,CAAC;oBAClB,MAAM;oBACN,OAAO;oBACP,MAAM;oBACN,MAAM;oBACN,MAAM;oBACN,MAAM;oBACN,oBAAoB;iBACrB,CAAC;aACH;YACD,WAAW,EAAE,YAAY;gBACvB,CAAC,CAAC,IAAI,qBAAqB,CAAC,YAAY,CAAC;gBACzC,CAAC,CAAC,SAAS;YACb,aAAa,EAAE,MAAM;SACtB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/middleware/RetryMiddleware.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Retry Middleware
+ *
+ * Provides retry orchestration with exponential backoff and jitter for failed operations.
+ * Uses error classification from ErrorClassificationMiddleware to determine retry eligibility.
+ *
+ * This component is standalone and can be used independently of the orchestrator.
+ *
+ * @version 1.0.0
+ * @author Agent 5 - Parallel Refactor Wave 1
+ */
+import type { IRetryExecutor, IErrorClassifier, RetryOptions, RetryResult } from './contracts/MiddlewareContracts.js';
+/**
+ * RetryMiddleware
+ *
+ * Orchestrates retry logic for failed operations using exponential backoff with jitter.
+ * Works in conjunction with ErrorClassificationMiddleware to determine which errors
+ * are retryable.
+ *
+ * **Exponential Backoff Algorithm:**
+ * ```
+ * delay = baseDelay * (backoffMultiplier ^ attempt)
+ * delay = min(delay, maxDelayMs)
+ * delay = delay ± (delay * jitterFactor * random())
+ * ```
+ *
+ * **Example backoff sequence (default options):**
+ * - Attempt 1: 1000ms ± 100ms = 900-1100ms
+ * - Attempt 2: 2000ms ± 200ms = 1800-2200ms
+ * - Attempt 3: 4000ms ± 400ms = 3600-4400ms
+ * - Attempt 4: 8000ms ± 800ms = 7200-8800ms
+ * - Capped at: 30000ms ± 3000ms = 27000-33000ms
+ *
+ * @example
+ * ```typescript
+ * const errorClassifier = new ErrorClassificationMiddleware();
+ * const retryMiddleware = new RetryMiddleware(errorClassifier, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   backoffMultiplier: 2,
+ *   jitterFactor: 0.1
+ * });
+ *
+ * const result = await retryMiddleware.executeWithRetry(
+ *   async () => {
+ *     return await fetchDataFromAPI();
+ *   },
+ *   'fetchDataFromAPI'
+ * );
+ *
+ * console.log(`Success after ${result.attemptCount} attempts`);
+ * console.log(`Total delay: ${result.totalDelayMs}ms`);
+ * ```
+ */
+export declare class RetryMiddleware implements IRetryExecutor {
+    private readonly errorClassifier;
+    private readonly options;
+    /**
+     * Create a new RetryMiddleware instance
+     *
+     * @param errorClassifier - Error classifier for determining retry eligibility
+     * @param options - Retry configuration options (merged with defaults)
+     */
+    constructor(errorClassifier: IErrorClassifier, options?: Partial<RetryOptions>);
+    /**
+     * Execute an operation with retry logic
+     *
+     * This method will:
+     * 1. Attempt the operation
+     * 2. If it fails, classify the error
+     * 3. If the error is retryable, wait with exponential backoff
+     * 4. Retry up to maxRetries times
+     * 5. If all retries fail, throw the last error with accumulated metadata
+     *
+     * @param operation - The async operation to execute
+     * @param context - Context string for logging/debugging (e.g., "fetchUserData", "executeToolX")
+     * @returns RetryResult containing the successful result and retry metadata
+     * @throws The last error if all retry attempts are exhausted or if a non-retryable error occurs
+     *
+     * @example
+     * ```typescript
+     * // Successful on first attempt
+     * const result = await retry.executeWithRetry(
+     *   async () => ({ data: 'success' }),
+     *   'testOperation'
+     * );
+     * // result.attemptCount === 1
+     * // result.totalDelayMs === 0
+     * // result.errors.length === 0
+     *
+     * // Retries on transient error
+     * let attempts = 0;
+     * const result = await retry.executeWithRetry(
+     *   async () => {
+     *     if (attempts++ < 2) throw new Error('ECONNRESET');
+     *     return { data: 'success' };
+     *   },
+     *   'retryOperation'
+     * );
+     * // result.attemptCount === 3
+     * // result.errors.length === 2
+     * ```
+     */
+    executeWithRetry<T>(operation: () => Promise<T>, context: string): Promise<RetryResult<T>>;
+    /**
+     * Calculate delay for a given attempt number using exponential backoff with jitter
+     *
+     * The algorithm:
+     * 1. Calculate exponential delay: baseDelay * (multiplier ^ attempt)
+     * 2. Cap at maxDelayMs
+     * 3. Add random jitter: ± (delay * jitterFactor)
+     *
+     * **Jitter Purpose:**
+     * Jitter prevents the "thundering herd" problem where many clients retry
+     * simultaneously, potentially overwhelming a recovering service.
+     *
+     * @param attempt - The attempt number (0-indexed)
+     * @returns Delay in milliseconds (always non-negative)
+     *
+     * @example
+     * ```typescript
+     * // With default options (baseDelayMs=1000, backoffMultiplier=2, jitterFactor=0.1)
+     * retry.calculateDelay(0); // ~1000ms ± 10% = 900-1100ms
+     * retry.calculateDelay(1); // ~2000ms ± 10% = 1800-2200ms
+     * retry.calculateDelay(2); // ~4000ms ± 10% = 3600-4400ms
+     * retry.calculateDelay(10); // capped at maxDelayMs (30000ms) ± 10%
+     * ```
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * Sleep for the specified duration
+     *
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     */
+    private sleep;
+    /**
+     * Enhance an error with retry metadata
+     *
+     * This adds useful debugging information to the error object without
+     * modifying the original error message or stack trace.
+     *
+     * @param error - The original error
+     * @param context - Context string
+     * @param attemptCount - Number of attempts made
+     * @param totalDelayMs - Total time spent waiting
+     * @param errors - Array of all error classifications
+     * @returns Enhanced error object
+     */
+    private enhanceError;
+    /**
+     * Get the current retry options
+     *
+     * @returns Current retry options (readonly)
+     */
+    getOptions(): Readonly<RetryOptions>;
+}
+//# sourceMappingURL=RetryMiddleware.d.ts.map

package/dist/middleware/RetryMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryMiddleware.d.ts","sourceRoot":"","sources":["../../src/middleware/RetryMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEZ,MAAM,oCAAoC,CAAC;AAoB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,eAAgB,YAAW,cAAc;IAUlD,OAAO,CAAC,QAAQ,CAAC,eAAe;IATlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;;OAKG;gBAEgB,eAAe,EAAE,gBAAgB,EAClD,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM;IA0BrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,gBAAgB,CAAC,CAAC,EACtB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAmD1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAkBvC;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAIb;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;OAIG;IACH,UAAU,IAAI,QAAQ,CAAC,YAAY,CAAC;CAGrC"}