Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

Eventos verificados

Os eventos enviados com uma chave de servidor, ou pelo seu próprio app Apple ou Android com prova do dispositivo, são marcados como verificados, para você distingui-los dos eventos que qualquer pessoa com a chave pública poderia ter enviado.

Uma chave de ingestão vai dentro do seu app ou da sua página web, então qualquer pessoa pode copiá-la e enviar eventos que parecem ser do seu app. O Lyrelog marca como verificados (verified) os eventos que ele consegue distinguir desses, de três formas:

  • eventos enviados com uma chave de servidor, um segredo que só os seus servidores têm,
  • eventos enviados pelo seu próprio app da Apple num dispositivo real, o que a Apple prova com App Attest, e
  • eventos enviados pelo seu próprio app Android num dispositivo real, o que o hardware seguro do dispositivo prova com Key Attestation.

O que "verificado" significa

Um evento verificado não pode ter sido enviado por alguém que copiou a chave pública de um app ou de uma página web. Com uma chave de servidor, ele veio com uma chave que só os servidores do projeto têm. Com o App Attest, ele veio do app legítimo do projeto, assinado pelo seu time, num dispositivo Apple legítimo. Com o Key Attestation, ele veio do app Android legítimo do projeto, assinado com o certificado do projeto, num dispositivo Android real com o sistema original e bloqueado.

Isso não prova que o que o evento diz é verdade. Um servidor pode enviar um valor errado, e alguém usando o app de verdade num dispositivo com jailbreak ainda pode fazê-lo enviar eventos. Um evento verificado só é tão confiável quanto o código que o enviou.

Os eventos enviados com a chave de ingestão pública e sem prova do app não são verificados: qualquer pessoa com essa chave poderia ter enviado eventos iguais a eles. É o caso da maioria dos eventos de páginas web e de apps que não usam App Attest nem Key Attestation, e isso é esperado.

Quem verifica

RemetenteChaveOs seus eventosverified_by
O seu servidorSend events from a server, lyr_srv_Verificadosserver
O seu app da Apple num iPhone, iPad ou Apple Watch real, configurado para App AttestSend events, lyr_ing_Verificadosapp_attest
O seu app Android num dispositivo real, configurado para Key AttestationSend events, lyr_ing_Verificadoskey_attestation
Qualquer outra coisa com a chave de ingestãoSend events, lyr_ing_Não verificadosvazio
Qualquer coisa com uma chave de acesso totalFull access, lyr_adm_Não verificadosvazio

O Lyrelog define isso em cada evento na ingestão, a partir da chave com que o lote veio e, no caso de uma chave de ingestão, do token de App Attest ou de Key Attestation que ele traz. Um cliente não pode defini-lo: uma linha que envia verified_by por conta própria é rejeitada com unknown fields: verified_by.

Uma chave de servidor só pode acrescentar eventos, como uma chave de ingestão; ela não consegue lê-los. Veja em Chaves como criar uma.

No painel

  • Na lista de eventos, um pequeno escudo ao lado do nome do evento marca um evento verificado.
  • Um evento aberto mostra um selo Verified no cabeçalho. Em Context, Sender diz Verified, server key, Verified, App Attest, Verified, Key Attestation ou Not verified, public key.
  • No explorer, o menu Filter tem um campo Verified by com os valores Server key, App Attest, Key Attestation e Not verified (na URL: server, app_attest, key_attestation e none). Escolha todos menos Not verified para ver só os eventos verificados, ou Not verified para ver o resto.

A API de leitura retorna verified_by em cada evento ("server", "app_attest", "key_attestation", ou "" quando não verificado) e filtra por ele com verified=server, verified=app_attest, verified=key_attestation ou verified=none, ou vários ao mesmo tempo (verified=server|app_attest|key_attestation).

Servidores

