Docs / Guides / Key management

Key Management

Backup, restore, rotate, and recover your publisher key.

Where the key lives

~/.npmvc/wallet/key.json   (mode 0600, owner-only)

Encrypted backup

# Export (AES-256-GCM encrypted)
npmvc wallet export --passphrase "strong-secret" > key.enc

# Import on new machine
npmvc wallet import --passphrase "strong-secret" --input key.enc

Safe to store in 1Password, a vault, or a git repo — cannot be decrypted without the passphrase.

Auto-backup during init

npmvc init --backup-passphrase "strong-secret"
# Saves key.enc alongside key.json automatically

Environment variables (CI)

Priority order:

  1. NPMVC_KEY — raw JSON or base64 (inline, no file)
  2. NPMVC_KEY_FILE — path to key file
  3. Default: ~/.npmvc/wallet/key.json

Social recovery

Set up guardians who can approve key recovery if you lose your device:

# During init
npmvc init --guardians "did:key:z6MkAlice,did:key:z6MkBob,did:key:z6MkCarol" --threshold 2

# Or add later
npmvc wallet add-guardian --did did:key:z6MkAlice
npmvc wallet guardians   # list all

Recovery flow

# 1. After key loss — create request
npmvc wallet recover --old-did did:key:z6MkYOUR... --guardians "did1,did2,did3"

# 2. Each guardian approves
npmvc wallet approve-recovery --request recovery-request.json

# 3. Collect approvals and apply
npmvc wallet apply-recovery --approvals approval1.json,approval2.json

Key rotation (did:webvh)

npmvc init --method webvh --registry https://npmvc.com
npmvc wallet rotate   # old key signs rotation, backup becomes active

Transferring a package

npmvc credential handover --package my-lib --to did:key:z6MkNewOwner...
# New maintainer imports: npmvc audit import handover.jsonld

Security practices

  • Never commit key.json to git
  • Use wallet export for backups, not raw file copy
  • In CI, use NPMVC_KEY as a secret
  • Set up guardians before you need them
  • For key rotation safety, use did:webvh with pre-rotation
← previousCI/CD integration