flwr-nightly 1.23.0.dev20251001__py3-none-any.whl → 1.23.0.dev20251003__py3-none-any.whl

flwr/cli/app.py

@@ -28,6 +28,9 @@ from .new import new
 from .pull import pull
 from .run import run
 from .stop import stop
+from .supernode import create as supernode_create
+from .supernode import delete as supernode_delete
+from .supernode import ls as supernode_list
 
 app = typer.Typer(
     help=typer.style(
@@ -49,6 +52,16 @@ app.command()(stop)
 app.command()(login)
 app.command()(pull)
 
+# Create supernode command group
+supernode_app = typer.Typer(help="Manage SuperNodes")
+supernode_app.command()(supernode_create)
+supernode_app.command()(supernode_delete)
+# Make it appear as "list"
+supernode_app.command("list")(supernode_list)
+# Hide "ls" command (left as alias)
+supernode_app.command(hidden=True)(supernode_list)
+app.add_typer(supernode_app, name="supernode")
+
 typer_click_object = get_command(app)
 
 

flwr/cli/auth_plugin/__init__.py

@@ -12,22 +12,25 @@
 # 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.constant import AuthType
+from flwr.common.constant import AuthnType
 
-from .auth_plugin import CliAuthPlugin
+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]]:
     """Return all CLI authentication plugins."""
-    return {AuthType.OIDC: OidcCliPlugin}
+    return {AuthnType.NOOP: NoOpCliAuthPlugin, AuthnType.OIDC: OidcCliPlugin}
 
 
 __all__ = [
     "CliAuthPlugin",
+    "LoginError",
+    "NoOpCliAuthPlugin",
     "OidcCliPlugin",
     "get_cli_auth_plugins",
 ]

flwr/cli/auth_plugin/auth_plugin.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Abstract classes for Flower User Auth Plugin."""
+"""Abstract classes for Flower account auth plugin."""
 
 
 from abc import ABC, abstractmethod
@@ -20,38 +20,50 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import Optional, Union
 
-from flwr.common.typing import UserAuthCredentials, UserAuthLoginDetails
+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 user's authentication credentials file.
+        Path to the Flower account's authentication credentials file.
     """
 
     @staticmethod
     @abstractmethod
     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 : UserAuthLoginDetails
-            An object containing the user's login details.
+        login_details : AccountAuthLoginDetails
+            An object containing the account's login details.
         control_stub : ControlStub
             A stub for executing RPC calls to the server.
 
         Returns
         -------
-        UserAuthCredentials
+        AccountAuthCredentials
             The authentication credentials obtained after login.
+
+        Raises
+        ------
+        LoginError
+            If the login process fails.
         """
 
     @abstractmethod
@@ -59,7 +71,7 @@ class CliAuthPlugin(ABC):
         """Abstract constructor."""
 
     @abstractmethod
-    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
@@ -79,5 +91,5 @@ class CliAuthPlugin(ABC):
     @abstractmethod
     def read_tokens_from_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[UserAuthCredentials]:
+    ) -> Optional[AccountAuthCredentials]:
         """Read authentication tokens from the provided metadata."""

flwr/cli/auth_plugin/noop_auth_plugin.py

@@ -0,0 +1,58 @@
+# 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 typing import Optional, Union
+
+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."""
+
+    @staticmethod
+    def login(
+        login_details: AccountAuthLoginDetails,
+        control_stub: ControlStub,
+    ) -> AccountAuthCredentials:
+        """Raise LoginError as no-op plugin does not support login."""
+        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."""
+
+    def load_tokens(self) -> None:
+        """Do nothing."""
+
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        """Return the metadata unchanged."""
+        return metadata
+
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[AccountAuthCredentials]:
+        """Return None."""
+        return None

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -12,7 +12,7 @@
 # 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
@@ -25,18 +25,18 @@ import typer
 
 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
+from .auth_plugin import CliAuthPlugin, LoginError
 
 
 class OidcCliPlugin(CliAuthPlugin):
@@ -49,12 +49,12 @@ class OidcCliPlugin(CliAuthPlugin):
 
     @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."""
         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,
         )
@@ -70,26 +70,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
@@ -98,7 +88,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,
         }
@@ -136,14 +126,14 @@ class OidcCliPlugin(CliAuthPlugin):
 
     def read_tokens_from_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[UserAuthCredentials]:
+    ) -> Optional[AccountAuthCredentials]:
         """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,
             )

flwr/cli/{cli_user_auth_interceptor.py → cli_account_auth_interceptor.py}

@@ -32,10 +32,10 @@ Request = Union[
 ]
 
 
-class CliUserAuthInterceptor(
+class CliAccountAuthInterceptor(
     grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
 ):
-    """CLI interceptor for user authentication."""
+    """CLI interceptor for account authentication."""
 
     def __init__(self, auth_plugin: CliAuthPlugin):
         self.auth_plugin = auth_plugin
@@ -70,7 +70,7 @@ class CliUserAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Intercept a unary-unary call for user authentication.
+        """Intercept a unary-unary call for account authentication.
 
         This method intercepts a unary-unary RPC call initiated from the CLI and adds
         the required authentication tokens to the RPC metadata.
