@coffeerunhobby/mcp-ha-connect 1.2.0 → 1.3.0

package/src/config.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { isValidBindAddress, isValidOrigin } from './utils/config-validations.js';
+import { isValidBindAddress, isValidOrigin, isLoopbackAddress } from './utils/config-validations.js';
 import { parsePermissionsConfig, type PermissionsConfig } from './permissions/index.js';
 import { logger } from './utils/logger.js';
 import type { AIProviderType } from './localAI/types.js';
@@ -64,6 +64,7 @@ const envSchema = z
     httpHealthcheckPath: z.string().optional(),
     httpAllowCors: createBooleanStringSchema(true),
     httpAllowedOrigins: z.string().optional().transform((v) => v?.split(',').map((s) => s.trim()).filter(Boolean)),
+    httpAllowedHosts: z.string().optional().transform((v) => v?.split(',').map((s) => s.trim()).filter(Boolean)),
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: createBooleanStringSchema(true),
@@ -73,10 +74,18 @@ const envSchema = z
     rateLimitEnabled: createBooleanStringSchema(true),
     rateLimitWindowMs: numericStringSchema,
     rateLimitMaxRequests: numericStringSchema,
+    // M4: immediate-peer IPs whose forwarding headers may be trusted (CSV).
+    rateLimitTrustedProxies: z
+      .string()
+      .optional()
+      .transform((v) => v?.split(',').map((s) => s.trim()).filter(Boolean)),
 
     // Authentication Configuration
     authMethod: z.enum(['none', 'bearer']).optional().default('none'),
     authSecret: z.string().optional(),
+    authRequireExp: createBooleanStringSchema(false),
+    authIssuer: z.string().min(1).optional(),
+    authAudience: z.string().min(1).optional(),
     permissionsConfig: z.string().optional(),
   })
   .refine(
@@ -121,6 +130,41 @@ const envSchema = z
       message: 'MCP_AUTH_SECRET is required when MCP_AUTH_METHOD is "bearer"',
       path: ['authSecret'],
     }
+  )
+  .refine(
+    (data) => {
+      // M8: a weak signing secret undermines the whole bearer scheme.
+      if (data.authMethod === 'bearer' && data.authSecret && data.authSecret.length < 32) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'MCP_AUTH_SECRET must be at least 32 characters when MCP_AUTH_METHOD is "bearer"',
+      path: ['authSecret'],
+    }
+  )
+  .refine(
+    (data) => {
+      // H5: an unauthenticated server must never be reachable off-host. Allow
+      // method=none only when the (explicit) bind address is loopback. A missing
+      // bind address defaults to 127.0.0.1 later, so it is safe.
+      if (
+        data.authMethod === 'none' &&
+        data.httpBindAddr &&
+        !isLoopbackAddress(data.httpBindAddr)
+      ) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message:
+        'MCP_AUTH_METHOD=none is only permitted on a loopback bind address ' +
+        '(127.0.0.0/8 or ::1). Set MCP_AUTH_METHOD=bearer (with MCP_AUTH_SECRET) ' +
+        'to bind a public interface such as 0.0.0.0.',
+      path: ['authMethod'],
+    }
   );
 
 export interface EnvironmentConfig {
@@ -165,6 +209,12 @@ export interface EnvironmentConfig {
   httpHealthcheckPath?: string;
   httpAllowCors: boolean;
   httpAllowedOrigins?: string[];
+  /**
+   * Opt-in list of Host-header values (host[:port]) the server is reached by.
+   * When set, DNS-rebinding Host validation is enforced at the transport (M3);
+   * when unset, Host validation is OFF (origin/CORS is handled separately).
+   */
+  httpAllowedHosts?: string[];
 
   // SSE Event Subscription Configuration
   sseEventsEnabled: boolean;
@@ -174,10 +224,14 @@ export interface EnvironmentConfig {
   rateLimitEnabled: boolean;
   rateLimitWindowMs: number;
   rateLimitMaxRequests: number;
+  rateLimitTrustedProxies?: string[];
 
   // Authentication Configuration
   authMethod: 'none' | 'bearer';
   authSecret?: string;
+  authRequireExp: boolean;
+  authIssuer?: string;
+  authAudience?: string;
   permissions: PermissionsConfig;
 }
 
@@ -224,6 +278,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     httpHealthcheckPath: env.MCP_HTTP_HEALTHCHECK_PATH,
     httpAllowCors: env.MCP_HTTP_ALLOW_CORS,
     httpAllowedOrigins: env.MCP_HTTP_ALLOWED_ORIGINS,
+    httpAllowedHosts: env.MCP_HTTP_ALLOWED_HOSTS,
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: env.MCP_SSE_EVENTS_ENABLED,
@@ -233,10 +288,14 @@ 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,
+    rateLimitTrustedProxies: env.MCP_RATE_LIMIT_TRUSTED_PROXIES,
 
     // Authentication Configuration
     authMethod: env.MCP_AUTH_METHOD,
     authSecret: env.MCP_AUTH_SECRET,
+    authRequireExp: env.MCP_AUTH_REQUIRE_EXP,
+    authIssuer: env.MCP_AUTH_ISSUER,
+    authAudience: env.MCP_AUTH_AUDIENCE,
     permissionsConfig: env.MCP_PERMISSIONS_CONFIG,
   });
 
