@owine/unifi-network-mcp 2.15.0 → 3.1.0

package/dist/client.js

@@ -1,42 +1,163 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NetworkClient = void 0;
+exports.NetworkClient = exports.CLASSIC_COLLECTIONS = void 0;
+exports.withCallSignal = withCallSignal;
+const node_async_hooks_1 = require("node:async_hooks");
+// undici's own fetch, not the global one: Node's built-in fetch bundles an
+// older undici whose handlers the Agent from tls.ts (undici 8) rejects.
+const undici_1 = require("undici");
+const config_js_1 = require("./config.js");
+const guard_js_1 = require("./guard.js");
+const tls_js_1 = require("./tls.js");
+const write_log_js_1 = require("./write-log.js");
+// Well under undici's 300s default, so a stalled controller fails the call
+// before the MCP host gives up on it.
+const REQUEST_TIMEOUT_MS = 30_000;
+const CONTROLLER_TIMEOUT_MS = 25_000;
+// What undici reports when the console closed the connection under a
+// request, typically a kept-alive socket it had already timed out.
+const SOCKET_CLOSED = ["UND_ERR_SOCKET", "ECONNRESET", "EPIPE"];
+function socketClosed(err) {
+    const cause = err instanceof Error ? err.cause : undefined;
+    return cause instanceof Error && "code" in cause && typeof cause.code === "string" && SOCKET_CLOSED.includes(cause.code);
+}
+/**
+ * Send a read, and once more if the console closed the connection under it. A
+ * connection the console closed while it sat idle fails the next request on
+ * it; nothing reached the console, and a read changes nothing anyway, so it
+ * goes out again on a fresh connection.
+ */
+function retryClosedSocket(send) {
+    return send().catch((err) => {
+        if (socketClosed(err))
+            return send();
+        throw err;
+    });
+}
+/**
+ * A request that failed in flight, worded so the model knows whether retrying
+ * is safe: a timed-out or cut-off write may already have been applied, and
+ * repeating a create would duplicate it. The timeout also covers reading the
+ * body, so this applies to the whole exchange, not only to fetch().
+ */
+function inFlightError(read, method, timeoutMs, err) {
+    const hint = read
+        ? "Retry when the console responds."
+        : `The ${method} may still have been applied; check the resource before retrying.`;
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+        return new Error(`UniFi controller did not respond within ${timeoutMs / 1000}s. ${hint}`, { cause: err });
+    }
+    if (!read && socketClosed(err)) {
+        return new Error(`The UniFi controller closed the connection during the ${method}. ${hint}`, { cause: err });
+    }
+    return err;
+}
+// The abort signal of the MCP tool call a request is made for. Without it a
+// cancelled (or abandoned) call keeps its request running, and a write lands
+// after the host has already reported the call as failed.
+const callSignal = new node_async_hooks_1.AsyncLocalStorage();
+/** Run fn so that every request it makes is aborted when signal is. */
+function withCallSignal(signal, fn) {
+    return signal ? callSignal.run(signal, fn) : fn();
+}
+const ERROR_BODY_LIMIT = 500;
+/**
+ * The useful part of an error body for the model: the API's documented
+ * message, code and request ID, or a capped excerpt of anything else (a proxy
+ * or UniFi OS HTML error page would otherwise land in the context whole).
+ */
+function describeErrorBody(text) {
+    try {
+        const body = JSON.parse(text);
+        if (body && typeof body === "object" && "message" in body && typeof body.message === "string") {
+            const details = [
+                "code" in body && typeof body.code === "string" ? body.code : undefined,
+                "requestId" in body && typeof body.requestId === "string" ? `request ${body.requestId}` : undefined,
+            ].filter((detail) => detail !== undefined);
+            const message = capped(body.message);
+            return details.length > 0 ? `${message} (${details.join("; ")})` : message;
+        }
+    }
+    catch {
+        // Not JSON: fall through to the excerpt.
+    }
+    return capped(text);
+}
+function capped(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > ERROR_BODY_LIMIT ? `${collapsed.slice(0, ERROR_BODY_LIMIT)}…` : collapsed;
+}
+function requestSignal(timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const caller = callSignal.getStore();
+    return caller ? AbortSignal.any([caller, timeout]) : timeout;
+}
+/** The classic controller REST collections the classic read tools list. */
+exports.CLASSIC_COLLECTIONS = ["networkconf", "firewallgroup", "firewallrule", "portforward"];
+const HISTORY = {
+    name: "Controller history",
+    query: "history query",
+    notEmpty: "This is not an empty history result.",
+    tooLarge: "reduce the page size or time window",
+};
+const CLASSIC = {
+    name: "Classic controller API",
+    query: "classic API read",
+    notEmpty: "This is not an empty result.",
+    tooLarge: "the collection is too large to return",
+};
 class NetworkClient {
-    baseUrl;
     headers;
     networkUrl;
+    dispatcher;
+    policy;
     constructor(config) {
         // Cloud Connector only exists behind api.ui.com. A console ID set against a
         // local controller is ignored rather than fatal: the other tools work fine
         // against that controller, and taking the whole server down helps nobody.
-        const useConnector = config.consoleId !== undefined && config.host === "api.ui.com";
+        const useConnector = config.consoleId !== undefined && (0, config_js_1.isSiteManagerHost)(config.host);
         if (config.consoleId !== undefined && !useConnector) {
             console.error(`Ignoring UNIFI_NETWORK_CONSOLE_ID: Cloud Connector requires host api.ui.com, but host is ${config.host}.`);
         }
         const consolePath = useConnector ? `/v1/connector/consoles/${config.consoleId}` : "";
         this.networkUrl = `https://${config.host}${consolePath}/proxy/network`;
-        this.baseUrl = `${this.networkUrl}/integration/v1`;
         this.headers = {
             "X-API-KEY": config.apiKey,
             "Content-Type": "application/json",
         };
-        if (!config.verifySsl) {
-            process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-        }
+        this.dispatcher = (0, tls_js_1.consoleDispatcher)(config);
+        this.policy = { readOnly: config.readOnly, ...(config.writeTools ? { writeTools: config.writeTools } : {}) };
     }
+    /**
+     * path is relative to the Integration API, as the tools pass it. The guard
+     * sees it as the canonical path under the Network application; the host and
+     * any Cloud Connector prefix are added only once it has passed.
+     */
     async request(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
+        const canonical = `/integration/v1${path}`;
+        this.guard(method, canonical);
+        const url = `${this.networkUrl}${canonical}`;
+        const send = () => this.send(method, url, body).catch((err) => {
+            throw inFlightError(method === "GET", method, REQUEST_TIMEOUT_MS, err);
+        });
+        return method === "GET" ? retryClosedSocket(send) : send();
+    }
+    async send(method, url, body) {
         const options = {
             method,
             headers: this.headers,
+            redirect: "error",
+            signal: requestSignal(REQUEST_TIMEOUT_MS),
+            dispatcher: this.dispatcher,
         };
         if (body !== undefined) {
             options.body = JSON.stringify(body);
         }
-        const response = await fetch(url, options);
+        const response = await (0, undici_1.fetch)(url, options);
+        if (method !== "GET")
+            (0, write_log_js_1.noteWriteStatus)(response.status);
         if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`HTTP ${response.status}: ${text}`);
+            throw new Error(`HTTP ${response.status}: ${describeErrorBody(await response.text())}`);
         }
         const contentType = response.headers.get("content-type") ?? "";
         if (contentType.includes("application/json")) {
@@ -44,6 +165,19 @@ class NetworkClient {
         }
         return response.text();
     }
