@coffeerunhobby/mcp-ha-connect 2.4.6 → 2.4.8

package/dist/net/adapters/omada.js

@@ -1,9 +1,10 @@
 /**
  * Omada adapter for the vendor-neutral network model (src/net/model.ts).
  *
- * 2.4.5 covers networks (LAN networks / VLANs) and Wi-Fi (SSIDs). Rules, groups, switch
- * ports and mDNS arrive with 2.4.7 and 2.4.8; until then those calls fail with
- * NetError UNSUPPORTED.
+ * 2.4.5 covers networks (LAN networks / VLANs) and Wi-Fi (SSIDs); 2.4.7 rules (gateway
+ * ACLs, see omadaRules.ts) and listing groups; 2.4.8 switch ports (the networks a port
+ * carries), listing port profiles and the mDNS repeater (see omadaPorts.ts). Creating
+ * port profiles, groups and reservations is refused with NetError UNSUPPORTED.
  *
  * Omada specifics handled here:
  * - networks have no "guest" purpose and no isolation flag in the API (guest is per
@@ -22,6 +23,8 @@ import { inSubnet, ipToNumber } from '../../utils/ipv4.js';
 import { redactSecrets } from '../../utils/redact.js';
 import { NetError, } from '../model.js';
 import { MAX_NETWORK_NAME, MAX_WIFI_NAME, checkBands, checkDhcp, checkGateway, checkName, checkNetworkUnique, checkVlan } from '../validate.js';
+import { GROUP_TYPE, controllerPath, controllerRisk, draftAsAcl, draftRule, isOwnedGroup, newRuleKey, ownedGroupName, resolve, ruleKey, tagged, toRule, } from './omadaRules.js';
+import { MDNS_GATEWAY, TAGS, cutOff, describeNetworks, linkPorts, toMdns, toPortNetworks, toPortProfile } from './omadaPorts.js';
 const PSEUDO_WLAN_ID = 'gateway';
 /** Omada LAN network purpose: 0 = VLAN only (switches), 1 = interface (routed by the gateway). */
 const PURPOSE_VLAN = 0;
@@ -46,6 +49,36 @@ const SSID_FIELDS = [
     'name', 'band', 'guestNetEnable', 'security', 'oweEnable', 'broadcast', 'vlanEnable', 'vlanId', 'pskSetting', 'mloEnable', 'pmfMode',
     'enable11r', 'hidePwd', 'greEnable', 'vlanSetting', 'prohibitWifiShare',
 ];
