PairingCommand.cpp

/*
 *   Copyright (c) 2020-2024 Project CHIP Authors
 *   All rights reserved.
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 */

#include "PairingCommand.h"
#include <commands/common/DeviceScanner.h>
#include <controller/ExampleOperationalCredentialsIssuer.h>
#include <crypto/CHIPCryptoPAL.h>
#include <inet/IPAddress.h>
#include <inet/InetInterface.h>
#include <lib/core/CHIPEncoding.h>
#include <lib/core/CHIPError.h>
#include <lib/core/CHIPSafeCasts.h>
#include <lib/dnssd/Types.h>
#include <lib/support/BytesToHex.h>
#include <lib/support/CHIPMemString.h>
#include <lib/support/CodeUtils.h>
#include <lib/support/Span.h>
#include <lib/support/ThreadDiscoveryCode.h>
#include <lib/support/ThreadOperationalDataset.h>
#include <lib/support/logging/CHIPLogging.h>
#include <protocols/secure_channel/PASESession.h>

#include <setup_payload/ManualSetupPayloadParser.h>
#include <setup_payload/QRCodeSetupPayloadParser.h>

#include "../dcl/DCLClient.h"
#include "../dcl/DisplayTermsAndConditions.h"

#include <algorithm>
#include <app/CommandSender.h>
#include <app/InteractionModelEngine.h>
#include <app/data-model/Encode.h>
#include <clusters/CommissioningProxy/Commands.h>
#include <inttypes.h>
#include <iostream>
#include <memory>
#include <netdb.h>
#include <netinet/in.h>
#include <string>
#include <sys/socket.h>

using namespace ::chip;
using namespace ::chip::Controller;

namespace {

// Endpoint used for the CommissioningProxy cluster when --proxy-endpoint is not given.
constexpr chip::EndpointId kDefaultProxyEndpointId = 1;

// Endpoint used for the Network Identity Management cluster when --pdc-netim-endpoint-id is not given.
constexpr chip::EndpointId kDefaultNETIMEndpointId = 1;

bool IsNoPasswordMarker(chip::ByteSpan password)
{
    // Use a one-character marker value (which is invalid in every supported Wi-Fi password encoding)
    // to signal that no password is to be used. An empty string, which would otherwise be the more
    // obvious choice, is used by the Network Commissioning Cluster to represent an open network.
    return password.data_equal(ByteSpan::fromCharSpan("-"_span));
}

// Upper bound on back-to-back null-Message polls that yield a message but no reply.
// A conformant proxy drains in a handful; the bound only stops a misbehaving one from
// spinning the commissioner.
constexpr uint8_t kMaxConsecutiveProxyPolls = 8;

[[maybe_unused]] CHIP_ERROR ParseSetupPayload(SetupPayload & setupPayload, const char * onboardingPayload)
{

    bool isQRCode = strncmp(onboardingPayload, kQRCodePrefix, strlen(kQRCodePrefix)) == 0;
    if (isQRCode)
    {
        ReturnErrorOnFailure(QRCodeSetupPayloadParser(onboardingPayload).populatePayload(setupPayload));
        VerifyOrReturnError(setupPayload.isValidQRCodePayload(), CHIP_ERROR_INVALID_ARGUMENT);
    }
    else
    {
        ReturnErrorOnFailure(ManualSetupPayloadParser(onboardingPayload).populatePayload(setupPayload));
        VerifyOrReturnError(setupPayload.isValidManualCode(), CHIP_ERROR_INVALID_ARGUMENT);
    }
    return CHIP_NO_ERROR;
}

class DeviceDiscoveryDelegateRegistry
{
public:
    DeviceDiscoveryDelegateRegistry() = delete;
    DeviceDiscoveryDelegateRegistry(DeviceController & controller, DeviceDiscoveryDelegate * delegate) : mController(controller)
    {
        mController.RegisterDeviceDiscoveryDelegate(delegate);
    }
    ~DeviceDiscoveryDelegateRegistry() { mController.RegisterDeviceDiscoveryDelegate(nullptr); }

private:
    DeviceController & mController;
};

} // namespace

CHIP_ERROR PairingCommand::RunCommand()
{
    CurrentCommissioner().RegisterPairingDelegate(this);
    // Clear the CATs in OperationalCredentialsIssuer
    mCredIssuerCmds->SetCredentialIssuerCATValues(kUndefinedCATs);

    mDeviceIsICD = false;

    if (mPDCRegistrarNodeId.HasValue())
    {
        mPDCRegistrar.emplace(CurrentCommissioner(), mPDCRegistrarNodeId.Value(),
                              mPDCRegistrarEndpointId.ValueOr(kDefaultNETIMEndpointId));
    }
    else if (IsNoPasswordMarker(mPassword))
    {
        ChipLogError(chipTool, "Either a password (or '') or --pdc-netim-node-id is required");
        return CHIP_ERROR_INVALID_ARGUMENT;
    }

    if (mCASEAuthTags.HasValue() && mCASEAuthTags.Value().size() <= kMaxSubjectCATAttributeCount)
    {
        CATValues cats = kUndefinedCATs;
        for (size_t index = 0; index < mCASEAuthTags.Value().size(); ++index)
        {
            cats.values[index] = mCASEAuthTags.Value()[index];
        }
        if (cats.AreValid())
        {
            mCredIssuerCmds->SetCredentialIssuerCATValues(cats);
        }
    }
    return RunInternal(mNodeId);
}

CHIP_ERROR PairingCommand::RunInternal(NodeId remoteId)
{
    CHIP_ERROR err = CHIP_NO_ERROR;

    switch (mPairingMode)
    {
    case PairingMode::None:
        err = Unpair(remoteId);
        break;
    case PairingMode::Code:
#if CHIP_DEVICE_CONFIG_ENABLE_WIFIPAF
        chip::DeviceLayer::ConnectivityMgr().WiFiPafSetApFreq(
            mApFreqStr.HasValue() ? static_cast<uint16_t>(std::stol(mApFreqStr.Value())) : 0);
#endif
        err = PairWithCode(remoteId);
        break;
    case PairingMode::CodePaseOnly:
        err = PaseWithCode(remoteId);
        break;
    case PairingMode::Ble:
        err = Pair(remoteId, PeerAddress::BLE());
        break;
    case PairingMode::Nfc:
        if (mDiscriminator.has_value())
        {
            err = Pair(remoteId, PeerAddress::NFC(mDiscriminator.value()));
        }
        else
        {
            // Discriminator is mandatory
            err = CHIP_ERROR_MESSAGE_INCOMPLETE;
        }
        break;
    case PairingMode::OnNetwork:
        err = PairWithMdns(remoteId);
        break;
    case PairingMode::SoftAP:
        err = Pair(remoteId, PeerAddress::UDP(mRemoteAddr.address, mRemotePort, mRemoteAddr.interfaceId));
        break;
#if CHIP_DEVICE_CONFIG_ENABLE_WIFIPAF
    case PairingMode::WiFiPAF:
        chip::DeviceLayer::ConnectivityMgr().WiFiPafSetApFreq(
            mApFreqStr.HasValue() ? static_cast<uint16_t>(std::stol(mApFreqStr.Value())) : 0);
        err = Pair(remoteId, PeerAddress::WiFiPAF(remoteId));
        break;
#endif
#if CHIP_SUPPORT_THREAD_MESHCOP
    case PairingMode::ThreadMeshcop: {
        Inet::IPAddress ipAddr;

        VerifyOrReturnError(mThreadBaHost.HasValue(), CHIP_ERROR_INVALID_ARGUMENT);
        VerifyOrReturnError(mThreadBaPort.HasValue(), CHIP_ERROR_INVALID_ARGUMENT);
        VerifyOrReturnError(Inet::IPAddress::FromString(mThreadBaHost.Value(), ipAddr), CHIP_ERROR_INVALID_ADDRESS);
        err = Pair(remoteId, PeerAddress::ThreadMeshcop(ipAddr, mThreadBaPort.Value()));
        break;
    }
#endif
    case PairingMode::AlreadyDiscovered:
        err = Pair(remoteId, PeerAddress::UDP(mRemoteAddr.address, mRemotePort, mRemoteAddr.interfaceId));
        break;
    case PairingMode::AlreadyDiscoveredByIndex:
        err = PairWithMdnsOrBleByIndex(remoteId, mIndex);
        break;
    case PairingMode::AlreadyDiscoveredByIndexWithCode:
        err = PairWithMdnsOrBleByIndexWithCode(remoteId, mIndex);
        break;
    case PairingMode::Proxy:
        err = PairViaProxy(remoteId);
        break;
    }

    return err;
}

