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)

At-rest encryption

By default npmvc init writes a plaintext key file (protected only by POSIX 0600 permissions). For stronger at-rest protection, encrypt the in-use key with a passphrase:

# Create encrypted key from scratch
npmvc init --encrypt --passphrase "your-strong-passphrase"

# Or upgrade an existing plaintext key
npmvc wallet encrypt --passphrase "your-strong-passphrase"

# Undo
npmvc wallet decrypt --passphrase "your-strong-passphrase"

Once encrypted, every npmvc command that signs (attest, audit publish, credential revoke, …) requires the passphrase, supplied via the NPMVC_KEY_PASSPHRASE env var:

NPMVC_KEY_PASSPHRASE=... npmvc attest

Uses scrypt (N=32768, r=8, p=1) + AES-256-GCM. Minimum passphrase length: 8 characters.

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

If the stored key was created with --encrypt, setNPMVC_KEY_PASSPHRASE too (typically as a CI secret).

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