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

flwr/supercore/primitives/asymmetric_ed25519.py

@@ -0,0 +1,165 @@
+# 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.
+# ==============================================================================
+"""Ed25519-only asymmetric cryptography utilities."""
+
+import base64
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+
+def generate_key_pair() -> tuple[ed25519.Ed25519PrivateKey, ed25519.Ed25519PublicKey]:
+    """Generate an Ed25519 private/public key pair.
+
+    Returns
+    -------
+    Tuple[Ed25519PrivateKey, Ed25519PublicKey]
+        Private and public key pair.
+    """
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    return private_key, private_key.public_key()
+
+
+def private_key_to_bytes(private_key: ed25519.Ed25519PrivateKey) -> bytes:
+    """Serialize an Ed25519 private key to PEM bytes.
+
+    Parameters
+    ----------
+    private_key : Ed25519PrivateKey
+        The private key to serialize.
+
+    Returns
+    -------
+    bytes
+        PEM-encoded private key.
+    """
+    return private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def bytes_to_private_key(private_key_bytes: bytes) -> ed25519.Ed25519PrivateKey:
+    """Deserialize an Ed25519 private key from PEM bytes.
+
+    Parameters
+    ----------
+    private_key_bytes : bytes
+        PEM-encoded private key.
+
+    Returns
+    -------
+    Ed25519PrivateKey
+        Deserialized private key.
+    """
+    return serialization.load_pem_private_key(
+        private_key_bytes, password=None
+    )  # type: ignore[return-value]
+
+
+def public_key_to_bytes(public_key: ed25519.Ed25519PublicKey) -> bytes:
+    """Serialize an Ed25519 public key to PEM bytes.
+
+    Parameters
+    ----------
+    public_key : Ed25519PublicKey
+        The public key to serialize.
+
+    Returns
+    -------
+    bytes
+        PEM-encoded public key.
+    """
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def bytes_to_public_key(public_key_bytes: bytes) -> ed25519.Ed25519PublicKey:
+    """Deserialize an Ed25519 public key from PEM bytes.
+
+    Parameters
+    ----------
+    public_key_bytes : bytes
+        PEM-encoded public key.
+
+    Returns
+    -------
+    Ed25519PublicKey
+        Deserialized public key.
+    """
+    return serialization.load_pem_public_key(public_key_bytes)  # type: ignore[return-value]
+
+
+def sign_message(private_key: ed25519.Ed25519PrivateKey, message: bytes) -> bytes:
+    """Sign a message using an Ed25519 private key.
+
+    Parameters
+    ----------
+    private_key : Ed25519PrivateKey
+        The private key used for signing.
+    message : bytes
+        The message to sign.
+
+    Returns
+    -------
+    bytes
+        The signature of the message.
+    """
+    return private_key.sign(message)
+
+
+def verify_signature(
+    public_key: ed25519.Ed25519PublicKey, message: bytes, signature: bytes
+) -> bool:
+    """Verify a signature using an Ed25519 public key.
+
+    Parameters
+    ----------
+    public_key : Ed25519PublicKey
+        The public key used for verification.
+    message : bytes
+        The original message.
+    signature : bytes
+        The signature to verify.
+
+    Returns
+    -------
+    bool
+        True if the signature is valid, False otherwise.
+    """
+    try:
+        public_key.verify(signature, message)
+        return True
+    except InvalidSignature:
+        return False
+
+
+def create_signed_message(fab_digest: bytes, timestamp: int) -> bytes:
+    """Create a canonical message:
+    timestamp (8 bytes big-endian) + fab_digest.
+    """
+    timestamp_bytes = timestamp.to_bytes(8, byteorder="big")
+    return timestamp_bytes + fab_digest
+
+
+def decode_base64url(sig: str) -> bytes:
+    """Convert signature to b64 format."""
+    # add missing padding (=) to a multiple of 4
+    pad = (-len(sig)) % 4
+    return base64.urlsafe_b64decode(sig + ("=" * pad))

flwr/supercore/sqlite_mixin.py