@@ -247,13 +306,29 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
 
   const httpPath = parsed.data.httpPath ?? '/mcp';
   const httpBindAddr = parsed.data.httpBindAddr ?? '127.0.0.1';
-  let httpAllowedOrigins = parsed.data.httpAllowedOrigins ?? ['127.0.0.1', 'localhost'];
+  const httpPort = parsed.data.httpPort ?? 3000;
+
+  // M3: default origins must be full scheme://host:port so they actually match a
+  // real browser `Origin` header (the SDK compares it by exact string). Bare
+  // hostnames like "localhost" never match "http://localhost:3000" and so left
+  // DNS-rebinding/CORS protection effectively disabled for the default config.
+  let httpAllowedOrigins =
+    parsed.data.httpAllowedOrigins ??
+    [`http://localhost:${httpPort}`, `http://127.0.0.1:${httpPort}`];
 
   if (httpAllowedOrigins.includes('*')) {
     logger.warn('Wildcard (*) origin allowed - origin validation disabled');
     httpAllowedOrigins = [];
   }
 
+  // H5: make the no-auth posture loud even when the bind is loopback.
+  if (parsed.data.authMethod === 'none') {
+    logger.warn(
+      'MCP_AUTH_METHOD=none: authentication is DISABLED. This is only permitted ' +
+        'on a loopback bind; set MCP_AUTH_METHOD=bearer to expose the server.'
+    );
+  }
+
   return {
     // Plugin Enable Flags
     haPluginEnabled: parsed.data.haPluginEnabled,
@@ -289,13 +364,14 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     stateful: parsed.data.stateful,
 
     // MCP Server HTTP Configuration
-    httpPort: parsed.data.httpPort,
+    httpPort,
     httpBindAddr,
     httpPath,
     httpEnableHealthcheck: parsed.data.httpEnableHealthcheck,
     httpHealthcheckPath: parsed.data.httpHealthcheckPath,
     httpAllowCors: parsed.data.httpAllowCors,
     httpAllowedOrigins,
+    httpAllowedHosts: parsed.data.httpAllowedHosts,
 
     // SSE Event Subscription Configuration
     sseEventsEnabled: parsed.data.sseEventsEnabled,
@@ -305,10 +381,14 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     rateLimitEnabled: parsed.data.rateLimitEnabled,
     rateLimitWindowMs: parsed.data.rateLimitWindowMs ?? 60000,
     rateLimitMaxRequests: parsed.data.rateLimitMaxRequests ?? 100,
+    rateLimitTrustedProxies: parsed.data.rateLimitTrustedProxies,
 
     // Authentication Configuration
     authMethod: parsed.data.authMethod,
     authSecret: parsed.data.authSecret,
+    authRequireExp: parsed.data.authRequireExp,
+    authIssuer: parsed.data.authIssuer,
+    authAudience: parsed.data.authAudience,
     permissions: parsePermissionsConfig(parsed.data.permissionsConfig),
   };
 }

package/src/haClient/automations.ts