void PairingCommand::Shutdown()
{
    if (mPDCRegistrar.has_value())
    {
        // Release the registrar before ResetArguments() invalidates the arguments it was built from.
        // Stop the pairing first, as the NetworkIdentityRegistrar contract requires: this run may have
        // ended on a timeout, with commissioning still under way and the commissioner still pointing at
        // the registrar. An error just means there was nothing left to stop.
        RETURN_SAFELY_IGNORED CurrentCommissioner().StopPairing(mNodeId);

        // Drop the idle notification before releasing the registrar: destroying it aborts whatever
        // is in flight, which would otherwise release the waiter and set an exit status from here,
        // re-entering StopWaiting() while the rest of the shutdown is still running.
        mPDCRegistrarIdleCallback.Cancel();

        // Anything still in flight is a revocation the run did not last long enough to see through;
        // the destructor aborts it and the commissioner reports the identity left behind.
        mPDCRegistrar.reset();
    }
    CHIPCommand::Shutdown();
}

void PairingCommand::FinishCommand(CHIP_ERROR aExitErr)
{
    // A rollback of the Network Client Identity may still be under way; the commissioner does not
    // generally wait (letting it complete in the background), but we should before quitting.
    VerifyOrReturn(!DeferExitForPDCRegistrar(aExitErr));

    SetCommandExitStatus(aExitErr);
}

bool PairingCommand::DeferExitForPDCRegistrar(CHIP_ERROR aExitErr)
{
    VerifyOrReturnValue(mPDCRegistrar.has_value() && !mPDCRegistrar->IsIdle(), false);

    ChipLogProgress(chipTool, "Waiting for the Network Client Identity revocation to complete");
    mPDCRegistrarExitErr = aExitErr;

    // Stop the registrar taking on anything new, so that the revocation in flight is all we wait for.
    mPDCRegistrar->StopAcceptingRequests();
    mPDCRegistrar->WaitForIdle(&mPDCRegistrarIdleCallback);
    return true;
}

void PairingCommand::OnPDCRegistrarIdle(void * context)
{
    auto * self = static_cast<PairingCommand *>(context);
    self->SetCommandExitStatus(self->mPDCRegistrarExitErr);
}

WiFiCredentials PairingCommand::GetWiFiCredentials()
{
    if (!mPDCRegistrar.has_value())
    {
        return WiFiCredentials(mSSID, mPassword);
    }
    if (IsNoPasswordMarker(mPassword))
    {
        return WiFiCredentials(mSSID, &mPDCRegistrar.value()); // PDC only
    }
    return WiFiCredentials(mSSID, &mPDCRegistrar.value(), mPassword); // PDC if supported
}

CommissioningParameters PairingCommand::GetCommissioningParameters()
{
    auto params = CommissioningParameters();
    params.SetSkipCommissioningComplete(mSkipCommissioningComplete.ValueOr(false));
    if (mBypassAttestationVerifier.ValueOr(false))
    {
        params.SetDeviceAttestationDelegate(this);
    }

    switch (mNetworkType)
    {
    case PairingNetworkType::WiFi:
        params.SetWiFiCredentials(GetWiFiCredentials());
        break;
    case PairingNetworkType::Thread:
        params.SetThreadOperationalDataset(mOperationalDataset);
        break;
    case PairingNetworkType::WiFiOrThread:
        params.SetWiFiCredentials(GetWiFiCredentials());
        params.SetThreadOperationalDataset(mOperationalDataset);
        break;
    case PairingNetworkType::None:
        break;
    }

    if (mCountryCode.HasValue())
    {
        params.SetCountryCode(CharSpan::fromCharString(mCountryCode.Value()));
    }

    // mTCAcknowledgements and mTCAcknowledgementVersion are optional, but related. When one is missing, default the value to 0, to
    // increase the test tools ability to test the applications.
    if (mTCAcknowledgements.HasValue() || mTCAcknowledgementVersion.HasValue())
    {
        TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement = {
            .acceptedTermsAndConditions        = mTCAcknowledgements.ValueOr(0),
            .acceptedTermsAndConditionsVersion = mTCAcknowledgementVersion.ValueOr(0),
        };
        params.SetTermsAndConditionsAcknowledgement(termsAndConditionsAcknowledgement);
    }

    // mTimeZoneList is an optional argument managed by TypedComplexArgument mComplex_TimeZones.
    // Since optional Complex arguments are not currently supported via the <chip::Optional> class,
    // we will use mTimeZoneList.data() value to determine if the argument was provided.
    if (mTimeZoneList.data())
    {
        params.SetTimeZone(mTimeZoneList);
    }

    // miDSTOffsetList is an optional argument managed by TypedComplexArgument mComplex_DSTOffsets.
    // Since optional Complex arguments are not currently supported via the <chip::Optional> class,
    // we will use mTimeZoneList.data() value to determine if the argument was provided.
    if (mDSTOffsetList.data())
    {
        params.SetDSTOffsets(mDSTOffsetList);
    }

    if (mICDRegistration.ValueOr(false))
    {
        params.SetICDRegistrationStrategy(ICDRegistrationStrategy::kBeforeComplete);

        if (!mICDSymmetricKey.HasValue())
        {
            VerifyOrDieWithMsg(Crypto::DRBG_get_bytes(mRandomGeneratedICDSymmetricKey, sizeof(mRandomGeneratedICDSymmetricKey)) ==
                                   CHIP_NO_ERROR,
                               NotSpecified, "Failed to generate ICD symmetric key (DRBG failure)");
            mICDSymmetricKey.SetValue(ByteSpan(mRandomGeneratedICDSymmetricKey));
        }
        if (!mICDCheckInNodeId.HasValue())
        {
            TEMPORARY_RETURN_IGNORED mICDCheckInNodeId.SetValue(CurrentCommissioner().GetNodeId());
        }
        if (!mICDMonitoredSubject.HasValue())
        {
            mICDMonitoredSubject.SetValue(mICDCheckInNodeId.Value());
        }
        if (!mICDClientType.HasValue())
        {
            mICDClientType.SetValue(app::Clusters::IcdManagement::ClientTypeEnum::kPermanent);
        }
        // These Optionals must have values now.
        // The commissioner will verify these values.
        params.SetICDSymmetricKey(mICDSymmetricKey.Value());
        if (mICDStayActiveDurationMsec.HasValue())
        {
            params.SetICDStayActiveDurationMsec(mICDStayActiveDurationMsec.Value());
        }
        params.SetICDCheckInNodeId(mICDCheckInNodeId.Value());
        params.SetICDMonitoredSubject(mICDMonitoredSubject.Value());
        params.SetICDClientType(mICDClientType.Value());
    }

    return params;
}

CHIP_ERROR PairingCommand::PaseWithCode(NodeId remoteId)
{
    auto discoveryType = DiscoveryType::kAll;
    if (mUseOnlyOnNetworkDiscovery.ValueOr(false))
    {
        discoveryType = DiscoveryType::kDiscoveryNetworkOnly;
    }

    if (mDiscoverOnce.ValueOr(false))
    {
        discoveryType = DiscoveryType::kDiscoveryNetworkOnlyWithoutPASEAutoRetry;
    }

    return CurrentCommissioner().EstablishPASEConnection(remoteId, mOnboardingPayload, discoveryType);
}

