homebridge 2.0.0-alpha.41 → 2.0.0-alpha.43

package/dist/matter/matterServer.js

@@ -1,13 +1,12 @@
-/* global NodeJS */
 /**
- * Real Matter.js Server Implementation
+ * Matter.js Server Implementation for Homebridge Plugin API
  *
- * Complete Matter.js integration
- * and official Matter.js v0.15 documentation
+ * This provides a Matter bridge that plugins can use to register
+ * Matter accessories via the Homebridge API.
  */
 import * as crypto from 'node:crypto';
 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';
@@ -18,61 +17,67 @@ import * as fse from 'fs-extra';
 import QRCode from 'qrcode-terminal';
 import { Logger } from '../logger.js';
 import getVersion from '../version.js';
-import { MatterDevice } from './matterDevice.js';
 import { diagnostics } from './matterDiagnostics.js';
 import { errorHandler } from './matterErrorHandler.js';
 import { networkMonitor } from './matterNetworkMonitor.js';
+import { MatterStorageManager } from './matterStorage.js';
+import { clusters, deviceTypes, MatterDeviceError, } from './matterTypes.js';
 const log = Logger.withPrefix('Matter');
+// 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;
 /**
- * Real Matter.js Server for Homebridge
- * Creates a Matter bridge that exposes HAP accessories to Matter controllers
+ * Matter Server for Homebridge Plugin API
+ * Allows plugins to register Matter accessories explicitly
  */
 export class MatterServer {
     config;
     serverNode = null;
     aggregator = null;
-    devices = new Map();
-    removedDevices = new Set(); // Track removed devices for restart
+    accessories = new Map();
     isRunning = false;
-    restartTimer = null;
-    isRestarting = false;
-    MAX_DEVICES = 1000; // Maximum number of devices
-    MAX_REMOVED_DEVICES = 10; // Trigger restart after this many removals
-    RESTART_DELAY_MS = 30000; // Delay before restarting server
+    MAX_DEVICES = MAX_DEVICES_PER_BRIDGE;
     shutdownHandler = null;
     // Internal commissioning values (generated, not user-configurable)
-    passcode;
-    discriminator;
+    passcode = 0;
+    discriminator = 0;
     vendorId;
     productId;
     commissioningInfo = {};
     serialNumber;
     cleanupHandlers = [];
+    storageManager = null;
+    matterStoragePath;
     constructor(config = {}) {
         this.config = config;
         // Store the user config with defaults
         this.config = {
-            port: config.port || 5540,
+            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,
-            mdnsInterface: config.mdnsInterface,
-            ipv4: config.ipv4 !== false, // Default to true
-            ipv6: config.ipv6 !== false, // Default to true
         };
-        // Generate internal commissioning values
-        this.passcode = this.generateSecurePasscode();
-        this.discriminator = this.generateRandomDiscriminator();
-        this.vendorId = 0xFFF1; // Test vendor ID
-        this.productId = 0x8001; // Test product ID
+        // Initialize commissioning values (will be loaded from storage in start())
+        this.vendorId = DEFAULT_VENDOR_ID;
+        this.productId = DEFAULT_PRODUCT_ID;
     }
     /**
      * 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 = 100;
+        const maxAttempts = MAX_PASSCODE_ATTEMPTS;
         let attempts = 0;
         const invalidPasscodes = [
             0,
@@ -92,22 +97,137 @@ export class MatterServer {
             // Use cryptographically secure random number generation
             const randomBytes = crypto.randomBytes(4);
             const randomValue = randomBytes.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)
-            || passcode.toString().padStart(8, '0').length !== 8);
+            || !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 randomBytes = crypto.randomBytes(2);
-        return randomBytes.readUInt16BE(0) & 0x0FFF; // Mask to 12 bits
+        const discriminator = randomBytes.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
+     * If ServerNode creation fails due to corrupted fabric data, automatically
+     * clean up the ServerNodeStore and retry once
+     */
+    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 = path.join(storageLocation, sanitizedId);
+            const serverNodeStoreJsonFile = `${serverNodeStorePath}.json`;
+            try {
+                let removedSomething = false;
+                // Delete the ServerNodeStore subdirectory
+                if (fs.existsSync(serverNodeStorePath)) {
+                    log.info(`Removing corrupted ServerNodeStore directory: ${serverNodeStorePath}`);
+                    await fse.remove(serverNodeStorePath);
+                    removedSomething = true;
+                }
+                // Delete the ServerNodeStore JSON file (contains fabric data)
+                if (fs.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
@@ -119,9 +239,12 @@ export class MatterServer {
         }
         try {
             log.info('Starting Matter.js server...');
-            log.info(`Configuration: Port=${this.config.port}, Passcode=${this.passcode}, Discriminator=${this.discriminator}`);
-            // Validate and set up storage path
+            // 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());
@@ -133,43 +256,43 @@ export class MatterServer {
                 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';
+            // 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
+            const sanitizedId = this.config.uniqueId.replace(/[^a-z0-9]/gi, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
             // Create node options with proper typing
             const nodeOptions = {
-                id: this.config.uniqueId,
+                id: sanitizedId,
                 network: {
                     port: this.config.port,
-                    ipv4: this.config.ipv4,
-                    ipv6: this.config.ipv6,
-                    mdnsInterface: this.config.mdnsInterface,
+                    ipv4: true, // Always enable IPv4 for Matter
                 },
                 commissioning: commissioningOptions,
                 productDescription: {
-                    name: bridgeName, // This should be the user-visible name
+                    name: bridgeName,
                     deviceType: AggregatorEndpoint.deviceType,
                 },
                 basicInformation: {
-                    // Try setting nodeLabel to the bridge name instead of product name
                     nodeLabel: bridgeName.slice(0, 32), // Maximum 32 characters
                     vendorId: VendorId(this.vendorId),
                     vendorName: 'Homebridge'.slice(0, 32),
                     productId: this.productId,
                     productName: 'Homebridge Matter Bridge'.slice(0, 32),
-                    // Set productLabel to bridge name as well
                     productLabel: bridgeName.slice(0, 64), // Maximum 64 characters
                     serialNumber: this.serialNumber = this.generateSerialNumber(),
                     hardwareVersion: 1,
-                    hardwareVersionString: os.release(), // Hardware version
+                    hardwareVersionString: os.release(),
                     softwareVersion: 1,
-                    softwareVersionString: getVersion(), // Shows as "Firmware" in Home app
+                    softwareVersionString: getVersion(),
                     reachable: true,
                 },
             };
-            // Create server node with proper configuration
-            this.serverNode = await ServerNode.create(nodeOptions);
+            // Create server node with automatic recovery from corrupted storage
+            this.serverNode = await this.createServerNodeWithRecovery(nodeOptions, sanitizedId);
             // Create aggregator endpoint for bridge pattern
-            // The bridge name is set via the ServerNode's basicInformation
             this.aggregator = new Endpoint(AggregatorEndpoint, {
                 id: 'homebridge-aggregator',
             });
@@ -195,8 +318,8 @@ export class MatterServer {
             // Wait for server to be ready
             await this.waitForServerReady();
             this.isRunning = true;
-            log.info(`✅ Matter server started successfully on port ${this.config.port}`);
-            log.info('Homebridge accessories can now be added to Matter controllers');
+            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);
@@ -232,15 +355,69 @@ export class MatterServer {
         catch (error) {
             throw new Error(`Storage path not accessible: ${error}`);
         }
-        // Create Matter-specific storage directory with bridge-specific subfolder
-        const bridgeId = this.config.uniqueId?.replace(/[^a-z0-9-]/gi, '_') || 'default';
-        const matterStoragePath = path.join(normalizedPath, '.matter', bridgeId);
-        await fse.ensureDir(matterStoragePath);
-        // Configure environment to use our storage
+        // 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';
+        this.matterStoragePath = path.join(normalizedPath, bridgeId);
+        await fse.ensureDir(this.matterStoragePath);
+        // Create storage manager
+        this.storageManager = new MatterStorageManager(this.matterStoragePath);
+        // Configure environment to use our custom storage
         const environment = Environment.default;
         const storageService = environment.get(StorageService);
-        storageService.location = matterStoragePath;
-        log.info(`✅ Matter storage initialized at: ${matterStoragePath}`);
+        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');
+        }
+        const storage = this.storageManager.getStorage('commissioning');
+        // 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 serial number for the bridge
@@ -259,14 +436,13 @@ export class MatterServer {
         const vendorId = this.vendorId;
         const productId = this.productId;
         // Use Matter.js library to generate pairing codes properly
-        // Generate 11-digit code (without vendor/product IDs) for better compatibility
         const manualCode = ManualPairingCodeCodec.encode({
             discriminator,
             passcode: this.passcode,
-            // Omit vendorId and productId to generate 11-digit code instead of 21-digit
         });
         // 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,
@@ -276,11 +452,33 @@ export class MatterServer {
                 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 = 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');
@@ -299,220 +497,257 @@ export class MatterServer {
     /**
      * Wait for the server to be ready
      */
-    async waitForServerReady(maxWaitTime = 5000) {
+    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, 100));
+            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, 200));
+        await new Promise(resolve => setTimeout(resolve, SERVER_INIT_DELAY_MS));
     }
     /**
-     * Add a Homebridge accessory as a bridged Matter device
+     * Register a Matter accessory (Plugin API)
      */
-    async addAccessory(accessory) {
+    async registerAccessory(accessory) {
         if (!this.serverNode || !this.aggregator) {
-            log.error('Matter server not started - cannot add accessory');
-            return null;
+            throw new MatterDeviceError('Matter server not started');
         }
-        // Check device limit
-        if (this.devices.size >= this.MAX_DEVICES) {
-            log.error(`Device limit reached (${this.MAX_DEVICES}), cannot add ${accessory.displayName}`);
-            return null;
+        // Validate required fields
+        if (!accessory.deviceType) {
+            throw new MatterDeviceError(`Missing deviceType for accessory "${accessory.displayName}". `
+                + 'Make sure you are using api.matterDeviceTypes (e.g., api.matterDeviceTypes.OnOffLight)');
+        }
+        if (!accessory.uuid) {
+            throw new MatterDeviceError('Accessory must have a uuid');
+        }
+        if (!accessory.displayName) {
+            throw new MatterDeviceError('Accessory must have a displayName');
+        }
+        if (!accessory.serialNumber) {
+            throw new MatterDeviceError(`Accessory "${accessory.displayName}" must have a serialNumber`);
+        }
+        if (!accessory.manufacturer) {
+            throw new MatterDeviceError(`Accessory "${accessory.displayName}" must have a manufacturer`);
+        }
+        if (!accessory.model) {
+            throw new MatterDeviceError(`Accessory "${accessory.displayName}" must have a model`);
         }
-        if (this.devices.has(accessory.UUID)) {
-            log.debug(`Accessory ${accessory.displayName} already exists as Matter device`);
-            return this.devices.get(accessory.UUID) || null;
+        if (!accessory.clusters || typeof accessory.clusters !== 'object') {
+            throw new MatterDeviceError(`Accessory "${accessory.displayName}" must have clusters defined`);
+        }
+        // Check if already registered
+        if (this.accessories.has(accessory.uuid)) {
+            throw new MatterDeviceError(`Accessory with UUID ${accessory.uuid} is already registered`);
+        }
+        // Check device limit
+        if (this.accessories.size >= this.MAX_DEVICES) {
+            throw new MatterDeviceError(`Maximum device limit (${this.MAX_DEVICES}) reached`);
         }
         try {
-            log.info(`Adding Matter device: ${accessory.displayName}`);
-            // Create Matter device from HAP accessory
-            const matterDevice = new MatterDevice(accessory);
-            const endpoint = await matterDevice.createEndpoint();
-            if (!endpoint) {
-                log.warn(`Could not create Matter endpoint for: ${accessory.displayName}`);
-                return null;
-            }
-            // Add to aggregator (bridge)
-            log.debug(`Adding endpoint to aggregator for ${accessory.displayName} (UUID: ${accessory.UUID})`);
+            // Create endpoint with device type
+            const endpoint = new Endpoint(accessory.deviceType, {
+                id: accessory.uuid,
+            });
+            // Add to aggregator FIRST (required before we can configure it)
             await this.aggregator.add(endpoint);
-            // Store for management
-            this.devices.set(accessory.UUID, matterDevice);
-            // Set up bidirectional sync
-            matterDevice.startSync();
-            log.info(`Added Matter device: ${accessory.displayName} (${matterDevice.getDeviceType()})`);
-            return matterDevice;
+            // NOW configure the endpoint
+            await this.configureEndpoint(endpoint, accessory);
+            // Store accessory
+            const internalAccessory = {
+                ...accessory,
+                endpoint,
+                registered: true,
+            };
+            this.accessories.set(accessory.uuid, internalAccessory);
+            log.info(`Registered Matter accessory: ${accessory.displayName} (${accessory.uuid})`);
         }
         catch (error) {
-            log.error(`Failed to add Matter device for ${accessory.displayName}:`, error);
-            await errorHandler.handleError(error, 'add-accessory');
-            return null;
+            log.error(`Failed to register Matter accessory ${accessory.displayName}:`, error);
+            throw new MatterDeviceError(`Failed to register accessory: ${error}`);
         }
     }
     /**
-     * Remove a Matter device
+     * Unregister a Matter accessory (Plugin API)
      */
-    async removeAccessory(accessory) {
-        const device = this.devices.get(accessory.UUID);
-        if (!device) {
-            log.debug(`No Matter device found for: ${accessory.displayName}`);
+    async unregisterAccessory(uuid) {
+        const accessory = this.accessories.get(uuid);
+        if (!accessory) {
+            log.debug(`Accessory ${uuid} not found, ignoring unregister request`);
             return;
         }
         try {
-            // Stop sync
-            device.stopSync();
-            // Get endpoint to remove
-            const endpoint = await device.getEndpoint();
-            if (endpoint && this.aggregator) {
-                // Remove from aggregator
-                // Note: Matter.js v0.15 doesn't provide a direct API to remove endpoints
-                // from an aggregator after they're added. This is a limitation of the current API.
-                // The endpoint will be cleaned up when the server stops.
-                log.debug('Endpoint marked for removal - will be cleaned up on server restart');
-                // Track removed devices and schedule restart if threshold reached
-                this.removedDevices.add(accessory.UUID);
-                if (this.removedDevices.size >= this.MAX_REMOVED_DEVICES) {
-                    log.warn(`Reached ${this.MAX_REMOVED_DEVICES} removed devices - scheduling Matter server restart in 30 seconds`);
-                    this.scheduleRestart();
-                }
+            if (accessory.endpoint && this.aggregator) {
+                await accessory.endpoint.close();
+                log.debug(`Removed endpoint for ${accessory.displayName}`);
             }
-            // Clean up device
-            await device.destroy();
-            this.devices.delete(accessory.UUID);
-            log.info(`Removed Matter device: ${accessory.displayName}`);
+            this.accessories.delete(uuid);
+            log.info(`Unregistered Matter accessory: ${accessory.displayName} (${uuid})`);
         }
         catch (error) {
-            log.error(`Failed to remove Matter device for ${accessory.displayName}:`, error);
-            await errorHandler.handleError(error, 'remove-accessory');
+            log.error(`Failed to unregister Matter accessory ${uuid}:`, error);
+            throw new MatterDeviceError(`Failed to unregister accessory: ${error}`);
         }
     }
     /**
-     * Schedule a server restart to clean up removed endpoints
+     * Update a Matter accessory's state (Plugin API)
      */
-    scheduleRestart() {
-        // Prevent scheduling if already restarting
-        if (this.isRestarting) {
-            log.debug('Restart already in progress, skipping schedule');
-            return;
-        }
-        // Cancel any existing restart timer
-        if (this.restartTimer) {
-            clearTimeout(this.restartTimer);
+    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`);
         }
-        this.restartTimer = setTimeout(async () => {
-            // Check again in case state changed
-            if (this.isRestarting) {
-                log.debug('Restart already in progress, skipping');
-                return;
-            }
-            this.isRestarting = true;
-            log.info('Restarting Matter server to clean up removed endpoints...');
-            try {
-                // Save current devices
-                const currentDevices = Array.from(this.devices.values());
-                // Stop server
-                await this.stop();
-                // Clear removed devices tracking
-                this.removedDevices.clear();
-                // Wait a moment
-                await new Promise(resolve => setTimeout(resolve, 2000));
-                // Restart server
-                await this.start();
-                // Re-add current devices
-                for (const device of currentDevices) {
-                    const accessory = device.getAccessory();
-                    if (accessory) {
-                        await this.addAccessory(accessory);
-                    }
-                }
-                log.info('Matter server restarted successfully');
-            }
-            catch (error) {
-                log.error('Failed to restart Matter server:', error);
+        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);
             }
-            finally {
-                this.isRestarting = false;
-                this.restartTimer = null;
+            else {
+                log.warn(`Cluster ${cluster} not found on accessory ${accessory.displayName}`);
             }
-        }, this.RESTART_DELAY_MS);
+        }
+        catch (error) {
+            log.error(`Failed to update state for accessory ${uuid}:`, error);
+            throw new MatterDeviceError(`Failed to update accessory state: ${error}`);
+        }
     }
     /**
-     * Get server information
+     * Get all registered accessories (Plugin API)
      */
-    getInfo() {
-        // Record diagnostics info (async, fire and forget)
-        diagnostics.collectDiagnostics({
-            enabled: true,
-            initialized: this.serverNode !== null,
-            running: this.isRunning,
-            port: this.config.port,
-            deviceCount: this.devices.size,
-            bridgeCount: 1,
-        }).catch(error => log.debug('Failed to collect diagnostics:', error));
-        return {
-            running: this.isRunning,
-            port: this.config.port,
-            deviceCount: this.devices.size,
-            config: this.config,
-            serialNumber: this.serialNumber,
-            commissioned: this.isCommissioned(),
-        };
+    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 commissioning information
+     * Get a specific accessory by UUID (Plugin API)
      */
-    getCommissioningInfo() {
-        return {
-            ...this.commissioningInfo,
-            commissioned: this.isCommissioned(),
-        };
+    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;
     }
     /**
-     * Check if the server is commissioned
+     * Configure a Matter endpoint after it's been added to the aggregator
      */
-    isCommissioned() {
-        // Type-safe check for commissioning state
-        try {
-            const serverState = this.serverNode;
-            return serverState?.state?.commissioning?.commissioned === true;
+    async configureEndpoint(endpoint, accessory) {
+        // Note: bridgedDeviceBasicInformation is not available in Matter.js v0.15.4
+        // The BridgedDeviceBasicInformation cluster is automatically added to bridged devices
+        // but cannot be configured via endpoint.set() in this version
+        // Leaving this commented out to avoid error logs
+        // try {
+        //   await endpoint.set({
+        //     bridgedDeviceBasicInformation: {
+        //       nodeLabel: accessory.displayName.slice(0, 32),
+        //       vendorName: accessory.manufacturer.slice(0, 32),
+        //       vendorId: VendorId(this.vendorId),
+        //       productName: accessory.model.slice(0, 32),
+        //       productLabel: accessory.displayName.slice(0, 64),
+        //       serialNumber: accessory.serialNumber,
+        //       reachable: true,
+        //       ...(accessory.hardwareRevision && { hardwareVersionString: accessory.hardwareRevision }),
+        //       ...(accessory.softwareVersion && { softwareVersionString: accessory.softwareVersion }),
+        //     },
+        //   } as any)
+        // } catch (error) {
+        //   log.debug(`Could not set bridgedDeviceBasicInformation for ${accessory.displayName}: ${error}`)
+        // }
+        // Set up cluster states
+        for (const [clusterName, attributes] of Object.entries(accessory.clusters)) {
+            // Cast to any temporarily to work around Matter.js type limitations
+            await endpoint.set({ [clusterName]: attributes });
         }
-        catch {
-            return false;
+        // Set up command handlers if provided
+        if (accessory.handlers) {
+            log.info(`Setting up handlers for accessory ${accessory.uuid}`);
+            // Use endpoint.act() to access behavior instances
+            await endpoint.act('setup-handlers', async (agent) => {
+                log.info(`  Inside act() - agent type: ${typeof agent}`);
+                log.info(`  Agent keys: ${Object.keys(agent).join(', ')}`);
+                for (const [clusterName, handlers] of Object.entries(accessory.handlers)) {
+                    log.info(`  Processing cluster: ${clusterName}`);
+                    // Try to access the behavior on the agent
+                    const behavior = agent[clusterName];
+                    if (!behavior) {
+                        log.warn(`  ✗ Behavior '${clusterName}' not found on agent`);
+                        log.warn('  Available behaviors:', Object.keys(agent).filter(k => typeof agent[k] === 'object'));
+                        continue;
+                    }
+                    log.info(`  ✓ Found behavior: ${clusterName}`);
+                    log.info(`    Behavior type: ${typeof behavior}`);
+                    log.info(`    Behavior constructor: ${behavior?.constructor?.name}`);
+                    // Get all methods on the behavior
+                    const behaviorMethods = Object.keys(behavior).filter(k => typeof behavior[k] === 'function');
+                    log.info(`    Available methods: ${behaviorMethods.join(', ')}`);
+                    for (const [commandName, handler] of Object.entries(handlers)) {
+                        log.info(`    Processing command: ${commandName}`);
+                        // Store the original method if it exists
+                        const originalMethod = behavior[commandName];
+                        if (typeof originalMethod !== 'function') {
+                            log.warn(`    ✗ Method '${commandName}' not found on ${clusterName} behavior`);
+                            continue;
+                        }
+                        log.info(`    ✓ Found method '${commandName}', wrapping with custom handler`);
+                        // Override the behavior method with our handler
+                        behavior[commandName] = async function (...args) {
+                            log.info(`    ┌─ HANDLER CALLED: ${clusterName}.${commandName}`);
+                            log.info(`    │  Args: ${JSON.stringify(args)}`);
+                            try {
+                                await handler(...args);
+                                log.info('    │  Custom handler completed successfully');
+                            }
+                            catch (error) {
+                                log.error('    │  Error in custom handler:', error);
+                            }
+                            // Call the original method to maintain default behavior
+                            const result = await originalMethod.call(this, ...args);
+                            log.info(`    └─ Original method returned: ${JSON.stringify(result)}`);
+                            return result;
+                        };
+                        log.info(`    ✓ Registered handler for ${clusterName}.${commandName}`);
+                    }
+                }
+            });
         }
     }
-    /**
-     * Get all Matter devices
-     */
-    getDevices() {
-        return this.devices;
-    }
     /**
      * Stop the Matter server
      */
     async stop() {
         if (!this.isRunning) {
+            log.debug('Matter server is not running');
             return;
         }
-        log.info('Stopping Matter server...');
+        this.isRunning = false;
         // Stop monitoring
         networkMonitor.stopMonitoring();
         diagnostics.stopDiagnostics();
         try {
-            // Clean up all devices
-            for (const device of this.devices.values()) {
+            // Clean up all accessories
+            for (const accessory of this.accessories.values()) {
                 try {
-                    device.stopSync();
-                    await device.destroy();
+                    if (accessory.endpoint) {
+                        await accessory.endpoint.close();
+                    }
                 }
                 catch (error) {
-                    log.error('Failed to clean up device:', error);
-                    await errorHandler.handleError(error, 'device-cleanup');
+                    log.error('Failed to clean up accessory:', error);
                 }
             }
-            this.devices.clear();
+            this.accessories.clear();
             // Stop server
             if (this.serverNode) {
                 await this.serverNode.close();
@@ -549,11 +784,6 @@ export class MatterServer {
             }
         }
         this.cleanupHandlers = [];
-        // Cancel any pending restart
-        if (this.restartTimer) {
-            clearTimeout(this.restartTimer);
-            this.restartTimer = null;
-        }
         // Clear references
         this.serverNode = null;
         this.aggregator = null;
@@ -561,24 +791,96 @@ export class MatterServer {
         this.commissioningInfo = {};
     }
     /**
-     * Clean up all devices
+     * Get fabric information for commissioned controllers
      */
-    async cleanupAllDevices() {
-        const cleanupPromises = [];
-        for (const [uuid, device] of this.devices.entries()) {
-            cleanupPromises.push((async () => {
-                try {
-                    log.debug(`Cleaning up device: ${uuid}`);
-                    device.stopSync();
-                    await device.destroy();
-                }
-                catch (error) {
-                    log.error(`Failed to clean up device ${uuid}:`, error);
-                }
-            })());
+    getFabricInfo() {
+        try {
+            if (!this.serverNode) {
+                return [];
+            }
+            const serverState = this.serverNode;
+            const fabrics = serverState?.state?.commissioning?.fabrics;
+            // Ensure fabrics is an array before mapping
+            if (!Array.isArray(fabrics)) {
+                return [];
+            }
+            return fabrics.map(fabric => ({
+                fabricIndex: fabric.fabricIndex,
+                fabricId: fabric.fabricId?.toString() || '',
+                nodeId: fabric.nodeId?.toString() || '',
+                rootVendorId: fabric.rootVendorId || 0,
+                label: fabric.label,
+            }));
         }
-        await Promise.all(cleanupPromises);
-        this.devices.clear();
+        catch (error) {
+            log.error('Failed to get fabric info:', error);
+            return [];
+        }
+    }
+    /**
+     * Check if the server is commissioned
+     */
+    isCommissioned() {
+        const fabrics = this.getFabricInfo();
+        return fabrics.length > 0;
+    }
+    /**
+     * 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;
     }
 }
 //# sourceMappingURL=matterServer.js.map