@matter/protocol 0.16.0-alpha.0-20250816-d22ad240d → 0.16.0-alpha.0-20250819-0a388db8b

package/src/certificate/AttestationCertificateManager.ts

@@ -76,7 +76,7 @@ export class AttestationCertificateManager {
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore
     private async generatePAACert(vendorId?: VendorId) {
-        const now = Time.get().now();
+        const now = Time.now;
         const cert = new Paa({
             serialNumber: Bytes.fromHex(toHex(this.paaCertId)),
             signatureAlgorithm: 1 /* EcdsaWithSHA256 */,
@@ -111,7 +111,7 @@ export class AttestationCertificateManager {
     }
 
     private async generatePAICert(vendorId: VendorId, productId?: number) {
-        const now = Time.get().now();
+        const now = Time.now;
         const cert = new Pai({
             serialNumber: Bytes.fromHex(toHex(this.#paiCertId)),
             signatureAlgorithm: 1 /* EcdsaWithSHA256 */,
@@ -146,7 +146,7 @@ export class AttestationCertificateManager {
     }
 
     async generateDaCert(publicKey: Bytes, vendorId: VendorId, productId: number) {
-        const now = Time.get().now();
+        const now = Time.now;
         const certId = this.#nextCertificateId++;
         const cert = new Dac({
             serialNumber: Bytes.fromHex(toHex(certId)),

package/src/certificate/CertificateAuthority.ts

@@ -117,7 +117,7 @@ export class CertificateAuthority {
     }
 
     async #generateRootCert() {
-        const now = Time.get().now();
+        const now = Time.now;
         const cert = new Rcac({
             serialNumber: Bytes.fromHex(toHex(this.#rootCertId)),
             signatureAlgorithm: 1 /* EcdsaWithSHA256 */,
@@ -148,7 +148,7 @@ export class CertificateAuthority {
         nodeId: NodeId,
         caseAuthenticatedTags?: CaseAuthenticatedTag[],
     ) {
-        const now = Time.get().now();
+        const now = Time.now;
         const certId = this.#nextCertificateId++;
         const cert = new Noc({
             serialNumber: Bytes.fromHex(toHex(certId)),

package/src/certificate/kinds/OperationalBase.ts

@@ -62,10 +62,10 @@ export abstract class OperationalBase<CT extends X509Certificate> extends X509Ba
 
         // notBefore date should be already reached, notAfter is not checked right now
         // TODO: implement real checks when we add "Last known Good UTC time"
-        if (cert.notBefore * 1000 > Time.nowMs()) {
-            logger.warn(`Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs()}`);
+        if (cert.notBefore * 1000 > Time.nowMs) {
+            logger.warn(`Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs}`);
             /*throw new CertificateError(
-                `Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs()}`,
+                `Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs}`,
             );*/
         }
     }

package/src/cluster/client/ClusterClient.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { capitalize, Diagnostic, ImplementationError, Logger, Merge } from "#general";
+import { capitalize, Diagnostic, Duration, ImplementationError, Logger, Merge } from "#general";
 import {
     Attribute,
     AttributeId,
@@ -387,16 +387,16 @@ export function ClusterClient<const T extends ClusterType>(
             request: RequestT,
             options: {
                 asTimedRequest?: boolean;
-                timedRequestTimeoutMs?: number;
-                expectedProcessingTimeMs?: number;
+                timedRequestTimeout?: Duration;
+                expectedProcessingTime?: Duration;
                 useExtendedFailSafeMessageResponseTimeout?: boolean;
             } = {},
         ) => {
             const {
                 asTimedRequest,
-                timedRequestTimeoutMs,
+                timedRequestTimeout,
                 useExtendedFailSafeMessageResponseTimeout,
-                expectedProcessingTimeMs,
+                expectedProcessingTime,
             } = options;
             if (isGroupAddress) {
                 return interactionClient.invokeWithSuppressedResponse<Command<RequestT, ResponseT, any>>({
@@ -404,7 +404,7 @@ export function ClusterClient<const T extends ClusterType>(
                     command: commandDef[commandName],
                     request,
                     asTimedRequest,
-                    timedRequestTimeoutMs,
+                    timedRequestTimeout,
                 });
             }
             return interactionClient.invoke<Command<RequestT, ResponseT, any>>({
@@ -413,8 +413,8 @@ export function ClusterClient<const T extends ClusterType>(
                 command: commandDef[commandName],
                 request,
                 asTimedRequest,
-                timedRequestTimeoutMs,
-                expectedProcessingTimeMs,
+                timedRequestTimeout,
+                expectedProcessingTime,
                 useExtendedFailSafeMessageResponseTimeout,
             });
         };

package/src/cluster/client/ClusterClientTypes.ts

@@ -3,7 +3,7 @@
  * Copyright 2022-2025 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Merge } from "#general";
+import { Duration, Merge } from "#general";
 import {
     Attribute,
     AttributeId,
@@ -63,13 +63,13 @@ export type SignatureFromCommandSpec<C extends Command<any, any, any>> = (
         asTimedRequest?: boolean;
 
         /** Override the request timeout when the command is sent as times request. Default are 10s. */
-        timedRequestTimeoutMs?: number;
+        timedRequestTimeout?: Duration;
 
         /**
          * Expected processing time on the device side for this command.
          * useExtendedFailSafeMessageResponseTimeout is ignored if this value is set.
          */
-        expectedProcessingTimeMs?: number;
+        expectedProcessingTime?: Duration;
 
         /**
          * Use the extended fail-safe message response timeout of 30 seconds. Use this for all commands

package/src/cluster/client/EventClient.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ImplementationError } from "#general";
+import { Duration, ImplementationError } from "#general";
 import { ClusterId, EndpointNumber, Event, EventId, EventNumber } from "#types";
 import { DecodedEventData } from "../../interaction/EventDataDecoder.js";
 import { InteractionClient } from "../../interaction/InteractionClient.js";
@@ -58,8 +58,8 @@ export class EventClient<T> {
     }
 
     async subscribe(
-        minIntervalFloorSeconds: number,
-        maxIntervalCeilingSeconds: number,
+        minIntervalFloor: Duration,
+        maxIntervalCeiling: Duration,
         isUrgent = true,
         minimumEventNumber?: EventNumber,
         isFabricFiltered?: boolean,
@@ -71,8 +71,8 @@ export class EventClient<T> {
             endpointId: this.endpointId,
             clusterId: this.clusterId,
             event: this.event,
-            minIntervalFloorSeconds,
-            maxIntervalCeilingSeconds,
+            minIntervalFloor,
+            maxIntervalCeiling,
             isUrgent,
             minimumEventNumber,
             isFabricFiltered,

package/src/common/FailsafeContext.ts

@@ -8,6 +8,7 @@ import {
     AsyncObservable,
     Bytes,
     Construction,
+    Duration,
     Logger,
     MatterFlowError,
     UnexpectedDataError,
@@ -46,7 +47,7 @@ export abstract class FailsafeContext {
     #commissioned = AsyncObservable<[], void>();
 
     constructor(options: FailsafeContext.Options) {
-        const { expiryLengthSeconds, associatedFabric, maxCumulativeFailsafeSeconds } = options;
+        const { expiryLength, associatedFabric, maxCumulativeFailsafe } = options;
 
         this.#sessions = options.sessions;
         this.#fabrics = options.fabrics;
@@ -61,21 +62,18 @@ 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(
-                associatedFabric,
-                expiryLengthSeconds,
-                maxCumulativeFailsafeSeconds,
-                () => this.#failSafeExpired(),
+            this.#failsafe = new FailsafeTimer(associatedFabric, expiryLength, maxCumulativeFailsafe, () =>
+                this.#failSafeExpired(),
             );
-            logger.debug(`Arm failSafe timer for ${expiryLengthSeconds}s.`);
+            logger.debug(`Arm failSafe timer for ${Duration.format(expiryLength)}`);
         });
     }
 
-    async extend(fabric: Fabric | undefined, expiryLengthSeconds: number) {
+    async extend(fabric: Fabric | undefined, expiryLength: Duration) {
         await this.#construction;
-        await this.#failsafe?.reArm(fabric, expiryLengthSeconds);
-        if (expiryLengthSeconds > 0) {
-            logger.debug(`Extend failSafe timer for ${expiryLengthSeconds}s.`);
+        await this.#failsafe?.reArm(fabric, expiryLength);
+        if (expiryLength > 0) {
+            logger.debug(`Extend failSafe timer for ${Duration.format(expiryLength)}`);
         }
     }
 
@@ -341,8 +339,8 @@ export namespace FailsafeContext {
     export interface Options {
         sessions: SessionManager;
         fabrics: FabricManager;
-        expiryLengthSeconds: number;
-        maxCumulativeFailsafeSeconds: number;
+        expiryLength: Duration;
+        maxCumulativeFailsafe: Duration;
         associatedFabric: Fabric | undefined;
     }
 }

package/src/common/FailsafeTimer.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Logger, MatterFlowError, Time, Timer } from "#general";
+import { Duration, Logger, MatterFlowError, Time, Timer } from "#general";
 import { Fabric } from "../fabric/Fabric.js";
 import type { FailsafeContext } from "./FailsafeContext.js";
 
@@ -22,16 +22,14 @@ export class FailsafeTimer {
 
     constructor(
         public associatedFabric: Fabric | undefined,
-        expiryLengthSeconds: number,
-        maxCumulativeFailsafeSeconds: number,
+        expiryLength: Duration,
+        maxCumulativeFailsafe: Duration,
         expiryCallback: () => Promise<void>,
     ) {
         this.#expiryCallback = expiryCallback;
-        this.#failsafeTimer = this.#startFailsafeTimer(expiryLengthSeconds);
-        this.#maxCumulativeFailsafeTimer = Time.getTimer(
-            "Max cumulative failsafe",
-            maxCumulativeFailsafeSeconds * 1000,
-            () => this.expire(),
+        this.#failsafeTimer = this.#startFailsafeTimer(expiryLength);
+        this.#maxCumulativeFailsafeTimer = Time.getTimer("Max cumulative failsafe", maxCumulativeFailsafe, () =>
+            this.expire(),
         ).start();
     }
 
@@ -45,7 +43,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, expiryLengthSeconds: number) {
+    async reArm(associatedFabric: Fabric | undefined, expiry: Duration) {
         if (!this.#failsafeTimer.isRunning) {
             throw new MatterFlowError("FailSafe already expired.");
         }
@@ -58,7 +56,7 @@ export class FailsafeTimer {
 
         this.#failsafeTimer.stop();
 
-        if (expiryLengthSeconds === 0) {
+        if (expiry === 0) {
             // 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).
@@ -67,7 +65,7 @@ export class FailsafeTimer {
             // 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
             // in ExpiryLengthSeconds.
-            this.#failsafeTimer = this.#startFailsafeTimer(expiryLengthSeconds);
+            this.#failsafeTimer = this.#startFailsafeTimer(expiry);
         }
     }
 
@@ -83,8 +81,8 @@ export class FailsafeTimer {
         this.#maxCumulativeFailsafeTimer.stop();
     }
 
-    #startFailsafeTimer(expiryLengthSeconds: number) {
-        return Time.getTimer("Failsafe expiration", expiryLengthSeconds * 1000, () =>
+    #startFailsafeTimer(expiry: Duration) {
+        return Time.getTimer("Failsafe expiration", expiry, () =>
             this.expire().catch(e => logger.error("Error during failsafe expiration", e)),
         ).start();
     }

package/src/common/Scanner.ts

@@ -4,7 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BasicSet, ChannelType, Environment, Environmental, Lifespan, ServerAddress, ServerAddressIp } from "#general";
+import {
+    BasicSet,
+    ChannelType,
+    Duration,
+    Environment,
+    Environmental,
+    Lifespan,
+    ServerAddress,
+    ServerAddressIp,
+} from "#general";
 import { DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
 import { Fabric } from "../fabric/Fabric.js";
 
@@ -32,13 +41,13 @@ export type DiscoveryData = {
     PI?: string;
 
     /** Sleep Idle Interval */
-    SII?: number;
+    SII?: Duration;
 
     /** Sleep Active Interval */
-    SAI?: number;
+    SAI?: Duration;
 
     /** Session active threshold */
-    SAT?: number;
+    SAT?: Duration;
 
     /** TCP supported */
     T?: number; // SupportedTransportsBitmap but comes in as number, so converted on usage
@@ -116,7 +125,7 @@ export interface Scanner {
     findOperationalDevice(
         fabric: Fabric,
         nodeId: NodeId,
-        timeoutSeconds?: number,
+        timeout?: Duration,
         ignoreExistingRecords?: boolean,
     ): Promise<OperationalDevice | undefined>;
 
@@ -132,7 +141,7 @@ export interface Scanner {
      */
     findCommissionableDevices(
         identifier: CommissionableDeviceIdentifiers,
-        timeoutSeconds?: number,
+        timeout?: Duration,
         ignoreExistingRecords?: boolean,
     ): Promise<CommissionableDevice[]>;
 
@@ -144,7 +153,7 @@ export interface Scanner {
     findCommissionableDevicesContinuously(
         identifier: CommissionableDeviceIdentifiers,
         callback: (device: CommissionableDevice) => void,
-        timeoutSeconds?: number,
+        timeout?: Duration,
         cancelSignal?: Promise<void>,
     ): Promise<CommissionableDevice[]>;
 

package/src/events/OccurrenceManager.ts

@@ -277,7 +277,7 @@ export class OccurrenceManager {
 
     add(occurrence: Occurrence): MaybePromise<NumberedOccurrence> {
         return MaybePromise.then(this.#store.add(occurrence), entry => {
-            logger.debug(`Recorded event #${entry.number}: ${Diagnostic.json(occurrence)}`);
+            logger.debug(`Recorded event #${entry.number}`, Diagnostic.dict(occurrence));
             this.#occurrences.push(entry);
             if (this.#occurrences.length > this.#bufferConfig.maxEventAllowance) {
                 this.#startCull();

package/src/groups/FabricGroups.ts

@@ -96,7 +96,7 @@ export class FabricGroups {
 
     /*
     TODO for Controller to generate new epochs
-    addGroupEpoch(groupKeySetId: number, startTimeMs = Time.nowMs()) {
+    addGroupEpoch(groupKeySetId: number, startTimeMs = Time.nowMs) {
         // TODO for Controller to generate new epochs
         const epochKey = Crypto.getRandomData(CRYPTO_SYMMETRIC_KEY_LENGTH);
         const operationalEpochKey = Crypto.hkdf(epochKey, this.#fabric.operationalId, GROUP_SECURITY_INFO);

package/src/groups/KeySets.ts

@@ -5,7 +5,7 @@
  */
 
 import type { GroupKeyManagement } from "#clusters/group-key-management";
-import { BasicSet, Bytes, Crypto, DataReader, ImplementationError, MatterFlowError, Time } from "#general";
+import { BasicSet, Bytes, Crypto, DataReader, ImplementationError, MatterFlowError, Time, Timestamp } from "#general";
 
 export const GROUP_KEY_INFO = Bytes.fromString("GroupKeyHash");
 
@@ -44,7 +44,7 @@ export class KeySets<T extends OperationalKeySet> extends BasicSet<T> {
         if (groupKeySet === undefined) {
             throw new MatterFlowError(`GroupKeySet for groupKeySet ${keySetId} not found.`);
         }
-        const operationalKeys = Array<{ key: Bytes; sessionId?: number; startTime: number | bigint }>();
+        const operationalKeys = Array<{ key: Bytes; sessionId?: number; startTime: Timestamp }>();
         const {
             operationalEpochKey0,
             groupSessionId0,
@@ -63,13 +63,21 @@ export class KeySets<T extends OperationalKeySet> extends BasicSet<T> {
         operationalKeys.push({
             key: operationalEpochKey0,
             sessionId: groupSessionId0 !== null ? groupSessionId0 : undefined,
-            startTime: epochStartTime0,
+            startTime: Timestamp.fromMicroseconds(epochStartTime0),
         });
         if (operationalEpochKey1 !== null && groupSessionId1 !== null && epochStartTime1 !== null) {
-            operationalKeys.push({ key: operationalEpochKey1, sessionId: groupSessionId1, startTime: epochStartTime1 });
+            operationalKeys.push({
+                key: operationalEpochKey1,
+                sessionId: groupSessionId1,
+                startTime: Timestamp.fromMicroseconds(epochStartTime1),
+            });
         }
         if (operationalEpochKey2 !== null && groupSessionId2 !== null && epochStartTime2 !== null) {
-            operationalKeys.push({ key: operationalEpochKey2, sessionId: groupSessionId2, startTime: epochStartTime2 });
+            operationalKeys.push({
+                key: operationalEpochKey2,
+                sessionId: groupSessionId2,
+                startTime: Timestamp.fromMicroseconds(epochStartTime2),
+            });
         }
         return operationalKeys;
     }
@@ -96,7 +104,7 @@ export class KeySets<T extends OperationalKeySet> extends BasicSet<T> {
             // epoch key (specifically, the epoch key with the latest start time that is not in the future).
             // TODO Nodes that cannot reliably keep track of time calculate the current epoch key as described in
             //  Section 4.17.3.4, “Epoch Key Rotation without Time Synchronization”.
-            const now = Time.nowUs();
+            const now = Time.nowUs;
             const relevantKeys = operationalKeys.filter(({ startTime }) => startTime <= now);
             if (relevantKeys.length === 0) {
                 throw new ImplementationError(