CHIP_ERROR
PairingCommand::GetMeshcopCommissionParams(chip::Controller::SetUpCodePairer::ThreadMeshcopCommissionParameters & meshcopParams)
{
#if CHIP_SUPPORT_THREAD_MESHCOP
    Inet::IPAddress ipAddr;
    VerifyOrReturnError(Inet::IPAddress::FromString(mThreadBaHost.Value(), ipAddr), CHIP_ERROR_INVALID_ADDRESS);
    meshcopParams.mBorderAgentAddress = PeerAddress::ThreadMeshcop(ipAddr, mThreadBaPort.Value());
    Thread::OperationalDatasetView dataset;
    ReturnErrorOnFailure(dataset.Init(mOperationalDataset));
    ReturnErrorOnFailure(dataset.GetPSKc(meshcopParams.mPSKcBuffer));
    return CHIP_NO_ERROR;
#else
    return CHIP_ERROR_NOT_IMPLEMENTED;
#endif // CHIP_SUPPORT_THREAD_MESHCOP
}

CHIP_ERROR PairingCommand::PairWithCode(NodeId remoteId)
{
    CommissioningParameters commissioningParams = GetCommissioningParameters();

    // If no network discovery behavior and no network credentials are provided, assume that the pairing command is trying to pair
    // with an on-network device.
    if (!mUseOnlyOnNetworkDiscovery.HasValue())
    {
        auto threadCredentials = commissioningParams.GetThreadOperationalDataset();
        auto wiFiCredentials   = commissioningParams.GetWiFiCredentials();
        mUseOnlyOnNetworkDiscovery.SetValue(!threadCredentials.HasValue() && !wiFiCredentials.HasValue());
    }

    auto discoveryType = DiscoveryType::kAll;
    if (mUseOnlyOnNetworkDiscovery.ValueOr(false))
    {
        discoveryType = DiscoveryType::kDiscoveryNetworkOnly;
    }

    if (mDiscoverOnce.ValueOr(false))
    {
        discoveryType = DiscoveryType::kDiscoveryNetworkOnlyWithoutPASEAutoRetry;
    }

    ReturnErrorOnFailure(MaybeDisplayTermsAndConditions(commissioningParams));
    return CurrentCommissioner().PairDevice(remoteId, mOnboardingPayload, commissioningParams, discoveryType);
}

CHIP_ERROR PairingCommand::Pair(NodeId remoteId, PeerAddress address)
{
    auto params = RendezvousParameters().SetPeerAddress(address);
    if (mOnboardingPayload != nullptr)
    {
        SetupPayload payload;

        ReturnErrorOnFailure(ParseSetupPayload(payload, mOnboardingPayload));
        params.SetSetupPINCode(payload.setUpPINCode);
        params.SetSetupDiscriminator(payload.discriminator);
    }
    else
    {
        VerifyOrDieWithMsg(mSetupPINCode.has_value(), chipTool, "Using mSetupPINCode in a mode when we have not gotten one");
        params.SetSetupPINCode(mSetupPINCode.value());
        if (mDiscriminator.has_value())
        {
            params.SetDiscriminator(mDiscriminator.value());
        }
    }

    if (address.GetTransportType() == Transport::Type::kThreadMeshcop && mOnboardingPayload)
    {
        SetUpCodePairer::ThreadMeshcopCommissionParameters meshcopParams;
        DeviceDiscoveryDelegateRegistry registry(CurrentCommissioner(), this);
        ReturnErrorOnFailure(GetMeshcopCommissionParams(meshcopParams));
        if (mPaseOnly.ValueOr(false))
        {
            return CurrentCommissioner().EstablishPASEConnection(remoteId, mOnboardingPayload, DiscoveryType::kAll, NullOptional,
                                                                 MakeOptional(meshcopParams));
        }
        auto commissioningParams = GetCommissioningParameters();
        return CurrentCommissioner().PairDevice(remoteId, mOnboardingPayload, commissioningParams, DiscoveryType::kAll,
                                                NullOptional, MakeOptional(meshcopParams));
    }
    if (mPaseOnly.ValueOr(false))
    {
        return CurrentCommissioner().EstablishPASEConnection(remoteId, params);
    }
    auto commissioningParams = GetCommissioningParameters();
    return CurrentCommissioner().PairDevice(remoteId, params, commissioningParams);
}

CHIP_ERROR PairingCommand::PairWithMdnsOrBleByIndex(NodeId remoteId, uint16_t index)
{
#if CHIP_DEVICE_LAYER_TARGET_DARWIN
    VerifyOrReturnError(IsInteractive(), CHIP_ERROR_INCORRECT_STATE);

    VerifyOrDieWithMsg(mSetupPINCode.has_value(), chipTool, "Using mSetupPINCode in a mode when we have not gotten one");

    RendezvousParameters params;
    ReturnErrorOnFailure(GetDeviceScanner().Get(index, params));
    params.SetSetupPINCode(mSetupPINCode.value());

    CHIP_ERROR err = CHIP_NO_ERROR;
    if (mPaseOnly.ValueOr(false))
    {
        err = CurrentCommissioner().EstablishPASEConnection(remoteId, params);
    }
    else
    {
        auto commissioningParams = GetCommissioningParameters();
        err                      = CurrentCommissioner().PairDevice(remoteId, params, commissioningParams);
    }
    return err;
#else
    return CHIP_ERROR_NOT_IMPLEMENTED;
#endif // CHIP_DEVICE_LAYER_TARGET_DARWIN
}

CHIP_ERROR PairingCommand::PairWithMdnsOrBleByIndexWithCode(NodeId remoteId, uint16_t index)
{
    // We might or might not have a setup code.  We don't know yet, but if we
    // do, we'll emplace it at that point.
    mSetupPINCode.reset();

#if CHIP_DEVICE_LAYER_TARGET_DARWIN
    VerifyOrReturnError(IsInteractive(), CHIP_ERROR_INCORRECT_STATE);

    Dnssd::CommonResolutionData resolutionData;
    auto err = GetDeviceScanner().Get(index, resolutionData);
    if (CHIP_ERROR_NOT_FOUND == err)
    {
        // There is no device with this index that has some resolution data. This could simply
        // be because the device is a ble device. In this case let's fall back to looking for
        // a device with this index and some RendezvousParameters.
        SetupPayload payload;
        ReturnErrorOnFailure(ParseSetupPayload(payload, mOnboardingPayload));
        mSetupPINCode.emplace(payload.setUpPINCode);
        return PairWithMdnsOrBleByIndex(remoteId, index);
    }

    err = CHIP_NO_ERROR;
    if (mPaseOnly.ValueOr(false))
    {
        err = CurrentCommissioner().EstablishPASEConnection(remoteId, mOnboardingPayload, DiscoveryType::kDiscoveryNetworkOnly,
                                                            MakeOptional(resolutionData));
    }
    else
    {
        auto commissioningParams = GetCommissioningParameters();
        err                      = CurrentCommissioner().PairDevice(remoteId, mOnboardingPayload, commissioningParams,
                                                                    DiscoveryType::kDiscoveryNetworkOnly, MakeOptional(resolutionData));
    }
    return err;
#else
    return CHIP_ERROR_NOT_IMPLEMENTED;
#endif // CHIP_DEVICE_LAYER_TARGET_DARWIN
}

