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.