flwr 1.21.0__py3-none-any.whl → 1.23.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,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/superexec/plugin/exec_plugin.py

@@ -17,7 +17,7 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import Callable, Optional
+from typing import Any, Callable, Optional
 
 from flwr.common.typing import Run
 
@@ -69,3 +69,13 @@ class ExecPlugin(ABC):
            The ID of the run associated with the token, used for tracking or
            logging purposes.
         """
+
+    # This method is optional to implement
+    def load_config(self, yaml_config: dict[str, Any]) -> None:
+        """Load configuration from a YAML dictionary.
+
+        Parameters
+        ----------
+        yaml_config : dict[str, Any]
+            A dictionary representing the YAML configuration.
+        """

flwr/supercore/superexec/run_superexec.py

@@ -17,10 +17,10 @@
 
 import time
 from logging import WARN
-from typing import Optional, Union
+from typing import Any, Optional, Union
 
 from flwr.common.config import get_flwr_dir
-from flwr.common.exit import register_signal_handlers
+from flwr.common.exit import ExitCode, flwr_exit, register_signal_handlers
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.logger import log
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
@@ -47,6 +47,7 @@ def run_superexec(  # pylint: disable=R0913,R0914,R0917
         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,
@@ -61,6 +62,9 @@ def run_superexec(  # pylint: disable=R0913,R0914,R0917
         The gRPC stub class for the AppIO API.
     appio_api_address : str
         The address of the AppIO API.
+    plugin_config : Optional[dict[str, Any]] (default: None)
+        The configuration dictionary for the plugin. If `None`, the plugin will use
+        its default configuration.
     flwr_dir : Optional[str] (default: None)
         The Flower directory.
     parent_pid : Optional[int] (default: None)
@@ -113,6 +117,16 @@ def run_superexec(  # pylint: disable=R0913,R0914,R0917
         get_run=get_run,
     )
 
+    # Load plugin configuration from file if provided
+    try:
+        if plugin_config is not None:
+            plugin.load_config(plugin_config)
+    except (KeyError, ValueError) as e:
+        flwr_exit(
+            code=ExitCode.SUPEREXEC_INVALID_PLUGIN_CONFIG,
+            message=f"Invalid plugin config: {e!r}",
+        )
+
     # Start the main loop
     try:
         while True:

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/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+# ==============================================================================
+"""ArtifactProvider for SuperLink."""
+
+
+from .artifact_provider import ArtifactProvider
+
+__all__ = [
+    "ArtifactProvider",
+]

flwr/superlink/artifact_provider/artifact_provider.py

@@ -0,0 +1,37 @@
+# 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 base class for ArtifactProvider."""
+
+
+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]:
+        """Return the artifact download link for the given run ID."""
+
+    @property
+    @abstractmethod
+    def output_dir(self) -> str:
+        """Permanent storage directory."""
+
+    @property
+    @abstractmethod
+    def tmp_dir(self) -> str:
+        """Temporary storage directory."""

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",
 ]