CHIP_ERROR PairingCommand::PairWithMdns(NodeId remoteId)
{
    Dnssd::DiscoveryFilter filter(mFilterType);
    switch (mFilterType)
    {
    case Dnssd::DiscoveryFilterType::kNone:
        break;
    case Dnssd::DiscoveryFilterType::kShortDiscriminator:
    case Dnssd::DiscoveryFilterType::kLongDiscriminator:
    case Dnssd::DiscoveryFilterType::kCompressedFabricId:
    case Dnssd::DiscoveryFilterType::kVendorId:
    case Dnssd::DiscoveryFilterType::kDeviceType:
        filter.code = mDiscoveryFilterCode;
        break;
    case Dnssd::DiscoveryFilterType::kCommissioningMode:
        break;
    case Dnssd::DiscoveryFilterType::kCommissioner:
        filter.code = 1;
        break;
    case Dnssd::DiscoveryFilterType::kInstanceName:
        filter.code         = 0;
        filter.instanceName = mDiscoveryFilterInstanceName;
        break;
    }

    CurrentCommissioner().RegisterDeviceDiscoveryDelegate(this);
    return CurrentCommissioner().DiscoverCommissionableNodes(filter);
}

CHIP_ERROR PairingCommand::Unpair(NodeId remoteId)
{
    mCurrentFabricRemover = Platform::MakeUnique<Controller::CurrentFabricRemover>(&CurrentCommissioner());
    return mCurrentFabricRemover->RemoveCurrentFabric(remoteId, &mCurrentFabricRemoveCallback);
}

void PairingCommand::OnStatusUpdate(DevicePairingDelegate::Status status)
{
    switch (status)
    {
    case DevicePairingDelegate::Status::SecurePairingSuccess:
        ChipLogProgress(chipTool, "Secure Pairing Success");
        ChipLogProgress(chipTool, "CASE establishment successful");
        break;
    case DevicePairingDelegate::Status::SecurePairingFailed:
        ChipLogError(chipTool, "Secure Pairing Failed");
        SetCommandExitStatus(CHIP_ERROR_INCORRECT_STATE);
        break;
    }
}

void PairingCommand::OnPairingComplete(CHIP_ERROR err)
{
    if (err == CHIP_NO_ERROR)
    {
        ChipLogProgress(chipTool, "Pairing Success");
        ChipLogProgress(chipTool, "PASE establishment successful");
        if (mPairingMode == PairingMode::CodePaseOnly || mPaseOnly.ValueOr(false))
        {
            SetCommandExitStatus(err);
        }
    }
    else
    {
        ChipLogProgress(chipTool, "Pairing Failure: %s", ErrorStr(err));

        // PASE failed — commissioning will not proceed, so clean up the proxy session now.
        if (mPairingMode == PairingMode::Proxy)
        {
            SendProxyDisconnect(err);
            return;
        }

        SetCommandExitStatus(err);
    }
}

void PairingCommand::OnPairingDeleted(CHIP_ERROR err)
{
    if (err == CHIP_NO_ERROR)
    {
        ChipLogProgress(chipTool, "Pairing Deleted Success");
    }
    else
    {
        ChipLogProgress(chipTool, "Pairing Deleted Failure: %s", ErrorStr(err));
    }

    SetCommandExitStatus(err);
}

void PairingCommand::OnCommissioningComplete(NodeId nodeId, CHIP_ERROR err)
{
    if (err == CHIP_NO_ERROR)
    {
        ChipLogProgress(chipTool, "Device commissioning completed with success");
    }
    else
    {
        // When ICD device commissioning fails, the ICDClientInfo stored in OnICDRegistrationComplete needs to be removed.
        if (mDeviceIsICD)
        {
            CHIP_ERROR deleteEntryError =
                CHIPCommand::sICDClientStorage.DeleteEntry(ScopedNodeId(mNodeId, CurrentCommissioner().GetFabricIndex()));
            if (deleteEntryError != CHIP_NO_ERROR)
            {
                ChipLogError(chipTool, "Failed to delete ICD entry: %s", ErrorStr(err));
            }
        }
        ChipLogProgress(chipTool, "Device commissioning Failure: %s", ErrorStr(err));
    }

    if (mPairingMode == PairingMode::Proxy)
    {
        // Clean up the proxy session before exiting, regardless of success or failure.
        // The disconnect completing is what eventually reaches FinishCommand().
        SendProxyDisconnect(err);
        return;
    }

    FinishCommand(err);
}

void PairingCommand::OnReadCommissioningInfo(const Controller::ReadCommissioningInfo & info)
{
    ChipLogProgress(AppServer, "OnReadCommissioningInfo - vendorId=0x%04X productId=0x%04X", info.basic.vendorId,
                    info.basic.productId);

    // The string in CharSpan received from the device is not null-terminated, we use std::string here for coping and
    // appending a numm-terminator at the end of the string.
    std::string userActiveModeTriggerInstruction;

    // Note: the callback doesn't own the buffer, should make a copy if it will be used it later.
    if (info.icd.userActiveModeTriggerInstruction.size() != 0)
    {
        userActiveModeTriggerInstruction =
            std::string(info.icd.userActiveModeTriggerInstruction.data(), info.icd.userActiveModeTriggerInstruction.size());
    }

    if (info.icd.userActiveModeTriggerHint.HasAny())
    {
        ChipLogProgress(AppServer, "OnReadCommissioningInfo - LIT UserActiveModeTriggerHint=0x%08x",
                        info.icd.userActiveModeTriggerHint.Raw());
        ChipLogProgress(AppServer, "OnReadCommissioningInfo - LIT UserActiveModeTriggerInstruction=%s",
                        userActiveModeTriggerInstruction.c_str());
    }
    ChipLogProgress(AppServer, "OnReadCommissioningInfo ICD - IdleModeDuration=%u activeModeDuration=%u activeModeThreshold=%u",
                    info.icd.idleModeDuration, info.icd.activeModeDuration, info.icd.activeModeThreshold);
}

void PairingCommand::OnICDRegistrationComplete(ScopedNodeId nodeId, uint32_t icdCounter)
{
    char icdSymmetricKeyHex[Crypto::kAES_CCM128_Key_Length * 2 + 1];

    TEMPORARY_RETURN_IGNORED Encoding::BytesToHex(mICDSymmetricKey.Value().data(), mICDSymmetricKey.Value().size(),
                                                  icdSymmetricKeyHex, sizeof(icdSymmetricKeyHex),
                                                  Encoding::HexFlags::kNullTerminate);

    app::ICDClientInfo clientInfo;
    clientInfo.check_in_node     = ScopedNodeId(mICDCheckInNodeId.Value(), nodeId.GetFabricIndex());
    clientInfo.peer_node         = nodeId;
    clientInfo.monitored_subject = mICDMonitoredSubject.Value();
    clientInfo.start_icd_counter = icdCounter;

    CHIP_ERROR err = CHIPCommand::sICDClientStorage.SetKey(clientInfo, mICDSymmetricKey.Value());
    if (err == CHIP_NO_ERROR)
    {
        err = CHIPCommand::sICDClientStorage.StoreEntry(clientInfo);
    }

    if (err != CHIP_NO_ERROR)
    {
        TEMPORARY_RETURN_IGNORED CHIPCommand::sICDClientStorage.RemoveKey(clientInfo);
        ChipLogError(chipTool, "Failed to persist symmetric key for " ChipLogFormatX64 ": %s", ChipLogValueX64(nodeId.GetNodeId()),
                     err.AsString());
        SetCommandExitStatus(err);
        return;
    }

    mDeviceIsICD = true;

    ChipLogProgress(chipTool, "Saved ICD Symmetric key for " ChipLogFormatX64, ChipLogValueX64(nodeId.GetNodeId()));
    ChipLogProgress(chipTool,
                    "ICD Registration Complete for device " ChipLogFormatX64 " / Check-In NodeID: " ChipLogFormatX64
                    " / Monitored Subject: " ChipLogFormatX64 " / Symmetric Key: %s / ICDCounter %u",
                    ChipLogValueX64(nodeId.GetNodeId()), ChipLogValueX64(mICDCheckInNodeId.Value()),
                    ChipLogValueX64(mICDMonitoredSubject.Value()), icdSymmetricKeyHex, icdCounter);
}