@@ -0,0 +1,156 @@
+# 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.
+# ==============================================================================
+"""Mixin providing common SQLite connection and initialization logic."""
+
+
+import re
+import sqlite3
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from logging import DEBUG, ERROR
+from typing import Any, Optional, Union
+
+from flwr.common.logger import log
+
+DictOrTuple = Union[tuple[Any, ...], dict[str, Any]]
+
+
+class SqliteMixin(ABC):
+    """Mixin providing common SQLite connection and initialization logic."""
+
+    def __init__(self, database_path: str) -> None:
+        self.database_path = database_path
+        self._conn: Optional[sqlite3.Connection] = None
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        """Get the SQLite connection."""
+        if self._conn is None:
+            raise AttributeError("Database not initialized. Call initialize() first.")
+        return self._conn
+
+    @abstractmethod
+    def initialize(self, log_queries: bool = False) -> list[tuple[str]]:
+        """Connect to the DB, enable FK support, and create tables if needed.
+
+        Parameters
+        ----------
+        log_queries : bool
+            Log each query which is executed.
+
+        Returns
+        -------
+        list[tuple[str]]
+            The list of all tables in the DB.
+
+        Examples
+        --------
+        Implement in subclass:
+
+        .. code:: python
+
+            def initialize(self, log_queries: bool = False) -> list[tuple[str]]:
+                return self._ensure_initialized(
+                    SQL_CREATE_TABLE_FOO,
+                    SQL_CREATE_TABLE_BAR,
+                    log_queries=log_queries
+                )
+        """
+
+    def _ensure_initialized(
+        self,
+        *create_statements: str,
+        log_queries: bool = False,
+    ) -> list[tuple[str]]:
+        """Connect to the DB, enable FK support, and create tables if needed.
+
+        Subclasses should call this with their own CREATE TABLE/INDEX statements in
+        their `.initialize()` methods.
+
+        Parameters
+        ----------
+        create_statements : str
+            SQL statements to create tables and indexes.
+        log_queries : bool
+            Log each query which is executed.
+
+        Returns
+        -------
+        list[tuple[str]]
+            The list of all tables in the DB.
+        """
+        self._conn = sqlite3.connect(self.database_path)
+        # Enable Write-Ahead Logging (WAL) for better concurrency
+        self._conn.execute("PRAGMA journal_mode = WAL;")
+        self._conn.execute("PRAGMA synchronous = NORMAL;")
+        self._conn.execute("PRAGMA foreign_keys = ON;")
+        self._conn.row_factory = dict_factory
+
+        if log_queries:
+            self._conn.set_trace_callback(lambda q: log(DEBUG, q))
+
+        # Create tables and indexes
+        cur = self._conn.cursor()
+        for sql in create_statements:
+            cur.execute(sql)
+        res = cur.execute("SELECT name FROM sqlite_schema;")
+        return res.fetchall()
+
+    def query(
+        self,
+        query: str,
+        data: Optional[Union[Sequence[DictOrTuple], DictOrTuple]] = None,
+    ) -> list[dict[str, Any]]:
+        """Execute a SQL query and return the results as list of dicts."""
+        if self._conn is None:
+            raise AttributeError("LinkState is not initialized.")
+
+        if data is None:
+            data = []
+
+        # Clean up whitespace to make the logs nicer
+        query = re.sub(r"\s+", " ", query)
+
+        try:
+            with self._conn:
+                if (
+                    len(data) > 0
+                    and isinstance(data, (tuple, list))
+                    and isinstance(data[0], (tuple, dict))
+                ):
+                    rows = self._conn.executemany(query, data)
+                else:
+                    rows = self._conn.execute(query, data)
+
+                # Extract results before committing to support
+                #   INSERT/UPDATE ... RETURNING
+                # style queries
+                result = rows.fetchall()
+        except KeyError as exc:
+            log(ERROR, {"query": query, "data": data, "exception": exc})
+
+        return result
+
+
+def dict_factory(
+    cursor: sqlite3.Cursor,
+    row: sqlite3.Row,
+) -> dict[str, Any]:
+    """Turn SQLite results into dicts.
+
+    Less efficent for retrival of large amounts of data but easier to use.
+    """
+    fields = [column[0] for column in cursor.description]
+    return dict(zip(fields, row))

flwr/supercore/utils.py

@@ -30,3 +30,23 @@ def mask_string(value: str, head: int = 4, tail: int = 4) -> str:
     if len(value) <= head + tail:
         return value
     return f"{value[:head]}...{value[-tail:]}"
+
+
+def uint64_to_int64(unsigned: int) -> int:
+    """Convert a uint64 integer to a sint64 with the same bit pattern.
+
+    For values >= 2^63, wraps around by subtracting 2^64.
+    """
+    if unsigned >= (1 << 63):
+        return unsigned - (1 << 64)
+    return unsigned
+
+
+def int64_to_uint64(signed: int) -> int:
+    """Convert a sint64 integer to a uint64 with the same bit pattern.
+
+    For negative values, wraps around by adding 2^64.
+    """
+    if signed < 0:
+        return signed + (1 << 64)
+    return signed

flwr/{common → superlink}/auth_plugin/__init__.py

