@matter/nodejs-shell 0.16.0-alpha.0-20251112-dba1973d5 → 0.16.0-alpha.0-20251125-16883ca92

package/src/MatterNode.ts

@@ -6,6 +6,7 @@
 
 // Include this first to auto-register Crypto, Network and Time Node.js implementations
 import { Environment, Logger, StorageContext, StorageService } from "#general";
+import { DclCertificateService, DclOtaUpdateService, DclVendorInfoService } from "#protocol";
 import { NodeId } from "#types";
 import { CommissioningController, ControllerStore } from "@project-chip/matter.js";
 import { CommissioningControllerNodeOptions, Endpoint, PairedNode } from "@project-chip/matter.js/device";
@@ -16,11 +17,12 @@ const logger = Logger.get("Node");
 export class MatterNode {
     #storageLocation?: string;
     #storageContext?: StorageContext;
-    readonly #environment?: Environment;
+    readonly #environment: Environment;
     commissioningController?: CommissioningController;
     #started = false;
     readonly #nodeNum: number;
     readonly #netInterface?: string;
+    #dclFetchTestCertificates = false;
 
     constructor(nodeNum: number, netInterface?: string) {
         this.#environment = Environment.default;
@@ -33,6 +35,30 @@ export class MatterNode {
         return this.#storageLocation;
     }
 
+    get environment() {
+        return this.#environment;
+    }
+
+    get otaService() {
+        return this.environment.has(DclOtaUpdateService)
+            ? this.environment.get(DclOtaUpdateService)
+            : new DclOtaUpdateService(this.environment); // Will add itself on initial instantiation
+    }
+
+    get certificateService() {
+        if (this.environment.has(DclCertificateService)) {
+            return this.environment.get(DclCertificateService);
+        }
+
+        return new DclCertificateService(this.environment, { fetchTestCertificates: this.#dclFetchTestCertificates });
+    }
+
+    get vendorInfoService() {
+        return this.environment.has(DclVendorInfoService)
+            ? this.environment.get(DclVendorInfoService)
+            : new DclVendorInfoService(this.environment); // Will add itself on initial instantiation
+    }
+
     async initialize(resetStorage: boolean) {
         /**
          * Initialize the storage system.
@@ -63,6 +89,9 @@ export class MatterNode {
             }
             this.#storageContext = controllerStore.storage.createContext("Node");
 
+            // Read DCL test certificates setting
+            this.#dclFetchTestCertificates = await this.#storageContext.get<boolean>("DclFetchTestCertificates", false);
+
             const storageService = this.commissioningController.env.get(StorageService);
             const baseLocation = storageService.location;
             if (baseLocation !== undefined) {

package/src/shell/Shell.ts

@@ -13,17 +13,21 @@ import yargs from "yargs/yargs";
 import { MatterNode } from "../MatterNode.js";
 import { exit } from "../app";
 import { commandlineParser } from "../util/CommandlineParser.js";
+import cmdCert from "./cmd_cert.js";
 import cmdAttributes from "./cmd_cluster-attributes";
 import cmdCommands from "./cmd_cluster-commands";
 import cmdEvents from "./cmd_cluster-events";
 import cmdCommission from "./cmd_commission.js";
 import cmdConfig from "./cmd_config.js";
+import cmdDcl from "./cmd_dcl.js";
 import cmdDiscover from "./cmd_discover.js";
 import cmdIdentify from "./cmd_identify.js";
 import cmdNodes from "./cmd_nodes.js";
+import cmdOta from "./cmd_ota.js";
 import cmdSession from "./cmd_session.js";
 import cmdSubscribe from "./cmd_subscribe.js";
 import cmdTlv from "./cmd_tlv";
+import cmdVendor from "./cmd_vendor.js";
 
 const MAX_HISTORY_SIZE = 1000;
 
@@ -148,7 +152,11 @@ export class Shell {
                     cmdAttributes(this.theNode),
                     cmdEvents(this.theNode),
                     cmdCommands(this.theNode),
+                    cmdOta(this.theNode),
+                    cmdCert(this.theNode),
+                    cmdVendor(this.theNode),
                     cmdTlv(),
+                    cmdDcl(),
                     exitCommand(),
                 ])
                 .command({

package/src/shell/cmd_cert.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "#general";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode.js";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "cert",
+        describe: "Certificate management operations",
+        builder: (yargs: Argv) =>
+            yargs
+                .command(
+                    ["*", "list [vendor-id]"],
+                    "List all stored certificates",
+                    yargs => {
+                        return yargs.positional("vendor-id", {
+                            describe: "Filter by vendor ID (hex format like 0xFFF1 or decimal)",
+                            type: "string",
+                        });
+                    },
+                    async argv => {
+                        const { vendorId: vendorIdStr } = argv;
+
+                        await theNode.start();
+                        let certificates = theNode.certificateService.certificates;
+
+                        // Filter by vendor ID if provided
+                        if (vendorIdStr) {
+                            let vendorId: number;
+                            if (vendorIdStr.startsWith("0x")) {
+                                const hexStr = vendorIdStr.replace(/^0x/i, "");
+                                vendorId = parseInt(hexStr, 16);
+                            } else {
+                                vendorId = parseInt(vendorIdStr, 10);
+                            }
+
+                            if (!isFinite(vendorId)) {
+                                console.error(`Error: Invalid vendor ID "${vendorIdStr}"`);
+                                return;
+                            }
+                            certificates = certificates.filter(cert => cert.vid === vendorId);
+                        }
+
+                        if (certificates.length === 0) {
+                            console.log(
+                                vendorIdStr
+                                    ? `No certificates found for vendor ID ${vendorIdStr}.`
+                                    : "No certificates found in storage.",
+                            );
+                            return;
+                        }
+
+                        console.log(`\nFound ${certificates.length} certificate(s):\n`);
+
+                        certificates.forEach(cert => {
+                            console.log(`Subject Key ID: ${cert.subjectKeyId}`);
+                            console.log(`  Subject: ${cert.subjectAsText || cert.subject || "N/A"}`);
+                            console.log("");
+                        });
+                    },
+                )
+                .command(
+                    "details <subject-key-id>",
+                    "Display detailed information about a certificate",
+                    yargs => {
+                        return yargs.positional("subject-key-id", {
+                            describe: "Subject Key ID of the certificate",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { subjectKeyId } = argv;
+
+                        await theNode.start();
+                        const cert = theNode.certificateService.getCertificate(subjectKeyId);
+                        if (!cert) {
+                            console.error(`Certificate with subject key ID ${subjectKeyId} not found`);
+                            return;
+                        }
+
+                        console.log("\nCertificate Details:");
+                        console.log(Diagnostic.json(cert));
+                    },
+                )
+                .command(
+                    "as-pem <subject-key-id>",
+                    "Get certificate in PEM format",
+                    yargs => {
+                        return yargs.positional("subject-key-id", {
+                            describe: "Subject Key ID of the certificate",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { subjectKeyId } = argv;
+                        // Normalize subject key ID by removing colons
+                        const normalizedId = subjectKeyId.replace(/:/g, "").toUpperCase();
+
+                        await theNode.start();
+                        const pemCert = await theNode.certificateService.getCertificateAsPem(normalizedId);
+                        console.log(pemCert);
+                    },
+                )
+                .command(
+                    "delete <subject-key-id>",
+                    "Deletes a certificate from the storage",
+                    yargs => {
+                        return yargs.positional("subject-key-id", {
+                            describe: "Subject Key ID of the certificate to delete",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { subjectKeyId } = argv;
+                        // Normalize subject key ID by removing colons
+                        const normalizedId = subjectKeyId.replace(/:/g, "").toUpperCase();
+
+                        await theNode.start();
+                        await theNode.certificateService.deleteCertificate(normalizedId);
+                        console.log(`Certificate ${subjectKeyId} deleted successfully`);
+                    },
+                )
+                .command(
+                    "update",
+                    "Update certificates from DCL",
+                    yargs =>
+                        yargs.option("force", {
+                            describe: "Force re-download and overwrite existing certificates",
+                            type: "boolean",
+                            default: false,
+                        }),
+                    async argv => {
+                        const { force } = argv;
+                        await theNode.start();
+
+                        console.log(`Updating certificates from DCL${force ? " (force mode)" : ""}...`);
+                        await theNode.certificateService.update(force);
+                        console.log("Certificate update completed successfully");
+
+                        const count = theNode.certificateService.certificates.length;
+                        console.log(`Total certificates in storage: ${count}`);
+                    },
+                ),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/shell/cmd_config.ts

@@ -5,6 +5,7 @@
  */
 
 import { Logger } from "#general";
+import { DclCertificateService } from "@matter/protocol";
 import { Argv } from "yargs";
 import { MatterNode } from "../MatterNode";
 import { setLogLevel } from "../app";
@@ -220,7 +221,42 @@ export default function commands(theNode: MatterNode) {
                             },
                             argv => doThreadCredentials(theNode, { action: "set", ...argv }),
                         );
-                }),
+                })
+
+                // DCL Test Certificates
+                .command(
+                    "dcl-test-certificates",
+                    "Manage DCL test certificate fetching (production only vs. include test)",
+                    yargs => {
+                        return yargs
+                            .command(
+                                "* [action]",
+                                "get/delete DCL test certificate setting",
+                                yargs => {
+                                    return yargs.positional("action", {
+                                        describe: "get/delete",
+                                        choices: ["get", "delete"] as const,
+                                        default: "get",
+                                        type: "string",
+                                    });
+                                },
+                                async argv => doDclTestCertificates(theNode, argv),
+                            )
+                            .command(
+                                "set <value>",
+                                "Enable or disable test certificate fetching from DCL",
+                                yargs => {
+                                    return yargs.positional("value", {
+                                        describe: "Enable test certificates (true/false)",
+                                        type: "string",
+                                        choices: ["true", "false"] as const,
+                                        demandOption: true,
+                                    });
+                                },
+                                async argv => doDclTestCertificates(theNode, { action: "set", ...argv }),
+                            );
+                    },
+                ),
         handler: async (argv: any) => {
             argv.unhandled = true;
         },
