pyios-firebase 0.2.0__py3-none-any.whl

pyios_firebase/auth/_apple_name_cache.py

@@ -0,0 +1,97 @@
+"""Keeps the name Apple shares at a user's FIRST authorization until Firebase
+has it.
+
+Sign in with Apple sends the name once per user per app. If the Firebase
+sign-in that should carry it fails (for example a flaky network), every retry
+gets no name. So the name is saved here, keyed by Apple's stable user ID
+(``credential.user``), as soon as Apple sends it, reused by a retry that gets
+none, and deleted once Firebase sign-in works.
+
+The store is NSUserDefaults on iOS; tests can pass a dict.
+"""
+
+from __future__ import annotations
+
+__all__ = ("AppleNameCache", "NameStore", "UserDefaultsStore")
+
+from collections.abc import Sequence
+from typing import Any, Final, Protocol
+
+DEFAULTS_KEY: Final = "pyios_firebase.apple_sign_in.pending_names"
+
+
+class NameStore(Protocol):
+    """Where names are kept: ``{apple_user: [given, family]}``. A ``dict`` works."""
+
+    def get(self, apple_user: str, default: Any = None, /) -> Any: ...
+    def __setitem__(self, apple_user: str, value: list[str], /) -> None: ...
+    def pop(self, apple_user: str, default: Any = None, /) -> Any: ...
+
+
+class UserDefaultsStore:
+    """A ``NameStore`` kept in one NSUserDefaults entry, so it survives restarts."""
+
+    def __init__(self, key: str = DEFAULTS_KEY) -> None:
+        from rubicon.objc import ns_from_py
+
+        from ..util import objc_class, to_python
+
+        self._key = key
+        self._defaults = objc_class("NSUserDefaults").standardUserDefaults
+        self._ns, self._py = ns_from_py, to_python
+
+    def _load(self) -> dict[str, list[str]]:
+        value = self._defaults.objectForKey_(self._key)
+        return dict(self._py(value)) if value is not None else {}
+
+    def _save(self, data: dict[str, list[str]]) -> None:
+        if data:
+            self._defaults.setObject_forKey_(self._ns(data), self._key)
+        else:
+            self._defaults.removeObjectForKey_(self._key)
+
+    def get(self, apple_user: str, default: Any = None, /) -> Any:
+        return self._load().get(apple_user, default)
+
+    def __setitem__(self, apple_user: str, value: list[str], /) -> None:
+        data = self._load()
+        data[apple_user] = list(value)
+        self._save(data)
+
+    def pop(self, apple_user: str, default: Any = None, /) -> Any:
+        data = self._load()
+        value = data.pop(apple_user, default)
+        self._save(data)
+        return value
+
+
+class AppleNameCache:
+    """Remembers the name Apple sent until a Firebase sign-in carries it."""
+
+    def __init__(self, store: NameStore | None = None) -> None:
+        self._store: NameStore = store if store is not None else UserDefaultsStore()
+
+    def resolve(
+        self, apple_user: str, first: str | None, last: str | None
+    ) -> tuple[str, str]:
+        """The name to use for this authorization: Apple's when it sent one
+        (which is then saved), else the one saved by an earlier attempt.
+
+        Returns:
+            ``(first_name, last_name)``; ``""`` for parts nobody knows.
+        """
+        first, last = first or "", last or ""
+        if not apple_user:
+            return first, last
+        if first or last:
+            self._store[apple_user] = [first, last]
+            return first, last
+        saved: Sequence[str | None] | None = self._store.get(apple_user)
+        if saved:
+            return str(saved[0] or ""), str(saved[1] or "")
+        return "", ""
+
+    def forget(self, apple_user: str | None) -> None:
+        """Drop the saved name: Firebase has it now (call after sign-in works)."""
+        if apple_user:
+            self._store.pop(apple_user, None)

pyios_firebase/auth/_common.py

