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

package/src/MatterError.ts

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { errorOf } from "./util/Error.js";
+
+const inspect = Symbol.for("nodejs.util.inspect.custom");
+
+/**
+ * Error base class for all errors thrown by this library.
+ */
+export class MatterError extends Error {
+    /**
+     * Convert the error to formatted text.
+     *
+     * Matter encodes errors with modern JS features including {@link Error#cause} and {@link AggregateError#errors}
+     * subfields.  You can use this function to ensure all error details are presented regardless of environment.
+     */
+    format(format: "plain" | "ansi" | "html" = "plain", indents = 0) {
+        let formatterFor = MatterError.formatterFor;
+        if (typeof formatterFor !== "function") {
+            formatterFor = MatterError.defaultFormatterFactory;
+        }
+
+        let formatter = formatterFor(format);
+        if (typeof formatter !== "function") {
+            formatter = fallbackFormatter;
+        }
+
+        let result = formatter(this, indents);
+        if (typeof result !== "string") {
+            result = `${result}`;
+        }
+
+        return result as string;
+    }
+
+    /**
+     * Node.js-style object inspection.
+     *
+     * Node's default inspection only prevents two levels of depth which may hide critical information.  It's also
+     * considerably more verbose than native matter.js formatting.  We therefore offer this custom implementation.
+     *
+     * Note that this conforms to Node's API but is not dependent on Node.
+     */
+    [inspect](depth: number, inspectionOptions?: { colors?: boolean }) {
+        const formatterFor = MatterError.formatterFor;
+        if (typeof formatterFor !== "function") {
+            return this;
+        }
+
+        const format = formatterFor(inspectionOptions?.colors ? "ansi" : "plain");
+        if (typeof format !== "function") {
+            return this;
+        }
+
+        return format(this, depth);
+    }
+
+    /**
+     * Rethrow an error unless it is an instance of this class.
+     */
+    static accept<T extends MatterError>(this: new (...args: any[]) => T, error: unknown): asserts error is T {
+        if (error instanceof this) {
+            return;
+        }
+        throw error;
+    }
+
+    /**
+     * Rethrow an error if it is an instance of this class.
+     */
+    static reject(error: unknown): void {
+        if (error instanceof this) {
+            throw error;
+        }
+    }
+
+    /**
+     * The fallback formatter factory.  This produces a limited plaintext formatter.
+     */
+    static defaultFormatterFactory = () => fallbackFormatter;
+
+    /**
+     * The error formatter factory.  The default formatter is replaced by Matter.js in ./Format.ts.
+     */
+    static formatterFor: (formatName: string) => (value: unknown, indents?: number) => unknown =
+        MatterError.defaultFormatterFactory;
+
+    // TODO - this is probably correct; MatterAggregateError should be typeof MatterError.  Need to diagnose some test
+    // breakage before enabling though
+    // static [Symbol.hasInstance](instance: unknown) {
+    //     if (instance instanceof MatterAggregateError) {
+    //         return true;
+    //     }
+    //     return Error[Symbol.hasInstance](instance);
+    // }
+}
+
+/**
+ * Error thrown when a Platform specific implementation was not added and so a provider (Network, Time, Crypto, etc)
+ * is not available.
+ */
+export class NoProviderError extends MatterError {}
+
+/**
+ * Error thrown when an internal error occurs like unexpected cases or missing data that should be there. Please
+ * report such errors.
+ */
+export class InternalError extends MatterError {}
+
+/** Error thrown when a feature is not implemented yet. Please report such errors. */
+export class NotImplementedError extends InternalError {}
+
+/** Error thrown when an unexpected case in the matter flow is encountered. Please report such errors. */
+export class MatterFlowError extends MatterError {}
+
+/** Error thrown when an unexpected data is encountered. Please report such errors. */
+export class UnexpectedDataError extends MatterError {}
+
+/**
+ * Error thrown if most likely an implementation error is detected. Please check and correct your implementation and
+ * provided data. if you are sure your code is correct please report the issue.
+ */
+export class ImplementationError extends MatterError {}
+
+/**
+ * Thrown for write attempts against immutable data.
+ */
+export class ReadOnlyError extends ImplementationError {
+    constructor(message = "This view is read-only") {
+        super(message);
+    }
+}
+
+/**
+ * Thrown for errors that have multiple underlying causes.
+ */
+export class MatterAggregateError extends AggregateError {
+    constructor(causes: Iterable<unknown>, message?: string) {
+        causes = [...causes].map(errorOf);
+        super(causes, message);
+    }
+
+    [inspect] = MatterError.prototype[inspect];
+    format = MatterError.prototype.format;
+
+    // TODO - see comment on MatterError.  If that one is correct this is incorrect
+    static override [Symbol.hasInstance](instance: unknown) {
+        if (instance instanceof MatterError) {
+            return true;
+        }
+        return AggregateError[Symbol.hasInstance](instance);
+    }
+}
+
+/**
+ * It's never reasonable to fail to present error information so we include this rudimentary fallback error formatter.
+ */
+function fallbackFormatter(value: unknown, indents = 0) {
+    if (value === undefined || value === null) {
+        return `${value}`;
+    }
+
+    function formatOne(value: unknown, indents: number, messagePrefix: string) {
+        const { message, stack, cause, errors } = value as {
+            message?: unknown;
+            stack?: unknown;
+            cause?: unknown;
+            errors?: unknown;
+        };
+
+        let indent;
+        if (typeof indents !== "number" || indents < 0) {
+            indent = "";
+        } else {
+            indent = "  ".repeat(indents);
+        }
+
+        const buffer = [`${indent}${messagePrefix}${message ?? "(unknown error)"}`];
+
+        if (stack !== undefined && stack !== null) {
+            const frames = stack.toString().split("\n");
+            frames.shift();
+            buffer.push(...frames.map(f => `${indent}  ${f.trim()}`));
+        }
+
+        if (cause !== undefined) {
+            buffer.push(formatOne(cause, indents, "Caused by: "));
+        }
+
+        if (typeof (errors as Iterable<unknown> | undefined)?.[Symbol.iterator] === "function") {
+            let causeNumber = 0;
+            for (const error of errors as Iterable<unknown>) {
+                buffer.push(formatOne(error, indents + 1, `Cause #${causeNumber++}: `));
+            }
+        }
+
+        return buffer.join("\n");
+    }
+
+    return formatOne(value, indents, "");
+}

