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

package/src/crypto/Spake2p.ts

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "../MatterError.js";
+import { Bytes, Endian } from "../util/Bytes.js";
+import { DataWriter } from "../util/DataWriter.js";
+import { Crypto, ec } from "./Crypto.js";
+import { CRYPTO_GROUP_SIZE_BYTES } from "./CryptoConstants.js";
+
+const {
+    p256: { ProjectivePoint, CURVE: P256_CURVE },
+    numberToBytesBE,
+    bytesToNumberBE,
+    mod,
+} = ec;
+
+// M and N constants from https://datatracker.ietf.org/doc/html/draft-bar-cfrg-spake2plus-01
+const M = ProjectivePoint.fromHex("02886e2f97ace46e55ba9dd7242579f2993b64e16ef3dcab95afd497333d8fa12f");
+const N = ProjectivePoint.fromHex("03d8bbd6c639c62937b04d997f38c3770719c629d7014d49a24b4f98baa1292b49");
+
+const CRYPTO_W_SIZE_BYTES = CRYPTO_GROUP_SIZE_BYTES + 8;
+
+export interface PbkdfParameters {
+    iterations: number;
+    salt: Uint8Array;
+}
+
+export class Spake2p {
+    static async computeW0W1({ iterations, salt }: PbkdfParameters, pin: number) {
+        const pinWriter = new DataWriter(Endian.Little);
+        pinWriter.writeUInt32(pin);
+        const ws = await Crypto.pbkdf2(pinWriter.toByteArray(), salt, iterations, CRYPTO_W_SIZE_BYTES * 2);
+        const w0 = mod(bytesToNumberBE(ws.slice(0, 40)), P256_CURVE.n);
+        const w1 = mod(bytesToNumberBE(ws.slice(40, 80)), P256_CURVE.n);
+        return { w0, w1 };
+    }
+
+    static async computeW0L(pbkdfParameters: PbkdfParameters, pin: number) {
+        const { w0, w1 } = await this.computeW0W1(pbkdfParameters, pin);
+        const L = ProjectivePoint.BASE.multiply(w1).toRawBytes(false);
+        return { w0, L };
+    }
+
+    static create(context: Uint8Array, w0: bigint) {
+        const random = Crypto.getRandomBigInt(32, P256_CURVE.p);
+        return new Spake2p(context, random, w0);
+    }
+
+    constructor(
+        private readonly context: Uint8Array,
+        private readonly random: bigint,
+        private readonly w0: bigint,
+    ) {}
+
+    computeX(): Uint8Array {
+        const X = ProjectivePoint.BASE.multiply(this.random).add(M.multiply(this.w0));
+        return X.toRawBytes(false);
+    }
+
+    computeY(): Uint8Array {
+        const Y = ProjectivePoint.BASE.multiply(this.random).add(N.multiply(this.w0));
+        return Y.toRawBytes(false);
+    }
+
+    async computeSecretAndVerifiersFromY(w1: bigint, X: Uint8Array, Y: Uint8Array) {
+        const YPoint = ProjectivePoint.fromHex(Y);
+        try {
+            YPoint.assertValidity();
+        } catch (error) {
+            throw new InternalError(`Y is not on the curve: ${(error as any).message}`);
+        }
+        const yNwo = YPoint.add(N.multiply(this.w0).negate());
+        const Z = yNwo.multiply(this.random);
+        const V = yNwo.multiply(w1);
+        return this.computeSecretAndVerifiers(X, Y, Z.toRawBytes(false), V.toRawBytes(false));
+    }
+
+    async computeSecretAndVerifiersFromX(L: Uint8Array, X: Uint8Array, Y: Uint8Array) {
+        const XPoint = ProjectivePoint.fromHex(X);
+        const LPoint = ProjectivePoint.fromHex(L);
+        try {
+            XPoint.assertValidity();
+        } catch (error) {
+            throw new InternalError(`X is not on the curve: ${(error as any).message}`);
+        }
+        const Z = XPoint.add(M.multiply(this.w0).negate()).multiply(this.random);
+        const V = LPoint.multiply(this.random);
+        return this.computeSecretAndVerifiers(X, Y, Z.toRawBytes(false), V.toRawBytes(false));
+    }
+
+    private async computeSecretAndVerifiers(X: Uint8Array, Y: Uint8Array, Z: Uint8Array, V: Uint8Array) {
+        const TT_HASH = this.computeTranscriptHash(X, Y, Z, V);
+        const Ka = TT_HASH.slice(0, 16);
+        const Ke = TT_HASH.slice(16, 32);
+
+        const KcAB = await Crypto.hkdf(Ka, new Uint8Array(0), Bytes.fromString("ConfirmationKeys"), 32);
+        const KcA = KcAB.slice(0, 16);
+        const KcB = KcAB.slice(16, 32);
+
+        const hAY = Crypto.hmac(KcA, Y);
+        const hBX = Crypto.hmac(KcB, X);
+
+        return { Ke, hAY, hBX };
+    }
+
+    private computeTranscriptHash(X: Uint8Array, Y: Uint8Array, Z: Uint8Array, V: Uint8Array) {
+        const TTwriter = new DataWriter(Endian.Little);
+        this.addToContext(TTwriter, this.context);
+        this.addToContext(TTwriter, Bytes.fromString(""));
+        this.addToContext(TTwriter, Bytes.fromString(""));
+        this.addToContext(TTwriter, M.toRawBytes(false));
+        this.addToContext(TTwriter, N.toRawBytes(false));
+        this.addToContext(TTwriter, X);
+        this.addToContext(TTwriter, Y);
+        this.addToContext(TTwriter, Z);
+        this.addToContext(TTwriter, V);
+        this.addToContext(TTwriter, numberToBytesBE(this.w0, 32));
+        return Crypto.hash(TTwriter.toByteArray());
+    }
+
+    private addToContext(TTwriter: DataWriter<Endian.Little>, data: Uint8Array) {
+        TTwriter.writeUInt64(data.length);
+        TTwriter.writeByteArray(data);
+    }
+}

