homebridge 2.0.0-alpha.42 → 2.0.0-alpha.44

package/dist/matter/matterServer.js

@@ -5,23 +5,26 @@
  * Matter accessories via the Homebridge API.
  */
 import * as crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
 import * as fs from 'node:fs';
-import { access } from 'node:fs/promises';
+import { access, writeFile } from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
-import { Endpoint, Environment, ServerNode, StorageService, VendorId, } from '@matter/main';
+import { Endpoint, Environment, ServerNode, StorageService, VendorId } from '@matter/main';
 import { AggregatorEndpoint } from '@matter/main/endpoints';
-import { ManualPairingCodeCodec, QrPairingCodeCodec, } from '@matter/types/schema';
+import { ManualPairingCodeCodec, QrPairingCodeCodec } from '@matter/types/schema';
 import * as fse from 'fs-extra';
 import QRCode from 'qrcode-terminal';
 import { Logger } from '../logger.js';
 import getVersion from '../version.js';
-import { diagnostics } from './matterDiagnostics.js';
+import { MatterAccessoryCache } from './matterAccessoryCache.js';
+import { HomebridgeColorControlServer, HomebridgeDoorLockServer, HomebridgeIdentifyServer, HomebridgeLevelControlServer, HomebridgeOnOffServer, HomebridgeThermostatServer, HomebridgeWindowCoveringServer, registerHandler, setAccessoriesMap, } from './matterBehaviors.js';
 import { errorHandler } from './matterErrorHandler.js';
 import { networkMonitor } from './matterNetworkMonitor.js';
 import { MatterStorageManager } from './matterStorage.js';
 import { clusters, deviceTypes, MatterDeviceError, } from './matterTypes.js';
+import { sanitizeUniqueId, truncateString, validatePort } from './matterValidation.js';
 const log = Logger.withPrefix('Matter');
 // Constants for Matter server configuration
 const DEFAULT_MATTER_PORT = 5540;
