@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/common/FailsafeTimer.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger, MatterFlowError, Time, Timer } from "#general";
+import { Fabric } from "../fabric/Fabric.js";
+import type { FailsafeContext } from "./FailsafeContext.js";
+
+export class MatterFabricConflictError extends MatterFlowError {}
+
+const logger = Logger.get("FailsafeTimer");
+
+/**
+ * Manages the failsafe timer associated with a {@link FailsafeContext}.
+ */
+export class FailsafeTimer {
+    #expiryCallback: () => Promise<void>;
+    #failsafeTimer: Timer;
+    #maxCumulativeFailsafeTimer: Timer;
+
+    constructor(
+        public associatedFabric: Fabric | undefined,
+        expiryLengthSeconds: number,
+        maxCumulativeFailsafeSeconds: number,
+        expiryCallback: () => Promise<void>,
+    ) {
+        this.#expiryCallback = expiryCallback;
+        this.#failsafeTimer = this.#startFailsafeTimer(expiryLengthSeconds);
+        this.#maxCumulativeFailsafeTimer = Time.getTimer(
+            "Max cumulative failsafe",
+            maxCumulativeFailsafeSeconds * 1000,
+            () => this.expire(),
+        ).start();
+    }
+
+    async close() {
+        if (this.#failsafeTimer.isRunning) {
+            this.#failsafeTimer.stop();
+        }
+        if (this.#maxCumulativeFailsafeTimer.isRunning) {
+            this.#maxCumulativeFailsafeTimer.stop();
+        }
+    }
+
+    /** Handle "Re-Arming" an existing FailSafe context to extend the timer, expire or fail if not allowed. */
+    async reArm(associatedFabric: Fabric | undefined, expiryLengthSeconds: number) {
+        if (!this.#failsafeTimer.isRunning) {
+            throw new MatterFlowError("FailSafe already expired.");
+        }
+
+        if (this.associatedFabric?.fabricIndex !== associatedFabric?.fabricIndex) {
+            throw new MatterFlowError(
+                `FailSafe already armed (index=${this.associatedFabric?.fabricIndex}) with different fabric (index=${associatedFabric?.fabricIndex}).`,
+            );
+        }
+
+        this.#failsafeTimer.stop();
+
+        if (expiryLengthSeconds === 0) {
+            // If ExpiryLengthSeconds is 0 and the fail-safe timer was already armed and the accessing fabric matches
+            // the Fabric currently associated with the fail-safe context, then the fail-safe timer SHALL be
+            // immediately expired (see further below for side-effects of expiration).
+            await this.expire();
+        } else {
+            // If ExpiryLengthSeconds is non-zero and the fail-safe timer was currently armed, and the accessing Fabric
+            // matches the fail-safe context’s associated Fabric, then the fail-safe timer SHALL be re- armed to expire
+            // in ExpiryLengthSeconds.
+            this.#failsafeTimer = this.#startFailsafeTimer(expiryLengthSeconds);
+        }
+    }
+
+    /** Expire the FailSafe context. This is called by the timer and can also be called manually if needed. */
+    async expire() {
+        this.complete();
+        await this.#expiryCallback();
+    }
+
+    /** Complete the FailSafe context. This is called when the commissioning is completed. */
+    complete() {
+        this.#failsafeTimer.stop();
+        this.#maxCumulativeFailsafeTimer.stop();
+    }
+
+    #startFailsafeTimer(expiryLengthSeconds: number) {
+        return Time.getTimer("Failsafe expiration", expiryLengthSeconds * 1000, () =>
+            this.expire().catch(e => logger.error("Error during failsafe expiration", e)),
+        ).start();
+    }
+}

