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

flwr/supercore/primitives/asymmetric.py

@@ -0,0 +1,117 @@
+# 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.
+# ==============================================================================
+"""Asymmetric cryptography utilities."""
+
+
+from typing import cast
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+def generate_key_pairs() -> (
+    tuple[ec.EllipticCurvePrivateKey, ec.EllipticCurvePublicKey]
+):
+    """Generate private and public key pairs with Cryptography."""
+    private_key = ec.generate_private_key(ec.SECP384R1())
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+def private_key_to_bytes(private_key: ec.EllipticCurvePrivateKey) -> bytes:
+    """Serialize private key to bytes."""
+    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) -> ec.EllipticCurvePrivateKey:
+    """Deserialize private key from bytes."""
+    return cast(
+        ec.EllipticCurvePrivateKey,
+        serialization.load_pem_private_key(data=private_key_bytes, password=None),
+    )
+
+
+def public_key_to_bytes(public_key: ec.EllipticCurvePublicKey) -> bytes:
+    """Serialize public key to bytes."""
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def bytes_to_public_key(public_key_bytes: bytes) -> ec.EllipticCurvePublicKey:
+    """Deserialize public key from bytes."""
+    return cast(
+        ec.EllipticCurvePublicKey,
+        serialization.load_pem_public_key(data=public_key_bytes),
+    )
+
+
+def sign_message(private_key: ec.EllipticCurvePrivateKey, message: bytes) -> bytes:
+    """Sign a message using the provided EC private key.
+
+    Parameters
+    ----------
+    private_key : ec.EllipticCurvePrivateKey
+        The EC private key to sign the message with.
+    message : bytes
+        The message to be signed.
+
+    Returns
+    -------
+    bytes
+        The signature of the message.
+    """
+    signature = private_key.sign(message, ec.ECDSA(hashes.SHA256()))
+    return signature
+
+
+def verify_signature(
+    public_key: ec.EllipticCurvePublicKey, message: bytes, signature: bytes
+) -> bool:
+    """Verify a signature against a message using the provided EC public key.
+
+    Parameters
+    ----------
+    public_key : ec.EllipticCurvePublicKey
+        The EC public key to verify the signature.
+    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, ec.ECDSA(hashes.SHA256()))
+        return True
+    except InvalidSignature:
+        return False
+
+
+def uses_nist_ec_curve(public_key: ec.EllipticCurvePublicKey) -> bool:
+    """Return True if the provided key uses a NIST EC curve."""
+    return isinstance(
+        public_key.curve,
+        (ec.SECP192R1 | ec.SECP224R1 | ec.SECP256R1 | ec.SECP384R1 | ec.SECP521R1),
+    )

flwr/supercore/primitives/asymmetric_ed25519.py

@@ -0,0 +1,175 @@
+# 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 pathlib import Path
+
+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_message_to_sign(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))
+
+
+def load_private_key(path: Path) -> ed25519.Ed25519PrivateKey:
+    """Load an SSH-format private key (Ed25519) using cryptography."""
+    key_bytes = path.read_bytes()
+    private_key = serialization.load_ssh_private_key(key_bytes, password=None)
+    if not isinstance(private_key, ed25519.Ed25519PrivateKey):
+        raise ValueError("Private key is not Ed25519")
+    return private_key

flwr/supercore/sqlite_mixin.py

@@ -0,0 +1,159 @@
+# 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
+from collections.abc import Sequence
+from logging import DEBUG, ERROR
+from typing import Any
+
+from flwr.common.logger import log
+
+DictOrTuple = 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: sqlite3.Connection | None = 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
+
+    def get_sql_statements(self) -> tuple[str, ...]:
+        """Return SQL statements for this class.
+
+        Subclasses can override this to provide their SQL CREATE statements.
+        The base implementation returns an empty tuple.
+
+        Returns
+        -------
+        tuple[str, ...]
+            SQL CREATE TABLE/INDEX statements for this class.
+        """
+        return ()
+
+    def initialize(self, log_queries: bool = False) -> list[tuple[str]]:
+        """Connect to the DB, enable FK support, and create tables if needed.
+
+        This method executes SQL statements returned by `get_sql_statements()`.
+
+        Parameters
+        ----------
+        log_queries : bool
+            Log each query which is executed.
+
+        Returns
+        -------
+        list[tuple[str]]
+            The list of all tables in the DB.
+
+        Examples
+        --------
+        Override `get_sql_statements()` in your subclass:
+
+        .. code:: python
+
+            def get_sql_statements(self) -> tuple[str, ...]:
+                return (
+                    SQL_CREATE_TABLE_FOO,
+                    SQL_CREATE_TABLE_BAR,
+                )
+
+        To include parent SQL statements, call super():
+
+        .. code:: python
+
+            def get_sql_statements(self) -> tuple[str, ...]:
+                return super().get_sql_statements() + (
+                    SQL_CREATE_TABLE_FOO,
+                    SQL_CREATE_TABLE_BAR,
+                )
+        """
+        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.execute("PRAGMA cache_size = -64000;")  # 64MB cache
+        self._conn.execute("PRAGMA temp_store = MEMORY;")  # In-memory temp tables
+        self._conn.execute("PRAGMA mmap_size = 268435456;")  # 256MB memory-mapped I/O
+        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 self.get_sql_statements():
+            cur.execute(sql)
+        res = cur.execute("SELECT name FROM sqlite_schema;")
+        return res.fetchall()
+
+    def query(
+        self,
+        query: str,
+        data: Sequence[DictOrTuple] | DictOrTuple | None = 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, strict=True))

flwr/supercore/superexec/plugin/base_exec_plugin.py

@@ -18,7 +18,6 @@
 import os
 import subprocess
 from collections.abc import Sequence
-from typing import Optional
 
 from .exec_plugin import ExecPlugin
 
@@ -33,7 +32,7 @@ class BaseExecPlugin(ExecPlugin):
     command = ""
     appio_api_address_arg = ""
 
-    def select_run_id(self, candidate_run_ids: Sequence[int]) -> Optional[int]:
+    def select_run_id(self, candidate_run_ids: Sequence[int]) -> int | None:
         """Select a run ID to execute from a sequence of candidates."""
         if not candidate_run_ids:
             return None

flwr/supercore/superexec/plugin/exec_plugin.py

@@ -16,8 +16,8 @@
 
 
 from abc import ABC, abstractmethod
-from collections.abc import Sequence
-from typing import Any, Callable, Optional
+from collections.abc import Callable, Sequence
+from typing import Any
 
 from flwr.common.typing import Run
 
@@ -36,7 +36,7 @@ class ExecPlugin(ABC):
         self.get_run = get_run
 
     @abstractmethod
-    def select_run_id(self, candidate_run_ids: Sequence[int]) -> Optional[int]:
+    def select_run_id(self, candidate_run_ids: Sequence[int]) -> int | None:
         """Select a run ID to execute from a sequence of candidates.
 
         A candidate run ID is one that has at least one pending message and is