Um backend (Node, Python, Go, Java ou Kotlin na JVM, ou curl a partir de um servidor) deve enviar com uma chave de servidor, lyr_srv_...: os seus eventos são verificados e ele não tem limite diário por endereço. Passe ao SDK a chave de servidor onde os exemplos mostram lyr_ing_...; nada mais muda.

Guarde-a como qualquer segredo: no ambiente do seu servidor ou no seu cofre de segredos, nunca num app, numa página web ou num repositório. Se ela vazar, revogue-a e crie outra.

Apps da Apple (App Attest)

O App Attest da Apple permite que um app prove a um servidor que é o app legítimo, assinado pelo seu time, rodando num dispositivo Apple legítimo. O SDK do Swift faz isso por você, assim como os SDKs de React Native e de Flutter no iOS, por meio do SDK do Swift. O Lyrelog guarda os eventos de um app comprovado como verificados (verified_by é app_attest).

Configurar

  1. Encontre o App ID do seu app: o seu Team ID, um ponto e o bundle id, como ABCDE12345.com.example.app. O Team ID fica na sua conta Apple Developer, em Membership.
  2. No Lyrelog, abra Project settings. A seção Verified events from your Apple apps aparece quando o projeto tem a plataforma de app iOS. Adicione o App ID com Add. Um proprietário pode adicionar até 10, um por app (um app de iPhone e o seu app de relógio têm bundle ids diferentes).
  3. No Xcode, adicione a capability App Attest ao target do app (Signing & Capabilities). Ela é o entitlement com.apple.developer.devicecheck.appattest-environment. Defina-o como production para builds da App Store e do TestFlight. Sem isso, a Apple usa o ambiente de desenvolvimento dela, que também verifica.
  4. Use o SDK do Swift. A opção appAttest dele é true por padrão, então não há mais nada a programar. O mesmo vale para React Native e Flutter (a opção deles é attest): as configurações do projeto são as mesmas, já que o SDK do Swift por baixo faz o trabalho.

Para desligar, remova os App IDs (os eventos chegam não verificados, como antes) ou defina appAttest: false no app.

Como funciona

  • Uma vez por instalação, o SDK cria uma chave no Secure Enclave do dispositivo e a Apple a atesta a partir de um desafio de uso único do Lyrelog. O Lyrelog confere a cadeia de certificados da Apple e se o app é um dos App IDs do projeto, e guarda a metade pública da chave: uma por instalação, apagada depois de 180 dias sem uso.
  • O SDK então recebe um token, válido por um dia, e o envia com cada lote. Ele renova o token com uma assinatura feita com essa chave (uma assertion), cujo contador não pode ser reaproveitado.
  • O envio nunca espera por isso. Enquanto o app não tem um token, e sempre que algo falha, os eventos são enviados e guardados como não verificados. Um lote nunca é recusado por causa do App Attest.

Onde não se aplica

O App Attest funciona em iPhones, iPads e Apple Watches reais. Estes enviam eventos não verificados, mesmo com tudo configurado:

  • Macs (a Apple não oferece App Attest neles),
  • o simulador,
  • a maioria das extensões de app,
  • dispositivos que não têm suporte a App Attest.

As rotas e o header estão na API HTTP.

Aceitar só eventos verificados do app iOS

Desligado por padrão. Na mesma seção das configurações, Accept only verified events from the iOS app faz o Lyrelog segurar todo lote não verificado cujos eventos dizem platform: ios: ele responde 425 Too Early, e o SDK guarda o lote e o envia de novo mais tarde. Os primeiros eventos de uma instalação nova esperam alguns segundos pelo token e depois chegam verificados, então nada se perde aí.

Ligue só quando todo mundo tiver uma versão do app com App Attest configurado. Até lá, os eventos de versões antigas, do simulador e de um app de iPad rodando num Mac nunca conseguem se provar: eles esperam no dispositivo, até o limite do que o SDK guarda (20 MB e 7 dias), e nunca são armazenados. Os eventos de outras plataformas, e os de uma chave de servidor, são aceitos como antes.