@@ -83,7 +83,7 @@ class CliUserAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Intercept a unary-stream call for user authentication.
+        """Intercept a unary-stream call for account authentication.
 
         This method intercepts a unary-stream RPC call initiated from the CLI and adds
         the required authentication tokens to the RPC metadata.

flwr/cli/login/login.py

@@ -20,6 +20,7 @@ from typing import Annotated, Optional
 
 import typer
 
+from flwr.cli.auth_plugin import LoginError
 from flwr.cli.config_utils import (
     exit_if_no_address,
     get_insecure_flag,
@@ -28,14 +29,19 @@ from flwr.cli.config_utils import (
     validate_federation_in_project_config,
 )
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
-from flwr.common.typing import UserAuthLoginDetails
+from flwr.common.typing import AccountAuthLoginDetails
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetLoginDetailsRequest,
     GetLoginDetailsResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
-from ..utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
+from ..utils import (
+    account_auth_enabled,
+    flwr_cli_grpc_exc_handler,
+    init_channel,
+    try_obtain_cli_auth_plugin,
+)
 
 
 def login(  # pylint: disable=R0914
@@ -67,12 +73,13 @@ def login(  # pylint: disable=R0914
     )
     exit_if_no_address(federation_config, "login")
 
-    # Check if `enable-user-auth` is set to `true`
-    if not federation_config.get("enable-user-auth", False):
+    # Check if `enable-account-auth` is set to `true`
+
+    if not account_auth_enabled(federation_config):
         typer.secho(
-            f"❌ User authentication is not enabled for the federation '{federation}'. "
-            "To enable it, set `enable-user-auth = true` in the federation "
-            "configuration.",
+            "❌ Account authentication is not enabled for the federation "
+            f"'{federation}'. To enable it, set `enable-account-auth = true` "
+            "in the federation configuration.",
             fg=typer.colors.RED,
             bold=True,
         )
@@ -96,28 +103,41 @@ def login(  # pylint: disable=R0914
         login_response: GetLoginDetailsResponse = stub.GetLoginDetails(login_request)
 
     # Get the auth plugin
-    auth_type = login_response.auth_type
+    authn_type = login_response.authn_type
     auth_plugin = try_obtain_cli_auth_plugin(
-        app, federation, federation_config, auth_type
+        app, federation, federation_config, authn_type
     )
     if auth_plugin is None:
         typer.secho(
-            f'❌ Authentication type "{auth_type}" not found',
+            f'❌ Authentication type "{authn_type}" not found',
             fg=typer.colors.RED,
             bold=True,
         )
         raise typer.Exit(code=1)
 
     # Login
-    details = UserAuthLoginDetails(
-        auth_type=login_response.auth_type,
+    details = AccountAuthLoginDetails(
+        authn_type=login_response.authn_type,
         device_code=login_response.device_code,
         verification_uri_complete=login_response.verification_uri_complete,
         expires_in=login_response.expires_in,
         interval=login_response.interval,
     )
-    with flwr_cli_grpc_exc_handler():
-        credentials = auth_plugin.login(details, stub)
+    try:
+        with flwr_cli_grpc_exc_handler():
+            credentials = auth_plugin.login(details, stub)
+        typer.secho(
+            "✅ Login successful.",
+            fg=typer.colors.GREEN,
+            bold=False,
+        )
+    except LoginError as e:
+        typer.secho(
+            f"❌ Login failed: {e.message}",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from None
 
     # Store the tokens
     auth_plugin.store_tokens(credentials)

flwr/{client/clientapp → cli/supernode}/__init__.py

@@ -12,4 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower AppIO service."""
+"""Flower command line interface `supernode` command."""
+
+from .create import create as create
+from .delete import delete as delete
+from .ls import ls as ls
+
+__all__ = [
+    "create",
+    "delete",
+    "ls",
+]

flwr/cli/supernode/create.py

@@ -0,0 +1,58 @@
+# 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.
+# ==============================================================================
+"""Flower command line interface `supernode create` command."""
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from flwr.cli.config_utils import (
+    exit_if_no_address,
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE
+
+
+def create(  # pylint: disable=R0914
+    public_key: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the public key file.",
+        ),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+) -> None:
+    """Add a SuperNode to the federation."""
+    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+    pyproject_path = app / FAB_CONFIG_FILE if app else None
+    config, errors, warnings = load_and_validate(path=pyproject_path)
+    config = process_loaded_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
+    exit_if_no_address(federation_config, "supernode add")
+
+    _ = public_key

flwr/cli/supernode/delete.py

@@ -0,0 +1,58 @@
+# 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.
+# ==============================================================================
+"""Flower command line interface `supernode delete` command."""
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from flwr.cli.config_utils import (
+    exit_if_no_address,
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE
+
+
+def delete(  # pylint: disable=R0914
+    node_id: Annotated[
+        int,
+        typer.Argument(
+            help="ID of the SuperNode to remove.",
+        ),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+) -> None:
+    """Remove a SuperNode from the federation."""
+    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+    pyproject_path = app / FAB_CONFIG_FILE if app else None
+    config, errors, warnings = load_and_validate(path=pyproject_path)
+    config = process_loaded_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
+    exit_if_no_address(federation_config, "supernode rm")
+
+    _ = node_id

flwr/cli/supernode/ls.py

@@ -0,0 +1,51 @@
+# 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.
+# ==============================================================================
+"""Flower command line interface `supernode list` command."""
+
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from flwr.cli.config_utils import (
+    exit_if_no_address,
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE
+
+
+def ls(  # pylint: disable=R0914
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+) -> None:
+    """List SuperNodes in the federation."""
+    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+    pyproject_path = app / FAB_CONFIG_FILE if app else None
+    config, errors, warnings = load_and_validate(path=pyproject_path)
+    config = process_loaded_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
+    exit_if_no_address(federation_config, "supernode ls")