@matter/node 0.14.1-alpha.0-20250607-a93593303 → 0.15.0-alpha.0-20250613-a55f991d4

package/src/behavior/cluster/FabricScopedDataHandler.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior, ClusterBehavior } from "#behavior/index.js";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import { SupportedElements } from "#endpoint/properties/Behaviors.js";
+import { createPromise, deepCopy, isObject, Logger, MaybePromise, withTimeout } from "#general";
+import { ServerNode } from "#node/ServerNode.js";
+import { OccurrenceManager, Val } from "#protocol";
+import { ClusterType, FabricIndex, ObjectSchema } from "#types";
+
+const logger = Logger.get("FabricScopedDataHandler");
+
+/** Helper function to iterate over all behaviors of an endpoint */
+async function forBehaviors(
+    endpoint: Endpoint,
+    callback: (type: Behavior.Type, cluster: ClusterType, elements: SupportedElements) => Promise<void>,
+) {
+    for (const type of Object.values(endpoint.behaviors.supported)) {
+        const cluster = (type as ClusterBehavior.Type)?.cluster;
+        if (!cluster) {
+            continue;
+        }
+        const elements = endpoint.behaviors.elementsOf(type);
+        if (elements.attributes.size || elements.events.size) {
+            await callback(type, cluster, elements);
+        }
+    }
+}
+
+/**
+ * Sanitize fabric-scoped attributes for a given endpoint and cluster.
+ * The changed state is returned in an array of promises and should be awaited to ensure the state is updated.
+ */
+async function sanitizeAttributeData(
+    endpoint: Endpoint,
+    type: Behavior.Type,
+    cluster: ClusterType,
+    supportedAttributes: Set<string>,
+    allowedIndices: FabricIndex[],
+) {
+    const stateUpdatePromises = new Array<Promise<void>>();
+
+    const stateUpdate = {} as Val.Struct;
+    // Iterate over all attributes and check if they are fabric-scoped
+    for (const attributeName of supportedAttributes) {
+        const attr = cluster.attributes[attributeName];
+        if (attr.fabricScoped) {
+            const value = (endpoint.stateOf(type) as Val.Struct)[attributeName];
+            // If the value contains data for the fabric being removed, remove the data
+            if (Array.isArray(value) && value.length > 0) {
+                const filtered = deepCopy(value).filter(entry => allowedIndices.includes(entry.fabricIndex));
+                if (filtered.length !== value.length) {
+                    stateUpdate[attributeName] = filtered;
+                }
+            }
+        }
+    }
+    // If we have any state updates for this behavior, we need to set the state.
+    // Errors are being logged and ignored
+    if (Object.keys(stateUpdate).length > 0) {
+        const { resolver, promise } = createPromise<void>();
+        (endpoint.eventsOf(type) as Behavior.EventsOf<any>).stateChanged?.on(resolver);
+        try {
+            await endpoint.setStateOf(type, stateUpdate);
+            stateUpdatePromises.push(withTimeout(5_000, promise)); // 5s should be enough for state change
+        } catch (error) {
+            logger.warn(
+                `Could not sanitize fabric-scoped attributes for cluster ${cluster.name} on endpoint ${endpoint.id}`,
+                error,
+            );
+        }
+    }
+
+    return stateUpdatePromises;
+}
+
+/**
+ * Sanitize Fabric scoped data and events to a list of allowed fabrics.
+ * The logic walks through all endpoints and removes relevant fabric-scoped attribute values for the relevant fabric
+ * from the state. After all state changes are processed, it removes all occurrences of fabric-scoped events.
+ */
+export async function limitNodeDataToAllowedFabrics(node: ServerNode, allowedIndices: FabricIndex[]) {
+    const fabricRelevantEvents = new Set<string>();
+    const stateUpdatePromises = new Array<Promise<void>>();
+    await node.visit(async endpoint => {
+        await forBehaviors(endpoint, async (type, cluster, elements) => {
+            if (elements.attributes.size) {
+                stateUpdatePromises.push(
+                    ...(await sanitizeAttributeData(endpoint, type, cluster, elements.attributes, allowedIndices)),
+                );
+            }
+            if (elements.events.size) {
+                // If we have events also check if they are fabric scoped and collect them
+                for (const eventName of elements.events) {
+                    const event = cluster.events[eventName];
+                    if ((event.schema as ObjectSchema<any>).isFabricScoped) {
+                        fabricRelevantEvents.add(`${cluster.id}-${event.id}`);
+                    }
+                }
+            }
+        });
+    });
+
+    // Wait for all state changed to be executed before processing events
+    await Promise.allSettled(stateUpdatePromises);
+
+    // Now we can remove all occurrences of fabric-scoped events when payload is bound to this fabric index
+    if (fabricRelevantEvents.size > 0) {
+        const occurrences = node.env.get(OccurrenceManager);
+        for await (const event of occurrences.get()) {
+            if (
+                fabricRelevantEvents.has(`${event.clusterId}-${event.eventId}`) &&
+                isObject(event.payload) &&
+                !allowedIndices.includes(event.payload.fabricIndex as FabricIndex)
+            ) {
+                // Remove occurrences of fabric-scoped events
+                const result = occurrences.remove(event.number);
+                if (MaybePromise.is(result)) {
+                    await result;
+                }
+            }
+        }
+    }
+}
+
+export async function limitEndpointAttributeDataToAllowedFabrics(endpoint: Endpoint, allowedIndices: FabricIndex[]) {
+    const stateUpdatePromises = new Array<Promise<void>>();
+    await forBehaviors(endpoint, async (type, cluster, elements) => {
+        if (elements.attributes.size) {
+            stateUpdatePromises.push(
+                ...(await sanitizeAttributeData(endpoint, type, cluster, elements.attributes, allowedIndices)),
+            );
+        }
+    });
+
+    // Wait for all state changed to be executed before processing events
+    await Promise.allSettled(stateUpdatePromises);
+}

