@mxf-dev/core 2.0.5 → 3.1.0

package/src/protocols/mcp/providers/GeminiMcpClient.ts

@@ -545,6 +545,8 @@ export class GeminiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         if (!this.genAiClient) {
             throw new Error('Google Gen AI client not initialized');
         }

package/src/protocols/mcp/providers/OllamaMcpClient.ts

@@ -113,6 +113,8 @@ const logger = new Logger('debug', 'OllamaMcpClient', 'server');
  * Ollama MCP Client implementation
  */
 export class OllamaMcpClient extends BaseMcpClient {
+    protected isExternalLlmProvider = false;
+
     private baseUrl: string;
     private timeout: number;
 
@@ -561,4 +563,4 @@ export class OllamaMcpClient extends BaseMcpClient {
 
         return ollamaMsg;
     }
-}
+}

package/src/protocols/mcp/providers/OpenAiMcpClient.ts

@@ -601,6 +601,8 @@ export class OpenAiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure messages for OpenAI based on context
         const openAiMessages = this.structureMessagesFromContext(context);
 

package/src/protocols/mcp/providers/OpenRouterMcpClient.ts

@@ -664,6 +664,7 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
 
         // Structure messages for OpenRouter based on context (returns OpenRouter format)
         const openRouterMessages = this.structureMessagesFromContext(context);
@@ -729,6 +730,8 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         options: Record<string, any>,
         onChunk: (chunk: McpStreamChunk) => void
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure and transform messages same as non-streaming path
         const openRouterMessages = this.structureMessagesFromContext(context);
         const converter = getMessageConverter('client');

package/src/protocols/mcp/providers/XaiMcpClient.ts

