Add GNP Sim Swap API (#296)

* adding the structure

* add sim swap api

* Bump version: 3.14.0 → 3.15.0

* blackening file

Author: maxkahan

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.14.0
+current_version = 3.15.0
 commit = True
 tag = False
 

CHANGES.md

@@ -1,3 +1,6 @@
+# 3.15.0
+- Add support for the [Vonage Sim Swap API](https://developer.vonage.com/en/sim-swap/overview)
+
 # 3.14.0
 - Add publisher-only as a valid Video API client token role
 

README.md

@@ -29,6 +29,7 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
 - [Managing Secrets](#managing-secrets)
 - [Application API](#application-api)
 - [Users API](#users-api)
+- [Sim Swap API](#sim-swap-api)
 - [Validating Webhook Signatures](#validate-webhook-signatures)
 - [JWT Parameters](#jwt-parameters)
 - [Overriding API Attributes](#overriding-api-attributes)
@@ -1137,6 +1138,22 @@ client.users.update_user('USER_ID', params={...})
 client.users.delete_user('USER_ID')
 ```
 
+## Sim Swap API
+
+This can be used to check the sim swap status of a device. You must register a business account with Vonage and create a network profile in order to use this API. [More information on authentication can be found in the Vonage Developer documentation]('https://developer.vonage.com/en/getting-started-network/authentication').
+
+### Check the Sim Swap Status of a Number
+
+```python
+client.sim_swap.check('447700900000', max_age=24)
+```
+
+### Retrieve the Last Sim Swap Date for a Number
+
+```python
+client.sim_swap.get_last_swap_date('447700900000')
+```
+
 ## Validate webhook signatures
 
 ```python

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name="vonage",
-    version="3.14.0",
+    version="3.15.0",
     description="Vonage Server SDK for Python",
     long_description=long_description,
     long_description_content_type="text/markdown",

src/vonage/__init__.py

@@ -1,4 +1,4 @@
 from .client import *
 from .ncco_builder.ncco import *
 
-__version__ = "3.14.0"
+__version__ = "3.15.0"

src/vonage/camara_auth.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from vonage import Client
+
+
+class CamaraAuth:
+    """Class containing methods for authenticating APIs following Camara standards."""
+
+    def __init__(self, client: Client):
+        self._client = client
+        self._auth_type = 'jwt'
+
+    def make_oidc_request(self, number: str, scope: str):
+        """Make an OIDC request to authenticate a user.
+
+        Returns a code that can be used to request a Camara token."""
+
+        login_hint = f'tel:+{number}'
+        params = {'login_hint': login_hint, 'scope': scope}
+
+        return self._client.post(
+            'api-eu.vonage.com',
+            '/oauth2/bc-authorize',
+            params=params,
+            auth_type=self._auth_type,
+            body_is_json=False,
+        )
+
+    def request_camara_token(
+        self, oidc_response: dict, grant_type: str = 'urn:openid:params:grant-type:ciba'
+    ):
+        """Request a Camara token using an authentication request ID given as a
+        response to the OIDC request.
+        """
+        params = {
+            'grant_type': grant_type,
+            'auth_req_id': oidc_response['auth_req_id'],
+        }
+
+        token_response = self._client.post(
+            'api-eu.vonage.com',
+            '/oauth2/token',
+            params=params,
+            auth_type=self._auth_type,
+            body_is_json=False,
+        )
+        return token_response['access_token']

src/vonage/client.py

@@ -10,6 +10,7 @@
 from .number_management import Numbers
 from .proactive_connect import ProactiveConnect
 from .redact import Redact
+from .sim_swap import SimSwap
 from .short_codes import ShortCodes
 from .sms import Sms
 from .subaccounts import Subaccounts
@@ -133,6 +134,7 @@ def __init__(
         self.numbers = Numbers(self)
         self.proactive_connect = ProactiveConnect(self)
         self.short_codes = ShortCodes(self)
+        self.sim_swap = SimSwap(self)
         self.sms = Sms(self)
         self.subaccounts = Subaccounts(self)
         self.users = Users(self)
@@ -258,6 +260,7 @@ def post(
         auth_type=None,
         body_is_json=True,
         supports_signature_auth=False,
+        oauth_token=None,
     ):
         """
         Low-level method to make a post request to an API server.
@@ -283,9 +286,11 @@ def post(
             )
         elif auth_type == 'header':
             self._request_headers['Authorization'] = self._create_header_auth_string()
+        elif auth_type == 'oauth2':
+            self._request_headers['Authorization'] = self._create_oauth2_auth_string(oauth_token)
         else:
             raise InvalidAuthenticationTypeError(
-                f'Invalid authentication type. Must be one of "jwt", "header" or "params".'
+                f'Invalid authentication type. Must be one of "jwt", "header", "params" or "oauth2".'
             )
 
         logger.debug(
@@ -461,3 +466,6 @@ def _generate_application_jwt(self):
     def _create_header_auth_string(self):
         hash = base64.b64encode(f"{self.api_key}:{self.api_secret}".encode("utf-8")).decode("ascii")
         return f"Basic {hash}"
+
+    def _create_oauth2_auth_string(self, token: str):
+        return f'Bearer {token}'

src/vonage/sim_swap.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .camara_auth import CamaraAuth
+
+if TYPE_CHECKING:
+    from vonage import Client
+
+
+class SimSwap:
+    """Class containing methods for working with the Vonage SIM Swap API."""
+
+    def __init__(self, client: Client):
+        self._client = client
+        self._auth_type = 'oauth2'
+        self._camara_auth = CamaraAuth(client)
+
+    def check(self, phone_number: str, max_age: int = None):
+        """Check if a SIM swap has been performed in a given time frame.
+
+        Args:
+            phone_number (str): The phone number to check. Use the E.164 format without a leading +.
+            max_age (int, optional): Period in hours to be checked for SIM swap.
+
+        Returns:
+            The response from the API as a dict.
+        """
+        oicd_response = self._camara_auth.make_oidc_request(
+            number=phone_number, scope='dpv:FraudPreventionAndDetection#check-sim-swap'
+        )
+        token = self._camara_auth.request_camara_token(oicd_response)
+
+        params = {'phoneNumber': phone_number}
+        if max_age:
+            params['maxAge'] = max_age
+
+        return self._client.post(
+            'api-eu.vonage.com',
+            '/camara/sim-swap/v040/check',
+            params=params,
+            auth_type=self._auth_type,
+            oauth_token=token,
+        )
+
+    def get_last_swap_date(self, phone_number: str):
+        """Get the last SIM swap date for a phone number.
+
+        Args:
+            phone_number (str): The phone number to check. Use the E.164 format without a leading +.
+
+        Returns:
+            The response from the API as a dict.
+        """
+        oicd_response = self._camara_auth.make_oidc_request(
+            number=phone_number,
+            scope='dpv:FraudPreventionAndDetection#retrieve-sim-swap-date',
+        )
+        token = self._camara_auth.request_camara_token(oicd_response)
+        return self._client.post(
+            'api-eu.vonage.com',
+            '/camara/sim-swap/v040/retrieve-date',
+            params={'phoneNumber': phone_number},
+            auth_type=self._auth_type,
+            oauth_token=token,
+        )

tests/conftest.py

@@ -139,3 +139,17 @@ def proc(client):
     import vonage
 
     return vonage.ProactiveConnect(client)
+
+
+@pytest.fixture
+def camara_auth(client):
+    from vonage.camara_auth import CamaraAuth
+
+    return CamaraAuth(client)
+
+
+@pytest.fixture
+def sim_swap(client):
+    import vonage
+
+    return vonage.SimSwap(client)

tests/data/camara_auth/oidc_request.json

@@ -0,0 +1,5 @@
+{
+    "auth_req_id": "arid/8b0d35f3-4627-487c-a776-aegtdsf4rsd2",
+    "expires_in": 300,
+    "interval": 0
+}