TLS certs and external superlink support (plus initial work on authentication keys and .blossomfile) (#3)

* Adds script for TLS certs generation.
* Adds support for SUPERLINK_MODE (internal or external)
* Updates UI to support external superlink.
* Adds docker-compose.yaml file for self-signed local certs testing.
* Adds more tests
* Updates README.md
* Adds .blossomfile spec: a single file for the participant, with the configuration needed to connect to a federation. Work in progress!

README.md

@@ -77,6 +77,50 @@ python -m blossomtune_gradio
 
 The application will be accessible via a local URL provided by Gradio.
 
+## Generating Self-Signed Certificates for Local Development (Docker)
+
+When running the application with `docker-compose`, the `superlink` service requires TLS certificates to enable secure connections.
+
+For local development, you can generate a self-signed Certificate Authority (CA) and a `localhost` certificate using the provided script.
+
+**Step 1: Run the Certificate Generator**
+
+Execute the interactive TLS generation script located in the `blossomtune_gradio` directory:
+
+```bash
+python3 -m blossomtune_gradio.generate_tls
+```
+
+**Step 2: Choose the Development Option**
+
+When prompted, select option **1** to generate a self-signed certificate for `localhost`.
+
+```text
+===== BlossomTune TLS Certificate Generator =====
+Select an option:
+  1. Generate a self-signed 'localhost' certificate (for Development)
+  2. Generate a server certificate using the main CA (for Production)
+  3. Exit
+Enter your choice [1]: 1
+```
+
+The script will create a new directory named `certificates_localhost` containing the generated CA (`ca.crt`) and the server certificate files (`server.key`, `server.crt`, `server.pem`).
+
+**Step 3: Copy Certificates to the Data Directory**
+
+The `docker-compose.yml` file is configured to mount a local `./data/certs` directory into the `superlink` container. You must copy the essential certificate files into this location:
+
+```bash
+cp certificates_localhost/ca.crt ./data/certs/
+cp certificates_localhost/server.key ./data/certs/
+cp certificates_localhost/server.pem ./data/certs/
+```
+
+Once these files are in place, you can start the services using `docker compose up`.
+
+The Superlink will automatically find and use these certificates to secure its connections.
+
+
 ## Usage Guide
 
 ### For Participants

blossomtune_gradio/auth_keys.py

@@ -0,0 +1,120 @@
+import os
+import csv
+import logging
+from typing import List, Tuple
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives import serialization
+
+log = logging.getLogger(__name__)
+
+
+def rebuild_authorized_keys_csv(
+    key_dir: str, authorized_participants: List[Tuple[str, str]]
+):
+    """
+    Overwrites the public key CSV with a fresh list from a trusted source.
+
+    This function should be called before starting the Flower SuperLink to ensure
+    the list of authorized nodes is always in sync with the database.
+
+    Args:
+        key_dir (str): The directory where the CSV will be stored.
+        authorized_participants (List[Tuple[str, str]]): A list of tuples,
+            where each tuple contains (participant_id, public_key_pem).
+    """
+    csv_path = os.path.join(key_dir, "authorized_supernodes.csv")
+    log.info(f"Rebuilding authorized keys CSV at: {csv_path}")
+
+    with open(csv_path, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["participant_id", "public_key_pem"])
+        for participant_id, public_key_pem in authorized_participants:
+            writer.writerow([participant_id, public_key_pem])
+
+    log.info(
+        f"Successfully rebuilt {csv_path} with {len(authorized_participants)} keys."
+    )
+
+
+class AuthKeyGenerator:
+    """
+    Handles the generation of Elliptic Curve (EC) key pairs for Flower
+    SuperNode authentication.
+    """
+
+    def __init__(self, key_dir: str = "keys"):
+        """
+        Initializes the generator and ensures the key directory exists.
+
+        Args:
+            key_dir (str): The directory where key files will be stored.
+        """
+        self.key_dir = key_dir
+        os.makedirs(self.key_dir, exist_ok=True)
+        log.info(f"Authentication key directory set to: {self.key_dir}")
+
+    def _generate_key_pair(self) -> ec.EllipticCurvePrivateKey:
+        """Generates a single EC private key using the SECP384R1 curve."""
+        return ec.generate_private_key(ec.SECP384R1())
+
+    def _save_private_key(
+        self, private_key: ec.EllipticCurvePrivateKey, participant_id: str
+    ) -> str:
+        """Saves the private key to a file with secure permissions."""
+        priv_key_path = os.path.join(self.key_dir, f"{participant_id}.key")
+        with open(priv_key_path, "wb") as f:
+            f.write(
+                private_key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.PKCS8,
+                    encryption_algorithm=serialization.NoEncryption(),
+                )
+            )
+        # Set file permissions to read/write for owner only (600)
+        os.chmod(priv_key_path, 0o600)
+        log.info(f"Private key for {participant_id} saved securely to {priv_key_path}")
+        return priv_key_path
+
+    def _save_public_key_file(
+        self, private_key: ec.EllipticCurvePrivateKey, participant_id: str
+    ) -> str:
+        """Saves the public key to a .pub file."""
+        public_key = private_key.public_key()
+        pub_key_path = os.path.join(self.key_dir, f"{participant_id}.pub")
+        with open(pub_key_path, "wb") as f:
+            f.write(
+                public_key.public_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PublicFormat.SubjectPublicKeyInfo,
+                )
+            )
+        log.info(f"Public key for {participant_id} saved to {pub_key_path}")
+        return pub_key_path
+
+    def generate_participant_keys(self, participant_id: str) -> Tuple[str, str, str]:
+        """
+        Generates and saves a new EC key pair for a participant.
+
+        This is the main public method to call when a new participant is approved.
+
+        Args:
+            participant_id (str): A unique identifier for the participant.
+
+        Returns:
+            A tuple containing:
+            - The file path to the generated private key.
+            - The file path to the generated public key.
+            - The public key as a PEM-encoded string (for database storage).
+        """
+        private_key = self._generate_key_pair()
+        public_key = private_key.public_key()
+
+        priv_key_path = self._save_private_key(private_key, participant_id)
+        pub_key_path = self._save_public_key_file(private_key, participant_id)
+
+        public_key_pem = public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        ).decode("utf-8")
+
+        return (priv_key_path, pub_key_path, public_key_pem)