Apps Android (Key Attestation)

O Key Attestation do Android permite que um app crie uma chave dentro do hardware seguro do celular (o seu ambiente de execução confiável, ou um chip StrongBox) e receba do dispositivo uma cadeia de certificados, assinada até chegar ao Google, que descreve a chave, o app e o estado do celular. O próprio Lyrelog confere essa cadeia: não é preciso conta do Google, Play Integrity nem projeto no Google Cloud. O SDK do Android faz isso por você, assim como os SDKs de React Native e de Flutter no Android, por meio do SDK do Android. O Lyrelog guarda os eventos de um app comprovado como verificados (verified_by é key_attestation).

Configurar

  1. Encontre o pacote do seu app (o application id, como com.example.app) e a impressão digital SHA-256 do certificado com que ele é assinado:
    • Para builds instaladas pelo Google Play, é o Google que assina o app: no Play Console, abra o app, depois Test and release, App integrity, e copie o SHA-256 do App signing key certificate.
    • Para builds que você mesmo assina (uma chave de upload, ou a chave de debug em desenvolvimento), rode ./gradlew signingReport e copie o SHA-256 dessa variante.
  2. No Lyrelog, abra Project settings. A seção Verified events from your Android apps aparece quando o projeto tem a plataforma de app Android. Adicione o pacote e a impressão digital com Add; adicione o mesmo pacote de novo com outra impressão digital para cada certificado que assina builds que enviam eventos (até 5 por pacote, 10 pacotes).
  3. Use o SDK do Android. A opção attest dele é true por padrão, então não há mais nada a programar. O mesmo vale para React Native e Flutter: as configurações do projeto são as mesmas, já que o SDK do Android por baixo faz o trabalho. Num projeto React Native ou Flutter, ./gradlew signingReport roda na pasta android do app.

Para desligar, remova os pacotes (os eventos chegam não verificados, como antes) ou defina attest = false no app.

O que é conferido

  • A cadeia é assinada, certificado por certificado, até uma das raízes de atestação do Google, e nenhum dos seus certificados está na lista de revogados do Google.
  • A chave fica no hardware seguro do celular, foi criada lá e responde a um desafio de uso único do Lyrelog.
  • O celular iniciou com o sistema original e verificado, e o bootloader está bloqueado.
  • O app é um dos pacotes do projeto, assinado com um dos seus certificados.

O Lyrelog então guarda a metade pública da chave (uma por instalação, apagada depois de 180 dias sem uso) e dá ao app um token, válido por um dia, que ele envia com cada lote. Ele renova o token assinando um novo desafio de uso único com essa chave. O envio nunca espera por isso: enquanto o app não tem um token, e sempre que algo falha, os eventos são enviados e guardados como não verificados. Um lote nunca é recusado por causa do Key Attestation.

Onde não se aplica

Estes enviam eventos não verificados, mesmo com tudo configurado:

  • emuladores (não têm hardware seguro, e as cadeias deles não levam ao Google),
  • celulares com root, com o bootloader desbloqueado ou com um sistema customizado,
  • celulares sem chaves protegidas por hardware (raro desde o Android 8),
  • builds assinadas com um certificado que o projeto não lista.

As rotas estão na API HTTP.

Aceitar só eventos verificados do app Android

Desligado por padrão, e funciona como o do iOS: com ele ligado, todo lote não verificado cujos eventos dizem platform: android recebe 425 Too Early e espera no dispositivo. Ligue só quando todo mundo tiver uma versão com Key Attestation: os eventos de versões antigas, de emuladores e de celulares com root ou desbloqueados nunca conseguem se provar e nunca são armazenados.

Páginas web, pelo seu próprio servidor

Uma página web não pode guardar uma chave de servidor: tudo o que está no navegador pode ser lido. Para ter eventos verificados de uma página, repasse-os pelo seu próprio backend. A página envia para uma rota do seu site, e a rota encaminha o lote para o Lyrelog com a chave de servidor.

