[darwin-framework-tool] Add Enhanced Commissioning Support (T&C Flow via Local DCL) to darwin-framework-tool (project-chip#37379)

* [darwin-framework-tool] Add darwin-framework-tool dcl tc-display and tc-display-by-payload commands

* [darwin-framework-tool] Add TermsAndConditions support to darwin-framework-tool pairing code

* [darwin] Add TermsAndConditions support MTRCommissioningParameters

Author: vivien-apple

examples/darwin-framework-tool/BUILD.gn

@@ -189,6 +189,9 @@ executable("darwin-framework-tool") {
     "${chip_root}/examples/chip-tool/commands/common/Commands.cpp",
     "${chip_root}/examples/chip-tool/commands/common/Commands.h",
     "${chip_root}/examples/chip-tool/commands/common/HexConversion.h",
+    "${chip_root}/examples/chip-tool/commands/dcl/DCLClient.cpp",
+    "${chip_root}/examples/chip-tool/commands/dcl/DisplayTermsAndConditions.cpp",
+    "${chip_root}/examples/chip-tool/commands/dcl/JsonSchemaMacros.cpp",
     "${chip_root}/examples/common/websocket-server/WebSocketServer.cpp",
     "${chip_root}/examples/common/websocket-server/WebSocketServer.h",
     "${chip_root}/zzz_generated/chip-tool/zap-generated/cluster/ComplexArgumentParser.cpp",
@@ -220,6 +223,7 @@ executable("darwin-framework-tool") {
     "commands/configuration/ResetMRPParametersCommand.mm",
     "commands/configuration/SetMRPParametersCommand.h",
     "commands/configuration/SetMRPParametersCommand.mm",
+    "commands/dcl/HTTPSRequest.mm",
     "commands/delay/Commands.h",
     "commands/delay/SleepCommand.h",
     "commands/delay/SleepCommand.mm",

examples/darwin-framework-tool/commands/dcl/HTTPSRequest.mm

@@ -63,6 +63,10 @@ class PairingCommandBridge : public CHIPCommandBridge
             break;
         case PairingMode::Code:
             AddArgument("payload", &mOnboardingPayload);
+            AddArgument("dcl-hostname", &mDCLHostName,
+                        "Hostname of the DCL server to fetch information from. Defaults to 'on.dcl.csa-iot.org'.");
+            AddArgument("dcl-port", 0, UINT16_MAX, &mDCLPort, "Port number for connecting to the DCL server. Defaults to '443'.");
+            AddArgument("use-dcl", 0, 1, &mUseDCL, "Use DCL to fetch onboarding information");
             break;
         case PairingMode::Ble:
             AddArgument("setup-pin-code", 0, 134217727, &mSetupPINCode);
@@ -71,6 +75,10 @@ class PairingCommandBridge : public CHIPCommandBridge
         case PairingMode::AlreadyDiscoveredByIndex:
             AddArgument("payload", &mOnboardingPayload);
             AddArgument("index", 0, UINT16_MAX, &mIndex);
+            AddArgument("dcl-hostname", &mDCLHostName,
+                        "Hostname of the DCL server to fetch information from. Defaults to 'on.dcl.csa-iot.org'.");
+            AddArgument("dcl-port", 0, UINT16_MAX, &mDCLPort, "Port number for connecting to the DCL server. Defaults to '443'.");
+            AddArgument("use-dcl", 0, 1, &mUseDCL, "Use DCL to fetch onboarding information");
             break;
         }
 
@@ -95,7 +103,8 @@ class PairingCommandBridge : public CHIPCommandBridge
     void PairWithIndex(NSError * __autoreleasing * error);
     void PairWithPayload(NSError * __autoreleasing * error);
     void Unpair();
-    void SetUpDeviceControllerDelegate();
+    void SetUpDeviceControllerDelegate(NSError * __autoreleasing * error);
+    void MaybeDisplayTermsAndConditions(MTRCommissioningParameters * params, NSError * __autoreleasing * error);
 
     const PairingMode mPairingMode;
     const CommissioningType mCommissioningType;
@@ -110,4 +119,7 @@ class PairingCommandBridge : public CHIPCommandBridge
     chip::Optional<bool> mUseDeviceAttestationDelegate;
     chip::Optional<uint16_t> mDeviceAttestationFailsafeTime;
     chip::Optional<char *> mCountryCode;
+    chip::Optional<char *> mDCLHostName;
+    chip::Optional<uint16_t> mDCLPort;
+    chip::Optional<bool> mUseDCL;
 };

examples/darwin-framework-tool/commands/pairing/PairingCommandBridge.h

@@ -22,6 +22,8 @@
 #include "../common/CertificateIssuer.h"
 #include "DeviceControllerDelegateBridge.h"
 #include "PairingCommandBridge.h"
+#include <commands/dcl/DCLClient.h>
+#include <commands/dcl/DisplayTermsAndConditions.h>
 #include <lib/support/logging/CHIPLogging.h>
 
 #import "MTRError_Utils.h"
@@ -47,7 +49,7 @@ - (void)deviceAttestationCompletedForController:(MTRDeviceController *)controlle
 
 @end
 
-void PairingCommandBridge::SetUpDeviceControllerDelegate()
+void PairingCommandBridge::SetUpDeviceControllerDelegate(NSError * __autoreleasing * error)
 {
     CHIPToolDeviceControllerDelegate * deviceControllerDelegate = [[CHIPToolDeviceControllerDelegate alloc] init];
     [deviceControllerDelegate setCommandBridge:this];
@@ -85,6 +87,8 @@ - (void)deviceAttestationCompletedForController:(MTRDeviceController *)controlle
             params.countryCode = [NSString stringWithUTF8String:mCountryCode.Value()];
         }
 
+        MaybeDisplayTermsAndConditions(params, error);
+        VerifyOrReturn(*error == nil);
         [deviceControllerDelegate setParams:params];
     }
 