blossomtune_gradio/blossomfile.py

@@ -0,0 +1,87 @@
+import os
+import json
+import zipfile
+import logging
+from typing import Dict, Any
+
+# Configure logging for the module
+log = logging.getLogger(__name__)
+
+
+def create_blossomfile(
+    participant_id: str,
+    output_dir: str,
+    ca_cert_path: str,
+    auth_key_path: str,
+    auth_pub_path: str,
+    superlink_address: str,
+    partition_id: int,
+    num_partitions: int,
+) -> str:
+    """
+    Generates a .blossomfile for a participant.
+
+    This function packages all necessary credentials and configuration into a
+    single, portable .zip archive that a participant can use to easily
+    connect to the federation.
+
+    Args:
+        participant_id: The unique identifier for the participant.
+        output_dir: The directory where the final .blossomfile will be saved.
+        ca_cert_path: Path to the CA public certificate (`ca.crt`).
+        auth_key_path: Path to the participant's private EC key (`auth.key`).
+        auth_pub_path: Path to the participant's public EC key (`auth.pub`).
+        superlink_address: The public address of the Flower SuperLink.
+        partition_id: The data partition ID assigned to the participant.
+        num_partitions: The total number of partitions in the federation.
+
+    Returns:
+        The full path to the generated .blossomfile.
+    """
+    os.makedirs(output_dir, exist_ok=True)
+    blossomfile_path = os.path.join(output_dir, f"{participant_id}.blossomfile")
+    log.info(f"Creating Blossomfile for {participant_id} at {blossomfile_path}")
+
+    # 1. Create the blossom.json configuration data
+    blossom_config: Dict[str, Any] = {
+        "superlink_address": superlink_address,
+        "node_config": {
+            "partition-id": partition_id,
+            "num-partitions": num_partitions,
+        },
+    }
+
+    # 2. Define the files to be included in the archive
+    files_to_add = {
+        ca_cert_path: "ca.crt",
+        auth_key_path: "auth.key",
+        auth_pub_path: "auth.pub",
+    }
+
+    # 3. Create the zip archive
+    try:
+        with zipfile.ZipFile(blossomfile_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            # Add the configuration file
+            zf.writestr("blossom.json", json.dumps(blossom_config, indent=2))
+            log.info("Added blossom.json to archive.")
+
+            # Add the certificate and key files
+            for src_path, arc_name in files_to_add.items():
+                if os.path.exists(src_path):
+                    zf.write(src_path, arcname=arc_name)
+                    log.info(f"Added {arc_name} to archive from {src_path}.")
+                else:
+                    log.error(f"Credential file not found: {src_path}. Aborting.")
+                    raise FileNotFoundError(
+                        f"Required credential file not found: {src_path}"
+                    )
+
+    except Exception as e:
+        log.critical(f"Failed to create Blossomfile: {e}")
+        # Clean up partially created file on failure
+        if os.path.exists(blossomfile_path):
+            os.remove(blossomfile_path)
+        raise
+
+    log.info(f"Successfully created Blossomfile: {blossomfile_path}")
+    return blossomfile_path

blossomtune_gradio/config.py

@@ -10,7 +10,9 @@ SPACE_ID = os.getenv("SPACE_ID", "ethicalabs/BlossomTune-Orchestrator")
 SPACE_OWNER = os.getenv("SPACE_OWNER", SPACE_ID.split("/")[0] if SPACE_ID else None)
 
 # Use persistent storage if available
-DB_PATH = "/data/federation.db" if os.path.isdir("/data") else "federation.db"
+DB_PATH = (
+    "/data/db/federation.db" if os.path.isdir("/data/db") else "./data/db/federation.db"
+)
 MAX_NUM_NODES = int(os.getenv("MAX_NUM_NODES", "20"))
 SMTP_SENDER = os.getenv("SMTP_SENDER", "hello@ethicalabs.ai")
 SMTP_SERVER = os.getenv("SMTP_SERVER", "localhost")
@@ -19,5 +21,19 @@ SMTP_REQUIRE_TLS = util.strtobool(os.getenv("SMTP_REQUIRE_TLS", "false"))
 SMTP_USER = os.getenv("SMTP_USER", "")
 SMTP_PASSWORD = os.getenv("SMTP_PASSWORD", "")
 EMAIL_PROVIDER = os.getenv("EMAIL_PROVIDER", "smtp")
-SUPERLINK_HOST = os.getenv("SUPERLINK_HOST", "")
+SUPERLINK_HOST = os.getenv("SUPERLINK_HOST", "127.0.0.1:9092")
 SUPERLINK_PORT = int(os.getenv("SUPERLINK_PORT", 9092))
+SUPERLINK_MODE = os.getenv("SUPERLINK_MODE", "internal").lower()  # Or external
+
+# TLS root cert path. For production only.
+TLS_CERT_DIR = os.getenv("TLS_CERT_DIR", "./certs/")
+TLS_CA_KEY_PATH = os.getenv("TLS_CA_KEY_PATH", False)
+TLS_CA_CERT_PATH = os.getenv("TLS_CA_CERT_PATH", False)
+
+# BlossomTune cert - To be distributed to the participants (supernodes).
+BLOSSOMTUNE_TLS_CERT_PATH = os.getenv(
+    "BLOSSOMTUNE_TLS_CERT_PATH",
+    "/data/certs/server.crt"
+    if os.path.isdir("/data/certs")
+    else "./data/certs/server.crt",
+)

blossomtune_gradio/generate_tls.py

@@ -0,0 +1,90 @@
+import os
+import shutil
+import logging
+
+
+from blossomtune_gradio.tls import TLSGenerator
+from blossomtune_gradio import config as cfg
+
+
+# Configure basic logging for the script
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+def generate_dev_cert():
+    """Generates a self-signed certificate for localhost development."""
+    try:
+        print("\n--- Generating self-signed certificate for localhost ---")
+        cert_dir = "certificates_localhost"
+        if os.path.exists(cert_dir):
+            shutil.rmtree(cert_dir)
+
+        generator = TLSGenerator(cert_dir=cert_dir)
+        # Note: No existing CA is passed, so a new one will be created.
+        generator.generate_server_certificate(
+            common_name="localhost", sans=["localhost", "127.0.0.1"]
+        )
+        print(f"\n✅ Success! Self-signed CA and server cert created in '{cert_dir}'.")
+    except Exception as e:
+        print(f"\n❌ An error occurred: {e}")
+
+
+def generate_prod_cert():
+    """Generates a server certificate signed by the CA specified in config."""
+    if not cfg.TLS_CA_KEY_PATH or not cfg.TLS_CA_CERT_PATH:
+        print(
+            "\n❌ Error: TLS_CA_KEY_PATH and TLS_CA_CERT_PATH are not set in your config."
+        )
+        print("Please configure the paths to your main CA certificate and key.")
+        return
+
+    try:
+        print(
+            f"\n--- Generating production certificate signed by {cfg.TLS_CA_CERT_PATH} ---"
+        )
+        common_name = input(
+            "Enter the primary domain name for the server (e.g., fl.mydomain.com): "
+        ).strip()
+        if not common_name:
+            print("Error: Domain name cannot be empty.")
+            return
+
+        generator = TLSGenerator(cert_dir=cfg.TLS_CERT_DIR)
+        generator.generate_server_certificate(
+            common_name=common_name,
+            ca_key_path=cfg.TLS_CA_KEY_PATH,
+            ca_cert_path=cfg.TLS_CA_CERT_PATH,
+        )
+        print(
+            f"\n✅ Success! Server certificate and key created in '{cfg.TLS_CERT_DIR}'."
+        )
+    except Exception as e:
+        print(f"\n❌ An error occurred: {e}")
+
+
+def main():
+    """Main function to run the interactive menu."""
+    while True:
+        print("\n===== BlossomTune TLS Certificate Generator =====")
+        print("Select an option:")
+        print("  1. Generate a self-signed 'localhost' certificate (for Development)")
+        print("  2. Generate a server certificate using the main CA (for Production)")
+        print("  3. Exit")
+
+        choice = input("Enter your choice [1]: ").strip() or "1"
+
+        if choice == "1":
+            generate_dev_cert()
+        elif choice == "2":
+            generate_prod_cert()
+        elif choice == "3":
+            print("Exiting.")
+            break
+        else:
+            print("Invalid choice. Please try again.")
+
+
+if __name__ == "__main__":
+    main()

blossomtune_gradio/processing.py

@@ -37,6 +37,11 @@ def run_process(command, process_key):
 
 
 def start_superlink():
+    # Do not start an internal process if in external mode.
+    if cfg.SUPERLINK_MODE == "external":
+        log.warning("start_superlink called while in external mode. Operation aborted.")
+        return False, "Application is in external Superlink mode."
+
     if process_store["superlink"] and process_store["superlink"].poll() is None:
         return False, "Superlink process is already running."
     command = [shutil.which("flower-superlink"), "--insecure"]

blossomtune_gradio/tls.py

@@ -0,0 +1,139 @@
+import os
+import datetime
+import logging
+from ipaddress import ip_address
+from cryptography import x509
+from cryptography.x509.oid import NameOID
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.backends import default_backend
+
+log = logging.getLogger(__name__)
+
+
+class TLSGenerator:
+    """
+    A class to handle the generation of TLS certificates, keys, and CSRs.
+    This class contains the core cryptographic logic and is separated from
+    any user interface.
+    """
+
+    def __init__(self, cert_dir: str = "certificates"):
+        self.cert_dir = cert_dir
+        os.makedirs(self.cert_dir, exist_ok=True)
+        log.info(f"Certificate directory set to: {self.cert_dir}")
+
+    def _generate_private_key(self, filename: str) -> rsa.RSAPrivateKey:
+        """Generates and saves a 4096-bit RSA private key."""
+        log.info(f"Generating private key: {filename}...")
+        private_key = rsa.generate_private_key(
+            public_exponent=65537, key_size=4096, backend=default_backend()
+        )
+        key_path = os.path.join(self.cert_dir, filename)
+        with open(key_path, "wb") as f:
+            f.write(
+                private_key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.TraditionalOpenSSL,
+                    encryption_algorithm=serialization.NoEncryption(),
+                )
+            )
+        log.info(f"Private key saved to {key_path}")
+        return private_key
+
+    def create_ca(self) -> tuple[rsa.RSAPrivateKey, x509.Certificate]:
+        """Generates a new self-signed CA key and certificate."""
+        log.info("Generating a new self-signed CA...")
+        ca_private_key = self._generate_private_key("ca.key")
+
+        subject = issuer = x509.Name(
+            [
+                x509.NameAttribute(NameOID.COUNTRY_NAME, "DE"),
+                x509.NameAttribute(NameOID.ORGANIZATION_NAME, "BlossomTune CA"),
+                x509.NameAttribute(NameOID.COMMON_NAME, "BlossomTune Self-Signed CA"),
+            ]
+        )
+        cert_builder = (
+            x509.CertificateBuilder()
+            .subject_name(subject)
+            .issuer_name(issuer)
+            .public_key(ca_private_key.public_key())
+            .serial_number(x509.random_serial_number())
+            .not_valid_before(datetime.datetime.utcnow())
+            .not_valid_after(datetime.datetime.utcnow() + datetime.timedelta(days=730))
+            .add_extension(
+                x509.BasicConstraints(ca=True, path_length=None), critical=True
+            )
+        )
+        ca_cert = cert_builder.sign(ca_private_key, hashes.SHA256(), default_backend())
+
+        ca_cert_path = os.path.join(self.cert_dir, "ca.crt")
+        with open(ca_cert_path, "wb") as f:
+            f.write(ca_cert.public_bytes(serialization.Encoding.PEM))
+        log.info(f"CA certificate saved to {ca_cert_path}")
+        return ca_private_key, ca_cert
+
+    def generate_server_certificate(
+        self,
+        common_name: str,
+        sans: list[str] | None = None,
+        ca_key_path: str | None = None,
+        ca_cert_path: str | None = None,
+    ):
+        """
+        Generates a server key, signs a certificate, and creates a combined server.pem file.
+        - If a CA is provided, it uses it.
+        - Otherwise, it generates a new self-signed CA first.
+        """
+        server_private_key = self._generate_private_key("server.key")
+
+        if ca_key_path and ca_cert_path:
+            log.info(f"Loading existing CA from {ca_cert_path}")
+            with open(ca_key_path, "rb") as f:
+                ca_private_key = serialization.load_pem_private_key(
+                    f.read(), password=None
+                )
+            with open(ca_cert_path, "rb") as f:
+                ca_cert = x509.load_pem_x509_certificate(f.read())
+        else:
+            ca_private_key, ca_cert = self.create_ca()
+
+        subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, common_name)])
+        san_list = [x509.DNSName(common_name)]
+        if sans:
+            for name in set(sans):
+                try:
+                    san_list.append(x509.IPAddress(ip_address(name)))
+                except ValueError:
+                    san_list.append(x509.DNSName(name))
+
+        builder = (
+            x509.CertificateBuilder()
+            .subject_name(subject)
+            .issuer_name(ca_cert.subject)
+            .public_key(server_private_key.public_key())
+            .serial_number(x509.random_serial_number())
+            .not_valid_before(datetime.datetime.utcnow())
+            .not_valid_after(datetime.datetime.utcnow() + datetime.timedelta(days=365))
+            .add_extension(x509.SubjectAlternativeName(san_list), critical=False)
+        )
+        server_cert = builder.sign(ca_private_key, hashes.SHA256(), default_backend())
+
+        # Save the individual server certificate (.crt)
+        server_cert_path = os.path.join(self.cert_dir, "server.crt")
+        server_cert_bytes = server_cert.public_bytes(serialization.Encoding.PEM)
+        with open(server_cert_path, "wb") as f:
+            f.write(server_cert_bytes)
+        log.info(f"Server certificate saved to {server_cert_path}")
+
+        # Create the combined server.pem file for Flower Superlink
+        server_key_bytes = server_private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        server_pem_path = os.path.join(self.cert_dir, "server.pem")
+        with open(server_pem_path, "wb") as f:
+            f.write(server_cert_bytes)
+            f.write(server_key_bytes)
+        log.info(f"Server PEM file (cert + key) saved to {server_pem_path}")

