@coffeerunhobby/mcp-ha-connect 2.2.0 → 2.2.1

package/src/utils/redact.ts

@@ -0,0 +1,59 @@
+/**
+ * Redaction of secrets in tool responses.
+ *
+ * Home Assistant and Omada return secrets inside ordinary read results: the
+ * Wi-Fi password (Omada `pskSetting.securityKey`), RADIUS / CoA / SNMP secrets,
+ * PPSK and VPN keys, portal passwords, camera access tokens in image URLs. A tool
+ * response goes to an AI client and from there into transcripts, so every tool
+ * response is passed through `redactSecrets` (see toToolResult).
+ *
+ * Only non-empty string values under secret-looking names are replaced, with
+ * "<redacted>": an empty value stays empty (so "is a password set?" is still
+ * answerable), and booleans or numbers under similar names (`hidePwd`,
+ * `encryptionPsk`) are left alone. `token=` / `access_token=` query values inside
+ * URLs are masked as well. The input is never modified.
+ *
+ * Applied at the response boundary only, never inside the API clients: internal
+ * read-modify-write paths (SSID schedule, site NTP) must see real values.
+ */
+
+export const REDACTED = '<redacted>';
+
+/**
+ * Secret-looking field names, matched on the whole name or its ending
+ * (case-insensitive), from the Omada Open API and Home Assistant responses.
+ */
+const SECRET_NAME =
+  /(^key$|password|passwd|pwd$|secret|token$|passphrase|presharedkey|privatekey|securitykey|communitystring|^psk$|md5key|simplekey|authcode|devicekey)/i;
+
+/** Credentials inside URLs, e.g. /api/camera_proxy/camera.door?token=abc123 */
+const URL_SECRET = /([?&](?:access_token|token|key|password|secret)=)[^&#\s"]+/gi;
+
+export function isSecretName(name: string): boolean {
+  return SECRET_NAME.test(name);
+}
+
+export function redactSecrets<T>(value: T): T {
+  return redact(value, new WeakSet()) as T;
+}
+
+function redact(value: unknown, seen: WeakSet<object>): unknown {
+  if (typeof value === 'string') {
+    return value.includes('=') ? value.replace(URL_SECRET, `$1${REDACTED}`) : value;
+  }
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  if (seen.has(value)) {
+    return '[circular]';
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item, seen));
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = typeof field === 'string' && field !== '' && isSecretName(key) ? REDACTED : redact(field, seen);
+  }
+  return out;
+}

package/src/version.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '2.2.0';
+export const VERSION = '2.2.1';