@@ -426,6 +426,8 @@ export class XaiMcpClient extends BaseMcpClient {
         context: AgentContext,
         options?: Record<string, any>
     ): Promise<McpApiResponse> {
+        this.assertExternalLlmCallAllowed();
+
         // Structure messages for X.ai based on context
         const xaiMessages = this.structureMessagesFromContext(context);
 

package/src/protocols/mcp/security/BrowserTargetGuard.ts

@@ -0,0 +1,64 @@
+/**
+ * Fail-closed network policy for Puppeteer pages used by MXF web tools.
+ *
+ * Checking only the top-level URL is insufficient: redirects, scripts, images,
+ * frames, and fetch/XHR requests can each target a different host. Every browser
+ * request is therefore checked immediately before Puppeteer continues it.
+ */
+
+import type { HTTPRequest, Page } from 'puppeteer';
+
+import { checkHttpTarget } from './HttpTargetGuard.js';
+
+const BROWSER_LOCAL_PROTOCOLS = new Set(['about:', 'blob:', 'data:']);
+
+const isBrowserLocalUrl = (rawUrl: string): boolean => {
+    try {
+        return BROWSER_LOCAL_PROTOCOLS.has(new URL(rawUrl).protocol);
+    } catch {
+        return rawUrl === 'about:blank';
+    }
+};
+
+/** Reject a top-level browser target before allocating a browser or page. */
+export const requireAllowedBrowserTarget = async (rawUrl: string): Promise<void> => {
+    const decision = await checkHttpTarget(rawUrl);
+    if (!decision.allowed) {
+        throw new Error(decision.reason ?? `Browser target '${rawUrl}' is not allowed`);
+    }
+};
+
+export const guardBrowserRequest = async (request: HTTPRequest): Promise<void> => {
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+
+    const rawUrl = request.url();
+    if (isBrowserLocalUrl(rawUrl)) {
+        await request.continue();
+        return;
+    }
+
+    const decision = await checkHttpTarget(rawUrl);
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+    if (!decision.allowed) {
+        await request.abort('blockedbyclient');
+        return;
+    }
+
+    await request.continue();
+};
+
+/** Install the target policy before the first navigation on a Puppeteer page. */
+export const installBrowserTargetGuard = async (page: Page): Promise<void> => {
+    await page.setRequestInterception(true);
+    page.on('request', (request: HTTPRequest) => {
+        void guardBrowserRequest(request).catch(async () => {
+            if (!request.isInterceptResolutionHandled()) {
+                await request.abort('blockedbyclient');
+            }
+        }).catch(() => undefined);
+    });
+};

package/src/protocols/mcp/security/ExternalMcpRegistrationPolicy.ts

@@ -0,0 +1,38 @@
+/**
+ * Policy for caller-supplied stdio MCP server registrations.
+ *
+ * A stdio registration is equivalent to asking the host to execute a command.
+ * It is therefore off by default and may only be exposed by a server entry
+ * point after that entry point has independently established an administrator
+ * principal. Built-in, server-owned configurations do not pass through this
+ * policy because their commands come from source-controlled configuration.
+ */
+
+export const UNSAFE_STDIO_MCP_ENV = 'MXF_UNSAFE_STDIO_MCP_ENABLED';
+
+/**
+ * True only for the exact, explicit opt-in value.
+ */
+export const isUnsafeStdioMcpEnabled = (): boolean => {
+    return process.env[UNSAFE_STDIO_MCP_ENV] === 'true';
+};
+
+/**
+ * External server payloads historically omitted transport and were treated as
+ * stdio, so an absent transport must remain on the dangerous side of the gate.
+ */
+export const isStdioMcpTransport = (transport: unknown): boolean => {
+    return transport === undefined || transport === null || transport === '' || transport === 'stdio';
+};
+
+/**
+ * Fail closed when a caller-controlled registration would execute a process.
+ */
+export const assertUnsafeStdioMcpEnabled = (transport: unknown): void => {
+    if (isStdioMcpTransport(transport) && !isUnsafeStdioMcpEnabled()) {
+        throw new Error(
+            `Caller-supplied stdio MCP registration is disabled. ` +
+            `An administrator must explicitly set ${UNSAFE_STDIO_MCP_ENV}=true to expose this unsafe capability.`
+        );
+    }
+};

package/src/protocols/mcp/security/HttpTargetGuard.ts

@@ -117,6 +117,75 @@ function ipv4InCidr(address: string, cidr: string): boolean {
     return (addressInt & mask) === (networkInt & mask);
 }
 
+/**
+ * Decode an IPv6 literal into its eight 16-bit words.
+ *
+ * Node's `isIP()` tells us that a value is IPv6, but it does not expose the
+ * embedded IPv4 address from mapped forms. Browsers and operating systems
+ * accept both dotted (`::ffff:127.0.0.1`) and hexadecimal
+ * (`::ffff:7f00:1`) spellings, so matching only the dotted text leaves a
+ * loopback/metadata bypass.
+ */
+function parseIpv6Words(address: string): number[] | null {
+    let normalized = address.toLowerCase();
+    const embeddedIpv4 = normalized.match(/^(.*:)(\d{1,3}(?:\.\d{1,3}){3})$/);
+    if (embeddedIpv4) {
+        const ipv4 = ipv4ToInt(embeddedIpv4[2]);
+        if (ipv4 === null) {
+            return null;
+        }
+        normalized = `${embeddedIpv4[1]}${(ipv4 >>> 16).toString(16)}:${(ipv4 & 0xffff).toString(16)}`;
+    }
+
+    const compressedParts = normalized.split('::');
+    if (compressedParts.length > 2) {
+        return null;
+    }
+
+    const parseSide = (side: string): number[] | null => {
+        if (side.length === 0) {
+            return [];
+        }
+        const words = side.split(':');
+        if (words.some(word => !/^[0-9a-f]{1,4}$/.test(word))) {
+            return null;
+        }
+        return words.map(word => Number.parseInt(word, 16));
+    };
+
+    const left = parseSide(compressedParts[0]);
+    const right = parseSide(compressedParts[1] ?? '');
+    if (!left || !right) {
+        return null;
+    }
+
+    if (compressedParts.length === 1) {
+        return left.length === 8 ? left : null;
+    }
+
+    const omittedWordCount = 8 - left.length - right.length;
+    if (omittedWordCount < 1) {
+        return null;
+    }
+    return [...left, ...Array<number>(omittedWordCount).fill(0), ...right];
+}
+
+/** Return the dotted IPv4 address carried by an IPv4-mapped IPv6 literal. */
+function mappedIpv4Address(address: string): string | null {
+    const words = parseIpv6Words(address);
+    if (!words || words.length !== 8 ||
+        words.slice(0, 5).some(word => word !== 0) || words[5] !== 0xffff) {
+        return null;
+    }
+
+    return [
+        words[6] >>> 8,
+        words[6] & 0xff,
+        words[7] >>> 8,
+        words[7] & 0xff
+    ].join('.');
+}
+
 /**
  * Is this address one the server must not be steered into?
  *
@@ -137,6 +206,14 @@ function matchBlockedRange(address: string): string | null {
     if (version === 6) {
         const normalized = address.toLowerCase();
 
+        // IPv4-mapped addresses have multiple equivalent textual forms. Decode
+        // the address instead of applying a dotted-quad-only regex, then run the
+        // embedded address through the complete IPv4 policy.
+        const mappedIpv4 = mappedIpv4Address(normalized);
+        if (mappedIpv4) {
+            return matchBlockedRange(mappedIpv4);
+        }
+
         // IPv6 loopback
         if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
             return 'IPv6 loopback';
@@ -153,12 +230,6 @@ function matchBlockedRange(address: string): string | null {
         if (/^fe[89ab][0-9a-f]:/.test(normalized)) {
             return 'IPv6 link-local address';
         }
-        // IPv4-mapped (::ffff:127.0.0.1) — re-check the embedded IPv4 address,
-        // otherwise ::ffff:169.254.169.254 would walk straight past this guard.
-        const mapped = normalized.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-        if (mapped) {
-            return matchBlockedRange(mapped[1]);
-        }
         return null;
     }
 

package/src/protocols/mcp/security/McpSecurityGuard.ts

@@ -235,17 +235,19 @@ export class McpSecurityGuard {
         const parsed = parseCommand(command);
         const effectiveCommands = extractEffectiveCommands(command);
 
-        // Subshell constructs ($() or backticks) cannot be safely parsed — the parser
-        // detects their presence but doesn't extract commands inside them. Require
-        // confirmation so agents can't bypass validation with `echo $(rm -rf /)`.
+        // Subshell constructs ($() or backticks) are run by the shell but never
+        // reach this parser, so the commands inside them are checked against
+        // neither the block rules nor the configured allowlist. `git status
+        // $(bash -c ...)` would pass on the strength of `git`. They are denied
+        // outright; an agent that needs a value from one command can run it as
+        // its own command first.
         if (parsed.hasSubshells) {
             const destructiveWarnings = getDestructiveWarnings(command);
             const warningMessages = destructiveWarnings.length > 0
                 ? destructiveWarnings.map(w => w.warning)
                 : undefined;
             return {
-                allowed: true,
-                requiresConfirmation: true,
+                allowed: false,
                 reason: 'Command contains subshell constructs ($() or backticks) that cannot be statically validated',
                 riskLevel: 'high',
                 warnings: warningMessages

package/src/protocols/mcp/security/McpToolPolicy.ts

@@ -47,6 +47,8 @@
  */
 
 import * as path from 'path';
+import { extractEffectiveCommands } from '../tools/shell/ShellCommandParser.js';
+import * as fs from 'fs';
 
 /**
  * Environment variables always forwarded to a shell child.
@@ -110,6 +112,33 @@ export function getShellAllowedCommands(): string[] {
     return parseList(process.env.MXF_SHELL_ALLOWED_COMMANDS);
 }
 
+/**
+ * Enforce MXF_SHELL_ALLOWED_COMMANDS against a full command line.
+ *
+ * Applies to every agent-driven command, whether it arrives through
+ * shell_execute or through a host tool that calls executeShellCommand.
+ * Wrappers and env prefixes (`sudo cmd`, `FOO=bar cmd`, `timeout 5 cmd`) are
+ * resolved to the command they run, and compound lines (`a && b`) are checked
+ * command by command, so an allowlisted wrapper cannot smuggle another binary.
+ *
+ * @throws Error when an allowlist is configured and any effective command is not on it
+ */
+export function assertCommandAllowlisted(commandLine: string): void {
+    if (!hasShellAllowlist()) {
+        return;
+    }
+    const allowedCommands = getShellAllowedCommands();
+    for (const effectiveCommand of extractEffectiveCommands(commandLine)) {
+        const baseCommand = effectiveCommand.trim().split(/\s+/)[0];
+        if (!allowedCommands.includes(baseCommand)) {
+            throw new Error(
+                `Command '${baseCommand}' is not in the configured allowlist ` +
+                `(MXF_SHELL_ALLOWED_COMMANDS). Allowed: ${allowedCommands.join(', ')}`
+            );
+        }
+    }
+}
+
 /**
  * Is a command allowlist configured at all?
  */
@@ -207,6 +236,51 @@ export function requireWorkspaceRoot(consumer: string): string {
     return root;
 }
 
+const isWithinPath = (root: string, candidate: string): boolean => (
+    candidate === root || candidate.startsWith(`${root}${path.sep}`)
+);
+
+/**
+ * Resolve a caller path under MXF_WORKSPACE_ROOT and reject lexical and symlink
+ * escapes. Non-existent leaf paths are checked through their nearest existing
+ * ancestor so create/write operations cannot traverse an existing symlink.
+ */
+export function resolveWorkspacePath(
+    candidate: string | undefined,
+    consumer: string
+): string {
+    const configuredRoot = requireWorkspaceRoot(consumer);
+    const realRoot = fs.realpathSync(configuredRoot);
+    const resolved = candidate && candidate.trim().length > 0
+        ? path.resolve(realRoot, candidate.trim())
+        : realRoot;
+
+    if (!isWithinPath(realRoot, resolved)) {
+        throw new Error(`${consumer} path is outside MXF_WORKSPACE_ROOT`);
+    }
+
+    let existingAncestor = resolved;
+    while (!fs.existsSync(existingAncestor)) {
+        const parent = path.dirname(existingAncestor);
+        if (parent === existingAncestor) {
+            throw new Error(`${consumer} path has no existing workspace ancestor`);
+        }
+        existingAncestor = parent;
+    }
+
+    const realAncestor = fs.realpathSync(existingAncestor);
+    if (!isWithinPath(realRoot, realAncestor)) {
+        throw new Error(`${consumer} path escapes MXF_WORKSPACE_ROOT through a symlink`);
+    }
+
+    const suffix = path.relative(existingAncestor, resolved);
+    const finalPath = path.resolve(realAncestor, suffix);
+    if (!isWithinPath(realRoot, finalPath)) {
+        throw new Error(`${consumer} path is outside MXF_WORKSPACE_ROOT`);
+    }
+    return finalPath;
+}
+
 /**
  * May api_fetch reach loopback and private-network addresses?
  *