@@ -94,6 +98,39 @@ - (void)deviceAttestationCompletedForController:(MTRDeviceController *)controlle
     [commissioner setDeviceControllerDelegate:deviceControllerDelegate queue:callbackQueue];
 }
 
+void PairingCommandBridge::MaybeDisplayTermsAndConditions(MTRCommissioningParameters * params, NSError * __autoreleasing * error)
+{
+    VerifyOrReturn(mUseDCL.ValueOr(false));
+
+    Json::Value tc;
+    auto client = tool::dcl::DCLClient(mDCLHostName, mDCLPort);
+    CHIP_ERROR err = client.TermsAndConditions(mOnboardingPayload, tc);
+
+    if (CHIP_NO_ERROR != err) {
+        auto errorString = [NSString stringWithFormat:@"Error retrieving terms and conditions."];
+        *error = [[NSError alloc] initWithDomain:@"PairingDomain"
+                                            code:MTRErrorCodeGeneralError
+                                        userInfo:@ { NSLocalizedDescriptionKey : NSLocalizedString(errorString, nil) }];
+        return;
+    }
+
+    if (tc != Json::nullValue) {
+        uint16_t version = 0;
+        uint16_t userResponse = 0;
+        err = tool::dcl::DisplayTermsAndConditions(tc, version, userResponse, mCountryCode);
+        if (CHIP_NO_ERROR != err) {
+            auto errorString = [NSString stringWithFormat:@"Error displaying terms and conditions."];
+            *error = [[NSError alloc] initWithDomain:@"PairingDomain"
+                                                code:MTRErrorCodeGeneralError
+                                            userInfo:@ { NSLocalizedDescriptionKey : NSLocalizedString(errorString, nil) }];
+            return;
+        }
+
+        params.acceptedTermsAndConditions = @(userResponse);
+        params.acceptedTermsAndConditionsVersion = @(version);
+    }
+}
+
 CHIP_ERROR PairingCommandBridge::RunCommand()
 {
     NSError * error;
@@ -120,17 +157,20 @@ - (void)deviceAttestationCompletedForController:(MTRDeviceController *)controlle
 
 void PairingCommandBridge::PairWithCode(NSError * __autoreleasing * error)
 {
-    SetUpDeviceControllerDelegate();
+    SetUpDeviceControllerDelegate(error);
+    VerifyOrReturn(*error == nil);
+
     auto * payload = [[MTRSetupPayload alloc] initWithSetupPasscode:@(mSetupPINCode) discriminator:@(mDiscriminator)];
     MTRDeviceController * commissioner = CurrentCommissioner();
     [commissioner setupCommissioningSessionWithPayload:payload newNodeID:@(mNodeId) error:error];
 }
 
 void PairingCommandBridge::PairWithIndex(NSError * __autoreleasing * error)
 {
-    SetUpDeviceControllerDelegate();
-    MTRDeviceController * commissioner = CurrentCommissioner();
+    SetUpDeviceControllerDelegate(error);
+    VerifyOrReturn(*error == nil);
 
+    MTRDeviceController * commissioner = CurrentCommissioner();
     if (mIndex >= [gDiscoveredDevices count]) {
         auto errorString = [NSString stringWithFormat:@"Error retrieving discovered device at index %@", @(mIndex)];
         *error = [[NSError alloc] initWithDomain:@"PairingDomain"
@@ -152,7 +192,9 @@ - (void)deviceAttestationCompletedForController:(MTRDeviceController *)controlle
 void PairingCommandBridge::PairWithPayload(NSError * __autoreleasing * error)
 {
     NSString * onboardingPayload = [NSString stringWithUTF8String:mOnboardingPayload];
-    SetUpDeviceControllerDelegate();
+    SetUpDeviceControllerDelegate(error);
+    VerifyOrReturn(*error == nil);
+
     auto * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:onboardingPayload error:error];
     if (payload == nil) {
         return;

examples/darwin-framework-tool/commands/pairing/PairingCommandBridge.mm

@@ -24,6 +24,7 @@
 #include "commands/bdx/Commands.h"
 #include "commands/common/Commands.h"
 #include "commands/configuration/Commands.h"
+#include "commands/dcl/Commands.h"
 #include "commands/delay/Commands.h"
 #include "commands/discover/Commands.h"
 #include "commands/interactive/Commands.h"
@@ -44,6 +45,7 @@ int main(int argc, const char * argv[])
         Commands commands;
         registerCommandsBdx(commands);
         registerCommandsPairing(commands);
+        registerCommandsDCL(commands);
         registerCommandsDelay(commands);
         registerCommandsDiscover(commands);
         registerCommandsInteractive(commands);

examples/darwin-framework-tool/main.mm

@@ -102,6 +102,17 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
  */
 @property (nonatomic, assign) BOOL readEndpointInformation MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4));
 
+/**
+ * A bitmask of the user’s responses to the presented terms and conditions.
+ * Each bit corresponds to a term’s acceptance (1) or non-acceptance (0) at the matching index.
+ */
+@property (nonatomic, copy, nullable) NSNumber * acceptedTermsAndConditions MTR_PROVISIONALLY_AVAILABLE;
+
+/**
+ * The version of the terms and conditions that the user has accepted.
+ */
+@property (nonatomic, copy, nullable) NSNumber * acceptedTermsAndConditionsVersion MTR_PROVISIONALLY_AVAILABLE;
+
 @end
 
 @interface MTRCommissioningParameters (Deprecated)

src/darwin/Framework/CHIP/MTRCommissioningParameters.h

@@ -973,6 +973,25 @@ - (BOOL)commissionNodeWithID:(NSNumber *)nodeID
         if (commissioningParams.threadOperationalDataset) {
             params.SetThreadOperationalDataset(AsByteSpan(commissioningParams.threadOperationalDataset));
         }
+        if (commissioningParams.acceptedTermsAndConditions && commissioningParams.acceptedTermsAndConditionsVersion) {
+            if (!chip::CanCastTo<uint16_t>([commissioningParams.acceptedTermsAndConditions unsignedIntValue])) {
+                MTR_LOG_ERROR("%@ Error: acceptedTermsAndConditions value should be between 0 and 65535", self);
+                *error = [MTRError errorForCHIPErrorCode:CHIP_ERROR_INVALID_INTEGER_VALUE];
+                return NO;
+            }
+
+            if (!chip::CanCastTo<uint16_t>([commissioningParams.acceptedTermsAndConditionsVersion unsignedIntValue])) {
+                MTR_LOG_ERROR("%@ Error: acceptedTermsAndConditionsVersion value should be between 0 and 65535", self);
+                *error = [MTRError errorForCHIPErrorCode:CHIP_ERROR_INVALID_INTEGER_VALUE];
+                return NO;
+            }
+
+            chip::Controller::TermsAndConditionsAcknowledgement termsAndConditionsAcknowledgement = {
+                .acceptedTermsAndConditions = static_cast<uint16_t>([commissioningParams.acceptedTermsAndConditions unsignedIntValue]),
+                .acceptedTermsAndConditionsVersion = static_cast<uint16_t>([commissioningParams.acceptedTermsAndConditionsVersion unsignedIntValue])
+            };
+            params.SetTermsAndConditionsAcknowledgement(termsAndConditionsAcknowledgement);
+        }
         params.SetSkipCommissioningComplete(commissioningParams.skipCommissioningComplete);
         if (commissioningParams.wifiSSID) {
             chip::ByteSpan ssid = AsByteSpan(commissioningParams.wifiSSID);

src/darwin/Framework/CHIP/MTRDeviceController_Concrete.mm

@@ -455,6 +455,10 @@
 		CF3B63D12CA31E71003C1C87 /* MTROTAImageTransferHandler.mm in Sources */ = {isa = PBXBuildFile; fileRef = CF3B63CD2CA31E71003C1C87 /* MTROTAImageTransferHandler.mm */; };
 		CF3B63D22CA31E71003C1C87 /* MTROTAUnsolicitedBDXMessageHandler.mm in Sources */ = {isa = PBXBuildFile; fileRef = CF3B63CE2CA31E71003C1C87 /* MTROTAUnsolicitedBDXMessageHandler.mm */; };
 		D4288E872C8A273F002FEC53 /* MTRDevice_XPC_Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = D4288E862C8A273F002FEC53 /* MTRDevice_XPC_Internal.h */; };
+		B4D67A922D527F4A00C49965 /* DCLClient.cpp in Sources */ = {isa = PBXBuildFile; fileRef = B4D67A8E2D527F4A00C49965 /* DCLClient.cpp */; };
+		B4D67A932D527F4A00C49965 /* DisplayTermsAndConditions.cpp in Sources */ = {isa = PBXBuildFile; fileRef = B4D67A8F2D527F4A00C49965 /* DisplayTermsAndConditions.cpp */; };
+		B4D67A952D527F4A00C49965 /* JsonSchemaMacros.cpp in Sources */ = {isa = PBXBuildFile; fileRef = B4D67A912D527F4A00C49965 /* JsonSchemaMacros.cpp */; };
+		B4D67A9B2D538E9700C49965 /* HTTPSRequest.mm in Sources */ = {isa = PBXBuildFile; fileRef = B4D67A992D538E9700C49965 /* HTTPSRequest.mm */; };
 		D444F9A72C6E8F9D007761E5 /* MTRXPCServerProtocol.h in Headers */ = {isa = PBXBuildFile; fileRef = D444F9A62C6E8F9D007761E5 /* MTRXPCServerProtocol.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		D444F9AA2C6E9A08007761E5 /* MTRXPCClientProtocol.h in Headers */ = {isa = PBXBuildFile; fileRef = D444F9A82C6E99CA007761E5 /* MTRXPCClientProtocol.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		D4772A46285AE98400383630 /* MTRClusterConstants.h in Headers */ = {isa = PBXBuildFile; fileRef = D4772A45285AE98300383630 /* MTRClusterConstants.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -963,6 +967,10 @@
 		CF3B63CD2CA31E71003C1C87 /* MTROTAImageTransferHandler.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MTROTAImageTransferHandler.mm; sourceTree = "<group>"; };
 		CF3B63CE2CA31E71003C1C87 /* MTROTAUnsolicitedBDXMessageHandler.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MTROTAUnsolicitedBDXMessageHandler.mm; sourceTree = "<group>"; };
 		D4288E862C8A273F002FEC53 /* MTRDevice_XPC_Internal.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MTRDevice_XPC_Internal.h; sourceTree = "<group>"; };
+		B4D67A8E2D527F4A00C49965 /* DCLClient.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; name = DCLClient.cpp; path = commands/dcl/DCLClient.cpp; sourceTree = "<group>"; };
+		B4D67A8F2D527F4A00C49965 /* DisplayTermsAndConditions.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; name = DisplayTermsAndConditions.cpp; path = commands/dcl/DisplayTermsAndConditions.cpp; sourceTree = "<group>"; };
+		B4D67A912D527F4A00C49965 /* JsonSchemaMacros.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; name = JsonSchemaMacros.cpp; path = commands/dcl/JsonSchemaMacros.cpp; sourceTree = "<group>"; };
+		B4D67A992D538E9700C49965 /* HTTPSRequest.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = HTTPSRequest.mm; sourceTree = "<group>"; };
 		D437613E285BDC0D0051FEA2 /* MTRErrorTestUtils.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTRErrorTestUtils.h; sourceTree = "<group>"; };
 		D437613F285BDC0D0051FEA2 /* MTRTestKeys.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTRTestKeys.h; sourceTree = "<group>"; };
 		D4376140285BDC0D0051FEA2 /* MTRTestStorage.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MTRTestStorage.h; sourceTree = "<group>"; };
@@ -1031,6 +1039,7 @@
 		037C3D7B2991BD4F00B7EEE2 /* commands */ = {
 			isa = PBXGroup;
 			children = (
+				B4D67A9A2D538E9700C49965 /* dcl */,
 				B43B39E92CB859A5006AA284 /* memory */,
 				5124311D2BA0C09A000BC136 /* configuration */,
 				B4FCD56C2B603A6300832859 /* bdx */,
@@ -1157,6 +1166,9 @@
 		039546872991C400006D42A8 /* chip-tool */ = {
 			isa = PBXGroup;
 			children = (
+				B4D67A8E2D527F4A00C49965 /* DCLClient.cpp */,
+				B4D67A8F2D527F4A00C49965 /* DisplayTermsAndConditions.cpp */,
+				B4D67A912D527F4A00C49965 /* JsonSchemaMacros.cpp */,
 				0382FA2F2992F40C00247BBB /* ComplexArgumentParser.cpp */,
 				0382FA2B2992F06C00247BBB /* Commands.cpp */,
 				0382FA292992F05E00247BBB /* Command.cpp */,
@@ -1760,6 +1772,14 @@
 			path = "../common/websocket-server";
 			sourceTree = "<group>";
 		};
+		B4D67A9A2D538E9700C49965 /* dcl */ = {
+			isa = PBXGroup;
+			children = (
+				B4D67A992D538E9700C49965 /* HTTPSRequest.mm */,
+			);
+			path = dcl;
+			sourceTree = "<group>";
+		};
 		B4E262182AA0CFFE00DBA5BC /* delay */ = {
 			isa = PBXGroup;
 			children = (
@@ -2198,9 +2218,13 @@
 				B45373D22A9FEB0C00807602 /* buflist.c in Sources */,
 				7592BCFB2CBEE98C00EB74A0 /* CodegenDataModelProvider_Read.cpp in Sources */,
 				7592BCFC2CBEE98C00EB74A0 /* Instance.cpp in Sources */,
+				B4D67A9B2D538E9700C49965 /* HTTPSRequest.mm in Sources */,
 				7592BCFD2CBEE98C00EB74A0 /* EmberMetadata.cpp in Sources */,
 				7592BCFE2CBEE98C00EB74A0 /* CodegenDataModelProvider.cpp in Sources */,
 				7592BCFF2CBEE98C00EB74A0 /* CodegenDataModelProvider_Write.cpp in Sources */,
+				B4D67A922D527F4A00C49965 /* DCLClient.cpp in Sources */,
+				B4D67A932D527F4A00C49965 /* DisplayTermsAndConditions.cpp in Sources */,
+				B4D67A952D527F4A00C49965 /* JsonSchemaMacros.cpp in Sources */,
 				B45373C12A9FEA9100807602 /* close.c in Sources */,
 				B45373D42A9FEB0C00807602 /* context.c in Sources */,
 				B45373E52A9FEBA400807602 /* date.c in Sources */,