@vanar/veil-keys-from-wallet

Deterministic VeilCapsule X25519 keypair derivation from an EVM wallet signature. The user's wallet seed phrase is the only secret; the keypair is re-derived on demand from a fixed signed message.

Why this exists

Most "audit dashboard" products either:

• Ask the user to remember an extra password / passphrase, or
• Hold the encryption key on the server, defeating the point of end-to-end encryption

This package side-steps both. Users sign a fixed message in their wallet (Vanar VeilCapsule key derivation v1); the SHA-256 of that signature becomes the X25519 secret key. No extra secrets to remember, no operator-held key, full backup via the existing wallet seed phrase.

Install

npm i @vanar/veil-keys-from-wallet

Usage

Browser (Reown / WalletConnect / wagmi / viem)

import { deriveFromWallet } from "@vanar/veil-keys-from-wallet";

// `walletClient` is any object exposing { signMessage({message}) → hex string }.
// Works with viem WalletClient, ethers.js Signer (via small adapter), wagmi, etc.
const veilKeys = await deriveFromWallet({
  signMessage: ({ message }) => walletClient.signMessage({ account, message }),
});

// veilKeys = { publicKey: 'dB9BSY...=', secretKey: 'o7nmZM...=' }
//
// SAFE TO SEND TO YOUR SERVER:
//   - veilKeys.publicKey
// MUST NEVER LEAVE THE BROWSER:
//   - veilKeys.secretKey

Server-side (re-derive for migrations / re-encryption)

import { deriveVeilKeyPairFromSignature } from "@vanar/veil-keys-from-wallet";

// Only call this with a signature the user has provided in real time.
// The server should normally NEVER see the user's secret key.
const keys = await deriveVeilKeyPairFromSignature(signatureHex);

How it works

1. User signs the fixed message in their wallet (signMessage)
2. Wallet returns a 65-byte ECDSA signature (RFC 6979 deterministic for all major EVM wallets - same (message, key) always yields same bytes)
3. SHA-256 of those bytes → 32 deterministic bytes
4. nacl.box.keyPair.fromSecretKey(seed) → X25519 keypair
5. Returns base64-encoded for parity with @vanar/veil-capsule's VeilKeyPair type

Properties

• ✅ Deterministic - same wallet + same message → same keypair
• ✅ Backup is implicit - if you have your wallet seed phrase, you have your VeilCapsule key
• ✅ Revocable via versioning - bump the message version (v2) to rotate; old capsules stay encrypted under v1
• ✅ No password fatigue - no extra secret to remember
• ✅ Works on every major EVM wallet - MetaMask, Rainbow, Coinbase Wallet, Trust Wallet, Ledger, etc

Versioning

The current derivation message is Vanar VeilCapsule key derivation v1. Bumping the version is intentional - it produces a fresh keypair, so all old capsules become unreadable except by the original wallet re-deriving with the old message. This is the rotation primitive.

import { DERIVATION_MESSAGE_V1, CURRENT_DERIVATION_MESSAGE } from "@vanar/veil-keys-from-wallet";
// DERIVATION_MESSAGE_V1 stays exported forever for migration purposes

Trust assumption

The wallet's signing algorithm (secp256k1 ECDSA) must be deterministic when used per RFC 6979. All major EVM wallets implement this. If a wallet returned a non-deterministic signature, the user's keypair would change every derivation and everything would break.

Security caveat

The derived keypair is only as private as the wallet seed phrase. If the wallet seed is compromised, so is every capsule encrypted to that keypair. This is the same trust model as the wallet's funds - by design.

Related

Companion to @vanar/veil-capsule. Use this package to derive a per-user X25519 keypair from the user's wallet so each user's audit capsules are encrypted to keys only their wallet can re-derive. Works standalone or with the rest of Vanar's open protocols. See veil.org for the protocol overview.