@microck/bap-identity

---
version: 1.0.1
name: bap-identity
description: Manage BAP (Bitcoin Attestation Protocol) identity files using bap-cli. This skill should be used when users need to create, decrypt, list, or extract BAP identity backups, work with .bep encrypted files, or generate test fixtures for Playwright tests involving BAP identities.
location: user
---

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

```bash
bap --version
bbackup --version
```

### Installing bap-cli

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

### Installing bbackup

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

```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.

### 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.

### 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:
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`:

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

## Core Operations with bbackup

### Encrypting JSON Files

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

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

**Use cases:**
- Inspecting backup contents
- Debugging encrypted files
- Extracting data for processing

**Example:**
```bash
# 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):

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

## Combined Workflows

### Inspect BAP Identity Using bbackup

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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:
```bash
bap list problematic.bep --password password
```

2. If that fails, try bbackup for more details:
```bash
bbackup dec problematic.bep -p password -o debug.json
```

3. Inspect the JSON structure:
```bash
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:

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

## 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**:
```bash
which bap bbackup
```

2. **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
```

3. **Check file format**:
```bash
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

```bash
# 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

```bash
# 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

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