@owine/unifi-network-mcp 2.14.2 → 3.0.0

package/dist/utils/output-schemas.js

@@ -1,20 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listClientSessionsOutputSchema = exports.listClientHistoryOutputSchema = exports.ClientSessionEnvelope = exports.ClientSession = exports.HistoryClient = exports.listPendingDevicesOutputSchema = exports.listCountriesOutputSchema = exports.listDpiApplicationsOutputSchema = exports.listDpiCategoriesOutputSchema = exports.listDeviceTagsOutputSchema = exports.listRadiusProfilesOutputSchema = exports.listVpnTunnelsOutputSchema = exports.listVpnServersOutputSchema = exports.listWansOutputSchema = exports.getWifiOutputSchema = exports.listWifiOutputSchema = exports.getClientOutputSchema = exports.listClientsOutputSchema = exports.getDeviceStatisticsOutputSchema = exports.getDeviceOutputSchema = exports.listDevicesOutputSchema = exports.listTrafficMatchingListsOutputSchema = exports.trafficMatchingListOutputSchema = exports.listDnsPoliciesOutputSchema = exports.dnsPolicyOutputSchema = exports.listLagsOutputSchema = exports.lagOutputSchema = exports.listMcLagDomainsOutputSchema = exports.mcLagDomainOutputSchema = exports.listSwitchStacksOutputSchema = exports.switchStackOutputSchema = exports.aclRuleOrderingOutputSchema = exports.listAclRulesOutputSchema = exports.aclRuleOutputSchema = exports.firewallPolicyOrderingOutputSchema = exports.listFirewallPoliciesOutputSchema = exports.firewallPolicyOutputSchema = exports.listFirewallZonesOutputSchema = exports.firewallZoneOutputSchema = exports.createVouchersOutputSchema = exports.listVouchersOutputSchema = exports.voucherOutputSchema = exports.getNetworkReferencesOutputSchema = exports.listNetworksOutputSchema = exports.networkOutputSchema = exports.listSitesOutputSchema = exports.getInfoOutputSchema = void 0;
+exports.looseOutput = looseOutput;
+exports.writeResult = writeResult;
 /**
- * Output schemas for high-value read tools (loose strategy: every non-key
- * field optional, every nested object uses .passthrough() to allow
+ * Output schemas for every read tool, and for write tools whose response
+ * echoes the resource (loose strategy: every non-key
+ * field optional, every nested object uses .loose() to allow
  * firmware/hardware-specific fields to flow through unchanged).
  *
- * Verified against UniFi Network API 10.6.106. Where the docs collapse
+ * Verified against UniFi Network API 11.0.83. Where the docs collapse
  * nested arrays/objects (e.g. interfaces.ports[], radios[]), the schema
- * uses passthrough records so the contract doesn't lock to fields we
- * haven't verified.
+ * uses loose records so the contract doesn't lock to fields we
+ * haven't verified. Tools register these raw shapes, and registerAllTools()
+ * publishes each as a loose object (src/tools/index.ts), so fields a schema
+ * does not list never fail client-side validation.
  */
 const zod_1 = require("zod");
+// configurable is live-verified (11.0.83) on system-defined zones, policies,
+// networks and RADIUS profiles; it is absent on user-defined resources.
 const Metadata = zod_1.z
