Add initial feature logic for Terms and Conditions (TC) acknowledgements

This commit introduces the initial logic for handling Terms and
Conditions (TC) acknowledgements in the General Commissioning cluster.
The logic includes support for setting and checking TC acknowledgements
and versions during the commissioning process.

Changes include:
- Handling TC acknowledgements and TC acknowledgement version in the
  pairing command.
- Logic to read TC attributes and check TC acceptance in the General
  Commissioning server.
- Introduction of classes to manage TC acceptance logic.
- Initialization and use of TC providers in the server setup.
- Addition of a new commissioning stage for TC acknowledgements in the
  commissioning flow.

The feature logic is currently disabled and will be enabled in an
example in a subsequent commit.

src/app/common_flags.gni

@@ -18,6 +18,10 @@ declare_args() {
   chip_enable_read_client = true
   chip_build_controller_dynamic_server = false
 
+  chip_config_tc_required = false
+  chip_config_tc_required_acknowledgements = 0
+  chip_config_tc_required_acknowledgements_version = 0
+
   # Flag that controls whether the time-to-wait from BUSY responses is
   # communicated to OperationalSessionSetup API consumers.
   chip_enable_busy_handling_for_operational_session_setup = true

src/app/server/BUILD.gn

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Project CHIP Authors
+# Copyright (c) 2020-2024 Project CHIP Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,6 +24,41 @@ config("server_config") {
   }
 }
 
