@coffeerunhobby/mcp-ha-connect 0.7.0 → 0.8.0

package/docs/CHANGELOG.md

@@ -1,4 +1,16 @@
-### 0.7.0 (January 2026)
+### 0.8.0
+- **Bearer Token Authentication**: Secure HTTP endpoints with bearer tokens
+  - `MCP_AUTH_METHOD`: Set to `bearer` to enable authentication
+  - `MCP_AUTH_TOKEN`: Comma-separated tokens for multiple clients
+  - `WWW-Authenticate` header on 401 responses
+  - Health check and OpenAPI endpoints skip authentication
+- **Server-Timing Header**: Response timing on all HTTP responses
+  - `Server-Timing: total;dur=X` header (integer milliseconds)
+  - Visible in browser DevTools Network tab
+- **Modular Auth Middleware**: Clean separation in `src/server/auth.ts`
+- All 648 tests passing
+
+### 0.7.0
 - **Calendar Tools**: Access Home Assistant calendar entities
   - `listCalendars`: Get all calendar entities
   - `getCalendarEvents`: Get events from one or all calendars with date filtering
@@ -8,7 +20,7 @@
   - Returns onsite/away counts and linked device trackers
 - Total tools increased from 34 to 37
 
-### 0.6.0 (January 2026)
+### 0.6.0
 - **Mobile App Notifications**: Full support for Home Assistant mobile app notifications
   - `sendNotification`: Enhanced with action buttons, priority, images, videos
   - `listNotificationTargets`: Discover available mobile app notification targets
@@ -27,7 +39,7 @@
 - Switched to NodeNext module resolution for TypeScript
 - All 310 tests passing
 
-### 0.5.0 (January 2026)
+### 0.5.0
 - **Real-time SSE Event Subscription**: Subscribe to Home Assistant events via Server-Sent Events
   - Filter by domain, entity_id, or event types
   - Automatic WebSocket connection to Home Assistant
@@ -60,7 +72,7 @@
   - `MCP_RATE_LIMIT_MAX_REQUESTS`: Max requests per window
 - Total tools increased from 16 to 33
 
-### 0.4.0 (January 2026)
+### 0.4.0
 - **Extensible AI Provider System**: Refactored AI client to support multiple providers
   - New `src/localAI/` folder with provider-based architecture
   - Supports Ollama (native API) and OpenAI-compatible APIs (LocalAI, LM Studio, vLLM)
@@ -80,7 +92,7 @@
 - No changes to public API or tools - fully backward compatible
 - All 325 tests pass
 
-### 0.3.0 (January 2026)
+### 0.3.0
 - Added 8 new tools: `getVersion`, `entityAction`, `listEntities`, `getDomainSummary`, `listAutomations`, `restartHomeAssistant`, `getSystemLog`, `checkUpdates`
 - Added MCP Resources support with 5 URI-based endpoints (`hass://entities`, etc.)
 - Added `entityAction` tool for simplified turn_on/turn_off/toggle operations
@@ -93,7 +105,7 @@
 - Total tools increased from 8 to 16
 - Enhanced type definitions for Automation, DomainSummary, HaVersion, LogbookEntry, UpdateInfo
 
-### 0.2.0 (January 2026)
+### 0.2.0
 - Added AI-powered sensor analysis with Ollama
 - Added `getAllSensors` tool
 - Added `analyzeSensors` tool
@@ -108,7 +120,7 @@
 - Added Docker CLI workflow import method
 - Enhanced troubleshooting with network/firewall diagnostics
 
-### 0.1.0 (Initial Release)
+### 0.1.0
 - Basic Home Assistant integration
 - 5 core tools (getStates, getState, callService, getEntitiesByDomain, searchEntities)
 - Multiple transport modes (stdio, SSE, HTTP streaming)

package/docs/SSE_API.md