void PairingCommand::OnICDStayActiveComplete(ScopedNodeId deviceId, uint32_t promisedActiveDuration)
{
    ChipLogProgress(chipTool, "ICD Stay Active Complete for device " ChipLogFormatX64 " / promisedActiveDuration: %u",
                    ChipLogValueX64(deviceId.GetNodeId()), promisedActiveDuration);
}

void PairingCommand::OnCommissioningStageStart(PeerId peerId, CommissioningStage stageStarting)
{
    ChipLogDetail(chipTool, "Starting commissioning stage '%s'", StageToString(stageStarting));
}

CHIP_ERROR PairingCommand::WiFiCredentialsNeeded(EndpointId endpoint)
{
    if (mNetworkType != PairingNetworkType::None)
    {
        // We only support prompting for credentials when no credentials were
        // provided up front, for now.
        return CHIP_ERROR_NOT_IMPLEMENTED;
    }

    // We block while prompting for the information, and that does not seem to
    // work well if we do it synchronously: we seem to lose the BLE connection
    // to the commissionee.  So do all the rest of the work async.  The
    // outermost ScheduleLambda is only there to avoid the prompt interleaving
    // with logging that happens on the Matter thread after this function
    // returns.
    TEMPORARY_RETURN_IGNORED DeviceLayer::SystemLayer().ScheduleLambda([this] {
        mPrompterThread.emplace([this] {
            do
            {
                std::cout << "Enter the Wi-Fi SSID: ";
                std::getline(std::cin, mPromptedSSID);
                if (OctetStringFromCharString(mPromptedSSID.data(), &mSSID))
                {
                    break;
                }
                ChipLogError(chipTool, "Invalid value for SSID");
            } while (true);

            do
            {
                std::cout << "Enter the Wi-Fi password (empty for an open network): ";
                std::getline(std::cin, mPromptedPassword);
                if (OctetStringFromCharString(mPromptedPassword.data(), &mPassword))
                {
                    break;
                }
                ChipLogError(chipTool, "Invalid value for password");
            } while (true);

            TEMPORARY_RETURN_IGNORED DeviceLayer::SystemLayer().ScheduleLambda([this] {
                // Ensure that the background thread (and its writes to our members) is done.
                mPrompterThread->join();
                mPrompterThread.reset();

                auto & commissioner            = CurrentCommissioner();
                CommissioningParameters params = commissioner.GetCommissioningParameters();
                params.SetWiFiCredentials(GetWiFiCredentials());
                TEMPORARY_RETURN_IGNORED commissioner.UpdateCommissioningParameters(params);

                TEMPORARY_RETURN_IGNORED commissioner.NetworkCredentialsReady();
            });
        });
    });

    return CHIP_NO_ERROR;
}

CHIP_ERROR PairingCommand::ThreadCredentialsNeeded(EndpointId endpoint)
{
    if (mNetworkType != PairingNetworkType::None)
    {
        // We only support prompting for credentials when no credentials were
        // provided up front, for now.
        return CHIP_ERROR_NOT_IMPLEMENTED;
    }

    // We block while prompting for the information, and that does not seem to
    // work well if we do it synchronously: we seem to lose the BLE connection
    // to the commissionee.  So do all the rest of the work async.  The
    // outermost ScheduleLambda is only there to avoid the prompt interleaving
    // with logging that happens on the Matter thread after this function
    // returns.
    TEMPORARY_RETURN_IGNORED DeviceLayer::SystemLayer().ScheduleLambda([this] {
        mPrompterThread.emplace([this] {
            do
            {
                std::cout << "Enter the operational dataset (probably as a hex string prefixed with \"hex:\"): ";
                std::getline(std::cin, mPromptedOperationalDataset);
                if (OctetStringFromCharString(mPromptedOperationalDataset.data(), &mOperationalDataset))
                {
                    break;
                }
                ChipLogError(chipTool, "Invalid value for operational dataset");
            } while (true);

            TEMPORARY_RETURN_IGNORED DeviceLayer::SystemLayer().ScheduleLambda([this] {
                // Ensure that the background thread (and its writes to our members) is done.
                mPrompterThread->join();
                mPrompterThread.reset();

                auto & commissioner            = CurrentCommissioner();
                CommissioningParameters params = commissioner.GetCommissioningParameters();
                params.SetThreadOperationalDataset(mOperationalDataset);
                TEMPORARY_RETURN_IGNORED commissioner.UpdateCommissioningParameters(params);

                TEMPORARY_RETURN_IGNORED commissioner.NetworkCredentialsReady();
            });
        });
    });

    return CHIP_NO_ERROR;
}

void PairingCommand::OnDiscoveredDevice(const Dnssd::CommissionNodeData & nodeData)
{
    // Ignore nodes with closed commissioning window
    VerifyOrReturn(nodeData.commissioningMode != 0);

    auto & resolutionData = nodeData;

    const uint16_t port = resolutionData.port;
    char buf[Inet::IPAddress::kMaxStringLength];
    resolutionData.ipAddress[0].ToString(buf);
    ChipLogProgress(chipTool, "Discovered Device: %s:%u", buf, port);

    // Stop Mdns discovery.
    auto err = CurrentCommissioner().StopCommissionableDiscovery();

    // Some platforms does not implement a mechanism to stop mdns browse, so
    // we just ignore CHIP_ERROR_NOT_IMPLEMENTED instead of bailing out.
    if (CHIP_NO_ERROR != err && CHIP_ERROR_NOT_IMPLEMENTED != err)
    {
        SetCommandExitStatus(err);
        return;
    }

    CurrentCommissioner().RegisterDeviceDiscoveryDelegate(nullptr);

    auto interfaceId = resolutionData.ipAddress[0].IsIPv6LinkLocal() ? resolutionData.interfaceId : Inet::InterfaceId::Null();
    auto peerAddress = PeerAddress::UDP(resolutionData.ipAddress[0], port, interfaceId);
    err              = Pair(mNodeId, peerAddress);
    if (CHIP_NO_ERROR != err)
    {
        SetCommandExitStatus(err);
    }
}

void PairingCommand::OnCurrentFabricRemove(void * context, NodeId nodeId, CHIP_ERROR err)
{
    PairingCommand * command = reinterpret_cast<PairingCommand *>(context);
    VerifyOrReturn(command != nullptr, ChipLogError(chipTool, "OnCurrentFabricRemove: context is null"));

    if (err == CHIP_NO_ERROR)
    {
        ChipLogProgress(chipTool, "Device unpair completed with success: " ChipLogFormatX64, ChipLogValueX64(nodeId));
    }
    else
    {
        ChipLogProgress(chipTool, "Device unpair Failure: " ChipLogFormatX64 " %s", ChipLogValueX64(nodeId), ErrorStr(err));
    }

    command->SetCommandExitStatus(err);
}

Optional<uint16_t> PairingCommand::FailSafeExpiryTimeoutSecs() const
{
    // We don't need to set additional failsafe timeout as we don't ask the final user if he wants to continue
    return Optional<uint16_t>();
}

void PairingCommand::OnDeviceAttestationCompleted(Controller::DeviceCommissioner * deviceCommissioner, DeviceProxy * device,
                                                  const Credentials::DeviceAttestationVerifier::AttestationDeviceInfo & info,
                                                  Credentials::AttestationVerificationResult attestationResult)
{
    // Bypass attestation verification, continue with success
    auto err = deviceCommissioner->ContinueCommissioningAfterDeviceAttestation(
        device, Credentials::AttestationVerificationResult::kSuccess);
    if (CHIP_NO_ERROR != err)
    {
        SetCommandExitStatus(err);
    }
}