+    /** Check a request against the guard before anything is sent, and note writes for the write log. */
+    guard(method, path) {
+        try {
+            const route = (0, guard_js_1.guardRequest)(method, path, this.policy);
+            if (route.tools !== undefined)
+                (0, write_log_js_1.noteWriteRequest)(method, path);
+        }
+        catch (err) {
+            if (err instanceof guard_js_1.GuardError)
+                (0, write_log_js_1.noteRefusal)("request_guard", method, path);
+            throw err;
+        }
+    }
     async get(path) {
         return this.request("GET", path);
     }
@@ -80,31 +214,64 @@ class NetworkClient {
             ...(mac ? { mac: mac.toLowerCase() } : {}),
         });
     }
+    /** A classic controller REST collection, read whole: the controller does not page these. */
+    async getClassic(siteReference, collection) {
+        this.validateSiteReference(siteReference);
+        if (!exports.CLASSIC_COLLECTIONS.includes(collection))
+            throw new Error(`Unknown classic collection ${collection}`);
+        return this.classicRequest(`/api/s/${siteReference}/rest/${collection}`);
+    }
+    /**
+     * The site's classic settings (get/setting): one record per section, keyed
+     * by its key field. Sections hold credentials (SSH passwords, RADIUS and
+     * cloud-access keys), so callers copy out only the fields they need.
+     */
+    async getClassicSettings(siteReference) {
+        this.validateSiteReference(siteReference);
+        return this.classicRequest(`/api/s/${siteReference}/get/setting`);
+    }
     validateSiteReference(siteReference) {
         if (!/^[A-Za-z0-9_-]{1,64}$/.test(siteReference)) {
             throw new Error("Use the site's internalReference from unifi_list_sites (for example default)");
         }
     }
     async historyRequest(path, body) {
-        const response = await fetch(`${this.networkUrl}${path}`, {
-            method: body === undefined ? "GET" : "POST", headers: this.headers,
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-            redirect: "error", signal: AbortSignal.timeout(25000),
+        const method = body === undefined ? "GET" : "POST";
+        this.guard(method, path);
+        // Both history endpoints are reads, the POST included.
+        return this.readController(HISTORY, method, path, body).catch((err) => {
+            throw inFlightError(true, method, CONTROLLER_TIMEOUT_MS, err);
         });
+    }
+    /** The classic controller API, outside /integration/v1. Only GETs of the collections the guard allows. */
+    async classicRequest(path) {
+        this.guard("GET", path);
+        return retryClosedSocket(() => this.readController(CLASSIC, "GET", path).catch((err) => {
+            throw inFlightError(true, "GET", CONTROLLER_TIMEOUT_MS, err);
+        }));
+    }
+    async readController(kind, method, path, body) {
+        const options = {
+            method, headers: this.headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            redirect: "error", signal: requestSignal(CONTROLLER_TIMEOUT_MS), dispatcher: this.dispatcher,
+        };
+        const response = await (0, undici_1.fetch)(`${this.networkUrl}${path}`, options);
         if (!response.ok) {
             // Drain before throwing: an unread body pins the socket until GC, so a
             // run of failures (say, a mis-scoped API key) would leak connections.
             await response.body?.cancel();
-            throw new Error(`Controller history returned HTTP ${response.status}; verify API-key access and controller support. This is not an empty history result.`);
+            throw new Error(`${kind.name} returned HTTP ${response.status}; verify API-key access and controller support. ${kind.notEmpty}`);
         }
         if (!response.headers.get("content-type")?.includes("application/json")) {
             await response.body?.cancel();
-            throw new Error("Controller history returned non-JSON data; verify controller authentication");
+            throw new Error(`${kind.name} returned non-JSON data; verify controller authentication`);
         }
         // Bound the body before parsing: controller session records can be large.
-        const reader = response.body?.getReader();
-        if (!reader)
-            throw new Error("Controller history returned no response body");
+        if (response.body === null)
+            throw new Error(`${kind.name} returned no response body`);
+        // undici types the body as an untyped stream; a fetch body is always bytes.
+        const reader = response.body.getReader();
         const chunks = [];
         let bytes = 0;
         try {
@@ -115,7 +282,7 @@ class NetworkClient {
                 bytes += value.length;
                 if (bytes > 10000000) {
                     await reader.cancel();
-                    throw new Error("Controller history exceeds 10 MB; reduce the page size or time window");
+                    throw new Error(`${kind.name} exceeds 10 MB; ${kind.tooLarge}`);
                 }
                 chunks.push(value);
             }
@@ -127,13 +294,21 @@ class NetworkClient {
         if (text.trim() === "") {
             // A bare JSON.parse would surface "Unexpected end of JSON input", which
             // reads as a broken tool rather than an unusable controller response.
-            throw new Error("Controller history returned an empty body; verify controller support. This is not an empty history result.");
+            throw new Error(`${kind.name} returned an empty body; verify controller support. ${kind.notEmpty}`);
+        }
+        let result;
+        try {
+            result = JSON.parse(text);
+        }
+        catch {
+            // The parser's message quotes the body around the fault, and classic
+            // records hold credentials: never pass it on.
+            throw new Error(`${kind.name} returned malformed JSON; verify controller support. ${kind.notEmpty}`);
         }
-        const result = JSON.parse(text);
         if (result && typeof result === "object" && "meta" in result) {
             const meta = result.meta;
             if (meta && typeof meta === "object" && "rc" in meta && meta.rc !== "ok") {
-                throw new Error("Controller rejected the history query (meta.rc is not ok)");
+                throw new Error(`Controller rejected the ${kind.query} (meta.rc is not ok)`);
             }
         }
         return result;

package/dist/config.d.ts

@@ -1,10 +1,21 @@
 import { z } from "zod";
+/**
+ * Whether host is api.ui.com however it is written: URL parsing lower-cases
+ * it and drops a port, and a trailing dot names the same host. The request
+ * goes to api.ui.com in each case, so each must get the same treatment.
+ */
+export declare function isSiteManagerHost(host: string): boolean;
 declare const configSchema: z.ZodObject<{
     host: z.ZodString;
     apiKey: z.ZodString;
     consoleId: z.ZodOptional<z.ZodString>;
     verifySsl: z.ZodDefault<z.ZodBoolean>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
+    writeTools: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>>;
+    allowWanExposure: z.ZodOptional<z.ZodLiteral<true>>;
+    wanZoneIds: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    writeLog: z.ZodOptional<z.ZodString>;
+    caCert: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSiteManagerHost = isSiteManagerHost;
 exports.loadConfig = loadConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const zod_1 = require("zod");
+const tls_js_1 = require("./tls.js");
+const responses_js_1 = require("./utils/responses.js");
+const write_tools_js_1 = require("./write-tools.js");
+function holdsCertificate(pem) {
+    try {
+        return (0, tls_js_1.pemCertificates)(pem).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether host is api.ui.com however it is written: URL parsing lower-cases
+ * it and drops a port, and a trailing dot names the same host. The request
+ * goes to api.ui.com in each case, so each must get the same treatment.
+ */
+function isSiteManagerHost(host) {
+    try {
+        return new URL(`https://${host}`).hostname.replace(/\.$/, "") === "api.ui.com";
+    }
+    catch {
+        return false;
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const configSchema = zod_1.z.object({
     host: zod_1.z.string().min(1).describe("UniFi Network host (IP or hostname)"),
     apiKey: zod_1.z.string().min(1).describe("UniFi Network API key"),
@@ -18,8 +46,59 @@ const configSchema = zod_1.z.object({
         .boolean()
         .default(true)
         .describe("When true, only read-only tools are registered"),
+    writeTools: zod_1.z.string()
+        .transform((value, ctx) => {
+        const { tools, unknown } = (0, write_tools_js_1.parseWriteTools)(value);
+        if (unknown.length > 0) {
+            ctx.addIssue({
+                code: "custom",
+                message: `UNIFI_NETWORK_WRITE_TOOLS names unknown write tools or groups: ${unknown.join(", ")}. Groups: ${Object.keys(write_tools_js_1.WRITE_TOOL_GROUPS).join(", ")}. Tools: ${write_tools_js_1.WRITE_TOOLS.join(", ")}. Use "none" for no write tools.`,
+            });
+            return zod_1.z.NEVER;
+        }
+        return tools;
+    })
+        .optional()
+        .describe("The write tools to register; undefined registers them all"),
+    allowWanExposure: zod_1.z
+        .literal(true)
+        .optional()
+        .describe("When true, writes that could let traffic in from the WAN fall back to the confirm flow instead of being refused"),
+    wanZoneIds: zod_1.z
+        .array(zod_1.z.string().regex(UUID, "UNIFI_NETWORK_WAN_ZONE_IDS must be a comma-separated list of firewall zone IDs (UUIDs)"))
+        .transform((ids) => ids.map((id) => id.toLowerCase()))
+        .optional()
+        .describe("Firewall zone IDs to treat as the WAN, in addition to the system-defined External zone"),
+    writeLog: zod_1.z.string()
+        .refine(node_path_1.isAbsolute, "UNIFI_NETWORK_WRITE_LOG must be an absolute path (MCP hosts do not expand ~)")
+        .optional()
+        .describe("JSON Lines file every write tool call is appended to"),
+    caCert: zod_1.z.string()
+        .refine(holdsCertificate, "UNIFI_NETWORK_CA_CERT must name a PEM file containing a certificate")
+        .optional()
+        .describe("PEM certificate(s) to trust for the console, e.g. its own self-signed certificate"),
+}).refine((config) => config.verifySsl || config.caCert === undefined, {
+    path: ["caCert"],
+    message: "UNIFI_NETWORK_CA_CERT pins a certificate to verify against; it cannot be combined with UNIFI_NETWORK_VERIFY_SSL=false",
+}).refine((config) => config.verifySsl || !isSiteManagerHost(config.host), {
+    // Opting out of verification is for local consoles with self-signed
+    // certificates. A Site Manager key reaches every console on the account
+    // and crosses the internet, so it never goes out unverified.
+    path: ["verifySsl"],
+    message: "TLS verification cannot be disabled for api.ui.com; unset UNIFI_NETWORK_VERIFY_SSL",
 });
 function loadConfig() {
+    const caCertPath = process.env.UNIFI_NETWORK_CA_CERT;
+    let caCert;
+    if (caCertPath) {
+        try {
+            caCert = (0, node_fs_1.readFileSync)(caCertPath, "utf8");
+        }
+        catch (err) {
+            console.error(`Configuration error: cannot read UNIFI_NETWORK_CA_CERT (${caCertPath}): ${(0, responses_js_1.errorMessage)(err)}`);
+            process.exit(1);
+        }
+    }
     const result = configSchema.safeParse({
         host: process.env.UNIFI_NETWORK_HOST,
         apiKey: process.env.UNIFI_NETWORK_API_KEY,
@@ -27,10 +106,30 @@ function loadConfig() {
             ? { consoleId: process.env.UNIFI_NETWORK_CONSOLE_ID } : {}),
         verifySsl: process.env.UNIFI_NETWORK_VERIFY_SSL?.toLowerCase() !== "false",
         readOnly: process.env.UNIFI_NETWORK_READ_ONLY?.toLowerCase() !== "false",
+        ...(caCert !== undefined ? { caCert } : {}),
+        ...(process.env.UNIFI_NETWORK_ALLOW_WAN_EXPOSURE?.toLowerCase() === "true"
+            ? { allowWanExposure: true } : {}),
+        ...(process.env.UNIFI_NETWORK_WAN_ZONE_IDS
+            ? { wanZoneIds: process.env.UNIFI_NETWORK_WAN_ZONE_IDS.split(",").map((id) => id.trim()).filter((id) => id !== "") } : {}),
+        ...(process.env.UNIFI_NETWORK_WRITE_LOG
+            ? { writeLog: process.env.UNIFI_NETWORK_WRITE_LOG } : {}),
+        ...(process.env.UNIFI_NETWORK_WRITE_TOOLS !== undefined
+            ? { writeTools: process.env.UNIFI_NETWORK_WRITE_TOOLS } : {}),
     });
     if (!result.success) {
-        console.error("Configuration error:", result.error.format());
-        process.exit(1);
+        console.error(`Configuration error:\n${zod_1.z.prettifyError(result.error)}`);
+        return process.exit(1);
+    }
+    const config = result.data;
+    if (config.readOnly && config.writeTools !== undefined) {
+        // Still validated above, so a typo shows up before writes are turned on.
+        console.error("Ignoring UNIFI_NETWORK_WRITE_TOOLS: the server is read-only, so no write tools load. Set UNIFI_NETWORK_READ_ONLY=false to use it.");
+        delete config.writeTools;
+    }
+    if (config.readOnly && config.writeLog !== undefined) {
+        // Nothing would be logged, and opening the file could stop the server.
+        console.error("Ignoring UNIFI_NETWORK_WRITE_LOG: the server is read-only, so there are no write calls to log. Set UNIFI_NETWORK_READ_ONLY=false to use it.");
+        delete config.writeLog;
     }
-    return result.data;
+    return config;
 }

package/dist/guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The request guard: every request NetworkClient makes is checked here before
+ * fetch is called, against a fixed allowlist of the endpoints the tools in
+ * src/tools/ use. Anything else is refused and nothing is sent, so a tool bug,
+ * a smuggled ID or a misled model cannot reach the rest of the console with
+ * this API key (the rest of the legacy controller API, Protect, another
+ * console behind the Cloud Connector).
+ *
+ * Paths are canonical and relative to the Network application: they start
+ * /integration/v1, /v2/api or /api/s, never with the Cloud Connector prefix,
+ * which NetworkClient adds only after the guard has passed.
+ */
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type GuardReason = "malformed" | "method" | "not_allowlisted" | "query" | "read_only" | "tool_disabled";
+export declare class GuardError extends Error {
+    readonly reason: GuardReason;
+    constructor(reason: GuardReason, message: string);
+}
+export interface Route {
+    method: Method;
+    /** Canonical path; each {id} is one ID segment, and {site} a site's internalReference. */
+    template: string;
+    /** Query parameters the endpoint may be sent; any other is refused. */
+    query?: readonly string[];
+    /** Query parameters that must be present. */
+    requiredQuery?: readonly string[];
+    /**
+     * The write tools that send this request. A route without tools is a read,
+     * allowed whatever write tools are enabled — including stat/session's POST,
+     * which only queries statistics.
+     */
+    tools?: readonly string[];
+}
+export interface GuardPolicy {
+    readOnly: boolean;
+    /** Enabled write tools; undefined enables every write tool. */
+    writeTools?: readonly string[];
+}
+/** Every request the tools make. Keep in step with src/tools/; tests/guard.test.ts sweeps every tool against it. */
+export declare const ROUTES: readonly Route[];
+/**
+ * Check one request and return the route it matched. Throws GuardError,
+ * before anything is sent, for a malformed path, an unknown endpoint, an
+ * unexpected query parameter, or a write the policy does not allow.
+ */
+export declare function guardRequest(method: string, path: string, policy: GuardPolicy): Route;