@darbotlabs/darbot-browser-mcp 0.1.1 → 1.3.0

package/lib/ai/workflow.js

@@ -0,0 +1,407 @@
+/**
+ * Copyright (c) DarbotLabs.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Workflow execution engine for automated task sequences
+ */
+export class WorkflowEngine {
+    templates = new Map();
+    executions = new Map();
+    constructor() {
+        this.registerDefaultTemplates();
+    }
+    /**
+     * Register default workflow templates
+     */
+    registerDefaultTemplates() {
+        // GitHub Issue Management
+        this.registerTemplate({
+            name: 'github_issue_management',
+            description: 'Create, update, or manage GitHub issues',
+            requiredParameters: ['repository', 'action'],
+            expectedDuration: 60,
+            successCriteria: ['Issue created or updated successfully'],
+            steps: [
+                {
+                    action: 'navigate',
+                    parameters: { url: 'https://github.com/{repository}/issues' },
+                    retryCount: 2,
+                    timeout: 10000,
+                },
+                {
+                    action: 'conditional_click',
+                    parameters: {
+                        element: 'New issue button',
+                        condition: (params) => params.action === 'create',
+                    },
+                },
+                {
+                    action: 'type',
+                    parameters: {
+                        element: 'issue title input',
+                        text: '{title}',
+                    },
+                },
+                {
+                    action: 'type',
+                    parameters: {
+                        element: 'issue description textarea',
+                        text: '{description}',
+                    },
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'Submit new issue' },
+                    validation: result => result.success,
+                },
+            ],
+        });
+        // Code Review Workflow
+        this.registerTemplate({
+            name: 'code_review_workflow',
+            description: 'Navigate and review pull requests',
+            requiredParameters: ['repository'],
+            expectedDuration: 120,
+            successCriteria: ['PR reviewed and commented'],
+            steps: [
+                {
+                    action: 'navigate',
+                    parameters: { url: 'https://github.com/{repository}/pulls' },
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'first pull request in list' },
+                },
+                {
+                    action: 'wait_for',
+                    parameters: { target: 'Files changed tab' },
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'Files changed tab' },
+                },
+                {
+                    action: 'analyze_changes',
+                    parameters: { focus: 'security and performance' },
+                },
+            ],
+        });
+        // Login Workflow
+        this.registerTemplate({
+            name: 'login_workflow',
+            description: 'Automated login to common services',
+            requiredParameters: ['service'],
+            expectedDuration: 30,
+            successCriteria: ['Successfully logged in'],
+            steps: [
+                {
+                    action: 'detect_login_form',
+                    parameters: {},
+                },
+                {
+                    action: 'type',
+                    parameters: {
+                        element: 'username input',
+                        text: '{username}',
+                    },
+                },
+                {
+                    action: 'type',
+                    parameters: {
+                        element: 'password input',
+                        text: '{password}',
+                    },
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'login button' },
+                },
+                {
+                    action: 'wait_for',
+                    parameters: { target: 'dashboard or home page' },
+                    timeout: 15000,
+                },
+            ],
+        });
+        // Repository Analysis
+        this.registerTemplate({
+            name: 'repository_analysis',
+            description: 'Comprehensive repository health and activity analysis',
+            requiredParameters: ['repository'],
+            expectedDuration: 90,
+            successCriteria: ['Analysis report generated'],
+            steps: [
+                {
+                    action: 'navigate',
+                    parameters: { url: 'https://github.com/{repository}' },
+                },
+                {
+                    action: 'analyze_readme',
+                    parameters: {},
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'Issues tab' },
+                },
+                {
+                    action: 'analyze_issues',
+                    parameters: {},
+                },
+                {
+                    action: 'click',
+                    parameters: { element: 'Pull requests tab' },
+                },
+                {
+                    action: 'analyze_pull_requests',
+                    parameters: {},
+                },
+                {
+                    action: 'generate_report',
+                    parameters: { format: 'summary' },
+                },
+            ],
+        });
+    }
+    /**
+     * Register a new workflow template
+     */
+    registerTemplate(template) {
+        this.templates.set(template.name, template);
+    }
+    /**
+     * Get available workflow templates
+     */
+    getTemplates() {
+        return Array.from(this.templates.values());
+    }
+    /**
+     * Execute a workflow by name
+     */
+    async executeWorkflow(context, templateName, parameters) {
+        const template = this.templates.get(templateName);
+        if (!template)
+            throw new Error(`Workflow template '${templateName}' not found`);
+        // Validate required parameters
+        for (const required of template.requiredParameters) {
+            if (!(required in parameters))
+                throw new Error(`Missing required parameter: ${required}`);
+        }
+        const executionId = `${templateName}_${Date.now()}`;
+        const execution = {
+            templateName,
+            status: 'running',
+            currentStep: 0,
+            startTime: Date.now(),
+            parameters,
+            results: [],
+            errors: [],
+        };
+        this.executions.set(executionId, execution);
+        try {
+            for (let i = 0; i < template.steps.length; i++) {
+                execution.currentStep = i;
+                const step = template.steps[i];
+                // Replace parameter placeholders
+                const resolvedStep = this.resolveStepParameters(step, parameters);
+                try {
+                    const result = await this.executeStep(context, resolvedStep);
+                    execution.results.push(result);
+                    // Validate step result if validation function provided
+                    if (step.validation && !step.validation(result))
+                        throw new Error(`Step validation failed for step ${i}`);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                    execution.errors.push(`Step ${i}: ${errorMessage}`);
+                    // Handle error based on step configuration
+                    const onError = step.onError || 'abort';
+                    if (onError === 'abort') {
+                        execution.status = 'failed';
+                        return execution;
+                    }
+                    else if (onError === 'retry' && (step.retryCount || 0) > 0) {
+                        // Implement retry logic
+                        for (let retry = 0; retry < (step.retryCount || 0); retry++) {
+                            try {
+                                const retryResult = await this.executeStep(context, resolvedStep);
+                                execution.results.push(retryResult);
+                                break;
+                            }
+                            catch (retryError) {
+                                if (retry === (step.retryCount || 0) - 1)
+                                    throw retryError;
+                            }
+                        }
+                    }
+                    // Continue to next step if onError is 'continue'
+                }
+            }
+            execution.status = 'completed';
+        }
+        catch (error) {
+            execution.status = 'failed';
+            execution.errors.push(error instanceof Error ? error.message : 'Unknown error');
+        }
+        return execution;
+    }
+    /**
+     * Resolve parameter placeholders in step
+     */
+    resolveStepParameters(step, parameters) {
+        const resolved = { ...step };
+        resolved.parameters = { ...step.parameters };
+        // Replace {parameter} placeholders
+        for (const [key, value] of Object.entries(resolved.parameters)) {
+            if (typeof value === 'string') {
+                resolved.parameters[key] = value.replace(/\{(\w+)\}/g, (match, paramName) => {
+                    return parameters[paramName] || match;
+                });
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Map workflow action names to browser tool names
+     */
+    actionToToolMap = {
+        'navigate': 'browser_navigate',
+        'click': 'browser_click',
+        'conditional_click': 'browser_click',
+        'type': 'browser_type',
+        'wait_for': 'browser_wait_for',
+        'screenshot': 'browser_screenshot',
+        'snapshot': 'browser_snapshot',
+        'detect_login_form': 'browser_snapshot',
+        'analyze_readme': 'browser_snapshot',
+        'analyze_issues': 'browser_snapshot',
+        'analyze_pull_requests': 'browser_snapshot',
+        'analyze_changes': 'browser_snapshot',
+        'generate_report': 'browser_snapshot',
+    };
+    /**
+     * Execute a single workflow step using the browser tool system
+     */
+    async executeStep(context, step) {
+        const startTime = Date.now();
+        // Map action to tool name
+        const toolName = this.actionToToolMap[step.action] || `browser_${step.action}`;
+        // Find the tool in context
+        const tool = context.tools.find(t => t.schema.name === toolName);
+        if (!tool) {
+            return {
+                action: step.action,
+                toolName,
+                success: false,
+                error: `Tool '${toolName}' not found for action '${step.action}'`,
+                timestamp: startTime,
+                duration: Date.now() - startTime,
+            };
+        }
+        // Build tool parameters from step parameters
+        const toolParams = {};
+        // Map common workflow parameters to tool parameters
+        if (step.parameters.url)
+            toolParams.url = step.parameters.url;
+        if (step.parameters.element)
+            toolParams.element = step.parameters.element;
+        if (step.parameters.text)
+            toolParams.text = step.parameters.text;
+        if (step.parameters.target)
+            toolParams.text = step.parameters.target; // wait_for uses 'text' param
+        // Handle conditional actions
+        if (step.action === 'conditional_click' && step.parameters.condition) {
+            const conditionFn = step.parameters.condition;
+            if (typeof conditionFn === 'function' && !conditionFn(step.parameters)) {
+                return {
+                    action: step.action,
+                    toolName,
+                    success: true,
+                    skipped: true,
+                    reason: 'Condition not met',
+                    timestamp: startTime,
+                    duration: Date.now() - startTime,
+                };
+            }
+        }
+        try {
+            // Execute the tool through context.run()
+            const result = await context.run(tool, toolParams);
+            return {
+                action: step.action,
+                toolName,
+                parameters: toolParams,
+                success: true,
+                result,
+                timestamp: startTime,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                action: step.action,
+                toolName,
+                parameters: toolParams,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                timestamp: startTime,
+                duration: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Get workflow execution status
+     */
+    getExecution(executionId) {
+        return this.executions.get(executionId);
+    }
+    /**
+     * List all active executions
+     */
+    getActiveExecutions() {
+        return Array.from(this.executions.values()).filter(execution => execution.status === 'running' || execution.status === 'paused');
+    }
+    /**
+     * Cancel a running workflow
+     */
+    cancelExecution(executionId) {
+        const execution = this.executions.get(executionId);
+        if (execution && execution.status === 'running') {
+            execution.status = 'failed';
+            execution.errors.push('Workflow cancelled by user');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Suggest workflows based on current context
+     */
+    suggestWorkflows(currentUrl, pageContent) {
+        const suggestions = [];
+        // GitHub-specific suggestions
+        if (currentUrl.includes('github.com')) {
+            if (currentUrl.includes('/issues'))
+                suggestions.push(this.templates.get('github_issue_management'));
+            if (currentUrl.includes('/pulls'))
+                suggestions.push(this.templates.get('code_review_workflow'));
+            suggestions.push(this.templates.get('repository_analysis'));
+        }
+        // Login form detection
+        if (pageContent.includes('password') && pageContent.includes('login'))
+            suggestions.push(this.templates.get('login_workflow'));
+        return suggestions.filter(Boolean);
+    }
+}
+// Global workflow engine instance
+export const workflowEngine = new WorkflowEngine();

package/lib/auth/apiKeyAuth.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) DarbotLabs.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export class ApiKeyAuthenticator {
+    _enabled;
+    _keys;
+    constructor(config) {
+        this._enabled = !!config.enabled;
+        this._keys = new Set((config.keys || []).map(k => k.trim()).filter(Boolean));
+    }
+    get enabled() {
+        return this._enabled;
+    }
+    /**
+     * Returns true when a provided X-API-Key matches one of the configured keys.
+     *
+     * If auth is disabled, returns true.
+     */
+    authenticate(req) {
+        if (!this._enabled)
+            return true;
+        const apiKeyHeader = req.headers['x-api-key'];
+        const apiKey = Array.isArray(apiKeyHeader) ? apiKeyHeader[0] : apiKeyHeader;
+        if (!apiKey)
+            return false;
+        return this._keys.has(apiKey);
+    }
+}
+export function createApiKeyAuthenticatorFromEnv() {
+    return new ApiKeyAuthenticator({
+        enabled: process.env.API_KEY_AUTH_ENABLED === 'true',
+        keys: (process.env.API_KEYS || '').split(',').map(s => s.trim()).filter(Boolean),
+    });
+}

package/lib/auth/entraAuth.js

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) DarbotLabs.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { verifyEntraJwt } from './entraJwtVerifier.js';
+/**
+ * Middleware for Microsoft Entra ID authentication
+ * Validates JWT tokens from Microsoft identity platform
+ */
+export class EntraIDAuthenticator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Validates the authorization header and extracts user information
+     */
+    async authenticate(req) {
+        if (!this.config.enabled) {
+            // Return a default user when authentication is disabled (for development)
+            return {
+                userId: 'dev-user',
+                tenantId: 'dev-tenant',
+                roles: ['user'],
+                permissions: ['browser:read', 'browser:write']
+            };
+        }
+        const authHeader = req.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer '))
+            return null;
+        const token = authHeader.substring(7);
+        return await this.validateToken(token);
+    }
+    /**
+     * Validates JWT token from Microsoft identity platform
+     */
+    async validateToken(token) {
+        try {
+            const tenantId = this.config.tenantId;
+            const clientId = this.config.clientId;
+            if (!tenantId || !clientId)
+                throw new Error('Entra auth is enabled but AZURE_TENANT_ID or AZURE_CLIENT_ID is not configured');
+            const payload = await verifyEntraJwt(token, { tenantId, clientId });
+            const tid = payload.tid || tenantId;
+            const oid = payload.oid;
+            const sub = payload.sub;
+            const userId = oid || sub;
+            if (!userId)
+                return null;
+            const rolesClaim = payload.roles;
+            const roles = Array.isArray(rolesClaim)
+                ? rolesClaim.filter((r) => typeof r === 'string')
+                : [];
+            const scp = payload.scp;
+            const permissions = scp ? scp.split(' ').map(s => s.trim()).filter(Boolean) : [];
+            return {
+                userId,
+                tenantId: tid,
+                roles,
+                permissions,
+            };
+        }
+        catch (error) {
+            // TODO: Replace with proper logging system
+            // eslint-disable-next-line no-console
+            console.error('Token validation failed:', error);
+            return null;
+        }
+    }
+    /**
+     * Middleware function for HTTP requests
+     */
+    middleware() {
+        return async (req, res, next) => {
+            const user = await this.authenticate(req);
+            if (!user && this.config.enabled) {
+                res.statusCode = 401;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ error: 'Unauthorized', message: 'Valid authentication required' }));
+                return;
+            }
+            // Attach user to request for downstream handlers
+            req.user = user;
+            next();
+        };
+    }
+}
+/**
+ * Creates an Entra ID authenticator from environment variables
+ */
+export function createEntraIDAuthenticator() {
+    const config = {
+        tenantId: process.env.AZURE_TENANT_ID,
+        clientId: process.env.AZURE_CLIENT_ID,
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+        enabled: process.env.ENTRA_AUTH_ENABLED === 'true'
+    };
+    return new EntraIDAuthenticator(config);
+}

package/lib/auth/entraJwtVerifier.js

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) DarbotLabs.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ConfidentialClientApplication, LogLevel } from '@azure/msal-node';
+// Cache MSAL client instances per tenant/client combination
+const msalClientCache = new Map();
+function getMsalClient(config) {
+    const { tenantId, clientId, clientSecret } = config;
+    const cacheKey = `${tenantId}:${clientId}`;
+    let client = msalClientCache.get(cacheKey);
+    if (!client) {
+        const msalConfig = {
+            auth: {
+                clientId,
+                authority: `https://login.microsoftonline.com/${tenantId}`,
+                clientSecret: clientSecret || process.env.AZURE_CLIENT_SECRET || '',
+            },
+            system: {
+                loggerOptions: {
+                    loggerCallback(loglevel, message, containsPii) {
+                        if (containsPii || loglevel > LogLevel.Warning)
+                            return;
+                        // eslint-disable-next-line no-console
+                        console.error(`MSAL [${LogLevel[loglevel]}]: ${message}`);
+                    },
+                    piiLoggingEnabled: false,
+                    logLevel: process.env.NODE_ENV === 'production' ? LogLevel.Warning : LogLevel.Info,
+                },
+            },
+        };
+        client = new ConfidentialClientApplication(msalConfig);
+        msalClientCache.set(cacheKey, client);
+    }
+    return client;
+}
+/**
+ * Decodes JWT payload without verification (for extracting claims after OBO validation)
+ */
+function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('Invalid JWT format');
+    const payloadBase64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const payloadJson = Buffer.from(payloadBase64, 'base64').toString('utf8');
+    return JSON.parse(payloadJson);
+}
+/**
+ * Validates an Entra ID JWT token using MSAL On-Behalf-Of flow.
+ * This validates the token by attempting to exchange it, proving it's valid.
+ * If OBO fails (e.g., no client secret), falls back to basic claim validation.
+ */
+export async function verifyEntraJwt(token, config) {
+    const { tenantId, clientId, clientSecret } = config;
+    if (!tenantId || !clientId)
+        throw new Error('Entra JWT validation misconfigured: missing tenantId or clientId');
+    // Decode token to extract claims
+    const payload = decodeJwtPayload(token);
+    // Validate basic claims
+    const issuerV2 = `https://login.microsoftonline.com/${tenantId}/v2.0`;
+    const issuerV1 = `https://sts.windows.net/${tenantId}/`;
+    const validIssuers = [issuerV2, issuerV1];
+    if (payload.iss && !validIssuers.includes(payload.iss))
+        throw new Error(`Invalid token issuer: ${payload.iss}`);
+    // Validate audience
+    const validAudiences = [clientId, `api://${clientId}`];
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    const hasValidAudience = aud.some(a => a && validAudiences.includes(a));
+    if (!hasValidAudience)
+        throw new Error(`Invalid token audience: ${payload.aud}`);
+    // Validate expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now)
+        throw new Error('Token has expired');
+    if (payload.nbf && payload.nbf > now)
+        throw new Error('Token not yet valid');
+    // If we have a client secret, validate token via OBO flow (cryptographic validation)
+    const secret = clientSecret || process.env.AZURE_CLIENT_SECRET;
+    if (secret) {
+        try {
+            const msalClient = getMsalClient({ ...config, clientSecret: secret });
+            // Attempt OBO to validate the token - this proves token signature is valid
+            // We request the same scope to validate without actually needing a downstream API
+            await msalClient.acquireTokenOnBehalfOf({
+                oboAssertion: token,
+                scopes: [`api://${clientId}/.default`],
+            });
+        }
+        catch (oboError) {
+            // AADSTS65001 means the token is valid but user hasn't consented to the scope
+            // AADSTS50013 means assertion audience doesn't match - token may be for different app
+            // Other errors may indicate invalid token
+            const errorCode = oboError?.errorCode || '';
+            const errorMessage = oboError?.message || '';
+            // These error codes indicate the token itself is valid, just scope/consent issues
+            const validTokenErrors = ['AADSTS65001', 'AADSTS50013', 'AADSTS700024'];
+            const isValidTokenError = validTokenErrors.some(code => errorCode.includes(code) || errorMessage.includes(code));
+            if (!isValidTokenError) {
+                // Token is actually invalid
+                throw new Error(`Token validation failed: ${errorMessage}`);
+            }
+            // Token is valid, just can't do OBO for scope reasons - that's OK
+        }
+    }
+    return payload;
+}