package/src/codec/Base64Codec.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function cp(text: string) {
+    return text.codePointAt(0) ?? 0;
+}
+
+const A2B = <number[]>[];
+const B2A = new Uint8Array(64);
+const B2A_URL = new Uint8Array(64);
+const PAD = cp("=");
+
+{
+    let pos = 0;
+
+    function addRange(start: string, stop: string) {
+        const end = cp(stop) + 1;
+        for (let i = cp(start); i < end; i++) {
+            A2B[i] = pos;
+            B2A[pos++] = i;
+        }
+    }
+    addRange("A", "Z");
+    addRange("a", "z");
+    addRange("0", "9");
+    addRange("+", "+");
+    addRange("/", "/");
+
+    // base64url
+    const slashValue = A2B[cp("/")];
+    const plusValue = A2B[cp("+")];
+    A2B[cp("_")] = slashValue;
+    A2B[cp("-")] = plusValue;
+    B2A_URL.set(B2A);
+    B2A_URL[slashValue] = cp("_");
+    B2A_URL[plusValue] = cp("-");
+}
+
+export namespace Base64 {
+    /**
+     * Encodes base64.
+     *
+     * @param input an indexable sequence of bytes
+     * @param url set to true to encode as base46url
+     * @returns an encoded string
+     */
+    export function encode(input: ArrayLike<number>, url = false) {
+        const dict = url ? B2A_URL : B2A;
+        let outLength = Math.trunc(input.length / 3) * 4;
+        if (url) {
+            const partial = input.length % 3;
+            if (partial) outLength += partial + 1;
+        } else {
+            outLength += input.length % 3 ? 4 : 0;
+        }
+        const out = new Uint8Array(outLength);
+
+        for (let inPos = 0, outPos = 0; outPos < outLength; ) {
+            const n = (input[inPos++] << 16) + ((input[inPos++] ?? 0) << 8) + (input[inPos++] ?? 0);
+
+            out[outPos++] = dict[n >>> 18];
+            out[outPos++] = dict[(n >>> 12) & 0o77];
+
+            if (inPos - input.length === 2) {
+                if (!url) out[outPos++] = PAD;
+            } else {
+                out[outPos++] = dict[(n >>> 6) & 0o77];
+            }
+
+            if (inPos > input.length) {
+                if (!url) out[outPos++] = PAD;
+            } else {
+                out[outPos++] = dict[n & 0o77];
+            }
+        }
+
+        return new TextDecoder("iso-8859-1").decode(out);
+    }
+
+    /**
+     * Decodes base64.
+     *
+     * @param input binary data encoded as a base64 or base64url string
+     * @returns decoded bytes in a ByteArray
+     */
+    export function decode(input: string) {
+        if (!input.length) {
+            return new Uint8Array();
+        }
+
+        let inputLength = input.length;
+        while (input.codePointAt(inputLength - 1) === PAD) inputLength--;
+
+        let outLength = Math.trunc(inputLength / 4) * 3;
+        switch (inputLength % 4) {
+            case 3:
+                outLength += 2;
+                break;
+            case 2:
+                outLength += 1;
+                break;
+            case 1:
+                throw new Error("Invalid base-64 encoding");
+        }
+
+        const out = new Uint8Array(outLength);
+
+        for (let inPos = 0, outPos = 0; ; ) {
+            function lookup() {
+                if (inPos >= inputLength) return 0;
+                const v = A2B[input.codePointAt(inPos++) ?? -1];
+                if (v === undefined) {
+                    throw new Error("Invalid base-64 encoding");
+                }
+                return v;
+            }
+
+            const n = (lookup() << 18) + (lookup() << 12) + (lookup() << 6) + lookup();
+            out[outPos++] = n >>> 16;
+            if (outPos < outLength) {
+                out[outPos++] = (n >>> 8) & 0xff;
+            } else {
+                break;
+            }
+            if (outPos < outLength) {
+                out[outPos++] = n & 0xff;
+            } else {
+                break;
+            }
+        }
+
+        return out;
+    }
+}