@@ -0,0 +1,121 @@
+"""Helpers shared by the auth modules: block builders and value readers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from rubicon.objc import Block, objc_id
+
+from ..types import ObjCObject
+from ..util import objc_class, objc_instance, one_shot_block, to_python
+from .errors import AuthError, auth_error_from_pointer, simple_auth_error
+
+T = TypeVar("T")
+
+
+def flag(obj: ObjCObject, name: str) -> bool:
+    """Read a Swift ``Bool`` property, whichever way Rubicon exposes it.
+
+    A plain getter is an attribute; a custom getter (``getter=isX``) is a
+    method, and reading it without calling it would always be truthy.
+    """
+    value = getattr(obj, name)
+    return bool(value() if callable(value) else value)
+
+
+def text(value: object) -> str | None:
+    """``str(value)``, or ``None`` for ``None``."""
+    return None if value is None else str(value)
+
+
+def url_text(url: ObjCObject | None) -> str | None:
+    """An ``NSURL`` as a string, or ``None``."""
+    return None if url is None else str(url.absoluteString)
+
+
+def result_block(
+    callback: Callable[[T | None, AuthError | None], None] | None,
+    wrap: Callable[[ObjCObject], T],
+) -> Block:
+    """Completion block for ``(result, NSError)``: ``callback(wrap(result), error)``."""
+
+    def done(result_ptr: Any, error_ptr: Any) -> None:
+        if callback is None:
+            return
+        error = auth_error_from_pointer(error_ptr)
+        if error is not None or not result_ptr:
+            callback(None, error)
+            return
+        try:
+            result = wrap(objc_instance(result_ptr))
+        except Exception as e:  # noqa: BLE001 - must always answer the caller
+            # an exception here would be swallowed by the SDK's block, and the
+            # caller would wait forever
+            callback(None, simple_auth_error(f"could not read the result: {e!r}"))
+            return
+        callback(result, None)
+
+    return one_shot_block(done, objc_id, objc_id)
+
+
+def error_block(callback: Callable[[AuthError | None], None] | None) -> Block:
+    """Completion block for ``(NSError)``: ``callback(error)``."""
+
+    def done(error_ptr: Any) -> None:
+        if callback is not None:
+            callback(auth_error_from_pointer(error_ptr))
+
+    return one_shot_block(done, objc_id)
+
+
+def string_block(callback: Callable[[str | None, AuthError | None], None]) -> Block:
+    """Completion block for ``(NSString, NSError)``."""
+    return result_block(callback, lambda value: str(value))
+
+
+def registered_url_schemes() -> set[str]:
+    """The URL schemes in the app's ``Info.plist`` (``CFBundleURLTypes``), lower case."""
+    url_types = objc_class("NSBundle").mainBundle.objectForInfoDictionaryKey_(
+        "CFBundleURLTypes"
+    )
+    schemes: set[str] = set()
+    for url_type in to_python(url_types) or []:
+        for scheme in (
+            url_type.get("CFBundleURLSchemes", []) if isinstance(url_type, dict) else []
+        ):
+            schemes.add(str(scheme).lower())
+    return schemes
+
+
+def missing_callback_scheme(auth_native: ObjCObject) -> str | None:
+    """Why phone and web sign-in cannot start, or ``None`` if they can.
+
+    The Firebase SDK stops the whole app (``fatalError``) when the callback URL
+    scheme is not in ``Info.plist``. This checks the same thing first: the
+    reversed client ID if it is registered, else ``app-<GOOGLE_APP_ID>``.
+    """
+    app = auth_native.app
+    options = app.options if app is not None else None
+    if options is None:
+        return "Firebase is not configured: call core.configure() first"
+    schemes = registered_url_schemes()
+    reversed_client_id = None
+    if options.clientID is not None:
+        reversed_client_id = ".".join(reversed(str(options.clientID).split(".")))
+        if reversed_client_id.lower() in schemes:
+            return None
+    if options.googleAppID is None:
+        return "the Firebase options have no GOOGLE_APP_ID"
+    app_scheme = "app-" + str(options.googleAppID).replace(":", "-")
+    if app_scheme.lower() in schemes:
+        return None
+    wanted = (
+        app_scheme
+        if reversed_client_id is None
+        else f"{reversed_client_id} (or {app_scheme})"
+    )
+    return (
+        f"add the URL scheme {wanted} to CFBundleURLTypes in Info.plist: Firebase Auth "
+        "needs it for phone and web sign-in, and stops the app without it"
+    )

