From 205aafcfe5767d031f2cd0e38796533f125e14f2 Mon Sep 17 00:00:00 2001 From: Jay Date: Thu, 23 Oct 2025 16:16:27 -0400 Subject: [PATCH] refactoring, added documentation --- event.go | 197 +++++---------------- event_json_test.go | 2 +- event_test.go | 2 +- filter.go | 78 +++++--- filter_match_test.go | 41 +++-- id.go | 37 ++++ event_id_test.go => id_test.go | 28 +-- keys.go | 9 +- keys_test.go | 2 +- sign.go | 31 ++++ event_sign_test.go => sign_test.go | 6 +- validate.go | 96 ++++++++++ event_validate_test.go => validate_test.go | 41 +++-- 13 files changed, 342 insertions(+), 228 deletions(-) create mode 100644 id.go rename event_id_test.go => id_test.go (91%) create mode 100644 sign.go rename event_sign_test.go => sign_test.go (78%) create mode 100644 validate.go rename event_validate_test.go => validate_test.go (87%) diff --git a/event.go b/event.go index b1edf79..d0a1291 100644 --- a/event.go +++ b/event.go @@ -1,166 +1,63 @@ +// Roots is a purposefully minimal, core Nostr protocol library that provides +// mathematically invariant primitives that define protocol compliance: event +// structure, serialization, cryptographic signatures, and subscription +// filters. package roots import ( - "crypto/sha256" - "encoding/hex" - "encoding/json" "errors" - "fmt" "regexp" - - "github.com/btcsuite/btcd/btcec/v2" - "github.com/btcsuite/btcd/btcec/v2/schnorr" ) +// Tag represents a single tag within an event as an array of strings. +// The first element identifies the tag name, the second contains the value, +// and subsequent elements are optional. +type Tag []string + +// Event represents a Nostr protocol event, with its seven required fields. +// All fields must be present for a valid event. type Event struct { - ID string `json:"id"` - PubKey string `json:"pubkey"` - CreatedAt int `json:"created_at"` - Kind int `json:"kind"` - Tags [][]string `json:"tags"` - Content string `json:"content"` - Sig string `json:"sig"` + ID string `json:"id"` + PubKey string `json:"pubkey"` + CreatedAt int `json:"created_at"` + Kind int `json:"kind"` + Tags []Tag `json:"tags"` + Content string `json:"content"` + Sig string `json:"sig"` } var ( - Hex64Pattern = regexp.MustCompile("^[a-f0-9]{64}$") + // Hex64Pattern matches 64-character, lowercase, hexadecimal strings. + // Used for validating event IDs and cryptographic keys. + Hex64Pattern = regexp.MustCompile("^[a-f0-9]{64}$") + + // Hex128Pattern matches 128-character, lowercase, hexadecimal strings. + // Used for validating signatures. Hex128Pattern = regexp.MustCompile("^[a-f0-9]{128}$") ) var ( - ErrMalformedPubKey = errors.New("pubkey must be 64 lowercase hex characters") - ErrMalformedID = errors.New("id must be 64 hex characters") - ErrMalformedSig = errors.New("signature must be 128 hex characters") - ErrMalformedTag = errors.New("tags must contain at least two elements") - ErrFailedIDComp = errors.New("failed to compute event id") - ErrNoEventID = errors.New("event id is empty") - ErrInvalidSig = errors.New("event signature is invalid") + // ErrMalformedPubKey indicates a public key is not 64 lowercase hex characters. + ErrMalformedPubKey = errors.New("public key must be 64 lowercase hex characters") + + // ErrMalformedPrivKey indicates a private key is not 64 lowercase hex characters. + ErrMalformedPrivKey = errors.New("private key must be 64 lowercase hex characters") + + // ErrMalformedID indicates an event id is not 64 hex characters. + ErrMalformedID = errors.New("event id must be 64 hex characters") + + // ErrMalformedSig indicates an event signature is not 128 hex characters. + ErrMalformedSig = errors.New("event signature must be 128 hex characters") + + // ErrMalformedTag indicates an event tag contains fewer than two elements. + ErrMalformedTag = errors.New("tags must contain at least two elements") + + // ErrFailedIDComp indicates the event ID could not be computed during validation. + ErrFailedIDComp = errors.New("failed to compute event id") + + // ErrNoEventID indicates the event ID field is empty. + ErrNoEventID = errors.New("event id is empty") + + // ErrInvalidSig indicates the event signature failed cryptographic validation. + ErrInvalidSig = errors.New("event signature is invalid") ) - -func (e *Event) Serialize() ([]byte, error) { - serialized := []interface{}{ - 0, - e.PubKey, - e.CreatedAt, - e.Kind, - e.Tags, - e.Content, - } - - bytes, err := json.Marshal(serialized) - if err != nil { - return []byte{}, err - } - return bytes, nil -} - -func (e *Event) GetID() (string, error) { - bytes, err := e.Serialize() - if err != nil { - return "", err - } - hash := sha256.Sum256(bytes) - return hex.EncodeToString(hash[:]), nil -} - -func SignEvent(eventID, privateKeyHex string) (string, error) { - skBytes, err := hex.DecodeString(privateKeyHex) - if err != nil { - return "", fmt.Errorf("invalid private key hex: %w", err) - } - - idBytes, err := hex.DecodeString(eventID) - if err != nil { - return "", fmt.Errorf("invalid event id hex: %w", err) - } - - // discard public key return value - sk, _ := btcec.PrivKeyFromBytes(skBytes) - sig, err := schnorr.Sign(sk, idBytes) - if err != nil { - return "", fmt.Errorf("schnorr signature error: %w", err) - } - - return hex.EncodeToString(sig.Serialize()), nil -} - -func (e *Event) Validate() error { - if err := e.ValidateStructure(); err != nil { - return err - } - - if err := e.ValidateID(); err != nil { - return err - } - - return ValidateSignature(e.ID, e.Sig, e.PubKey) -} - -func (e *Event) ValidateStructure() error { - if !Hex64Pattern.MatchString(e.PubKey) { - return ErrMalformedPubKey - } - - if !Hex64Pattern.MatchString(e.ID) { - return ErrMalformedID - } - - if !Hex128Pattern.MatchString(e.Sig) { - return ErrMalformedSig - } - - for _, tag := range e.Tags { - if len(tag) < 2 { - return ErrMalformedTag - } - } - - return nil -} - -func (e *Event) ValidateID() error { - computedID, err := e.GetID() - if err != nil { - return ErrFailedIDComp - } - if e.ID == "" { - return ErrNoEventID - } - if computedID != e.ID { - return fmt.Errorf("event id %q does not match computed id %q", e.ID, computedID) - } - return nil -} - -func ValidateSignature(eventID, eventSig, publicKeyHex string) error { - idBytes, err := hex.DecodeString(eventID) - if err != nil { - return fmt.Errorf("invalid event id hex: %w", err) - } - - sigBytes, err := hex.DecodeString(eventSig) - if err != nil { - return fmt.Errorf("invalid event signature hex: %w", err) - } - - pkBytes, err := hex.DecodeString(publicKeyHex) - if err != nil { - return fmt.Errorf("invalid public key hex: %w", err) - } - - signature, err := schnorr.ParseSignature(sigBytes) - if err != nil { - return fmt.Errorf("malformed signature: %w", err) - } - - publicKey, err := schnorr.ParsePubKey(pkBytes) - if err != nil { - return fmt.Errorf("malformed public key: %w", err) - } - - if signature.Verify(idBytes, publicKey) { - return nil - } else { - return ErrInvalidSig - } -} diff --git a/event_json_test.go b/event_json_test.go index b0de636..73e0b6f 100644 --- a/event_json_test.go +++ b/event_json_test.go @@ -27,7 +27,7 @@ func TestEventJSONRoundTrip(t *testing.T) { PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: testEvent.Kind, - Tags: [][]string{ + Tags: []Tag{ {"a", "value"}, {"b", "value", "optional"}, {"name", "value", "optional", "optional"}, diff --git a/event_test.go b/event_test.go index 36d74b9..9b26ed3 100644 --- a/event_test.go +++ b/event_test.go @@ -13,7 +13,7 @@ var testEvent = Event{ PubKey: testPK, CreatedAt: 1760740551, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "hello world", Sig: "83b71e15649c9e9da362c175f988c36404cabf357a976d869102a74451cfb8af486f6088b5631033b4927bd46cad7a0d90d7f624aefc0ac260364aa65c36071a", } diff --git a/filter.go b/filter.go index 6efa267..b83a6d0 100644 --- a/filter.go +++ b/filter.go @@ -2,10 +2,19 @@ package roots import ( "encoding/json" - // "fmt" "strings" ) +// TagFilters maps tag names to arrays of values for tag-based filtering +// Keys correspond to tag names without the "#" prefix. +type TagFilters map[string][]string + +// FilterExtensions holds arbitrary additional filter fields as raw JSON. +// Allows custom filter extensions without modifying the core Filter type. +type FilterExtensions map[string]json.RawMessage + +// Filter defines subscription criteria for events. +// All conditions within a filter applied with AND logic. type Filter struct { IDs []string Authors []string @@ -13,10 +22,12 @@ type Filter struct { Since *int Until *int Limit *int - Tags map[string][]string - Extensions map[string]json.RawMessage + Tags TagFilters + Extensions FilterExtensions } +// MarshalJSON converts the filter to JSON with standard fields, tag filters +// (prefixed with "#"), and extensions merged into a single object. func (f *Filter) MarshalJSON() ([]byte, error) { outputMap := make(map[string]interface{}) @@ -72,9 +83,11 @@ func (f *Filter) MarshalJSON() ([]byte, error) { return json.Marshal(outputMap) } +// UnmarshalJSON parses JSON into the filter, separating standard fields, +// tag filters (keys starting with "#"), and extensions. func (f *Filter) UnmarshalJSON(data []byte) error { // Decode into raw map - raw := make(map[string]json.RawMessage) + raw := make(FilterExtensions) if err := json.Unmarshal(data, &raw); err != nil { return err } @@ -145,7 +158,7 @@ func (f *Filter) UnmarshalJSON(data []byte) error { if strings.HasPrefix(key, "#") { // Leave Tags as `nil` unless tag fields exist if f.Tags == nil { - f.Tags = make(map[string][]string) + f.Tags = make(TagFilters) } tagKey := key[1:] var tagValues []string @@ -165,24 +178,27 @@ func (f *Filter) UnmarshalJSON(data []byte) error { return nil } +// Matches returns true if the event satisfies all filter conditions. +// Supports prefix matching for IDs and authors, and tag filtering. +// Does not account for custom extensions. func (f *Filter) Matches(event *Event) bool { // Check ID if len(f.IDs) > 0 { - if !matchesPrefix(event.ID, &f.IDs) { + if !matchesPrefix(event.ID, f.IDs) { return false } } // Check Author if len(f.Authors) > 0 { - if !matchesPrefix(event.PubKey, &f.Authors) { + if !matchesPrefix(event.PubKey, f.Authors) { return false } } // Check Kind if len(f.Kinds) > 0 { - if !matchesKinds(event.Kind, &f.Kinds) { + if !matchesKinds(event.Kind, f.Kinds) { return false } } @@ -194,7 +210,7 @@ func (f *Filter) Matches(event *Event) bool { // Check Tags if len(f.Tags) > 0 { - if !matchesTags(&event.Tags, &f.Tags) { + if !matchesTags(event.Tags, &f.Tags) { return false } } @@ -202,8 +218,8 @@ func (f *Filter) Matches(event *Event) bool { return true } -func matchesPrefix(candidate string, prefixes *[]string) bool { - for _, prefix := range *prefixes { +func matchesPrefix(candidate string, prefixes []string) bool { + for _, prefix := range prefixes { if strings.HasPrefix(candidate, prefix) { return true } @@ -211,8 +227,8 @@ func matchesPrefix(candidate string, prefixes *[]string) bool { return false } -func matchesKinds(candidate int, kinds *[]int) bool { - for _, kind := range *kinds { +func matchesKinds(candidate int, kinds []int) bool { + for _, kind := range kinds { if candidate == kind { return true } @@ -230,23 +246,32 @@ func matchesTimeRange(timestamp int, since *int, until *int) bool { return true } -func matchesTags(eventTags *[][]string, filterTags *map[string][]string) bool { - for tagName, filterValues := range *filterTags { +func matchesTags(eventTags []Tag, tagFilters *TagFilters) bool { + // Build index of tags and values + eventIndex := make(map[string][]string, len(eventTags)) + for _, tag := range eventTags { + if len(tag) < 2 { + continue + } + eventIndex[tag[0]] = append(eventIndex[tag[0]], tag[1]) + } + + // Check filters against the index + for tagName, filterValues := range *tagFilters { + // Skip empty tag filters (empty tag filters match all events) if len(filterValues) == 0 { - return true + continue + } + + eventValues, exists := eventIndex[tagName] + if !exists { + return false } found := false - for _, eventTag := range *eventTags { - if len(eventTag) < 2 { - continue - } - if eventTag[0] != tagName { - continue - } - - for _, filterValue := range filterValues { - if eventTag[1] == filterValue { + for _, filterVal := range filterValues { + for _, eventVal := range eventValues { + if eventVal == filterVal { found = true break } @@ -261,5 +286,6 @@ func matchesTags(eventTags *[][]string, filterTags *map[string][]string) bool { } } + // If no filter explicitly fails, then the event is matched return true } diff --git a/filter_match_test.go b/filter_match_test.go index 392e5c4..58261a9 100644 --- a/filter_match_test.go +++ b/filter_match_test.go @@ -19,6 +19,7 @@ func init() { } } +// Test keypairs corresponding to test events, for reference. var ( nayru_sk = "1784be782585dfa97712afe12585d13ee608b624cf564116fa143c31a124d31e" nayru_pk = "d877e187934bd942a71221b50ff2b426bd0777991b41b6c749119805dc40bcbe" @@ -225,7 +226,7 @@ var filterTestCases = []FilterTestCase{ { name: "empty tag filter", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "e": {}, }, }, @@ -245,7 +246,7 @@ var filterTestCases = []FilterTestCase{ { name: "single letter tag filter: e", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "e": {"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"}, }, }, @@ -255,7 +256,7 @@ var filterTestCases = []FilterTestCase{ { name: "multiple tag matches", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "e": { "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36", "ae3f2a91b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7", @@ -268,7 +269,7 @@ var filterTestCases = []FilterTestCase{ { name: "multiple tag matches - single event match", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "e": { "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36", "cb7787c460a79187d6a13e75a0f19240e05fafca8ea42288f5765773ea69cf2f", @@ -281,7 +282,7 @@ var filterTestCases = []FilterTestCase{ { name: "single letter tag filter: p", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "p": {"91cf9b32f3735070f46c0a86a820a47efa08a5be6c9f4f8cf68e5b5b75c92d60"}, }, }, @@ -291,7 +292,7 @@ var filterTestCases = []FilterTestCase{ { name: "multi letter tag filter", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "emoji": {"🌊"}, }, }, @@ -301,7 +302,7 @@ var filterTestCases = []FilterTestCase{ { name: "multiple tag filters", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "e": {"ae3f2a91b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7e9a1c5b4d8f2e7a9b6c3d8f7"}, "p": {"3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"}, }, @@ -312,7 +313,7 @@ var filterTestCases = []FilterTestCase{ { name: "prefix tag filter", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "p": {"ae3f2a91"}, }, }, @@ -322,7 +323,7 @@ var filterTestCases = []FilterTestCase{ { name: "unknown tag filter", filter: Filter{ - Tags: map[string][]string{ + Tags: TagFilters{ "z": {"anything"}, }, }, @@ -358,7 +359,7 @@ var filterTestCases = []FilterTestCase{ name: "combined author+tag tag filter", filter: Filter{ Authors: []string{"e719e8f8"}, - Tags: map[string][]string{ + Tags: TagFilters{ "power": {"fire"}, }, }, @@ -374,7 +375,7 @@ var filterTestCases = []FilterTestCase{ Kinds: []int{0}, Since: intPtr(5000), Until: intPtr(10000), - Tags: map[string][]string{ + Tags: TagFilters{ "power": {"fire"}, }, }, @@ -398,3 +399,21 @@ func TestEventFilterMatching(t *testing.T) { }) } } + +// TestEventFilterMatchingSkipMalformedTags documents that filter.Matches() +// skips malformed tags during tag matching +func TestEventFilterMatchingSkipMalformedTags(t *testing.T) { + event := Event{ + Tags: []Tag{ + {"malformed"}, + {"valid", "value"}, + }, + } + filter := Filter{ + Tags: TagFilters{ + "valid": {"value"}, + }, + } + + assert.True(t, filter.Matches(&event)) +} diff --git a/id.go b/id.go new file mode 100644 index 0000000..a98fa46 --- /dev/null +++ b/id.go @@ -0,0 +1,37 @@ +package roots + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" +) + +// Serialize returns the canonical JSON array representation of the event. +// used for ID computation: [0, pubkey, created_at, kind, tags, content]. +func (e *Event) Serialize() ([]byte, error) { + serialized := []interface{}{ + 0, + e.PubKey, + e.CreatedAt, + e.Kind, + e.Tags, + e.Content, + } + + bytes, err := json.Marshal(serialized) + if err != nil { + return []byte{}, err + } + return bytes, nil +} + +// GetID computes and returns the event ID as a lowercase, hex-encoded SHA-256 hash +// of the serialized event. +func (e *Event) GetID() (string, error) { + bytes, err := e.Serialize() + if err != nil { + return "", err + } + hash := sha256.Sum256(bytes) + return hex.EncodeToString(hash[:]), nil +} diff --git a/event_id_test.go b/id_test.go similarity index 91% rename from event_id_test.go rename to id_test.go index da23072..28b5910 100644 --- a/event_id_test.go +++ b/id_test.go @@ -18,7 +18,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "", }, expected: "13a55672a600398894592f4cb338652d4936caffe5d3718d11597582bb030c39", @@ -30,7 +30,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "hello world", }, expected: "c7a702e6158744ca03508bbb4c90f9dbb0d6e88fefbfaa511d5ab24b4e3c48ad", @@ -42,7 +42,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "hello world 😀", }, expected: "e42083fafbf9a39f97914fd9a27cedb38c429ac3ca8814288414eaad1f472fe8", @@ -54,7 +54,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "\"You say yes.\"\\n\\t\"I say no.\"", }, expected: "343de133996a766bf00561945b6f2b2717d4905275976ca75c1d7096b7d1900c", @@ -66,7 +66,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "{\"field\": [\"value\",\"value\"],\"numeral\": 123}", }, expected: "c6140190453ee947efb790e70541a9d37c41604d1f29e4185da4325621ed5270", @@ -78,7 +78,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{ + Tags: []Tag{ {"a", ""}, }, Content: "", @@ -92,7 +92,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{ + Tags: []Tag{ {"a", "value"}, }, Content: "", @@ -106,7 +106,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{ + Tags: []Tag{ {"a", "value", "optional"}, }, Content: "", @@ -120,7 +120,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{ + Tags: []Tag{ {"a", "value", "optional"}, {"b", "another"}, {"c", "data"}, @@ -136,7 +136,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 1, - Tags: [][]string{ + Tags: []Tag{ {"a", "😀"}, }, Content: "", @@ -150,7 +150,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: 0, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "", }, expected: "9ca742f2e2eea72ad6e0277a6287e2bb16a3e47d64b8468bc98474e266cf0ec2", @@ -162,7 +162,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: -1760740551, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "", }, expected: "4740b027040bb4d0ee8e885f567a80277097da70cddd143d8a6dadf97f6faaa3", @@ -174,7 +174,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: 9223372036854775807, Kind: 1, - Tags: [][]string{}, + Tags: []Tag{}, Content: "", }, expected: "b28cdd44496acb49e36c25859f0f819122829a12dc57c07612d5f44cb121d2a7", @@ -186,7 +186,7 @@ var idTestCases = []IDTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: 20021, - Tags: [][]string{}, + Tags: []Tag{}, Content: "", }, expected: "995c4894c264e6b9558cb94b7b34008768d53801b99960b47298d4e3e23fadd3", diff --git a/keys.go b/keys.go index 8b24382..c2c8d48 100644 --- a/keys.go +++ b/keys.go @@ -2,10 +2,11 @@ package roots import ( "encoding/hex" - "fmt" "github.com/decred/dcrd/dcrec/secp256k1/v4" ) +// GeneratePrivateKey generates a new, random secp256k1 private key and returns +// it as a 64-character, lowercase hexadecimal string. func GeneratePrivateKey() (string, error) { sk, err := secp256k1.GeneratePrivateKey() if err != nil { @@ -15,13 +16,15 @@ func GeneratePrivateKey() (string, error) { return hex.EncodeToString(skBytes), nil } +// GetPublicKey derives the public key from a private key hex string +// and returns the x-coordinate as 64 lowercase hex characters. func GetPublicKey(privateKeyHex string) (string, error) { if len(privateKeyHex) != 64 { - return "", fmt.Errorf("private key must be 64 hex characters") + return "", ErrMalformedPrivKey } skBytes, err := hex.DecodeString(privateKeyHex) if err != nil { - return "", fmt.Errorf("invalid private key hex: %w", err) + return "", ErrMalformedPrivKey } pk := secp256k1.PrivKeyFromBytes(skBytes).PubKey() diff --git a/keys_test.go b/keys_test.go index 8acd044..3f06791 100644 --- a/keys_test.go +++ b/keys_test.go @@ -26,5 +26,5 @@ func TestGetPublicKey(t *testing.T) { func TestGetPublicKeyInvalidPrivateKey(t *testing.T) { _, err := GetPublicKey("abc123") - assert.ErrorContains(t, err, "private key must be 64 hex characters") + assert.ErrorContains(t, err, "private key must be 64 lowercase hex characters") } diff --git a/sign.go b/sign.go new file mode 100644 index 0000000..a970959 --- /dev/null +++ b/sign.go @@ -0,0 +1,31 @@ +package roots + +import ( + "encoding/hex" + "fmt" + "github.com/btcsuite/btcd/btcec/v2" + "github.com/btcsuite/btcd/btcec/v2/schnorr" +) + +// SignEvent generates a Schnorr signature for the given event ID using the +// provided private key. Returns the signature as 128 lowercase hex characters. +func SignEvent(eventID, privateKeyHex string) (string, error) { + skBytes, err := hex.DecodeString(privateKeyHex) + if err != nil { + return "", ErrMalformedPrivKey + } + + idBytes, err := hex.DecodeString(eventID) + if err != nil { + return "", ErrMalformedID + } + + // discard public key return value + sk, _ := btcec.PrivKeyFromBytes(skBytes) + sig, err := schnorr.Sign(sk, idBytes) + if err != nil { + return "", fmt.Errorf("schnorr signature error: %w", err) + } + + return hex.EncodeToString(sig.Serialize()), nil +} diff --git a/event_sign_test.go b/sign_test.go similarity index 78% rename from event_sign_test.go rename to sign_test.go index b69f768..125181d 100644 --- a/event_sign_test.go +++ b/sign_test.go @@ -11,12 +11,12 @@ func TestSignEvent(t *testing.T) { actualSig, err := SignEvent(eventID, testSK) assert.NoError(t, err) - assert.Equal(t, actualSig, expectedSig) + assert.Equal(t, expectedSig, actualSig) } func TestSignInvalidEventID(t *testing.T) { badEventID := "thisisabadeventid" - expectedError := "invalid event id hex" + expectedError := "event id must be 64 hex characters" _, err := SignEvent(badEventID, testSK) @@ -26,7 +26,7 @@ func TestSignInvalidEventID(t *testing.T) { func TestSignInvalidPrivateKey(t *testing.T) { eventID := testEvent.ID badSK := "thisisabadsecretkey" - expectedError := "invalid private key hex" + expectedError := "private key must be 64 lowercase hex characters" _, err := SignEvent(eventID, badSK) diff --git a/validate.go b/validate.go new file mode 100644 index 0000000..c185e8c --- /dev/null +++ b/validate.go @@ -0,0 +1,96 @@ +package roots + +import ( + "encoding/hex" + "fmt" + + "github.com/btcsuite/btcd/btcec/v2/schnorr" +) + +// Validate performs a complete event validation: structure, ID computation, +// and signature verification. Returns the first error encountered. +func (e *Event) Validate() error { + if err := e.ValidateStructure(); err != nil { + return err + } + + if err := e.ValidateID(); err != nil { + return err + } + + return e.ValidateSignature() +} + +// ValidateStructure checks that all event fields conform to the protocol +// specification: hex lengths, tag structure, and field formats. +func (e *Event) ValidateStructure() error { + if !Hex64Pattern.MatchString(e.PubKey) { + return ErrMalformedPubKey + } + + if !Hex64Pattern.MatchString(e.ID) { + return ErrMalformedID + } + + if !Hex128Pattern.MatchString(e.Sig) { + return ErrMalformedSig + } + + for _, tag := range e.Tags { + if len(tag) < 2 { + return ErrMalformedTag + } + } + + return nil +} + +// ValidateID recomputes the event ID and verifies it matches the stored ID field. +func (e *Event) ValidateID() error { + computedID, err := e.GetID() + if err != nil { + return ErrFailedIDComp + } + if e.ID == "" { + return ErrNoEventID + } + if computedID != e.ID { + return fmt.Errorf("event id %q does not match computed id %q", e.ID, computedID) + } + return nil +} + +// ValidateSignature verifies the event signature is cryptographically valid +// for the event ID and public key using Schnorr verification. +func (e *Event) ValidateSignature() error { + idBytes, err := hex.DecodeString(e.ID) + if err != nil { + return fmt.Errorf("invalid event id hex: %w", err) + } + + sigBytes, err := hex.DecodeString(e.Sig) + if err != nil { + return fmt.Errorf("invalid event signature hex: %w", err) + } + + pkBytes, err := hex.DecodeString(e.PubKey) + if err != nil { + return fmt.Errorf("invalid public key hex: %w", err) + } + + signature, err := schnorr.ParseSignature(sigBytes) + if err != nil { + return fmt.Errorf("malformed signature: %w", err) + } + + publicKey, err := schnorr.ParsePubKey(pkBytes) + if err != nil { + return fmt.Errorf("malformed public key: %w", err) + } + + if signature.Verify(idBytes, publicKey) { + return nil + } else { + return ErrInvalidSig + } +} diff --git a/event_validate_test.go b/validate_test.go similarity index 87% rename from event_validate_test.go rename to validate_test.go index 3babfc8..a5b9964 100644 --- a/event_validate_test.go +++ b/validate_test.go @@ -23,7 +23,7 @@ var structureTestCases = []ValidateEventTestCase{ Content: testEvent.Content, Sig: testEvent.Sig, }, - expectedError: "pubkey must be 64 lowercase hex characters", + expectedError: "public key must be 64 lowercase hex characters", }, { @@ -37,7 +37,7 @@ var structureTestCases = []ValidateEventTestCase{ Content: testEvent.Content, Sig: testEvent.Sig, }, - expectedError: "pubkey must be 64 lowercase hex characters", + expectedError: "public key must be 64 lowercase hex characters", }, { @@ -51,7 +51,7 @@ var structureTestCases = []ValidateEventTestCase{ Content: testEvent.Content, Sig: testEvent.Sig, }, - expectedError: "pubkey must be 64 lowercase hex characters", + expectedError: "public key must be 64 lowercase hex characters", }, { @@ -65,7 +65,7 @@ var structureTestCases = []ValidateEventTestCase{ Content: testEvent.Content, Sig: testEvent.Sig, }, - expectedError: "pubkey must be 64 lowercase hex characters", + expectedError: "public key must be 64 lowercase hex characters", }, { @@ -79,7 +79,7 @@ var structureTestCases = []ValidateEventTestCase{ Content: testEvent.Content, Sig: testEvent.Sig, }, - expectedError: "pubkey must be 64 lowercase hex characters", + expectedError: "public key must be 64 lowercase hex characters", }, { @@ -145,7 +145,7 @@ var structureTestCases = []ValidateEventTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: testEvent.Kind, - Tags: [][]string{{}}, + Tags: []Tag{{}}, Content: testEvent.Content, Sig: testEvent.Sig, }, @@ -159,7 +159,7 @@ var structureTestCases = []ValidateEventTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: testEvent.Kind, - Tags: [][]string{{"a"}}, + Tags: []Tag{{"a"}}, Content: testEvent.Content, Sig: testEvent.Sig, }, @@ -173,7 +173,7 @@ var structureTestCases = []ValidateEventTestCase{ PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: testEvent.Kind, - Tags: [][]string{{"a", "value"}, {"b"}}, + Tags: []Tag{{"a", "value"}, {"b"}}, Content: testEvent.Content, Sig: testEvent.Sig, }, @@ -206,19 +206,23 @@ func TestValidateEventIDFailure(t *testing.T) { } func TestValidateSignature(t *testing.T) { - eventID := testEvent.ID - eventSig := testEvent.Sig - publicKey := testEvent.PubKey - err := ValidateSignature(eventID, eventSig, publicKey) + event := Event{ + ID: testEvent.ID, + PubKey: testEvent.PubKey, + Sig: testEvent.Sig, + } + err := event.ValidateSignature() assert.NoError(t, err) } func TestValidateInvalidSignature(t *testing.T) { - eventID := testEvent.ID - eventSig := "9e43cbcf7e828a21c53fa35371ee79bffbfd7a3063ae46fc05ec623dd3186667c57e3d006488015e19247df35eb41c61013e051aa87860e23fa5ffbd44120482" - publicKey := testEvent.PubKey - err := ValidateSignature(eventID, eventSig, publicKey) + event := Event{ + ID: testEvent.ID, + PubKey: testEvent.PubKey, + Sig: "9e43cbcf7e828a21c53fa35371ee79bffbfd7a3063ae46fc05ec623dd3186667c57e3d006488015e19247df35eb41c61013e051aa87860e23fa5ffbd44120482", + } + err := event.ValidateSignature() assert.ErrorContains(t, err, "event signature is invalid") } @@ -276,7 +280,8 @@ var validateSignatureTestCases = []ValidateSignatureTestCase{ func TestValidateSignatureInvalidEventSignature(t *testing.T) { for _, tc := range validateSignatureTestCases { t.Run(tc.name, func(t *testing.T) { - err := ValidateSignature(tc.id, tc.sig, tc.pubkey) + event := Event{ID: tc.id, PubKey: tc.pubkey, Sig: tc.sig} + err := event.ValidateSignature() assert.ErrorContains(t, err, tc.expectedError) }) } @@ -288,7 +293,7 @@ func TestValidateEvent(t *testing.T) { PubKey: testEvent.PubKey, CreatedAt: testEvent.CreatedAt, Kind: testEvent.Kind, - Tags: [][]string{ + Tags: []Tag{ {"a", "value"}, {"b", "value", "optional"}, },