@@ -273,7 +273,7 @@ Response:
 ```json
 {
   "status": "healthy",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "sseEventsEnabled": true,
   "sseEventsPath": "/subscribe_events",
   "sseConnectedClients": 3

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Home Assistant MCP Wrapper",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "REST endpoints that wrap MCP tools for Home Assistant integration. Raw JSON-RPC passthrough available at POST / for n8n compatibility."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeerunhobby/mcp-ha-connect",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Smart home MCP server for Home Assistant plus Local AI integration",
   "type": "module",
   "main": "dist/index.js",

package/src/config.ts

@@ -71,6 +71,10 @@ const envSchema = z
     rateLimitEnabled: createBooleanStringSchema(true),
     rateLimitWindowMs: numericStringSchema,
     rateLimitMaxRequests: numericStringSchema,
+
+    // Authentication Configuration
+    authMethod: z.enum(['none', 'bearer']).optional().default('none'),
+    authToken: listStringSchema,
   })
   .refine(
     (data) => {
@@ -104,6 +108,19 @@ const envSchema = z
         path: ['httpAllowedOrigins'],
       };
     }
+  )
+  .refine(
+    (data) => {
+      // If bearer auth is enabled, token must be provided
+      if (data.authMethod === 'bearer' && !data.authToken) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'MCP_AUTH_TOKEN is required when MCP_AUTH_METHOD is "bearer"',
+      path: ['authToken'],
+    }
   );
 
 export interface EnvironmentConfig {
@@ -144,6 +161,10 @@ export interface EnvironmentConfig {
   rateLimitEnabled: boolean;
   rateLimitWindowMs: number;
   rateLimitMaxRequests: number;
+
+  // Authentication Configuration
+  authMethod: 'none' | 'bearer';
+  authToken?: Set<string>;
 }
 
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentConfig {
@@ -185,6 +206,10 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     rateLimitEnabled: env.MCP_RATE_LIMIT_ENABLED,
     rateLimitWindowMs: env.MCP_RATE_LIMIT_WINDOW_MS,
     rateLimitMaxRequests: env.MCP_RATE_LIMIT_MAX_REQUESTS,
+
+    // Authentication Configuration
+    authMethod: env.MCP_AUTH_METHOD,
+    authToken: env.MCP_AUTH_TOKEN,
   });
 
   if (!parsed.success) {
@@ -244,6 +269,10 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     rateLimitEnabled: parsed.data.rateLimitEnabled,
     rateLimitWindowMs: parsed.data.rateLimitWindowMs ?? 60000,
     rateLimitMaxRequests: parsed.data.rateLimitMaxRequests ?? 100,
+
+    // Authentication Configuration
+    authMethod: parsed.data.authMethod,
+    authToken: parsed.data.authToken ? new Set(parsed.data.authToken) : undefined,
   };
 }
 

package/src/server/auth.ts

@@ -0,0 +1,103 @@
+/**
+ * Authentication middleware for HTTP server
+ * Supports bearer token authentication with multi-token support
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { logger } from '../utils/logger.js';
+
+export type AuthMethod = 'none' | 'bearer';
+
+export interface AuthConfig {
+  method: AuthMethod;
+  tokens?: Set<string>;
+  skipPaths?: string[];
+}
+
+export interface AuthResult {
+  authenticated: boolean;
+  error?: string;
+}
+
+/**
+ * Validate bearer token from Authorization header
+ */
+function validateBearerToken(req: IncomingMessage, validTokens: Set<string>): AuthResult {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader) {
+    return { authenticated: false, error: 'Missing Authorization header' };
+  }
+
+  if (!authHeader.startsWith('Bearer ')) {
+    return { authenticated: false, error: 'Invalid Authorization header format. Expected: Bearer <token>' };
+  }
+
+  const token = authHeader.slice(7);
+  if (!validTokens.has(token)) {
+    return { authenticated: false, error: 'Invalid token' };
+  }
+
+  return { authenticated: true };
+}
+
+/**
+ * Authentication middleware
+ * Returns true if request should proceed, false if blocked
+ */
+export function createAuthMiddleware(config: AuthConfig): (req: IncomingMessage, res: ServerResponse) => boolean {
+  const { method, tokens, skipPaths = [] } = config;
+
+  return (req: IncomingMessage, res: ServerResponse): boolean => {
+    // No auth required
+    if (method === 'none') {
+      return true;
+    }
+
+    // Check if path should skip auth
+    const url = req.url ?? '/';
+    const urlPath = url.split('?')[0];
+
+    if (skipPaths.some((path) => urlPath === path || urlPath.startsWith(path + '/'))) {
+      return true;
+    }
+
+    // Bearer auth
+    if (method === 'bearer') {
+      if (!tokens?.size) {
+        logger.error('Bearer auth enabled but no token configured');
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'Server misconfiguration: auth token not set' }));
+        return false;
+      }
+
+      const result = validateBearerToken(req, tokens);
+
+      if (!result.authenticated) {
+        logger.warn('Authentication failed', {
+          method: req.method,
+          url: urlPath,
+          error: result.error,
+          ip: req.socket.remoteAddress,
+        });
+
+        res.statusCode = 401;
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('WWW-Authenticate', result.error === 'Invalid token' ? 'Bearer error="invalid_token"' : 'Bearer');
+        res.end(JSON.stringify({ error: 'Unauthorized', message: result.error }));
+        return false;
+      }
+
+      logger.debug('Authentication successful', { method: req.method, url: urlPath });
+      return true;
+    }
+
+    // Unknown auth method
+    logger.error('Unknown auth method', { method });
+    res.statusCode = 500;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'Server misconfiguration: unknown auth method' }));
+    return false;
+  };
+}

package/src/server/common.ts

@@ -9,13 +9,14 @@ import type { LocalAIClient } from '../localAI/index.js';
 import { registerAllTools } from '../tools/index.js';
 import { registerAllResources } from '../resources/index.js';
 import { logger } from '../utils/logger.js';
+import { VERSION } from '../version.js';
 
 export function createServer(client: HaClient, aiClient?: LocalAIClient): McpServer {
   logger.debug('Creating MCP server instance');
 
   const server = new McpServer({
     name: 'mcp-ha-connect',
-    version: '0.5.0',
+    version: VERSION,
   });
 
   // Register all Home Assistant tools

package/src/server/http.ts

@@ -13,10 +13,45 @@ import { handleSseConnection, handleSseMessage, getSseMessagePath, type SSETrans
 import { handleStreamRequest, type StreamTransportState } from './stream.js';
 import { handleEventSubscription, getClientCount } from './eventSubscription.js';
 import { RateLimiter } from './rateLimiter.js';
+import { createAuthMiddleware } from './auth.js';
+import { VERSION } from '../version.js';
 
 // Session storage for stateful mode
 const sessions = new Map<string, SSETransportState | StreamTransportState>();
 
+/**
+ * Wrap response to add Server-Timing header with request duration
+ * The timing is calculated and header set just before res.end() is called
+ */
+function wrapResponseWithTiming(res: ServerResponse): { res: ServerResponse; startTime: number } {
+  const startTime = performance.now();
+  const originalEnd = res.end.bind(res);
+
+  // Override res.end to set timing header before sending
+  res.end = function (
+    chunk?: unknown,
+    encodingOrCallback?: BufferEncoding | (() => void),
+    callback?: () => void
+  ): ServerResponse {
+    // Set Server-Timing header if headers haven't been sent
+    if (!res.headersSent) {
+      const durationMs = Math.round(performance.now() - startTime);
+      res.setHeader('Server-Timing', `total;dur=${durationMs}`);
+    }
+
+    // Call original end with proper overload handling
+    if (typeof encodingOrCallback === 'function') {
+      return originalEnd(chunk, encodingOrCallback);
+    }
+    if (encodingOrCallback !== undefined) {
+      return originalEnd(chunk, encodingOrCallback, callback);
+    }
+    return originalEnd(chunk, callback);
+  } as typeof res.end;
+
+  return { res, startTime };
+}
+
 /**
  * Parse JSON body from request
  */
@@ -43,7 +78,8 @@ function parseBody(req: IncomingMessage): Promise<unknown> {
  * Send JSON response
  */
 function sendJson(res: ServerResponse, statusCode: number, data: unknown): void {
-  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/json');
   res.end(JSON.stringify(data));
 }
 
@@ -53,9 +89,10 @@ function sendJson(res: ServerResponse, statusCode: number, data: unknown): void
 function handleHealthCheck(res: ServerResponse, config: EnvironmentConfig, aiEnabled: boolean, sseEnabled: boolean): void {
   sendJson(res, 200, {
     status: 'healthy',
-    version: '0.5.0',
+    version: VERSION,
     transport: config.httpTransport,
     stateful: config.stateful,
+    authMethod: config.authMethod,
     aiEnabled,
     aiProvider: aiEnabled ? config.aiProvider : undefined,
     aiUrl: aiEnabled ? config.aiUrl : undefined,
@@ -197,7 +234,7 @@ function getOpenApiSpec(baseUrl: string): object {
     info: {
       title: 'Home Assistant MCP Tools',
       description: 'MCP server for Home Assistant - exposes entity states and service calls',
-      version: '0.2.0',
+      version: VERSION,
     },
     servers: [{ url: baseUrl }],
     paths: {
@@ -361,6 +398,13 @@ export async function startHttpServer(client: HaClient, config: EnvironmentConfi
       })
     : null;
 
+  // Initialize auth middleware
+  const authMiddleware = createAuthMiddleware({
+    method: config.authMethod,
+    tokens: config.authToken,
+    skipPaths: [healthPath, '/openapi.json'],
+  });
+
   // Initialize event subscriber if SSE events are enabled
   let eventSubscriber: EventSubscriber | null = null;
   if (config.sseEventsEnabled) {
@@ -394,7 +438,10 @@ export async function startHttpServer(client: HaClient, config: EnvironmentConfi
     sseEventsEnabled: config.sseEventsEnabled && !!eventSubscriber,
   });
 
-  const server = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+  const server = createHttpServer(async (req: IncomingMessage, originalRes: ServerResponse) => {
+    // Wrap response to add Server-Timing header
+    const { res } = wrapResponseWithTiming(originalRes);
+
     const url = req.url ?? '/';
     const urlPath = url.split('?')[0];
 
@@ -418,6 +465,11 @@ export async function startHttpServer(client: HaClient, config: EnvironmentConfi
       }
     }
 
+    // Apply authentication (skip health checks and openapi.json)
+    if (!authMiddleware(req, res)) {
+      return; // Response already sent by auth middleware
+    }
+
     // Add CORS headers for MCP endpoints
     handleCors(req, res, config);
 

package/src/version.ts

@@ -0,0 +1,16 @@
+/**
+ * Package version
+ * Uses npm_package_version when available (npm scripts), falls back to package.json
+ */
+
+export const VERSION: string = process.env.npm_package_version ?? (() => {
+  // Fallback: read from package.json at runtime (for direct node execution)
+  // Uses process.cwd() to avoid dist folder path issues
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const pkg = require(`${process.cwd()}/package.json`) as { version: string };
+    return pkg.version;
+  } catch {
+    return 'dev';
+  }
+})();

package/tests/server/auth.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Authentication middleware tests
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createAuthMiddleware } from '../../src/server/auth.js';
+
+vi.mock('../../src/utils/logger.js');
+
+describe('Auth Middleware', () => {
+  let mockReq: Partial<IncomingMessage>;
+  let mockRes: Partial<ServerResponse>;
+  let responseData: { statusCode?: number; headers: Record<string, string>; body?: string };
+
+  beforeEach(() => {
+    responseData = { headers: {} };
+
+    mockReq = {
+      url: '/api/states',
+      method: 'GET',
+      headers: {},
+      socket: { remoteAddress: '127.0.0.1' } as any,
+    };
+
+    mockRes = {
+      statusCode: 200,
+      setHeader: vi.fn((key: string, value: string) => {
+        responseData.headers[key] = value;
+        return mockRes as ServerResponse;
+      }),
+      end: vi.fn((body?: string) => {
+        responseData.body = body;
+        return mockRes as ServerResponse;
+      }) as unknown as ServerResponse['end'],
+    };
+
+    Object.defineProperty(mockRes, 'statusCode', {
+      get: () => responseData.statusCode,
+      set: (val) => { responseData.statusCode = val; },
+    });
+  });
+
+  describe('No Auth', () => {
+    it('should allow all requests when method is none', () => {
+      const middleware = createAuthMiddleware({ method: 'none' });
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+      expect(mockRes.end).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Bearer Auth', () => {
+    const validTokens = new Set(['test-token-123', 'another-token']);
+
+    it('should allow request with valid token', () => {
+      mockReq.headers = { authorization: 'Bearer test-token-123' };
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: validTokens });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+      expect(mockRes.end).not.toHaveBeenCalled();
+    });
+
+    it('should allow request with any valid token from set', () => {
+      mockReq.headers = { authorization: 'Bearer another-token' };
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: validTokens });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+    });
+
+    it('should reject request without Authorization header', () => {
+      mockReq.headers = {};
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: validTokens });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(false);
+      expect(responseData.statusCode).toBe(401);
+      expect(responseData.headers['WWW-Authenticate']).toBe('Bearer');
+      expect(responseData.body).toContain('Missing Authorization header');
+    });
+
+    it('should reject request with invalid token', () => {
+      mockReq.headers = { authorization: 'Bearer wrong-token' };
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: validTokens });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(false);
+      expect(responseData.statusCode).toBe(401);
+      expect(responseData.headers['WWW-Authenticate']).toBe('Bearer error="invalid_token"');
+      expect(responseData.body).toContain('Invalid token');
+    });
+
+    it('should reject request with malformed Authorization header', () => {
+      mockReq.headers = { authorization: 'Basic dXNlcjpwYXNz' };
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: validTokens });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(false);
+      expect(responseData.statusCode).toBe(401);
+      expect(responseData.body).toContain('Invalid Authorization header format');
+    });
+
+    it('should return 500 if bearer auth enabled but no tokens configured', () => {
+      mockReq.headers = { authorization: 'Bearer test-token' };
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens: undefined });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(false);
+      expect(responseData.statusCode).toBe(500);
+      expect(responseData.body).toContain('auth token not set');
+    });
+  });
+
+  describe('Skip Paths', () => {
+    const validTokens = new Set(['secret-token']);
+
+    it('should skip auth for exact path match', () => {
+      mockReq.url = '/health';
+      mockReq.headers = {}; // No auth header
+      const middleware = createAuthMiddleware({
+        method: 'bearer',
+        tokens: validTokens,
+        skipPaths: ['/health'],
+      });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+    });
+
+    it('should skip auth for path prefix', () => {
+      mockReq.url = '/health/detailed';
+      mockReq.headers = {};
+      const middleware = createAuthMiddleware({
+        method: 'bearer',
+        tokens: validTokens,
+        skipPaths: ['/health'],
+      });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+    });
+
+    it('should require auth for non-skipped paths', () => {
+      mockReq.url = '/api/states';
+      mockReq.headers = {};
+      const middleware = createAuthMiddleware({
+        method: 'bearer',
+        tokens: validTokens,
+        skipPaths: ['/health'],
+      });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(false);
+      expect(responseData.statusCode).toBe(401);
+    });
+
+    it('should handle query strings in URL', () => {
+      mockReq.url = '/health?check=true';
+      mockReq.headers = {};
+      const middleware = createAuthMiddleware({
+        method: 'bearer',
+        tokens: validTokens,
+        skipPaths: ['/health'],
+      });
+
+      const result = middleware(mockReq as IncomingMessage, mockRes as ServerResponse);
+
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('Multi-token Support', () => {
+    it('should support multiple tokens for different clients', () => {
+      const tokens = new Set(['n8n-token', 'openwebui-token', 'cli-token']);
+      const middleware = createAuthMiddleware({ method: 'bearer', tokens });
+
+      // n8n client
+      mockReq.headers = { authorization: 'Bearer n8n-token' };
+      expect(middleware(mockReq as IncomingMessage, mockRes as ServerResponse)).toBe(true);
+
+      // Open WebUI client
+      mockReq.headers = { authorization: 'Bearer openwebui-token' };
+      expect(middleware(mockReq as IncomingMessage, mockRes as ServerResponse)).toBe(true);
+
+      // CLI client
+      mockReq.headers = { authorization: 'Bearer cli-token' };
+      expect(middleware(mockReq as IncomingMessage, mockRes as ServerResponse)).toBe(true);
+
+      // Invalid client
+      mockReq.headers = { authorization: 'Bearer unknown-token' };
+      expect(middleware(mockReq as IncomingMessage, mockRes as ServerResponse)).toBe(false);
+    });
+  });
+});