@matter/protocol 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/src/codec/MessageCodec.ts

@@ -4,12 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Mark } from "#common/Mark.js";
 import {
     Bytes,
     DataReader,
     DataWriter,
     Diagnostic,
     Endian,
+    hex,
     InternalError,
     NotImplementedError,
     UnexpectedDataError,
@@ -53,6 +55,7 @@ export interface Packet {
 export interface DecodedPacket extends Packet {
     header: DecodedPacketHeader;
 }
+
 export interface Message {
     packetHeader: PacketHeader;
     payloadHeader: PayloadHeader;
@@ -60,6 +63,42 @@ export interface Message {
     payload: Bytes;
 }
 
+export namespace Message {
+    export function via({ via }: { via: string }, { packetHeader: { messageId } }: Message) {
+        return Diagnostic.via(`${via}${Mark.MESSAGE}${hex.fixed(messageId, 8)}`);
+    }
+
+    export function diagnosticsOf(context: { via: string }, message: Message, logContext?: ExchangeLogContext) {
+        const {
+            payloadHeader: { messageType, protocolId, ackedMessageId, requiresAck },
+            payload,
+        } = message;
+
+        const duplicate = !!logContext?.duplicate;
+        const forInfo = logContext?.for;
+        const log = { ...logContext };
+        delete log.duplicate;
+        delete log.for;
+        const { type, for: forType } = mapProtocolAndMessageType(protocolId, messageType);
+        return Diagnostic.dict(
+            {
+                for: forInfo ?? forType,
+                ...log,
+                id: Message.via(context, message),
+                type,
+                acked: ackedMessageId === undefined ? undefined : hex.fixed(ackedMessageId, 8),
+                msgFlags: Diagnostic.asFlags({
+                    reqAck: requiresAck,
+                    dup: duplicate,
+                }),
+                size: payload.byteLength ? payload.byteLength : undefined,
+                payload: payload.byteLength ? payload : undefined,
+            },
+            true,
+        );
+    }
+}
+
 export interface DecodedMessage extends Message {
     packetHeader: DecodedPacketHeader;
 }
@@ -291,38 +330,6 @@ export class MessageCodec {
         return writer.toByteArray();
     }
 
-    static messageDiagnostics(
-        {
-            packetHeader: { messageId, sessionId },
-            payloadHeader: { exchangeId, messageType, protocolId, ackedMessageId, requiresAck },
-            payload,
-        }: Message,
-        logContext?: ExchangeLogContext,
-    ) {
-        const duplicate = !!logContext?.duplicate;
-        const forInfo = logContext?.for;
-        const log = { ...logContext };
-        delete log.duplicate;
-        delete log.for;
-        const { type, for: forType } = mapProtocolAndMessageType(protocolId, messageType);
-        return Diagnostic.dict(
-            {
-                for: forInfo ?? forType,
-                ...log,
-                msgId: `${sessionId}/${exchangeId}/${messageId}`,
-                type,
-                acked: ackedMessageId,
-                msgFlags: Diagnostic.asFlags({
-                    reqAck: requiresAck,
-                    dup: duplicate,
-                }),
-                size: payload.byteLength ? payload.byteLength : undefined,
-                payload: payload.byteLength ? payload : undefined,
-            },
-            true,
-        );
-    }
-
     private static encodePayloadHeader({
         exchangeId,
         isInitiatorMessage,

package/src/common/FailsafeContext.ts

@@ -14,7 +14,8 @@ import {
     UnexpectedDataError,
     UninitializedDependencyError,
 } from "#general";
-import { SecureSession } from "#session/SecureSession.js";
+import type { MessageExchange } from "#protocol/MessageExchange.js";
+import type { NodeSession } from "#session/NodeSession.js";
 import { CaseAuthenticatedTag, NodeId, ValidationError, VendorId } from "#types";
 import { Fabric, FabricBuilder } from "../fabric/Fabric.js";
 import { FabricManager } from "../fabric/FabricManager.js";
@@ -63,8 +64,11 @@ export abstract class FailsafeContext {
 
             // 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(this.#associatedFabric, expiryLength, maxCumulativeFailsafe, () =>
-                this.#failSafeExpired(),
+            this.#failsafe = new FailsafeTimer(
+                this.#associatedFabric,
+                expiryLength,
+                maxCumulativeFailsafe,
+                this.#failSafeExpired.bind(this),
             );
             logger.debug(`Arm failSafe timer for ${Duration.format(expiryLength)}`);
 
@@ -78,9 +82,9 @@ export abstract class FailsafeContext {
         });
     }
 
-    async extend(fabric: Fabric | undefined, expiryLength: Duration) {
+    async extend(fabric: Fabric | undefined, expiryLength: Duration, currentExchange?: MessageExchange) {
         await this.#construction;
-        await this.#failsafe?.reArm(fabric, expiryLength);
+        await this.#failsafe?.reArm(fabric, expiryLength, currentExchange);
         if (expiryLength > 0) {
             logger.debug(`Extend failSafe timer for ${Duration.format(expiryLength)}`);
         }
@@ -141,7 +145,7 @@ export abstract class FailsafeContext {
         // 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.closePaseSession();
 
         await this.close();
     }
@@ -155,16 +159,8 @@ export abstract class FailsafeContext {
         return this.#fabrics.allocateFabricIndex();
     }
 
-    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);
+    async replaceFabric(fabric: Fabric) {
+        await this.#fabrics.replaceFabric(fabric);
         await this.#sessions.deleteResumptionRecordsForFabric(fabric);
     }
 
@@ -183,19 +179,19 @@ export abstract class FailsafeContext {
         return result;
     }
 
-    async removePaseSession() {
+    async closePaseSession(currentExchange?: MessageExchange) {
         const session = this.#sessions.getPaseSession();
-        if (session !== undefined) {
-            await session.close(true);
+        if (session) {
+            await session.initiateForceClose(currentExchange);
         }
     }
 
-    async close() {
+    async close(currentExchange?: MessageExchange) {
         await this.#construction.close(async () => {
             if (this.#failsafe) {
                 await this.#failsafe.close();
                 this.#failsafe = undefined;
-                await this.rollback();
+                await this.rollback(currentExchange);
             }
         });
     }
@@ -256,28 +252,35 @@ export abstract class FailsafeContext {
             );
         }
 
-        return builder
+        this.#associatedFabric = await builder
             .setRootVendorId(adminVendorId)
             .setIdentityProtectionKey(ipkValue)
             .setRootNodeId(caseAdminSubject)
             .build(this.#fabrics.allocateFabricIndex());
+        this.#fabrics.addFabric(this.#associatedFabric);
+
+        if (this.#failsafe) {
+            this.#failsafe.associatedFabric = this.#associatedFabric;
+        }
+
+        return this.#associatedFabric;
     }
 
-    async #failSafeExpired() {
+    async #failSafeExpired(currentExchange?: MessageExchange) {
         logger.info("Failsafe timer expired; resetting fabric builder");
 
-        await this.close();
+        await this.close(currentExchange);
     }
 
-    protected async rollback() {
+    protected async rollback(currentExchange?: MessageExchange) {
         if (this.fabricIndex !== undefined && !this.#forUpdateNoc) {
-            logger.debug(`Revoking fabric with index ${this.fabricIndex}`);
-            await this.#fabrics.revokeFabric(this.fabricIndex);
+            logger.debug(`Revoking fabric index ${this.fabricIndex}`);
+            await this.#associatedFabric?.delete(currentExchange);
         }
 
         // 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();
+        await this.closePaseSession(currentExchange);
 
         // 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.
 
@@ -287,9 +290,8 @@ export abstract class FailsafeContext {
             const fabricIndex = this.fabricIndex;
             if (this.#fabrics.has(fabricIndex)) {
                 fabric = this.#fabrics.for(fabricIndex);
-                const session = this.#sessions.getSessionForNode(fabric.addressOf(fabric.rootNodeId));
-                if (session !== undefined && session.isSecure) {
-                    await session.close(false);
+                for (const session of this.#sessions.sessionsForFabricIndex(fabricIndex)) {
+                    await session.initiateForceClose(currentExchange);
                 }
             }
         }
@@ -309,10 +311,7 @@ export abstract class FailsafeContext {
         // 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 && this.#fabrics.has(fabricIndex)) {
-                await this.revokeFabric(this.#fabrics.for(fabricIndex));
-            }
+            await this.#associatedFabric?.delete();
         }
 
         // 8. Reset the Breadcrumb attribute to zero.
@@ -329,11 +328,9 @@ export abstract class FailsafeContext {
     abstract restoreNetworkState(): Promise<void>;
 
     async restoreFabric(fabric: Fabric) {
-        await this.updateFabric(fabric);
+        await this.replaceFabric(fabric);
     }
 
-    abstract revokeFabric(fabric: Fabric): Promise<void>;
-
     abstract restoreBreadcrumb(): Promise<void>;
 
     get #builder() {
@@ -350,6 +347,6 @@ export namespace FailsafeContext {
         fabrics: FabricManager;
         expiryLength: Duration;
         maxCumulativeFailsafe: Duration;
-        session: SecureSession;
+        session: NodeSession;
     }
 }

package/src/common/FailsafeTimer.ts

@@ -5,6 +5,7 @@
  */
 
 import { Duration, Logger, MatterFlowError, Time, Timer } from "#general";
+import { MessageExchange } from "#protocol/MessageExchange.js";
 import { Fabric } from "../fabric/Fabric.js";
 import type { FailsafeContext } from "./FailsafeContext.js";
 
@@ -16,7 +17,7 @@ const logger = Logger.get("FailsafeTimer");
  * Manages the failsafe timer associated with a {@link FailsafeContext}.
  */
 export class FailsafeTimer {
-    #expiryCallback: () => Promise<void>;
+    #expiryCallback: (currentExchange?: MessageExchange) => Promise<void>;
     #failsafeTimer: Timer;
     #maxCumulativeFailsafeTimer: Timer;
     #completed = false;
@@ -25,7 +26,7 @@ export class FailsafeTimer {
         public associatedFabric: Fabric | undefined,
         expiryLength: Duration,
         maxCumulativeFailsafe: Duration,
-        expiryCallback: () => Promise<void>,
+        expiryCallback: (currentExchange?: MessageExchange) => Promise<void>,
     ) {
         this.#expiryCallback = expiryCallback;
         this.#failsafeTimer = this.#startFailsafeTimer(expiryLength);
@@ -44,7 +45,7 @@ export class FailsafeTimer {
     }
 
     /** Handle "Re-Arming" an existing FailSafe context to extend the timer, expire or fail if not allowed. */
-    async reArm(associatedFabric: Fabric | undefined, expiry: Duration) {
+    async reArm(associatedFabric: Fabric | undefined, expiry: Duration, currentExchange?: MessageExchange) {
         if (!this.#failsafeTimer.isRunning) {
             throw new MatterFlowError("FailSafe already expired.");
         }
@@ -61,7 +62,7 @@ export class FailsafeTimer {
             // 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();
+            await this.expire(currentExchange);
         } 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
@@ -76,13 +77,13 @@ export class FailsafeTimer {
     }
 
     /** Expire the FailSafe context. This is called by the timer and can also be called manually if needed. */
-    async expire() {
+    async expire(currentExchange?: MessageExchange) {
         if (this.#completed) {
             // Completion was already triggered, so do nothing
             return;
         }
         this.complete();
-        await this.#expiryCallback();
+        await this.#expiryCallback(currentExchange);
     }
 
     /** Complete the FailSafe context. This is called when the commissioning is completed. */

package/src/common/Mark.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Visual demarcators for specific log elements.
+ */
+export namespace Mark {
+    export const INBOUND = "«";
+    export const OUTBOUND = "»";
+    export const SESSION = "•"; // Makes more sense but renders poorly: "⚭" (marriage).  Infinity OK too: "∞"
+    export const LOCAL_SESSION = "◦";
+    export const EXCHANGE = "⇵";
+    export const MESSAGE = "✉";
+}

package/src/common/index.ts

@@ -8,6 +8,7 @@ export * from "../peer/PeerAddress.js";
 export * from "./ExpandedPath.js";
 export * from "./FailsafeContext.js";
 export * from "./FailsafeTimer.js";
+export * from "./Mark.js";
 export * from "./OperationalCredentialsTypes.js";
 export * from "./Scanner.js";
 export * from "./SupportedTransportsBitmap.js";

package/src/fabric/Fabric.ts

@@ -9,6 +9,7 @@ import { Icac } from "#certificate/kinds/Icac.js";
 import { Noc } from "#certificate/kinds/Noc.js";
 import { Rcac } from "#certificate/kinds/Rcac.js";
 import {
+    AsyncObservable,
     BinaryKeyPair,
     Bytes,
     Crypto,
@@ -28,7 +29,8 @@ import {
 import { FabricGroups, GROUP_SECURITY_INFO } from "#groups/FabricGroups.js";
 import { FabricAccessControl } from "#interaction/FabricAccessControl.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import { Session } from "#session/Session.js";
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { SecureSession } from "#session/SecureSession.js";
 import { CaseAuthenticatedTag, FabricId, FabricIndex, GroupId, NodeId, StatusResponse, VendorId } from "#types";
 
 const logger = Logger.get("Fabric");
@@ -61,15 +63,20 @@ export class Fabric {
     readonly intermediateCACert: Bytes | undefined;
     readonly operationalCert: Bytes;
     readonly #keyPair: Key;
-    readonly #sessions = new Set<Session>();
+    readonly #sessions = new Set<SecureSession>();
     readonly #groups: FabricGroups;
     readonly #accessControl: FabricAccessControl;
+
+    readonly #leaving = AsyncObservable<[]>();
+    readonly #deleting = AsyncObservable<[]>();
+    readonly #deleted = AsyncObservable<[]>();
+
     #vidVerificationStatement?: Bytes;
     #vvsc?: Bytes;
     #label: string;
-    #removeCallbacks = new Array<() => MaybePromise<void>>();
     #persistCallback: ((isUpdate?: boolean) => MaybePromise<void>) | undefined;
     #storage?: StorageContext;
+    #isDeleting?: boolean;
 
     constructor(crypto: Crypto, config: Fabric.Config) {
         this.#crypto = crypto;
@@ -203,6 +210,22 @@ export class Fabric {
         return this.#keyPair.publicKey;
     }
 
+    get isDeleting() {
+        return this.#isDeleting;
+    }
+
+    get leaving() {
+        return this.#leaving;
+    }
+
+    get deleting() {
+        return this.#deleting;
+    }
+
+    get deleted() {
+        return this.#deleted;
+    }
+
     sign(data: Bytes) {
         return this.crypto.signEcdsa(this.#keyPair, data);
     }
@@ -258,11 +281,11 @@ export class Fabric {
         return await Promise.all(destinationIds);
     }
 
-    addSession(session: Session) {
+    addSession(session: SecureSession) {
         this.#sessions.add(session);
     }
 
-    removeSession(session: Session) {
+    deleteSession(session: SecureSession) {
         this.#sessions.delete(session);
     }
 
@@ -274,17 +297,6 @@ export class Fabric {
         }
     }
 
-    addRemoveCallback(callback: () => MaybePromise<void>) {
-        this.#removeCallbacks.push(callback);
-    }
-
-    deleteRemoveCallback(callback: () => MaybePromise<void>) {
-        const index = this.#removeCallbacks.indexOf(callback);
-        if (index >= 0) {
-            this.#removeCallbacks.splice(index, 1);
-        }
-    }
-
     set persistCallback(callback: (isUpdate?: boolean) => MaybePromise<void>) {
         // TODO Remove "isUpdate" parameter as soon as the fabric scoped data are removed from here/legacy API gets removed
         this.#persistCallback = callback;
@@ -296,17 +308,33 @@ export class Fabric {
      * Devices should use this to cleanly exit a fabric.  It flushes subscriptions to ensure the "leave" event emits
      * and closes sessions.
      */
-    leave(currentSessionId?: number) {
-        return this.remove(currentSessionId, true);
-    }
+    async leave(currentExchange?: MessageExchange) {
+        await this.#leaving.emit();
 
-    async remove(currentSessionId?: number, graceful = false) {
-        for (const callback of this.#removeCallbacks) {
-            await callback();
+        for (const session of [...this.#sessions]) {
+            await session.initiateClose(async () => {
+                await session.closeSubscriptions(true);
+            });
         }
+
+        await this.delete(currentExchange);
+    }
+
+    /**
+     * Permanently remove the fabric.
+     *
+     * Does not emit the leave event.
+     */
+    async delete(currentExchange?: MessageExchange) {
+        this.#isDeleting = true;
+
+        await this.#deleting.emit();
+
         for (const session of [...this.#sessions]) {
-            await session.destroy(graceful, session.id === currentSessionId, graceful); // Delay Close for current session only
+            await session.initiateForceClose(currentExchange);
         }
+
+        await this.#deleted.emit();
     }
 
     persist(isUpdate = true) {

package/src/fabric/FabricAuthority.ts

@@ -6,6 +6,7 @@
 
 import { CertificateAuthority } from "#certificate/CertificateAuthority.js";
 import {
+    AsyncObservable,
     Bytes,
     Construction,
     CRYPTO_SYMMETRIC_KEY_LENGTH,
@@ -13,7 +14,6 @@ import {
     Environmental,
     ImplementationError,
     Logger,
-    Observable,
 } from "#general";
 import { CaseAuthenticatedTag, FabricId, FabricIndex, NodeId, VendorId } from "#types";
 import { Fabric, FabricBuilder } from "./Fabric.js";
@@ -52,7 +52,7 @@ export class FabricAuthority {
     #construction: Construction<FabricAuthority>;
     #ca: CertificateAuthority;
     #fabrics: FabricManager;
-    #fabricAdded = new Observable<[Fabric]>();
+    #fabricAdded = new AsyncObservable<[Fabric]>();
 
     constructor({ ca, fabrics }: FabricAuthorityContext) {
         this.#ca = ca;
@@ -143,7 +143,7 @@ export class FabricAuthority {
         let index = config.adminFabricIndex;
         if (index === undefined) {
             index = this.#fabrics.allocateFabricIndex();
-        } else if (this.#fabrics.findByIndex(index) !== undefined) {
+        } else if (this.#fabrics.maybeForIndex(index) !== undefined) {
             throw new ImplementationError(`Cannot allocate controller fabric ${index} because index is in use`);
         }
 
@@ -153,7 +153,7 @@ export class FabricAuthority {
         fabric.persist();
 
         logger.debug(`Created new controller fabric ${index}`);
-        this.#fabricAdded.emit(fabric);
+        await this.#fabricAdded.emit(fabric);
 
         return fabric;
     }