nwc-ruby 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d541ad9af31629ad26492d8da61d56b0a63980cc8597a460cca9949df56f382d
-  data.tar.gz: 8d48fbbe532bdcf56d889f68f9d7878fa2958381c1ea285fb572aebb70d17d7e
+  metadata.gz: 33006d633764a07adc713f4e5e6fe49a5108927286258abf0d976076a3f125d1
+  data.tar.gz: 4727a1b8968c741a2ec2feb2c4f576b4afe8d4df2066f09ddf26f6eb53ed42a1
 SHA512:
-  metadata.gz: bbc5e4a3efdac9b24a4a2c5fc183f3945ba9987fd5312c78a7e8c4ba8cff625af5c08521094cc10101fd24a0bef5f35261eb29720d533d7e0167a236ee59d106
-  data.tar.gz: fb2c7a1ed8d7785a886b38e250432466354b257cef1e4c8552ef24c493c304dbd446bf4c17e57debcce8bc6875666686c16f901d29474ef08541194e6e2a97f3
+  metadata.gz: 6fc9796e80a92b9e1d255ee2fdafb85d5171c7a74a6d25b522ddebf2114620081775a7a21d409ff6209a2d522e02451d6f3057627dd07e2f7091bbba779639a4
+  data.tar.gz: '087888d35e9b84ad81a8ab1f97ee1914a75b2d32a3632c62972bda323225d83eb082fb3e02df469138a980795e3e62692ba9877a0bb398ed228d6a9337f622bd'

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] — 2026-07-17
+
+### Security
+
+- **Event ids are now recomputed before the signature is trusted.**
+  `Event#valid_signature?` verified the signature against the `id` supplied by
+  the relay without checking that the `id` actually described the event body.
+  Because a Nostr signature only ever commits to the `id`, nothing bound that
+  `id` to the event it arrived with: a relay could lift a genuine
+  `(id, sig, pubkey)` triple from any real wallet event and re-attach it to
+  arbitrary `content`, `tags`, `kind` or `created_at`, and the result verified.
+  The id is now recomputed from the canonical serialization first, via the new
+  `Event#valid_id?`. Reported by @riccardobl in
+  [#1](https://github.com/MegalithicBTC/nwc-ruby/issues/1).
+
+  The sharpest edge was the kind 13194 info event, whose content and tags are
+  plaintext: stripping its `encryption` tag silently downgraded every
+  subsequent request from NIP-44 v2 to NIP-04, since the spec reads an absent
+  tag as "nip04 only".
+
+- **Responses are now bound to the request that asked for them.** `call` trusted
+  the relay to honour the `#e` REQ filter and never checked the response's `e`
+  tag itself, so a relay could replay an older but genuine response — a past
+  "payment succeeded" answering a fresh `pay_invoice`, for instance.
+
+- **`fetch_info` now verifies the event author.** It previously checked only
+  `valid_signature?` and never compared the pubkey to the wallet's, so a relay
+  could sign an info event with its own key and have it accepted — forcing the
+  encryption downgrade above without needing to tamper with anything.
+
+### Fixed
+
+- The notification listener no longer tears down when a relay delivers an event
+  of an unexpected kind. `Notification.parse` raises `ArgumentError` on a
+  non-notification kind, but only `EncryptionError` was rescued, so a relay
+  echoing a kind 23195 response onto the subscription killed the listener.
+- A rejected info event no longer ends the `fetch_info` read loop, so one junk
+  event cannot deny service while a genuine info event is still inbound.
+- Corrected `source_code_uri` and `changelog_uri` in the gemspec, which pointed
+  at a `main` branch that does not exist — both links 404'd from the RubyGems
+  page. This repo uses `master`; `PUBLISHING.md` has been corrected to match.
+- `PUBLISHING.md` no longer claims releases publish automatically on tag. There
+  is no `release.yml` in this repo — only `ci.yml`, which tests but never
+  publishes — so releases are manual.
+
+### Added
+
+- Documented a gentle `lookup_invoice` backup polling cadence for invoices so
+  apps can recover from missed notifications without getting rate limited by the
+  backing NWC service.
+
+## [0.2.3] — 2026-04-23
+
 ### Fixed
 
 - Silenced the noisy `Async::Task` warn log ("Task may have ended with

data/README.md

@@ -224,6 +224,67 @@ to keep middleboxes from idle-closing the socket, reconnects with capped
 exponential backoff on failure, and force-recycles the connection every 5 minutes
 as a belt-and-suspenders check against silently dead TCP streams.
 
+#### Polling as a backup
+
+Notifications should be your primary settlement path, but production checkout
+flows should also run a small `lookup_invoice` poller after creating an invoice.
+Treat it as a backup for missed notifications, relay interruptions, app restarts,
+or wallet services that deliver notifications slowly.
+
+Do not poll every second until the invoice expires. Backing NWC services often
+enforce rate limits, and aggressive polling can get your app throttled right
+when a customer is trying to pay. Start soon after invoice creation, then poll
+less often as the invoice gets older, and stop when it is paid or expired.
+
+One reasonable cadence:
+
+```ruby
+def next_lookup_delay(elapsed)
+  return 3.seconds  if elapsed < 2.minutes
+  return 6.seconds  if elapsed < 5.minutes
+  12.seconds
+end
+
+invoice = client.make_invoice(amount: 10_000, description: "coffee")
+record = Invoice.create!(
+  payment_hash: invoice["payment_hash"],
+  bolt11: invoice["invoice"],
+  state: "pending",
+  expires_at: Time.current + 10.minutes,
+  next_lookup_at: Time.current + 3.seconds
+)
+
+# In a continuously running rake task / worker:
+loop do
+  Invoice.where(state: "pending")
+         .where("next_lookup_at <= ?", Time.current)
+         .find_each do |inv|
+    if inv.expires_at <= Time.current
+      inv.update!(state: "expired", next_lookup_at: nil)
+      next
+    end
+
+    response = client.lookup_invoice(payment_hash: inv.payment_hash)
+    settled = response["settled"] || response["paid"] ||
+              response["state"] == "settled" || response["state"] == "SETTLED" ||
+              response["settled_at"]
+
+    if settled
+      inv.update!(state: "paid", paid_at: Time.current, next_lookup_at: nil)
+    else
+      elapsed = Time.current - inv.created_at
+      inv.update!(next_lookup_at: Time.current + next_lookup_delay(elapsed))
+    end
+  end
+
+  sleep 2
+end
+```
+
+Keep the notification handler and the poller idempotent. Either one might mark
+the invoice paid first, and the other should see an already-paid row and do
+nothing.
+
 #### Resuming after a restart
 
 Persist the `created_at` of the last notification you processed and pass it as

data/lib/nwc_ruby/client.rb

@@ -187,8 +187,10 @@ module NwcRuby
 
       conn.on_event do |_sub, event_hash|
         event = Event.from_hash(event_hash)
-        next unless event.valid_signature?
-        next unless event.pubkey == @connection_string.wallet_pubkey
+        next unless authentic?(event)
+        # Notification.parse raises on any other kind, which would tear down
+        # the listener; the relay chooses what it sends us, not the filter.
+        next unless kinds.include?(event.kind)
 
         # Advance the poll watermark so we don't re-fetch old events.
         last_seen_at = event.created_at if event.created_at && event.created_at > last_seen_at
@@ -219,6 +221,33 @@ module NwcRuby
 
     private
 
+    # Every event arriving from a relay must clear this before it is parsed.
+    # `valid_signature?` recomputes the id, so a passing event is byte-for-byte
+    # what the wallet signed — which is what makes the kind and tag checks
+    # below meaningful.
+    def authentic?(event)
+      event.valid_signature? && event.pubkey == @connection_string.wallet_pubkey
+    end
+
+    # A relay is not trusted to honour the REQ filter it was sent, so the
+    # response is bound to the request here. Without this an older but genuine
+    # response (say, a past "payment succeeded") can be replayed against a new
+    # request.
+    def response_to?(event, request_id)
+      e_tag = event.tags.find { |t| t[0] == 'e' }
+      !e_tag.nil? && e_tag[1] == request_id
+    end
+
+    # Advisory only — the relay decides what it actually sends, so `fetch_info`
+    # re-checks the author and kind on whatever comes back.
+    def info_filter
+      {
+        'authors' => [@connection_string.wallet_pubkey],
+        'kinds' => [NIP47::Methods::KIND_INFO],
+        'limit' => 1
+      }
+    end
+
     # rubocop:disable Metrics/MethodLength
     def call(method, params)
       ensure_supports!(method)
@@ -260,8 +289,9 @@ module NwcRuby
             next unless parsed[0] == 'EVENT' && parsed[1] == sub_id
 
             event = Event.from_hash(parsed[2])
-            next unless event.valid_signature?
-            next unless event.pubkey == @connection_string.wallet_pubkey
+            next unless authentic?(event)
+            next unless event.kind == NIP47::Methods::KIND_RESPONSE
+            next unless response_to?(event, request_event.id)
 
             result = NIP47::Response.parse(event, @connection_string.secret, @connection_string.wallet_pubkey)
             break
@@ -290,11 +320,7 @@ module NwcRuby
       Async do
         Async::WebSocket::Client.connect(endpoint) do |conn|
           sub_id = "info-#{SecureRandom.hex(4)}"
-          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, {
-                                                                 'authors' => [@connection_string.wallet_pubkey],
-                                                                 'kinds' => [NIP47::Methods::KIND_INFO],
-                                                                 'limit' => 1
-                                                               }]))
+          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, info_filter]))
           conn.flush
 
           while (msg = conn.read)
