@owine/unifi-network-mcp 2.14.2 → 3.0.0

package/dist/utils/secrets.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * WiFi broadcasts come back from the API with their passphrases in plaintext
+ * (`securityConfiguration.passphrase`, and one per VLAN in
+ * `securityConfiguration.presharedKeys[].passphrase` on PPSK SSIDs). None of
+ * this is in the published docs. Tools redact these values by default so they
+ * do not land in LLM transcripts; callers opt in with `includeSecrets: true`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTED = void 0;
+exports.redactSecrets = redactSecrets;
+exports.restoreRedacted = restoreRedacted;
+exports.containsRedacted = containsRedacted;
+exports.REDACTED = "[REDACTED]";
+const SECRET_KEYS = new Set(["passphrase", "password", "secret", "sharedSecret"]);
+/** Deep copy of `data` with every secret-named string value replaced by REDACTED. */
+function redactSecrets(data) {
+    return redact(data);
+}
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        SECRET_KEYS.has(key) && typeof entry === "string" ? exports.REDACTED : redact(entry),
+    ]));
+}
+/**
+ * Replace each REDACTED placeholder in `value` with the real value found at the
+ * same path in `current`. This lets a caller echo back a redacted object from a
+ * read tool without overwriting the passphrase with the placeholder text.
+ * Throws if a placeholder has no real value to restore (e.g. on create, or when
+ * a new PPSK entry is added without its passphrase).
+ *
+ * Array items are matched by index, which is only safe while the item is
+ * otherwise unchanged: a reordered `presharedKeys[]` must not hand one VLAN's
+ * passphrase to another. So a placeholder inside an array item is restored only
+ * when that item equals the current item at the same index apart from secrets.
+ */
+function restoreRedacted(value, current, path = "body") {
+    if (value === exports.REDACTED) {
+        if (typeof current === "string")
+            return current;
+        throw new Error(`${path} is "${exports.REDACTED}" with no existing value to keep — pass the real secret, or omit the field`);
+    }
+    if (Array.isArray(value)) {
+        const currentItems = Array.isArray(current) ? current : [];
+        return value.map((item, i) => {
+            const itemPath = `${path}[${i}]`;
+            if (!containsRedacted(item))
+                return item;
+            if (stableStringify(redact(item)) !== stableStringify(redact(currentItems[i]))) {
+                throw new Error(`${itemPath} contains "${exports.REDACTED}" but differs from the existing entry at that position — pass the real secret for changed or reordered entries`);
+            }
+            return restoreRedacted(item, currentItems[i], itemPath);
+        });
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    const currentObject = current !== null && typeof current === "object" && !Array.isArray(current)
+        ? current
+        : {};
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        restoreRedacted(entry, currentObject[key], `${path}.${key}`),
+    ]));
+}
+function containsRedacted(value) {
+    if (value === exports.REDACTED)
+        return true;
+    if (Array.isArray(value))
+        return value.some(containsRedacted);
+    if (value === null || typeof value !== "object")
+        return false;
+    return Object.values(value).some(containsRedacted);
+}
+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)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
+    return `{${entries.join(",")}}`;
+}

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;

