AppIntegrity

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

重要 此库当前处于 alpha 阶段，并且将频繁出现破坏性变更。

@expo/app-integrity 提供了一组 API，用于帮助确保你的后端资源只能被运行在真实设备上的、合法安装的应用访问。它在 Android 上使用 Google 的 Play Integrity APIs，在 iOS 上使用 Apple 的 App Attest service 来验证应用真实性，从而帮助防止未经授权的客户端、被修改的应用或自动化脚本向你的服务器发起请求。

通常，@expo/app-integrity 可以帮助你的服务器区分以下两者：

• 运行在真实设备上的你的真实应用
• 其他任何东西（被修改的应用、脚本、模拟器）

它通过使用平台推荐的应用证明服务来实现这一点。

安装

If you are installing this in an existing React Native app, make sure to install expo in your project.

Android 上的使用

@expo/app-integrity 使用 Play Integrity 的 标准请求流程 进行完整性检查。

配置

请参考 Play Integrity 设置指南 了解如何在应用中启用完整性 API。

准备完整性令牌提供器（仅需一次）

在发起完整性检查请求之前，你需要先准备好完整性令牌提供器。你可以在应用启动时执行，或者在需要完整性检查之前于后台执行。

import * as AppIntegrity from '@expo/app-integrity';

const cloudProjectNumber = 'your-cloud-project-number';
await AppIntegrity.prepareIntegrityTokenProviderAsync(cloudProjectNumber);

请求完整性令牌（按需）

每当你的应用发起一个你希望验证其真实性的服务器请求时，你都需要请求一个完整性令牌，并将其发送到应用的后端服务器进行解密和验证。随后，你的后端服务器即可决定如何处理。

const requestHash = '2cp24z...';
const result = await AppIntegrity.requestIntegrityCheckAsync(requestHash);

在调用 requestIntegrityCheckAsync 之前，请确保 prepareIntegrityTokenProviderAsync 已成功调用。

在此示例中，requestHash 是与被验证的特定用户操作唯一对应的哈希值。对于不同的用户操作，你可以使用不同的哈希多次调用 requestIntegrityCheckAsync。

成功后，将结果发送到你的服务器进行验证。

注意：如果你的应用长时间使用同一个令牌提供器，该提供器可能会过期，这会导致下一次令牌请求返回 ERR_APP_INTEGRITY_PROVIDER_INVALID 错误。你应该通过再次调用 prepareIntegrityTokenProviderAsync 来请求新的提供器，从而处理该错误。

解密并验证完整性判定结果

请参考 Play Integrity 指南 在你的服务器上验证完整性令牌。

其他资源

• Google Play Integrity 文档：请参考 Google 的官方指南，了解支撑 @expo/app-integrity 的 API 和验证流程。

• Play Integrity 标准请求流程：此页面描述了如何发起标准 API 请求以获取完整性判定结果，该功能支持 Android 5.0（API 级别 21）及以上。每当你的应用发起服务器调用以检查交互是否真实时，都可以发起标准 API 请求获取完整性判定结果。

• 关于完整性判定结果：完整性判定结果会传达有关设备、应用和账号有效性的信息。你的应用服务器可以使用解密并验证后的判定结果载荷，来决定针对应用中的某个操作或请求的最佳处理方式。

• 处理错误代码：如果你的应用发起 Play Integrity API 请求但调用失败，应用会收到一个错误代码。这些错误可能由多种原因引起，例如网络连接较弱等环境问题、API 集成问题，或恶意活动和主动攻击。

iOS 上的使用

配置

在 Xcode 中，进入 Signing & Capabilities，点击 + Capability，添加 App Attest。Xcode 会自动为你的应用添加所需的 entitlement。

注意：要使用 App Attest 服务，你的应用必须具有你在 Apple Developer 网站上注册的 App ID。

关于服务器上的验证逻辑，请参见 验证连接到你服务器的应用。

检查设备是否支持应用证明

并非所有设备都能使用 App Attest 服务，因此在访问该服务之前，让应用先执行兼容性检查非常重要。如果用户的应用未通过兼容性检查，请优雅地绕过该服务。你可以通过读取 isSupported 属性来检查是否可用。

import * as AppIntegrity from '@expo/app-integrity';

if (AppIntegrity.isSupported) {
  // 执行密钥生成和证明。
}
// 继续进行你的服务器 API 访问。

注意：iOS 模拟器不支持 App Attest。

