feat: NIP-AB device pairing — Phase 1 (core library + CLI)

[tlongwell-block]

Summary

Implements the NIP-AB device pairing protocol for securely transferring Nostr private keys between devices. Phase 1 delivers the core Rust library, a standalone CLI interop tool, and relay-side global fan-out for channel-less ephemeral events. Phase 2 (desktop/mobile UI integration) will follow.

What is NIP-AB?

A protocol for moving a Nostr identity from one device to another over standard relays, using:

• QR code to bootstrap the connection (ephemeral pubkey + session secret + relay URL + protocol version)
• ECDH + NIP-44 v2 for end-to-end encryption (relay sees only opaque ciphertext)
• 6-digit SAS code for MITM prevention (user visually confirms codes match)
• Ephemeral keypairs discarded after the session (no persistent footprint)

Think of it as the Nostr equivalent of Signal device linking or Bluetooth Secure Simple Pairing — but over standard Nostr relays with no custom infrastructure.

What's in this PR

Core library (sprout-core/src/pairing/):

• NIP-AB.md — Protocol spec (~750 lines) with versioning, limitations, pseudocode, design rationale, edge case coverage, and computed test vectors. Multi-relay support demoted to optional guidance ("Multi-Relay Considerations" section) — single-relay implementations are fully conformant.
• crypto.rs — HKDF-SHA256 derivations (session ID, SAS code, transcript hash) with constant-time comparison via subtle::ConstantTimeEq
• types.rs — Serde-serializable pairing message types (offer with version field, sas-confirm, payload, complete, abort) with forward-compatible AbortReason extensibility via #[serde(other)]
• qr.rs — nostrpair:// URI encode/decode with protocol version (v=1), 2048-char URI limit, relay scheme validation, lowercase hex enforcement, all-zeros session_secret rejection
• session.rs — PairingSession state machine (7 states, strict role/state enforcement, Zeroizing<String> payload API, sign_event() for NIP-42 auth, per-session duplicate event ID tracking)

CLI tool (sprout-pairing-cli/):

• sprout-pair source — display QR, wait for target, SAS confirm, send payload
• sprout-pair target — paste QR, send offer, verify SAS, receive payload
• sprout-pair test-vectors — print all derived values from spec's fixed keys
• NIP-42 authentication support, EOSE-gated subscription on both source and target
• Zeroizing<String> throughout the secret handling path
• Silent discard of invalid/out-of-order events per NIP-AB §Event Validation
• Sends abort(sas_mismatch) on transcript hash mismatch
• README with usage guide and local testing instructions

Relay (sprout-relay + sprout-db):

• Global Redis fan-out for channel-less ephemeral events using Uuid::nil() sentinel pattern — enables cross-node delivery of NIP-AB pairing events (kind:24134) without requiring channel membership
• Nil UUID guard in create_channel_with_id + CHECK constraint in schema to prevent sentinel collision with real channel IDs
• Subscriber loop nil-check converting sentinel back to None for correct global fan-out routing

Security hardening

• NIP-01 event signature verification on all incoming events
• Constant-time comparison via subtle::ConstantTimeEq for transcript hash and session ID
• Zeroizing<String> for secret payloads — deferred ? pattern ensures zeroization on both success and error paths; serialized plaintext and decrypted plaintext explicitly zeroized after use
• ECDH shared secret zeroed via zeroize immediately after SAS derivation
• Session secret and derived material zeroed on Drop via zeroize
• Terminal state finality (Completed/Aborted cannot regress)
• Pre-peer abort rejection (relay observers cannot kill sessions)
• Protocol version enforcement — handle_offer rejects unsupported versions
• QR URI size limit (2048 chars) to prevent DoS via QR scanning
• NIP-44 pinned to version 2 (0x02) — rejects other version bytes
• created_at timestamp randomization (0–30s jitter for metadata privacy)
• QR relay URL scheme validation (rejects non-WebSocket schemes)
• Lowercase hex enforcement and all-zeros session_secret rejection in QR decode
• TranscriptMismatch surfaced as a hard security error with abort sent to peer
• Per-session duplicate event ID tracking (check/record split prevents speculative probe poisoning)
• Forward-compatible AbortReason deserialization
• Nil UUID sentinel defended at both application and schema level

Test coverage

68 unit tests covering:

• Full happy-path protocol (source → target → SAS → payload → complete)
• State machine enforcement (out-of-order operations rejected)
• Abort flows (pre-peer, post-completion, from either side)
• QR URI round-trips with version, reserved characters, scheme validation
• Unsupported version rejection (QR and offer)
• Duplicate payload rejection, target confirmation gating
• Wrong-pubkey and wrong-session-id rejection
• Pinned test vectors for all HKDF derivations
• Duplicate event ID tracking (speculative abort probe does not poison dedup set)
• Wrong-type message not recorded in dedup set
• complete(success: false) aborts without recording (verified via has_processed test accessor)
• All-zeros session_secret rejection
• Uppercase hex rejection in QR pubkey and secret

E2E tested over a local Sprout relay using an expect-driven test harness.

Review process

Crossfire reviewed across multiple rounds by Claude Opus and Codex CLI:

Change	Rounds	Final Score
Global fan-out	3→8→9	✅ 9/10
Zeroizing<String>	5→7→8→9	✅ 9/10
NIP-AB spec + code	6→7→9	✅ 9/10
Spec compliance fixes (dedup, abort, validation)	6→5→8→8→9→10	✅ 10/10

What's next (Phase 2)

• Desktop UI integration (refactor MobilePairingCard.tsx to drive the new protocol)
• Mobile client integration (replace pairing_provider.dart)

How to test

cargo test -p sprout-core --lib pairing    # 68 tests
cargo clippy --workspace --all-targets -- -D warnings

# End-to-end over a local Sprout relay:
.scratch/e2e-pair-local.sh

# Manual two-terminal test:
cargo run -p sprout-pairing-cli -- source --relay ws://localhost:3000
cargo run -p sprout-pairing-cli -- target --show-secret

# Print test vectors:
cargo run -p sprout-pairing-cli -- test-vectors

See crates/sprout-pairing-cli/README.md for full testing guide.