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
| Remetente | Chave | Os seus eventos | verified_by |
|---|---|---|---|
| O seu servidor | Send events from a server, lyr_srv_ | Verificados | server |
| O seu app da Apple num iPhone, iPad ou Apple Watch real, configurado para App Attest | Send events, lyr_ing_ | Verificados | app_attest |
| O seu app Android num dispositivo real, configurado para Key Attestation | Send events, lyr_ing_ | Verificados | key_attestation |
| Qualquer outra coisa com a chave de ingestão | Send events, lyr_ing_ | Não verificados | vazio |
| Qualquer coisa com uma chave de acesso total | Full access, lyr_adm_ | Não verificados | vazio |
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_attestationenone). 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
- 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. - 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).
- No Xcode, adicione a capability App Attest ao target do app (Signing & Capabilities). Ela
é o entitlement
com.apple.developer.devicecheck.appattest-environment. Defina-o comoproductionpara builds da App Store e do TestFlight. Sem isso, a Apple usa o ambiente de desenvolvimento dela, que também verifica. - Use o SDK do Swift. A opção
appAttestdele étruepor 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
- 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 signingReporte copie o SHA-256 dessa variante.
- 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).
- Use o SDK do Android. A opção
attestdele étruepor 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 signingReportroda na pastaandroiddo 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-Aftersem alterá-los: é com base neles que o SDK decide se tenta de novo ou descarta um lote. - Um
401ou403faz 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-srcda 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.
| Plano | Eventos por dia de um endereço |
|---|---|
| Free | 20.000 |
| Pro | 200.000 |
| Business | 4.000.000 |
| Unlimited | Sem 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.