blossomtune_gradio/ui/callbacks.py

@@ -8,6 +8,7 @@ from blossomtune_gradio.logs import log
 from blossomtune_gradio import federation as fed
 from blossomtune_gradio import processing
 from blossomtune_gradio.settings import settings
+from blossomtune_gradio import util
 
 from . import components
 from . import auth
@@ -24,7 +25,7 @@ def get_full_status_update(
     profile: gr.OAuthProfile | None, oauth_token: gr.OAuthToken | None
 ):
     owner = auth.is_space_owner(profile, oauth_token)
-    auth_status = "Authenticating..."  # Initial state, not in schema
+    auth_status = "Authenticating..."
     is_on_space = cfg.SPACE_OWNER is not None
     hf_handle_val = ""
     hf_handle_interactive = not is_on_space
@@ -53,27 +54,42 @@ def get_full_status_update(
             "SELECT participant_id, hf_handle, email, partition_id FROM requests WHERE status = 'approved' ORDER BY timestamp DESC"
         ).fetchall()
 
-    superlink_is_running = (
-        processing.process_store["superlink"]
-        and processing.process_store["superlink"].poll() is None
-    )
+    # Superlink Status Logic
+    superlink_btn_update = gr.update()  # Default empty update
+
+    if cfg.SUPERLINK_MODE == "internal":
+        superlink_is_running = (
+            processing.process_store["superlink"]
+            and processing.process_store["superlink"].poll() is None
+        )
+        superlink_status = "🟢 Running" if superlink_is_running else "🔴 Not Running"
+        if superlink_is_running:
+            superlink_btn_update = gr.update(
+                value="🛑 Stop Superlink", variant="stop", interactive=True
+            )
+        else:
+            superlink_btn_update = gr.update(
+                value="🚀 Start Superlink", variant="secondary", interactive=True
+            )
+
+    elif cfg.SUPERLINK_MODE == "external":
+        if not cfg.SUPERLINK_HOST:
+            superlink_status = "🔴 Not Configured"
+        else:
+            is_open = util.is_port_open(cfg.SUPERLINK_HOST, cfg.SUPERLINK_PORT)
+            superlink_status = "🟢 Running" if is_open else "🔴 Not Running"
+        # Disable the button in external mode
+        superlink_btn_update = gr.update(value="Managed Externally", interactive=False)
+    else:
+        superlink_status = "⚠️ Invalid Mode"
+        superlink_btn_update = gr.update(interactive=False)
+
     runner_is_running = (
         processing.process_store["runner"]
         and processing.process_store["runner"].poll() is None
     )
