github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/flagship.md (about)

     1  # Flagship App
     2  
     3  ## Introduction
     4  
     5  The flagship application is a mobile application that can be used to run all
     6  the Cozy webapps inside it. It also has a bunch of exclusive features like the
     7  client-side connectors. But, to be able to work, it needs a very powerful
     8  access to the Cozy instance. Technically, it means that the flagship app is an
     9  OAuth client with a scope that covers everything. And we want to ensure that
    10  only the flagship can have this power. So, we require the application to be
    11  certified. It can be certified via the Google and Apple stores, and when it's
    12  not available, the user has the possibility to manually certify the flagship
    13  app (lineage OS users for example).
    14  
    15  Let's see the workflow when a user opens the flagship app for the first time.
    16  The app will load, and it will open a page of the cloudery for the onboarding.
    17  The user can type their email address, the cloudery sends an email, the user
    18  opens a link in this email, and then, we have two cases: the user already have
    19  a Cozy instance, or they want to create a new one. In both cases, the flagship
    20  will register its-self as an OAuth client on the Cozy and will type their
    21  passphrase before going to the home of the Cozy inside the flagship app. It is
    22  just that for a new Cozy, there are a few additional steps like accepting the
    23  terms of services.
    24  
    25  **Note:** the flagship app can be used with self-hosted stack. The user will
    26  have to type their Cozy address instead of using their email address, but
    27  everything else should work, including the certification via the Google and
    28  Apple stores (there are some config parameters, but they have a default value
    29  that make this possible).
    30  
    31  ## Create the OAuth client & certification
    32  
    33  When the flagship app knows the Cozy instance of the user, it will register
    34  itself as an OAuth client, and will try to attest that it is really the
    35  flagship app via the Google and Apple APIs. It is done by calling these 3
    36  routes from the stack:
    37  
    38  1. `POST /auth/register`
    39  2. `POST /auth/clients/:client-id/challenge`
    40  3. `POST /auth/clients/:client-id/attestation`
    41  
    42  Between 2 and 3, the app will ask the mobile OS to certify that this is really
    43  the flagship app. It is done via the [Play Integrity
    44  API](https://developer.android.com/google/play/integrity) (or [SafetyNet
    45  attestation API](https://developer.android.com/training/safetynet/attestation))
    46  on Android, and the [AppAttest
    47  API](https://developer.apple.com/documentation/devicecheck) on iOS.
    48  
    49  ## New Cozy instance
    50  
    51  On a new Cozy instance, the user will choose a passphrase that will be
    52  registered on the Cozy by sending its PBKDF2 hash to
    53  `POST /settings/passphrase/flagship`.
    54  
    55  ## Existing Cozy instance
    56  
    57  On an existing Cozy instance, the app will fetch some parameters with
    58  `GET /public/prelogin`, then the user can type their passphrase, and the PBKDF2
    59  hash will be sent to `POST /auth/login/flagship` to give the app access to the
    60  whole Cozy.
    61  
    62  ## Magic link variant
    63  
    64  When magic link is enabled on a Cozy, the flagship app can use
    65  `POST /auth/magic_link/flagship` with a code sent by email to the user to get
    66  access to the Cozy.
    67  
    68  ## OIDC variant
    69  
    70  When a user uses an OIDC provider, or FranceConnect, the flagship app will get
    71  a delegated code from the cloudery and will use it via the `POST /oidc/access_token`
    72  endpoint to get access to the Cozy.
    73  
    74  ## Manual certification
    75  
    76  When the certification from the Google and Apple stores has failed, the app
    77  will have to do a few more steps to have access to the Cozy:
    78  
    79  1. Opening an in-app browser on the authorize page of the stack
    80     `GET /auth/authorize?scope=*`
    81     (note: PKCE is mandatory for the flagship app)
    82  
    83  2. The stack sends a mail with a 6 digits code in that case. The email explains
    84     that this code can be used to certify the flagship app.
    85  
    86  3. The user can type this code on the authorize page and submit it. It makes
    87     a `POST /auth/clients/:client-id/flagship`.
    88  
    89  4. If successful, it redirects back to the same page
    90     (`GET /auth/authorize?scope=*`), but this time, the user has button to
    91     accept using the flagship app.
    92  
    93  5. The user accepts, it sends a request to `POST /auth/authorize`, and the
    94     flagship app can finish the OAuth danse and have a full access on the Cozy.
    95  
    96  ## Special routes
    97  
    98  Some routes of the stack are dedicated to the flagship app, like:
    99  
   100  - creating a session code with `POST /auth/session_code`
   101  - getting a konnector token with `POST /auth/tokens/konnectors/:slug`
   102  - getting the parameters to open a webapp with `GET /apps/:slug/open`
   103  
   104  And some routes accept a `session_code` to open a session in a webview or
   105  inAppBrowser, like:
   106  
   107  - serving the `index.html` of a webapp
   108  - starting the OAuth danse of a konnector (`/accounts/:slug/start`)
   109  - starting the reconnect BI flow (`/accounts/:slug/reconnect`).
   110  
   111  ## Notifications
   112  
   113  When a notification is sent via the push channel, the stack will first try to
   114  send it to the dedicated mobile app. If there are no dedicated apps with a push
   115  token, the stack will then try to send the notification to the flagship apps.
   116  If it fails again, the stack then fallbacks on email.
   117  
   118  If the notification is sent to the flagship app, the title is modified to
   119  preprend the application name. By default, the notification `slug` is used but,
   120  if present, the name is taken from the `appName` field of the additional
   121  parameters (`data`). It allows the user to have more context when reading the
   122  notification on their mobile. The `data.appName` field can also be used to
   123  completely remove the application name from the notification title if set to an
   124  empty string.