Manage BAP Backup

Export and import BAP identity backups using the bsv-bap library.

Installation

bun add bsv-bap @bsv/sdk

Backup Format

Contains everything needed to reconstruct all identities:

{
  "rootPk": "L4vB5...",        // Master key WIF (Type42) or xprv (BIP32)
  "ids": "<encrypted string>", // All identity metadata, encrypted with master
  "label": "optional",
  "createdAt": "2026-03-13T..."
}

The encrypted ids blob contains: name, description, identityKey (BAP ID), identityAttributes, and paths.

Export Master Backup

import { BAP } from "bsv-bap";

const bap = new BAP({ rootPk: storedWif });
bap.importIds(encryptedIds);

const backup = bap.exportForBackup("My Identity");
// { rootPk: "L1SJ...", ids: "QklFMQ...", createdAt: "..." }

import { writeFileSync } from "node:fs";
writeFileSync("backup.json", JSON.stringify(backup, null, 2));

Import Master Backup

import { BAP } from "bsv-bap";
import { readFileSync } from "node:fs";

const backup = JSON.parse(readFileSync("backup.json", "utf-8"));
const bap = new BAP({ rootPk: backup.rootPk });
if (backup.ids) {
  bap.importIds(backup.ids);
}

const idKeys = bap.listIds();
const identity = bap.getId(idKeys[0]);
console.log(identity.idName, identity.getIdentityKey());

List Accounts

const idKeys = bap.listIds();

for (const key of idKeys) {
  const identity = bap.getId(key);
  console.log(`${identity.idName}: ${key}`);
  console.log(`  Root: ${identity.rootAddress}`);
  console.log(`  Current: ${identity.getCurrentAddress()}`);
}

Encrypted Backups (.bep)

For encrypted backup files using AES-256-GCM, use the bitcoin-backup CLI:

bun add -g bitcoin-backup

# Encrypt a backup
bbackup enc backup.json -p "password" -o identity.bep

# Decrypt a backup
bbackup dec identity.bep -p "password" -o decrypted.json

See encrypt-decrypt-backup skill for full bitcoin-backup reference.

CLI Option

For quick operations, use the bap CLI:

npm install -g bsv-bap

bap export              # Export identity JSON to stdout
bap export > backup.json
bap import backup.json  # Import from file
bap info                # View current identity

Master vs Member Backups

BAP supports two backup levels with different capabilities:

Backup Type	Contains	Can Derive New IDs?	Use Case
Master	rootPk (Type42) or xprv (legacy) + ids	Yes	Full identity management, key rotation
Member	Single derived WIF + encrypted identity data	No	Delegated access, agent auth, app-scoped signing

Member Backup Export

exportMemberBackup() produces a MemberIdentity with:

derivedPrivateKey — the stable member key WIF (from rootPath, never changes)
address — the current signing address (changes on rotation)
counter — rotation counter for the signing key derivation
identityKey — the BAP identity key

Stable Member Key

The member key is the stable identity anchor for authentication:

import { getStableMemberWif, getStableMemberPubkey } from "./bap/utils";

// These stay fixed even after key rotation
const wif = getStableMemberWif(identity);    // For auth token signing
const pubkey = getStableMemberPubkey(identity); // For identity resolution

Auth tokens (bitcoin-auth) are signed with the stable member WIF, not the rotating signing key. This ensures identity continuity across rotations.

Related Skills

create-bap-identity - Create new BAP identities
encrypt-decrypt-backup - bitcoin-backup CLI for .bep files
key-derivation - Type42 and BRC-43 key derivation

BAP identities can be used for OAuth authentication with Sigma Identity. See @sigma-auth/better-auth-plugin for integration patterns.

manage-bap-backup