/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { CertificateAuthority } from "#certificate/CertificateAuthority.js"; import { DeviceAttestationValidator } from "#certificate/DeviceAttestationValidator.js"; import { DiscoveryData } from "#common/Scanner.js"; import { Fabric } from "#fabric/Fabric.js"; import { ControllerCommissioningFlow, ControllerCommissioningFlowOptions } from "#peer/ControllerCommissioningFlow.js"; import { ExchangeManager } from "#protocol/ExchangeManager.js"; import { NodeSession } from "#session/NodeSession.js"; import { SessionManager } from "#session/SessionManager.js"; import { SessionParameters } from "#session/SessionParameters.js"; import { ClassExtends, Duration, Environment, Environmental, MaybePromise, ServerAddress, TransportSet } from "@matter/general"; import { FabricIndex, NodeId } from "@matter/types"; import { PeerAddress } from "./PeerAddress.js"; import { PeerSet } from "./PeerSet.js"; import { PeerTimingParameters } from "./PeerTimingParameters.js"; /** * General commissioning options. */ export interface CommissioningOptions extends Partial { /** Controls behavior when device attestation produces findings. */ onAttestationFailure?: DeviceAttestationValidator.OnAttestationFailure; /** The fabric into which to commission. */ fabric: Fabric; /** The node ID to assign (the commissioner assigns a random node ID if omitted) */ nodeId?: NodeId; /** Passcode to use for commissioning. */ passcode: number; /** * Commissioning completion callback * * This optional callback allows the caller to complete commissioning once PASE commissioning completes. If it does * not throw, the commissioner considers commissioning complete. `sessionParameters` are those the device reported * over PASE; whoever establishes the operational CASE session should use them. */ finalizeCommissioning?: (peerAddress: PeerAddress, discoveryData?: DiscoveryData, sessionParameters?: Partial) => MaybePromise; /** * Commissioning Flow Implementation as class that extends the official implementation to use for commissioning. * Defaults to the matter.js default implementation {@link ControllerCommissioningFlow}. */ commissioningFlowImpl?: ClassExtends; /** * Timing overrides for the step-18 CASE reconnect. * * After commissioning completes, the commissioner establishes the first operational CASE session. The device is * known to be freshly online at this point, so tighter timing is appropriate. Any fields provided here are merged * on top of the global {@link PeerSet.timing} for that single connection only. */ caseConnectionTiming?: Partial; /** * Wall-clock budget for the step-18 CASE reconnect, across every candidate address and retry. * * Defaults to {@link DEFAULT_CASE_CONNECTION_TIMEOUT}. Lower it to bound commissioning to a single handshake * attempt, so a handshake the device fails is a commissioning failure rather than something a retry can recover. * * On an IP transport, raising it past the failsafe armed for this step (`ControllerCommissioningFlow` allows up to * 5 minutes for the reconnect, clamped by the device's own `MaxCumulativeFailsafeSeconds`) has the device roll * `addNOC` back mid-connect, so a longer budget cannot succeed. The concurrent BLE flow keeps re-arming instead. * * Expiry fails commissioning, which deletes the peer and so aborts the connection it was still attempting. The * rejection therefore reports a budget that ran out, not what the device answered. No effect where * {@link finalizeCommissioning} owns the operational step instead. */ caseConnectionTimeout?: Duration; } /** * 4m15s allows two ~2-minute server-side retry windows to complete before we abort. */ export declare const DEFAULT_CASE_CONNECTION_TIMEOUT: Duration; /** * {@link DiscoveryData} of a device to commission. A non-empty `deviceIdentifier` marks the addresses as those of one * discovered device instance, so a wrong passcode on one of them stops the attempts on the others. */ export type CommissioningDiscoveryData = DiscoveryData & { deviceIdentifier?: string; }; /** * Configuration for commissioning a previously discovered node. */ export interface LocatedNodeCommissioningOptions extends CommissioningOptions { /** * Addresses of the one node to commission. They are tried one after the other, ordered by * {@link ServerAddressSet.compareDesirability} (see {@link CommissioningConnection}). */ addresses: ServerAddress[]; /** Discovery metadata of the device. */ discoveryData?: CommissioningDiscoveryData; /** * Overall wall-clock budget for PASE establishment across all candidate addresses. * Defaults to 30 seconds. */ timeout?: Duration; /** * Abort signal for cancellation. When fired during PASE establishment, cancels the attempt. * In parallel commissioning scenarios this is used to cancel other candidates once one wins. */ abort?: AbortSignal; /** * Called immediately after PASE is established, before the main commissioning flow begins. * * Returns the {@link NodeId} to assign this device, reserved at win-time so the operational identity is * claimed only once a candidate has won the PASE race. Returns `undefined` to abort — the PASE session is * closed and commissioning is skipped. * * This is the hook used by {@link CommissioningDiscovery} for multi-candidate parallel flows: the first * candidate to establish PASE claims and returns its node ID (and signals the others via {@link abort} to * stop). Any candidate that establishes PASE after another has already won returns `undefined` here and * cleans up. In the single-device located-node path this callback is unnecessary; provide {@link nodeId} * (or leave it undefined for an automatically assigned ID) instead. */ claimNodeIdAfterPase?: () => MaybePromise; } /** * Options for establishing a PASE session with a device whose address(es) are already known. * * Use this when you have at least one address for the device (from a prior discovery, a QR code, or a * pre-configured address). For pure mDNS/BLE discovery without known addresses, use {@link PaseDiscovery}. */ export interface EstablishPaseOptions { /** * One or more addresses at which the device may be reached. They are tried one after the other, ordered by * {@link ServerAddressSet.compareDesirability} (see {@link CommissioningConnection}). */ addresses: ServerAddress[]; /** Discovery metadata of the device. */ discoveryData?: CommissioningDiscoveryData; /** PASE passcode for the device. */ passcode: number; /** Overall timeout for PASE establishment across all addresses. Defaults to 30 seconds. */ timeout?: Duration; /** External abort signal that, when fired, cancels all in-flight PASE attempts. */ abort?: AbortSignal; /** * Atomic gate for parallel PASE racing. * * Called immediately after PASE is established (before any further work). Return `true` to claim this * PASE session as the winner. Return `false` if another candidate already won — this session is closed * cleanly without proceeding. * * When omitted, the first successful PASE session is always accepted. */ continueAfterPase?: () => boolean; } /** Result returned by {@link ControllerCommissioner.establishPase}. */ export interface EstablishPaseResult { paseSession: NodeSession; discoveryData?: DiscoveryData; } /** * Interfaces {@link ControllerCommissioner} with other components. */ export interface ControllerCommissionerContext { peers: PeerSet; transports: TransportSet; sessions: SessionManager; exchanges: ExchangeManager; ca: CertificateAuthority; environment: Environment; } /** * Commissions other nodes onto a fabric. */ export declare class ControllerCommissioner { #private; constructor(context: ControllerCommissionerContext); static [Environmental.create](env: Environment): ControllerCommissioner; /** * Commission a previously discovered node. */ commission(options: LocatedNodeCommissioningOptions): Promise; /** * Establishes a PASE session with a known device without running a commissioning flow. * * The addresses are tried one after the other, most desirable first (see {@link EstablishPaseOptions.addresses}). * The first to complete PASE wins; the rest are cancelled via an abort signal. A wrong passcode * (`PasscodeMismatchError`) stops the remaining addresses when they belong to one discovered device (see * {@link EstablishPaseOptions.discoveryData}); otherwise it fails only the address it occurred on. */ establishPase(options: EstablishPaseOptions): Promise; } /** Result of a successful commissioning operation. */ export interface CommissionResult { /** Controller-side {@link PeerAddress} (interned). */ address: PeerAddress; /** Fabric index the peer assigned to our identity, from the AddNoc response. */ fabricIndexOnPeer?: FabricIndex; } //# sourceMappingURL=ControllerCommissioner.d.ts.map