-
-    # Hardcode status text as it's not in the schema
-    superlink_status = "🟢 Running" if superlink_is_running else "🔴 Not Running"
     runner_status = "🟢 Running" if runner_is_running else "🔴 Not Running"
 
-    # Hardcode button text as it's not in the schema
-    if superlink_is_running:
-        superlink_btn_update = gr.update(value="🛑 Stop Superlink", variant="stop")
-    else:
-        superlink_btn_update = gr.update(
-            value="🚀 Start Superlink", variant="secondary"
-        )
-
     if runner_is_running:
         runner_btn_update = gr.update(value="🛑 Stop Runner", variant="stop")
     else:

blossomtune_gradio/util.py

@@ -1,7 +1,32 @@
 import re
+import socket
 import dns.resolver
 
 
+def is_port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    """
+    Checks if a TCP port is open on a given host.
+
+    Args:
+        host: The hostname or IP address to check.
+        port: The port number to check.
+        timeout: The connection timeout in seconds.
+
+    Returns:
+        True if the port is open and a connection can be established,
+        False otherwise.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(timeout)
+            s.connect((host, port))
+        print(f"TCP check successful: Port {port} is open on {host}.")
+        return True
+    except (socket.timeout, ConnectionRefusedError, OSError) as e:
+        print(f"TCP check failed: Port {port} on {host} is not open. Error: {e}")
+        return False
+
+
 def validate_email(email_address: str) -> bool:
     """
     Validates an email address using regex for format and