package/src/crypto/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Crypto.js";
+export * from "./CryptoConstants.js";
+export * from "./Key.js";
+export * from "./Spake2p.js";

package/src/environment/Environment.ts

@@ -0,0 +1,215 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DiagnosticSource } from "../log/DiagnosticSource.js";
+import { Logger } from "../log/Logger.js";
+import "../polyfills/disposable.js";
+import { Time } from "../time/Time.js";
+import { UnsupportedDependencyError } from "../util/Lifecycle.js";
+import { Observable } from "../util/Observable.js";
+import { Environmental } from "./Environmental.js";
+import { RuntimeService } from "./RuntimeService.js";
+import { VariableService } from "./VariableService.js";
+
+const logger = Logger.get("Environment");
+
+/**
+ * Access to general platform-dependent features.
+ *
+ * The following variables are defined by this class:
+ * * `log.level` - Log level to use {@link Logger.LEVEL}
+ * * `log.format` - Log format to use {@link Logger.FORMAT}
+ * * `log.stack.limit` - Stack trace limit, see https://nodejs.org/api/errors.html#errorstacktracelimit
+ * * `mdns.networkInterface` - Network interface to use for MDNS broadcasts and scanning, default are all available interfaces
+ * * `mdns.ipv4` - Also announce/scan on IPv4 interfaces
+ * * `network.interface` - Map of interface names to types, expected to be defined as object with name as key and of `{type: string|number}` objects with types: 1=Wifi, 2=Ethernet, 3=Cellular, 4=Thread (strings or numbers can be used). Can also be provided via env or cli like `MATTER_NETWORK_INTERFACE_ETH0_TYPE=Ethernet`
+ *
+ * TODO - could remove global singletons by moving here
+ */
+export class Environment {
+    #services?: Map<abstract new (...args: any[]) => any, Environmental.Service>;
+    #name: string;
+    #parent?: Environment;
+    #added = Observable<[type: abstract new (...args: any[]) => {}, instance: {}]>();
+    #deleted = Observable<[type: abstract new (...args: any[]) => {}, instance: {}]>();
+    #serviceEvents = new Map<abstract new (...args: any[]) => any, Environmental.ServiceEvents<any>>();
+
+    constructor(name: string, parent?: Environment) {
+        this.#name = name;
+        this.#parent = parent;
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Access an environmental service.
+     */
+    get<T extends object>(type: abstract new (...args: any[]) => T): T {
+        let instance = this.#services?.get(type) ?? this.#parent?.get(type);
+
+        if (instance) {
+            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;
+        }
+
+        throw new UnsupportedDependencyError(`Required dependency ${type.name}`, "is not available");
+    }
+
+    /**
+     * Remove an environmental service.
+     *
+     * @param type the class of the service to remove
+     * @param instance optional instance expected, if existing instance does not match it is not deleted
+     */
+    delete(type: abstract new (...args: any[]) => any, instance?: any) {
+        if (instance !== undefined && this.#services?.get(type) !== instance) {
+            return;
+        }
+        this.#services?.delete(type);
+        this.#parent?.delete(type);
+
+        this.#deleted.emit(type, instance);
+
+        const serviceEvents = this.#serviceEvents.get(type);
+        if (serviceEvents) {
+            serviceEvents.deleted.emit(instance);
+        }
+    }
+
+    /**
+     * Access an environmental service, waiting for any async initialization to complete.
+     */
+    async load<T extends Environmental.Service>(type: Environmental.Factory<T>) {
+        const instance = this.get(type);
+        await instance.construction;
+        return instance;
+    }
+
+    /**
+     * Install a preinitialized version of an environmental service.
+     */
+    set<T extends {}>(type: abstract new (...args: any[]) => T, instance: T) {
+        if (!this.#services) {
+            this.#services = new Map();
+        }
+        this.#services.set(type, instance as Environmental.Service);
+        this.#added.emit(type, instance);
+        const serviceEvents = this.#serviceEvents.get(type);
+        if (serviceEvents) {
+            serviceEvents.added.emit(instance);
+        }
+    }
+
+    /**
+     * Name of the environment.
+     */
+    get name() {
+        return this.#name;
+    }
+
+    /**
+     * Emits on service add.
+     *
+     * Currently only emits for services owned directly by this environment.
+     */
+    get added() {
+        return this.#added;
+    }
+
+    /**
+     * Emits on service delete.
+     *
+     * Currently only emits for services owned directly by this environment.
+     */
+    get deleted() {
+        return this.#deleted;
+    }
+
+    /**
+     * Obtain an object with events that trigger when a specific service is added or deleted.
+     *
+     * This is a more convenient way to observe a specific service than {@link added} and {@link deleted}.
+     */
+    eventsFor<T extends Environmental.Factory<any>>(type: T) {
+        let events = this.#serviceEvents.get(type);
+        if (events === undefined) {
+            events = {
+                added: new Observable(),
+                deleted: new Observable(),
+            };
+            this.#serviceEvents.set(type, events);
+        }
+        return events as Environmental.ServiceEvents<T>;
+    }
+
+    /**
+     * The default environment.
+     *
+     * Currently only emits for services owned directly by this environment.
+     */
+    static get default() {
+        return global;
+    }
+
+    /**
+     * Set the default environment.
+     */
+    static set default(env: Environment) {
+        global = env;
+
+        env.vars.use(() => {
+            Logger.level = env.vars.get("log.level", Logger.level);
+            Logger.format = env.vars.get("log.format", Logger.format);
+
+            const stackLimit = global.vars.number("log.stack.limit");
+            if (stackLimit !== undefined) {
+                (Error as { stackTraceLimit?: number }).stackTraceLimit = stackLimit;
+            }
+        });
+    }
+
+    /**
+     * Shortcut for accessing {@link VariableService.vars}.
+     */
+    get vars() {
+        return this.get(VariableService);
+    }
+
+    /**
+     * Shortcut for accessing {@link RuntimeService}.
+     */
+    get runtime() {
+        return this.get(RuntimeService);
+    }
+
+    /**
+     * Display tasks that supply diagnostics.
+     */
+    diagnose() {
+        Time.getTimer("Diagnostics", 0, () => {
+            try {
+                logger.notice("Diagnostics follow", DiagnosticSource);
+            } catch (e) {
+                logger.error(`Unhandled error gathering diagnostics:`, e);
+            }
+        }).start();
+    }
+
+    protected loadVariables(): Record<string, any> {
+        return {};
+    }
+}
+
+let global: Environment = new Environment("default");

package/src/environment/Environmental.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "../log/Diagnostic.js";
+import { Observable } from "../util/Observable.js";
+import type { Environment } from "./Environment.js";
+
+export namespace Environmental {
+    export const create = Symbol("create");
+
+    /**
+     * An "environmental service" is an object available via {@link Environment.get}.
+     *
+     * Any object may be an environmental service.  This methods in this interface are optional.
+     */
+    export interface Service {
+        /**
+         * Asynchronous construction, respected by {@link Environment.load}.
+         */
+        construction?: Promise<any>;
+
+        /**
+         * Asynchronous destruction.  Invoked by the environment when it is destroyed.
+         */
+        [Symbol.asyncDispose]?: () => Promise<any>;
+
+        /**
+         * Standard diagnostic presentation.
+         */
+        [Diagnostic.presentation]?: Diagnostic.Presentation;
+
+        /**
+         * Standard diagnostic value.
+         */
+        [Diagnostic.value]?: unknown;
+    }
+
+    /**
+     * A factory for a {@link Service}.  Any constructor may be a service factory.
+     */
+    export interface Factory<T extends Service> {
+        new (...args: any[]): T;
+
+        /**
+         * The environment will create the service automatically if the factory supports {@link create}.
+         */
+        [create]?: (environment: Environment) => T;
+    }
+
+    /**
+     * Events related to service lifecycle.
+     */
+    export interface ServiceEvents<T extends abstract new (...args: any[]) => T> {
+        added: Observable<[instance: InstanceType<T>]>;
+        deleted: Observable<[instance: InstanceType<T>]>;
+    }
+}