# @choochmeque/tauri-plugin-biometry-api 中文文档

规范地址：https://npmcn.com/package/%40choochmeque/tauri-plugin-biometry-api/

版本：0\.3\.0-rc\.3
npm 元数据更新时间：2026-09-01T11:42:05.332Z
中文译文更新时间：2026-11-09T14:34:55.234Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40choochmeque/tauri-plugin-biometry-api
原文对照：https://npmcn.com/package/%40choochmeque/tauri-plugin-biometry-api/?lang=original
项目主页：https://github.com/Choochmeque/tauri-plugin-biometry#readme
源码仓库：https://github.com/Choochmeque/tauri-plugin-biometry

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：36.9 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-09-05T15:30:16.967Z
- 最新版本发布：2026-09-01T11:42:04.986Z
- 近 30 天下载量：5700（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 5 个）

## 中文简介

一个Tauri v2插件,用于Android,macOS,iOS和Windows上的生物鉴别认证(Touch ID,Face ID,指纹).

## 安装

```sh
npm install @choochmeque/tauri-plugin-biometry-api
```

也可以使用：`pnpm add @choochmeque/tauri-plugin-biometry-api`、`yarn add @choochmeque/tauri-plugin-biometry-api`、`bun add @choochmeque/tauri-plugin-biometry-api`

## README

[![Crates.io](https://img.shields.io/crates/v/tauri-plugin-biometry)](https://crates.io/crates/tauri-plugin-biometry) [![npm](https://img.shields.io/npm/v/@choochmeque/tauri-plugin-biometry-api)](https://www.npmjs.com/package/@choochmeque/tauri-plugin-biometry-api) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40choochmeque/tauri-plugin-biometry-api/LICENSE)

# Tauri 插件生物测量

用于生物鉴别认证的Tauri插件(Touch ID,Face ID,Windows Hello,指纹等),支持macOS,Windows,iOS,和Android.

## 特征

-   \* 生物测量认证(Touch ID、Face ID、Windows Hello、指纹)
-   iOS和Android的完整支持
-   macOS(Touch ID)和Windows(Windows Hello)的桌面支持
-   \* 有生物鉴别保护的安全数据储存(Android/iOS/macOS/Windows)
-   返回到设备密码/密码
-   土著安全最佳做法
-   使用详细的错误代码妥善处理错误

## 安装

### 锈

将插件添加到您的 `Cargo.toml`数字 :

```toml
[dependencies]
tauri-plugin-biometry = "0.3"
```

### Java 脚本/ Type 脚本

安装 JavaScript/ TypeScript API :

```bash
npm install @choochmeque/tauri-plugin-biometry-api
# or
yarn add @choochmeque/tauri-plugin-biometry-api
# or
pnpm add @choochmeque/tauri-plugin-biometry-api
```

## 设置

### Rust 设置

在您的 Tauri 应用程序中注册插件 :

```rust
fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_biometry::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### iOS 设置

添加 `NSFaceIDUsageDescription` 给您的 `Info.plist`数字 :

```xml
<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to secure your data</string>
```

### Android 设置

插件会自动处理Android所需的权限.

### 权限

该插件使用Tauri的许可系统,具有两级模式:

-   `biometry:default` 只授予非存储命令( q)`status` 财务报告和审定财务报表 `authenticate`) (中文(简体) ).
-   存储命令( E)`has_data`, (中文(简体) ), `get_data`, (中文(简体) ), `set_data`, (中文(简体) ), `remove_data`每项能力必须明确批准 **财务报告和审定财务报表** 范围为 `(domain, name)` 双对调用网络视图允许触摸。 一个空的瞄准镜通过设计拒绝了每一个呼叫.

仅需要的最小能力 `status` 编号 : `authenticate`数字 :

```json
{
  "identifier": "default",
  "windows": ["main"],
  "permissions": ["core:default", "biometry:default"]
}
```

读取/写入单个域的能力:

```json
{
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "biometry:default",
    {
      "identifier": "biometry:allow-has-data",
      "allow": [{ "domain": "com.myapp.creds" }]
    },
    {
      "identifier": "biometry:allow-get-data",
      "allow": [{ "domain": "com.myapp.creds" }]
    },
    {
      "identifier": "biometry:allow-set-data",
      "allow": [{ "domain": "com.myapp.creds" }]
    },
    {
      "identifier": "biometry:allow-remove-data",
      "allow": [{ "domain": "com.myapp.creds" }]
    }
  ]
}
```

范围条目形状 :

-   `{ "domain": "com.example" }` - 匹配每一个 `name` 在那个领域.
-   `{ "domain": "com.example", "name": "session-token" }` - 准确匹配在 `(domain, name)`。 。 。 .
-   每个存储权限也支持一个 `deny` 使用相同形状的数组. `deny` 于 `allow`。 。 。 .

## 使用量

### 检查生物测量状态

```typescript
import { checkStatus } from '@choochmeque/tauri-plugin-biometry-api';

const status = await checkStatus();
console.log('Biometry available:', status.isAvailable);
console.log('Biometry type:', status.biometryType); // 0: None, 1: TouchID, 2: FaceID, 3: Iris, 4: Auto (Windows Hello)

if (status.error) {
  console.error('Error:', status.error);
  console.error('Error code:', status.errorCode);
}
```

### 认证

```typescript
import { authenticate } from '@choochmeque/tauri-plugin-biometry-api';

try {
  await authenticate('Please authenticate to continue', {
    allowDeviceCredential: true,
    cancelTitle: 'Cancel',
    fallbackTitle: 'Use Passcode',
    title: 'Authentication Required',
    subtitle: 'Access your secure data',
    confirmationRequired: false
  });
  console.log('Authentication successful');
} catch (error) {
  console.error('Authentication failed:', error);
}
```

### 存储安全数据

```typescript
import { setData, getData, hasData, removeData } from '@choochmeque/tauri-plugin-biometry-api';

// Store data with biometric protection
await setData({
  domain: 'com.myapp',
  name: 'api_key',
  data: 'secret-api-key-123'
});

// Check if data exists
const exists = await hasData({
  domain: 'com.myapp',
  name: 'api_key'
});

// Retrieve data (will prompt for biometric authentication)
if (exists) {
  const response = await getData({
    domain: 'com.myapp',
    name: 'api_key',
    reason: 'Access your API key'
  });
  console.log('Retrieved data:', response.data);
}

// Remove data
await removeData({
  domain: 'com.myapp',
  name: 'api_key'
});
```

## API 参考

### 类型

```typescript
enum BiometryType {
  None = 0,
  TouchID = 1,
  FaceID = 2,
  Iris = 3,
  Auto = 4  // Windows Hello (auto-detects available biometry)
}

interface Status {
  isAvailable: boolean;
  biometryType: BiometryType;
  error?: string;
  errorCode?: string;
}

interface AuthOptions {
  allowDeviceCredential?: boolean;  // Allow fallback to device passcode
  cancelTitle?: string;              // iOS/Android: Cancel button text
  fallbackTitle?: string;            // iOS only: Fallback button text
  title?: string;                    // Android only: Dialog title
  subtitle?: string;                 // Android only: Dialog subtitle
  confirmationRequired?: boolean;    // Android only: Require explicit confirmation
}
```

### 职能

#### `checkStatus(): Promise<Status>`

检查设备上是否有生物鉴别认证.

#### `authenticate(reason: string, options?: AuthOptions): Promise<void>`

提示用户进行生物鉴别认证.

#### `hasData(options: DataOptions): Promise<boolean>`

检查给定域和名称的安全数据是否存在 .

#### `getData(options: GetDataOptions): Promise<DataResponse>`

在生物鉴别认证后检索安全数据.

#### `setData(options: SetDataOptions): Promise<void>`

储存有生物鉴别保护的数据.

#### `removeData(options: RemoveDataOptions): Promise<void>`

删除安全数据.

## 平台差异

### iOS系统

-   支持触摸 ID 和 Face ID
-   要求数 `NSFaceIDUsageDescription` 在face ID 的 Info.plist 列表中
-   后退按钮可以被定制 `fallbackTitle`

### 机器人

-   支持指纹,相貌和虹膜识别.
-   对话框外观可以定制 `title` 财务报告和审定财务报表 `subtitle`,以及 `confirmationRequired` 执行明确的确认.
-   存储为每`(domain, name)`:新鲜的AES-256密钥用AES-GCM和随机的12字节IV加密有效载荷,AES密钥由AndroidKeyStore所持有的每张记录4096位的RSA密钥包接而来,将OAEP与SHA-256作为OAEP文摘,将SHA-1作为MGF1文摘(SHA-1 MGF1与AndroidKeyStore的内部默认相匹配;SHA-256是保护OAEP建筑的方法. RSA 密钥为 认证 `setUserAuthenticationRequired(true)`和 `setInvalidatedByBiometricEnrollment(true)`因此,改变注册生物鉴别 无效记录.
-   凯斯多尔的别名是 `biometry_` + SHA-256六进制 `len(domain):domain:name`,那么不一样 `(domain, name)` 记录从不共享密钥输入,不同域下的同名记录也从不碰撞.
-   AES-GCM AAD 将每个密码文本绑入 `(version, algorithm-id, domain, name)`,所以存储的blob不能在不同的下重放 `(domain, name)` 或在未来算法改变之后.
-   加密的blobs和被包裹的密钥生活在两个云备份中都不包括的首选项数据库中(`dataExtractionRules`)和装置对设备的转移.
-   `domain` 财务报告和审定财务报表 `name` 在每一次召唤中,都证实那是不空的, `domain` 64个字符和匹配 `[A-Za-z0-9._-]`, (中文(简体) ), `name` 256个字符.

### 马科斯

-   支持触摸 ID
-   安全数据存储的全键链集成
-   一致性与 iOS 相同 API
-   需要用户认证数据访问
-   **重要内容:** 该应用程序必须经过适当的代码签名才能使用密钥链数据存储. 如果没有适当的签名,数据存储操作可能会出错而失败

### 窗口

-   支持Windows Hello(指印,相貌,PIN). 回返 `BiometryType.Auto` 因为你好选择模式.
-   存储使用 WebAuthn API (`webauthn.dll`与 `hmac-secret` / PRF 扩展为密钥衍生源. 每人录入一个 Hello-ball 证书 `(app-identifier, domain)`;32字节的PRF输出被直接用作AES-256-GCM密钥(这是HMAC-SHA-256输出,已经是256个统一的密钥,所以顶部的KDF会是多余的). 被记录的独特性来自新鲜的32字节随机盐(PRF输入)和新鲜的12字节随机IV与密码并存.
-   AES-GCM AAD 将每个密码文本绑入 `(version, domain, name, salt, credential_id)`,所以存储的blob不能在不同的下重放 `name`编号 :`domain` 在金库里.
-   `authenticate` 父母 呼叫 Tauri 窗口的 Hello 对话框通过 `IUserConsentVerifierInterop::RequestVerificationForWindowAsync`因此,提示总是在顶端.
-   **所需经费:** Windows 11带有WebAuthn API ≥ v8(创建时间PRF eval需要)和一个用户验证平台认证器. `checkStatus()` 报告前的探测器 `isAvailable`。 。 。 .
-   **第一套数据/ 每 `(app-identifier, domain)`** 一次显示 Windows 的“ 保存您的密码” 同意对话框—— 这就是正在注册的平台证书 。 后续 `setData`编号 :`getData` 在同一域上只显示生物鉴别/PIN提示.
-   `removeData` 在最后一个时删除基本的 WebAuthn 证书 `name` 在一个域中被删除,所以密码列表保持干净.

## 错误代码

插件返回的常见错误代码 :

-   `userCancel` - 用户取消了认证
-   `authenticationFailed` - 认证失败(生物鉴别错误)
-   `biometryNotAvailable` - 设备上没有生物计量
-   `biometryNotEnrolled` - 没有生物鉴别数据
-   `biometryLockout` - 太多失败的尝试,生物测量被锁定
-   `systemCancel` - 系统取消了操作( 设备繁忙)
-   `appCancel` - 应用程序取消了操作
-   `invalidContext` - 无效的认证上下文
-   `notInteractive` - 不允许非交互式认证
-   `passcodeNotSet` - 未设置设备密码
-   `userFallback` - 用户选择使用倒置认证
-   `itemNotFound` - 未找到关键链项(macOS/iOS)
-   `authenticationRequired` - 需要认证,但不允许用户界面交互
-   `keychainError` - 通用密钥链操作错误
-   `internalError` - 内部插件出错
-   `notSupported` - 在这个平台上不支持操作
-   `scopeDenied` - 请求 `(domain, name)` 不在能力范围内 `allow` 列表(或为 `deny`(中文(简体) )
-   `dataNeedsReenrollment` - 存储的Windows blob来自前一个插件版本,在重新存储前必须删除

## 安全考虑

-   所有安全数据存储在系统密钥链(macOS/iOS),Android Keystore,或Windows证书管理器中
-   数据被加密,只有在生物鉴别认证成功后才能访问
-   该插件遵循特定平台的安全最佳做法
-   Windows使用AES-256-GCM,其密钥取自于Windows Hello证书的WebAuthn `hmac-secret` / PRF 输出; 密码文本绑定到 `(version, domain, name, salt, credential_id)` 通过AES-GCM AAD
-   Android使用AES-256-GCM,并用每张AndroidKeyStore RSA-4096密钥用OAEP(SHA-256文摘,MGF1 SHA-1-匹配AndroidKeyStore内部的MGF1)包裹了新鲜的每张记录的AES密钥;包接密钥是认证并具有生物鉴别功能的;密钥被绑定于OAEP `(version, algorithm-id, domain, name)` 通过 AES-GCM AAD,DataStore 文件被排除在云备份和设备传输之外
-   许可范围界定(见 _权限_ (上文)是主要授权边界——只有 `(domain, name)` 以能力申报的对数 `allow` 即使 `biometry:allow-get-data` 授予等
-   **macOS 代码签名 :** 您的应用程序必须经过适当的代码签名才能在macOS上使用密钥链存储. 开发架构可能与临时签名相配合,但生产应用程序需要有效的开发者ID或App Store签名
-   考虑对高度敏感数据实施额外的应用级加密

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 许可证

这个项目根据麻省理工学院的许可证获得许可.

## 承认

与 [陶里语Name](https://tauri.app/) - 盖得更小,更快 和具有网络前端的更安全的桌面应用程序.

## 常见问题

### @choochmeque/tauri-plugin-biometry-api 是什么？

一个Tauri v2插件,用于Android,macOS,iOS和Windows上的生物鉴别认证\(Touch ID,Face ID,指纹\)\.

### 如何安装 @choochmeque/tauri-plugin-biometry-api？

在项目目录运行 npm install @choochmeque/tauri-plugin-biometry-api，或使用 pnpm add / yarn add / bun add。

### @choochmeque/tauri-plugin-biometry-api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @choochmeque/tauri-plugin-biometry-api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @choochmeque/tauri-plugin-biometry-api 可以商用吗？

@choochmeque/tauri-plugin-biometry-api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @choochmeque/tauri-plugin-biometry-api 的下载量有多少？

根据 npm 官方下载统计，@choochmeque/tauri-plugin-biometry-api 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,700 次，日均约 190 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @choochmeque/tauri-plugin-biometry-api 还在维护吗？

最新版本 0\.3\.0-rc\.3 发布于 2026/09/01（2 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/09/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。