É importante deixar claro o que isso prova. Esses eventos são verificados só no sentido de que passaram pelo seu servidor. Qualquer um pode fazer um POST numa rota do seu site, então o relay deve aceitar eventos só das suas próprias sessões autenticadas, e limitar o que uma sessão envia. Um relay que aceita qualquer coisa de qualquer um não verifica nada.

Na página, aponte o endpoint do SDK de JavaScript para o relay. Ele é uma URL base: o SDK faz POST em <endpoint>/v1/events:batch. apiKey não pode ficar vazio, mas o relay o substitui, então qualquer valor provisório serve:

export const log = Lyrelog.init({
  endpoint: "https://example.com/api/lyrelog", // posts to /api/lyrelog/v1/events:batch
  apiKey: "relay", // replaced by the server key on your server
});

O relay, como um route handler do Next.js (app/api/lyrelog/[...path]/route.ts):

import { getSession } from "@/lib/auth"; // your own sign-in

export async function POST(request: Request) {
  const session = await getSession(request);
  if (!session) return new Response(null, { status: 401 });

  const encoding = request.headers.get("Content-Encoding");
  const upstream = await fetch("https://ingest.lyrelog.com/v1/events:batch", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LYRELOG_SERVER_KEY}`, // lyr_srv_..., server only
      "Content-Type": request.headers.get("Content-Type") ?? "application/x-ndjson",
      ...(encoding ? { "Content-Encoding": encoding } : {}),
    },
    body: await request.arrayBuffer(),
  });

  const headers = new Headers({ "Content-Type": "application/json" });
  const retryAfter = upstream.headers.get("Retry-After");
  if (retryAfter) headers.set("Retry-After", retryAfter);
  return new Response(await upstream.text(), { status: upstream.status, headers });
}

Bom saber:

  • Devolva o status e o Retry-After sem alterá-los: é com base neles que o SDK decide se tenta de novo ou descarta um lote.
  • Um 401 ou 403 faz o SDK parar de enviar até a página recarregar. Inicie o cliente depois que o visitante entrar, não antes.
  • O país vem do endereço que envia o lote ao Lyrelog, que agora é o do seu servidor. Os eventos repassados trazem o país do seu servidor, não o do visitante.
  • Adicione o endereço do relay ao connect-src da sua Content Security Policy, se você usa uma ('self' cobre uma rota no mesmo site).

Outros apps e páginas web

Os eventos de apps da Apple sem App Attest, de apps Android sem Key Attestation e de páginas web que enviam diretamente usam a chave de ingestão pública sem prova do app, então não são verificados. Uma página web pode ter eventos verificados pelo seu próprio servidor. Dois limites impedem que uma chave copiada cause muito estrago:

  • os eventos mensais do plano, para a organização inteira, e
  • a cota diária de um endereço, abaixo.

A cota diária de um endereço

Com uma chave pública (uma chave de ingestão ou uma chave de acesso total), um endereço remetente pode enviar no máximo 1/50 dos eventos mensais do plano num dia UTC, somando os projetos da organização. Endereços IPv6 contam por /64. Só contam os eventos que não são verificados.

PlanoEventos por dia de um endereço
Free20.000
Pro200.000
Business4.000.000
UnlimitedSem limite

Isso é muito mais do que um dispositivo envia. O limite existe para que uma chave copiada de um app não consiga gastar o mês da organização a partir de uma só máquina. Os eventos verificados (de uma chave de servidor, do App Attest ou do Key Attestation) não contam para ele.

Passado esse limite, o endereço recebe 429 com um Retry-After de no máximo uma hora, até o dia UTC seguinte. Os outros endereços continuam enviando. Os SDKs tentam de novo como em qualquer 429, mantendo os eventos dentro dos limites da fila. O corpo está na API HTTP.

Se um dos seus servidores chegar a esse limite, ele deveria estar usando uma chave de servidor.