@matter/protocol 0.14.1-alpha.0-20250605-9fc134af0 → 0.14.1-alpha.0-20250607-a93593303

package/src/session/GroupSession.ts

@@ -0,0 +1,223 @@
+/**
+ * @license
+ * Copyright 2022-2023 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Subject } from "#action/server/Subject.js";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "#codec/index.js";
+import { Fabric } from "#fabric/Fabric.js";
+import { FabricManager } from "#fabric/FabricManager.js";
+import {
+    Bytes,
+    Crypto,
+    CryptoDecryptError,
+    ImplementationError,
+    InternalError,
+    Logger,
+    MatterFlowError,
+    UnexpectedDataError,
+} from "#general";
+import type { SessionManager } from "#session/SessionManager.js";
+import { GroupId, NodeId } from "#types";
+import { SecureSession } from "./SecureSession.js";
+import { Session } from "./Session.js";
+
+const logger = Logger.get("SecureGroupSession");
+
+/** Secure Group session instance */
+export class GroupSession extends SecureSession {
+    readonly #id: number;
+    readonly #fabric: Fabric;
+    readonly #peerNodeId: NodeId;
+    readonly #operationalGroupKey: Uint8Array;
+    readonly supportsMRP = false;
+    readonly closingAfterExchangeFinished = false; // Group sessions do not close after exchange finished, they are long-lived
+
+    readonly keySetId: number;
+
+    constructor(args: {
+        manager?: SessionManager;
+        id: number; // Records the Group Session ID derived from the Operational Group Key used to encrypt the message.
+        fabric: Fabric;
+        keySetId: number; // The Group Key Set ID that was used to encrypt the incoming group message.
+        peerNodeId: NodeId; //The Target Group Node Id
+        operationalGroupKey: Uint8Array; // The Operational Group Key that was used to encrypt the incoming group message.
+    }) {
+        const { manager, fabric, operationalGroupKey, id, peerNodeId, keySetId } = args;
+        super({
+            ...args,
+            setActiveTimestamp: false, // We always set the active timestamp for Secure sessions TODO Check
+            messageCounter: fabric.groups.messaging.counterFor(operationalGroupKey),
+        });
+        this.#id = id;
+        this.#fabric = fabric;
+        this.#peerNodeId = peerNodeId;
+        this.keySetId = keySetId;
+        this.#operationalGroupKey = operationalGroupKey;
+
+        manager?.registerGroupSession(this);
+        fabric.addSession(this);
+
+        logger.debug(`Created secure GROUP session for fabric index ${fabric.fabricIndex}`, this.name);
+    }
+
+    override get type() {
+        return SessionType.Group;
+    }
+
+    get fabric(): Fabric {
+        return this.#fabric;
+    }
+
+    get id() {
+        return this.#id;
+    }
+
+    get peerSessionId(): number {
+        return this.#id; // we use the same peer session ID then ours because should be the same keys
+    }
+
+    get name() {
+        return `group/${this.#id}`;
+    }
+
+    get nodeId() {
+        return this.#fabric.nodeId;
+    }
+
+    get peerNodeId() {
+        return this.#peerNodeId;
+    }
+
+    get associatedFabric(): Fabric {
+        return this.#fabric;
+    }
+
+    subjectFor(message?: Message): Subject {
+        if (message === undefined || message.packetHeader.destGroupId === undefined) {
+            throw new ImplementationError("GroupSession requires a message with destGroupId");
+        }
+        return this.fabric.groups.subjectForGroup(GroupId(message.packetHeader.destGroupId), this.keySetId);
+    }
+
+    override notifyActivity(_messageReceived: boolean) {
+        // Group sessions do not have a specific activity notification, so we do nothing here
+    }
+
+    override updateMessageCounter(messageCounter: number, sourceNodeId: NodeId, operationalKey: Uint8Array) {
+        if (sourceNodeId === undefined || operationalKey === undefined) {
+            throw new InternalError("Source Node ID is required for GroupSession updateMessageCounter.");
+        }
+        const receptionState = this.#fabric.groups.messaging.receptionStateFor(sourceNodeId, operationalKey);
+        receptionState.updateMessageCounter(messageCounter);
+    }
+
+    encode(message: Message): Packet {
+        message.packetHeader.sessionId = this.#id;
+        const { header, applicationPayload } = MessageCodec.encodePayload(message);
+        if (header.destGroupId === undefined) {
+            // Just to be sure
+            throw new UnexpectedDataError("Group ID is required for GroupSession encode.");
+        }
+
+        const headerBytes = MessageCodec.encodePacketHeader(message.packetHeader);
+        const securityFlags = headerBytes[3];
+        const nonce = Session.generateNonce(securityFlags, header.messageId, this.#fabric.nodeId);
+
+        return {
+            header,
+            applicationPayload: Crypto.encrypt(this.#operationalGroupKey, applicationPayload, nonce, headerBytes),
+        };
+    }
+
+    decode(): DecodedMessage {
+        throw new InternalError("GroupSession does not support decode on instance.");
+    }
+
+    static decode(
+        fabrics: FabricManager,
+        { header, applicationPayload, messageExtension }: DecodedPacket,
+        aad: Uint8Array,
+    ): {
+        message: DecodedMessage;
+        key: Uint8Array;
+        sessionId: number;
+        sourceNodeId: NodeId;
+        keySetId: number;
+        fabric: Fabric;
+    } {
+        if (header.hasMessageExtensions) {
+            logger.info(
+                `Message extensions are not supported. Ignoring ${messageExtension ? Bytes.toHex(messageExtension) : undefined}`,
+            );
+        }
+        const sourceNodeId = header.sourceNodeId;
+        if (sourceNodeId === undefined) {
+            // Already checked on decoding, but validate twice
+            throw new UnexpectedDataError("Source Node ID is required for GroupSession decode.");
+        }
+        const nonce = Session.generateNonce(header.securityFlags, header.messageId, sourceNodeId);
+        const sessionId = header.sessionId;
+        const keys = new Array<{ key: Uint8Array; keySetId: number; fabric: Fabric }>();
+        for (const fabric of fabrics) {
+            const sessions = fabric.groups.sessions.get(sessionId);
+            if (sessions?.length) {
+                for (const session of sessions) {
+                    keys.push({ ...session, fabric });
+                }
+            }
+        }
+        if (keys.length === 0) {
+            throw new MatterFlowError("No key candidate found for group session decryption.");
+        }
+        let message: DecodedMessage | undefined;
+        let key: Uint8Array | undefined;
+        let fabric: Fabric | undefined;
+        let keySetId: number | undefined;
+        let found = false;
+        for ({ key, keySetId, fabric } of keys) {
+            try {
+                message = MessageCodec.decodePayload({
+                    header,
+                    applicationPayload: Crypto.decrypt(key, applicationPayload, nonce, aad),
+                });
+                found = true;
+                break; // Exit loop on first successful decryption
+            } catch (error) {
+                CryptoDecryptError.accept(error);
+            }
+        }
+        if (!found || !message || !key || !keySetId || !fabric) {
+            throw new MatterFlowError("Failed to decode group message with any key candidate.");
+        }
+
+        if (message.payloadHeader.hasSecuredExtension) {
+            logger.info(
+                `Secured extensions are not supported. Ignoring ${message.securityExtension ? Bytes.toHex(message.securityExtension) : undefined}`,
+            );
+        }
+
+        return { message, key, sessionId, sourceNodeId, keySetId, fabric };
+    }
+
+    async destroy() {
+        logger.info(`End group session ${this.name}`);
+        this.manager?.removeGroupSession(this);
+    }
+
+    end() {
+        return this.destroy();
+    }
+}
+
+export namespace GroupSession {
+    export function assert(session?: Session, errorText?: string): asserts session is GroupSession {
+        if (!is(session)) {
+            throw new MatterFlowError(errorText ?? "Insecure session in secure context");
+        }
+    }
+
+    export function is(session?: Session): session is GroupSession {
+        return session?.type === SessionType.Group;
+    }
+}

package/src/session/InsecureSession.ts

@@ -6,11 +6,11 @@
 
 import { Logger, MatterFlowError } from "#general";
 import { NodeId } from "#types";
-import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet } from "../codec/MessageCodec.js";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "../codec/MessageCodec.js";
 import { Fabric } from "../fabric/Fabric.js";
 import { MessageCounter } from "../protocol/MessageCounter.js";
 import { MessageReceptionStateUnencryptedWithRollover } from "../protocol/MessageReceptionState.js";
-import { NoAssociatedFabricError } from "./SecureSession.js";
+import { NoAssociatedFabricError } from "./NodeSession.js";
 import { Session, SessionParameterOptions } from "./Session.js";
 import { SessionManager, UNICAST_UNSECURE_SESSION_ID } from "./SessionManager.js";
 
@@ -20,6 +20,7 @@ export class InsecureSession extends Session {
     readonly #initiatorNodeId: NodeId;
     readonly closingAfterExchangeFinished = false;
     readonly supportsMRP = true;
+    readonly type = SessionType.Unicast;
 
     constructor(args: {
         manager?: SessionManager;

package/src/session/NodeSession.ts

@@ -0,0 +1,367 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Subject } from "#action/server/Subject.js";
+import { DecodedMessage, DecodedPacket, Message, MessageCodec, Packet, SessionType } from "#codec/MessageCodec.js";
+import { Fabric } from "#fabric/Fabric.js";
+import { BasicSet, Bytes, CRYPTO_SYMMETRIC_KEY_LENGTH, Crypto, Diagnostic, Logger, MatterFlowError } from "#general";
+import { Subscription } from "#interaction/Subscription.js";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { NoChannelError } from "#protocol/ChannelManager.js";
+import { MessageCounter } from "#protocol/MessageCounter.js";
+import { MessageReceptionStateEncryptedWithoutRollover } from "#protocol/MessageReceptionState.js";
+import { CaseAuthenticatedTag, FabricIndex, NodeId, StatusCode, StatusResponseError } from "#types";
+import { SecureSession } from "./SecureSession.js";
+import { Session, SessionParameterOptions } from "./Session.js";
+import { type SessionManager } from "./SessionManager.js";
+
+const logger = Logger.get("SecureSession");
+
+const SESSION_KEYS_INFO = Bytes.fromString("SessionKeys");
+const SESSION_RESUMPTION_KEYS_INFO = Bytes.fromString("SessionResumptionKeys");
+
+export class NoAssociatedFabricError extends StatusResponseError {
+    constructor(message: string) {
+        super(message, StatusCode.UnsupportedAccess);
+    }
+}
+
+export class NodeSession extends SecureSession {
+    readonly #subscriptions = new BasicSet<Subscription>();
+    #closingAfterExchangeFinished = false;
+    #sendCloseMessageWhenClosing = true;
+    readonly #id: number;
+    readonly #isInitiator: boolean;
+    #fabric: Fabric | undefined;
+    readonly #peerNodeId: NodeId;
+    readonly #peerSessionId: number;
+    readonly #decryptKey: Uint8Array;
+    readonly #encryptKey: Uint8Array;
+    readonly #attestationKey: Uint8Array;
+    #caseAuthenticatedTags: CaseAuthenticatedTag[];
+    #isClosing = false;
+    readonly supportsMRP = true;
+    readonly type = SessionType.Unicast;
+
+    static async create(args: {
+        manager?: SessionManager;
+        id: number;
+        fabric: Fabric | undefined;
+        peerNodeId: NodeId;
+        peerSessionId: number;
+        sharedSecret: Uint8Array;
+        salt: Uint8Array;
+        isInitiator: boolean;
+        isResumption: boolean;
+        peerSessionParameters?: SessionParameterOptions;
+        caseAuthenticatedTags?: CaseAuthenticatedTag[];
+    }) {
+        const {
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            sharedSecret,
+            salt,
+            isInitiator,
+            isResumption,
+            peerSessionParameters,
+            caseAuthenticatedTags,
+        } = args;
+        const keys = await Crypto.hkdf(
+            sharedSecret,
+            salt,
+            isResumption ? SESSION_RESUMPTION_KEYS_INFO : SESSION_KEYS_INFO,
+            CRYPTO_SYMMETRIC_KEY_LENGTH * 3,
+        );
+        const decryptKey = isInitiator ? keys.slice(16, 32) : keys.slice(0, 16);
+        const encryptKey = isInitiator ? keys.slice(0, 16) : keys.slice(16, 32);
+        const attestationKey = keys.slice(32, 48);
+        return new NodeSession({
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            decryptKey,
+            encryptKey,
+            attestationKey,
+            sessionParameters: peerSessionParameters,
+            isInitiator,
+            caseAuthenticatedTags,
+        });
+    }
+
+    constructor(args: {
+        manager?: SessionManager;
+        id: number;
+        fabric: Fabric | undefined;
+        peerNodeId: NodeId;
+        peerSessionId: number;
+        decryptKey: Uint8Array;
+        encryptKey: Uint8Array;
+        attestationKey: Uint8Array;
+        sessionParameters?: SessionParameterOptions;
+        caseAuthenticatedTags?: CaseAuthenticatedTag[];
+        isInitiator: boolean;
+    }) {
+        super({
+            ...args,
+            setActiveTimestamp: true, // We always set the active timestamp for Secure sessions
+            // Can be changed to a PersistedMessageCounter if we implement session storage
+            messageCounter: new MessageCounter(() => {
+                // Secure Session Message Counter
+                // Expire/End the session before the counter rolls over
+                this.end(true, true).catch(error => logger.error(`Error while closing session: ${error}`));
+            }),
+            messageReceptionState: new MessageReceptionStateEncryptedWithoutRollover(),
+        });
+        const {
+            manager,
+            id,
+            fabric,
+            peerNodeId,
+            peerSessionId,
+            decryptKey,
+            encryptKey,
+            attestationKey,
+            caseAuthenticatedTags,
+            isInitiator,
+        } = args;
+
+        this.#id = id;
+        this.#fabric = fabric;
+        this.#peerNodeId = peerNodeId;
+        this.#peerSessionId = peerSessionId;
+        this.#decryptKey = decryptKey;
+        this.#encryptKey = encryptKey;
+        this.#attestationKey = attestationKey;
+        this.#caseAuthenticatedTags = caseAuthenticatedTags ?? [];
+        this.#isInitiator = isInitiator;
+
+        manager?.sessions.add(this);
+        fabric?.addSession(this);
+
+        logger.debug(
+            `Created secure ${this.isPase ? "PASE" : "CASE"} session for fabric index ${fabric?.fabricIndex}`,
+            this.name,
+            this.parameterDiagnostics(),
+        );
+    }
+
+    parameterDiagnostics() {
+        return Diagnostic.dict(
+            {
+                SII: this.idleIntervalMs,
+                SAI: this.activeIntervalMs,
+                SAT: this.activeThresholdMs,
+                DMRev: this.dataModelRevision,
+                IMRev: this.interactionModelRevision,
+                spec: Diagnostic.hex(this.specificationVersion),
+                maxPaths: this.maxPathsPerInvoke,
+                CATs: this.#caseAuthenticatedTags,
+            },
+            true,
+        );
+    }
+
+    get caseAuthenticatedTags() {
+        return this.#caseAuthenticatedTags;
+    }
+
+    get closingAfterExchangeFinished() {
+        return this.#closingAfterExchangeFinished;
+    }
+
+    get sendCloseMessageWhenClosing() {
+        return this.#sendCloseMessageWhenClosing;
+    }
+
+    get isPase(): boolean {
+        return this.#peerNodeId === NodeId.UNSPECIFIED_NODE_ID;
+    }
+
+    get subscriptions() {
+        return this.#subscriptions;
+    }
+
+    get isInitiator() {
+        return this.#isInitiator;
+    }
+
+    get isClosing() {
+        return this.#isClosing;
+    }
+
+    subjectFor(_message?: Message): Subject {
+        return Subject.Node({
+            id: this.peerNodeId,
+            catSubjects: this.#caseAuthenticatedTags.map(cat => NodeId.fromCaseAuthenticatedTag(cat)),
+        });
+    }
+
+    async close(closeAfterExchangeFinished?: boolean) {
+        if (closeAfterExchangeFinished === undefined) {
+            closeAfterExchangeFinished = this.isPeerActive(); // We delay session close if the peer is actively communicating with us
+        }
+        await this.end(true, closeAfterExchangeFinished);
+    }
+
+    decode({ header, applicationPayload, messageExtension }: DecodedPacket, aad: Uint8Array): DecodedMessage {
+        if (header.hasMessageExtensions) {
+            logger.info(
+                `Message extensions are not supported. Ignoring ${messageExtension ? Bytes.toHex(messageExtension) : undefined}`,
+            );
+        }
+        const nonce = Session.generateNonce(header.securityFlags, header.messageId, this.#peerNodeId);
+        const message = MessageCodec.decodePayload({
+            header,
+            applicationPayload: Crypto.decrypt(this.#decryptKey, applicationPayload, nonce, aad),
+        });
+
+        if (message.payloadHeader.hasSecuredExtension) {
+            logger.info(
+                `Secured extensions are not supported. Ignoring ${message.securityExtension ? Bytes.toHex(message.securityExtension) : undefined}`,
+            );
+        }
+
+        return message;
+    }
+
+    encode(message: Message): Packet {
+        message.packetHeader.sessionId = this.#peerSessionId;
+        const { header, applicationPayload } = MessageCodec.encodePayload(message);
+        const headerBytes = MessageCodec.encodePacketHeader(message.packetHeader);
+        const securityFlags = headerBytes[3];
+        const sessionNodeId = this.isPase
+            ? NodeId.UNSPECIFIED_NODE_ID
+            : (this.#fabric?.nodeId ?? NodeId.UNSPECIFIED_NODE_ID);
+        const nonce = Session.generateNonce(securityFlags, header.messageId, sessionNodeId);
+        return { header, applicationPayload: Crypto.encrypt(this.#encryptKey, applicationPayload, nonce, headerBytes) };
+    }
+
+    get attestationChallengeKey(): Uint8Array {
+        return this.#attestationKey;
+    }
+
+    get fabric() {
+        return this.#fabric;
+    }
+
+    addAssociatedFabric(fabric: Fabric) {
+        if (this.#fabric !== undefined) {
+            throw new MatterFlowError("Session already has an associated Fabric. Cannot change this.");
+        }
+        this.#fabric = fabric;
+    }
+
+    get id() {
+        return this.#id;
+    }
+
+    get name() {
+        return `secure/${this.#id}`;
+    }
+
+    get peerSessionId(): number {
+        return this.#peerSessionId;
+    }
+
+    get nodeId() {
+        return this.#fabric?.nodeId ?? NodeId.UNSPECIFIED_NODE_ID;
+    }
+
+    get peerNodeId() {
+        return this.#peerNodeId;
+    }
+
+    get associatedFabric(): Fabric {
+        if (this.#fabric === undefined) {
+            throw new NoAssociatedFabricError(
+                `${this.isPase ? "PASE " : ""}Session needs to have an associated Fabric for fabric sensitive data handling.`,
+            );
+        }
+        return this.#fabric;
+    }
+
+    async clearSubscriptions(flushSubscriptions = false, cancelledByPeer = false) {
+        const subscriptions = [...this.#subscriptions]; // get all values because subscriptions will remove themselves when cancelled
+        for (const subscription of subscriptions) {
+            await subscription.close(flushSubscriptions, cancelledByPeer);
+        }
+        return subscriptions.length;
+    }
+
+    /** Ends a session. Outstanding subscription data will be flushed before the session is destroyed. */
+    async end(sendClose: boolean, closeAfterExchangeFinished = false) {
+        await this.clearSubscriptions(true);
+        await this.destroy(sendClose, closeAfterExchangeFinished);
+    }
+
+    /** Destroys a session. Outstanding subscription data will be discarded. */
+    async destroy(sendClose = false, closeAfterExchangeFinished = true) {
+        await this.clearSubscriptions(false);
+        this.#fabric?.removeSession(this);
+        if (!sendClose) {
+            this.#sendCloseMessageWhenClosing = false;
+        }
+
+        if (closeAfterExchangeFinished) {
+            logger.info(`Register Session ${this.name} to close when exchange is ended.`);
+            this.#closingAfterExchangeFinished = true;
+        } else {
+            this.#isClosing = true;
+            logger.info(`End ${this.isPase ? "PASE" : "CASE"} session ${this.name}`);
+            this.manager?.sessions.delete(this);
+
+            // Wait for the exchange to finish closing, but ignore errors if channel is already closed
+            if (this.closer) {
+                try {
+                    await this.closer;
+                } catch (error) {
+                    NoChannelError.accept(error);
+                } finally {
+                    await this.destroyed.emit();
+                }
+                return;
+            }
+            await this.destroyed.emit();
+        }
+    }
+
+    /**
+     * The peer node's address.
+     */
+    get peerAddress() {
+        return PeerAddress({
+            fabricIndex: this.#fabric?.fabricIndex ?? FabricIndex.NO_FABRIC,
+            nodeId: this.#peerNodeId,
+        });
+    }
+
+    /**
+     * Indicates whether a peer matches a specific address.
+     */
+    peerIs(address: PeerAddress) {
+        return (
+            (this.#fabric?.fabricIndex ?? FabricIndex.NO_FABRIC) === address.fabricIndex &&
+            this.#peerNodeId === address.nodeId
+        );
+    }
+}
+
+export namespace NodeSession {
+    export function assert(session?: Session, errorText?: string): asserts session is NodeSession {
+        if (!is(session)) {
+            throw new MatterFlowError(errorText ?? "Insecure session in secure context");
+        }
+    }
+
+    export function is(session?: Session): session is NodeSession {
+        return session?.type === SessionType.Unicast;
+    }
+}