@matter/protocol 0.16.0-alpha.0-20251217-038f88085 → 0.16.0-alpha.0-20251221-21acf226d

package/src/fabric/Fabric.ts

@@ -31,12 +31,19 @@ import { FabricAccessControl } from "#interaction/FabricAccessControl.js";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { MessageExchange } from "#protocol/MessageExchange.js";
 import { SecureSession } from "#session/SecureSession.js";
-import { CaseAuthenticatedTag, FabricId, FabricIndex, GroupId, NodeId, StatusResponse, VendorId } from "#types";
+import {
+    CaseAuthenticatedTag,
+    FabricId,
+    FabricIndex,
+    GlobalFabricId,
+    GroupId,
+    NodeId,
+    StatusResponse,
+    VendorId,
+} from "#types";
 
 const logger = Logger.get("Fabric");
 
-const COMPRESSED_FABRIC_ID_INFO = Bytes.fromString("CompressedFabric");
-
 export class PublicKeyError extends MatterError {}
 
 export type ExposedFabricInformation = {
@@ -54,8 +61,8 @@ export class Fabric {
     readonly fabricId: FabricId;
     readonly nodeId: NodeId;
     readonly rootNodeId: NodeId;
-    readonly operationalId: Bytes;
-    readonly rootPublicKey: Bytes;
+    readonly globalId: GlobalFabricId;
+    #rootPublicKey?: Bytes;
     #rootVendorId: VendorId;
     readonly rootCert: Bytes;
     readonly identityProtectionKey: Bytes;
@@ -78,14 +85,24 @@ export class Fabric {
     #storage?: StorageContext;
     #isDeleting?: boolean;
 
-    constructor(crypto: Crypto, config: Fabric.Config) {
+    /**
+     * Create a fabric synchronously.
+     *
+     * Certain derived fields that require async crypto operations to compute must be supplied here.  Use {@link create}
+     * to populate these fields automatically.
+     */
+    constructor(crypto: Crypto, config: Fabric.ConstructorConfig) {
         this.#crypto = crypto;
         this.fabricIndex = config.fabricIndex;
         this.fabricId = config.fabricId;
         this.nodeId = config.nodeId;
         this.rootNodeId = config.rootNodeId;
-        this.operationalId = config.operationalId;
-        this.rootPublicKey = config.rootPublicKey;
+        if ("operationalId" in config) {
+            this.globalId = GlobalFabricId(config.operationalId);
+        } else {
+            this.globalId = config.globalId;
+        }
+        this.#rootPublicKey = config.rootPublicKey;
         this.#rootVendorId = config.rootVendorId;
         this.rootCert = config.rootCert;
         this.identityProtectionKey = config.identityProtectionKey;
@@ -100,17 +117,52 @@ export class Fabric {
         this.#groups = new FabricGroups(this);
     }
 
+    /**
+     * Create a fabric.
+     *
+     * This async creation path populates derived fields that require async crypto operations to compute.
+     */
+    static async create(crypto: Crypto, config: Fabric.Config) {
+        let { globalId, operationalIdentityProtectionKey } = config;
+
+        // Compute global ID if not passed as config
+        if (globalId === undefined) {
+            const caKey = config.rootPublicKey ?? Rcac.publicKeyOfTlv(config.rootCert);
+            globalId = await GlobalFabricId.compute(crypto, config.fabricId, caKey);
+        }
+
+        // Compute operational IPK if not passed as config
+        if (operationalIdentityProtectionKey === undefined) {
+            operationalIdentityProtectionKey = await crypto.createHkdfKey(
+                config.identityProtectionKey,
+                Bytes.fromBigInt(globalId, 8),
+                GROUP_SECURITY_INFO,
+            );
+        }
+
+        return new Fabric(crypto, {
+            ...config,
+            globalId,
+            operationalIdentityProtectionKey,
+        });
+    }
+
     get crypto() {
         return this.#crypto;
     }
 
-    get config(): Fabric.Config {
-        return {
+    /**
+     * Obtain configuration required to recreate fabric.
+     *
+     * TODO - we currently use this for persistence; remove when we move to OperationalCredentials as "source of truth"
+     */
+    get config(): Fabric.SyncConfig {
+        const config = {
             fabricIndex: this.fabricIndex,
             fabricId: this.fabricId,
             nodeId: this.nodeId,
             rootNodeId: this.rootNodeId,
-            operationalId: this.operationalId,
+            globalId: this.globalId,
             rootPublicKey: this.rootPublicKey,
             keyPair: this.#keyPair.keyPair,
             rootVendorId: this.rootVendorId,
@@ -122,6 +174,11 @@ export class Fabric {
             vidVerificationStatement: this.vidVerificationStatement,
             label: this.#label,
         };
+
+        // Backwards compatibility
+        (config as unknown as { operationalId: Bytes }).operationalId = Bytes.fromBigInt(this.globalId, 8);
+
+        return config;
     }
 
     get label() {
@@ -185,6 +242,13 @@ export class Fabric {
         return this.#vvsc;
     }
 
+    get rootPublicKey() {
+        if (this.#rootPublicKey === undefined) {
+            this.#rootPublicKey = Rcac.publicKeyOfTlv(this.rootCert);
+        }
+        return this.#rootPublicKey;
+    }
+
     get rootVendorId() {
         return this.#rootVendorId;
     }
@@ -373,7 +437,6 @@ export class FabricBuilder {
     #fabricId?: FabricId;
     #nodeId?: NodeId;
     #rootNodeId?: NodeId;
-    #rootPublicKey?: Bytes;
     #identityProtectionKey?: Bytes;
     #vidVerificationStatement?: Bytes;
     #vvsc?: Bytes;
@@ -405,7 +468,6 @@ export class FabricBuilder {
         const root = Rcac.fromTlv(rootCert);
         await root.verify(this.#crypto);
         this.#rootCert = rootCert;
-        this.#rootPublicKey = root.cert.ellipticCurvePublicKey;
         return this;
     }
 
@@ -423,7 +485,7 @@ export class FabricBuilder {
         } = Noc.fromTlv(operationalCert).cert;
         logger.debug(
             "Installing operational certificate",
-            Diagnostic.dict({ nodeId, fabricId, caseAuthenticatedTags }),
+            Diagnostic.dict({ nodeId: NodeId.strOf(nodeId), fabricId, caseAuthenticatedTags }),
         );
         if (caseAuthenticatedTags !== undefined) {
             CaseAuthenticatedTag.validateNocTagList(caseAuthenticatedTags);
@@ -481,17 +543,16 @@ export class FabricBuilder {
         this.#rootNodeId = fabric.rootNodeId;
         this.#identityProtectionKey = fabric.identityProtectionKey;
         this.#rootCert = fabric.rootCert;
-        this.#rootPublicKey = fabric.rootPublicKey;
         this.#vidVerificationStatement = fabric.vidVerificationStatement;
         this.#vvsc = fabric.vvsc;
         this.#label = fabric.label;
     }
 
-    matchesToFabric(fabric: Fabric) {
-        if (this.#fabricId === undefined || this.#rootPublicKey === undefined) {
+    get globalId() {
+        if (this.#fabricId === undefined || this.#rootCert === undefined) {
             throw new MatterFlowError("Node Operational Data needs to be set first.");
         }
-        return fabric.matchesFabricIdAndRootPublicKey(this.#fabricId, this.#rootPublicKey);
+        return GlobalFabricId.compute(this.#crypto, this.#fabricId, Rcac.publicKeyOfTlv(this.#rootCert));
     }
 
     get nodeId() {
@@ -510,38 +571,22 @@ export class FabricBuilder {
         if (this.#fabricIndex !== undefined) throw new InternalError("FabricBuilder can only be built once");
         if (this.#rootNodeId === undefined) throw new InternalError("rootNodeId needs to be set");
         if (this.#rootVendorId === undefined) throw new InternalError("vendorId needs to be set");
-        if (this.#rootCert === undefined || this.#rootPublicKey === undefined)
-            throw new InternalError("rootCert needs to be set");
+        if (this.#rootCert === undefined) throw new InternalError("rootCert needs to be set");
         if (this.#identityProtectionKey === undefined) throw new InternalError("identityProtectionKey needs to be set");
         if (this.#operationalCert === undefined || this.#fabricId === undefined || this.#nodeId === undefined)
             throw new InternalError("operationalCert needs to be set");
 
         this.#fabricIndex = fabricIndex;
-        const saltWriter = new DataWriter();
-        saltWriter.writeUInt64(this.#fabricId);
-        const operationalId = await this.#crypto.createHkdfKey(
-            Bytes.of(this.#rootPublicKey).slice(1),
-            saltWriter.toByteArray(),
-            COMPRESSED_FABRIC_ID_INFO,
-            8,
-        );
 
-        return new Fabric(this.#crypto, {
+        return await Fabric.create(this.#crypto, {
             fabricIndex: this.#fabricIndex,
             fabricId: this.#fabricId,
             nodeId: this.#nodeId,
             rootNodeId: this.#rootNodeId,
-            operationalId: operationalId,
-            rootPublicKey: this.#rootPublicKey,
             keyPair: this.#keyPair,
             rootVendorId: this.#rootVendorId,
             rootCert: this.#rootCert,
             identityProtectionKey: this.#identityProtectionKey, // Epoch Key
-            operationalIdentityProtectionKey: await this.#crypto.createHkdfKey(
-                this.#identityProtectionKey,
-                operationalId,
-                GROUP_SECURITY_INFO,
-            ),
             intermediateCACert: this.#intermediateCACert,
             operationalCert: this.#operationalCert,
             vidVerificationStatement: this.#vidVerificationStatement,
@@ -552,22 +597,56 @@ export class FabricBuilder {
 }
 
 export namespace Fabric {
+    /**
+     * Configuration required to initialize a fabric.
+     */
     export type Config = {
         fabricIndex: FabricIndex;
         fabricId: FabricId;
         nodeId: NodeId;
         rootNodeId: NodeId;
-        operationalId: Bytes;
-        rootPublicKey: Bytes;
         keyPair: BinaryKeyPair;
         rootVendorId: VendorId;
         rootCert: Bytes;
         identityProtectionKey: Bytes;
         vidVerificationStatement?: Bytes;
         vvsc?: Bytes;
-        operationalIdentityProtectionKey: Bytes;
         intermediateCACert: Bytes | undefined;
         operationalCert: Bytes;
         label: string;
+
+        // These are derived; Fabric.create() will generate if necessary
+        rootPublicKey?: Bytes;
+        globalId?: GlobalFabricId;
+        operationalIdentityProtectionKey?: Bytes;
+    };
+
+    /**
+     * Configuration required to initialize a fabric without asynchronous crypto operations.
+     */
+    export type SyncConfig = Config & {
+        operationalIdentityProtectionKey: Bytes;
+        globalId: GlobalFabricId;
     };
+
+    /**
+     * Configuration passed to fabric constructor.
+     *
+     * Provides deprecated fields for backwards compatibility.
+     */
+    export type ConstructorConfig = Omit<SyncConfig, "globalId"> &
+        (
+            | {
+                  globalId: GlobalFabricId;
+              }
+            | {
+                  /** @deprecated */
+                  operationalId: Bytes;
+              }
+        );
+
+    /**
+     * An object that may be used to identify a fabric.
+     */
+    export type Identifier = FabricIndex | GlobalFabricId | { fabricIndex: FabricIndex };
 }

package/src/fabric/FabricAuthority.ts

@@ -147,7 +147,7 @@ export class FabricAuthority {
         let index = config.adminFabricIndex;
         if (index === undefined) {
             index = this.#fabrics.allocateFabricIndex();
-        } else if (this.#fabrics.maybeForIndex(index) !== undefined) {
+        } else if (this.#fabrics.maybeFor(index) !== undefined) {
             throw new ImplementationError(`Cannot allocate controller fabric ${index} because index is in use`);
         }
 

package/src/fabric/FabricManager.ts

@@ -6,9 +6,11 @@
 
 import {
     AsyncObservable,
+    BasicSet,
     Bytes,
     Construction,
     Crypto,
+    Diagnostic,
     Environment,
     Environmental,
     ImplementationError,
@@ -22,8 +24,7 @@ import {
     StorageContext,
     StorageManager,
 } from "#general";
-import { PeerAddress } from "#peer/PeerAddress.js";
-import { FabricId, FabricIndex } from "#types";
+import { FabricId, FabricIndex, GlobalFabricId, NodeId } from "#types";
 import { Fabric } from "./Fabric.js";
 
 const logger = Logger.get("FabricManager");
@@ -35,7 +36,7 @@ export class FabricTableFullError extends MatterError {}
 export class FabricManager {
     #crypto: Crypto;
     #nextFabricIndex = 1;
-    readonly #fabrics = new Map<FabricIndex, Fabric>();
+    readonly #fabrics = new BasicSet<Fabric>();
     #initializationDone = false;
     #storage?: StorageContext;
     #events = {
@@ -64,7 +65,7 @@ export class FabricManager {
 
                 const fabrics = await this.#storage.get<Fabric.Config[]>("fabrics", []);
                 for (const fabricConfig of fabrics) {
-                    this.#addNewFabric(new Fabric(crypto, fabricConfig));
+                    this.#addNewFabric(await Fabric.create(crypto, fabricConfig));
                 }
 
                 this.#nextFabricIndex = await this.#storage.get("nextFabricIndex", this.#nextFabricIndex);
@@ -105,32 +106,63 @@ export class FabricManager {
         await this.#storage?.clear();
     }
 
-    has(address: FabricIndex | PeerAddress) {
-        if (typeof address === "object") {
-            address = address.fabricIndex;
+    /**
+     * Test whether the fabric identified by {@link identifier} is present.
+     */
+    has(address: Fabric.Identifier) {
+        let fabric;
+        if (typeof address === "bigint") {
+            fabric = this.#fabrics.get("globalId", address);
+        } else {
+            if (typeof address === "object") {
+                address = address.fabricIndex;
+            }
+            fabric = this.#fabrics.get("fabricIndex", address);
         }
-        const fabric = this.maybeForIndex(address);
-        return fabric && !fabric.isDeleting;
+        return fabric !== undefined && !fabric.isDeleting;
     }
 
-    for(address: FabricIndex | PeerAddress) {
-        if (typeof address === "object") {
-            address = address.fabricIndex;
+    /**
+     * Obtain the fabric identified by {@link identifier}.
+     *
+     * Throws if the fabric is not found.
+     */
+    for(identifier: Fabric.Identifier) {
+        let fabric;
+        if (typeof identifier === "bigint") {
+            fabric = this.#fabrics.get("globalId", identifier);
+        } else {
+            if (typeof identifier === "object") {
+                identifier = identifier.fabricIndex;
+            }
+            fabric = this.#fabrics.get("fabricIndex", identifier);
         }
-        const fabric = this.#fabrics.get(address);
-        if (fabric === undefined) {
-            throw new FabricNotFoundError(`Cannot access fabric for unknown index ${address}`);
+
+        if (fabric === undefined || fabric.isDeleting) {
+            const str = typeof identifier === "bigint" ? GlobalFabricId.strOf(identifier) : `#${identifier}`;
+            throw new FabricNotFoundError(
+                `Fabric index ${str} ${fabric === undefined ? "does not exist" : "is deleted"}`,
+            );
         }
         return fabric;
     }
 
+    /**
+     * Get the fabric identified by {@link identifier} if present.
+     */
+    maybeFor(identifier: Fabric.Identifier) {
+        if (this.has(identifier)) {
+            return this.for(identifier);
+        }
+    }
+
     allocateFabricIndex() {
         this.#construction.assert();
 
         for (let i = 0; i < 254; i++) {
             const fabricIndex = this.#nextFabricIndex++;
             if (this.#nextFabricIndex > 254) this.#nextFabricIndex = 1;
-            if (!this.#fabrics.has(FabricIndex(fabricIndex))) {
+            if (!this.#fabrics.get("fabricIndex", FabricIndex(fabricIndex))) {
                 return FabricIndex(fabricIndex);
             }
         }
@@ -163,7 +195,7 @@ export class FabricManager {
 
     #addNewFabric(fabric: Fabric) {
         const { fabricIndex } = fabric;
-        if (this.#fabrics.has(fabricIndex)) {
+        if (this.#fabrics.get("fabricIndex", fabricIndex)) {
             throw new MatterFlowError(`Fabric with index ${fabricIndex} already exists.`);
         }
 
@@ -176,8 +208,12 @@ export class FabricManager {
 
     /** Insert Fabric into the manager without emitting events */
     #addOrUpdateFabricEntry(fabric: Fabric) {
-        const { fabricIndex } = fabric;
-        this.#fabrics.set(fabricIndex, fabric);
+        const existing = this.#fabrics.get("fabricIndex", fabric.fabricIndex);
+        if (existing) {
+            this.#fabrics.delete(existing);
+        }
+
+        this.#fabrics.add(fabric);
 
         fabric.leaving.on(() => this.events.leaving.emit(fabric));
         fabric.deleting.on(() => this.events.deleting.emit(fabric));
@@ -186,7 +222,7 @@ export class FabricManager {
         fabric.persistCallback = (isUpdate = true) => {
             if (!this.#storage) {
                 if (isUpdate) {
-                    logger.warn(`Fabric ${fabricIndex} cannot persist because FabricManager has no storage`);
+                    logger.warn(`Fabric ${fabric.fabricIndex} cannot persist because FabricManager has no storage`);
                 }
                 return;
             }
@@ -198,14 +234,14 @@ export class FabricManager {
             });
         };
         if (this.#storage !== undefined && fabric.storage === undefined) {
-            fabric.storage = this.#storage.createContext(`fabric-${fabricIndex}`);
+            fabric.storage = this.#storage.createContext(`fabric-${fabric.fabricIndex}`);
         }
     }
 
     async #handleFabricDeleted(fabric: Fabric) {
         await this.#construction;
 
-        this.#fabrics.delete(fabric.fabricIndex);
+        this.#fabrics.delete(fabric);
         if (this.#storage) {
             await this.persistFabrics();
         }
@@ -221,7 +257,7 @@ export class FabricManager {
     get fabrics() {
         this.#construction.assert();
 
-        return Array.from(this.#fabrics.values()).filter(fabric => !fabric.isDeleting);
+        return this.#fabrics.filter(fabric => !fabric.isDeleting);
     }
 
     get length() {
@@ -239,18 +275,31 @@ export class FabricManager {
     async findFabricFromDestinationId(destinationId: Bytes, initiatorRandom: Bytes) {
         this.#construction.assert();
 
-        for (const fabric of this.#fabrics.values()) {
+        for (const fabric of this.#fabrics) {
             const candidateDestinationIds = await fabric.destinationIdsFor(fabric.nodeId, initiatorRandom);
             if (candidateDestinationIds.some(candidate => Bytes.areEqual(candidate, destinationId))) {
                 if (fabric.isDeleting) {
-                    throw new FabricNotFoundError("Fabric is deleting");
+                    throw new FabricNotFoundError("Fabric is deleting for CASE sigma2");
                 }
 
                 return fabric;
             }
         }
 
-        throw new FabricNotFoundError("Fabric not found");
+        const fabrics = this.#fabrics.map(
+            fabric =>
+                `#${fabric.fabricIndex} (node ID ${NodeId.strOf(fabric.nodeId)}) keys ${fabric.groups.keySets
+                    .allKeysForId(0)
+                    .map(({ key }) => Bytes.toHex(key))
+                    .join(" & ")}`,
+        );
+
+        logger.debug(
+            `No match for destination ID`,
+            Diagnostic.dict({ destId: destinationId, random: initiatorRandom, ...fabrics }),
+        );
+
+        throw new FabricNotFoundError("Fabric not found for CASE sigma2");
     }
 
     findByKeypair(keypair: Key) {
@@ -264,28 +313,6 @@ export class FabricManager {
         return undefined;
     }
 
-    maybeForIndex(index: FabricIndex) {
-        this.#construction.assert();
-
-        const fabric = this.#fabrics.get(index);
-        if (fabric && !fabric.isDeleting) {
-            return fabric;
-        }
-    }
-
-    forIndex(index: FabricIndex) {
-        this.#construction.assert();
-
-        const fabric = this.#fabrics.get(index);
-        if (fabric === undefined) {
-            throw new FabricNotFoundError(`Fabric index ${index} does not exist`);
-        }
-        if (fabric.isDeleting) {
-            throw new FabricNotFoundError(`Fabric index ${index} is deleting`);
-        }
-        return fabric;
-    }
-
     forDescriptor(descriptor: { rootPublicKey: Bytes; fabricId: FabricId }) {
         this.#construction.assert();
 
@@ -300,7 +327,7 @@ export class FabricManager {
         await this.#construction;
 
         const { fabricIndex } = fabric;
-        const existingFabric = this.#fabrics.get(fabricIndex);
+        const existingFabric = this.for(fabricIndex);
         if (existingFabric === undefined) {
             throw new FabricNotFoundError(
                 `Fabric with index ${fabricIndex} cannot be replaced because it does not exist.`,

package/src/groups/FabricGroups.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Fabric } from "#fabric/Fabric.js";
-import { BasicMap, Bytes, InternalError, MatterFlowError, StorageContext } from "#general";
+import { BasicMap, Bytes, hex, InternalError, MatterFlowError, StorageContext } from "#general";
 import { GroupKeySet, KeySets, OperationalKeySet } from "#groups/KeySets.js";
 import { MessagingState } from "#groups/MessagingState.js";
 import { GroupId, MATTER_EPOCH_OFFSET_US } from "#types";
@@ -122,19 +122,15 @@ export class FabricGroups {
         await this.#cleanUpCounters(groupKeySetId);
 
         // Lets pre-calculate the operational keys
-        const operationalId = this.#fabric.operationalId;
-        const operationalEpochKey0 = await this.#fabric.crypto.createHkdfKey(
-            epochKey0,
-            operationalId,
-            GROUP_SECURITY_INFO,
-        );
+        const globalId = Bytes.fromHex(hex.fixed(this.#fabric.globalId, 16));
+        const operationalEpochKey0 = await this.#fabric.crypto.createHkdfKey(epochKey0, globalId, GROUP_SECURITY_INFO);
         const operationalEpochKey1 =
             epochKey1 !== null
-                ? await this.#fabric.crypto.createHkdfKey(epochKey1, operationalId, GROUP_SECURITY_INFO)
+                ? await this.#fabric.crypto.createHkdfKey(epochKey1, globalId, GROUP_SECURITY_INFO)
                 : null;
         const operationalEpochKey2 =
             epochKey2 !== null
-                ? await this.#fabric.crypto.createHkdfKey(epochKey2, operationalId, GROUP_SECURITY_INFO)
+                ? await this.#fabric.crypto.createHkdfKey(epochKey2, globalId, GROUP_SECURITY_INFO)
                 : null;
         this.#keySets.add({
             ...groupKeySet,

package/src/index.ts

@@ -21,6 +21,7 @@ export * from "./fabric/index.js";
 export * from "./groups/index.js";
 export * from "./interaction/index.js";
 export * from "./mdns/index.js";
+export * from "./ota/index.js";
 export * from "./peer/index.js";
 export * from "./protocol/index.js";
 export * from "./securechannel/index.js";