身份认证
定义用户身份验证机制规范
认证类型说明
本应用涉及两种不同的认证概念，必须明确区分：
钱包锁 (Wallet Lock)
| 属性 | 说明 |
|---|---|
| 作用域 | 本地应用层面 |
| 用途 | 加密存储在设备上的助记词/私钥 |
| 存储位置 | 不存储，仅用于派生加密密钥 |
| 设置时机 | 创建/导入钱包时设置 |
| 使用场景 | 解锁钱包、查看助记词、导出私钥 |
| 是否可修改 | 是（需验证原图案） |
| 与链的关系 | 无关，纯本地 |
| 是否必需 | 取决于平台能力（见下方说明） |
| 实现形式 | 九宫格图案锁 (3x3 Pattern Lock) |
关于必要性：钱包锁的本质是应用级加密保护。如果设备提供了原生的安全存储（如 iOS Keychain with Secure Enclave、Android Keystore with TEE），理论上可以不需要用户设置钱包锁，直接使用硬件级加密。目前为了实现 Web 适配器而要求设置。
交易密码 / 二次签名 (Pay Password / Second Signature)
| 属性 | 说明 |
|---|---|
| 作用域 | 链上层面（仅 BioForest 链） |
| 用途 | 交易的二次签名，防止私钥泄露后资产被盗 |
| 存储位置 | 链上存储 secondPublicKey |
| 设置时机 | 用户主动设置（可选） |
| 使用场景 | 每次转账时需要额外输入 |
| 是否可修改 | 否（链上不可变） |
| 与链的关系 | 链上记录，交易需要 signSignature 字段 |
关系图
┌─────────────────────────────────────────────────────────────────┐
│ 用户视角 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 创建钱包 ──► 设置【钱包锁图案】──► 加密助记词存储到设备 │
│ │
│ 设置二次签名 ──► 设置【安全密码】──► 链上记录 secondPublicKey │
│ │
│ 转账时: │
│ 1. 绘制【钱包锁图案】解锁助记词 │
│ 2. 如有二次签名，还需输入【安全密码】 │
│ │
└─────────────────────────────────────────────────────────────────┘开发注意事项
- MUST 在 UI 中使用不同的术语区分两者
- MUST NOT 混淆
walletLock/patternKey和twoStepSecret变量命名 - SHOULD 钱包锁使用图案锁组件，安全密码使用密码输入框
- SHOULD 检查
secondPublicKey存在时才请求安全密码
认证方式
| 方式 | 场景 | 安全级别 | 便捷性 |
|---|---|---|---|
| 图案锁 | 首次解锁、敏感操作 | 高 | 中 |
| 生物识别 | 日常解锁、快捷支付 | 高 | 高 |
应用锁规范
锁定状态
| 状态 | 说明 |
|---|---|
| locked | 已锁定，需要认证 |
| unlocked | 已解锁，可正常使用 |
状态数据
| 字段 | 类型 | 说明 |
|---|---|---|
| isLocked | boolean | 当前锁定状态 |
| isWalletLockEnabled | boolean | 是否启用钱包锁 |
| isBiometricEnabled | boolean | 是否启用生物识别 |
| lastUnlockTime | timestamp | 上次解锁时间 |
| autoLockTimeout | number | 自动锁定时间（分钟） |
解锁流程
用户打开应用
│
▼
检查是否启用锁定
│
├── 未启用 ──► 直接进入
│
└── 已启用
│
▼
检查生物识别是否可用
│
├── 可用 ──► 提示指纹/面容解锁
│ │
│ ├── 成功 ──► 解锁
│ │
│ └── 失败 ──► 回退图案锁
│
└── 不可用 ──► 显示图案锁
│
├── 正确 ──► 解锁
│
└── 错误 ──► 显示错误 + 重试自动锁定规范
触发条件
| 条件 | 说明 | 可配置 |
|---|---|---|
| 超时无操作 | 设定时间内无用户活动 | 是 |
| 应用切后台 | 应用进入后台 | 是 |
| 屏幕锁定 | 设备屏幕锁定 | 否 |
超时选项
| 选项 | 默认 |
|---|---|
| 1 分钟 | |
| 5 分钟 | ✓ |
| 15 分钟 | |
| 30 分钟 | |
| 从不 |
活动监听
以下用户活动 SHOULD 重置超时计时器：
- 触摸/点击事件
- 滚动事件
- 键盘输入
- 导航操作
生物识别认证规范
支持类型
| 类型 | 平台 |
|---|---|
| 指纹 (Touch ID) | iOS, Android |
| 面容 (Face ID) | iOS |
| 指纹 (Fingerprint) | Android |
启用流程
用户进入安全设置
│
▼
开启"生物识别解锁"
│
▼
验证钱包锁图案 ← 确保用户是钱包所有者
│
├── 图案错误 ──► 显示错误
│
└── 图案正确
│
▼
检查设备生物识别可用性
│
├── 不可用 ──► 显示提示
│
└── 可用
│
▼
验证生物识别
│
├── 成功 ──► 启用功能
│
└── 失败 ──► 显示错误认证要求
- MUST 启用前验证钱包锁图案
- MUST 检查设备是否支持生物识别
- MUST 提供回退到图案锁的选项
- SHOULD 显示生物识别类型名称
- SHOULD 记录启用状态到安全存储
转账确认规范
确认层级
| 操作 | 认证要求 |
|---|---|
| 查看余额 | 无需认证 |
| 查看地址 | 无需认证 |
| 小额转账 | 生物识别 |
| 大额转账 | 图案锁 |
| 查看助记词 | 图案锁 |
| 删除钱包 | 图案锁 |
确认流程
用户发起转账
│
▼
判断金额级别
│
├── 大额（>阈值）──► 强制图案锁验证
│
└── 小额
│
▼
检查生物识别是否启用
│
├── 已启用 ──► 生物识别验证
│ │
│ ├── 成功 ──► 执行转账
│ │
│ └── 失败 ──► 回退图案锁
│
└── 未启用 ──► 图案锁验证大额阈值配置
- SHOULD 支持用户自定义阈值
- SHOULD 按币种设置不同阈值
- MAY 提供建议阈值
图案锁验证规范
验证方式
通过尝试解密钱包助记词验证图案：
用户绘制图案
│
▼
使用图案派生解密密钥
│
▼
尝试解密助记词
│
├── 解密失败 ──► 图案错误
│
└── 解密成功 ──► 图案正确安全要求
- MUST 使用 AES-GCM 的认证标签验证
- MUST NOT 存储图案哈希值
- MUST NOT 在日志中记录图案
- SHOULD 限制连续错误次数
- MUST 最少连接 4 个点
安全设置页面规范
设置项
| 设置 | 类型 | 依赖 |
|---|---|---|
| 钱包锁 | 开关 | - |
| 生物识别解锁 | 开关 | 钱包锁已启用 |
| 自动锁定时间 | 选择 | 钱包锁已启用 |
| 后台锁定 | 开关 | 钱包锁已启用 |
| 修改钱包锁 | 按钮 | - |
依赖关系
- 生物识别解锁 MUST 在钱包锁启用后才能开启
- 关闭钱包锁 MUST 同时关闭生物识别
- 自动锁定时间 SHOULD 在钱包锁关闭时禁用
钱包锁验证 UI 模式
本应用提供两种钱包锁验证的 UI 模式，需要根据使用场景选择合适的模式：
页面级别验证 (Full Page)
适用场景：
- 验证是主要流程的一部分，用户预期会进入一个新页面
- 验证后有后续操作需要在同一页面完成
- 需要更多上下文信息展示
具体场景：
| 页面 | 说明 |
|---|---|
| 修改钱包锁 | 验证当前图案 → 设置新图案（两步流程在同一页面） |
| 管理钱包网络 | 选择网络 → 验证图案 → 保存（多步骤流程） |
| 查看助记词 | 验证后需要在页面内展示助记词 |
UI 特征：
- 全屏页面，有返回按钮
- 可以有多个步骤
- 支持复杂的状态展示
底部抽屉验证 (Bottom Sheet)
适用场景：
- 验证是即时确认，用户只需要验证身份即可
- 验证后立即执行操作并关闭
- 需要保持上下文，不离开当前页面
具体场景：
| 场景 | 说明 |
|---|---|
| 转账确认 | 用户在转账页面，弹出验证后执行转账 |
| 删除钱包 | 在钱包详情页，确认删除操作 |
| 二次签名设置 | 验证身份后立即执行链上操作 |
UI 特征：
- 底部弹出，支持手势关闭
- 单一步骤，验证成功后自动关闭
- 保持父页面可见
选择决策树
需要钱包锁验证？
│
▼
验证后是否有后续操作？
│
├── 是 ──► 验证后需要停留在页面操作？
│ │
│ ├── 是 ──► 使用【页面级别验证】
│ │
│ └── 否 ──► 使用【底部抽屉验证】
│
└── 否（即时确认）──► 使用【底部抽屉验证】实现组件
| 模式 | 组件 | 路径 |
|---|---|---|
| 页面级别 | PatternLock | 直接在页面中使用 |
| 底部抽屉 | WalletLockConfirmJob | @/stackflow/activities/sheets |
使用示例
页面级别验证：
tsx
// 在页面组件中直接使用 PatternLock
<PatternLock
value={pattern}
onChange={setPattern}
onComplete={handleVerify}
error={verifyError}
/>底部抽屉验证：
tsx
// 设置回调并推送 Sheet
import { setWalletLockConfirmCallback } from '@/stackflow/activities/sheets';
setWalletLockConfirmCallback(async (patternKey) => {
const isValid = await verifyPattern(encryptedMnemonic, patternKey);
if (isValid) {
// 执行操作
await doSomething();
}
return isValid;
});
push('WalletLockConfirmJob', { title: '验证钱包锁' });错误处理规范
认证错误
| 错误类型 | 处理方式 |
|---|---|
| 图案错误 | 显示错误动画 + 清空输入 |
| 生物识别取消 | 显示图案锁 |
| 生物识别失败 | 提示重试或使用图案锁 |
| 生物识别锁定 | 强制使用图案锁 |
错误次数限制
- SHOULD 连续错误后增加延迟
- SHOULD 错误次数过多时临时锁定
- MAY 支持错误通知（邮件/推送）
本章小结
- 支持图案锁和生物识别两种认证方式
- 自动锁定保护用户资产安全
- 生物识别提升日常使用便捷性
- 分层安全：日常操作用生物识别，敏感操作要图案锁
- 完善的错误处理和回退机制