@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/tests/tools/infra/invokeAction.test.ts

@@ -1,280 +0,0 @@
-/**
- * Unit tests for the infra plugin: MCP_REST_ACTIONS parsing and the invokeAction
- * tool ("actuator rails for HTTP").
- *
- * The security property under test throughout: the model's ONLY input is an
- * action NAME resolved by exact own-property lookup — a malformed or hostile
- * string can fail the lookup, and nothing else. It never reaches URL, method,
- * headers, or body.
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import type { McpServer } from '@modelcontextprotocol/server';
-import { registerInfraTools, parseRestActions, resetActionCooldowns } from '../../../src/tools/infra/index.js';
-import { Permission } from '../../../src/tools/common.js';
-
-describe('parseRestActions', () => {
-    it('returns an empty map for unset/blank input', () => {
-        expect(parseRestActions(undefined)).toEqual({});
-        expect(parseRestActions('')).toEqual({});
-        expect(parseRestActions('   ')).toEqual({});
-    });
-
-    it('parses a valid action map (method defaults to POST)', () => {
-        const parsed = parseRestActions(
-            '{"update-node-u2":{"url":"http://192.168.0.9:8425/v1/update","bearerToken":"secret-1","description":"deploy latest images"}}'
-        );
-        expect(parsed['update-node-u2']).toMatchObject({
-            method: 'POST',
-            url: 'http://192.168.0.9:8425/v1/update',
-            bearerToken: 'secret-1',
-        });
-    });
-
-    it('returns a null-prototype map (no Object.prototype reachable through it)', () => {
-        const parsed = parseRestActions('{"ok-action":{"url":"http://h:1/x"}}');
-        expect(Object.getPrototypeOf(parsed)).toBeNull();
-    });
-
-    it('fails loudly on malformed JSON, arrays, and non-objects', () => {
-        expect(() => parseRestActions('not-json')).toThrow(/must be valid JSON/);
-        expect(() => parseRestActions('[1,2]')).toThrow(/JSON object keyed by action name/);
-        expect(() => parseRestActions('"str"')).toThrow(/JSON object keyed by action name/);
-    });
-
-    it('rejects hostile or malformed action names at config time', () => {
-        for (const bad of ['__proto__', 'has space', 'UPPER', 'a/../b', 'x'.repeat(65), '-startdash']) {
-            expect(() => parseRestActions(`{"${bad}":{"url":"http://h:1/x"}}`)).toThrow(/Invalid MCP_REST_ACTIONS action name/);
-        }
-    });
-
-    it('rejects invalid urls, non-http(s) schemes, and bad methods', () => {
-        expect(() => parseRestActions('{"a":{"url":"nope"}}')).toThrow(/Invalid MCP_REST_ACTIONS entry/);
-        expect(() => parseRestActions('{"a":{"url":"file:///etc/passwd"}}')).toThrow(/only http\(s\)/);
-        expect(() => parseRestActions('{"a":{"url":"http://h:1/x","method":"DELETE"}}')).toThrow(/Invalid MCP_REST_ACTIONS entry/);
-    });
-});
-
-// Mock server that captures registered handlers (same pattern as omada handler tests)
-function createMockServer() {
-    const handlers = new Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }>();
-    return {
-        registerTool: vi.fn((name: string, config: unknown, handler: (...args: unknown[]) => unknown) => {
-            handlers.set(name, { config, handler });
-        }),
-        handlers,
-    } as unknown as McpServer & { handlers: Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }> };
-}
-const adminExtra = {
-    sessionId: 'test-session',
-    http: { authInfo: { extra: { permissions: 0xff } } },
-};
-
-const ACTIONS = parseRestActions(
-    JSON.stringify({
-        'update-node-u2': {
-            url: 'http://192.168.0.9:8425/v1/update',
-            bearerToken: 'tok-u2',
-            description: 'deploy latest images on node-u2',
-        },
-        'ping-webhook': { url: 'http://192.168.0.18:5678/webhook/ping', method: 'GET' },
-    })
-);
-
-describe('invokeAction tool', () => {
-    let fetchSpy: ReturnType<typeof vi.spyOn>;
-
-    beforeEach(() => {
-        fetchSpy = vi.spyOn(globalThis, 'fetch');
-        // The cooldown store is process-wide (module-level by design — sessions
-        // must share it); clear it so cases can't poison each other.
-        resetActionCooldowns();
-    });
-
-    afterEach(() => {
-        fetchSpy.mockRestore();
-    });
-
-    it('does not register at all when no actions are configured', () => {
-        const server = createMockServer();
-        expect(registerInfraTools(server, {})).toBe(0);
-        expect(server.handlers.size).toBe(0);
-    });
-
-    it('embeds the action names + descriptions in the tool description', () => {
-        const server = createMockServer();
-        expect(registerInfraTools(server, ACTIONS)).toBe(1);
-        const description = (server.handlers.get('invokeAction')?.config as { description: string }).description;
-        expect(description).toContain('update-node-u2 (deploy latest images on node-u2)');
-        expect(description).toContain('ping-webhook');
-    });
-
-    it('fires the configured request exactly — model input shapes nothing but the lookup', async () => {
-        fetchSpy.mockResolvedValue(new Response('OK', { status: 200 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-
-        const { handler } = server.handlers.get('invokeAction')!;
-        const result = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-
-        expect(fetchSpy).toHaveBeenCalledTimes(1);
-        expect(fetchSpy).toHaveBeenCalledWith(
-            'http://192.168.0.9:8425/v1/update',
-            expect.objectContaining({
-                method: 'POST',
-                headers: { Authorization: 'Bearer tok-u2' },
-                redirect: 'error',
-            })
-        );
-        expect(result.isError).toBeFalsy();
-        expect(result.content[0].text).toContain('completed');
-    });
-
-    it('sends no Authorization header when the action has no token', async () => {
-        fetchSpy.mockResolvedValue(new Response('pong', { status: 200 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-
-        const { handler } = server.handlers.get('invokeAction')!;
-        await handler({ action: 'ping-webhook' }, adminExtra);
-
-        expect(fetchSpy).toHaveBeenCalledWith(
-            'http://192.168.0.18:5678/webhook/ping',
-            expect.objectContaining({ method: 'GET', headers: undefined })
-        );
-    });
-
-    it('rejects unknown actions without touching the network', async () => {
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-
-        const { handler } = server.handlers.get('invokeAction')!;
-        const result = (await handler({ action: 'rm-rf-everything' }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-
-        expect(result.isError).toBe(true);
-        expect(result.content[0].text).toMatch(/Unknown action 'rm-rf-everything'/);
-        expect(fetchSpy).not.toHaveBeenCalled();
-    });
-
-    it('cannot be escaped via prototype-chain names — lookup is own-property only', async () => {
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-        const { handler } = server.handlers.get('invokeAction')!;
-
-        for (const hostile of ['__proto__', 'constructor', 'toString', 'hasOwnProperty']) {
-            const result = (await handler({ action: hostile }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-            expect(result.isError).toBe(true);
-            expect(result.content[0].text).toContain('Unknown action');
-        }
-        expect(fetchSpy).not.toHaveBeenCalled();
-    });
-
-    it('surfaces non-200 responses as errors (body truncated)', async () => {
-        fetchSpy.mockResolvedValue(new Response('x'.repeat(2000), { status: 503 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-
-        const { handler } = server.handlers.get('invokeAction')!;
-        const result = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-
-        expect(result.isError).toBe(true);
-        expect(result.content[0].text).toMatch(/HTTP 503/);
-        expect(result.content[0].text.length).toBeLessThan(700); // 500-char cap + wrapper
-    });
-
-    it('rate-limits: a second firing within the cooldown is rejected without touching the network', async () => {
-        fetchSpy.mockResolvedValue(new Response('OK', { status: 200 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-        const { handler } = server.handlers.get('invokeAction')!;
-
-        const first = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean };
-        expect(first.isError).toBeFalsy();
-
-        const second = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-        expect(second.isError).toBe(true);
-        expect(second.content[0].text).toMatch(/cooling down/);
-        expect(fetchSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('rate-limits per action: cooling one action does not block another', async () => {
-        fetchSpy.mockResolvedValue(new Response('OK', { status: 200 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-        const { handler } = server.handlers.get('invokeAction')!;
-
-        await handler({ action: 'update-node-u2' }, adminExtra);
-        const other = (await handler({ action: 'ping-webhook' }, adminExtra)) as { isError?: boolean };
-        expect(other.isError).toBeFalsy();
-        expect(fetchSpy).toHaveBeenCalledTimes(2);
-    });
-
-    it('allows firing again once the cooldown has elapsed', async () => {
-        vi.useFakeTimers();
-        try {
-            fetchSpy.mockResolvedValue(new Response('OK', { status: 200 }));
-            const server = createMockServer();
-            registerInfraTools(server, ACTIONS);
-            const { handler } = server.handlers.get('invokeAction')!;
-
-            await handler({ action: 'update-node-u2' }, adminExtra);
-            vi.advanceTimersByTime(60_001); // default cooldown is 60s
-            const again = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean };
-            expect(again.isError).toBeFalsy();
-            expect(fetchSpy).toHaveBeenCalledTimes(2);
-        } finally {
-            vi.useRealTimers();
-        }
-    });
-
-    it('a FAILED firing still consumes the cooldown slot (no hammering a dying endpoint)', async () => {
-        fetchSpy.mockResolvedValue(new Response('boom', { status: 503 }));
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-        const { handler } = server.handlers.get('invokeAction')!;
-
-        const first = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean };
-        expect(first.isError).toBe(true); // HTTP 503 surfaced
-        const retry = (await handler({ action: 'update-node-u2' }, adminExtra)) as { isError?: boolean; content: Array<{ text: string }> };
-        expect(retry.isError).toBe(true);
-        expect(retry.content[0].text).toMatch(/cooling down/);
-        expect(fetchSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('cooldownMs: 0 disables the rate limit for that action', async () => {
-        fetchSpy.mockResolvedValue(new Response('OK', { status: 200 }));
-        const noCooldown = parseRestActions(
-            '{"rapid":{"url":"http://192.168.0.9:1/x","cooldownMs":0}}'
-        );
-        const server = createMockServer();
-        registerInfraTools(server, noCooldown);
-        const { handler } = server.handlers.get('invokeAction')!;
-
-        await handler({ action: 'rapid' }, adminExtra);
-        const second = (await handler({ action: 'rapid' }, adminExtra)) as { isError?: boolean };
-        expect(second.isError).toBeFalsy();
-        expect(fetchSpy).toHaveBeenCalledTimes(2);
-    });
-
-    it('rejects invalid cooldownMs at config parse', () => {
-        expect(() => parseRestActions('{"a":{"url":"http://h:1/x","cooldownMs":-1}}')).toThrow(/Invalid MCP_REST_ACTIONS entry/);
-        expect(() => parseRestActions('{"a":{"url":"http://h:1/x","cooldownMs":999999999}}')).toThrow(/Invalid MCP_REST_ACTIONS entry/);
-        expect(parseRestActions('{"a":{"url":"http://h:1/x","cooldownMs":30000}}')['a'].cooldownMs).toBe(30000);
-    });
-
-    it('denies callers without the ADMIN permission bit', async () => {
-        const server = createMockServer();
-        registerInfraTools(server, ACTIONS);
-        const operatorExtra = {
-            sessionId: 'test-session',
-            // OPERATOR mask = QUERY|CONTROL|NOTIFY — no ADMIN bit
-            http: { authInfo: { extra: { permissions: Permission.QUERY | Permission.CONTROL | Permission.NOTIFY } } },
-        };
-
-        const { handler } = server.handlers.get('invokeAction')!;
-        const result = (await handler({ action: 'update-node-u2' }, operatorExtra)) as { isError?: boolean };
-
-        expect(result.isError).toBe(true);
-        expect(fetchSpy).not.toHaveBeenCalled();
-    });
-});

package/tests/tools/omada/graph.test.ts

@@ -1,385 +0,0 @@
-/**
- * Unit tests for the Omada resource-graph tools (omada_browse + omada_read).
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { OmadaClient } from '../../../src/omadaClient/index.js';
-import { registerOmadaGraphTools } from '../../../src/tools/omada/graph.js';
-import { registerOmadaTools } from '../../../src/tools/omada/index.js';
-import { Permission } from '../../../src/permissions/index.js';
-
-function createMockServer() {
-  const handlers = new Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }>();
-  return {
-    registerTool: vi.fn((name: string, config: unknown, handler: (...args: unknown[]) => unknown) => {
-      handlers.set(name, { config, handler });
-    }),
-    handlers,
-  } as unknown as McpServer & {
-    registerTool: ReturnType<typeof vi.fn>;
-    handlers: Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }>;
-  };
-}
-
-function createMockClient() {
-  return {
-    listSites: vi.fn(),
-    listDevices: vi.fn(),
-    getDevice: vi.fn(),
-    listClients: vi.fn(),
-    getClient: vi.fn(),
-    listMostActiveClients: vi.fn(),
-    getInternetInfo: vi.fn(),
-    getSiteNtpStatus: vi.fn(),
-    getLanNetworkList: vi.fn(),
-    getLanProfileList: vi.fn(),
-    getWlanGroupList: vi.fn(),
-    getFirewallSetting: vi.fn(),
-    listDevicesStats: vi.fn(),
-    getSwitchStackDetail: vi.fn(),
-    listClientsActivity: vi.fn(),
-    listClientsPastConnections: vi.fn(),
-    getPortForwardingStatus: vi.fn(),
-    getRateLimitProfiles: vi.fn(),
-    getSsidList: vi.fn(),
-    getSsidDetail: vi.fn(),
-    getThreatList: vi.fn(),
-    readResource: vi.fn(),
-    // writes (graph mode also registers these)
-    setClientRateLimit: vi.fn(),
-    setClientRateLimitProfile: vi.fn(),
-    disableClientRateLimit: vi.fn(),
-    blockClient: vi.fn(),
-    unblockClient: vi.fn(),
-  } as unknown as OmadaClient;
-}
-
-// Caller with all permissions.
-const adminExtra = { sessionId: 'test', http: { authInfo: { extra: { permissions: 0xff } } } };
-// Caller with only QUERY (read-only).
-const readonlyExtra = { sessionId: 'test', http: { authInfo: { extra: { permissions: Permission.QUERY } } } };
-// Caller with NO permissions.
-const noPermsExtra = { sessionId: 'test', http: { authInfo: { extra: { permissions: 0 } } } };
-
-function parseResult(result: { content: { text: string }[]; isError?: boolean }): {
-  isError?: boolean;
-  data: Record<string, unknown>;
-} {
-  return { isError: result.isError, data: JSON.parse(result.content[0].text) };
-}
-
-describe('Omada graph tools - registration', () => {
-  it('registerOmadaGraphTools registers omada_browse and omada_read', () => {
-    const server = createMockServer();
-    const client = createMockClient();
-    const count = registerOmadaGraphTools(server, client);
-    expect(count).toBe(2);
-    expect(server.handlers.has('omada_browse')).toBe(true);
-    expect(server.handlers.has('omada_read')).toBe(true);
-  });
-
-  it('graph mode registers browse + read + 9 typed writes, and NO typed getters', () => {
-    const server = createMockServer();
-    const client = createMockClient();
-    const count = registerOmadaTools(server, client, 'graph');
-    expect(count).toBe(11);
-    const names = [...server.handlers.keys()];
-    expect(names).toContain('omada_browse');
-    expect(names).toContain('omada_read');
-    expect(names).toContain('omada_blockClient');
-    expect(names).toContain('omada_setClientRateLimit');
-    // v1.6 action tools ride along in graph mode too (writes stay typed).
-    expect(names).toContain('omada_cyclePoePort');
-    expect(names).toContain('omada_setSsidEnabled');
-    expect(names).toContain('omada_setSiteNtpServers');
-    expect(names).toContain('omada_deleteClient');
-    // Typed read getters must NOT be present in graph mode.
-    expect(names).not.toContain('omada_listSites');
-    expect(names).not.toContain('omada_getFirewallSetting');
-    expect(names).not.toContain('omada_getSiteNtpStatus');
-    expect(names).not.toContain('omada_listBlockedClients');
-  });
-
-  it('eager mode (default) registers the typed getters, not the graph tools', () => {
-    const server = createMockServer();
-    const client = createMockClient();
-    registerOmadaTools(server, client);
-    const names = [...server.handlers.keys()];
-    expect(names).toContain('omada_listSites');
-    expect(names).not.toContain('omada_browse');
-    expect(names).not.toContain('omada_read');
-  });
-});
-
-describe('omada_browse', () => {
-  let server: ReturnType<typeof createMockServer>;
-  let client: ReturnType<typeof createMockClient>;
-
-  beforeEach(() => {
-    server = createMockServer();
-    client = createMockClient();
-    vi.clearAllMocks();
-    registerOmadaGraphTools(server, client);
-  });
-
-  function browse(args: { path?: string }, extra: unknown) {
-    return server.handlers.get('omada_browse')!.handler(args, extra) as Promise<{
-      content: { text: string }[];
-      isError?: boolean;
-    }>;
-  }
-
-  it('lists top-level resource types at root', async () => {
-    const { isError, data } = parseResult(await browse({ path: '/' }, adminExtra));
-    expect(isError).toBeFalsy();
-    expect(data.path).toBe('/');
-    const childPaths = (data.children as Array<{ path: string }>).map((c) => c.path);
-    expect(childPaths).toEqual(expect.arrayContaining(['/sites', '/clients', '/gateway', '/wifi']));
-  });
-
-  it('defaults to root when no path is given', async () => {
-    const { data } = parseResult(await browse({}, adminExtra));
-    expect(data.path).toBe('/');
-  });
-
-  it('surfaces metadata (kind, permission, readable, pagination) for children', async () => {
-    const { data } = parseResult(await browse({ path: '/events' }, adminExtra));
-    expect(data.supportsPagination).toBe(true);
-    expect(data.defaultPageSize).toBe(50);
-  });
-
-  it('returns an error for an unknown path', async () => {
-    const { isError, data } = parseResult(await browse({ path: '/nope' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Unknown path');
-  });
-
-  it('is denied for callers lacking QUERY', async () => {
-    const { isError, data } = parseResult(await browse({ path: '/' }, noPermsExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Permission denied');
-  });
-
-  it('read-only callers can browse (all Tier-1 nodes are QUERY)', async () => {
-    const { isError, data } = parseResult(await browse({ path: '/gateway' }, readonlyExtra));
-    expect(isError).toBeFalsy();
-    const childPaths = (data.children as Array<{ path: string }>).map((c) => c.path);
-    expect(childPaths).toEqual(expect.arrayContaining(['/gateway/wan', '/gateway/health']));
-  });
-
-  it('advertises /security at root to ADMIN callers', async () => {
-    const { data } = parseResult(await browse({ path: '/' }, adminExtra));
-    const childPaths = (data.children as Array<{ path: string }>).map((c) => c.path);
-    expect(childPaths).toContain('/security');
-  });
-
-  it('hides the ADMIN-only /security subtree from QUERY-only callers', async () => {
-    const { data } = parseResult(await browse({ path: '/' }, readonlyExtra));
-    const childPaths = (data.children as Array<{ path: string }>).map((c) => c.path);
-    expect(childPaths).not.toContain('/security');
-  });
-});
-
-describe('omada_read', () => {
-  let server: ReturnType<typeof createMockServer>;
-  let client: ReturnType<typeof createMockClient>;
-
-  beforeEach(() => {
-    server = createMockServer();
-    client = createMockClient();
-    vi.clearAllMocks();
-    registerOmadaGraphTools(server, client);
-  });
-
-  function read(args: Record<string, unknown>, extra: unknown) {
-    return server.handlers.get('omada_read')!.handler(args, extra) as Promise<{
-      content: { text: string }[];
-      isError?: boolean;
-    }>;
-  }
-
-  it('reads a collection via the backing client method', async () => {
-    (client.listSites as ReturnType<typeof vi.fn>).mockResolvedValue([{ id: 's1' }]);
-    const { isError, data } = parseResult(await read({ path: '/sites' }, adminExtra));
-    expect(isError).toBeFalsy();
-    expect(data).toEqual([{ id: 's1' }]);
-    expect(client.listSites).toHaveBeenCalled();
-  });
-
-  it('looks up a single collection member when id is provided', async () => {
-    (client.getClient as ReturnType<typeof vi.fn>).mockResolvedValue({ mac: 'AA' });
-    await read({ path: '/clients', id: 'AA', siteId: 'site1' }, adminExtra);
-    expect(client.getClient).toHaveBeenCalledWith('AA', 'site1');
-    expect(client.listClients).not.toHaveBeenCalled();
-  });
-
-  it('lists the collection when no id is provided', async () => {
-    (client.listClients as ReturnType<typeof vi.fn>).mockResolvedValue([]);
-    await read({ path: '/clients' }, adminExtra);
-    expect(client.listClients).toHaveBeenCalled();
-    expect(client.getClient).not.toHaveBeenCalled();
-  });
-
-  it('routes generic leaves through readResource with the right template', async () => {
-    (client.readResource as ReturnType<typeof vi.fn>).mockResolvedValue({ wanIp: '1.2.3.4' });
-    const { data } = parseResult(
-      await read({ path: '/gateway/wan', params: { gatewayMac: 'AA-BB' }, siteId: 'site1' }, adminExtra)
-    );
-    expect(data).toEqual({ wanIp: '1.2.3.4' });
-    expect(client.readResource).toHaveBeenCalledWith(
-      expect.objectContaining({
-        pathTemplate: '/sites/{siteId}/gateways/{gatewayMac}/wan-status',
-        siteId: 'site1',
-        pathParams: { gatewayMac: 'AA-BB' },
-      })
-    );
-  });
-
-  it('forwards pagination to paginated resources', async () => {
-    (client.readResource as ReturnType<typeof vi.fn>).mockResolvedValue({ data: [] });
-    await read({ path: '/events', page: 2, pageSize: 25 }, adminExtra);
-    expect(client.readResource).toHaveBeenCalledWith(
-      expect.objectContaining({ paginated: true, page: 2, pageSize: 25 })
-    );
-  });
-
-  it('reads the controller-global firmware overview without a site', async () => {
-    (client.readResource as ReturnType<typeof vi.fn>).mockResolvedValue({ critical: 0 });
-    await read({ path: '/firmware/critical' }, adminExtra);
-    expect(client.readResource).toHaveBeenCalledWith(
-      expect.objectContaining({ pathTemplate: '/upgrade/overview/critical', siteScoped: false })
-    );
-  });
-
-  it('rejects missing required path parameters before calling the client', async () => {
-    const { isError, data } = parseResult(await read({ path: '/gateway/wan' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Missing parameters');
-    expect(data.missing).toEqual(['gatewayMac']);
-    expect(client.readResource).not.toHaveBeenCalled();
-  });
-
-  it('returns an error for an unknown path', async () => {
-    const { isError, data } = parseResult(await read({ path: '/nope' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Unknown path');
-  });
-
-  it('refuses to read a container node', async () => {
-    const { isError, data } = parseResult(await read({ path: '/gateway' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Not readable');
-  });
-
-  it('defaults port-forwarding type to "User" and forwards pagination', async () => {
-    (client.getPortForwardingStatus as ReturnType<typeof vi.fn>).mockResolvedValue({ data: [] });
-    await read({ path: '/network/port-forwarding', siteId: 's1', page: 3, pageSize: 5 }, adminExtra);
-    expect(client.getPortForwardingStatus).toHaveBeenCalledWith('User', 's1', 3, 5);
-  });
-
-  it('routes /wifi/ssids to the list (wlanId) or detail (wlanId+ssidId)', async () => {
-    (client.getSsidList as ReturnType<typeof vi.fn>).mockResolvedValue([]);
-    (client.getSsidDetail as ReturnType<typeof vi.fn>).mockResolvedValue({ id: 'x' });
-
-    await read({ path: '/wifi/ssids', params: { wlanId: 'w1' }, siteId: 's1' }, adminExtra);
-    expect(client.getSsidList).toHaveBeenCalledWith('w1', 's1');
-
-    await read({ path: '/wifi/ssids', params: { wlanId: 'w1', ssidId: 's9' }, siteId: 's1' }, adminExtra);
-    expect(client.getSsidDetail).toHaveBeenCalledWith('w1', 's9', 's1');
-  });
-
-  it('requires wlanId for /wifi/ssids', async () => {
-    const { isError, data } = parseResult(await read({ path: '/wifi/ssids' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Missing parameters');
-    expect(data.missing).toEqual(['wlanId']);
-  });
-
-  it('reads /network/ntp via getSiteNtpStatus, forwarding an explicit siteId', async () => {
-    (client.getSiteNtpStatus as ReturnType<typeof vi.fn>).mockResolvedValue({ ntpEnable: true, ntpServers: ['82.76.255.14'] });
-    const { isError, data } = parseResult(await read({ path: '/network/ntp', siteId: 'site9' }, readonlyExtra));
-    expect(isError).toBeFalsy();
-    expect(data).toEqual({ ntpEnable: true, ntpServers: ['82.76.255.14'] });
-    expect(client.getSiteNtpStatus).toHaveBeenCalledWith('site9');
-    expect(client.getInternetInfo).not.toHaveBeenCalled();
-  });
-
-  it('denies /network/ntp without QUERY and never calls the controller', async () => {
-    const { isError, data } = parseResult(await read({ path: '/network/ntp' }, noPermsExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Permission denied');
-    expect(client.getSiteNtpStatus).not.toHaveBeenCalled();
-  });
-
-  it('reads /clients/known as one page of known clients (with block state)', async () => {
-    (client.readResource as ReturnType<typeof vi.fn>).mockResolvedValue({ totalRows: 1, data: [{ mac: 'AA', block: true }] });
-    await read({ path: '/clients/known', page: 3, pageSize: 20, siteId: 'site1' }, readonlyExtra);
-    expect(client.readResource).toHaveBeenCalledTimes(1);
-    expect(client.readResource).toHaveBeenCalledWith(
-      expect.objectContaining({ pathTemplate: '/sites/{siteId}/insight/clients', siteId: 'site1', paginated: true, page: 3, pageSize: 20 })
-    );
-  });
-
-  it('enforces per-path permission (fail closed) for under-privileged callers', async () => {
-    const { isError, data } = parseResult(await read({ path: '/sites' }, noPermsExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Permission denied');
-    expect(client.listSites).not.toHaveBeenCalled();
-  });
-
-  it('reads /security/threats via getThreatList, parsing the time window and filters', async () => {
-    (client.getThreatList as ReturnType<typeof vi.fn>).mockResolvedValue({ data: [] });
-    await read(
-      {
-        path: '/security/threats',
-        params: { startTime: '1682000000', endTime: '1682003600', archived: 'true', severity: '1', sortTime: 'desc', searchKey: 'syn' },
-        page: 2,
-        pageSize: 25,
-      },
-      adminExtra
-    );
-    expect(client.getThreatList).toHaveBeenCalledWith({
-      siteList: undefined,
-      archived: true,
-      page: 2,
-      pageSize: 25,
-      startTime: 1682000000,
-      endTime: 1682003600,
-      severity: 1,
-      sortTime: 'desc',
-      searchKey: 'syn',
-    });
-  });
-
-  it('defaults /security/threats archived=false and page/pageSize when omitted', async () => {
-    (client.getThreatList as ReturnType<typeof vi.fn>).mockResolvedValue({ data: [] });
-    await read({ path: '/security/threats', params: { startTime: '1', endTime: '2' } }, adminExtra);
-    expect(client.getThreatList).toHaveBeenCalledWith(
-      expect.objectContaining({ archived: false, page: 1, pageSize: 10, severity: undefined, sortTime: undefined })
-    );
-  });
-
-  it('requires the startTime/endTime window for /security/threats', async () => {
-    const { isError, data } = parseResult(await read({ path: '/security/threats' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Missing parameters');
-    expect(data.missing).toEqual(['startTime', 'endTime']);
-    expect(client.getThreatList).not.toHaveBeenCalled();
-  });
-
-  it('denies /security/threats to QUERY-only callers (ADMIN required)', async () => {
-    const { isError, data } = parseResult(
-      await read({ path: '/security/threats', params: { startTime: '1', endTime: '2' } }, readonlyExtra)
-    );
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Permission denied');
-    expect(client.getThreatList).not.toHaveBeenCalled();
-  });
-
-  it('refuses to read the /security container', async () => {
-    const { isError, data } = parseResult(await read({ path: '/security' }, adminExtra));
-    expect(isError).toBe(true);
-    expect(data.error).toBe('Not readable');
-  });
-});