@coffeerunhobby/mcp-ha-connect 1.2.0 → 1.3.1

package/src/utils/jwt.ts

@@ -9,6 +9,9 @@ export interface JwtPayload {
   sub?: string;
   exp?: number;
   iat?: number;
+  nbf?: number;
+  iss?: string;
+  aud?: string | string[];
   [key: string]: unknown;
 }
 
@@ -18,6 +21,18 @@ export interface JwtResult {
   error?: string;
 }
 
+/** Optional claim-validation policy for verifyJwt. */
+export interface JwtVerifyOptions {
+  /** Reject tokens that have no `exp` claim (H3). Default: false (backward-compatible). */
+  requireExp?: boolean;
+  /** Require `iss` to equal this value when set (L6). */
+  issuer?: string;
+  /** Require `aud` to include this value when set (L6). */
+  audience?: string;
+  /** Allowable clock skew in seconds for exp/nbf comparisons (L6). Default: 0. */
+  clockSkewSec?: number;
+}
+
 function b64decode(str: string): string {
   const pad = str + '='.repeat((4 - (str.length % 4)) % 4);
   return Buffer.from(pad.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString();
@@ -27,7 +42,7 @@ function b64encode(data: Buffer): string {
   return data.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
 
-export function verifyJwt(token: string, secret: string): JwtResult {
+export function verifyJwt(token: string, secret: string, options: JwtVerifyOptions = {}): JwtResult {
   const parts = token.split('.');
   if (parts.length !== 3) {
     return { valid: false, error: 'bad format' };
@@ -52,9 +67,37 @@ export function verifyJwt(token: string, secret: string): JwtResult {
     return { valid: false, error: 'bad payload' };
   }
 
-  // Check expiration
-  if (payload.exp && payload.exp < Date.now() / 1000) {
-    return { valid: false, error: 'expired' };
+  const now = Date.now() / 1000;
+  const skew = options.clockSkewSec ?? 0;
+
+  // Expiration (H3): enforce when present; optionally require it.
+  if (payload.exp !== undefined) {
+    if (typeof payload.exp !== 'number' || payload.exp < now - skew) {
+      return { valid: false, error: 'expired' };
+    }
+  } else if (options.requireExp) {
+    return { valid: false, error: 'missing exp' };
+  }
+
+  // Not-before (L6)
+  if (payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || payload.nbf > now + skew) {
+      return { valid: false, error: 'not yet valid' };
+    }
+  }
+
+  // Issuer (L6): only checked when an expected issuer is configured.
+  if (options.issuer !== undefined && payload.iss !== options.issuer) {
+    return { valid: false, error: 'bad issuer' };
+  }
+
+  // Audience (L6): only checked when an expected audience is configured.
+  if (options.audience !== undefined) {
+    const aud = payload.aud;
+    const ok = Array.isArray(aud) ? aud.includes(options.audience) : aud === options.audience;
+    if (!ok) {
+      return { valid: false, error: 'bad audience' };
+    }
   }
 
   return { valid: true, payload };

package/src/utils/sanitizeError.ts

@@ -0,0 +1,18 @@
+/**
+ * Error sanitization for client-facing responses (M6 / OWASP A09:2021).
+ *
+ * Raw `error.message` values routinely embed infrastructure detail — internal
+ * hostnames, ports, filesystem paths, upstream stack fragments, occasionally
+ * tokens. None of that belongs in an HTTP response body. Callers should log the
+ * full error server-side (via `logger.error`) and send the return of this helper
+ * to the client instead.
+ *
+ * The function intentionally ignores the error's own text: returning a constant
+ * generic string is the whole point — there is no "safe subset" of an arbitrary
+ * upstream message we can trust to forward.
+ */
+const GENERIC_MESSAGE = 'Internal server error';
+
+export function sanitizeError(_error: unknown, fallback: string = GENERIC_MESSAGE): string {
+  return fallback;
+}

package/src/utils/tlsDispatcher.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-client TLS dispatcher helper (SEC-CRYPTO / H2).
+ *
+ * When a client must talk to a host with a self-signed certificate, the ONLY
+ * acceptable way to relax certificate validation is to scope it to that single
+ * client. The previous implementation toggled the process-global
+ * `NODE_TLS_REJECT_UNAUTHORIZED` env var around each `fetch` call, which
+ * disables TLS verification for EVERY concurrent outbound request in the
+ * process for the duration of the call — a TOCTOU race that silently strips
+ * certificate validation from unrelated Home Assistant / AI traffic.
+ *
+ * Node's global `fetch` (undici) ignores the legacy `agent` option; the
+ * supported mechanism is a per-call `dispatcher`. We build one undici Agent per
+ * client instance and pass it on every request, leaving the process-global TLS
+ * policy untouched.
+ */
+
+import { Agent, type Dispatcher } from 'undici';
+
+/**
+ * `fetch` init augmented with undici's per-request dispatcher option, which is
+ * not present in the lib.dom / @types/node `RequestInit` typings.
+ */
+export type FetchInitWithDispatcher = RequestInit & { dispatcher?: Dispatcher };
+
+/**
+ * Build an undici dispatcher that disables TLS certificate validation, scoped
+ * to a single client instance. Returns `undefined` when `strictSsl` is not
+ * explicitly disabled, so strict clients carry no dispatcher and use Node's
+ * default (validating) global agent.
+ *
+ * @param strictSsl - When `false`, certificate validation is disabled for this
+ *   client only. Any other value (including `undefined`) keeps validation on.
+ */
+export function createTlsDispatcher(strictSsl: boolean | undefined): Dispatcher | undefined {
+  if (strictSsl === false) {
+    return new Agent({ connect: { rejectUnauthorized: false } });
+  }
+  return undefined;
+}

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 = '1.2.0';
+export const VERSION = '1.3.1';

package/tests/bdd/configuration.spec.ts

@@ -211,6 +211,9 @@ describeFeature(feature, ({ Scenario }) => {
         HA_URL: 'http://homeassistant.local:8123',
         HA_TOKEN: 'test-token',
         MCP_HTTP_BIND_ADDR: '192.168.1.100',
+        // H5: a non-loopback bind requires authentication.
+        MCP_AUTH_METHOD: 'bearer',
+        MCP_AUTH_SECRET: 'test-secret-key-32chars-minimum!',
       };
     });
 

package/tests/config.test.ts

@@ -175,6 +175,9 @@ describe('loadConfig', () => {
       HA_URL: 'http://homeassistant.10.0.0.19.nip.io:8123',
       HA_TOKEN: 'test-token-12345',
       MCP_HTTP_BIND_ADDR: '192.168.1.100',
+      // H5: a non-loopback bind requires authentication.
+      MCP_AUTH_METHOD: 'bearer',
+      MCP_AUTH_SECRET: 'test-secret-key-32chars-minimum!',
     };
 
     const config = loadConfig(env);

package/tests/permissions/index.test.ts

@@ -143,6 +143,27 @@ describe('getUserPermissions', () => {
     const configWithDefault = { ...config, defaultRole: 'READONLY' as const };
     expect(getUserPermissions('unknown', configWithDefault)).toBe(Role.READONLY);
   });
+
+  it('should resolve a lowercase defaultRole (case-insensitive)', () => {
+    // Real-world config commonly uses lowercase ("operator"); it must resolve to
+    // the OPERATOR mask, not silently fall through to an empty/undefined mask.
+    const cfg = { users: [], defaultRole: 'operator' as unknown as 'OPERATOR' };
+    expect(getUserPermissions('unlisted-sub', cfg)).toBe(Role.OPERATOR);
+    expect(getUserPermissions(undefined, cfg)).toBe(Role.OPERATOR);
+  });
+
+  it('should resolve a lowercase per-user role (case-insensitive)', () => {
+    const cfg = {
+      users: [{ sub: 'claude', role: 'admin' as unknown as 'ADMIN' }],
+      defaultRole: 'NONE' as const,
+    };
+    expect(getUserPermissions('claude', cfg)).toBe(Role.ADMIN);
+  });
+
+  it('should fail closed to NONE for an unrecognized role name', () => {
+    const cfg = { users: [], defaultRole: 'wizard' as unknown as 'ADMIN' };
+    expect(getUserPermissions('anyone', cfg)).toBe(Role.NONE);
+  });
 });
 
 describe('parsePermissionsConfig', () => {

package/tests/resources/index.test.ts

@@ -9,13 +9,13 @@ import { registerAllResources } from '../../src/resources/index.js';
 
 // Create mock server that captures registered resources
 function createMockServer() {
-  const resources = new Map<string, { config: unknown; handler: Function }>();
+  const resources = new Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }>();
   return {
-    resource: vi.fn((name: string, uriOrTemplate: unknown, config: unknown, handler: Function) => {
+    resource: vi.fn((name: string, uriOrTemplate: unknown, config: unknown, handler: (...args: unknown[]) => unknown) => {
       resources.set(name, { config, handler });
     }),
     resources,
-  } as unknown as McpServer & { resources: Map<string, { config: unknown; handler: Function }> };
+  } as unknown as McpServer & { resources: Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }> };
 }
 
 // Create mock HaClient

package/tests/security/accessControl.test.ts

@@ -0,0 +1,223 @@
+/**
+ * SEC-AC — Access Control / Authorization
+ * OWASP A01:2021 (Broken Access Control), API1/API5:2023 (BOLA/BFLA)
+ *
+ * Findings covered:
+ *   H1 — REST /api/* routes bypass RBAC (authenticated but no permission check).
+ *
+ * These tests assert the SECURE behavior: every REST route is gated on the same
+ * Permission.* bit as its MCP-tool twin, and a token lacking that bit is rejected
+ * with 403 BEFORE any Home Assistant call is made.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HaClient } from '../../src/haClient/index.js';
+import { Permission } from '../../src/permissions/index.js';
+import { requiredRestPermission, handleRestApi } from '../../src/server/http.js';
+import { handleEventSubscription, getClientCount } from '../../src/server/eventSubscription.js';
+import type { EventSubscriber } from '../../src/haClient/events.js';
+import type { AuthenticatedRequest } from '../../src/server/auth.js';
+
+/** Build a mock request carrying a permission mask in auth.extra. */
+function mockReq(
+  method: string,
+  url: string,
+  permissions: number,
+  body?: unknown
+): AuthenticatedRequest {
+  const listeners: Record<string, ((arg?: unknown) => void)[]> = {};
+  const req = {
+    method,
+    url,
+    headers: { host: 'mcp.test:3000' },
+    auth: { token: 't', clientId: 'u', scopes: [], extra: { permissions } },
+    on(event: string, cb: (arg?: unknown) => void) {
+      (listeners[event] ??= []).push(cb);
+      // Drive the body stream synchronously on the next tick for POST parseBody().
+      if (event === 'end') {
+        queueMicrotask(() => {
+          if (body !== undefined) {
+            for (const d of listeners['data'] ?? []) d(Buffer.from(JSON.stringify(body)));
+          }
+          for (const e of listeners['end'] ?? []) e();
+        });
+      }
+      return req;
+    },
+  } as unknown as AuthenticatedRequest;
+  return req;
+}
+
+/** Capture status code and JSON body written to the response. */
+function mockRes(): ServerResponse & { _status?: number; _body?: unknown } {
+  const res = {
+    statusCode: 200,
+    headersSent: false,
+    setHeader: vi.fn(),
+    end: vi.fn(function (this: { _body?: unknown }, payload?: unknown) {
+      if (typeof payload === 'string') {
+        try {
+          this._body = JSON.parse(payload);
+        } catch {
+          this._body = payload;
+        }
+      }
+      return this;
+    }),
+  } as unknown as ServerResponse & { _status?: number; _body?: unknown };
+  // mirror statusCode into _status when sendJson sets it
+  Object.defineProperty(res, '_status', {
+    get() {
+      return res.statusCode;
+    },
+    configurable: true,
+  });
+  return res;
+}
+
+describe('SEC-AC — Access Control', () => {
+  describe('H1: REST route → permission mapping (mirrors MCP-tool twins)', () => {
+    it('maps read routes to QUERY', () => {
+      expect(requiredRestPermission('GET', '/api/states')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/states/light.kitchen')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/sensors')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/entities/light')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/search')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/history/sensor.temp')).toBe(Permission.QUERY);
+      expect(requiredRestPermission('GET', '/api/version')).toBe(Permission.QUERY);
+    });
+
+    it('maps the service-call route to CONTROL', () => {
+      expect(requiredRestPermission('POST', '/api/services/light/turn_on')).toBe(Permission.CONTROL);
+    });
+
+    it('returns null for unknown routes (fall through to 404, no auth needed)', () => {
+      expect(requiredRestPermission('GET', '/api/unknown')).toBeNull();
+      expect(requiredRestPermission('DELETE', '/api/states')).toBeNull();
+    });
+  });
+
+  describe('H1: enforcement — insufficient permission is rejected with 403', () => {
+    it('blocks GET /api/states without QUERY and never calls the client', async () => {
+      const client = { getStates: vi.fn().mockResolvedValue([]) } as unknown as HaClient;
+      const req = mockReq('GET', '/api/states', Permission.CONTROL); // CONTROL, not QUERY
+      const res = mockRes();
+
+      await handleRestApi(req, res, '/api/states', client);
+
+      expect(res.statusCode).toBe(403);
+      expect(client.getStates).not.toHaveBeenCalled();
+    });
+
+    it('blocks POST /api/services without CONTROL and never calls the service', async () => {
+      const client = { callService: vi.fn().mockResolvedValue({ ok: true }) } as unknown as HaClient;
+      const req = mockReq('POST', '/api/services/light/turn_on', Permission.QUERY, {
+        entity_id: 'light.kitchen',
+      });
+      const res = mockRes();
+
+      await handleRestApi(req, res, '/api/services/light/turn_on', client);
+
+      expect(res.statusCode).toBe(403);
+      expect(client.callService).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('H1: enforcement — sufficient permission is allowed', () => {
+    it('allows GET /api/states with QUERY', async () => {
+      const client = { getStates: vi.fn().mockResolvedValue([{ entity_id: 'light.x' }]) } as unknown as HaClient;
+      const req = mockReq('GET', '/api/states', Permission.QUERY);
+      const res = mockRes();
+
+      await handleRestApi(req, res, '/api/states', client);
+
+      expect(res.statusCode).toBe(200);
+      expect(client.getStates).toHaveBeenCalledOnce();
+    });
+
+    it('allows POST /api/services with CONTROL', async () => {
+      const client = { callService: vi.fn().mockResolvedValue({ ok: true }) } as unknown as HaClient;
+      const req = mockReq('POST', '/api/services/light/turn_on', Permission.CONTROL, {
+        entity_id: 'light.kitchen',
+      });
+      const res = mockRes();
+
+      await handleRestApi(req, res, '/api/services/light/turn_on', client);
+
+      expect(res.statusCode).toBe(200);
+      expect(client.callService).toHaveBeenCalledOnce();
+    });
+
+    it('treats SUPERUSER (0xFF) as allowed everywhere', async () => {
+      const client = { getStates: vi.fn().mockResolvedValue([]) } as unknown as HaClient;
+      const req = mockReq('GET', '/api/states', 0xff);
+      const res = mockRes();
+
+      await handleRestApi(req, res, '/api/states', client);
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('L2: SSE /subscribe_events requires QUERY permission', () => {
+    /** Minimal SSE-capable response mock. */
+    function sseRes() {
+      return {
+        writableEnded: false,
+        writeHead: vi.fn(),
+        write: vi.fn(),
+        end: vi.fn(),
+      } as unknown as ServerResponse & { writeHead: ReturnType<typeof vi.fn> };
+    }
+
+    /** Request mock that captures the 'close' handler so we can tear down timers. */
+    function sseReq(permissions: number) {
+      const handlers: Record<string, (arg?: unknown) => void> = {};
+      const req = {
+        url: '/subscribe_events',
+        headers: {},
+        auth: { token: 't', clientId: 'u', scopes: [], extra: { permissions } },
+        on(event: string, cb: (arg?: unknown) => void) {
+          handlers[event] = cb;
+          return req;
+        },
+      } as unknown as AuthenticatedRequest;
+      return { req, handlers };
+    }
+
+    it('rejects a subscriber lacking QUERY with 403 and creates no client', async () => {
+      const before = getClientCount();
+      const { req } = sseReq(Permission.CONTROL); // CONTROL, not QUERY
+      const res = sseRes();
+      const subscriber = { isConnected: vi.fn() } as unknown as EventSubscriber;
+
+      await handleEventSubscription(req, res, subscriber);
+
+      expect(res.writeHead).toHaveBeenCalledWith(403, expect.anything());
+      expect(getClientCount()).toBe(before); // no leak
+      expect(subscriber.isConnected).not.toHaveBeenCalled();
+    });
+
+    it('allows a subscriber with QUERY to open the stream', async () => {
+      const { req, handlers } = sseReq(Permission.QUERY);
+      const res = sseRes();
+      const subscriber = {
+        isConnected: vi.fn().mockReturnValue(true),
+        subscribeEventType: vi.fn().mockResolvedValue('sub-1'),
+        unsubscribe: vi.fn().mockResolvedValue(undefined),
+      } as unknown as EventSubscriber;
+
+      await handleEventSubscription(req, res, subscriber);
+
+      // 200 stream opened, not 403
+      expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+        'Content-Type': 'text/event-stream',
+      }));
+      expect(subscriber.subscribeEventType).toHaveBeenCalled();
+
+      // tear down the keep-alive interval the handler registered
+      handlers['close']?.();
+    });
+  });
+});

package/tests/security/authentication.test.ts

@@ -0,0 +1,117 @@
+/**
+ * SEC-AUTHN — Authentication & Session
+ * OWASP A07:2021 (Identification & Authentication Failures), API2:2023
+ *
+ * Findings covered:
+ *   H3 — tokens without `exp` never expire; expiry is optional and unenforceable.
+ *   M8 — JWT secret strength is not enforced at startup.
+ *   L6 — no `iss` / `aud` / `nbf` / clock-skew validation.
+ *
+ * Secure behavior asserted here:
+ *   - verifyJwt can REQUIRE exp (opt-in), validate nbf, and check iss/aud when configured.
+ *   - The default (no options) stays backward-compatible: a token without exp is accepted.
+ *   - loadConfig refuses a bearer secret shorter than 32 chars.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createJwt, verifyJwt } from '../../src/utils/jwt.js';
+import { loadConfig } from '../../src/config.js';
+
+const SECRET = 'test-secret-key-32chars-minimum!';
+const now = () => Math.floor(Date.now() / 1000);
+
+describe('SEC-AUTHN — Authentication', () => {
+  describe('H3: enforce token expiry (opt-in via requireExp)', () => {
+    it('rejects a token without exp when requireExp is set', () => {
+      const token = createJwt({ sub: 'service' }, SECRET);
+      const result = verifyJwt(token, SECRET, { requireExp: true });
+      expect(result.valid).toBe(false);
+      expect(result.error).toMatch(/exp/i);
+    });
+
+    it('accepts a token with a future exp when requireExp is set', () => {
+      const token = createJwt({ sub: 'u', exp: now() + 3600 }, SECRET);
+      expect(verifyJwt(token, SECRET, { requireExp: true }).valid).toBe(true);
+    });
+
+    it('still rejects an expired token when requireExp is set', () => {
+      const token = createJwt({ sub: 'u', exp: now() - 100 }, SECRET);
+      expect(verifyJwt(token, SECRET, { requireExp: true }).valid).toBe(false);
+    });
+
+    it('default (no options) remains backward-compatible: accepts no-exp token', () => {
+      const token = createJwt({ sub: 'service' }, SECRET);
+      expect(verifyJwt(token, SECRET).valid).toBe(true);
+    });
+  });
+
+  describe('L6: nbf (not-before) validation', () => {
+    it('rejects a token whose nbf is in the future', () => {
+      const token = createJwt({ sub: 'u', nbf: now() + 3600 }, SECRET);
+      const result = verifyJwt(token, SECRET);
+      expect(result.valid).toBe(false);
+      expect(result.error).toMatch(/not yet valid|nbf/i);
+    });
+
+    it('accepts a token whose nbf is in the past', () => {
+      const token = createJwt({ sub: 'u', nbf: now() - 100 }, SECRET);
+      expect(verifyJwt(token, SECRET).valid).toBe(true);
+    });
+
+    it('tolerates small clock skew on nbf', () => {
+      const token = createJwt({ sub: 'u', nbf: now() + 30 }, SECRET);
+      expect(verifyJwt(token, SECRET, { clockSkewSec: 60 }).valid).toBe(true);
+    });
+  });
+
+  describe('L6: issuer / audience validation (only when configured)', () => {
+    it('rejects a token with the wrong issuer', () => {
+      const token = createJwt({ sub: 'u', iss: 'evil' }, SECRET);
+      const result = verifyJwt(token, SECRET, { issuer: 'mcp-ha-connect' });
+      expect(result.valid).toBe(false);
+      expect(result.error).toMatch(/issuer/i);
+    });
+
+    it('accepts a token with the expected issuer', () => {
+      const token = createJwt({ sub: 'u', iss: 'mcp-ha-connect' }, SECRET);
+      expect(verifyJwt(token, SECRET, { issuer: 'mcp-ha-connect' }).valid).toBe(true);
+    });
+
+    it('rejects a token whose audience does not match', () => {
+      const token = createJwt({ sub: 'u', aud: 'other' }, SECRET);
+      const result = verifyJwt(token, SECRET, { audience: 'mcp' });
+      expect(result.valid).toBe(false);
+      expect(result.error).toMatch(/audience/i);
+    });
+
+    it('accepts a token whose audience array contains the expected value', () => {
+      const token = createJwt({ sub: 'u', aud: ['mcp', 'other'] }, SECRET);
+      expect(verifyJwt(token, SECRET, { audience: 'mcp' }).valid).toBe(true);
+    });
+
+    it('ignores iss/aud when not configured (backward-compatible)', () => {
+      const token = createJwt({ sub: 'u', iss: 'whatever', aud: 'whatever' }, SECRET);
+      expect(verifyJwt(token, SECRET).valid).toBe(true);
+    });
+  });
+
+  describe('M8: bearer secret strength enforced at startup', () => {
+    const base = { MCP_SERVER_USE_HTTP: 'true', MCP_AUTH_METHOD: 'bearer' };
+
+    it('rejects a bearer secret shorter than 32 characters', () => {
+      expect(() =>
+        loadConfig({ ...base, MCP_AUTH_SECRET: 'too-short' } as NodeJS.ProcessEnv)
+      ).toThrow(/32|secret/i);
+    });
+
+    it('accepts a bearer secret of at least 32 characters', () => {
+      expect(() =>
+        loadConfig({ ...base, MCP_AUTH_SECRET: 'a'.repeat(32) } as NodeJS.ProcessEnv)
+      ).not.toThrow();
+    });
+
+    it('does not require a secret when auth method is none', () => {
+      expect(() => loadConfig({ MCP_AUTH_METHOD: 'none' } as NodeJS.ProcessEnv)).not.toThrow();
+    });
+  });
+});