アーリーアクセス招待制です。SDK はまだ公開されていません。招待をリクエスト
本文へスキップ
ドキュメント

検証済みイベント

サーバーキーで送られたイベントや、デバイスによって証明された自分の Apple または Android アプリから送られたイベントは検証済みとしてマークされます。公開キーを持つ誰かが送ったかもしれないイベントと区別できます。

インジェストキーはアプリや Web ページに含めて配布されるので、誰でもコピーして、アプリから来たように見えるイベントを送れます。Lyrelog は、そうしたイベントと区別できるイベントを検証済み(verified)としてマークします。方法は 3 つあります。

  • サーバーキーで送られたイベント。サーバーキーは自分のサーバーだけが持つ秘密です。
  • 実機上の自分の Apple アプリから送られたイベント。Apple が App Attest で証明します。
  • 実機上の自分の Android アプリから送られたイベント。デバイスのセキュアなハードウェアが Key Attestation で証明します。

検証済みの意味

検証済みのイベントは、アプリや Web ページから公開キーをコピーした誰かが送ったものではありえません。サーバーキーの場合は、プロジェクトのサーバーだけが持つキーで送られています。App Attest の場合は、チームが署名したプロジェクトの本物のアプリから、本物の Apple デバイス上で送られています。Key Attestation の場合は、プロジェクトの証明書で署名された本物の Android アプリから、改変されていないロック済みのシステムを持つ実機の Android デバイス上で送られています。

ただし、イベントの内容が正しいことまでは証明しません。サーバーが誤った値を送ることもあれば、jailbreak したデバイスで本物のアプリを使っている人がアプリにイベントを送らせることもできます。検証済みイベントの信頼性は、それを送ったコードの信頼性と同じです。

公開インジェストキーで送られ、アプリの証明がないイベントは検証済みではありません。そのキーを持つ誰もが、同じようなイベントを送れたからです。Web ページからのイベントや、App Attest も Key Attestation も使わないアプリからのイベントのほとんどがこれにあたり、それは想定どおりです。

誰が検証するか

送信元キーそのイベントverified_by
自分のサーバーSend events from a server、lyr_srv_検証済みserver
実機の iPhone、iPad、Apple Watch 上の自分の Apple アプリ(App Attest を設定済み)Send events、lyr_ing_検証済みapp_attest
実機上の自分の Android アプリ(Key Attestation を設定済み)Send events、lyr_ing_検証済みkey_attestation
インジェストキーを使うその他すべてSend events、lyr_ing_検証済みではない空
フルアクセスキーを使うすべてFull access、lyr_adm_検証済みではない空

Lyrelog はインジェスト時に、バッチに付いてきたキーと、インジェストキーの場合はバッチが運ぶ App Attest または Key Attestation のトークンから、すべてのイベントにこの値を設定します。クライアントからは設定できません。verified_by を自分で送る行は unknown fields: verified_by で拒否されます。

サーバーキーにできるのは、インジェストキーと同じくイベントの追加だけで、読み取りはできません。作り方はキーを参照してください。

ダッシュボードでの表示

  • イベント一覧では、イベント名の横の小さな盾のアイコンが検証済みイベントを示します。
  • イベントを開くと、ヘッダーに Verified バッジが表示されます。Context の Sender には、Verified, server key、Verified, App Attest、Verified, Key Attestation、Not verified, public key のいずれかが表示されます。
  • エクスプローラーの Filter メニューには Verified by フィールドがあり、値は Server key、App Attest、Key Attestation、Not verified です(URL では server、app_attest、key_attestation、none)。検証済みイベントだけを見るには Not verified 以外をすべて選び、それ以外を見るには Not verified を選びます。

読み取り API は各イベントの verified_by("server"、"app_attest"、"key_attestation"、検証済みでなければ "")を返し、verified=server、verified=app_attest、verified=key_attestation、verified=none で、または複数をまとめて(verified=server|app_attest|key_attestation)絞り込めます。

