@matter/nodejs 0.11.0-alpha.0-20241005-e3e4e4a7a

package/package.json

@@ -0,0 +1,114 @@
+{
+    "name": "@matter/nodejs",
+    "version": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+    "description": "Node.js platform support for matter.js",
+    "keywords": [
+        "iot",
+        "home automation",
+        "matter",
+        "smart device"
+    ],
+    "license": "Apache-2.0",
+    "author": "matter.js authors",
+    "contributors": [
+        "Martin Turon <mturon@google.com>",
+        "Marco Fucci di Napoli <mfucci@gmail.com>",
+        "Ingo Fischer <github@fischer-ka.de>",
+        "Greg Lauckhart <greg@lauckhart.com>"
+    ],
+    "bugs": {
+        "url": "https://github.com/project-chip/matter.js/issues"
+    },
+    "homepage": "https://github.com/project-chip/matter.js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/project-chip/matter.js.git"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "scripts": {
+        "clean": "matter-build clean",
+        "build": "matter-build",
+        "build-clean": "matter-build --clean",
+        "test": "matter-test",
+        "coverage": "c8 matter-test esm",
+        "embed-examples": "embedme **/README.md"
+    },
+    "imports": {
+        "#general": "@matter/general",
+        "#types": "@matter/types",
+        "#clusters/*": "@matter/types/clusters/*",
+        "#node": "@matter/node",
+        "#protocol": "@matter/protocol",
+        "#*": "./src/*"
+    },
+    "dependencies": {
+        "@matter/general": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@matter/types": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@matter/protocol": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@matter/node": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@project-chip/matter.js": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "node-localstorage": "^3.0.5"
+    },
+    "devDependencies": {
+        "@matter/model": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@matter/protocol": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@matter/tools": "0.11.0-alpha.0-20241005-e3e4e4a7a",
+        "@types/bytebuffer": "^5.0.49",
+        "@types/node-localstorage": "^1.3.3"
+    },
+    "files": [
+        "dist/**/*",
+        "src/**/*",
+        "LICENSE",
+        "README.md"
+    ],
+    "type": "module",
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/esm/index.d.ts",
+                "default": "./dist/esm/index.js"
+            },
+            "require": {
+                "types": "./dist/cjs/index.d.ts",
+                "default": "./dist/cjs/index.js"
+            }
+        }
+    },
+    "types": "dist/esm/index.d.ts",
+    "typesVersions": {
+        "*": {
+            "interaction": [
+                "/dist/cjs/protocol/interaction/export.d.ts"
+            ],
+            "model": [
+                "/dist/cjs/model/index.d.ts"
+            ],
+            "securechannel": [
+                "/dist/cjs/protocol/securechannel/export.d.ts"
+            ],
+            "behaviors/*": [
+                "/dist/cjs/behavior/definitions/*/export.d.ts"
+            ],
+            "devices/*": [
+                "/dist/cjs/endpoint/definitions/device/*.d.ts"
+            ],
+            "endpoints/*": [
+                "/dist/cjs/endpoint/definitions/system/*.d.ts"
+            ],
+            ".": [
+                "/dist/cjs/export.d.ts"
+            ],
+            "*": [
+                "/dist/cjs/*/export.d.ts"
+            ]
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/behavior/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./register.js";

package/src/behavior/instrumentation.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Instrumentation, Val } from "#node";
+import { inspect } from "util";
+
+/**
+ * Node's default console formatting makes it difficult to view the value of managed collections.  This function
+ * instruments values to make inspection work more naturally.
+ */
+export function installInspectionInstrumentation() {
+    Instrumentation.instrumentStruct = constructor => {
+        constructor.prototype[inspect.custom] = function (this: Val.Struct) {
+            return { ...this };
+        };
+
+        return constructor;
+    };
+
+    Instrumentation.instrumentList = (factory): Instrumentation.ListFactory => {
+        return (handlers, target) => {
+            (target as any)[inspect.custom] = function (this: Val.List) {
+                return [...this];
+            };
+
+            return factory(handlers, target);
+        };
+    };
+}

package/src/behavior/register.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { installInspectionInstrumentation } from "./instrumentation.js";
+
+installInspectionInstrumentation();

package/src/crypto/NodeJsCrypto.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    CRYPTO_AUTH_TAG_LENGTH,
+    CRYPTO_EC_CURVE,
+    CRYPTO_EC_KEY_BYTES,
+    CRYPTO_ENCRYPT_ALGORITHM,
+    CRYPTO_HASH_ALGORITHM,
+    CRYPTO_SYMMETRIC_KEY_LENGTH,
+    Crypto,
+    CryptoDsaEncoding,
+    CryptoVerifyError,
+    PrivateKey,
+} from "#general";
+import * as crypto from "crypto";
+
+export class NodeJsCrypto extends Crypto {
+    encrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array {
+        const cipher = crypto.createCipheriv(CRYPTO_ENCRYPT_ALGORITHM, key, nonce, {
+            authTagLength: CRYPTO_AUTH_TAG_LENGTH,
+        });
+        if (aad !== undefined) {
+            cipher.setAAD(aad, { plaintextLength: data.length });
+        }
+        const encrypted = cipher.update(data);
+        cipher.final();
+        return Bytes.concat(encrypted, cipher.getAuthTag());
+    }
+
+    decrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array {
+        const cipher = crypto.createDecipheriv(CRYPTO_ENCRYPT_ALGORITHM, key, nonce, {
+            authTagLength: CRYPTO_AUTH_TAG_LENGTH,
+        });
+        const plaintextLength = data.length - CRYPTO_AUTH_TAG_LENGTH;
+        if (aad !== undefined) {
+            cipher.setAAD(aad, { plaintextLength });
+        }
+        cipher.setAuthTag(data.slice(plaintextLength));
+        const result = cipher.update(data.slice(0, plaintextLength));
+        cipher.final();
+        return new Uint8Array(result);
+    }
+
+    getRandomData(length: number): Uint8Array {
+        return new Uint8Array(crypto.randomBytes(length));
+    }
+
+    ecdhGeneratePublicKey(): { publicKey: Uint8Array; ecdh: any } {
+        const ecdh = crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.generateKeys();
+        return { publicKey: new Uint8Array(ecdh.getPublicKey()), ecdh: ecdh };
+    }
+
+    ecdhGeneratePublicKeyAndSecret(peerPublicKey: Uint8Array): { publicKey: Uint8Array; sharedSecret: Uint8Array } {
+        const ecdh = crypto.createECDH(CRYPTO_EC_CURVE);
+        ecdh.generateKeys();
+        return {
+            publicKey: new Uint8Array(ecdh.getPublicKey()),
+            sharedSecret: new Uint8Array(ecdh.computeSecret(peerPublicKey)),
+        };
+    }
+
+    ecdhGenerateSecret(peerPublicKey: Uint8Array, ecdh: crypto.ECDH): Uint8Array {
+        return new Uint8Array(ecdh.computeSecret(peerPublicKey));
+    }
+
+    hash(data: Uint8Array | Uint8Array[]): Uint8Array {
+        const hasher = crypto.createHash(CRYPTO_HASH_ALGORITHM);
+        if (Array.isArray(data)) {
+            data.forEach(chunk => hasher.update(chunk));
+        } else {
+            hasher.update(data);
+        }
+        return new Uint8Array(hasher.digest());
+    }
+
+    pbkdf2(secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number): Promise<Uint8Array> {
+        return new Promise<Uint8Array>((resolver, rejecter) => {
+            crypto.pbkdf2(secret, salt, iteration, keyLength, CRYPTO_HASH_ALGORITHM, (error, key) => {
+                if (error !== null) rejecter(error);
+                resolver(new Uint8Array(key));
+            });
+        });
+    }
+
+    hkdf(
+        secret: Uint8Array,
+        salt: Uint8Array,
+        info: Uint8Array,
+        length: number = CRYPTO_SYMMETRIC_KEY_LENGTH,
+    ): Promise<Uint8Array> {
+        return new Promise<Uint8Array>((resolver, rejecter) => {
+            crypto.hkdf(CRYPTO_HASH_ALGORITHM, secret, salt, info, length, (error, key) => {
+                if (error !== null) rejecter(error);
+                resolver(new Uint8Array(key));
+            });
+        });
+    }
+
+    hmac(key: Uint8Array, data: Uint8Array): Uint8Array {
+        const hmac = crypto.createHmac(CRYPTO_HASH_ALGORITHM, key);
+        hmac.update(data);
+        return new Uint8Array(hmac.digest());
+    }
+
+    sign(
+        privateKey: JsonWebKey,
+        data: Uint8Array | Uint8Array[],
+        dsaEncoding: CryptoDsaEncoding = "ieee-p1363",
+    ): Uint8Array {
+        const signer = crypto.createSign(CRYPTO_HASH_ALGORITHM);
+        if (Array.isArray(data)) {
+            data.forEach(chunk => signer.update(chunk));
+        } else {
+            signer.update(data);
+        }
+        return new Uint8Array(
+            signer.sign({
+                key: privateKey as any,
+                format: "jwk",
+                type: "pkcs8",
+                dsaEncoding,
+            }),
+        );
+    }
+
+    verify(
+        publicKey: JsonWebKey,
+        data: Uint8Array,
+        signature: Uint8Array,
+        dsaEncoding: CryptoDsaEncoding = "ieee-p1363",
+    ) {
+        const verifier = crypto.createVerify(CRYPTO_HASH_ALGORITHM);
+        verifier.update(data);
+        const success = verifier.verify(
+            {
+                key: publicKey as any,
+                format: "jwk",
+                type: "spki",
+                dsaEncoding,
+            },
+            signature,
+        );
+        if (!success) throw new CryptoVerifyError("Signature verification failed");
+    }
+
+    createKeyPair() {
+        const ecdh = 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: ecdh.getPublicKey() });
+    }
+}

