@matter/general 0.16.0-alpha.0-20250820-24939dd26 → 0.16.0-alpha.0-20250822-523588650

package/src/crypto/NodeJsStyleCrypto.ts

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "#util/Bytes.js";
+import { asError } from "#util/Error.js";
+import { Identity } from "#util/Type.js";
+import {
+    Crypto,
+    CRYPTO_AUTH_TAG_LENGTH,
+    CRYPTO_EC_CURVE,
+    CRYPTO_EC_KEY_BYTES,
+    CRYPTO_ENCRYPT_ALGORITHM,
+    CRYPTO_HASH_ALGORITHM,
+    CRYPTO_SYMMETRIC_KEY_LENGTH,
+    CryptoDsaEncoding,
+} from "./Crypto.js";
+import { CryptoDecryptError, CryptoVerifyError } from "./CryptoError.js";
+import { PrivateKey, PublicKey } from "./Key.js";
+
+// Note that this is a type-only import, not a runtime dependency.
+import type * as NodeJsCryptoApi from "node:crypto";
+
+// Ensure we don't reference global crypto accidentally
+declare const crypto: never;
+
+/**
+ * A crypto API implemented in the style of Node.js.
+ */
+export interface NodeJsCryptoApiLike extends Identity<typeof NodeJsCryptoApi> {}
+
+/**
+ * A crypto implementation that uses the Node.js crypto API.
+ *
+ * It is Node.js "style" because there are many packages that emulate the Node.js API.  As of now (mid-2025) these are
+ * sometimes more mature than the available Web Crypto implementation.
+ *
+ * This module does not import the Node.js crypto implementation directly.  You must provide a crypto implementation to
+ * use it.
+ */
+export class NodeJsStyleCrypto extends Crypto {
+    implementationName = "Node.js";
+
+    #crypto: NodeJsCryptoApiLike;
+
+    constructor(crypto: NodeJsCryptoApiLike) {
+        super();
+
+        this.#crypto = crypto;
+    }
+
+    encrypt(key: Bytes, data: Bytes, nonce: Bytes, aad?: Bytes): Bytes {
+        const cipher = this.#crypto.createCipheriv(CRYPTO_ENCRYPT_ALGORITHM, Bytes.of(key), Bytes.of(nonce), {
+            authTagLength: CRYPTO_AUTH_TAG_LENGTH,
+        });
+        if (aad !== undefined) {
+            cipher.setAAD(Bytes.of(aad), { plaintextLength: data.byteLength });
+        }
+        const encrypted = cipher.update(Bytes.of(data));
+        cipher.final();
+        return Bytes.concat(Bytes.of(encrypted), Bytes.of(cipher.getAuthTag()));
+    }
+
+    decrypt(key: Bytes, encrypted: Bytes, nonce: Bytes, aad?: Bytes): Bytes {
+        const cipher = this.#crypto.createDecipheriv(CRYPTO_ENCRYPT_ALGORITHM, Bytes.of(key), Bytes.of(nonce), {
+            authTagLength: CRYPTO_AUTH_TAG_LENGTH,
+        });
+        const data = Bytes.of(encrypted);
+        const plaintextLength = data.length - CRYPTO_AUTH_TAG_LENGTH;
+        if (aad !== undefined) {
+            cipher.setAAD(Bytes.of(aad), { plaintextLength });
+        }
+        cipher.setAuthTag(data.slice(plaintextLength));
+        const result = cipher.update(data.slice(0, plaintextLength));
+        try {
+            cipher.final();
+        } catch (e) {
+            throw new CryptoDecryptError(`${CRYPTO_ENCRYPT_ALGORITHM} decryption failed: ${asError(e).message}`);
+        }
+        return Bytes.of(result);
+    }
+
+    randomBytes(length: number): Bytes {
+        return Bytes.of(this.#crypto.randomBytes(length));
+    }
+
+    ecdhGeneratePublicKey(): { publicKey: Bytes; ecdh: any } {
+        const ecdh = this.#crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.generateKeys();
+        return { publicKey: Bytes.of(ecdh.getPublicKey()), ecdh: ecdh };
+    }
+
+    ecdhGeneratePublicKeyAndSecret(peerPublicKey: Bytes): {
+        publicKey: Bytes;
+        sharedSecret: Bytes;
+    } {
+        const ecdh = this.#crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.generateKeys();
+        return {
+            publicKey: Bytes.of(ecdh.getPublicKey()),
+            sharedSecret: Bytes.of(ecdh.computeSecret(Bytes.of(peerPublicKey))),
+        };
+    }
+
+    computeSha256(data: Bytes | Bytes[]): Bytes {
+        const hasher = this.#crypto.createHash(CRYPTO_HASH_ALGORITHM);
+        if (Array.isArray(data)) {
+            data.forEach(chunk => hasher.update(Bytes.of(chunk)));
+        } else {
+            hasher.update(Bytes.of(data));
+        }
+        return Bytes.of(hasher.digest());
+    }
+
+    createPbkdf2Key(secret: Bytes, salt: Bytes, iteration: number, keyLength: number): Promise<Bytes> {
+        return new Promise<Bytes>((resolver, rejecter) => {
+            this.#crypto.pbkdf2(
+                Bytes.of(secret),
+                Bytes.of(salt),
+                iteration,
+                keyLength,
+                CRYPTO_HASH_ALGORITHM,
+                (error, key) => {
+                    if (error !== null) rejecter(error);
+                    resolver(Bytes.of(key));
+                },
+            );
+        });
+    }
+
+    createHkdfKey(
+        secret: Bytes,
+        salt: Bytes,
+        info: Bytes,
+        length: number = CRYPTO_SYMMETRIC_KEY_LENGTH,
+    ): Promise<Bytes> {
+        return new Promise<Bytes>((resolver, rejecter) => {
+            this.#crypto.hkdf(
+                CRYPTO_HASH_ALGORITHM,
+                Bytes.of(secret),
+                Bytes.of(salt),
+                Bytes.of(info),
+                length,
+                (error, key) => {
+                    if (error !== null) rejecter(error);
+                    resolver(Bytes.of(key));
+                },
+            );
+        });
+    }
+
+    signHmac(key: Bytes, data: Bytes): Bytes {
+        const hmac = this.#crypto.createHmac(CRYPTO_HASH_ALGORITHM, Bytes.of(key));
+        hmac.update(Bytes.of(data));
+        return Bytes.of(hmac.digest());
+    }
+
+    signEcdsa(privateKey: JsonWebKey, data: Bytes | Bytes[], dsaEncoding: CryptoDsaEncoding = "ieee-p1363"): Bytes {
+        const signer = this.#crypto.createSign(CRYPTO_HASH_ALGORITHM);
+        if (Array.isArray(data)) {
+            data.forEach(chunk => signer.update(Bytes.of(chunk)));
+        } else {
+            signer.update(Bytes.of(data));
+        }
+        return Bytes.of(
+            signer.sign({
+                key: privateKey as any,
+                format: "jwk",
+                type: "pkcs8",
+                dsaEncoding,
+            }),
+        );
+    }
+
+    verifyEcdsa(publicKey: JsonWebKey, data: Bytes, signature: Bytes, dsaEncoding: CryptoDsaEncoding = "ieee-p1363") {
+        const verifier = this.#crypto.createVerify(CRYPTO_HASH_ALGORITHM);
+        verifier.update(Bytes.of(data));
+        const success = verifier.verify(
+            {
+                key: publicKey as any,
+                format: "jwk",
+                type: "spki",
+                dsaEncoding,
+            },
+            Bytes.of(signature),
+        );
+        if (!success) throw new CryptoVerifyError("Signature verification failed");
+    }
+
+    createKeyPair() {
+        // Note that we this key may be used for DH or DSA but we use an ECDH to generate
+        const ecdh = this.#crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.generateKeys();
+
+        // The key exported from Node doesn't include most-significant bytes that are 0.  This doesn't affect how we
+        // currently use keys but it's a little weird so 0 pad to avoid future confusion
+        const privateKey = new Uint8Array(CRYPTO_EC_KEY_BYTES);
+        const nodePrivateKey = ecdh.getPrivateKey();
+        privateKey.set(nodePrivateKey, CRYPTO_EC_KEY_BYTES - nodePrivateKey.length);
+
+        return PrivateKey(privateKey, { publicKey: Bytes.of(ecdh.getPublicKey()) });
+    }
+
+    generateDhSecret(key: PrivateKey, peerKey: PublicKey): Bytes {
+        const ecdh = this.#crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.setPrivateKey(Bytes.of(key.privateBits));
+
+        return Bytes.of(ecdh.computeSecret(Bytes.of(peerKey.publicBits)));
+    }
+}