package/src/behavior/cluster/index.ts

@@ -9,4 +9,5 @@ export * from "./ClusterBehaviorUtil.js";
 export * from "./ClusterEvents.js";
 export * from "./ClusterInterface.js";
 export * from "./ClusterState.js";
+export * from "./FabricScopedDataHandler.js";
 export * from "./ValidatedElements.js";

package/src/behavior/context/server/OnlineContext.ts

@@ -4,21 +4,33 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AccessControlServer } from "#behaviors/access-control";
 import { Agent } from "#endpoint/Agent.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointType } from "#endpoint/type/EndpointType.js";
-import { Diagnostic, ImplementationError, InternalError, MaybePromise, Transaction } from "#general";
+import { AsyncObservable, Diagnostic, ImplementationError, InternalError, MaybePromise, Transaction } from "#general";
 import { AccessLevel } from "#model";
 import type { Node } from "#node/Node.js";
 import type { Message, NodeProtocol } from "#protocol";
-import { AccessControl, AclEndpointContext, MessageExchange, SecureSession, Subject } from "#protocol";
+import {
+    AccessControl,
+    AclEndpointContext,
+    FabricAccessControl,
+    MessageExchange,
+    SecureSession,
+    Subject,
+} from "#protocol";
 import { FabricIndex, NodeId } from "#types";
 import { ActionContext } from "../ActionContext.js";
 import { Contextual } from "../Contextual.js";
 import { NodeActivity } from "../NodeActivity.js";
 import { ContextAgents } from "./ContextAgents.js";
 
+/**
+ * Caches completion events per exchange. Uses if multiple OnlineContext instances are created for an exchange.
+ * Entries will be cleaned up when the exchange is closed.
+ */
+const exchangeCompleteEvents = new WeakMap<MessageExchange, AsyncObservable<[session?: ActionContext | undefined]>>();
+
 /**
  * Operate in online context.  Public Matter API interactions happen in online context.
  */