@@ -32,11 +35,14 @@ 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 {
+export class MatterServer extends EventEmitter {
     config;
     serverNode = null;
     aggregator = null;
@@ -53,19 +59,88 @@ export class MatterServer {
     serialNumber;
     cleanupHandlers = [];
     storageManager = null;
-    constructor(config = {}) {
-        this.config = config;
-        // Store the user config with defaults
-        this.config = {
-            port: config.port || DEFAULT_MATTER_PORT,
-            name: config.name || 'Homebridge Matter Bridge',
-            // Use a consistent uniqueId based on the name to ensure storage persistence
-            uniqueId: config.uniqueId || `homebridge-matter-${config.name?.replace(/[^a-z0-9]/gi, '-') || 'bridge'}`,
-            storagePath: config.storagePath,
-        };
+    matterStoragePath;
+    accessoryCache = null;
+    // Fabric monitoring
+    fabricMonitorInterval = null;
+    previousFabrics = new Map();
+    constructor(config) {
+        super();
+        // Store the validated config
+        this.config = this.validateAndSanitizeConfig(config);
+        // Enable debug logging if requested
+        if (this.config.debugModeEnabled) {
+            log.info('Matter debug mode enabled - verbose logging active');
+        }
         // 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 = path.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
@@ -166,8 +241,21 @@ export class MatterServer {
     }
     /**
      * Create ServerNode with automatic recovery from corrupted storage
-     * If ServerNode creation fails due to corrupted fabric data, automatically
-     * clean up the ServerNodeStore and retry once
+     *
+     * 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 {
@@ -247,17 +335,14 @@ export class MatterServer {
             // Start network monitoring
             networkMonitor.startMonitoring();
             this.cleanupHandlers.push(() => networkMonitor.stopMonitoring());
-            // Start diagnostics
-            diagnostics.startDiagnostics();
-            this.cleanupHandlers.push(() => diagnostics.stopDiagnostics());
             // Create commissioning options
             const commissioningOptions = {
                 passcode: this.passcode,
                 discriminator: this.discriminator,
             };
             log.info(`Using commissioning credentials: passcode=${this.passcode}, discriminator=${this.discriminator}`);
-            // Ensure we have a name for the bridge
-            const bridgeName = this.config.name || 'Homebridge Matter Bridge';
+            // Use default name for the Matter bridge
+            const bridgeName = 'Homebridge Matter Bridge';
             // Sanitize the uniqueId to ensure it's filesystem-safe
             // Replace any characters that could cause issues (colons, slashes, etc.)
             // Use only alphanumeric and hyphens, collapse multiple hyphens, trim leading/trailing hyphens
@@ -277,15 +362,15 @@ export class MatterServer {
                 basicInformation: {
                     nodeLabel: bridgeName.slice(0, 32), // Maximum 32 characters
                     vendorId: VendorId(this.vendorId),
-                    vendorName: 'Homebridge'.slice(0, 32),
+                    vendorName: (this.config.manufacturer || 'Homebridge').slice(0, 32),
                     productId: this.productId,
-                    productName: 'Homebridge Matter Bridge'.slice(0, 32),
+                    productName: (this.config.model || 'Homebridge Matter Bridge').slice(0, 32),
                     productLabel: bridgeName.slice(0, 64), // Maximum 64 characters
-                    serialNumber: this.serialNumber = this.generateSerialNumber(),
+                    serialNumber: this.serialNumber = this.config.serialNumber || this.generateSerialNumber(),
                     hardwareVersion: 1,
                     hardwareVersionString: os.release(),
                     softwareVersion: 1,
-                    softwareVersionString: getVersion(),
+                    softwareVersionString: this.config.firmwareRevision || getVersion(),
                     reachable: true,
                 },
             };
@@ -316,6 +401,12 @@ export class MatterServer {
             });
             // 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) {
+                await this.accessoryCache.load();
+            }
+            // 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');
@@ -357,14 +448,16 @@ export class MatterServer {
         // Create bridge-specific storage directory
         // Use only alphanumeric characters and hyphens for maximum compatibility
         const bridgeId = this.config.uniqueId?.replace(/[^a-z0-9]/gi, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'default';
-        const matterStoragePath = path.join(normalizedPath, bridgeId);
-        await fse.ensureDir(matterStoragePath);
+        this.matterStoragePath = path.join(normalizedPath, bridgeId);
+        await fse.ensureDir(this.matterStoragePath);
         // Create storage manager
-        this.storageManager = new MatterStorageManager(matterStoragePath);
+        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 = matterStoragePath;
+        storageService.location = this.matterStoragePath;
         // CRITICAL: Override storage factory with custom implementation
         // This ensures fabric data is properly persisted
         storageService.factory = (namespace) => {
@@ -385,7 +478,7 @@ export class MatterServer {
                 await this.storageManager.closeAll();
             }
         });
-        log.info(`Matter storage initialized at: ${matterStoragePath}`);
+        log.info(`Matter storage initialized at: ${this.matterStoragePath}`);
     }
     /**
      * Load or generate commissioning credentials (passcode and discriminator)
@@ -395,7 +488,8 @@ export class MatterServer {
         if (!this.storageManager) {
             throw new Error('Storage manager not initialized');
         }
-        const storage = this.storageManager.getStorage('commissioning');
+        // 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
@@ -458,6 +552,26 @@ export class MatterServer {
             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 = path.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');
@@ -487,6 +601,115 @@ export class MatterServer {
         // 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 = path.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 a Matter accessory (Plugin API)
      */
@@ -494,44 +717,127 @@ export class MatterServer {
         if (!this.serverNode || !this.aggregator) {
             throw new MatterDeviceError('Matter server not started');
         }
-        // Validate required fields
+        // Validate required fields with helpful error messages
         if (!accessory.deviceType) {
-            throw new MatterDeviceError(`Missing deviceType for accessory "${accessory.displayName}". `
-                + 'Make sure you are using api.matterDeviceTypes (e.g., api.matterDeviceTypes.OnOffLight)');
+            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('Accessory must have a 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('Accessory must have a 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(`Accessory "${accessory.displayName}" must have a 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(`Accessory "${accessory.displayName}" must have a 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(`Accessory "${accessory.displayName}" must have a 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(`Accessory "${accessory.displayName}" must have clusters defined`);
+            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
+        // Check if already registered (during this session)
         if (this.accessories.has(accessory.uuid)) {
-            throw new MatterDeviceError(`Accessory with UUID ${accessory.uuid} is already registered`);
+            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) {
+                    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(`Maximum device limit (${this.MAX_DEVICES}) reached`);
+            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 {
-            // Create endpoint with device type
-            const endpoint = new Endpoint(accessory.deviceType, {
+            // Modify device type with custom behaviors if handlers are defined
+            let deviceType = accessory.deviceType;
+            if (accessory.handlers) {
+                // 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,
+                    // Identification
+                    identify: HomebridgeIdentifyServer,
+                };
+                // Build array of custom behaviors to apply based on what handlers are defined
+                const customBehaviors = [];
+                for (const clusterName of Object.keys(accessory.handlers)) {
+                    const behaviorClass = behaviorMap[clusterName];
+                    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
+            const endpoint = new Endpoint(deviceType, {
                 id: accessory.uuid,
             });
             // Add to aggregator FIRST (required before we can configure it)
             await this.aggregator.add(endpoint);
+            if (this.config.debugModeEnabled) {
+                log.debug(`Added endpoint for ${accessory.displayName} to aggregator`);
+            }
             // NOW configure the endpoint
             await this.configureEndpoint(endpoint, accessory);
             // Store accessory
@@ -542,6 +848,17 @@ export class MatterServer {
             };
             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);
+            // 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);
@@ -564,6 +881,15 @@ export class MatterServer {
             }
             this.accessories.delete(uuid);
             log.info(`Unregistered Matter accessory: ${accessory.displayName} (${uuid})`);
+            // Emit accessory-unregistered event
+            this.emit('accessory-unregistered', uuid);
+            // 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);
@@ -572,27 +898,113 @@ export class MatterServer {
     }
     /**
      * 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 {
-            // Update the endpoint's cluster state
-            // Note: Endpoint types from Matter.js don't expose state properly, needs runtime check
             const endpoint = accessory.endpoint;
-            if (endpoint.state?.[cluster]) {
-                Object.assign(endpoint.state[cluster], attributes);
-                log.debug(`Updated ${cluster} state for ${accessory.displayName}:`, attributes);
+            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);
+                }
             }
-            else {
-                log.warn(`Cluster ${cluster} not found on accessory ${accessory.displayName}`);
+            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 update state for accessory ${uuid}:`, error);
-            throw new MatterDeviceError(`Failed to update accessory state: ${error}`);
+            log.error(`Failed to get state for accessory ${uuid}:`, error);
+            return undefined;
         }
     }
     /**
@@ -651,12 +1063,12 @@ export class MatterServer {
         }
         // 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)) {
-                    const endpointWithEvents = endpoint;
-                    if (endpointWithEvents.events?.[clusterName]?.[`${commandName}$Action`]) {
-                        endpointWithEvents.events[clusterName][`${commandName}$Action`].on(handler);
-                    }
+                    registerHandler(accessory.uuid, clusterName, commandName, handler);
                 }
             }
         }
@@ -671,9 +1083,14 @@ export class MatterServer {
         }
         this.isRunning = false;
         // Stop monitoring
+        this.stopFabricMonitoring();
         networkMonitor.stopMonitoring();
-        diagnostics.stopDiagnostics();
         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 {
@@ -820,5 +1237,40 @@ export class MatterServer {
     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);
+    }
 }
 //# sourceMappingURL=matterServer.js.map