CHIP_ERROR PairingCommand::MaybeDisplayTermsAndConditions(CommissioningParameters & params)
{
    VerifyOrReturnError(mUseDCL.ValueOr(false), CHIP_NO_ERROR);

    Json::Value tc;
    auto client = tool::dcl::DCLClient(mDCLHostName, mDCLPort);
    ReturnErrorOnFailure(client.TermsAndConditions(mOnboardingPayload, tc));
    if (tc != Json::nullValue)
    {
        uint16_t version      = 0;
        uint16_t userResponse = 0;
        ReturnErrorOnFailure(tool::dcl::DisplayTermsAndConditions(tc, version, userResponse, mCountryCode));

        TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement = {
            .acceptedTermsAndConditions        = userResponse,
            .acceptedTermsAndConditionsVersion = version,
        };
        params.SetTermsAndConditionsAcknowledgement(termsAndConditionsAcknowledgement);
    }

    return CHIP_NO_ERROR;
}

// ==========================================================================
// Proxy commissioning support
// ==========================================================================

CHIP_ERROR PairingCommand::ParseProxyTransportArguments()
{
    using namespace chip::app::Clusters::CommissioningProxy;

    // Interactive mode reuses this command instance, and Command::ResetArguments() only
    // clears registered arguments, not what was derived from them.  Set() ORs, so without
    // this a second run would send the union of both transports.
    mProxyTransportBits.ClearAll();
    mProxyWiFiBandBits.ClearValue();

    VerifyOrReturnError(mProxyTransport != nullptr, CHIP_ERROR_INVALID_ARGUMENT,
                        ChipLogError(chipTool, "PairViaProxy: --proxy-transport is required (one of: ble | wifipaf)"));

    if (strcmp(mProxyTransport, "wifipaf") == 0)
    {
        mProxyTransportBits.Set(CapabilitiesBitmap::kWiFiPAF);
        if (mProxyWiFiBand.HasValue())
        {
            if (strcmp(mProxyWiFiBand.Value(), "2g4") == 0)
            {
                mProxyWiFiBandBits.SetValue(chip::BitMask<WiFiBandBitmap>(WiFiBandBitmap::k2g4));
            }
            else if (strcmp(mProxyWiFiBand.Value(), "5g") == 0)
            {
                mProxyWiFiBandBits.SetValue(chip::BitMask<WiFiBandBitmap>(WiFiBandBitmap::k5g));
            }
            else
            {
                ChipLogError(chipTool, "PairViaProxy: --proxy-wifi-band must be 2g4 or 5g (got '%s')", mProxyWiFiBand.Value());
                return CHIP_ERROR_INVALID_ARGUMENT;
            }
        }
    }
    else if (strcmp(mProxyTransport, "ble") == 0)
    {
        mProxyTransportBits.Set(CapabilitiesBitmap::kBle);
        VerifyOrReturnError(!mProxyWiFiBand.HasValue(), CHIP_ERROR_INVALID_ARGUMENT,
                            ChipLogError(chipTool, "PairViaProxy: --proxy-wifi-band only valid with --proxy-transport=wifipaf"));
    }
    else
    {
        ChipLogError(chipTool, "PairViaProxy: --proxy-transport must be 'ble' or 'wifipaf' (got '%s')", mProxyTransport);
        return CHIP_ERROR_INVALID_ARGUMENT;
    }

    return CHIP_NO_ERROR;
}

CHIP_ERROR PairingCommand::PairViaProxy(NodeId remoteId)
{
    // Refuse a new flow while a previous one still has a sender outstanding.  Interactive
    // mode reuses this instance, and SendProxyDisconnect() only clears mProxySessionActive;
    // it neither waits for nor clears the message senders.  A sender left over from an
    // abandoned flow would otherwise run its callback against this flow's session state and
    // tear down a session it knows nothing about.
    VerifyOrReturnError(
        mProxyConnectCmdSender == nullptr && mProxyMessageCmdSenders.empty() && mProxyDisconnectCmdSender == nullptr,
        CHIP_ERROR_INCORRECT_STATE, ChipLogError(chipTool, "PairViaProxy: a previous proxy flow is still finishing"));

    // Validate the command line before the CASE session below: a bad --proxy-transport
    // should not cost a full handshake with the proxy first.
    VerifyOrReturnError(mProxyNodeId != chip::kUndefinedNodeId, CHIP_ERROR_INVALID_ARGUMENT,
                        ChipLogError(chipTool, "PairViaProxy: --proxy-node-id is required"));
    ReturnErrorOnFailure(ParseProxyTransportArguments());

    ChipLogProgress(chipTool, "PairViaProxy: connecting to proxy node 0x%" PRIx64, mProxyNodeId);

    // Step 1: establish a CASE session to the proxy app.  The rest of the
    // flow continues in OnProxyDeviceConnected().
    return CurrentCommissioner().GetConnectedDevice(mProxyNodeId, &mOnProxyConnectedCallback, &mOnProxyConnectionFailureCallback,
                                                    chip::TransportPayloadCapability::kLargePayload);
}

// static
void PairingCommand::OnProxyDeviceConnected(void * context, chip::Messaging::ExchangeManager & exchangeMgr,
                                            const chip::SessionHandle & sessionHandle)
{
    auto * self = reinterpret_cast<PairingCommand *>(context);

    ChipLogProgress(chipTool, "PairViaProxy: CASE session established to proxy, sending ProxyConnectRequest");

    self->mProxyExchangeMgr = &exchangeMgr;
    self->mProxySession.Grab(sessionHandle);

    // Step 2: send ProxyConnectRequest to the proxy.
    auto cmdSender = chip::Platform::MakeUnique<chip::app::CommandSender>(self, &exchangeMgr);
    if (!cmdSender)
    {
        ChipLogError(chipTool, "PairViaProxy: failed to allocate CommandSender");
        self->mProxySession.Release();
        self->SetCommandExitStatus(CHIP_ERROR_NO_MEMORY);
        return;
    }

    using namespace chip::app::Clusters::CommissioningProxy;
    Commands::ProxyConnectRequest::Type request;
    request.address.SetNull();

    // Already validated by ParseProxyTransportArguments() before the CASE session.
    request.transport = self->mProxyTransportBits;
    request.wiFiBand  = self->mProxyWiFiBandBits;

    request.discriminator = self->mDiscriminator.value_or(0);
    request.vendorID      = chip::VendorId::Common;
    request.productID     = 0;
    request.timeout       = self->mProxyConnectTimeout;

    chip::app::CommandPathParams pathParams(self->mProxyEndpointId.ValueOr(kDefaultProxyEndpointId),
                                            chip::app::Clusters::CommissioningProxy::Id, Commands::ProxyConnectRequest::Id,
                                            chip::app::CommandPathFlags::kEndpointIdValid);

    if (cmdSender->AddRequestData(pathParams, request) != CHIP_NO_ERROR)
    {
        ChipLogError(chipTool, "PairViaProxy: AddRequestData failed");
        self->mProxySession.Release();
        self->SetCommandExitStatus(CHIP_ERROR_INCORRECT_STATE);
        return;
    }

    CHIP_ERROR err = cmdSender->SendCommandRequest(sessionHandle);
    if (err != CHIP_NO_ERROR)
    {
        ChipLogError(chipTool, "PairViaProxy: SendCommandRequest failed: %" CHIP_ERROR_FORMAT, err.Format());
        self->mProxySession.Release();
        self->SetCommandExitStatus(err);
        return;
    }

    // Keep the sender alive until OnDone fires.  This must NOT be the same member the
    // ProxyMessageRequest path uses: PASE is started from this sender's OnResponse, so
    // the first ProxyMessageRequest is issued while this sender is still on the stack.
    self->mProxyConnectCmdSender = std::move(cmdSender);
}

// static
void PairingCommand::OnProxyDeviceConnectionFailed(void * context, const chip::ScopedNodeId & nodeId, CHIP_ERROR error)
{
    auto * self = reinterpret_cast<PairingCommand *>(context);
    ChipLogError(chipTool, "PairViaProxy: failed to connect to proxy: %" CHIP_ERROR_FORMAT, error.Format());
    self->SetCommandExitStatus(error);
}

