refactor: rename fpnv module to phone_number_verification for clarity

Author: jonathanedey

firebase_admin/fpnv.py …ebase_admin/phone_number_verification.pyfirebase_admin/fpnv.py renamed to firebase_admin/phone_number_verification.py firebase_admin/fpnv.py renamed to firebase_admin/phone_number_verification.py

@@ -22,13 +22,13 @@
 
 import jwt
 from jwt import (
-    PyJWKClient, InvalidTokenError, DecodeError, InvalidSignatureError,
+    PyJWKClient, InvalidSignatureError,
     PyJWKClientError, InvalidAudienceError, InvalidIssuerError, ExpiredSignatureError
 )
 
 from firebase_admin import App, _utils, exceptions
 
-_FPNV_ATTRIBUTE = '_fpnv'
+_FPNV_ATTRIBUTE = '_phone_number_verification'
 _FPNV_JWKS_URL = 'https://fpnv.googleapis.com/v1beta/jwks'
 _FPNV_ISSUER = 'https://fpnv.googleapis.com/projects/'
 _ALGORITHM_ES256 = 'ES256'
@@ -37,25 +37,25 @@
 def _get_fpnv_service(app):
     return _utils.get_app_service(app, _FPNV_ATTRIBUTE, _FpnvService)
 
-def verify_token(token: str, app: Optional[App] = None) -> FpnvToken:
+def verify_token(token: str, app: Optional[App] = None) -> PhoneNumberVerificationToken:
     """Verifies a Firebase Phone Number Verification (FPNV) token.
 
     Args:
         token: A string containing the FPNV JWT.
         app: An App instance (optional).
 
     Returns:
-        FpnvToken: The verified token claims.
+        PhoneNumberVerificationToken: The verified token claims.
 
     Raises:
         ValueError: If the token is not a string or is empty.
-        InvalidFpnvTokenError: If the token is invalid or malformed.
-        ExpiredFpnvTokenError: If the token has expired.
+        InvalidTokenError: If the token is invalid or malformed.
+        ExpiredTokenError: If the token has expired.
     """
     return _get_fpnv_service(app).verify_token(token)
 
 
-class FpnvToken(dict):
+class PhoneNumberVerificationToken(dict):
     """Represents a verified FPNV token.
 
     This class behaves like a dictionary, allowing access to the decoded claims.
@@ -118,23 +118,23 @@ def __init__(self, app):
 
         self._verifier = _FpnvTokenVerifier(self._project_id)
 
-    def verify_token(self, token) -> FpnvToken:
-        """Verifies the given FPNV token.
+    def verify_token(self, token) -> PhoneNumberVerificationToken:
+        """Verifies a Firebase Phone Number Verification token.
 
         Verifies the signature, expiration, and claims of the token.
 
         Args:
-            token: A string containing the FPNV JWT.
+            token: A string containing the Firebase Phone Number Verification JWT.
 
         Returns:
-            FpnvToken: The verified token claims.
+            PhoneNumberVerificationToken: The verified token claims.
 
         Raises:
             ValueError: If the token is not a string or is empty.
-            InvalidFpnvTokenError: If the token is invalid or malformed.
-            ExpiredFpnvTokenError: If the token has expired.
+            InvalidTokenError: If the token is invalid or malformed.
+            ExpiredTokenError: If the token has expired.
         """
-        return FpnvToken(self._verifier.verify(token))
+        return PhoneNumberVerificationToken(self._verifier.verify(token))
 
 
 class _FpnvTokenVerifier:
@@ -153,9 +153,9 @@ def verify(self, token) -> Dict[str, Any]:
             self._validate_headers(jwt.get_unverified_header(token))
             signing_key = self._jwks_client.get_signing_key_from_jwt(token)
             claims = self._decode_and_verify(token, signing_key.key)
-        except (InvalidTokenError, DecodeError, PyJWKClientError) as exception:
-            raise InvalidFpnvTokenError(
-                'Verifying FPNV token failed.',
+        except (jwt.InvalidTokenError, PyJWKClientError) as exception:
+            raise InvalidTokenError(
+                'Verifying phone number verification token failed.',
                 cause=exception,
                 http_response=getattr(exception, 'http_response', None)
             ) from exception
@@ -165,18 +165,18 @@ def verify(self, token) -> Dict[str, Any]:
     def _validate_headers(self, headers: Any) -> None:
         """Validates the headers."""
         if headers.get('kid') is None:
-            raise InvalidFpnvTokenError("FPNV has no 'kid' claim.")
+            raise InvalidTokenError("Token has no 'kid' claim.")
 
         if headers.get('typ') != 'JWT':
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an incorrect type header. ' \
+            raise InvalidTokenError(
+                'The provided token has an incorrect type header. ' \
                 f"Expected 'JWT' but got {headers.get('typ')!r}."
             )
 
         algorithm = headers.get('alg')
         if algorithm != _ALGORITHM_ES256:
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an incorrect alg header. '
+            raise InvalidTokenError(
+                'The provided token has an incorrect alg header. '
                 f'Expected {_ALGORITHM_ES256} but got {algorithm}.'
             )
 