docker-compose.yaml

@@ -0,0 +1,45 @@
+services:
+  gradio_app:
+    image: ethicalabs/blossomtune-orchestrator:latest
+    container_name: gradio_app
+    build:
+      context: .
+      dockerfile: Dockerfile
+    command: ["gradio_app"]
+    ports:
+      - "7860:7860" # Expose the Gradio port to the host machine
+    volumes:
+      - ./data/db:/data/db # Mount the database directory for persistence
+      - ./data/certs:/data/certs:ro # Mount TLS certificates (read-only)
+      - ./data/keys:/data/keys:rw   # Mount authentication keys (read-write)
+      - ./data/cache:/root/.cache # Mount Hugging Face cache for models/datasets
+    depends_on:
+      - superlink # Optional: Ensures superlink starts before the UI
+    environment:
+      HF_TOKEN: ${HF_TOKEN}
+      SUPERLINK_MODE: external
+      SUPERLINK_HOST: host.docker.internal
+  superlink:
+    image: ethicalabs/blossomtune-orchestrator:latest
+    container_name: superlink
+    build:
+      context: .
+      dockerfile: Dockerfile
+    command: ["superlink"]
+    ports:
+      - "127.0.0.1:9092:9092" # Port for SuperNode connections
+      - "9093:9093" # Port for Flower CLI (e.g., flwr run)
+    volumes:
+      - ./data/certs:/data/certs:ro # Mount TLS certificates (read-only)
+      - ./data/keys:/data/keys:ro   # Mount authentication keys (read-only)
+      - ./data/results:/data/results # Mount results directory for persisting run artifacts
+  mailhog:
+    image: mailhog/mailhog
+    container_name: mailhog
+    restart: always
+    volumes:
+      - ./mailhog.auth:/mailhog.auth:ro
+      - ./data:/data:rw
+    ports:
+      - "1025:1025"
+      - "8025:8025"

docker_entrypoint.sh

@@ -8,6 +8,12 @@ env | grep -v -E "SECRET|KEY|TOKEN|PASSWORD|ACCESS"
 if [ "${1}" = "gradio_app" ]; then
     echo "Running Gradio App..."
     exec python3 -m blossomtune_gradio
