diff --git a/hub/docs/source/how-to-publish-app-on-hub.rst b/hub/docs/source/how-to-publish-app-on-hub.rst index 1a18057aa0d6..111c78520ded 100644 --- a/hub/docs/source/how-to-publish-app-on-hub.rst +++ b/hub/docs/source/how-to-publish-app-on-hub.rst @@ -290,6 +290,10 @@ You can view it at: https://flower.ai/apps/// +.. tip:: + If you want trusted reviewers to verify your app after publication, see + :doc:`how-to-sign-hub-apps`. + Publish a New Version of Your App --------------------------------- diff --git a/hub/docs/source/how-to-sign-hub-apps.rst b/hub/docs/source/how-to-sign-hub-apps.rst new file mode 100644 index 000000000000..aef4dd6c1b27 --- /dev/null +++ b/hub/docs/source/how-to-sign-hub-apps.rst @@ -0,0 +1,158 @@ +Sign Hub Apps +============= + +This guide explains how app signing works in Flower Hub and how to use it in practice. + +Before an app can be reviewed and signed, it must already be published to Flower Hub. +The app does not need to be published by the same account that reviews and signs it. + +.. note:: + + App signing and app-page verification metadata are preview features. They may + change over time. + + +How App Signing Works +--------------------- + +At a high level: + +1. An app exists on Flower Hub. +2. The reviewer has an Ed25519 key pair and has registered the public key in + their Flower account profile. +3. The reviewer downloads the FAB and signs it with the matching Ed25519 + private key via :code:`flwr app review`. +4. The signature is attached to app verification metadata in Flower Hub. +5. Users can inspect the app's verification metadata on the app page and decide + which signers they trust. + + +Prerequisites +------------- + +- Ensure :code:`flwr` is installed +- A Flower account and active login +- An Ed25519 OpenSSH key pair for signing +- The corresponding public key added to your Flower account profile +- An app on Flower Hub to review and sign + +Log in to your Flower account on SuperGrid: + +.. code-block:: bash + + flwr login supergrid + + +Create a Signing Key +-------------------- + +Generate an Ed25519 key pair in OpenSSH format: + +.. code-block:: bash + + ssh-keygen -t ed25519 -f hub_signing_key -C "hub-review-key" + +This creates: + +- :code:`hub_signing_key` (private key, keep secret) +- :code:`hub_signing_key.pub` (public key) + +.. warning:: + + Keep private keys secure. Anyone with this private key can produce signatures + attributed to that signer. + + +Register Your Public Key in Your Flower Account +----------------------------------------------- + +Add the public key to your Flower account profile: + +- Open :code:`https://flower.ai/profile//` +- Add the content of :code:`hub_signing_key.pub` to your profile keys + +When signing, you must use the private key corresponding to a public key +registered in the reviewer account. + + +Choose an App to Sign +--------------------- + +You can sign: + +- your own app, or +- an app published by someone else. + +Supported app specs: + +- :code:`@account/app` (latest version) +- :code:`@account/app==x.y.z` (specific version) + +Examples: + +.. code-block:: bash + + # Sign latest version + flwr app review @flwrlabs/quickstart-pytorch + + # Sign a specific version + flwr app review @flwrlabs/quickstart-pytorch==1.1.0 + + +Review and Sign the App +----------------------- + +Sign an app version: + +.. code-block:: bash + + flwr app review @account/app==x.y.z + +The CLI will: + +1. Download the FAB. +2. Unpack it for manual inspection. +3. Ask you to type :code:`SIGN`. +4. Ask for the path to your Ed25519 OpenSSH private key. +5. Submit the signature to Flower Hub. + +.. note:: + + :code:`flwr app review` signs the FAB digest plus timestamp. The resulting + signature is submitted with the app ID and version. + + +Check Verifications on the App Page +----------------------------------- + +If you want to run an app and evaluate trust, open the app page on Flower Hub +and check the :code:`Verifications` section. +Use this section to see who signed the app and decide whether you trust those +signers. + + +Troubleshooting +--------------- + +- **Private key errors during review** + + Ensure that your private key is an **Ed25519 OpenSSH** key. Other key types + or formats are not supported. + +- **Signature not displayed on the app page** + + Verify that you: + + 1. Successfully completed :code:`flwr app review` + 2. Signed the app using a private key that corresponds to a public key + registered in your Flower account profile + + If the public key is not registered, or does not match the private key used + for signing, the signature will not be displayed. + + +See Also +-------- + +- :doc:`how-to-publish-app-on-hub` +- :doc:`how-to-use-app-from-hub` diff --git a/hub/docs/source/how-to-use-app-from-hub.rst b/hub/docs/source/how-to-use-app-from-hub.rst index c3b2e4bad941..cca3a9bad77a 100644 --- a/hub/docs/source/how-to-use-app-from-hub.rst +++ b/hub/docs/source/how-to-use-app-from-hub.rst @@ -108,3 +108,8 @@ In this setup, the SuperLink downloads the app from Flower Hub and—when using Flower version compatibility does not match the Flower version used by the local environment (Simulation) or the SuperNodes (Deployment). See :doc:`fab-format-version`. + +.. tip:: + Before running a Hub app, you can inspect the app page's + :code:`Verifications` section to evaluate which signers you trust. For + details on how app signing works, see :doc:`how-to-sign-hub-apps`. diff --git a/hub/docs/source/index.rst b/hub/docs/source/index.rst index 9cd26c39a91b..ec3e54060757 100644 --- a/hub/docs/source/index.rst +++ b/hub/docs/source/index.rst @@ -18,13 +18,14 @@ The Flower Community is growing quickly - we're a friendly group of researchers, Flower Hub ---------- -Flower Hub is a hub for collaborative AI that enables the discovery, distribution, and execution of federated AI apps across heterogeneous environments. +Flower Hub is a hub for collaborative AI that enables the discovery, distribution, execution, and decentralized verification of federated AI apps across heterogeneous environments, without reliance on a centralized trust authority. With Flower Hub, you can: - Focus on **federated application logic** without managing infrastructure complexity. - **Run applications with a single command** across simulation and deployment environments. - **Publish applications in a standardized format** and share them with the community, fostering collaboration and accelerating federated AI innovation. +- **Sign published applications** and discover others verified by trusted reviewers. - Discover, reuse, and build upon federated applications created by others. Explore the available applications on Flower Hub and contribute your own federated apps to help grow the ecosystem. @@ -41,6 +42,7 @@ How-to guides provide step-by-step instructions to help you accomplish specific how-to-use-app-from-hub how-to-publish-app-on-hub + how-to-sign-hub-apps Explanations