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:

• First run bap list on the master backup

• Note the index of the desired identity

• 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:

• Try with bap-cli first:

bap list problematic.bep --password password

• If that fails, try bbackup for more details:

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

• 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

• Verify tools are installed:

which bap bbackup

• 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

• 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