cbrowser 18.3.10 → 18.3.12

package/dist/security/tool-permissions.js

@@ -0,0 +1,317 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Per-Tool Permission Model for CBrowser MCP Server
+ *
+ * Provides granular permission control for MCP tools based on security zones.
+ * Users can override default zone assignments to customize tool access.
+ *
+ * Zone Levels:
+ * - GREEN: Read-only, always safe - auto-execute
+ * - YELLOW: Interactive but safe - allowed, no confirmation
+ * - ORANGE: State-modifying - allowed with warning
+ * - RED: Sensitive/Autonomous - requires --force flag
+ * - BLACK: Prohibited - always blocked, even with --force
+ *
+ * Storage: ~/.cbrowser/tool-permissions.json
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ============================================================================
+// Default Zone Assignments
+// ============================================================================
+/**
+ * Default zone assignments for CBrowser tools.
+ * Conservative by default - unknown tools are classified as YELLOW.
+ */
+export const DEFAULT_ZONES = {
+    // =========================================================================
+    // GREEN - Read-only, always safe
+    // =========================================================================
+    navigate: "green",
+    screenshot: "green",
+    extract: "green",
+    status: "green",
+    list_sessions: "green",
+    list_baselines: "green",
+    list_cognitive_personas: "green",
+    list_influence_patterns: "green",
+    persona_traits_list: "green",
+    persona_values_lookup: "green",
+    persona_trait_lookup: "green",
+    visual_baseline: "green",
+    heal_stats: "green",
+    stealth_status: "green",
+    stealth_check: "green",
+    browser_health: "green",
+    perf_baseline: "green",
+    ab_comparison: "green",
+    coverage_map: "green",
+    compare_personas_init: "green",
+    compare_personas_complete: "green",
+    competitive_benchmark: "green",
+    cross_browser_diff: "green",
+    agent_ready_audit: "green",
+    empathy_audit: "green",
+    api_key_status: "green",
+    get_api_key_prompt: "green",
+    marketing_discover_status: "green",
+    marketing_personas_list: "green",
+    // =========================================================================
+    // YELLOW - Interactive but safe
+    // =========================================================================
+    click: "yellow",
+    hover: "yellow",
+    scroll: "yellow",
+    assert: "yellow",
+    analyze_page: "yellow",
+    find_element_by_intent: "yellow",
+    dismiss_overlay: "yellow",
+    compare_personas: "yellow",
+    cloudflare_detect: "yellow",
+    cloudflare_wait: "yellow",
+    persona_category_guidance: "yellow",
+    persona_questionnaire_get: "yellow",
+    load_session: "yellow",
+    visual_regression: "yellow",
+    perf_regression: "yellow",
+    responsive_test: "yellow",
+    cross_browser_test: "yellow",
+    // =========================================================================
+    // ORANGE - State-modifying
+    // =========================================================================
+    fill: "orange",
+    smart_click: "orange",
+    save_session: "orange",
+    delete_session: "orange",
+    reset_browser: "orange",
+    browser_recover: "orange",
+    persona_create_start: "orange",
+    persona_create_submit_traits: "orange",
+    persona_create_from_description: "orange",
+    persona_create_questionnaire_start: "orange",
+    persona_create_questionnaire_answer: "orange",
+    persona_questionnaire_build: "orange",
+    persona_create_cancel: "orange",
+    cognitive_journey_init: "orange",
+    cognitive_journey_update_state: "orange",
+    nl_test_inline: "orange",
+    nl_test_file: "orange",
+    generate_tests: "orange",
+    repair_test: "orange",
+    detect_flaky_tests: "orange",
+    hunt_bugs: "orange",
+    marketing_audience_discover: "orange",
+    marketing_campaign_create: "orange",
+    marketing_campaign_run: "orange",
+    marketing_campaign_report_result: "orange",
+    marketing_compete: "orange",
+    marketing_funnel_analyze: "orange",
+    marketing_influence_matrix: "orange",
+    marketing_lever_analysis: "orange",
+    // =========================================================================
+    // RED - Sensitive/Autonomous (requires --force)
+    // =========================================================================
+    cognitive_journey_autonomous: "red",
+    stealth_enable: "red",
+    stealth_disable: "red",
+    stealth_diagnose: "red",
+    chaos_test: "red",
+    set_api_key: "red",
+    clear_api_key: "red",
+    ask_user: "red", // Can be used for social engineering
+};
+// Valid zone values for validation
+const VALID_ZONES = new Set(["green", "yellow", "orange", "red", "black"]);
+// ============================================================================
+// File Path Utilities
+// ============================================================================
+/**
+ * Get the path to the tool permissions file.
+ */
+function getPermissionsPath() {
+    const dataDir = process.env.CBROWSER_DATA_DIR || join(homedir(), ".cbrowser");
+    return join(dataDir, "tool-permissions.json");
+}
+/**
+ * Ensure the data directory exists.
+ */
+function ensureDataDir() {
+    const dataDir = process.env.CBROWSER_DATA_DIR || join(homedir(), ".cbrowser");
+    if (!existsSync(dataDir)) {
+        mkdirSync(dataDir, { recursive: true });
+    }
+}
+// ============================================================================
+// Configuration Functions
+// ============================================================================
+/**
+ * Load tool permissions from file.
+ *
+ * @returns The permission config, or null if no file exists or file is invalid
+ */
+export function loadToolPermissions() {
+    const path = getPermissionsPath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(path, "utf-8");
+        if (!content.trim()) {
+            return null;
+        }
+        const config = JSON.parse(content);
+        // Validate the structure
+        if (!config.toolPermissions || typeof config.toolPermissions !== "object") {
+            return null;
+        }
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save tool permissions to file.
+ *
+ * @param config The permission config to save
+ */
+export function saveToolPermissions(config) {
+    ensureDataDir();
+    const path = getPermissionsPath();
+    writeFileSync(path, JSON.stringify(config, null, 2));
+}
+/**
+ * Set the zone for a specific tool.
+ * Creates the permission file if it doesn't exist.
+ *
+ * @param tool The tool name
+ * @param zone The zone to assign
+ */
+export function setToolZone(tool, zone) {
+    let config = loadToolPermissions();
+    if (!config) {
+        config = {
+            toolPermissions: {},
+            lastUpdated: new Date().toISOString(),
+        };
+    }
+    config.toolPermissions[tool] = zone;
+    config.lastUpdated = new Date().toISOString();
+    saveToolPermissions(config);
+}
+/**
+ * Get the zone for a tool.
+ * Returns user override if set, otherwise returns default zone.
+ * Unknown tools default to YELLOW (conservative).
+ *
+ * @param tool The tool name
+ * @returns The zone classification
+ */
+export function getToolZone(tool) {
+    // Check for user override first
+    const config = loadToolPermissions();
+    if (config?.toolPermissions[tool]) {
+        const userZone = config.toolPermissions[tool];
+        // Validate the zone is valid
+        if (VALID_ZONES.has(userZone)) {
+            return userZone;
+        }
+    }
+    // Fall back to default
+    return DEFAULT_ZONES[tool] || "yellow";
+}
+/**
+ * Check if a tool is allowed to execute based on its zone.
+ *
+ * @param tool The tool name
+ * @param forceFlag Whether the --force flag was provided
+ * @returns Permission check result
+ */
+export function checkToolPermission(tool, forceFlag = false) {
+    const config = loadToolPermissions();
+    const hasOverride = config?.toolPermissions[tool] && VALID_ZONES.has(config.toolPermissions[tool]);
+    const zone = getToolZone(tool);
+    const source = hasOverride ? "user_override" : "default";
+    const result = {
+        tool,
+        zone,
+        source,
+        allowed: false,
+        requiresForce: false,
+    };
+    switch (zone) {
+        case "green":
+            // Always allowed, no restrictions
+            result.allowed = true;
+            result.requiresForce = false;
+            break;
+        case "yellow":
+            // Allowed without confirmation
+            result.allowed = true;
+            result.requiresForce = false;
+            break;
+        case "orange":
+            // Allowed with warning
+            result.allowed = true;
+            result.requiresForce = false;
+            result.message = `Tool '${tool}' is state-modifying (orange zone). Proceeding with caution.`;
+            break;
+        case "red":
+            // Requires --force flag
+            result.requiresForce = true;
+            if (forceFlag) {
+                result.allowed = true;
+                result.message = `Tool '${tool}' is sensitive (red zone). Executing with --force override.`;
+            }
+            else {
+                result.allowed = false;
+                result.message = `Tool '${tool}' is classified as RED (sensitive/autonomous). Use --force flag to execute.`;
+            }
+            break;
+        case "black":
+            // Always blocked, even with --force
+            result.allowed = false;
+            result.requiresForce = false;
+            result.message = `Tool '${tool}' is prohibited (black zone). This action is not allowed.`;
+            break;
+    }
+    return result;
+}
+/**
+ * List all tool zones (both defaults and overrides).
+ *
+ * @returns Map of tool names to zone info
+ */
+export function listToolZones() {
+    const result = {};
+    // Add all default zones
+    for (const [tool, zone] of Object.entries(DEFAULT_ZONES)) {
+        result[tool] = { zone, source: "default" };
+    }
+    // Overlay user overrides
+    const config = loadToolPermissions();
+    if (config?.toolPermissions) {
+        for (const [tool, zone] of Object.entries(config.toolPermissions)) {
+            if (VALID_ZONES.has(zone)) {
+                result[tool] = { zone, source: "user_override" };
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Reset all tool zones to defaults.
+ * Removes the permission file entirely.
+ */
+export function resetToolZones() {
+    const path = getPermissionsPath();
+    if (existsSync(path)) {
+        rmSync(path);
+    }
+}
+//# sourceMappingURL=tool-permissions.js.map

package/dist/security/tool-permissions.js.map

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

package/dist/security/tool-pinning.d.ts

@@ -0,0 +1,143 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * A tool definition for pinning purposes.
+ * Extracted from MCP server tool registration.
+ */
+export interface ToolDefinition {
+    /** Tool name (unique identifier) */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Tool input schema (Zod schema converted to JSON Schema) */
+    schema: unknown;
+}
+/**
+ * Entry for a single pinned tool in the manifest.
+ */
+export interface ToolPinEntry {
+    /** SHA-256 hash of name + description + JSON.stringify(schema) */
+    hash: string;
+    /** Length of description (for quick diff detection) */
+    descriptionLength: number;
+    /** Number of parameters in schema (for quick diff detection) */
+    parameterCount: number;
+    /** ISO timestamp when this tool was pinned */
+    pinnedAt: string;
+}
+/**
+ * The complete tool manifest stored on disk.
+ */
+export interface ToolManifest {
+    /** Server identifier */
+    server: string;
+    /** CBrowser version that created this manifest */
+    version: string;
+    /** ISO timestamp when manifest was created */
+    pinnedAt: string;
+    /** Map of tool name -> pin entry */
+    tools: Record<string, ToolPinEntry>;
+}
+/**
+ * Result of verifying tool definitions against the manifest.
+ */
+export interface PinningResult {
+    /** Overall status */
+    status: "created" | "verified" | "changed" | "error";
+    /** Tools that have different hashes than pinned */
+    changedTools?: string[];
+    /** Tools present in definitions but not in manifest */
+    newTools?: string[];
+    /** Tools in manifest but not in definitions */
+    removedTools?: string[];
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Get the path to the tool manifest file.
+ * Uses ~/.cbrowser/tool-manifest.json by default.
+ */
+export declare function getManifestPath(): string;
+/**
+ * Create a SHA-256 hash of a tool definition.
+ *
+ * The hash includes:
+ * - Tool name
+ * - Tool description
+ * - JSON-stringified schema (sorted keys for consistency)
+ *
+ * @param name - Tool name
+ * @param description - Tool description
+ * @param schema - Tool schema object
+ * @returns 64-character hex SHA-256 hash
+ */
+export declare function hashToolDefinition(name: string, description: string, schema: unknown): string;
+/**
+ * Create a new tool manifest from a list of tool definitions.
+ *
+ * @param tools - Array of tool definitions
+ * @returns Complete manifest ready for saving
+ */
+export declare function createToolManifest(tools: ToolDefinition[]): ToolManifest;
+/**
+ * Load the tool manifest from disk.
+ *
+ * @returns Manifest if it exists and is valid, null otherwise
+ */
+export declare function loadToolManifest(): ToolManifest | null;
+/**
+ * Save a tool manifest to disk.
+ * Creates the directory if it doesn't exist.
+ *
+ * @param manifest - The manifest to save
+ */
+export declare function saveToolManifest(manifest: ToolManifest): void;
+/**
+ * Verify tool definitions against the pinned manifest.
+ *
+ * Behavior:
+ * - If no manifest exists: Creates one and returns status "created"
+ * - If all hashes match: Returns status "verified"
+ * - If any differences: Returns status "changed" with details
+ *
+ * @param tools - Current tool definitions from MCP server
+ * @returns Verification result
+ */
+export declare function verifyToolDefinitions(tools: ToolDefinition[]): PinningResult;
+/**
+ * Approve a tool change by updating its hash in the manifest.
+ * Used to re-approve a tool after intentional modification.
+ *
+ * @param toolName - Name of the tool to approve
+ * @param tool - Current tool definition
+ * @throws Error if no manifest exists
+ */
+export declare function approveToolChange(toolName: string, tool: ToolDefinition): void;
+/**
+ * Remove a tool from the manifest.
+ * Used when a tool is intentionally removed.
+ *
+ * @param toolName - Name of the tool to remove
+ * @throws Error if no manifest exists
+ */
+export declare function removeToolFromManifest(toolName: string): void;
+/**
+ * Approve all current tools, replacing the entire manifest.
+ * Use with caution - this trusts the current state completely.
+ *
+ * @param tools - Current tool definitions
+ */
+export declare function approveAllTools(tools: ToolDefinition[]): void;
+/**
+ * Get a summary of the current manifest for status display.
+ */
+export declare function getManifestSummary(): {
+    exists: boolean;
+    toolCount: number;
+    version: string | null;
+    pinnedAt: string | null;
+};
+//# sourceMappingURL=tool-pinning.d.ts.map

package/dist/security/tool-pinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-pinning.d.ts","sourceRoot":"","sources":["../../src/security/tool-pinning.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;IACrD,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,GACd,MAAM,CASR;AAiCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,CAmBxE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,GAAG,IAAI,CAsBtD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAU7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,aAAa,CA0E5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAiB9E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAG7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAkBA"}