+elif [ "${1}" = "superlink" ]; then
+    echo "Running Superlink..."
+    exec flower-superlink \
+        --ssl-ca-certfile /data/certs/ca.crt \
+        --ssl-certfile /data/certs/server.pem \
+        --ssl-keyfile /data/certs/server.key
 else
     exec "$@"
 fi

pyproject.toml

@@ -68,6 +68,7 @@ convention = "google"  # Accepts: "google", "numpy", or "pep257".
 
 [dependency-groups]
 dev = [
+    "cryptography>=44.0.3",
     "dnspython>=2.8.0",
     "pytest>=8.4.1",
     "pytest-mock>=3.15.1",

tests/test_auth_keys.py

@@ -0,0 +1,133 @@
+import os
+import csv
+import stat
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from blossomtune_gradio.auth_keys import AuthKeyGenerator, rebuild_authorized_keys_csv
+
+
+@pytest.fixture
+def key_generator(tmp_path):
+    """Fixture to create an AuthKeyGenerator instance in a temporary directory."""
+    key_dir = tmp_path / "auth_keys"
+    return AuthKeyGenerator(key_dir=str(key_dir))
+
+
+class TestAuthKeyGenerator:
+    """Test suite for the AuthKeyGenerator class."""
+
+    def test_init_creates_directory(self, tmp_path):
+        """Verify that the key directory is created on initialization."""
+        key_dir = tmp_path / "new_keys"
+        assert not os.path.exists(key_dir)
+        AuthKeyGenerator(key_dir=str(key_dir))
+        assert os.path.exists(key_dir)
+
+    def test_generate_participant_keys_creates_files_and_returns_data(
+        self, key_generator
+    ):
+        """
+        Verify that the main method generates all expected files and returns
+        the correct data tuple.
+        """
+        participant_id = "participant_01"
+        priv_path, pub_path, pub_pem = key_generator.generate_participant_keys(
+            participant_id
+        )
+
+        # 1. Check if files exist
+        assert os.path.exists(priv_path)
+        assert os.path.exists(pub_path)
+        assert priv_path == os.path.join(key_generator.key_dir, f"{participant_id}.key")
+        assert pub_path == os.path.join(key_generator.key_dir, f"{participant_id}.pub")
+
+        # 2. Check private key file permissions (security check)
+        # In non-Windows environments, check for 600 permissions.
+        if os.name != "nt":
+            file_mode = stat.S_IMODE(os.stat(priv_path).st_mode)
+            assert file_mode == 0o600
+
+        # 3. Verify key formats and consistency
+        with open(priv_path, "rb") as f:
+            private_key = serialization.load_pem_private_key(f.read(), password=None)
+        with open(pub_path, "rb") as f:
+            public_key = serialization.load_pem_public_key(f.read())
+            _ = f.read()  # Read again to get bytes
+
+        assert isinstance(private_key, ec.EllipticCurvePrivateKey)
+        assert isinstance(public_key, ec.EllipticCurvePublicKey)
+
+        # Check that the returned PEM string matches the public key
+        generated_public_key = private_key.public_key()
+        pem_from_private = generated_public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        ).decode("utf-8")
+        assert pub_pem == pem_from_private
+
+
+class TestRebuildCSV:
+    """Test suite for the rebuild_authorized_keys_csv function."""
+
+    def test_rebuild_csv_creates_file_with_header_for_empty_list(self, tmp_path):
+        """Verify a CSV with only a header is created for an empty participant list."""
+        key_dir = tmp_path / "csv_test"
+        os.makedirs(key_dir)
+        csv_path = os.path.join(key_dir, "authorized_supernodes.csv")
+
+        rebuild_authorized_keys_csv(key_dir, [])
+
+        assert os.path.exists(csv_path)
+        with open(csv_path, "r") as f:
+            reader = csv.reader(f)
+            header = next(reader)
+            assert header == ["participant_id", "public_key_pem"]
+            # Check that there are no more rows
+            with pytest.raises(StopIteration):
+                next(reader)
+
+    def test_rebuild_csv_writes_correct_data(self, tmp_path):
+        """Verify the CSV is created with the correct participant data."""
+        key_dir = tmp_path / "csv_test"
+        os.makedirs(key_dir)
+        csv_path = os.path.join(key_dir, "authorized_supernodes.csv")
+
+        participants = [
+            ("p1", "---BEGIN PUBLIC KEY---...p1...---END PUBLIC KEY---"),
+            ("p2", "---BEGIN PUBLIC KEY---...p2...---END PUBLIC KEY---"),
+        ]
+        rebuild_authorized_keys_csv(key_dir, participants)
+
+        with open(csv_path, "r") as f:
+            reader = csv.reader(f)
+            header = next(reader)
+            row1 = next(reader)
+            row2 = next(reader)
+            assert header == ["participant_id", "public_key_pem"]
+            assert row1 == list(participants[0])
+            assert row2 == list(participants[1])
+
+    def test_rebuild_csv_overwrites_existing_file(self, tmp_path):
+        """Verify that an existing CSV file is correctly overwritten."""
+        key_dir = tmp_path / "csv_test"
+        os.makedirs(key_dir)
+        csv_path = os.path.join(key_dir, "authorized_supernodes.csv")
+
+        # First run with initial data
+        initial_participants = [("old_p1", "old_key_1")]
+        rebuild_authorized_keys_csv(key_dir, initial_participants)
+
+        # Second run with new data
+        new_participants = [("new_p1", "new_key_1"), ("new_p2", "new_key_2")]
+        rebuild_authorized_keys_csv(key_dir, new_participants)
+
+        with open(csv_path, "r") as f:
+            reader = csv.reader(f)
+            _ = next(reader)
+            rows = list(reader)
+
+        assert len(rows) == 2
+        assert rows[0] == list(new_participants[0])
+        assert rows[1] == list(new_participants[1])

