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

package/src/codec/MessageCodec.ts

@@ -0,0 +1,276 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, DataReader, DataWriter, Diagnostic, Endian, NotImplementedError, UnexpectedDataError } from "#general";
+import { GroupId, NodeId } from "#types";
+
+export interface PacketHeader {
+    sessionId: number;
+    sessionType: SessionType;
+    hasPrivacyEnhancements: boolean;
+    isControlMessage: boolean;
+    hasMessageExtensions: boolean;
+    messageId: number;
+    sourceNodeId?: NodeId;
+    destNodeId?: NodeId;
+    destGroupId?: number;
+}
+
+export interface DecodedPacketHeader extends PacketHeader {
+    securityFlags: number; // The SecurityFlags as pure data field to be used as nonce
+}
+
+export interface PayloadHeader {
+    exchangeId: number;
+    protocolId: number;
+    messageType: number;
+    isInitiatorMessage: boolean;
+    requiresAck: boolean;
+    ackedMessageId?: number;
+    hasSecuredExtension: boolean;
+}
+
+export interface Packet {
+    header: PacketHeader;
+    messageExtension?: Uint8Array;
+    applicationPayload: Uint8Array;
+}
+
+export interface DecodedPacket extends Packet {
+    header: DecodedPacketHeader;
+}
+export interface Message {
+    packetHeader: PacketHeader;
+    payloadHeader: PayloadHeader;
+    securityExtension?: Uint8Array;
+    payload: Uint8Array;
+}
+
+export interface DecodedMessage extends Message {
+    packetHeader: DecodedPacketHeader;
+}
+
+const HEADER_VERSION = 0x00;
+
+export enum SessionType {
+    Group = 1,
+    Unicast = 0,
+}
+
+const COMMON_VENDOR_ID = 0x0000;
+
+const enum PacketHeaderFlag {
+    HasDestNodeId = 0b00000001,
+    HasDestGroupId = 0b00000010,
+    HasSourceNodeId = 0b00000100,
+    Reserved = 0b00001000,
+    VersionMask = 0b11110000,
+}
+
+const enum PayloadHeaderFlag {
+    IsInitiatorMessage = 0b00000001,
+    IsAckMessage = 0b00000010,
+    RequiresAck = 0b00000100,
+    HasSecureExtension = 0b00001000,
+    HasVendorId = 0b00010000,
+}
+
+const enum SecurityFlag {
+    HasPrivacyEnhancements = 0b10000000,
+    IsControlMessage = 0b01000000,
+    HasMessageExtension = 0b00100000,
+}
+
+export class MessageCodec {
+    static decodePacket(data: Uint8Array): DecodedPacket {
+        const reader = new DataReader(data, Endian.Little);
+        const header = this.decodePacketHeader(reader);
+
+        let messageExtension: Uint8Array | undefined = undefined;
+        if (header.hasMessageExtensions) {
+            const extensionLength = reader.readUInt16();
+            messageExtension = reader.readByteArray(extensionLength);
+        }
+
+        const applicationPayload = reader.getRemainingBytes();
+        return {
+            header,
+            messageExtension,
+            applicationPayload,
+        };
+    }
+
+    static decodePayload({ header, applicationPayload }: DecodedPacket): DecodedMessage {
+        const reader = new DataReader(applicationPayload, Endian.Little);
+        const payloadHeader = this.decodePayloadHeader(reader);
+        let securityExtension: Uint8Array | undefined = undefined;
+        if (payloadHeader.hasSecuredExtension) {
+            const extensionLength = reader.readUInt16();
+            securityExtension = reader.readByteArray(extensionLength);
+        }
+        return {
+            packetHeader: header,
+            payloadHeader,
+            securityExtension,
+            payload: reader.getRemainingBytes(),
+        };
+    }
+
+    static encodePayload({ packetHeader, payloadHeader, payload, securityExtension }: Message): Packet {
+        if (securityExtension !== undefined || payloadHeader.hasSecuredExtension) {
+            throw new NotImplementedError(`Security extensions not supported when encoding a payload.`);
+        }
+
+        return {
+            header: packetHeader,
+            applicationPayload: Bytes.concat(this.encodePayloadHeader(payloadHeader), payload),
+        };
+    }
+
+    static encodePacket({ header, applicationPayload, messageExtension }: Packet): Uint8Array {
+        if (messageExtension !== undefined || header.hasMessageExtensions) {
+            throw new NotImplementedError(`Message extensions not supported when encoding a packet.`);
+        }
+        return Bytes.concat(this.encodePacketHeader(header), applicationPayload);
+    }
+
+    private static decodePacketHeader(reader: DataReader<Endian.Little>): DecodedPacketHeader {
+        // Read and parse message flags
+        const flags = reader.readUInt8();
+        const version = (flags & PacketHeaderFlag.VersionMask) >> 4;
+        const hasDestNodeId = (flags & PacketHeaderFlag.HasDestNodeId) !== 0;
+        const hasDestGroupId = (flags & PacketHeaderFlag.HasDestGroupId) !== 0;
+        const hasSourceNodeId = (flags & PacketHeaderFlag.HasSourceNodeId) !== 0;
+
+        if (hasDestNodeId && hasDestGroupId)
+            throw new UnexpectedDataError(
+                "The header cannot contain destination group and node at the same time. Reserved for future use. Discard message.",
+            );
+        if (version !== HEADER_VERSION) throw new NotImplementedError(`Unsupported header version ${version}.`);
+
+        const sessionId = reader.readUInt16();
+        const securityFlags = reader.readUInt8();
+        const messageId = reader.readUInt32();
+        const sourceNodeId = hasSourceNodeId ? NodeId(reader.readUInt64()) : undefined;
+        const destNodeId = hasDestNodeId ? NodeId(reader.readUInt64()) : undefined;
+        const destGroupId = hasDestGroupId ? GroupId(reader.readUInt16()) : undefined;
+
+        const sessionType = securityFlags & 0b00000011;
+        if (sessionType !== SessionType.Group && sessionType !== SessionType.Unicast)
+            throw new UnexpectedDataError(`Unsupported session type ${sessionType}`);
+        const hasPrivacyEnhancements = (securityFlags & SecurityFlag.HasPrivacyEnhancements) !== 0;
+        if (hasPrivacyEnhancements) throw new NotImplementedError(`Privacy enhancements not supported`);
+        const isControlMessage = (securityFlags & SecurityFlag.IsControlMessage) !== 0;
+        if (isControlMessage) throw new NotImplementedError(`Control Messages not supported`);
+        const hasMessageExtensions = (securityFlags & SecurityFlag.HasMessageExtension) !== 0;
+
+        return {
+            securityFlags,
+            sessionId,
+            sourceNodeId,
+            messageId,
+            destGroupId,
+            destNodeId,
+            sessionType,
+            hasPrivacyEnhancements,
+            isControlMessage,
+            hasMessageExtensions,
+        };
+    }
+
+    private static decodePayloadHeader(reader: DataReader<Endian.Little>): PayloadHeader {
+        const exchangeFlags = reader.readUInt8();
+        const isInitiatorMessage = (exchangeFlags & PayloadHeaderFlag.IsInitiatorMessage) !== 0;
+        const isAckMessage = (exchangeFlags & PayloadHeaderFlag.IsAckMessage) !== 0;
+        const requiresAck = (exchangeFlags & PayloadHeaderFlag.RequiresAck) !== 0;
+        const hasSecuredExtension = (exchangeFlags & PayloadHeaderFlag.HasSecureExtension) !== 0;
+        const hasVendorId = (exchangeFlags & PayloadHeaderFlag.HasVendorId) !== 0;
+
+        const messageType = reader.readUInt8();
+        const exchangeId = reader.readUInt16();
+        const vendorId = hasVendorId ? reader.readUInt16() : COMMON_VENDOR_ID;
+        const protocolId = (vendorId << 16) | reader.readUInt16();
+        const ackedMessageId = isAckMessage ? reader.readUInt32() : undefined;
+
+        return {
+            protocolId,
+            exchangeId,
+            messageType,
+            isInitiatorMessage,
+            requiresAck,
+            ackedMessageId,
+            hasSecuredExtension,
+        };
+    }
+
+    static encodePacketHeader({
+        messageId: messageCounter,
+        sessionId,
+        destGroupId,
+        destNodeId,
+        sourceNodeId,
+        sessionType,
+    }: PacketHeader) {
+        const writer = new DataWriter(Endian.Little);
+        const flags =
+            (HEADER_VERSION << 4) |
+            (destGroupId !== undefined ? PacketHeaderFlag.HasDestGroupId : 0) |
+            (destNodeId !== undefined ? PacketHeaderFlag.HasDestNodeId : 0) |
+            (sourceNodeId !== undefined ? PacketHeaderFlag.HasSourceNodeId : 0);
+        const securityFlags = sessionType;
+
+        writer.writeUInt8(flags);
+        writer.writeUInt16(sessionId);
+        writer.writeUInt8(securityFlags);
+        writer.writeUInt32(messageCounter);
+        if (sourceNodeId !== undefined) writer.writeUInt64(sourceNodeId);
+        if (destNodeId !== undefined) writer.writeUInt64(destNodeId);
+        if (destGroupId !== undefined) writer.writeUInt32(destGroupId);
+        return writer.toByteArray();
+    }
+
+    static messageDiagnostics(
+        {
+            packetHeader: { messageId, sessionId },
+            payloadHeader: { exchangeId, messageType, protocolId, ackedMessageId, requiresAck },
+            payload,
+        }: Message,
+        isDuplicate = false,
+    ) {
+        return Diagnostic.dict({
+            id: `${sessionId}/${exchangeId}/${messageId}`,
+            type: `${protocolId}/${messageType}`,
+            acked: ackedMessageId,
+            reqAck: requiresAck,
+            duplicate: isDuplicate,
+            payload: payload,
+        });
+    }
+
+    private static encodePayloadHeader({
+        exchangeId,
+        isInitiatorMessage,
+        messageType,
+        protocolId,
+        requiresAck,
+        ackedMessageId: ackedMessageCounter,
+    }: PayloadHeader) {
+        const writer = new DataWriter(Endian.Little);
+        const vendorId = (protocolId & 0xffff0000) >> 16;
+        const flags =
+            (isInitiatorMessage ? PayloadHeaderFlag.IsInitiatorMessage : 0) |
+            (ackedMessageCounter !== undefined ? PayloadHeaderFlag.IsAckMessage : 0) |
+            (requiresAck ? PayloadHeaderFlag.RequiresAck : 0) |
+            (vendorId !== COMMON_VENDOR_ID ? PayloadHeaderFlag.HasVendorId : 0);
+
+        writer.writeUInt8(flags);
+        writer.writeUInt8(messageType);
+        writer.writeUInt16(exchangeId);
+        vendorId !== COMMON_VENDOR_ID ? writer.writeUInt32(protocolId) : writer.writeUInt16(protocolId);
+        if (ackedMessageCounter !== undefined) writer.writeUInt32(ackedMessageCounter);
+        return writer.toByteArray();
+    }
+}

