flwr 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/auth_plugin/__init__.py

@@ -12,20 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower user auth plugins."""
+"""Flower account auth plugins."""
 
 
-from flwr.common.auth_plugin import CliAuthPlugin
-from flwr.common.constant import AuthType
+from flwr.common.constant import AuthnType
 
+from .auth_plugin import CliAuthPlugin, LoginError
+from .noop_auth_plugin import NoOpCliAuthPlugin
 from .oidc_cli_plugin import OidcCliPlugin
 
 
-def get_cli_auth_plugins() -> dict[str, type[CliAuthPlugin]]:
+def get_cli_plugin_class(authn_type: str) -> type[CliAuthPlugin]:
     """Return all CLI authentication plugins."""
-    return {AuthType.OIDC: OidcCliPlugin}
+    if authn_type == AuthnType.NOOP:
+        return NoOpCliAuthPlugin
+    if authn_type == AuthnType.OIDC:
+        return OidcCliPlugin
+    raise ValueError(f"Unsupported authentication type: {authn_type}")
 
 
 __all__ = [
-    "get_cli_auth_plugins",
+    "CliAuthPlugin",
+    "LoginError",
+    "NoOpCliAuthPlugin",
+    "OidcCliPlugin",
+    "get_cli_plugin_class",
 ]

flwr/cli/auth_plugin/auth_plugin.py

@@ -0,0 +1,94 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# 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.
+# ==============================================================================
+"""Abstract classes for Flower account auth plugin."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
+from flwr.proto.control_pb2_grpc import ControlStub
+
+
+class LoginError(Exception):
+    """Login error exception."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+
+class CliAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for CLI.
+
+    Parameters
+    ----------
+    credentials_path : Path
+        Path to the Flower account's authentication credentials file.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def login(
+        login_details: AccountAuthLoginDetails,
+        control_stub: ControlStub,
+    ) -> AccountAuthCredentials:
+        """Authenticate the account and retrieve authentication credentials.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            An object containing the account's login details.
+        control_stub : ControlStub
+            A stub for executing RPC calls to the server.
+
+        Returns
+        -------
+        AccountAuthCredentials
+            The authentication credentials obtained after login.
+
+        Raises
+        ------
+        LoginError
+            If the login process fails.
+        """
+
+    @abstractmethod
+    def __init__(self, credentials_path: Path):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
+        """Store authentication tokens to the `credentials_path`.
+
+        The credentials, including tokens, will be saved as a JSON file
+        at `credentials_path`.
+        """
+
+    @abstractmethod
+    def load_tokens(self) -> None:
+        """Load authentication tokens from the `credentials_path`."""
+
+    @abstractmethod
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
+        """Write authentication tokens to the provided metadata."""
+
+    @abstractmethod
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
+        """Read authentication tokens from the provided metadata."""

flwr/cli/auth_plugin/noop_auth_plugin.py

@@ -0,0 +1,101 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# 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.
+# ==============================================================================
+"""Concrete NoOp implementation for CLI-side account authentication plugin."""
+
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
+from flwr.proto.control_pb2_grpc import ControlStub
+
+from .auth_plugin import CliAuthPlugin, LoginError
+
+
+class NoOpCliAuthPlugin(CliAuthPlugin):
+    """No-operation implementation of the CliAuthPlugin.
+
+    This plugin is used when account authentication is not enabled. It provides stub
+    implementations of all authentication methods that perform no actions.
+    """
+
+    @staticmethod
+    def login(
+        login_details: AccountAuthLoginDetails,
+        control_stub: ControlStub,
+    ) -> AccountAuthCredentials:
+        """Raise LoginError as no-op plugin does not support login.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            Login details (unused).
+        control_stub : ControlStub
+            Control stub (unused).
+
+        Returns
+        -------
+        AccountAuthCredentials
+            This method never returns as it always raises an exception.
+
+        Raises
+        ------
+        LoginError
+            Always raised to indicate authentication is not enabled.
+        """
+        raise LoginError("Account authentication is not enabled on this SuperLink.")
+
+    def __init__(self, credentials_path: Path) -> None:
+        pass
+
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
+        """Do nothing (no-op implementation)."""
+
+    def load_tokens(self) -> None:
+        """Do nothing (no-op implementation)."""
+
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
+        """Return the metadata unchanged.
+
+        Parameters
+        ----------
+        metadata : Sequence[tuple[str, str | bytes]]
+            The original metadata.
+
+        Returns
+        -------
+        Sequence[tuple[str, str | bytes]]
+            The same metadata, unmodified.
+        """
+        return metadata
+
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
+        """Return None (no tokens to read).
+
+        Parameters
+        ----------
+        metadata : Sequence[tuple[str, str | bytes]]
+            The metadata to read from (unused).
+
+        Returns
+        -------
+        None
+            Always returns None as no authentication is performed.
+        """
+        return None

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -12,48 +12,71 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower CLI user auth plugin for OIDC."""
+"""Flower CLI account auth plugin for OIDC."""
 
 
 import json
 import time
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import typer
 
