@nexus-cortex/core 4.26.0

package/dist/middleware/permissions/FileOperationPolicy.js

@@ -0,0 +1,222 @@
+/**
+ * File Operation Permission Policy
+ *
+ * Validates file paths and operations to prevent unauthorized access.
+ * Supports:
+ * - Allowed path prefixes
+ * - Blocked path patterns
+ * - Path traversal detection
+ * - Delete operation approval requirements
+ * - Glob pattern matching
+ *
+ * Priority: HIGH (80) - Security-critical validation
+ *
+ * @module permissions/FileOperationPolicy
+ */
+import * as path from 'node:path';
+import { BasePermissionPolicy, PolicyPriority } from './PermissionPolicy.js';
+/**
+ * File tools that this policy applies to
+ * (uses canonical PascalCase names as defined in toolDefinitions.ts)
+ * Note: Glob and Grep use patterns, not file paths, so they're not included here
+ */
+const FILE_TOOLS = new Set([
+    'Read',
+    'Write',
+    'Edit',
+]);
+/**
+ * Sensitive directories that should be blocked by default
+ */
+const SENSITIVE_DIRECTORIES = [
+    '/etc',
+    '/root',
+    '/sys',
+    '/proc',
+    '/dev',
+    '/.git',
+    '/node_modules',
+    '/.env',
+    '/.ssh',
+    '/.aws',
+    '/.config',
+];
+/**
+ * File operation permission policy
+ *
+ * @example
+ * ```typescript
+ * const policy = new FileOperationPolicy({
+ *   allowedPaths: ['/home/user/workspace'],
+ *   blockedPaths: ['/etc', '/root'],
+ *   requireApprovalForDelete: true
+ * });
+ *
+ * await policy.evaluate({
+ *   toolName: 'read_file',
+ *   toolInput: { file_path: '/home/user/workspace/file.txt' },
+ *   sessionId: '123',
+ *   timestamp: new Date()
+ * }); // Returns { allowed: true }
+ *
+ * await policy.evaluate({
+ *   toolName: 'read_file',
+ *   toolInput: { file_path: '/etc/passwd' },
+ *   sessionId: '123',
+ *   timestamp: new Date()
+ * }); // Returns { allowed: false, reason: '...', canApprove: false }
+ * ```
+ */
+export class FileOperationPolicy extends BasePermissionPolicy {
+    config;
+    /**
+     * Create a new file operation policy
+     *
+     * @param config Policy configuration
+     * @param priority Policy priority (default: PolicyPriority.HIGH)
+     * @param enabled Whether the policy is enabled (default: true)
+     */
+    constructor(config, priority = PolicyPriority.HIGH, enabled = true) {
+        super('file-operation', priority, enabled);
+        this.config = {
+            allowedPaths: config.allowedPaths,
+            blockedPaths: config.blockedPaths,
+            requireApprovalForDelete: config.requireApprovalForDelete ?? true,
+            requireApprovalForWrite: config.requireApprovalForWrite ?? false,
+            maxPathLength: config.maxPathLength ?? 4096,
+        };
+        // Normalize all paths to absolute paths
+        this.config.allowedPaths = this.config.allowedPaths.map((p) => path.resolve(p));
+        this.config.blockedPaths = this.config.blockedPaths.map((p) => path.resolve(p));
+    }
+    /**
+     * Evaluate file operation permission
+     */
+    async evaluate(context) {
+        // Only apply to file operations
+        if (!FILE_TOOLS.has(context.toolName)) {
+            return this.allow();
+        }
+        // Extract file path from tool input
+        const filePath = this.extractFilePath(context.toolInput);
+        if (!filePath) {
+            return this.deny('No file path provided in tool input', false);
+        }
+        // Validate path length
+        if (filePath.length > this.config.maxPathLength) {
+            return this.deny(`File path exceeds maximum length (${this.config.maxPathLength})`, false);
+        }
+        // Resolve to absolute path and normalize
+        let absolutePath;
+        try {
+            absolutePath = path.resolve(filePath);
+        }
+        catch (error) {
+            return this.deny(`Invalid file path: ${error instanceof Error ? error.message : 'Unknown error'}`, false);
+        }
+        // Check for path traversal attempts
+        if (this.hasPathTraversal(filePath)) {
+            return this.deny('Path traversal detected in file path', false);
+        }
+        // Check blocked paths (highest priority - no approval)
+        if (this.isPathBlocked(absolutePath)) {
+            return this.deny(`Access to path "${absolutePath}" is restricted`, false // Hard block - no approval
+            );
+        }
+        // Check allowed paths
+        if (!this.isPathAllowed(absolutePath)) {
+            return this.deny(`Path "${absolutePath}" is outside allowed directories`, true // Can approve
+            );
+        }
+        // Check if write operation requires approval
+        if (context.toolName === 'Write' &&
+            this.config.requireApprovalForWrite) {
+            return this.deny('Write operation requires approval', true);
+        }
+        // Note: Delete operations are handled via Bash tool with rm commands,
+        // so requireApprovalForDelete should be checked in BashCommandPolicy
+        return this.allow();
+    }
+    /**
+     * Extract file path from various tool input formats
+     */
+    extractFilePath(toolInput) {
+        if (typeof toolInput === 'string') {
+            return toolInput;
+        }
+        if (typeof toolInput === 'object' && toolInput !== null) {
+            // Try common field names
+            return (toolInput.file_path ||
+                toolInput.path ||
+                toolInput.filePath ||
+                toolInput.filepath ||
+                null);
+        }
+        return null;
+    }
+    /**
+     * Check if path contains traversal patterns
+     */
+    hasPathTraversal(filePath) {
+        const traversalPatterns = ['../', '..\\', '/../', '\\..\\'];
+        return traversalPatterns.some((pattern) => filePath.includes(pattern));
+    }
+    /**
+     * Check if path is blocked
+     */
+    isPathBlocked(absolutePath) {
+        // Check against blocked paths
+        for (const blockedPath of this.config.blockedPaths) {
+            if (absolutePath.startsWith(blockedPath)) {
+                return true;
+            }
+            // Also check if any part of the path matches
+            if (absolutePath.includes(blockedPath)) {
+                return true;
+            }
+        }
+        // Check against sensitive directories
+        for (const sensitiveDir of SENSITIVE_DIRECTORIES) {
+            if (absolutePath.startsWith(sensitiveDir)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if path is in allowed paths
+     */
+    isPathAllowed(absolutePath) {
+        // If no allowed paths configured, all paths are allowed (unless blocked)
+        if (this.config.allowedPaths.length === 0) {
+            return true;
+        }
+        // Check if path starts with any allowed path prefix
+        return this.config.allowedPaths.some((allowedPath) => absolutePath.startsWith(allowedPath));
+    }
+    /**
+     * Add an allowed path
+     */
+    addAllowedPath(pathPrefix) {
+        const absolutePath = path.resolve(pathPrefix);
+        if (!this.config.allowedPaths.includes(absolutePath)) {
+            this.config.allowedPaths.push(absolutePath);
+        }
+    }
+    /**
+     * Add a blocked path
+     */
+    addBlockedPath(pathPrefix) {
+        const absolutePath = path.resolve(pathPrefix);
+        if (!this.config.blockedPaths.includes(absolutePath)) {
+            this.config.blockedPaths.push(absolutePath);
+        }
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+//# sourceMappingURL=FileOperationPolicy.js.map

package/dist/middleware/permissions/FileOperationPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileOperationPolicy.js","sourceRoot":"","sources":["../../../src/middleware/permissions/FileOperationPolicy.ts"],"names":[],"mappings":"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"}

package/dist/middleware/permissions/IPCApprovalHandler.d.ts

@@ -0,0 +1,94 @@
+/**
+ * IPC Approval Handler
+ *
+ * Used by sub-agent child processes to forward permission requests
+ * to the parent process via IPC. The parent process displays the
+ * approval UI to the user and sends the response back.
+ *
+ * This ensures sub-agents have the same permission harness as the
+ * main model (whitelist/graylist/blacklist with user approval).
+ *
+ * @module permissions/IPCApprovalHandler
+ */
+import type { ApprovalHandler, ApprovalRequest } from '../contracts/MiddlewareContracts.js';
+import type { IPCPermissionResponseMessage } from '../../orchestrator/SubAgentIPC.js';
+/**
+ * Options for IPC approval handler
+ */
+export interface IPCApprovalHandlerOptions {
+    /**
+     * Agent ID for correlation
+     */
+    agentId: string;
+    /**
+     * Timeout for waiting for parent response (ms)
+     * @default 300000 (5 minutes)
+     */
+    timeoutMs?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * IPC-based approval handler for sub-agent processes
+ *
+ * Sends permission requests to the parent process and waits for
+ * the response. The parent process is responsible for displaying
+ * the approval UI to the user.
+ *
+ * @example
+ * ```typescript
+ * // In sub-agent child process
+ * const handler = new IPCApprovalHandler({
+ *   agentId: 'agent-123',
+ *   timeoutMs: 60000
+ * });
+ *
+ * // Register to receive responses from parent
+ * process.on('message', (msg) => {
+ *   if (msg.type === 'permission_response') {
+ *     handler.handleResponse(msg);
+ *   }
+ * });
+ *
+ * // Request approval (will send IPC to parent and wait)
+ * const approved = await handler.requestApproval({
+ *   toolName: 'Write',
+ *   toolInput: { file_path: '/workspace/file.txt', content: '...' },
+ *   reason: 'File write requires approval',
+ *   timestamp: new Date()
+ * });
+ * ```
+ */
+export declare class IPCApprovalHandler implements ApprovalHandler {
+    private options;
+    private pendingApprovals;
+    constructor(options: IPCApprovalHandlerOptions);
+    /**
+     * Request approval by sending IPC message to parent and waiting for response.
+     *
+     * Signal honors tool-execution abort: if the orchestrator aborts (e.g. tool timeout),
+     * the pending approval is resolved as denied instead of hanging until its own timeout.
+     */
+    requestApproval(request: ApprovalRequest, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Handle response from parent process
+     * Call this when receiving a 'permission_response' IPC message
+     */
+    handleResponse(message: IPCPermissionResponseMessage): void;
+    /**
+     * Check if there are any pending approval requests
+     */
+    hasPendingRequests(): boolean;
+    /**
+     * Get count of pending approval requests
+     */
+    getPendingCount(): number;
+    /**
+     * Cancel all pending requests (e.g., on shutdown)
+     */
+    cancelAll(): void;
+}
+//# sourceMappingURL=IPCApprovalHandler.d.ts.map

package/dist/middleware/permissions/IPCApprovalHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IPCApprovalHandler.d.ts","sourceRoot":"","sources":["../../../src/middleware/permissions/IPCApprovalHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAC5F,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAEtF;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,gBAAgB,CAA2C;gBAEvD,OAAO,EAAE,yBAAyB;IAQ9C;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA2EvF;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI;IA0B3D;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,SAAS,IAAI,IAAI;CAOlB"}

package/dist/middleware/permissions/IPCApprovalHandler.js

@@ -0,0 +1,178 @@
+/**
+ * IPC Approval Handler
+ *
+ * Used by sub-agent child processes to forward permission requests
+ * to the parent process via IPC. The parent process displays the
+ * approval UI to the user and sends the response back.
+ *
+ * This ensures sub-agents have the same permission harness as the
+ * main model (whitelist/graylist/blacklist with user approval).
+ *
+ * @module permissions/IPCApprovalHandler
+ */
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * IPC-based approval handler for sub-agent processes
+ *
+ * Sends permission requests to the parent process and waits for
+ * the response. The parent process is responsible for displaying
+ * the approval UI to the user.
+ *
+ * @example
+ * ```typescript
+ * // In sub-agent child process
+ * const handler = new IPCApprovalHandler({
+ *   agentId: 'agent-123',
+ *   timeoutMs: 60000
+ * });
+ *
+ * // Register to receive responses from parent
+ * process.on('message', (msg) => {
+ *   if (msg.type === 'permission_response') {
+ *     handler.handleResponse(msg);
+ *   }
+ * });
+ *
+ * // Request approval (will send IPC to parent and wait)
+ * const approved = await handler.requestApproval({
+ *   toolName: 'Write',
+ *   toolInput: { file_path: '/workspace/file.txt', content: '...' },
+ *   reason: 'File write requires approval',
+ *   timestamp: new Date()
+ * });
+ * ```
+ */
+export class IPCApprovalHandler {
+    options;
+    pendingApprovals = new Map();
+    constructor(options) {
+        this.options = {
+            agentId: options.agentId,
+            timeoutMs: options.timeoutMs ?? 300000,
+            debug: options.debug ?? false,
+        };
+    }
+    /**
+     * Request approval by sending IPC message to parent and waiting for response.
+     *
+     * Signal honors tool-execution abort: if the orchestrator aborts (e.g. tool timeout),
+     * the pending approval is resolved as denied instead of hanging until its own timeout.
+     */
+    async requestApproval(request, signal) {
+        const requestId = uuidv4();
+        if (this.options.debug) {
+            console.log(`[IPCApprovalHandler] Requesting approval: ${request.toolName} (${requestId})`);
+        }
+        // Short-circuit if already aborted
+        if (signal?.aborted) {
+            if (this.options.debug) {
+                console.log(`[IPCApprovalHandler] Request aborted before send: ${requestId}`);
+            }
+            return false;
+        }
+        // Create promise that will be resolved when parent responds
+        return new Promise((resolve, reject) => {
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                this.pendingApprovals.delete(requestId);
+                if (signal)
+                    signal.removeEventListener('abort', onAbort);
+                if (this.options.debug) {
+                    console.log(`[IPCApprovalHandler] Approval request timed out: ${requestId}`);
+                }
+                // On timeout, deny the request for safety
+                resolve(false);
+            }, this.options.timeoutMs);
+            // Wire AbortSignal — deny immediately if orchestrator aborts
+            const onAbort = () => {
+                clearTimeout(timeoutId);
+                this.pendingApprovals.delete(requestId);
+                if (this.options.debug) {
+                    console.log(`[IPCApprovalHandler] Approval request aborted: ${requestId}`);
+                }
+                resolve(false);
+            };
+            if (signal) {
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            // Store pending approval
+            this.pendingApprovals.set(requestId, {
+                requestId,
+                resolve,
+                reject,
+                timeoutId,
+            });
+            // Send IPC message to parent
+            if (process.send) {
+                process.send({
+                    type: 'permission_request',
+                    payload: {
+                        agentId: this.options.agentId,
+                        requestId,
+                        toolName: request.toolName,
+                        toolInput: request.toolInput,
+                        reason: request.reason,
+                        timestamp: request.timestamp.toISOString(),
+                    },
+                });
+            }
+            else {
+                // Not running as child process - deny for safety
+                clearTimeout(timeoutId);
+                if (signal)
+                    signal.removeEventListener('abort', onAbort);
+                this.pendingApprovals.delete(requestId);
+                if (this.options.debug) {
+                    console.log(`[IPCApprovalHandler] Not running as child process, denying request`);
+                }
+                resolve(false);
+            }
+        });
+    }
+    /**
+     * Handle response from parent process
+     * Call this when receiving a 'permission_response' IPC message
+     */
+    handleResponse(message) {
+        const { requestId, approved, reason } = message.payload;
+        const pending = this.pendingApprovals.get(requestId);
+        if (!pending) {
+            if (this.options.debug) {
+                console.log(`[IPCApprovalHandler] Received response for unknown request: ${requestId}`);
+            }
+            return;
+        }
+        // Clear timeout and remove from pending
+        clearTimeout(pending.timeoutId);
+        this.pendingApprovals.delete(requestId);
+        if (this.options.debug) {
+            console.log(`[IPCApprovalHandler] Received approval response: ${requestId} -> ${approved}` +
+                (reason ? ` (${reason})` : ''));
+        }
+        // Resolve the pending promise
+        pending.resolve(approved);
+    }
+    /**
+     * Check if there are any pending approval requests
+     */
+    hasPendingRequests() {
+        return this.pendingApprovals.size > 0;
+    }
+    /**
+     * Get count of pending approval requests
+     */
+    getPendingCount() {
+        return this.pendingApprovals.size;
+    }
+    /**
+     * Cancel all pending requests (e.g., on shutdown)
+     */
+    cancelAll() {
+        for (const pending of this.pendingApprovals.values()) {
+            clearTimeout(pending.timeoutId);
+            pending.resolve(false);
+        }
+        this.pendingApprovals.clear();
+    }
+}
+//# sourceMappingURL=IPCApprovalHandler.js.map

package/dist/middleware/permissions/IPCApprovalHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IPCApprovalHandler.js","sourceRoot":"","sources":["../../../src/middleware/permissions/IPCApprovalHandler.ts"],"names":[],"mappings":"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"}

package/dist/middleware/permissions/PermissionAuditLogger.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Permission Audit Logger
+ *
+ * JSONL-based audit logging for all permission decisions.
+ * Each line is a JSON object representing a single audit entry.
+ *
+ * Features:
+ * - Append-only logging (tamper-evident)
+ * - JSONL format (one JSON object per line)
+ * - Query interface for audit entries
+ * - Session and tool filtering
+ *
+ * @module permissions/PermissionAuditLogger
+ */
+import type { PermissionAuditEntry } from '../contracts/MiddlewareContracts.js';
+/**
+ * Options for audit logger
+ */
+export interface PermissionAuditLoggerOptions {
+    /**
+     * Maximum file size before rotation (bytes)
+     * @default 10MB
+     */
+    maxFileSizeBytes?: number;
+    /**
+     * Whether to enable file rotation
+     * @default true
+     */
+    enableRotation?: boolean;
+    /**
+     * Number of rotated files to keep
+     * @default 5
+     */
+    maxRotatedFiles?: number;
+}
+/**
+ * Query options for filtering audit entries
+ */
+export interface AuditQueryOptions {
+    /**
+     * Filter by session ID
+     */
+    sessionId?: string;
+    /**
+     * Filter by tool name
+     */
+    toolName?: string;
+    /**
+     * Only return denied operations
+     */
+    deniedOnly?: boolean;
+    /**
+     * Only return approved operations
+     */
+    approvedOnly?: boolean;
+    /**
+     * Start date for filtering
+     */
+    startDate?: Date;
+    /**
+     * End date for filtering
+     */
+    endDate?: Date;
+    /**
+     * Maximum number of entries to return
+     */
+    limit?: number;
+}
+/**
+ * Permission audit logger with JSONL storage
+ *
+ * @example
+ * ```typescript
+ * const logger = new PermissionAuditLogger('/path/to/audit.log');
+ *
+ * await logger.log({
+ *   timestamp: new Date(),
+ *   sessionId: '123',
+ *   toolName: 'read_file',
+ *   toolInput: { file_path: '/workspace/file.txt' },
+ *   decision: { allowed: true },
+ *   approvalRequested: false
+ * });
+ *
+ * const entries = await logger.query({ sessionId: '123' });
+ * ```
+ */
+export declare class PermissionAuditLogger {
+    private logPath;
+    private options;
+    private writeStream;
+    /**
+     * Create a new permission audit logger
+     *
+     * @param logPath Path to the audit log file
+     * @param options Logger options
+     */
+    constructor(logPath: string, options?: PermissionAuditLoggerOptions);
+    /**
+     * Log a permission audit entry
+     */
+    log(entry: PermissionAuditEntry): Promise<void>;
+    /**
+     * Query audit entries with filtering
+     */
+    query(options?: AuditQueryOptions): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get entries for a specific session
+     */
+    getEntriesBySession(sessionId: string): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get entries for a specific tool
+     */
+    getEntriesByTool(toolName: string): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get all denied operations
+     */
+    getDeniedOperations(): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get all operations that required approval
+     */
+    getApprovalRequests(): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get audit statistics
+     */
+    getStatistics(): Promise<{
+        totalEntries: number;
+        allowedCount: number;
+        deniedCount: number;
+        approvalRequestCount: number;
+        approvalGrantedCount: number;
+        uniqueSessions: number;
+        uniqueTools: Set<string>;
+    }>;
+    /**
+     * Clear the audit log
+     * WARNING: This is a destructive operation
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the logger and cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Ensure the log directory exists
+     */
+    private ensureDirectoryExists;
+    /**
+     * Write to file with append
+     */
+    private writeToFile;
+    /**
+     * Rotate log file if size exceeds limit
+     *
+     * Round 9 (parallel-bench output): previously called `fs.existsSync`
+     * before the async `fs.promises.stat`. This method is called from `log()`
+     * on every audit-log write — i.e. per permission check (10-20× per
+     * multi-iter turn). Sync I/O inside an async hot path blocks the event
+     * loop. The async `stat` already throws `ENOENT` when the file doesn't
+     * exist; we catch and treat as "no rotation needed", eliminating the
+     * sync `existsSync` call.
+     */
+    private rotateIfNeeded;
+    /**
+     * Rotate log files
+     */
+    private rotateFiles;
+}
+//# sourceMappingURL=PermissionAuditLogger.d.ts.map

package/dist/middleware/permissions/PermissionAuditLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionAuditLogger.d.ts","sourceRoot":"","sources":["../../../src/middleware/permissions/PermissionAuditLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,WAAW,CAA+B;IAElD;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,4BAAiC;IAYvE;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD;;OAEG;IACG,KAAK,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA0D7E;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAI7E;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAIzE;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAI5D;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAK5D;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;KAC1B,CAAC;IAkBF;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;OAEG;YACW,WAAW;IAgBzB;;;;;;;;;;OAUG;YACW,cAAc;IAoB5B;;OAEG;YACW,WAAW;CAoB1B"}