Support storing Thread credentials from Thread configuration panel

[agners]

Summary

Handle the thread/store_in_platform_keychain external bus message, the inverse of the existing Phone → HA Thread credential import (#6951): the frontend Thread panel's "Send credentials to phone" button sends the active operational dataset to the app, which stores it in the device's Thread credential storage via Google Play Services. (The bus message name follows the frontend/iOS naming, where the credentials land in the Apple Keychain.)

• ThreadManager gains the HA → Phone primitives: parsing the network name from the TLV (to label dialogs before any storage mutation), predicting whether the credential will become the device's preferred one, and adding the credential while tracking its border agent ID per server so orphan cleanup keeps working.
• canTransferThreadCredentialsToKeychain is reported in the config response (same gate as the import direction) so the frontend only surfaces the button on supported devices.
• FrontendMatterThreadHandler drives the flow with a progress dialog over the Play Services round-trips, a confirmation step before the write, and a result dialog afterwards. Because Play Services offers no way to remove "preferred" status once set, the user is warned up front when adding would demote another credential, and the result dialogs are explicit about whether the credential actually became preferred. The preflight texts only claim what the app can actually observe — Play Services hides credentials owned by other apps, so the "will likely become preferred" case is hedged accordingly.
• The Confirm and Information frontend dialogs support an optional "Learn more" link; all dialogs of this flow link to the companion documentation (a new Thread page explaining Android's preferred-network behavior, added via the documentation PR below).
• The shared Matter/Thread progress dialog now uses a neutral "Working…" label instead of reusing the Developer Settings "Syncing…" string, since it covers commissioning, import, and this new flow.

Relationship to the existing credential sync

The app has an older, automatic bidirectional reconciliation in Settings > Companion app > Troubleshooting > Sync Thread credentials (ThreadManager.syncPreferredDataset): it imports the server dataset when the device has none, offers exporting the device's preferred dataset when the server has none, and reconciles/cleans up stale app-added datasets when both sides have one. Its silent decision-making has been a recurring source of confusion (see #4146: sync reports success while the device keeps preferring a stale network).

The frontend-driven flows replace that model with two explicit, user-initiated directions: Phone → HA (#6951, one-way exportPreferredDataset) and HA → Phone (this PR), each with its own consent/preflight messaging. This PR reuses the sync's building blocks where they fit — the orphaned-credential cleanup now also runs on the HA → Phone add path, and the per-server border-agent tracking list is shared.

The Troubleshooting sync is deliberately left untouched here. Once both explicit directions have shipped (app and frontend), a follow-up can remove it together with syncPreferredDataset and its reconciliation-only result variants, leaving the two explicit primitives as the only credential paths.

Checklist

• New or updated tests have been added to cover the changes following the testing guidelines.
• The code follows the project's code style and best_practices.
• The changes have been thoroughly tested, and edge cases have been considered.
• Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.

Link to pull request in documentation repositories

User Documentation: home-assistant/companion.home-assistant#

Any other notes

No frontend changes are needed: the "Send credentials to phone" button already exists — added for iOS in home-assistant/frontend#20743 and moved to the main Thread configuration panel in home-assistant/frontend#21066 — and is shown once the app reports canTransferThreadCredentialsToKeychain. This PR implements the Android side of that existing external bus message.

The feature only works on the full flavor (Google Play Services Thread network client); on other builds the flow reports that Thread credential management isn't supported.

[agners]

A few screenshots showing the flow when adding the credentials via the new button.

[Copilot]

Pull request overview

Implements the Android side of the frontend Thread panel’s “Send credentials to phone” action by handling the thread/store_in_platform_keychain external bus message, running a preflight/confirmation flow, and storing the received operational dataset into the device’s Thread credential storage (Play Services on full flavor).

Changes:

• Added a new HA → Phone Thread credential store flow in FrontendMatterThreadHandler, including preflight outcome messaging, progress dialog usage, and result dialogs.
• Extended external bus message models and config response (canTransferThreadCredentialsToKeychain) to support the frontend’s capability gating.
• Enhanced frontend dialogs (Confirm/Information) with an optional “Learn more” link and added Robolectric/Compose test coverage.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
common/src/main/res/values/strings.xml	Adds new user-facing strings for the Thread store flow and a neutral “Working…” label for shared progress UI.
app/src/main/res/xml/changelog_master.xml	Changelog entry for the new Thread credential store capability.
app/src/main/kotlin/io/homeassistant/companion/android/thread/ThreadManager.kt	Adds Thread store-related APIs and models (preflight outcome, TLV network name parsing, add-to-device).
app/src/full/kotlin/io/homeassistant/companion/android/thread/ThreadManagerImpl.kt	Implements TLV parsing, preferred-outcome prediction, and credential add + per-server BA tracking in full flavor.
app/src/minimal/kotlin/io/homeassistant/companion/android/thread/ThreadManagerImpl.kt	Stubs the new ThreadManager APIs for minimal flavor (unsupported).
app/src/main/kotlin/io/homeassistant/companion/android/frontend/matterthread/FrontendMatterThreadHandler.kt	Drives the HA → Phone store flow with progress + confirm/info dialogs, and ties it into in-flight flow coordination.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/matterthread/ui/MatterThreadDialogs.kt	Updates progress dialog label to use the new “Working…” string.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt	Decodes thread/store_in_platform_keychain payload TLV hex and maps it to a new handler event.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendHandlerEvent.kt	Adds a new event type for storing Thread credentials on-device with proper equals/hash for ByteArray.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendViewModel.kt	Dispatches the new store event to FrontendMatterThreadHandler.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/externalbus/outgoing/OutgoingExternalBusMessage.kt	Adds canTransferThreadCredentialsToKeychain to config results (same gate as import).
app/src/main/kotlin/io/homeassistant/companion/android/frontend/externalbus/incoming/IncomingExternalBusMessage.kt	Adds the ThreadStoreInPlatformKeychainMessage + payload model and KDoc.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/dialog/FrontendDialog.kt	Extends Confirm and Information dialog models with an optional moreInfoUrl.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/dialog/FrontendDialogManager.kt	Adds optional moreInfoUrl plumbing for confirm/information dialogs.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/dialog/SimpleConfirmDialog.kt	Renders a “Learn more” action in confirm dialogs when a URL is provided.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/dialog/InformationDialog.kt	Renders a “Learn more” action in information dialogs and adds a reusable MoreInfoButton.
app/src/test/kotlin/io/homeassistant/companion/android/frontend/matterthread/FrontendMatterThreadHandlerTest.kt	Updates handler test wiring for the new injected application context.
app/src/test/kotlin/io/homeassistant/companion/android/frontend/externalbus/outgoing/OutgoingExternalBusMessageTest.kt	Updates expected config JSON to include canTransferThreadCredentialsToKeychain.
app/src/test/kotlin/io/homeassistant/companion/android/frontend/dialog/SimpleConfirmDialogTest.kt	Adds tests for presence/behavior of “Learn more” in confirm dialogs.
app/src/test/kotlin/io/homeassistant/companion/android/frontend/dialog/InformationDialogTest.kt	New tests for information dialog UI and “Learn more” behavior.

Suppressed comments (2)

app/src/main/kotlin/io/homeassistant/companion/android/frontend/matterthread/FrontendMatterThreadHandler.kt:251

• The invalid-payload information dialog in this flow doesn’t include the documentation link, but the PR description states all dialogs in this HA → Phone store flow should offer “Learn more”. Consider passing moreInfoUrl here as well so the user can understand what happened and how Thread credential preference works.

            if (networkName == null) {
                dialogManager.showInformation(
                    applicationContext.getString(commonR.string.thread_store_invalid_payload),
                )
                return

app/src/main/kotlin/io/homeassistant/companion/android/frontend/matterthread/FrontendMatterThreadHandler.kt:308

• thread_store_failed includes an error-detail placeholder, but this code passes an empty string when e.message is null/blank, producing a user-facing message that ends with a dangling “: ”. Consider falling back to thread_store_failed_unknown (or another non-detailed string) when there’s no usable detail.

            } catch (e: Exception) {
                Timber.w(e, "Thread store: failed to add credential '%s'", networkName)
                applicationContext.getString(commonR.string.thread_store_failed, networkName, e.message ?: "")
            }