サーバー

バックエンド(Node、Python、Go、JVM 上の Java や Kotlin、またはサーバーからの curl)は、サーバーキー lyr_srv_... で送るべきです。そのイベントは検証済みになり、1 アドレスあたりの 1 日の割り当てもありません。例で lyr_ing_... となっている箇所にサーバーキーを渡すだけで、ほかは何も変わりません。

ほかの秘密情報と同じように管理してください。サーバーの環境変数やシークレットストアに置き、アプリ、Web ページ、リポジトリには決して入れません。漏れたら失効させて、新しいものを作ってください。

Apple アプリ(App Attest)

Apple の App Attest を使うと、アプリはチームが署名した本物のアプリであり、本物の Apple デバイスで動いていることをサーバーに証明できます。Swift SDK がこれを自動で行います。iOS の React Native と Flutter の SDK も、Swift SDK を通じて同じことを行います。Lyrelog は、証明されたアプリのイベントを検証済み(verified_by が app_attest)として保存します。

設定する

  1. アプリの App ID を確認します。Team ID、ドット、bundle id をつなげたもので、ABCDE12345.com.example.app のような形です。Team ID は Apple Developer アカウントの Membership にあります。
  2. Lyrelog で Project settings を開きます。プロジェクトに iOS アプリのプラットフォームがあると、Verified events from your Apple apps セクションが表示されます。Add で App ID を追加します。オーナーはアプリごとに 1 つ、最大 10 個まで追加できます(iPhone アプリとその watch アプリは bundle id が異なります)。
  3. Xcode で、アプリのターゲットに App Attest capability を追加します(Signing & Capabilities)。これは entitlement com.apple.developer.devicecheck.appattest-environment です。App Store と TestFlight のビルドでは production に設定してください。設定しないと Apple は開発用の環境を使いますが、その環境でも検証されます。
  4. Swift SDK を使います。オプション appAttest はデフォルトで true なので、ほかに書くコードはありません。React Native と Flutter も同様です(オプションは attest)。内部で Swift SDK が処理するので、プロジェクトの設定も同じです。

無効にするには、App ID を削除する(イベントは以前と同じく検証されずに届きます)か、アプリで appAttest: false を設定します。

仕組み

  • インストールごとに一度、SDK はデバイスの Secure Enclave にキーを作り、Lyrelog が発行する 1 回限りのチャレンジに対して Apple がそのキーを証明(attest)します。Lyrelog は Apple の証明書チェーンと、アプリがプロジェクトの App ID のどれかであることを確認し、キーの公開鍵部分を保存します。インストールごとに 1 つで、180 日間使われなければ削除されます。
  • 次に SDK は 1 日有効なトークンを受け取り、各バッチと一緒に送ります。トークンの更新には、そのキーによる署名(assertion)を使います。署名にはカウンターが含まれるので、リプレイはできません。
  • 送信がこの処理を待つことはありません。アプリがトークンを得るまでの間や、何かが失敗したときは、イベントは検証されないまま送られ、保存されます。App Attest が原因でバッチが拒否されることはありません。

対象外のケース

App Attest は実機の iPhone、iPad、Apple Watch で動作します。次のものは、すべて設定済みでも検証されないイベントを送ります。

  • Mac(Apple が App Attest を提供していません)
  • シミュレーター
  • ほとんどの App Extension
  • App Attest に対応していないデバイス

ルートとヘッダーは HTTP API にあります。

iOS アプリからは検証済みイベントだけを受け付ける

デフォルトではオフです。同じ設定セクションの Accept only verified events from the iOS app をオンにすると、Lyrelog はイベントが platform: ios を示す検証されていないバッチをすべて保留します。425 Too Early を返し、SDK はバッチを保持して後で再送します。新しいインストールの最初のイベントは、トークンを得るまで数秒待ってから検証済みとして届くので、そこで失われるものはありません。