-from flwr.common.auth_plugin import CliAuthPlugin
 from flwr.common.constant import (
     ACCESS_TOKEN_KEY,
-    AUTH_TYPE_JSON_KEY,
+    AUTHN_TYPE_JSON_KEY,
     REFRESH_TOKEN_KEY,
-    AuthType,
+    AuthnType,
 )
-from flwr.common.typing import UserAuthCredentials, UserAuthLoginDetails
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
+from .auth_plugin import CliAuthPlugin, LoginError
+
 
 class OidcCliPlugin(CliAuthPlugin):
-    """Flower OIDC auth plugin for CLI."""
+    """Flower OIDC authentication plugin for CLI.
+
+    This plugin implements OpenID Connect (OIDC) device flow authentication for CLI
+    access to Flower SuperLink.
+    """
 
     def __init__(self, credentials_path: Path):
-        self.access_token: Optional[str] = None
-        self.refresh_token: Optional[str] = None
+        self.access_token: str | None = None
+        self.refresh_token: str | None = None
         self.credentials_path = credentials_path
 
     @staticmethod
     def login(
-        login_details: UserAuthLoginDetails,
+        login_details: AccountAuthLoginDetails,
         control_stub: ControlStub,
-    ) -> UserAuthCredentials:
-        """Authenticate the user and retrieve authentication credentials."""
+    ) -> AccountAuthCredentials:
+        """Authenticate the account and retrieve authentication credentials.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            Login details containing device code and verification URI.
+        control_stub : ControlStub
+            Control stub for making authentication requests.
+
+        Returns
+        -------
+        AccountAuthCredentials
+            The access and refresh tokens.
+
+        Raises
+        ------
+        LoginError
+            If authentication times out.
+        """
         typer.secho(
-            "Please login with your user credentials here: "
+            "Please log into your Flower account here: "
             f"{login_details.verification_uri_complete}",
             fg=typer.colors.BLUE,
         )
@@ -69,26 +92,16 @@ class OidcCliPlugin(CliAuthPlugin):
             refresh_token = res.refresh_token
 
             if access_token and refresh_token:
-                typer.secho(
-                    "✅ Login successful.",
-                    fg=typer.colors.GREEN,
-                    bold=False,
-                )
-                return UserAuthCredentials(
+                return AccountAuthCredentials(
                     access_token=access_token,
                     refresh_token=refresh_token,
                 )
 
             time.sleep(login_details.interval)
 
-        typer.secho(
-            "❌ Timeout, failed to sign in.",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
+        raise LoginError("Process timed out.")
 
-    def store_tokens(self, credentials: UserAuthCredentials) -> None:
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
         """Store authentication tokens to the `credentials_path`.
 
         The credentials, including tokens, will be saved as a JSON file
@@ -97,7 +110,7 @@ class OidcCliPlugin(CliAuthPlugin):
         self.access_token = credentials.access_token
         self.refresh_token = credentials.refresh_token
         json_dict = {
-            AUTH_TYPE_JSON_KEY: AuthType.OIDC,
+            AUTHN_TYPE_JSON_KEY: AuthnType.OIDC,
             ACCESS_TOKEN_KEY: credentials.access_token,
             REFRESH_TOKEN_KEY: credentials.refresh_token,
         }
@@ -117,14 +130,15 @@ class OidcCliPlugin(CliAuthPlugin):
             self.refresh_token = refresh_token
 
     def write_tokens_to_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
         """Write authentication tokens to the provided metadata."""
         if self.access_token is None or self.refresh_token is None:
             typer.secho(
                 "❌ Missing authentication tokens. Please login first.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 
@@ -134,15 +148,15 @@ class OidcCliPlugin(CliAuthPlugin):
         ]
 
     def read_tokens_from_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[UserAuthCredentials]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
         """Read authentication tokens from the provided metadata."""
         metadata_dict = dict(metadata)
         access_token = metadata_dict.get(ACCESS_TOKEN_KEY)
         refresh_token = metadata_dict.get(REFRESH_TOKEN_KEY)
 
         if isinstance(access_token, str) and isinstance(refresh_token, str):
-            return UserAuthCredentials(
+            return AccountAuthCredentials(
                 access_token=access_token,
                 refresh_token=refresh_token,
             )