@matter/node 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

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

@@ -82,6 +82,10 @@ export interface ValReference<T extends Val = Val> {
 export namespace ValReference {
     /**
      * How a container keys its own members.
+     *
+     * `id` also asserts provenance: only a datasource mirroring a peer keys by element ID, and for such a container
+     * the peer's reports are the only source of values — no locally derived value (state-class field initializer,
+     * configured default or computed schema default) may enter it or be synthesized on read.
      */
     export type PrimaryKey = "id" | "name";
 }

package/src/behavior/state/managed/values/StructManager.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { camelize, GeneratedClass, ImplementationError, isObject } from "@matter/general";
+import { camelize, deepCopy, GeneratedClass, isObject } from "@matter/general";
 import type { Schema } from "@matter/model";
-import { Access, ElementTag, FieldValue, Metatype, ValueModel } from "@matter/model";
+import { Access, ElementTag, FieldValue, MandatoryDefaultValue, Metatype, ValueModel } from "@matter/model";
 import { AccessControl, PhantomReferenceError, SchemaImplementationError, Val } from "@matter/protocol";
 import { FabricIndex } from "@matter/types";
 import { RootSupervisor } from "../../../supervision/RootSupervisor.js";
@@ -14,24 +14,23 @@ import type { ValueSupervisor } from "../../../supervision/ValueSupervisor.js";
 import { Instrumentation } from "../Instrumentation.js";
 import { Internal } from "../Internal.js";
 import { ManagedReference } from "../ManagedReference.js";
-import { memberFallbackKeyFor, memberKeyFor, memberValueOf } from "../MemberKeys.js";
+import {
+    memberFallbackKeyFor,
+    memberKeyFor,
+    memberReadFallbackKeyFor,
+    memberSlotOf,
+    memberValueOf,
+} from "../MemberKeys.js";
 import { NameResolver } from "../NameResolver.js";
 import type { ValReference } from "../ValReference.js";
 import { PrimitiveManager } from "./PrimitiveManager.js";
 
-const AUTHORIZE_READ = Symbol("authorize-read");
-
 /**
  * Internal view of struct.
  */
 interface Struct extends Val.Struct {
     [Internal.session]: ValueSupervisor.Session;
     [Internal.reference]: ValReference<Val.Struct>;
-
-    /**
-     * Direct read authorization.
-     */
-    [AUTHORIZE_READ](attributeId: number): void;
 }
 
 /**
@@ -48,26 +47,12 @@ export function StructManager(owner: RootSupervisor, schema: Schema): ValueSuper
         // [Symbol.toStringTag]: {
         //     value: name,
         // },
-
         // TODO - makes Mocha diffs pretty useless.  Best fix is probably customized diff but leaving out for now
         // toString: {
         //     value() {
         //         return serialize(this);
         //     }
         // },
-
-        // AUTHORIZE_READ is effectively a protected method, see StructManager.assertDirectReadAuthorized below
-        [AUTHORIZE_READ]: {
-            value(this: Struct, attributeId: number) {
-                const access = propertyAccessControls[attributeId];
-
-                if (access === undefined) {
-                    throw new ImplementationError(`Direct read of unknown property ${attributeId}`);
-                }
-
-                access.authorizeRead(this[Internal.session], this[Internal.reference].location);
-            },
-        },
     } as PropertyDescriptorMap;
 
     /**
@@ -75,7 +60,6 @@ export function StructManager(owner: RootSupervisor, schema: Schema): ValueSuper
      */
     const instanceDescriptors = {} as PropertyDescriptorMap;
 
-    const propertyAccessControls = {} as Record<number, AccessControl>;
     let hasFabricIndex = false;
     const isCluster = schema.tag === ElementTag.Cluster;
 
@@ -83,12 +67,11 @@ export function StructManager(owner: RootSupervisor, schema: Schema): ValueSuper
     for (const member of owner.membersOf(schema)) {
         const name = member.propertyName;
 
-        const { access, descriptor } = configureProperty(owner, member);
+        const { descriptor } = configureProperty(owner, member);
 
         instanceDescriptors[name] = descriptor;
         if (member.id !== undefined) {
             prototypeDescriptors[member.id] = { ...descriptor, enumerable: false };
-            propertyAccessControls[member.id] = access;
         }
 
         if (member.name === "FabricIndex") {
@@ -150,25 +133,6 @@ export function StructManager(owner: RootSupervisor, schema: Schema): ValueSuper
     };
 }
 
-export namespace StructManager {
-    /**
-     * If a struct is referenced as a whole, fields for which the session are unauthorized are simply omitted.
-     *
-     * This function instead throws an error for unauthorized access.  It must be invoked before direct property reads.
-     *
-     * @deprecated remove with old API
-     *
-     * @param struct a managed struct
-     * @param attributeId the AttributeId to read
-     */
-    export function assertDirectReadAuthorized(struct: Val.Struct, attributeId: number) {
-        if (!(struct as Struct)?.[AUTHORIZE_READ]) {
-            throw new ImplementationError("Cannot authorize read of unmanaged value");
-        }
-        return (struct as Struct)[AUTHORIZE_READ](attributeId);
-    }
-}
-
 function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
     const name = schema.propertyName;
     const id = schema.id;
@@ -186,6 +150,36 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
         defaultReader = NameResolver(supervisor, schema.parent, camelize(FieldValue.referenced(schema.default)!));
     }
 