@@ -27,6 +39,7 @@ export function OnlineContext(options: OnlineContext.Options) {
     let subject: Subject;
     let nodeProtocol: NodeProtocol | undefined;
     let accessLevelCache: Map<AccessControl.Location, number[]> | undefined;
+    let aclManager: FabricAccessControl;
 
     const { exchange, message } = options;
     const session = exchange?.session;
@@ -35,6 +48,8 @@ export function OnlineContext(options: OnlineContext.Options) {
         SecureSession.assert(session);
         fabric = session.fabric?.fabricIndex;
         subject = session.subjectFor(message);
+        // Without a fabric, we assume default PASE based access controls and use a fresh FabricAccessControlManager instance
+        aclManager = session?.fabric?.acl ?? new FabricAccessControl();
     } else {
         fabric = options.fabric;
         if (options.subject !== undefined) {
@@ -42,6 +57,7 @@ export function OnlineContext(options: OnlineContext.Options) {
         } else {
             throw new ImplementationError("OnlineContext requires an authorized subject");
         }
+        aclManager = options.aclManager ?? new FabricAccessControl();
     }
 
     // If we have subjects, the first is the main one, used for diagnostics
@@ -135,6 +151,23 @@ export function OnlineContext(options: OnlineContext.Options) {
             SecureSession.assert(session);
         }
         let agents: undefined | ContextAgents;
+        let interactionComplete: AsyncObservable<[session?: ActionContext | undefined]> | undefined;
+        if (exchange !== undefined) {
+            interactionComplete = exchangeCompleteEvents.get(exchange);
+            if (interactionComplete === undefined) {
+                interactionComplete = new AsyncObservable();
+                exchangeCompleteEvents.set(exchange, interactionComplete);
+            }
+
+            const notifyInteractionComplete = () => {
+                exchange.closing.off(notifyInteractionComplete);
+                exchangeCompleteEvents.delete(exchange);
+                if (context.interactionComplete?.isObserved) {
+                    context.interactionComplete.emit(context);
+                }
+            };
+            exchange.closing.on(notifyInteractionComplete);
+        }
         const context: ActionContext = {
             ...options,
             session,
@@ -144,7 +177,7 @@ export function OnlineContext(options: OnlineContext.Options) {
             fabric,
             transaction,
 
-            interactionComplete: exchange?.closed,
+            interactionComplete,
 
             ...methods,
 
@@ -166,11 +199,7 @@ export function OnlineContext(options: OnlineContext.Options) {
                     throw new InternalError("OnlineContext initialized without node");
                 }
 
-                const accessControl = options.node.act(agent => agent.get(AccessControlServer));
-                if (MaybePromise.is(accessControl)) {
-                    throw new InternalError("AccessControlServer should already be initialized.");
-                }
-                const accessLevels = accessControl.accessLevelsFor(context, location, aclEndpointContextFor(location));
+                const accessLevels = aclManager.accessLevelsFor(context, location, aclEndpointContextFor(location));
 
                 if (accessLevelCache === undefined) {
                     accessLevelCache = new Map();
@@ -238,6 +267,7 @@ export namespace OnlineContext {
         timed?: boolean;
         fabricFiltered?: boolean;
         message?: Message;
+        aclManager?: FabricAccessControl;
     } & (
         | { exchange: MessageExchange; fabric?: undefined; subject?: undefined }
         | { exchange?: undefined; fabric: FabricIndex; subject: NodeId }

package/src/behavior/state/managed/Datasource.ts

@@ -26,7 +26,7 @@ const logger = Logger.get("Datasource");
 
 const FEATURES_KEY = "__features__";
 
-const stateChanged = Symbol("stateChanged");
+const changed = Symbol("changed");
 
 const viewTx = Transaction.open("offline-view", "ro");
 
@@ -66,7 +66,7 @@ export interface Datasource<T extends StateType = StateType> extends Transaction
     /**
      * Event that gets emitted when the state changes.
      */
-    stateChanged: Observable<[changes: string[], version: number], MaybePromise>;
+    changed: Observable<[changes: string[], version: number], MaybePromise>;
 
     /**
      * Events registered for this Datasource
@@ -103,8 +103,8 @@ export function Datasource<const T extends StateType = StateType>(options: Datas
             return internals.location;
         },
 
-        get stateChanged() {
-            return internals.events[stateChanged];
+        get changed() {
+            return internals.events[changed];
         },
 
         get events() {
@@ -142,14 +142,15 @@ export namespace Datasource {
      * Datasource events.
      */
     export type Events = {
-        interactionBegin?: Observable<[]>;
-        interactionEnd?: Observable<[], MaybePromise>;
+        interactionBegin?: Observable<[context?: ValueSupervisor.Session], MaybePromise>;
+        interactionEnd?: Observable<[context?: ValueSupervisor.Session], MaybePromise>;
+        stateChanged?: Observable<[context?: ValueSupervisor.Session], MaybePromise>;
     } & {
         [K in `${string}$Changing` | `${string}$Changed`]: Observable<Parameters<ValueObserver>, MaybePromise>;
     };
 
     export type InternalEvents = Events & {
-        [stateChanged]: Observable<[changes: string[], version: number], MaybePromise>;
+        [changed]: Observable<[changes: string[], version: number], MaybePromise>;
     };
 
     /**
@@ -235,7 +236,7 @@ interface Internals extends Datasource.Options {
     version: number;
     sessions?: Map<ValueSupervisor.Session, SessionContext>;
     featuresKey?: string;
-    interactionObserver(): MaybePromise<void>;
+    interactionObserver(session?: AccessControl.Session): MaybePromise<void>;
     events: Datasource.InternalEvents;
 }
 
@@ -246,7 +247,7 @@ interface CommitChanges {
     persistent?: Val.Struct;
     notifications: Array<{
         event: Observable<any[], MaybePromise>;
-        params: Parameters<Datasource.ValueObserver>;
+        params: Parameters<Datasource.ValueObserver> | [context?: ValueSupervisor.Session];
     }>;
     changeList: Set<string>;
 }
@@ -285,7 +286,7 @@ function configure(options: Datasource.Options): Internals {
     Object.freeze(options.location);
 
     const events = (options.events ?? {}) as Datasource.InternalEvents;
-    events[stateChanged] = new Observable();
+    events[changed] = new Observable();
 
     return {
         ...options,
@@ -294,18 +295,20 @@ function configure(options: Datasource.Options): Internals {
         values: values,
         featuresKey,
 
-        interactionObserver() {
+        interactionObserver(session?: ValueSupervisor.Session) {
             function handleObserverError(error: any) {
                 logger.error(`Error in ${options.location.path} observer:`, error);
             }
 
-            try {
-                const result = options.events?.interactionEnd?.emit();
-                if (MaybePromise.is(result)) {
-                    return MaybePromise.then(result, undefined, handleObserverError);
+            if (options.events?.interactionEnd?.isObserved) {
+                try {
+                    const result = options.events?.interactionEnd?.emit(session);
+                    if (MaybePromise.is(result)) {
+                        return MaybePromise.then(result, undefined, handleObserverError);
+                    }
+                } catch (e) {
+                    handleObserverError(e);
                 }
-            } catch (e) {
-                handleObserverError(e);
             }
         },
     };
@@ -468,8 +471,15 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
         // Enter exclusive mode.  This will throw if my lock is unavailable
         transaction.beginSync();
 
-        if (session.interactionComplete && !session.interactionComplete.isObservedBy(internals.interactionObserver)) {
-            internals.events?.interactionBegin?.emit();
+        if (
+            !session.interactionStarted &&
+            session.interactionComplete &&
+            !session.interactionComplete.isObservedBy(internals.interactionObserver)
+        ) {
+            session.interactionStarted = true;
+            if (internals.events?.interactionBegin?.isObserved) {
+                internals.events?.interactionBegin?.emit(session);
+            }
             session.interactionComplete.on(internals.interactionObserver);
         }
     }
@@ -613,6 +623,13 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
         if (changes) {
             // We don't revert the version number on rollback.  Should be OK
             incrementVersion();
+
+            if (internals.events.stateChanged?.isObserved) {
+                changes.notifications.push({
+                    event: internals.events.stateChanged,
+                    params: [session],
+                });
+            }
         }
     }
 
@@ -678,7 +695,7 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
             }
         }
 
-        const changeSetResult = internals.events[stateChanged]?.emit(
+        const changeSetResult = internals.events[changed]?.emit(
             Array.from(changes.changeList.values()),
             internals.version,
         );

package/src/behavior/supervision/ValueSupervisor.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Transaction } from "#general";
-import { AsyncObservable } from "#general";
+import { ActionContext } from "#behavior/context/ActionContext.js";
+import type { AsyncObservable, Transaction } from "#general";
 import { DataModelPath, Schema } from "#model";
 import type { AccessControl, Val } from "#protocol";
 import type { ValidationLocation } from "../state/validation/location.js";
@@ -84,7 +84,12 @@ export namespace ValueSupervisor {
         /**
          * If present the session is associated with an online interaction.  Emits when the interaction ends.
          */
-        interactionComplete?: AsyncObservable<[]>;
+        interactionComplete?: AsyncObservable<[session?: ActionContext]>;
+
+        /**
+         * Set to true when the interaction has started and the interactionBegin event was emitted for this session
+         */
+        interactionStarted?: boolean;
 
         /**
          * If true, structs initialize without named properties which are more expensive to install.  This is useful