@coffeerunhobby/mcp-ha-connect 1.3.4 → 1.5.0

package/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+# Advisory only. This workflow REPORTS a pass/fail status on commits and PRs.
+# It does NOT block commits, pushes, or merges. The code builds, publishes, and
+# deploys with zero dependency on this file — delete it and nothing breaks.
+# (Blocking only happens if you separately enable branch-protection in the
+#  GitHub web UI, which is off by default and intentionally not set here.)
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  # Lets you re-run it by hand from the Actions tab.
+  workflow_dispatch:
+
+# If you push twice quickly, cancel the older run instead of stacking them.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test-lint:
+    runs-on: ubuntu-latest
+
+    strategy:
+      # Don't kill the Node 22 run just because Node 20 failed (or vice-versa) —
+      # we want to see both results.
+      fail-fast: false
+      matrix:
+        # The two LTS lines we support (package.json engines: ">=20").
+        node-version: ['20.x', '22.x']
+
+    name: node ${{ matrix.node-version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      # npm ci installs exactly what's in package-lock.json (reproducible),
+      # the same command Docker uses. It never edits the lockfile.
+      - name: Install dependencies
+        run: npm ci
+
+      # 1. Compile cleanly (tsc -> dist/). Catches type errors.
+      - name: Build
+        run: npm run build
+
+      # 2. Lint src + tests. CLAUDE.md policy: zero errors AND zero warnings.
+      #    --max-warnings=0 makes a warning fail the job, matching that policy.
+      - name: Lint
+        run: npm run lint -- --max-warnings=0
+
+      # 3. Version-sync gate. Fails if package.json / src/version.ts / openapi.json
+      #    disagree on the version — the exact drift CLAUDE.md warns about.
+      - name: Version sync
+        run: npm run check:sync
+
+      # 4. Unit tests WITH coverage gate. test:coverage excludes tests/integration/**
+      #    (those need a live .env CI must never have) and enforces the regression
+      #    floor in vitest.config.ts — a coverage DROP fails the build.
+      - name: Test + coverage gate
+        run: npm run test:coverage

package/Dockerfile

@@ -3,7 +3,10 @@
 FROM node:25-alpine AS deps
 WORKDIR /app
 COPY package*.json ./
-RUN npm install
+# npm ci installs exactly from the committed package-lock.json (reproducible) and
+# fails if package.json and the lockfile have drifted. The `package*.json` COPY
+# above pulls in package-lock.json, so the lockfile is present in this stage.
+RUN npm ci
 
 FROM node:25-alpine AS build
 WORKDIR /app
@@ -26,7 +29,8 @@ WORKDIR /app
 ENV NODE_ENV=production
 RUN apk add --no-cache curl
 COPY package*.json ./
-RUN npm install --omit=dev
+# Reproducible prod-only install from the lockfile (drops devDependencies).
+RUN npm ci --omit=dev
 COPY --from=build /app/dist ./dist
 
 # M10: drop root. The official node image ships a non-root `node` user (uid 1000).

package/dist/tools/omada/namespace.d.ts

@@ -75,6 +75,14 @@ export declare function resolveUsageWindowSec(params: Record<string, string> | u
     start: number;
     end: number;
 };
+/**
+ * Build the optional query filters for the audit-log endpoints from caller params.
+ * `startTime`/`endTime` are epoch MILLISECONDS, forwarded as the controller's
+ * `filters.startTime`/`filters.endTime`; `searchKey` is fuzzy text. Absent params
+ * are omitted so a bare read returns the most recent page unfiltered. Exported for
+ * unit testing.
+ */
+export declare function auditFilters(params: Record<string, string> | undefined): Record<string, unknown>;
 /**
  * The Omada resource graph. Containers have no `fetch` (browse-only); collections
  * and leaves fetch data. Existing client methods back the well-trodden reads;

package/dist/tools/omada/namespace.js

@@ -49,6 +49,26 @@ export function resolveUsageWindowSec(params, now = Date.now()) {
     const start = params?.startTime ? Number(params.startTime) : end - 24 * 60 * 60;
     return { start, end };
 }
+/**
+ * Build the optional query filters for the audit-log endpoints from caller params.
+ * `startTime`/`endTime` are epoch MILLISECONDS, forwarded as the controller's
+ * `filters.startTime`/`filters.endTime`; `searchKey` is fuzzy text. Absent params
+ * are omitted so a bare read returns the most recent page unfiltered. Exported for
+ * unit testing.
+ */
+export function auditFilters(params) {
+    const query = {};
+    if (params?.startTime !== undefined) {
+        query['filters.startTime'] = Number(params.startTime);
+    }
+    if (params?.endTime !== undefined) {
+        query['filters.endTime'] = Number(params.endTime);
+    }
+    if (params?.searchKey) {
+        query.searchKey = params.searchKey;
+    }
+    return query;
+}
 /**
  * The Omada resource graph. Containers have no `fetch` (browse-only); collections
  * and leaves fetch data. Existing client methods back the well-trodden reads;
@@ -116,6 +136,85 @@ export const OMADA_RESOURCES = [
         params: [{ name: 'stackId', required: true, description: 'Switch stack identifier' }],
         fetch: (c, a) => c.getSwitchStackDetail(a.params?.stackId ?? '', a.siteId),
     },
+    {
+        path: '/devices/search',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Search infrastructure devices across all sites by name/MAC/model. Requires searchKey.',
+        params: [{ name: 'searchKey', required: true, description: 'Text to match against device name, MAC, or model' }],
+        fetch: (c, a) => c.searchDevices(a.params?.searchKey ?? ''),
+    },
+    // ---- Cable test (switch port diagnostics) -----------------------------
+    {
+        path: '/devices/cable-test',
+        kind: 'container',
+        permission: Q,
+        description: 'Switch-port cable diagnostics. Children require a switchMac (find via /devices).',
+    },
+    {
+        path: '/devices/cable-test/ports',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Ports available for cable testing on a switch. Requires switchMac.',
+        params: [{ name: 'switchMac', required: true, description: 'Switch MAC address' }],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/cable-test/switches/{switchMac}/ports',
+            siteId: a.siteId,
+            pathParams: { switchMac: a.params?.switchMac ?? '' },
+        }),
+    },
+    {
+        path: '/devices/cable-test/results',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Full cable-test results (pair status, length, fault distance) for a switch. Requires switchMac.',
+        params: [{ name: 'switchMac', required: true, description: 'Switch MAC address' }],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/cable-test/switches/{switchMac}/full-results',
+            siteId: a.siteId,
+            pathParams: { switchMac: a.params?.switchMac ?? '' },
+        }),
+    },
+    {
+        path: '/devices/cable-test/logs',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Cable-test run history for a switch. Requires switchMac.',
+        params: [{ name: 'switchMac', required: true, description: 'Switch MAC address' }],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/cable-test/switches/{switchMac}/logs',
+            siteId: a.siteId,
+            pathParams: { switchMac: a.params?.switchMac ?? '' },
+        }),
+    },
+    {
+        path: '/devices/poe',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Per-port PoE status across switches (which ports deliver power, to what, and how much). Paginated.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/switches/ports/poe-info',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/devices/lldp',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Site-wide LLDP neighbor information (physical link/topology discovery between devices).',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/lldp', siteId: a.siteId }),
+    },
     // ---- Clients (connected users) ----------------------------------------
     {
         path: '/clients',
@@ -241,6 +340,178 @@ export const OMADA_RESOURCES = [
         params: [{ name: 'type', required: false, description: "'User' (default) or 'UPnP'" }],
         fetch: (c, a) => c.getPortForwardingStatus(a.params?.type === 'UPnP' ? 'UPnP' : 'User', a.siteId, a.page ?? 1, a.pageSize ?? 10),
     },
+    {
+        path: '/network/port-forwarding/rules',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Configured NAT port-forwarding rules (the full rule list, not just status). Paginated — use page/pageSize.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/nat/port-forwardings',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/network/dhcp-leases',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'medium',
+        description: 'Active DHCP leases across all DHCP servers on the site (paginated). Use page/pageSize. See /network/dhcp-reservations for static reservations.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/setting/service/dhcp/user-list',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/network/load-balance',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Multi-WAN load-balance status for the gateway (which WANs are up / in the balancing pool).',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/internet/load-balance/status', siteId: a.siteId }),
+    },
+    {
+        path: '/network/dhcp-reservations',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Static DHCP reservations (each maps a client MAC to a fixed IP). Paginated. See /network/dhcp-leases for active leases.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/setting/service/dhcp',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/network/static-routes',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Configured static routes for the gateway (destination → next-hop). Paginated.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/routing/static-routings',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/network/ip-mac-binding',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'IP↔MAC binding entries (ARP-spoofing protection: which MACs are pinned to which IPs). Paginated.',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/ip-mac-binds',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    {
+        path: '/network/attack-defense',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Gateway attack-defense settings (flood/scan/spoof protection toggles and thresholds).',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/attack-defense', siteId: a.siteId }),
+    },
+    // ---- Access-control lists (read-only policy visibility) ---------------
+    { path: '/network/acls', kind: 'container', permission: Q, description: 'Access-control lists by enforcement point (gateway, switch, EAP/AP).' },
+    {
+        path: '/network/acls/gateway',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Gateway ACL rules (osg-acls). Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/acls/osg-acls', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    {
+        path: '/network/acls/switch',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Switch ACL rules (osw-acls). Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/acls/osw-acls', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    {
+        path: '/network/acls/eap',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'EAP/AP ACL rules (eap-acls). Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/acls/eap-acls', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    // ---- URL filtering (content controls) ---------------------------------
+    { path: '/network/url-filters', kind: 'container', permission: Q, description: 'URL-filtering rules (content/parental controls) by enforcement point.' },
+    {
+        path: '/network/url-filters/gateway',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'Gateway URL-filter rules. Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/url-filters/gateway', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    {
+        path: '/network/url-filters/eap',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'EAP/AP URL-filter rules. Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/url-filters/eap', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    // ---- MAC filtering -----------------------------------------------------
+    { path: '/network/mac-filters', kind: 'container', permission: Q, description: 'Wireless MAC allow/deny filtering lists.' },
+    {
+        path: '/network/mac-filters/allow',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'MAC addresses on the allow list. Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/mac-filters/allow', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
+    {
+        path: '/network/mac-filters/deny',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'MAC addresses on the deny list. Paginated.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/mac-filters/deny', siteId: a.siteId, paginated: true, page: a.page, pageSize: a.pageSize }),
+    },
     {
         path: '/network/rate-limit-profiles',
         kind: 'collection',
@@ -312,6 +583,14 @@ export const OMADA_RESOURCES = [
             ? c.getSsidDetail(a.params.wlanId ?? '', a.params.ssidId, a.siteId)
             : c.getSsidList(a.params?.wlanId ?? '', a.siteId),
     },
+    {
+        path: '/wifi/band-steering',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Band-steering settings for the site (steering clients between 2.4/5/6 GHz radios).',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/band-steering', siteId: a.siteId }),
+    },
     // ---- Events / alerts (paginated) --------------------------------------
     {
         path: '/events',
@@ -400,6 +679,40 @@ export const OMADA_RESOURCES = [
         ],
         fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/dashboard/top-device-memory-usage', siteId: a.siteId, query: resolveUsageWindowSec(a.params) }),
     },
+    {
+        path: '/dashboard/client-distribution',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Breakdown of connected clients by category (wired/wireless, band, SSID). No time window required.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/dashboard/client-distribution', siteId: a.siteId }),
+    },
+    {
+        path: '/dashboard/traffic-distribution',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Traffic distribution across the site over a time window (default: last 24h). Override with params.startTime / ' +
+            'params.endTime (epoch SECONDS).',
+        params: [
+            { name: 'startTime', required: false, description: 'Window start, epoch seconds (default: 24h ago)' },
+            { name: 'endTime', required: false, description: 'Window end, epoch seconds (default: now)' },
+        ],
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/dashboard/traffic-distribution', siteId: a.siteId, query: resolveUsageWindowSec(a.params) }),
+    },
+    {
+        path: '/dashboard/traffic-activities',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'medium',
+        description: 'Traffic activity over time (a time-series for charting) for the site (default window: last 24h). Override with ' +
+            'params.startTime / params.endTime (epoch SECONDS).',
+        params: [
+            { name: 'startTime', required: false, description: 'Window start, epoch seconds (default: 24h ago)' },
+            { name: 'endTime', required: false, description: 'Window end, epoch seconds (default: now)' },
+        ],
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/dashboard/traffic-activities', siteId: a.siteId, query: resolveUsageWindowSec(a.params) }),
+    },
     // ---- Firmware ----------------------------------------------------------
     {
         path: '/firmware',
@@ -422,6 +735,211 @@ export const OMADA_RESOURCES = [
         description: 'Controller-wide overview of critical firmware upgrades (not site-scoped).',
         fetch: (c) => c.readResource({ pathTemplate: '/upgrade/overview/critical', siteScoped: false }),
     },
+    // ---- VPN (status & tunnels) -------------------------------------------
+    {
+        path: '/vpn',
+        kind: 'container',
+        permission: Q,
+        description: 'VPN status: site-to-site, client-to-site, WireGuard, and IPsec tunnel stats.',
+    },
+    {
+        path: '/vpn/site-to-site',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Site-to-site VPN tunnels. Pass id=<vpnId> to fetch a single tunnel.',
+        params: [{ name: 'id', required: false, description: 'VPN id to fetch a single site-to-site tunnel' }],
+        fetch: (c, a) => a.id
+            ? c.readResource({
+                pathTemplate: '/sites/{siteId}/vpn/site-to-site-vpns/{vpnId}',
+                siteId: a.siteId,
+                pathParams: { vpnId: a.id },
+            })
+            : c.readResource({ pathTemplate: '/sites/{siteId}/vpn/site-to-site-vpns', siteId: a.siteId }),
+    },
+    {
+        path: '/vpn/client-to-site',
+        kind: 'container',
+        permission: Q,
+        description: 'Client-to-site (remote-access) VPN: configured servers and connected clients.',
+    },
+    {
+        path: '/vpn/client-to-site/servers',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Configured client-to-site VPN servers (L2TP/OpenVPN/etc.).',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/vpn/client-to-site-vpn-servers', siteId: a.siteId }),
+    },
+    {
+        path: '/vpn/client-to-site/clients',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Currently connected client-to-site (remote-access) VPN clients.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/vpn/client-to-site-vpn-clients', siteId: a.siteId }),
+    },
+    {
+        path: '/vpn/wireguard',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Configured WireGuard VPN interfaces on the gateway.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/vpn/wireguards', siteId: a.siteId }),
+    },
+    {
+        path: '/vpn/ipsec-stats',
+        kind: 'collection',
+        permission: Q,
+        paginated: true,
+        defaultPageSize: 50,
+        estimatedSize: 'small',
+        description: 'IPsec VPN tunnel statistics (paginated — use page/pageSize).',
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/setting/vpn/stats/ipsec',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+        }),
+    },
+    // ---- Profiles (reusable network profiles) -----------------------------
+    {
+        path: '/profiles',
+        kind: 'container',
+        permission: Q,
+        description: 'Reusable network profiles: per-device Wi-Fi keys (PPSK) and time-range schedules.',
+    },
+    {
+        path: '/profiles/ppsk',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'PPSK (Private Pre-Shared Key) profiles — unique per-user/per-device Wi-Fi passwords on a shared SSID. ' +
+            'REQUIRES params.type: 0 = PPSK without RADIUS, 1 = PPSK with RADIUS.',
+        params: [{ name: 'type', required: true, description: '0 = PPSK without RADIUS, 1 = PPSK with RADIUS' }],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/ppsk-profiles',
+            siteId: a.siteId,
+            query: { type: Number(a.params?.type) },
+        }),
+    },
+    {
+        path: '/profiles/time-range',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Time-range profiles — reusable schedules referenced by ACLs, Wi-Fi, and PoE rules.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/time-range-profiles', siteId: a.siteId }),
+    },
+    // ---- Schedules (PoE / port / firmware-upgrade) ------------------------
+    {
+        path: '/schedules',
+        kind: 'container',
+        permission: Q,
+        description: 'Device schedules: PoE power, switch-port on/off, and firmware-upgrade windows. ' +
+            '(Reboot schedules are site-template-scoped enterprise config and are intentionally not exposed here.)',
+    },
+    {
+        path: '/schedules/poe',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'PoE schedules — when switch ports deliver power to PoE devices.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/poe-schedules', siteId: a.siteId }),
+    },
+    {
+        path: '/schedules/port',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Port schedules — when switch ports are administratively up/down.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/port-schedules', siteId: a.siteId }),
+    },
+    {
+        path: '/schedules/upgrade',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Firmware-upgrade schedules — planned maintenance windows for device upgrades.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/upgrade-schedules', siteId: a.siteId }),
+    },
+    // ---- Backup (controller/site backup status) ---------------------------
+    {
+        path: '/backup',
+        kind: 'container',
+        permission: Q,
+        description: 'Site backup status: available backup files and the most recent backup result.',
+    },
+    {
+        path: '/backup/files',
+        kind: 'collection',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'List of available site backup files.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/maintenance/backup/files', siteId: a.siteId }),
+    },
+    {
+        path: '/backup/result',
+        kind: 'leaf',
+        permission: Q,
+        estimatedSize: 'small',
+        description: 'Result of the most recent site backup operation.',
+        fetch: (c, a) => c.readResource({ pathTemplate: '/sites/{siteId}/backup/result', siteId: a.siteId }),
+    },
+    // ---- Audit logs (administrative operation history) — ADMIN only -------
+    {
+        path: '/audit',
+        kind: 'container',
+        permission: A,
+        description: 'Administrative audit logs — who did what on the controller. ADMIN only (reveals full admin activity).',
+    },
+    {
+        path: '/audit/site',
+        kind: 'collection',
+        permission: A,
+        paginated: true,
+        defaultPageSize: 10,
+        estimatedSize: 'large',
+        description: 'Site-scoped administrative audit log (paginated, ADMIN). Optional params: startTime/endTime ' +
+            '(epoch MILLISECONDS) to bound the window, and searchKey (fuzzy text).',
+        params: [
+            { name: 'startTime', required: false, description: 'Window start, epoch milliseconds' },
+            { name: 'endTime', required: false, description: 'Window end, epoch milliseconds' },
+            { name: 'searchKey', required: false, description: 'Fuzzy search on the log text' },
+        ],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/sites/{siteId}/audit-logs',
+            siteId: a.siteId,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+            query: auditFilters(a.params),
+        }),
+    },
+    {
+        path: '/audit/global',
+        kind: 'collection',
+        permission: A,
+        paginated: true,
+        defaultPageSize: 10,
+        estimatedSize: 'large',
+        description: 'Controller-wide administrative audit log across all sites (paginated, ADMIN). Optional params: ' +
+            'startTime/endTime (epoch MILLISECONDS) and searchKey (fuzzy text).',
+        params: [
+            { name: 'startTime', required: false, description: 'Window start, epoch milliseconds' },
+            { name: 'endTime', required: false, description: 'Window end, epoch milliseconds' },
+            { name: 'searchKey', required: false, description: 'Fuzzy search on the log text' },
+        ],
+        fetch: (c, a) => c.readResource({
+            pathTemplate: '/audit-logs',
+            siteScoped: false,
+            paginated: true,
+            page: a.page,
+            pageSize: a.pageSize,
+            query: auditFilters(a.params),
+        }),
+    },
     // ---- Security (IDS/IPS) — ADMIN only -----------------------------------
     {
         path: '/security',