@matter/node 0.17.4 → 0.17.5-alpha.0-20260704-9ea70abfa

package/src/node/server/InteractionServer.ts

@@ -53,6 +53,7 @@ import {
     AttributePath,
     DEFAULT_MAX_PATHS_PER_INVOKE,
     EventPath,
+    GroupId,
     INTERACTION_PROTOCOL_ID,
     InvokeResponseData,
     ReceivedStatusResponseError,
@@ -65,12 +66,19 @@ import {
     TlvSubscribeResponse,
     TypeFromSchema,
 } from "@matter/types";
+import { Groupcast } from "@matter/types/clusters/groupcast";
 import { ServerNode } from "../ServerNode.js";
 import { OnlineServerInteraction } from "./OnlineServerInteraction.js";
 import { ServerSubscription, ServerSubscriptionConfig, ServerSubscriptionContext } from "./ServerSubscription.js";
 
 const logger = Logger.get("InteractionServer");
 
+// Hard acceptance ceiling for paths in a single read/subscribe interaction, set to the upper bound of the
+// CapabilityMinimaStruct field constraints in the data model.  Separate from the advertised CapabilityMinima defaults:
+// we advertise a guaranteed floor and accept up to this ceiling, blocking only beyond it.
+const MAX_READ_PATHS = 10_000;
+const MAX_SUBSCRIBE_PATHS = 10_000;
+
 export interface PeerSubscription {
     subscriptionId: number;
     peerAddress: PeerAddress;
@@ -83,6 +91,13 @@ export interface PeerSubscription {
     sendInterval: Duration;
 }
 
+/** Cumulative counters tracked by the interaction server since startup. */
+export interface InteractionCounters {
+    totalSubscriptionsEstablished: number;
+    totalInteractionModelMessagesSent: number;
+    totalInteractionModelMessagesReceived: number;
+}
+
 function validateReadAttributesPath(path: AttributePath) {
     const { clusterId, attributeId } = path;
     if (clusterId === undefined && attributeId !== undefined) {
@@ -139,6 +154,11 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
     #newActivityBlocked = false;
     #aclServer?: AccessControlServer;
     #serverInteraction: OnlineServerInteraction;
+    #counters: InteractionCounters = {
+        totalSubscriptionsEstablished: 0,
+        totalInteractionModelMessagesSent: 0,
+        totalInteractionModelMessagesReceived: 0,
+    };
 
     constructor(node: ServerNode, sessions: SessionManager) {
         this.#lifetime = node.construction.join("interaction server");
@@ -182,6 +202,10 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         return this.#subscriptionEstablishmentStarted;
     }
 
+    get counters(): InteractionCounters {
+        return this.#counters;
+    }
+
     async onNewExchange(exchange: MessageExchange, message: Message) {
         // When closing, ignore anything newly incoming
         if (this.#newActivityBlocked || this.isClosing) {
@@ -194,6 +218,11 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
             return await this.clientHandler.onNewExchange(exchange, message);
         }
 
+        // Count the initiating message (received before the exchange notifier could be attached) then track all
+        // further sends/receipts on this exchange (chunked DataReports, StatusResponse acks, etc.)
+        this.#counters.totalInteractionModelMessagesReceived++;
+        this.#countExchangeMessages(exchange);
+
         // Activity tracking.  This provides diagnostic information and prevents the server from shutting down whilst
         // the exchange is active
         using activity = this.#activity.begin(`session#${exchange.session.id.toString(16)}`);
@@ -207,6 +236,23 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         }
     }
 
+    /**
+     * Attach per-message counters to an exchange so DeviceLoadStatus reflects every IM message sent and received.
+     * Excludes MRP retransmissions (only the initial transmission of each message counts) and duplicate receipts.
+     */
+    #countExchangeMessages(exchange: MessageExchange) {
+        exchange.onSend = (_, retransmission) => {
+            if (retransmission === 0) {
+                this.#counters.totalInteractionModelMessagesSent++;
+            }
+        };
+        exchange.onReceive = (_, duplicate) => {
+            if (!duplicate) {
+                this.#counters.totalInteractionModelMessagesReceived++;
+            }
+        };
+    }
+
     get aclServer() {
         if (this.#aclServer !== undefined) {
             return this.#aclServer;
@@ -313,6 +359,14 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
 
         validateReadPaths(attributeRequests, eventRequests);
 
+        const readPathsCount = (attributeRequests?.length ?? 0) + (eventRequests?.length ?? 0);
+        if (readPathsCount > MAX_READ_PATHS) {
+            throw new StatusResponseError(
+                `Read request with ${readPathsCount} paths exceeds maximum of ${MAX_READ_PATHS}`,
+                Status.PathsExhausted,
+            );
+        }
+
         return {
             dataReport: {
                 interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
@@ -539,6 +593,14 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
             throw new StatusResponseError("Subscriptions are only allowed on unicast sessions", Status.InvalidAction);
         }
 
+        const subscribePathsCount = (attributeRequests?.length ?? 0) + (eventRequests?.length ?? 0);
+        if (subscribePathsCount > MAX_SUBSCRIBE_PATHS) {
+            throw new StatusResponseError(
+                `Subscribe request with ${subscribePathsCount} paths exceeds maximum of ${MAX_SUBSCRIBE_PATHS}`,
+                Status.PathsExhausted,
+            );
+        }
+
         NodeSession.assert(exchange.session, "Subscriptions are only implemented on secure sessions");
         const session = exchange.session;
         const fabric = session.fabric;
@@ -676,13 +738,19 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
 
         // When an error occurs while sending the response, the subscription is not yet active and will be cleaned up by GC
         subscription.activate();
+        this.#counters.totalSubscriptionsEstablished++;
     }
 
     #initiateSubscriptionExchange(addressOrSession: PeerAddress | Session, protocolId: number) {
-        if (addressOrSession instanceof Session) {
-            return this.#context.exchangeManager.initiateExchangeForSession(addressOrSession, protocolId);
-        }
-        return this.#context.exchangeManager.initiateExchange(addressOrSession, protocolId);
+        const exchange =
+            addressOrSession instanceof Session
+                ? this.#context.exchangeManager.initiateExchangeForSession(addressOrSession, protocolId)
+                : this.#context.exchangeManager.initiateExchange(addressOrSession, protocolId);
+
+        // Count subscription report messages we push and the acks we receive in response
+        this.#countExchangeMessages(exchange);
+
+        return exchange;
     }
 
     async #establishSubscription(
@@ -789,6 +857,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                 true, // Do not send status responses because we simulate that the subscription is still established
             );
             subscription.activate();
+            this.#counters.totalSubscriptionsEstablished++;
 
             logger.notice(
                 `Subscription successfully reestablished`,
@@ -869,9 +938,47 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         // Get the invoke-results from the server interaction
         const results = this.#serverInteraction.invoke(request, context);
 
-        // A groupcast invoke never produces a response; just consume the iterator.
+        // For group sessions: consume iterator, report each dispatched command to SessionManager so
+        // Groupcast testing (if enabled for the fabric) can emit the GroupcastTesting event
         if (isGroupSession) {
-            for await (const _chunk of results);
+            const rawGroupId = message.packetHeader.destGroupId;
+            const groupId = rawGroupId !== undefined ? GroupId(rawGroupId) : undefined;
+            const fabric = exchange.session.associatedFabric;
+            let emitted = false;
+            for await (const chunk of results) {
+                for (const data of chunk) {
+                    if (data.kind !== "cmd-response" && data.kind !== "cmd-status") {
+                        continue;
+                    }
+                    const accessAllowed = data.kind === "cmd-response" || data.status === Status.Success;
+                    this.#context.sessions.emitGroupMessage({
+                        result: Groupcast.GroupcastTestResult.Success,
+                        fabric,
+                        groupId,
+                        endpointId: data.path.endpointId,
+                        clusterId: data.path.clusterId,
+                        elementId: data.path.commandId,
+                        accessAllowed,
+                    });
+                    emitted = true;
+                }
+            }
+            // If wildcard expansion produced no dispatches (all paths filtered out by ACL or no
+            // endpoint mappings for the group), still emit one event per requested invoke path so
+            // observers see the message arrived. FailedAuth + accessAllowed=false signals denial.
+            if (!emitted) {
+                for (const { commandPath } of invokeRequests) {
+                    this.#context.sessions.emitGroupMessage({
+                        result: Groupcast.GroupcastTestResult.FailedAuth,
+                        fabric,
+                        groupId,
+                        endpointId: commandPath.endpointId,
+                        clusterId: commandPath.clusterId,
+                        elementId: commandPath.commandId,
+                        accessAllowed: false,
+                    });
+                }
+            }
             return;
         }
 

