@mxf-dev/core 1.0.0 → 2.0.0

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

@@ -0,0 +1,267 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * 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.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * HttpTargetGuard.ts
+ *
+ * Decides whether an agent-supplied URL may be fetched from the server.
+ *
+ * The server sits inside the trust boundary: it can reach the MXF API on
+ * localhost:3001, Meilisearch, MongoDB, and — on a cloud host — the instance
+ * metadata endpoint at 169.254.169.254 that hands out IAM credentials. A tool
+ * that fetches an arbitrary URL on the model's behalf turns the server into a
+ * proxy across that boundary (server-side request forgery).
+ *
+ * This guard resolves the hostname and checks every address it resolves to, so a
+ * public name that points at 127.0.0.1 is caught as well as a literal IP.
+ *
+ * The guard fails closed: a target that cannot be resolved or cannot be parsed
+ * is refused, with an error saying why. It never silently skips the check.
+ */
+
+import { promises as dns } from 'dns';
+import { isIP } from 'net';
+
+import { allowPrivateHttpHosts } from './McpToolPolicy.js';
+
+/**
+ * Result of checking a URL.
+ */
+export interface HttpTargetCheck {
+    /** Whether the fetch may proceed */
+    allowed: boolean;
+    /** Why it was refused — written for the model, so it can correct course */
+    reason?: string;
+    /** The addresses the hostname resolved to */
+    resolvedAddresses?: string[];
+}
+
+/**
+ * IPv4 ranges the server must not be steered into.
+ * Each entry is [first octet-based CIDR, human name].
+ */
+const BLOCKED_IPV4_RANGES: Array<{ cidr: string; name: string }> = [
+    { cidr: '0.0.0.0/8', name: '"this network"' },
+    { cidr: '10.0.0.0/8', name: 'RFC1918 private network' },
+    { cidr: '100.64.0.0/10', name: 'carrier-grade NAT' },
+    { cidr: '127.0.0.0/8', name: 'loopback' },
+    { cidr: '169.254.0.0/16', name: 'link-local / cloud instance metadata' },
+    { cidr: '172.16.0.0/12', name: 'RFC1918 private network' },
+    { cidr: '192.0.0.0/24', name: 'IETF protocol assignments' },
+    { cidr: '192.168.0.0/16', name: 'RFC1918 private network' },
+    { cidr: '198.18.0.0/15', name: 'benchmark network' },
+    { cidr: '224.0.0.0/4', name: 'multicast' },
+    { cidr: '240.0.0.0/4', name: 'reserved' }
+];
+
+/** Convert a dotted-quad IPv4 string to a 32-bit unsigned integer. */
+function ipv4ToInt(address: string): number | null {
+    const octets = address.split('.');
+    if (octets.length !== 4) {
+        return null;
+    }
+
+    let value = 0;
+    for (const octet of octets) {
+        // Reject empty, non-numeric, or out-of-range octets rather than coercing.
+        if (!/^\d{1,3}$/.test(octet)) {
+            return null;
+        }
+        const num = Number(octet);
+        if (num > 255) {
+            return null;
+        }
+        value = (value << 8) | num;
+    }
+
+    // `>>> 0` forces the result back to unsigned — the shifts above produce a
+    // signed 32-bit int for addresses above 127.255.255.255.
+    return value >>> 0;
+}
+
+/** Is an IPv4 address inside the given CIDR block? */
+function ipv4InCidr(address: string, cidr: string): boolean {
+    const [network, prefixText] = cidr.split('/');
+    const prefix = Number(prefixText);
+
+    const addressInt = ipv4ToInt(address);
+    const networkInt = ipv4ToInt(network);
+
+    if (addressInt === null || networkInt === null) {
+        return false;
+    }
+
+    // A /0 mask would shift by 32, which is a no-op in JS — handle it explicitly.
+    if (prefix === 0) {
+        return true;
+    }
+
+    const mask = (0xffffffff << (32 - prefix)) >>> 0;
+    return (addressInt & mask) === (networkInt & mask);
+}
+
+/**
+ * Is this address one the server must not be steered into?
+ *
+ * @returns the name of the matched range, or null when the address is fine
+ */
+function matchBlockedRange(address: string): string | null {
+    const version = isIP(address);
+
+    if (version === 4) {
+        for (const range of BLOCKED_IPV4_RANGES) {
+            if (ipv4InCidr(address, range.cidr)) {
+                return range.name;
+            }
+        }
+        return null;
+    }
+
+    if (version === 6) {
+        const normalized = address.toLowerCase();
+
+        // IPv6 loopback
+        if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
+            return 'IPv6 loopback';
+        }
+        // Unspecified address
+        if (normalized === '::' || normalized === '0:0:0:0:0:0:0:0') {
+            return 'IPv6 unspecified address';
+        }
+        // Unique local addresses, fc00::/7
+        if (/^f[cd][0-9a-f]{2}:/.test(normalized)) {
+            return 'IPv6 unique local address';
+        }
+        // Link-local, fe80::/10
+        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;
+    }
+
+    return null;
+}
+
+/**
+ * Check whether an agent-supplied URL may be fetched.
+ *
+ * @param rawUrl - The URL the tool was asked to fetch
+ * @returns Whether the fetch may proceed, and why not when it may not
+ */
+export async function checkHttpTarget(rawUrl: string): Promise<HttpTargetCheck> {
+    let url: URL;
+    try {
+        url = new URL(rawUrl);
+    } catch {
+        return {
+            allowed: false,
+            reason: `"${rawUrl}" is not a valid URL.`
+        };
+    }
+
+    // Only HTTP(S). file:, gopher:, ftp: and friends reach places an HTTP client
+    // has no business reaching.
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return {
+            allowed: false,
+            reason: `Protocol "${url.protocol}" is not allowed. Use http: or https:.`
+        };
+    }
+
+    // The operator can open this up for local development. Off by default.
+    if (allowPrivateHttpHosts()) {
+        return { allowed: true };
+    }
+
+    const hostname = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+
+    // A literal IP needs no DNS round trip.
+    if (isIP(hostname) !== 0) {
+        const blocked = matchBlockedRange(hostname);
+        if (blocked) {
+            return {
+                allowed: false,
+                reason:
+                    `Refusing to fetch ${hostname}: it is a ${blocked} address. ` +
+                    `This tool may only reach public internet hosts. ` +
+                    `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`,
+                resolvedAddresses: [hostname]
+            };
+        }
+        return { allowed: true, resolvedAddresses: [hostname] };
+    }
+
+    // "localhost" and anything under .localhost resolve to loopback by definition.
+    const lowerHost = hostname.toLowerCase();
+    if (lowerHost === 'localhost' || lowerHost.endsWith('.localhost')) {
+        return {
+            allowed: false,
+            reason:
+                `Refusing to fetch ${hostname}: it is a loopback address. ` +
+                `This tool may only reach public internet hosts. ` +
+                `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`
+        };
+    }
+
+    // Resolve the name and check every address behind it. A public hostname can
+    // legitimately resolve to 127.0.0.1, and a malicious one will.
+    let addresses: string[];
+    try {
+        const records = await dns.lookup(hostname, { all: true, verbatim: true });
+        addresses = records.map(record => record.address);
+    } catch (error) {
+        // Fail closed. An unresolvable host is not a host we quietly try anyway.
+        return {
+            allowed: false,
+            reason:
+                `Could not resolve "${hostname}": ` +
+                `${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+
+    if (addresses.length === 0) {
+        return {
+            allowed: false,
+            reason: `"${hostname}" did not resolve to any address.`
+        };
+    }
+
+    for (const address of addresses) {
+        const blocked = matchBlockedRange(address);
+        if (blocked) {
+            return {
+                allowed: false,
+                reason:
+                    `Refusing to fetch ${hostname}: it resolves to ${address}, ` +
+                    `a ${blocked} address. This tool may only reach public internet hosts. ` +
+                    `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`,
+                resolvedAddresses: addresses
+            };
+        }
+    }
+
+    return { allowed: true, resolvedAddresses: addresses };
+}

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -203,11 +203,18 @@ export class McpSecurityGuard {
     private projectRoot: string;
     private allowedPaths: string[] = [];
     
-    constructor(projectRoot: string, additionalAllowedPaths?: string[]) {
-        this.platform = platform();
+    /**
+     * @param projectRoot - Root the guard confines filesystem access to
+     * @param additionalAllowedPaths - Extra paths outside the project root to permit
+     * @param platformOverride - Force the OS rule set. Command rules are OS-specific
+     *   (`apt-get` is blocked outright on Linux but unknown on macOS, for example), so
+     *   without this a test asserting one platform's rules passes on a developer's machine
+     *   and fails on a runner with a different OS. Production code should omit it.
+     */
+    constructor(projectRoot: string, additionalAllowedPaths?: string[], platformOverride?: NodeJS.Platform) {
+        this.platform = platformOverride ?? platform();
         this.projectRoot = path.resolve(projectRoot);
         this.allowedPaths = [this.projectRoot, ...(additionalAllowedPaths || [])];
-        
     }
     
     /**

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

@@ -0,0 +1,221 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * 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.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * McpToolPolicy.ts
+ *
+ * Operator-controlled policy for the tools that reach outside the process:
+ * shell execution, the child environment those shells inherit, the workspace
+ * agents may touch, and the hosts `api_fetch` may reach.
+ *
+ * Every value here comes from configuration (environment variables), never from
+ * tool arguments. That distinction is the whole point of the module: an
+ * allowlist supplied as a tool input is supplied by the very model it is meant
+ * to restrict, so it restricts nothing.
+ *
+ * Environment variables:
+ *   MXF_SHELL_ALLOWED_COMMANDS   Comma-separated base commands agents may run.
+ *                                Empty/unset means "no command allowlist" — the
+ *                                McpSecurityGuard's own rules still apply.
+ *   MXF_SHELL_ENV_PASSTHROUGH    Comma-separated extra environment variable names
+ *                                to forward to shell children, on top of the
+ *                                always-safe base (PATH, HOME, and friends).
+ *   MXF_SHELL_SANDBOX_ENABLED    'true' to run shell_execute inside the Docker
+ *                                sandbox (see ShellSandbox.ts). Default false.
+ *   MXF_WORKSPACE_ROOT           Directory agents are allowed to work in. Required
+ *                                by anything that grants filesystem reach; there is
+ *                                no default, because the old default was $HOME.
+ *   MXF_HTTP_ALLOW_PRIVATE_HOSTS 'true' to let api_fetch reach loopback/private
+ *                                addresses. Default false. Only for local dev.
+ */
+
+import * as path from 'path';
+
+/**
+ * Environment variables always forwarded to a shell child.
+ *
+ * These are what a process needs to run at all — a PATH to find binaries, a HOME
+ * for tool caches, a TMPDIR to write scratch files, and locale/terminal settings
+ * so output is not garbled. Nothing here carries a credential.
+ *
+ * Everything else in the server's environment — JWT_SECRET, MONGODB_URI,
+ * OPENROUTER_API_KEY, MEILISEARCH_MASTER_KEY, MXP_ENCRYPTION_KEY — stays behind.
+ */
+const BASE_SHELL_ENV_VARS = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'LANG',
+    'LC_ALL',
+    'TERM',
+    'TMPDIR',
+    'TZ',
+    'NODE_ENV',
+    // Windows equivalents — a child on win32 cannot resolve paths without these.
+    'SYSTEMROOT',
+    'COMSPEC',
+    'PATHEXT',
+    'USERPROFILE',
+    'TEMP',
+    'TMP'
+];
+
+/** Parse a comma-separated env var into a trimmed, non-empty list. */
+function parseList(value: string | undefined): string[] {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(entry => entry.length > 0);
+}
+
+/** Parse a boolean env var. Anything other than 'true' is false. */
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+    if (value === undefined || value === '') {
+        return fallback;
+    }
+    return value.toLowerCase() === 'true';
+}
+
+/**
+ * Base commands agents are permitted to run via shell_execute.
+ *
+ * Read from MXF_SHELL_ALLOWED_COMMANDS. An empty list means no allowlist is
+ * configured: the McpSecurityGuard's block rules and confirmation prompts remain
+ * the control, exactly as before. This is a config-supplied allowlist, so a model
+ * cannot widen it by passing arguments.
+ */
+export function getShellAllowedCommands(): string[] {
+    return parseList(process.env.MXF_SHELL_ALLOWED_COMMANDS);
+}
+
+/**
+ * Is a command allowlist configured at all?
+ */
+export function hasShellAllowlist(): boolean {
+    return getShellAllowedCommands().length > 0;
+}
+
+/**
+ * Build the environment a shell child process receives.
+ *
+ * Least privilege: start from the small base set above, add any names the
+ * operator explicitly opted into via MXF_SHELL_ENV_PASSTHROUGH, then add the
+ * caller's own explicit variables. The server's secrets are never copied in.
+ *
+ * This mirrors what ExternalMcpServerManager already does when it spawns an
+ * external MCP server.
+ *
+ * @param explicitEnv - Variables the caller wants the child to see
+ * @returns The complete environment for the child process
+ */
+export function buildShellChildEnv(
+    explicitEnv?: Record<string, string>
+): Record<string, string> {
+    const childEnv: Record<string, string> = {};
+
+    const passthroughNames = [
+        ...BASE_SHELL_ENV_VARS,
+        ...parseList(process.env.MXF_SHELL_ENV_PASSTHROUGH)
+    ];
+
+    for (const name of passthroughNames) {
+        const value = process.env[name];
+        if (value !== undefined && value !== '') {
+            childEnv[name] = value;
+        }
+    }
+
+    // Caller-supplied variables are layered last so a tool can set, for example,
+    // CI=true or NODE_OPTIONS for the command it is about to run.
+    if (explicitEnv) {
+        for (const [name, value] of Object.entries(explicitEnv)) {
+            if (value !== undefined && value !== null) {
+                childEnv[name] = String(value);
+            }
+        }
+    }
+
+    return childEnv;
+}
+
+/**
+ * Should shell_execute run commands inside the Docker sandbox?
+ *
+ * Off by default: the sandbox requires Docker and the mxf/shell-executor image,
+ * and turning it on changes where commands run. When it is on and Docker is
+ * missing, execution fails — it never silently falls back to the host.
+ */
+export function isShellSandboxEnabled(): boolean {
+    return parseBoolean(process.env.MXF_SHELL_SANDBOX_ENABLED, false);
+}
+
+/**
+ * The directory tree agents are allowed to work in.
+ *
+ * Returns undefined when MXF_WORKSPACE_ROOT is not set. Callers that hand out
+ * filesystem reach must treat that as fatal — see {@link requireWorkspaceRoot}.
+ * There is deliberately no default: the previous default was the user's home
+ * directory, which put ~/.ssh, ~/.aws and ~/.mxf/config.json inside the agents'
+ * reach.
+ */
+export function getWorkspaceRoot(): string | undefined {
+    const configured = process.env.MXF_WORKSPACE_ROOT;
+    if (!configured || configured.trim().length === 0) {
+        return undefined;
+    }
+    return path.resolve(configured.trim());
+}
+
+/**
+ * The workspace root, or a thrown error explaining how to set it.
+ *
+ * @throws Error when MXF_WORKSPACE_ROOT is not configured
+ */
+export function requireWorkspaceRoot(consumer: string): string {
+    const root = getWorkspaceRoot();
+    if (!root) {
+        throw new Error(
+            `${consumer} needs a workspace directory but MXF_WORKSPACE_ROOT is not set. ` +
+            `Set it to the directory agents are allowed to work in ` +
+            `(for example: MXF_WORKSPACE_ROOT=/Users/you/projects/my-app). ` +
+            `It has no default — the previous default was your home directory, which ` +
+            `exposed ~/.ssh, ~/.aws and ~/.mxf/config.json to agents.`
+        );
+    }
+    return root;
+}
+
+/**
+ * May api_fetch reach loopback and private-network addresses?
+ *
+ * Default false. When false, api_fetch refuses localhost, RFC1918 ranges, and
+ * the cloud metadata endpoint — otherwise an agent could use the server as a
+ * proxy into the MXF API itself, Meilisearch, or a cloud instance's credentials.
+ *
+ * Turn on only for local development against services on your own machine.
+ */
+export function allowPrivateHttpHosts(): boolean {
+    return parseBoolean(process.env.MXF_HTTP_ALLOW_PRIVATE_HOSTS, false);
+}

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */