Merge pull request #179 from fernandopradocabrillo/prepare-r2.4

Preparations for release r2.4

Author: fernandopradocabrillo

CHANGELOG.md

@@ -3,10 +3,11 @@
 
 ## Table of contents
 
-- **[r2.3](#r23)**
+- **[r2.4](#r24) Spring25**
+- ~~[r2.3](#r23)~~
 - **[r2.2](#r22)**
 - **[r2.1](#r21)**
-- **[r1.3](#r13)**
+- **[r1.3](#r13) Fall24**
 - **[r1.2](#r12)**
 - **[r1.1](#r11)**
 - **[v0.3.1](#v031)**
@@ -21,44 +22,60 @@ The below sections record the changes for each API version in each release as fo
 * for subsequent release-candidate(s), only the delta to the previous release-candidate
 * for a public release, the consolidated changes since the previous public release
 
-# r2.3
+# r2.4
 
 ## Release Notes
 
-This public release contains the definition and documentation of
-* number-verification 1.1.0
+This **public release** contains the definition and documentation of
+* number-verification 2.0.0
 
 The API definition(s) are based on
 * Commonalities v0.5.0
 * Identity and Consent Management v0.3.0
 
-## number-verification 1.1.0
+## number-verification 2.0.0
 
-**number-verification 1.1.0 is the release for v1.1.0 of the NumberVerification API.**
+**number-verification 2.0.0 is the public release for v2.0.0 of the NumberVerification API.**
+
+The NumberVerification API version has been upgraded from previous v1.0.0 to v2.0.0 even though the functionality updates included in this version do not contain any breaking change.
+However, the inclusion of a new supported authentication method (CIBA+TS.43 temporary token) to enable the use of the API over Wifi, justifies the generation of a new major version of the API.
 
 - API definition **with inline documentation**:
-  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.3/code/API_definitions/number-verification.yaml&nocors)
-  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.3/code/API_definitions/number-verification.yaml)
-  - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.3/code/API_definitions/number-verification.yaml)
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.4/code/API_definitions/number-verification.yaml)
 
-Changes included in v1.1.0 compared to v1.0.0
+Changes included in v2.0.0 compared to v1.0.0
 
 ### Changed
 
 - Align error list & model with comm 0.5 by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/161
 - Add a pattern for x-correlator allowing zero-length string by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/164
 - servers.url format aligned with current guidelines (`'{apiRoot}/number-verification/v1rc2'`) by @hdamker in https://github.com/camaraproject/NumberVerification/issues/169
 - Link into main branch replaced with link into release branch by @hdamker in https://github.com/camaraproject/NumberVerification/issues/169
+- NumberVerification over WiFi by @AxelNennker in https://github.com/camaraproject/NumberVerification/pull/174
 
 ### Removed
 
 - Remove 403 INVALID_TOKEN_CONTEXT by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/163
 
-**Full Changelog** between v1.1.0 and v1.0.0: https://github.com/camaraproject/NumberVerification/compare/r1.3...r2.3
+**Full Changelog** between v2.0.0 and v1.0.0: https://github.com/camaraproject/NumberVerification/compare/r1.3...r2.4
 
 ## New Contributors
 * @hdamker made their first contribution by servers.url format aligned with current guidelines (`'{apiRoot}/number-verification/v1rc2'`)
 
+# ~~r2.3~~
+
+**Release r2.3 has been revoked and removed in favor of the release r2.4**
+
+Following the recent approval of TS.43 temporary tokens usage in the ICM workgroup, it has been decided that this API will support them, enabling authentication over WiFi networks.
+
+As a result, in release r2.4, both authentication methods are now available:
+- AuthCode + network-based authentication
+- CIBA + TS.43 temporary tokens
+
+r2.4 is the official public release for Spring25 meta-release.
+
 # r2.2
 
 ## Release Notes

README.md

@@ -9,13 +9,13 @@
 
 # NumberVerification
 
-Incubating API Repository to evolve and maintain the definitions and documentation of the NumberVerification API family
+Incubating API Repository to evolve and maintain the definitions and documentation of the NumberVerification API
 * API Repository wiki page: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14562399/NumberVerification
 
 ## Scope
 
 * Service APIs for “NumberVerification” (see APIBacklog.md)  
-* It provides the customer with the ability to:  
+* It provides the API Provider with the ability to:  
   * verify the phone number associated with the SIM used in the device connected to the mobile data network.
 * Describe, develop, document and test the APIs (with 1-2 Telcos)  
 * Started: October 2022
@@ -26,11 +26,11 @@ Incubating API Repository to evolve and maintain the definitions and documentati
 
 * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
 
-* The public release r2.3 with version 1.1.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.3)
-  - 1.1.0 Number Verification definition **with inline documentation**:
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.3/code/API_definitions/number-verification.yaml)
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.3/code/API_definitions/number-verification.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.3/code/API_definitions/number-verification.yaml)
+* The public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4)
+  - 2.0.0 Number Verification definition **with inline documentation**:
+    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.4/code/API_definitions/number-verification.yaml)
+    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml&nocors)
+    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml)
 
 * Previous releases and pre-releases of the repository are available in https://github.com/camaraproject/NumberVerification/releases 
 * For changes see [CHANGELOG.md](https://github.com/camaraproject/NumberVerification/blob/main/CHANGELOG.md)

code/API_definitions/number-verification.yaml

@@ -47,7 +47,7 @@ info:
 
     The following sequence diagram shows an example of a direct integration into the developer's application and the API Provider's Authorization Server and API for the case that no temporary token is available.
 
-    ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg)
+    ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/documentation/API_documentation/assets/uml_v0.3.jpg)
 
     **Implementation Details:**
 
@@ -72,7 +72,7 @@ info:
 
     In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication.
 
-  version: wip
+  version: 2.0.0
   x-camara-commonalities: 0.5
   license:
     name: Apache 2.0
@@ -81,7 +81,7 @@ externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/NumberVerification
 servers:
-  - url: '{apiRoot}/number-verification/vwip'
+  - url: '{apiRoot}/number-verification/v2'
     variables:
       apiRoot:
         default: http://localhost:9091

code/Test_Definitions/number-verification-device-phone-number-share.feature

@@ -1,5 +1,4 @@
-@NumberVerification_device_phone_number_share
-Feature: Camara Number Verification API device phone number share
+Feature: CAMARA Number Verification API, v2.0.0 - Operation phoneNumberShare
 
 # Input to be provided by the implementation to the tests
 # References to OAS spec schemas refer to schemas specified in
@@ -13,7 +12,7 @@ Feature: Camara Number Verification API device phone number share
 # * a mobile device with SIM card with NUMBERVERIFY_SHARE_PHONENUMBER2
 
   Background: Common Number Verification phone number share setup
-    Given the resource "/device-phone-number/vwip"  as  base url
+    Given the resource "/device-phone-number/v2" as base url
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" is set to a UUID value
@@ -86,18 +85,18 @@ Feature: Camara Number Verification API device phone number share
 #    And the response property "$.code" is "INVALID_TOKEN_CONTEXT"
 #    And the response property "$.message" is "Phone number cannot be deducted from access token context."
 
-  @NumberVerification_phone_number_share205_must_have_used_network_authentication
-  Scenario:  share phone number with valid access token but network authentication was not used
+  @NumberVerification_phone_number_share205_must_have_used_network_or_sim_based_authentication
+  Scenario: share phone number with valid access token but neither Network-Based authentication nor SIM-Based authentication was used
     Given they use the base url
     And the resource is "/device-phone-number"
     And one of the scopes associated with the access token is number-verification:verify
     When the HTTPS "GET" request is sent
     And the connection the request is sent over originates from a device with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1
-    And the information, e.g. authentication method reference, associated with the access token indicates that network authentication was NOT used
+    And the information, e.g. authentication method reference, associated with the access token indicates that neither Network-based nor SIM-based authentication was used
     And the response header "x-correlator" has same value as the request header "x-correlator"
     And the response header "Content-Type" is "application/json"
     And the response body complies with the OAS schema at "/components/schemas/ErrorInfo"
     Then the response status code is 403
     And the response property "$.status" is 403
     And the response property "$.code" is "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK"
-    And the response property "$.message" is "The subscription must be identified via the mobile network to use this servicet."
+    And the response property "$.message" is "The subscription must be identified using either Network-based authentication or SIM-based authentication to access this service."

code/Test_Definitions/number-verification-verify.feature

@@ -1,5 +1,4 @@
-@NumberVerification_verify
-Feature: Camara Number Verification API verify
+Feature: CAMARA Number Verification API, v2.0.0 - Operation phoneNumberVerify
 
 # Input to be provided by the implementation to the tests
 # References to OAS spec schemas refer to schemas specified in
@@ -15,7 +14,7 @@ Feature: Camara Number Verification API verify
 # * a mobile device with SIM card with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER_HASHED2
 
   Background: Common Number Verification verify setup
-    Given the resource "/number-verification/vwip"  as  base url
+    Given the resource "/number-verification/v2"  as  base url
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" is set to a UUID value
@@ -184,18 +183,18 @@ Feature: Camara Number Verification API verify
 #    And the response property "$.code" is "INVALID_TOKEN_CONTEXT"
 #    And the response property "$.message" is "Phone number cannot be deducted from access token context."
 
-  @NumberVerification_phone_number_verify205_must_have_used_network_authentication
-  Scenario:  verify phone number with valid access token but network authentication was not used
+  @NumberVerification_phone_number_verify205_must_have_used_network_or_sim_based_authentication
+  Scenario: verify phone number with valid access token but neither Network-Based authentication nor SIM-Based authentication was used
     Given they use the base url
     And the resource is "/verify"
     And one of the scopes associated with the access token is number-verification:verify
     When the HTTPS "GET" request is sent
     And the connection the request is sent over originates from a device with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1
-    And the information, e.g. authentication method reference, associated with the access token indicates that network authentication was NOT used
+    And the information, e.g. authentication method reference, associated with the access token indicates that neither Network-based nor SIM-based authentication was used
     And the response header "x-correlator" has same value as the request header "x-correlator"
     And the response header "Content-Type" is "application/json"
     And the response body complies with the OAS schema at "/components/schemas/ErrorInfo"
     Then the response status code is 403
     And the response property "$.status" is 403
     And the response property "$.code" is "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK"
-    And the response property "$.message" is "The subscription must be identified via the mobile network to use this servicet."
+    And the response property "$.message" is "The subscription must be identified using either Network-based authentication or SIM-based authentication to access this service."

documentation/API_documentation/NumberVerification_device_phone_number_User_Story.md

@@ -2,9 +2,9 @@
 
 | **Item** | **Details** |
 | ---- | ------- |
-| ***Summary*** | As an application developer, I want to retrieve the phone number associated with a mobile connection. I use client credentials to authenticate and provide e.g. the IP address of the mobile connection. |
+| ***Summary*** | As an application developer, I want to retrieve the phone number associated with a mobile connection from which the API call was made, so that I can ensure that I obtain the correct phone number and avoid fraud e.g. identity theft. |
 | ***Actors and Scope*** | **Actors:** Application service provider (ASP), ASP:User, ASP: BusinessManager, ASP:Administrator, Channel Partner, End-User, Communication Service Provider (CSP). <br>**Scope:**  <br>-Returns the phone number associated with the access token so the ASPs can get the phone number and verify it themselves.|
 | ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The ASP:BusinessManager and ASP:Administrator have been onboarded to the CSP's API platform via (or not) a Channel Partner.</li><li>The ASP:BusinessManager has successfully subscribed to the Number Verification product from the CSP's product catalog via (or not) a Channel Partner.</li><li>The ASP:Administrator has onboarded the ASP:User to the CSP API platform via (or not) a Channel Partner.</li><li>The ASP:User performs an authorization request to CSP.</li><li> The CSP checks access & End-User approval then provide access token to the ASP:User </li><li> The ASP:User get the access token, via (or not) the Channel Partner, based on network authentication to ensure secure access of the API.|
-| ***Activities/Steps*** | **Starts when:** The ASP:User makes a POST request via the number verification API. This request could be done via (or not) the Channel Partner.<br>**Ends when:** The CSP's Number Verification Server answers providing the phone number corresponding to the one of the end-user's device from which the request was triggered. The ASP:User can check if this number corresponds to the one keyed by the End-User.|
+| ***Activities/Steps*** | **Starts when:** The ASP:User makes a POST request via the number verification API. This request could be done via (or not) the Channel Partner.<br>**Ends when:** The CSP's Number Verification Server answers providing the phone number corresponding to the one of the end-user's device from which the request was triggered. The ASP:User can check if this number corresponds to the one keyed by the End-User. |
 | ***Post-conditions*** | The ASP:User could continue offering its service to the End-User with the confirmation of the End-User phone number.  |
-| ***Exceptions*** | Several exceptions might occur during the Number Verification API operations<br>- Unauthorized: Not valid credentials (e.g. use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g. phone number without the '+' prefix).<br>- Not able to provide: Client authentication was not performed via mobile network. Not working on mobile hotspot (tethering) neither Wifi nor VPN mobile connections|
+| ***Exceptions*** | Several exceptions might occur during the Number Verification API operations<br>- Unauthorized: Not valid credentials (e.g. use of already expired access token).<br>- Not able to provide: Client authentication was not performed via mobile network or temporary token. Not working on mobile hotspot (tethering) neither Wifi nor VPN mobile connections **if client authentication is performed via mobile network** |