tests/test_blossomfile.py

@@ -0,0 +1,104 @@
+import os
+import json
+import zipfile
+import pytest
+
+from blossomtune_gradio.blossomfile import create_blossomfile
+
+
+@pytest.fixture
+def dummy_credential_files(tmp_path):
+    """
+    Pytest fixture to create dummy credential files in a temporary directory.
+    Returns the paths to the created files.
+    """
+    creds_dir = tmp_path / "creds"
+    os.makedirs(creds_dir)
+
+    ca_cert_path = creds_dir / "ca.crt"
+    auth_key_path = creds_dir / "auth.key"
+    auth_pub_path = creds_dir / "auth.pub"
+
+    ca_cert_path.write_text("---BEGIN CERTIFICATE---")
+    auth_key_path.write_text("---BEGIN EC PRIVATE KEY---")
+    auth_pub_path.write_text("---BEGIN PUBLIC KEY---")
+
+    return {
+        "ca_cert_path": str(ca_cert_path),
+        "auth_key_path": str(auth_key_path),
+        "auth_pub_path": str(auth_pub_path),
+    }
+
+
+def test_create_blossomfile_success(tmp_path, dummy_credential_files):
+    """
+    Tests the successful creation of a .blossomfile, verifying its contents.
+    """
+    output_dir = tmp_path / "output"
+    participant_id = "participant_abc"
+
+    blossomfile_path = create_blossomfile(
+        participant_id=participant_id,
+        output_dir=str(output_dir),
+        ca_cert_path=dummy_credential_files["ca_cert_path"],
+        auth_key_path=dummy_credential_files["auth_key_path"],
+        auth_pub_path=dummy_credential_files["auth_pub_path"],
+        superlink_address="blossomtune-test.ethicalabs.ai:9092",
+        partition_id=5,
+        num_partitions=10,
+    )
+
+    # 1. Verify the file was created at the correct path
+    assert os.path.exists(blossomfile_path)
+    assert blossomfile_path == str(output_dir / f"{participant_id}.blossomfile")
+
+    # 2. Verify the contents of the zip archive
+    with zipfile.ZipFile(blossomfile_path, "r") as zf:
+        # Check that all expected files are present
+        namelist = zf.namelist()
+        assert "blossom.json" in namelist
+        assert "ca.crt" in namelist
+        assert "auth.key" in namelist
+        assert "auth.pub" in namelist
+        assert len(namelist) == 4
+
+        # Check the content of blossom.json
+        with zf.open("blossom.json") as f:
+            config_data = json.load(f)
+            assert (
+                config_data["superlink_address"]
+                == "blossomtune-test.ethicalabs.ai:9092"
+            )
+            assert config_data["node_config"]["partition-id"] == 5
+            assert config_data["node_config"]["num-partitions"] == 10
+
+        # Check the content of the credential files
+        assert zf.read("ca.crt").decode("utf-8") == "---BEGIN CERTIFICATE---"
+        assert zf.read("auth.key").decode("utf-8") == "---BEGIN EC PRIVATE KEY---"
+        assert zf.read("auth.pub").decode("utf-8") == "---BEGIN PUBLIC KEY---"
+
+
+def test_create_blossomfile_missing_input_file(tmp_path):
+    """
+    Tests that the function raises FileNotFoundError if a required credential
+    file is missing and cleans up the partial archive.
+    """
+    output_dir = tmp_path / "output"
+    participant_id = "participant_xyz"
+    missing_file_path = tmp_path / "creds" / "non_existent.key"
+    blossomfile_path = output_dir / f"{participant_id}.blossomfile"
+
+    with pytest.raises(FileNotFoundError, match="Required credential file not found"):
+        create_blossomfile(
+            participant_id=participant_id,
+            output_dir=str(output_dir),
+            ca_cert_path=str(missing_file_path),  # Pass a path that doesn't exist
+            auth_key_path="dummy",
+            auth_pub_path="dummy",
+            superlink_address="test:9092",
+            partition_id=1,
+            num_partitions=2,
+        )
+
+    # Verify that the partially created blossomfile was removed
+    assert not os.path.exists(blossomfile_path)

tests/test_tls.py