@@ -307,8 +333,12 @@ module NwcRuby
             end
 
             if parsed[0] == 'EVENT' && parsed[1] == sub_id
-              event  = Event.from_hash(parsed[2])
-              result = NIP47::Info.parse(event) if event.valid_signature?
+              event = Event.from_hash(parsed[2])
+              # A rejected event must not end the read: a genuine info event
+              # may still follow, and the deadline above bounds the wait.
+              next unless authentic?(event) && event.kind == NIP47::Methods::KIND_INFO
+
+              result = NIP47::Info.parse(event)
               break
             elsif parsed[0] == 'EOSE' && parsed[1] == sub_id
               break

data/lib/nwc_ruby/event.rb

@@ -50,8 +50,20 @@ module NwcRuby
       self
     end
 
+    # True when the id is the SHA-256 of this event's canonical serialization.
+    def valid_id?
+      return false unless @id.is_a?(String)
+
+      @id == OpenSSL::Digest::SHA256.hexdigest(serialize_for_id)
+    end
+
+    # The signature only commits to the id, so the id must be recomputed from
+    # the event body before the signature means anything. Without that check a
+    # relay can graft a genuine (id, sig) pair from one event onto arbitrary
+    # pubkey/created_at/kind/tags/content and still verify.
     def valid_signature?
       return false unless @id && @sig && @pubkey