flwr/supercore/superexec/run_superexec.py

@@ -17,7 +17,7 @@
 
 import time
 from logging import WARN
-from typing import Any, Optional, Union
+from typing import Any
 
 from flwr.common.config import get_flwr_dir
 from flwr.common.exit import ExitCode, flwr_exit, register_signal_handlers
@@ -43,14 +43,12 @@ from .plugin import ExecPlugin
 
 def run_superexec(  # pylint: disable=R0913,R0914,R0917
     plugin_class: type[ExecPlugin],
-    stub_class: Union[
-        type[ClientAppIoStub], type[ServerAppIoStub], type[SimulationIoStub]
-    ],
+    stub_class: type[ClientAppIoStub] | type[ServerAppIoStub] | type[SimulationIoStub],
     appio_api_address: str,
-    plugin_config: Optional[dict[str, Any]] = None,
-    flwr_dir: Optional[str] = None,
-    parent_pid: Optional[int] = None,
-    health_server_address: Optional[str] = None,
+    plugin_config: dict[str, Any] | None = None,
+    flwr_dir: str | None = None,
+    parent_pid: int | None = None,
+    health_server_address: str | None = None,
 ) -> None:
     """Run Flower SuperExec.
 
@@ -158,12 +156,10 @@ def run_with_deprecation_warning(  # pylint: disable=R0913, R0917
     cmd: str,
     plugin_type: str,
     plugin_class: type[ExecPlugin],
-    stub_class: Union[
-        type[ClientAppIoStub], type[ServerAppIoStub], type[SimulationIoStub]
-    ],
+    stub_class: type[ClientAppIoStub] | type[ServerAppIoStub] | type[SimulationIoStub],
     appio_api_address: str,
-    flwr_dir: Optional[str],
-    parent_pid: Optional[int],
+    flwr_dir: str | None,
+    parent_pid: int | None,
     warn_run_once: bool,
 ) -> None:
     """Log a deprecation warning and run the equivalent `flower-superexec` command.

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/superlink/artifact_provider/artifact_provider.py

@@ -16,14 +16,13 @@
 
 
 from abc import ABC, abstractmethod
-from typing import Optional
 
 
 class ArtifactProvider(ABC):
     """ArtifactProvider interface for providing artifact download links."""
 
     @abstractmethod
-    def get_url(self, run_id: int) -> Optional[str]:
+    def get_url(self, run_id: int) -> str | None:
         """Return the artifact download link for the given run ID."""
 
     @property

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,88 @@
+# 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 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) -> AccountAuthLoginDetails | None:
+        """Get the login details."""
+
+    @abstractmethod
+    def validate_tokens_in_metadata(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> tuple[bool, AccountInfo | None]:
+        """Validate authentication tokens in the provided metadata."""
+
+    @abstractmethod
+    def get_auth_tokens(self, device_code: str) -> AccountAuthCredentials | None:
+        """Get authentication tokens."""
+
+    @abstractmethod
+    def refresh_tokens(
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> tuple[Sequence[tuple[str, str | bytes]] | None, AccountInfo | None]:
+        """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."""