@@ -0,0 +1,93 @@
+import os
+import pytest
+from cryptography import x509
+
+from blossomtune_gradio.tls import TLSGenerator
+
+
+@pytest.fixture
+def tls_generator(tmp_path):
+    """Fixture to create a TLSGenerator instance in a temporary directory."""
+    cert_dir = tmp_path / "certs"
+    return TLSGenerator(cert_dir=str(cert_dir))
+
+
+class TestTLSGenerator:
+    """Test suite for the TLSGenerator class."""
+
+    def test_init_creates_directory(self, tmp_path):
+        """Verify that the certificate directory is created on initialization."""
+        cert_dir = tmp_path / "new_certs"
+        assert not os.path.exists(cert_dir)
+        TLSGenerator(cert_dir=str(cert_dir))
+        assert os.path.exists(cert_dir)
+
+    def test_create_ca(self, tls_generator):
+        """Test the creation of a self-signed Certificate Authority."""
+        ca_key, ca_cert = tls_generator.create_ca()
+
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "ca.key"))
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "ca.crt"))
+        assert ca_cert.issuer == ca_cert.subject
+        assert (
+            ca_cert.extensions.get_extension_for_class(x509.BasicConstraints).value.ca
+            is True
+        )
+
+    def test_generate_server_certificate_with_new_ca(self, tls_generator):
+        """
+        Test generating a server certificate, which should also create a new CA
+        and the combined server.pem file.
+        """
+        common_name = "test.local"
+        sans = ["test.local", "192.168.1.10"]
+        tls_generator.generate_server_certificate(common_name=common_name, sans=sans)
+
+        # Check for all expected files
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "ca.key"))
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "ca.crt"))
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "server.key"))
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "server.crt"))
+        assert os.path.exists(os.path.join(tls_generator.cert_dir, "server.pem"))
+
+        # Load certs to verify issuer relationship
+        with open(os.path.join(tls_generator.cert_dir, "ca.crt"), "rb") as f:
+            ca_cert = x509.load_pem_x509_certificate(f.read())
+        with open(os.path.join(tls_generator.cert_dir, "server.crt"), "rb") as f:
+            server_cert = x509.load_pem_x509_certificate(f.read())
+
+        assert server_cert.issuer == ca_cert.subject
+
+        # Verify PEM content
+        with open(os.path.join(tls_generator.cert_dir, "server.pem"), "r") as f:
+            pem_content = f.read()
+        assert "-----BEGIN CERTIFICATE-----" in pem_content
+        assert "-----BEGIN RSA PRIVATE KEY-----" in pem_content
+
+    def test_generate_server_certificate_with_existing_ca(self, tls_generator):
+        """Test generating a server certificate using a pre-existing CA."""
+        tls_generator.create_ca()
+        ca_key_path = os.path.join(tls_generator.cert_dir, "ca.key")
+        ca_cert_path = os.path.join(tls_generator.cert_dir, "ca.crt")
+
+        server_gen_dir = os.path.join(
+            os.path.dirname(tls_generator.cert_dir), "server_certs"
+        )
+        server_generator = TLSGenerator(cert_dir=server_gen_dir)
+
+        server_generator.generate_server_certificate(
+            common_name="prod.local", ca_key_path=ca_key_path, ca_cert_path=ca_cert_path
+        )
+
+        # Check that server files were created in the new directory
+        assert os.path.exists(os.path.join(server_gen_dir, "server.key"))
+        assert os.path.exists(os.path.join(server_gen_dir, "server.crt"))
+        assert os.path.exists(os.path.join(server_gen_dir, "server.pem"))
+        # Check that a *new* CA was NOT created in the server directory
+        assert not os.path.exists(os.path.join(server_gen_dir, "ca.key"))
+
+        # Verify PEM content
+        with open(os.path.join(server_gen_dir, "server.pem"), "r") as f:
+            pem_content = f.read()
+        assert "-----BEGIN CERTIFICATE-----" in pem_content
+        assert "-----BEGIN RSA PRIVATE KEY-----" in pem_content

tests/test_util.py

@@ -1,8 +1,43 @@
 import pytest
+import socket
 import dns.resolver
 from unittest.mock import MagicMock
 
-from blossomtune_gradio.util import validate_email, strtobool
+from blossomtune_gradio.util import is_port_open, validate_email, strtobool
+
+
+def test_is_port_open_success(mocker):
+    """
+    Tests the case where the port is open and the connection succeeds.
+    """
+    mock_socket = mocker.patch("blossomtune_gradio.util.socket.socket")
+    mock_socket.return_value.__enter__.return_value.connect.return_value = None
+
+    result = is_port_open("testhost", 1234)
+
+    assert result is True
+    # Verify that the socket was created and connect was called with the correct args
+    mock_socket.return_value.__enter__.return_value.settimeout.assert_called_once_with(
+        1.0
+    )
+    mock_socket.return_value.__enter__.return_value.connect.assert_called_once_with(
+        ("testhost", 1234)
+    )
+
+
+@pytest.mark.parametrize("exception", [ConnectionRefusedError, socket.timeout, OSError])
+def test_is_port_open_failures(mocker, exception):
+    """
+    Tests various failure scenarios where the port is not open.
+    - ConnectionRefusedError: The host actively refuses the connection.
+    - socket.timeout: The connection attempt times out.
+    - OSError: A generic network error occurs.
+    """
+    mock_socket = mocker.patch("blossomtune_gradio.util.socket.socket")
+    mock_socket.return_value.__enter__.return_value.connect.side_effect = exception
+
+    result = is_port_open("testhost", 1234)
+    assert result is False
 
 
 def test_validate_email_valid(monkeypatch):

uv.lock

@@ -241,6 +241,7 @@ dependencies = [
 
 [package.dev-dependencies]
 dev = [
+    { name = "cryptography" },
     { name = "dnspython" },
     { name = "pytest" },
     { name = "pytest-mock" },
@@ -262,6 +263,7 @@ requires-dist = [
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "cryptography", specifier = ">=44.0.3" },
     { name = "dnspython", specifier = ">=2.8.0" },
     { name = "pytest", specifier = ">=8.4.1" },
     { name = "pytest-mock", specifier = ">=3.15.1" },