package/src/crypto/StandardCrypto.ts

@@ -9,6 +9,7 @@ import { DerBigUint, DerCodec, DerError } from "#codec/DerCodec.js";
 import { Environment } from "#environment/Environment.js";
 import { ImplementationError } from "#MatterError.js";
 import { Bytes } from "#util/Bytes.js";
+import { MaybePromise } from "#util/Promises.js";
 import { describeList } from "#util/String.js";
 import { Ccm } from "./aes/Ccm.js";
 import { Crypto, CRYPTO_SYMMETRIC_KEY_LENGTH, CryptoDsaEncoding } from "./Crypto.js";
@@ -135,9 +136,10 @@ export class StandardCrypto extends Crypto {
         );
     }
 
-    async signHmac(secret: Bytes, data: Bytes): Promise<Bytes> {
-        const key = await this.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-        return this.#subtle.sign("HMAC", key, Bytes.exclusive(data));
+    signHmac(secret: Bytes, data: Bytes): MaybePromise<Bytes> {
+        return this.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]).then(key =>
+            this.#subtle.sign("HMAC", key, Bytes.exclusive(data)),
+        );
     }
 
     async signEcdsa(key: JsonWebKey, data: Bytes | Bytes[], dsaEncoding?: CryptoDsaEncoding) {

package/src/crypto/index.ts

@@ -9,6 +9,7 @@ export * from "./CryptoConstants.js";
 export * from "./CryptoError.js";
 export * from "./Key.js";
 export * from "./MockCrypto.js";
+export * from "./NodeJsStyleCrypto.js";
 export * from "./Spake2p.js";
 export * from "./StandardCrypto.js";
 export * from "./WebCrypto.js";

package/src/environment/Environment.ts

@@ -32,7 +32,7 @@ const logger = Logger.get("Environment");
  * TODO - could remove global singletons by moving here
  */
 export class Environment {
-    #services?: Map<abstract new (...args: any[]) => any, Environmental.Service>;
+    #services?: Map<abstract new (...args: any[]) => any, Environmental.Service | null>;
     #name: string;
     #parent?: Environment;
     #added = Observable<[type: abstract new (...args: any[]) => {}, instance: {}]>();
@@ -48,7 +48,13 @@ export class Environment {
      * Determine if an environmental service is available.
      */
     has(type: abstract new (...args: any[]) => any): boolean {
-        return this.#services?.get(type) !== undefined || (this.#parent?.has(type) ?? false);
+        const mine = this.#services?.get(type);
+
+        if (mine === null) {
+            return false;
+        }
+
+        return mine !== undefined || (this.#parent?.has(type) ?? false);
     }
 
     /**
@@ -57,13 +63,15 @@ export class Environment {
     get<T extends object>(type: abstract new (...args: any[]) => T): T {
         let instance = this.#services?.get(type) ?? this.#parent?.maybeGet(type);
 
-        if (instance) {
+        if (instance !== undefined && instance !== null) {
             return instance as T;
         }
 
-        if ((type as Environmental.Factory<T>)[Environmental.create]) {
-            this.set(type, (instance = (type as any)[Environmental.create](this)));
-            return instance as T;
+        if (instance !== null) {
+            if ((type as Environmental.Factory<T>)[Environmental.create]) {
+                this.set(type, (instance = (type as any)[Environmental.create](this)));
+                return instance as T;
+            }
         }
 
         throw new UnsupportedDependencyError(`Required dependency ${type.name}`, "is not available");
@@ -99,6 +107,19 @@ export class Environment {
         }
     }
 
+    /**
+     * Prevent this environment from automatically instantiating or retrieving a service from parent environment.
+     *
+     * @param type the class of the service to block
+     */
+    block(type: abstract new (...args: any[]) => any) {
+        if (this.has(type)) {
+            this.delete(type);
+        }
+
+        this.#services?.set(type, null);
+    }
+
     /**
      * Remove and close an environmental service.
      */