package/src/tags/ClosureCabinetTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the closure domain and shall NOT be used in any other
  * domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 26
+ * @see {@link MatterSpecification.v16.Namespace} § 26
  */
 export const ClosureCabinetTag = SemanticNamespace({
     id: 0x48,

package/src/tags/ClosureCoveringTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the closure domain and shall NOT be used in any other
  * domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 24
+ * @see {@link MatterSpecification.v16.Namespace} § 24
  */
 export const ClosureCoveringTag = SemanticNamespace({
     id: 0x46,

package/src/tags/ClosurePanelTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the closure panel domain and shall NOT be used in any
  * other domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 23
+ * @see {@link MatterSpecification.v16.Namespace} § 23
  */
 export const ClosurePanelTag = SemanticNamespace({
     id: 0x45,

package/src/tags/ClosureTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the closure domain and shall NOT be used in any other
  * domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 22
+ * @see {@link MatterSpecification.v16.Namespace} § 22
  */
 export const ClosureTag = SemanticNamespace({
     id: 0x44,

package/src/tags/ClosureWindowTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the closure domain and shall NOT be used in any other
  * domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 25
+ * @see {@link MatterSpecification.v16.Namespace} § 25
  */
 export const ClosureWindowTag = SemanticNamespace({
     id: 0x47,

package/src/tags/CommodityTariffChronologyTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the energy calendar domain and shall NOT be used in
  * any other domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 11
+ * @see {@link MatterSpecification.v16.Namespace} § 11
  */
 export const CommodityTariffChronologyTag = SemanticNamespace({
     id: 0xb,

package/src/tags/CommodityTariffCommodityTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the Commodity Tariff commodity domain and shall NOT be
  * used in any other domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 12
+ * @see {@link MatterSpecification.v16.Namespace} § 12
  */
 export const CommodityTariffCommodityTag = SemanticNamespace({
     id: 0xd,

package/src/tags/CommodityTariffFlowTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the Commodity Tariff flow domain and shall NOT be used
  * in any other domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 18
+ * @see {@link MatterSpecification.v16.Namespace} § 18
  */
 export const CommodityTariffFlowTag = SemanticNamespace({
     id: 0x13,

package/src/tags/CommonAreaNamespaceTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with an indoor
  * or outdoor area of a home.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 15
+ * @see {@link MatterSpecification.v16.Namespace} § 15
  */
 export const CommonAreaNamespaceTag = SemanticNamespace({
     id: 0x10,

package/src/tags/CommonClosureTag.ts

@@ -17,7 +17,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * > NOTE: This namespace has been deprecated as of Matter 1.4.2. Clients SHOULD still have support for these tags,
  *   since the tags could be used by a server certified on a previous revision of Matter.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 2
+ * @see {@link MatterSpecification.v16.Namespace} § 2
  */
 export const CommonClosureTag = SemanticNamespace({
     id: 0x1,

package/src/tags/CommonCompassDirectionTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with a movement
  * into a certain compass direction. Note the difference with Chapter 4, Common Compass Location Semantic Tag Namespace.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 3
+ * @see {@link MatterSpecification.v16.Namespace} § 3
  */
 export const CommonCompassDirectionTag = SemanticNamespace({
     id: 0x2,

package/src/tags/CommonCompassLocationTag.ts

@@ -13,7 +13,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * in a certain compass direction (e.g. an outdoor sensor in the North garden). Note the difference with Chapter 3,
  * Common Compass Direction Semantic Tag Namespace.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 4
+ * @see {@link MatterSpecification.v16.Namespace} § 4
  */
 export const CommonCompassLocationTag = SemanticNamespace({
     id: 0x3,

package/src/tags/CommonDirectionTag.ts

@@ -13,7 +13,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * in a certain direction relative to the device. Note the difference with Chapter 9, Common Position Semantic Tag
  * Namespace.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 5
+ * @see {@link MatterSpecification.v16.Namespace} § 5
  */
 export const CommonDirectionTag = SemanticNamespace({
     id: 0x4,

package/src/tags/CommonLandmarkNamespaceTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with a home
  * landmark.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 16
+ * @see {@link MatterSpecification.v16.Namespace} § 16
  */
 export const CommonLandmarkNamespaceTag = SemanticNamespace({
     id: 0x11,

package/src/tags/CommonLevelTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with a certain
  * level for a feature of a device (e.g. a button to set the speed of a fan).
  *
- * @see {@link MatterSpecification.v151.Namespace} § 6
+ * @see {@link MatterSpecification.v16.Namespace} § 6
  */
 export const CommonLevelTag = SemanticNamespace({
     id: 0x5,

package/src/tags/CommonLocationTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with a location
  * of a device (e.g. an outdoor temperature sensor).
  *
- * @see {@link MatterSpecification.v151.Namespace} § 7
+ * @see {@link MatterSpecification.v16.Namespace} § 7
  */
 export const CommonLocationTag = SemanticNamespace({
     id: 0x6,

package/src/tags/CommonNumberTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace may be used in any domain or context, to indicate an association with a certain
  * numeric feature of a device (e.g. a numeric input button).
  *
- * @see {@link MatterSpecification.v151.Namespace} § 8
+ * @see {@link MatterSpecification.v16.Namespace} § 8
  */
 export const CommonNumberTag = SemanticNamespace({
     id: 0x7,

package/src/tags/CommonPositionTag.ts

@@ -23,7 +23,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * comprised of Arabic numerals encoded as a string to indicate the row/column of the item. Number words (e.g. "one",
  * "two", etc.) shall NOT be used to describe the position of the item. The first row/column shall use Label "1".
  *
- * @see {@link MatterSpecification.v151.Namespace} § 9
+ * @see {@link MatterSpecification.v16.Namespace} § 9
  */
 export const CommonPositionTag = SemanticNamespace({
     id: 0x8,

package/src/tags/CommonRelativePositionTag.ts

@@ -15,7 +15,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * difference with Chapter 9, Common Position Semantic Tag Namespace, which contains tags indicating the position
  * relative to the device.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 17
+ * @see {@link MatterSpecification.v16.Namespace} § 17
  */
 export const CommonRelativePositionTag = SemanticNamespace({
     id: 0x12,

package/src/tags/ElectricalMeasurementTag.ts

@@ -12,7 +12,7 @@ import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
  * The tags contained in this namespace are restricted for use in the electrical measurement domain and shall NOT be
  * used in any other domain or context.
  *
- * @see {@link MatterSpecification.v151.Namespace} § 10
+ * @see {@link MatterSpecification.v16.Namespace} § 10
  */
 export const ElectricalMeasurementTag = SemanticNamespace({
     id: 0xa,

package/src/tags/IdentifiedHumanActivityTag.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE IS GENERATED, DO NOT EDIT ***/
+
+import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
+
+/**
+ * The tags contained in this namespace are intended to be used to identify human activity by some detection or sensing
+ * implementation.
+ *
+ * @see {@link MatterSpecification.v16.Namespace} § 29
+ */
+export const IdentifiedHumanActivityTag = SemanticNamespace({
+    id: 0x4b,
+
+    tags: {
+        /**
+         * Unknown human activity is detected.
+         */
+        Unknown: { id: 0x0, label: "Unknown" },
+
+        /**
+         * Human fall is detected.
+         */
+        Fall: { id: 0x1, label: "Fall" },
+
+        /**
+         * Human sleeping is detected.
+         */
+        Sleeping: { id: 0x2, label: "Sleeping" },
+
+        /**
+         * Human walking is detected.
+         */
+        Walking: { id: 0x3, label: "Walking" },
+
+        /**
+         * Human workout is detected.
+         */
+        Workout: { id: 0x4, label: "Workout" },
+
+        /**
+         * Human sitting is detected.
+         */
+        Sitting: { id: 0x5, label: "Sitting" },
+
+        /**
+         * Human standing is detected.
+         */
+        Standing: { id: 0x6, label: "Standing" },
+
+        /**
+         * Human dancing is detected.
+         */
+        Dancing: { id: 0x7, label: "Dancing" },
+
+        /**
+         * Human delivery of package is detected.
+         */
+        PackageDelivery: { id: 0x8, label: "PackageDelivery" },
+
+        /**
+         * Human retrieval of package is detected.
+         */
+        PackageRetrieval: { id: 0x9, label: "PackageRetrieval" }
+    }
+});

package/src/tags/IdentifiedObjectTag.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE IS GENERATED, DO NOT EDIT ***/
+
+import { SemanticNamespace } from "../endpoint/type/SemanticNamespace.js";
+
+/**
+ * This section contains the standard semantic tag namespace for identifiable objects to be exposed by some detection or
+ * sensing implementation.
+ *
+ * Thus, the tags contained in this namespace are intended to be used to identify a specific detected object for a
+ * common use.
+ *
+ * Regarding pet object identification, if an implementation enables a further specific pet identification such as a
+ * "Dog" or a "Cat", then the specific pet object identification tag shall be used instead of a generalized "Pet" object
+ * identification tag. If a client cannot recognize the specific pet identification tag, then, the client SHOULD
+ * recognize it either as a pet or an animal identification tag based on its recognition capability.
+ *
+ * Similarly, if an implementation enables a further specific person/human identification such as an "Adult" or a
+ * "Child", then the specific person/human object identification tag shall be used instead of a generalized "Person"
+ * object identification tag. If a client cannot recognize the specific person/human object identification tag, then,
+ * the client SHOULD recognize it either as a person or a human identification tag based on its recognition capability."
+ *
+ * @see {@link MatterSpecification.v16.Namespace} § 28
+ */
+export const IdentifiedObjectTag = SemanticNamespace({
+    id: 0x49,
+
+    tags: {
+        /**
+         * Unknown object is detected.
+         */
+        Unknown: { id: 0x0, label: "Unknown" },
+
+        /**
+         * Human adult is detected.
+         */
+        Adult: { id: 0x1, label: "Adult" },
+
+        /**
+         * Human child is detected.
+         */
+        Child: { id: 0x2, label: "Child" },
+
+        /**
+         * Person is detected.
+         */
+        Person: { id: 0x3, label: "Person" },
+
+        /**
+         * Robot Vacuum Cleaner is detected.
+         */
+        Rvc: { id: 0x4, label: "RVC" },
+
+        /**
+         * Pet animal is detected.
+         */
+        Pet: { id: 0x5, label: "Pet" },
+
+        /**
+         * Dog is detected.
+         */
+        Dog: { id: 0x6, label: "Dog" },
+
+        /**
+         * Cat is detected.
+         */
+        Cat: { id: 0x7, label: "Cat" },
+
+        /**
+         * Animal is detected.
+         */
+        Animal: { id: 0x8, label: "Animal" },
+
+        /**
+         * Car is detected.
+         */
+        Car: { id: 0x9, label: "Car" },
+
+        /**
+         * Vehicle is detected.
+         */
+        Vehicle: { id: 0xa, label: "Vehicle" },
+
+        /**
+         * Package is detected.
+         */
+        Package: { id: 0xb, label: "Package" },
+
+        /**
+         * Clothes are detected.
+         */
+        Clothes: { id: 0xc, label: "Clothes" }
+    }
+});