@matter/protocol 0.16.0-alpha.0-20251103-b47ffa15b → 0.16.0-alpha.0-20251106-4e10fd77b

package/src/certificate/kinds/Icac.ts

@@ -88,6 +88,11 @@ export class Icac extends OperationalBase<OperationalCertificate.Icac> {
             throw new CertificateError(`Ica certificate must not contain a caseAuthenticatedTags.`);
         }
 
+        // The subject DN SHALL NOT encode any matter-vvs-id attribute.
+        if ("vvsId" in subject) {
+            throw new CertificateError(`Ica certificate must not contain a vvsId.`);
+        }
+
         // When any matter-fabric-id attributes are present in either the Matter Root CA Certificate or the Matter ICA
         // Certificate, the value SHALL match the one present in the Matter Node Operational Certificate (NOC) within
         // the same certificate chain.

package/src/certificate/kinds/Noc.ts

@@ -89,6 +89,11 @@ export class Noc extends OperationalBase<OperationalCertificate.Noc> {
             throw new CertificateError(`Noc certificate must not contain an rcacId.`);
         }
 
+        // The subject DN SHALL NOT encode any matter-vvs-id attribute.
+        if ("vvsId" in subject) {
+            throw new CertificateError(`Noc certificate must not contain a vvsId.`);
+        }
+
         // The subject DN MAY encode at most three matter-noc-cat attributes.
         if (caseAuthenticatedTags !== undefined) {
             CaseAuthenticatedTag.validateNocTagList(caseAuthenticatedTags); // throws ValidationError

package/src/certificate/kinds/Rcac.ts

@@ -79,6 +79,11 @@ export class Rcac extends OperationalBase<OperationalCertificate.Rcac> {
             throw new CertificateError(`Root certificate must not contain a caseAuthenticatedTags.`);
         }
 
+        // The subject DN SHALL NOT encode any matter-vsc-id attribute.
+        if ("vvsId" in subject) {
+            throw new CertificateError(`Root certificate must not contain a vvsId.`);
+        }
+
         // The basic constraints extension SHALL be encoded with is-ca set to true.
         if (basicConstraints.isCa !== true) {
             throw new CertificateError(`Root certificate must have isCa set to true.`);

package/src/certificate/kinds/Vvsc.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Crypto, Diagnostic } from "#general";
+import { CertificateError } from "./common.js";
+import { OperationalCertificate } from "./definitions/operational.js";
+import { OperationalBase } from "./OperationalBase.js";
+
+/**
+ * Represents an Vendor Verification Signer Certificate
+ */
+export class Vvsc extends OperationalBase<OperationalCertificate.Vvsc> {
+    /** Construct the class from a Tlv version of the certificate */
+    static fromTlv(tlv: Bytes): Vvsc {
+        return new Vvsc(OperationalCertificate.TlvVvsc.decode(tlv));
+    }
+
+    /** Validates all basic certificate fields on construction. */
+    protected validateFields() {
+        const {
+            extensions: {
+                basicConstraints: { isCa },
+            },
+        } = this.cert;
+        if (!isCa) {
+            throw new CertificateError("Intermediate certificate must be a CA.");
+        }
+    }
+
+    /**
+     * Encodes the certificate with the signature as Matter Tlv.
+     * If the certificate is not signed, it throws a CertificateError.
+     */
+    asSignedTlv() {
+        return OperationalCertificate.TlvVvsc.encode({ ...this.cert, signature: this.signature });
+    }
+
+    /**
+     * Verify requirements a Matter Intermediate CA certificate must fulfill.
+     * Rules for this are listed in @see {@link MatterSpecification.v12.Core} §6.5.x
+     * // TODO ADD Verification once we know more about the chain
+     */
+    async verify(_crypto: Crypto) {
+        this.generalVerify();
+
+        const { subject } = this.cert;
+        const { vvsId } = subject;
+
+        // The subject DN SHALL encode exactly one matter-vvs-id attribute.
+        if (vvsId === undefined || Array.isArray(vvsId)) {
+            throw new CertificateError(`Invalid vvsId in Vsc certificate: ${Diagnostic.json(vvsId)}`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-node-id attribute.
+        if ("nodeId" in subject) {
+            throw new CertificateError(`Vsc certificate must not contain a nodeId.`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-fabric-id attribute.
+        if ("fabricId" in subject) {
+            throw new CertificateError(`Vsc certificate must not contain a fabricId.`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-noc-cat attribute.
+        if ("caseAuthenticatedTags" in subject) {
+            throw new CertificateError(`Vvsc certificate must not contain a caseAuthenticatedTags.`);
+        }
+    }
+}

package/src/certificate/kinds/X509Base.ts

@@ -32,6 +32,7 @@ import {
     ProductId_Matter,
     RcacId_Matter,
     VendorId_Matter,
+    VvsId_Matter,
 } from "./definitions/asn.js";
 import { ExtensionKeyUsageBitmap, ExtensionKeyUsageSchema, X509Certificate } from "./definitions/base.js";
 import { CertificateExtension } from "./definitions/operational.js";
@@ -170,6 +171,9 @@ export abstract class X509Base<CT extends X509Certificate> {
                 case "rcacId":
                     asn.rcacId = RcacId_Matter(value as number | bigint);
                     break;
+                case "vvsId":
+                    asn.vvsId = VvsId_Matter(value as number | bigint);
+                    break;
                 case "fabricId":
                     asn.fabricId = FabricId_Matter(value as FabricId);
                     break;

package/src/certificate/kinds/definitions/asn.ts

@@ -90,6 +90,9 @@ export const FabricId_Matter = GenericMatterOpCertObject<FabricId>(5);
 /** matter-noc-cat = ASN.1 OID 1.3.6.1.4.1.37244.1.6 */
 export const NocCat_Matter = GenericMatterOpCertObject<number>(6, uInt16To8Chars);
 
+/** matter-vvs-id = ASN.1 OID 1.3.6.1.4.1.37244.1.7 */
+export const VvsId_Matter = GenericMatterOpCertObject<bigint | number>(7);
+
 /** matter-oid-vid = ASN.1 OID 1.3.6.1.4.1.37244.2.1 */
 export const VendorId_Matter = GenericMatterAttCertObject<VendorId>(1, uInt16To4Chars);
 

package/src/certificate/kinds/definitions/operational.ts

@@ -173,7 +173,15 @@ export namespace OperationalCertificate {
         issuer: AllowedSubjectAndIssuerMatterFields,
     });
 
+    export const TlvVvsc = BaseMatterCertificate({
+        subject: {
+            vvsId: TlvField(23, TlvUInt64),
+        },
+        issuer: AllowedSubjectAndIssuerMatterFields,
+    });
+
     export type Rcac = TypeFromSchema<typeof TlvRcac>;
     export type Icac = TypeFromSchema<typeof TlvIcac>;
     export type Noc = TypeFromSchema<typeof TlvNoc>;
+    export type Vvsc = TypeFromSchema<typeof TlvVvsc>;
 }

package/src/certificate/kinds/index.ts

@@ -9,4 +9,5 @@ export * from "./CertificationDeclaration.js";
 export * from "./Icac.js";
 export * from "./Noc.js";
 export * from "./Rcac.js";
+export * from "./Vvsc.js";
 export * from "./X509Base.js";

package/src/fabric/Fabric.ts

@@ -29,7 +29,7 @@ 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 { CaseAuthenticatedTag, FabricId, FabricIndex, GroupId, NodeId, VendorId } from "#types";
+import { CaseAuthenticatedTag, FabricId, FabricIndex, GroupId, NodeId, StatusResponse, VendorId } from "#types";
 
 const logger = Logger.get("Fabric");
 
@@ -54,7 +54,7 @@ export class Fabric {
     readonly rootNodeId: NodeId;
     readonly operationalId: Bytes;
     readonly rootPublicKey: Bytes;
-    readonly rootVendorId: VendorId;
+    #rootVendorId: VendorId;
     readonly rootCert: Bytes;
     readonly identityProtectionKey: Bytes;
     readonly operationalIdentityProtectionKey: Bytes;
@@ -64,6 +64,8 @@ export class Fabric {
     readonly #sessions = new Set<Session>();
     readonly #groups: FabricGroups;
     readonly #accessControl: FabricAccessControl;
+    #vidVerificationStatement?: Bytes;
+    #vvsc?: Bytes;
     #label: string;
     #removeCallbacks = new Array<() => MaybePromise<void>>();
     #persistCallback: ((isUpdate?: boolean) => MaybePromise<void>) | undefined;
@@ -77,12 +79,14 @@ export class Fabric {
         this.rootNodeId = config.rootNodeId;
         this.operationalId = config.operationalId;
         this.rootPublicKey = config.rootPublicKey;
-        this.rootVendorId = config.rootVendorId;
+        this.#rootVendorId = config.rootVendorId;
         this.rootCert = config.rootCert;
         this.identityProtectionKey = config.identityProtectionKey;
         this.operationalIdentityProtectionKey = config.operationalIdentityProtectionKey;
         this.intermediateCACert = config.intermediateCACert;
         this.operationalCert = config.operationalCert;
+        this.#vidVerificationStatement = config.vidVerificationStatement;
+        this.#vvsc = config.vvsc;
         this.#label = config.label;
         this.#keyPair = PrivateKey(config.keyPair);
         this.#accessControl = new FabricAccessControl(this);
@@ -108,6 +112,7 @@ export class Fabric {
             operationalIdentityProtectionKey: this.operationalIdentityProtectionKey,
             intermediateCACert: this.intermediateCACert,
             operationalCert: this.operationalCert,
+            vidVerificationStatement: this.vidVerificationStatement,
             label: this.#label,
         };
     }
@@ -127,6 +132,56 @@ export class Fabric {
         await this.persist();
     }
 
+    get vidVerificationStatement() {
+        return this.#vidVerificationStatement;
+    }
+
+    async updateVendorVerificationData(
+        vendorId: VendorId | undefined,
+        vidVerificationStatement: Bytes | undefined,
+        vvsc: Bytes | undefined,
+    ) {
+        if (vvsc !== undefined && this.intermediateCACert !== undefined) {
+            throw new StatusResponse.InvalidCommandError("A VVSC is only allowed without an ICAC.");
+        }
+
+        if (vidVerificationStatement !== undefined) {
+            if (vidVerificationStatement.byteLength === 0) {
+                this.#vidVerificationStatement = undefined;
+            } else if (vidVerificationStatement.byteLength === 85) {
+                // VERIFICATION_STATEMENT_SIZE
+                this.#vidVerificationStatement = vidVerificationStatement;
+            } else {
+                throw new StatusResponse.ConstraintErrorError("VID Verification Statement must be 0 or 85 bytes long.");
+            }
+        }
+        if (vendorId !== undefined) {
+            this.#rootVendorId = vendorId;
+        }
+        if (vvsc !== undefined) {
+            if (vvsc.byteLength === 0) {
+                this.#vvsc = undefined;
+            } else {
+                this.#vvsc = vvsc;
+            }
+        }
+        logger.info(
+            "Updated Vendor Verification Data for Fabric",
+            this.#rootVendorId,
+            this.#vidVerificationStatement,
+            this.#vvsc,
+        );
+        await this.persist();
+    }
+
+    get vvsc() {
+        return this.#vvsc;
+    }
+
+    get rootVendorId() {
+        return this.#rootVendorId;
+    }
+
     set storage(storage: StorageContext) {
         this.#storage = storage;
         this.#groups.storage = storage;
@@ -282,6 +337,8 @@ export class FabricBuilder {
     #rootNodeId?: NodeId;
     #rootPublicKey?: Bytes;
     #identityProtectionKey?: Bytes;
+    #vidVerificationStatement?: Bytes;
+    #vvsc?: Bytes;
     #fabricIndex?: FabricIndex;
     #label = "";
 
@@ -387,6 +444,8 @@ export class FabricBuilder {
         this.#identityProtectionKey = fabric.identityProtectionKey;
         this.#rootCert = fabric.rootCert;
         this.#rootPublicKey = fabric.rootPublicKey;
+        this.#vidVerificationStatement = fabric.vidVerificationStatement;
+        this.#vvsc = fabric.vvsc;
         this.#label = fabric.label;
     }
 
@@ -447,6 +506,8 @@ export class FabricBuilder {
             ),
             intermediateCACert: this.#intermediateCACert,
             operationalCert: this.#operationalCert,
+            vidVerificationStatement: this.#vidVerificationStatement,
+            vvsc: this.#vvsc,
             label: this.#label,
         });
     }
@@ -464,6 +525,8 @@ export namespace Fabric {
         rootVendorId: VendorId;
         rootCert: Bytes;
         identityProtectionKey: Bytes;
+        vidVerificationStatement?: Bytes;
+        vvsc?: Bytes;
         operationalIdentityProtectionKey: Bytes;
         intermediateCACert: Bytes | undefined;
         operationalCert: Bytes;

package/src/fabric/FabricManager.ts

@@ -12,6 +12,7 @@ import {
     Environmental,
     ImplementationError,
     Key,
+    Logger,
     MatterError,
     MatterFlowError,
     MaybePromise,
@@ -23,6 +24,8 @@ import { PeerAddress } from "#peer/PeerAddress.js";
 import { FabricIndex } from "#types";
 import { Fabric } from "./Fabric.js";
 
+const logger = Logger.get("FabricManager");
+
 /** Specific Error for when a fabric is not found. */
 export class FabricNotFoundError extends MatterError {}
 export class FabricTableFullError extends MatterError {}
@@ -63,7 +66,7 @@ export class FabricManager {
 
                 const fabrics = await this.#storage.get<Fabric.Config[]>("fabrics", []);
                 for (const fabricConfig of fabrics) {
-                    this.#addFabric(new Fabric(crypto, fabricConfig));
+                    this.#addNewFabric(new Fabric(crypto, fabricConfig));
                 }
 
                 this.#nextFabricIndex = await this.#storage.get("nextFabricIndex", this.#nextFabricIndex);
@@ -156,18 +159,34 @@ export class FabricManager {
 
     addFabric(fabric: Fabric) {
         this.#construction.assert();
-        this.#addFabric(fabric);
+        this.#addNewFabric(fabric);
     }
 
-    #addFabric(fabric: Fabric) {
+    #addNewFabric(fabric: Fabric) {
         const { fabricIndex } = fabric;
         if (this.#fabrics.has(fabricIndex)) {
             throw new MatterFlowError(`Fabric with index ${fabricIndex} already exists.`);
         }
+
+        this.#addOrUpdateFabricEntry(fabric);
+
+        if (this.#initializationDone) {
+            this.#events.added.emit(fabric);
+        }
+    }
+
+    /** Insert Fabric into the manager without emitting events */
+    #addOrUpdateFabricEntry(fabric: Fabric) {
+        const { fabricIndex } = fabric;
         this.#fabrics.set(fabricIndex, fabric);
         fabric.addRemoveCallback(async () => this.removeFabric(fabricIndex));
         fabric.persistCallback = (isUpdate = true) => {
             if (!this.#storage) {
+                if (isUpdate) {
+                    logger.warn(
+                        "Fabric can not be persisted because FabricManager has no storage but it is a fabric update.",
+                    );
+                }
                 return;
             }
             const persistResult = this.persistFabrics();
@@ -177,12 +196,9 @@ export class FabricManager {
                 }
             });
         };
-        if (this.#storage !== undefined) {
+        if (this.#storage !== undefined && fabric.storage === undefined) {
             fabric.storage = this.#storage.createContext(`fabric-${fabricIndex}`);
         }
-        if (this.#initializationDone) {
-            this.#events.added.emit(fabric);
-        }
     }
 
     async removeFabric(fabricIndex: FabricIndex) {
@@ -259,12 +275,19 @@ export class FabricManager {
         await this.#construction;
 
         const { fabricIndex } = fabric;
-        if (!this.#fabrics.has(fabricIndex)) {
+        const existingFabric = this.#fabrics.get(fabricIndex);
+        if (existingFabric === undefined) {
             throw new FabricNotFoundError(
                 `Fabric with index ${fabricIndex} cannot be updated because it does not exist.`,
             );
         }
-        this.#fabrics.set(fabricIndex, fabric);
+        if (existingFabric === fabric) {
+            // Nothing changed, so it is a restore without any change
+            return;
+        }
+
+        this.#addOrUpdateFabricEntry(fabric);
+
         if (this.#storage) {
             await this.persistFabrics();
         }

package/src/peer/PhysicalDeviceProperties.ts

@@ -4,77 +4,94 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Logger } from "#general";
+import { Duration, Instant, Logger, Minutes, Seconds } from "#general";
 
 const logger = Logger.get("PhysicalDeviceProperties");
 
-const DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT_S = 1;
-const DEFAULT_SUBSCRIPTION_FLOOR_ICD_S = 0;
-const DEFAULT_SUBSCRIPTION_CEILING_WIFI_S = 60;
-const DEFAULT_SUBSCRIPTION_CEILING_THREAD_S = 60;
-const DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY_S = 180;
-const DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED_S = 600;
+const DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT = Seconds(1);
+const DEFAULT_SUBSCRIPTION_FLOOR_ICD = Instant;
+const DEFAULT_SUBSCRIPTION_CEILING_WIFI = Minutes(1);
+const DEFAULT_SUBSCRIPTION_CEILING_THREAD = Minutes(1);
+const DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY = Minutes(3);
+const DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED = Minutes(10);
 
 export interface PhysicalDeviceProperties {
     threadConnected: boolean;
     wifiConnected: boolean;
     ethernetConnected: boolean;
     rootEndpointServerList: number[];
+    isMainsPowered: boolean;
     isBatteryPowered: boolean;
     isIntermittentlyConnected: boolean;
     isThreadSleepyEndDevice: boolean;
 }
 
 export namespace PhysicalDeviceProperties {
-    export function determineSubscriptionParameters(options?: {
+    export function subscriptionIntervalBoundsFor(options?: {
         properties?: PhysicalDeviceProperties;
         description?: string;
-        subscribeMinIntervalFloorSeconds?: number;
-        subscribeMaxIntervalCeilingSeconds?: number;
-    }) {
-        const { properties } = options ?? {};
+        request?: Partial<PhysicalDeviceProperties.IntervalBounds>;
+    }): PhysicalDeviceProperties.IntervalBounds {
+        const { properties, request } = options ?? {};
 
-        let {
-            description,
-            subscribeMinIntervalFloorSeconds: minIntervalFloorSeconds,
-            subscribeMaxIntervalCeilingSeconds: maxIntervalCeilingSeconds,
-        } = options ?? {};
+        let { description } = options ?? {};
+
+        let minIntervalFloor, maxIntervalCeiling;
+        if (request) {
+            ({ minIntervalFloor, maxIntervalCeiling } = request);
+        }
 
         if (description === undefined) {
             description = "Node";
         }
 
-        const { isBatteryPowered, isIntermittentlyConnected, threadConnected, isThreadSleepyEndDevice } =
-            properties ?? {};
+        const {
+            isMainsPowered,
+            isBatteryPowered,
+            isIntermittentlyConnected,
+            threadConnected,
+            isThreadSleepyEndDevice,
+        } = properties ?? {};
 
         if (isIntermittentlyConnected) {
-            if (minIntervalFloorSeconds !== undefined && minIntervalFloorSeconds !== DEFAULT_SUBSCRIPTION_FLOOR_ICD_S) {
+            if (minIntervalFloor !== undefined && minIntervalFloor !== DEFAULT_SUBSCRIPTION_FLOOR_ICD) {
                 logger.info(
-                    `${description}: Overwriting minIntervalFloorSeconds for intermittently connected device to ${DEFAULT_SUBSCRIPTION_FLOOR_ICD_S}`,
+                    `${description}: Overwriting minIntervalFloorSeconds for intermittently connected device to ${Duration.format(DEFAULT_SUBSCRIPTION_FLOOR_ICD)}`,
                 );
-                minIntervalFloorSeconds = DEFAULT_SUBSCRIPTION_FLOOR_ICD_S;
+                minIntervalFloor = DEFAULT_SUBSCRIPTION_FLOOR_ICD;
             }
         }
+        if (minIntervalFloor === undefined) {
+            minIntervalFloor = DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT;
+        }
 
-        const defaultCeiling = isBatteryPowered
-            ? DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED_S
-            : isThreadSleepyEndDevice
-              ? DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY_S
-              : threadConnected
-                ? DEFAULT_SUBSCRIPTION_CEILING_THREAD_S
-                : DEFAULT_SUBSCRIPTION_CEILING_WIFI_S;
-        if (maxIntervalCeilingSeconds === undefined) {
-            maxIntervalCeilingSeconds = defaultCeiling;
+        const defaultCeiling =
+            isBatteryPowered && !isMainsPowered
+                ? DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED
+                : isThreadSleepyEndDevice
+                  ? DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY
+                  : threadConnected
+                    ? DEFAULT_SUBSCRIPTION_CEILING_THREAD
+                    : DEFAULT_SUBSCRIPTION_CEILING_WIFI;
+        if (maxIntervalCeiling === undefined) {
+            maxIntervalCeiling = defaultCeiling;
         }
-        if (maxIntervalCeilingSeconds < defaultCeiling) {
+        if (maxIntervalCeiling < defaultCeiling) {
             logger.debug(
-                `${description}: maxIntervalCeilingSeconds ideally is ${defaultCeiling}s instead of ${maxIntervalCeilingSeconds}s due to device type`,
+                `${description}: maxIntervalCeilingSeconds ideally is ${defaultCeiling}s instead of ${maxIntervalCeiling}s due to device type`,
             );
         }
 
         return {
-            minIntervalFloorSeconds: minIntervalFloorSeconds ?? DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT_S,
-            maxIntervalCeilingSeconds,
+            minIntervalFloor,
+            maxIntervalCeiling,
         };
     }
 }
+
+export namespace PhysicalDeviceProperties {
+    export interface IntervalBounds {
+        minIntervalFloor: Duration;
+        maxIntervalCeiling: Duration;
+    }
+}

package/src/protocol/DeviceAdvertiser.ts

@@ -47,6 +47,36 @@ export class DeviceAdvertiser {
             this.#advertiseFabric(fabric, "startup");
         });
 
+        // When a fabric is updated we might need to adjust announcements
+        this.#observers.on(fabrics.events.updated, async fabric => {
+            if (!this.#isOperational) {
+                return;
+            }
+
+            // Look for update for this fabricIndex because other Ids might have changed and object is different
+            const fabricIndexAdvertisements = this.#advertisements(
+                ad => ad.isOperational() && ad.description.fabric.fabricIndex === fabric.fabricIndex,
+            );
+
+            // If the announcement relevant IDs are unchanged, do nothing
+            if (
+                fabricIndexAdvertisements.every(
+                    ad =>
+                        ad.isOperational() &&
+                        ad.description.fabric.operationalId === fabric.operationalId &&
+                        ad.description.fabric.nodeId === fabric.nodeId,
+                )
+            ) {
+                return;
+            }
+
+            for (const ad of fabricIndexAdvertisements) {
+                await ad.close();
+            }
+
+            this.#advertiseFabric(fabric, "startup");
+        });
+
         // When a fabric is deleted, cancel any active advertisement
         this.#observers.on(fabrics.events.deleted, fabric => {
             Advertisement.cancelAll(this.#advertisements(ad => ad.isOperational() && ad.description.fabric === fabric));