package/tests/omadaClient/clientBlocks.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Unblocking clients the controller no longer treats as current, the blocked
+ * list, and deleting a client record (for orphaned blocks).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { McpServer } from '@modelcontextprotocol/server';
+
+import { ClientOperations, CLIENT_DOES_NOT_EXIST, normalizeMac } from '../../src/omadaClient/client.js';
+import { OmadaApiError, RequestHandler } from '../../src/omadaClient/request.js';
+import type { SiteOperations } from '../../src/omadaClient/site.js';
+import type { OmadaClient } from '../../src/omadaClient/index.js';
+import { registerDeleteClientTool } from '../../src/tools/omada/deleteClient.js';
+import { registerListBlockedClientsTool } from '../../src/tools/omada/listBlockedClients.js';
+import { Permission } from '../../src/permissions/index.js';
+
+const buildPath = (p: string): string => `/openapi/v1/omadac1${p}`;
+const MAC = '4C-1D-96-8D-37-C7';
+
+function setup(knownClients: unknown[] = []) {
+    const request = {
+        post: vi.fn(),
+        request: vi.fn(),
+        fetchPaginated: vi.fn().mockResolvedValue(knownClients),
+        // Mirrors the real ensureSuccess: a typed error carrying the controller's errorCode.
+        ensureSuccess: vi.fn((response: { errorCode: number; msg?: string; result?: unknown }) => {
+            if (response.errorCode !== 0) throw new OmadaApiError(response.msg ?? 'Omada error', response.errorCode);
+            return response.result;
+        }),
+    };
+    const site = { resolveSiteId: vi.fn(() => 'site-1') } as unknown as SiteOperations;
+    return { request, ops: new ClientOperations(request as unknown as RequestHandler, site, buildPath) };
+}
+
+const doesNotExist = { errorCode: CLIENT_DOES_NOT_EXIST, msg: 'This client does not exist.' };
+
+describe('normalizeMac', () => {
+    it('treats colon, dash and bare formats as the same MAC', () => {
+        expect(normalizeMac('4c:1d:96:8d:37:c7')).toBe(normalizeMac(MAC));
+        expect(normalizeMac('4c1d968d37c7')).toBe('4C1D968D37C7');
+    });
+});
+
+describe('ClientOperations.unblockClient', () => {
+    it('unblocks normally when the controller knows the client', async () => {
+        const { request, ops } = setup();
+        request.post.mockResolvedValue({ errorCode: 0 });
+
+        await expect(ops.unblockClient(MAC)).resolves.toEqual({ mac: MAC, siteId: 'site-1', blocked: false });
+        expect(request.fetchPaginated).not.toHaveBeenCalled();
+    });
+
+    it('reports success when the client is known and no longer blocked (e.g. unblocked in the web UI)', async () => {
+        const { request, ops } = setup([{ mac: '4c:1d:96:8d:37:c7', name: 'node-1271', block: false }]);
+        request.post.mockResolvedValue(doesNotExist);
+
+        await expect(ops.unblockClient(MAC)).resolves.toEqual({ mac: MAC, siteId: 'site-1', blocked: false });
+        expect(request.fetchPaginated).toHaveBeenCalledWith('/openapi/v1/omadac1/sites/site-1/insight/clients');
+    });
+
+    it('explains the controller limitation when the known client is still blocked', async () => {
+        const { request, ops } = setup([{ mac: MAC, name: 'node-1271', block: true }]);
+        request.post.mockResolvedValue(doesNotExist);
+
+        await expect(ops.unblockClient(MAC)).rejects.toThrow(/cannot unblock .* offline.*Known Clients.*omada_deleteClient/);
+    });
+
+    it('a known record without block state is not proof of an unblock', async () => {
+        const { request, ops } = setup([{ mac: MAC, name: 'node-1271' }]);
+        request.post.mockResolvedValue(doesNotExist);
+
+        await expect(ops.unblockClient(MAC)).rejects.toThrow(/cannot unblock/);
+    });
+
+    it('never reports success when the controller has no record at all (an orphaned block may remain)', async () => {
+        const { request, ops } = setup([{ mac: 'AA-BB-CC-DD-EE-FF', block: false }]);
+        request.post.mockResolvedValue(doesNotExist);
+
+        await expect(ops.unblockClient(MAC)).rejects.toThrow(/no record of .*orphaned block.*omada_deleteClient/);
+    });
+
+    it('other controller errors are passed through as before', async () => {
+        const { request, ops } = setup();
+        request.post.mockResolvedValue({ errorCode: -1, msg: 'General error' });
+
+        await expect(ops.unblockClient(MAC)).rejects.toThrow('General error');
+        expect(request.fetchPaginated).not.toHaveBeenCalled();
+    });
+});
+
+describe('unblockClient through the real request handler', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    it('handles "client does not exist" sent with an HTTP error status, too', async () => {
+        const fetchMock = vi.fn(async (url: string) => {
+            if (url.includes('/unblock')) {
+                return new Response(JSON.stringify({ errorCode: CLIENT_DOES_NOT_EXIST, msg: 'This client does not exist.' }), { status: 400 });
+            }
+            // Known clients: present and no longer blocked.
+            return new Response(JSON.stringify({ errorCode: 0, result: { totalRows: 1, data: [{ mac: MAC, block: false }] } }), { status: 200 });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const auth = { getAccessToken: vi.fn().mockResolvedValue('t'), clearToken: vi.fn() };
+        const request = new RequestHandler({ baseUrl: 'https://omada.test', strictSsl: true }, auth as never);
+        const site = { resolveSiteId: vi.fn(() => 'site-1') } as unknown as SiteOperations;
+        const ops = new ClientOperations(request, site, buildPath);
+
+        await expect(ops.unblockClient(MAC)).resolves.toEqual({ mac: MAC, siteId: 'site-1', blocked: false });
+        expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/insight/clients'))).toBe(true);
+    });
+});
+
+describe('ClientOperations.listBlockedClients / deleteClient', () => {
+    it('lists only blocked known clients, offline ones included', async () => {
+        const { ops } = setup([
+            { mac: MAC, name: 'node-1271', block: true, lastSeen: 1 },
+            { mac: 'AA-BB-CC-DD-EE-FF', name: 'tv', block: false },
+            { mac: '11-22-33-44-55-66', name: 'old' },
+        ]);
+
+        await expect(ops.listBlockedClients()).resolves.toEqual([{ mac: MAC, name: 'node-1271', block: true, lastSeen: 1 }]);
+    });
+
+    it('deletes the client record with DELETE /clients/{mac}, encoding the MAC', async () => {
+        const { request, ops } = setup();
+        request.request.mockResolvedValue({ errorCode: 0 });
+
+        await expect(ops.deleteClient(MAC)).resolves.toEqual({ mac: MAC, siteId: 'site-1', deleted: true });
+        expect(request.request).toHaveBeenCalledWith({ method: 'DELETE', url: `/openapi/v1/omadac1/sites/site-1/clients/${MAC}` });
+    });
+
+    it('surfaces a failed delete', async () => {
+        const { request, ops } = setup();
+        request.request.mockResolvedValue(doesNotExist);
+
+        await expect(ops.deleteClient(MAC)).rejects.toThrow('This client does not exist.');
+    });
+});
+
+describe('client block tools: permissions', () => {
+    const extra = (permissions: number) => ({ sessionId: 's', http: { authInfo: { extra: { permissions } } } });
+
+    function register() {
+        const handlers = new Map<string, (a: unknown, e: unknown) => Promise<{ content: { text: string }[] }>>();
+        const server = { registerTool: vi.fn((name, _c, h) => handlers.set(name, h)) } as unknown as McpServer;
+        const client = { deleteClient: vi.fn().mockResolvedValue({ deleted: true }), listBlockedClients: vi.fn().mockResolvedValue([]) };
+        registerDeleteClientTool(server, client as unknown as OmadaClient);
+        registerListBlockedClientsTool(server, client as unknown as OmadaClient);
+        return { handlers, client };
+    }
+
+    let tools: ReturnType<typeof register>;
+    beforeEach(() => {
+        tools = register();
+    });
+
+    it('omada_deleteClient needs CONFIGURE (CONTROL is not enough)', async () => {
+        const denied = await tools.handlers.get('omada_deleteClient')!({ clientMac: MAC }, extra(Permission.QUERY | Permission.CONTROL));
+        expect(JSON.parse(denied.content[0].text)).toMatchObject({ error: 'Permission denied' });
+        expect(tools.client.deleteClient).not.toHaveBeenCalled();
+
+        await tools.handlers.get('omada_deleteClient')!({ clientMac: MAC }, extra(Permission.CONFIGURE));
+        expect(tools.client.deleteClient).toHaveBeenCalledWith(MAC, undefined);
+    });
+
+    it('omada_listBlockedClients needs only QUERY', async () => {
+        await tools.handlers.get('omada_listBlockedClients')!({}, extra(Permission.QUERY));
+        expect(tools.client.listBlockedClients).toHaveBeenCalled();
+    });
+});

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

@@ -79,11 +79,11 @@ describe('Omada graph tools - registration', () => {
     expect(server.handlers.has('omada_read')).toBe(true);
   });
 
-  it('graph mode registers browse + read + 8 typed writes, and NO typed getters', () => {
+  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(10);
+    expect(count).toBe(11);
     const names = [...server.handlers.keys()];
     expect(names).toContain('omada_browse');
     expect(names).toContain('omada_read');
@@ -93,10 +93,12 @@ describe('Omada graph tools - registration', () => {
     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', () => {
@@ -310,6 +312,15 @@ describe('omada_read', () => {
     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);

package/tests/utils/redact.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Secrets returned by Home Assistant / Omada never reach a tool response.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { McpServer } from '@modelcontextprotocol/server';
+
+import { redactSecrets, REDACTED } from '../../src/utils/redact.js';
+import { toToolResult } from '../../src/tools/common.js';
+import { registerOmadaGraphTools } from '../../src/tools/omada/graph.js';
+import type { OmadaClient } from '../../src/omadaClient/index.js';
+
+/** Shape of an Omada SSID detail (GET .../wlans/{wlanId}/ssids/{ssidId}). */
+const ssidDetail = {
+    ssidId: 'node-s55',
+    name: 'node-s55',
+    security: 3,
+    hidePwd: true,
+    pskSetting: { versionPsk: 2, encryptionPsk: 3, gikRekeyPskEnable: false, securityKey: 'HouseWifiPassw0rd!' },
+    macFilterEnable: false,
+};
+
+describe('redactSecrets', () => {
+    it('redacts the Wi-Fi password but keeps flags and numbers with similar names', () => {
+        const out = redactSecrets(ssidDetail);
+
+        expect(out.pskSetting.securityKey).toBe(REDACTED);
+        expect(out.pskSetting.versionPsk).toBe(2);
+        expect(out.pskSetting.encryptionPsk).toBe(3);
+        expect(out.hidePwd).toBe(true);
+        expect(out.name).toBe('node-s55');
+        expect(JSON.stringify(out)).not.toContain('HouseWifiPassw0rd!');
+    });
+
+    it.each([
+        ['RADIUS profile', { authServer: [{ ip: '192.168.0.2', port: 1812, secret: 'radius-s3cret' }], accountingServerPwd: 'acct-pw', coaPassword: 'coa-pw', radiusPwd: 'rp' }],
+        ['PPSK profile', { name: 'kids', ppsk: [{ name: 'tablet', password: 'ppsk-key-1', vlanId: 20 }] }],
+        ['VPN', { preSharedKey: 'ipsec-psk', presharedKey: 'wg-psk', privateKey: 'wg-private', publicKey: 'wg-public' }],
+        ['SNMP', { snmpV1V2CEnable: true, communityString: 'snmp-community' }],
+        ['portal and hotspot', { password: 'portal-pw', authCode: 'auth-code-123', simpleKey: 'sk', md5Key: 'mk' }],
+        ['SSID variants', { psk: 'override-psk', ssidPassword: 'ssid-pw', bridgeSsidPassword: 'bridge-pw', overrideSsidPassword: 'ov-pw' }],
+        ['VRRP and certificates', { key: 'vrrp-key', keyPassword: 'ks-pw', trustPassword: 'trust-pw' }],
+        ['webhooks and tokens', { shardedSecret: 'hook-secret', authToken: 'twilio-token', accessToken: 'at', token: 'user-token' }],
+    ])('redacts every secret in a %s', (_name, input) => {
+        const text = JSON.stringify(redactSecrets(input));
+
+        for (const secret of ['radius-s3cret', 'acct-pw', 'coa-pw', 'ppsk-key-1', 'ipsec-psk', 'wg-psk', 'wg-private', 'snmp-community', 'portal-pw', 'auth-code-123', 'override-psk', 'ssid-pw', 'bridge-pw', 'ov-pw', 'vrrp-key', 'ks-pw', 'trust-pw', 'hook-secret', 'twilio-token', 'user-token']) {
+            expect(text).not.toContain(secret);
+        }
+    });
+
+    it('keeps public, non-secret values (public keys, ids, names)', () => {
+        const out = redactSecrets({ publicKey: 'wg-public', keyId: 'k1', searchKey: 'abc', ppskProfileId: 'p1' });
+        expect(out).toEqual({ publicKey: 'wg-public', keyId: 'k1', searchKey: 'abc', ppskProfileId: 'p1' });
+    });
+
+    it('masks tokens inside URLs (Home Assistant camera image)', () => {
+        const out = redactSecrets({
+            entity_picture: '/api/camera_proxy/camera.door?token=0123456789abcdef&width=640',
+            attributes: { access_token: 'cam-token' },
+        });
+        expect(out.entity_picture).toBe(`/api/camera_proxy/camera.door?token=${REDACTED}&width=640`);
+        expect(out.attributes.access_token).toBe(REDACTED);
+    });
+
+    it('leaves empty secrets empty, so "is it set?" stays answerable', () => {
+        expect(redactSecrets({ password: '', securityKey: 'x' })).toEqual({ password: '', securityKey: REDACTED });
+    });
+
+    it('does not modify its input', () => {
+        const input = structuredClone(ssidDetail);
+        redactSecrets(input);
+        expect(input).toEqual(ssidDetail);
+    });
+
+    it('handles arrays, nulls and plain strings', () => {
+        expect(redactSecrets([{ password: 'p' }, null, 3])).toEqual([{ password: REDACTED }, null, 3]);
+        expect(redactSecrets('see /x?token=abc')).toBe(`see /x?token=${REDACTED}`);
+        expect(redactSecrets(null)).toBeNull();
+    });
+});
+
+describe('tool responses are redacted', () => {
+    it('toToolResult never carries a secret', () => {
+        const result = toToolResult(ssidDetail);
+        expect(result.content[0].text).not.toContain('HouseWifiPassw0rd!');
+        expect(result.content[0].text).toContain(REDACTED);
+    });
+
+    it('omada_read /wifi/ssids (SSID detail) does not return the Wi-Fi password', async () => {
+        const handlers = new Map<string, (args: unknown, extra: unknown) => Promise<{ content: { text: string }[] }>>();
+        const server = { registerTool: vi.fn((name, _c, h) => handlers.set(name, h)) } as unknown as McpServer;
+        const client = { getSsidDetail: vi.fn().mockResolvedValue(ssidDetail), getSsidList: vi.fn() } as unknown as OmadaClient;
+        registerOmadaGraphTools(server, client);
+
+        const result = await handlers.get('omada_read')!(
+            { path: '/wifi/ssids', params: { wlanId: 'w1', ssidId: 'node-s55' } },
+            { sessionId: 's', http: { authInfo: { extra: { permissions: 0xff } } } }
+        );
+
+        expect(client.getSsidDetail).toHaveBeenCalled();
+        expect(result.content[0].text).not.toContain('HouseWifiPassw0rd!');
+        expect(JSON.parse(result.content[0].text).pskSetting.securityKey).toBe(REDACTED);
+    });
+});