nostr 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 168cbde3fb029345d4fa10043eead7c194a57fe3ee23c12b76bbaf79b1bdc71d
-  data.tar.gz: ff1a1837e897a8c0ad233a61ed4526fe3e4087c04474e54778a00a0d4313e361
+  metadata.gz: dcfeb88b78cad383e565b6e908be58f58e6f1002083044957ee0f09cf63228f4
+  data.tar.gz: ca2229181586e8bf5f329e4d5ac60ad346076fc8e39281dd43690d57ac98fcb7
 SHA512:
-  metadata.gz: e5549507ded84026a2295c3914324e8c74aff3c1ae80322db3cd449e7f65c3475186e9daaa76f7a22241e33b6759c2073da5a31a910a2082c8e49a99081dc5bf
-  data.tar.gz: 19f69ed10ae3ba42113992541912bb18a4aa3ad8239b582b996e7c7845c4624c4a9ee73d800f51fbd883d2bdd9ea603eeb807ade147bcfc22db7183c1db30ce6
+  metadata.gz: 4511decc634548b75429db9166433060795295aea61cda64cd7b2b2647415db3808f4def27f8a4806d77b6fbaef88b11d08788254febd66bcfb7be318059cced
+  data.tar.gz: aef568e9fad07e0b387e3ae1437a50d08c81b59485c8aadd42cd9d7a035319b3da2bd5247e7d58fc890961eec5e0284d9299e6631c674cce3df3a5c210202bf2

data/.adr-dir

@@ -0,0 +1 @@
+adr

data/.rubocop.yml

@@ -5,7 +5,7 @@ require:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.3
   DisplayCopNames: true
   NewCops: enable
 

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 3.2.2
-bun 1.0.11
+ruby 3.3.0
+bun 1.0.30

data/CHANGELOG.md

@@ -4,13 +4,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.1/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] 2024-03-15
+
+### Added
+
+- Added Architecture Decision Records (ADRs) to document architectural decisions
+- Added the `Signature` class to fix the primitive obsession with signatures and to make it easier to work with them
+- Added `valid_sig?` and `check_sig!` to the `Crypto` class to verify whether an event's signature is valid
+- Added `sign_message` to the `Crypto` class to sign a message
+- Added `verify_signature?` to the `Event` class to verify whether an event's signature is valid
+- Added `#to_ary` to the `KeyPair` class to enable keypair destructuring
+- Added RBS types for `schnorr`
+
+### Changed
+
+- Updated the required Ruby version to `3.3.0` (was `3.2.0`)
+- Updated the gem `dotenv` to version `3.1` (was `2.8`)
+- Updated the gem `bip-schnorr` to version `0.7` (was `0.6`)
+- Updated the gem `overcommit` to version `0.63` (was `0.59`)
+- Updated the gem `rbs` to version `3.4` (was `3.3`)
+- Updated the gem `rspec` to version `3.13` (was `3.12`)
+- Updated the gem `rspec-rubocop` to version `2.27` (was `2.25`)
+- Updated the gem `rubocop` to version `1.62` (was `1.57`)
+
+## Fixed
+
+- Fixed a typo in the README (`generate_keypair` -> `generate_key_pair`)
+- Fixed a typo in the YARD documentation of `Nostr::Key#initialize` (`ValidationError` -> `KeyValidationError`)
+
+### Fixed
+
+- Fixed YARD example rendering issues in `InvalidKeyFormatError#initialize`, `InvalidKeyLengthError#initialize`,
+`InvalidKeyTypeError#initialize`, `Event#initialize`, `EncryptedDirectMessage#initialize` and `Filter#to_h`
+
 ## [0.5.0] 2023-11-20
 
 ### Added
 
 - Added relay message type enums `Nostr::RelayMessageType`
 - Compliance with [NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md) - bech32-formatted strings
-- `Nostr::PrivateKey` and `Nostr::PublicKey` to represent private and public keys, respectively
+- Added `Nostr::PrivateKey` and `Nostr::PublicKey` to represent private and public keys, respectively
 - Added a validation of private and public keys
 - Added an ability to convert keys to and from Bech32 format
 - Added RBS types for `faye-websocket` and `bech32`
@@ -82,6 +115,7 @@ principles of immutability and was a major source of internal complexity as I ne
 
 - Initial release
 
+[0.6.0]: https://github.com/wilsonsilva/nostr/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/wilsonsilva/nostr/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/wilsonsilva/nostr/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/wilsonsilva/nostr/compare/v0.2.0...v0.3.0

data/README.md