@@ -192,32 +192,32 @@ def _decode_and_verify(self, token, signing_key) -> Dict[str, Any]:
                 issuer=expected_issuer
             )
         except InvalidSignatureError as exception:
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an invalid signature.'
+            raise InvalidTokenError(
+                'The provided token has an invalid signature.'
             ) from exception
         except InvalidAudienceError as exception:
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an incorrect "aud" (audience) claim. '
+            raise InvalidTokenError(
+                'The provided token has an incorrect "aud" (audience) claim. '
                 f'Expected {expected_issuer}.'
             ) from exception
         except InvalidIssuerError as exception:
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an incorrect "iss" (issuer) claim. '
+            raise InvalidTokenError(
+                'The provided token has an incorrect "iss" (issuer) claim. '
                 f'Expected {expected_issuer}.'
             ) from exception
         except ExpiredSignatureError as exception:
-            raise ExpiredFpnvTokenError(
-                'The provided FPNV token has expired.'
+            raise ExpiredTokenError(
+                'The provided token has expired.'
             ) from exception
-        except InvalidTokenError as exception:
-            raise InvalidFpnvTokenError(
-                f'Decoding FPNV token failed. Error: {exception}'
+        except jwt.InvalidTokenError as exception:
+            raise InvalidTokenError(
+                f'Decoding token failed. Error: {exception}'
             ) from exception
 
         sub_claim = payload.get('sub')
         if not isinstance(sub_claim, str) or not sub_claim:
-            raise InvalidFpnvTokenError(
-                'The provided FPNV token has an incorrect "sub" (subject) claim. '
+            raise InvalidTokenError(
+                'The provided token has an incorrect "sub" (subject) claim. '
                 'Expected a non-empty string.'
             )
 
@@ -237,14 +237,14 @@ def check_string(cls, label: str, value: Any):
             raise ValueError(f'{label} must be a non-empty string.')
 
 # Firebase Phone Number Verification (FPNV) Errors
-class InvalidFpnvTokenError(exceptions.InvalidArgumentError):
-    """Raised when an FPNV token is invalid."""
+class InvalidTokenError(exceptions.InvalidArgumentError):
+    """Raised when a Firebase Phone Number Verification token is invalid."""
 
     def __init__(self, message, cause=None, http_response=None):
         exceptions.InvalidArgumentError.__init__(self, message, cause, http_response)
 
-class ExpiredFpnvTokenError(InvalidFpnvTokenError):
-    """Raised when an FPNV token is expired."""
+class ExpiredTokenError(InvalidTokenError):
+    """Raised when a Firebase Phone Number Verification token is expired."""
 
     def __init__(self, message, cause=None, http_response=None):
-        InvalidFpnvTokenError.__init__(self, message, cause, http_response)
+        InvalidTokenError.__init__(self, message, cause, http_response)

tests/test_fpnv.py tests/test_phone_number_verification.pytests/test_fpnv.py renamed to tests/test_phone_number_verification.py

@@ -24,7 +24,7 @@
 from cryptography.hazmat.primitives.asymmetric import ec
 
 import firebase_admin
-from firebase_admin import fpnv
+from firebase_admin import phone_number_verification as fpnv
 from tests import testutils
 
 # Mock Data
@@ -62,7 +62,7 @@ def teardown_class(cls):
 
 class TestFpnvToken:
     def test_properties(self):
-        token = fpnv.FpnvToken(_MOCK_PAYLOAD)
+        token = fpnv.PhoneNumberVerificationToken(_MOCK_PAYLOAD)
 
         assert token.phone_number == _PHONE_NUMBER
         assert token.sub == _PHONE_NUMBER
@@ -140,7 +140,9 @@ def to_b64url(b_data):
 
     def test_verify_token_module_level_delegation(self):
         """Verifies module-level verify_token delegates correctly."""
-        with patch('firebase_admin.fpnv._FpnvService.verify_token') as mock_verify:
+        with patch(
+            'firebase_admin.phone_number_verification._FpnvService.verify_token'
+        ) as mock_verify:
             mock_verify.return_value = 'mock-result'
             res = fpnv.verify_token('some-token')
             assert res == 'mock-result'
@@ -168,7 +170,7 @@ def test_verify_token_success(self, mock_header, mock_decode, mock_jwks_cls):
         token = fpnv.verify_token(token_str)
 
         # Verify
-        assert isinstance(token, fpnv.FpnvToken)
+        assert isinstance(token, fpnv.PhoneNumberVerificationToken)
         assert token.phone_number == _PHONE_NUMBER
 
         mock_header.assert_called_with(token_str)
@@ -192,19 +194,19 @@ def test_verify_token_no_name(self, mock_header):
     def test_verify_token_no_kid(self, mock_header):
         app = firebase_admin.get_app()
         mock_header.return_value = {'typ': 'JWT', 'alg': 'ES256'}  # Missing kid
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="FPNV has no 'kid' claim."):
+        with pytest.raises(fpnv.InvalidTokenError, match="Token has no 'kid' claim."):
             fpnv.verify_token('token', app=app)
 
     @mock.patch('jwt.get_unverified_header')
     def test_verify_token_wrong_alg(self, mock_header):
         mock_header.return_value = {'kid': 'k', 'typ': 'JWT', 'alg': 'RS256'}  # Wrong alg
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="incorrect alg"):
+        with pytest.raises(fpnv.InvalidTokenError, match="incorrect alg"):
             fpnv.verify_token('token')
 
     @mock.patch('jwt.get_unverified_header')
     def test_verify_token_wrong_typ(self, mock_header):
         mock_header.return_value = {'kid': 'k', 'typ': 'WRONG', 'alg': 'ES256'} # wrong typ
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="incorrect type header"):
+        with pytest.raises(fpnv.InvalidTokenError, match="incorrect type header"):
             fpnv.verify_token('token')
 
     def test_verify_token_jwk_error(self):