@@ -162,7 +162,7 @@ export class AutomationOperations {
     logger.info('Creating automation', { alias: config.alias, id: automationId });
 
     // POST to /config/automation/config/{id} - the ID must be in the URL path
-    await this.request.post<{ result: string }>(`/config/automation/config/${automationId}`, {
+    await this.request.post<{ result: string }>(`/config/automation/config/${encodeURIComponent(automationId)}`, {
       id: automationId,
       alias: config.alias,
       description: config.description || '',
@@ -224,6 +224,6 @@ export class AutomationOperations {
     const automationId = entityId.replace('automation.', '');
     logger.debug('Fetching automation trace', { automationId });
 
-    return this.request.get<unknown[]>(`/trace/automation/${automationId}`);
+    return this.request.get<unknown[]>(`/trace/automation/${encodeURIComponent(automationId)}`);
   }
 }

package/src/haClient/calendars.ts

@@ -54,7 +54,7 @@ export class CalendarOperations {
 
     // Calendar events use a special API endpoint, not the standard services API
     const events = await this.request.get<CalendarEvent[]>(
-      `/calendars/${entityId}`,
+      `/calendars/${encodeURIComponent(entityId)}`,
       {
         start: start.toISOString(),
         end: end.toISOString(),

package/src/haClient/request.ts

@@ -3,10 +3,11 @@
  * Handles authentication and HTTP requests
  */
 
-import https from 'https';
+import type { Dispatcher } from 'undici';
 import type { RequestOptions } from '../types/index.js';
 import { AuthenticationError, ApiError } from '../types/index.js';
 import { logger } from '../utils/logger.js';
+import { createTlsDispatcher, type FetchInitWithDispatcher } from '../utils/tlsDispatcher.js';
 
 export interface RequestHandlerConfig {
   baseUrl: string;
@@ -19,7 +20,8 @@ export interface RequestHandlerConfig {
  * HTTP request handler for Home Assistant API calls.
  */
 export class RequestHandler {
-  private httpsAgent?: https.Agent;
+  /** Per-client undici dispatcher; set only when strictSsl is disabled (H2). */
+  private dispatcher?: Dispatcher;
   private baseUrl: string;
   private token: string;
   private timeout: number;
@@ -29,11 +31,11 @@ export class RequestHandler {
     this.token = config.token;
     this.timeout = config.timeout;
 
-    // Create HTTPS agent with custom SSL settings
-    if (!config.strictSsl) {
-      this.httpsAgent = new https.Agent({
-        rejectUnauthorized: false,
-      });
+    // Relax TLS validation for THIS client only, via a per-instance undici
+    // dispatcher. Node's global fetch ignores the legacy `agent` option, so the
+    // previous https.Agent was silently a no-op for self-signed HA instances.
+    this.dispatcher = createTlsDispatcher(config.strictSsl);
+    if (this.dispatcher) {
       logger.warn('SSL certificate validation is disabled');
     }
   }
@@ -44,6 +46,13 @@ export class RequestHandler {
   async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
     const url = new URL(`${this.baseUrl}/api${path}`);
 
+    // H4 defense-in-depth: refuse any path that resolves outside /api/.
+    // Call sites encode user-controlled segments, but this guard catches any
+    // raw "../" traversal that would otherwise escape the API namespace.
+    if (url.pathname !== '/api' && !url.pathname.startsWith('/api/')) {
+      throw new ApiError('Invalid API path', 400, { path });
+    }
+
     // Add query parameters
     if (options.params) {
       Object.entries(options.params).forEach(([key, value]) => {
@@ -64,14 +73,17 @@ export class RequestHandler {
     });
 
     try {
-      const response = await fetch(url.toString(), {
+      const init: FetchInitWithDispatcher = {
         method: options.method ?? 'GET',
         headers,
         body: options.body ? JSON.stringify(options.body) : undefined,
-        // @ts-expect-error - agent is valid but not in types
-        agent: this.httpsAgent,
         signal: AbortSignal.timeout(this.timeout),
-      });
+      };
+      if (this.dispatcher) {
+        init.dispatcher = this.dispatcher;
+      }
+
+      const response = await fetch(url.toString(), init);
 
       if (!response.ok) {
         const errorText = await response.text();

package/src/haClient/services.ts

@@ -23,7 +23,7 @@ export class ServiceOperations {
       hasTarget: !!data.target,
     });
 
-    const path = `/services/${data.domain}/${data.service}`;
+    const path = `/services/${encodeURIComponent(data.domain)}/${encodeURIComponent(data.service)}`;
     const body = {
       ...data.service_data,
       ...data.target,

package/src/haClient/states.ts

@@ -31,7 +31,7 @@ export class StateOperations {
     logger.debug('Fetching state', { entityId });
 
     try {
-      const state = await this.request.get<Entity>(`/states/${entityId}`);
+      const state = await this.request.get<Entity>(`/states/${encodeURIComponent(entityId)}`);
       return state;
     } catch (error) {
       if (error instanceof ApiError && error.statusCode === 404) {

package/src/omadaClient/auth.ts

@@ -1,5 +1,7 @@
+import type { Dispatcher } from 'undici';
 import type { OmadaApiResponse, TokenResult } from '../types/index.js';
 import { logger } from '../utils/logger.js';
+import { createTlsDispatcher, type FetchInitWithDispatcher } from '../utils/tlsDispatcher.js';
 
 const TOKEN_EXPIRY_BUFFER_SECONDS = 30;
 
@@ -27,7 +29,8 @@ export class AuthManager {
     private readonly clientSecret: string;
     private readonly omadacId: string;
     private readonly timeout: number;
-    private readonly strictSsl: boolean;
+    /** Per-client undici dispatcher; set only when strictSsl is disabled (H2). */
+    private readonly dispatcher?: Dispatcher;
 
     constructor(config: AuthManagerConfig) {
         this.baseUrl = config.baseUrl;
@@ -35,7 +38,7 @@ export class AuthManager {
         this.clientSecret = config.clientSecret;
         this.omadacId = config.omadacId;
         this.timeout = config.timeout ?? 30000;
-        this.strictSsl = config.strictSsl ?? true;
+        this.dispatcher = createTlsDispatcher(config.strictSsl);
     }
 
     /**
@@ -100,34 +103,23 @@ export class AuthManager {
         }
 
         try {
-            // For self-signed certificates, we need to temporarily disable TLS validation
-            // Node.js native fetch doesn't support the `agent` option like axios/node-fetch
-            const originalRejectUnauthorized = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-            if (!this.strictSsl) {
-                process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+            // For self-signed certificates we relax TLS validation for THIS client
+            // only, via a per-instance undici dispatcher (H2) — never by toggling the
+            // process-global NODE_TLS_REJECT_UNAUTHORIZED env var.
+            const init: FetchInitWithDispatcher = {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeout),
+            };
+            if (this.dispatcher) {
+                init.dispatcher = this.dispatcher;
             }
 
-            let response: Response;
-            try {
-                response = await fetch(url.toString(), {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Accept: 'application/json',
-                    },
-                    body: JSON.stringify(body),
-                    signal: AbortSignal.timeout(this.timeout),
-                });
-            } finally {
-                // Restore original setting
-                if (!this.strictSsl) {
-                    if (originalRejectUnauthorized === undefined) {
-                        delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-                    } else {
-                        process.env.NODE_TLS_REJECT_UNAUTHORIZED = originalRejectUnauthorized;
-                    }
-                }
-            }
+            const response = await fetch(url.toString(), init);
 
             if (!response.ok) {
                 const errorText = await response.text();

package/src/omadaClient/request.ts

@@ -1,5 +1,7 @@
+import type { Dispatcher } from 'undici';
 import type { OmadaApiResponse, PaginatedResult } from '../types/index.js';
 import { logger } from '../utils/logger.js';
+import { createTlsDispatcher, type FetchInitWithDispatcher } from '../utils/tlsDispatcher.js';
 
 import type { AuthManager } from './auth.js';
 
@@ -25,7 +27,8 @@ export interface RequestHandlerConfig {
 export class RequestHandler {
     private readonly baseUrl: string;
     private readonly timeout: number;
-    private readonly strictSsl: boolean;
+    /** Per-client undici dispatcher; set only when strictSsl is disabled (H2). */
+    private readonly dispatcher?: Dispatcher;
 
     constructor(
         config: RequestHandlerConfig,
@@ -33,7 +36,7 @@ export class RequestHandler {
     ) {
         this.baseUrl = config.baseUrl;
         this.timeout = config.timeout ?? 30000;
-        this.strictSsl = config.strictSsl ?? true;
+        this.dispatcher = createTlsDispatcher(config.strictSsl);
     }
 
     /**
@@ -98,31 +101,22 @@ export class RequestHandler {
         });
 
         try {
-            // For self-signed certificates, we need to temporarily disable TLS validation
-            // Node.js native fetch doesn't support the `agent` option like axios/node-fetch
-            const originalRejectUnauthorized = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-            if (!this.strictSsl) {
-                process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+            // For self-signed certificates we relax TLS validation for THIS client
+            // only, via a per-instance undici dispatcher (H2). Node's global fetch
+            // ignores the legacy `agent` option, and toggling the process-global
+            // NODE_TLS_REJECT_UNAUTHORIZED env var would disable validation for every
+            // concurrent outbound request in the process.
+            const init: FetchInitWithDispatcher = {
+                method,
+                headers,
+                body: config.data ? JSON.stringify(config.data) : undefined,
+                signal: AbortSignal.timeout(this.timeout),
+            };
+            if (this.dispatcher) {
+                init.dispatcher = this.dispatcher;
             }
 
-            let response: Response;
-            try {
-                response = await fetch(url.toString(), {
-                    method,
-                    headers,
-                    body: config.data ? JSON.stringify(config.data) : undefined,
-                    signal: AbortSignal.timeout(this.timeout),
-                });
-            } finally {
-                // Restore original setting
-                if (!this.strictSsl) {
-                    if (originalRejectUnauthorized === undefined) {
-                        delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
-                    } else {
-                        process.env.NODE_TLS_REJECT_UNAUTHORIZED = originalRejectUnauthorized;
-                    }
-                }
-            }
+            const response = await fetch(url.toString(), init);
 
             logger.info('Omada response', {
                 method,

package/src/server/auth.ts

@@ -5,7 +5,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { verifyJwt, type JwtPayload } from '../utils/jwt.js';
-import { getUserPermissions, type PermissionsConfig } from '../permissions/index.js';
+import { getUserPermissions, Role, type PermissionsConfig } from '../permissions/index.js';
 import { logger } from '../utils/logger.js';
 
 export type AuthMethod = 'none' | 'bearer';
@@ -15,8 +15,17 @@ export interface AuthConfig {
   secret?: string;
   permissions?: PermissionsConfig;
   skipPaths?: string[];
+  /** Reject tokens without an exp claim (H3). */
+  requireExp?: boolean;
+  /** Expected JWT issuer, if any (L6). */
+  issuer?: string;
+  /** Expected JWT audience, if any (L6). */
+  audience?: string;
 }
 
+/** Emit the "no exp" advisory at most once per process. */
+let warnedNoExp = false;
+
 export interface AuthResult {
   authenticated: boolean;
   payload?: JwtPayload;
@@ -32,7 +41,18 @@ export interface AuthenticatedRequest extends IncomingMessage {
 /**
  * Validate JWT from Authorization header
  */
-function validateJwt(req: IncomingMessage, secret: string, permConfig?: PermissionsConfig): AuthResult {
+interface ClaimPolicy {
+  requireExp?: boolean;
+  issuer?: string;
+  audience?: string;
+}
+
+function validateJwt(
+  req: IncomingMessage,
+  secret: string,
+  permConfig?: PermissionsConfig,
+  policy: ClaimPolicy = {}
+): AuthResult {
   const authHeader = req.headers.authorization;
 
   if (!authHeader) {
@@ -44,16 +64,30 @@ function validateJwt(req: IncomingMessage, secret: string, permConfig?: Permissi
   }
 
   const token = authHeader.slice(7);
-  const result = verifyJwt(token, secret);
+  const result = verifyJwt(token, secret, {
+    requireExp: policy.requireExp,
+    issuer: policy.issuer,
+    audience: policy.audience,
+    clockSkewSec: 60,
+  });
 
   if (!result.valid) {
     return { authenticated: false, error: result.error };
   }
 
-  // Get user permissions from config
+  // H3: warn (once) when accepting a token that can never expire.
+  if (!policy.requireExp && result.payload?.exp === undefined && !warnedNoExp) {
+    warnedNoExp = true;
+    logger.warn('Accepting a JWT without an exp claim; set MCP_AUTH_REQUIRE_EXP=true to enforce token expiry');
+  }
+
+  // Get user permissions from config.
+  // L3: fail closed when no permission map is configured — an authenticated token
+  // with no RBAC mapping gets NONE, never full access. (In the real server path
+  // `permConfig` is always supplied by loadConfig, so this is defense in depth.)
   const permissions = permConfig
     ? getUserPermissions(result.payload?.sub, permConfig)
-    : 0xFF; // No config = all permissions
+    : Role.NONE;
 
   return { authenticated: true, payload: result.payload, permissions };
 }
@@ -63,7 +97,7 @@ function validateJwt(req: IncomingMessage, secret: string, permConfig?: Permissi
  * Returns true if request should proceed, false if blocked
  */
 export function createAuthMiddleware(config: AuthConfig): (req: IncomingMessage, res: ServerResponse) => boolean {
-  const { method, secret, permissions: permConfig, skipPaths = [] } = config;
+  const { method, secret, permissions: permConfig, skipPaths = [], requireExp, issuer, audience } = config;
 
   return (req: IncomingMessage, res: ServerResponse): boolean => {
     if (method === 'none') {
@@ -95,7 +129,7 @@ export function createAuthMiddleware(config: AuthConfig): (req: IncomingMessage,
         return false;
       }
 
-      const result = validateJwt(req, secret, permConfig);
+      const result = validateJwt(req, secret, permConfig, { requireExp, issuer, audience });
 
       if (!result.authenticated) {
         logger.warn('Auth failed', { path, error: result.error, ip: req.socket.remoteAddress });

package/src/server/eventSubscription.ts

@@ -4,8 +4,12 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
 import type { EventSubscriber, HaEvent } from '../haClient/events.js';
 import { logger } from '../utils/logger.js';
+import { sanitizeError } from '../utils/sanitizeError.js';
+import { Permission, hasPermission } from '../permissions/index.js';
+import type { AuthenticatedRequest } from './auth.js';
 
 export interface SSEClient {
   id: string;
@@ -22,6 +26,17 @@ export interface SSEClient {
 // Store active SSE clients
 const clients = new Map<string, SSEClient>();
 
+/**
+ * Generate an unguessable SSE client ID (L5).
+ *
+ * Uses a CSPRNG (randomUUID) rather than Math.random()/Date.now(), so a client
+ * ID cannot be predicted or enumerated by an observer who knows roughly when a
+ * connection was opened.
+ */
+export function generateClientId(): string {
+  return randomUUID();
+}
+
 /**
  * Parse query parameters from URL
  */
@@ -64,7 +79,17 @@ export async function handleEventSubscription(
   res: ServerResponse,
   eventSubscriber: EventSubscriber
 ): Promise<void> {
-  const clientId = `sse_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  // L2: the SSE stream reads entity state — require QUERY, like every other read.
+  // Auth middleware has already populated req.auth; fail closed if the mask is absent.
+  const userPermissions = ((req as AuthenticatedRequest).auth?.extra?.permissions as number | undefined) ?? 0;
+  if (!hasPermission(userPermissions, Permission.QUERY)) {
+    logger.warn('SSE subscription denied: missing QUERY permission');
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Forbidden', message: 'SSE event subscription requires QUERY permission' }));
+    return;
+  }
+
+  const clientId = generateClientId();
   const params = parseQueryParams(req.url ?? '');
 
   // Parse filter parameters
@@ -72,14 +97,12 @@ export async function handleEventSubscription(
   const entityId = params.get('entity_id') ?? undefined;
   const eventTypesParam = params.get('event_types');
   const eventTypes = eventTypesParam ? eventTypesParam.split(',').map(t => t.trim()) : undefined;
-  const token = params.get('token');
 
   logger.info('New SSE subscription request', {
     clientId,
     domain,
     entityId,
     eventTypes,
-    hasToken: !!token,
   });
 
   // Set SSE headers
@@ -119,9 +142,10 @@ export async function handleEventSubscription(
       await eventSubscriber.connect();
     } catch (error) {
       logger.error('Failed to connect event subscriber', { error });
+      // M6: log detail above; the SSE client gets a generic message only.
       sendSSEEvent(res, 'error', {
         error: 'Failed to connect to Home Assistant',
-        message: error instanceof Error ? error.message : String(error),
+        message: sanitizeError(error),
       });
       res.end();
       clients.delete(clientId);
@@ -191,9 +215,10 @@ export async function handleEventSubscription(
     });
   } catch (error) {
     logger.error('Failed to subscribe to events', { error, clientId });
+    // M6: log detail above; the SSE client gets a generic message only.
     sendSSEEvent(res, 'error', {
       error: 'Failed to subscribe to events',
-      message: error instanceof Error ? error.message : String(error),
+      message: sanitizeError(error),
     });
   }