coracle-rust/book/research/keys.md

Research: Keys

Topic Summary

The Keys chapter covers nostr cryptographic identity: PublicKey and SecretKey as type-safe Rust wrappers around secp256k1. Includes hex encoding, NIP-19 bech32 encoding (npub / nsec), key generation, validation, FromStr auto-detection of encoding variants, and safety measures that reduce accidental leakage of secret material (redacted Debug, no Display, zeroization on drop).

Philosophy

From ref/building-nostr:

• Self-sovereignty via cryptography. Nostr inverts platform-mediated identity: users unilaterally generate a secp256k1 keypair and become the authority over their own identity. No custodian, no issuer.
• Identity is subjective and relational. Keys enable users to act; reputation and context are layered on top via follow graphs, NIP-05, kind-0 profiles.
• Publicity, not privacy. Nostr is "publicity technology" — signed, verifiable, permanent. Keys enable authenticity, not confidentiality.
• Key handling is a big assumption. Storage is deferred to signers (NIP-07 browser, NIP-46 remote, NIP-55 Android). A library should make it hard to accidentally leak secret material.
• Key rotation is unsolved. Losing a secret key means losing social identity permanently; this is a philosophical reason to take secret-key handling seriously at the type-system level.
• Zooko's triangle. Hex/bech32 keys are secure and decentralized but not human-meaningful. The raw-key layer should be correct and minimal; naming is someone else's job.

Design implication: the SecretKey type should nudge users toward safety by default (no Display, redacted Debug, explicit method to extract material).

Reference Implementation Analysis

applesauce (TypeScript)

• Secret keys: raw Uint8Array (32 bytes). Public keys: 64-char lowercase hex.
• No wrapper types — thin helpers (normalizeToSecretKey, normalizeToPubkey) accept hex, nsec, or NIP-19 pointer and return primitives.
• Depends on nostr-tools for NIP-19, @noble/secp256k1 underneath.
• No debug redaction; no memory zeroing. Locking a signer just nulls its private field.
• isHexKey() validates format (length + charset), not curve membership.

ndk (TypeScript)

• Hexpubkey and Npub are branded string type aliases; secret keys are Uint8Array stored privately inside NDKPrivateKeySigner.
• Auto-detects nsec1 prefix vs. 64-char hex on signer construction, throws on invalid input.
• Delegates all NIP-19 work to nostr-tools/nip19; uses @noble/hashes for hex↔bytes and nostr-tools/nip49 for password-encrypted keys (ncryptsec).
• Keys live in private fields with controlled accessors; no accidental logging.
• Character-code loop for hex validation (avoids regex).

nostr-gadgets (TypeScript)

• No dedicated key types at all. pubkey is string (hex), secrets are passed as Uint8Array at call sites and not stored.
• isHex32() validates via charCodeAt against ASCII ranges.
• bareNostrUser() normalizes npub / nprofile / hex into both hex and npub fields on demand.
• Zero key material coupling — cryptography is entirely outsourced to @nostr/tools.

nostr-tools (TypeScript)

• Minimal, explicit: generateSecretKey() -> Uint8Array, getPublicKey(sk) -> hex.
• NPub/NSec branded string types for bech32 forms.
• NIP-19 TLV encoding/decoding via @scure/base for nprofile/nevent/naddr.
• Dependencies: @noble/curves (schnorr), @noble/hashes, @scure/base. Pure-JS, auditable, no OS bindings.
• Type guards via regex. validateEvent() rejects pubkeys that don't match ^[a-f0-9]{64}$.
• No zeroization — JS has no safe wipe primitive.

rust-nostr (Rust — most directly relevant)

• PublicKey: 32-byte wrapper around secp256k1::XOnlyPublicKey. Implements Copy.
• SecretKey: newtype around secp256k1::SecretKey, not Copy, implements Drop via non_secure_erase() from secp256k1-rs.
• Keys: composite holding both plus secp256k1::Keypair. Custom Debug impl that only shows the public key.
• SecretKey derives Debug directly, which the authors note is a footgun — Keys compensates by overriding.
• parse() method on both types auto-detects hex vs. bech32 (and NIP-21 nostr: URIs on PublicKey). FromStr delegates to parse().
• Dependencies: secp256k1 = "0.29", bech32 = "0.11", faster-hex = "0.10", bitcoin_hashes.
• Global SECP256K1: LazyLock<Secp256k1<All>> context, randomized via OsRng at first access (blinding countermeasure).
• NIP-19 handled in a separate nip19.rs module; serde serializes PublicKey as hex string.

welshman (TypeScript)

• No wrapper types; keys are hex strings. makeSecret() / getPubkey() as pure functions.
• Pubkey class wraps a pubkey hex with .toNpub() and Pubkey.from(entity) that decodes npub/nprofile and validates with regex.
• Nip01Signer stores the secret in a private #secret field, exposing only async signing operations.
• Depends on nostr-tools + @noble/curves.

Common Patterns

• secp256k1 everywhere. All references use secp256k1 with Schnorr-style x-only public keys (BIP-340). This is fixed by the protocol.
• Dual encoding. Hex for internal storage and wire format (event JSON); bech32 (NIP-19 npub/nsec) for user-facing display and copy-paste.
• Auto-detect on parse. Most libraries accept either form and figure out which is which by prefix or length.
• Secret material isolation. The TypeScript libraries hide secrets in private fields of a signer class. rust-nostr uses the type system: no Copy, explicit to_secret_hex() getter, redacted Debug on the composite, memory erase on Drop.
• No curve-membership validation up front. Most validate format only and let the underlying crypto library reject invalid points lazily. rust-nostr is stricter because secp256k1::SecretKey::from_slice rejects out-of-range values on construction.
• NIP-19 is a separate concern. Every library has a distinct NIP-19 module; the key types depend on it for bech32 but the bech32 logic is not inside the key type itself.

Considerations for Our Implementation

Crate choice. The secp256k1 crate (already in coracle-lib/Cargo.toml per commit history) is the natural fit — widely audited, used by Bitcoin Core bindings, same choice as rust-nostr. Its SecretKey::from_slice enforces curve constraints. For bech32 we'll pull in bech32 = "0.11". Hex can come from the existing hex crate (already a dependency).

Types.

• PublicKey — newtype around secp256k1::XOnlyPublicKey. Implements Copy, Debug, Display (hex), FromStr, Serialize, Deserialize.
• SecretKey — newtype around secp256k1::SecretKey. Does not implement Copy or Display. Custom Debug that prints SecretKey(<redacted>). FromStr that auto-detects hex vs. nsec1…. Explicit to_hex() and to_nsec() methods that opt into exposing the material.

Encoding.

• PublicKey::to_hex() / to_npub() and their from_ counterparts.
• SecretKey::to_hex() / to_nsec() / from_*.
• FromStr auto-detects by checking npub1/nsec1 prefix first, then falling back to 64-char hex.

Safety posture. Match rust-nostr's conventions where they're sensible in a teaching context, but don't hide secret-material extraction behind unsafe or complicated APIs — the chapter is pedagogical. Redact Debug, omit Display, require an explicit .to_hex() / .to_nsec() call.

Out of scope for this chapter.

• Signing and verification (next chapter).
• Key derivation, BIP-32, mnemonics (not part of the nostr protocol).
• NIP-49 encrypted key storage (ncryptsec).
• Remote / browser / Android signers (later chapters).
• nprofile, nevent, naddr TLV pointers (chapter on entities/content).

Keep the chapter narrow: identity as a keypair, how to encode it, how to avoid leaking it.