+      return false unless valid_id?
 
       digest_bytes = Crypto::Keys.hex_to_bytes(@id)
       Crypto::Schnorr.verify(digest_bytes, @sig, @pubkey)

data/lib/nwc_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NwcRuby
-  VERSION = '0.2.3'
+  VERSION = '0.2.4'
 end

data/nwc-ruby.gemspec

@@ -23,9 +23,9 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['homepage_uri']          = spec.homepage
-  spec.metadata['source_code_uri']       = "#{spec.homepage}/tree/main"
+  spec.metadata['source_code_uri']       = "#{spec.homepage}/tree/master"
   spec.metadata['bug_tracker_uri']       = "#{spec.homepage}/issues"
-  spec.metadata['changelog_uri']         = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['changelog_uri']         = "#{spec.homepage}/blob/master/CHANGELOG.md"
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir[

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nwc-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - MegalithicBTC
@@ -204,9 +204,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/MegalithicBTC/nwc-ruby
-  source_code_uri: https://github.com/MegalithicBTC/nwc-ruby/tree/main
+  source_code_uri: https://github.com/MegalithicBTC/nwc-ruby/tree/master
   bug_tracker_uri: https://github.com/MegalithicBTC/nwc-ruby/issues
-  changelog_uri: https://github.com/MegalithicBTC/nwc-ruby/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/MegalithicBTC/nwc-ruby/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for Nostr Wallet Connect (NIP-47) with safe long-running relay
   connections.