bap-identity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BAP Identity Management

BAP 身份管理

Overview

概述

This skill enables comprehensive management of BAP (Bitcoin Attestation Protocol) identity files using two complementary command-line tools:

bap-cli: High-level BAP identity operations (create, list, extract member identities)
bbackup: Low-level encryption/decryption of any JSON backup data

Use this skill when working with encrypted BAP identity backups (.bep files), creating new identities, extracting member identities, encrypting/decrypting JSON files, or generating test fixtures.

本技能通过两个互补的命令行工具，实现对BAP（Bitcoin Attestation Protocol）身份文件的全面管理：

bap-cli：高级BAP身份操作（创建、列出、提取成员身份）
bbackup：对任意JSON备份数据进行底层加密/解密

在处理加密BAP身份备份（.bep文件）、创建新身份、提取成员身份、加密/解密JSON文件或生成测试夹具时，可使用本技能。

Prerequisites

前提条件

Required Tools

所需工具

Verify both tools are installed:

bash

bap --version
bbackup --version

验证以下两个工具已安装：

bash

bap --version
bbackup --version

Installing bap-cli

安装bap-cli

bash

git clone https://github.com/b-open-io/bap-cli.git
cd bap-cli
bun install
bun run build
bun link

bash

git clone https://github.com/b-open-io/bap-cli.git
cd bap-cli
bun install
bun run build
bun link

Installing bbackup

安装bbackup

bash

git clone https://github.com/rohenaz/bitcoin-backup.git
cd bitcoin-backup
bun install
bun run build
bun link

bash

git clone https://github.com/rohenaz/bitcoin-backup.git
cd bitcoin-backup
bun install
bun run build
bun link

Tool Selection Guide

工具选择指南

Choose the appropriate tool based on the task:

根据任务选择合适的工具：

Use bap-cli when:

以下场景使用bap-cli：

Creating new BAP identities
Listing identities in a master backup
Extracting member identities from master backup
Working specifically with BAP identity structures
Generating test fixtures for automated tests

创建新的BAP身份
列出主备份中的身份
从主备份中提取成员身份
专门处理BAP身份结构
为自动化测试生成测试夹具

Use bbackup when:

以下场景使用bbackup：

Encrypting arbitrary JSON data to .bep format
Decrypting .bep files to inspect contents
Upgrading encryption strength (100k → 600k iterations)
Working with non-BAP backup formats (WifBackup, OneSatBackup, VaultBackup)
Need lower-level control over encryption parameters

将任意JSON数据加密为.bep格式
解密.bep文件以查看内容
升级加密强度（10万 → 60万迭代次数）
处理非BAP备份格式（WifBackup、OneSatBackup、VaultBackup）
需要对加密参数进行底层控制

Use both when:

以下场景同时使用两者：

Inspecting BAP identities created by bap-cli
Re-encrypting backups with different passwords
Migrating between encryption strengths
Debugging backup file issues

检查由bap-cli创建的BAP身份
使用不同密码重新加密备份
在不同加密强度间迁移备份
调试备份文件问题

Core Operations with bap-cli

bap-cli核心操作

Creating New Identity Backups

创建新身份备份

When users request a new BAP identity, use the

bap new

command with appropriate backup type:

Type42 backups (recommended for simplicity):

Use random root private key
Simpler key management
Suitable for most use cases

bash

bap new --type type42 --password <password> --name "<name>" --output <file.bep>

Legacy (BIP32) backups (for hierarchical deterministic wallets):

Use HD derivation from mnemonic
Generates BIP32 mnemonic phrase
Required when mnemonic recovery is needed

bash

bap new --type legacy --password <password> --name "<name>" --output <file.bep>

Important: Always use strong passwords. The password encrypts the backup file and cannot be recovered if lost.

当用户需要新的BAP身份时，使用

bap new

命令并选择合适的备份类型：

Type42备份（推荐用于简单场景）：

使用随机根私钥
密钥管理更简单
适用于大多数使用场景