@@ -12,15 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Auth plugin components."""
+"""Account auth plugin for ControlServicer."""
 
 
-from .auth_plugin import CliAuthPlugin as CliAuthPlugin
-from .auth_plugin import ControlAuthPlugin as ControlAuthPlugin
-from .auth_plugin import ControlAuthzPlugin as ControlAuthzPlugin
+from .auth_plugin import ControlAuthnPlugin, ControlAuthzPlugin
+from .noop_auth_plugin import NoOpControlAuthnPlugin, NoOpControlAuthzPlugin
 
 __all__ = [
-    "CliAuthPlugin",
-    "ControlAuthPlugin",
+    "ControlAuthnPlugin",
     "ControlAuthzPlugin",
+    "NoOpControlAuthnPlugin",
+    "NoOpControlAuthzPlugin",
 ]

flwr/superlink/auth_plugin/auth_plugin.py

@@ -0,0 +1,91 @@
+# 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 plugins."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Optional, Union
+
+from flwr.common.typing import (
+    AccountAuthCredentials,
+    AccountAuthLoginDetails,
+    AccountInfo,
+)
+
+
+class ControlAuthnPlugin(ABC):
+    """Abstract Flower Authentication Plugin class for ControlServicer.
+
+    Parameters
+    ----------
+    account_auth_config_path : Path
+        Path to the YAML file containing the authentication configuration.
+    verify_tls_cert : bool
+        Boolean indicating whether to verify the TLS certificate
+        when making requests to the server.
+    """
+
+    @abstractmethod
+    def __init__(
+        self,
+        account_auth_config_path: Path,
+        verify_tls_cert: bool,
+    ):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def get_login_details(self) -> Optional[AccountAuthLoginDetails]:
+        """Get the login details."""
+
+    @abstractmethod
+    def validate_tokens_in_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> tuple[bool, Optional[AccountInfo]]:
+        """Validate authentication tokens in the provided metadata."""
+
+    @abstractmethod
+    def get_auth_tokens(self, device_code: str) -> Optional[AccountAuthCredentials]:
+        """Get authentication tokens."""
+
+    @abstractmethod
+    def refresh_tokens(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> tuple[
+        Optional[Sequence[tuple[str, Union[str, bytes]]]], Optional[AccountInfo]
+    ]:
+        """Refresh authentication tokens in the provided metadata."""
+
+
+class ControlAuthzPlugin(ABC):  # pylint: disable=too-few-public-methods
+    """Abstract Flower Authorization Plugin class for ControlServicer.
+
+    Parameters
+    ----------
+    account_auth_config_path : Path
+        Path to the YAML file containing the authorization configuration.
+    verify_tls_cert : bool
+        Boolean indicating whether to verify the TLS certificate
+        when making requests to the server.
+    """
+
+    @abstractmethod
+    def __init__(self, account_auth_config_path: Path, verify_tls_cert: bool):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def authorize(self, account_info: AccountInfo) -> bool:
+        """Verify account authorization request."""

flwr/superlink/auth_plugin/noop_auth_plugin.py

@@ -0,0 +1,87 @@
+# 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 Servicer-side account authentication and
+authorization plugins."""
+
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Optional, Union
+
+from flwr.common.constant import NOOP_ACCOUNT_NAME, NOOP_FLWR_AID, AuthnType
+from flwr.common.typing import (
+    AccountAuthCredentials,
+    AccountAuthLoginDetails,
+    AccountInfo,
+)
+
+from .auth_plugin import ControlAuthnPlugin, ControlAuthzPlugin
+
+NOOP_ACCOUNT_INFO = AccountInfo(
+    flwr_aid=NOOP_FLWR_AID,
+    account_name=NOOP_ACCOUNT_NAME,
+)
+
+
+class NoOpControlAuthnPlugin(ControlAuthnPlugin):
+    """No-operation implementation of ControlAuthnPlugin."""
+
+    def __init__(
+        self,
+        account_auth_config_path: Path,
+        verify_tls_cert: bool,
+    ):
+        pass
+
+    def get_login_details(self) -> Optional[AccountAuthLoginDetails]:
+        """Get the login details."""
+        # This allows the `flwr login` command to load the NoOp plugin accordingly,
+        # which then raises a LoginError when attempting to login.
+        return AccountAuthLoginDetails(
+            authn_type=AuthnType.NOOP,  # No operation authn type
+            device_code="",
+            verification_uri_complete="",
+            expires_in=0,
+            interval=0,
+        )
+
+    def validate_tokens_in_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> tuple[bool, Optional[AccountInfo]]:
+        """Return valid for no-op plugin."""
+        return True, NOOP_ACCOUNT_INFO
+
+    def get_auth_tokens(self, device_code: str) -> Optional[AccountAuthCredentials]:
+        """Get authentication tokens."""
+        raise RuntimeError("NoOp plugin does not support getting auth tokens.")
+
+    def refresh_tokens(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> tuple[
+        Optional[Sequence[tuple[str, Union[str, bytes]]]], Optional[AccountInfo]
+    ]:
+        """Refresh authentication tokens in the provided metadata."""
+        return metadata, NOOP_ACCOUNT_INFO
+
+
+class NoOpControlAuthzPlugin(ControlAuthzPlugin):
+    """No-operation implementation of ControlAuthzPlugin."""
+
+    def __init__(self, account_auth_config_path: Path, verify_tls_cert: bool):
+        pass
+
+    def authorize(self, account_info: AccountInfo) -> bool:
+        """Return True for no-op plugin."""
+        return True

flwr/superlink/servicer/control/{control_user_auth_interceptor.py → control_account_auth_interceptor.py}

@@ -20,7 +20,6 @@ from typing import Any, Callable, Union
 
 import grpc
 
-from flwr.common.auth_plugin import ControlAuthPlugin, ControlAuthzPlugin
 from flwr.common.typing import AccountInfo
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
@@ -32,6 +31,7 @@ from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StreamLogsRequest,
     StreamLogsResponse,
 )