package/src/common/InstanceBroadcaster.ts

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BitFlag, BitmapSchema, ProductDescription, TypeFromPartialBitSchema, VendorId } from "#types";
+import { Fabric } from "../fabric/Fabric.js";
+
+export const PairingHintBitmap = {
+    /**
+     * The Device will automatically enter Commissioning Mode upon power cycle (unplug/re- plug, remove/re-insert
+     * batteries). This bit SHALL be set to 1 for devices using Standard Commissioning Flow, and set to 0 otherwise.
+     */
+    powerCycle: BitFlag(0),
+
+    /**
+     * This SHALL be set to 1 for devices requiring Custom Commissioning Flow before they can be available for
+     * Commissioning by any Commissioner. For such a flow, the user SHOULD be sent to the URL specified in the
+     * CommissioningCustomFlowUrl of the DeviceModel schema entry indexed by the Vendor ID and Product ID (e.g., as
+     * found in the announcement) in the Distributed Compliance Ledger.
+     */
+    deviceManufacturerUrl: BitFlag(1),
+
+    /**
+     * The Device has been commissioned. Any Administrator that commissioned the device provides a user interface that
+     * may be used to put the device into Commissioning Mode.
+     */
+    administrator: BitFlag(2),
+
+    /**
+     * The settings menu on the Device provides instructions to put it into Commissioning Mode.
+     */
+    settingsMenuOnNode: BitFlag(3),
+
+    /**
+     * The PI key/value pair describes a custom way to put the Device into Commissioning Mode. This Custom Instruction
+     * option is NOT recommended for use by a Device that does not have knowledge of the user’s language preference.
+     */
+    customInstruction: BitFlag(4),
+
+    /**
+     * The Device Manual provides special instructions to put the Device into Commissioning Mode (see Section 11.22.5.8,
+     * “UserManualUrl”). This is a catch-all option to capture user interactions that are not codified by other options
+     * in this table.
+     */
+    deviceManual: BitFlag(5),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed.
+     */
+    pressResetButton: BitFlag(6),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed when applying power to it.
+     */
+    pressResetButtonWithApplicationOfPower: BitFlag(7),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed for N seconds. The exact value of N SHALL
+     * be made available via PI key.
+     */
+    pressRestButtonForNumberOfSeconds: BitFlag(8),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed until associated light blinks.
+     * Information on color of light MAY be made available via PI key (see Note 1).
+     */
+    pressResetButtonUntilLightBlinks: BitFlag(9),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed for N seconds when applying power to it.
+     * The exact value of N SHALL be made available via PI key.
+     */
+    pressResetButtonForNumberOfSecondsWithApplicationOfPower: BitFlag(10),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed until associated light blinks when
+     * applying power to the Device. Information on color of light MAY be made available via PI key (see Note 1).
+     */
+    pressResetButtonUntilLightBlinksWithApplicationOfPower: BitFlag(11),
+
+    /**
+     * The Device will enter Commissioning Mode when reset button is pressed N times with maximum 1 second between each
+     * press. The exact value of N SHALL be made available via PI key.
+     */
+    pressResetButtonNumberOfTimes: BitFlag(12),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed.
+     */
+    pressSetupButton: BitFlag(13),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed when applying power to it.
+     */
+    pressSetupButtonWithApplicationOfPower: BitFlag(14),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed for N seconds. The exact value of N SHALL
+     * be made available via PI key.
+     */
+    pressSetupButtonForNumberOfSeconds: BitFlag(15),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed until associated light blinks.
+     * Information on color of light MAY be made available via PI key (see Note 1).
+     */
+    pressSetupButtonUntilLightBlinks: BitFlag(16),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed for N seconds when applying power to it.
+     * The exact value of N SHALL be made available via PI key.
+     */
+    pressSetupButtonForNumberOfSecondsWithApplicationOfPower: BitFlag(17),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed until associated light blinks when
+     * applying power to the Device. Information on color of light MAY be made available via PI key (see Note 1).
+     */
+    pressSetupButtonUntilLightBlinksWithApplicationOfPower: BitFlag(18),
+
+    /**
+     * The Device will enter Commissioning Mode when setup button is pressed N times with maximum 1 second between each
+     * press. The exact value of N SHALL be made available via PI key.
+     */
+    pressSetupButtonNumberOfTimes: BitFlag(19),
+};
+
+export const PairingHintBitmapSchema = BitmapSchema(PairingHintBitmap);
+
+export interface CommissioningModeInstanceData extends ProductDescription {
+    /** Device discriminator for commissionable announcements. */
+    discriminator: number;
+
+    /** Session Idle Interval of the device for commissionable announcements. */
+    sessionIdleInterval?: number;
+
+    /** Session Active Interval of the device for commissionable announcements. */
+    sessionActiveInterval?: number;
+
+    /** Duration of time the node should stay Active after the last network activity. **/
+    sessionActiveThreshold?: number;
+
+    /** Pairing Hint of the device for commissionable announcements. */
+    pairingHint?: TypeFromPartialBitSchema<typeof PairingHintBitmap>;
+
+    /** Pairing Instruction of the device for commissionable announcements. */
+    pairingInstructions?: string;
+}
+
+export type CommissionerInstanceData = {
+    /** Device name for commissionable announcements. */
+    deviceName: string;
+
+    /** Device type for commissionable announcements. */
+    vendorId: VendorId;
+
+    /** Vendor ID for commissionable announcements. */
+    productId: number;
+
+    /** Device type for commissionable announcements. */
+    deviceType?: number;
+
+    /** Session Idle Interval of the device for commissionable announcements. */
+    sessionIdleInterval?: number;
+
+    /** Session Active Interval of the device for commissionable announcements. */
+    sessionActiveInterval?: number;
+
+    /** This key defines the duration of time the node stays Active after the last network activity. **/
+    sessionActiveThreshold?: number;
+};
+
+export type OperationalInstanceData = {
+    /** Session Idle Interval of the device for operational announcements. */
+    sessionIdleInterval?: number;
+
+    /** Session Active Interval of the device for operational announcements. */
+    sessionActiveInterval?: number;
+
+    /** This key defines the duration of time the node stays Active after the last network activity. **/
+    sessionActiveThreshold?: number;
+};
+
+export enum CommissioningMode {
+    NotCommissioning = 0,
+    Basic = 1,
+    Enhanced = 2,
+}
+
+/** Interface for classes that allow to announce one Matter instance. */
+export interface InstanceBroadcaster {
+    /** Set a commissionable mode and details to announce a commissionable device. */
+    setCommissionMode(mode: CommissioningMode, deviceData: CommissioningModeInstanceData): Promise<void>;
+
+    /**
+     * Set operational details to Announce an operational device which is already commissioned.
+     * Use expireCommissioningAnnouncements = true when Fabrics are changed after a n commissioning process.
+     */
+    setFabrics(fabrics: Fabric[], expireCommissioningAnnouncements?: boolean): Promise<void>;
+
+    /** Set commissioner details to announce a commissioner service for User directed commissioning (UDC). */
+    setCommissionerInfo(commissionerData: CommissionerInstanceData): Promise<void>;
+
+    /** Send out announcements for this instance. */
+    announce(): Promise<void>;
+
+    /** Expire the announcement for this operative instance. */
+    expireFabricAnnouncement(): Promise<void>;
+
+    /** Expire the announcement for this commissioning instance. */
+    expireCommissioningAnnouncement(): Promise<void>;
+
+    /** Expire all announcements. */
+    expireAllAnnouncements(): Promise<void>;
+
+    /** Destroy the instance */
+    close(): Promise<void>;
+}