package/src/codec/DerCodec.ts

@@ -0,0 +1,300 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { UnexpectedDataError } from "../MatterError.js";
+import { Bytes, Endian } from "../util/Bytes.js";
+import { DataReader } from "../util/DataReader.js";
+import { toHex } from "../util/Number.js";
+import { isObject } from "../util/Type.js";
+
+export enum DerKey {
+    ObjectId = "_objectId",
+    TagId = "_tag",
+    Bytes = "_bytes",
+    Elements = "_elements",
+    BitsPadding = "_padding",
+    TypeOverride = "_type",
+    RawData = "_raw",
+}
+
+export class DerError extends UnexpectedDataError {}
+
+export enum DerType {
+    Boolean = 0x01,
+    Integer = 0x02,
+    BitString = 0x03,
+    OctetString = 0x04,
+    Null = 0x05,
+    ObjectIdentifier = 0x06,
+    UTF8String = 0x0c,
+    Sequence = 0x10,
+    Set = 0x11,
+    PrintableString = 0x13,
+    T16String = 0x14,
+    IA5String = 0x16,
+    UtcDate = 0x17,
+    GeneralizedTime = 0x18,
+}
+
+const CONSTRUCTED = 0x20;
+
+const enum DerClass {
+    Universal = 0x00,
+    Application = 0x40,
+    ContextSpecific = 0x80,
+    Private = 0xc0,
+}
+export const ObjectId = (objectId: string) => ({
+    [DerKey.TagId]: DerType.ObjectIdentifier as number,
+    [DerKey.Bytes]: Bytes.fromHex(objectId),
+});
+export const DerObject = (objectId: string, content: any = {}) => ({
+    [DerKey.ObjectId]: ObjectId(objectId),
+    ...content,
+});
+export const BitByteArray = (data: Uint8Array, padding = 0) => ({
+    [DerKey.TagId]: DerType.BitString as number,
+    [DerKey.Bytes]: data,
+    [DerKey.BitsPadding]: padding,
+});
+export const ContextTagged = (tagId: number, value?: any) => ({
+    [DerKey.TagId]: tagId | DerClass.ContextSpecific | CONSTRUCTED,
+    [DerKey.Bytes]: value === undefined ? new Uint8Array(0) : DerCodec.encode(value),
+});
+export const ContextTaggedBytes = (tagId: number, value: Uint8Array) => ({
+    [DerKey.TagId]: tagId | DerClass.ContextSpecific,
+    [DerKey.Bytes]: value,
+});
+export const DatatypeOverride = (type: DerType, value: any) => ({
+    [DerKey.TypeOverride]: type,
+    [DerKey.RawData]: value,
+});
+export const RawBytes = (bytes: Uint8Array) => ({
+    [DerKey.Bytes]: bytes,
+});
+
+export type DerNode = {
+    [DerKey.TagId]: number;
+    [DerKey.Bytes]: Uint8Array;
+    [DerKey.Elements]?: DerNode[];
+    [DerKey.BitsPadding]?: number;
+};
+
+export class DerCodec {
+    static encode(value: any): Uint8Array {
+        if (Array.isArray(value)) {
+            return this.encodeArray(value);
+        } else if (value instanceof Uint8Array) {
+            return this.encodeOctetString(value);
+        } else if (value instanceof Date) {
+            return this.encodeDate(value);
+        } else if (typeof value === "string") {
+            return this.encodeString(value);
+        } else if (typeof value === "number" || typeof value === "bigint") {
+            return this.encodeInteger(value);
+        } else if (typeof value === "boolean") {
+            return this.encodeBoolean(value);
+        } else if (value === undefined) {
+            return new Uint8Array(0);
+        } else if (isObject(value)) {
+            if (value[DerKey.TagId] !== undefined) {
+                const { [DerKey.TagId]: tagId, [DerKey.BitsPadding]: bitsPadding, [DerKey.Bytes]: bytes } = value;
+                if (typeof tagId !== "number") {
+                    throw new DerError("Tag ID is non-numeric");
+                }
+                if (bitsPadding !== undefined && typeof bitsPadding !== "number") {
+                    throw new DerError("Bits padding is not a numeric byte value");
+                }
+                if (bytes === undefined || !ArrayBuffer.isView(bytes)) {
+                    throw new DerError("DER bytes is not a byte array");
+                }
+                return this.encodeAsn1(
+                    tagId,
+                    bitsPadding === undefined
+                        ? (bytes as Uint8Array)
+                        : Bytes.concat(Uint8Array.of(bitsPadding), bytes as Uint8Array),
+                );
+            } else if (value[DerKey.TypeOverride] !== undefined && value[DerKey.RawData] !== undefined) {
+                if (value[DerKey.TypeOverride] === DerType.Integer && value[DerKey.RawData] instanceof Uint8Array) {
+                    return this.encodeInteger(value[DerKey.RawData]);
+                } else if (
+                    value[DerKey.TypeOverride] === DerType.BitString &&
+                    typeof value[DerKey.RawData] === "number"
+                ) {
+                    return this.encodeBitString(value[DerKey.RawData]);
+                } else if (
+                    value[DerKey.TypeOverride] === DerType.PrintableString &&
+                    typeof value[DerKey.RawData] === "string"
+                ) {
+                    return this.encodePrintableString(value[DerKey.RawData]);
+                } else if (
+                    value[DerKey.TypeOverride] === DerType.IA5String &&
+                    typeof value[DerKey.RawData] === "string"
+                ) {
+                    return this.encodeIA5String(value[DerKey.RawData]);
+                } else {
+                    throw new UnexpectedDataError(`Unsupported override type ${value[DerKey.TypeOverride]}`);
+                }
+            } else if (
+                value[DerKey.Bytes] !== undefined &&
+                value[DerKey.Bytes] instanceof Uint8Array &&
+                Object.keys(value).length === 1
+            ) {
+                // Raw Data
+                return value[DerKey.Bytes];
+            } else if (value[DerKey.TypeOverride] === undefined && value[DerKey.Bytes] === undefined) {
+                return this.encodeObject(value);
+            } else {
+                throw new UnexpectedDataError(`Unsupported object type ${typeof value}`);
+            }
+        } else {
+            throw new UnexpectedDataError(`Unsupported type ${typeof value}`);
+        }
+    }
+
+    private static encodeDate(date: Date) {
+        if (date.getFullYear() > 2049) {
+            // Dates 2050+ are encoded as GeneralizedTime. This includes the special Non Well Defined date 9999-12-31.
+            return this.encodeAsn1(
+                DerType.GeneralizedTime,
+                Bytes.fromString(
+                    date
+                        .toISOString()
+                        .replace(/[-:.T]/g, "")
+                        .slice(0, 14) + "Z",
+                ),
+            );
+        } else
+            return this.encodeAsn1(
+                DerType.UtcDate,
+                Bytes.fromString(
+                    date
+                        .toISOString()
+                        .replace(/[-:.T]/g, "")
+                        .slice(2, 14) + "Z",
+                ),
+            );
+    }
+
+    private static encodeBoolean(bool: boolean) {
+        return this.encodeAsn1(DerType.Boolean, Uint8Array.of(bool ? 0xff : 0));
+    }
+
+    private static encodeArray(array: Array<any>) {
+        return this.encodeAsn1(DerType.Set | CONSTRUCTED, Bytes.concat(...array.map(element => this.encode(element))));
+    }
+
+    private static encodeOctetString(value: Uint8Array) {
+        return this.encodeAsn1(DerType.OctetString, value);
+    }
+
+    private static encodeObject(object: any) {
+        const attributes = new Array<Uint8Array>();
+        for (const key in object) {
+            attributes.push(this.encode(object[key]));
+        }
+        return this.encodeAsn1(DerType.Sequence | CONSTRUCTED, Bytes.concat(...attributes));
+    }
+
+    private static encodeString(value: string) {
+        return this.encodeAsn1(DerType.UTF8String, Bytes.fromString(value));
+    }
+
+    private static encodePrintableString(value: string) {
+        if (!/^[A-Za-z0-9 '()+,-./:=?]*$/g.test(value)) {
+            throw new UnexpectedDataError(`String ${value} is not a printable string.`);
+        }
+        return this.encodeAsn1(DerType.PrintableString, Bytes.fromString(value));
+    }
+
+    private static encodeIA5String(value: string) {
+        /*eslint-disable-next-line no-control-regex */
+        if (!/^[\x00-\x7F]*$/.test(value)) {
+            throw new UnexpectedDataError(`String ${value} is not an IA5 string.`);
+        }
+        return this.encodeAsn1(DerType.IA5String, Bytes.fromString(value));
+    }
+
+    private static encodeInteger(value: number | bigint | Uint8Array) {
+        const isByteArray = ArrayBuffer.isView(value);
+        let valueBytes: Uint8Array;
+        if (isByteArray) {
+            valueBytes = value;
+        } else {
+            valueBytes = Bytes.fromHex(toHex(value));
+        }
+        const byteArray = Bytes.concat(new Uint8Array(1), valueBytes);
+        const dataView = Bytes.dataViewOf(byteArray);
+        let start = 0;
+        while (true) {
+            if (dataView.getUint8(start) !== 0) break;
+            if (dataView.getUint8(start + 1) >= 0x80) break;
+            start++;
+            if (start === byteArray.length - 1) break;
+        }
+        return this.encodeAsn1(DerType.Integer, byteArray.slice(start));
+    }
+
+    private static encodeBitString(value: number) {
+        const reversedBits = value.toString(2).padStart(8, "0");
+        const unusedBits = reversedBits.indexOf("1");
+        const bitByteArray = Uint8Array.of(parseInt(reversedBits.split("").reverse().join(""), 2));
+        return this.encode(BitByteArray(bitByteArray, unusedBits === -1 ? 8 : unusedBits));
+    }
+
+    private static encodeLengthBytes(value: number) {
+        const byteArray = new Uint8Array(5);
+        const dataView = Bytes.dataViewOf(byteArray);
+        dataView.setUint32(1, value);
+        let start = 0;
+        while (true) {
+            if (dataView.getUint8(start) !== 0) break;
+            start++;
+            if (start === 4) break;
+        }
+        const lengthLength = byteArray.length - start;
+        if (lengthLength > 1 || dataView.getUint8(start) >= 0x80) {
+            start--;
+            dataView.setUint8(start, 0x80 + lengthLength);
+        }
+        return byteArray.slice(start);
+    }
+
+    private static encodeAsn1(tag: number, data: Uint8Array) {
+        return Bytes.concat(Uint8Array.of(tag), this.encodeLengthBytes(data.length), data);
+    }
+
+    static decode(data: Uint8Array): DerNode {
+        return this.decodeRec(new DataReader(data, Endian.Big));
+    }
+
+    private static decodeRec(reader: DataReader<Endian.Big>): DerNode {
+        const { tag, bytes } = this.decodeAsn1(reader);
+        if (tag === DerType.BitString)
+            return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes.slice(1), [DerKey.BitsPadding]: bytes[0] };
+        if ((tag & CONSTRUCTED) === 0) return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes };
+        const elementsReader = new DataReader(bytes, Endian.Big);
+        const elements: DerNode[] = [];
+        while (elementsReader.getRemainingBytesCount() > 0) {
+            elements.push(this.decodeRec(elementsReader));
+        }
+        return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes, [DerKey.Elements]: elements };
+    }
+
+    private static decodeAsn1(reader: DataReader<Endian.Big>): { tag: number; bytes: Uint8Array } {
+        const tag = reader.readUInt8();
+        let length = reader.readUInt8();
+        if ((length & 0x80) !== 0) {
+            let lengthLength = length & 0x7f;
+            length = 0;
+            while (lengthLength > 0) {
+                length = (length << 8) + reader.readUInt8();
+                lengthLength--;
+            }
+        }
+        const bytes = reader.readByteArray(length);
+        return { tag, bytes };
+    }
+}