-    .object({ origin: zod_1.z.string().optional() })
-    .passthrough();
+    .object({ origin: zod_1.z.string().optional(), configurable: zod_1.z.boolean().optional() })
+    .loose();
 const PaginationFields = {
     offset: zod_1.z.number().int().optional(),
     limit: zod_1.z.number().int().optional(),
@@ -43,7 +50,7 @@ const DeviceListItem = zod_1.z
     features: zod_1.z.array(zod_1.z.string()).optional(),
     interfaces: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 const DevicePort = zod_1.z
     .object({
     idx: zod_1.z.number(),
@@ -59,10 +66,10 @@ const DevicePort = zod_1.z
         enabled: zod_1.z.boolean().optional(),
         state: zod_1.z.string().optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceRadio = zod_1.z
     .object({
     wlanStandard: zod_1.z.string().optional(),
@@ -70,7 +77,7 @@ const DeviceRadio = zod_1.z
     channelWidthMHz: zod_1.z.number().optional(),
     channel: zod_1.z.number().optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceDetail = zod_1.z
     .object({
     ...DeviceCommon,
@@ -79,7 +86,7 @@ const DeviceDetail = zod_1.z
     configurationId: zod_1.z.string().optional(),
     uplink: zod_1.z
         .object({ deviceId: zod_1.z.string().optional() })
-        .passthrough()
+        .loose()
         .optional(),
     // Detail view: object keyed by capability (switching/accessPoint).
     features: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
@@ -88,10 +95,10 @@ const DeviceDetail = zod_1.z
         ports: zod_1.z.array(DevicePort).optional(),
         radios: zod_1.z.array(DeviceRadio).optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const DeviceStatistics = zod_1.z
     .object({
     uptimeSec: zod_1.z.number().optional(),
@@ -107,7 +114,7 @@ const DeviceStatistics = zod_1.z
         txRateBps: zod_1.z.number().optional(),
         rxRateBps: zod_1.z.number().optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
     interfaces: zod_1.z
         .object({
@@ -117,13 +124,13 @@ const DeviceStatistics = zod_1.z
             frequencyGHz: zod_1.z.number().optional(),
             txRetriesPct: zod_1.z.number().optional(),
         })
-            .passthrough())
+            .loose())
             .optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const Client = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -135,10 +142,10 @@ const Client = zod_1.z
     uplinkDeviceId: zod_1.z.string().optional(),
     access: zod_1.z
         .object({ type: zod_1.z.string().optional() })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const WifiBroadcast = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -157,20 +164,20 @@ const WifiBroadcast = zod_1.z
     broadcastingDeviceFilter: zod_1.z.unknown().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const ApplicationInfo = zod_1.z
     .object({
-    // Live-verified (10.6.106): only applicationVersion is returned.
+    // Live-verified (11.0.83): only applicationVersion is returned.
     applicationVersion: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const Site = zod_1.z
     .object({
     id: zod_1.z.string(),
     internalReference: zod_1.z.string().optional(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const Network = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -190,12 +197,12 @@ const Network = zod_1.z
     ipv6Configuration: zod_1.z.unknown().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const NetworkReferences = zod_1.z
     .object({
     referenceResources: zod_1.z.array(zod_1.z.unknown()).optional(),
 })
-    .passthrough();
+    .loose();
 const Voucher = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -212,7 +219,7 @@ const Voucher = zod_1.z
     authorizedGuestCount: zod_1.z.number().optional(),
     expired: zod_1.z.boolean().optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallZone = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -220,7 +227,7 @@ const FirewallZone = zod_1.z
     networkIds: zod_1.z.array(zod_1.z.string()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallPolicy = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -236,11 +243,13 @@ const FirewallPolicy = zod_1.z
     ipsecFilter: zod_1.z.unknown().optional(),
     schedule: zod_1.z.unknown().optional(),
     loggingEnabled: zod_1.z.boolean().optional(),
+    // New in 11.0.83; live-verified as a boolean on every policy.
+    reportFlowEnabled: zod_1.z.boolean().optional(),
     index: zod_1.z.number().optional(),
     description: zod_1.z.string().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const FirewallPolicyOrdering = zod_1.z
     .object({
     orderedFirewallPolicyIds: zod_1.z
@@ -248,10 +257,10 @@ const FirewallPolicyOrdering = zod_1.z
         beforeSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
         afterSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
 })
-    .passthrough();
+    .loose();
 const AclRule = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -259,8 +268,11 @@ const AclRule = zod_1.z
     name: zod_1.z.string().optional(),
     enabled: zod_1.z.boolean().optional(),
     action: zod_1.z.string().optional(),
-    description: zod_1.z.string().optional(),
-    protocolFilter: zod_1.z.array(zod_1.z.string()).optional(),
+    // The docs give null a meaning ("When null, the rule will be applied to
+    // all protocols") and ACL samples already carry explicit nulls, so both
+    // must accept null or a protocol-agnostic rule hard-fails with -32602.
+    description: zod_1.z.string().nullable().optional(),
+    protocolFilter: zod_1.z.array(zod_1.z.string()).nullable().optional(),
     sourceFilter: zod_1.z.unknown().optional(),
     destinationFilter: zod_1.z.unknown().optional(),
     enforcingDeviceFilter: zod_1.z.unknown().optional(),
@@ -269,12 +281,12 @@ const AclRule = zod_1.z
     index: zod_1.z.number().int().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const AclRuleOrdering = zod_1.z
     .object({
     orderedAclRuleIds: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 const SwitchStack = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -289,7 +301,7 @@ const SwitchStack = zod_1.z
     lags: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const McLagDomain = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -298,7 +310,7 @@ const McLagDomain = zod_1.z
     lags: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const Lag = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -309,11 +321,11 @@ const Lag = zod_1.z
         deviceId: zod_1.z.string().optional(),
         portIdxs: zod_1.z.array(zod_1.z.number()).optional(),
     })
-        .passthrough())
+        .loose())
         .optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const DnsPolicy = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -322,9 +334,22 @@ const DnsPolicy = zod_1.z
     domain: zod_1.z.string().optional(),
     ipv4Address: zod_1.z.string().optional(),
     ttlSeconds: zod_1.z.number().optional(),
+    // Type-specific fields from the 11.0.83 response samples (no live DNS
+    // policies to sample), so nullable to be safe.
+    ipv6Address: zod_1.z.string().nullable().optional(),
+    targetDomain: zod_1.z.string().nullable().optional(),
+    mailServerDomain: zod_1.z.string().nullable().optional(),
+    text: zod_1.z.string().nullable().optional(),
+    serverDomain: zod_1.z.string().nullable().optional(),
+    service: zod_1.z.string().nullable().optional(),
+    protocol: zod_1.z.string().nullable().optional(),
+    port: zod_1.z.number().nullable().optional(),
+    priority: zod_1.z.number().nullable().optional(),
+    weight: zod_1.z.number().nullable().optional(),
+    ipAddress: zod_1.z.string().nullable().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 const TrafficMatchingList = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -333,15 +358,15 @@ const TrafficMatchingList = zod_1.z
     items: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
-// Verified against the live Integration API (10.6.106). The WAN and
+    .loose();
+// Verified against the live Integration API (11.0.83). The WAN and
 // site-to-site-tunnel list rows are intentionally minimal in the API.
 const Wan = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const VpnServer = zod_1.z
     .object({
     id: zod_1.z.string(),
@@ -350,21 +375,21 @@ const VpnServer = zod_1.z
     enabled: zod_1.z.boolean().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 // No tunnels present in the verification environment — keep loose.
 const VpnTunnel = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const RadiusProfile = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
     metadata: Metadata.optional(),
 })
-    .passthrough();
+    .loose();
 // No tags present in the verification environment — documented shape.
 const DeviceTag = zod_1.z
     .object({
@@ -372,27 +397,27 @@ const DeviceTag = zod_1.z
     name: zod_1.z.string().optional(),
     deviceIds: zod_1.z.array(zod_1.z.string()).optional(),
 })
-    .passthrough();
+    .loose();
 // DPI category/application ids are NUMERIC (verified live).
 const DpiCategory = zod_1.z
     .object({
     id: zod_1.z.number(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const DpiApplication = zod_1.z
     .object({
     id: zod_1.z.number(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 // Countries key on `code` (ISO alpha-2), NOT `id` (verified live).
 const Country = zod_1.z
     .object({
     code: zod_1.z.string(),
     name: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 // No pending devices in the verification environment — keep loose.
 const PendingDevice = zod_1.z
     .object({
@@ -401,7 +426,31 @@ const PendingDevice = zod_1.z
     ipAddress: zod_1.z.string().optional(),
     firmwareVersion: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
+// A write tool returns either the API's echo of the resource or, with dryRun,
+// a preview of the request it would send. The SDK validates both against the
+// one outputSchema, so the resource's key fields relax to optional alongside
+// the preview fields; read tools keep their stricter schemas.
+const DryRunPreview = {
+    dryRun: zod_1.z.literal(true).optional(),
+    wouldExecute: zod_1.z
+        .object({ method: zod_1.z.string(), path: zod_1.z.string(), body: zod_1.z.unknown().optional() })
+        .loose()
+        .optional(),
+    confirmationRequired: zod_1.z.string().optional(),
+};
+/**
+ * The outputSchema to publish for a tool: always a loose object, whether the
+ * tool passed a raw shape or a Zod object (the SDK accepts both). Wrapping a
+ * Zod object in z.looseObject() would build a broken schema that makes
+ * tools/list throw for every tool.
+ */
+function looseOutput(schema) {
+    return schema instanceof zod_1.z.ZodObject ? schema.loose() : zod_1.z.looseObject(schema);
+}
+function writeResult(shape) {
+    return { ...zod_1.z.object(shape).partial().shape, ...DryRunPreview };
+}
 exports.getInfoOutputSchema = ApplicationInfo.shape;
 exports.listSitesOutputSchema = {
     ...PaginationFields,
@@ -532,7 +581,7 @@ exports.HistoryClient = zod_1.z
     is_wired: zod_1.z.boolean().optional(),
     status: zod_1.z.string().optional(),
 })
-    .passthrough();
+    .loose();
 exports.ClientSession = zod_1.z
     .object({
     _id: zod_1.z.string(),
@@ -545,15 +594,18 @@ exports.ClientSession = zod_1.z
     is_wired: zod_1.z.boolean().optional(),
     roaming_sessions: zod_1.z.array(zod_1.z.unknown()).optional(),
 })
-    .passthrough();
+    .loose();
 /** Envelope returned by the controller's stat/session endpoint. */
 exports.ClientSessionEnvelope = zod_1.z.object({
-    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).passthrough(),
+    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).loose(),
     data: zod_1.z.array(exports.ClientSession),
 });
 exports.listClientHistoryOutputSchema = {
     data: zod_1.z.array(exports.HistoryClient),
     count: zod_1.z.number(),
+    totalCount: zod_1.z.number(),
+    limit: zod_1.z.number(),
+    truncated: zod_1.z.boolean(),
     withinHours: zod_1.z.number(),
     coverage: zod_1.z.string(),
 };

package/dist/utils/params.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+/**
+ * An Integration API resource ID. IDs are interpolated into request paths, so
+ * only the plain ID charset is accepted — anything else could smuggle a query
+ * (`?force=true`), a fragment, or extra path segments into the request.
+ */
+export declare function resourceId(): z.ZodString;

package/dist/utils/params.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceId = resourceId;
+const zod_1 = require("zod");
+/**
+ * An Integration API resource ID. IDs are interpolated into request paths, so
+ * only the plain ID charset is accepted — anything else could smuggle a query
+ * (`?force=true`), a fragment, or extra path segments into the request.
+ */
+function resourceId() {
+    return zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "Use an ID returned by a list or get tool");
+}

package/dist/utils/responses.d.ts

@@ -7,6 +7,8 @@ export declare function formatSuccess(data: unknown, opts?: {
     }[];
     structuredContent?: Record<string, unknown>;
 };
+/** The message of a thrown value, which need not be an Error. */
+export declare function errorMessage(err: unknown): string;
 export declare function formatError(err: unknown): {
     content: {
         type: "text";

package/dist/utils/responses.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSuccess = formatSuccess;
+exports.errorMessage = errorMessage;
 exports.formatError = formatError;
 function formatSuccess(data, opts) {
     const result = {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(data) }],
     };
     if (opts?.structured &&
         data !== null &&
@@ -14,10 +15,35 @@ function formatSuccess(data, opts) {
     }
     return result;
 }
+/** The message of a thrown value, which need not be an Error. */
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function formatError(err) {
-    const message = err instanceof Error ? err.message : String(err);
+    let message = errorMessage(err);
+    // fetch reports every network failure as "fetch failed" and keeps the reason
+    // (ECONNREFUSED, ENOTFOUND, a certificate error) in cause.
+    const cause = err instanceof Error ? err.cause : undefined;
+    const code = cause instanceof Error && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+    if (code) {
+        message += ` (${code})`;
+        message += tlsHint(code);
+    }
     return {
         content: [{ type: "text", text: `Error: ${message}` }],
         isError: true,
     };
 }
+/**
+ * What to do about a certificate that did not verify. Pinning makes a
+ * console's own certificate trusted, but it does not lift the validity dates,
+ * so an expired certificate gets its own advice.
+ */
+function tlsHint(code) {
+    if (code === "CERT_HAS_EXPIRED" || code === "CERT_NOT_YET_VALID") {
+        return ". The console's TLS certificate is outside its validity dates; check the clocks on the console and this machine, and renew the certificate if it has expired (pinning it with UNIFI_NETWORK_CA_CERT does not override the dates)";
+    }
+    if (!/CERT|SELF_SIGNED|LEAF_SIGNATURE/.test(code))
+        return "";
+    return ". The console's TLS certificate did not verify. For a local console with a self-signed certificate, save the certificate and point UNIFI_NETWORK_CA_CERT at it; if it is already set, the console has a new certificate, so save it again. Against api.ui.com, something between you and Ubiquiti presented this certificate: do not work around it";
+}

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.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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`.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** Deep copy of `data` with every secret-named string value replaced by REDACTED. */
+export declare function redactSecrets<T>(data: T): T;
+/**
+ * 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.
+ */
+export declare function restoreRedacted(value: unknown, current: unknown, path?: string): unknown;
+export declare function containsRedacted(value: unknown): boolean;