@juspay/neurolink 13.8.16 → 13.8.18

package/dist/cli/commands/serve.js

@@ -16,7 +16,7 @@ import { NeuroLink } from "../../neurolink.js";
 import { ConfigurationError, ServerStartError, } from "../../server/errors.js";
 import { withTimeout } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
-import { clearStateOnExit, createServerApiKeyMiddleware, formatUptime, isOtherServerRunning, isProcessRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, StateFileManager, } from "../utils/serverUtils.js";
+import { clearStateOnExit, createServerApiKeyMiddleware, DEFAULT_SERVER_HOST, envFlag, formatUptime, isLoopbackHost, isOtherServerRunning, isProcessRunning, readServerApiKeys, resolveServerPort, SERVER_ALLOW_UNAUTHENTICATED_ENV, SERVER_API_KEY_ENV, SERVER_ENABLE_BUILTIN_TOOLS_ENV, SERVER_WS_ALLOW_QUERY_TOKEN_ENV, StateFileManager, unauthenticatedBindRefusal, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -159,7 +159,7 @@ function corsOriginsFromArgv(values) {
         .filter((origin) => origin.length > 0);
     return origins.length > 0 ? origins : undefined;
 }
-async function attachTranscriptionWebSocket(server, neurolink, serverConfig) {
+async function attachTranscriptionWebSocket(server, neurolink, serverConfig, hardening) {
     const native = server.getNativeServer?.();
     if (!isNodeHttpServer(native)) {
         return;
@@ -175,9 +175,28 @@ async function attachTranscriptionWebSocket(server, neurolink, serverConfig) {
     await attachTranscribeWebSocket(native, neurolink, {
         ...(apiKeys.length > 0 ? { authToken: apiKeys } : {}),
         ...(allowedOrigins ? { allowedOrigins } : {}),
+        // The key rides in the Authorization header or the subprotocol; a URL is
+        // logged, so `?token=` is an explicit choice.
+        allowQueryToken: envFlag(SERVER_WS_ALLOW_QUERY_TOKEN_ENV),
+        // The same opt-out as the HTTP routes: whoever runs open on purpose also
+        // gets file mode without a key.
+        allowUnauthenticatedFileMode: hardening.allowUnauthenticated === true,
     });
     logger.debug("[serve] transcription WebSocket attached at /v1/audio/transcriptions/stream");
 }
+/**
+ * The hardening flags, from the command line or the environment:
+ * `--allow-unauthenticated` / NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1 and
+ * `--enable-builtin-tools` / NEUROLINK_SERVER_ENABLE_BUILTIN_TOOLS=1.
+ */
+function resolveHardening(argv) {
+    return {
+        allowUnauthenticated: argv.allowUnauthenticated === true ||
+            envFlag(SERVER_ALLOW_UNAUTHENTICATED_ENV),
+        enableBuiltinTools: argv.enableBuiltinTools === true ||
+            envFlag(SERVER_ENABLE_BUILTIN_TOOLS_ENV),
+    };
+}
 export class ServeCommandFactory {
     /**
      * Create the main serve command
@@ -208,7 +227,19 @@ export class ServeCommandFactory {
                     .option("host", {
                     type: "string",
                     alias: "H",
-                    description: "Host to bind to (default: 0.0.0.0)",
+                    description: `Host to bind to (default: ${DEFAULT_SERVER_HOST}, this machine only; 0.0.0.0 listens on every interface and needs ${SERVER_API_KEY_ENV} or --allow-unauthenticated)`,
+                })
+                    .option("allow-unauthenticated", {
+                    type: "boolean",
+                    alias: "allowUnauthenticated",
+                    default: false,
+                    description: `Listen on a non-loopback host with no ${SERVER_API_KEY_ENV}, and serve tool and MCP execution to anyone who can reach the port (${SERVER_ALLOW_UNAUTHENTICATED_ENV}=1)`,
+                })
+                    .option("enable-builtin-tools", {
+                    type: "boolean",
+                    alias: "enableBuiltinTools",
+                    default: false,
+                    description: `Keep NeuroLink's built-in tools, file reads and writes under the working directory among them, in the server's registry (${SERVER_ENABLE_BUILTIN_TOOLS_ENV}=1)`,
                 })
                     .option("framework", {
                     type: "string",
@@ -275,7 +306,7 @@ export class ServeCommandFactory {
                     .example("neurolink serve --cors --rate-limit 50", "Start server with CORS and rate limiting (50 req/15min)")
                     .example("neurolink serve --swagger", "Start server with OpenAPI documentation enabled")
                     .example("neurolink serve --watch", "Start server in watch mode (restart on changes)")
-                    .example("NEUROLINK_SERVER_API_KEY=secret neurolink serve", "Require 'Authorization: Bearer secret' (or X-API-Key) on every route except health")
+                    .example("NEUROLINK_SERVER_API_KEY=secret neurolink serve --host 0.0.0.0", "Listen on every interface; require 'Authorization: Bearer secret' (or X-API-Key) on every route except the health probes")
                     .example("neurolink serve status", "Show server status")
                     .help();
             },
@@ -319,9 +350,24 @@ export class ServeCommandFactory {
             const fileConfig = ServeCommandFactory.loadFileConfig(argv, spinner);
             // Merge CLI args with file config (CLI takes precedence)
             const port = resolveServerPort(argv.port, fileConfig.port);
-            const host = argv.host ?? fileConfig.host ?? "0.0.0.0";
+            const host = argv.host ?? fileConfig.host ?? DEFAULT_SERVER_HOST;
             const framework = argv.framework ?? fileConfig.framework ?? "hono";
             const basePath = argv.basePath ?? fileConfig.basePath ?? "/api";
+            const hardening = resolveHardening(argv);
+            // A listener the network can reach with no key is refused unless the
+            // operator asked for exactly that.
+            const refusal = unauthenticatedBindRefusal({
+                host,
+                apiKeyCount: readServerApiKeys().length,
+                allowUnauthenticated: hardening.allowUnauthenticated === true,
+            });
+            if (refusal) {
+                if (spinner) {
+                    spinner.fail(chalk.red("Refusing to start"));
+                }
+                logger.error(chalk.red(refusal));
+                process.exit(1);
+            }
             // Build server adapter config from merged values
             const serverConfig = ServeCommandFactory.buildServerConfig(argv, fileConfig, {
                 port,
@@ -332,9 +378,9 @@ export class ServeCommandFactory {
                 spinner.text = `Creating ${framework} server...`;
             }
             // Create, register routes, initialize and start server
-            const serverRef = await ServeCommandFactory.createAndStartServer({ framework, serverConfig, basePath, port, host }, spinner);
+            const serverRef = await ServeCommandFactory.createAndStartServer({ framework, serverConfig, basePath, port, host, hardening }, spinner);
             // Save state and print startup banner
-            ServeCommandFactory.saveAndPrintStartupInfo({ argv, port, host, framework, basePath, serverConfig }, spinner);
+            ServeCommandFactory.saveAndPrintStartupInfo({ argv, port, host, framework, basePath, serverConfig, hardening }, spinner);
             // Set up watch mode if enabled
             const stopWatcher = ServeCommandFactory.setupWatchMode(argv, {
                 serverRef,
@@ -343,6 +389,7 @@ export class ServeCommandFactory {
                 basePath,
                 port,
                 host,
+                hardening,
             });
             // Register signal handlers for graceful shutdown
             ServeCommandFactory.registerSignalHandlers(serverRef, stopWatcher);
@@ -450,7 +497,7 @@ export class ServeCommandFactory {
      */
     static async createAndStartServer(opts, spinner) {
         const { createServer, registerAllRoutes } = await import("../../server/index.js");
-        const neurolink = new NeuroLink();
+        const neurolink = ServeCommandFactory.createServerNeuroLink(opts.hardening);
         const serverRef = {
             current: await createServer(neurolink, {
                 framework: opts.framework,
@@ -458,17 +505,33 @@ export class ServeCommandFactory {
             }),
         };
         ServeCommandFactory.applyApiKeyAuth(serverRef.current, opts.basePath);
-        registerAllRoutes(serverRef.current, opts.basePath);
+        registerAllRoutes(serverRef.current, opts.basePath, {
+            allowUnauthenticated: opts.hardening.allowUnauthenticated,
+        });
         if (spinner) {
             spinner.text = "Initializing server...";
         }
         await withTimeout(serverRef.current.initialize(), 30000, new ServerStartError("Server initialization timed out after 30 seconds", undefined, opts.port, opts.host));
         await withTimeout(serverRef.current.start(), 30000, new ServerStartError("Server startup timed out after 30 seconds", undefined, opts.port, opts.host));
-        await attachTranscriptionWebSocket(serverRef.current, neurolink, opts.serverConfig);
+        await attachTranscriptionWebSocket(serverRef.current, neurolink, opts.serverConfig, opts.hardening);
         return serverRef;
     }
     /**
-     * Put every route except health behind the API key(s) in
+     * The NeuroLink instance the server runs. Its registry holds no built-in
+     * tool unless `--enable-builtin-tools`: those tools read and write files
+     * under the server's working directory, and `/tools/execute` and the agent
+     * routes would hand them to every caller. The switch is the SDK's own
+     * (NEUROLINK_DISABLE_BUILTIN_TOOLS), set before the instance and its
+     * providers read it, so generate() in this process does not see them either.
+     */
+    static createServerNeuroLink(hardening) {
+        if (!hardening.enableBuiltinTools) {
+            process.env.NEUROLINK_DISABLE_BUILTIN_TOOLS = "true";
+        }
+        return new NeuroLink();
+    }
+    /**
+     * Put every route except the health probes behind the API key(s) in
      * NEUROLINK_SERVER_API_KEY. Must run before the routes are registered.
      */
     static applyApiKeyAuth(server, basePath) {
@@ -495,7 +558,7 @@ export class ServeCommandFactory {
         if (spinner) {
             spinner.succeed(chalk.green("NeuroLink server started successfully"));
         }
-        const url = `http://${opts.host === "0.0.0.0" ? "localhost" : opts.host}:${opts.port}`;
+        const url = `http://${opts.host === "0.0.0.0" || opts.host === "::" ? "localhost" : opts.host}:${opts.port}`;
         const corsEnabled = opts.argv.cors ?? opts.serverConfig.cors?.enabled ?? true;
         // The origin list and the API key together decide whether any browser
         // page may call this server; the banner says which case this is.
@@ -507,6 +570,7 @@ export class ServeCommandFactory {
         const swaggerEnabled = opts.argv.swagger ?? opts.serverConfig.enableSwagger ?? false;
         ServeCommandFactory.printStartupBanner({
             url,
+            host: opts.host,
             framework: opts.framework,
             basePath: opts.basePath,
             pid: state.pid,
@@ -519,6 +583,8 @@ export class ServeCommandFactory {
             swaggerEnabled,
             watchEnabled: opts.argv.watch ?? false,
             authEnabled: readServerApiKeys().length > 0,
+            allowUnauthenticated: opts.hardening.allowUnauthenticated === true,
+            builtinToolsEnabled: opts.hardening.enableBuiltinTools === true,
         });
         return state;
     }
@@ -531,6 +597,11 @@ export class ServeCommandFactory {
         logger.always(chalk.gray("=".repeat(50)));
         logger.always("");
         logger.always(`  ${chalk.bold("URL:")}        ${chalk.cyan(info.url)}`);
+        logger.always(`  ${chalk.bold("Listening:")}  ${isLoopbackHost(info.host)
+            ? chalk.green(`${info.host} (this machine only)`)
+            : info.authEnabled
+                ? chalk.green(`${info.host} (network; API key required)`)
+                : chalk.yellow(`${info.host} (network, NO authentication — every route is open to anyone who can reach this port)`)}`);
         logger.always(`  ${chalk.bold("Framework:")}  ${chalk.cyan(info.framework)}`);
         logger.always(`  ${chalk.bold("Base Path:")}  ${chalk.cyan(info.basePath)}`);
         logger.always(`  ${chalk.bold("PID:")}        ${chalk.cyan(info.pid)}`);
@@ -554,7 +625,15 @@ export class ServeCommandFactory {
         if (info.watchEnabled) {
             logger.always(`  Watch Mode:  ${chalk.green("enabled")}`);
         }
-        logger.always(`  API Key:     ${info.authEnabled ? chalk.green("required (health routes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
+        logger.always(`  API Key:     ${info.authEnabled ? chalk.green("required (health probes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
+        if (!info.authEnabled) {
+            logger.always(`  Tool/MCP:    ${info.allowUnauthenticated
+                ? chalk.yellow("execution routes OPEN (--allow-unauthenticated)")
+                : chalk.green("execution routes answer 403 until a key is set")}`);
+        }
+        logger.always(`  Built-in:    ${info.builtinToolsEnabled
+            ? chalk.yellow("tools enabled (file reads/writes under the working directory)")
+            : chalk.green("tools disabled (--enable-builtin-tools to allow)")}`);
         logger.always("");
         logger.always(chalk.bold("Available Endpoints:"));
         logger.always(chalk.gray("  Health & Monitoring:"));
@@ -600,20 +679,22 @@ export class ServeCommandFactory {
                 const timestamp = Date.now();
                 const { createServer: createNewServer, registerAllRoutes: registerNewRoutes, } = await import(`../../server/index.js?t=${timestamp}`);
                 // Create new server
-                const newNeurolink = new NeuroLink();
+                const newNeurolink = ServeCommandFactory.createServerNeuroLink(ctx.hardening);
                 const newServer = await createNewServer(newNeurolink, {
                     framework: ctx.framework,
                     config: ctx.serverConfig,
                 });
                 ServeCommandFactory.applyApiKeyAuth(newServer, ctx.basePath);
-                registerNewRoutes(newServer, ctx.basePath);
+                registerNewRoutes(newServer, ctx.basePath, {
+                    allowUnauthenticated: ctx.hardening.allowUnauthenticated,
+                });
                 // Initialize and start with timeouts
                 await withTimeout(newServer.initialize(), 30000, new ServerStartError("Server initialization timed out during restart", undefined, ctx.port, ctx.host));
                 await withTimeout(newServer.start(), 30000, new ServerStartError("Server startup timed out during restart", undefined, ctx.port, ctx.host));
                 // The upgrade handler lives on the old adapter's http.Server; the
                 // restarted one needs its own, or the stream route is gone after the
                 // first file change.
-                await attachTranscriptionWebSocket(newServer, newNeurolink, ctx.serverConfig);
+                await attachTranscriptionWebSocket(newServer, newNeurolink, ctx.serverConfig, ctx.hardening);
                 // Update the reference so signal handlers use the new server instance
                 ctx.serverRef.current = newServer;
                 logger.always(chalk.green("Server restarted successfully"));
@@ -709,7 +790,7 @@ export class ServeCommandFactory {
                 status.startTime = state.startTime;
                 status.uptime = Date.now() - new Date(state.startTime).getTime();
                 status.configFile = state.configFile ?? null;
-                status.url = `http://${state.host === "0.0.0.0" ? "localhost" : state.host}:${state.port}`;
+                status.url = `http://${state.host === "0.0.0.0" || state.host === "::" ? "localhost" : state.host}:${state.port}`;
             }
             if (argv.format === "json") {
                 logger.always(JSON.stringify(status, null, 2));

package/dist/cli/commands/server.js

@@ -9,7 +9,7 @@ import path from "path";
 import { logger } from "../../utils/logger.js";
 import { NeuroLink } from "../../neurolink.js";
 import { withTimeout } from "../../utils/errorHandling.js";
-import { isProcessRunning, formatUptime, ensureStateDir, getNeuroLinkDir, clearStateOnExit, createServerApiKeyMiddleware, isOtherServerRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, } from "../utils/serverUtils.js";
+import { DEFAULT_SERVER_HOST, SERVER_ALLOW_UNAUTHENTICATED_ENV, SERVER_API_KEY_ENV, clearStateOnExit, createServerApiKeyMiddleware, ensureStateDir, formatUptime, getNeuroLinkDir, isOtherServerRunning, isProcessRunning, readServerApiKeys, resolveServerPort, unauthenticatedBindRefusal, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -47,7 +47,7 @@ const CONFIG_FILE = path.join(getNeuroLinkDir(), "server-config.json");
 function loadServerConfig() {
     const defaults = {
         defaultPort: 3000,
-        defaultHost: "0.0.0.0",
+        defaultHost: DEFAULT_SERVER_HOST,
         defaultFramework: "hono",
         defaultBasePath: "/api",
         cors: { enabled: true },
@@ -165,7 +165,7 @@ export class ServerCommandFactory {
             .option("host", {
             type: "string",
             alias: "H",
-            default: "0.0.0.0",
+            default: DEFAULT_SERVER_HOST,
             description: "Host to bind to",
         })
             .option("framework", {
@@ -356,12 +356,24 @@ export class ServerCommandFactory {
             const { createServer, registerAllRoutes } = await import("../../server/index.js");
             const port = resolveServerPort(argv.port);
             const framework = (argv.framework ?? "hono");
+            // A listener the network can reach with no key is refused unless the
+            // operator asked for exactly that (NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1).
+            const bindHost = argv.host ?? DEFAULT_SERVER_HOST;
+            const refusal = unauthenticatedBindRefusal({
+                host: bindHost,
+                apiKeyCount: readServerApiKeys().length,
+                allowUnauthenticated: process.env[SERVER_ALLOW_UNAUTHENTICATED_ENV] === "1",
+            });
+            if (refusal) {
+                logger.error(chalk.red(refusal));
+                process.exit(1);
+            }
             // Create server
             const server = await createServer(neurolink, {
                 framework,
                 config: {
                     port,
-                    host: argv.host ?? "0.0.0.0",
+                    host: bindHost,
                     basePath: argv.basePath ?? "/api",
                     cors: {
                         enabled: argv.cors ?? true,
@@ -386,7 +398,7 @@ export class ServerCommandFactory {
             const state = {
                 pid: process.pid,
                 port,
-                host: argv.host ?? "0.0.0.0",
+                host: argv.host ?? DEFAULT_SERVER_HOST,
                 framework,
                 startTime: new Date().toISOString(),
                 basePath: argv.basePath ?? "/api",

package/dist/cli/index.js

@@ -7,10 +7,14 @@ process.env.DOTENV_CONFIG_QUIET = "true";
  * Professional CLI experience with minimal maintenance overhead.
  * Features: Spinners, colors, batch processing, provider testing, rich help
  */
+import { existsSync } from "node:fs";
+import * as path from "node:path";
 import { initializeCliParser } from "./parser.js";
 import chalk from "chalk";
 import { initializeCliLifecycle, cleanupCliLifecycle } from "./lifecycle.js";
 import { loadProcessDotenv } from "../utils/dotenvBootstrap.js";
+import { ensureStdinRef } from "./utils/stdinRef.js";
+import { PROJECT_MCP_CONFIG_FILENAME, TRUST_MCP_CONFIG_ENV, TRUST_MCP_CONFIG_FLAG, formatProjectMcpConfigSummary, getProjectMcpConfigTrustStatus, getTrustedMcpConfigStorePath, recordTrustedProjectMcpConfig, setProjectMcpConfigTrustHook, summarizeProjectMcpConfig, } from "../mcp/projectConfigTrust.js";
 // Clean up pnpm-specific environment variables that cause npm warnings
 // These variables are set by pnpm but cause "Unknown env config" warnings in npm
 if (process.env.npm_config_verify_deps_before_run) {
@@ -19,11 +23,148 @@ if (process.env.npm_config_verify_deps_before_run) {
 if (process.env.npm_config__jsr_registry) {
     delete process.env.npm_config__jsr_registry;
 }
-// Load environment variables from .env file. Shared with the SDK entry
-// point; see dotenvBootstrap for why DOTENV_CONFIG_PATH has to be honoured
-// here too — a suite that drives the built CLI inherits the stripped
-// environment, and this is the process that would otherwise undo it.
-await loadProcessDotenv();
+// `--trust-mcp-config` is a global flag consumed here, before yargs sees the
+// argument vector: the parser runs with `strictOptions()`, so an option it
+// does not know about would otherwise be rejected on every command.
+const trustMcpConfigFlag = process.argv.includes(TRUST_MCP_CONFIG_FLAG);
+if (trustMcpConfigFlag) {
+    process.argv = process.argv.filter((argument) => argument !== TRUST_MCP_CONFIG_FLAG);
+}
+// Load environment variables from `.env`. The CLI is the one entry point
+// that still does this implicitly — a terminal session in a project directory
+// is what the file is for. Endpoint-override variables are refused unless the
+// file is owned by this user and not group/world-writable; see
+// dotenvBootstrap.ts. `NEUROLINK_DOTENV=0` disables the load entirely.
+await loadProcessDotenv({ caller: "cli" });
+function warn(message) {
+    process.stderr.write(chalk.yellow(`${message}\n`));
+}
+function isHelpOrVersionInvocation(args) {
+    if (args.length === 0) {
+        return true;
+    }
+    return args.some((argument) => argument === "--help" ||
+        argument === "-h" ||
+        argument === "help" ||
+        argument === "--version" ||
+        argument === "-V" ||
+        argument === "version");
+}
+function describeUntrusted(summary, status) {
+    return [
+        status === "changed"
+            ? `This project's ${PROJECT_MCP_CONFIG_FILENAME} has changed since you last trusted it:`
+            : `This project has a ${PROJECT_MCP_CONFIG_FILENAME} you have not trusted yet:`,
+        ...formatProjectMcpConfigSummary(summary),
+        "Loading it starts the commands and connections above with your environment.",
+    ];
+}
+function howToDecide() {
+    return [
+        "To continue, either:",
+        `  • review the file, then re-run with ${TRUST_MCP_CONFIG_FLAG} (or ${TRUST_MCP_CONFIG_ENV}=1) to trust exactly this content — the hash is remembered in ${getTrustedMcpConfigStorePath()}`,
+        `  • or set ${TRUST_MCP_CONFIG_ENV}=0 to run without it`,
+        "  • or pass --disable-tools so no MCP server is needed",
+    ];
+}
+async function promptForTrust(summary, status) {
+    ensureStdinRef();
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        process.stderr.write(chalk.yellow(`${describeUntrusted(summary, status).join("\n")}\n`));
+        const answer = await rl.question("Trust this file and start these servers? [y/N] ");
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Decide, once per invocation, what to do about the working directory's
+ * `.mcp-config.json`, and hand that decision to the SDK through its trust
+ * hook. The hook only runs when a command actually initialises MCP, so a
+ * command that never needs a tool is unaffected, and the decision that does
+ * refuse happens before any server is started.
+ *
+ * A file already recorded in `~/.neurolink/trusted-mcp-configs.json` with the
+ * same hash loads silently. Otherwise `--trust-mcp-config` /
+ * `NEUROLINK_TRUST_MCP_CONFIG=1` accepts and records it, `=0` ignores it, an
+ * interactive terminal is asked, and a non-interactive run that was told
+ * nothing refuses with exit status 1 at the moment the file would load.
+ */
+async function installProjectMcpConfigGate() {
+    if (isHelpOrVersionInvocation(process.argv.slice(2))) {
+        return;
+    }
+    const candidate = path.join(process.cwd(), PROJECT_MCP_CONFIG_FILENAME);
+    if (!existsSync(candidate)) {
+        return;
+    }
+    const envValue = process.env[TRUST_MCP_CONFIG_ENV];
+    if (envValue === "0" || envValue === "false") {
+        setProjectMcpConfigTrustHook(async () => {
+            warn(`[neurolink] Ignoring ${candidate} (${TRUST_MCP_CONFIG_ENV}=${envValue}).`);
+            return null;
+        });
+        return;
+    }
+    let summary;
+    try {
+        summary = summarizeProjectMcpConfig(candidate);
+    }
+    catch (error) {
+        setProjectMcpConfigTrustHook(async () => {
+            warn(`[neurolink] Not loading ${candidate}: it could not be read (${error instanceof Error ? error.message : String(error)}).`);
+            return null;
+        });
+        return;
+    }
+    // Nothing to run, nothing to trust: let the loader report the parse error
+    // or the empty server list itself.
+    if (summary.parseError !== undefined || summary.servers.length === 0) {
+        setProjectMcpConfigTrustHook(async () => summary.path);
+        return;
+    }
+    const status = getProjectMcpConfigTrustStatus(summary.path, summary.sha256);
+    if (status === "trusted") {
+        setProjectMcpConfigTrustHook(async () => summary.path);
+        return;
+    }
+    const accept = () => {
+        try {
+            recordTrustedProjectMcpConfig(summary.path, summary.sha256);
+        }
+        catch (error) {
+            warn(`[neurolink] Trusted ${summary.path} for this run, but could not record it in ${getTrustedMcpConfigStorePath()} (${error instanceof Error ? error.message : String(error)}).`);
+        }
+        setProjectMcpConfigTrustHook(async () => summary.path);
+    };
+    if (trustMcpConfigFlag || envValue === "1" || envValue === "true") {
+        accept();
+        return;
+    }
+    const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (interactive) {
+        if (await promptForTrust(summary, status)) {
+            accept();
+        }
+        else {
+            warn(`[neurolink] Not loading ${summary.path}. Re-run with ${TRUST_MCP_CONFIG_FLAG} once you have reviewed it.`);
+            setProjectMcpConfigTrustHook(async () => null);
+        }
+        return;
+    }
+    setProjectMcpConfigTrustHook(async () => {
+        process.stderr.write(chalk.red(`neurolink: refusing to load an untrusted project MCP configuration.\n`));
+        process.stderr.write(`${[...describeUntrusted(summary, status), ...howToDecide()].join("\n")}\n`);
+        process.exit(1);
+    });
+}
+await installProjectMcpConfigGate();
 // Enhanced CLI with Professional UX
 const cli = initializeCliParser();
 initializeCliLifecycle(async () => {

package/dist/cli/loop/optionsSchema.d.ts

@@ -4,4 +4,4 @@ import type { OptionSchema, TextGenerationOptions } from "../../types/index.js";
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "audioOptions" | "videoOptions" | "officeOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder" | "toolRoots">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "audioOptions" | "videoOptions" | "officeOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "attachmentPolicy" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder" | "toolRoots">, OptionSchema>;

package/dist/cli/utils/envManager.js

@@ -22,7 +22,13 @@ export function backupEnvFile(envPath = ".env") {
             .split(".")[0]; // Remove milliseconds
         const backupPath = `${envPath}.backup.${timestamp}`;
         try {
-            fs.copyFileSync(envPath, backupPath);
+            // The backup holds the same provider keys as `.env`: owner-only, and
+            // never over an existing file (a second backup in the same second gets
+            // a fresh error rather than a silent overwrite).
+            fs.writeFileSync(backupPath, fs.readFileSync(envPath), {
+                mode: 0o600,
+                flag: "wx",
+            });
             result.backupPath = backupPath;
         }
         catch (error) {
@@ -153,9 +159,17 @@ export function updateEnvFile(newVars, envPath = ".env", createBackup = true, ke
     }
     // Generate new content
     const newContent = generateEnvContent(newVars, existingContent, keysToDelete);
-    // Write updated file
+    // Write updated file, owner-only. `mode` applies only when the file is
+    // created, so an existing `.env` is tightened explicitly as well; a
+    // platform without POSIX modes (Windows) ignores the chmod.
     try {
-        fs.writeFileSync(envPath, newContent, "utf8");
+        fs.writeFileSync(envPath, newContent, { encoding: "utf8", mode: 0o600 });
+        try {
+            fs.chmodSync(envPath, 0o600);
+        }
+        catch {
+            // Not a POSIX file system; the write itself succeeded.
+        }
     }
     catch (error) {
         throw new Error(`Failed to write .env file: ${error instanceof Error ? error.message : String(error)}`, { cause: error });

package/dist/cli/utils/serverUtils.d.ts

@@ -2,10 +2,43 @@
  * Server Utilities for NeuroLink CLI
  * Shared utility functions for server management commands (serve.ts and server.ts)
  */
+import { DEFAULT_SERVER_HOST } from "../../server/abstract/baseServerAdapter.js";
 import type { MiddlewareDefinition } from "../../types/index.js";
 export declare const DEFAULT_SERVER_PORT = 3000;
-/** Comma-separated API keys; when set, every route except health needs one. */
+/** The interface `neurolink serve` binds unless told otherwise: this host only. */
+export { DEFAULT_SERVER_HOST };
+/** Comma-separated API keys; when set, every route except the health probes needs one. */
 export declare const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * `=1` lets `neurolink serve` listen on a non-loopback host with no API key,
+ * and serves the tool and MCP execution routes to anyone who can reach it.
+ */
+export declare const SERVER_ALLOW_UNAUTHENTICATED_ENV = "NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED";
+/** `=1` keeps the built-in tools (filesystem among them) in the server's registry. */
+export declare const SERVER_ENABLE_BUILTIN_TOOLS_ENV = "NEUROLINK_SERVER_ENABLE_BUILTIN_TOOLS";
+/** `=1` lets the transcription WebSocket take the API key as `?token=`. */
+export declare const SERVER_WS_ALLOW_QUERY_TOKEN_ENV = "NEUROLINK_SERVER_WS_ALLOW_QUERY_TOKEN";
+/** Whether `name` is set to `1` (trimmed) in the environment. */
+export declare function envFlag(name: string): boolean;
+/** `true` when `host` names only this machine (`127.0.0.1`, `::1`, `localhost`). */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Why `neurolink serve` must not start as asked, or `undefined` when it may.
+ * A listener the network can reach with no API key hands every route, tool
+ * execution included, to anyone who finds the port; the operator has to say so.
+ */
+export declare function unauthenticatedBindRefusal(options: {
+    host: string;
+    apiKeyCount: number;
+    allowUnauthenticated: boolean;
+}): string | undefined;
+/**
+ * The paths a key never guards: the liveness, readiness and startup probes an
+ * orchestrator calls with no credentials, and the basic health check. An
+ * exact list: `/health/detailed` reports the runtime and the MCP inventory,
+ * and `/version` the Node version, so both need the key like any other route.
+ */
+export declare function healthExemptPaths(basePath: string): string[];
 /**
  * Resolve the listen port: --port, then the config file, then the PORT
  * environment variable (what container platforms set), then 3000.
@@ -14,8 +47,11 @@ export declare function resolveServerPort(cliPort?: number, filePort?: number):
 export declare function readServerApiKeys(): string[];
 /**
  * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
- * Health probes stay open so orchestrators can reach them, and the dev
- * playground header cannot bypass a key the operator configured.
+ * The health probes (see `healthExemptPaths`) stay open so orchestrators can
+ * reach them, and the dev playground header cannot bypass a key the operator
+ * configured. The exemption is an exact match on the path, made here rather
+ * than through the adapters' `excludePaths`, whose entries cover a subtree:
+ * `/health` used to exempt `/health/detailed` and even `/health/api/version`.
  *
  * Every holder of a key gets the same `{ id: "api-key" }`, marked `shared` so
  * the agent routes know it names no person and do not warn when a request