federated-android-client — Cliente Federado Android (BL-092)¶
Aplicação Android que atua como cliente federado HDT-AF em um dispositivo móvel real: coleta dados, retém localmente até a solicitação de treinamento, treina o modelo no dispositivo e submete apenas os pesos — com consentimento LGPD obrigatório e comunicação segura (TLS/mTLS + envelopes HMAC).
Arquitetura¶
federated-android-client/
├── core/ ← montagem Gradle Java pura; fontes portáveis do ciclo federado em federated-client
└── app/ ← camada Android
├── net/ FederatedMqttService + transportes MQTT/REST e composição da plataforma
├── storage/ SqliteObservationStore, PrefsConsentStore (EncryptedSharedPreferences)
├── config/ ClientConfig (segredos cifrados em repouso, AES-256-GCM)
└── ui/ MainActivity, ConsentActivity, ExperimentDetailActivity, CollectedDataActivity, ExperimentMonitorActivity
Além do FederatedMqttService, a camada Android mantém um segundo serviço em primeiro plano (FederatedMdplInferenceEngineService, oriundo de modules/federated-client/src/android/java) dedicado à execução local do runtime MDPL/DEX.
Processo de inferência centralizado: consentimento, observações, montagem do conjunto de treino,
RoundLifecycle, engines Java/MDPL e contratos de pacote são mantidos em
modules/federated-client/src/main/java/br/ufma/lsdi/fedandroid/core. O build Gradle de :core
compila diretamente esses fontes (além de federated-common, federated-experiment-sdk e classes do federated-experiment-packager via srcDirs +=), sem depender de JARs pré-compilados por Maven. A ligação Android a MDPL (OnDataArrivalInference, CDDL e carregamento DEX) fica em
modules/federated-client/src/android/java, incluída por :app; assim, a compilação Maven do
módulo não incorpora dependências Android.
Compatibilidade de wire garantida por construção: :core compila diretamente os tipos reais do federated-common (MqttEnvelope, MqttTopics, ClientUpdateMessage, HmacSignatureService, VectorCodec, Hashing) — nenhuma classe de protocolo foi duplicada. O teste RoundLifecycleTest prova o ciclo completo contra essas classes.
Fluxo do cliente no dispositivo¶
- Consentimento por contrato (
ConsentActivity) — o titular vê os termos de cada experimento/versão e decide; o sha256 do texto exibido fica registrado (Art. 8 §4). SemACCEPTED, aquele experimento não recebe dados nem treina. Revogar remove seus dados e encerra somente sua rodada; a captura compartilhada continua para outros experimentos consentidos. - Prévia CDDL — após existir ao menos um experimento com consentimento ativo (
!consentedExperiments().isEmpty()), o CDDL/CDAL exibe sensores ativos e até 150 leituras recentes na tela Dados CDDL (CollectedDataActivity), mesmo fora de uma rodada ativa. Leituras recebidas antes de qualquer consentimento são descartadas porFederatedMqttService.onSensorMessage. Esse buffer de prévia fica somente em memória e não alimenta o SQLite nem o treinamento. - Orquestração multiexperimento —
FederatedClientOrchestrator, no módulofederated-client, recebe os filtros MQTT de configuração e finalização de todos os experimentos. Cada par experimento/versão recebe seu próprioRoundLifecycle; somente rodadas com consentimento válido entram na coleta. Sensores CDDL e a conexão MQTT são compartilhados, mas cada observação é gravada no espaço SQLite do par experimento/versão correspondente. - Término, treino e submissão —
.../finalizationválido encerra a coleta daquela rodada.FederatedMdplOrchestratorprepara o engine por experimento/versão, obtém e valida o.hdtclient.zipcom assinatura Ed25519 e hash, e registra o plugin no runtime MDPL. O treinamento é despachado pela capacidadeexecuteFederatedTrainingda interfaceOnDataArrivalInference; pedido e resultado passam por tópicos CDDL locais. Dados de treino permanecem no dispositivo. Sem pacote publicado, o orquestrador usa o treinador Java embutido; pacote inválido interrompe a preparação. Em ambos os casos,RoundLifecycleenvialocal_update.bin,metrics.jsonedata_profile.jsonvia HTTP(S) REST (RestRoundArtifactGateway→POST /api/experiments/{id}/rounds/{roundId}/clients/{clientId}/artifacts) e publica apenas a referência assinada (ClientUpdateMessagecom URI/hash) no tópico MQTT client-facing.
Pacote MDPL independente¶
O .hdtclient.zip é separado do pacote do experimento/servidor e do APK. Ele contém o DEX
do algoritmo, descritor, checksums e assinatura Ed25519. A chave privada deve ficar apenas
no ambiente de empacotamento; o app confia na chave pública configurada no build:
CLIENT_PACKAGE_TRUSTED_PUBLIC_KEY='PUBLIC_KEY_BASE64' \
CLIENT_PACKAGE_TRUSTED_KEY_ID='release-1' \
bash gradlew :app:assembleDebug
O processo de distribuição registra o pacote por experimento e versão. O Android não carrega
JARs recebidos: FederatedMdplOrchestrator delega a validação do pacote ao MdplClientPackageManager
antes de resolver a classe plugin e executa apenas a interface de treinamento compatível com a
capacidade federada do OnArrivalPhenotypeInferenceEngine pré-instalado. Para compilar
o plugin do cliente, o build composto espera o checkout hdt-mobile-apps no caminho relativo
configurado em settings.gradle. O script independente produz e, opcionalmente, publica o ZIP:
CLIENT_PACKAGE_SIGNING_KEY=/caminho-seguro/release-key.pem \
CLIENT_PACKAGE_SIGNING_KEY_ID=release-1 \
sh ../../scripts/package-federated-client.sh exp-mdpl-001 1.0.0 \
federated_mlp_classifier 1 br.ufma.lsdi.fedandroid.plugin.MlpTrainingPlugin \
path/to/classes.dex --submit
O mesmo key-id e a chave pública correspondente devem ser configurados no servidor
(HDT_AF_CLIENT_PACKAGE_TRUSTED_KEY_ID / HDT_AF_CLIENT_PACKAGE_TRUSTED_PUBLIC_KEY) e no
build do APK (CLIENT_PACKAGE_TRUSTED_KEY_ID / CLIENT_PACKAGE_TRUSTED_PUBLIC_KEY). A chave
privada não deve ser colocada no repositório nem no APK.
Experiência de uso¶
MainActivityagora usa um dashboard Material 3 com app bar, card de prontidão, blocos dedicados para status operacional, nomes dos sensores ativos no CDDL, catálogo de experimentos e ações rápidas.- Depois que
FederatedMqttServiceinicia a coleta, os nomes retornados porCDDL.getInternalSensorList()são persistidos e exibidos como sensores ativos; a lista é removida quando a captura falha ou é encerrada. - Falhas na inicialização do CDDL ou no processamento de uma leitura acionam um alerta Material no dashboard. A mensagem não expõe detalhes técnicos ou dados brutos; a causa completa fica apenas no log do aplicativo.
- As dependências transitivas dos AARs são declaradas explicitamente: Netty
5.0.0.Alpha2(a versão usada pelo microbroker de referência) e SpongyCastlecore/prov/pkix. O testeCddlRuntimeDependenciesTestprotege as classes e a assinatura pública deMqttEncoderexigidas em runtime. ConsentActivityfoi redesenhada como fluxo de revisão dos termos, com destaque visual para o impacto do aceite e CTA primário/secundário mais claros.- Ao abrir ou retornar aos detalhes de um experimento, o app consulta
GET /api/experiments/{id}?version={version}e localiza o UUID anônimo atual no arrayconsents. A ação exibida é exclusiva: Aceitar termos quando não há aceite remoto ou Revogar quando o monitor confirmaACCEPTED(também aceita o legadoEXPCEPTED). A tela de termos aguarda oPOSTde sincronização terminar antes de voltar à tela anterior. - A lógica do estado visual "pronto" vs. "aguardando consentimento" foi mantida em
:core(ClientOverviewFormatter) para continuar testável fora do Android SDK.
Segurança¶
| Camada | Mecanismo |
|---|---|
| Transporte | MQTT 5 sobre TLS 1.2+ (ssl://…:8883); pinning de CA via filesDir/ca.pem; mTLS via filesDir/client.p12 |
| Mensagens | Envelope HMAC-SHA256 (MqttEnvelope.signed) + hash de payload (verifyPayloadIntegrity) |
| Repouso | Segredos e consentimento em EncryptedSharedPreferences (AES-256-GCM, chave no Android Keystore); observações em SQLite privado do app |
| Pacote cliente | .hdtclient.zip validado por Ed25519 com chave pública pinada no APK, além de checksums e vínculo ao contrato |
| Dados | Observações brutas e o dataset de treino permanecem no dispositivo; a participação pode publicar o update do modelo, métricas/perfil permitido pelo contrato e mensagens de controle |
O microbroker local usa TLS quando o certificado de cliente CDDL foi provisionado. Na
variante debug, se esse certificado ainda não existir, o app faz fallback explícito para
o microbroker local sem TLS apenas para permitir desenvolvimento no emulador. A variante
release recusa esse fallback e exige o certificado; o MQTT federado externo permanece
configurado com TLS/mTLS em ambas as variantes.
Build e testes¶
# Testes JVM do core (sem SDK Android):
./gradlew :core:test
# Verifica as dependências exigidas pelos AARs CDDL/CDAL/microbroker:
./gradlew :app:testDebugUnitTest
# Exercita coordenação multiexperimento e os engines MDPL:
./gradlew :core:test :client-engine-plugin:test
# APK de debug (exige Android SDK; ver local.properties):
./gradlew :app:assembleDebug
# → app/build/outputs/apk/debug/app-debug.apk
# Compila, instala e abre no emulador (inicia o primeiro AVD se necessario):
sh ../../scripts/run-android-emulator.sh
# Ou selecione explicitamente o AVD:
sh ../../scripts/run-android-emulator.sh --avd HDTAF_API32_Simple
Nota: o sh scripts/compile.sh na raiz compila o reator Maven Java 25, enquanto o :core do Android compila diretamente os fontes Java compartilhados sob :core (sem depender do JAR gerado pelo Maven).
Configuração¶
Padrões em ClientConfig (todos sobrescrevíveis via preferências cifradas, exceto a
identidade): client_id é sempre o UUID v4 anônimo gerado uma única vez para a instalação,
experiment_id=exp-mnist-digits-001, contract_version=1.0.0,
broker_uri=ssl://192.168.10.198:8883, feature_codes=pixel_0..pixel_783,
target_property=label, sensor_names= (vazio = todos os sensores internos do
CDDL), sensor_bucket_millis=1000, sensor_measurement_interval_millis=1000.
O mesmo UUID anônimo é usado nos tópicos MQTT, consentimentos REST e artefatos da rodada; o endereço IP mostrado é um valor padrão de desenvolvimento e deve ser configurado para cada ambiente.
Segredos seguem a convenção das sessões (mnist-client-{id}-secret /
orchestrator-secret); em produção, o agregador deve registrar a credencial HMAC para
esse mesmo UUID antes de aceitar o update assinado.
Limitações conhecidas (registradas no BL-092)¶
- O valor padrão de
broker_uriéssl://192.168.10.198:8883; ajuste-o para o endpoint MQTT 5 TLS provisionado no ambiente.tcp://deve ficar restrito a desenvolvimento/testes locais. - Os bytes de artefato do cliente são enviados pelo
ClientArtifactChannel; no fluxo do gêmeo digital,TwinArtifactChannelpublicaClientArtifactPayloadpelo microbroker local para ingestão no lado servidor. Não trate o URI local do artefato como um caminho de filesystem compartilhado entre processos. - Consentimento é registrado localmente em
EncryptedSharedPreferencese sincronizado sincronamente viaRestConsentSyncClient(POST /api/experiments/{id}/clients/{uuid}) quando o monitor está acessível; se o monitor estiver indisponível, o estado local é mantido e a re-sincronização ocorre posteriormente. - A API de registro anônimo não provisiona ainda uma credencial HMAC no agregador. Para treinamento MQTT real, a infraestrutura deve cadastrar o UUID gerado pelo aplicativo com o segredo correspondente antes da rodada.
Integração do repositório com a arquitetura¶
Este é um build Gradle independente, distribuído em :core, :app e :client-engine-plugin; não é um módulo Maven do reactor. :core reutiliza fontes portáveis de modules/federated-client e os tipos MQTT reais de modules/federated-common. A camada Android conecta sensores e armazenamento local ao ciclo comum do cliente. O serviço administrativo publica contratos/pacotes e acompanha o estado, enquanto o dispositivo usa MQTT para receber configuração/finalização e enviar updates assinados. A agregação ocorre no servidor depois que o federated-orchestrator recebe e encaminha os updates.
O build composto resolve br.ufma.lsdi:mdpl a partir do checkout hdt-mobile-apps declarado em settings.gradle; os testes do MDPL devem ser executados dentro daquele build independente. O app requer Android SDK e o JDK aceito pelo wrapper Gradle. Para compilar o aplicativo:
O APK contém apenas chaves públicas de confiança para validar pacotes. Chaves privadas de assinatura permanecem no ambiente de release e nunca devem ser armazenadas neste repositório. Consulte ../../docs/components/06-federated-client.md para o contrato servidor-cliente e ../../docs/modules.md para a visão do workspace.