Eventos verificados
Los eventos enviados con una clave de servidor, o por tu propia app de Apple o Android con la prueba del dispositivo, se marcan como verificados, para que los distingas de los que podría haber enviado cualquiera con la clave pública.
Una clave de ingesta va dentro de tu app o de tu página web, así que cualquiera puede copiarla y enviar eventos que parezcan de tu app. Lyrelog marca como verificados (verified) los eventos que sí puede distinguir de esos, de tres maneras:
- los eventos enviados con una clave de servidor, un secreto que solo tienen tus servidores,
- los eventos enviados por tu propia app de Apple en un dispositivo real, algo que Apple demuestra con App Attest, y
- los eventos enviados por tu propia app de Android en un dispositivo real, algo que el hardware seguro del dispositivo demuestra con Key Attestation.
Qué significa verificado
Un evento verificado no puede haberlo enviado alguien que copió la clave pública de una app o de una página web. Con una clave de servidor, llegó con una clave que solo tienen los servidores del proyecto. Con App Attest, llegó desde la app auténtica del proyecto, firmada por su equipo, en un dispositivo Apple auténtico. Con Key Attestation, llegó desde la app de Android auténtica del proyecto, firmada con el certificado del proyecto, en un dispositivo Android real con su sistema original y bloqueado.
No demuestra que lo que dice el evento sea cierto. Un servidor puede enviar un valor erróneo, y alguien que use la app real en un dispositivo con jailbreak podría seguir haciendo que envíe eventos. Un evento verificado solo es tan fiable como el código que lo envió.
Los eventos enviados con la clave de ingesta pública y sin prueba de la app no están verificados: cualquiera con esa clave podría haber enviado eventos idénticos. Son la mayoría de los eventos de las páginas web y de las apps que no usan App Attest ni Key Attestation, y es lo esperado.
Quién verifica
| Remitente | Clave | Sus eventos | verified_by |
|---|---|---|---|
| Tu servidor | Send events from a server, lyr_srv_ | Verificados | server |
| Tu app de Apple en un iPhone, iPad o Apple Watch real, configurada para App Attest | Send events, lyr_ing_ | Verificados | app_attest |
| Tu app de Android en un dispositivo real, configurada para Key Attestation | Send events, lyr_ing_ | Verificados | key_attestation |
| Cualquier otra cosa con la clave de ingesta | Send events, lyr_ing_ | No verificados | vacío |
| Cualquier cosa con una clave de acceso total | Full access, lyr_adm_ | No verificados | vacío |
Lyrelog fija esto en cada evento durante la ingesta, a partir de la clave con la que llegó el
lote y, para una clave de ingesta, del token de App Attest o de Key Attestation que lleva. Un
cliente no puede fijarlo: una línea que envíe verified_by por su cuenta se rechaza con
unknown fields: verified_by.
Una clave de servidor solo puede añadir eventos, como una clave de ingesta; no puede leerlos. Consulta Claves para ver cómo crear una.
En el panel
- En la lista de eventos, un pequeño escudo junto al nombre del evento señala un evento verificado.
- Un evento abierto muestra una insignia Verified en su cabecera. En Context, Sender dice Verified, server key, Verified, App Attest, Verified, Key Attestation o Not verified, public key.
- En el explorador, el menú Filter tiene un campo Verified by con
los valores Server key, App Attest, Key Attestation y Not verified (en la URL:
server,app_attest,key_attestationynone). Elige todos menos Not verified para ver solo los eventos verificados, o Not verified para ver el resto.
La API de lectura devuelve verified_by en cada evento ("server", "app_attest",
"key_attestation", o "" si no está verificado) y filtra por él con verified=server,
verified=app_attest, verified=key_attestation o verified=none, o con varios a la vez
(verified=server|app_attest|key_attestation).
Servidores
Un backend (Node, Python, Go, Java o Kotlin en la JVM, o curl desde un servidor)
debería enviar con una clave de servidor, lyr_srv_...: sus eventos quedan verificados y no
están sujetos a la cuota diaria de una dirección. Dale al SDK la clave de
servidor donde los ejemplos ponen lyr_ing_...; nada más cambia.
Guárdala como cualquier secreto: en el entorno de tu servidor o en su almacén de secretos, nunca en una app, una página web o un repositorio. Si se filtra, revócala y crea otra.
Apps de Apple (App Attest)
App Attest de Apple permite que una app demuestre a un servidor que es la app auténtica, firmada
por su equipo, ejecutándose en un dispositivo Apple auténtico. El
SDK de Swift lo hace por ti, y también los SDK de
React Native y Flutter en iOS,
a través del SDK de Swift. Lyrelog guarda como verificados los eventos de una app que lo ha
demostrado (verified_by es app_attest).
Configúralo
- Busca el App ID de tu app: tu Team ID, un punto y el bundle id, como
ABCDE12345.com.example.app. El Team ID está en tu cuenta de Apple Developer, en Membership. - En Lyrelog, abre Project settings. La sección Verified events from your Apple apps aparece cuando el proyecto tiene la plataforma de app de iOS. Añade el App ID con Add. Un propietario puede añadir hasta 10, uno por app (una app de iPhone y su app de reloj tienen bundle ids distintos).
- En Xcode, añade la capability App Attest al target de la app (Signing & Capabilities). Es
el entitlement
com.apple.developer.devicecheck.appattest-environment. Ponlo enproductionpara las builds de la App Store y de TestFlight. Sin él, Apple usa su entorno de desarrollo, que también verifica. - Usa el SDK de Swift. Su opción
appAttestestruepor defecto, así que no hay nada más que programar. Lo mismo vale para React Native y Flutter (su opción esattest): los ajustes del proyecto son los mismos, porque el trabajo lo hace el SDK de Swift que tienen debajo.
Para desactivarlo, quita los App ID (los eventos llegan sin verificar, como antes) o pon
appAttest: false en la app.
Cómo funciona
- Una vez por instalación, el SDK crea una clave en el Secure Enclave del dispositivo y Apple la certifica respondiendo a un desafío de un solo uso que envía Lyrelog. Lyrelog comprueba la cadena de certificados de Apple y que la app es uno de los App ID del proyecto, y guarda la mitad pública de la clave: una por instalación, que se borra tras 180 días sin usarse.
- Después el SDK obtiene un token, válido durante un día, y lo envía con cada lote. Renueva el token con una firma de esa clave (una aserción), cuyo contador no se puede reutilizar.
- El envío nunca espera a esto. Mientras la app no tiene token, y siempre que algo falla, los eventos se envían y se guardan sin verificar. Nunca se rechaza un lote por culpa de App Attest.
Dónde no se aplica
App Attest funciona en iPhones, iPads y Apple Watches reales. Estos envían eventos sin verificar, aunque todo esté configurado:
- los Mac (Apple no ofrece App Attest en ellos),
- el simulador,
- la mayoría de las extensiones de app,
- los dispositivos que no admiten App Attest.
Las rutas y el header están en la API HTTP.
Aceptar solo eventos verificados de la app de iOS
Desactivado por defecto. En la misma sección de ajustes, Accept only verified events from the
iOS app hace que Lyrelog retenga todos los lotes sin verificar cuyos eventos digan platform: ios:
responde 425 Too Early, y el SDK conserva el lote y lo vuelve a enviar más tarde. Los primeros
eventos de una instalación nueva esperan unos segundos a su token y luego llegan verificados, así
que ahí no se pierde nada.
Actívalo solo cuando todo el mundo tenga una versión de la app con App Attest configurado. Hasta entonces, los eventos de versiones anteriores, del simulador y de una app de iPad que se ejecute en un Mac no podrán verificarse nunca: esperan en el dispositivo, hasta lo que guarda el SDK (20 MB y 7 días), y nunca se guardan. Los eventos de otras plataformas, y los de una clave de servidor, se aceptan como antes.
Apps de Android (Key Attestation)
Key Attestation de Android permite que una app cree una clave dentro del hardware seguro del
teléfono (su entorno de ejecución de confianza, o un chip StrongBox) y obtenga del dispositivo
una cadena de certificados, firmada hasta llegar a Google, que describe la clave, la app y el
estado del teléfono. Lyrelog comprueba esa cadena por su cuenta: no hace falta cuenta de Google,
Play Integrity ni proyecto de Google Cloud. El SDK de Android lo
hace por ti, y también los SDK de React Native y
Flutter en Android, a través del SDK de Android. Lyrelog guarda
como verificados los eventos de una app que lo ha demostrado (verified_by es
key_attestation).
Configúralo
- Busca el paquete de tu app (su application id, como
com.example.app) y la huella SHA-256 del certificado con el que está firmada:- En las builds instaladas desde Google Play, Google firma la app: en Play Console, abre la app, luego Test and release, App integrity, y copia el SHA-256 de App signing key certificate.
- En las builds que firmas tú (con una clave de subida, o la clave de depuración en
desarrollo), ejecuta
./gradlew signingReporty copia el SHA-256 de esa variante.
- En Lyrelog, abre Project settings. La sección Verified events from your Android apps aparece cuando el proyecto tiene la plataforma de app de Android. Añade el paquete y la huella con Add; vuelve a añadir el mismo paquete con otra huella por cada certificado que firme builds que envían eventos (hasta 5 por paquete, 10 paquetes).
- Usa el SDK de Android. Su opción
attestestruepor defecto, así que no hay nada más que programar. Lo mismo vale para React Native y Flutter: los ajustes del proyecto son los mismos, porque el trabajo lo hace el SDK de Android que tienen debajo. En un proyecto de React Native o Flutter,./gradlew signingReportse ejecuta en la carpetaandroidde la app.
Para desactivarlo, quita los paquetes (los eventos llegan sin verificar, como antes) o pon
attest = false en la app.
Qué se comprueba
- La cadena está firmada, certificado a certificado, hasta una de las raíces de atestación de Google, y ninguno de sus certificados está en la lista de revocados de Google.
- La clave vive en el hardware seguro del teléfono, se creó ahí y responde a un desafío de un solo uso de Lyrelog.
- El teléfono arrancó su sistema original y verificado, y su bootloader está bloqueado.
- La app es uno de los paquetes del proyecto, firmada con uno de sus certificados.
Después Lyrelog guarda la mitad pública de la clave (una por instalación, que se borra tras 180 días sin usarse) y le da a la app un token, válido durante un día, que envía con cada lote. Renueva el token firmando con esa clave un nuevo desafío de un solo uso. El envío nunca espera a esto: mientras la app no tiene token, y siempre que algo falla, los eventos se envían y se guardan sin verificar. Nunca se rechaza un lote por culpa de Key Attestation.
Dónde no se aplica
Estos envían eventos sin verificar, aunque todo esté configurado:
- los emuladores (no tienen hardware seguro y sus cadenas no llevan a Google),
- los teléfonos rooteados, con el bootloader desbloqueado o con un sistema personalizado,
- los teléfonos sin claves respaldadas por hardware (raros desde Android 8),
- las builds firmadas con un certificado que el proyecto no tiene en su lista.
Las rutas están en la API HTTP.
Aceptar solo eventos verificados de la app de Android
Desactivado por defecto, y funciona como el de iOS:
si está activado, todos los lotes sin verificar cuyos eventos digan platform: android reciben
425 Too Early y esperan en el dispositivo. Actívalo solo cuando todo el mundo tenga una versión
con Key Attestation: los eventos de versiones anteriores, de emuladores y de teléfonos rooteados
o desbloqueados no podrán verificarse nunca y no se guardan.
Páginas web, a través de tu propio servidor
Una página web no puede guardar una clave de servidor: todo lo que está en el navegador se puede leer. Para obtener eventos verificados desde una página, reenvíalos a través de tu propio backend. La página envía a una ruta de tu sitio, y la ruta reenvía el lote a Lyrelog con la clave de servidor.
Ten claro qué demuestra eso. Estos eventos están verificados solo en el sentido de que pasaron por tu servidor. Cualquiera puede hacer un POST a una ruta de tu sitio, así que el relay debería aceptar eventos solo de tus propias sesiones autenticadas, y limitar lo que envía cada sesión. Un relay que acepta cualquier cosa de cualquiera no verifica nada.
En la página, apunta el endpoint del SDK de JavaScript al relay. Es una URL
base: el SDK hace POST a <endpoint>/v1/events:batch. apiKey no puede estar vacío, pero el
relay lo sustituye, así que sirve cualquier marcador:
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
});El relay, como route handler de 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 });
}Conviene saber:
- Devuelve el código de estado y
Retry-Aftersin cambios: el SDK decide con ellos si reintenta un lote o lo descarta. - Un
401o403hace que el SDK deje de enviar hasta que la página se recarga. Inicia el cliente cuando el visitante haya iniciado sesión, no antes. - El país sale de la dirección que envía el lote a Lyrelog, que ahora es la de tu servidor. Los eventos reenviados llevan el país de tu servidor, no el del visitante.
- Añade la dirección del relay al
connect-srcde tu Content Security Policy si tienes una ('self'cubre una ruta del mismo sitio).
Otras apps y páginas web
Los eventos de apps de Apple sin App Attest, de apps de Android sin Key Attestation y de páginas web que envían directamente usan la clave de ingesta pública sin prueba de la app, así que no están verificados. Una página web puede obtener eventos verificados a través de tu propio servidor. Dos límites impiden que una clave copiada haga mucho daño:
- los eventos mensuales del plan, para toda la organización, y
- la cuota diaria de una dirección, que se explica abajo.
La cuota diaria de una dirección
Con una clave pública (una clave de ingesta o una de acceso total), una dirección remitente puede enviar como máximo una cincuentava parte de los eventos mensuales del plan en un día UTC, sumando los proyectos de la organización. Las direcciones IPv6 cuentan por /64. Solo cuentan los eventos que no están verificados.
| Plan | Eventos al día desde una dirección |
|---|---|
| Free | 20.000 |
| Pro | 200.000 |
| Business | 4.000.000 |
| Unlimited | Sin límite |
Es mucho más de lo que envía un dispositivo. Existe para que una clave copiada de una app no pueda gastar el mes de la organización desde una sola máquina. Los eventos verificados (de una clave de servidor, App Attest o Key Attestation) no cuentan para ella.
Superada esa cuota, esa dirección recibe 429 con un Retry-After de como mucho una hora, hasta el
siguiente día UTC. Las demás direcciones siguen enviando. Los SDK lo reintentan como cualquier
429, conservando los eventos dentro de los límites de su cola. El cuerpo está en la
API HTTP.
Si uno de tus servidores la alcanza, debería estar usando una clave de servidor.