信息 大多数应用扩展都不支持 App Attest。通常，当在这些扩展中执行代码时，即使 isSupported 方法属性为 true，也应绕过密钥生成和证明。唯一支持 App Attest 的应用扩展是 watchOS 9 或更高版本中的 watchOS 扩展。对于这些扩展，你可以使用 isSupported 的结果来表示你的 WatchKit 扩展是否绕过证明。

创建密钥对

对于应用运行所在的每台设备上的每个用户账号，通过调用 generateKey 方法生成一个唯一的、基于硬件的加密密钥对。

const keyId = await AppIntegrity.generateKeyAsync();

成功后，该方法会返回一个密钥标识符（keyId），你之后会用它来访问该密钥。请将该标识符记录到持久化存储中，因为没有标识符就无法使用该密钥，而且之后也无法再获取该标识符。设备会自动将关联的私钥存储在 Secure Enclave 中，App Attest 服务可以利用它来创建签名，但任何进程都无法直接读取或修改它，从而确保其安全性。

信息 如果你在 App Clip 中创建了密钥对，请在对应的应用中使用同一密钥对。为支持这一点，请务必将标识符存储在可由完整应用访问的共享容器中。请参阅 Expo 关于使用 expo-sqlite 在应用/扩展之间共享数据库的指南，或者使用 React Native MMKV 的 App Groups / extensions 共享存储，以便在两个目标中持久保存该标识符。

不要在同一设备上的多个用户之间复用同一个密钥，因为这会削弱安全保护。特别是，这会使检测某些攻击变得困难——例如，攻击者使用一台被攻破的设备，为多个远程用户提供一个被攻破版本的应用服务。更多信息，请参见 评估欺诈风险。

从服务器获取挑战

向你的服务器请求一个唯一的、一次性的挑战值。该挑战值会被嵌入到下面的证明步骤中，确保它无法被攻击者重复使用。挑战值应至少为 16 字节长，以提供足够的熵，使其难以被猜测。

将密钥对认证为有效

如下所示，在 attestKey 方法中，将上一阶段由服务器创建的 keyId 与挑战值一起传入：

const attestationObject = await AppIntegrity.attestKeyAsync(keyId, challenge);

成功后，将收到的 attestationObject 和 keyId 一并发送到你的服务器进行验证。

如果该方法返回 ERR_APP_INTEGRITY_SERVER_UNAVAILABLE 错误，请稍后使用同一密钥重试证明。对于其他任何错误，请丢弃该密钥标识符，并在准备再次尝试时创建新的密钥。

信息 如果你的应用已经拥有数百万日活用户，并且你想开始在应用中调用 attestKey 方法来发起证明，请参考 准备使用 app attest 服务，了解如何安全地逐步放量给用户。

如果服务器能够成功验证 attestation 对象，就认为该应用实例是有效的。在这种情况下，请务必在应用中持久化保存密钥标识符——而不是 attestation 对象——以便将来对服务器请求进行签名。

在敏感请求上生成断言

在成功验证某个密钥的证明后，你的服务器可以要求应用对未来的全部或部分服务器请求声明其合法性。应用通过对请求进行签名来完成这一点。在应用中，从服务器获取一个唯一的、一次性的挑战值。这里使用挑战值和证明一样，是为了避免重放攻击。

const challenge = 'A string from your server';
const request = {
  action: 'getGameLevel',
  levelId: '1234',
  challenge: challenge,
};
const assertion = await AppIntegrity.generateAssertionAsync(keyId, JSON.stringify(request));

成功后，将断言对象连同客户端数据一起传递给服务器。如果断言对象验证失败，如何处理该请求由你负责决定。

对于使用某个密钥可以生成多少次断言，没有限制。不过，通常你会将断言保留给应用生命周期中较敏感的时刻所发起的请求，例如应用下载高级内容时。

在重新安装后重新开始

你生成的密钥会在常规应用更新中保持有效，但在应用重新安装、设备迁移或从备份还原设备后不会保留。在这些情况下，你需要从头开始流程并生成新的密钥。请尽量将新密钥的生成限制在这些事件发生时，或者在新增用户时进行。保持设备上的密钥数量较少，有助于检测某些类型的欺诈行为。

其他资源

• Apple 的 App Attest 文档：请参考 Apple 的官方指南，了解支撑 @expo/app-integrity 的 API 和验证流程。

• 验证连接到你服务器的应用：在你的服务器上验证应用证明和断言。

• 评估欺诈风险：通过服务器到服务器的调用请求并分析风险数据。

• 准备使用 app attest 服务：在开发环境中测试你的实现，并逐步引导用户加入。

API

import * as AppIntegrity from '@expo/app-integrity';

Constants

Methods