bash

bap new --type type42 --password <password> --name "<name>" --output <file.bep>

传统（BIP32）备份（用于分层确定性钱包）：

从助记词进行HD衍生
生成BIP32助记词短语
当需要助记词恢复时必须使用

bash

bap new --type legacy --password <password> --name "<name>" --output <file.bep>

重要提示：务必使用强密码。密码用于加密备份文件，丢失后无法恢复。

Listing Identities

列出身份

When users need to see what identities are in a backup file, use

bap list

bash

bap list <backup.bep> --password <password>

This displays:

All identity keys with their indices
Backup type (Type42 or Legacy)
Number of identities in the backup

Use this before extracting member identities to determine the correct index.

当用户需要查看备份文件中的身份时，使用

bap list

：

bash

bap list <backup.bep> --password <password>

该命令会显示：

所有带索引的身份密钥
备份类型（Type42或传统）
备份中的身份数量

在提取成员身份前使用此命令，以确定正确的索引。

Extracting Member Identities

提取成员身份

When users need to extract a single identity from a master backup (common for distributing individual identities), use

bap member

bash

bap member <master.bep> --password <password> --index <index> --output <member.bep>

The index is zero-based. To find the correct index:

First run
```
bap list
```
on the master backup
Note the index of the desired identity
Extract using that index

当用户需要从主备份中提取单个身份（常用于分发独立身份）时，使用

bap member

：

bash

bap member <master.bep> --password <password> --index <index> --output <member.bep>

索引从0开始。查找正确索引的步骤：

首先对主备份运行
```
bap list
```
记录目标身份的索引
使用该索引进行提取

Decrypting and Inspecting Backups

解密并检查备份

When users need to view the contents of an encrypted backup, use

bap export

bash

bap export <backup.bep> --password <password>

This outputs the decrypted JSON structure. Use this to:

Debug backup issues
Verify backup contents
Inspect identity structure

Optionally save re-encrypted version:

bash

bap export <backup.bep> --password <password> --output <new.bep>

当用户需要查看加密备份的内容时，使用

bap export

：

bash

bap export <backup.bep> --password <password>

该命令会输出解密后的JSON结构。可用于：

调试备份问题
验证备份内容
检查身份结构

可选保存重新加密的版本：

bash

bap export <backup.bep> --password <password> --output <new.bep>

Core Operations with bbackup

bbackup核心操作

Encrypting JSON Files

加密JSON文件

When users have JSON data that needs encryption:

bash

bbackup enc <input.json> -p <password> [-o <output.bep>]

Use cases:

Encrypting manually created backup JSON
Encrypting exported identity data
Creating custom encrypted payloads

Example:

bash

undefined

当用户需要加密JSON数据时：

bash

bbackup enc <input.json> -p <password> [-o <output.bep>]

使用场景：

加密手动创建的备份JSON
加密导出的身份数据
创建自定义加密负载

示例：

bash

undefined

Create JSON file

创建JSON文件

echo '{"wif":"L5EZftvrYa...","label":"My Key"}' > wallet.json

Encrypt it

加密文件

bbackup enc wallet.json -p "strongpass" -o wallet.bep

undefined

bbackup enc wallet.json -p "strongpass" -o wallet.bep

undefined

Decrypting to JSON

解密为JSON

When users need to inspect encrypted .bep files:

bash

bbackup dec <input.bep> -p <password> [-o <output.json>]

Use cases:

Inspecting backup contents
Debugging encrypted files
Extracting data for processing

Example:

bash

undefined

当用户需要查看加密的.bep文件时：

bash

bbackup dec <input.bep> -p <password> [-o <output.json>]

使用场景：

检查备份内容
调试加密文件
提取数据用于处理

示例：

bash

undefined

Decrypt to JSON

解密为JSON

bbackup dec identity.bep -p "password" -o identity.json

View contents

查看内容

cat identity.json

undefined

cat identity.json

undefined

Upgrading Encryption Strength

升级加密强度