+    // A member mandatory under the mirror's active features always reads a value even when the peer's
+    // AttributeList omits it, and an optional member stays undefined even when the peer's AttributeList reports
+    // it -- this mirrors the conformance-aware TypeScript typings, which know nothing about runtime AttributeList
+    // data. The container itself never holds this value, so it can't masquerade as peer data in persistence,
+    // change detection or external-change integration.
+    const scope = supervisor.scope;
+    const isMandatory = scope.isMandatory(schema);
+
+    // The template is memoized but every value handed out is a fresh copy: an explicit schema default is
+    // model-owned shared state.
+    let template: Val | undefined;
+    let templated = false;
+    const synthesizeDefault = isMandatory
+        ? () => {
+              if (!templated) {
+                  template = MandatoryDefaultValue(scope, schema);
+                  templated = true;
+              }
+              return deepCopy(template);
+          }
+        : undefined;
+
+    // Rebind so the closure below narrows: TS doesn't narrow a captured `let` across a nested function boundary.
+    const referencedDefault = defaultReader;
+    const readDefault: ((self: Struct) => Val | undefined) | undefined = synthesizeDefault
+        ? referencedDefault
+            ? (self: Struct) => referencedDefault(self) ?? synthesizeDefault()
+            : () => synthesizeDefault()
+        : undefined;
+
     const descriptor: PropertyDescriptor = {
         enumerable: true,
 
@@ -195,17 +189,11 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             // We allow attribute/field name or id as key.  If name is present id is ignored
             const pk = this[Internal.reference].primaryKey;
             let key = memberKeyFor(pk, name, id);
-            let storedKey: undefined | number | string;
-            if (key in this[Internal.reference].value) {
-                storedKey = key;
-            } else {
-                const fallbackKey = memberFallbackKeyFor(pk, name, id);
-                if (fallbackKey !== undefined && fallbackKey in this[Internal.reference].value) {
-                    storedKey = fallbackKey;
-                }
-            }
+            let storedKey = memberSlotOf(this[Internal.reference].value, key, memberFallbackKeyFor(pk, name, id));
 
-            const oldValue = storedKey === undefined ? undefined : this[Internal.reference].value[storedKey];
+            // Rollback and the fabric-scoped-list merge check must see stored truth — never the write-migration
+            // slot above and never a synthesized default
+            const oldValue = memberValueOf(this[Internal.reference].value, key, memberReadFallbackKeyFor(pk, name, id));
 
             const self = this;
 
@@ -214,6 +202,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
 
                 // Identify the target.  Usually just "struct" except when struct supports Val.Dynamic
                 let target;
+                let previousValue = oldValue;
                 if (Val.properties in struct) {
                     const properties = (struct as Val.Dynamic)[Val.properties](
                         this[Internal.reference].rootOwner,
@@ -222,6 +211,13 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     if (name in properties) {
                         key = storedKey = name;
                         target = properties;
+                        if (isFabricScopedList || validate) {
+                            // A dynamic member's previous value lives in the provider, not the container slot;
+                            // read it only when rollback or the fabric-scoped merge check may consume it, as the
+                            // provider's getter may be costly.  Unmanage in case the provider serves a managed
+                            // value — rollback must not plant a proxy that expires with this session
+                            previousValue = Internal.unmanage(properties[name]);
+                        }
                     } else {
                         target = struct;
                     }
@@ -233,10 +229,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 value = Internal.unmanage(value);
 
                 // Modify the value
-                if (isFabricScopedList && Array.isArray(value) && Array.isArray(oldValue)) {
+                if (isFabricScopedList && Array.isArray(value) && Array.isArray(previousValue)) {
                     // In the case of fabric-scoped write to established list we use the managed proxy to perform update
                     // as it will sort through values and only modify those with correct fabricIndex
-                    const proxy = self[name] as Val.List;
+                    const proxy = self[memberKeyFor(pk, name, id)] as Val.List;
                     for (let i = 0; i < value.length; i++) {
                         proxy[i] = value[i];
                     }
@@ -265,8 +261,14 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                         });
                     } catch (e) {
                         // Undo our change on error.  Rollback will take care of this when transactional but this
-                        // handles the cases of 1.) no transaction, and 2.) error is caught within transaction
-                        target[key] = oldValue;
+                        // handles the cases of 1.) no transaction, and 2.) error is caught within transaction.
+                        // A previously absent member must not leave a slot behind — consumers enumerate slot keys to
+                        // discover which members hold values
+                        if (previousValue === undefined) {
+                            delete target[key];
+                        } else {
+                            target[key] = previousValue;
+                        }
 
                         throw e;
                     }
@@ -294,11 +296,12 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 }
 
                 const primaryKey = this[Internal.reference].primaryKey;
-                return memberValueOf(
+                const value = memberValueOf(
                     struct,
                     memberKeyFor(primaryKey, name, id),
-                    memberFallbackKeyFor(primaryKey, name, id),
+                    memberReadFallbackKeyFor(primaryKey, name, id),
                 );
+                return value === undefined && primaryKey === "id" ? readDefault?.(this) : value;
             }
         };
     } else {
@@ -341,17 +344,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 if (name in properties) {
                     value = properties[name];
                 } else {
-                    value = struct[key];
-                }
-            } else if (key in struct) {
-                value = struct[key];
-            } else if (primaryKey === "name") {
-                // A value decoded without a schema — an unknown cluster or attribute, including one a later model
-                // learns about — keys its members by TLV tag number, so a name-keyed container accepts the ID too.
-                const fallbackKey = memberFallbackKeyFor(primaryKey, name, id);
-                if (fallbackKey !== undefined && fallbackKey in struct) {
-                    value = struct[fallbackKey];
+                    value = memberValueOf(struct, key, memberReadFallbackKeyFor(primaryKey, name, id));
                 }
+            } else {
+                value = memberValueOf(struct, key, memberReadFallbackKeyFor(primaryKey, name, id));
             }
 
             // Note that we only mask values that are unreadable.  This is appropriate when the parent object is
