@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/mcp/validators.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * src/mcp/validators.ts — lightweight, dependency-free runtime guards for tool
+ * arguments. The JSON Schema in `tools.ts` is the advertised contract; these
+ * guards defend each handler from malformed input and throw `McpToolError` with
+ * an actionable message (rendered as a structured `isError` result upstream).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpToolError = void 0;
+exports.asArgs = asArgs;
+exports.requireString = requireString;
+exports.optionalString = optionalString;
+exports.optionalBoolean = optionalBoolean;
+exports.optionalNumber = optionalNumber;
+exports.optionalStringArray = optionalStringArray;
+exports.requireTarget = requireTarget;
+exports.optionalTarget = optionalTarget;
+/**
+ * Thrown when a tool request can't be fulfilled for a caller-actionable reason
+ * (bad args, exactly-one-of violation, …). The dispatch firewall converts it to
+ * an `isError` result, so it never tears down the transport.
+ */
+class McpToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpToolError';
+    }
+}
+exports.McpToolError = McpToolError;
+/** Coerce raw tool args into a plain object, rejecting non-objects. */
+function asArgs(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new McpToolError('tool arguments must be a JSON object');
+    }
+    return raw;
+}
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new McpToolError(`"${key}" is required and must be a non-empty string`);
+    }
+    return v;
+}
+function optionalString(args, key) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string')
+        throw new McpToolError(`"${key}" must be a string`);
+    return v;
+}
+function optionalBoolean(args, key) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'boolean')
+        throw new McpToolError(`"${key}" must be a boolean`);
+    return v;
+}
+function optionalNumber(args, key, bounds) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new McpToolError(`"${key}" must be a finite number`);
+    }
+    if (bounds?.min !== undefined && v < bounds.min)
+        throw new McpToolError(`"${key}" must be >= ${bounds.min}`);
+    if (bounds?.max !== undefined && v > bounds.max)
+        throw new McpToolError(`"${key}" must be <= ${bounds.max}`);
+    return v;
+}
+function optionalStringArray(args, key) {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (!Array.isArray(v) || v.some((x) => typeof x !== 'string')) {
+        throw new McpToolError(`"${key}" must be an array of strings`);
+    }
+    return v;
+}
+/**
+ * Require EXACTLY ONE of `selector` | `ref`. Returns a normalized `Target`.
+ * Both-present and neither-present are both errors — the contract is one-of.
+ */
+function requireTarget(args) {
+    const hasSel = typeof args.selector === 'string' && args.selector.length > 0;
+    const hasRef = typeof args.ref === 'string' && args.ref.length > 0;
+    if (hasSel === hasRef) {
+        throw new McpToolError('provide exactly one of "selector" or "ref"');
+    }
+    return hasSel ? { selector: args.selector } : { ref: args.ref };
+}
+/** Like `requireTarget` but the target is optional (whole-page reads). */
+function optionalTarget(args) {
+    const hasSel = typeof args.selector === 'string' && args.selector.length > 0;
+    const hasRef = typeof args.ref === 'string' && args.ref.length > 0;
+    if (!hasSel && !hasRef)
+        return undefined;
+    return requireTarget(args);
+}
+//# sourceMappingURL=validators.js.map