When users have older backups with weaker encryption (100k iterations):

bash

bbackup upg <old.bep> -p <password> -o <upgraded.bep>

This upgrades to 600,000 PBKDF2 iterations (NIST recommended).

Use cases:

Strengthening security of existing backups
Migrating legacy backups
Preparing backups for long-term storage

当用户拥有加密强度较弱的旧备份（10万迭代次数）时：

bash

bbackup upg <old.bep> -p <password> -o <upgraded.bep>

此命令会升级为60万次PBKDF2迭代（NIST推荐标准）。

使用场景：

增强现有备份的安全性
迁移传统备份
为长期存储准备备份

Combined Workflows

组合工作流

Inspect BAP Identity Using bbackup

使用bbackup检查BAP身份

When users need to examine a BAP identity created by bap-cli:

bash

undefined

当用户需要检查由bap-cli创建的BAP身份时：

bash

undefined

Create identity with bap-cli

使用bap-cli创建身份

bap new --type type42 --password pass123 --name "Alice" --output alice.bep

Decrypt with bbackup to inspect

使用bbackup解密以检查

bbackup dec alice.bep -p pass123 -o alice.json

View the JSON structure

查看JSON结构

cat alice.json

Shows: { "ids": "...", "rootPk": "...", "label": "Alice", "createdAt": "..." }

输出内容：{ "ids": "...", "rootPk": "...", "label": "Alice", "createdAt": "..." }


This is useful for:
- Understanding the internal structure
- Debugging identity issues
- Verifying backup contents
- Extracting specific fields programmatically


此操作可用于：
- 理解内部结构
- 调试身份问题
- 验证备份内容
- 以编程方式提取特定字段

Change Password on BAP Identity

修改BAP身份的密码

When users need to re-encrypt a backup with a different password:

bash

undefined

当用户需要使用不同密码重新加密备份时：

bash

undefined

Decrypt with old password

使用旧密码解密

bbackup dec identity.bep -p "oldpass" -o identity.json

Re-encrypt with new password

使用新密码重新加密

bbackup enc identity.json -p "newpass" -o identity-new.bep

Clean up temporary file

清理临时文件

rm identity.json

undefined

rm identity.json

undefined

Upgrade Security of BAP Backup

升级BAP备份的安全性

When users have older BAP identities that need stronger encryption:

bash

undefined

当用户拥有需要更强加密的旧BAP身份时：

bash

undefined

Upgrade directly (maintains same password)

直接升级（保持密码不变）

bbackup upg old-identity.bep -p "password" -o identity-upgraded.bep

Verify it works with bap-cli

使用bap-cli验证可用性

bap list identity-upgraded.bep --password password

undefined

bap list identity-upgraded.bep --password password

undefined

Extract and Transform Member Identity

提取并转换成员身份

When users need to extract and modify a member identity:

bash

undefined

当用户需要提取并修改成员身份时：

bash

undefined

Extract member with bap-cli

使用bap-cli提取成员

bap member master.bep --password pass --index 0 --output member.bep

Decrypt to JSON with bbackup

使用bbackup解密为JSON

bbackup dec member.bep -p pass -o member.json

Modify JSON as needed (e.g., change label)

根据需要修改JSON（例如，更改标签）

... manual editing or script ...

... 手动编辑或脚本处理 ...

Re-encrypt modified version

重新加密修改后的版本

bbackup enc member.json -p pass -o member-modified.bep

undefined

bbackup enc member.json -p pass -o member-modified.bep

undefined

Debug Backup Issues

调试备份问题

When users encounter problems with backups:

Try with bap-cli first:

bash

bap list problematic.bep --password password

If that fails, try bbackup for more details:

bash

bbackup dec problematic.bep -p password -o debug.json

Inspect the JSON structure:

bash

cat debug.json | jq .  # Pretty print if jq is available

当用户遇到备份相关问题时：

首先尝试使用bap-cli：

bash

bap list problematic.bep --password password

