Bap Identity

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

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

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

3. 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 operation

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

Error Handling

bap-cli Errors

"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

bbackup Errors

"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

General Troubleshooting

1. Verify tools are installed:

which bap bbackup

2. Test basic encryption cycle:

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

3. Check file format:

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

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

Common Use Case Patterns

Pattern 1: Create → Inspect → Distribute

# 1. Create master identity
bap new --type type42 --password masterpass --name "Org Master" --output master.bep

# 2. Verify contents
bbackup dec master.bep -p masterpass -o master.json
cat master.json

# 3. Extract member for distribution
bap member master.bep --password masterpass --index 0 --output member-alice.bep

# 4. Distribute member.bep to Alice

Pattern 2: Import → Upgrade → Export

# 1. Receive old backup
# old.bep (using 100k iterations)

# 2. Upgrade encryption
bbackup upg old.bep -p "password" -o new.bep

# 3. Verify with BAP tools
bap list new.bep --password password

Pattern 3: Generate → Test → Cleanup

// 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