pyios_firebase/auth/_ui.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ..types import ObjCObject
+from ..util import objc_class
+
+
+def key_window() -> ObjCObject | None:
+    """The app's key window (scene-based apps first, then the old ``keyWindow``)."""
+    app = objc_class("UIApplication").sharedApplication
+    for scene in app.connectedScenes.allObjects():
+        for window in getattr(scene, "windows", None) or []:
+            if window.isKeyWindow():  # a getter with a custom name: must be called
+                return window
+    fallback: ObjCObject | None = app.keyWindow
+    return fallback
+
+
+def root_view_controller() -> ObjCObject | None:
+    """The key window's root view controller, to present sign-in sheets from."""
+    window = key_window()
+    return window.rootViewController if window is not None else None

pyios_firebase/auth/apple.py

@@ -0,0 +1,326 @@
+"""Sign in with Apple, then Firebase Auth.
+
+    from pyios_firebase.auth.apple import start_apple_sign_in
+
+    def on_signed_in(result, error):
+        if error is not None:
+            if not error.cancelled:
+                print(error.message or error.description)
+            return
+        print("Signed in:", result.user.uid, result.first_name)
+
+    start_apple_sign_in(on_signed_in)
+
+Apple shares the name (and a real or relay email) only the FIRST time a user
+signs in to the app; later sign-ins give ``""`` for those. The name is kept on
+the device until a Firebase sign-in carries it.
+
+Needs the ``com.apple.developer.applesignin`` entitlement and the Apple
+provider enabled in the Firebase console (Authentication, Sign-in method).
+"""
+
+from __future__ import annotations
+
+__all__ = (
+    "AUTHORIZATION_ERROR_CANCELED",
+    "AUTHORIZATION_ERROR_DOMAIN",
+    "AUTHORIZATION_ERROR_UNKNOWN",
+    "AppleCredential",
+    "AppleSignInResult",
+    "get_apple_credential",
+    "start_apple_sign_in",
+)
+
+import hashlib
+import secrets
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Final, cast
+
+from rubicon.objc import NSObject, ObjCInstance, ObjCProtocol, ns_from_py, objc_method
+from rubicon.objc.runtime import load_library, objc_id
+
+from ..types import ObjCObject
+from ..util import objc_class
+from ._apple_name_cache import AppleNameCache
+from ._ui import key_window
+from .auth import Auth
+from .credentials import OAuthCredential, OAuthProvider
+from .errors import AuthError, auth_error_from_nserror, simple_auth_error
+from .results import AuthDataResult
+
+_auth_services = load_library("AuthenticationServices")
+
+
+def _string_constant(name: str, fallback: str) -> str:
+    """An NSString constant exported by AuthenticationServices."""
+    try:
+        value = objc_id.in_dll(_auth_services, name)
+    except ValueError:
+        return fallback
+    return str(ObjCInstance(value)) if value.value else fallback
+
+
+SCOPE_FULL_NAME: Final = _string_constant("ASAuthorizationScopeFullName", "full_name")
+SCOPE_EMAIL: Final = _string_constant("ASAuthorizationScopeEmail", "email")
+AUTHORIZATION_ERROR_DOMAIN: Final = _string_constant(
+    "ASAuthorizationErrorDomain", "com.apple.AuthenticationServices.AuthorizationError"
+)
+"""The error domain of Apple's sign-in errors."""
+AUTHORIZATION_ERROR_UNKNOWN: Final = 1000
+"""Set-up problems, or no Apple Account on the device (also: the user closed
+iOS's "sign in to your Apple Account" alert)."""
+AUTHORIZATION_ERROR_CANCELED: Final = 1001
+"""``ASAuthorizationErrorCanceled``: the user closed the Apple sheet."""
+
+NOT_SIGNED_IN_MESSAGE: Final = (
+    "Sign in with Apple didn't finish. Check that you're signed in to your "
+    "Apple Account in Settings, then try again"
+)
+
+NSUTF8StringEncoding: Final = 4
+
+
+@dataclass(frozen=True)
+class AppleCredential:
+    """What Sign in with Apple gave, ready for Firebase."""
+
+    credential: OAuthCredential
+    """The Firebase credential (provider ``"apple.com"``)."""
+    apple_user: str
+    """Apple's stable ID for the user in this app."""
+    first_name: str
+    """The given name: only on the first sign-in to the app, else ``""``
+    (or the name kept from an earlier, failed attempt)."""
+    last_name: str
+    """The family name: same rules as ``first_name``."""
+    email: str
+    """The email (real or private relay): only on the first sign-in, else ``""``."""
+    authorization_code: str
+    """A short-lived code: pass it to ``Auth.revoke_token`` before deleting the
+    account (App Store rule)."""
+
+
+class AppleSignInResult(AuthDataResult):
+    """A Firebase sign-in with Apple: an ``AuthDataResult`` plus what Apple shared.
+
+    Args:
+        native: the native ``FIRAuthDataResult``.
+        apple: what Apple gave for this sign-in.
+    """
+
+    def __init__(self, native: ObjCObject, apple: AppleCredential) -> None:
+        super().__init__(native)
+        self.apple = apple
+        """What Apple gave (names, email, authorization code)."""
+
+    @property
+    def first_name(self) -> str:
+        """The given name Apple shared (first sign-in only), else ``""``."""
+        return self.apple.first_name
+
+    @property
+    def last_name(self) -> str:
+        """The family name Apple shared (first sign-in only), else ``""``."""
+        return self.apple.last_name
+
+
+AppleCredentialCallback = Callable[[AppleCredential | None, AuthError | None], None]
+AppleSignInCallback = Callable[[AppleSignInResult | None, AuthError | None], None]
+
+_names: AppleNameCache | None = None  # made on first use (NSUserDefaults)
+# the sign-ins in progress, by delegate: UIKit keeps the delegate only weakly
+_pending: dict[int, dict[str, Any]] = {}
+
+
+def _key(delegate: ObjCObject) -> int:
+    """The delegate's address: the key of its sign-in in ``_pending``."""
+    return int(delegate.ptr.value or 0)
+
+
+def _name_cache() -> AppleNameCache:
+    global _names
+    if _names is None:
+        _names = AppleNameCache()
+    return _names
+
+
+def _protocols(*names: str) -> list[ObjCProtocol]:
+    found = []
+    for name in names:
+        try:
+            found.append(ObjCProtocol(name))
+        except NameError:
+            pass
+    return found
+
+
+def _apple_error(error: ObjCObject) -> AuthError:
+    result = auth_error_from_nserror(error)
+    apple = result.domain == AUTHORIZATION_ERROR_DOMAIN
+    result.cancelled = result.cancelled or (
+        apple and result.code == AUTHORIZATION_ERROR_CANCELED
+    )
+    # 1000 covers "no Apple Account on this device" (and set-up problems):
+    # not a network failure, so don't let the app say it is
+    if apple and result.code == AUTHORIZATION_ERROR_UNKNOWN:
+        result.message = NOT_SIGNED_IN_MESSAGE
+    return result
+
+
+def _text(value: object) -> str:
+    return "" if value is None else str(value)
+
+
+def _utf8(data: ObjCObject | None) -> str:
+    if data is None:
+        return ""
+    return str(
+        objc_class("NSString")
+        .alloc()
+        .initWithData_encoding_(data, NSUTF8StringEncoding)
+    )
+
+
+class PyAppleSignInDelegate(  # type: ignore[call-arg]  # Rubicon's class keyword
+    NSObject,
+    protocols=_protocols(
+        "ASAuthorizationControllerDelegate",
+        "ASAuthorizationControllerPresentationContextProviding",
+    ),
+):
+    """The ``ASAuthorizationController`` delegate and presentation context.
+
+    Rubicon reads these methods' annotations to build their Objective-C
+    signatures: parameters must be annotated with ctypes types (``objc_id``),
+    not Python types.
+    """
+
+    @objc_method
+    def presentationAnchorForAuthorizationController_(
+        self, controller: objc_id
+    ) -> objc_id:
+        """The window the Apple sheet is shown over: the key window."""
+        # objc_id is what Rubicon needs for the signature; the value is an object
+        return cast("objc_id", key_window())
+
+    @objc_method
+    def authorizationController_didCompleteWithAuthorization_(
+        self, controller: objc_id, authorization: objc_id
+    ) -> None:
+        """Apple signed the user in: turn the identity token into a credential."""
+        state = _pending.pop(_key(self), None)
+        if state is None:
+            return
+        callback: AppleCredentialCallback = state["callback"]
+        auth: ObjCObject = (
+            authorization  # an object at runtime (see the class docstring)
+        )
+        try:
+            credential = auth.credential
+            if not credential.isKindOfClass(
+                objc_class("ASAuthorizationAppleIDCredential")
+            ):
+                callback(None, simple_auth_error("Unexpected credential type"))
+                return
+            id_token = _utf8(credential.identityToken)
+            if not id_token:
+                callback(None, simple_auth_error("Apple returned no identity token"))
+                return
+            apple_user = _text(credential.user)
+            name = credential.fullName
+            sent_first = _text(name.givenName) if name is not None else ""
+            sent_last = _text(name.familyName) if name is not None else ""
+            # Apple sends the name only once: reuse the one an earlier,
+            # failed attempt saved
+            first, last = _name_cache().resolve(apple_user, sent_first, sent_last)
+            result = AppleCredential(
+                credential=OAuthProvider.apple_credential(
+                    id_token, state["raw_nonce"], first, last
+                ),
+                apple_user=apple_user,
+                first_name=first,
+                last_name=last,
+                email=_text(credential.email),
+                authorization_code=_utf8(credential.authorizationCode),
+            )
+        except Exception as e:  # noqa: BLE001 - must always answer the caller
+            callback(None, simple_auth_error(str(e)))
+            return
+        callback(result, None)
+
+    @objc_method
+    def authorizationController_didCompleteWithError_(
+        self, controller: objc_id, error: objc_id
+    ) -> None:
+        """Apple sign-in failed or was cancelled: report it."""
+        state = _pending.pop(_key(self), None)
+        if state is not None:
+            state["callback"](None, _apple_error(error))
+
+
+def get_apple_credential(callback: AppleCredentialCallback) -> None:
+    """Show the Sign in with Apple sheet and give back a Firebase credential,
+    without signing in to Firebase (for example to link Apple to the current
+    user, or to re-authenticate before deleting the account).
+
+    Args:
+        callback: gets ``(AppleCredential, None)``, or ``(None, error)``.
+            ``error.cancelled`` is True when the user closed the sheet;
+            ``error.message``, when not ``""``, is a sentence for the user.
+    """
+    # Apple signs SHA-256(nonce); Firebase checks it against the raw nonce
+    raw_nonce = secrets.token_urlsafe(32)
+    request = (
+        objc_class("ASAuthorizationAppleIDProvider").alloc().init().createRequest()
+    )
+    request.requestedScopes = ns_from_py([SCOPE_FULL_NAME, SCOPE_EMAIL])
+    request.nonce = hashlib.sha256(raw_nonce.encode()).hexdigest()
+
+    delegate = PyAppleSignInDelegate.alloc().init()
+    controller = (
+        objc_class("ASAuthorizationController")
+        .alloc()
+        .initWithAuthorizationRequests_(ns_from_py([request]))
+    )
+    controller.delegate = delegate  # weak in UIKit: _pending keeps both alive
+    controller.presentationContextProvider = delegate
+    _pending[_key(delegate)] = {
+        "callback": callback,
+        "raw_nonce": raw_nonce,
+        "delegate": delegate,
+        "controller": controller,
+    }
+    controller.performRequests()
+
+
+def start_apple_sign_in(
+    callback: AppleSignInCallback, auth: Auth | None = None
+) -> None:
+    """Show the Sign in with Apple sheet, then sign in to Firebase.
+
+    Args:
+        callback: gets ``(AppleSignInResult, None)``, or ``(None, error)``.
+            ``error.cancelled`` is True when the user closed the sheet: not a
+            failure to report. ``error.message``, when not ``""``, is a
+            sentence to show to the user.
+        auth: the ``Auth`` to sign in to (default: ``Auth.auth()``).
+    """
+
+    def got_credential(apple: AppleCredential | None, error: AuthError | None) -> None:
+        if apple is None:
+            callback(None, error)
+            return
+
+        def signed_in(
+            result: AuthDataResult | None, sign_in_error: AuthError | None
+        ) -> None:
+            if result is None:
+                callback(None, sign_in_error)
+                return
+            _name_cache().forget(apple.apple_user)  # Firebase has the name now
+            callback(AppleSignInResult(result._native, apple), None)
+
+        (auth or Auth.auth()).sign_in_with_credential(apple.credential, signed_in)
+
+    get_apple_credential(got_credential)