@owine/unifi-network-mcp 2.15.0 → 3.1.0

package/dist/utils/safety.d.ts

@@ -1,14 +1,48 @@
+import { z } from "zod";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+/** The confirm input of a DESTRUCTIVE tool. */
+export declare const confirmDestructive: () => z.ZodOptional<z.ZodBoolean>;
 export declare const READ_ONLY: ToolAnnotations;
 export declare const WRITE: ToolAnnotations;
 export declare const WRITE_NOT_IDEMPOTENT: ToolAnnotations;
 export declare const DESTRUCTIVE: ToolAnnotations;
-export declare function formatDryRun(method: string, path: string, body?: unknown): {
+/**
+ * A dry run's result. confirmationRequired is the reason the real call needs
+ * confirm, if it does: the preview is what the user approves, so it has to
+ * say that the change opens access before they approve it, not after.
+ */
+export declare function formatDryRun(method: string, path: string, body?: unknown, confirmationRequired?: string): {
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent: Record<string, unknown>;
 };
+/**
+ * Confirmation for a write that is routine in general but, with these inputs,
+ * opens access — an ALLOW rule, an open SSID, a batch of guest codes. reason
+ * says what opens, or is undefined when nothing does; a dry run changes
+ * nothing, so it never needs confirming.
+ */
+export declare function requireConfirmationIf(reason: string | undefined, confirm: boolean | undefined, dryRun: boolean | undefined): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;
+/** How a rule in an evaluation order treats the traffic it matches. */
+export interface RuleEffect {
+    letsThrough: boolean;
+    blocks: boolean;
+}
+/**
+ * Whether a reorder opens access: whether it moves a rule that lets traffic
+ * through ahead of one that blocks, which it used to follow. Only rules in
+ * both orders are compared, and effect is asked only about the rules a
+ * reorder actually moves past one another. IDs are compared without case.
+ */
+export declare function reorderOpens(before: readonly string[], after: readonly string[], effect: (id: string) => Promise<RuleEffect>): Promise<boolean>;
 export declare function requireConfirmation(confirm: boolean | undefined, action: string): {
     content: {
         type: "text";

package/dist/utils/safety.js

@@ -1,38 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DESTRUCTIVE = exports.WRITE_NOT_IDEMPOTENT = exports.WRITE = exports.READ_ONLY = void 0;
+exports.DESTRUCTIVE = exports.WRITE_NOT_IDEMPOTENT = exports.WRITE = exports.READ_ONLY = exports.confirmDestructive = void 0;
 exports.formatDryRun = formatDryRun;
+exports.requireConfirmationIf = requireConfirmationIf;
+exports.reorderOpens = reorderOpens;
 exports.requireConfirmation = requireConfirmation;
+const zod_1 = require("zod");
+const write_log_js_1 = require("../write-log.js");
+/** The confirm input of a DESTRUCTIVE tool. */
+const confirmDestructive = () => zod_1.z.boolean().optional().describe("Must be true to execute this destructive action; not needed with dryRun: true");
+exports.confirmDestructive = confirmDestructive;
 exports.READ_ONLY = {
     readOnlyHint: true,
     destructiveHint: false,
+    openWorldHint: false,
 };
 exports.WRITE = {
     readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: true,
+    openWorldHint: false,
 };
 exports.WRITE_NOT_IDEMPOTENT = {
     readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: false,
+    openWorldHint: false,
 };
 exports.DESTRUCTIVE = {
     readOnlyHint: false,
     destructiveHint: true,
     idempotentHint: false,
+    openWorldHint: false,
 };
-function formatDryRun(method, path, body) {
+/**
+ * A dry run's result. confirmationRequired is the reason the real call needs
+ * confirm, if it does: the preview is what the user approves, so it has to
+ * say that the change opens access before they approve it, not after.
+ */
+function formatDryRun(method, path, body, confirmationRequired) {
     const preview = {
         dryRun: true,
         wouldExecute: { method, path, ...(body !== undefined ? { body } : {}) },
+        ...(confirmationRequired !== undefined ? { confirmationRequired } : {}),
     };
+    // structuredContent is required: the SDK rejects a result without it from
+    // any tool that declares an outputSchema.
     return {
-        content: [{ type: "text", text: JSON.stringify(preview, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(preview) }],
+        structuredContent: preview,
     };
 }
+/**
+ * Confirmation for a write that is routine in general but, with these inputs,
+ * opens access — an ALLOW rule, an open SSID, a batch of guest codes. reason
+ * says what opens, or is undefined when nothing does; a dry run changes
+ * nothing, so it never needs confirming.
+ */
+function requireConfirmationIf(reason, confirm, dryRun) {
+    return reason === undefined || dryRun ? null : requireConfirmation(confirm, reason);
+}
+/**
+ * Whether a reorder opens access: whether it moves a rule that lets traffic
+ * through ahead of one that blocks, which it used to follow. Only rules in
+ * both orders are compared, and effect is asked only about the rules a
+ * reorder actually moves past one another. IDs are compared without case.
+ */
+async function reorderOpens(before, after, effect) {
+    const rank = new Map(before.map((id, index) => [id.toLowerCase(), index]));
+    const passes = [];
+    after.forEach((ahead, i) => {
+        for (const behind of after.slice(i + 1)) {
+            const [was, other] = [rank.get(ahead.toLowerCase()), rank.get(behind.toLowerCase())];
+            if (was !== undefined && other !== undefined && was > other)
+                passes.push([ahead, behind]);
+        }
+    });
+    const ids = [...new Set(passes.flat())];
+    const effects = new Map(await Promise.all(ids.map(async (id) => [id, await effect(id)])));
+    return passes.some(([ahead, behind]) => effects.get(ahead)?.letsThrough === true && effects.get(behind)?.blocks === true);
+}
 function requireConfirmation(confirm, action) {
     if (confirm !== true) {
+        (0, write_log_js_1.noteRefusal)("confirmation_required");
         return {
             content: [
                 {

package/dist/utils/secrets.js

@@ -79,6 +79,9 @@ function containsRedacted(value) {
 function stableStringify(value) {
     if (Array.isArray(value))
         return `[${value.map(stableStringify).join(",")}]`;
+    // JSON.stringify returns undefined for undefined and functions, whatever
+    // its lib.d.ts signature says.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (value === null || typeof value !== "object")
         return JSON.stringify(value) ?? "undefined";
     const entries = Object.entries(value)

package/dist/utils/wan-exposure.d.ts

@@ -0,0 +1,69 @@
+import type { NetworkClient } from "../client.js";
+/**
+ * Hard refusals for writes that would let traffic in from the WAN. Unlike
+ * confirm, which the model can pass after asking (or after being talked into
+ * it by data it read), these hold whatever the call says: the operator turns
+ * them off with UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true, and then the existing
+ * confirm flow applies.
+ *
+ * Which zone is the WAN: the Integration API marks zones only with
+ * metadata.origin, and names can be changed, so a zone is the WAN when its ID
+ * is in UNIFI_NETWORK_WAN_ZONE_IDS, or when it is system-defined and named
+ * "External". The ID list is the reliable signal; the name is the fallback
+ * for operators who have not set it. When the zones cannot be read, or a
+ * zone a change depends on is not among them, the write is refused: a check
+ * that cannot run must not pass.
+ *
+ * ACL rules need no check: they are switch-enforced IPV4/MAC rules between
+ * LAN hosts and have no zone, so they cannot admit WAN traffic past the
+ * gateway firewall. The Integration API has no port-forward endpoint.
+ */
+export interface WanPolicy {
+    /** UNIFI_NETWORK_ALLOW_WAN_EXPOSURE: skip these refusals. */
+    allowExposure: boolean;
+    /** UNIFI_NETWORK_WAN_ZONE_IDS, lower-cased. */
+    zoneIds: readonly string[];
+}
+export declare const DEFAULT_WAN_POLICY: WanPolicy;
+/** The checks for one site; zones and policies are read at most once per call. */
+export declare class WanExposure {
+    private readonly client;
+    private readonly wan;
+    private readonly siteId;
+    private zones?;
+    private policies?;
+    constructor(client: NetworkClient, wan: WanPolicy, siteId: string);
+    /** A firewall policy, as it would be after the write: refused if it ALLOWs traffic from the WAN. */
+    firewallPolicy(policy: Record<string, unknown>): Promise<string | undefined>;
+    /** A zone create (zoneId undefined) or full update: refused if it changes the WAN zone or takes networks from it. */
+    firewallZone(zoneId: string | undefined, networkIds: readonly string[]): Promise<string | undefined>;
+    /** A zone delete: refused if it is the WAN zone. */
+    zoneDelete(zoneId: string): Promise<string | undefined>;
+    /** The zone a network is put in, and on an update the zone it leaves: refused if either is the WAN zone. */
+    networkZone(zoneId: string, currentZoneId?: string): Promise<string | undefined>;
+    /** A policy reorder: refused for policies that apply to traffic from the WAN. */
+    policyOrder(sourceZoneId: string): Promise<string | undefined>;
+    /** A traffic matching list update: refused if a policy that ALLOWs traffic from the WAN uses the list. */
+    matchingList(listId: string): Promise<string | undefined>;
+    /**
+     * Refuse a change that puts networks in zone when a policy ALLOWs traffic
+     * from the WAN into it: the networks would be reachable from the WAN with no
+     * policy changing. A policy's destination trafficFilter may narrow it to
+     * hosts outside the networks, but telling that apart takes more of the
+     * filter's shape than the docs pin down, so it counts either way.
+     */
+    private refuseIfWanTarget;
+    private isWan;
+    private zone;
+    private zoneList;
+    private policyList;
+    private refusal;
+}
+/** The result of a refused write; method and path are the write it would have sent. */
+export declare function wanRefusal(reason: string, method: string, path: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/utils/wan-exposure.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WanExposure = exports.DEFAULT_WAN_POLICY = void 0;
+exports.wanRefusal = wanRefusal;
+const zod_1 = require("zod");
+const write_log_js_1 = require("../write-log.js");
+const responses_js_1 = require("./responses.js");
+exports.DEFAULT_WAN_POLICY = { allowExposure: false, zoneIds: [] };
+const Zone = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    networkIds: zod_1.z.array(zod_1.z.string()).optional(),
+    metadata: zod_1.z.object({ origin: zod_1.z.string().optional() }).loose().optional(),
+}).loose();
+const Policy = zod_1.z.object({
+    id: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    action: zod_1.z.unknown().optional(),
+    source: zod_1.z.unknown().optional(),
+    destination: zod_1.z.unknown().optional(),
+}).loose();
+const PAGE_LIMIT = 200;
+const MAX_PAGES = 50;
+async function listAll(client, path, item) {
+    const page = zod_1.z.object({ data: zod_1.z.array(item), totalCount: zod_1.z.number().optional() }).loose();
+    const items = [];
+    for (let pages = 0; pages < MAX_PAGES; pages++) {
+        const { data, totalCount } = page.parse(await client.get(`${path}?offset=${items.length}&limit=${PAGE_LIMIT}`));
+        items.push(...data);
+        // Without a totalCount, only an empty page shows the list has ended: a
+        // controller may cap pages below PAGE_LIMIT, so a short page proves nothing.
+        if (data.length === 0 || (totalCount !== undefined && items.length >= totalCount))
+            return items;
+    }
+    // A list that does not end cannot be checked, which must not pass.
+    throw new Error(`the list did not end after ${MAX_PAGES} pages`);
+}
+class Refusal extends Error {
+}
+/** The checks for one site; zones and policies are read at most once per call. */
+class WanExposure {
+    client;
+    wan;
+    siteId;
+    zones;
+    policies;
+    constructor(client, wan, siteId) {
+        this.client = client;
+        this.wan = wan;
+        this.siteId = siteId;
+    }
+    /** A firewall policy, as it would be after the write: refused if it ALLOWs traffic from the WAN. */
+    async firewallPolicy(policy) {
+        if (this.wan.allowExposure || !allowsTraffic(policy))
+            return undefined;
+        return this.refusal(async () => {
+            const zoneId = sourceZoneId(policy);
+            if (zoneId === undefined) {
+                throw new Refusal("the policy ALLOWs traffic but has no source.zoneId, so its source cannot be checked against the WAN zone");
+            }
+            const zone = await this.zone(zoneId, "its source zone");
+            if (this.isWan(zone))
+                throw new Refusal(`the policy would ALLOW traffic from the ${label(zone)} zone, which is the WAN`);
+        });
+    }
+    /** A zone create (zoneId undefined) or full update: refused if it changes the WAN zone or takes networks from it. */
+    async firewallZone(zoneId, networkIds) {
+        if (this.wan.allowExposure || (zoneId === undefined && networkIds.length === 0))
+            return undefined;
+        return this.refusal(async () => {
+            if (zoneId !== undefined) {
+                const zone = await this.zone(zoneId, "the zone");
+                if (this.isWan(zone))
+                    throw new Refusal(`the change would modify the ${label(zone)} zone, which is the WAN`);
+            }
+            const wanNetworks = new Set((await this.zoneList()).filter((zone) => this.isWan(zone))
+                .flatMap((zone) => zone.networkIds ?? []).map((id) => id.toLowerCase()));
+            const moved = networkIds.filter((id) => wanNetworks.has(id.toLowerCase()));
+            if (moved.length > 0)
+                throw new Refusal(`the change would move networks out of the WAN zone: ${moved.join(", ")}`);
+            // A new zone has no policies yet; an existing one may be open to the WAN.
+            if (zoneId !== undefined) {
+                const zone = await this.zone(zoneId, "the zone");
+                const present = new Set((zone.networkIds ?? []).map((id) => id.toLowerCase()));
+                const added = networkIds.filter((id) => !present.has(id.toLowerCase()));
+                if (added.length > 0)
+                    await this.refuseIfWanTarget(zone, `add networks (${added.join(", ")}) to`);
+            }
+        });
+    }
+    /** A zone delete: refused if it is the WAN zone. */
+    async zoneDelete(zoneId) {
+        if (this.wan.allowExposure)
+            return undefined;
+        return this.refusal(async () => {
+            const zone = await this.zone(zoneId, "the zone");
+            if (this.isWan(zone))
+                throw new Refusal(`the change would delete the ${label(zone)} zone, which is the WAN`);
+        });
+    }
+    /** The zone a network is put in, and on an update the zone it leaves: refused if either is the WAN zone. */
+    async networkZone(zoneId, currentZoneId) {
+        if (this.wan.allowExposure)
+            return undefined;
+        return this.refusal(async () => {
+            if (currentZoneId !== undefined) {
+                const current = await this.zone(currentZoneId, "the network's current zoneId");
+                if (this.isWan(current))
+                    throw new Refusal(`the change would move the network out of the ${label(current)} zone, which is the WAN`);
+            }
+            const zone = await this.zone(zoneId, "the network's zoneId");
+            if (this.isWan(zone))
+                throw new Refusal(`the change would put the network in the ${label(zone)} zone, which is the WAN`);
+            await this.refuseIfWanTarget(zone, "put the network in");
+        });
+    }
+    /** A policy reorder: refused for policies that apply to traffic from the WAN. */
+    async policyOrder(sourceZoneId) {
+        if (this.wan.allowExposure)
+            return undefined;
+        return this.refusal(async () => {
+            const zone = await this.zone(sourceZoneId, "the source zone");
+            if (this.isWan(zone)) {
+                throw new Refusal(`the change would reorder the policies for traffic from the ${label(zone)} zone, which is the WAN, and could put an ALLOW ahead of a BLOCK`);
+            }
+        });
+    }
+    /** A traffic matching list update: refused if a policy that ALLOWs traffic from the WAN uses the list. */
+    async matchingList(listId) {
+        if (this.wan.allowExposure)
+            return undefined;
+        return this.refusal(async () => {
+            // Either lookup failing refuses the write.
+            const [zones, policies] = await Promise.all([this.zoneList(), this.policyList()]);
+            const user = policies.find((policy) => {
+                // IDs are compared without case: the controller may not care about it.
+                if (!allowsTraffic(policy) || !JSON.stringify(policy).toLowerCase().includes(JSON.stringify(listId.toLowerCase())))
+                    return false;
+                // A source zone that is not on the list could be the WAN: count it.
+                const zone = zones.find((candidate) => sameId(candidate.id, sourceZoneId(policy)));
+                return zone === undefined || this.isWan(zone);
+            });
+            if (user) {
+                throw new Refusal(`the list is used by firewall policy ${JSON.stringify(user.name ?? user.id)}, which ALLOWs traffic from the WAN, so changing it changes what the WAN can reach`);
+            }
+        });
+    }
+    /**
+     * Refuse a change that puts networks in zone when a policy ALLOWs traffic
+     * from the WAN into it: the networks would be reachable from the WAN with no
+     * policy changing. A policy's destination trafficFilter may narrow it to
+     * hosts outside the networks, but telling that apart takes more of the
+     * filter's shape than the docs pin down, so it counts either way.
+     */
+    async refuseIfWanTarget(zone, change) {
+        const [zones, policies] = await Promise.all([this.zoneList(), this.policyList()]);
+        const exposing = policies.find((policy) => {
+            if (!allowsTraffic(policy) || !sameId(zone.id, destinationZoneId(policy)))
+                return false;
+            // A source zone that is not on the list could be the WAN: count it.
+            const source = zones.find((candidate) => sameId(candidate.id, sourceZoneId(policy)));
+            return source === undefined || this.isWan(source);
+        });
+        if (exposing) {
+            throw new Refusal(`the change would ${change} the ${label(zone)} zone, which firewall policy ${JSON.stringify(exposing.name ?? exposing.id)} ALLOWs traffic into from the WAN`);
+        }
+    }
+    isWan(zone) {
+        return this.wan.zoneIds.includes(zone.id.toLowerCase()) ||
+            (zone.metadata?.origin === "SYSTEM_DEFINED" && zone.name?.toLowerCase() === "external");
+    }
+    async zone(zoneId, what) {
+        const zone = (await this.zoneList()).find((candidate) => sameId(candidate.id, zoneId));
+        if (zone === undefined)
+            throw new Refusal(`${what} (${zoneId}) is not one of this site's firewall zones, so it cannot be checked against the WAN zone`);
+        return zone;
+    }
+    zoneList() {
+        this.zones ??= listAll(this.client, `/sites/${this.siteId}/firewall/zones`, Zone).catch((err) => {
+            throw new Refusal(`the firewall zones could not be read to find the WAN zone (${(0, responses_js_1.errorMessage)(err)})`);
+        });
+        return this.zones;
+    }
+    policyList() {
+        this.policies ??= listAll(this.client, `/sites/${this.siteId}/firewall/policies`, Policy).catch((err) => {
+            throw new Refusal(`the firewall policies that the change depends on could not be read (${(0, responses_js_1.errorMessage)(err)})`);
+        });
+        return this.policies;
+    }
+    async refusal(check) {
+        try {
+            await check();
+            return undefined;
+        }
+        catch (err) {
+            if (err instanceof Refusal)
+                return err.message;
+            return `the WAN check failed (${(0, responses_js_1.errorMessage)(err)})`;
+        }
+    }
+}
+exports.WanExposure = WanExposure;
+/** Connection states that only answer traffic already let through, so cannot open a new connection. */
+const RETURN_STATES = ["ESTABLISHED", "RELATED"];
+/**
+ * Any action but BLOCK or REJECT lets traffic through, including a missing
+ * one, unless the policy matches only ESTABLISHED and RELATED connections.
+ * A missing, null or empty connectionStateFilter matches every state.
+ */
+function allowsTraffic(policy) {
+    const action = policy.action;
+    const type = action !== null && typeof action === "object" && "type" in action ? action.type : undefined;
+    if (type === "BLOCK" || type === "REJECT")
+        return false;
+    const states = policy.connectionStateFilter;
+    return !(Array.isArray(states) && states.length > 0 && states.every((state) => RETURN_STATES.includes(state)));
+}
+function sourceZoneId(policy) {
+    const source = policy.source;
+    const zoneId = source !== null && typeof source === "object" && "zoneId" in source ? source.zoneId : undefined;
+    return typeof zoneId === "string" ? zoneId : undefined;
+}
+function destinationZoneId(policy) {
+    const destination = policy.destination;
+    const zoneId = destination !== null && typeof destination === "object" && "zoneId" in destination ? destination.zoneId : undefined;
+    return typeof zoneId === "string" ? zoneId : undefined;
+}
+/** IDs are compared without case: the controller may not care about it. */
+function sameId(a, b) {
+    return a.toLowerCase() === b?.toLowerCase();
+}
+function label(zone) {
+    return zone.name ?? zone.id;
+}
+/** The result of a refused write; method and path are the write it would have sent. */
+function wanRefusal(reason, method, path) {
+    (0, write_log_js_1.noteRefusal)("wan_exposure", method, `/integration/v1${path}`);
+    return {
+        content: [{
+                type: "text",
+                text: `Refused: ${reason}. This server does not make changes that could let traffic in from the WAN, and confirm does not override this; if the change is intended, make it in the UniFi console.`,
+            }],
+        isError: true,
+    };
+}

package/dist/write-log.d.ts

@@ -0,0 +1,52 @@
+/**
+ * UNIFI_NETWORK_WRITE_LOG: one JSON line per write tool call, so an operator
+ * can see what an agent changed (or tried to) without trusting its account
+ * of it. Lines carry the canonical request path and HTTP status, never the
+ * host, the console ID, the API key or a controller response body.
+ */
+export type RefusalReason = "request_guard" | "wan_exposure" | "confirmation_required";
+export interface WriteLogEntry {
+    ts: string;
+    tsLocal: string;
+    tool: string;
+    args: unknown;
+    method: string | null;
+    path: string | null;
+    dryRun: boolean;
+    outcome: "ok" | "dry_run" | "refused" | "error";
+    status?: number;
+    reason?: RefusalReason;
+    durationMs: number;
+}
+/** NetworkClient: a write request passed the guard and is about to be sent. */
+export declare function noteWriteRequest(method: string, path: string): void;
+/** NetworkClient: the controller answered the write request. */
+export declare function noteWriteStatus(status: number): void;
+/** A check refused the call; the first refusal is the one logged. */
+export declare function noteRefusal(reason: RefusalReason, method?: string, path?: string): void;
+/** "2026-10-18T21:04:05.123+02:00": the local time with its offset. */
+export declare function localTimestamp(date: Date): string;
+export declare class WriteLog {
+    private readonly sink;
+    private readonly apiKey;
+    private failed;
+    /** sink appends one line; it may throw, and a failure is reported once and never breaks the call. */
+    constructor(sink: (line: string) => void, apiKey: string);
+    /**
+     * Open path for appending, creating it 0600 (and its directory 0700) if
+     * needed. Throws for a symlink, anything but a regular file, or a file
+     * others can write to, which could be truncated or filled with lies.
+     *
+     * On Windows, Node reports every writable file as mode 0666 and a link
+     * count that says nothing about access, and O_NOFOLLOW does not exist, so
+     * only the symlink and regular-file checks apply there: the file's ACL is
+     * the operator's to set.
+     */
+    static open(path: string, apiKey: string): WriteLog;
+    /** Run one write tool call and append its line. */
+    record<T>(tool: string, input: unknown, run: () => T | Promise<T>): Promise<T>;
+    private entry;
+    private append;
+}
+/** Open the write log at startup, or exit with a configuration error. */
+export declare function openWriteLog(path: string, apiKey: string): WriteLog;