/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { CommissionableDevice } from "#common/Scanner.js"; import { NodeSession } from "#session/NodeSession.js"; import { Duration, ServerAddress } from "@matter/general"; /** * Attempts PASE establishment with the provided device candidates, returning the first successful session. * * All candidates come from {@link CommissioningConnection.Options.devices}, in their order, one PASE attempt per * (device, address). This is used when addresses are already known (e.g. from a prior mDNS discovery or a * pre-configured address list). * * The first candidate launches immediately. The next one launches once the latest attempt has settled or has run * for {@link DELAY_BEFORE_NEXT_ADDRESS}, but never while an attempt holds its responder, i.e. has received the * PBKDFParamResponse. The CHIP SDK responder binds its single PASESession to the first PBKDFParamRequest exchange, * and a request on another exchange clears the handshake in progress, so addresses of one device (e.g. IPv6 ULA + * link-local + IPv4) must not be raced. An older, unanswered attempt may still run when a newer one starts. * * If an attempt fails with a {@link PasscodeMismatchError} the device is permanently dropped and its queued addresses * are skipped. If it fails with another `UnexpectedDataError` or a transient network/timeout error, the remaining * addresses are still tried. Any other error ends the whole process. The process completes when one session is * established, all candidates are exhausted, or the overall timeout fires. * * When the first PASE session is established the abort signal passed to * {@link CommissioningConnection.Options.establishSession} fires on all remaining in-flight attempts, allowing * them to cancel cleanly (e.g. by sending an InvalidParam status to the device to prevent a 60-second pairing * lockout). */ export declare function CommissioningConnection(options: CommissioningConnection.Options): Promise; export declare namespace CommissioningConnection { interface Options { /** * Commissioning candidates to attempt PASE with. * * Each address of a device becomes one `(device, address)` attempt, in the given order, and attempts launch * one after the other across all devices (see {@link CommissioningConnection}). A credential failure drops * every attempt whose device has the same `deviceIdentifier`. * * Callers that discover genuinely distinct devices should coordinate fan-out at a higher layer * (e.g. {@link ParallelPaseDiscovery}); passing multiple distinct devices here serialises them too, which is * usually not what you want for a multi-device race. */ devices: CommissionableDevice[]; /** Overall timeout for the entire connection attempt. */ timeout: Duration; /** * Establishes a PASE session for the given candidate. */ establishSession: (address: ServerAddress, device: CommissionableDevice, context: EstablishSessionContext) => Promise; /** * An external abort signal. When fired, terminates all in-flight PASE attempts immediately. */ externalAbort?: AbortSignal; /** * How long the latest attempt runs before the next candidate starts, unless it settles first. Defaults to * the internal 10s production value. Exposed primarily for tests that need to disable or shorten it; * production callers should not override this. */ delayBeforeNextAddress?: Duration; } interface EstablishSessionContext { /** * Fires when the overall timeout expires or when another candidate wins the race first. Implementations * should respect it and abort cleanly (e.g. by sending an InvalidParam status to prevent a 60-second device * lockout). */ signal: AbortSignal; /** Call once the PBKDFParamResponse has arrived; no further candidate launches until this attempt settles. */ onPbkdfParamResponse: () => void; } interface Result { session: NodeSession; discoveryData: CommissionableDevice; } } //# sourceMappingURL=CommissioningConnection.d.ts.map