+from flwr.superlink.auth_plugin import ControlAuthnPlugin, ControlAuthzPlugin
 
 Request = Union[
     StartRunRequest,
@@ -50,15 +50,15 @@ shared_account_info: contextvars.ContextVar[AccountInfo] = contextvars.ContextVa
 )
 
 
-class ControlUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
-    """Control API interceptor for user authentication."""
+class ControlAccountAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Control API interceptor for account authentication."""
 
     def __init__(
         self,
-        auth_plugin: ControlAuthPlugin,
+        authn_plugin: ControlAuthnPlugin,
         authz_plugin: ControlAuthzPlugin,
     ):
-        self.auth_plugin = auth_plugin
+        self.authn_plugin = authn_plugin
         self.authz_plugin = authz_plugin
 
     def intercept_service(
@@ -96,45 +96,45 @@ class ControlUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
             if isinstance(request, (GetLoginDetailsRequest, GetAuthTokensRequest)):
                 return call(request, context)  # type: ignore
 
-            # For other requests, check if the user is authenticated
-            valid_tokens, account_info = self.auth_plugin.validate_tokens_in_metadata(
+            # For other requests, check if the account is authenticated
+            valid_tokens, account_info = self.authn_plugin.validate_tokens_in_metadata(
                 metadata
             )
             if valid_tokens:
                 if account_info is None:
                     context.abort(
                         grpc.StatusCode.UNAUTHENTICATED,
-                        "Tokens validated, but user info not found",
+                        "Tokens validated, but account info not found",
                     )
                     raise grpc.RpcError()
-                # Store user info in contextvars for authenticated users
+                # Store account info in contextvars for authenticated accounts
                 shared_account_info.set(account_info)
-                # Check if the user is authorized
-                if not self.authz_plugin.verify_user_authorization(account_info):
+                # Check if the account is authorized
+                if not self.authz_plugin.authorize(account_info):
                     context.abort(
                         grpc.StatusCode.PERMISSION_DENIED,
-                        "❗️ User not authorized. "
+                        "❗️ Account not authorized. "
                         "Please contact the SuperLink administrator.",
                     )
                     raise grpc.RpcError()
                 return call(request, context)  # type: ignore
 
-            # If the user is not authenticated, refresh tokens
-            tokens, account_info = self.auth_plugin.refresh_tokens(metadata)
+            # If the account is not authenticated, refresh tokens
+            tokens, account_info = self.authn_plugin.refresh_tokens(metadata)
             if tokens is not None:
                 if account_info is None:
                     context.abort(
                         grpc.StatusCode.UNAUTHENTICATED,
-                        "Tokens refreshed, but user info not found",
+                        "Tokens refreshed, but account info not found",
                     )
                     raise grpc.RpcError()
-                # Store user info in contextvars for authenticated users
+                # Store account info in contextvars for authenticated accounts
                 shared_account_info.set(account_info)
-                # Check if the user is authorized
-                if not self.authz_plugin.verify_user_authorization(account_info):
+                # Check if the account is authorized
+                if not self.authz_plugin.authorize(account_info):
                     context.abort(
                         grpc.StatusCode.PERMISSION_DENIED,
-                        "❗️ User not authorized. "
+                        "❗️ Account not authorized. "
                         "Please contact the SuperLink administrator.",
                     )
                     raise grpc.RpcError()

flwr/superlink/servicer/control/control_event_log_interceptor.py

@@ -24,7 +24,7 @@ from google.protobuf.message import Message as GrpcMessage
 from flwr.common.event_log_plugin.event_log_plugin import EventLogWriterPlugin
 from flwr.common.typing import LogEntry
 
-from .control_user_auth_interceptor import shared_account_info
+from .control_account_auth_interceptor import shared_account_info
 
 
 class ControlEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore