bap-identity

BAP Identity Management

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.

Prerequisites

Required Tools

Verify both tools are installed:

bap --version
bbackup --version

Installing bap-cli

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

Installing bbackup

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:

• 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

Use bbackup when:

• 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

Use both when:

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

Core Operations with 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

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

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.

Listing Identities

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

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.

Extracting Member Identities

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

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

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

1. First run bap list on the master backup
2. Note the index of the desired identity
3. Extract using that index

Decrypting and Inspecting Backups

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

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:

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

Core Operations with bbackup

Encrypting JSON Files

When users have JSON data that needs encryption:

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:

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

# Encrypt it
bbackup enc wallet.json -p "strongpass" -o wallet.bep

Decrypting to JSON

When users need to inspect encrypted .bep files:

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

Use cases:

• Inspecting backup contents
• Debugging encrypted files
• Extracting data for processing

Example:

# Decrypt to JSON
bbackup dec identity.bep -p "password" -o identity.json

# View contents
cat identity.json

Upgrading Encryption Strength

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

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

Combined Workflows

Inspect BAP Identity Using bbackup

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

# Create identity with bap-cli
bap new --type type42 --password pass123 --name "Alice" --output alice.bep

# Decrypt with bbackup to inspect
bbackup dec alice.bep -p pass123 -o alice.json

# View the JSON structure
cat alice.json

# Shows: { "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

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

# 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

Upgrade Security of BAP Backup

When users have older BAP identities that need stronger encryption:

# Upgrade directly (maintains same password)
bbackup upg old-identity.bep -p "password" -o identity-upgraded.bep

# Verify it works with bap-cli
bap list identity-upgraded.bep --password password

Extract and Transform Member Identity

When users need to extract and modify a member identity:

# Extract member with bap-cli
bap member master.bep --password pass --index 0 --output member.bep

# Decrypt to JSON with bbackup
bbackup dec member.bep -p pass -o member.json

# Modify JSON as needed (e.g., change label)
# ... manual editing or script ...

# Re-encrypt modified version
bbackup enc member.json -p pass -o member-modified.bep

Debug Backup Issues

When users encounter problems with backups:

1. Try with bap-cli first:

bap list problematic.bep --password password

1. If that fails, try bbackup for more details:

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

1. Inspect the JSON structure:

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

Test Fixture Generation (Programmatic)

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

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 oper