firebase-admin 7.5.0__tar.gz → 7.7.0__tar.gz

{firebase_admin-7.5.0 → firebase_admin-7.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firebase_admin
-Version: 7.5.0
+Version: 7.7.0
 Summary: Firebase Admin Python SDK
 Home-page: https://firebase.google.com/docs/admin/setup/
 Author: Firebase

{firebase_admin-7.5.0 → firebase_admin-7.7.0}/firebase_admin/__about__.py

@@ -14,7 +14,7 @@
 
 """About information (version, etc) for Firebase Admin SDK."""
 
-__version__ = '7.5.0'
+__version__ = '7.7.0'
 __title__ = 'firebase_admin'
 __author__ = 'Firebase'
 __license__ = 'Apache License 2.0'

{firebase_admin-7.5.0 → firebase_admin-7.7.0}/firebase_admin/app_check.py

@@ -15,38 +15,47 @@
 """Firebase App Check module."""
 
 from typing import Any, Dict
+import requests
 import jwt
 from jwt import PyJWKClient, ExpiredSignatureError, InvalidTokenError, DecodeError
 from jwt import InvalidAudienceError, InvalidIssuerError, InvalidSignatureError
-from firebase_admin import _utils
+from firebase_admin import _http_client, _utils, exceptions
 
 _APP_CHECK_ATTRIBUTE = '_app_check'
 
 def _get_app_check_service(app) -> Any:
     return _utils.get_app_service(app, _APP_CHECK_ATTRIBUTE, _AppCheckService)
 
-def verify_token(token: str, app=None) -> Dict[str, Any]:
-    """Verifies a Firebase App Check token.
+def verify_token(token: str, app=None, consume: bool = False) -> Dict[str, Any]:
+    """Verifies a Firebase App Check token, optionally consuming limited-use tokens.
 
     Args:
         token: A token from App Check.
         app: An App instance (optional).
+        consume: Set to ``True`` only if the token is a limited-use (one-time) token
+            that should be consumed upon verification (optional, defaults to ``False``).
 
     Returns:
-        Dict[str, Any]: The token's decoded claims.
+        Dict[str, Any]: The token's decoded claims. If ``consume`` is ``True``, the dictionary
+            also includes an ``already_consumed`` boolean key indicating whether the token was
+            previously consumed.
 
     Raises:
-        ValueError: If the app's ``project_id`` is invalid or unspecified,
-        or if the token's headers or payload are invalid.
+        ValueError: If ``consume`` is not a boolean, or if the app's ``project_id``
+            is invalid or unspecified, or if the token's headers or payload are invalid.
+        FirebaseError: If an error occurs while communicating with the App Check service.
         PyJWKClientError: If PyJWKClient fails to fetch a valid signing key.
     """
-    return _get_app_check_service(app).verify_token(token)
+    return _get_app_check_service(app).verify_token(token, consume=consume)
 
 class _AppCheckService:
     """Service class that implements Firebase App Check functionality."""
 
     _APP_CHECK_ISSUER = 'https://firebaseappcheck.googleapis.com/'
     _JWKS_URL = 'https://firebaseappcheck.googleapis.com/v1/jwks'
+    _VERIFY_URL_FORMAT = (
+        'https://firebaseappcheck.googleapis.com/v1beta/projects/{project_id}:verifyAppCheckToken'
+    )
     _project_id = None
     _scoped_project_id = None
     _jwks_client = None
@@ -68,11 +77,15 @@ class _AppCheckService:
         # Default lifespan is 300 seconds (5 minutes) so we change it to 21600 seconds (6 hours).
         self._jwks_client = PyJWKClient(
             self._JWKS_URL, lifespan=21600, headers=self._APP_CHECK_HEADERS)
+        timeout = app.options.get('httpTimeout', _http_client.DEFAULT_TIMEOUT_SECONDS)
+        self._http_client = _http_client.JsonHttpClient(
+            credential=app.credential.get_credential(), timeout=timeout)
 
 
-    def verify_token(self, token: str) -> Dict[str, Any]:
-        """Verifies a Firebase App Check token."""
+    def verify_token(self, token: str, consume: bool = False) -> Dict[str, Any]:
+        """Verifies a Firebase App Check token, optionally consuming limited-use tokens."""
         _Validators.check_string("app check token", token)
+        _Validators.check_boolean("consume", consume)
 
         # Obtain the Firebase App Check Public Keys
         # Note: It is not recommended to hard code these keys as they rotate,
@@ -87,8 +100,32 @@ class _AppCheckService:
                 ) from exception
 
         verified_claims['app_id'] = verified_claims.get('sub')
+
+        if consume:
+            verified_claims['already_consumed'] = self._verify_replay_protection(token)
+
         return verified_claims
 
+    def _verify_replay_protection(self, token: str) -> bool:
+        """Verifies replay protection with the backend and returns the alreadyConsumed status."""
+        url = self._VERIFY_URL_FORMAT.format(project_id=self._project_id)
+        try:
+            body = self._http_client.body('post', url, json={'app_check_token': token})
+        except requests.exceptions.RequestException as error:
+            raise _utils.handle_platform_error_from_requests(error)
+        except ValueError as error:
+            raise exceptions.UnknownError(
+                f'Unexpected response from App Check service: {error}'
+            ) from error
+
+        if not isinstance(body, dict):
+            raise exceptions.UnknownError(
+                'Unexpected response from App Check service. '
+                f'Expected a JSON object, but got {type(body).__name__}.'
+            )
+
+        return bool(body.get('alreadyConsumed', False))
+
     def _has_valid_token_headers(self, headers: Any) -> None:
         """Checks whether the token has valid headers for App Check."""
         # Ensure the token's header has type JWT
@@ -159,3 +196,10 @@ class _Validators:
             raise ValueError(f'{label} "{value}" must be a non-empty string.')
         if not isinstance(value, str):
             raise ValueError(f'{label} "{value}" must be a string.')
+
+    @classmethod
+    def check_boolean(cls, label: str, value: Any):
+        """Checks if the given value is a boolean."""
+        if not isinstance(value, bool):
+            raise ValueError(f'{label} must be a boolean.')
+        return value

{firebase_admin-7.5.0 → firebase_admin-7.7.0}/firebase_admin/messaging.py

@@ -15,14 +15,17 @@
 """Firebase Cloud Messaging module."""
 
 from __future__ import annotations
-from typing import Any, Callable, Dict, List, Optional, cast
+import asyncio
 import concurrent.futures
 import json
-import asyncio
 import logging
+import re
+from typing import Any, Callable, Dict, List, Optional, Union, cast
+import urllib.parse
 import warnings
-import requests
+
 import httpx
+import requests
 
 import firebase_admin
 from firebase_admin import (
@@ -73,7 +76,11 @@ __all__ = [
     'send_each_for_multicast',
     'send_each_for_multicast_async',
     'subscribe_to_topic',
+    'subscribe_to_topic_async',
+    'subscribe_to_topic_legacy',
     'unsubscribe_from_topic',
+    'unsubscribe_from_topic_async',
+    'unsubscribe_from_topic_legacy',
 ]
 
 
@@ -252,9 +259,53 @@ def send_each_for_multicast(multicast_message, dry_run=False, app=None):
     messages = _get_messages_from_multicast(multicast_message)
     return _get_messaging_service(app).send_each(messages, dry_run)
 
-def subscribe_to_topic(tokens, topic, app=None):
+def subscribe_to_topic(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
     """Subscribes a list of registration tokens to an FCM topic.
 
+    Args:
+        tokens: A non-empty list of device registration tokens. List may not have more than 1000
+            elements.
+        topic: Name of the topic to subscribe to. May contain the ``/topics/`` prefix.
+        app: An App instance (optional).
+
+    Returns:
+        TopicManagementResponse: A ``TopicManagementResponse`` instance.
+
+    Raises:
+        FirebaseError: If an error occurs while communicating with the FCM service.
+        ValueError: If the input arguments are invalid.
+    """
+    return _get_messaging_service(app).subscribe_to_topic(tokens, topic)
+
+async def subscribe_to_topic_async(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
+    """Subscribes a list of registration tokens to an FCM topic asynchronously.
+
+    Args:
+        tokens: A non-empty list of device registration tokens. List may not have more than 1000
+            elements.
+        topic: Name of the topic to subscribe to. May contain the ``/topics/`` prefix.
+        app: An App instance (optional).
+
+    Returns:
+        TopicManagementResponse: A ``TopicManagementResponse`` instance.
+
+    Raises:
+        FirebaseError: If an error occurs while communicating with the FCM service.
+        ValueError: If the input arguments are invalid.
+    """
+    return await _get_messaging_service(app).subscribe_to_topic_async(tokens, topic)
+
+def subscribe_to_topic_legacy(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
+    """Subscribes a list of registration tokens to an FCM topic using the legacy Instance ID API.
+
+    subscribe_to_topic_legacy is deprecated. Use subscribe_to_topic instead.
+
     Args:
         tokens: A non-empty list of device registration tokens. List may not have more than 1000
             elements.
@@ -268,12 +319,61 @@ def subscribe_to_topic(tokens, topic, app=None):
         FirebaseError: If an error occurs while communicating with instance ID service.
         ValueError: If the input arguments are invalid.
     """
+    warnings.warn(
+        'subscribe_to_topic_legacy is deprecated. Use subscribe_to_topic instead.',
+        DeprecationWarning,
+        stacklevel=2)
     return _get_messaging_service(app).make_topic_management_request(
         tokens, topic, 'iid/v1:batchAdd')
 
-def unsubscribe_from_topic(tokens, topic, app=None):
+def unsubscribe_from_topic(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
     """Unsubscribes a list of registration tokens from an FCM topic.
 
+    Args:
+        tokens: A non-empty list of device registration tokens. List may not have more than 1000
+            elements.
+        topic: Name of the topic to unsubscribe from. May contain the ``/topics/`` prefix.
+        app: An App instance (optional).
+
+    Returns:
+        TopicManagementResponse: A ``TopicManagementResponse`` instance.
+
+    Raises:
+        FirebaseError: If an error occurs while communicating with the FCM service.
+        ValueError: If the input arguments are invalid.
+    """
+    return _get_messaging_service(app).unsubscribe_from_topic(tokens, topic)
+
+async def unsubscribe_from_topic_async(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
+    """Unsubscribes a list of registration tokens from an FCM topic asynchronously.
+
+    Args:
+        tokens: A non-empty list of device registration tokens. List may not have more than 1000
+            elements.
+        topic: Name of the topic to unsubscribe from. May contain the ``/topics/`` prefix.
+        app: An App instance (optional).
+
+    Returns:
+        TopicManagementResponse: A ``TopicManagementResponse`` instance.
+
+    Raises:
+        FirebaseError: If an error occurs while communicating with the FCM service.
+        ValueError: If the input arguments are invalid.
+    """
+    return await _get_messaging_service(app).unsubscribe_from_topic_async(tokens, topic)
+
+def unsubscribe_from_topic_legacy(
+    tokens: Union[str, List[str]], topic: str, app: Optional[App] = None
+) -> TopicManagementResponse:
+    """Unsubscribes a list of registration tokens from an FCM topic using the legacy
+    Instance ID API.
+
+    unsubscribe_from_topic_legacy is deprecated. Use unsubscribe_from_topic instead.
+
     Args:
         tokens: A non-empty list of device registration tokens. List may not have more than 1000
             elements.
@@ -287,6 +387,10 @@ def unsubscribe_from_topic(tokens, topic, app=None):
         FirebaseError: If an error occurs while communicating with instance ID service.
         ValueError: If the input arguments are invalid.
     """
+    warnings.warn(
+        'unsubscribe_from_topic_legacy is deprecated. Use unsubscribe_from_topic instead.',
+        DeprecationWarning,
+        stacklevel=2)
     return _get_messaging_service(app).make_topic_management_request(
         tokens, topic, 'iid/v1:batchRemove')
 
@@ -410,7 +514,9 @@ class _MessagingService:
                 'Project ID is required to access Cloud Messaging service. Either set the '
                 'projectId option, or use service account credentials. Alternatively, set the '
                 'GOOGLE_CLOUD_PROJECT environment variable.')
+        self._project_id = project_id
         self._fcm_url = _MessagingService.FCM_URL.format(project_id)
+        self._fcm_topic_url = f'https://fcm.googleapis.com/v1/projects/{project_id}/registrations'
         self._fcm_headers = {
             'X-GOOG-API-FORMAT-VERSION': '2',
             'X-FIREBASE-CLIENT': f'fire-admin-python/{firebase_admin.__version__}',
@@ -418,6 +524,12 @@ class _MessagingService:
         timeout = app.options.get('httpTimeout', _http_client.DEFAULT_TIMEOUT_SECONDS)
         self._credential = app.credential.get_credential()
         self._client = _http_client.JsonHttpClient(credential=self._credential, timeout=timeout)
+        fcm_adapter = requests.adapters.HTTPAdapter(
+            pool_connections=100,
+            pool_maxsize=100,
+            max_retries=_http_client.DEFAULT_RETRY_CONFIG
+        )
+        self._client.session.mount('https://fcm.googleapis.com', fcm_adapter)
         self._async_client = _http_client.HttpxAsyncClient(
             credential=self._credential, timeout=timeout)
 
@@ -434,7 +546,7 @@ class _MessagingService:
             resp = self._client.body(
                 'post',
                 url=self._fcm_url,
-                headers=self._fcm_headers,
+                headers=dict(self._fcm_headers),
                 json=data
             )
         except requests.exceptions.RequestException as error:
@@ -453,7 +565,7 @@ class _MessagingService:
                 resp = self._client.body(
                     'post',
                     url=self._fcm_url,
-                    headers=self._fcm_headers,
+                    headers=dict(self._fcm_headers),
                     json=data)
             except requests.exceptions.RequestException as exception:
                 return SendResponse(resp=None, exception=self._handle_fcm_error(exception))
@@ -481,7 +593,7 @@ class _MessagingService:
                 resp = await self._async_client.request(
                     'post',
                     url=self._fcm_url,
-                    headers=self._fcm_headers,
+                    headers=dict(self._fcm_headers),
                     json=data)
             except httpx.HTTPError as exception:
                 return SendResponse(resp=None, exception=self._handle_fcm_httpx_error(exception))
@@ -499,6 +611,225 @@ class _MessagingService:
                 message=f'Unknown error while making remote service calls: {error}',
                 cause=error)
 
+    def _validate_topic_management_args(self, tokens, topic):
+        """Validates and formats topic management arguments."""
+        if isinstance(tokens, str):
+            tokens = [tokens]
+        if not isinstance(tokens, list) or not tokens:
+            raise ValueError('Tokens must be a string or a non-empty list of strings.')
+        invalid_str = [t for t in tokens if not isinstance(t, str) or not t]
+        if invalid_str:
+            raise ValueError('Tokens must be non-empty strings.')
+        if len(tokens) > 1000:
+            raise ValueError('tokens must not contain more than 1000 elements.')
+
+        if not isinstance(topic, str) or not topic:
+            raise ValueError('Topic must be a non-empty string.')
+        topic_name = topic
+        if topic_name.startswith('/topics/'):
+            topic_name = topic_name[len('/topics/'):]
+        if not topic_name or not re.match(r'^[a-zA-Z0-9-_\.~%]+\Z', topic_name):
+            raise ValueError('Malformed topic name.')
+
+        return tokens, topic_name
+
+    def subscribe_to_topic(
+        self, tokens: Union[str, List[str]], topic: str
+    ) -> TopicManagementResponse:
+        """Subscribes a list of registration tokens to an FCM topic via the FCM v1 API."""
+        return self._make_topic_management_request_v1(tokens, topic, is_subscribe=True)
+
+    def unsubscribe_from_topic(
+        self, tokens: Union[str, List[str]], topic: str
+    ) -> TopicManagementResponse:
+        """Unsubscribes a list of registration tokens from an FCM topic via the FCM v1 API."""
+        return self._make_topic_management_request_v1(tokens, topic, is_subscribe=False)
+
+    async def subscribe_to_topic_async(
+        self, tokens: Union[str, List[str]], topic: str
+    ) -> TopicManagementResponse:
+        """Subscribes a list of registration tokens to an FCM topic asynchronously
+        via the FCM v1 API."""
+        return await self._make_topic_management_request_v1_async(
+            tokens, topic, is_subscribe=True)
+
+    async def unsubscribe_from_topic_async(
+        self, tokens: Union[str, List[str]], topic: str
+    ) -> TopicManagementResponse:
+        """Unsubscribes a list of registration tokens from an FCM topic asynchronously
+        via the FCM v1 API."""
+        return await self._make_topic_management_request_v1_async(
+            tokens, topic, is_subscribe=False)
+
+    def _make_topic_management_request_v1(
+        self, tokens, topic, is_subscribe: bool
+    ) -> TopicManagementResponse:
+        """Helper method that sends topic subscription requests via FCM v1 API."""
+        tokens_list, topic_name = self._validate_topic_management_args(tokens, topic)
+        encoded_topic = urllib.parse.quote(topic_name, safe='')
+
+        def send_request(token: str):
+            encoded_token = urllib.parse.quote(token, safe='')
+            base_url = f'{self._fcm_topic_url}/{encoded_token}/topicSubscriptions'
+            if is_subscribe:
+                url = f'{base_url}?topic_name={encoded_topic}'
+                method = 'post'
+                json_data = {}
+            else:
+                url = f'{base_url}/{encoded_topic}?allow_missing=true'
+                method = 'delete'
+                json_data = None
+
+            try:
+                self._client.request(
+                    method,
+                    url=url,
+                    headers=dict(self._fcm_headers),
+                    json=json_data,
+                )
+                return {'success': True}
+            except requests.exceptions.RequestException as error:
+                return self._build_topic_subscription_result_from_requests_error(
+                    error, is_subscribe)
+
+        try:
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=min(len(tokens_list), 100)
+            ) as executor:
+                results = list(executor.map(send_request, tokens_list))
+                return self._parse_topic_management_results(results)
+        except Exception as error:
+            raise exceptions.UnknownError(
+                message=f'Unknown error while making remote service calls: {error}',
+                cause=error)
+
+    async def _make_topic_management_request_v1_async(
+        self, tokens, topic, is_subscribe: bool
+    ) -> TopicManagementResponse:
+        """Helper method that sends topic subscription requests asynchronously via FCM v1 API."""
+        tokens_list, topic_name = self._validate_topic_management_args(tokens, topic)
+        encoded_topic = urllib.parse.quote(topic_name, safe='')
+        semaphore = asyncio.Semaphore(100)
+
+        async def send_request_async(token: str):
+            encoded_token = urllib.parse.quote(token, safe='')
+            base_url = f'{self._fcm_topic_url}/{encoded_token}/topicSubscriptions'
+            if is_subscribe:
+                url = f'{base_url}?topic_name={encoded_topic}'
+                method = 'post'
+                json_data = {}
+            else:
+                url = f'{base_url}/{encoded_topic}?allow_missing=true'
+                method = 'delete'
+                json_data = None
+
+            async with semaphore:
+                try:
+                    await self._async_client.request(
+                        method,
+                        url=url,
+                        headers=dict(self._fcm_headers),
+                        json=json_data,
+                    )
+                    return {'success': True}
+                except httpx.HTTPError as error:
+                    return self._build_topic_subscription_result_from_httpx_error(
+                        error, is_subscribe)
+                except requests.exceptions.RequestException as error:
+                    return self._build_topic_subscription_result_from_requests_error(
+                        error, is_subscribe)
+
+        try:
+            results = await asyncio.gather(*[send_request_async(token) for token in tokens_list])
+            return self._parse_topic_management_results(results)
+        except Exception as error:
+            raise exceptions.UnknownError(
+                message=f'Unknown error while making remote service calls: {error}',
+                cause=error)
+
+    @classmethod
+    def _get_topic_error_code(cls, error_dict: dict, status_code: int) -> str:
+        """Extracts the error code for a topic subscription error response."""
+        error_data = error_dict.get('error')
+        if isinstance(error_data, str) and error_data:
+            return error_data
+        if isinstance(error_data, dict):
+            details = error_data.get('details')
+            if isinstance(details, list):
+                fcm_error_type = 'type.googleapis.com/google.firebase.fcm.v1.FcmError'
+                for element in details:
+                    if isinstance(element, dict) and element.get('@type') == fcm_error_type:
+                        code = element.get('errorCode')
+                        if code:
+                            return code
+            status = error_data.get('status')
+            if status:
+                return status
+
+        status_map = {
+            400: 'INVALID_ARGUMENT',
+            401: 'UNAUTHENTICATED',
+            403: 'PERMISSION_DENIED',
+            404: 'NOT_FOUND',
+            408: 'DEADLINE_EXCEEDED',
+            429: 'RESOURCE_EXHAUSTED',
+            500: 'INTERNAL',
+            503: 'UNAVAILABLE',
+            504: 'DEADLINE_EXCEEDED',
+        }
+        if status_code in status_map:
+            return status_map[status_code]
+
+        if isinstance(error_data, dict):
+            message = error_data.get('message')
+            if message:
+                return message
+
+        return 'UNKNOWN_ERROR'
+
+    def _build_topic_subscription_result(self, response, is_subscribe):
+        """Constructs a result dict from a response object."""
+        if response is not None:
+            if is_subscribe and response.status_code == 409:
+                return {'success': True}
+            error_dict = {}
+            try:
+                parsed = response.json()
+                if isinstance(parsed, dict):
+                    error_dict = parsed
+            except ValueError:
+                pass
+
+            error_data = error_dict.get('error')
+            if is_subscribe and isinstance(error_data, dict) and (
+                error_data.get('status') == 'ALREADY_EXISTS'
+            ):
+                return {'success': True}
+
+            error_code = self._get_topic_error_code(error_dict, response.status_code)
+            return {'success': False, 'error': error_code}
+
+        return {'success': False, 'error': 'UNKNOWN_ERROR'}
+
+    def _build_topic_subscription_result_from_requests_error(self, error, is_subscribe):
+        """Constructs a result dict from a requests error."""
+        return self._build_topic_subscription_result(error.response, is_subscribe)
+
+    def _build_topic_subscription_result_from_httpx_error(self, error, is_subscribe):
+        """Constructs a result dict from an httpx error."""
+        response = error.response if isinstance(error, httpx.HTTPStatusError) else None
+        return self._build_topic_subscription_result(response, is_subscribe)
+
+    def _parse_topic_management_results(self, results) -> TopicManagementResponse:
+        """Parses individual request results into a TopicManagementResponse."""
+        formatted_results = []
+        for result in results:
+            if result.get('success'):
+                formatted_results.append({})
+            else:
+                formatted_results.append({'error': result.get('error', 'UNKNOWN_ERROR')})
+        return TopicManagementResponse({'results': formatted_results})
+
     def make_topic_management_request(self, tokens, topic, operation):
         """Invokes the IID service for topic management functionality."""
         if isinstance(tokens, str):