@@ -219,7 +221,10 @@ def test_verify_token_jwk_error(self):
             with mock.patch('jwt.get_unverified_header') as mock_header:
                 mock_header.return_value = {'kid': 'k', 'typ': 'JWT', 'alg': 'ES256'}
 
-                with pytest.raises(fpnv.InvalidFpnvTokenError, match="Verifying FPNV token failed"):
+                with pytest.raises(
+                    fpnv.InvalidTokenError,
+                    match="Verifying phone number verification token failed"
+                ):
                     fpnv.verify_token('token')
 
     @mock.patch('jwt.PyJWKClient')
@@ -235,7 +240,7 @@ def test_verify_token_expired(self, mock_header, mock_decode, mock_jwks_cls):
         # Simulate ExpiredSignatureError
         mock_decode.side_effect = jwt.ExpiredSignatureError("Expired")
 
-        with pytest.raises(fpnv.ExpiredFpnvTokenError, match="token has expired"):
+        with pytest.raises(fpnv.ExpiredTokenError, match="token has expired"):
             fpnv.verify_token('token')
 
     @mock.patch('jwt.PyJWKClient')
@@ -251,7 +256,7 @@ def test_verify_token_invalid_signature(self, mock_header, mock_decode, mock_jwk
         # Simulate InvalidSignatureError
         mock_decode.side_effect = jwt.InvalidSignatureError("Wrong Signature")
 
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="invalid signature"):
+        with pytest.raises(fpnv.InvalidTokenError, match="invalid signature"):
             fpnv.verify_token('token')
 
     @mock.patch('jwt.PyJWKClient')
@@ -267,7 +272,7 @@ def test_verify_token_invalid_audience(self, mock_header, mock_decode, mock_jwks
         # Simulate InvalidAudienceError
         mock_decode.side_effect = jwt.InvalidAudienceError("Wrong Aud")
 
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="incorrect \"aud\""):
+        with pytest.raises(fpnv.InvalidTokenError, match="incorrect \"aud\""):
             fpnv.verify_token('token')
 
     @mock.patch('jwt.PyJWKClient')
@@ -283,7 +288,7 @@ def test_verify_token_invalid_issuer(self, mock_header, mock_decode, mock_jwks_c
         # Simulate InvalidIssuerError
         mock_decode.side_effect = jwt.InvalidIssuerError("Wrong Iss")
 
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="incorrect \"iss\""):
+        with pytest.raises(fpnv.InvalidTokenError, match="incorrect \"iss\""):
             fpnv.verify_token('token')
 
     @mock.patch('jwt.PyJWKClient')
@@ -299,5 +304,5 @@ def test_verify_token_invalid_token(self, mock_header, mock_decode, mock_jwks_cl
         # Simulate InvalidTokenError
         mock_decode.side_effect = jwt.InvalidTokenError("Decoding FPNV token failed")
 
-        with pytest.raises(fpnv.InvalidFpnvTokenError, match="Decoding FPNV token failed"):
+        with pytest.raises(fpnv.InvalidTokenError, match="Decoding FPNV token failed"):
             fpnv.verify_token('token')