+config("enhanced_setup_flow_config") {
+  defines = []
+  if (chip_config_tc_required) {
+    defines += [
+      "CHIP_CONFIG_TC_REQUIRED=1",
+      "CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS=${chip_config_tc_required_acknowledgements}",
+      "CHIP_CONFIG_TC_REQUIRED_ACKNOWLEDGEMENTS_VERSION=${chip_config_tc_required_acknowledgements_version}",
+    ]
+  } else {
+    defines += [ "CHIP_CONFIG_TC_REQUIRED=0" ]
+  }
+}
+
+source_set("enhanced_setup_flow_interface") {
+  sources = [
+    "DefaultEnhancedSetupFlowProvider.h",
+    "DefaultTermsAndConditionsProvider.h",
+    "EnhancedSetupFlowProvider.h",
+    "TermsAndConditionsProvider.h",
+  ]
+
+  public_configs = [ ":enhanced_setup_flow_config" ]
+
+  public_deps = [ "${chip_root}/src/lib/core" ]
+}
+
+source_set("enhanced_setup_flow") {
+  sources = [
+    "DefaultEnhancedSetupFlowProvider.cpp",
+    "DefaultTermsAndConditionsProvider.cpp",
+  ]
+
+  deps = [ ":enhanced_setup_flow_interface" ]
+}
+
 static_library("server") {
   output_name = "libCHIPAppServer"
 
@@ -51,6 +86,7 @@ static_library("server") {
   cflags = [ "-Wconversion" ]
 
   public_deps = [
+    ":enhanced_setup_flow_interface",
     "${chip_root}/src/app",
     "${chip_root}/src/app:test-event-trigger",
     "${chip_root}/src/app/icd/server:check-in-back-off",
@@ -79,4 +115,8 @@ static_library("server") {
           [ "${chip_root}/src/app/icd/server:default-check-in-back-off" ]
     }
   }
+
+  if (chip_config_tc_required) {
+    public_deps += [ ":enhanced_setup_flow" ]
+  }
 }

src/app/server/DefaultEnhancedSetupFlowProvider.cpp

@@ -0,0 +1,158 @@
+/*
+ *
+ *    Copyright (c) 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 "DefaultEnhancedSetupFlowProvider.h"
+
+#include <lib/core/CHIPConfig.h>
+#include <lib/support/CodeUtils.h>
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::Init(TermsAndConditionsProvider * const inTermsAndConditionsProvider)
+{
+    VerifyOrReturnError(nullptr != inTermsAndConditionsProvider, CHIP_ERROR_INVALID_ARGUMENT);
+
+    mTermsAndConditionsProvider = inTermsAndConditionsProvider;
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR
+chip::app::DefaultEnhancedSetupFlowProvider::HasTermsAndConditionsRequiredAcknowledgementsBeenAccepted(bool & outAccepted) const
+{
+    uint16_t requiredAcknowledgements;
+    uint16_t requiredAcknowledgementsVersion;
+    uint16_t acceptedAcknowledgements;
+    uint16_t acceptedAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetRequirements(requiredAcknowledgements, requiredAcknowledgementsVersion));
+
+    if (0 == requiredAcknowledgements)
+    {
+        outAccepted = true;
+        return CHIP_NO_ERROR;
+    }
+
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetAcceptance(acceptedAcknowledgements, acceptedAcknowledgementsVersion));
+
+    outAccepted = ((requiredAcknowledgements & acceptedAcknowledgements) == requiredAcknowledgements);
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::HasTermsAndConditionsRequiredAcknowledgementsVersionBeenAccepted(
+    bool & outAccepted) const
+{
+    uint16_t requiredAcknowledgements;
+    uint16_t requiredAcknowledgementsVersion;
+    uint16_t acceptedAcknowledgements;
+    uint16_t acceptedAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetRequirements(requiredAcknowledgements, requiredAcknowledgementsVersion));
+
+    if (0 == requiredAcknowledgementsVersion)
+    {
+        outAccepted = true;
+        return CHIP_NO_ERROR;
+    }
+
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetAcceptance(acceptedAcknowledgements, acceptedAcknowledgementsVersion));
+
+    outAccepted = (acceptedAcknowledgementsVersion >= requiredAcknowledgementsVersion);
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::IsTermsAndConditionsAcceptanceRequired(bool & outValue) const
+{
+    // Default implementation requires terms and conditions check only if not previously accepted. Other implementations may skip
+    // requiring a terms and conditions check on secondary commissioning, in the case that the required terms and conditions may
+    // have changed.
+    return HasTermsAndConditionsRequiredAcknowledgementsVersionBeenAccepted(outValue);
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::GetTermsAndConditionsRequiredAcknowledgements(uint16_t & outValue) const
+{
+    uint16_t requiredAcknowledgements;
+    uint16_t requiredAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetRequirements(requiredAcknowledgements, requiredAcknowledgementsVersion));
+
+    outValue = requiredAcknowledgements;
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR
+chip::app::DefaultEnhancedSetupFlowProvider::GetTermsAndConditionsRequiredAcknowledgementsVersion(uint16_t & outValue) const
+{
+    uint16_t requiredAcknowledgements;
+    uint16_t requiredAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetRequirements(requiredAcknowledgements, requiredAcknowledgementsVersion));
+
+    outValue = requiredAcknowledgementsVersion;
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::GetTermsAndConditionsAcceptedAcknowledgements(uint16_t & outValue) const
+{
+    uint16_t acceptedAcknowledgements;
+    uint16_t acceptedAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetAcceptance(acceptedAcknowledgements, acceptedAcknowledgementsVersion));
+
+    outValue = acceptedAcknowledgements;
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR
+chip::app::DefaultEnhancedSetupFlowProvider::GetTermsAndConditionsAcceptedAcknowledgementsVersion(uint16_t & outValue) const
+{
+    uint16_t acceptedAcknowledgements;
+    uint16_t acceptedAcknowledgementsVersion;
+
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->GetAcceptance(acceptedAcknowledgements, acceptedAcknowledgementsVersion));
+
+    outValue = acceptedAcknowledgementsVersion;
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::SetTermsAndConditionsAcceptance(uint16_t inTCAcknowledgementsValue,
+                                                                                        uint16_t inTCAcknowledgementsVersionValue)
+{
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->SetAcceptance(inTCAcknowledgementsValue, inTCAcknowledgementsVersionValue));
+
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR chip::app::DefaultEnhancedSetupFlowProvider::ClearTermsAndConditionsAcceptance()
+{
+    VerifyOrReturnError(nullptr != mTermsAndConditionsProvider, CHIP_ERROR_UNINITIALIZED);
+    ReturnErrorOnFailure(mTermsAndConditionsProvider->ClearAcceptance());
+
+    return CHIP_NO_ERROR;
+}

src/app/server/DefaultEnhancedSetupFlowProvider.h

@@ -0,0 +1,65 @@
+/*
+ *
+ *    Copyright (c) 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.
+ */
+
+#pragma once
+
+#include "EnhancedSetupFlowProvider.h"
+
+#include <stdint.h>
+
+#include <lib/core/CHIPConfig.h>
+#include <lib/core/CHIPError.h>
+
+#include "TermsAndConditionsProvider.h"
+
+namespace chip {
+namespace app {
+class DefaultEnhancedSetupFlowProvider : public EnhancedSetupFlowProvider
+{
+public:
+    /**
+     * @brief Initializes the EnhancedSetupFlowProvider.
+     *
+     * @param[in] inTermsAndConditionsProvider The terms and conditions provide dependency.
+     */
+    CHIP_ERROR Init(TermsAndConditionsProvider * const inTermsAndConditionsProvider);
+
+    CHIP_ERROR HasTermsAndConditionsRequiredAcknowledgementsBeenAccepted(bool & outAccepted) const override;
+
+    CHIP_ERROR HasTermsAndConditionsRequiredAcknowledgementsVersionBeenAccepted(bool & outAccepted) const override;
+
+    CHIP_ERROR IsTermsAndConditionsAcceptanceRequired(bool & outValue) const override;
+
+    CHIP_ERROR GetTermsAndConditionsRequiredAcknowledgements(uint16_t & outValue) const override;
+
+    CHIP_ERROR GetTermsAndConditionsRequiredAcknowledgementsVersion(uint16_t & outValue) const override;
+
+    CHIP_ERROR GetTermsAndConditionsAcceptedAcknowledgements(uint16_t & outValue) const override;
+
+    CHIP_ERROR GetTermsAndConditionsAcceptedAcknowledgementsVersion(uint16_t & outValue) const override;
+
+    CHIP_ERROR SetTermsAndConditionsAcceptance(uint16_t aTCAcknowledgements, uint16_t inTCAcknowledgementsVersionValue) override;
+
+    CHIP_ERROR ClearTermsAndConditionsAcceptance() override;
+
+private:
+    TermsAndConditionsProvider * mTermsAndConditionsProvider;
+};
+
+} // namespace app
+} // namespace chip