void PairingCommand::OnProxyConnected(uint16_t sessionId)
{
    ChipLogProgress(chipTool, "PairViaProxy: ProxyConnectResponse received, sessionId=%u", sessionId);

    mProxySessionId     = sessionId;
    mProxySessionActive = true;

    // Activate the ProxyTransport so commissioning packets are routed through it.
    // GetTransportMgr() is null once the commissioner's system state is gone, and
    // Activate() refuses to replace a session that is still live.
    auto * transportMgr   = CurrentCommissioner().GetTransportMgr();
    auto * proxyTransport = GetDeviceProxyTransport(transportMgr);
    CHIP_ERROR err        = (proxyTransport == nullptr) ? CHIP_ERROR_INCORRECT_STATE : proxyTransport->Activate(sessionId, this);
    if (err != CHIP_NO_ERROR)
    {
        ChipLogError(chipTool, "PairViaProxy: could not activate the proxy transport: %" CHIP_ERROR_FORMAT, err.Format());
        SendProxyDisconnect(err);
        return;
    }

    // Step 3: start the commissioning process via the proxy tunnel.
    err = Pair(mNodeId, chip::Transport::PeerAddress::Proxy(sessionId));
    if (err != CHIP_NO_ERROR)
    {
        ChipLogError(chipTool, "PairViaProxy: Pair() failed: %" CHIP_ERROR_FORMAT, err.Format());
        SendProxyDisconnect(err);
    }
}

// CommandSender::Callback — called when a response to ProxyConnectRequest or
// ProxyMessageRequest arrives.
void PairingCommand::OnResponse(chip::app::CommandSender * client, const chip::app::ConcreteCommandPath & path,
                                const chip::app::StatusIB & status, chip::TLV::TLVReader * data)
{
    using namespace chip::app::Clusters::CommissioningProxy::Commands;

    if (path.mCommandId == ProxyConnectResponse::Id)
    {
        ProxyConnectResponse::DecodableType response;
        if (data && chip::app::DataModel::Decode(*data, response) == CHIP_NO_ERROR)
        {
            OnProxyConnected(response.sessionID);
        }
        else
        {
            ChipLogError(chipTool, "PairViaProxy: failed to decode ProxyConnectResponse");
            // The proxy may have accepted the request even though its response was
            // undecodable, and no SessionID is known, so cancel rather than disconnect.
            SendProxyDisconnect(CHIP_ERROR_INCORRECT_STATE, /* aCancelPendingConnect */ true);
        }
        return;
    }

    if (path.mCommandId == ProxyMessageResponse::Id)
    {
        // The request is no longer outstanding the moment its response arrives.  Clear
        // this BEFORE injecting: the injection drives PASE/CASE forward synchronously and
        // the reply it produces is sent from inside this call.
        mProxyMessageAwaitingResponse = false;

        ProxyMessageResponse::DecodableType response;
        if (data && chip::app::DataModel::Decode(*data, response) == CHIP_NO_ERROR)
        {
            if (response.message.IsNull())
            {
                // Null means the proxy has nothing queued, so the drain is complete.
                mProxyConsecutivePolls = 0;
                return;
            }

            auto * transportMgr   = CurrentCommissioner().GetTransportMgr();
            auto * proxyTransport = GetDeviceProxyTransport(transportMgr);
            if (proxyTransport == nullptr)
            {
                ChipLogError(chipTool, "PairViaProxy: no proxy transport to inject into");
                SendProxyDisconnect(CHIP_ERROR_INCORRECT_STATE);
                return;
            }

            CHIP_ERROR injectErr = proxyTransport->OnProxyMessageReceived(response.sessionID, response.message.Value());
            if (injectErr != CHIP_NO_ERROR)
            {
                ChipLogError(chipTool, "PairViaProxy: failed to inject proxied message: %" CHIP_ERROR_FORMAT, injectErr.Format());
                SendProxyDisconnect(injectErr);
                return;
            }

            // The injection above may have driven the stack to send a reply, which takes
            // the outstanding slot and will collect anything else queued.  Only when it
            // produced nothing does the commissioner have to ask -- the commissionee can
            // send more than one message per request (retransmits, standalone acks) and
            // this session carries no MRP to prompt another send.
            if (mProxyMessageAwaitingResponse)
            {
                return;
            }

            // Injecting above can complete PASE or commissioning synchronously, and those
            // callbacks start the disconnect.  Draining further would issue a request against
            // a session already being torn down, and that sender then blocks the next flow.
            if (!mProxySessionActive || mProxyDisconnectCmdSender != nullptr)
            {
                return;
            }

            if (++mProxyConsecutivePolls > kMaxConsecutiveProxyPolls)
            {
                ChipLogError(chipTool, "PairViaProxy: stopping after %u consecutive queued-message polls",
                             static_cast<unsigned>(kMaxConsecutiveProxyPolls));
                mProxyConsecutivePolls = 0;
                return;
            }

            CHIP_ERROR pollErr = PollProxyForQueuedMessage();
            if (pollErr != CHIP_NO_ERROR)
            {
                ChipLogError(chipTool, "PairViaProxy: failed to poll for queued messages: %" CHIP_ERROR_FORMAT, pollErr.Format());
                SendProxyDisconnect(pollErr);
            }
        }
        else
        {
            ChipLogError(chipTool, "PairViaProxy: failed to decode ProxyMessageResponse");
            SendProxyDisconnect(CHIP_ERROR_INCORRECT_STATE);
        }
        return;
    }
}

void PairingCommand::OnError(const chip::app::CommandSender * client, CHIP_ERROR error)
{
    if (client == mProxyDisconnectCmdSender.get())
    {
        // The disconnect is best-effort; log but use the original exit status.
        ChipLogDetail(chipTool, "PairViaProxy: ProxyDisconnectRequest error (ignored): %" CHIP_ERROR_FORMAT, error.Format());
        FinishCommand(mProxyDisconnectExitErr);
        return;
    }
    ChipLogError(chipTool, "PairViaProxy CommandSender error: %" CHIP_ERROR_FORMAT, error.Format());

    if (IsProxyMessageCmdSender(client))
    {
        // No response is coming, so stop treating the request as outstanding; otherwise
        // the tunnel would refuse every later message with BUSY.
        mProxyMessageAwaitingResponse = false;

        // The tunnel is the only path to the commissionee and this session has no MRP,
        // so nothing will retry underneath us.  Tear the proxy session down and report
        // the real cause rather than letting commissioning stall until something
        // unrelated times out.
        ChipLogError(chipTool, "PairViaProxy: ProxyMessageRequest failed, abandoning commissioning");
        SendProxyDisconnect(error);
        return;
    }

    if (client == mProxyConnectCmdSender.get())
    {
        // ProxyConnectRequest failed.  The proxy may still be trying to reach the
        // commissionee -- with Timeout 0 it will do so indefinitely -- so cancel it
        // explicitly with a null SessionID before exiting.
        SendProxyDisconnect(error, /* aCancelPendingConnect */ true);
    }
}

bool PairingCommand::IsProxyMessageCmdSender(const chip::app::CommandSender * client) const
{
    return std::any_of(mProxyMessageCmdSenders.begin(), mProxyMessageCmdSenders.end(),
                       [client](const auto & sender) { return sender.get() == client; });
}

void PairingCommand::OnDone(chip::app::CommandSender * client)
{
    if (mProxyConnectCmdSender.get() == client)
    {
        mProxyConnectCmdSender.reset();
    }
    else if (IsProxyMessageCmdSender(client))
    {
        // Destroying the sender from its own OnDone is the documented contract.
        mProxyMessageCmdSenders.erase(std::remove_if(mProxyMessageCmdSenders.begin(), mProxyMessageCmdSenders.end(),
                                                     [client](const auto & sender) { return sender.get() == client; }),
                                      mProxyMessageCmdSenders.end());
    }
    else if (mProxyDisconnectCmdSender.get() == client)
    {
        mProxyDisconnectCmdSender.reset();
        mProxySession.Release();
        FinishCommand(mProxyDisconnectExitErr);
    }
}

