@matter/general 0.16.0-alpha.0-20250809-ee8375bcb → 0.16.0-alpha.0-20250812-285b75d83

package/src/codec/DnsCodec.ts

@@ -16,20 +16,13 @@ import { ipv4BytesToString, ipv4ToBytes, ipv6BytesToString, ipv6ToBytes, isIPv4,
  */
 export const MAX_MDNS_MESSAGE_SIZE = 1232; // 1280bytes (IPv6 packet size) - 8bytes (UDP header) - 40bytes (IPv6 IP header, IPv4 is only 20bytes)
 
-export const PtrRecord = (
-    name: string,
-    ptr: string,
-    forInstance?: string,
-    ttl = 120,
-    flushCache = false,
-): DnsRecord<string> => ({
+export const PtrRecord = (name: string, ptr: string, ttl = 120, flushCache = false): DnsRecord<string> => ({
     name,
     value: ptr,
     ttl,
     recordType: DnsRecordType.PTR,
     recordClass: DnsRecordClass.IN,
     flushCache,
-    forInstance,
 });
 export const ARecord = (name: string, ip: string, ttl = 120, flushCache = false): DnsRecord<string> => ({
     name,
@@ -47,25 +40,17 @@ export const AAAARecord = (name: string, ip: string, ttl = 120, flushCache = fal
     recordClass: DnsRecordClass.IN,
     flushCache,
 });
-export const TxtRecord = (
-    name: string,
-    entries: string[],
-    forInstance?: string,
-    ttl = 120,
-    flushCache = false,
-): DnsRecord<string[]> => ({
+export const TxtRecord = (name: string, entries: string[], ttl = 120, flushCache = false): DnsRecord<string[]> => ({
     name,
     value: entries,
     ttl,
     recordType: DnsRecordType.TXT,
     recordClass: DnsRecordClass.IN,
     flushCache,
-    forInstance,
 });
 export const SrvRecord = (
     name: string,
     srv: SrvRecordValue,
-    forInstance?: string,
     ttl = 120,
     flushCache = false,
 ): DnsRecord<SrvRecordValue> => ({
@@ -75,7 +60,6 @@ export const SrvRecord = (
     recordType: DnsRecordType.SRV,
     recordClass: DnsRecordClass.IN,
     flushCache,
-    forInstance,
 });
 
 export type SrvRecordValue = {
@@ -92,14 +76,13 @@ export type DnsQuery = {
     uniCastResponse?: boolean;
 };
 
-export type DnsRecord<T> = {
+export type DnsRecord<T = unknown> = {
     name: string;
     recordType: DnsRecordType;
     recordClass: DnsRecordClass;
     flushCache?: boolean;
     ttl: number;
     value: T;
-    forInstance?: string;
 };
 
 export type DnsMessage = {

package/src/crypto/Key.ts

@@ -13,7 +13,7 @@ import { KeyInputError } from "./CryptoError.js";
 
 const {
     numberToBytesBE,
-    p256: { ProjectivePoint },
+    p256: { Point, getSharedSecret },
 } = ec;
 
 const JWK_KEYS = [
@@ -211,6 +211,7 @@ export interface PrivateKey extends PublicKey {
     privateKey: Uint8Array;
     keyPair: BinaryKeyPair;
     keyPairBits: BinaryKeyPair;
+    sharedSecretFor(peerKey: PublicKey): Uint8Array;
 }
 
 /**
@@ -535,7 +536,7 @@ export function Key(properties: Partial<Key>) {
         }
 
         // Compute
-        const ecKey = ProjectivePoint.fromPrivateKey(that.privateKey);
+        const ecKey = Point.fromPrivateKey(that.privateKey);
 
         // Install
         that.xBits = numberToBytesBE(ecKey.x, keyLength);
@@ -573,7 +574,8 @@ export function PrivateKey(privateKey: Uint8Array | BinaryKeyPair, options?: Par
         privateKey: priv,
         publicKey: pub,
         ...options,
-    }) as PrivateKey;
+        sharedSecretFor,
+    } as Key) as PrivateKey;
 }
 
 /**
@@ -597,3 +599,12 @@ export function SymmetricKey(privateKey: Uint8Array, options?: Partial<Key>) {
         ...options,
     });
 }
+
+/**
+ * Diffie-Hellman shared secret computation.
+ *
+ * We provide this for platforms without a native implementation.
+ */
+export function sharedSecretFor(this: PrivateKey, peerKey: PublicKey): Uint8Array {
+    return getSharedSecret(this.privateBits, peerKey.publicBits);
+}

package/src/crypto/StandardCrypto.ts

@@ -14,6 +14,10 @@ import { Ccm } from "./aes/Ccm.js";
 import { Crypto, CRYPTO_SYMMETRIC_KEY_LENGTH, CryptoDsaEncoding } from "./Crypto.js";
 import { CryptoVerifyError, KeyInputError } from "./CryptoError.js";
 import { CurveType, Key, KeyType, PrivateKey, PublicKey } from "./Key.js";
+import { WebCrypto } from "./WebCrypto.js";
+
+// Ensure we don't reference global crypto accidentally
+declare const crypto: never;
 
 const SIGNATURE_ALGORITHM = <EcdsaParams>{
     name: "ECDSA",
@@ -21,6 +25,8 @@ const SIGNATURE_ALGORITHM = <EcdsaParams>{
     hash: { name: "SHA-256" },
 };
 
+const requiredCryptoMethods: Array<keyof WebCrypto> = ["getRandomValues"];
+
 const requiredSubtleMethods: Array<keyof SubtleCrypto> = [
     "digest",
     "deriveBits",
@@ -42,34 +48,32 @@ const requiredSubtleMethods: Array<keyof SubtleCrypto> = [
  */
 export class StandardCrypto extends Crypto {
     implementationName = "JS";
+    #crypto: WebCrypto;
     #subtle: SubtleCrypto;
 
-    constructor(subtle: SubtleCrypto = globalThis.crypto?.subtle) {
-        if (typeof subtle !== "object" || subtle === null) {
-            throw new ImplementationError(
-                "You cannot instantiate StandardCrypto in this runtime because crypto.subtle is not present",
-            );
-        }
+    constructor(crypto: WebCrypto = globalThis.crypto) {
+        const { subtle } = crypto;
 
-        const missingMethods = requiredSubtleMethods.filter(name => typeof subtle[name] !== "function");
-        if (missingMethods.length) {
-            throw new ImplementationError(
-                `SubtleCrypto implementation is missing required method${missingMethods.length === 1 ? "" : "s"} ${describeList("and", ...missingMethods)}`,
-            );
-        }
+        assertInterface("crypto", crypto, requiredCryptoMethods);
+        assertInterface("crypto.subtle", subtle, requiredSubtleMethods);
 
         super();
 
+        this.#crypto = crypto;
         this.#subtle = subtle;
     }
 
+    protected get subtle() {
+        return this.#subtle;
+    }
+
     static provider() {
         return new StandardCrypto();
     }
 
     randomBytes(length: number): Uint8Array {
         const result = new Uint8Array(length);
-        crypto.getRandomValues(result);
+        this.#crypto.getRandomValues(result);
         return result;
     }
 
@@ -91,7 +95,7 @@ export class StandardCrypto extends Crypto {
     }
 
     async createPbkdf2Key(secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number) {
-        const key = await this.#importKey("raw", secret, "PBKDF2", false, ["deriveBits"]);
+        const key = await this.importKey("raw", secret, "PBKDF2", false, ["deriveBits"]);
         const bits = await this.#subtle.deriveBits(
             {
                 name: "PBKDF2",
@@ -111,7 +115,7 @@ export class StandardCrypto extends Crypto {
         info: Uint8Array,
         length: number = CRYPTO_SYMMETRIC_KEY_LENGTH,
     ) {
-        const key = await this.#importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+        const key = await this.importKey("raw", secret, "HKDF", false, ["deriveBits"]);
         const bits = await this.#subtle.deriveBits(
             {
                 name: "HKDF",
@@ -126,7 +130,7 @@ export class StandardCrypto extends Crypto {
     }
 
     async signHmac(secret: Uint8Array, data: Uint8Array) {
-        const key = await this.#importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const key = await this.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
         return new Uint8Array(await this.#subtle.sign("HMAC", key, data));
     }
 
@@ -147,7 +151,7 @@ export class StandardCrypto extends Crypto {
             key_ops: ["sign"],
         };
 
-        const subtleKey = await this.#importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["sign"]);
+        const subtleKey = await this.importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["sign"]);
 
         const ieeeP1363 = await this.#subtle.sign(SIGNATURE_ALGORITHM, subtleKey, data);
 
@@ -164,7 +168,7 @@ export class StandardCrypto extends Crypto {
     async verifyEcdsa(key: JsonWebKey, data: Uint8Array, signature: Uint8Array, dsaEncoding?: CryptoDsaEncoding) {
         const { crv, kty, x, y } = key;
         key = { crv, kty, x, y };
-        const subtleKey = await this.#importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["verify"]);
+        const subtleKey = await this.importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["verify"]);
 
         if (dsaEncoding === "der") {
             try {
@@ -189,6 +193,19 @@ export class StandardCrypto extends Crypto {
     }
 
     async createKeyPair() {
+        const key = await this.generateJwk();
+
+        // Extract only private and public fields; we do not want key_ops
+        return Key({
+            kty: KeyType.EC,
+            crv: CurveType.p256,
+            d: key.d,
+            x: key.x,
+            y: key.y,
+        }) as PrivateKey;
+    }
+
+    protected async generateJwk() {
         const subtleKey = await this.#subtle.generateKey(
             {
                 // We must specify either ECDH or ECDSA to get an EC key but we may use the key for either (but not for
@@ -203,20 +220,11 @@ export class StandardCrypto extends Crypto {
         );
 
         // Do not export as JWK because we do not want to inherit the algorithm and key_ops
-        const key = await this.#subtle.exportKey("jwk", subtleKey.privateKey);
-
-        // Extract only private and public fields; we do not want key_ops
-        return Key({
-            kty: KeyType.EC,
-            crv: CurveType.p256,
-            d: key.d,
-            x: key.x,
-            y: key.y,
-        }) as PrivateKey;
+        return await this.#subtle.exportKey("jwk", subtleKey.privateKey);
     }
 
     async generateDhSecret(key: PrivateKey, peerKey: PublicKey) {
-        const subtleKey = await this.#importKey(
+        const subtleKey = await this.importKey(
             "jwk",
             key,
             {
@@ -227,7 +235,7 @@ export class StandardCrypto extends Crypto {
             ["deriveBits"],
         );
 
-        const subtlePeerKey = await this.#importKey(
+        const subtlePeerKey = await this.importKey(
             "jwk",
             peerKey,
             {
@@ -250,32 +258,38 @@ export class StandardCrypto extends Crypto {
         return new Uint8Array(secret);
     }
 
-    #importKey(
-        format: "jwk",
-        keyData: JsonWebKey,
+    protected async importKey(
+        format: KeyFormat,
+        keyData: JsonWebKey | BufferSource,
         algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm,
         extractable: boolean,
         keyUsages: ReadonlyArray<KeyUsage>,
-    ): Promise<CryptoKey>;
-    #importKey(
-        format: Exclude<KeyFormat, "jwk">,
-        keyData: BufferSource,
-        algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm,
-        extractable: boolean,
-        keyUsages: KeyUsage[],
-    ): Promise<CryptoKey>;
-
-    async #importKey(...params: unknown[]) {
+    ) {
         try {
-            return await this.#subtle.importKey(...(params as Parameters<SubtleCrypto["importKey"]>));
+            return await this.#subtle.importKey(format as any, keyData as any, algorithm, extractable, keyUsages);
         } catch (cause) {
             throw new KeyInputError("Invalid key", { cause });
         }
     }
 }
 
+function assertInterface<T extends {}>(name: string, object: T, requiredMethods: (keyof T & string)[]) {
+    if (typeof object !== "object" || object === null) {
+        throw new ImplementationError(
+            `The ${name} implementation passed to StandardCrypto is invalid (received ${typeof object})`,
+        );
+    }
+
+    const missingMethods = requiredMethods.filter(name => typeof object[name] !== "function");
+    if (missingMethods.length) {
+        throw new ImplementationError(
+            `The ${name} implementation passed to StandardCrypto is missing required method${missingMethods.length === 1 ? "" : "s"} ${describeList("and", ...missingMethods)}`,
+        );
+    }
+}
+
 // If available, unconditionally add to Environment as it has not been exported yet so there can be no other
 // implementation present
 if ("crypto" in globalThis && globalThis.crypto?.subtle) {
-    Environment.default.set(Crypto, new StandardCrypto(globalThis.crypto.subtle));
+    Environment.default.set(Crypto, new StandardCrypto());
 }

package/src/crypto/WebCrypto.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Our "Crypto" interface masks the standard web crypto "Crypto" type provided by typescript.  Make an alias to work
+ * around this.
+ */
+export interface WebCrypto extends Crypto {}

package/src/crypto/index.ts

@@ -11,3 +11,4 @@ export * from "./Key.js";
 export * from "./MockCrypto.js";
 export * from "./Spake2p.js";
 export * from "./StandardCrypto.js";
+export * from "./WebCrypto.js";

package/src/net/RetrySchedule.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Crypto } from "#crypto/Crypto.js";
+
+/**
+ * An iterable of retry values based on a scheduling configuration.
+ */
+export class RetrySchedule {
+    #crypto: Crypto;
+    readonly config: RetrySchedule.Configuration;
+
+    constructor(crypto: Crypto, config: RetrySchedule.Configuration) {
+        this.#crypto = crypto;
+        this.config = config;
+    }
+
+    /**
+     * Yields intervals.
+     *
+     * Will yield indefinitely until canceled unless {@link config} specifies a timeout.
+     */
+    *[Symbol.iterator]() {
+        const {
+            timeout,
+            maximumInterval,
+            maximumCount,
+            jitterFactor = 0,
+            initialInterval = 1000,
+            backoffFactor = 2,
+        } = this.config;
+
+        let count = 0;
+        let baseInterval = initialInterval;
+        let timeSoFar = 0;
+
+        while ((timeout === undefined || timeSoFar < timeout) && (maximumCount === undefined || maximumCount > count)) {
+            count++;
+            const maxJitter = jitterFactor * baseInterval;
+            const jitter = Math.floor((maxJitter * this.#crypto.randomUint32) / Math.pow(2, 32));
+            let interval = baseInterval + jitter;
+
+            if (timeout !== undefined && timeSoFar + interval > timeout) {
+                interval = timeout - timeSoFar;
+            }
+            if (maximumInterval !== undefined && interval > maximumInterval) {
+                interval = maximumInterval;
+            }
+
+            yield interval;
+            timeSoFar += interval;
+
+            baseInterval *= backoffFactor;
+        }
+    }
+}
+
+export namespace RetrySchedule {
+    /**
+     * Configuration parameters for retry schedule.
+     *
+     * All intervals are in milliseconds.
+     */
+    export interface Configuration {
+        /**
+         * Overall timeout in seconds.
+         *
+         * Leave undefined to allow indefinite transmission.
+         */
+        readonly timeout?: number;
+
+        /**
+         * Maximum number of occurrences (including first).
+         *
+         * Set to zero to disable transmission completely; leave undefined to allow any number of transmissions.
+         */
+        readonly maximumCount?: number;
+
+        /**
+         * Interval between first request and final interval.
+         *
+         * Defaults to 1000 ms.
+         */
+        readonly initialInterval?: number;
+
+        /**
+         * Multiplier for subsequent retries.
+         *
+         * Defaults to 2.
+         */
+        readonly backoffFactor?: number;
+
+        /**
+         * Maximum interval between retries (excluding jitter).
+         *
+         * Leave undefined for interval to allow interval to grow continuously.
+         */
+        readonly maximumInterval?: number;
+
+        /**
+         * Multiplier for retry jitter.
+         *
+         * Leave undefined to disable jitter.
+         */
+        readonly jitterFactor?: number;
+    }
+
+    /**
+     * Create a full configuration with defaults.
+     */
+    export function Configuration(defaults: Configuration, config?: Configuration) {
+        return {
+            ...defaults,
+            ...config,
+        };
+    }
+}

package/src/net/UdpMulticastServer.ts

@@ -76,15 +76,19 @@ export class UdpMulticastServer {
     );
 
     private constructor(
-        private readonly network: Network,
+        readonly network: Network,
         private readonly broadcastAddressIpv4: string | undefined,
         private readonly broadcastAddressIpv6: string,
         private readonly broadcastPort: number,
         private readonly serverIpv4: UdpChannel | undefined,
         private readonly serverIpv6: UdpChannel,
-        private readonly netInterface: string | undefined,
+        readonly netInterface: string | undefined,
     ) {}
 
+    get supportsIpv4() {
+        return this.serverIpv4 !== undefined;
+    }
+
     onMessage(listener: (message: Uint8Array, peerAddress: string, netInterface: string) => void) {
         this.serverIpv4?.onData((netInterface, peerAddress, _port, message) => {
             if (netInterface === undefined) {

package/src/net/index.ts

@@ -8,6 +8,7 @@ export * from "./Channel.js";
 export * from "./mock/index.js";
 export * from "./NetInterface.js";
 export * from "./Network.js";
+export * from "./RetrySchedule.js";
 export * from "./ServerAddress.js";
 export * from "./TransportInterface.js";
 export * from "./UdpChannel.js";

package/src/time/Time.ts

@@ -32,7 +32,7 @@ export class Time {
     static readonly now = (): Date => Time.get().now();
 
     nowMs() {
-        return this.now().getTime();
+        return Date.now();
     }
     static readonly nowMs = (): number => Time.get().nowMs();
 

package/src/util/Bytes.ts

@@ -56,6 +56,18 @@ export namespace Bytes {
         return array1.every((value, index) => array2[index] === value);
     }
 
+    export function of(source: BufferSource) {
+        if (source instanceof Uint8Array) {
+            return source;
+        }
+
+        if (ArrayBuffer.isView(source)) {
+            return new Uint8Array(source.buffer, source.byteLength, source.byteOffset);
+        }
+
+        return new Uint8Array(source);
+    }
+
     export function fromHex(hexString: string) {
         if (hexString.length === 0) return new Uint8Array(0);
         if (hexString.length % 2 !== 0) throw new UnexpectedDataError("Hex string should have an even length.");

package/src/util/Cache.ts

@@ -32,7 +32,7 @@ class GenericCache<T> {
         return Array.from(this.knownKeys.values());
     }
 
-    private async deleteEntry(key: string) {
+    async delete(key: string) {
         const value = this.values.get(key);
         if (this.expireCallback !== undefined && value !== undefined) {
             await this.expireCallback(key, value);
@@ -43,7 +43,7 @@ class GenericCache<T> {
 
     async clear() {
         for (const key of this.values.keys()) {
-            await this.deleteEntry(key);
+            await this.delete(key);
         }
         this.values.clear();
         this.timestamps.clear();
@@ -59,7 +59,7 @@ class GenericCache<T> {
         const now = Time.nowMs();
         for (const [key, timestamp] of this.timestamps.entries()) {
             if (now - timestamp < this.expirationMs) continue;
-            await this.deleteEntry(key);
+            await this.delete(key);
         }
     }
 }

package/src/util/Cancelable.ts

@@ -116,7 +116,7 @@ export class CancelablePromise<T = void> implements Promise<T>, Cancelable {
     catch<TResult = never>(
         onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
     ): CancelablePromise<T | TResult> {
-        return this.then(onrejected);
+        return this.then(undefined, onrejected);
     }
 
     finally(onfinally?: (() => void) | null): CancelablePromise<T> {

package/src/util/Multiplex.ts

@@ -4,11 +4,66 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Logger } from "#log/Logger.js";
+import { MatterAggregateError } from "#MatterError.js";
+import { MaybePromise } from "./Promises.js";
+import { BasicSet } from "./Set.js";
+
+const logger = Logger.get("Multiplex");
+
 /**
  * A "multiplex" tracks an extensible set of promises.
  */
 export interface Multiplex {
-    add(worker: Promise<unknown>): void;
+    add(worker: Promise<unknown>, description?: string): void;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }
+
+interface WorkerEntry {
+    done: Promise<unknown>;
+    description?: string;
+}
+
+/**
+ * A basic multiplex that tracks all promises given to it.
+ */
+export class BasicMultiplex implements PromiseLike<void> {
+    #workers = new BasicSet<WorkerEntry>();
+
+    add(worker: MaybePromise<unknown>, description?: string) {
+        if (!MaybePromise.is(worker)) {
+            return;
+        }
+
+        const entry = {
+            done: Promise.resolve(worker)
+                .catch(e => {
+                    let message = "Unhandled error";
+                    if (description) {
+                        message = `${message} in ${description}`;
+                    }
+                    logger.error(message, e);
+                })
+                .finally(() => this.#workers.delete(entry)),
+            description,
+        };
+
+        this.#workers.add(entry);
+    }
+
+    async close() {
+        while (this.#workers.size) {
+            await MatterAggregateError.allSettled([...this.#workers].map(entry => entry.done));
+        }
+    }
+
+    then<TResult1 = void, TResult2 = never>(
+        onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): PromiseLike<TResult1 | TResult2> {
+        return this.close().then(onfulfilled, onrejected);
+    }
+
+    [Symbol.asyncDispose] = this.close.bind(this);
+}

package/src/util/index.ts

@@ -21,6 +21,7 @@ export * from "./GeneratedClass.js";
 export * from "./Ip.js";
 export * from "./Lifecycle.js";
 export * from "./Map.js";
+export * from "./Multiplex.js";
 export * from "./Mutex.js";
 export * from "./NamedHandler.js";
 export * from "./Number.js";