package/src/crypto/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./register.js";
+export * from "./NodeJsCrypto.js";

package/src/crypto/register.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Crypto, NoProviderError, singleton } from "#general";
+import { NodeJsCrypto } from "./NodeJsCrypto.js";
+
+// Check if Crypto singleton is already registered
+let needCrypto = true;
+try {
+    const crypto = Crypto.get();
+
+    if ((crypto as { mock?: boolean }).mock !== true) {
+        needCrypto = false;
+    }
+} catch (error) {
+    NoProviderError.accept(error);
+}
+
+// Register if necessary
+if (needCrypto) {
+    Crypto.get = singleton(() => new NodeJsCrypto());
+}

package/src/environment/NodeJsActionTracer.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment, MaybePromise, serialize } from "#general";
+import { ActionTracer } from "#node";
+import { FileHandle, open } from "fs/promises";
+import { resolve } from "path";
+
+export class NodeJsActionTracer extends ActionTracer {
+    #path: string;
+    #output?: FileHandle;
+    #write?: MaybePromise<void>;
+
+    constructor(path: string) {
+        super();
+
+        this.#path = path;
+    }
+
+    static configure(env: Environment) {
+        env.vars.use(() => {
+            if (env.has(ActionTracer)) {
+                env.delete(env.get(ActionTracer).constructor as new () => ActionTracer);
+            }
+
+            if (!env.vars.boolean("trace.enable")) {
+                return;
+            }
+
+            const path = resolve(env.vars.get("path.root", "."), env.vars.get("trace.path", "trace.jsonl"));
+
+            const tracer = new NodeJsActionTracer(path);
+            env.set(ActionTracer, tracer);
+            env.runtime.add(tracer);
+        });
+    }
+
+    [Symbol.asyncDispose]() {
+        MaybePromise.then(this.#write, () => this.#output?.close());
+    }
+
+    override record(action: ActionTracer.Action) {
+        const raw = {
+            ...action,
+            path: action.path?.toString(false),
+            mutations: action.mutations
+                ? action.mutations.map(m => ({ ...m, path: m.path.toString(false) }))
+                : undefined,
+        };
+        this.#write = MaybePromise.then(this.#write, () => this.#record(raw));
+    }
+
+    async #record(action: object) {
+        if (this.#output === undefined) {
+            this.#output = await open(this.#path, "w");
+        }
+        await this.#output.write(JSON.stringify(action, replacer));
+        await this.#output.write("\n");
+    }
+}
+
+function replacer(_key: string, value: any) {
+    if (typeof value === "bigint" || ArrayBuffer.isView(value)) {
+        return serialize(value);
+    }
+    return value;
+}