@@ -424,3 +460,46 @@ async function doThreadCredentials(
             break;
     }
 }
+
+async function doDclTestCertificates(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        value?: string;
+    },
+) {
+    const { action, value } = args;
+    switch (action) {
+        case "get":
+            const enabled = await theNode.Store.get<boolean>("DclFetchTestCertificates", false);
+            console.log(
+                `DCL test certificates: ${enabled ? "enabled (production + test + GitHub)" : "disabled (production only)"}`,
+            );
+            break;
+        case "set":
+            if (value === undefined) {
+                console.log(`Cannot change DCL test certificates setting: New value not provided`);
+                return;
+            }
+            const newValue = value === "true";
+            await theNode.Store.set("DclFetchTestCertificates", newValue);
+
+            // Close existing certificate service so it gets re-initialized with new setting
+            await theNode.environment.close(DclCertificateService);
+
+            console.log(
+                `DCL test certificates: ${newValue ? "enabled (production + test + GitHub)" : "disabled (production only)"}. Please restart the shell for the changes to take effect.`,
+            );
+            break;
+        case "delete":
+            await theNode.Store.delete("DclFetchTestCertificates");
+
+            // Close existing certificate service so it gets re-initialized with new setting
+            await theNode.environment.close(DclCertificateService);
+
+            console.log(
+                `DCL test certificates setting reset to default (disabled). Please restart the shell for the changes to take effect.`,
+            );
+            break;
+    }
+}

