homebridge 2.0.0-alpha.6 → 2.0.0-alpha.60

package/dist/matter/matterServer.js

@@ -0,0 +1,1623 @@
+/**
+ * Matter.js Server Implementation for Homebridge Plugin API
+ *
+ * This provides a Matter bridge that plugins can use to register
+ * Matter accessories via the Homebridge API.
+ */
+import { randomBytes } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { constants, existsSync } from 'node:fs';
+import { access, writeFile } from 'node:fs/promises';
+import { homedir, release } from 'node:os';
+import { join, normalize, resolve } from 'node:path';
+import process from 'node:process';
+import { Endpoint, Environment, Logger as MatterLogger, LogLevel as MatterLogLevel, ServerNode, StorageService, VendorId, } from '@matter/main';
+import { WindowCoveringServer } from '@matter/main/behaviors';
+import * as devices from '@matter/main/devices';
+import { AggregatorEndpoint } from '@matter/main/endpoints';
+import { ManualPairingCodeCodec, QrPairingCodeCodec } from '@matter/types/schema';
+import fse from 'fs-extra';
+import QRCode from 'qrcode-terminal';
+import { Logger } from '../logger.js';
+import getVersion from '../version.js';
+import { MatterAccessoryCache } from './matterAccessoryCache.js';
+import { HomebridgeColorControlServer, HomebridgeDoorLockServer, HomebridgeIdentifyServer, HomebridgeLevelControlServer, HomebridgeOnOffServer, HomebridgeRvcCleanModeServer, HomebridgeRvcOperationalStateServer, HomebridgeRvcRunModeServer, HomebridgeServiceAreaServer, HomebridgeThermostatServer, HomebridgeWindowCoveringServer, registerHandler, setAccessoriesMap, } from './matterBehaviors.js';
+import { sanitizeUniqueId, truncateString, validatePort } from './matterConfigValidator.js';
+import { errorHandler } from './matterErrorHandler.js';
+import { createHomebridgeLogFormatter } from './matterLogFormatter.js';
+import { networkMonitor } from './matterNetworkMonitor.js';
+import { MatterStorageManager } from './matterStorage.js';
+import { clusters, deviceTypes, MatterDeviceError, } from './matterTypes.js';
+const log = Logger.withPrefix('Matter/Server');
+// Constants for Matter server configuration
+const DEFAULT_MATTER_PORT = 5540;
+const DEFAULT_VENDOR_ID = 0xFFF1; // Test vendor ID from Matter spec
+const DEFAULT_PRODUCT_ID = 0x8001; // Test product ID
+const MAX_DEVICES_PER_BRIDGE = 1000; // Matter spec maximum devices per aggregator
+const SERVER_READY_TIMEOUT_MS = 5000;
+const SERVER_READY_POLL_INTERVAL_MS = 100;
+const SERVER_INIT_DELAY_MS = 200;
+const MAX_PASSCODE_ATTEMPTS = 100;
+const FABRIC_MONITOR_INTERVAL_MS = 2000; // Check for fabric changes every 2 seconds
+/**
+ * Matter Server for Homebridge Plugin API
+ * Allows plugins to register Matter accessories explicitly
+ *
+ * Extends EventEmitter to provide commissioning lifecycle events
+ */
+export class MatterServer extends EventEmitter {
+    config;
+    serverNode = null;
+    aggregator = null;
+    accessories = new Map();
+    isRunning = false;
+    MAX_DEVICES = MAX_DEVICES_PER_BRIDGE;
+    shutdownHandler = null;
+    // Internal commissioning values (generated, not user-configurable)
+    passcode = 0;
+    discriminator = 0;
+    vendorId;
+    productId;
+    commissioningInfo = {};
+    serialNumber;
+    cleanupHandlers = [];
+    storageManager = null;
+    matterStoragePath;
+    accessoryCache = null;
+    // Fabric monitoring
+    fabricMonitorInterval = null;
+    previousFabrics = new Map();
+    constructor(config) {
+        super();
+        // Store the validated config
+        this.config = this.validateAndSanitizeConfig(config);
+        // Configure Matter.js library logging
+        // Suppress DEBUG/INFO logs from Matter.js library unless debug mode is explicitly enabled
+        if (this.config.debugModeEnabled) {
+            log.info('Matter debug mode enabled - verbose logging active');
+            MatterLogger.level = MatterLogLevel.DEBUG;
+        }
+        else {
+            MatterLogger.level = MatterLogLevel.NOTICE;
+        }
+        // Set custom log format to match homebridge format:
+        // [DD/MM/YYYY, HH:MM:SS] [Matter/Facility] message
+        MatterLogger.format = createHomebridgeLogFormatter();
+        // Redirect all Matter.js logs to console.log to prevent console.debug() suppression
+        // Matter.js uses console.debug() for DEBUG level logs, which is silently ignored in many Node.js environments
+        MatterLogger.destinations.default.write = (text) => {
+            console.log(text); // eslint-disable-line no-console
+        };
+        // Initialize commissioning values (will be loaded from storage in start())
+        this.vendorId = DEFAULT_VENDOR_ID;
+        this.productId = DEFAULT_PRODUCT_ID;
+        // Provide accessories map reference to behaviors for cache syncing
+        setAccessoriesMap(this.accessories);
+    }
+    /**
+     * Validate and sanitize Matter server configuration
+     * Throws descriptive errors if configuration is invalid
+     */
+    validateAndSanitizeConfig(config) {
+        const errors = [];
+        // Validate port
+        const port = config.port || DEFAULT_MATTER_PORT;
+        const portValidation = validatePort(port, false);
+        if (!portValidation.valid) {
+            errors.push(`Invalid port: ${portValidation.error}`);
+        }
+        // Validate and sanitize uniqueId (REQUIRED)
+        if (!config.uniqueId) {
+            errors.push('uniqueId is required for Matter server configuration');
+        }
+        const rawUniqueId = config.uniqueId || '';
+        const uniqueIdResult = sanitizeUniqueId(rawUniqueId);
+        const uniqueId = uniqueIdResult.value;
+        if (uniqueId.length === 0) {
+            errors.push('Invalid uniqueId: must be a non-empty string');
+        }
+        // Validate storagePath (if provided)
+        let storagePath = config.storagePath;
+        if (storagePath !== undefined) {
+            storagePath = resolve(storagePath); // Resolve to absolute path
+        }
+        // Validate and sanitize manufacturer
+        let manufacturer = config.manufacturer;
+        if (manufacturer !== undefined) {
+            manufacturer = truncateString(manufacturer, 32, 'Manufacturer name').value;
+        }
+        // Validate and sanitize model
+        let model = config.model;
+        if (model !== undefined) {
+            model = truncateString(model, 32, 'Model name').value;
+        }
+        // Validate firmwareRevision
+        let firmwareRevision = config.firmwareRevision;
+        if (firmwareRevision !== undefined) {
+            firmwareRevision = truncateString(firmwareRevision, 64, 'Firmware revision').value;
+        }
+        // Validate serialNumber
+        let serialNumber = config.serialNumber;
+        if (serialNumber !== undefined) {
+            serialNumber = truncateString(serialNumber, 32, 'Serial number').value;
+        }
+        // Validate debugModeEnabled
+        const debugModeEnabled = config.debugModeEnabled || false;
+        // Throw if there are validation errors
+        if (errors.length > 0) {
+            throw new MatterDeviceError(`Matter configuration validation failed:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+        }
+        return {
+            port,
+            uniqueId,
+            storagePath,
+            manufacturer,
+            model,
+            firmwareRevision,
+            serialNumber,
+            debugModeEnabled,
+        };
+    }
+    /**
+     * Generate a secure random passcode
+     * According to Matter spec, passcode must be:
+     * - 8 digits (00000001 to 99999998)
+     * - Not in the invalid list
+     * - Not sequential or repeating patterns
+     */
+    generateSecurePasscode() {
+        let passcode;
+        const maxAttempts = MAX_PASSCODE_ATTEMPTS;
+        let attempts = 0;
+        const invalidPasscodes = [
+            0,
+            11111111,
+            22222222,
+            33333333,
+            44444444,
+            55555555,
+            66666666,
+            77777777,
+            88888888,
+            99999999,
+            12345678,
+            87654321,
+        ];
+        do {
+            // Use cryptographically secure random number generation
+            const randomValue = randomBytes(4).readUInt32BE(0);
+            // Generate a value between 1 and 99999998
+            passcode = (randomValue % 99999998) + 1;
+            attempts++;
+            if (attempts > maxAttempts) {
+                throw new Error('Failed to generate secure passcode after maximum attempts');
+            }
+        } while (invalidPasscodes.includes(passcode)
+            || !this.isValidPasscode(passcode));
+        return passcode;
+    }
+    /**
+     * Validate a passcode according to Matter specifications
+     */
+    isValidPasscode(passcode) {
+        // Must be between 1 and 99999998
+        if (passcode < 1 || passcode > 99999998) {
+            return false;
+        }
+        // Convert to 8-digit string
+        const passcodeStr = passcode.toString().padStart(8, '0');
+        // Check for sequential patterns (12345678, 23456789, etc.)
+        let isSequential = true;
+        for (let i = 1; i < passcodeStr.length; i++) {
+            if (Number.parseInt(passcodeStr[i]) !== Number.parseInt(passcodeStr[i - 1]) + 1) {
+                isSequential = false;
+                break;
+            }
+        }
+        if (isSequential) {
+            return false;
+        }
+        // Check for reverse sequential (87654321, 76543210, etc.)
+        let isReverseSequential = true;
+        for (let i = 1; i < passcodeStr.length; i++) {
+            if (Number.parseInt(passcodeStr[i]) !== Number.parseInt(passcodeStr[i - 1]) - 1) {
+                isReverseSequential = false;
+                break;
+            }
+        }
+        if (isReverseSequential) {
+            return false;
+        }
+        // Check for too many repeating digits (more than 3 of same digit)
+        const digitCounts = new Map();
+        for (const digit of passcodeStr) {
+            digitCounts.set(digit, (digitCounts.get(digit) || 0) + 1);
+            if (digitCounts.get(digit) > 3) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Generate a random discriminator
+     * According to Matter spec, discriminator must be:
+     * - 12 bits (0-4095)
+     * - Should be random for security
+     */
+    generateRandomDiscriminator() {
+        // Generate cryptographically secure random 12-bit discriminator (0-4095)
+        const discriminator = randomBytes(2).readUInt16BE(0) & 0x0FFF; // Mask to 12 bits
+        // Validate discriminator range
+        if (discriminator < 0 || discriminator > 4095) {
+            throw new Error(`Invalid discriminator generated: ${discriminator}`);
+        }
+        return discriminator;
+    }
+    /**
+     * Create ServerNode with automatic recovery from corrupted storage
+     *
+     * Matter.js can fail to start if fabric data is corrupted (common after
+     * hard shutdowns or disk errors). This method implements automatic recovery by:
+     *
+     * 1. Attempting normal ServerNode creation
+     * 2. If it fails with storage errors, identifying and removing corrupted files
+     * 3. Retrying ServerNode creation with fresh storage
+     *
+     * This prevents the need for manual intervention while preserving data
+     * safety by only removing storage on confirmed corruption errors.
+     *
+     * @param nodeOptions - Matter.js ServerNode configuration
+     * @param sanitizedId - Filesystem-safe bridge identifier
+     * @returns Initialized ServerNode instance
+     * @throws Error if recovery fails or error is not storage-related
+     */
+    async createServerNodeWithRecovery(nodeOptions, sanitizedId) {
+        try {
+            // First attempt to create ServerNode
+            return await ServerNode.create(nodeOptions);
+        }
+        catch (error) {
+            // Check if this is a storage corruption error
+            const isStorageError = error?.message?.includes('Invalid public key encoding')
+                || error?.message?.includes('FabricManager unavailable')
+                || error?.message?.includes('key-input')
+                || error?.cause?.message?.includes('Invalid public key encoding');
+            if (!isStorageError) {
+                // Not a storage error, rethrow
+                throw error;
+            }
+            // Storage is corrupted - clean up and retry
+            log.warn('Detected corrupted Matter storage, attempting automatic recovery...');
+            // The ServerNodeStore directory is inside our storage path with the same name as the bridge ID
+            const environment = Environment.default;
+            const storageService = environment.get(StorageService);
+            const storageLocation = storageService.location;
+            if (!storageLocation) {
+                throw new Error('Storage location not set, cannot recover from corrupted storage');
+            }
+            const serverNodeStorePath = join(storageLocation, sanitizedId);
+            const serverNodeStoreJsonFile = `${serverNodeStorePath}.json`;
+            try {
+                let removedSomething = false;
+                // Delete the ServerNodeStore subdirectory
+                if (existsSync(serverNodeStorePath)) {
+                    log.info(`Removing corrupted ServerNodeStore directory: ${serverNodeStorePath}`);
+                    await fse.remove(serverNodeStorePath);
+                    removedSomething = true;
+                }
+                // Delete the ServerNodeStore JSON file (contains fabric data)
+                if (existsSync(serverNodeStoreJsonFile)) {
+                    log.info(`Removing corrupted ServerNodeStore JSON file: ${serverNodeStoreJsonFile}`);
+                    await fse.remove(serverNodeStoreJsonFile);
+                    removedSomething = true;
+                }
+                if (removedSomething) {
+                    log.info('Corrupted storage removed, retrying ServerNode creation...');
+                }
+                else {
+                    log.warn('No corrupted storage files found, corruption may be elsewhere');
+                }
+                // Retry ServerNode creation
+                const serverNode = await ServerNode.create(nodeOptions);
+                log.info('Successfully recovered from corrupted Matter storage');
+                return serverNode;
+            }
+            catch (retryError) {
+                log.error('Failed to recover from corrupted storage:', retryError);
+                log.error('Original error:', error);
+                throw new Error('Matter storage is corrupted and automatic recovery failed. '
+                    + `Please manually delete: ${serverNodeStorePath}`);
+            }
+        }
+    }
+    /**
+     * Start the Matter server
+     */
+    async start() {
+        if (this.isRunning) {
+            log.warn('Matter server is already running');
+            return;
+        }
+        try {
+            log.info('Starting Matter.js server...');
+            // IMPORTANT: Storage must be configured BEFORE any Matter.js operations
+            // This ensures persistent fabric data across restarts
+            await this.setupStorage();
+            // Load or generate commissioning credentials
+            await this.loadOrGenerateCredentials();
+            log.info(`Configuration: Port=${this.config.port}, Passcode=${this.passcode}, Discriminator=${this.discriminator}`);
+            // Start network monitoring
+            networkMonitor.startMonitoring();
+            this.cleanupHandlers.push(() => networkMonitor.stopMonitoring());
+            // Create commissioning options
+            const commissioningOptions = {
+                passcode: this.passcode,
+                discriminator: this.discriminator,
+            };
+            log.info(`Using commissioning credentials: passcode=${this.passcode}, discriminator=${this.discriminator}`);
+            // Use default name for the Matter bridge
+            const bridgeName = 'Homebridge Matter Bridge';
+            // uniqueId is already sanitized in validateAndSanitizeConfig()
+            const sanitizedId = this.config.uniqueId;
+            // Create node options with proper typing
+            const nodeOptions = {
+                id: sanitizedId,
+                network: {
+                    port: this.config.port,
+                    ipv4: true, // Always enable IPv4 for Matter
+                },
+                commissioning: commissioningOptions,
+                productDescription: {
+                    name: bridgeName,
+                    deviceType: AggregatorEndpoint.deviceType,
+                },
+                basicInformation: {
+                    nodeLabel: bridgeName.slice(0, 32), // Maximum 32 characters
+                    vendorId: VendorId(this.vendorId),
+                    vendorName: (this.config.manufacturer || 'Homebridge').slice(0, 32),
+                    productId: this.productId,
+                    productName: (this.config.model || 'Homebridge Matter Bridge').slice(0, 32),
+                    productLabel: bridgeName.slice(0, 64), // Maximum 64 characters
+                    serialNumber: this.serialNumber = this.config.serialNumber || this.config.uniqueId,
+                    hardwareVersion: 1,
+                    hardwareVersionString: release(),
+                    softwareVersion: 1,
+                    softwareVersionString: this.config.firmwareRevision || getVersion(),
+                    reachable: true,
+                },
+            };
+            // Create server node with automatic recovery from corrupted storage
+            this.serverNode = await this.createServerNodeWithRecovery(nodeOptions, sanitizedId);
+            // Create aggregator endpoint for bridge pattern
+            this.aggregator = new Endpoint(AggregatorEndpoint, {
+                id: 'homebridge-aggregator',
+            });
+            // Add aggregator to server
+            await this.serverNode.add(this.aggregator);
+            // Generate and display commissioning information
+            await this.generateCommissioningInfo();
+            // Set up graceful shutdown handler
+            this.shutdownHandler = async () => {
+                log.info('Shutting down Matter server...');
+                await this.stop();
+            };
+            // Register shutdown handlers
+            process.on('SIGINT', this.shutdownHandler);
+            process.on('SIGTERM', this.shutdownHandler);
+            // Start the server in a non-blocking way
+            this.serverNode.run().then(() => {
+                log.info('Matter server stopped normally');
+            }, (error) => {
+                log.error('Matter server stopped with error:', error);
+                errorHandler.handleError(error, 'server-runtime');
+            });
+            // Wait for server to be ready
+            await this.waitForServerReady();
+            // Load cached accessories (don't restore them yet - wait for plugins to re-register)
+            if (this.accessoryCache) {
+                const loaded = await this.accessoryCache.load();
+                log.debug(`Matter cache loaded: ${loaded.size} accessories`);
+            }
+            else {
+                log.debug('No accessory cache available');
+            }
+            // Start fabric monitoring to emit commissioning events
+            this.startFabricMonitoring();
+            this.isRunning = true;
+            log.info(`Matter server started successfully on port ${this.config.port}`);
+            log.info('Plugins can now register Matter accessories via the API');
+        }
+        catch (error) {
+            log.error('Failed to start Matter server:', error);
+            await this.cleanup();
+            throw error;
+        }
+    }
+    /**
+     * Set up and validate storage
+     */
+    async setupStorage() {
+        if (!this.config.storagePath) {
+            throw new Error('Storage path is required for Matter server');
+        }
+        // Resolve to absolute path and validate
+        const storagePath = resolve(this.config.storagePath);
+        const normalizedPath = normalize(storagePath);
+        // Ensure path is within allowed directories
+        const allowedBasePaths = [
+            resolve(homedir(), '.homebridge'),
+            resolve(process.cwd()),
+            '/var/lib/homebridge', // Common system location
+        ];
+        const isAllowed = allowedBasePaths.some(basePath => normalizedPath.startsWith(basePath));
+        if (!isAllowed || normalizedPath.includes('..')) {
+            throw new Error(`Storage path not allowed: ${normalizedPath}. Must be within homebridge directories.`);
+        }
+        // Ensure the storage directory exists with proper permissions
+        try {
+            await fse.ensureDir(normalizedPath);
+            await access(normalizedPath, constants.R_OK | constants.W_OK);
+        }
+        catch (error) {
+            throw new Error(`Storage path not accessible: ${error}`);
+        }
+        // Create bridge-specific storage directory
+        // uniqueId is already sanitized in validateAndSanitizeConfig()
+        const bridgeId = this.config.uniqueId || 'default';
+        this.matterStoragePath = join(normalizedPath, bridgeId);
+        await fse.ensureDir(this.matterStoragePath);
+        // Create storage manager
+        this.storageManager = new MatterStorageManager(this.matterStoragePath);
+        // Create accessory cache
+        this.accessoryCache = new MatterAccessoryCache(normalizedPath, bridgeId);
+        // Configure environment to use our custom storage
+        const environment = Environment.default;
+        const storageService = environment.get(StorageService);
+        storageService.location = this.matterStoragePath;
+        // CRITICAL: Override storage factory with custom implementation
+        // This ensures fabric data is properly persisted
+        storageService.factory = (namespace) => {
+            if (!this.storageManager) {
+                throw new Error('Storage manager not initialized');
+            }
+            const storage = this.storageManager.getStorage(namespace);
+            // Initialize asynchronously - Matter.js handles async storage properly
+            storage.initialize().catch((error) => {
+                log.error(`Failed to initialize storage namespace ${namespace}:`, error);
+            });
+            // Note: Cast to unknown first to satisfy TypeScript - our storage implements the required interface
+            return storage;
+        };
+        // Add cleanup handler for storage
+        this.cleanupHandlers.push(async () => {
+            if (this.storageManager) {
+                await this.storageManager.closeAll();
+            }
+        });
+        log.info(`Matter storage initialized at: ${this.matterStoragePath}`);
+    }
+    /**
+     * Load or generate commissioning credentials (passcode and discriminator)
+     * These must be persistent across restarts to maintain the same QR code
+     */
+    async loadOrGenerateCredentials() {
+        if (!this.storageManager) {
+            throw new Error('Storage manager not initialized');
+        }
+        // Use 'credentials' namespace
+        const storage = this.storageManager.getStorage('credentials');
+        // CRITICAL: Initialize storage before reading to avoid race condition
+        await storage.initialize();
+        // Try to load existing credentials
+        const storedPasscode = storage.get([], 'passcode');
+        const storedDiscriminator = storage.get([], 'discriminator');
+        if (storedPasscode && storedDiscriminator) {
+            // Use stored credentials
+            log.info('Loading existing commissioning credentials from storage');
+            this.passcode = storedPasscode;
+            this.discriminator = storedDiscriminator;
+        }
+        else {
+            // Generate new credentials and store them
+            log.info('Generating new commissioning credentials');
+            this.passcode = this.generateSecurePasscode();
+            this.discriminator = this.generateRandomDiscriminator();
+            // Store for future use
+            storage.set([], 'passcode', this.passcode);
+            storage.set([], 'discriminator', this.discriminator);
+            log.info('Commissioning credentials saved to storage');
+        }
+    }
+    /**
+     * Generate and display commissioning information
+     */
+    async generateCommissioningInfo() {
+        const passcode = this.passcode.toString().padStart(8, '0');
+        const discriminator = this.discriminator;
+        const vendorId = this.vendorId;
+        const productId = this.productId;
+        // Use Matter.js library to generate pairing codes properly
+        const manualCode = ManualPairingCodeCodec.encode({
+            discriminator,
+            passcode: this.passcode,
+        });
+        // Format as XXXX-XXX-XXXX for display
+        const manualPairingCode = `${manualCode.slice(0, 4)}-${manualCode.slice(4, 7)}-${manualCode.slice(7, 11)}`;
+        log.info(`Encoding QR code with: passcode=${this.passcode}, discriminator=${discriminator}, vendorId=${vendorId}, productId=${productId}`);
+        const qrCodePayload = QrPairingCodeCodec.encode([{
+                version: 0,
+                vendorId,
+                productId,
+                flowType: 0, // Standard commissioning flow
+                discoveryCapabilities: 4, // OnNetwork=4
+                discriminator,
+                passcode: this.passcode,
+            }]);
+        log.info(`Generated QR code: ${qrCodePayload}`);
+        log.info(`Generated manual code: ${manualPairingCode}`);
+        // Store commissioning info
+        this.commissioningInfo = {
+            qrCode: qrCodePayload,
+            manualPairingCode,
+        };
+        // Save commissioning info to disk for UI access
+        try {
+            if (!this.matterStoragePath) {
+                throw new Error('Matter storage path not initialized');
+            }
+            const commissioningFilePath = join(this.matterStoragePath, 'commissioning.json');
+            const commissioningData = {
+                qrCode: qrCodePayload,
+                manualPairingCode,
+                serialNumber: this.serialNumber,
+                passcode: this.passcode,
+                discriminator: this.discriminator,
+                commissioned: this.isCommissioned(),
+            };
+            await writeFile(commissioningFilePath, JSON.stringify(commissioningData, null, 2), 'utf-8');
+            log.debug(`Saved commissioning info to ${commissioningFilePath}`);
+        }
+        catch (error) {
+            log.warn(`Failed to save commissioning info to disk: ${error.message}`);
+        }
+        // Display commissioning information
+        log.info(`\n${'='.repeat(60)}`);
+        log.info('📱 MATTER COMMISSIONING INFORMATION');
+        log.info('='.repeat(60));
+        log.info(`Manual Pairing Code: ${manualPairingCode}`);
+        log.info(`Passcode: ${passcode}`);
+        log.info(`Discriminator: ${discriminator}`);
+        log.info('\nQR Code for commissioning:');
+        // Generate and display QR code in terminal
+        QRCode.generate(qrCodePayload, { small: true }, (qrcode) => {
+            // eslint-disable-next-line no-console
+            console.log(qrcode);
+        });
+        log.info(`${'='.repeat(60)}\n`);
+    }
+    /**
+     * Wait for the server to be ready
+     */
+    async waitForServerReady(maxWaitTime = SERVER_READY_TIMEOUT_MS) {
+        const startTime = Date.now();
+        while (!this.serverNode || !this.aggregator) {
+            if (Date.now() - startTime > maxWaitTime) {
+                throw new Error('Server failed to become ready within timeout');
+            }
+            await new Promise(resolve => setTimeout(resolve, SERVER_READY_POLL_INTERVAL_MS));
+        }
+        // Additional small delay to ensure everything is initialized
+        await new Promise(resolve => setTimeout(resolve, SERVER_INIT_DELAY_MS));
+    }
+    /**
+     * Start monitoring fabric changes to emit commissioning events
+     */
+    startFabricMonitoring() {
+        // Stop any existing monitor
+        this.stopFabricMonitoring();
+        // Initialize with current fabrics
+        const initialFabrics = this.getFabricInfo();
+        for (const fabric of initialFabrics) {
+            this.previousFabrics.set(fabric.fabricIndex, fabric);
+        }
+        log.debug('Starting fabric monitoring for commissioning events');
+        // Set up periodic monitoring
+        this.fabricMonitorInterval = setInterval(() => {
+            this.checkFabricChanges();
+        }, FABRIC_MONITOR_INTERVAL_MS);
+        // Add to clean up handlers
+        this.cleanupHandlers.push(() => this.stopFabricMonitoring());
+    }
+    /**
+     * Stop fabric monitoring
+     */
+    stopFabricMonitoring() {
+        if (this.fabricMonitorInterval) {
+            clearInterval(this.fabricMonitorInterval);
+            this.fabricMonitorInterval = null;
+            log.debug('Stopped fabric monitoring');
+        }
+    }
+    /**
+     * Check for fabric changes and emit appropriate events
+     */
+    checkFabricChanges() {
+        try {
+            const currentFabrics = this.getFabricInfo();
+            const currentFabricMap = new Map();
+            // Build map of current fabrics
+            for (const fabric of currentFabrics) {
+                currentFabricMap.set(fabric.fabricIndex, fabric);
+            }
+            const previousCount = this.previousFabrics.size;
+            const currentCount = currentFabricMap.size;
+            // Check for added fabrics
+            for (const [fabricIndex, fabric] of currentFabricMap) {
+                if (!this.previousFabrics.has(fabricIndex)) {
+                    log.info(`Fabric added: ${fabric.fabricId} (index: ${fabricIndex})`);
+                    this.emit('fabric-added', fabric);
+                    // If this is the first fabric, emit 'commissioned' event
+                    if (previousCount === 0 && currentCount === 1) {
+                        log.info('Bridge commissioned for the first time');
+                        this.emit('commissioned', fabric);
+                    }
+                }
+            }
+            // Check for removed fabrics
+            for (const [fabricIndex, fabric] of this.previousFabrics) {
+                if (!currentFabricMap.has(fabricIndex)) {
+                    log.info(`Fabric removed: ${fabric.fabricId} (index: ${fabricIndex})`);
+                    this.emit('fabric-removed', fabric);
+                    // If this was the last fabric, emit 'decommissioned' event
+                    if (previousCount === 1 && currentCount === 0) {
+                        log.info('Bridge decommissioned (last fabric removed)');
+                        this.emit('decommissioned');
+                    }
+                }
+            }
+            // Emit general commissioning-changed event if count changed
+            if (previousCount !== currentCount) {
+                const commissioned = currentCount > 0;
+                log.debug(`Commissioning state changed: commissioned=${commissioned}, fabricCount=${currentCount}`);
+                this.emit('commissioning-changed', commissioned, currentCount);
+                // Update commissioning info file
+                this.updateCommissioningFile().catch((error) => {
+                    log.warn('Failed to update commissioning file:', error);
+                });
+            }
+            // Update previous fabrics map
+            this.previousFabrics = currentFabricMap;
+        }
+        catch (error) {
+            log.error('Error checking fabric changes:', error);
+        }
+    }
+    /**
+     * Update commissioning info file when commissioning state changes
+     */
+    async updateCommissioningFile() {
+        try {
+            if (!this.matterStoragePath) {
+                return;
+            }
+            const commissioningFilePath = join(this.matterStoragePath, 'commissioning.json');
+            const commissioningData = {
+                qrCode: this.commissioningInfo.qrCode,
+                manualPairingCode: this.commissioningInfo.manualPairingCode,
+                serialNumber: this.serialNumber,
+                passcode: this.passcode,
+                discriminator: this.discriminator,
+                commissioned: this.isCommissioned(),
+                fabricCount: this.getCommissionedFabricCount(),
+                fabrics: this.getFabricInfo(),
+            };
+            await writeFile(commissioningFilePath, JSON.stringify(commissioningData, null, 2), 'utf-8');
+            log.debug('Updated commissioning info file');
+        }
+        catch (error) {
+            log.debug(`Failed to update commissioning info file: ${error.message}`);
+        }
+    }
+    /**
+     * Register Matter platform accessories (Plugin API - matches HAP pattern)
+     */
+    async registerPlatformAccessories(pluginIdentifier, platformName, accessories) {
+        for (const accessory of accessories) {
+            await this.registerAccessory(pluginIdentifier, platformName, accessory);
+        }
+    }
+    /**
+     * Unregister Matter platform accessories (Plugin API - matches HAP pattern)
+     */
+    async unregisterPlatformAccessories(pluginIdentifier, platformName, accessories) {
+        for (const accessory of accessories) {
+            await this.unregisterAccessory(accessory.uuid);
+        }
+    }
+    /**
+     * Register a single Matter accessory (internal method)
+     */
+    async registerAccessory(pluginIdentifier, platformName, accessory) {
+        if (!this.serverNode || !this.aggregator) {
+            throw new MatterDeviceError('Matter server not started');
+        }
+        // Validate required fields with helpful error messages
+        if (!accessory.deviceType) {
+            throw new MatterDeviceError(`Matter accessory "${accessory.displayName || 'unknown'}" is missing required field 'deviceType'. `
+                + 'Example: deviceType: api.matterDeviceTypes.OnOffLight\n'
+                + 'Available device types: OnOffLight, DimmableLight, TemperatureSensor, etc.\n'
+                + 'See the Matter types documentation for the full list.');
+        }
+        if (!accessory.uuid) {
+            throw new MatterDeviceError('Matter accessory is missing required field \'uuid\'.\n'
+                + 'Generate a unique UUID for your accessory:\n'
+                + '  const uuid = api.hap.uuid.generate(\'my-unique-id\')');
+        }
+        if (!accessory.displayName) {
+            throw new MatterDeviceError(`Matter accessory (${accessory.uuid}) is missing required field 'displayName'.\n`
+                + 'Example: displayName: \'Living Room Light\'');
+        }
+        if (!accessory.serialNumber) {
+            throw new MatterDeviceError(`Matter accessory "${accessory.displayName}" is missing required field 'serialNumber'.\n`
+                + 'Example: serialNumber: \'ABC123\' or serialNumber: accessory.UUID');
+        }
+        if (!accessory.manufacturer) {
+            throw new MatterDeviceError(`Matter accessory "${accessory.displayName}" is missing required field 'manufacturer'.\n`
+                + 'Example: manufacturer: \'Homebridge\' or manufacturer: \'My Plugin Name\'');
+        }
+        if (!accessory.model) {
+            throw new MatterDeviceError(`Matter accessory "${accessory.displayName}" is missing required field 'model'.\n`
+                + 'Example: model: \'v1.0\' or model: \'Smart Light\'');
+        }
+        if (!accessory.clusters || typeof accessory.clusters !== 'object') {
+            throw new MatterDeviceError(`Matter accessory "${accessory.displayName}" is missing or has invalid 'clusters' field.\n`
+                + 'Clusters define the functionality of your device. Example:\n'
+                + '  clusters: {\n'
+                + '    onOff: { onOff: false },\n'
+                + '    levelControl: { currentLevel: 0, minLevel: 0, maxLevel: 254 }\n'
+                + '  }');
+        }
+        // Check if already registered (during this session)
+        if (this.accessories.has(accessory.uuid)) {
+            const existing = this.accessories.get(accessory.uuid);
+            throw new MatterDeviceError(`Matter accessory with UUID "${accessory.uuid}" is already registered.\n`
+                + `Existing accessory: "${existing?.displayName}"\n`
+                + `New accessory: "${accessory.displayName}"\n`
+                + 'Each accessory must have a unique UUID. Use api.hap.uuid.generate() with a unique string.');
+        }
+        // Check if there's a cached version - merge cached cluster states with new registration
+        if (this.accessoryCache && this.accessoryCache.hasCached(accessory.uuid)) {
+            const cached = this.accessoryCache.getCached(accessory.uuid);
+            if (cached && cached.clusters) {
+                // Merge cached cluster states with new ones (prefer cached state to persist values across restarts)
+                for (const [clusterName, cachedAttrs] of Object.entries(cached.clusters)) {
+                    if (!accessory.clusters[clusterName]) {
+                        // Cluster exists in cache but not in new registration - preserve it
+                        accessory.clusters[clusterName] = cachedAttrs;
+                    }
+                    else {
+                        // Cluster exists in both - merge (prefer cached state over initial values)
+                        accessory.clusters[clusterName] = {
+                            ...accessory.clusters[clusterName],
+                            ...cachedAttrs,
+                        };
+                    }
+                }
+                // Restore context if available
+                if (cached.context) {
+                    accessory.context = cached.context;
+                }
+                log.info(`Restored cached state for Matter accessory: ${accessory.displayName}`);
+            }
+        }
+        // Check device limit
+        if (this.accessories.size >= this.MAX_DEVICES) {
+            throw new MatterDeviceError(`Cannot register Matter accessory "${accessory.displayName}": `
+                + `Maximum device limit reached (${this.MAX_DEVICES} devices).\n`
+                + `Current registered devices: ${this.accessories.size}`);
+        }
+        try {
+            // Modify device type with custom behaviors if handlers are defined
+            let deviceType = accessory.deviceType;
+            // IMPORTANT: Detect WindowCovering features based on accessory attributes
+            // This must run BEFORE any other device type modifications
+            let windowCoveringFeatures = null;
+            if (accessory.clusters.windowCovering) {
+                windowCoveringFeatures = [];
+                const wcCluster = accessory.clusters.windowCovering;
+                // Check for lift attributes
+                const hasLiftAttrs = 'targetPositionLiftPercent100ths' in wcCluster || 'currentPositionLiftPercent100ths' in wcCluster;
+                const hasConfigLift = wcCluster.configStatus?.liftPositionAware === true;
+                // Check for tilt attributes
+                const hasTiltAttrs = 'targetPositionTiltPercent100ths' in wcCluster || 'currentPositionTiltPercent100ths' in wcCluster;
+                const hasConfigTilt = wcCluster.configStatus?.tiltPositionAware === true;
+                log.debug(`[${accessory.displayName}] WindowCovering detection: hasLiftAttrs=${hasLiftAttrs}, hasConfigLift=${hasConfigLift}, hasTiltAttrs=${hasTiltAttrs}, hasConfigTilt=${hasConfigTilt}`);
+                // Add Lift features if lift attributes are present
+                if (hasLiftAttrs) {
+                    windowCoveringFeatures.push('Lift');
+                    if (hasConfigLift) {
+                        windowCoveringFeatures.push('PositionAwareLift');
+                    }
+                }
+                // Add Tilt features if tilt attributes are present
+                if (hasTiltAttrs) {
+                    windowCoveringFeatures.push('Tilt');
+                    if (hasConfigTilt) {
+                        windowCoveringFeatures.push('PositionAwareTilt');
+                    }
+                }
+                if (windowCoveringFeatures.length > 0) {
+                    log.info(`Auto-detected WindowCovering features for ${accessory.displayName}: ${windowCoveringFeatures.join(', ')}`);
+                    // Apply WindowCovering features to base device type using ONLY base WindowCoveringServer
+                    // Don't use custom behavior for WindowCovering to avoid conflicts
+                    deviceType = deviceType.with(WindowCoveringServer.with(...windowCoveringFeatures));
+                    // Set type attribute ONLY for devices with Tilt features
+                    // Type 8 (TiltBlindLift) supports lift+tilt
+                    // Default Rollershade (0) works fine for lift-only devices
+                    const hasTiltFeatures = windowCoveringFeatures.includes('Tilt');
+                    if (hasTiltFeatures) {
+                        const wcCluster = accessory.clusters.windowCovering;
+                        wcCluster.type = 8; // TiltBlindLift
+                        log.debug('Set WindowCovering type to 8 (TiltBlindLift) for tilt-capable device');
+                    }
+                    // Mark that we should skip custom behavior for windowCovering
+                    if (!accessory.context) {
+                        accessory.context = {};
+                    }
+                    accessory.context._skipWindowCoveringBehavior = true;
+                }
+                else {
+                    log.warn(`⚠️  No WindowCovering features detected for ${accessory.displayName}!`);
+                }
+            }
+            if (accessory.handlers) {
+                log.warn(`📝 [${accessory.displayName}] Has handlers: ${Object.keys(accessory.handlers).join(', ')}`);
+                // IMPORTANT: Detect ServiceArea features BEFORE modifying device type
+                let serviceAreaFeatures = null;
+                if (accessory.clusters?.serviceArea) {
+                    const features = [];
+                    // Check if Maps feature should be enabled (when supportedMaps is defined)
+                    if (accessory.clusters.serviceArea.supportedMaps) {
+                        features.push('Maps');
+                    }
+                    // Check if ProgressReporting feature should be enabled (when progress is defined)
+                    if (accessory.clusters.serviceArea.progress !== undefined) {
+                        features.push('ProgressReporting');
+                    }
+                    if (features.length > 0) {
+                        serviceAreaFeatures = features;
+                        log.info(`ServiceArea features will be enabled for ${accessory.displayName}: ${features.join(', ')}`);
+                    }
+                }
+                // IMPORTANT: Detect ColorControl features BEFORE modifying device type
+                // Once we start applying custom behaviors, the original structure is lost
+                let colorControlFeatures = null;
+                if (accessory.handlers.colorControl) {
+                    const deviceTypeDef = deviceType;
+                    const existingBehaviors = deviceTypeDef.behaviors;
+                    if (existingBehaviors) {
+                        // Behaviors can be an array, Set, or object - handle all cases
+                        let behaviorsArray;
+                        if (Array.isArray(existingBehaviors)) {
+                            behaviorsArray = existingBehaviors;
+                        }
+                        else if (typeof existingBehaviors === 'object') {
+                            // It's an object - get the values
+                            behaviorsArray = Object.values(existingBehaviors);
+                        }
+                        else {
+                            // Try Array.from as fallback for Sets, Maps, etc.
+                            behaviorsArray = Array.from(existingBehaviors);
+                        }
+                        for (const behavior of behaviorsArray) {
+                            if (behavior.id === 'colorControl' || behavior.cluster?.id === 0x0300) {
+                                if (behavior.cluster?.supportedFeatures) {
+                                    const features = behavior.cluster.supportedFeatures;
+                                    colorControlFeatures = [];
+                                    // supportedFeatures is an object with boolean properties, not a bitmap
+                                    if (features.hueSaturation) {
+                                        colorControlFeatures.push('HueSaturation');
+                                    }
+                                    if (features.xy) {
+                                        colorControlFeatures.push('Xy');
+                                    }
+                                    if (features.colorTemperature) {
+                                        colorControlFeatures.push('ColorTemperature');
+                                    }
+                                }
+                                // IMPORTANT: Adjust features based on provided handlers
+                                // Add missing features and remove features without handlers
+                                if (accessory.handlers.colorControl) {
+                                    if (!colorControlFeatures) {
+                                        colorControlFeatures = [];
+                                    }
+                                    const handlers = accessory.handlers.colorControl;
+                                    const finalFeatures = [];
+                                    // Check each possible feature and only include it if the handler is provided
+                                    // HueSaturation feature
+                                    if ('moveToHueAndSaturationLogic' in handlers) {
+                                        finalFeatures.push('HueSaturation');
+                                    }
+                                    // Xy feature
+                                    if ('moveToColorLogic' in handlers) {
+                                        finalFeatures.push('Xy');
+                                    }
+                                    // ColorTemperature feature
+                                    if ('moveToColorTemperatureLogic' in handlers) {
+                                        finalFeatures.push('ColorTemperature');
+                                    }
+                                    colorControlFeatures = finalFeatures;
+                                }
+                                break;
+                            }
+                        }
+                    }
+                    else {
+                        log.warn(`No behaviors found on device type for ${accessory.displayName}`);
+                    }
+                }
+                // IMPORTANT: Detect Thermostat features BEFORE modifying device type
+                let thermostatFeatures = null;
+                if (accessory.handlers.thermostat) {
+                    const deviceTypeDef = deviceType;
+                    const existingBehaviors = deviceTypeDef.behaviors;
+                    if (existingBehaviors) {
+                        // Behaviors can be an array, Set, or object - handle all cases
+                        let behaviorsArray;
+                        if (Array.isArray(existingBehaviors)) {
+                            behaviorsArray = existingBehaviors;
+                        }
+                        else if (typeof existingBehaviors === 'object') {
+                            // It's an object - get the values
+                            behaviorsArray = Object.values(existingBehaviors);
+                        }
+                        else {
+                            // Try Array.from as fallback for Sets, Maps, etc.
+                            behaviorsArray = Array.from(existingBehaviors);
+                        }
+                        for (const behavior of behaviorsArray) {
+                            if (behavior.id === 'thermostat' || behavior.cluster?.id === 0x0201) {
+                                if (behavior.cluster?.supportedFeatures) {
+                                    const features = behavior.cluster.supportedFeatures;
+                                    thermostatFeatures = [];
+                                    // supportedFeatures is an object with boolean properties
+                                    if (features.heating) {
+                                        thermostatFeatures.push('Heating');
+                                    }
+                                    if (features.cooling) {
+                                        thermostatFeatures.push('Cooling');
+                                    }
+                                    if (features.occupancy) {
+                                        thermostatFeatures.push('Occupancy');
+                                    }
+                                    if (features.autoMode) {
+                                        thermostatFeatures.push('AutoMode');
+                                    }
+                                    log.info(`Detected Thermostat features: ${thermostatFeatures.join(', ')}`);
+                                }
+                                break;
+                            }
+                        }
+                    }
+                }
+                // Map cluster names to custom behavior classes
+                // Only clusters with user-triggered commands need custom behaviors
+                const behaviorMap = {
+                    // Core controls
+                    onOff: HomebridgeOnOffServer,
+                    levelControl: HomebridgeLevelControlServer,
+                    colorControl: HomebridgeColorControlServer,
+                    // Coverings & locks
+                    windowCovering: HomebridgeWindowCoveringServer,
+                    doorLock: HomebridgeDoorLockServer,
+                    // Climate control
+                    thermostat: HomebridgeThermostatServer,
+                    // Robotic vacuum cleaners
+                    rvcOperationalState: HomebridgeRvcOperationalStateServer,
+                    rvcRunMode: HomebridgeRvcRunModeServer,
+                    rvcCleanMode: HomebridgeRvcCleanModeServer,
+                    serviceArea: HomebridgeServiceAreaServer,
+                    // Identification
+                    identify: HomebridgeIdentifyServer,
+                };
+                // Build array of custom behaviors to apply based on what handlers are defined
+                const customBehaviors = [];
+                // For RoboticVacuumCleaner, add optional clusters if they're defined in accessory.clusters
+                // These clusters need to be added to the device type even if there are no handlers
+                if (deviceType === devices.RoboticVacuumCleanerDevice || deviceType.name === 'RoboticVacuumCleaner') {
+                    // Import RVC requirements
+                    const { RvcCleanModeServer, ServiceAreaServer } = devices.RoboticVacuumCleanerRequirements;
+                    // Add RvcCleanMode if defined in clusters
+                    if (accessory.clusters?.rvcCleanMode) {
+                        // Check if there's a custom behavior with handlers
+                        if (accessory.handlers?.rvcCleanMode) {
+                            const behaviorClass = HomebridgeRvcCleanModeServer;
+                            customBehaviors.push(behaviorClass);
+                            log.info('Adding custom RvcCleanMode behavior with handlers');
+                        }
+                        else {
+                            // No handlers, use base server
+                            customBehaviors.push(RvcCleanModeServer);
+                            log.info('Adding base RvcCleanMode server');
+                        }
+                    }
+                    // Add ServiceArea if defined in clusters
+                    if (accessory.clusters?.serviceArea) {
+                        // Check if there's a custom behavior with handlers
+                        if (accessory.handlers?.serviceArea) {
+                            let behaviorClass = HomebridgeServiceAreaServer;
+                            // Apply features if detected
+                            if (serviceAreaFeatures && serviceAreaFeatures.length > 0) {
+                                behaviorClass = behaviorClass.with(...serviceAreaFeatures);
+                                log.info(`ServiceArea custom behavior will have features: ${serviceAreaFeatures.join(', ')}`);
+                            }
+                            customBehaviors.push(behaviorClass);
+                            log.info('Adding custom ServiceArea behavior with handlers');
+                        }
+                        else {
+                            // No handlers, use base server with features
+                            let behaviorClass = ServiceAreaServer;
+                            if (serviceAreaFeatures && serviceAreaFeatures.length > 0) {
+                                behaviorClass = behaviorClass.with(...serviceAreaFeatures);
+                                log.info(`ServiceArea base server will have features: ${serviceAreaFeatures.join(', ')}`);
+                            }
+                            customBehaviors.push(behaviorClass);
+                            log.info('Adding base ServiceArea server');
+                        }
+                    }
+                }
+                for (const clusterName of Object.keys(accessory.handlers || {})) {
+                    // Skip windowCovering if we already applied features via base WindowCoveringServer
+                    if (clusterName === 'windowCovering' && accessory.context?._skipWindowCoveringBehavior) {
+                        log.debug('Skipping custom WindowCovering behavior (using base server with features instead)');
+                        continue;
+                    }
+                    // Skip RVC clusters - they're handled specially above for RoboticVacuumCleaner
+                    if (clusterName === 'rvcCleanMode' || clusterName === 'serviceArea') {
+                        continue;
+                    }
+                    let behaviorClass = behaviorMap[clusterName];
+                    // Apply ColorControl features if we detected them earlier
+                    if (clusterName === 'colorControl' && behaviorClass && colorControlFeatures && colorControlFeatures.length > 0) {
+                        behaviorClass = behaviorClass.with(...colorControlFeatures);
+                        log.info(`ColorControl custom behavior will preserve features: ${colorControlFeatures.join(', ')}`);
+                    }
+                    // Apply Thermostat features if we detected them earlier
+                    if (clusterName === 'thermostat' && behaviorClass && thermostatFeatures && thermostatFeatures.length > 0) {
+                        behaviorClass = behaviorClass.with(...thermostatFeatures);
+                        log.info(`Thermostat custom behavior will preserve features: ${thermostatFeatures.join(', ')}`);
+                    }
+                    // Apply ServiceArea features if we detected them earlier
+                    if (clusterName === 'serviceArea' && behaviorClass && serviceAreaFeatures && serviceAreaFeatures.length > 0) {
+                        behaviorClass = behaviorClass.with(...serviceAreaFeatures);
+                        log.info(`ServiceArea custom behavior will preserve features: ${serviceAreaFeatures.join(', ')}`);
+                    }
+                    // Apply WindowCovering features to custom behavior as well
+                    // (features were already applied to base device type, but custom behavior needs them too)
+                    if (clusterName === 'windowCovering') {
+                        log.warn(`🔍 WindowCovering handler found: behaviorClass=${!!behaviorClass}, windowCoveringFeatures=${windowCoveringFeatures}, length=${windowCoveringFeatures?.length}`);
+                        if (behaviorClass && windowCoveringFeatures && windowCoveringFeatures.length > 0) {
+                            behaviorClass = behaviorClass.with(...windowCoveringFeatures);
+                            log.warn(`🔧 WindowCovering custom behavior will have features: ${windowCoveringFeatures.join(', ')}`);
+                        }
+                        else {
+                            log.warn(`⚠️  Skipping WindowCovering feature application: behaviorClass=${!!behaviorClass}, features=${windowCoveringFeatures}`);
+                        }
+                    }
+                    if (behaviorClass) {
+                        customBehaviors.push(behaviorClass);
+                        log.info(`Will use ${behaviorClass.name} for ${accessory.displayName}`);
+                    }
+                    else {
+                        log.warn(`No custom behavior class available for cluster '${clusterName}' - handlers will be registered but may not be called`);
+                    }
+                }
+                if (customBehaviors.length > 0) {
+                    // Cast to any to bypass TypeScript limitations
+                    deviceType = deviceType.with(...customBehaviors);
+                    log.info(`Applied ${customBehaviors.length} custom behavior(s) to device type`);
+                }
+            }
+            // Create endpoint with the modified device type AND initial cluster states
+            // IMPORTANT: Cluster states must be provided at creation time, before adding to aggregator
+            // This ensures mandatory attributes are set before Matter.js validates the endpoint
+            const endpointOptions = {
+                id: accessory.uuid,
+                ...accessory.clusters, // Spread cluster states as initial values
+            };
+            const endpoint = new Endpoint(deviceType, endpointOptions);
+            if (this.config.debugModeEnabled) {
+                log.debug(`Created endpoint for ${accessory.displayName} with initial cluster states`);
+            }
+            // Add to aggregator (validation happens here - cluster states must already be set)
+            await this.aggregator.add(endpoint);
+            if (this.config.debugModeEnabled) {
+                log.debug(`Added endpoint for ${accessory.displayName} to aggregator`);
+            }
+            // Set up command handlers if provided
+            if (accessory.handlers) {
+                log.info(`Setting up handlers for accessory ${accessory.uuid}`);
+                // Register handlers with the custom behavior classes
+                for (const [clusterName, handlers] of Object.entries(accessory.handlers)) {
+                    log.info(`  Processing cluster: ${clusterName}`);
+                    for (const [commandName, handler] of Object.entries(handlers)) {
+                        registerHandler(accessory.uuid, clusterName, commandName, handler);
+                    }
+                }
+            }
+            // Store accessory
+            const internalAccessory = {
+                ...accessory,
+                _associatedPlugin: pluginIdentifier,
+                _associatedPlatform: platformName,
+                endpoint,
+                registered: true,
+            };
+            this.accessories.set(accessory.uuid, internalAccessory);
+            log.info(`Registered Matter accessory: ${accessory.displayName} (${accessory.uuid})`);
+            if (this.config.debugModeEnabled) {
+                log.debug(`Total registered accessories: ${this.accessories.size}/${this.MAX_DEVICES}`);
+            }
+            // Emit accessory-registered event
+            this.emit('accessory-registered', accessory);
+            // Notify controllers about the new device (parts list changed)
+            // This allows the Home app to discover new devices without re-pairing
+            await this.notifyPartsListChanged();
+            // Save to cache asynchronously (don't block registration)
+            if (this.accessoryCache) {
+                this.accessoryCache.save(this.accessories).catch((error) => {
+                    log.warn('Failed to save accessory cache:', error);
+                });
+            }
+        }
+        catch (error) {
+            log.error(`Failed to register Matter accessory ${accessory.displayName}:`, error);
+            throw new MatterDeviceError(`Failed to register accessory: ${error}`);
+        }
+    }
+    /**
+     * Unregister a Matter accessory (Plugin API)
+     */
+    async unregisterAccessory(uuid) {
+        const accessory = this.accessories.get(uuid);
+        if (!accessory) {
+            // Accessory not in memory, but might be in cache - still remove from cache
+            log.debug(`Accessory ${uuid} not found or not registered`);
+            // Check if it exists in cache and remove it
+            if (this.accessoryCache && this.accessoryCache.getCached(uuid)) {
+                log.debug(`Removing ${uuid} from cache`);
+                this.accessoryCache.removeCached(uuid);
+                this.accessoryCache.save(this.accessories).catch((error) => {
+                    log.warn('Failed to save accessory cache:', error);
+                });
+            }
+            return;
+        }
+        try {
+            if (accessory.endpoint && this.aggregator) {
+                await accessory.endpoint.close();
+                log.debug(`Removed endpoint for ${accessory.displayName}`);
+            }
+            this.accessories.delete(uuid);
+            log.info(`Unregistered Matter accessory: ${accessory.displayName} (${uuid})`);
+            // Emit accessory-unregistered event
+            this.emit('accessory-unregistered', uuid);
+            // Notify controllers about the removed device (parts list changed)
+            await this.notifyPartsListChanged();
+            // Update cache (remove the accessory)
+            if (this.accessoryCache) {
+                this.accessoryCache.removeCached(uuid);
+                this.accessoryCache.save(this.accessories).catch((error) => {
+                    log.warn('Failed to save accessory cache:', error);
+                });
+            }
+        }
+        catch (error) {
+            log.error(`Failed to unregister Matter accessory ${uuid}:`, error);
+            throw new MatterDeviceError(`Failed to unregister accessory: ${error}`);
+        }
+    }
+    /**
+     * Update a Matter accessory's state (Plugin API)
+     *
+     * This method can be called from anywhere, including from within handlers.
+     * State updates are automatically deferred to avoid transaction conflicts.
+     */
+    async updateAccessoryState(uuid, cluster, attributes) {
+        const accessory = this.accessories.get(uuid);
+        if (!accessory || !accessory.endpoint) {
+            throw new MatterDeviceError(`Accessory ${uuid} not found or not registered`);
+        }
+        // Defer the update to avoid "read-only transaction" errors when called from handlers
+        // Matter.js uses transactions, and we need to wait until the transaction fully completes
+        // Use setTimeout with a delay to ensure we're completely outside the transaction
+        return new Promise((resolve, reject) => {
+            setTimeout(async () => {
+                try {
+                    // Use endpoint.set() method which is the proper way to update state
+                    // This handles transactions correctly
+                    const endpoint = accessory.endpoint;
+                    // Construct the update object
+                    const updateObject = { [cluster]: attributes };
+                    // Use endpoint.set() which properly handles state updates
+                    await endpoint.set(updateObject);
+                    // CRITICAL: Also update the cached clusters object so state persists across restarts
+                    // Merge the new attributes into the existing cluster state
+                    if (!accessory.clusters[cluster]) {
+                        accessory.clusters[cluster] = {};
+                    }
+                    accessory.clusters[cluster] = {
+                        ...accessory.clusters[cluster],
+                        ...attributes,
+                    };
+                    log.debug(`Updated ${cluster} state for ${accessory.displayName}:`, attributes);
+                    resolve();
+                }
+                catch (error) {
+                    log.error(`Failed to update state for accessory ${uuid}:`, error);
+                    reject(new MatterDeviceError(`Failed to update accessory state: ${error}`));
+                }
+            }, 50); // 50ms delay to ensure we're completely outside the transaction
+        });
+    }
+    /**
+     * Get a Matter accessory's current state (Plugin API)
+     *
+     * Returns the current cluster attribute values that are exposed to Matter controllers.
+     * This is useful for:
+     * - Reading state after plugin restart (when local variables are lost)
+     * - Verifying current state before making changes
+     * - Multiple parts of code that need to read state
+     * - Debugging and logging
+     *
+     * @param uuid - The UUID of the accessory
+     * @param cluster - The cluster name (e.g., 'onOff', 'levelControl')
+     * @returns Current cluster attribute values, or undefined if cluster not found
+     */
+    getAccessoryState(uuid, cluster) {
+        const accessory = this.accessories.get(uuid);
+        if (!accessory || !accessory.endpoint) {
+            log.debug(`Accessory ${uuid} not found or not registered`);
+            return undefined;
+        }
+        try {
+            const endpoint = accessory.endpoint;
+            if (!endpoint.state) {
+                log.debug(`endpoint.state is undefined for ${accessory.displayName}`);
+                return undefined;
+            }
+            if (!endpoint.state[cluster]) {
+                const availableClusters = Object.keys(endpoint.state || {});
+                log.debug(`Cluster '${cluster}' not found on ${accessory.displayName}. Available: ${availableClusters.join(', ')}`);
+                return undefined;
+            }
+            const clusterState = endpoint.state[cluster];
+            // Build result object by reading each property directly
+            const result = {};
+            // Get list of properties to read - use both approaches for maximum compatibility
+            const allKeys = new Set([
+                ...Object.keys(clusterState),
+                ...Object.getOwnPropertyNames(clusterState),
+            ]);
+            for (const key of allKeys) {
+                try {
+                    // Skip internal properties, methods, and symbols
+                    if (key.startsWith('_') || key.startsWith('$')) {
+                        continue;
+                    }
+                    // Try to read the value directly
+                    const value = clusterState[key];
+                    // Skip functions and undefined values
+                    if (typeof value === 'function' || value === undefined) {
+                        continue;
+                    }
+                    result[key] = value;
+                }
+                catch (propError) {
+                    log.debug(`Could not read property ${key} from ${cluster}:`, propError);
+                }
+            }
+            if (Object.keys(result).length === 0) {
+                log.debug(`Cluster ${cluster} found but no readable properties on accessory ${accessory.displayName}`);
+                return undefined;
+            }
+            return result;
+        }
+        catch (error) {
+            log.error(`Failed to get state for accessory ${uuid}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Get all cached accessories (Internal - for restore process)
+     * @internal
+     */
+    getAllCachedAccessories() {
+        if (!this.accessoryCache) {
+            log.debug('getAllCachedAccessories: No cache available');
+            return [];
+        }
+        const cached = Array.from(this.accessoryCache.getAllCached().values());
+        log.debug(`getAllCachedAccessories: Returning ${cached.length} accessories`);
+        return cached;
+    }
+    /**
+     * Get all registered accessories (Plugin API)
+     */
+    getAccessories() {
+        return Array.from(this.accessories.values()).map((acc) => {
+            // Return copy without internal fields
+            // eslint-disable-next-line unused-imports/no-unused-vars
+            const { endpoint, registered, ...publicAccessory } = acc;
+            return publicAccessory;
+        });
+    }
+    /**
+     * Get a specific accessory by UUID (Plugin API)
+     */
+    getAccessory(uuid) {
+        const accessory = this.accessories.get(uuid);
+        if (!accessory) {
+            return undefined;
+        }
+        // Return copy without internal fields
+        // eslint-disable-next-line unused-imports/no-unused-vars
+        const { endpoint, registered, ...publicAccessory } = accessory;
+        return publicAccessory;
+    }
+    /**
+     * Stop the Matter server
+     */
+    async stop() {
+        if (!this.isRunning) {
+            log.debug('Matter server is not running');
+            return;
+        }
+        this.isRunning = false;
+        // Stop monitoring
+        this.stopFabricMonitoring();
+        networkMonitor.stopMonitoring();
+        try {
+            // Save accessory cache before shutting down (BEFORE clearing accessories!)
+            if (this.accessoryCache && this.accessories.size > 0) {
+                await this.accessoryCache.save(this.accessories);
+                log.debug('Saved accessory cache before shutdown');
+            }
+            // Clean up all accessories
+            for (const accessory of this.accessories.values()) {
+                try {
+                    if (accessory.endpoint) {
+                        await accessory.endpoint.close();
+                    }
+                }
+                catch (error) {
+                    log.error('Failed to clean up accessory:', error);
+                }
+            }
+            this.accessories.clear();
+            // Stop server
+            if (this.serverNode) {
+                await this.serverNode.close();
+            }
+            await this.cleanup();
+            log.info('Matter server stopped');
+        }
+        catch (error) {
+            log.error('Error stopping Matter server:', error);
+            await errorHandler.handleError(error, 'server-stop');
+            throw error;
+        }
+        finally {
+            this.isRunning = false;
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    async cleanup() {
+        // Remove signal handlers
+        if (this.shutdownHandler) {
+            process.off('SIGINT', this.shutdownHandler);
+            process.off('SIGTERM', this.shutdownHandler);
+            this.shutdownHandler = null;
+        }
+        // Run all cleanup handlers
+        for (const handler of this.cleanupHandlers) {
+            try {
+                await handler();
+            }
+            catch (error) {
+                log.debug('Error during cleanup handler:', error);
+            }
+        }
+        this.cleanupHandlers = [];
+        // Clear references
+        this.serverNode = null;
+        this.aggregator = null;
+        this.isRunning = false;
+        this.commissioningInfo = {};
+    }
+    /**
+     * Get fabric information for commissioned controllers
+     */
+    getFabricInfo() {
+        try {
+            if (!this.serverNode || !this.storageManager) {
+                return [];
+            }
+            // Fabric data is stored in the main storage file (uniqueId namespace)
+            // with the key "fabrics.fabrics"
+            const storage = this.storageManager.getStorage(this.config.uniqueId);
+            const fabricsData = storage.get(['fabrics'], 'fabrics');
+            if (Array.isArray(fabricsData) && fabricsData.length > 0) {
+                // Map the fabric data to our interface
+                return fabricsData.map(fabric => ({
+                    fabricIndex: fabric.fabricIndex || 0,
+                    fabricId: fabric.fabricId?.value?.toString() || '',
+                    nodeId: fabric.nodeId?.value?.toString() || '',
+                    rootVendorId: fabric.rootVendorId || 0,
+                    label: fabric.label || '',
+                }));
+            }
+            return [];
+        }
+        catch (error) {
+            log.debug('Failed to get fabric info from storage:', error);
+            return [];
+        }
+    }
+    /**
+     * Check if the server is commissioned
+     */
+    isCommissioned() {
+        try {
+            if (!this.storageManager) {
+                return false;
+            }
+            // Commissioned status is stored in the main storage file (uniqueId namespace)
+            // at key "root.commissioning.commissioned"
+            const storage = this.storageManager.getStorage(this.config.uniqueId);
+            const commissioned = storage.get(['root', 'commissioning'], 'commissioned');
+            if (commissioned === true) {
+                return true;
+            }
+            // Fallback to checking fabric count if commissioned flag not found
+            const fabrics = this.getFabricInfo();
+            return fabrics.length > 0;
+        }
+        catch (error) {
+            log.debug('Failed to check commissioned status from storage:', error);
+            return false;
+        }
+    }
+    /**
+     * Get the number of commissioned fabrics
+     */
+    getCommissionedFabricCount() {
+        return this.getFabricInfo().length;
+    }
+    /**
+     * Get server status information
+     */
+    getServerInfo() {
+        return {
+            running: this.isRunning,
+            port: this.config.port || 5540,
+            deviceCount: this.accessories.size,
+            commissioned: this.isCommissioned(),
+            fabricCount: this.getCommissionedFabricCount(),
+            serialNumber: this.serialNumber,
+        };
+    }
+    /**
+     * Get commissioning information
+     */
+    getCommissioningInfo() {
+        return {
+            ...this.commissioningInfo,
+            serialNumber: this.serialNumber,
+            passcode: this.passcode,
+            discriminator: this.discriminator,
+            commissioned: this.isCommissioned(),
+        };
+    }
+    /**
+     * Get storage statistics
+     */
+    getStorageStats() {
+        if (!this.storageManager) {
+            return null;
+        }
+        return this.storageManager.getAllStats();
+    }
+    /**
+     * Check if server is running
+     */
+    isServerRunning() {
+        return this.isRunning;
+    }
+    /**
+     * Get Matter device types available for plugin use
+     */
+    getDeviceTypes() {
+        return deviceTypes;
+    }
+    /**
+     * Get Matter clusters available for plugin use
+     */
+    getClusters() {
+        return clusters;
+    }
+    /**
+     * Remove a specific fabric (controller) from the bridge
+     * This decommissions a single controller while leaving others intact
+     *
+     * @param fabricIndex - The fabric index to remove
+     * @returns Promise that resolves when the fabric is removed
+     */
+    async removeFabric(fabricIndex) {
+        if (!this.serverNode) {
+            throw new MatterDeviceError('Matter server not started');
+        }
+        try {
+            log.info(`Removing fabric ${fabricIndex}...`);
+            const serverState = this.serverNode;
+            const removeFabric = serverState?.state?.commissioning?.removeFabric;
+            if (typeof removeFabric !== 'function') {
+                throw new MatterDeviceError('Fabric removal not supported by Matter.js version');
+            }
+            // Remove the fabric
+            await removeFabric(fabricIndex);
+            log.info(`Fabric ${fabricIndex} removed successfully`);
+            // The fabric monitoring will detect this change and emit the appropriate events
+        }
+        catch (error) {
+            log.error(`Failed to remove fabric ${fabricIndex}:`, error);
+            throw new MatterDeviceError(`Failed to remove fabric: ${error.message}`, error);
+        }
+    }
+    /**
+     * Check if a specific fabric exists
+     */
+    hasFabric(fabricIndex) {
+        const fabrics = this.getFabricInfo();
+        return fabrics.some(f => f.fabricIndex === fabricIndex);
+    }
+    /**
+     * Notify controllers that the parts list has changed
+     * This triggers controllers (like Home app) to re-read the device list
+     * and discover new or removed accessories without needing to re-pair
+     */
+    async notifyPartsListChanged() {
+        if (!this.aggregator || !this.isCommissioned()) {
+            // No controllers connected, skip notification
+            return;
+        }
+        try {
+            // Access the aggregator's descriptor cluster state
+            // The partsList is automatically updated by Matter.js when endpoints are added/removed
+            // We just need to ensure controllers are notified of the change
+            const aggregatorState = this.aggregator;
+            if (aggregatorState.state?.descriptor) {
+                // Get current parts list (endpoint numbers of all children)
+                const partsList = aggregatorState.state.descriptor.partsList || [];
+                if (this.config.debugModeEnabled) {
+                    log.debug(`Parts list changed: ${partsList.length} devices (endpoints: ${partsList.join(', ')})`);
+                }
+                // Trigger a state update event to notify subscribed controllers
+                // By setting the partsList to itself, we trigger the change notification
+                await this.aggregator.set({
+                    descriptor: {
+                        partsList,
+                    },
+                });
+                log.info(`Notified controllers of parts list change (${this.accessories.size} devices)`);
+            }
+        }
+        catch (error) {
+            // Non-fatal error - log but don't throw
+            log.warn(`Failed to notify controllers of parts list change: ${error.message}`);
+        }
+    }
+}
+//# sourceMappingURL=matterServer.js.map