はじめに

インストール

AIアシストセットアップを使ってプラグインをインストールできます。以下のコマンドで、お使いのAIツールに Capgo スキルを追加してください：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

次に、以下のプロンプトを使用します：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-device-integrity` plugin in my project.

手動セットアップを希望する場合は、以下のコマンドでプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

1. パッケージをインストール

   bun add @capgo/capacitor-device-integrity

2. ネイティブプロジェクトを同期

   bunx cap sync

3. プラットフォーム要件の設定

   • Android: 設定 plugins.DeviceIntegrity.cloudProjectNumber attestation APIを使用する場合、Play Integrity用に設定してください。
   • iOS: attestation APIを使用する場合、XcodeでApp Attest capabilityを有効にしてください。

クイックスタート

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const result = await DeviceIntegrity.getCapabilities();
console.log(result);

例: getWidevineFingerprint

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
if (capabilities.widevine.fingerprintAvailable) {
  const result = await DeviceIntegrity.getWidevineFingerprint();
  console.log(result);
}

例: prepareAttestation

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  const result = await DeviceIntegrity.prepareAttestation();
  console.log(result);
}

よくある落とし穴

• ネイティブ同期: 実行 npx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼する src/definitions.ts GitHub リポジトリ内に

このプラグインを使う理由

サインアップ、ログイン、またはリスクの高い操作の際に、API を使用して整合性シグナルを収集できます：

• ネイティブ API を呼び出す前に Probe をサポートしているか確認 (getCapabilities)
• Widevine を使用して Android デバイスをフィンガープリント (getWidevineFingerprint)
• App Attest または Play Integrity で登録とアサーションを実行 (prepareAttestation, createAttestation, createAssertion)
• iOS DeviceCheck トークンをリクエスト (getDeviceCheckToken)

バックエンドでトークンを検証し、リプレイ攻撃対策を適用するまで、クライアント側の値は信頼できません。

使い方

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
console.log(capabilities.platform, capabilities.playIntegrity.supported);

if (capabilities.widevine.fingerprintAvailable) {
  const widevine = await DeviceIntegrity.getWidevineFingerprint();
  console.log(widevine.fingerprint, widevine.securityLevel);
}

const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  try {
    const prepared = await DeviceIntegrity.prepareAttestation();

    const challengeResponse = await fetch(
      'https://api.example.com/integrity/registration-challenge',
    );
    if (!challengeResponse.ok) {
      throw new Error(`Challenge request failed with ${challengeResponse.status}`);
    }
    const challengeBody = await challengeResponse.json();
    if (typeof challengeBody.challenge !== 'string' || challengeBody.challenge.length === 0) {
      throw new Error('Backend response missing challenge');
    }
    const challenge = challengeBody.challenge;

    const registration = await DeviceIntegrity.createAttestation({
      keyId: prepared.keyId,
      challenge,
    });

    const payloadResponse = await fetch(
      'https://api.example.com/integrity/assertion-payload',
    );
    if (!payloadResponse.ok) {
      throw new Error(`Payload request failed with ${payloadResponse.status}`);
    }
    const payloadBody = await payloadResponse.json();
    if (typeof payloadBody.payload !== 'string' || payloadBody.payload.length === 0) {
      throw new Error('Backend response missing payload');
    }
    const payload = payloadBody.payload;

    const assertion = await DeviceIntegrity.createAssertion({
      keyId: prepared.keyId,
      payload,
    });

    console.log(registration.format, registration.token);
    console.log(assertion.format, assertion.token);
  } catch (error) {
    console.error('Attestation flow failed', error);
  }
}

if (capabilities.deviceCheck.supported) {
  const deviceCheck = await DeviceIntegrity.getDeviceCheckToken();
  console.log(deviceCheck.token);
}

Widevine オプション

getWidevineFingerprint() 以下のオプションフィールドを受け付けます：

項目	種類	説明
includeRawId	boolean	true の場合、base64 形式の Widevine デバイス ID（機密情報）を含めます。
hashSalt	string	〜用のソルト fingerprint。Android では省略時、アプリのパッケージ名が使用されます。

バックエンドの要件

• サーバー側で App Attest および Play Integrity トークンの検証を行ってください。
• Widevine 識別子は機密情報として扱い、プライバシーポリシーにその使用目的を明記してください。
• 広告やアプリを跨いだトラッキングに Widevine の値を使用しないでください。

Getting Started から続ける

以下を使用している場合： はじめに セキュリティとコンプライアンスの計画に使う場合は、以下と連携してください： @capgo/capacitor-device-integrity を使用する場合 @capgo/capacitor-device-integrity を使用してネイティブ機能を利用する場合、 @capgo/capacitor-app-attest App AttestおよびPlay Integrityフローに特化した実装には、 暗号化 実装の詳細は「暗号化」を参照： コンプライアンス Compliance の実装詳細、および Capgo セキュリティ Capgo Security のプロダクトワークフローについて。