@@ -1,6 +1,7 @@
 # Nostr
 
 [![Gem Version](https://badge.fury.io/rb/nostr.svg)](https://badge.fury.io/rb/nostr)
+![Build](https://github.com/wilsonsilva/nostr/actions/workflows/main.yml/badge.svg)
 [![Maintainability](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/maintainability)](https://codeclimate.com/github/wilsonsilva/nostr/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/test_coverage)](https://codeclimate.com/github/wilsonsilva/nostr/test_coverage)
 
@@ -63,7 +64,7 @@ keypair = keygen.get_key_pair_from_private_key(
 
 # c) Or create a new keypair
 keygen = Nostr::Keygen.new
-keypair = keygen.generate_keypair
+keypair = keygen.generate_key_pair
 
 # Create a user with the keypair
 user = Nostr::User.new(keypair: keypair)

data/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2024-03-13
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

data/adr/0002-introduction-of-signature-class.md

@@ -0,0 +1,27 @@
+# 2. introduction-of-signature-class
+
+Date: 2024-03-14
+
+## Status
+
+Accepted
+
+## Context
+
+I noticed significant overuse of primitive strings for signatures, which led to widespread and repetitive validation logic, increasing the potential for errors and making the system harder to manage and maintain.
+
+## Decision
+
+I introduced the Nostr::Signature class, choosing to subclass String to leverage string-like behavior while embedding specific validation rules for signatures. This move was aimed at streamlining validation, ensuring consistency, and maintaining the usability of strings.
+
+## Consequences
+
+### Positive
+
+- This design choice has made the codebase cleaner and more robust, reducing the chances of errors related to signature handling. It ensures that all signature instances are valid at creation, leveraging the familiarity and flexibility of string operations without sacrificing the integrity of the data. Moreover, it sets a strong foundation for extending signature-related functionality in the future.
+
+### Negative
+
+- __Performance Concerns:__ Subclassing String might introduce slight performance overheads due to the additional validation logic executed upon instantiation of a Signature object.
+- __Integration Challenges:__ Integrating this class into existing systems where strings were used indiscriminately for signatures requires careful refactoring to ensure compatibility. There's also the potential for issues when passing Nostr::Signature objects to libraries or APIs expecting plain strings without the additional constraints.
+- __Learning Curve:__ For new team members or contributors, understanding the necessity and functionality of the Nostr::Signature class adds to the learning curve, potentially slowing down initial development efforts as they familiarize themselves with the custom implementation.

data/docs/.vitepress/config.mjs

@@ -79,6 +79,8 @@ export default defineConfig(withMermaid({
         collapsed: false,
         items: [
           { text: 'Bech32 enc/decoding (NIP-19)', link: '/common-use-cases/bech32-encoding-and-decoding-(NIP-19)' },
+          { text: 'Signing/verifying messages', link: '/common-use-cases/signing-and-verifying-messages' },
+          { text: 'Signing/verifying events', link: '/common-use-cases/signing-and-verifying-events' },
         ]
       },
       {

data/docs/common-use-cases/signing-and-verifying-events.md

@@ -0,0 +1,50 @@
+# Signing and verifying events
+
+Signing an event in Nostr proves it was sent by the owner of a specific private key.
+
+## Signing an event
+
+To sign an event, use the private key associated with the event's creator. Here's how to sign a message using a
+predefined keypair:
+
+```ruby{14}
+require 'nostr'
+
+private_key = Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+public_key = Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+
+event = Nostr::Event.new(
+  pubkey: public_key.to_s,
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'We did it with security, now we’re going to do it with the economy.',
+  created_at: Time.now.to_i,
+)
+
+# Sign the event with the private key
+event.sign(private_key)
+
+puts "Event ID: #{event.id}"
+puts "Event Signature: #{event.sig}"
+```
+
+## Verifying an event's signature
+
+To verify an event, you must ensure the event's signature is valid. This indicates the event was created by the owner
+of the corresponding public key.
+
+When the event was signed with the private key corresponding to the public key, the `verify_signature` method will
+return `true`.
+
+```ruby
+event.verify_signature # => true
+```
+
+And when the event was not signed with the private key corresponding to the public key, the `verify_signature` method
+will return `false`.
+
+An event without an `id`, `pubkey`, `sig` is considered invalid and will return `false` when calling `verify_signature`.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+event.verify_signature # => false
+```

data/docs/common-use-cases/signing-and-verifying-messages.md

@@ -0,0 +1,43 @@
+# Signing and verifying messages
+
+Signing a message in Nostr proves it was sent by the owner of a specific private key.
+
+## Signing a message
+
+To sign a message, you'll need a private key. Here's how to sign a message using a predefined keypair:
+
+```ruby{9}
+require 'nostr'
+
+private_key = Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+public_key = Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+
+message = 'We did it with security, now we’re going to do it with the economy.' # The message you want to sign
+
+crypto = Nostr::Crypto.new
+signature = crypto.sign_message(message, private_key)
+signature # => "d7a0aac1fadcddf1aa2949bedfcdf25ce0c1604e648e55d31431fdacbff8e8256f7c2166d98292f80bc5f79105a0b6e8a89236a47d97cf5d0e7cc1ebf34dea5c"
+```
+
+## Verifying a signature
+
+To verify a signature, you need the original message, the public key of the signer, and the signature.
+
+```ruby
+crypto.valid_sig?(message, public_key, signature) # => true
+crypto.check_sig!(message, public_key, signature) # => true
+```
+
+When the message was not signed with the private key corresponding to the public key, the `valid_sig?` method will return `false`.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+crypto.valid_sig?(message, public_key, signature) # => false
+```
+
+And when the message was not signed with the private key corresponding to the public key, the `check_sig!` method will raise an error.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+crypto.check_sig!(message, other_public_key, signature) # => Schnorr::InvalidSignatureError: signature verification failed
+```

data/docs/getting-started/overview.md

@@ -35,6 +35,7 @@ classDiagram
         serialize()
         to_h()
         sign(private_key)
+        verify_signature()
     }
     class Subscription {
         id
@@ -110,7 +111,7 @@ keypair = keygen.get_key_pair_from_private_key(
 
 # c) Or create a new keypair
 keygen = Nostr::Keygen.new
-keypair = keygen.generate_keypair
+keypair = keygen.generate_key_pair
 
 # Create a user with the keypair
 user = Nostr::User.new(keypair: keypair)

data/docs/index.md

@@ -39,6 +39,4 @@ features:
   - title: Fully typed
     details: All code is typed with <a href="https://rubygems.org/gems/rbs" target="_blank">RBS</a> with the help of <a href="https://rubygems.org/gems/typeprof" target="_blank">TypeProf</a>. Type correctness is enforced by <a href="https://rubygems.org/gems/steep" target="_blank">Steep</a>.
     icon: ✅
-
 ---
-

data/lib/nostr/crypto.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Nostr
-  # Performs cryptographic operations on a +Nostr::Event+.
+  # Performs cryptographic operations.
   class Crypto
     # Numeric base of the OpenSSL big number used in an event content's encryption.
     #
@@ -90,17 +90,93 @@ module Nostr
     #
     def sign_event(event, private_key)
       event_digest = hash_event(event)
-
-      hex_private_key = Array(private_key).pack('H*')
-      hex_message     = Array(event_digest).pack('H*')
-      event_signature = Schnorr.sign(hex_message, hex_private_key).encode.unpack1('H*')
+      signature = sign_message(event_digest, private_key)
 
       event.id = event_digest
-      event.sig = event_signature
+      event.sig = signature
 
       event
     end
 
+    # Signs a message using the Schnorr signature algorithm
+    #
+    # @api public
+    #
+    # @example Signing a message
+    #   crypto = Nostr::Crypto.new
+    #   message = 'Viva la libertad carajo'
+    #   private_key = Nostr::PrivateKey.new('7d1e4219a5e7d8342654c675085bfbdee143f0eb0f0921f5541ef1705a2b407d')
+    #   signature = crypto.sign_message(message, private_key)
+    #   signature # => 'b2115694a576f5bdcebf8c0951a3c7adcfbdb17b11cb9e6d6b7017691138bc6' \
+    #     '38fee642a7bd26f71b313a7057181294198900a9770d1435e43f182acf3d34c26'
+    #
+    # @param [String] message The message to be signed
+    # @param [PrivateKey] private_key The private key used for signing
+    #
+    # @return [Signature] A signature object containing the signature as a 64-byte hexadecimal string.
+    #
+    def sign_message(message, private_key)
+      hex_private_key = Array(private_key).pack('H*')
+      hex_message     = Array(message).pack('H*')
+      hex_signature   = Schnorr.sign(hex_message, hex_private_key).encode.unpack1('H*')
+
+      Signature.new(hex_signature.to_s)
+    end
+
+    # Verifies the given {Signature} and returns true if it is valid
+    #
+    # @api public
+    #
+    # @example Checking a signature
+    #   public_key = Nostr::PublicKey.new('15678d8fbc126fa326fac536acd5a6dcb5ef64b3d939abe31d6830cba6cd26d6')
+    #   private_key = Nostr::PrivateKey.new('7d1e4219a5e7d8342654c675085bfbdee143f0eb0f0921f5541ef1705a2b407d')
+    #   message = 'Viva la libertad carajo'
+    #   crypto = Nostr::Crypto.new
+    #   signature = crypto.sign_message(message, private_key)
+    #   valid = crypto.valid_sig?(message, public_key, signature)
+    #   valid # => true
+    #
+    # @see #check_sig!
+    #
+    # @param [String] message A message to be signed with binary format.
+    # @param [PublicKey] public_key The public key with binary format.
+    # @param [Signature] signature The signature with binary format.
+    #
+    # @return [Boolean] whether signature is valid.
+    #
+    def valid_sig?(message, public_key, signature)
+      signature = Schnorr::Signature.decode([signature].pack('H*'))
+      Schnorr.valid_sig?([message].pack('H*'), [public_key].pack('H*'), signature.encode)
+    end
+
+    # Verifies the given {Signature} and raises an +Schnorr::InvalidSignatureError+ if it is invalid
+    #
+    # @api public
+    #
+    # @example Checking a signature
+    #   public_key = Nostr::PublicKey.new('15678d8fbc126fa326fac536acd5a6dcb5ef64b3d939abe31d6830cba6cd26d6')
+    #   private_key = Nostr::PrivateKey.new('7d1e4219a5e7d8342654c675085bfbdee143f0eb0f0921f5541ef1705a2b407d')
+    #   message = 'Viva la libertad carajo'
+    #   crypto = Nostr::Crypto.new
+    #   signature = crypto.sign_message(message, private_key)
+    #   valid = crypto.valid_sig?(message, public_key, signature)
+    #   valid # => true
+    #
+    # @see #valid_sig?
+    #
+    # @param [String] message A message to be signed with binary format.
+    # @param [PublicKey] public_key The public key with binary format.
+    # @param [Signature] signature The signature with binary format.
+    #
+    # @raise [Schnorr::InvalidSignatureError] if the signature is invalid.
+    #
+    # @return [Boolean] whether signature is valid.
+    #
+    def check_sig!(message, public_key, signature)
+      signature = Schnorr::Signature.decode([signature].pack('H*'))
+      Schnorr.check_sig!([message].pack('H*'), [public_key].pack('H*'), signature.encode)
+    end
+
     private
 
     # Finds a shared key between two keys

data/lib/nostr/errors/invalid_key_format_error.rb

@@ -9,7 +9,7 @@ module Nostr
     # Initializes the error
     #
     # @example
-    #   InvalidKeyFormatError.new('private'')
+    #   InvalidKeyFormatError.new('private')
     #
     # @param [String] key_kind The kind of key that is invalid (public or private)
     #

data/lib/nostr/errors/invalid_key_length_error.rb

@@ -9,7 +9,7 @@ module Nostr
     # Initializes the error
     #
     # @example
-    #   InvalidKeyLengthError.new('private'')
+    #   InvalidKeyLengthError.new('private')
     #
     # @param [String] key_kind The kind of key that is invalid (public or private)
     #

data/lib/nostr/errors/invalid_key_type_error.rb

@@ -9,7 +9,7 @@ module Nostr
     # Initializes the error
     #
     # @example
-    #   InvalidKeyTypeError.new('private'')
+    #   InvalidKeyTypeError.new('private')
     #
     # @param [String] key_kind The kind of key that is invalid (public or private)
     #

data/lib/nostr/errors/invalid_signature_format_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the signature is in an invalid format
+  #
+  # @api public
+  #
+  class InvalidSignatureFormatError < SignatureValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidSignatureFormatError.new
+    #
+    def initialize
+      super('Only lowercase hexadecimal characters are allowed in signatures.')
+    end
+  end
+end

data/lib/nostr/errors/invalid_signature_length_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the signature's length is not 128 characters
+  #
+  # @api public
+  #
+  class InvalidSignatureLengthError < SignatureValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidSignatureLengthError.new
+    #
+    def initialize
+      super('Invalid signature length. It should have 128 characters.')
+    end
+  end
+end

data/lib/nostr/errors/invalid_signature_type_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the signature is not a string
+  #
+  # @api public
+  #
+  class InvalidSignatureTypeError < SignatureValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidSignatureTypeError.new
+    #
+    def initialize = super('Invalid signature type')
+  end
+end

data/lib/nostr/errors/signature_validation_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Base class for all signature validation errors
+  class SignatureValidationError < Error; end
+end

data/lib/nostr/errors.rb

@@ -6,3 +6,7 @@ require_relative 'errors/invalid_hrp_error'
 require_relative 'errors/invalid_key_type_error'
 require_relative 'errors/invalid_key_length_error'
 require_relative 'errors/invalid_key_format_error'
+require_relative 'errors/signature_validation_error'
+require_relative 'errors/invalid_signature_type_error'
+require_relative 'errors/invalid_signature_length_error'
+require_relative 'errors/invalid_signature_format_error'

data/lib/nostr/event.rb

@@ -100,15 +100,15 @@ module Nostr
     #
     # @example Instantiating a new event
     #   Nostr::Event.new(
-    #    id: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
-    #    pubkey: '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e',
-    #    created_at: 1230981305,
-    #    kind: 1,
-    #    tags: [],
-    #    content: 'Your feedback is appreciated, now pay $8',
-    #    sig: '123ac2923b792ce730b3da34f16155470ab13c8f97f9c53eaeb334f1fb3a5dc9a7f643
-    #          937c6d6e9855477638f5655c5d89c9aa5501ea9b578a66aced4f1cd7b3'
-    # )
+    #     id: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
+    #     pubkey: '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e',
+    #     created_at: 1230981305,
+    #     kind: 1,
+    #     tags: [],
+    #     content: 'Your feedback is appreciated, now pay $8',
+    #     sig: '123ac2923b792ce730b3da34f16155470ab13c8f97f9c53eaeb334f1fb3a5dc9a7f643
+    #           937c6d6e9855477638f5655c5d89c9aa5501ea9b578a66aced4f1cd7b3'
+    #   )
     #
     # @param id [String|nil] 32-bytes sha256 of the the serialized event data.
     # @param sig [String|nil] 64-bytes signature of the sha256 hash of the serialized event data, which is
@@ -181,6 +181,34 @@ module Nostr
       crypto.sign_event(self, private_key)
     end
 
+    # Verifies if the signature of the event is valid. A valid signature means that the event was signed by the owner
+    #
+    # @api public
+    #
+    # @example Verifying the signature of an event
+    #   event = Nostr::Event.new(
+    #     id: '90b75b78daf883ae57fbcc414d43faa028560b3211ee58e4ea82bf395bb82042',
+    #     pubkey: Nostr::PublicKey.new('2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558'),
+    #     created_at: 1667422587,
+    #     kind: Nostr::EventKind::TEXT_NOTE,
+    #     content: 'Your feedback is appreciated, now pay $8',
+    #     sig: '32f18adebe942e19b171c1c7d2fb27ce794dfea4155e289dca7952b43ed1ec39' \
+    #       '1d3dc198ba2761bc6d40c737a6eaf4edcc8963acabd3bfcebd04f16637025bdc'
+    #   )
+    #
+    #   event.verify_signature # => true
+    #
+    # @return [Boolean] Whether the signature is valid or not.
+    #
+    def verify_signature
+      crypto = Crypto.new
+
+      return false if id.nil? || pubkey.nil?
+      return false if sig.nil? # FIXME: See https://github.com/soutaro/steep/issues/1079
+
+      crypto.valid_sig?(id, pubkey, sig)
+    end
+
     # Serializes the event, to obtain a SHA256 digest of it
     #
     # @api public

data/lib/nostr/event_kind.rb

@@ -21,6 +21,7 @@ module Nostr
     # The content is set to the URL (e.g., wss://somerelay.com) of a relay the event creator wants to
     # recommend to its followers.
     #
+    # @deprecated This event kind was removed in https://github.com/nostr-protocol/nips/pull/703/files#diff-39307f1617417657ee9874be314f13aabdc74401b124d0afe8217f2919c9c7d8L105
     # @return [Integer]
     #
     RECOMMEND_SERVER = 2

data/lib/nostr/events/encrypted_direct_message.rb

@@ -11,19 +11,19 @@ module Nostr
       # @api public
       #
       # @example Instantiating a new encrypted direct message
-      #   Nostr::Events::EncryptedDirectMessage.new(
+      #  Nostr::Events::EncryptedDirectMessage.new(
       #    sender_private_key: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
       #    recipient_public_key: '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e',
       #    plain_text: 'Your feedback is appreciated, now pay $8',
-      # )
+      #  )
       #
       # @example Instantiating a new encrypted direct message that references a previous direct message
-      #   Nostr::Events::EncryptedDirectMessage.new(
+      #  Nostr::Events::EncryptedDirectMessage.new(
       #    sender_private_key: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
       #    recipient_public_key: '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e',
       #    plain_text: 'Your feedback is appreciated, now pay $8',
       #    previous_direct_message: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460'
-      # )
+      #  )
       #
       # @param plain_text [String] The +content+ of the encrypted message.
       # @param sender_private_key [PrivateKey] 32-bytes hex-encoded private key of the message's author.

data/lib/nostr/filter.rb

@@ -133,13 +133,16 @@ module Nostr
     # @api public
     #
     # @example
-    #   filter.to_h # => {:ids=>["c24881c305c5cfb7c1168be7e9b0e150"],
-    #    :authors=>["000000001c5c45196786e79f83d21fe801549fdc98e2c26f96dcef068a5dbcd7"],
-    #    :kinds=>[0, 1, 2],
-    #    :"#e"=>["7bdb422f254194ae4bb86d354c0bd5a888fce233ffc77dceb3e844ceec1fcfb2"],
-    #    :"#p"=>["000000001c5c45196786e79f83d21fe801549fdc98e2c26f96dcef068a5dbcd7"],
-    #    :since=>1230981305,
-    #    :until=>1292190341}
+    #   filter.to_h # =>
+    #   {
+    #      ids: ['c24881c305c5cfb7c1168be7e9b0e150'],
+    #      authors: ['000000001c5c45196786e79f83d21fe801549fdc98e2c26f96dcef068a5dbcd7'],
+    #      kinds: [0, 1, 2],
+    #      '#e': ['7bdb422f254194ae4bb86d354c0bd5a888fce233ffc77dceb3e844ceec1fcfb2'],
+    #      '#p': ['000000001c5c45196786e79f83d21fe801549fdc98e2c26f96dcef068a5dbcd7'],
+    #      since: 1230981305,
+    #      until: 1292190341
+    #   }
     #
     # @return [Hash] The filter as a hash.
     #

data/lib/nostr/key.rb

@@ -18,14 +18,14 @@ module Nostr
     #
     LENGTH = 64
 
-    # Instantiates a new key. Can't be used directly because this is an abstract class. Raises a +ValidationError+
+    # Instantiates a new key. Can't be used directly because this is an abstract class. Raises a +KeyValidationError+
     #
     # @see Nostr::PrivateKey
     # @see Nostr::PublicKey
     #
     # @param [String] hex_value Hex-encoded value of the key
     #
-    # @raise [ValidationError]
+    # @raise [KeyValidationError]
     #
     def initialize(hex_value)
       validate_hex_value(hex_value)

data/lib/nostr/key_pair.rb

@@ -38,8 +38,8 @@ module Nostr
     # @param private_key [PrivateKey] 32-bytes hex-encoded private key.
     # @param public_key [PublicKey] 32-bytes hex-encoded public key.
     #
-    # @raise ArgumentError when the private key is not a +PrivateKey+
-    # @raise ArgumentError when the public key is not a +PublicKey+
+    # @raise ArgumentError when the private key is not a {PrivateKey}
+    # @raise ArgumentError when the public key is not a {PublicKey}
     #
     def initialize(private_key:, public_key:)
       validate_keys(private_key, public_key)
@@ -48,6 +48,30 @@ module Nostr
       @public_key = public_key
     end
 
+    # Allows array destructuring of the KeyPair, enabling the extraction of +PrivateKey+ and +PublicKey+ separately
+    #
+    # @api public
+    #
+    # @example Implicit usage of `to_ary` for destructuring
+    #   keypair = Nostr::KeyPair.new(
+    #     private_key: Nostr::PrivateKey.new('7d1e4219a5e7d8342654c675085bfbdee143f0eb0f0921f5541ef1705a2b407d'),
+    #     public_key: Nostr::PublicKey.new('15678d8fbc126fa326fac536acd5a6dcb5ef64b3d939abe31d6830cba6cd26d6'),
+    #   )
+    #   # The `to_ary` method can be implicitly used for array destructuring:
+    #   private_key, public_key = keypair
+    #   # Now `private_key` and `public_key` hold the respective values.
+    #
+    # @example Explicit usage of `to_ary`
+    #   array_representation = keypair.to_ary
+    #   # array_representation is now an array: [PrivateKey, PublicKey]
+    #   # where PrivateKey and PublicKey are the respective objects.
+    #
+    # @return [Array<PrivateKey, PublicKey>] An array containing the {PrivateKey} and {PublicKey} in that order
+    #
+    def to_ary
+      [private_key, public_key]
+    end
+
     private
 
     # Validates the keys

data/lib/nostr/keygen.rb

@@ -22,7 +22,7 @@ module Nostr
     # @api public
     #
     # @example
-    #   keypair = keygen.generate_keypair
+    #   keypair = keygen.generate_key_pair
     #   keypair # #<Nostr::KeyPair:0x0000000107bd3550
     #    @private_key="893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900",
     #    @public_key="2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558">

data/lib/nostr/signature.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Nostr
+  # 64-bytes lowercase hex of the signature of the sha256 hash of the serialized event data,
+  # which is the same as the "id" field
+  class Signature < String
+    # The regular expression for hexadecimal lowercase characters
+    #
+    # @return [Regexp] The regular expression for hexadecimal lowercase characters
+    #
+    FORMAT = /^[a-f0-9]+$/
+
+    # The length of the signature in hex format
+    #
+    # @return [Integer] The length of the signature in hex format
+    #
+    LENGTH = 128
+
+    # Instantiates a new Signature
+    #
+    # @api public
+    #
+    # @example Instantiating a new signature
+    #  Nostr::Signature.new(
+    #    'f418c97b50cc68227e82f4f3a79d79eb2b7a0fa517859c86e1a8fa91e3741b7f' \
+    #    '06e070c44129227b83fcbe93cecb02a346804a4080ce47685ecad60ab4f5f128'
+    #  )
+    #
+    # @param [String] hex_value Hex-encoded value of the signature
+    #
+    # @raise [SignatureValidationError]
+    #
+    def initialize(hex_value)
+      validate(hex_value)
+
+      super(hex_value)
+    end
+
+    private
+
+    # Hex-encoded value of the signature
+    #
+    # @api private
+    #
+    # @return [String] hex_value Hex-encoded value of the signature
+    #
+    attr_reader :hex_value
+
+    # Validates the hex value of the signature
+    #
+    # @api private
+    #
+    # @param [String] hex_value The signature in hex format
+    #
+    # @raise InvalidSignatureTypeError when the signature is not a string
+    # @raise InvalidSignatureLengthError when the signature's length is not 128 characters
+    # @raise InvalidSignatureFormatError when the signature is in an invalid format
+    #
+    # @return [void]
+    #
+    def validate(hex_value)
+      raise InvalidSignatureTypeError   unless hex_value.is_a?(String)
+      raise InvalidSignatureLengthError unless hex_value.size == LENGTH
+      raise InvalidSignatureFormatError unless hex_value.match(FORMAT)
+    end
+  end
+end

data/lib/nostr/version.rb

@@ -2,5 +2,5 @@
 
 module Nostr
   # The version of the gem
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/nostr.rb

@@ -12,6 +12,7 @@ require_relative 'nostr/relay'
 require_relative 'nostr/relay_message_type'
 require_relative 'nostr/key_pair'
 require_relative 'nostr/event_kind'
+require_relative 'nostr/signature'
 require_relative 'nostr/event'
 require_relative 'nostr/events/encrypted_direct_message'
 require_relative 'nostr/client'

data/nostr.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = 'Client and relay implementation of the Nostr protocol.'
   spec.homepage = 'https://nostr-ruby.com/'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.2.0'
+  spec.required_ruby_version = '>= 3.3.0'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.metadata['homepage_uri'] = spec.homepage
@@ -32,29 +32,29 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'bech32', '~> 1.4'
-  spec.add_dependency 'bip-schnorr', '~> 0.6'
+  spec.add_dependency 'bip-schnorr', '~> 0.7'
   spec.add_dependency 'ecdsa', '~> 1.2'
   spec.add_dependency 'event_emitter', '~> 0.2'
   spec.add_dependency 'faye-websocket', '~> 0.11'
   spec.add_dependency 'json', '~> 2.6'
 
   spec.add_development_dependency 'bundler-audit', '~> 0.9'
-  spec.add_development_dependency 'dotenv', '~> 2.8'
+  spec.add_development_dependency 'dotenv', '~> 3.1'
   spec.add_development_dependency 'guard', '~> 2.18'
   spec.add_development_dependency 'guard-bundler', '~> 3.0'
   spec.add_development_dependency 'guard-bundler-audit', '~> 0.1'
   spec.add_development_dependency 'guard-rspec', '~> 4.7'
   spec.add_development_dependency 'guard-rubocop', '~> 1.5'
-  spec.add_development_dependency 'overcommit', '~> 0.59'
+  spec.add_development_dependency 'overcommit', '~> 0.63'
   spec.add_development_dependency 'pry', '~> 0.14'
   spec.add_development_dependency 'puma', '~> 6.4'
   spec.add_development_dependency 'rack', '~> 3.0'
   spec.add_development_dependency 'rake', '~> 13.1'
-  spec.add_development_dependency 'rbs', '~> 3.3'
-  spec.add_development_dependency 'rspec', '~> 3.12'
-  spec.add_development_dependency 'rubocop', '~> 1.57'
+  spec.add_development_dependency 'rbs', '~> 3.4'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.62'
   spec.add_development_dependency 'rubocop-rake', '~> 0.6'
-  spec.add_development_dependency 'rubocop-rspec', '2.25'
+  spec.add_development_dependency 'rubocop-rspec', '2.27'
   spec.add_development_dependency 'simplecov', '= 0.17'
   spec.add_development_dependency 'simplecov-console', '~> 0.9'
   spec.add_development_dependency 'steep', '~> 1.6'

data/sig/nostr/crypto.rbs

@@ -7,6 +7,9 @@ module Nostr
     def encrypt_text: (PrivateKey, PublicKey, String) -> String
     def decrypt_text: (PrivateKey, PublicKey, String) -> String
     def sign_event: (Event, PrivateKey) -> Event
+    def sign_message: (String, PrivateKey) -> Signature
+    def valid_sig?: (String, PublicKey, Signature) -> bool
+    def check_sig!: (String, PublicKey, Signature) -> bool
 
     private
 

data/sig/nostr/errors/invalid_signature_format_error.rbs

@@ -0,0 +1,5 @@
+module Nostr
+  class InvalidSignatureFormatError < SignatureValidationError
+    def initialize: -> void
+  end
+end

data/sig/nostr/errors/invalid_signature_length_error.rbs

@@ -0,0 +1,5 @@
+module Nostr
+  class InvalidSignatureLengthError < SignatureValidationError
+    def initialize: -> void
+  end
+end

data/sig/nostr/errors/invalid_signature_type_error.rbs

@@ -0,0 +1,5 @@
+module Nostr
+  class InvalidSignatureTypeError < SignatureValidationError
+    def initialize: -> void
+  end
+end

data/sig/nostr/errors/signature_validation_error.rbs

@@ -0,0 +1,4 @@
+module Nostr
+  class SignatureValidationError < Error
+  end
+end

data/sig/nostr/event.rbs

@@ -5,8 +5,8 @@ module Nostr
     attr_reader kind: Integer
     attr_reader tags: Array[Array[String]]
     attr_reader content: String
-    attr_accessor id: String?|nil
-    attr_accessor sig: String?|nil
+    attr_accessor id: String?
+    attr_accessor sig: Signature?
 
     def initialize: (
       pubkey: PublicKey,
@@ -14,24 +14,25 @@ module Nostr
       content: String,
       ?created_at: Integer,
       ?tags: Array[Array[String]],
-      ?id: String|nil,
-      ?sig: String|nil
+      ?id: String?,
+      ?sig: Signature?
     ) -> void
 
     def serialize: -> [Integer, String, Integer, Integer, Array[Array[String]], String]
 
     def to_h: -> {
-      id: String?|nil,
+      id: String?,
       pubkey: String,
       created_at: Integer,
       kind: Integer,
       tags: Array[Array[String]],
       content: String,
-      sig: String?|nil
+      sig: String?
     }
     def ==: (Event other) -> bool
 
     def sign:(PrivateKey) -> Event
+    def verify_signature: -> bool
 
     def add_event_reference: (String) -> Array[Array[String]]
     def add_pubkey_reference: (PublicKey) -> Array[Array[String]]

data/sig/nostr/key_pair.rbs

@@ -5,6 +5,7 @@ module Nostr
     attr_reader public_key: PublicKey
 
     def initialize: (private_key: PrivateKey, public_key: PublicKey) -> void
+    def to_ary: -> [PrivateKey, PublicKey]
 
     private
 

data/sig/nostr/signature.rbs

@@ -0,0 +1,14 @@
+module Nostr
+  class Signature < String
+    FORMAT: Regexp
+    LENGTH: int
+
+    def initialize: (String) -> void
+
+    private
+
+    attr_reader hex_value: String
+
+    def validate: (String) -> nil
+  end
+end

data/sig/vendor/schnorr/signature.rbs

@@ -0,0 +1,16 @@
+# Added only to satisfy the Steep requirements. Not 100% reliable.
+module Schnorr
+  class InvalidSignatureError < StandardError
+  end
+
+  class Signature
+    attr_reader r: Integer
+    attr_reader s: Integer
+
+    def self.decode: (String string) -> Signature
+
+    def initialize: (Integer r, Integer s) -> void
+    def encode: -> String
+    def ==: (untyped other) -> bool
+  end
+end

data/sig/vendor/schnorr.rbs

@@ -1,4 +1,6 @@
 # Added only to satisfy the Steep requirements. Not 100% reliable.
 module Schnorr
-  def self.sign: (String message, String private_key, ?String aux_rand) -> untyped
+  def self.sign: (String message, String private_key, ?String aux_rand) -> Signature
+  def self.valid_sig?: (String message, String public_key, String signature) -> bool
+  def self.check_sig!: (String message, String public_key, String signature) -> bool
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nostr
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-20 00:00:00.000000000 Z
+date: 2024-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bech32
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: ecdsa
   requirement: !ruby/object:Gem::Requirement
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '3.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -198,14 +198,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.59'
+        version: '0.63'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.59'
+        version: '0.63'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -268,42 +268,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '3.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.57'
+        version: '1.62'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.57'
+        version: '1.62'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
@@ -324,14 +324,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '2.27'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '2.27'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -437,6 +437,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".adr-dir"
 - ".editorconfig"
 - ".overcommit.yml"
 - ".rspec"
@@ -452,12 +453,16 @@ files:
 - README.md
 - Rakefile
 - Steepfile
+- adr/0001-record-architecture-decisions.md
+- adr/0002-introduction-of-signature-class.md
 - docs/.gitignore
 - docs/.vitepress/config.mjs
 - docs/README.md
 - docs/api-examples.md
 - docs/bun.lockb
 - docs/common-use-cases/bech32-encoding-and-decoding-(NIP-19).md
+- docs/common-use-cases/signing-and-verifying-events.md
+- docs/common-use-cases/signing-and-verifying-messages.md
 - docs/core/client.md
 - docs/core/keys.md
 - docs/core/user.md
@@ -491,7 +496,11 @@ files:
 - lib/nostr/errors/invalid_key_format_error.rb
 - lib/nostr/errors/invalid_key_length_error.rb
 - lib/nostr/errors/invalid_key_type_error.rb
+- lib/nostr/errors/invalid_signature_format_error.rb
+- lib/nostr/errors/invalid_signature_length_error.rb
+- lib/nostr/errors/invalid_signature_type_error.rb
 - lib/nostr/errors/key_validation_error.rb
+- lib/nostr/errors/signature_validation_error.rb
 - lib/nostr/event.rb
 - lib/nostr/event_kind.rb
 - lib/nostr/events/encrypted_direct_message.rb
@@ -503,6 +512,7 @@ files:
 - lib/nostr/public_key.rb
 - lib/nostr/relay.rb
 - lib/nostr/relay_message_type.rb
+- lib/nostr/signature.rb
 - lib/nostr/subscription.rb
 - lib/nostr/user.rb
 - lib/nostr/version.rb
@@ -517,7 +527,11 @@ files:
 - sig/nostr/errors/invalid_key_format_error.rbs
 - sig/nostr/errors/invalid_key_length_error.rbs
 - sig/nostr/errors/invalid_key_type_error.rbs
+- sig/nostr/errors/invalid_signature_format_error.rbs
+- sig/nostr/errors/invalid_signature_length_error.rbs
+- sig/nostr/errors/invalid_signature_type_error.rbs
 - sig/nostr/errors/key_validation_error.rbs
+- sig/nostr/errors/signature_validation_error.rbs
 - sig/nostr/event.rbs
 - sig/nostr/event_kind.rbs
 - sig/nostr/events/encrypted_direct_message.rbs
@@ -529,6 +543,7 @@ files:
 - sig/nostr/public_key.rbs
 - sig/nostr/relay.rbs
 - sig/nostr/relay_message_type.rbs
+- sig/nostr/signature.rbs
 - sig/nostr/subscription.rbs
 - sig/nostr/user.rbs
 - sig/vendor/bech32.rbs
@@ -543,6 +558,7 @@ files:
 - sig/vendor/faye/websocket/api.rbs
 - sig/vendor/faye/websocket/client.rbs
 - sig/vendor/schnorr.rbs
+- sig/vendor/schnorr/signature.rbs
 homepage: https://nostr-ruby.com/
 licenses:
 - MIT
@@ -559,14 +575,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Client and relay implementation of the Nostr protocol.