package/src/environment/NodeJsEnvironment.ts

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Environment,
+    ImplementationError,
+    LogFormat,
+    Logger,
+    Network,
+    StorageService,
+    VariableService,
+} from "#general";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { NodeJsNetwork } from "../net/NodeJsNetwork.js";
+import { StorageBackendDisk } from "../storage/StorageBackendDisk.js";
+import { NodeJsActionTracer } from "./NodeJsActionTracer.js";
+import { ProcessManager } from "./ProcessManager.js";
+
+/**
+ * This is the default environment implementation for Node.js:
+ *
+ *   - Sets variables using rudimentary command line, environment and configuration file parsers.
+ *
+ *   - Processes UNIX-style signals and sets process exit codes via {@link ProcessManager}
+ *
+ *   - Creates a default storage pool using the loaded configuration.
+ *
+ * You can modify this behavior:
+ *
+ *   - Via configuration
+ *
+ *   - By modifying {@link Environment.default}
+ *
+ *   - By providing an {@link Environment} to your components other than {@link Environment.default}
+ *
+ * The settings are applied in this order (the higher numbers overwrite lower numbers):
+ * 1. Some internal Defaults (mainly Loglevel and such)
+ * 2. Config file
+ * 3. Environment variables (MATTER_*)
+ * 4. Command line parameters
+ *
+ * The following variables are defined by this class additionally to {@link Environment}:
+ * * `environment` - Name of the environment, Default "default"
+ * * `path.root` - Path considered as root for any files to store, Fallback: ".", Default: APPDATA/.matter (Windows), HOME/.matter else (or .matter-<envname>)
+ * * `path.config` - Path to config file, Default: "config.json"
+ * * `trace.path` - Path of the trace file to write, Default: "trace.jsonl" relative to path.root
+ * * `trace.enable` - Enable writing a trace file
+ * * `storage.path` - Where to store storage files, Default: "path.root"
+ * * `storage.clear` - Clear storage on start? Default: false
+ * * `runtime.signals` - By default register SIGINT and SIGUSR2 (diag) handlers, set to false if not wanted
+ * * `runtime.exitcode` - By default we set the process.exitcode to 0 (ok) or 1 (crash); set to false to disable
+ * * `runtime.unhandlederrors` - By default we log unhandled errors to matter.js log; set to false to disable
+ */
+export function NodeJsEnvironment() {
+    const env = new Environment("default");
+
+    loadVariables(env);
+    configureRuntime(env);
+    configureStorage(env);
+    configureNetwork(env);
+
+    // When no logger format is set, we still use the default, and the process is running in a TTY, use ANSI formatting
+    // If a user wants to change the log format he still can do after the environment was initialized (which should be
+    // first thing anyway)
+    if (!env.vars.has("logger.format") && Logger.format === LogFormat.PLAIN && process.stdin?.isTTY) {
+        env.vars.set("logger.format", LogFormat.ANSI);
+    }
+
+    NodeJsActionTracer.configure(env);
+
+    return env;
+}
+
+function loadVariables(env: Environment) {
+    const vars = env.vars;
+
+    // Install defaults
+    vars.addConfigStyle(getDefaults(vars));
+
+    // Preload environment and argv so we can use it to find config file
+    vars.addUnixEnvStyle(process.env);
+    vars.addArgvStyle(process.argv);
+
+    // Load config files
+    vars.addConfigStyle(loadConfigFile(vars));
+
+    // Reload environment and argv so they override config
+    vars.addUnixEnvStyle(process.env);
+    vars.addArgvStyle(process.argv);
+}
+
+function configureRuntime(env: Environment) {
+    const processManager = new ProcessManager(env);
+    env.set(ProcessManager, processManager);
+}
+
+function configureStorage(env: Environment) {
+    const service = env.get(StorageService);
+
+    env.vars.use(() => {
+        const location = env.vars.get("storage.path", env.vars.get("path.root", "."));
+        service.location = location;
+    });
+
+    service.factory = namespace =>
+        new StorageBackendDisk(resolve(service.location ?? ".", namespace), env.vars.get("storage.clear", false));
+}
+
+function configureNetwork(env: Environment) {
+    env.set(Network, new NodeJsNetwork());
+}
+
+export function loadConfigFile(vars: VariableService) {
+    const path = vars.get("path.config", "config.json");
+
+    if (!existsSync(path)) {
+        return {};
+    }
+
+    let configJson;
+    try {
+        configJson = readFileSync(path).toString();
+    } catch (e) {
+        throw new ImplementationError(`Error reading configuration file ${path}: ${(e as Error).message}`);
+    }
+
+    let configVars;
+    try {
+        configVars = JSON.parse(configJson);
+    } catch (e) {
+        throw new ImplementationError(`Error parsing configuration file ${path}: ${(e as Error).message}`);
+    }
+
+    return configVars;
+}
+
+function getDefaultRoot(envName: string) {
+    let matterDir;
+    if (process.platform === "win32") {
+        matterDir = resolve(process.env.APPDATA ?? ".", "matter");
+    } else {
+        matterDir = resolve(process.env.HOME ?? ".", ".matter");
+    }
+
+    if (envName !== "default") {
+        matterDir = `${matterDir}-${envName}`;
+    }
+
+    return matterDir;
+}
+
+export function getDefaults(vars: VariableService) {
+    const envName = vars.get("environment", "default");
+    const rootPath = vars.get("path.root", getDefaultRoot(envName));
+    const configPath = resolve(rootPath, vars.get("path.config", "config.json"));
+
+    return {
+        environment: envName,
+        path: {
+            root: rootPath,
+            config: configPath,
+        },
+        runtime: {
+            signals: true,
+            exitcode: true,
+        },
+    };
+}