From 606824693d7b30638bc690a0266b48fcaf6af1f5 Mon Sep 17 00:00:00 2001 From: Louis CAD Date: Thu, 18 Dec 2025 17:23:31 +0100 Subject: [PATCH 1/4] docs(TwoFactorAuth): Add 2FA doc for integration in a new app --- TwoFactorAuth/README.md | 129 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 TwoFactorAuth/README.md diff --git a/TwoFactorAuth/README.md b/TwoFactorAuth/README.md new file mode 100644 index 000000000..6fd4f1af1 --- /dev/null +++ b/TwoFactorAuth/README.md @@ -0,0 +1,129 @@ +# 2 factor authentication + +## How to integrate into a new app (Part One, polling-only) + +This enables the feature, that tries to retrieve any ongoing login challenge when the app is brought to the foreground. +It does NOT include notifications support, which is an extra (Part Two). + +### 1. Add the dependencies + +Depend on these 2FA related libraries: + +```kotlin +implementation(project(":Core:TwoFactorAuth:Front")) +implementation(project(":Core:TwoFactorAuth:Back:WithUserDb")) +``` + +### 2. Define the TwoFactorAuthManager singleton + +#### A. With the user db dependency + +Example: + +```kotlin +/** + * Singleton for incoming 2FA (two factor authentication) challenges. + * + * Not a ViewModel because the state needs to be scoped for the entire app. + */ +val twoFactorAuthManager = TwoFactorAuthManager { userId -> AccountUtils.getHttpClient(userId) } +``` + +#### B. With NO dependency on the user db + +If you can't or don't want to depend on the user database dependency, you need to provide several more parameters. +Here's an example. + +```kotlin +val twoFactorAuthManager = TwoFactorAuthManager( + coroutineScope = coroutineScope, + userIds = someStorage.connectedUsers.map(mutableSetOf()) { users -> + users.map { it.id } + }.distinctUntilChanged(), + getAccountInfo = { + val info = getUserAccountInfoById(it) + ConnectionAttemptInfo.TargetAccount( + avatarUrl = info.avatar, + fullName = info.displayName, + initials = info.computeInitials(), + email = info.email, + id = it.toLong(), + ) + }, + getConnectedHttpClient = { userId -> getHttpClientForUser(userId) } +) +``` + +### 3. Add the overlay where needed + +For each Activity in the app (including login screen for multi-account apps): + +Add `TwoFactorAuthApprovalAutoManagedBottomSheet(twoFactorAuthManager)` at the root of the content. + +Example: + +```kotlin +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContent { + TwoFactorAuthApprovalAutoManagedBottomSheet(twoFactorAuthManager) // References the singleton declare just before. + Whatever() + } + } +} +``` + +If the Activity is NOT using Compose, or if you don't know (e.g. in a `BaseActivity` class), the `addComposableOverlay` +function was made just for that, just make sure it's called after `setContentView` or `setContent`. + +Example: + +```kotlin +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(whatever) + addComposableOverlay { TwoFactorAuthApprovalAutoManagedBottomSheet(twoFactorAuthManager) } + } +} +``` + +At this point, you can expect the feature to be working (albeit without notifications). + +## How to integrate into a new app (Part Two, notifications support) + +**⚠️⚠️ NOTE: ⚠️⚠️** + +Unless specified otherwise, the **code below is to be put into Google Play Services dedicated source sets**. + +For example, if the host app is published to F-Droid + the Google Play Store and has 2 product flavors named "fdroid" and "standard", where "standard" contains Google Play Services dependent code, by default, the code below should be located into `app-module/src/standard/kotlin`, where `app-module` is the target app or library module. + +### 1. Add the right dependency in the right configuration + +Add this dependency in the host app's Gradle build file: + +```kotlin +"standardImplementation"(project(":Core:Notifications:Registration")) +``` + +Here, "standard" matches the product flavor that includes Firebase/Google Play Services dependencies. + +### 2. Ensure notification token and topics will be synced + +First, create the `RegisterUserDeviceWorker` class (if it doesn't exist already). It needs to subclass `AbstractNotificationsRegistrationWorker`. + +You can find the Mail app example here: https://github.com/Infomaniak/android-kMail/blob/e272d5b5ff5f4b1eb1f11784537a3d624c063e80/app/src/standard/java/com/infomaniak/mail/firebase/RegisterUserDeviceWorker.kt + +Follow other changes from this PR in the Mail, or the kDrive app: +https://github.com/Infomaniak/android-kDrive/pull/1872/changes +https://github.com/Infomaniak/android-kMail/pull/2698/changes + +Here's the list of changes you need to add from the example PRs above: +- Ensure `TwoFactorAuthNotifications.channel()` is created/submitted to Android's NotificationManager. +- Ensure `NotificationsRegistrationManager` is added in `userDataCleanableList` at the beginning of the app process for the Play Services app variant. +- Ensure the user addition and removal functions to call `resetForUser` in elements registered `userDataCleanableList` (already done if added Cross-app login first). +- Ensure `NotificationsRegistrationManager.scheduleWorkerOnUpdate` is called in an app process wide coroutine, right from the app process start. +- Ensure the `Application` subclass is declared properly in the manifest for the Play Services dependent product flavor +- In the `FirebaseMessagingService` subclass (create it and declare it in the manifest if needed), make sure the `onNewToken` and `onMessageReceived` functions are implemented properly to forward the new tokens to `NotificationsRegistrationManager`, and matching notifications (the ones with `TwoFactorAuthNotifications.TYPE` in key `"type"`), forwarded to `twoFactorAuthManager.onApprovalChallengePushed(…)`. +- Ensure any other push notification topics are properly integrated for `RegisterUserDeviceWorker` and `NotificationsRegistrationManager.scheduleWorkerOnUpdate`. From ab09da5e4fe586f2b9e6f1a9e1c84fcb4e9b1897 Mon Sep 17 00:00:00 2001 From: Louis CAD Date: Thu, 13 Aug 2026 13:42:51 +0200 Subject: [PATCH 2/4] chore(TwoFactorAuth): Update the doc --- TwoFactorAuth/README.md | 58 +++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 16 deletions(-) diff --git a/TwoFactorAuth/README.md b/TwoFactorAuth/README.md index 6fd4f1af1..3f22d9002 100644 --- a/TwoFactorAuth/README.md +++ b/TwoFactorAuth/README.md @@ -1,4 +1,4 @@ -# 2 factor authentication +# 2-factor authentication ## How to integrate into a new app (Part One, polling-only) @@ -10,28 +10,38 @@ It does NOT include notifications support, which is an extra (Part Two). Depend on these 2FA related libraries: ```kotlin -implementation(project(":Core:TwoFactorAuth:Front")) -implementation(project(":Core:TwoFactorAuth:Back:WithUserDb")) +implementation(core.infomaniak.core.twofactorauth.back.withuserdb) +implementation(core.infomaniak.core.twofactorauth.front) ``` ### 2. Define the TwoFactorAuthManager singleton #### A. With the user db dependency -Example: +Example with top-level declaration: ```kotlin /** - * Singleton for incoming 2FA (two factor authentication) challenges. + * Singleton for incoming 2FA (two-factor authentication) challenges. * * Not a ViewModel because the state needs to be scoped for the entire app. */ val twoFactorAuthManager = TwoFactorAuthManager { userId -> AccountUtils.getHttpClient(userId) } ``` +Example with annotation based dependency injection: + +```kotlin +@Provides +@Singleton +fun provideTwoFactorAuthManager(accountUtils: AccountUtils): TwoFactorAuthManager { + return TwoFactorAuthManager { userId -> accountUtils.getHttpClient(userId) } +} +``` + #### B. With NO dependency on the user db -If you can't or don't want to depend on the user database dependency, you need to provide several more parameters. +If you can't or don't want to depend on the user database dependency, you need to provide several extra parameters. Here's an example. ```kotlin @@ -64,10 +74,17 @@ Example: ```kotlin class MainActivity : ComponentActivity() { + + @Inject + lateinit var twoFactorAuthManager: TwoFactorAuthManager // If using annotation based DI lib. + override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { - TwoFactorAuthApprovalAutoManagedBottomSheet(twoFactorAuthManager) // References the singleton declare just before. + TwoFactorAuthApprovalAutoManagedBottomSheet( + twoFactorAuthManager = twoFactorAuthManager, // References the member var, or the singleton. + isInDarkTheme = isSystemInDarkTheme() + ) Whatever() } } @@ -81,10 +98,19 @@ Example: ```kotlin class MainActivity : ComponentActivity() { + + @Inject + lateinit var twoFactorAuthManager: TwoFactorAuthManager // If using annotation based DI lib. + override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(whatever) - addComposableOverlay { TwoFactorAuthApprovalAutoManagedBottomSheet(twoFactorAuthManager) } + addComposableOverlay { + TwoFactorAuthApprovalAutoManagedBottomSheet( + twoFactorAuthManager = twoFactorAuthManager, // References the member var, or the singleton. + isInDarkTheme = isSystemInDarkTheme() + ) + } } } ``` @@ -104,7 +130,7 @@ For example, if the host app is published to F-Droid + the Google Play Store and Add this dependency in the host app's Gradle build file: ```kotlin -"standardImplementation"(project(":Core:Notifications:Registration")) +"standardImplementation"(core.infomaniak.core.notifications.registration) ``` Here, "standard" matches the product flavor that includes Firebase/Google Play Services dependencies. @@ -120,10 +146,10 @@ https://github.com/Infomaniak/android-kDrive/pull/1872/changes https://github.com/Infomaniak/android-kMail/pull/2698/changes Here's the list of changes you need to add from the example PRs above: -- Ensure `TwoFactorAuthNotifications.channel()` is created/submitted to Android's NotificationManager. -- Ensure `NotificationsRegistrationManager` is added in `userDataCleanableList` at the beginning of the app process for the Play Services app variant. -- Ensure the user addition and removal functions to call `resetForUser` in elements registered `userDataCleanableList` (already done if added Cross-app login first). -- Ensure `NotificationsRegistrationManager.scheduleWorkerOnUpdate` is called in an app process wide coroutine, right from the app process start. -- Ensure the `Application` subclass is declared properly in the manifest for the Play Services dependent product flavor -- In the `FirebaseMessagingService` subclass (create it and declare it in the manifest if needed), make sure the `onNewToken` and `onMessageReceived` functions are implemented properly to forward the new tokens to `NotificationsRegistrationManager`, and matching notifications (the ones with `TwoFactorAuthNotifications.TYPE` in key `"type"`), forwarded to `twoFactorAuthManager.onApprovalChallengePushed(…)`. -- Ensure any other push notification topics are properly integrated for `RegisterUserDeviceWorker` and `NotificationsRegistrationManager.scheduleWorkerOnUpdate`. +1. Ensure `TwoFactorAuthNotifications.channel()` is created/submitted to Android's NotificationManager. +2. Ensure `NotificationsRegistrationManager` is added in `userDataCleanableList` at the beginning of the app process for the Play Services app variant. +3. Ensure the user addition and removal functions to call `resetForUser` in elements registered `userDataCleanableList` (already done if added Cross-app login first). +4. Ensure `NotificationsRegistrationManager.scheduleWorkerOnUpdate` is called in an app process wide coroutine, right from the app process start. +5. Ensure the `Application` subclass is declared properly in the manifest for the Play Services dependent product flavor +6. In the `FirebaseMessagingService` subclass (create it and declare it in the manifest if needed), make sure the `onNewToken` and `onMessageReceived` functions are implemented properly to forward the new tokens to `NotificationsRegistrationManager`, and matching notifications (the ones with `TwoFactorAuthNotifications.TYPE` in key `"type"`), forwarded to `twoFactorAuthManager.onApprovalChallengePushed(…)`. +7. Ensure any other push notification topics are properly integrated for `RegisterUserDeviceWorker` and `NotificationsRegistrationManager.scheduleWorkerOnUpdate`. From 243247294c64c1e23ad22a491f9ddceb2b9397a8 Mon Sep 17 00:00:00 2001 From: Louis CAD Date: Thu, 13 Aug 2026 17:11:04 +0200 Subject: [PATCH 3/4] docs(TwoFactorAuth): Fix example snippet --- TwoFactorAuth/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TwoFactorAuth/README.md b/TwoFactorAuth/README.md index 3f22d9002..a5a638700 100644 --- a/TwoFactorAuth/README.md +++ b/TwoFactorAuth/README.md @@ -47,8 +47,8 @@ Here's an example. ```kotlin val twoFactorAuthManager = TwoFactorAuthManager( coroutineScope = coroutineScope, - userIds = someStorage.connectedUsers.map(mutableSetOf()) { users -> - users.map { it.id } + userIds = someStorage.connectedUsers.map { users -> + users.map(mutableSetOf()) { it.id } }.distinctUntilChanged(), getAccountInfo = { val info = getUserAccountInfoById(it) From 584c87d432ee63940bd8d338490ec937a2977cac Mon Sep 17 00:00:00 2001 From: Louis CAD Date: Thu, 13 Aug 2026 17:11:43 +0200 Subject: [PATCH 4/4] docs(TwoFactorAuth): Update doc to clarify no user db support --- TwoFactorAuth/README.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/TwoFactorAuth/README.md b/TwoFactorAuth/README.md index a5a638700..9096de72a 100644 --- a/TwoFactorAuth/README.md +++ b/TwoFactorAuth/README.md @@ -39,10 +39,30 @@ fun provideTwoFactorAuthManager(accountUtils: AccountUtils): TwoFactorAuthManage } ``` -#### B. With NO dependency on the user db +#### B. With NO dependency on the user db (not fully supported) -If you can't or don't want to depend on the user database dependency, you need to provide several extra parameters. -Here's an example. +If you can't or don't want to depend on the user database dependency, there is a way. + +**⚠️⚠️ NOTE: ⚠️⚠️** + +Currently, the notifications part doesn't work without the user db, because so far, all our apps are using the user db, +including apps that initially were not projected to do so. + +Technically, it is possible to make a user-db free version of the `notifications.registration` module, but it'll be +done only if needed by an app. + +##### How to + +1. Drop the `.withuserdb` in the dependency + +```kotlin +-implementation(core.infomaniak.core.twofactorauth.back.withuserdb) ++implementation(core.infomaniak.core.twofactorauth.back) +``` + +2. Provide the required extra parameters. + +Example: ```kotlin val twoFactorAuthManager = TwoFactorAuthManager(