如果失败，尝试使用bbackup获取更多详情：

bash

bbackup dec problematic.bep -p password -o debug.json

检查JSON结构：

bash

cat debug.json | jq .  # 如果安装了jq，可格式化输出

Test Fixture Generation (Programmatic)

测试夹具生成（编程方式）

When users need BAP identities for Playwright or automated testing, use the programmatic API:

typescript

import { createType42Backup } from "bap-cli";

// Generate backup with multiple test identities
const backup = await createType42Backup("testpassword123", [
  { name: "Test User 1" },
  { name: "Test User 2" },
]);

// Save to file
await backup.saveTo("/tmp/test-backup.bep");

// Get identity keys for assertions
const keys = await backup.getIdentityKeys();

// Extract member backup for specific identity
const memberBackup = await backup.getMemberBackup(0);

// Clean up temp files when done
await backup.cleanup();

This approach is more efficient than CLI for test automation as it:

Generates identities programmatically
Provides direct access to keys for test assertions
Handles cleanup automatically
Works with multiple identities in a single operation

当用户需要为Playwright或自动化测试生成BAP身份时，使用编程API：

typescript

import { createType42Backup } from "bap-cli";

// 生成包含多个测试身份的备份
const backup = await createType42Backup("testpassword123", [
  { name: "Test User 1" },
  { name: "Test User 2" },
]);

// 保存到文件
await backup.saveTo("/tmp/test-backup.bep");

// 获取身份密钥用于断言
const keys = await backup.getIdentityKeys();

// 提取特定身份的成员备份
const memberBackup = await backup.getMemberBackup(0);

// 完成后清理临时文件
await backup.cleanup();

这种方式比CLI更适合测试自动化，因为：

以编程方式生成身份
直接访问密钥用于测试断言
自动处理清理操作
可在单次操作中处理多个身份

File Format Details

文件格式详情

All BAP identity files use the

.bep

extension (Bitcoin Encrypted Payload):

Master backups (from bap-cli):

Contain root key/xprv and can generate multiple identities

Structure:

{ ids, rootPk/xprv, label?, createdAt? }

Member backups (from bap-cli):

Contain single identity (WIF and identity key)
Structure:
```
{ wif, id, label?, createdAt? }
```

Encryption (used by both tools):

Algorithm: AES-256-GCM
Key derivation: PBKDF2-SHA256
Iterations: 600,000 (recommended) or 100,000 (legacy)
Format: Base64 encoded string

所有BAP身份文件均使用.bep扩展名（Bitcoin Encrypted Payload）：

主备份（来自bap-cli）：

包含根密钥/xprv，可生成多个身份

结构：

{ ids, rootPk/xprv, label?, createdAt? }

成员备份（来自bap-cli）：

包含单个身份（WIF和身份密钥）
结构：
```
{ wif, id, label?, createdAt? }
```

加密方式（两个工具均使用）：

算法：AES-256-GCM
密钥衍生：PBKDF2-SHA256
迭代次数：60万（推荐）或10万（传统）
格式：Base64编码字符串

Error Handling

错误处理

bap-cli Errors

bap-cli错误

"Error: type must be 'legacy' or 'type42'"

Use correct --type flag with valid value

"Error: Invalid index"

Run
```
bap list
```
first to see available indices
Indices are zero-based (first identity is index 0)

Decryption failures

Verify correct password
Ensure file is not corrupted
Check file is actually a .bep backup

"bap: command not found"

Install bap-cli globally using installation steps above

"Error: type must be 'legacy' or 'type42'"

使用正确的--type参数并传入有效值

"Error: Invalid index"

先运行
```
bap list
```
查看可用索引
索引从0开始（第一个身份为索引0）

解密失败

验证密码是否正确
确保文件未损坏
检查文件是否确实是.bep备份

"bap: command not found"

按照上述安装步骤全局安装bap-cli

bbackup Errors

bbackup错误

"Decryption failed"

Wrong password
Corrupted file
Try bap-cli commands if file is BAP-specific