オンにするのは、全員が App Attest を設定したバージョンのアプリを使うようになってからにしてください。それまでは、古いバージョン、シミュレーター、Mac 上で動く iPad アプリからのイベントは決して証明できません。それらは SDK が保持できる範囲(20 MB、7 日間)でデバイス上で待ち、保存されることはありません。ほかのプラットフォームからのイベントやサーバーキーによるイベントは、これまでどおり受け付けられます。

Android アプリ(Key Attestation)

Android の Key Attestation を使うと、アプリは端末のセキュアなハードウェア(Trusted Execution Environment、または StrongBox チップ)の中にキーを作り、そのキー、アプリ、端末の状態を記述した、Google まで署名がつながる証明書チェーンをデバイスから得られます。Lyrelog はそのチェーンを自分で検証するので、Google アカウントも Play Integrity も Google Cloud プロジェクトも不要です。Android SDK がこれを自動で行います。Android の React Native と Flutter の SDK も、Android SDK を通じて同じことを行います。Lyrelog は、証明されたアプリのイベントを検証済み(verified_by が key_attestation)として保存します。

設定する

  1. アプリのパッケージ名(com.example.app のような application id)と、署名に使っている証明書の SHA-256 フィンガープリントを確認します。
    • Google Play からインストールされるビルドは Google が署名します。Play Console でアプリを開き、Test and release、App integrity と進んで、App signing key certificate の SHA-256 をコピーします。
    • 自分で署名するビルド(アップロード鍵、または開発中の debug 鍵)では、./gradlew signingReport を実行して、そのバリアントの SHA-256 をコピーします。
  2. Lyrelog で Project settings を開きます。プロジェクトに Android アプリのプラットフォームがあると、Verified events from your Android apps セクションが表示されます。Add でパッケージ名とフィンガープリントを追加します。イベントを送るビルドに署名する証明書が複数ある場合は、証明書ごとに同じパッケージ名を別のフィンガープリントで追加します(パッケージごとに最大 5 個、パッケージは 10 個まで)。
  3. Android SDK を使います。オプション attest はデフォルトで true なので、ほかに書くコードはありません。React Native と Flutter も同様です。内部で Android SDK が処理するので、プロジェクトの設定も同じです。React Native や Flutter のプロジェクトでは、./gradlew signingReport はアプリの android フォルダーで実行します。

無効にするには、パッケージを削除する(イベントは以前と同じく検証されずに届きます)か、アプリで attest = false を設定します。

確認される内容

  • チェーンが証明書ごとに署名され、Google のアテステーションルートのどれかまでつながっていること。そして、どの証明書も Google の失効リストに載っていないこと。
  • キーが端末のセキュアなハードウェアにあり、そこで作られ、Lyrelog が発行する 1 回限りのチャレンジに応答すること。
  • 端末が改変されていない検証済みのシステムで起動し、ブートローダーがロックされていること。
  • アプリがプロジェクトのパッケージのどれかで、その証明書のどれかで署名されていること。

その後 Lyrelog はキーの公開鍵部分を保存し(インストールごとに 1 つ、180 日間使われなければ削除)、1 日有効なトークンをアプリに渡します。アプリはそれを各バッチと一緒に送ります。トークンは、新しい 1 回限りのチャレンジにそのキーで署名して更新します。送信がこの処理を待つことはありません。アプリがトークンを得るまでの間や、何かが失敗したときは、イベントは検証されないまま送られ、保存されます。Key Attestation が原因でバッチが拒否されることはありません。

対象外のケース

次のものは、すべて設定済みでも検証されないイベントを送ります。

  • エミュレーター(セキュアなハードウェアがなく、チェーンが Google につながりません)
  • root 化した端末、ブートローダーをアンロックした端末、カスタムシステムの端末
  • ハードウェアに裏付けられたキーを持たない端末(Android 8 以降ではまれです)
  • プロジェクトに登録されていない証明書で署名されたビルド

