Skip to content

Commit 9f1e306

Browse files
mohammadnaseriyan-gao-GYCopilot
authored
docs(hub): Add app signing guide (#7012)
Co-authored-by: Yan Gao <yan@flower.ai> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 270d56e commit 9f1e306

File tree

4 files changed

+170
-1
lines changed

4 files changed

+170
-1
lines changed

‎hub/docs/source/how-to-publish-app-on-hub.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,10 @@ You can view it at:
290290
291291
https://flower.ai/apps/<account_name>/<app_name>/
292292
293+
.. tip::
294+
If you want trusted reviewers to verify your app after publication, see
295+
:doc:`how-to-sign-hub-apps`.
296+
293297

294298
Publish a New Version of Your App
295299
---------------------------------

‎hub/docs/source/how-to-sign-hub-apps.rst‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
Sign Hub Apps
2+
=============
3+
4+
This guide explains how app signing works in Flower Hub and how to use it in practice.
5+
6+
Before an app can be reviewed and signed, it must already be published to Flower Hub.
7+
The app does not need to be published by the same account that reviews and signs it.
8+
9+
.. note::
10+
11+
App signing and app-page verification metadata are preview features. They may
12+
change over time.
13+
14+
15+
How App Signing Works
16+
---------------------
17+
18+
At a high level:
19+
20+
1. An app exists on Flower Hub.
21+
2. The reviewer has an Ed25519 key pair and has registered the public key in
22+
their Flower account profile.
23+
3. The reviewer downloads the FAB and signs it with the matching Ed25519
24+
private key via :code:`flwr app review`.
25+
4. The signature is attached to app verification metadata in Flower Hub.
26+
5. Users can inspect the app's verification metadata on the app page and decide
27+
which signers they trust.
28+
29+
30+
Prerequisites
31+
-------------
32+
33+
- Ensure :code:`flwr` is installed
34+
- A Flower account and active login
35+
- An Ed25519 OpenSSH key pair for signing
36+
- The corresponding public key added to your Flower account profile
37+
- An app on Flower Hub to review and sign
38+
39+
Log in to your Flower account on SuperGrid:
40+
41+
.. code-block:: bash
42+
43+
flwr login supergrid
44+
45+
46+
Create a Signing Key
47+
--------------------
48+
49+
Generate an Ed25519 key pair in OpenSSH format:
50+
51+
.. code-block:: bash
52+
53+
ssh-keygen -t ed25519 -f hub_signing_key -C "hub-review-key"
54+
55+
This creates:
56+
57+
- :code:`hub_signing_key` (private key, keep secret)
58+
- :code:`hub_signing_key.pub` (public key)
59+
60+
.. warning::
61+
62+
Keep private keys secure. Anyone with this private key can produce signatures
63+
attributed to that signer.
64+
65+
66+
Register Your Public Key in Your Flower Account
67+
-----------------------------------------------
68+
69+
Add the public key to your Flower account profile:
70+
71+
- Open :code:`https://flower.ai/profile/<account_username>/`
72+
- Add the content of :code:`hub_signing_key.pub` to your profile keys
73+
74+
When signing, you must use the private key corresponding to a public key
75+
registered in the reviewer account.
76+
77+
78+
Choose an App to Sign
79+
---------------------
80+
81+
You can sign:
82+
83+
- your own app, or
84+
- an app published by someone else.
85+
86+
Supported app specs:
87+
88+
- :code:`@account/app` (latest version)
89+
- :code:`@account/app==x.y.z` (specific version)
90+
91+
Examples:
92+
93+
.. code-block:: bash
94+
95+
# Sign latest version
96+
flwr app review @flwrlabs/quickstart-pytorch
97+
98+
# Sign a specific version
99+
flwr app review @flwrlabs/quickstart-pytorch==1.1.0
100+
101+
102+
Review and Sign the App
103+
-----------------------
104+
105+
Sign an app version:
106+
107+
.. code-block:: bash
108+
109+
flwr app review @account/app==x.y.z
110+
111+
The CLI will:
112+
113+
1. Download the FAB.
114+
2. Unpack it for manual inspection.
115+
3. Ask you to type :code:`SIGN`.
116+
4. Ask for the path to your Ed25519 OpenSSH private key.
117+
5. Submit the signature to Flower Hub.
118+
119+
.. note::
120+
121+
:code:`flwr app review` signs the FAB digest plus timestamp. The resulting
122+
signature is submitted with the app ID and version.
123+
124+
125+
Check Verifications on the App Page
126+
-----------------------------------
127+
128+
If you want to run an app and evaluate trust, open the app page on Flower Hub
129+
and check the :code:`Verifications` section.
130+
Use this section to see who signed the app and decide whether you trust those
131+
signers.
132+
133+
134+
Troubleshooting
135+
---------------
136+
137+
- **Private key errors during review**
138+
139+
Ensure that your private key is an **Ed25519 OpenSSH** key. Other key types
140+
or formats are not supported.
141+
142+
- **Signature not displayed on the app page**
143+
144+
Verify that you:
145+
146+
1. Successfully completed :code:`flwr app review`
147+
2. Signed the app using a private key that corresponds to a public key
148+
registered in your Flower account profile
149+
150+
If the public key is not registered, or does not match the private key used
151+
for signing, the signature will not be displayed.
152+
153+
154+
See Also
155+
--------
156+
157+
- :doc:`how-to-publish-app-on-hub`
158+
- :doc:`how-to-use-app-from-hub`

‎hub/docs/source/how-to-use-app-from-hub.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,8 @@ In this setup, the SuperLink downloads the app from Flower Hub and—when using
108108
Flower version compatibility does not match the Flower version used by the
109109
local environment (Simulation) or the SuperNodes (Deployment). See
110110
:doc:`fab-format-version`.
111+
112+
.. tip::
113+
Before running a Hub app, you can inspect the app page's
114+
:code:`Verifications` section to evaluate which signers you trust. For
115+
details on how app signing works, see :doc:`how-to-sign-hub-apps`.

‎hub/docs/source/index.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,14 @@ The Flower Community is growing quickly - we're a friendly group of researchers,
1818
Flower Hub
1919
----------
2020

21-
Flower Hub is a hub for collaborative AI that enables the discovery, distribution, and execution of federated AI apps across heterogeneous environments.
21+
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.
2222

2323
With Flower Hub, you can:
2424

2525
- Focus on **federated application logic** without managing infrastructure complexity.
2626
- **Run applications with a single command** across simulation and deployment environments.
2727
- **Publish applications in a standardized format** and share them with the community, fostering collaboration and accelerating federated AI innovation.
28+
- **Sign published applications** and discover others verified by trusted reviewers.
2829
- Discover, reuse, and build upon federated applications created by others.
2930

3031
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
4142

4243
how-to-use-app-from-hub
4344
how-to-publish-app-on-hub
45+
how-to-sign-hub-apps
4446

4547

4648
Explanations

0 commit comments

Comments
 (0)