nostr 0.4.0 → 0.6.0

data/docs/relays/publishing-events.md

@@ -0,0 +1,29 @@
+# Publishing events
+
+Create a [signed event](../core/keys) and call the method
+[`Nostr::Client#publish`](https://www.rubydoc.info/gems/nostr/Nostr/Client#publish-instance_method) to send the
+event to the relay.
+
+```ruby{4-8,17}
+# Create a user with the keypair
+user = Nostr::User.new(keypair: keypair)
+
+# Create a signed event
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+# Connect asynchronously to a relay
+relay = Nostr::Relay.new(url: 'wss://nostr.wine', name: 'Wine')
+client.connect(relay)
+
+# Listen asynchronously for the connect event
+client.on :connect do
+  # Send the event to the relay
+  client.publish(text_note_event)
+end
+```
+
+The relay will verify the signature of the event with the public key. If the signature is valid, the relay should
+broadcast the event to all subscribers.

data/docs/relays/receiving-events.md

@@ -0,0 +1,6 @@
+# Receiving events
+
+To receive events from Relays, you must create a subscription on the relay. A subscription is a filter that defines the
+events you want to receive.
+
+For more information, read the [Subscription](../subscriptions/creating-a-subscription.md) section.

data/docs/subscriptions/creating-a-subscription.md

@@ -0,0 +1,49 @@
+# Creating a subscription
+
+A client can request events and subscribe to new updates __after__ it has established a connection with the Relay.
+
+You may use a [`Nostr::Filter`](https://www.rubydoc.info/gems/nostr/Nostr/Filter) instance with as many attributes as
+you wish:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(
+    ids: ['8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8'],
+    authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
+    kinds: [Nostr::EventKind::TEXT_NOTE],
+    e: ["f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52"],
+    p: ["f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8"],
+    since: 1230981305,
+    until: 1292190341,
+    limit: 420,
+  )
+
+  subscription = client.subscribe(subscription_id: 'an-id', filter: filter)
+end
+```
+
+With just a few:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(kinds: [Nostr::EventKind::TEXT_NOTE])
+  subscription = client.subscribe(subscription_id: 'an-id', filter: filter)
+end
+```
+
+Or omit the filter:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe(subscription_id: 'an-id')
+end
+```
+
+Or even omit the subscription id:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe(filter: filter)
+  subscription.id # => "13736f08dee8d7b697222ba605c6fab2" (randomly generated)
+end
+```

data/docs/subscriptions/deleting-a-subscription.md

@@ -0,0 +1,10 @@
+# Stop previous subscriptions
+
+You can stop receiving messages from a subscription by calling
+[`Nostr::Client#unsubscribe`](https://www.rubydoc.info/gems/nostr/Nostr/Client#unsubscribe-instance_method) with the
+ID of the subscription you want to stop receiving messages from:
+
+```ruby
+client.unsubscribe('your-subscription-id')
+client.unsubscribe(subscription.id)
+```

data/docs/subscriptions/filtering-subscription-events.md

@@ -0,0 +1,115 @@
+# Filtering events
+
+## Filtering by id
+
+You can filter events by their ids:
+
+```ruby
+filter = Nostr::Filter.new(
+  ids: [
+    # matches events with these exact IDs
+    '8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8',
+    '461544014d87c9eaf3e76e021240007dff2c7afb356319f99c741b45749bf82f',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by author
+
+You can filter events by their author's pubkey:
+
+```ruby
+filter = Nostr::Filter.new(
+  authors: [
+    # matches events whose (authors) pubkey match these exact IDs
+    'b698043170d580f8ae5bad4ac80b1fdb508e957f0bbffe97f2a8915fa8b34070',
+    '51f853ff4894b062950e46ebed8c1c7015160f8173994414a96dd286f65f0f49',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by kind
+
+You can filter events by their kind:
+
+```ruby
+filter = Nostr::Filter.new(
+  kinds: [
+    # matches events whose kind is TEXT_NOTE
+    Nostr::EventKind::TEXT_NOTE,
+    # and matches events whose kind is CONTACT_LIST
+    Nostr::EventKind::CONTACT_LIST,
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by referenced event
+
+You can filter events by the events they reference (in their `e` tag):
+
+```ruby
+filter = Nostr::Filter.new(
+  e: [
+    # matches events that reference other events whose ids match these exact IDs
+    'f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52',
+    'f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by referenced pubkey
+
+You can filter events by the pubkeys they reference (in their `p` tag):
+
+```ruby
+filter = Nostr::Filter.new(
+  p: [
+    # matches events that reference other pubkeys that match these exact IDs
+    'b698043170d580f8ae5bad4ac80b1fdb508e957f0bbffe97f2a8915fa8b34070',
+    '51f853ff4894b062950e46ebed8c1c7015160f8173994414a96dd286f65f0f49',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by timestamp
+
+You can filter events by their timestamp:
+
+```ruby
+filter = Nostr::Filter.new(
+  since: 1230981305, # matches events that are newer than this timestamp
+  until: 1292190341, # matches events that are older than this timestamp
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Limiting the number of events
+
+You can limit the number of events received:
+
+```ruby
+filter = Nostr::Filter.new(
+  limit: 420, # matches at most 420 events
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Combining filters
+
+You can combine filters. For example, to match `5` text note events that are newer than `1230981305` from the author
+`ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577`:
+
+```ruby
+filter = Nostr::Filter.new(
+  authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
+  kinds: [Nostr::EventKind::TEXT_NOTE],
+  since: 1230981305,
+  limit: 5,
+)
+subscription = client.subscribe(filter: filter)
+```

data/docs/subscriptions/updating-a-subscription.md

@@ -0,0 +1,4 @@
+# Updating a subscription
+
+Updating a subscription is done by creating a new subscription with the same id as the previous one. See
+[creating a subscription](./creating-a-subscription.md) for more information.

data/lib/nostr/bech32.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'bech32'
+require 'bech32/nostr'
+require 'bech32/nostr/entity'
+
+module Nostr
+  # Bech32 encoding and decoding
+  #
+  # @api public
+  #
+  module Bech32
+    # Decodes a bech32-encoded string
+    #
+    # @api public
+    #
+    # @example
+    #   bech32_value = 'npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'
+    #   Nostr::Bech32.decode(bech32_value) # => ['npub', '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d8...']
+    #
+    # @param [String] bech32_value The bech32-encoded string to decode
+    #
+    # @return [Array<String, String>] The human readable part and the data
+    #
+    def self.decode(bech32_value)
+      entity = ::Bech32::Nostr::NIP19.decode(bech32_value)
+
+      case entity
+      in ::Bech32::Nostr::BareEntity
+        [entity.hrp, entity.data]
+      in ::Bech32::Nostr::TLVEntity
+        [entity.hrp, entity.entries]
+      end
+    end
+
+    # Encodes data into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   Nostr::Bech32.encode(hrp: 'npub', data: '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e')
+    #   # => 'npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'
+    #
+    # @param [String] hrp The human readable part (npub, nsec, nprofile, nrelay, nevent, naddr, etc)
+    # @param [String] data The data to encode
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.encode(hrp:, data:)
+      ::Bech32::Nostr::BareEntity.new(hrp, data).encode
+    end
+
+    # Encodes a hex-encoded public key into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   Nostr::Bech32.npub_encode('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e')
+    #   # => 'npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'
+    #
+    # @param [String] npub The public key to encode
+    #
+    # @see Nostr::Bech32#encode
+    # @see Nostr::PublicKey#to_bech32
+    # @see Nostr::PrivateKey#to_bech32
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.npub_encode(npub)
+      encode(hrp: 'npub', data: npub)
+    end
+
+    # Encodes a hex-encoded private key into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   Nostr::Bech32.nsec_encode('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e')
+    #   # => 'nsec10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'
+    #
+    # @param [String] nsec The private key to encode
+    #
+    # @see Nostr::Bech32#encode
+    # @see Nostr::PrivateKey#to_bech32
+    # @see Nostr::PublicKey#to_bech32
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.nsec_encode(nsec)
+      encode(hrp: 'nsec', data: nsec)
+    end
+
+    # Encodes an address into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   naddr = Nostr::Bech32.naddr_encode(
+    #     pubkey: '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e',
+    #     relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+    #     kind: Nostr::EventKind::TEXT_NOTE,
+    #     identifier: 'damus'
+    #   )
+    #   naddr # => 'naddr1qgs8ul5ug253hlh3n75jne0a5xmjur4urfxpzst88cnegg6ds6ka7ns...'
+    #
+    # @param [PublicKey] pubkey The public key to encode
+    # @param [Array<String>] relays The relays to encode
+    # @param [String] kind The kind of address to encode
+    # @param [String] identifier The identifier of the address to encode
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.naddr_encode(pubkey:, relays: [], kind: nil, identifier: nil)
+      entry_relays = relays.map do |relay_url|
+        ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_RELAY, relay_url)
+      end
+
+      pubkey_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_AUTHOR, pubkey)
+      kind_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_KIND, kind)
+      identifier_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_SPECIAL, identifier)
+
+      entries = [pubkey_entry, *entry_relays, kind_entry, identifier_entry].compact
+      entity = ::Bech32::Nostr::TLVEntity.new(::Bech32::Nostr::NIP19::HRP_EVENT_COORDINATE, entries)
+      entity.encode
+    end
+
+    # Encodes an event into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   nevent = Nostr::Bech32.nevent_encode(
+    #     id: '0fdb90f8e234d3400edafdd26d493f12efc0d7de2c6f9f21f997847d33ad2ea3',
+    #     relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+    #     kind: Nostr::EventKind::TEXT_NOTE,
+    #   )
+    #   nevent # => 'nevent1qgsqlkuslr3rf56qpmd0m5ndfyl39m7q6l0zcmuly8ue0pra...'
+    #
+    # @param [PublicKey] id The id the event to encode
+    # @param [Array<String>] relays The relays to encode
+    # @param [String] kind The kind of event to encode
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.nevent_encode(id:, relays: [], kind: nil)
+      entry_relays = relays.map do |relay_url|
+        ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_RELAY, relay_url)
+      end
+
+      id_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_AUTHOR, id)
+      kind_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_KIND, kind)
+
+      entries = [id_entry, *entry_relays, kind_entry].compact
+      entity = ::Bech32::Nostr::TLVEntity.new(::Bech32::Nostr::NIP19::HRP_EVENT, entries)
+      entity.encode
+    end
+
+    # Encodes a profile into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   nprofile = Nostr::Bech32.nprofile_encode(
+    #     pubkey: '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e',
+    #     relays: ['wss://relay.damus.io', 'wss://nos.lol']
+    #   )
+    #
+    # @param [PublicKey] pubkey The public key to encode
+    # @param [Array<String>] relays The relays to encode
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.nprofile_encode(pubkey:, relays: [])
+      entry_relays = relays.map do |relay_url|
+        ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_RELAY, relay_url)
+      end
+
+      pubkey_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_SPECIAL, pubkey)
+      entries = [pubkey_entry, *entry_relays].compact
+      entity = ::Bech32::Nostr::TLVEntity.new(::Bech32::Nostr::NIP19::HRP_PROFILE, entries)
+      entity.encode
+    end
+
+    # Encodes a relay URL into a bech32 string
+    #
+    # @api public
+    #
+    # @example
+    #   nrelay = Nostr::Bech32.nrelay_encode('wss://relay.damus.io')
+    #   nrelay # => 'nrelay1qq28wumn8ghj7un9d3shjtnyv9kh2uewd9hsc5zt2x'
+    #
+    # @param [String] relay_url The relay url to encode
+    #
+    # @return [String] The bech32-encoded string
+    #
+    def self.nrelay_encode(relay_url)
+      relay_entry = ::Bech32::Nostr::TLVEntry.new(::Bech32::Nostr::TLVEntity::TYPE_SPECIAL, relay_url)
+
+      entity = ::Bech32::Nostr::TLVEntity.new(::Bech32::Nostr::NIP19::HRP_RELAY, [relay_entry])
+      entity.encode
+    end
+  end
+end

data/lib/nostr/client.rb

@@ -74,7 +74,8 @@ module Nostr
     # @example Subscribing to all events created after a certain time
     #   subscription = client.subscribe(filter: Nostr::Filter.new(since: 1230981305))
     #
-    # @param subscription_id [String] The subscription id. A random string.
+    # @param subscription_id [String] The subscription id. An arbitrary, non-empty string of max length 64
+    #   chars used to represent a subscription.
     # @param filter [Filter] A set of attributes that represent the events that the client is interested in.
     #
     # @return [Subscription] The subscription object

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.
     #
@@ -30,8 +30,8 @@ module Nostr
     #   encrypted = crypto.encrypt_text(sender_private_key, recipient_public_key, 'Feedback appreciated. Now pay $8')
     #   encrypted # => "wrYQaHDfpOEvyJELSCg1vzsywmlJTz8NqH03eFW44s8iQs869jtSb26Lr4s23gmY?iv=v38vAJ3LlJAGZxbmWU4qAg=="
     #
-    # @param sender_private_key [String] 32-bytes hex-encoded private key of the creator.
-    # @param recipient_public_key [String] 32-bytes hex-encoded public key of the recipient.
+    # @param sender_private_key [PrivateKey] 32-bytes hex-encoded private key of the creator.
+    # @param recipient_public_key [PublicKey] 32-bytes hex-encoded public key of the recipient.
     # @param plain_text [String] The text to be encrypted
     #
     # @return [String] Encrypted text.
@@ -54,14 +54,18 @@ module Nostr
     #   encrypted # => "wrYQaHDfpOEvyJELSCg1vzsywmlJTz8NqH03eFW44s8iQs869jtSb26Lr4s23gmY?iv=v38vAJ3LlJAGZxbmWU4qAg=="
     #   decrypted = crypto.decrypt_text(recipient_private_key, sender_public_key, encrypted)
     #
-    # @param sender_public_key [String] 32-bytes hex-encoded public key of the message creator.
-    # @param recipient_private_key [String] 32-bytes hex-encoded public key of the recipient.
+    # @param sender_public_key [PublicKey] 32-bytes hex-encoded public key of the message creator.
+    # @param recipient_private_key [PrivateKey] 32-bytes hex-encoded public key of the recipient.
     # @param encrypted_text [String] The text to be decrypted
     #
     # @return [String] Decrypted text.
     #
     def decrypt_text(recipient_private_key, sender_public_key, encrypted_text)
       base64_encoded_text, iv = encrypted_text.split('?iv=')
+
+      # Ensure iv and base64_encoded_text are not nil
+      return '' unless iv && base64_encoded_text
+
       cipher = OpenSSL::Cipher.new(CIPHER_ALGORITHM).decrypt
       cipher.iv = Base64.decode64(iv)
       cipher.key = compute_shared_key(recipient_private_key, sender_public_key)
@@ -80,31 +84,107 @@ module Nostr
     #   event.sig # => a signature
     #
     # @param event [Event] The event to be signed
-    # @param private_key [String] 32-bytes hex-encoded private key.
+    # @param private_key [PrivateKey] 32-bytes hex-encoded private key.
     #
     # @return [Event] An unsigned event.
     #
     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
     #
     # @api private
     #
-    # @param private_key [String] 32-bytes hex-encoded private key.
-    # @param public_key [String] 32-bytes hex-encoded public key.
+    # @param private_key [PrivateKey] 32-bytes hex-encoded private key.
+    # @param public_key [PublicKey] 32-bytes hex-encoded public key.
     #
     # @return [String] A shared key used in the event's content encryption and decryption.
     #

data/lib/nostr/errors/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Base error class
+  class Error < StandardError
+  end
+end

data/lib/nostr/errors/invalid_hrp_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the human readable part of a Bech32 string is invalid
+  #
+  # @api public
+  #
+  class InvalidHRPError < KeyValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidHRPError.new('example wrong hrp', 'nsec')
+    #
+    # @param given_hrp [String] The given human readable part of the Bech32 string
+    # @param allowed_hrp [String] The allowed human readable part of the Bech32 string
+    #
+    def initialize(given_hrp, allowed_hrp)
+      super("Invalid hrp: #{given_hrp}. The allowed hrp value for this kind of entity is '#{allowed_hrp}'.")
+    end
+  end
+end

data/lib/nostr/errors/invalid_key_format_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the private key is in an invalid format
+  #
+  # @api public
+  #
+  class InvalidKeyFormatError < KeyValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidKeyFormatError.new('private')
+    #
+    # @param [String] key_kind The kind of key that is invalid (public or private)
+    #
+    def initialize(key_kind)
+      super("Only lowercase hexadecimal characters are allowed in #{key_kind} keys.")
+    end
+  end
+end

data/lib/nostr/errors/invalid_key_length_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the private key's length is not 64 characters
+  #
+  # @api public
+  #
+  class InvalidKeyLengthError < KeyValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidKeyLengthError.new('private')
+    #
+    # @param [String] key_kind The kind of key that is invalid (public or private)
+    #
+    def initialize(key_kind)
+      super("Invalid #{key_kind} key length. It should have 64 characters.")
+    end
+  end
+end

data/lib/nostr/errors/invalid_key_type_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Raised when the private key is not a string
+  #
+  # @api public
+  #
+  class InvalidKeyTypeError < KeyValidationError
+    # Initializes the error
+    #
+    # @example
+    #   InvalidKeyTypeError.new('private')
+    #
+    # @param [String] key_kind The kind of key that is invalid (public or private)
+    #
+    def initialize(key_kind) = super("Invalid #{key_kind} key type")
+  end
+end