+/** Lists a switch's entry under a network has (live, 6.3.0.45: always all six). */
+const AFFECTED_LISTS = ['nativePorts', 'untagPorts', 'tagPorts', 'nativeLags', 'untagLags', 'tagLags'];
+/** A switch's `affectedPorts` with every list in place, or undefined: then which of its ports carry the network can't be told. */
+function affectedPortsOf(device) {
+    const affected = device.switchInfo?.affectedPorts;
+    return affected && AFFECTED_LISTS.every((k) => Array.isArray(affected[k])) ? affected : undefined;
+}
+/**
+ * Which ports of one switch carry each network (a network that doesn't list the switch reaches
+ * none of them); undefined when a network lists the switch twice or without all its lists.
+ */
+function affectedOf(carrying, mac) {
+    const out = new Map();
+    for (const { id, devices } of carrying) {
+        const entries = devices.filter((d) => typeof d.mac === 'string' && normalizeMac(d.mac) === normalizeMac(mac));
+        if (entries.length > 1)
+            return undefined;
+        if (!entries.length) {
+            out.set(id, {});
+            continue;
+        }
+        const affected = affectedPortsOf(entries[0]);
+        if (!affected)
+            return undefined;
+        out.set(id, affected);
+    }
+    return out;
+}
+/** Port fields a port change depends on (link state and counters change all the time and are left out). */
+const PORT_FIELDS = ['port', 'name', 'profileId', 'profileOverrideEnable', 'lagPort'];
 const pick = (raw, fields) => Object.fromEntries(fields.filter((f) => raw[f] !== undefined).map((f) => [f, raw[f]]));
 export class OmadaNetworkController {
     client;
@@ -55,6 +88,14 @@ export class OmadaNetworkController {
     executors = new WeakMap();
     /** The controller's IPv4 addresses; 'unknown' when its host name can't be resolved (then every routed network is protected). */
     controllerAddresses = [];
+    /** This server's IPv4 addresses; 'unset' when not configured, 'unknown' when one can't be resolved. */
+    serverAddresses = 'unset';
+    /**
+     * The controller's and this server's addresses together: their networks are protected and rules
+     * must not cut them off the internet. 'unknown' when either can't be resolved (then every routed
+     * network is protected); this server's are left out while not configured.
+     */
+    hostAddresses = [];
     constructor(client, options = {}) {
         this.client = client;
         this.options = options;
@@ -65,35 +106,46 @@ export class OmadaNetworkController {
             vendor: 'omada',
             networks: { create: 'native', isolation: 'unsupported', ipv6: 'unsupported', guestPurpose: 'unsupported' },
             wifi: { create: 'native', bands: ['2.4', '5', '6'], security: ['open', 'wpa2', 'wpa3'], pmf: 'native', fastRoaming: 'native', bandSteering: 'unsupported' },
-            ports: { profiles: 'unsupported', assign: 'unsupported' },
-            rules: { between: 'unsupported', toInternet: 'unsupported', deviceMatch: 'unsupported', wifiMatch: 'unsupported', stateful: 'unsupported', schedule: 'unsupported' },
+            // Port profiles are listed and assigned; they are created in the controller web UI.
+            ports: { profiles: 'unsupported', assign: 'native' },
+            rules: { between: 'native', toInternet: 'native', deviceMatch: 'unsupported', wifiMatch: 'unsupported', stateful: 'native', schedule: 'unsupported' },
             groups: { address: 'unsupported', mac: 'unsupported' },
             reservations: 'native',
-            mdnsRepeater: 'unsupported',
+            mdnsRepeater: 'native',
         };
     }
     // ---- reads -----------------------------------------------------------------------
     async resolveController() {
         const host = this.options.controllerHost;
-        if (!host) {
-            this.controllerAddresses = [];
-            return;
-        }
-        try {
-            this.controllerAddresses = [ipToNumber(host)];
-            return;
-        }
-        catch {
-            // a host name
-        }
-        try {
-            const resolve = this.options.resolveHost ?? (async (name) => (await lookup(name, { all: true, family: 4 })).map((a) => a.address));
-            const addresses = await resolve(host);
-            this.controllerAddresses = addresses.length ? addresses.map(ipToNumber) : 'unknown';
-        }
-        catch {
-            this.controllerAddresses = 'unknown';
+        this.controllerAddresses = host ? await this.addressesOf([host]) : [];
+        const server = this.options.serverHosts ?? [];
+        this.serverAddresses = server.length ? await this.addressesOf(server) : 'unset';
+        const both = [this.controllerAddresses, this.serverAddresses === 'unset' ? [] : this.serverAddresses];
+        this.hostAddresses = both.some((a) => a === 'unknown') ? 'unknown' : both.flatMap((a) => a);
+    }
+    /** IPv4 addresses of hosts given by address or name; 'unknown' if any can't be resolved. */
+    async addressesOf(hosts) {
+        const all = [];
+        for (const host of hosts) {
+            try {
+                all.push(ipToNumber(host));
+                continue;
+            }
+            catch {
+                // a host name
+            }
+            try {
+                const resolve = this.options.resolveHost ?? (async (name) => (await lookup(name, { all: true, family: 4 })).map((a) => a.address));
+                const addresses = await resolve(host);
+                if (!addresses.length)
+                    return 'unknown';
+                all.push(...addresses.map(ipToNumber));
+            }
+            catch {
+                return 'unknown';
+            }
         }
+        return all;
     }
     async snapshot() {
         await this.resolveController();
@@ -112,10 +164,14 @@ export class OmadaNetworkController {
                 ssids.push({ wlanId: wlan.wlanId, ssidId: s.ssidId, detail: await this.client.networkConfig.getSsidDetail(wlan.wlanId, s.ssidId, siteId) });
             }
         }
-        const clients = (await this.client.listClients(siteId)).map((c) => this.toClient(c, networks));
+        const clients = (await this.client.listClients(siteId)).map((c) => this.toClient(c, networks, ssids));
         const alwaysProfileId = (await this.client.accessControl.listTimeRanges(siteId)).find((p) => p.name === ALWAYS_PROFILE_NAME)?.profileId;
         const macGroups = await this.client.listMacGroups(siteId);
-        return { siteId, networksRaw, networks, ssids, clients, macGroups, ...(alwaysProfileId ? { alwaysProfileId } : {}) };
+        const acls = (await this.client.networkConfig.listAcls('osg-acls', siteId)).sort((a, b) => Number(a.index ?? 0) - Number(b.index ?? 0));
+        const otherAcls = [...(await this.client.networkConfig.listAcls('osw-acls', siteId)), ...(await this.client.networkConfig.listAcls('eap-acls', siteId))];
+        const ipGroups = await this.client.networkConfig.listGroups(GROUP_TYPE.ip, siteId);
+        const ipPortGroups = await this.client.networkConfig.listGroups(GROUP_TYPE.ipPort, siteId);
+        return { siteId, networksRaw, networks, ssids, clients, macGroups, acls, otherAcls, ipGroups, ipPortGroups, ...(alwaysProfileId ? { alwaysProfileId } : {}) };
     }
     toNetwork(raw) {
         const dhcp = (raw.dhcpSettingsVO ?? {});
@@ -148,26 +204,37 @@ export class OmadaNetworkController {
             return true;
         if (typeof raw.gatewaySubnet !== 'string')
             return false;
-        // Fail closed: if the controller's address is unknown, any routed network could be its own.
-        if (this.controllerAddresses === 'unknown')
+        // Fail closed: if the controller's or this server's address is unknown, any routed network could be its own.
+        if (this.hostAddresses === 'unknown')
             return true;
         const subnet = raw.gatewaySubnet;
-        return this.controllerAddresses.some((address) => inSubnet(address, subnet));
+        return this.hostAddresses.some((address) => inSubnet(address, subnet));
     }
-    toClient(raw, networks) {
+    toClient(raw, networks, ssids) {
         // A device still waiting for DHCP reports no (or an empty) address.
         const ip = typeof raw.ip === 'string' && isIpv4(raw.ip) ? raw.ip : undefined;
+        const ssid = typeof raw.ssid === 'string' && raw.ssid ? raw.ssid : undefined;
         let network;
-        if (typeof raw.vid === 'number')
+        // Wireless clients report vid 0 (the field is for wired ones; no network has VLAN 0).
+        if (typeof raw.vid === 'number' && raw.wireless !== true)
             network = networks.find((n) => n.vlan === raw.vid);
         if (!network && ip)
             network = networks.find((n) => n.gateway && inSubnet(ipToNumber(ip), n.gateway));
+        if (!network && ssid) {
+            // No address yet: the network its Wi-Fi puts it on, when that is a single one.
+            const found = ssids.filter((s) => s.detail.name === ssid);
+            const ids = found.length === 1 ? this.ssidNetworkIds(found[0].detail, networks) : [];
+            if (ids.length === 1)
+                network = networks.find((n) => n.id === ids[0]);
+        }
+        const port = Number(raw.port);
         return {
             mac: formatMac(String(raw.mac)),
             ...(typeof raw.name === 'string' ? { name: raw.name } : {}),
             ...(ip ? { ip } : {}),
             ...(network ? { network: { id: network.id } } : {}),
-            ...(typeof raw.ssid === 'string' && raw.ssid ? { wifi: { name: raw.ssid } } : {}),
+            ...(ssid ? { wifi: { name: ssid } } : {}),
+            ...(raw.wireless !== true && typeof raw.switchMac === 'string' && Number.isInteger(port) && port > 0 ? { port: { device: { mac: formatMac(raw.switchMac) }, port } } : {}),
             online: raw.active !== false,
         };
     }
@@ -237,19 +304,294 @@ export class OmadaNetworkController {
             .map((r) => ({ mac: formatMac(r.mac), ip: String(r.ip), network: { id: r.netId }, ...(r.description ? { description: String(r.description) } : {}) }));
     }
     async listPortProfiles() {
-        throw notYet('switch port profiles', '2.4.8');
+        return (await this.client.networkConfig.listPortProfiles(this.options.siteId)).map(toPortProfile);
     }
-    async listPorts() {
-        throw notYet('switch ports', '2.4.8');
+    async listPorts(device) {
+        const snap = await this.snapshot();
+        const world = await this.portWorld(snap);
+        const switches = device ? [this.resolveSwitch(world, device)] : world.switches;
+        return switches.flatMap((sw) => sw.ports.map((p) => this.toPort(sw, p, snap)));
     }
     async listRules() {
-        throw notYet('rules', '2.4.7');
+        const snap = await this.snapshot();
+        const world = this.ruleWorld(snap);
+        return snap.acls.map((raw, i) => toRule(raw, i + 1, world));
     }
-    async listGroups() {
-        throw notYet('groups', '2.4.7');
+    async listGroups(kind) {
+        const snap = await this.snapshot();
+        const address = snap.ipGroups.map((g) => ({
+            id: String(g.groupId),
+            name: String(g.name),
+            kind: 'address',
+            entries: (g.ipList ?? []).map((e) => ({
+                value: Number(e.mask) === 32 ? e.ip : `${e.ip}/${e.mask}`,
+                ...(e.description ? { name: e.description } : {}),
+            })),
+        }));
+        const mac = snap.macGroups.map((g) => ({
+            id: g.groupId,
+            name: g.name,
+            kind: 'mac',
+            entries: (g.macAddressList ?? []).map((e) => ({ value: formatMac(e.macAddress), ...(e.name ? { name: e.name } : {}) })),
+        }));
+        return kind === 'address' ? address : kind === 'mac' ? mac : [...address, ...mac];
     }
     async getMdnsRepeater() {
-        throw notYet('the mDNS repeater', '2.4.8');
+        return toMdns(await this.client.networkConfig.listMdnsRules(this.options.siteId)).repeater;
+    }
+    // ---- switch ports and the mDNS repeater (mapping in omadaPorts.ts) ------------------------
+    async portWorld(snap) {
+        const adopted = await this.client.listDevices(snap.siteId);
+        const devices = adopted.filter((d) => d.type === 'switch');
+        if (!devices.length)
+            return { switches: [] };
+        let topology;
+        try {
+            topology = await this.client.networkConfig.getTopology(snap.siteId);
+        }
+        catch {
+            // Unknown topology: every port is protected (linkPorts undefined), listing still works.
+        }
+        const carrying = await this.carrying(snap.networks, snap.siteId);
+        const switches = [];
+        for (const d of devices) {
+            const mac = String(d.mac);
+            const detail = await this.client.networkConfig.getSwitch(mac, snap.siteId);
+            const ports = detail.portList ?? [];
+            let links = topology ? linkPorts(topology, mac, adopted.map((a) => String(a.mac))) : undefined;
+            // A link on a port the switch doesn't have: the topology is stale, so the real port is unknown.
+            if (links && [...links.keys()].some((n) => !ports.some((p) => Number(p.port) === n)))
+                links = undefined;
+            const affected = affectedOf(carrying, mac);
+            switches.push({ mac, name: String(d.name ?? mac), ports, ...(links ? { links } : {}), ...(affected ? { affected } : {}) });
+        }
+        return { switches };
+    }
+    /** For each network, the devices whose ports carry it. */
+    async carrying(networks, siteId) {
+        const out = [];
+        for (const n of networks)
+            out.push({ id: n.id, devices: await this.client.networkConfig.listNetworkPorts(n.id, n.vlan, siteId) });
+        return out;
+    }
+    /** A switch by name, or by MAC (as { mac } or as its id). */
+    resolveSwitch(world, device) {
+        if ('name' in device)
+            return resolve(world.switches.map((s) => ({ ...s, id: s.mac })), device, 'switch');
+        const wanted = 'mac' in device ? device.mac : device.id;
+        const found = normalizeMac(wanted) === '' ? undefined : world.switches.find((s) => normalizeMac(s.mac) === normalizeMac(wanted));
+        if (!found)
+            throw new NetError('NOT_FOUND', `No switch with MAC '${wanted}'. Switches: ${world.switches.map((s) => `${s.name} (${s.mac})`).join(', ') || '(none)'}`);
+        return found;
+    }
+    /**
+     * Why a port can't be reassigned, or undefined. Never: an uplink, the port the controller
+     * or this server is on (allowLockout doesn't change that). When where they are can't be
+     * told (address unknown or not configured, or inside the site but not seen on it), ports
+     * with online devices are left alone; empty ports can still be assigned.
+     */
+    portProtection(sw, raw, seen, clients, networks) {
+        if (!sw.links)
+            return `the controller's topology doesn't show which port links switch '${sw.name}' to the network`;
+        const link = sw.links.get(Number(raw.port));
+        if (link)
+            return link;
+        if (raw.lagPort === true)
+            return 'it is part of a link aggregation (LAG); change it in the controller web UI';
+        const hosts = [
+            { who: 'the controller', addresses: this.controllerAddresses },
+            { who: 'this server', addresses: this.serverAddresses },
+        ];
+        const on = (c, addresses) => c.ip !== undefined && addresses.includes(ipToNumber(c.ip));
+        for (const { who, addresses } of hosts) {
+            if (Array.isArray(addresses) && seen.some((c) => on(c, addresses)))
+                return `${who} is on it`;
+        }
+        if (seen.length === 0)
+            return undefined;
+        for (const { who, addresses } of hosts) {
+            if (addresses === 'unset')
+                return `${who}'s address isn't configured (MCP_SERVER_ADDRESSES), so its port can't be told; ports with devices on them are left alone`;
+            if (addresses === 'unknown')
+                return `${who}'s address can't be resolved, so its port can't be told; ports with devices on them are left alone`;
+            const inSite = (a) => networks.some((n) => n.gateway && inSubnet(a, n.gateway));
+            // Located only when seen on a switch port: on Wi-Fi or straight on the gateway, what it hangs off can't be told.
+            if (addresses.some((a) => inSite(a) && !clients.some((c) => c.port !== undefined && on(c, [a])))) {
+                return `${who} isn't seen on a switch port, so its port can't be told; ports with devices on them are left alone`;
+            }
+        }
+        return undefined;
+    }
+    toPort(sw, raw, snap) {
+        const port = Number(raw.port);
+        const seen = snap.clients.filter((c) => c.online && c.port && 'mac' in c.port.device && normalizeMac(c.port.device.mac) === normalizeMac(sw.mac) && c.port.port === port);
+        const protection = this.portProtection(sw, raw, seen, snap.clients, snap.networks);
+        const networks = sw.affected ? toPortNetworks(sw.affected, port) : undefined;
+        return {
+            device: { mac: formatMac(sw.mac) },
+            port,
+            ...(typeof raw.name === 'string' ? { name: raw.name } : {}),
+            ...(typeof raw.profileId === 'string' ? { profile: { id: raw.profileId } } : {}),
+            ...(networks ? { networks } : {}),
+            customSettings: raw.profileOverrideEnable === true,
+            seen,
+            uplink: sw.links?.has(port) === true,
+            ...(protection ? { protected: protection } : {}),
+        };
+    }
+    /**
+     * Gives a port its own networks (untagged + tagged); its other settings keep following its
+     * profile. What it carries before and after comes from each network's list of ports.
+     */
+    async buildPortAssign(target, wanted, snap) {
+        const world = await this.portWorld(snap);
+        const sw = this.resolveSwitch(world, target.device);
+        const raw = sw.ports.find((p) => Number(p.port) === target.port);
+        if (!raw)
+            throw new NetError('NOT_FOUND', `Switch '${sw.name}' has no port ${target.port} (ports ${sw.ports.map((p) => p.port).join(', ')})`);
+        const where = `port ${target.port} on '${sw.name}'`;
+        const port = this.toPort(sw, raw, snap);
+        if (port.protected)
+            throw new NetError('PROTECTED', `${where} can't be reassigned here: ${port.protected}`);
+        if (port.customSettings) {
+            throw new NetError('UNSUPPORTED', `${where} has its own settings (profile override); change its networks in the controller web UI`, { capability: 'ports.assign' });
+        }
+        if (wanted.untagged?.length)
+            throw new NetError('UNSUPPORTED', 'Further untagged networks besides the native one are not offered here', { capability: 'ports.assign' });
+        if (!wanted.native)
+            throw new NetError('INVALID', `${where} needs an untagged (native) network`);
+        const native = resolve(snap.networks, wanted.native, 'network');
+        const tagged = Array.isArray(wanted.tagged) ? [...new Set(wanted.tagged.map((r) => resolve(snap.networks, r, 'network')))] : wanted.tagged;
+        if (Array.isArray(tagged) && tagged.includes(native))
+            throw new NetError('INVALID', `'${native.name}' can't be both untagged and tagged on a port`);
+        const goal = { native: { id: native.id }, tagged: Array.isArray(tagged) ? (tagged.length ? tagged.map((n) => ({ id: n.id })) : 'none') : tagged };
+        // What it carries now, as each network lists it ("all tagged" is every network but the native one).
+        const flat = (c) => {
+            const nativeId = c.native && 'id' in c.native ? c.native.id : undefined;
+            const list = (refs) => refs.map((r) => ('id' in r ? r.id : r.name)).sort();
+            const taggedIds = c.tagged === 'all' ? snap.networks.map((n) => n.id).filter((id) => id !== nativeId) : c.tagged === 'none' ? [] : c.tagged.map((r) => ('id' in r ? r.id : r.name));
+            return JSON.stringify([nativeId, list(c.untagged ?? []), [...taggedIds].sort()]);
+        };
+        if (port.networks && flat(port.networks) === flat(goal))
+            throw new NetError('INVALID', `${where} already carries that (${describeNetworks(goal, snap.networks)})`);
+        const affected = cutOff(port.seen, port.networks, goal);
+        const body = {
+            // Both required by the controller; unchanged.
+            name: raw.name,
+            profileId: raw.profileId,
+            profileOverrideEnable: false,
+            profileVlanOverrideEnable: true,
+            nativeNetworkId: native.id,
+            networkTagsSetting: goal.tagged === 'all' ? TAGS.all : goal.tagged === 'none' ? TAGS.none : TAGS.custom,
+            tagNetworkIds: Array.isArray(goal.tagged) ? goal.tagged.map((r) => ('id' in r ? r.id : r.name)) : [],
+            untagNetworkIds: [],
+        };
+        const now = port.networks ? describeNetworks(port.networks, snap.networks) : 'unknown';
+        return {
+            steps: [{ action: 'update', object: 'omada.switchPort', name: `${sw.name} port ${target.port}`, detail: `${now} → ${describeNetworks(goal, snap.networks)}` }],
+            effects: [
+                `${where} carries ${describeNetworks(goal, snap.networks)}; its other settings keep following profile '${String(raw.profileName ?? raw.profileId ?? 'unknown')}'.`,
+                ...(affected.length ? [`Devices on it lose their network: ${affected.map((c) => c.name ?? c.mac).join(', ')}.`] : []),
+            ],
+            wouldLockOut: affected,
+            reads: { networks: true },
+            // Known here: a switch without known links has every port protected (refused above).
+            // In a fixed order: the same state listed differently by the controller is no change.
+            extra: {
+                switch: sw.mac,
+                ports: sw.ports.map((p) => pick(p, PORT_FIELDS)).sort((a, b) => Number(a.port) - Number(b.port)),
+                links: [...sw.links].sort((a, b) => a[0] - b[0]),
+                // In the order of the networks, which the fingerprint already covers as listed.
+                carried: sw.affected ? [...sw.affected].map(([id, a]) => [id, canonical(a)]) : null,
+            },
+            execute: async (s) => {
+                await this.client.networkConfig.updateSwitchPort(sw.mac, target.port, body, s.siteId);
+                let after;
+                try {
+                    after = affectedOf(await this.carrying(s.networks, s.siteId), sw.mac);
+                }
+                catch {
+                    return { applied: true, owned: [], warnings: ['The port is changed, but reading it back failed; check it with net_listPorts.'] };
+                }
+                const carried = after ? toPortNetworks(after, target.port) : undefined;
+                if (!carried || flat(carried) !== flat(goal)) {
+                    const shown = carried ? describeNetworks(carried, s.networks) : 'something that can\'t be told';
+                    throw new NetError('CONFLICT', `The controller accepted the change, but ${where} carries ${shown}; check it with net_listPorts.`);
+                }
+                return { applied: true, object: this.toPort({ ...sw, affected: after }, raw, s), owned: [] };
+            },
+        };
+    }
+    async buildMdnsSet(enabled, refs, snap) {
+        const rulesRaw = await this.client.networkConfig.listMdnsRules(snap.siteId);
+        const { repeater, rule, networkIds: currentIds } = toMdns(rulesRaw);
+        if (repeater.foreign)
+            throw new NetError('UNSUPPORTED', repeater.foreign.reason, { capability: 'mdnsRepeater' });
+        if (!rule) {
+            throw new NetError('UNSUPPORTED', 'There is no mDNS rule yet: create one in the controller web UI (Settings > Services > mDNS, type Gateway, with the services to repeat); after that it can be changed here.', {
+                capability: 'mdnsRepeater',
+            });
+        }
+        // The networks given, or the ones the rule keeps: each must exist and be routed.
+        const chosen = refs
+            ? [...new Set(refs.map((r) => resolve(snap.networks, r, 'network')))]
+            : currentIds.map((id) => {
+                const found = snap.networks.find((n) => n.id === id);
+                if (!found)
+                    throw new NetError('INVALID', `The mDNS rule repeats over a network that no longer exists (${id}); give the networks to repeat between`);
+                return found;
+            });
+        const ids = chosen.map((n) => {
+            if (n.purpose !== 'normal')
+                throw new NetError('INVALID', `'${n.name}' is switch-only; the gateway repeats mDNS only between routed networks`);
+            return n.id;
+        });
+        if (enabled && ids.length < 2)
+            throw new NetError('INVALID', 'The mDNS repeater needs at least two networks to repeat between');
+        const same = ids.length === currentIds.length && ids.every((id) => currentIds.includes(id));
+        if (same && enabled === repeater.enabled)
+            throw new NetError('INVALID', 'Nothing to change on the mDNS repeater');
+        const name = (id) => snap.networks.find((n) => n.id === id)?.name ?? id;
+        const changes = [
+            ...(enabled !== repeater.enabled ? [enabled ? 'switched on' : 'switched off'] : []),
+            ...(same ? [] : [`networks ${currentIds.map(name).join(', ') || '(none)'} → ${ids.map(name).join(', ')}`]),
+        ];
+        const body = {
+            name: rule.name,
+            status: enabled,
+            // The services the rule repeats are kept as they are (the controller requires them).
+            profileIds: rule.profileIds,
+            type: MDNS_GATEWAY,
+            osg: { serviceNetworks: ids, clientNetworks: ids },
+        };
+        return {
+            steps: [{ action: 'update', object: 'omada.mdnsRule', name: String(rule.name), detail: changes.join('; ') }],
+            effects: [
+                enabled
+                    ? `mDNS (Bonjour) announcements are repeated between ${ids.map(name).join(', ')}: devices there discover each other's services (AirPlay, Chromecast, HomeKit, printers). Discovery only: traffic still follows the rules. The services the rule repeats stay as set in the controller.`
+                    : 'mDNS announcements are no longer repeated between networks; devices only discover services on their own network.',
+            ],
+            wouldLockOut: [],
+            reads: { networks: true },
+            extra: { mdns: rulesRaw.map(canonical) },
+            execute: async (s) => {
+                await this.client.networkConfig.updateMdnsRule(String(rule.id), body, s.siteId);
+                let after;
+                try {
+                    after = toMdns(await this.client.networkConfig.listMdnsRules(s.siteId));
+                }
+                catch {
+                    return { applied: true, owned: [], warnings: ['The mDNS repeater is changed, but reading it back failed; check it with net_getMdnsRepeater.'] };
+                }
+                const stored = after.networkIds;
+                const services = (r) => [...new Set((r?.profileIds ?? []).map(String))].sort().join(',');
+                const sameRule = after.rule?.id === rule.id && after.rule?.name === rule.name && services(after.rule) === services(rule);
+                if (after.repeater.foreign || !sameRule || after.repeater.enabled !== enabled || stored.length !== ids.length || !ids.every((id) => stored.includes(id))) {
+                    throw new NetError('CONFLICT', 'The controller accepted the mDNS change but shows something else now; check it with net_getMdnsRepeater.');
+                }
+                return { applied: true, object: after.repeater, owned: [] };
+            },
+        };
     }
     // ---- plan / apply ------------------------------------------------------------------
     async plan(change) {
@@ -277,13 +619,16 @@ export class OmadaNetworkController {
     }
     async planWith(change, snap) {
         const built = await this.build(change, snap);
+        const redacted = redactSecrets(change);
         const plan = {
-            change: redactSecrets(change),
+            change: redacted,
             vendor: 'omada',
             steps: built.steps,
             effects: built.effects,
             wouldLockOut: built.wouldLockOut,
-            basis: fingerprint(snap, built.reads),
+            // What was agreed to: this change (a basis can't vouch for another one) and the devices it
+            // cuts off (a different set at apply time is a CONFLICT, allowLockout or not).
+            basis: fingerprint(snap, built.reads, { change: redacted, extra: built.extra, lockOut: built.wouldLockOut.map((c) => normalizeMac(c.mac)).sort() }),
         };
         this.executors.set(plan, built.execute);
         return plan;
@@ -306,18 +651,424 @@ export class OmadaNetworkController {
                 if (change.op === 'delete')
                     return this.buildWifiDelete(change.ref, snap);
                 break;
+            case 'port':
+                return await this.buildPortAssign(change.port, change.networks, snap);
+            case 'portProfile':
+                throw unsupported('creating or deleting port profiles here (do it in the controller web UI)', 'ports.profiles');
+            case 'mdnsRepeater':
+                return await this.buildMdnsSet(change.enabled, change.networks, snap);
+            case 'rule':
+                if (change.op === 'create')
+                    return this.buildRuleCreate(change.value, snap);
+                if (change.op === 'update')
+                    return this.buildRuleUpdate(change.value.ref, change.value.set, snap);
+                if (change.op === 'delete')
+                    return this.buildRuleDelete(change.ref, snap);
+                if (change.op === 'move')
+                    return this.buildRuleMove(change.ref, change.position, snap);
+                break;
             default:
-                throw notYet(`${change.kind} changes`, change.kind === 'rule' || change.kind === 'group' ? '2.4.7' : change.kind === 'reservation' ? 'a later release (use omada_setDhcpReservation)' : '2.4.8');
+                throw notYet(`${change.kind} changes`, change.kind === 'group' ? 'a later release (use omada_createGroup / omada_deleteGroup)' : 'a later release (use omada_setDhcpReservation)');
         }
         throw new NetError('INVALID', 'This change is not supported');
     }
+    // ---- rules (gateway ACLs; mapping and checks in omadaRules.ts) ---------------------------
+    ruleWorld(snap) {
+        return {
+            networks: snap.networks,
+            acls: snap.acls,
+            ipGroups: snap.ipGroups,
+            ipPortGroups: snap.ipPortGroups,
+            ssids: snap.ssids.map((s) => ({ id: s.ssidId, name: String(s.detail.name) })),
+            // This server's addresses too: a rule must not cut it off the internet either.
+            controllerAddresses: this.hostAddresses,
+        };
+    }
+    /** The rule as the model sees it, with its raw ACL; a rule the model can't express is refused. */
+    editableRule(ref, snap, what) {
+        const world = this.ruleWorld(snap);
+        const rules = snap.acls.map((raw, i) => ({ raw, rule: toRule(raw, i + 1, world) }));
+        const found = resolve(rules.map((r) => ({ ...r, id: r.rule.id, name: r.rule.name })), ref, 'rule');
+        if (found.rule.foreign)
+            throw new NetError('UNSUPPORTED', `Rule '${found.rule.name}' can't be ${what} through net_: ${found.rule.foreign.reason} Use the omada_ gateway ACL tools for it.`, { capability: 'rules' });
+        return { raw: found.raw, rule: found.rule };
+    }
+    checkPosition(position, count) {
+        if (!Number.isInteger(position) || position < 1 || position > count)
+            throw new NetError('INVALID', `Position must be 1 to ${count}`);
+        return position;
+    }
+    /**
+     * Refuses a change if any rule list it passes through (the end state, and the staged
+     * one where the rule is switched off) could expose some of the controller's (and this
+     * server's) internet traffic to a block that doesn't reach it today (controllerRisk).
+     * Waived only when the controller is certainly cut off already.
+     */
+    guardController(snap, states) {
+        const today = controllerPath(snap.acls, this.ruleWorld(snap));
+        for (const state of states) {
+            const risk = controllerRisk(today, controllerPath(state.acls, state.world));
+            if (risk)
+                throw new NetError('PROTECTED', `This could cut the controller or this server off the internet: ${risk}. Nothing was changed.`);
+        }
+    }
+    buildRuleCreate(value, snap) {
+        const world = this.ruleWorld(snap);
+        const draft = draftRule(value, world);
+        const position = value.position === undefined ? undefined : this.checkPosition(value.position, snap.acls.length + 1);
+        const moves = position !== undefined && position <= snap.acls.length;
+        const steps = [
+            ...groupSteps(draft),
+            { action: 'create', object: 'omada.gatewayAcl', name: draft.name, detail: draft.direction === 'lanToLan' ? 'LAN to LAN' : 'LAN to internet' },
+            ...(moves ? [{ action: 'update', object: 'omada.gatewayAclOrder', name: draft.name, detail: `position ${position}` }] : []),
+            ...(moves && draft.enabled ? [{ action: 'update', object: 'omada.gatewayAcl', name: draft.name, detail: 'switched on once in place' }] : []),
+        ];
+        const at = position ?? snap.acls.length + 1;
+        const placed = draftAsAcl(draft, 'new-rule', world);
+        this.guardController(snap, [{ acls: placeAt(snap.acls, placed.acl, at), world: placed.world }]);
+        return {
+            steps,
+            effects: [...draft.effects, `It is rule ${at} of ${snap.acls.length + 1}; rules are checked in order and the first match decides.`],
+            wouldLockOut: [],
+            reads: { networks: true, ssids: true, rules: true },
+            execute: async (s) => {
+                // Every new rule carries a fresh tag: its description is unique, so the rule is found
+                // again (and undone) by it, never mistaken for one made elsewhere at the same moment.
+                const key = newRuleKey();
+                const description = tagged(draft.name, key);
+                const made = [];
+                // 'none': nothing sent; 'sent': the create was sent and may have happened.
+                let acl = 'none';
+                let aclId;
+                try {
+                    const source = await this.materialize(draft.source, key, 'from', s.siteId, made);
+                    const destination = await this.materialize(draft.destination, key, 'to', s.siteId, made);
+                    // A rule that still has to move is created switched off, so it never acts from the wrong place.
+                    const body = aclBody(draft, description, source, destination, false);
+                    acl = 'sent';
+                    await this.client.networkConfig.createGatewayAcl({ ...body, status: moves ? false : draft.enabled }, s.siteId);
+                    const acls = await this.sortedAcls(s.siteId);
+                    aclId = acls.find((a) => a.description === description)?.id;
+                    if (!aclId)
+                        throw new NetError('CONFLICT', `Created rule '${draft.name}' but could not find it again`);
+                    if (moves) {
+                        await this.reorder(acls, aclId, position, s.siteId);
+                        if (draft.enabled)
+                            await this.client.networkConfig.updateGatewayAcl(aclId, body, s.siteId);
+                    }
+                }
+                catch (error) {
+                    throw await this.undoCreate(error, acl, description, made, s.siteId);
+                }
+                return await this.done(aclId, await this.sweepOwnedGroups(s.siteId), [
+                    ...made.map((g) => ({ object: g.type === GROUP_TYPE.ip ? 'omada.ipGroup' : 'omada.ipPortGroup', id: g.id ?? g.name })),
+                    { object: 'omada.gatewayAcl', id: aclId },
+                ]);
+            },
+        };
+    }
+    buildRuleUpdate(ref, set, snap) {
+        const current = this.editableRule(ref, snap, 'changed');
+        const world = this.ruleWorld(snap);
+        const { position, ...fields } = set;
+        const next = { ...current.rule, ...fields };
+        const draft = draftRule(next, world, current);
+        const target = position === undefined ? undefined : this.checkPosition(position, snap.acls.length);
+        const moves = target !== undefined && target !== current.rule.position;
+        const changes = describeRuleChanges(current.rule, next);
+        if (changes.length === 0 && !moves)
+            throw new NetError('INVALID', `Nothing to change on rule '${current.rule.name}'`);
+        const oldKey = ruleKey(String(current.raw.description));
+        // Changed and moved: written switched off, moved, then switched on, so the new content never acts from the old place.
+        const staged = moves && changes.length > 0 && draft.enabled;
+        {
+            const id = String(current.raw.id);
+            const others = snap.acls.filter((a) => String(a.id) !== id);
+            const after = draftAsAcl(draft, id, world);
+            const states = [{ acls: placeAt(others, after.acl, target ?? current.rule.position), world: after.world }];
+            // Switched off on the way (staging, and the first step of undoing it): as if the rule were gone.
+            if (staged)
+                states.push({ acls: others, world });
+            this.guardController(snap, states);
+        }
+        const steps = [
+            ...groupSteps(draft),
+            ...(changes.length ? [{ action: 'update', object: 'omada.gatewayAcl', name: current.rule.name, detail: `${changes.join('; ')}${staged ? ' (switched off until in place)' : ''}` }] : []),
+            ...(moves ? [{ action: 'update', object: 'omada.gatewayAclOrder', name: current.rule.name, detail: `position ${target}` }] : []),
+            ...(staged ? [{ action: 'update', object: 'omada.gatewayAcl', name: current.rule.name, detail: 'switched on in place' }] : []),
+        ];
+        return {
+            steps,
+            effects: [
+                ...(changes.length ? [`'${current.rule.name}': ${changes.join('; ')}.`, ...draft.effects] : []),
+                ...(moves ? [`It moves from position ${current.rule.position} to ${target} of ${snap.acls.length}.`] : []),
+            ],
+            wouldLockOut: [],
+            reads: { networks: true, ssids: true, rules: true },
+            execute: async (s) => {
+                const aclId = String(current.raw.id);
+                const original = writableAcl(current.raw);
+                const originalOrder = orderOf(s.acls);
+                const made = [];
+                // 'sent' = the write was sent and may have happened, even if it reported an error.
+                let put = 'none';
+                let reorder = 'none';
+                try {
+                    if (changes.length) {
+                        const key = oldKey ?? (needsGroups(draft) ? newRuleKey() : undefined);
+                        const source = await this.materialize(draft.source, key, 'from', s.siteId, made);
+                        const destination = await this.materialize(draft.destination, key, 'to', s.siteId, made);
+                        const body = aclBody(draft, tagged(draft.name, key), source, destination, current.raw.syslog === true);
+                        put = 'sent';
+                        await this.client.networkConfig.updateGatewayAcl(aclId, staged ? { ...body, status: false } : body, s.siteId);
+                        if (moves) {
+                            reorder = 'sent';
+                            await this.reorder(await this.sortedAcls(s.siteId), aclId, target, s.siteId);
+                        }
+                        if (staged)
+                            await this.client.networkConfig.updateGatewayAcl(aclId, body, s.siteId);
+                    }
+                    else if (moves) {
+                        reorder = 'sent';
+                        await this.reorder(await this.sortedAcls(s.siteId), aclId, target, s.siteId);
+                    }
+                }
+                catch (error) {
+                    throw await this.undoUpdate(error, { aclId, original, originalOrder, put, reorder, made }, s.siteId);
+                }
+                // Only now, with everything in place: groups no rule uses any more.
+                return await this.done(aclId, await this.sweepOwnedGroups(s.siteId));
+            },
+        };
+    }
+    buildRuleDelete(ref, snap) {
+        const current = this.editableRule(ref, snap, 'deleted');
+        const ids = referencedIds(current.raw);
+        const otherUses = new Set([...snap.acls.filter((a) => a.id !== current.raw.id), ...snap.otherAcls].flatMap(referencedIds));
+        const released = [...snap.ipGroups, ...snap.ipPortGroups].filter((g) => isOwnedGroup(g) && ids.includes(String(g.groupId)) && !otherUses.has(String(g.groupId)));
+        this.guardController(snap, [{ acls: snap.acls.filter((a) => a.id !== current.raw.id), world: this.ruleWorld(snap) }]);
+        return {
+            steps: [
+                { action: 'delete', object: 'omada.gatewayAcl', name: current.rule.name },
+                ...released.map((g) => ({ action: 'delete', object: g.type === GROUP_TYPE.ipPort ? 'omada.ipPortGroup' : 'omada.ipGroup', name: String(g.name) })),
+            ],
+            effects: [`Rule '${current.rule.name}' is removed${released.length ? ', with the address group it owns' : ''}.`],
+            wouldLockOut: [],
+            reads: { networks: true, ssids: true, rules: true },
+            execute: async (s) => {
+                const warnings = [];
+                try {
+                    await this.client.networkConfig.deleteGatewayAcl(String(current.raw.id), s.siteId);
+                }
+                catch (error) {
+                    // The delete may have happened even though it reported an error: look.
+                    let gone;
+                    try {
+                        gone = !(await this.sortedAcls(s.siteId)).some((a) => String(a.id) === String(current.raw.id));
+                    }
+                    catch {
+                        throw withNote(error, `whether rule '${current.rule.name}' was deleted is unknown; check net_listRules`);
+                    }
+                    if (!gone)
+                        throw error;
+                    warnings.push("The controller's answer was lost, but the rule is gone.");
+                }
+                return await this.done(undefined, [...warnings, ...(await this.sweepOwnedGroups(s.siteId))]);
+            },
+        };
+    }
+    buildRuleMove(ref, position, snap) {
+        const world = this.ruleWorld(snap);
+        const rules = snap.acls.map((raw, i) => ({ raw, rule: toRule(raw, i + 1, world) }));
+        // Moving touches only the order, so a rule the model can't otherwise express may move too.
+        const found = resolve(rules.map((r) => ({ ...r, id: r.rule.id, name: r.rule.name })), ref, 'rule');
+        const target = this.checkPosition(position, snap.acls.length);
+        if (target === found.rule.position)
+            throw new NetError('INVALID', `Rule '${found.rule.name}' is already at position ${target}`);
+        this.guardController(snap, [{ acls: placeAt(snap.acls.filter((a) => a.id !== found.raw.id), found.raw, target), world }]);
+        return {
+            steps: [{ action: 'update', object: 'omada.gatewayAclOrder', name: found.rule.name, detail: `position ${target}` }],
+            effects: [`'${found.rule.name}' moves from position ${found.rule.position} to ${target} of ${snap.acls.length}; rules are checked in order and the first match decides.`],
+            wouldLockOut: [],
+            reads: { networks: true, ssids: true, rules: true },
+            execute: async (s) => {
+                const originalOrder = orderOf(s.acls);
+                try {
+                    await this.reorder(await this.sortedAcls(s.siteId), String(found.raw.id), target, s.siteId);
+                }
+                catch (error) {
+                    // The reorder may have happened even though it reported an error: put the order back.
+                    throw await this.restoreOrder(error, originalOrder, s.siteId);
+                }
+                return await this.done(String(found.raw.id), await this.sweepOwnedGroups(s.siteId));
+            },
+        };
+    }
+    /**
+     * Existing ids for an endpoint, or the id of the group created for it. The group is
+     * tracked by its (unique) name before it is created, so a create whose answer or
+     * read-back got lost can still be found and undone.
+     */
+    async materialize(endpoint, key, side, siteId, made) {
+        if ('ids' in endpoint)
+            return { type: endpoint.type, ids: endpoint.ids };
+        if (!key)
+            throw new NetError('INVALID', 'Internal: a rule that owns a group needs a tag');
+        const { groupType, body } = endpoint.newGroup;
+        // A name no group has yet: finding it by name afterwards (or in an undo) can only find this one.
+        const existing = await this.client.networkConfig.listGroups(groupType, siteId);
+        const tracked = { type: groupType, name: ownedGroupName(key, side, new Set(existing.map((g) => String(g.name)))) };
+        made.push(tracked);
+        await this.client.networkConfig.createGroup({ name: tracked.name, ...body }, siteId);
+        const group = (await this.client.networkConfig.listGroups(groupType, siteId)).find((g) => g.name === tracked.name);
+        if (!group)
+            throw new NetError('CONFLICT', `Created group '${tracked.name}' but could not find it again`);
+        tracked.id = String(group.groupId);
+        return { type: endpoint.type, ids: [tracked.id] };
+    }
+    /**
+     * Undoes a create that failed part-way and returns the error to throw. A create that
+     * was sent may have happened even if it reported an error: the rule is looked up by
+     * its description and removed before its groups. When that can't be confirmed, the
+     * groups stay (a live rule must never point at deleted groups) and the error says so.
+     */
+    async undoCreate(error, acl, description, made, siteId) {
+        const notes = [];
+        if (acl === 'sent') {
+            try {
+                const found = (await this.sortedAcls(siteId)).find((a) => a.description === description);
+                if (found)
+                    await this.client.networkConfig.deleteGatewayAcl(String(found.id), siteId);
+            }
+            catch {
+                return withNote(error, `the rule may have been created; check net_listRules for '${description}' (its groups were kept)`);
+            }
+        }
+        notes.push(...(await this.dropGroups(made, siteId)));
+        return notes.length ? withNote(error, notes.join('; ')) : error;
+    }
+    /**
+     * Undoes an update that failed part-way and returns the error to throw: puts the rule
+     * back as it was (if the change may have been written) and removes the groups made
+     * for it, unless the rule might still point at them.
+     */
+    async undoUpdate(error, u, siteId) {
+        if (u.reorder === 'sent') {
+            try {
+                // Content changed too: switch it off first, so neither version acts from the wrong place while the order goes back.
+                if (u.put === 'sent')
+                    await this.client.networkConfig.updateGatewayAcl(u.aclId, { ...u.original, status: false }, siteId);
+                await this.client.networkConfig.reorderGatewayAcls(u.originalOrder, siteId);
+            }
+            catch {
+                return withNote(error, 'the rule order could not be put back; check it with net_listRules (the groups made for the change were kept)');
+            }
+        }
+        if (u.put === 'sent') {
+            try {
+                await this.client.networkConfig.updateGatewayAcl(u.aclId, u.original, siteId);
+            }
+            catch {
+                return withNote(error, 'the rule could not be put back as it was; check it with net_listRules (the groups made for the change were kept)');
+            }
+        }
+        const notes = await this.dropGroups(u.made, siteId);
+        return notes.length ? withNote(error, notes.join('; ')) : error;
+    }
+    /** Puts the rule order back after a move that failed (it may have happened anyway); returns the error to throw. */
+    async restoreOrder(error, originalOrder, siteId) {
+        try {
+            await this.client.networkConfig.reorderGatewayAcls(originalOrder, siteId);
+            return error;
+        }
+        catch {
+            return withNote(error, 'the rule order could not be put back; check it with net_listRules');
+        }
+    }
+    /** Deletes groups made during a failed change (found by name when the id is unknown); returns what it couldn't remove. */
+    async dropGroups(made, siteId) {
+        const left = [];
+        for (const g of made) {
+            try {
+                const id = g.id ?? (await this.client.networkConfig.listGroups(g.type, siteId)).find((x) => x.name === g.name)?.groupId;
+                if (id)
+                    await this.client.networkConfig.deleteGroup(g.type, String(id), siteId);
+            }
+            catch {
+                left.push(`group '${g.name}' may be left behind`);
+            }
+        }
+        return left;
+    }
+    /**
+     * Deletes every group a net_ rule owned that no ACL (gateway, switch or access point)
+     * references any more. Run after each successful rule change, so a cleanup that failed
+     * once is finished by the next change; a failure here is a warning, not an error (the
+     * change itself is done). Writes are serialized per site, so no rule is half-created
+     * meanwhile.
+     */
+    async sweepOwnedGroups(siteId) {
+        try {
+            const acls = [
+                ...(await this.client.networkConfig.listAcls('osg-acls', siteId)),
+                ...(await this.client.networkConfig.listAcls('osw-acls', siteId)),
+                ...(await this.client.networkConfig.listAcls('eap-acls', siteId)),
+            ];
+            const used = new Set(acls.flatMap(referencedIds));
+            const left = [];
+            for (const type of [GROUP_TYPE.ip, GROUP_TYPE.ipPort]) {
+                for (const g of await this.client.networkConfig.listGroups(type, siteId)) {
+                    const id = String(g.groupId);
+                    if (!isOwnedGroup(g) || used.has(id))
+                        continue;
+                    await this.client.networkConfig.deleteGroup(type, id, siteId).catch(() => left.push(String(g.name)));
+                }
+            }
+            return left.length ? [`Could not remove the unused group(s) ${left.join(', ')} now; the next rule change removes them.`] : [];
+        }
+        catch {
+            return ['Could not check for unused rule groups now; the next rule change removes them.'];
+        }
+    }
+    async sortedAcls(siteId) {
+        return (await this.client.networkConfig.listAcls('osg-acls', siteId)).sort((a, b) => Number(a.index ?? 0) - Number(b.index ?? 0));
+    }
+    /** Moves one rule to `position` (1 = first); the others keep their order. */
+    async reorder(acls, aclId, position, siteId) {
+        const moving = acls.find((a) => String(a.id) === aclId);
+        if (!moving)
+            throw new NetError('NOT_FOUND', 'The rule disappeared before it could be moved');
+        const order = acls.filter((a) => String(a.id) !== aclId);
+        order.splice(Math.min(position, acls.length) - 1, 0, moving);
+        await this.client.networkConfig.reorderGatewayAcls(Object.fromEntries(order.map((a, i) => [String(a.id), i + 1])), siteId);
+    }
+    /**
+     * The result of a change that is done: the rule as it reads back, plus warnings. A
+     * failed read-back is a warning, never an error: the change is already applied.
+     */
+    async done(aclId, warnings, owned = []) {
+        const notes = [...warnings];
+        let object;
+        if (aclId) {
+            try {
+                const snap = await this.snapshot();
+                const index = snap.acls.findIndex((a) => String(a.id) === aclId);
+                if (index >= 0)
+                    object = toRule(snap.acls[index], index + 1, this.ruleWorld(snap));
+            }
+            catch {
+                notes.push(`The change is applied, but reading the rule back failed; check it with net_listRules (rule id ${aclId}).`);
+            }
+        }
+        return { applied: true, ...(object ? { object } : {}), owned, ...(notes.length ? { warnings: notes } : {}) };
+    }
     // ---- networks ------------------------------------------------------------------------
     buildNetworkCreate(value, snap) {
         const name = checkName(value.name, MAX_NETWORK_NAME, 'Network');
         if (value.purpose === 'guest')
             throw unsupported('a guest network type (Omada makes a Wi-Fi network a guest network instead: clientIsolation)', 'networks.guestPurpose');
         if (value.isolated)
-            throw unsupported('network isolation (it comes as rules in 2.4.7)', 'networks.isolation');
+            throw unsupported('a network isolation flag (make a block rule from this network to the others with net_createRule)', 'networks.isolation');
         if (value.ipv6)
             throw unsupported('switching IPv6 on (do it in the controller web UI)', 'networks.ipv6');
         const vlan = checkVlan(value.vlan);
@@ -376,12 +1127,12 @@ export class OmadaNetworkController {
             throw new NetError('INVALID', `'${current.name}' is switch-only: it has no gateway and no DHCP to change`);
         }
         if (set.isolated)
-            throw unsupported('network isolation (it comes as rules in 2.4.7)', 'networks.isolation');
+            throw unsupported('a network isolation flag (make a block rule from this network to the others with net_createRule)', 'networks.isolation');
         if (set.ipv6 === true && !current.ipv6)
             throw unsupported('switching IPv6 on (do it in the controller web UI)', 'networks.ipv6');
         const addressing = (set.vlan !== undefined && set.vlan !== current.vlan) || (set.gateway !== undefined && set.gateway !== current.gateway);
         if (current.protected && addressing) {
-            throw new NetError('PROTECTED', `'${current.name}' carries the controller or the primary network; its VLAN and gateway can't be changed here`);
+            throw new NetError('PROTECTED', `'${current.name}' carries the controller, this server or the primary network; its VLAN and gateway can't be changed here`);
         }
         const name = set.name !== undefined ? checkName(set.name, MAX_NETWORK_NAME, 'Network') : current.name;
         const vlan = set.vlan !== undefined ? checkVlan(set.vlan) : current.vlan;
@@ -465,7 +1216,7 @@ export class OmadaNetworkController {
     async buildNetworkDelete(ref, snap) {
         const current = resolve(snap.networks, ref, 'network');
         if (current.protected)
-            throw new NetError('PROTECTED', `'${current.name}' carries the controller or the primary network and can't be deleted`);
+            throw new NetError('PROTECTED', `'${current.name}' carries the controller, this server or the primary network and can't be deleted`);
         const users = await this.networkUsers(current, snap);
         if (users.length)
             throw new NetError('IN_USE', `'${current.name}' is used by ${users.join(', ')}; change those first`, { users });
@@ -481,7 +1232,7 @@ export class OmadaNetworkController {
             },
         };
     }
-    /** Everything that still references a network: SSIDs, port profiles, DHCP reservations, ACL rules. */
+    /** Everything that still references a network: SSIDs, port profiles, switch ports carrying it untagged, DHCP reservations, ACL rules. */
     async networkUsers(network, snap) {
         const users = [];
         for (const s of snap.ssids)
@@ -492,6 +1243,24 @@ export class OmadaNetworkController {
             if (ids.includes(network.id))
                 users.push(`port profile '${String(p.name)}'`);
         }
+        // Devices on a port that carries it untagged would be left without a network; a switch whose
+        // lists can't be read may have such a port (other devices, like the gateway, have no switch ports).
+        for (const d of await this.client.networkConfig.listNetworkPorts(network.id, network.vlan, snap.siteId)) {
+            if (d.type !== 'switch' && d.switchInfo === undefined)
+                continue;
+            const name = `switch '${String(d.name ?? d.mac)}'`;
+            const a = affectedPortsOf(d);
+            if (!a) {
+                users.push(`${name} (which of its ports carry it can't be read)`);
+                continue;
+            }
+            const nums = (...keys) => [...new Set(keys.flatMap((k) => a[k].map(Number)))].sort((x, y) => x - y);
+            const ports = nums('nativePorts', 'untagPorts');
+            const lags = nums('nativeLags', 'untagLags');
+            const on = [...(ports.length ? [`ports ${ports.join(', ')}`] : []), ...(lags.length ? [`LAGs ${lags.join(', ')}`] : [])];
+            if (on.length)
+                users.push(`${name} ${on.join(' and ')} (untagged)`);
+        }
         for (const r of await this.client.accessControl.listDhcpReservations(snap.siteId))
             if (r.netId === network.id)
                 users.push(`DHCP reservation ${formatMac(r.mac)}`);
@@ -715,32 +1484,82 @@ export class OmadaNetworkController {
         };
     }
 }
-// ---- helpers -----------------------------------------------------------------------------
+/**
+ * Every id an ACL's source or destination references. Endpoint type numbers differ between
+ * gateway, switch and access point ACLs, so ids are not filtered by type: a network id
+ * never equals a group id, and over-counting only keeps a group longer.
+ */
+function referencedIds(acl) {
+    return [...(acl.sourceIds ?? []), ...(acl.destinationIds ?? [])].map(String);
+}
+/** A rule list with `acl` at `position` (1 = first). */
+function placeAt(acls, acl, position) {
+    const list = [...acls];
+    list.splice(Math.min(Math.max(position, 1), list.length + 1) - 1, 0, acl);
+    return list;
+}
+/** The current rule order as reorderGatewayAcls takes it. */
+function orderOf(acls) {
+    return Object.fromEntries(acls.map((a, i) => [String(a.id), i + 1]));
+}
+/** What a PUT must resend to put an ACL back exactly as it was. */
+function writableAcl(raw) {
+    const fields = ['description', 'status', 'policy', 'protocols', 'sourceType', 'sourceIds', 'destinationType', 'destinationIds', 'syslog', 'direction', 'stateMode', 'states', 'timeRangeId'];
+    return Object.fromEntries(fields.filter((f) => raw[f] !== undefined && raw[f] !== null).map((f) => [f, raw[f]]));
+}
+/** The original error, with what the undo couldn't do appended. */
+function withNote(error, note) {
+    if (error instanceof NetError)
+        return new NetError(error.code, `${error.message} (${note})`, error.details);
+    return new Error(`${error instanceof Error ? error.message : String(error)} (${note})`);
+}
+function needsGroups(draft) {
+    return 'newGroup' in draft.source || 'newGroup' in draft.destination;
+}
+function groupSteps(draft) {
+    return [draft.source, draft.destination]
+        .filter((e) => 'newGroup' in e)
+        .map((e) => ({ action: 'create', object: e.newGroup.groupType === GROUP_TYPE.ipPort ? 'omada.ipPortGroup' : 'omada.ipGroup', name: e.label }));
+}
+function aclBody(draft, description, source, destination, syslog) {
+    return {
+        description,
+        status: draft.enabled,
+        policy: draft.policy,
+        protocols: draft.protocols,
+        sourceType: source.type,
+        sourceIds: source.ids,
+        destinationType: destination.type,
+        destinationIds: destination.ids,
+        syslog,
+        direction: { lanToWan: draft.direction === 'lanToWan', lanToLan: draft.direction === 'lanToLan', wanInIds: [], vpnInIds: [] },
+        // 0 = "Auto": replies to connections started on the other side pass (see omadaRules.ts).
+        stateMode: 0,
+    };
+}
+function describeRuleChanges(current, next) {
+    const out = [];
+    const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    if (next.name !== current.name)
+        out.push(`name → ${next.name}`);
+    if (next.action !== current.action)
+        out.push(`action → ${next.action}`);
+    if (!same(next.from, current.from))
+        out.push('source changed');
+    if (!same(next.to, current.to))
+        out.push('destination changed');
+    if (!same(next.protocol, current.protocol))
+        out.push(`protocol → ${typeof next.protocol === 'object' ? `ports ${next.protocol.tcpUdpPorts}` : next.protocol}`);
+    if (next.enabled !== current.enabled)
+        out.push(next.enabled ? 'switched on' : 'switched off');
+    return out;
+}
 function notYet(what, release) {
     return new NetError('UNSUPPORTED', `Changing ${what} through the net_ tools arrives in ${release}`, { capability: what });
 }
 function unsupported(what, capability) {
     return new NetError('UNSUPPORTED', `Omada can't do ${what} through its API`, { capability });
 }
-function resolve(items, ref, what) {
-    if ('id' in ref) {
-        const byId = items.find((i) => i.id === ref.id);
-        if (byId)
-            return byId;
-        throw new NetError('NOT_FOUND', `No ${what} with id '${ref.id}'`);
-    }
-    // Tools pass what the user typed as { name }; an exact id match wins.
-    const byId = items.find((i) => i.id === ref.name);
-    if (byId)
-        return byId;
-    const wanted = ref.name.trim().toLowerCase();
-    const matches = items.filter((i) => i.name.toLowerCase() === wanted);
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length > 1)
-        throw new NetError('AMBIGUOUS', `Several ${what}s are named '${ref.name}'; use the id`);
-    throw new NetError('NOT_FOUND', `${what[0].toUpperCase()}${what.slice(1)} '${ref.name}' not found. Available: ${items.map((i) => i.name).join(', ') || '(none)'}`);
-}
 /** The network a Wi-Fi network may put its devices on: one with a gateway (and so an address for them). */
 function wifiNetwork(networks, ref) {
     const network = resolve(networks, ref, 'network');
@@ -846,6 +1665,26 @@ function describeNetworkChanges(current, next) {
         out.push('IPv6 → off');
     return out;
 }
+/**
+ * A controller record with its keys and every list sorted: the lists in port profiles and mDNS
+ * rules are sets (ids of networks, services...), so the same state listed in another order
+ * fingerprints the same.
+ */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map(canonical)
+            .map((item) => [JSON.stringify(item), item])
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([, item]) => item);
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonical(v)]));
+    }
+    return value;
+}
 function describeClients(clients) {
     return clients.map((c) => `${c.name ?? '?'} (${c.mac})`).join(', ');
 }
@@ -853,12 +1692,14 @@ function describeClients(clients) {
  * Fingerprint of what a plan read, secrets stripped (the Wi-Fi password is never hashed:
  * a hash of a short secret leaks it to anyone who can guess).
  */
-function fingerprint(snap, reads) {
+function fingerprint(snap, reads, extra) {
     const material = {
         networks: reads.networks ? snap.networksRaw : undefined,
         ssids: reads.ssids ? redactSecrets(snap.ssids) : undefined,
         // A MAC filter plan resolved a group by name: a renamed or replaced group must not slip through.
         macGroups: reads.macGroups ? snap.macGroups : undefined,
+        rules: reads.rules ? { acls: snap.acls, otherAcls: snap.otherAcls, ipGroups: snap.ipGroups, ipPortGroups: snap.ipPortGroups } : undefined,
+        extra,
     };
     return createHash('sha256').update(JSON.stringify(material)).digest('hex').slice(0, 16);
 }