// Send ProxyDisconnectRequest to clean up the proxy session, then exit.
// Finishing the command is deferred until the response (or a timeout) is received so
// that chip-tool keeps the TCP session alive long enough for the proxy to reply.
void PairingCommand::SendProxyDisconnect(CHIP_ERROR exitErr, bool aCancelPendingConnect)
{
    // A cancel needs no session -- it is precisely for the case where ProxyConnectRequest
    // never produced one -- but it still needs the CASE session to the proxy.
    const bool haveSomethingToSend = aCancelPendingConnect || mProxySessionActive;
    if (!haveSomethingToSend || mProxyExchangeMgr == nullptr || !static_cast<bool>(mProxySession))
    {
        FinishCommand(exitErr);
        return;
    }

    // A disconnect already in flight owns the exit status; a second one would displace
    // its sender and lose the callback.
    if (mProxyDisconnectCmdSender)
    {
        return;
    }

    using namespace chip::app::Clusters::CommissioningProxy;

    Commands::ProxyDisconnectRequest::Type request;
    if (aCancelPendingConnect)
    {
        // Spec: "A null value SHALL cancel any ongoing ProxyConnectRequest for the
        // invoking fabric."
        request.sessionID.SetNull();
        ChipLogProgress(chipTool, "PairViaProxy: cancelling any ongoing ProxyConnectRequest");
    }
    else
    {
        request.sessionID.SetNonNull(mProxySessionId);
    }

    chip::app::CommandPathParams pathParams(mProxyEndpointId.ValueOr(kDefaultProxyEndpointId),
                                            chip::app::Clusters::CommissioningProxy::Id, Commands::ProxyDisconnectRequest::Id,
                                            chip::app::CommandPathFlags::kEndpointIdValid);

    // Mark the session dead now so a duplicate call is a no-op.  mProxySessionId is left
    // alone: 0 is a valid SessionID, so it cannot be used to mean "no session".
    // Deactivating also releases the transport, which Activate() requires to be idle --
    // in interactive mode a later "pairing proxy" reuses the same instance.
    mProxySessionActive = false;
    if (auto * proxyTransport = GetDeviceProxyTransport(CurrentCommissioner().GetTransportMgr()))
    {
        proxyTransport->Deactivate();
    }
    mProxyDisconnectExitErr = exitErr;

    // Allocate only once the local session is retired: releasing the CASE session while
    // the transport is still active would leave nothing able to deactivate it.
    auto cmdSender = chip::Platform::MakeUnique<chip::app::CommandSender>(this, mProxyExchangeMgr);
    if (cmdSender == nullptr)
    {
        ChipLogError(chipTool, "PairViaProxy: failed to allocate CommandSender for ProxyDisconnectRequest");
        mProxySession.Release();
        FinishCommand(exitErr);
        return;
    }

    if (cmdSender->AddRequestData(pathParams, request) != CHIP_NO_ERROR ||
        cmdSender->SendCommandRequest(mProxySession.Get().Value()) != CHIP_NO_ERROR)
    {
        ChipLogError(chipTool, "PairViaProxy: failed to send ProxyDisconnectRequest");
        mProxySession.Release();
        FinishCommand(exitErr);
        return;
    }

    ChipLogProgress(chipTool, "PairViaProxy: sent ProxyDisconnectRequest, waiting for response");
    mProxyDisconnectCmdSender = std::move(cmdSender);
    // Finishing the command is deferred until OnDone/OnError fires for mProxyDisconnectCmdSender.
}

// ProxyTransportDelegate — called by ProxyTransport when it needs to forward
// a commissioning packet to the proxy app via ProxyMessageRequest.
CHIP_ERROR PairingCommand::SendProxyMessage(uint16_t sessionId, chip::ByteSpan message)
{
    // A real outbound message ends any drain in progress.
    mProxyConsecutivePolls = 0;
    return SendProxyMessageRequest(sessionId, chip::app::DataModel::MakeNullable(message));
}

CHIP_ERROR PairingCommand::PollProxyForQueuedMessage()
{
    ChipLogDetail(chipTool, "PairViaProxy: polling the proxy for a queued message (session %u)", mProxySessionId);
    return SendProxyMessageRequest(mProxySessionId, chip::app::DataModel::Nullable<chip::ByteSpan>());
}

CHIP_ERROR PairingCommand::SendProxyMessageRequest(uint16_t sessionId,
                                                   const chip::app::DataModel::Nullable<chip::ByteSpan> & message)
{
    VerifyOrReturnError(mProxyExchangeMgr != nullptr, CHIP_ERROR_INCORRECT_STATE);
    VerifyOrReturnError(static_cast<bool>(mProxySession), CHIP_ERROR_INCORRECT_STATE);

    // Nothing may be sent for a session that is closing: the disconnect has already
    // deactivated the transport, so a request issued now can only outlive the flow.
    VerifyOrReturnError(mProxySessionActive && mProxyDisconnectCmdSender == nullptr, CHIP_ERROR_INCORRECT_STATE);

    // Only one ProxyMessageRequest may be outstanding per session; the proxy answers a
    // second one with BUSY.  Refuse here so the caller can retry rather than displacing
    // the in-flight request.  Note this tracks the RESPONSE, not the sender's lifetime:
    // senders outlive their response by one callback, and the next message is sent from
    // inside that window.
    VerifyOrReturnError(!mProxyMessageAwaitingResponse, CHIP_ERROR_BUSY);

    using namespace chip::app::Clusters::CommissioningProxy;

    // Allow large payload so that commissioning messages fit inside ProxyMessageRequest.
    auto cmdSender =
        chip::Platform::MakeUnique<chip::app::CommandSender>(this, mProxyExchangeMgr, /* aIsTimedRequest */ false,
                                                             /* aSuppressResponse */ false, /* aAllowLargePayload */ true);
    VerifyOrReturnError(cmdSender != nullptr, CHIP_ERROR_NO_MEMORY);

    Commands::ProxyMessageRequest::Type request;
    request.sessionID = sessionId;
    // ConnectNetwork on Linux can take 20-30s (wpa_supplicant scan + join).
    // The proxy exchange must stay open at least this long.
    request.responseTimeout = 60;
    request.message         = message;

    chip::app::CommandPathParams pathParams(mProxyEndpointId.ValueOr(kDefaultProxyEndpointId),
                                            chip::app::Clusters::CommissioningProxy::Id, Commands::ProxyMessageRequest::Id,
                                            chip::app::CommandPathFlags::kEndpointIdValid);

    ReturnErrorOnFailure(cmdSender->AddRequestData(pathParams, request));

    // Take ownership before sending, and mark the request outstanding, so a re-entrant
    // call is refused rather than displacing this one.  OnDone cannot run before
    // SendCommandRequest returns, so undoing both on failure cannot race with it.
    auto * sender = cmdSender.get();
    mProxyMessageCmdSenders.push_back(std::move(cmdSender));
    mProxyMessageAwaitingResponse = true;

    // Give chip-tool's exchange a little extra headroom beyond responseTimeout
    // so it does not expire before the proxy has a chance to forward the reply.
    auto cmdTimeout = chip::System::Clock::Seconds16(request.responseTimeout + 10);
    CHIP_ERROR err  = sender->SendCommandRequest(mProxySession.Get().Value(), chip::MakeOptional(cmdTimeout));
    if (err != CHIP_NO_ERROR)
    {
        mProxyMessageAwaitingResponse = false;
        mProxyMessageCmdSenders.pop_back();
        return err;
    }
    return CHIP_NO_ERROR;
}