package/dist/write-log.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteLog = void 0;
+exports.noteWriteRequest = noteWriteRequest;
+exports.noteWriteStatus = noteWriteStatus;
+exports.noteRefusal = noteRefusal;
+exports.localTimestamp = localTimestamp;
+exports.openWriteLog = openWriteLog;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const responses_js_1 = require("./utils/responses.js");
+const secrets_js_1 = require("./utils/secrets.js");
+const currentCall = new node_async_hooks_1.AsyncLocalStorage();
+const withoutQuery = (path) => path.split("?")[0];
+/** NetworkClient: a write request passed the guard and is about to be sent. */
+function noteWriteRequest(method, path) {
+    const call = currentCall.getStore();
+    if (call)
+        call.request = { method, path: withoutQuery(path) };
+}
+/** NetworkClient: the controller answered the write request. */
+function noteWriteStatus(status) {
+    const request = currentCall.getStore()?.request;
+    if (request)
+        request.status = status;
+}
+/** A check refused the call; the first refusal is the one logged. */
+function noteRefusal(reason, method, path) {
+    const call = currentCall.getStore();
+    if (call && !call.refusal)
+        call.refusal = { reason, method, ...(path === undefined ? {} : { path: withoutQuery(path) }) };
+}
+/**
+ * Field names, compared without case, whose value is redacted whatever it
+ * is. Names are matched exactly, not by substring, so containers such as
+ * presharedKeys keep their network IDs (redactSecrets masks the passphrase
+ * in each entry) and fields like keyId stay readable. The list: the names
+ * redactSecrets knows from WiFi and RADIUS bodies, their legacy-API x_
+ * forms, and the usual names of credentials and key material a firewall
+ * policy record (or a mistaken argument) could carry.
+ */
+const SECRET_FIELDS = new Set([
+    "passphrase", "password", "secret", "sharedSecret", "radiusSecret",
+    "x_passphrase", "x_password", "x_secret", "x_shared_secret",
+    "apiKey", "api_key", "apiToken", "token", "accessToken", "refreshToken", "authToken",
+    "privateKey", "private_key", "presharedKey",
+].map((name) => name.toLowerCase()));
+function redactArgs(value) {
+    if (Array.isArray(value))
+        return value.map(redactArgs);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, SECRET_FIELDS.has(key.toLowerCase()) ? secrets_js_1.REDACTED : redactArgs(entry)]));
+}
+/** "2026-10-18T21:04:05.123+02:00": the local time with its offset. */
+function localTimestamp(date) {
+    const pad = (n, width = 2) => String(Math.abs(n)).padStart(width, "0");
+    const offset = -date.getTimezoneOffset();
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}` +
+        `${offset < 0 ? "-" : "+"}${pad(Math.trunc(offset / 60))}:${pad(offset % 60)}`;
+}
+class WriteLog {
+    sink;
+    apiKey;
+    failed = false;
+    /** sink appends one line; it may throw, and a failure is reported once and never breaks the call. */
+    constructor(sink, apiKey) {
+        this.sink = sink;
+        this.apiKey = apiKey;
+    }
+    /**
+     * 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, apiKey) {
+        const windows = process.platform === "win32";
+        let existing;
+        try {
+            existing = (0, node_fs_1.lstatSync)(path);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        if (existing?.isSymbolicLink())
+            throw new Error("it is a symlink; point it at the file itself");
+        if (existing === undefined)
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        // O_NOFOLLOW closes the gap between the check above and the open.
+        const noFollow = windows ? 0 : node_fs_1.constants.O_NOFOLLOW;
+        const fd = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_APPEND | node_fs_1.constants.O_CREAT | noFollow, 0o600);
+        const stats = (0, node_fs_1.fstatSync)(fd);
+        const problem = !stats.isFile() ? "it is not a regular file"
+            : windows ? undefined
+                : stats.nlink > 1 ? "it has other hard links, so lines could land in another file"
+                    : (stats.mode & 0o022) !== 0 ? `it is group- or world-writable (mode ${(stats.mode & 0o777).toString(8)}); chmod 600 it`
+                        : undefined;
+        if (problem !== undefined) {
+            (0, node_fs_1.closeSync)(fd);
+            throw new Error(problem);
+        }
+        return new WriteLog((line) => { (0, node_fs_1.writeSync)(fd, line); }, apiKey);
+    }
+    /** Run one write tool call and append its line. */
+    async record(tool, input, run) {
+        const started = new Date();
+        const call = {};
+        let result;
+        try {
+            result = await currentCall.run(call, run);
+            return result;
+        }
+        finally {
+            this.append(this.entry(tool, input, call, result, started));
+        }
+    }
+    entry(tool, input, call, result, started) {
+        const dryRun = input !== null && typeof input === "object" && "dryRun" in input && input.dryRun === true;
+        const preview = result?.structuredContent?.dryRun === true ? result.structuredContent.wouldExecute : undefined;
+        const base = {
+            ts: started.toISOString(),
+            tsLocal: localTimestamp(started),
+            tool,
+            args: redactArgs((0, secrets_js_1.redactSecrets)(input)),
+            method: null,
+            path: null,
+            dryRun,
+        };
+        const durationMs = Date.now() - started.getTime();
+        if (call.refusal) {
+            const { reason, method, path } = call.refusal;
+            return { ...base, method: method ?? null, path: path ?? null, outcome: "refused", reason, durationMs };
+        }
+        if (preview) {
+            const method = typeof preview.method === "string" ? preview.method : null;
+            const path = typeof preview.path === "string" ? withoutQuery(`/integration/v1${preview.path}`) : null;
+            return { ...base, method, path, outcome: "dry_run", durationMs };
+        }
+        const request = call.request;
+        const status = request?.status === undefined ? {} : { status: request.status };
+        const where = request ? { method: request.method, path: request.path } : {};
+        return { ...base, ...where, outcome: result === undefined || result.isError ? "error" : "ok", ...status, durationMs };
+    }
+    append(entry) {
+        try {
+            let line = JSON.stringify(entry);
+            // Arguments are the model's; if it ever pasted the key into one, keep it out.
+            if (this.apiKey.length >= 8)
+                line = line.replaceAll(this.apiKey, secrets_js_1.REDACTED);
+            this.sink(`${line}\n`);
+        }
+        catch (err) {
+            if (this.failed)
+                return;
+            this.failed = true;
+            console.error(`UNIFI_NETWORK_WRITE_LOG: cannot write the log (${(0, responses_js_1.errorMessage)(err)}); tool calls continue, but are not being logged.`);
+        }
+    }
+}
+exports.WriteLog = WriteLog;
+/** Open the write log at startup, or exit with a configuration error. */
+function openWriteLog(path, apiKey) {
+    try {
+        return WriteLog.open(path, apiKey);
+    }
+    catch (err) {
+        console.error(`Configuration error: cannot use UNIFI_NETWORK_WRITE_LOG (${path}): ${(0, responses_js_1.errorMessage)(err)}`);
+        return process.exit(1);
+    }
+}

package/dist/write-tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every write tool, grouped by the module in src/tools/ that registers it.
+ * UNIFI_NETWORK_WRITE_TOOLS names tools or groups from here, and
+ * registerAllTools() refuses to register a write tool that is missing, so the
+ * list cannot fall behind the code.
+ */
+export declare const WRITE_TOOL_GROUPS: {
+    readonly devices: readonly ["unifi_adopt_device", "unifi_remove_device", "unifi_restart_device", "unifi_power_cycle_port"];
+    readonly clients: readonly ["unifi_authorize_guest", "unifi_unauthorize_guest"];
+    readonly networks: readonly ["unifi_create_network", "unifi_update_network", "unifi_delete_network"];
+    readonly wifi: readonly ["unifi_create_wifi", "unifi_update_wifi", "unifi_delete_wifi"];
+    readonly hotspot: readonly ["unifi_create_voucher", "unifi_delete_voucher", "unifi_bulk_delete_vouchers"];
+    readonly firewall: readonly ["unifi_create_firewall_zone", "unifi_update_firewall_zone", "unifi_delete_firewall_zone", "unifi_create_firewall_policy", "unifi_update_firewall_policy", "unifi_patch_firewall_policy", "unifi_delete_firewall_policy", "unifi_reorder_firewall_policies"];
+    readonly acl: readonly ["unifi_create_acl_rule", "unifi_update_acl_rule", "unifi_delete_acl_rule", "unifi_reorder_acl_rules"];
+    readonly "dns-policies": readonly ["unifi_create_dns_policy", "unifi_update_dns_policy", "unifi_delete_dns_policy"];
+    readonly "traffic-matching": readonly ["unifi_create_traffic_matching_list", "unifi_update_traffic_matching_list", "unifi_delete_traffic_matching_list"];
+};
+export declare const WRITE_TOOLS: readonly string[];
+/**
+ * The write tools a UNIFI_NETWORK_WRITE_TOOLS value enables, in catalog
+ * order: a comma-separated list of tool and group names, or "" / "none" for
+ * none. Names that are neither come back in unknown.
+ */
+export declare function parseWriteTools(value: string): {
+    tools: string[];
+    unknown: string[];
+};