@@ -362,7 +358,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             }
 
             if (value === undefined) {
-                return defaultReader?.(this);
+                return primaryKey === "name" ? defaultReader?.(this) : readDefault?.(this);
             }
 
             // Value is null or a dynamic property, so just return it

package/src/behavior/state/validation/ValueValidator.ts

@@ -13,6 +13,7 @@ import { RootSupervisor } from "../../supervision/RootSupervisor.js";
 import { maybeConfigOf } from "../../supervision/SupervisionConfig.js";
 import type { ValueSupervisor } from "../../supervision/ValueSupervisor.js";
 import { Internal } from "../managed/Internal.js";
+import { memberSlotOf, memberValueOf } from "../managed/MemberKeys.js";
 import {
     assertArray,
     assertBoolean,
@@ -309,6 +310,8 @@ function createIntegerValidator(schema: ValueModel, supervisor: RootSupervisor,
     // per-field StructManager setter path AND the ListManager.writeEntry path (which writes raw entry objects
     // bypassing per-field setters).  One mechanism handles every setStateOf path.
     if (isFabricIndexSentinel(schema)) {
+        const fieldName = schema.propertyName;
+        const fieldId = schema.id;
         const fabricSentinelOrSubstitute: ValueSupervisor.Validate = (value, session, location) => {
             const peerContext = session.clientPeerContext;
             if (value !== FabricIndex.OMIT_FABRIC || peerContext === undefined) {
@@ -317,7 +320,9 @@ function createIntegerValidator(schema: ValueModel, supervisor: RootSupervisor,
             }
             const siblings = location.siblings as Val.Struct | undefined;
             if (siblings !== undefined && peerContext.fabricIndexOnPeer !== undefined) {
-                siblings.fabricIndex = peerContext.fabricIndexOnPeer;
+                // Substitute into the slot holding the sentinel — a name-keyed container may hold it under the
+                // field's TLV tag number, and writing another slot would leave two disagreeing fabricIndex values
+                siblings[memberSlotOf(siblings, fieldName, fieldId) ?? fieldName] = peerContext.fabricIndexOnPeer;
                 return;
             }
             logger.debug(
@@ -332,7 +337,7 @@ function createIntegerValidator(schema: ValueModel, supervisor: RootSupervisor,
 }
 
 function createStructValidator(schema: Schema, supervisor: RootSupervisor): ValueSupervisor.Validate {
-    const validators = {} as Record<string, ValueSupervisor.Validate>;
+    const validators = {} as Record<string, { id: number | undefined; validate: ValueSupervisor.Validate }>;
 
     for (const field of supervisor.membersOf(schema)) {
         // Skip deprecated, and global attributes we currently handle in lower levels
@@ -341,7 +346,7 @@ function createStructValidator(schema: Schema, supervisor: RootSupervisor): Valu
         }
         const validate = supervisor.get(field).validate;
         if (validate) {
-            validators[field.propertyName] = validate;
+            validators[field.propertyName] = { id: field.id, validate };
         }
     }
 
@@ -359,23 +364,27 @@ function createStructValidator(schema: Schema, supervisor: RootSupervisor): Valu
         } as ValidationLocation;
 
         for (const name in validators) {
+            const { id, validate } = validators[name];
             let value;
 
+            // The validator has no reference and thus no primaryKey, so it accepts either spelling, name preferred:
+            // a name-keyed struct decoded without a schema keys members by TLV tag number, and an id-keyed mirror
+            // root keys by id canonically — do not narrow this to the read-fallback policy
             if ((struct as Val.Dynamic)[Val.properties]) {
                 const rootOwner = (struct as unknown as Internal.Collection)[Internal.reference];
                 const properties = (struct as Val.Dynamic)[Val.properties](rootOwner, session);
                 if (name in properties) {
                     value = properties[name];
                 } else {
-                    value = struct[name];
+                    value = memberValueOf(struct, name, id);
                 }
             } else {
-                value = struct[name];
+                value = memberValueOf(struct, name, id);
             }
 
             sublocation.path.id = name;
             sublocation.config = config?.readonlyChild?.(name);
-            validators[name](value, session, sublocation);
+            validate(value, session, sublocation);
         }
 
         for (const name in sublocation.choices) {

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -7,6 +7,7 @@
 import { Behavior } from "#behavior/Behavior.js";
 import { Events as BaseEvents } from "#behavior/Events.js";
 import { SoftwareUpdateManager } from "#behavior/system/software-update/SoftwareUpdateManager.js";
+import { AdministratorCommissioningClient } from "#behaviors/administrator-commissioning";
 import { BasicInformationClient } from "#behaviors/basic-information";
 import { OperationalCredentialsClient } from "#behaviors/operational-credentials";
 import { OtaSoftwareUpdateProviderServer } from "#behaviors/ota-software-update-provider";
@@ -16,6 +17,8 @@ import type { ServerNode } from "#node/ServerNode.js";
 import {
     causedBy,
     ClassExtends,
+    Crypto,
+    CRYPTO_PBKDF_ITERATIONS_MIN,
     Diagnostic,
     Duration,
     ImplementationError,
@@ -61,6 +64,7 @@ import {
     FabricRemovedError,
     LocatedNodeCommissioningOptions,
     OperationalAddress,
+    PaseClient,
     Peer,
     PeerAddress,
     PeerInitiatedCloseError,
@@ -74,14 +78,20 @@ import {
 } from "@matter/protocol";
 import {
     CaseAuthenticatedTag,
+    CommissioningFlowType,
     DeviceTypeId,
     DiscoveryCapabilitiesBitmap,
+    DiscoveryCapabilitiesSchema,
     FabricIndex,
     ManualPairingCodeCodec,
     NodeId,
+    QrPairingCodeCodec,
+    Status,
+    StatusResponseError,
     TypeFromPartialBitSchema,
     VendorId,
 } from "@matter/types";
+import { AdministratorCommissioning } from "@matter/types/clusters/administrator-commissioning";
 import { OperationalCredentials } from "@matter/types/clusters/operational-credentials";
 import { ControllerBehavior } from "../controller/ControllerBehavior.js";
 import { NetworkClient } from "../network/NetworkClient.js";
@@ -403,6 +413,103 @@ export class CommissioningClient extends Behavior {
         }
     }
 
+    /**
+     * Open a Basic Commissioning Window (uses the passcode originally printed on the device).
+     *
+     * This is an optional feature and not all devices support it; use {@link openEnhancedCommissioningWindow} unless
+     * you specifically need the basic commissioning method.
+     */
+    async openBasicCommissioningWindow(commissioningTimeout: Duration = Seconds(900)) {
+        if (!this.endpoint.featuresOf(AdministratorCommissioningClient).basic) {
+            throw new ImplementationError(`${this.endpoint} does not support the basic commissioning method`);
+        }
+
+        const adminCommissioning = this.agent.get(AdministratorCommissioningClient);
+        await this.#revokeStaleCommissioningWindow(adminCommissioning);
+
+        await adminCommissioning.openBasicCommissioningWindow({
+            commissioningTimeout: Seconds.of(commissioningTimeout),
+        });
+    }
+
+    /**
+     * Open an Enhanced Commissioning Window using a freshly generated random passcode.
+     *
+     * The peer's BasicInformation must be seeded — its vendor/product IDs are encoded into the QR pairing code — so
+     * this throws (before opening any window) if it is not.
+     *
+     * @returns the manual and QR pairing codes encoding the generated passcode.
+     */
+    async openEnhancedCommissioningWindow(
+        commissioningTimeout: Duration = Seconds(900),
+    ): Promise<{ manualPairingCode: string; qrPairingCode: string }> {
+        const basicInformation = this.endpoint.maybeStateOf(BasicInformationClient);
+        if (basicInformation === undefined) {
+            throw new ImplementationError(
+                `${this.endpoint} must be seeded (BasicInformation) before opening an enhanced commissioning window; its vendor/product IDs are encoded in the QR pairing code`,
+            );
+        }
+
+        const adminCommissioning = this.agent.get(AdministratorCommissioningClient);
+        await this.#revokeStaleCommissioningWindow(adminCommissioning);
+
+        const crypto = this.env.get(Crypto);
+        const discriminator = PaseClient.generateRandomDiscriminator(crypto);
+        const passcode = PaseClient.generateRandomPasscode(crypto);
+        const salt = crypto.randomBytes(32);
+        const iterations = CRYPTO_PBKDF_ITERATIONS_MIN;
+        const pakePasscodeVerifier = await PaseClient.generatePakePasscodeVerifier(crypto, passcode, {
+            iterations,
+            salt,
+        });
+
+        await adminCommissioning.openCommissioningWindow({
+            commissioningTimeout: Seconds.of(commissioningTimeout),
+            pakePasscodeVerifier,
+            salt,
+            iterations,
+            discriminator,
+        });
+
+        const { vendorId, productId } = basicInformation;
+
+        // TODO: If the timeout is shorter than 15 minutes, also encode it in the QR code's TLV data.
+        const qrPairingCode = QrPairingCodeCodec.encode([
+            {
+                version: 0,
+                vendorId,
+                productId,
+                flowType: CommissioningFlowType.Standard,
+                discriminator,
+                passcode,
+                discoveryCapabilities: DiscoveryCapabilitiesSchema.encode({ onIpNetwork: true }),
+            },
+        ]);
+
+        return {
+            manualPairingCode: ManualPairingCodeCodec.encode({
+                discriminator,
+                passcode,
+                flowType: CommissioningFlowType.Standard,
+            }),
+            qrPairingCode,
+        };
+    }
+
+    /** Tolerates the device reporting that no window is currently open, so a stale window can be revoked blindly. */
+    async #revokeStaleCommissioningWindow(adminCommissioning: AdministratorCommissioningClient) {
+        try {
+            await adminCommissioning.revokeCommissioning();
+        } catch (error) {
+            if (
+                !StatusResponseError.is(error, Status.Failure) ||
+                StatusResponseError.of(error)?.clusterCode !== AdministratorCommissioning.StatusCode.WindowNotOpen
+            ) {
+                throw error;
+            }
+        }
+    }
+
     /**
      * Override to implement CASE commissioning yourself.
      *
@@ -1005,15 +1112,19 @@ export namespace CommissioningClient {
         regulatoryCountryCode?: ControllerCommissioningFlowOptions["regulatoryCountryCode"];
 
         /**
-         * Override the final commissioning step.
+         * Override the final operational step of commissioning.
          *
-         * When provided, matter.js completes commissioning over PASE and then calls this function instead of performing
-         * the CASE reconnection and "CommissioningComplete" command internally.  The function must connect to the device
-         * operationally and invoke "CommissioningComplete" itself.
+         * The flow runs PASE, arm-failsafe, CSR and AddNOC as usual, then invokes this hook **instead of** connecting
+         * to the device operationally and sending "CommissioningComplete" itself, and awaits it. The hook owns the
+         * finalization and must drive it to completion before resolving: resolve on success, throw on failure.
+         * `commission()` resolves or rejects with this hook's outcome — a throw rolls the commissioning back.
          *
-         * This is used by {@link PaseCommissioner} so that a lightweight commissioner can perform the PASE phase and
-         * then hand off to a full controller to finish commissioning.
-         * TODO: Revisit when we decide how to continue with the PaseCommissioner approach at all
+         * For a delegated/split flow, hand `address.nodeId` and `discoveryData` to the controller that will finish
+         * (typically a separate, network-side controller sharing this fabric) and **await** its
+         * `serverNode.peers.completeCommissioning(nodeId, discoveryData)` from within this hook. Do not return before
+         * that completes: the PASE session is held open across the hook and the device's failsafe stays armed until
+         * "CommissioningComplete" arrives, so returning early leaves the device mid-commission and it reverts,
+         * discarding the freshly issued NOC. See docs/MIGRATION_CONTROLLER_018.md for the full recipe.
          */
         finalizeCommissioning?: (address: ProtocolPeerAddress, discoveryData?: DiscoveryData) => Promise<void>;
 

package/src/behavior/system/network/NetworkBehavior.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { MaybePromise, STANDARD_MATTER_PORT } from "@matter/general";
+import { MaybePromise } from "@matter/general";
 import { Behavior } from "../../Behavior.js";
 import type { NetworkRuntime } from "./NetworkRuntime.js";
 
@@ -37,7 +37,11 @@ export namespace NetworkBehavior {
     }
 
     export class State {
-        port = STANDARD_MATTER_PORT;
+        /**
+         * The operational port the node binds.  When unset the node binds the standard Matter port (5540) if it is
+         * commissionable, or an ephemeral port if commissioning is disabled (e.g. a controller).
+         */
+        port?: number = undefined;
         operationalPort = -1;
     }
 }