Ir para o conteúdo

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

  1. 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). Sem ACCEPTED, 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.
  2. 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 por FederatedMqttService.onSensorMessage. Esse buffer de prévia fica somente em memória e não alimenta o SQLite nem o treinamento.
  3. Orquestração multiexperimento — FederatedClientOrchestrator, no módulo federated-client, recebe os filtros MQTT de configuração e finalização de todos os experimentos. Cada par experimento/versão recebe seu próprio RoundLifecycle; 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.
  4. Término, treino e submissão — .../finalization válido encerra a coleta daquela rodada. FederatedMdplOrchestrator prepara o engine por experimento/versão, obtém e valida o .hdtclient.zip com assinatura Ed25519 e hash, e registra o plugin no runtime MDPL. O treinamento é despachado pela capacidade executeFederatedTraining da interface OnDataArrivalInference; 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, RoundLifecycle envia local_update.bin, metrics.json e data_profile.json via HTTP(S) REST (RestRoundArtifactGateway → POST /api/experiments/{id}/rounds/{roundId}/clients/{clientId}/artifacts) e publica apenas a referência assinada (ClientUpdateMessage com 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

  • MainActivity agora 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 FederatedMqttService inicia a coleta, os nomes retornados por CDDL.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 SpongyCastle core/prov/pkix. O teste CddlRuntimeDependenciesTest protege as classes e a assinatura pública de MqttEncoder exigidas em runtime.
  • ConsentActivity foi 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 array consents. A ação exibida é exclusiva: Aceitar termos quando não há aceite remoto ou Revogar quando o monitor confirma ACCEPTED (também aceita o legado EXPCEPTED). A tela de termos aguarda o POST de 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, TwinArtifactChannel publica ClientArtifactPayload pelo 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 EncryptedSharedPreferences e sincronizado sincronamente via RestConsentSyncClient (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:

./gradlew :app:assembleDebug
./gradlew :app:compileDebugJavaWithJavac

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.