From 385ec2aa27190d62398f8072f2befce2086b0b97 Mon Sep 17 00:00:00 2001 From: mleku Date: Sat, 29 Mar 2025 13:48:09 -0106 Subject: [PATCH] documentation comments for apputil, auth and bech32encoding also removed relay.damus.io which is a dumpster fire of spammers and trolls --- apputil/apputil.go | 3 ++- auth/doc.go | 2 ++ bech32encoding/doc.go | 6 +++++ bech32encoding/keys.go | 15 +++++++++-- bech32encoding/nip19.go | 41 +++++++++++++++-------------- bech32encoding/pointers/pointers.go | 3 +++ ws/subscription_test.go | 2 +- 7 files changed, 48 insertions(+), 24 deletions(-) create mode 100644 auth/doc.go create mode 100644 bech32encoding/doc.go diff --git a/apputil/apputil.go b/apputil/apputil.go index 55a5dd9..fe989a3 100644 --- a/apputil/apputil.go +++ b/apputil/apputil.go @@ -5,7 +5,8 @@ import ( "path/filepath" ) -// EnsureDir checks a file could be written to a path, creates the directories as needed +// EnsureDir checks a file could be written to a path, creates the directories +// as needed func EnsureDir(fileName string) { dirName := filepath.Dir(fileName) if _, serr := os.Stat(dirName); serr != nil { diff --git a/auth/doc.go b/auth/doc.go new file mode 100644 index 0000000..4f0dd7f --- /dev/null +++ b/auth/doc.go @@ -0,0 +1,2 @@ +// Package auth implements NIP-42 authentication. +package auth diff --git a/bech32encoding/doc.go b/bech32encoding/doc.go new file mode 100644 index 0000000..ca37c76 --- /dev/null +++ b/bech32encoding/doc.go @@ -0,0 +1,6 @@ +// Package bech32encoding implements NIP-19 entities, which are bech32 encoded +// data that describes nostr data types. +// +// These are not just identifiers of events and users, but also include things +// like relay hints where to find events. +package bech32encoding diff --git a/bech32encoding/keys.go b/bech32encoding/keys.go index 03d2c7d..f0d5a41 100644 --- a/bech32encoding/keys.go +++ b/bech32encoding/keys.go @@ -14,12 +14,16 @@ const ( // MinKeyStringLen is 56 because Bech32 needs 52 characters plus 4 for the HRP, // any string shorter than this cannot be a nostr key. MinKeyStringLen = 56 - HexKeyLen = 64 - Bech32HRPLen = 4 + // HexKeyLen is the length of a nostr key in hexadecimal. + HexKeyLen = 64 + // Bech32HRPLen is the length of the standard nostr keys, nsec and npub. + Bech32HRPLen = 4 ) var ( + // SecHRP is the standard Human Readable Prefix (HRP) for a nostr secret key in bech32 encoding - nsec SecHRP = []byte("nsec") + // PubHRP is the standard Human Readable Prefix (HRP) for a nostr public key in bech32 encoding - nsec PubHRP = []byte("npub") ) @@ -59,6 +63,7 @@ func NsecToSecretKey(encoded []byte) (sk *secp256k1.SecretKey, err error) { return } +// NsecToBytes converts a nostr bech32 encoded secret key to raw bytes. func NsecToBytes(encoded []byte) (sk []byte, err error) { var b5, hrp []byte if hrp, b5, err = bech32.Decode(encoded); chk.E(err) { @@ -76,6 +81,7 @@ func NsecToBytes(encoded []byte) (sk []byte, err error) { return } +// NpubToBytes converts a bech32 encoded public key to raw bytes. func NpubToBytes(encoded []byte) (pk []byte, err error) { var b5, hrp []byte if hrp, b5, err = bech32.Decode(encoded); chk.E(err) { @@ -151,6 +157,8 @@ func HexToSecretKey(sk []byte) (s *btcec.SecretKey, err error) { return } +// HexToNpub converts a raw 64 character hex encoded public key (as used in +// standard nostr json events) to a bech32 encoded npub. func HexToNpub(publicKeyHex []byte) (s []byte, err error) { b := make([]byte, schnorr.PubKeyBytesLen) if _, err = hex.DecBytes(b, publicKeyHex); chk.D(err) { @@ -164,6 +172,7 @@ func HexToNpub(publicKeyHex []byte) (s []byte, err error) { return bech32.Encode(NpubHRP, bits5) } +// BinToNpub converts a raw 32 byte public key to nostr bech32 encoded npub. func BinToNpub(b []byte) (s []byte, err error) { var bits5 []byte if bits5, err = bech32.ConvertBits(b, 8, 5, true); chk.D(err) { @@ -200,6 +209,8 @@ func SecretKeyToHex(sk *btcec.SecretKey) (hexSec []byte) { return } +// NsecToHex converts a bech32 encoded nostr secret key to a raw hexadecimal +// string. func NsecToHex(nsec []byte) (hexSec []byte, err error) { var sk *secp256k1.SecretKey if sk, err = NsecToSecretKey(nsec); chk.E(err) { diff --git a/bech32encoding/nip19.go b/bech32encoding/nip19.go index 23bdf68..ffc7b41 100644 --- a/bech32encoding/nip19.go +++ b/bech32encoding/nip19.go @@ -3,7 +3,6 @@ package bech32encoding import ( "bytes" "encoding/binary" - "reflect" "realy.lol/bech32encoding/pointers" "realy.lol/ec/bech32" @@ -15,28 +14,24 @@ import ( ) var ( - NoteHRP = []byte("note") - NsecHRP = []byte("nsec") - NpubHRP = []byte("npub") + // NoteHRP is the Human Readable Prefix (HRP) for a nostr note (kind 1) + NoteHRP = []byte("note") + // NsecHRP is the Human Readable Prefix (HRP) for a nostr secret key + NsecHRP = []byte("nsec") + // NpubHRP is the Human Readable Prefix (HRP) for a nostr public key + NpubHRP = []byte("npub") + // NprofileHRP is the Human Readable Prefix (HRP) for a nostr profile metadata + // event (kind 0) NprofileHRP = []byte("nprofile") - NeventHRP = []byte("nevent") - NentityHRP = []byte("naddr") + // NeventHRP is the Human Readable Prefix (HRP) for a nostr event, which may + // include relay hints to find the event, and the author's npub. + NeventHRP = []byte("nevent") + // NentityHRP is the Human Readable Prefix (HRP) for a nostr is a generic nostr entity, which may include relay hints to find the event, and the author's npub. + NentityHRP = []byte("naddr") ) -func DecodeToString(bech32String []byte) (prefix, value []byte, err error) { - var s any - if prefix, s, err = Decode(bech32String); chk.D(err) { - return - } - var ok bool - if value, ok = s.([]byte); ok { - return - } - err = log.E.Err("value was not decoded to a string, found type %s", - reflect.TypeOf(s)) - return -} - +// Decode a nostr bech32 encoded entity, return the prefix, and the decoded +// value, and any error if one occurred in the process of decoding. func Decode(bech32string []byte) (prefix []byte, value any, err error) { var bits5 []byte if prefix, bits5, err = bech32.DecodeNoLimit(bech32string); chk.D(err) { @@ -153,6 +148,8 @@ func Decode(bech32string []byte) (prefix []byte, value any, err error) { return prefix, data, errorf.E("unknown tag %s", prefix) } +// EncodeNote encodes a standard nostr NIP-19 note entity (mostly meaning a +// nostr kind 1 short text note) func EncodeNote(eventIDHex []byte) (s []byte, err error) { var b []byte if _, err = hex.DecBytes(b, eventIDHex); chk.D(err) { @@ -166,6 +163,8 @@ func EncodeNote(eventIDHex []byte) (s []byte, err error) { return bech32.Encode(NoteHRP, bits5) } +// EncodeProfile encodes a pubkey and a set of relays into a bech32 encoded +// entity. func EncodeProfile(publicKeyHex []byte, relays [][]byte) (s []byte, err error) { buf := &bytes.Buffer{} pb := make([]byte, schnorr.PubKeyBytesLen) @@ -185,6 +184,7 @@ func EncodeProfile(publicKeyHex []byte, relays [][]byte) (s []byte, err error) { return bech32.Encode(NprofileHRP, bits5) } +// EncodeEvent encodes an event, including relay hints and author pubkey. func EncodeEvent(eventIDHex *eventid.T, relays [][]byte, author []byte) (s []byte, err error) { buf := &bytes.Buffer{} id := make([]byte, sha256.Size) @@ -211,6 +211,7 @@ func EncodeEvent(eventIDHex *eventid.T, relays [][]byte, author []byte) (s []byt return bech32.Encode(NeventHRP, bits5) } +// EncodeEntity encodes a pubkey, kind, event Id, and relay hints. func EncodeEntity(pk []byte, k *kind.T, id []byte, relays [][]byte) (s []byte, err error) { buf := &bytes.Buffer{} writeTLVEntry(buf, TLVDefault, []byte(id)) diff --git a/bech32encoding/pointers/pointers.go b/bech32encoding/pointers/pointers.go index 67ac689..9330219 100644 --- a/bech32encoding/pointers/pointers.go +++ b/bech32encoding/pointers/pointers.go @@ -5,11 +5,13 @@ import ( "realy.lol/kind" ) +// Profile pointer is a combination of pubkey and relay list. type Profile struct { PublicKey []byte `json:"pubkey"` Relays [][]byte `json:"relays,omitempty"` } +// Event pointer is the combination of an event Id, relay hints, author pubkey and kind. type Event struct { ID *eventid.T `json:"id"` Relays [][]byte `json:"relays,omitempty"` @@ -17,6 +19,7 @@ type Event struct { Kind *kind.T `json:"kind,omitempty"` } +// Entity is the combination of a pubkey, kind, arbitrary identifier, and relay hints. type Entity struct { PublicKey []byte `json:"pubkey"` Kind *kind.T `json:"kind,omitempty"` diff --git a/ws/subscription_test.go b/ws/subscription_test.go index e0799cd..3aed616 100644 --- a/ws/subscription_test.go +++ b/ws/subscription_test.go @@ -15,7 +15,7 @@ import ( "realy.lol/tags" ) -const RELAY = "wss://relay.damus.io" +const RELAY = "wss://mleku.realy.lol" // test if we can fetch a couple of random events func TestSubscribeBasic(t *testing.T) {