bap-identity

What this skill does

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