package/src/codec/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { Base64, DerCodec, DerKey, DnsCodec, type DerNode } from "#general";
+export * from "./BtpCodec.js";
+export * from "./MessageCodec.js";

package/src/common/FailsafeContext.ts

@@ -0,0 +1,330 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AsyncObservable, Construction, Logger, MatterFlowError, UnexpectedDataError } from "#general";
+import { CaseAuthenticatedTag, NodeId, ValidationError, VendorId } from "#types";
+import { Fabric, FabricBuilder } from "../fabric/Fabric.js";
+import { FabricManager } from "../fabric/FabricManager.js";
+import { SessionManager } from "../session/SessionManager.js";
+import { FailsafeTimer, MatterFabricConflictError } from "./FailsafeTimer.js";
+
+const logger = Logger.get("FailsafeContext");
+
+export class MatterFabricInvalidAdminSubjectError extends MatterFlowError {}
+
+/**
+ * A "timed operation" is a command or sequence of commands that operate with a failsafe timer that will abort the
+ * operation if it does not complete within a specific window.
+ *
+ * FailsafeContext maintains the failsafe timer and tracks information required to rollback state if the operation
+ * aborts.
+ *
+ * Timed operations are exclusive for a node.
+ */
+export abstract class FailsafeContext {
+    #sessions: SessionManager;
+    #fabrics: FabricManager;
+    #failsafe?: FailsafeTimer;
+    #construction: Construction<FailsafeContext>;
+    #associatedFabric?: Fabric;
+    #csrSessionId?: number;
+    #forUpdateNoc?: boolean;
+    #fabricBuilder = new FabricBuilder();
+
+    #commissioned = AsyncObservable<[], void>();
+
+    constructor(options: FailsafeContext.Options) {
+        const { expiryLengthSeconds, associatedFabric, maxCumulativeFailsafeSeconds } = options;
+
+        this.#sessions = options.sessions;
+        this.#fabrics = options.fabrics;
+        this.#associatedFabric = options.associatedFabric;
+
+        this.#construction = Construction(this, async () => {
+            // Ensure derived class construction is complete
+            await Promise.resolve();
+
+            await this.storeEndpointState();
+
+            // If ExpiryLengthSeconds is non-zero and the fail-safe timer was not currently armed, then the fail-safe
+            // timer SHALL be armed for that duration.
+            this.#failsafe = new FailsafeTimer(
+                associatedFabric,
+                expiryLengthSeconds,
+                maxCumulativeFailsafeSeconds,
+                () => this.#failSafeExpired(),
+            );
+            logger.debug(`Arm failSafe timer for ${expiryLengthSeconds}s.`);
+        });
+    }
+
+    async extend(fabric: Fabric | undefined, expiryLengthSeconds: number) {
+        await this.#construction;
+        await this.#failsafe?.reArm(fabric, expiryLengthSeconds);
+        if (expiryLengthSeconds > 0) {
+            logger.debug(`Extend failSafe timer for ${expiryLengthSeconds}s.`);
+        }
+    }
+
+    get fabricIndex() {
+        return this.#fabricBuilder.fabricIndex;
+    }
+
+    get construction() {
+        return this.#construction;
+    }
+
+    get commissioned() {
+        return this.#commissioned;
+    }
+
+    get associatedFabric() {
+        return this.#associatedFabric;
+    }
+
+    get csrSessionId() {
+        return this.#csrSessionId;
+    }
+
+    get forUpdateNoc() {
+        return this.#forUpdateNoc;
+    }
+
+    get hasRootCert() {
+        return this.#fabricBuilder.hasRootCert();
+    }
+
+    get rootCert() {
+        return this.#fabricBuilder.rootCert;
+    }
+
+    async completeCommission() {
+        // 1. The Fail-Safe timer associated with the current Fail-Safe context SHALL be disarmed.
+        if (this.#failsafe === undefined) {
+            throw new MatterFlowError("armFailSafe should be called first!"); // TODO
+        }
+        this.#failsafe.complete();
+
+        if (this.fabricIndex !== undefined) {
+            await this.#fabrics.persistFabrics();
+        }
+
+        this.#failsafe = undefined;
+
+        // 2. The commissioning window at the Server SHALL be closed.
+        await this.commissioned.emit();
+
+        // TODO 3. Any temporary administrative privileges automatically granted to any open PASE session SHALL be revoked (see Section 6.6.2.8, “Bootstrapping of the Access Control Cluster”).
+
+        // 4. The Secure Session Context of any PASE session still established at the Server SHALL be cleared.
+        await this.removePaseSession();
+
+        await this.close();
+    }
+
+    getFailSafeContext() {
+        if (this.#failsafe === undefined) throw new MatterFlowError("armFailSafe should be called first!");
+        return this.#failsafe;
+    }
+
+    getNextFabricIndex() {
+        return this.#fabrics.getNextFabricIndex();
+    }
+
+    async addFabric(fabric: Fabric) {
+        this.#fabrics.addFabric(fabric);
+        if (this.#failsafe !== undefined) {
+            this.#associatedFabric = this.#failsafe.associatedFabric = fabric;
+        }
+        return fabric.fabricIndex;
+    }
+
+    async updateFabric(fabric: Fabric) {
+        await this.#fabrics.updateFabric(fabric);
+        await this.#sessions.deleteResumptionRecordsForFabric(fabric);
+    }
+
+    /**
+     * Handles a CSR from OperationalCredentials cluster and stores additional internal information for further
+     * validity checks.
+     */
+    createCertificateSigningRequest(isForUpdateNoc: boolean, sessionId: number) {
+        if (this.#fabrics.findByKeypair(this.#fabricBuilder.keyPair)) {
+            throw new MatterFlowError("Key pair already exists."); // becomes Failure as StateResponse
+        }
+
+        const result = this.#fabricBuilder.createCertificateSigningRequest();
+        this.#csrSessionId = sessionId;
+        this.#forUpdateNoc = isForUpdateNoc;
+        return result;
+    }
+
+    async removePaseSession() {
+        const session = this.#sessions.getPaseSession();
+        if (session) {
+            await session.close(true);
+        }
+    }
+
+    async close() {
+        await this.#construction;
+        await this.#construction.close(async () => {
+            if (this.#failsafe) {
+                await this.#failsafe.close();
+                this.#failsafe = undefined;
+                await this.rollback();
+            }
+        });
+    }
+
+    /** Handles adding a trusted root certificate from Operational Credentials cluster. */
+    setRootCert(rootCert: Uint8Array) {
+        this.#fabricBuilder.setRootCert(rootCert);
+    }
+
+    /**
+     * Build a new Fabric object based on an existing fabric for the "UpdateNoc" case of the Operational Credentials
+     * cluster.
+     */
+    async buildUpdatedFabric(nocValue: Uint8Array, icacValue: Uint8Array | undefined) {
+        if (this.associatedFabric === undefined) {
+            throw new MatterFlowError("No fabric associated with failsafe context, but we prepare an Fabric update.");
+        }
+        this.#fabricBuilder.initializeFromFabricForUpdate(this.associatedFabric);
+        this.#fabricBuilder.setOperationalCert(nocValue, icacValue);
+        return await this.#fabricBuilder.build(this.associatedFabric.fabricIndex);
+    }
+
+    /** Build a new Fabric object for a new fabric for the "AddNoc" case of the Operational Credentials cluster. */
+    async buildFabric(nocData: {
+        nocValue: Uint8Array;
+        icacValue: Uint8Array | undefined;
+        adminVendorId: VendorId;
+        ipkValue: Uint8Array;
+        caseAdminSubject: NodeId;
+    }) {
+        const builder = this.#fabricBuilder;
+
+        const { nocValue, icacValue, adminVendorId, ipkValue, caseAdminSubject } = nocData;
+
+        // Handle error if the CaseAdminSubject field is not a valid ACL subject in the context of AuthMode set to CASE
+        if (!NodeId.isOperationalNodeId(caseAdminSubject) && !NodeId.isCaseAuthenticatedTag(caseAdminSubject)) {
+            try {
+                if (CaseAuthenticatedTag.getVersion(NodeId.extractAsCaseAuthenticatedTag(caseAdminSubject)) === 0) {
+                    throw new MatterFabricInvalidAdminSubjectError();
+                }
+            } catch (error) {
+                // Validation error can happen when parsing the CaseAuthenticatedTag, then it is invalid too
+                if (error instanceof ValidationError || error instanceof UnexpectedDataError) {
+                    throw new MatterFabricInvalidAdminSubjectError();
+                } else {
+                    throw error;
+                }
+            }
+        }
+
+        builder.setOperationalCert(nocValue, icacValue);
+        const fabricAlreadyExisting = this.#fabrics.getFabrics().find(fabric => builder.matchesToFabric(fabric));
+
+        if (fabricAlreadyExisting) {
+            throw new MatterFabricConflictError(
+                `Fabric with Id ${builder.fabricId} and Node Id ${builder.nodeId} already exists.`,
+            );
+        }
+
+        return builder
+            .setRootVendorId(adminVendorId)
+            .setIdentityProtectionKey(ipkValue)
+            .setRootNodeId(caseAdminSubject)
+            .build(this.#fabrics.getNextFabricIndex());
+    }
+
+    async #failSafeExpired() {
+        logger.info("Failsafe timer expired, Reset fabric builder.");
+
+        await this.close();
+    }
+
+    protected async rollback() {
+        if (this.fabricIndex !== undefined && !this.#forUpdateNoc) {
+            logger.debug(`Revoking fabric with index ${this.fabricIndex}`);
+            await this.#fabrics.revokeFabric(this.fabricIndex);
+        }
+
+        // On expiry of the fail-safe timer, the following actions SHALL be performed in order:
+        // 1. Terminate any open PASE secure session by clearing any associated Secure Session Context at the Server.
+        await this.removePaseSession();
+
+        // TODO 2. Revoke the temporary administrative privileges granted to any open PASE session (see Section 6.6.2.8, “Bootstrapping of the Access Control Cluster”) at the Server.
+
+        // 3. If an AddNOC or UpdateNOC command has been successfully invoked, terminate all CASE sessions associated with the Fabric whose Fabric Index is recorded in the Fail-Safe context (see Section 11.9.6.2, “ArmFailSafe Command”) by clearing any associated Secure Session Context at the Server.
+        let fabric: Fabric | undefined = undefined;
+        if (this.fabricIndex !== undefined) {
+            const fabricIndex = this.fabricIndex;
+            fabric = this.#fabrics.getFabrics().find(fabric => fabric.fabricIndex === fabricIndex);
+            if (fabric !== undefined) {
+                const session = this.#sessions.getSessionForNode(fabric.addressOf(fabric.rootNodeId));
+                if (session !== undefined && session.isSecure) {
+                    await session.close(false);
+                }
+            }
+        }
+
+        // 4. Reset the configuration of all Network Commissioning Networks attribute to their state prior to the
+        //    Fail-Safe being armed.
+        await this.restoreNetworkState();
+
+        // 5. If an UpdateNOC command had been successfully invoked, revert the state of operational key pair, NOC and
+        //    ICAC for that Fabric to the state prior to the Fail-Safe timer being armed, for the Fabric Index that was
+        //    the subject of the UpdateNOC command.
+        if (this.#forUpdateNoc && this.associatedFabric !== undefined) {
+            // update FabricManager and Resumption records but leave current session intact
+            await this.restoreFabric(this.associatedFabric);
+        }
+
+        // 6. If an AddNOC command had been successfully invoked, achieve the equivalent effect of invoking the RemoveFabric command against the Fabric Index stored in the Fail-Safe Context for the Fabric Index that was the subject of the AddNOC command. This SHALL remove all associations to that Fabric including all fabric-scoped data, and MAY possibly factory-reset the device depending on current device state. This SHALL only apply to Fabrics added during the fail-safe period as the result of the AddNOC command.
+        // 7. Remove any RCACs added by the AddTrustedRootCertificate command that are not currently referenced by any entry in the Fabrics attribute.
+        if (!this.#forUpdateNoc && fabric !== undefined) {
+            const fabricIndex = this.fabricIndex;
+            if (fabricIndex !== undefined) {
+                const fabric = this.#fabrics.getFabrics().find(fabric => fabric.fabricIndex === fabricIndex);
+                if (fabric !== undefined) {
+                    await this.revokeFabric(fabric);
+                }
+            }
+        }
+
+        // 8. Reset the Breadcrumb attribute to zero.
+        await this.restoreBreadcrumb();
+
+        // TODO 9. Optionally: if no factory-reset resulted from the previous steps, it is RECOMMENDED that the
+        //  Node rollback the state of all non fabric-scoped data present in the Fail-Safe context.
+        //  In theory happens automatically by revoking last fabric
+    }
+
+    abstract storeEndpointState(): Promise<void>;
+
+    /** Restore Cluster data when the FailSafe context expired. */
+    abstract restoreNetworkState(): Promise<void>;
+
+    async restoreFabric(fabric: Fabric) {
+        await this.updateFabric(fabric);
+    }
+
+    abstract revokeFabric(fabric: Fabric): Promise<void>;
+
+    abstract restoreBreadcrumb(): Promise<void>;
+}
+
+export namespace FailsafeContext {
+    export interface Options {
+        sessions: SessionManager;
+        fabrics: FabricManager;
+        expiryLengthSeconds: number;
+        maxCumulativeFailsafeSeconds: number;
+        associatedFabric: Fabric | undefined;
+    }
+}