package/src/shell/cmd_dcl.ts

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "#general";
+import { DclClient } from "@matter/protocol";
+import type { Argv } from "yargs";
+
+/**
+ * Parse a VID or PID from string (supports decimal or hex with 0x prefix)
+ */
+function parseVidPid(value: string, fieldName: string): number {
+    const num = value.startsWith("0x") ? parseInt(value, 16) : parseInt(value, 10);
+    if (isNaN(num) || num < 0 || num > 0xffff) {
+        throw new Error(`${fieldName} must be a valid 16-bit number`);
+    }
+    return num;
+}
+
+/**
+ * Get DCL environment description
+ */
+function getDclEnv(isTest: boolean): string {
+    return isTest ? "test" : "production";
+}
+
+/**
+ * Create yargs positional argument configuration for VID
+ */
+function vidPositional() {
+    return {
+        describe: "Vendor ID (decimal or hex with 0x prefix)",
+        type: "string" as const,
+        demandOption: true,
+        coerce: (value: string) => parseVidPid(value, "VID"),
+    };
+}
+
+/**
+ * Create yargs positional argument configuration for PID
+ */
+function pidPositional() {
+    return {
+        describe: "Product ID (decimal or hex with 0x prefix)",
+        type: "string" as const,
+        demandOption: true,
+        coerce: (value: string) => parseVidPid(value, "PID"),
+    };
+}
+
+/**
+ * DCL (Distributed Compliance Ledger) query commands
+ *
+ * These commands allow querying the CSA DCL for Matter compliance information,
+ * including root certificates, device models, and firmware versions.
+ */
+export default function commands() {
+    return {
+        command: "dcl",
+        describe: "Query the CSA Distributed Compliance Ledger (DCL) for Matter compliance information",
+        builder: (yargs: Argv) =>
+            yargs
+                .option("test", {
+                    alias: "t",
+                    describe: "Use test DCL network instead of production",
+                    type: "boolean",
+                    default: false,
+                    global: true,
+                })
+                .command(
+                    "fetch-root-certificates",
+                    "Fetch list of all approved Product Attestation Authority (PAA) root certificates",
+                    yargs => yargs,
+                    async argv => {
+                        const { test } = argv;
+                        const client = new DclClient(!test);
+
+                        try {
+                            console.log(`Fetching root certificate list from ${getDclEnv(test)} DCL...`);
+                            const certificates = await client.fetchRootCertificateList();
+                            console.log(`Found ${certificates.length} root certificates:`);
+                            console.log(JSON.stringify(certificates, null, 2));
+                        } catch (error) {
+                            console.error("Error fetching root certificates:", error);
+                        }
+                    },
+                )
+                .command(
+                    "fetch-root-certificate <subject> <subjectKeyId>",
+                    "Fetch detailed information for a specific root certificate",
+                    yargs => {
+                        return yargs
+                            .positional("subject", {
+                                describe: "Certificate subject (DN)",
+                                type: "string",
+                                demandOption: true,
+                            })
+                            .positional("subjectKeyId", {
+                                describe: "Subject key identifier",
+                                type: "string",
+                                demandOption: true,
+                            });
+                    },
+                    async argv => {
+                        const { subject, subjectKeyId, test } = argv;
+                        const client = new DclClient(!test);
+
+                        try {
+                            console.log(`Fetching certificate details from ${getDclEnv(test)} DCL...`);
+                            console.log(`Subject: ${subject}`);
+                            console.log(`Subject Key ID: ${subjectKeyId}`);
+
+                            const certificate = await client.fetchRootCertificateBySubject({
+                                subject,
+                                subjectKeyId,
+                            });
+                            console.log("Certificate details:");
+                            console.log(JSON.stringify(certificate, null, 2));
+                        } catch (error) {
+                            console.error("Error fetching certificate:", error);
+                        }
+                    },
+                )
+                .command(
+                    "fetch-model <vid> <pid>",
+                    "Fetch device model information by Vendor ID and Product ID",
+                    yargs => {
+                        return yargs.positional("vid", vidPositional()).positional("pid", pidPositional());
+                    },
+                    async argv => {
+                        const { vid, pid, test } = argv;
+                        if (vid === undefined || pid === undefined) {
+                            throw new Error("VID and PID are required");
+                        }
+                        const client = new DclClient(!test);
+
+                        try {
+                            console.log(`Fetching model information from ${getDclEnv(test)} DCL...`);
+                            console.log(`VID: ${Diagnostic.hex(vid, 4)}`);
+                            console.log(`PID: ${Diagnostic.hex(pid, 4)}`);
+
+                            const model = await client.fetchModelByVidPid(vid, pid);
+                            console.log("Device model information:");
+                            console.log(JSON.stringify(model, null, 2));
+                        } catch (error) {
+                            console.error("Error fetching model:", error);
+                        }
+                    },
+                )
+                .command(
+                    "fetch-model-versions <vid> <pid>",
+                    "Fetch available software versions for a device model",
+                    yargs => {
+                        return yargs.positional("vid", vidPositional()).positional("pid", pidPositional());
+                    },
+                    async argv => {
+                        const { vid, pid, test } = argv;
+                        if (vid === undefined || pid === undefined) {
+                            throw new Error("VID and PID are required");
+                        }
+                        const client = new DclClient(!test);
+
+                        try {
+                            console.log(`Fetching available versions from ${getDclEnv(test)} DCL...`);
+                            console.log(`VID: ${Diagnostic.hex(vid, 4)}`);
+                            console.log(`PID: ${Diagnostic.hex(pid, 4)}`);
+
+                            const versions = await client.fetchModelVersionsByVidPid(vid, pid);
+                            console.log(`Found ${versions.length} software version(s):`);
+                            console.log(JSON.stringify(versions, null, 2));
+                        } catch (error) {
+                            console.error("Error fetching versions:", error);
+                        }
+                    },
+                )
+                .command(
+                    "fetch-model-version <vid> <pid> <softwareVersion>",
+                    "Fetch detailed information for a specific software version",
+                    yargs => {
+                        return yargs
+                            .positional("vid", vidPositional())
+                            .positional("pid", pidPositional())
+                            .positional("softwareVersion", {
+                                describe: "Software version number",
+                                type: "number",
+                                demandOption: true,
+                            });
+                    },
+                    async argv => {
+                        const { vid, pid, softwareVersion, test } = argv;
+                        if (vid === undefined || pid === undefined || softwareVersion === undefined) {
+                            throw new Error("VID, PID, and software version are required");
+                        }
+                        const client = new DclClient(!test);
+
+                        try {
+                            console.log(`Fetching version details from ${getDclEnv(test)} DCL...`);
+                            console.log(`VID: ${Diagnostic.hex(vid, 4)}`);
+                            console.log(`PID: ${Diagnostic.hex(pid, 4)}`);
+                            console.log(`Software Version: ${softwareVersion}`);
+
+                            const versionInfo = await client.fetchModelVersionByVidPidSoftwareVersion(
+                                vid,
+                                pid,
+                                softwareVersion,
+                            );
+                            console.log("Software version information:");
+                            console.log(JSON.stringify(versionInfo, null, 2));
+                        } catch (error) {
+                            console.error("Error fetching version details:", error);
+                        }
+                    },
+                )
+                .demandCommand(1, "You must specify a DCL query command"),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}