package/dist/src/security/policy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * src/security/policy.ts — the default-deny domain policy and capability gate.
+ *
+ * This is the real exfiltration firewall. Because this tool feeds untrusted page
+ * text to an LLM that can call `eval`, prompt-injection-to-exfil is a PRIMARY
+ * threat, so the policy:
+ *   - is ON by default with a SAFE default (empty allowlist, no eval, no
+ *     downloads, mutations disabled),
+ *   - gates READS as well as writes (reads are the exfil payload),
+ *   - is enforced at BOTH ends — the executor dispatch (server) AND the
+ *     extension router — before any attach/navigate/eval/read.
+ *
+ * `assertUrlAllowed(url, method, policy)` is the single chokepoint. It throws an
+ * `ExecutorError('POLICY_DENIED', …)` which the never-throw dispatch firewall
+ * renders as a structured MCP error.
+ */
+import type { WireMethod } from '../../shared/protocol';
+export interface Policy {
+    /** Glob domain allowlist, e.g. ['example.com', '*.example.com', '*']. Empty = deny all. */
+    allowDomains: string[];
+    /** Allow the `eval` primitive at all. */
+    allowEval: boolean;
+    /** Allow `download_file`. */
+    allowDownloads: boolean;
+    /** Allow acting on / reading tabs whose URL is not in `allowDomains` is governed
+     *  by `allowDomains`; this flag instead relaxes tab *management* (list/select)
+     *  to all tabs regardless of their URL. Default false. */
+    allowAllTabs: boolean;
+    /** Safe-mode master switch for the mutating tool set (click/type/navigate/…). */
+    enableMutations: boolean;
+}
+/** The SAFE default: deny everything until the user opts in. */
+export declare const DEFAULT_POLICY: Readonly<Policy>;
+/** Merge a partial (from a policy file and/or CLI flags) over the safe default. */
+export declare function resolvePolicy(partial?: Partial<Policy>): Policy;
+export declare function isReadMethod(method: WireMethod): boolean;
+/** Everything in the mutating tool set that safe-mode disables. `eval` is gated
+ *  separately via `allowEval`; `download_file` separately via `allowDownloads`. */
+export declare function isMutatingMethod(method: WireMethod): boolean;
+/** Parse a host out of a URL string; '' if it has none (about:blank, data:, …). */
+export declare function hostOf(url: string): string;
+export declare function isDomainAllowed(url: string, policy: Policy): boolean;
+/**
+ * Throw `POLICY_DENIED` unless `method` against `url` is permitted by `policy`.
+ * `url` is the DESTINATION for navigation, otherwise the current tab URL.
+ * Pure and side-effect-free so it can run identically on server and extension.
+ */
+export declare function assertUrlAllowed(url: string, method: WireMethod, policy: Policy): void;