ルートは HTTP API にあります。

Android アプリからは検証済みイベントだけを受け付ける

デフォルトではオフで、iOS の設定と同じように働きます。オンにすると、イベントが platform: android を示す検証されていないバッチにはすべて 425 Too Early が返り、デバイス上で待つことになります。オンにするのは、全員が Key Attestation 対応のバージョンを使うようになってからにしてください。古いバージョン、エミュレーター、root 化またはアンロックされた端末からのイベントは決して証明できず、保存されることもありません。

Web ページ(自分のサーバーを経由)

Web ページにはサーバーキーを置けません。ブラウザー内のものはすべて読み取れるからです。ページから検証済みイベントを得るには、自分のバックエンドを経由して中継します。ページは自分のサイトのルートに送り、そのルートがサーバーキーを付けてバッチを Lyrelog に転送します。

これで何が証明されるのかははっきりさせておきましょう。これらのイベントが検証済みなのは、自分のサーバーを通ったという意味においてだけです。サイトのルートには誰でも POST できるので、中継ではサインイン済みの自分のセッションからのイベントだけを受け付け、1 つのセッションが送れる量に上限を設けてください。誰からでも何でも受け取る中継は、何も検証しません。

ページでは、JavaScript SDK の endpoint を中継先に向けます。これはベース URL で、SDK は <endpoint>/v1/events:batch に POST します。apiKey は空にできませんが、中継で置き換えられるので、どんなプレースホルダーでも構いません。

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
});

Next.js の route handler(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 });
}

知っておくとよいこと:

  • ステータスと Retry-After はそのまま返してください。SDK はそれを見て、バッチを再送するか捨てるかを決めます。
  • 401 または 403 を受け取ると、SDK はページがリロードされるまで送信を止めます。クライアントは訪問者がサインインしてから起動し、その前には起動しないでください。
  • 国は Lyrelog にバッチを送るアドレスから決まり、それは自分のサーバーのアドレスになります。中継されたイベントには、訪問者ではなくサーバーの国が入ります。
  • Content Security Policy を設定している場合は、中継のアドレスを connect-src に追加してください(同じサイトのルートなら 'self' で足ります)。

その他のアプリと Web ページ

App Attest を使わない Apple アプリ、Key Attestation を使わない Android アプリ、直接送信する Web ページからのイベントは、アプリの証明なしに公開インジェストキーを使うので、検証済みではありません。Web ページは自分のサーバーを経由して検証済みイベントを得られます。コピーされたキーが大きな害を及ぼさないよう、2 つの上限があります。

  • 組織全体に対する、プランの月間イベント数
  • 下で説明する、1 アドレスあたりの 1 日の割り当て

1 アドレスあたりの 1 日の割り当て

公開キー(インジェストキー、またはフルアクセスキー)では、1 つの送信元アドレスが UTC の 1 日に送れるのは、組織のプロジェクト全体で、プランの月間イベント数の 50 分の 1 までです。IPv6 アドレスは /64 単位で数えます。数えるのは検証済みでないイベントだけです。

プラン1 つのアドレスから 1 日に送れるイベント数
Free20,000
Pro200,000
Business4,000,000
Unlimited上限なし

これは 1 台のデバイスが送る量をはるかに上回ります。アプリからコピーされたキーで、1 台のマシンから組織の 1 か月分を使い切られないようにするための上限です。検証済みイベント(サーバーキー、App Attest、Key Attestation によるもの)は数えられません。

上限を超えると、そのアドレスには翌 UTC 日まで、Retry-After が最大 1 時間の 429 が返ります。ほかのアドレスは送信を続けられます。SDK はほかの 429 と同様に再試行し、キューの上限の範囲でイベントを保持します。レスポンスの本文は HTTP API にあります。

自分のサーバーのどれかがこの上限に達するなら、そのサーバーはサーバーキーを使うべきです。