"Invalid backup format"

Input file for
```
enc
```
must be valid JSON
Check JSON syntax:
```
cat file.json | jq .
```

"Password too short"

Minimum 8 characters required
Use 12+ characters for high-value secrets

"Decryption failed"

密码错误
文件损坏
如果文件是BAP专用，尝试使用bap-cli命令

"Invalid backup format"

```
enc
```
命令的输入文件必须是有效的JSON
检查JSON语法：
```
cat file.json | jq .
```

"Password too short"

密码至少需要8个字符
对于高价值机密，使用12个以上字符

General Troubleshooting

通用故障排除

Verify tools are installed:

bash

which bap bbackup

Test basic encryption cycle:

bash

echo '{"test":"data"}' > test.json
bbackup enc test.json -p "testpass" -o test.bep
bbackup dec test.bep -p "testpass" -o out.json
diff test.json out.json  # Should match
rm test.json test.bep out.json

Check file format:

bash

file backup.bep  # Should show ASCII text (base64)
head -c 50 backup.bep  # Should show base64 characters

验证工具是否安装：

bash

which bap bbackup

测试基本加密循环：

bash

echo '{"test":"data"}' > test.json
bbackup enc test.json -p "testpass" -o test.bep
bbackup dec test.bep -p "testpass" -o out.json
diff test.json out.json  # 内容应匹配
rm test.json test.bep out.json

检查文件格式：

bash

file backup.bep  # 应显示ASCII文本（base64）
head -c 50 backup.bep  # 应显示base64字符

Reference Documentation

参考文档

Complete command reference and advanced usage:

bap-cli: See
```
references/bap-cli-reference.md
```
for:
- Detailed command syntax
- All available options
- Programmatic API documentation
- Complete examples
bbackup: See
```
references/bbackup-reference.md
```
for:
- Encryption specifications
- Security features
- Integration patterns
- Troubleshooting guide

完整命令参考和高级用法：

bap-cli：查看
```
references/bap-cli-reference.md
```
获取：
- 详细命令语法
- 所有可用选项
- 编程API文档
- 完整示例
bbackup：查看
```
references/bbackup-reference.md
```
获取：
- 加密规范
- 安全特性
- 集成模式
- 故障排除指南

Common Use Case Patterns

常见使用场景模式

Pattern 1: Create → Inspect → Distribute

模式1：创建 → 检查 → 分发

bash

undefined

bash

undefined

1. Create master identity

1. 创建主身份

bap new --type type42 --password masterpass --name "Org Master" --output master.bep

2. Verify contents

2. 验证内容

bbackup dec master.bep -p masterpass -o master.json cat master.json

3. Extract member for distribution

3. 提取成员身份用于分发

bap member master.bep --password masterpass --index 0 --output member-alice.bep

4. Distribute member.bep to Alice

4. 将member.bep分发给Alice

undefined

undefined

Pattern 2: Import → Upgrade → Export

模式2：导入 → 升级 → 导出

bash

undefined

bash

undefined

1. Receive old backup

1. 接收旧备份

old.bep (using 100k iterations)

old.bep（使用10万迭代次数）

2. Upgrade encryption

2. 升级加密

bbackup upg old.bep -p "password" -o new.bep

3. Verify with BAP tools

3. 使用BAP工具验证

bap list new.bep --password password

undefined

bap list new.bep --password password

undefined

Pattern 3: Generate → Test → Cleanup

模式3：生成 → 测试 → 清理

typescript

// In test file
const backup = await createType42Backup("testpass", [
  { name: "Test Identity" }
]);

await backup.saveTo("/tmp/test.bep");

// Run tests using /tmp/test.bep

await backup.cleanup();  // Removes temp files

typescript

// 在测试文件中
const backup = await createType42Backup("testpass", [
  { name: "Test Identity" }
]);

await backup.saveTo("/tmp/test.bep");

// 使用/tmp/test.bep运行测试

await backup.cleanup();  // 删除临时文件