package/dist/src/security/policy.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * src/security/policy.ts — the default-deny domain policy and capability gate.
+ *
+ * This is the real exfiltration firewall. Because this tool feeds untrusted page
+ * text to an LLM that can call `eval`, prompt-injection-to-exfil is a PRIMARY
+ * threat, so the policy:
+ *   - is ON by default with a SAFE default (empty allowlist, no eval, no
+ *     downloads, mutations disabled),
+ *   - gates READS as well as writes (reads are the exfil payload),
+ *   - is enforced at BOTH ends — the executor dispatch (server) AND the
+ *     extension router — before any attach/navigate/eval/read.
+ *
+ * `assertUrlAllowed(url, method, policy)` is the single chokepoint. It throws an
+ * `ExecutorError('POLICY_DENIED', …)` which the never-throw dispatch firewall
+ * renders as a structured MCP error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLICY = void 0;
+exports.resolvePolicy = resolvePolicy;
+exports.isReadMethod = isReadMethod;
+exports.isMutatingMethod = isMutatingMethod;
+exports.hostOf = hostOf;
+exports.isDomainAllowed = isDomainAllowed;
+exports.assertUrlAllowed = assertUrlAllowed;
+const types_1 = require("../executor/types");
+/** The SAFE default: deny everything until the user opts in. */
+exports.DEFAULT_POLICY = Object.freeze({
+    allowDomains: [],
+    allowEval: false,
+    allowDownloads: false,
+    allowAllTabs: false,
+    enableMutations: false,
+});
+/** Merge a partial (from a policy file and/or CLI flags) over the safe default. */
+function resolvePolicy(partial) {
+    return {
+        allowDomains: partial?.allowDomains ?? [...exports.DEFAULT_POLICY.allowDomains],
+        allowEval: partial?.allowEval ?? exports.DEFAULT_POLICY.allowEval,
+        allowDownloads: partial?.allowDownloads ?? exports.DEFAULT_POLICY.allowDownloads,
+        allowAllTabs: partial?.allowAllTabs ?? exports.DEFAULT_POLICY.allowAllTabs,
+        enableMutations: partial?.enableMutations ?? exports.DEFAULT_POLICY.enableMutations,
+    };
+}
+// ---------------------------------------------------------------------------
+// Method classification
+// ---------------------------------------------------------------------------
+/** Methods that read page CONTENT (the exfil payload) — URL-gated. */
+const READ_CONTENT = new Set([
+    'get_text',
+    'get_html',
+    'screenshot',
+    'wait_for',
+]);
+/** Content-mutating actions — URL-gated AND mutation-gated. */
+const MUTATE_CONTENT = new Set([
+    'click',
+    'type',
+    'press',
+    'hover',
+    'scroll',
+]);
+/** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
+const NAVIGATION = new Set([
+    'navigate',
+    'back',
+    'forward',
+    'reload',
+]);
+/** Tab management — mutation-gated, but not content-URL-gated (unless allowAllTabs is off). */
+const TAB_MUTATE = new Set([
+    'tab_select',
+    'tab_new',
+    'tab_close',
+]);
+function isReadMethod(method) {
+    return READ_CONTENT.has(method) || method === 'tabs_list';
+}
+/** Everything in the mutating tool set that safe-mode disables. `eval` is gated
+ *  separately via `allowEval`; `download_file` separately via `allowDownloads`. */
+function isMutatingMethod(method) {
+    return MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || TAB_MUTATE.has(method);
+}
+/** Whether the method touches a specific URL that must be allowlisted. */
+function isUrlGated(method) {
+    return READ_CONTENT.has(method) || MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || method === 'eval';
+}
+// ---------------------------------------------------------------------------
+// Domain matching
+// ---------------------------------------------------------------------------
+/** Parse a host out of a URL string; '' if it has none (about:blank, data:, …). */
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+function isAboutBlank(url) {
+    return url === 'about:blank' || url === '' || url.startsWith('about:');
+}
+/** Convert a single domain glob to a predicate. '*' matches everything;
+ *  '*.example.com' matches example.com and any subdomain; otherwise exact host. */
+function globMatches(host, pattern) {
+    const p = pattern.trim().toLowerCase();
+    if (p === '*' || p === '*://*/*')
+        return true;
+    if (p.startsWith('*.')) {
+        const base = p.slice(2);
+        return host === base || host.endsWith('.' + base);
+    }
+    return host === p;
+}
+function isDomainAllowed(url, policy) {
+    const host = hostOf(url);
+    if (!host)
+        return false;
+    return policy.allowDomains.some((pat) => globMatches(host, pat));
+}
+// ---------------------------------------------------------------------------
+// The gate
+// ---------------------------------------------------------------------------
+/**
+ * Throw `POLICY_DENIED` unless `method` against `url` is permitted by `policy`.
+ * `url` is the DESTINATION for navigation, otherwise the current tab URL.
+ * Pure and side-effect-free so it can run identically on server and extension.
+ */
+function assertUrlAllowed(url, method, policy) {
+    // -- capability gates (independent of URL) --
+    if (method === 'eval' && !policy.allowEval) {
+        throw new types_1.ExecutorError('POLICY_DENIED', 'eval is disabled (safe-mode). Pass --unsafe-enable-eval to allow it.');
+    }
+    if (method === 'download_file' && !policy.allowDownloads) {
+        throw new types_1.ExecutorError('POLICY_DENIED', 'downloads are disabled. Pass --enable-downloads or set allowDownloads.');
+    }
+    if (isMutatingMethod(method) && !policy.enableMutations) {
+        throw new types_1.ExecutorError('POLICY_DENIED', `mutating tool "${method}" is disabled (safe-mode). Pass --enable-mutations to allow it.`);
+    }
+    // -- tab management without allowAllTabs still needs the target tab's URL allowlisted,
+    //    but list/select/close don't carry a content URL here; treat them as allowed once
+    //    the mutation gate above has passed (URL-gating of their effect happens on the
+    //    subsequent content op). --
+    if (!isUrlGated(method))
+        return;
+    // Navigating to a blank page is always fine.
+    if (isAboutBlank(url) && NAVIGATION.has(method))
+        return;
+    if (!isDomainAllowed(url, policy)) {
+        const host = hostOf(url) || url;
+        throw new types_1.ExecutorError('POLICY_DENIED', `"${method}" denied: ${host} is not in the domain allowlist. ` +
+            `Add it to allowDomains, or pass --unsafe-all-domains.`);
+    }
+}
+//# sourceMappingURL=policy.js.map