package/src/common/OperationalCredentialsTypes.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvByteString, TlvField, TlvObject, TlvOptionalField, TlvUInt32 } from "#types";
+
+/** @see {@link MatterSpecification.v11.Core} § 11.17.5.4 */
+export const TlvAttestation = TlvObject({
+    declaration: TlvField(1, TlvByteString),
+    attestationNonce: TlvField(2, TlvByteString.bound({ length: 32 })),
+    timestamp: TlvField(3, TlvUInt32), // TODO: check actual max length in specs
+    firmwareInfo: TlvOptionalField(4, TlvByteString),
+});
+
+/** @see {@link MatterSpecification.v11.Core} § 11.17.5.6 */
+export const TlvCertSigningRequest = TlvObject({
+    certSigningRequest: TlvField(1, TlvByteString),
+    csrNonce: TlvField(2, TlvByteString.bound({ length: 32 })),
+    vendorReserved1: TlvOptionalField(3, TlvByteString),
+    vendorReserved2: TlvOptionalField(4, TlvByteString),
+    vendorReserved3: TlvOptionalField(5, TlvByteString),
+});

package/src/common/Scanner.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BasicSet, ChannelType, Environment, Environmental, ServerAddress, ServerAddressIp } from "#general";
+import { DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
+import { Fabric } from "../fabric/Fabric.js";
+
+/**
+ * All information exposed by a commissionable device via announcements.
+ * The properties are named identical as in the Matter specification.
+ */
+export type DiscoveryData = {
+    /** VendorId + ProductId */
+    VP?: string;
+
+    /** Device type */
+    DT?: number;
+
+    /** Device advertising name */
+    DN?: string;
+
+    /** Rotating device identifier */
+    RI?: string;
+
+    /** Pairing hint */
+    PH?: number;
+
+    /** Pairing instructions */
+    PI?: string;
+
+    /** Sleep Idle Interval */
+    SII?: number;
+
+    /** Sleep Active Interval */
+    SAI?: number;
+
+    /** Session active threshold */
+    SAT?: number;
+
+    /** TCP supported */
+    T?: number;
+
+    /** ICD Long Idle Time operating mode supported */
+    ICD?: number;
+};
+
+export type DiscoverableDevice<SA extends ServerAddress> = DiscoveryData & {
+    /** The device's addresses IP/port pairs */
+    addresses: SA[];
+};
+
+export type AddressTypeFromDevice<D extends DiscoverableDevice<any>> =
+    D extends DiscoverableDevice<infer SA> ? SA : never;
+
+export type OperationalDevice = DiscoverableDevice<ServerAddressIp> & {
+    deviceIdentifier: string;
+};
+
+export type CommissionableDevice = DiscoverableDevice<ServerAddress> & {
+    deviceIdentifier: string;
+
+    /** Discriminator */
+    D: number;
+
+    /** Commissioning Mode */
+    CM: number;
+};
+
+/**
+ * Identifier to use to discover a commissionable device.
+ * Please decide for the best matching identifier that you have.
+ */
+export type CommissionableDeviceIdentifiers =
+    | {
+          /** Instance ID of the commissionable device. This is mainly used by UDC. */
+          instanceId: string;
+      }
+    | {
+          /** The Long Discriminator of the commissionable device that can be obtained from the QR code. */
+          longDiscriminator: number;
+      }
+    | {
+          /** The Short Discriminator of the commissionable device that can be obtained from the Pairing code. */
+          shortDiscriminator: number;
+      }
+    | {
+          /** The vendor ID of the commissionable device, if devices from a special vendor should be discovered. */
+          vendorId: VendorId;
+
+          /** Optionally the product ID of the commissionable device, if devices from a special vendor should be discovered. */
+          productId?: number;
+      }
+    | {
+          /** The device type of the commissionable device, if devices of a special type should be discovered. */
+          deviceType: number;
+      }
+    | {
+          /** The product ID of the commissionable device, if devices with a special product should be discovered. */
+          productId: number;
+      }
+    | {
+          /** Pass empty object to discover any commissionable device. */
+          [K in any]: never; // aka "empty object" for just discovering any commisionable device
+      };
+
+export interface Scanner {
+    type: ChannelType;
+
+    /**
+     * Send DNS-SD queries to discover the current addresses of an operational paired device by its operational ID
+     * and return them.
+     */
+    findOperationalDevice(
+        fabric: Fabric,
+        nodeId: NodeId,
+        timeoutSeconds?: number,
+        ignoreExistingRecords?: boolean,
+    ): Promise<OperationalDevice | undefined>;
+
+    /**
+     * Return already discovered addresses of an operational paired device and return them. Does not send out new
+     * DNS-SD queries.
+     */
+    getDiscoveredOperationalDevice(fabric: Fabric, nodeId: NodeId): OperationalDevice | undefined;
+
+    /**
+     * Send DNS-SD queries to discover commissionable devices by a provided identifier (e.g. discriminator,
+     * vendorId, etc.) and returns as soon as minimum one was found or the timeout is over.
+     */
+    findCommissionableDevices(
+        identifier: CommissionableDeviceIdentifiers,
+        timeoutSeconds?: number,
+        ignoreExistingRecords?: boolean,
+    ): Promise<CommissionableDevice[]>;
+
+    /**
+     * Send DNS-SD queries to discover commissionable devices by a provided identifier (e.g. discriminator,
+     * vendorId, etc.) and returns after the timeout is over. For each new discovered device the provided callback is
+     * called when it is discovered.
+     */
+    findCommissionableDevicesContinuously(
+        identifier: CommissionableDeviceIdentifiers,
+        callback: (device: CommissionableDevice) => void,
+        timeoutSeconds?: number,
+    ): Promise<CommissionableDevice[]>;
+
+    /** Return already discovered commissionable devices and return them. Does not send out new DNS-SD queries. */
+    getDiscoveredCommissionableDevices(identifier: CommissionableDeviceIdentifiers): CommissionableDevice[];
+
+    /**
+     * Cancel a running discovery of commissionable devices. The waiter promises are resolved as if the timeout would
+     * be over.
+     */
+    cancelCommissionableDeviceDiscovery(identifier: CommissionableDeviceIdentifiers, resolvePromise?: boolean): void;
+
+    /** Close the scanner server and free resources. */
+    close(): void;
+}
+
+export class ScannerSet extends BasicSet<Scanner> {
+    scannerFor(type: ChannelType) {
+        return this.find(scanner => scanner.type === type);
+    }
+
+    hasScannerFor(type: ChannelType) {
+        return this.scannerFor(type) !== undefined;
+    }
+
+    /**
+     * Select a set of scanners based on discovery capabilities.
+     */
+    public select(discoveryCapabilities?: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap>) {
+        // Note we always scan via MDNS if available
+        return this.filter(
+            scanner =>
+                scanner.type === ChannelType.UDP || (discoveryCapabilities?.ble && scanner.type === ChannelType.BLE),
+        );
+    }
+
+    [Environmental.create](env: Environment) {
+        const instance = new ScannerSet();
+        env.set(ScannerSet, instance);
+        return instance;
+    }
+}

package/src/common/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "../peer/PeerAddress.js";
+export * from "./FailsafeContext.js";
+export * from "./FailsafeTimer.js";
+export * from "./InstanceBroadcaster.js";
+export * from "./OperationalCredentialsTypes.js";
+export * from "./Scanner.js";

package/src/endpoint/EndpointInterface.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterId, ClusterType, DeviceTypeId, EndpointNumber } from "#types";
+import { ClusterClientObj } from "../cluster/index.js";
+import { ClusterServer } from "../cluster/server/ClusterServer.js";
+
+/**
+ * The primary interface for Matter.js endpoint implementations.
+ *
+ * TODO - this is a transitional interface that allows us to have multiple implementations of the legacy endpoint API
+ */
+export interface EndpointInterface {
+    name: string;
+    number: EndpointNumber | undefined;
+    deviceType: DeviceTypeId;
+    getNumber(): EndpointNumber;
+    removeFromStructure(): void;
+    updatePartsList(): EndpointNumber[];
+    getChildEndpoints(): EndpointInterface[];
+    determineUniqueID(): string | undefined;
+    verifyRequiredClusters(): void;
+    close(): void;
+    setStructureChangedCallback(callback: () => void): void;
+
+    addClusterServer(server: ClusterServer): void;
+    hasClusterServer(cluster: ClusterType): boolean;
+    getClusterServer<T extends ClusterType>(cluster: T): ClusterServer | undefined;
+    getClusterServerById(clusterId: ClusterId): ClusterServer | undefined;
+    getAllClusterServers(): ClusterServer[];
+
+    addClusterClient(client: ClusterClientObj): void;
+    getClusterClient<const T extends ClusterType>(cluster: T): ClusterClientObj<T> | undefined;
+    getAllClusterClients(): ClusterClientObj[];
+
+    addChildEndpoint(endpoint: EndpointInterface): void;
+    getChildEndpoint(id: EndpointNumber): EndpointInterface | undefined;
+}