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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firebase_admin
-Version: 7.3.0
+Version: 7.5.0
 Summary: Firebase Admin Python SDK
 Home-page: https://firebase.google.com/docs/admin/setup/
 Author: Firebase
@@ -25,6 +25,7 @@ Requires-Dist: google-api-core[grpc]<3.0.0dev,>=2.25.1; platform_python_implemen
 Requires-Dist: google-cloud-firestore>=2.21.0; platform_python_implementation != "PyPy"
 Requires-Dist: google-cloud-storage>=3.1.1
 Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: cryptography<44.0.0; platform_python_implementation == "PyPy" and python_version < "3.11"
 Requires-Dist: httpx[http2]==0.28.1
 Dynamic: author
 Dynamic: classifier

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

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

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/firebase_admin/_messaging_encoder.py

@@ -19,6 +19,7 @@ import json
 import math
 import numbers
 import re
+import warnings
 
 from firebase_admin import _messaging_utils
 
@@ -27,7 +28,7 @@ class Message:
     """A message that can be sent via Firebase Cloud Messaging.
 
     Contains payload information as well as recipient information. In particular, the message must
-    contain exactly one of token, topic or condition fields.
+    contain exactly one of fid, token, topic or condition fields.
 
     Args:
         data: A dictionary of data fields (optional). All keys and values in the dictionary must be
@@ -37,20 +38,29 @@ class Message:
         webpush: An instance of ``messaging.WebpushConfig`` (optional).
         apns: An instance of ``messaging.ApnsConfig`` (optional).
         fcm_options: An instance of ``messaging.FCMOptions`` (optional).
-        token: The registration token of the device to which the message should be sent (optional).
+        fid: The Firebase installation ID of an FCM registered app instance to which the
+            message should be sent (optional).
+        token: Deprecated. Use ``fid`` instead.
         topic: Name of the FCM topic to which the message should be sent (optional). Topic name
             may contain the ``/topics/`` prefix.
         condition: The FCM condition to which the message should be sent (optional).
     """
 
     def __init__(self, data=None, notification=None, android=None, webpush=None, apns=None,
-                 fcm_options=None, token=None, topic=None, condition=None):
+                 fcm_options=None, token=None, topic=None, condition=None, fid=None):
+        if token is not None:
+            warnings.warn(
+                "Message.token is deprecated. Use Message.fid instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
         self.data = data
         self.notification = notification
         self.android = android
         self.webpush = webpush
         self.apns = apns
         self.fcm_options = fcm_options
+        self.fid = fid
         self.token = token
         self.topic = topic
         self.condition = condition
@@ -60,10 +70,10 @@ class Message:
 
 
 class MulticastMessage:
-    """A message that can be sent to multiple tokens via Firebase Cloud Messaging.
+    """A message that can be sent to multiple tokens or fids via Firebase Cloud Messaging.
 
     Args:
-        tokens: A list of registration tokens of targeted devices.
+        tokens: Deprecated. Use ``fids`` instead (optional).
         data: A dictionary of data fields (optional). All keys and values in the dictionary must be
             strings.
         notification: An instance of ``messaging.Notification`` (optional).
@@ -71,13 +81,35 @@ class MulticastMessage:
         webpush: An instance of ``messaging.WebpushConfig`` (optional).
         apns: An instance of ``messaging.ApnsConfig`` (optional).
         fcm_options: An instance of ``messaging.FCMOptions`` (optional).
+        fids: A list of Firebase Installation IDs of targeted app instances (optional).
     """
-    def __init__(self, tokens, data=None, notification=None, android=None, webpush=None, apns=None,
-                 fcm_options=None):
-        _Validators.check_string_list('MulticastMessage.tokens', tokens)
-        if len(tokens) > 500:
-            raise ValueError('MulticastMessage.tokens must not contain more than 500 tokens.')
+    def __init__(
+            self, tokens=None, data=None, notification=None, android=None,
+            webpush=None, apns=None, fcm_options=None, fids=None):
+        if tokens is not None:
+            warnings.warn(
+                "MulticastMessage.tokens is deprecated. Use MulticastMessage.fids instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+
+        if tokens is None and fids is None:
+            raise ValueError(
+                "Must specify at least one of MulticastMessage.tokens or MulticastMessage.fids.")
+
+        if tokens is not None:
+            _Validators.check_string_list('MulticastMessage.tokens', tokens)
+        if fids is not None:
+            _Validators.check_string_list('MulticastMessage.fids', fids)
+
+        tokens_len = len(tokens) if tokens is not None else 0
+        fids_len = len(fids) if fids is not None else 0
+        if tokens_len + fids_len > 500:
+            raise ValueError(
+                'Total number of tokens and fids must not exceed 500.')
+
         self.tokens = tokens
+        self.fids = fids
         self.data = data
         self.notification = notification
         self.android = android
@@ -695,6 +727,7 @@ class MessageEncoder(json.JSONEncoder):
                 'Message.condition', o.condition, non_empty=True),
             'data': _Validators.check_string_dict('Message.data', o.data),
             'notification': MessageEncoder.encode_notification(o.notification),
+            'fid': _Validators.check_string('Message.fid', o.fid, non_empty=True),
             'token': _Validators.check_string('Message.token', o.token, non_empty=True),
             'topic': _Validators.check_string('Message.topic', o.topic, non_empty=True),
             'webpush': MessageEncoder.encode_webpush(o.webpush),
@@ -702,9 +735,9 @@ class MessageEncoder(json.JSONEncoder):
         }
         result['topic'] = MessageEncoder.sanitize_topic_name(result.get('topic'))
         result = MessageEncoder.remove_null_values(result)
-        target_count = sum(t in result for t in ['token', 'topic', 'condition'])
+        target_count = sum(t in result for t in ['fid', 'token', 'topic', 'condition'])
         if target_count != 1:
-            raise ValueError('Exactly one of token, topic or condition must be specified.')
+            raise ValueError('Exactly one of fid, token, topic or condition must be specified.')
         return result
 
     @classmethod

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/firebase_admin/_messaging_utils.py

@@ -519,7 +519,8 @@ class SenderIdMismatchError(exceptions.PermissionDeniedError):
 class UnregisteredError(exceptions.NotFoundError):
     """App instance was unregistered from FCM.
 
-    This usually means that the token used is no longer valid and a new one must be used."""
+    This usually means that the registration token or installation ID (FID) used
+    is no longer valid and a new one must be used."""
 
     def __init__(self, message, cause=None, http_response=None):
         exceptions.NotFoundError.__init__(self, message, cause, http_response)

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

@@ -20,6 +20,7 @@ import concurrent.futures
 import json
 import asyncio
 import logging
+import warnings
 import requests
 import httpx
 
@@ -172,13 +173,45 @@ async def send_each_async(
     """
     return await _get_messaging_service(app).send_each_async(messages, dry_run)
 
+def _get_messages_from_multicast(multicast_message: MulticastMessage) -> List[Message]:
+    """Extracts individual Message objects from a MulticastMessage."""
+    if not isinstance(multicast_message, MulticastMessage):
+        raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
+
+    messages = []
+    if multicast_message.tokens is not None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            messages.extend([Message(
+                data=multicast_message.data,
+                notification=multicast_message.notification,
+                android=multicast_message.android,
+                webpush=multicast_message.webpush,
+                apns=multicast_message.apns,
+                fcm_options=multicast_message.fcm_options,
+                token=token
+            ) for token in multicast_message.tokens])
+
+    if multicast_message.fids is not None:
+        messages.extend([Message(
+            data=multicast_message.data,
+            notification=multicast_message.notification,
+            android=multicast_message.android,
+            webpush=multicast_message.webpush,
+            apns=multicast_message.apns,
+            fcm_options=multicast_message.fcm_options,
+            fid=fid
+        ) for fid in multicast_message.fids])
+
+    return messages
+
 async def send_each_for_multicast_async(
         multicast_message: MulticastMessage,
         dry_run: bool = False,
         app: Optional[App] = None
     ) -> BatchResponse:
-    """Sends the given mutlicast message to each token asynchronously via Firebase Cloud Messaging
-    (FCM).
+    """Sends the given multicast message to each token or fid asynchronously via
+    Firebase Cloud Messaging (FCM).
 
     If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
     recipients. Instead, FCM performs all the usual validations and emulates the send operation.
@@ -195,21 +228,11 @@ async def send_each_for_multicast_async(
         FirebaseError: If an error occurs while sending the message to the FCM service.
         ValueError: If the input arguments are invalid.
     """
-    if not isinstance(multicast_message, MulticastMessage):
-        raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
-    messages = [Message(
-        data=multicast_message.data,
-        notification=multicast_message.notification,
-        android=multicast_message.android,
-        webpush=multicast_message.webpush,
-        apns=multicast_message.apns,
-        fcm_options=multicast_message.fcm_options,
-        token=token
-    ) for token in multicast_message.tokens]
+    messages = _get_messages_from_multicast(multicast_message)
     return await _get_messaging_service(app).send_each_async(messages, dry_run)
 
 def send_each_for_multicast(multicast_message, dry_run=False, app=None):
-    """Sends the given mutlicast message to each token via Firebase Cloud Messaging (FCM).
+    """Sends the given multicast message to each token or fid via Firebase Cloud Messaging (FCM).
 
     If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
     recipients. Instead, FCM performs all the usual validations and emulates the send operation.
@@ -226,17 +249,7 @@ def send_each_for_multicast(multicast_message, dry_run=False, app=None):
         FirebaseError: If an error occurs while sending the message to the FCM service.
         ValueError: If the input arguments are invalid.
     """
-    if not isinstance(multicast_message, MulticastMessage):
-        raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
-    messages = [Message(
-        data=multicast_message.data,
-        notification=multicast_message.notification,
-        android=multicast_message.android,
-        webpush=multicast_message.webpush,
-        apns=multicast_message.apns,
-        fcm_options=multicast_message.fcm_options,
-        token=token
-    ) for token in multicast_message.tokens]
+    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):

firebase_admin-7.5.0/firebase_admin/phone_number_verification.py

@@ -0,0 +1,250 @@
+# Copyright 2026 Google Inc.
+#
+# 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.
+
+"""Firebase Phone Number Verification module.
+
+This module contains functions for verifying JWTs related to the Firebase
+Phone Number Verification service.
+"""
+from __future__ import annotations
+from typing import Any, Dict, Optional
+
+import jwt
+from jwt import (
+    PyJWKClient, InvalidSignatureError,
+    PyJWKClientError, InvalidAudienceError, InvalidIssuerError, ExpiredSignatureError
+)
+
+from firebase_admin import App, _utils, exceptions
+
+_FPNV_ATTRIBUTE = '_phone_number_verification'
+_FPNV_JWKS_URL = 'https://fpnv.googleapis.com/v1beta/jwks'
+_FPNV_ISSUER = 'https://fpnv.googleapis.com/projects/'
+_ALGORITHM_ES256 = 'ES256'
+
+
+def _get_fpnv_service(app):
+    return _utils.get_app_service(app, _FPNV_ATTRIBUTE, _FpnvService)
+
+def verify_token(token: str, app: Optional[App] = None) -> PhoneNumberVerificationToken:
+    """Verifies a Firebase Phone Number Verification token.
+
+    Args:
+        token: A string containing the Firebase Phone Number Verification JWT.
+        app: An App instance (optional).
+
+    Returns:
+        PhoneNumberVerificationToken: The verified token claims.
+
+    Raises:
+        ValueError: If the token is not a string or is empty.
+        InvalidTokenError: If the token is invalid or malformed.
+        ExpiredTokenError: If the token has expired.
+    """
+    return _get_fpnv_service(app).verify_token(token)
+
+
+class PhoneNumberVerificationToken(dict):
+    """Represents a verified Firebase Phone Number Verification token.
+
+    This class behaves like a dictionary, allowing access to the decoded claims.
+    It also provides convenience properties for common claims.
+    """
+
+    def __init__(self, claims):
+        super().__init__(claims)
+        self['phone_number'] = claims.get('sub')
+
+    @property
+    def phone_number(self) -> str:
+        """Returns the phone number of the user.
+        This corresponds to the 'sub' claim in the JWT.
+        """
+        return self.get('sub')
+
+    @property
+    def issuer(self) -> str:
+        """Returns the issuer identifier for the issuer of the response."""
+        return self.get('iss')
+
+    @property
+    def audience(self) -> str:
+        """Returns the audience for which this token is intended."""
+        return self.get('aud')
+
+    @property
+    def exp(self) -> int:
+        """Returns the expiration time since the Unix epoch."""
+        return self.get('exp')
+
+    @property
+    def iat(self) -> int:
+        """Returns the issued-at time since the Unix epoch."""
+        return self.get('iat')
+
+    @property
+    def sub(self) -> str:
+        """Returns the sub (subject) of the token, which is the phone number."""
+        return self.get('sub')
+
+    @property
+    def claims(self):
+        """Returns the entire map of claims."""
+        return self
+
+
+class _FpnvService:
+    """Service class that implements Firebase Phone Number Verification functionality."""
+    _project_id = None
+
+    def __init__(self, app):
+        self._project_id = app.project_id
+        if not self._project_id:
+            raise ValueError(
+                'Project ID is required for Firebase Phone Number Verification. Please ensure the '
+                'app is initialized with a credential that contains a project ID.'
+            )
+
+        self._verifier = _FpnvTokenVerifier(self._project_id)
+
+    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 Firebase Phone Number Verification JWT.
+
+        Returns:
+            PhoneNumberVerificationToken: The verified token claims.
+
+        Raises:
+            ValueError: If the token is not a string or is empty.
+            InvalidTokenError: If the token is invalid or malformed.
+            ExpiredTokenError: If the token has expired.
+        """
+        return PhoneNumberVerificationToken(self._verifier.verify(token))
+
+
+class _FpnvTokenVerifier:
+    """Internal class for verifying Firebase Phone Number Verification JWTs signed with ES256."""
+    _jwks_client = None
+    _project_id = None
+
+    def __init__(self, project_id):
+        self._project_id = project_id
+        self._jwks_client = PyJWKClient(_FPNV_JWKS_URL, lifespan=21600)
+
+    def verify(self, token) -> Dict[str, Any]:
+        """Verifies the given Firebase Phone Number Verification token."""
+        _Validators.check_string("Firebase Phone Number Verification check token", token)
+        try:
+            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 (jwt.InvalidTokenError, PyJWKClientError) as exception:
+            raise InvalidTokenError(
+                'Verifying phone number verification token failed.',
+                cause=exception,
+                http_response=getattr(exception, 'http_response', None)
+            ) from exception
+
+        return claims
+
+    def _validate_headers(self, headers: Any) -> None:
+        """Validates the headers."""
+        if headers.get('kid') is None:
+            raise InvalidTokenError("Token has no 'kid' claim.")
+
+        if headers.get('typ') != 'JWT':
+            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 InvalidTokenError(
+                'The provided token has an incorrect alg header. '
+                f'Expected {_ALGORITHM_ES256} but got {algorithm}.'
+            )
+
+    def _decode_and_verify(self, token, signing_key) -> Dict[str, Any]:
+        """Decodes and verifies the token."""
+        expected_issuer = f'{_FPNV_ISSUER}{self._project_id}'
+        try:
+            payload = jwt.decode(
+                token,
+                signing_key,
+                algorithms=[_ALGORITHM_ES256],
+                audience=expected_issuer,
+                issuer=expected_issuer
+            )
+        except InvalidSignatureError as exception:
+            raise InvalidTokenError(
+                'The provided token has an invalid signature.'
+            ) from exception
+        except InvalidAudienceError as exception:
+            raise InvalidTokenError(
+                'The provided token has an incorrect "aud" (audience) claim. '
+                f'Expected {expected_issuer}.'
+            ) from exception
+        except InvalidIssuerError as exception:
+            raise InvalidTokenError(
+                'The provided token has an incorrect "iss" (issuer) claim. '
+                f'Expected {expected_issuer}.'
+            ) from exception
+        except ExpiredSignatureError as exception:
+            raise ExpiredTokenError(
+                'The provided token has expired.'
+            ) from 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 InvalidTokenError(
+                'The provided token has an incorrect "sub" (subject) claim. '
+                'Expected a non-empty string.'
+            )
+
+        return payload
+
+
+class _Validators:
+    """A collection of data validation utilities.
+
+    Methods provided in this class raise ``ValueErrors`` if any validations fail.
+    """
+
+    @classmethod
+    def check_string(cls, label: str, value: Any):
+        """Checks if the given value is a string."""
+        if not isinstance(value, str) or not value:
+            raise ValueError(f'{label} must be a non-empty string.')
+
+# Firebase Phone Number Verification Errors
+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 ExpiredTokenError(InvalidTokenError):
+    """Raised when a Firebase Phone Number Verification token is expired."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        InvalidTokenError.__init__(self, message, cause, http_response)

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/firebase_admin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firebase_admin
-Version: 7.3.0
+Version: 7.5.0
 Summary: Firebase Admin Python SDK
 Home-page: https://firebase.google.com/docs/admin/setup/
 Author: Firebase
@@ -25,6 +25,7 @@ Requires-Dist: google-api-core[grpc]<3.0.0dev,>=2.25.1; platform_python_implemen
 Requires-Dist: google-cloud-firestore>=2.21.0; platform_python_implementation != "PyPy"
 Requires-Dist: google-cloud-storage>=3.1.1
 Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: cryptography<44.0.0; platform_python_implementation == "PyPy" and python_version < "3.11"
 Requires-Dist: httpx[http2]==0.28.1
 Dynamic: author
 Dynamic: classifier

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/firebase_admin.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ firebase_admin/functions.py
 firebase_admin/instance_id.py
 firebase_admin/messaging.py
 firebase_admin/ml.py
+firebase_admin/phone_number_verification.py
 firebase_admin/project_management.py
 firebase_admin/remote_config.py
 firebase_admin/storage.py
@@ -51,6 +52,7 @@ tests/test_http_client.py
 tests/test_instance_id.py
 tests/test_messaging.py
 tests/test_ml.py
+tests/test_phone_number_verification.py
 tests/test_project_management.py
 tests/test_remote_config.py
 tests/test_retry.py

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/firebase_admin.egg-info/requires.txt

@@ -6,3 +6,6 @@ httpx[http2]==0.28.1
 [:platform_python_implementation != "PyPy"]
 google-api-core[grpc]<3.0.0dev,>=2.25.1
 google-cloud-firestore>=2.21.0
+
+[:platform_python_implementation == "PyPy" and python_version < "3.11"]
+cryptography<44.0.0

{firebase_admin-7.3.0 → firebase_admin-7.5.0}/setup.py

@@ -42,6 +42,7 @@ install_requires = [
     'google-cloud-firestore>=2.21.0; platform.python_implementation != "PyPy"',
     'google-cloud-storage>=3.1.1',
     'pyjwt[crypto] >= 2.10.1',
+    'cryptography < 44.0.0; platform.python_implementation == "PyPy" and python_version < "3.11"',
     'httpx[http2] == 0.28.1',
 ]