feat(crypto): deterministic P2PK & NUT-20 quote-lock key derivation

[robwoodgate]

NUTS:

• Deterministic pay to public key generation nuts#331
• NUT-20: add deterministic NUT-20 quote locking derivation nuts#373

Summary

Adds BIP-32 derivation of deterministic signing keys under m/129373'/{purpose}'/0'/0'/{counter} (non-hardened counter), as defined for:

• NUT-11: P2PK keys (purpose index 10)
• NUT-20: quote locking keys (purpose index 20)

API

export type Bip32KeyPurpose = 'P2PK' | 'QuoteLock';

deriveKeyPair(seed, purpose, counter): { pubkey: string; privkey: string }            // one-shot
createKeyPairDeriver(seed, purpose): (counter) => { pubkey: string; privkey: string } // cached, for loops

purpose is passed by name ('P2PK' / 'QuoteLock'). Both return hex pubkey/privkey that drop straight into the existing lock/quote and signP2PKProofs APIs with zero conversion:

const { pubkey, privkey } = deriveKeyPair(seed, 'P2PK', counter);
await wallet.send(64, proofs, undefined, { send: { type: 'p2pk', options: { pubkey } } });
await wallet.send(64, lockedProofs, { privkey });

const { pubkey: qp, privkey: qk } = deriveKeyPair(seed, 'QuoteLock', counter);
const quote = await wallet.createLockedMintQuote(amount, qp);
await wallet.mintProofs('bolt11', amount, quote, { privkey: qk });

createKeyPairDeriver caches the shared parent derivation, so restore scans cost a single non-hardened child derivation per counter (~5x faster than re-walking the full path) while still returning the ready-to-use hex keypair:

const derive = createKeyPairDeriver(seed, 'P2PK');
for (let counter = 0; counter < gapLimit; counter++) {
  if (derive(counter).pubkey === targetPubkey) break; // matched
}

Scope

Crypto primitive only. Counter allocation and the quote/proof-to-counter mapping stay with the consumer; they need that mapping regardless, so a wallet-owned counter would add coupling without removing consumer state. No NUT-20 module changes needed: createLockedMintQuote/locked mint already accept the pubkey/privkey directly.

Testing

Verified against the NUT-11 / NUT-20 test vectors for both purposes, counters 0 to 4. npm run prtasks green (lint, format, api-extractor, full suite).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.21%. Comparing base (f568ed3) to head (3d199cf).
⚠️ Report is 40 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #697      +/-   ##
==========================================
+ Coverage   92.40%   95.21%   +2.80%     
==========================================
  Files          54       54              
  Lines        4990     5078      +88     
  Branches     1224     1254      +30     
==========================================
+ Hits         4611     4835     +224     
+ Misses        160      103      -57     
+ Partials      219      140      -79     

Flag	Coverage Δ
integration	38.28% <10.00%> (-0.40%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🧬 Mutation testing (incremental)

✅ Mutation score: 89.4% (break threshold: 80%) — repo-wide 5221 killed / 535 survived / 84 no-coverage.

Surviving mutants in files this PR changed (20):

• crypto/NUT13.ts:126 BlockStatement: {}
• crypto/NUT13.ts:127 StringLiteral: ""
• crypto/NUT13.ts:32 StringLiteral: ""
• crypto/NUT13.ts:185 ConditionalExpression: false
• crypto/NUT13.ts:185 LogicalOperator: secret === null && blindingFactor === null
• crypto/NUT13.ts:185 ConditionalExpression: false
• crypto/NUT13.ts:185 ConditionalExpression: false
• crypto/NUT13.ts:185 BlockStatement: {}
• crypto/NUT13.ts:186 StringLiteral: ""
• crypto/NUT13.ts:213 EqualityOperator: attempt <= 1 << 16
• crypto/NUT13.ts:217 ConditionalExpression: false
• crypto/NUT13.ts:217 EqualityOperator: x > BLS_FR_ORDER
• crypto/NUT13.ts:221 StringLiteral: ""
• crypto/NUT13.ts:227 ConditionalExpression: false
• crypto/NUT13.ts:227 EqualityOperator: x > SECP256K1_N
• crypto/NUT13.ts:227 ArithmeticOperator: x + SECP256K1_N
• crypto/NUT13.ts:229 ConditionalExpression: false
• crypto/NUT13.ts:229 BlockStatement: {}
• crypto/NUT13.ts:230 StringLiteral: ""
• crypto/NUT13.ts:126 ConditionalExpression: false

Full report (all files): download the mutation-report-pr artifact from this run. Codecov shows lines this PR left uncovered; this shows changed lines that run but aren’t asserted.