/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { ClientInteraction } from "#action/client/ClientInteraction.js"; import { Bytes } from "@matter/general"; import { ClusterId, ClusterType, EndpointNumber, FabricIndex, NodeId, VendorId } from "@matter/types"; import { GeneralCommissioning } from "@matter/types/clusters/general-commissioning"; import { NetworkCommissioning } from "@matter/types/clusters/network-commissioning"; import { CertificateAuthority } from "../certificate/CertificateAuthority.js"; import { DeviceAttestationValidator } from "../certificate/DeviceAttestationValidator.js"; import { DclCertificateService } from "../dcl/DclCertificateService.js"; import { Fabric } from "../fabric/Fabric.js"; import { CommissioningError } from "./CommissioningError.js"; import { PeerAddress } from "./PeerAddress.js"; export interface OtaProviderLocation { nodeId: NodeId; endpoint: EndpointNumber; } /** * User specific options for the Commissioning process */ export type ControllerCommissioningFlowOptions = { /** * The regulatory location (indoor or outdoor) where the device is used. */ regulatoryLocation: GeneralCommissioning.RegulatoryLocationType; /** * The country where the device is used. */ regulatoryCountryCode: string; /** * The vendor ID we present as a commissioner. */ adminVendorId?: VendorId; /** * Required credentials if the device is to connect to a wifi network provide the credentials here. */ wifiNetwork?: { wifiSsid: string; wifiCredentials: string; }; /** * If the device should connect to a thread network. */ threadNetwork?: { networkName?: string; operationalDataset: string; }; /** The Location of the OTA provider for this fabric set on the commissioned devices if OTA is supported */ otaUpdateProviderLocation?: OtaProviderLocation; /** * Attestation validation settings. Injected by ControllerCommissioner — the only user-facing * part is `onFailure` which is forwarded from CommissioningClient options. */ attestation: { /** Attestation challenge key from the PASE session, used to verify attestation and CSR signatures. */ challengeKey: Bytes; /** DclCertificateService for PAA trust store and revocation checks. Looked up from environment. */ dclCertificateService?: DclCertificateService; /** * Controls behavior when attestation produces findings. * - `false`: reject on any finding * - `true`: always accept with info logging * - callback: receives `AttestationFinding[]` and decides the outcome; may * - return `true` to proceed * - return `false` to reject with the underlying error * - return a `string` to reject with a new {@link CommissioningError} whose message is * that string and whose `cause` is the underlying error * - throw any error to reject by rethrowing that error verbatim (no wrapping) * - `undefined`: accept with warning logging (backward compatibility) * * The callback receives either: * - A single error-level finding for hard failures (invalid chain, bad signature, revoked * certificate, untrusted PAA, DCL service unavailable). The commissioner must decide * whether to proceed despite the failure. * - One or more warning/info-level findings after successful validation (e.g. provisional * CD, test CD, skipped CD signer verification, no revocation data, test-cert-only PAA). * These are informational and the commissioner can inspect them for detailed decisions. * * TODO: Make required in next breaking version and remove undefined backward-compatible accept */ onFailure?: DeviceAttestationValidator.OnAttestationFailure; }; }; /** Result code of a single commissioning step. */ declare enum CommissioningStepResultCode { Success = 0, Failure = 1, Skipped = 2, Stop = 3 } /** * Result of a single commissioning step * Breadcrump value is stored for each step for transparency */ type CommissioningStepResult = { code: CommissioningStepResultCode; breadcrumb: number; }; /** * Definition of one commissioning step * All steps are for execution sorted by stepNumber and subStepNumber */ type CommissioningStep = { /** Step Number according to the specs */ stepNumber: number; /** Order of actions within a step */ subStepNumber: number; /** Name of the action or step */ name: string; /** Logic function to execute */ stepLogic: () => Promise; /** Optional flag to indicate that the failsafe timer should be rearmed in any case before this step. */ reArmFailsafe?: boolean; }; /** Data that are collected initially or through the commissioning process and can be used also by other steps. */ type CollectedCommissioningData = { basicCommissioningInfo?: GeneralCommissioning.BasicCommissioningInfo; productName?: string; networkFeatures?: { endpointId: EndpointNumber; value: ClusterType.FeaturesOf; }[]; networkStatus?: { endpointId: EndpointNumber; value: NetworkCommissioning.NetworkInfo[]; }[]; otaRequestorList?: EndpointNumber[]; rootPartsList?: EndpointNumber[]; rootServerList?: ClusterId[]; vendorId?: VendorId; productId?: number; supportsConcurrentConnection?: boolean; successfullyConnectedToNetwork?: boolean; fabricIndex?: FabricIndex; }; /** The number of fabrics that can be commissioned is already reached. */ export declare class MaximumCommissionedFabricsReachedError extends CommissioningError { } /** The commissioning process could not be finished within the maximum allowed commissioning timeframe. */ export declare class CommissioningTimeoutError extends CommissioningError { } /** Error that throws when the device is already commissioned to this fabric. */ export declare class DeviceAlreadyCommissionedToThisFabricError extends CommissioningError { } /** Error that throws when the device is already commissioned to another fabric with the same label. */ export declare class FabricLabelConflictError extends CommissioningError { } /** Error that throws when the device has no connected network and no credentials for Wifi or Thread network were configured. */ export declare class WifiOrThreadNetworkCredentialsNotConfiguredError extends CommissioningError { } /** Error that throws when the setup for the provided Wifi network failed. */ export declare class WifiNetworkSetupFailedError extends CommissioningError { } /** Error that throws when the setup for the provided Thread network failed. */ export declare class ThreadNetworkSetupFailedError extends CommissioningError { } /** Error that throws when the NodeId is already used in the fabric. */ export declare class NodeIdConflictError extends CommissioningError { } /** Error that throws when the device could not be connected using the operational discovery and no session could be created. */ export declare class OperativeConnectionFailedError extends CommissioningError { } /** Error that throws when a supplied Thread network name contradicts the name inside the operational dataset. */ export declare class ThreadNetworkNameMismatchError extends CommissioningError { } /** * Resolve the Thread network name to commission with. * * Derives the name from the operational dataset when the caller omitted it, and verifies a caller-supplied name against * the dataset — declining on mismatch so an ambiguous credential set cannot silently commission the wrong network. A * dataset that cannot be decoded is left to the device to reject; the supplied name is kept as-is. */ export declare function resolveThreadNetworkName(threadNetwork: { networkName?: string; operationalDataset: string; }): string | undefined; /** * Class to abstract the Device commission flow in a step wise way as defined in Specs. The specs are not 100% */ export declare class ControllerCommissioningFlow { #private; protected interaction: ClientInteraction; protected readonly ca: CertificateAuthority; protected readonly fabric: Fabric; protected readonly transitionToCase: (peerAddress: PeerAddress, supportsConcurrentConnections: boolean) => Promise; protected readonly commissioningOptions: ControllerCommissioningFlowOptions; protected readonly commissioningSteps: CommissioningStep[]; protected readonly commissioningStepResults: Map; protected lastBreadcrumb: number; protected collectedCommissioningData: CollectedCommissioningData; constructor( /** ClientInteraction for the initiated PASE session */ interaction: ClientInteraction, /** CertificateAuthority of the controller. */ ca: CertificateAuthority, /** Fabric of the controller. */ fabric: Fabric, /** Commissioning options for the commissioning process. */ commissioningOptions: ControllerCommissioningFlowOptions, /** Callback that establishes CASE connection or handles final commissioning */ transitionToCase: (peerAddress: PeerAddress, supportsConcurrentConnections: boolean) => Promise); [Symbol.asyncDispose](): Promise; /** * Fabric index assigned to our identity by the peer device, captured from the AddNoc response. Defined * after `executeCommissioning()` resolves successfully. */ get fabricIndexOnPeer(): FabricIndex | undefined; /** * Execute the commissioning process in the defined order. The steps are sorted before execution based on the step * number and sub step number. * If >50% of the failsafe time has passed, the failsafe timer is re-armed (50% of 60s default are 30s and each * action is allowed to take 30s at minimum based on specs). */ executeCommissioning(): Promise; getCommissioningStepResult(stepNumber: number, subStepNumber: number): CommissioningStepResult | undefined; close(): void; } export {}; //# sourceMappingURL=ControllerCommissioningFlow.d.ts.map