nwc-ruby 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b847b05f148d03753548528e0f4483129cf59887e40329f28e7bbe31f0eda1cd
-  data.tar.gz: 9c99704df81a6e7cfa9c1bfede014b49270b15bf11a3bba8663b5d6f1f3500fa
+  metadata.gz: 33006d633764a07adc713f4e5e6fe49a5108927286258abf0d976076a3f125d1
+  data.tar.gz: 4727a1b8968c741a2ec2feb2c4f576b4afe8d4df2066f09ddf26f6eb53ed42a1
 SHA512:
-  metadata.gz: 11e62747c2dfa88459d900a2e1f89e7a42df5420b88221508bf62df39b65ebe7f9937db357557b2ab3ee8b95be0b50b5062fa3667cf21002dbf607366f49675d
-  data.tar.gz: c0ff4c40f5d8fa68d3b12e6b7c745ff1ff5b19da5719c0998c8cc5db6098ee77917c2c914b0ca96dc9e9301ac4240595f7e472019e6001394c996e75ffdcff6a
+  metadata.gz: 6fc9796e80a92b9e1d255ee2fdafb85d5171c7a74a6d25b522ddebf2114620081775a7a21d409ff6209a2d522e02451d6f3057627dd07e2f7091bbba779639a4
+  data.tar.gz: '087888d35e9b84ad81a8ab1f97ee1914a75b2d32a3632c62972bda323225d83eb082fb3e02df469138a980795e3e62692ba9877a0bb398ed228d6a9337f622bd'

data/CHANGELOG.md

@@ -7,6 +7,72 @@ 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
+  unhandled exception") that was emitted every `recycle_interval` (default
+  5 min) by the heartbeat task. The forced recycle used to be signaled by
+  raising `TransportError` from inside the heartbeat's child Async task; the
+  parent's reconnect loop caught it correctly, but Async's console logger
+  logged the unhandled-in-child exception with a full backtrace first.
+  The recycle is now signaled by setting an `@recycle_requested` flag and
+  closing the websocket, which unblocks the read loop and lets
+  `run_one_connection` return normally without any exception crossing a task
+  boundary.
+
 ## [0.2.2] — 2026-04-21
 
 ### Fixed

data/README.md

@@ -2,6 +2,14 @@
 
 A production-grade Ruby client for [Nostr Wallet Connect (NIP-47)][nip47].
 
+Accept and track Bitcoin Lightning payments in your Rails app without running
+any Lightning infrastructure yourself. Generate Lightning invoices for your
+users to pay, then get notified the instant each one settles — all by talking
+to a Nostr Wallet Connect (NWC) service that someone else operates. The gem
+works with any NWC-compatible backend (Rizful, Alby Hub, Alby Cloud, CoinOs,
+any NIP-47 wallet service), so you're not locked into a single provider and
+can swap vendors by changing one environment variable.
+
 ```ruby
 require "nwc_ruby"
 
@@ -216,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/transport/relay_connection.rb

@@ -146,6 +146,7 @@ module NwcRuby
       def run_one_connection(top)
         endpoint  = Async::HTTP::Endpoint.parse(@url, alpn_protocols: ['http/1.1'])
         opened_at = Async::Clock.now
+        @recycle_requested = false
         @logger.info("[nwc] connecting to #{@url}")
 
         Async::WebSocket::Client.connect(endpoint) do |conn|
@@ -155,6 +156,7 @@ module NwcRuby
 
           @open_cb&.call(self)
           read_loop(conn)
+          @logger.info("[nwc] recycling connection (#{@recycle_interval}s)") if @recycle_requested
         ensure
           heartbeat&.stop
           poll&.stop
@@ -167,6 +169,13 @@ module NwcRuby
         end
       end
 
+      # Heartbeat task: sends RFC 6455 ping every @ping_interval seconds and
+      # requests a recycle once the connection has been open longer than
+      # @recycle_interval. The recycle is signaled via a flag + close rather
+      # than by raising across task boundaries, because an exception raised
+      # inside a child Async task is logged at warn level by Async's console
+      # logger ("Task may have ended with unhandled exception") before the
+      # parent's rescue runs — producing a noisy backtrace on every recycle.
       def start_heartbeat(top, conn, opened_at)
         top.async do
           loop do
@@ -176,12 +185,25 @@ module NwcRuby
 
             sleep @ping_interval
             break if @stop
-
-            raise TransportError, "recycle (#{@recycle_interval}s)" if Async::Clock.now - opened_at > @recycle_interval
+            break if recycle_due?(opened_at) && request_recycle(conn)
           end
         end
       end
 
+      def recycle_due?(opened_at)
+        Async::Clock.now - opened_at > @recycle_interval
+      end
+
+      def request_recycle(conn)
+        @recycle_requested = true
+        begin
+          conn.close
+        rescue StandardError
+          nil
+        end
+        true
+      end
+
       def start_poll(top)
         return unless @poll_interval && @poll_cb
 
@@ -200,7 +222,21 @@ module NwcRuby
       end
 
       def read_loop(conn)
-        while (message = conn.read)
+        loop do
+          message =
+            begin
+              conn.read
+            rescue StandardError => e
+              # If we asked for the recycle/close ourselves, treat the
+              # resulting read error as a clean EOF rather than propagating
+              # it up into the reconnect-on-error path (which would log a
+              # spurious warning).
+              raise unless @recycle_requested || @stop
+
+              @logger.debug("[nwc] read interrupted by close: #{e.class}")
+              nil
+            end
+          break if message.nil?
           break if @stop
 
           begin

data/lib/nwc_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NwcRuby
-  VERSION = '0.2.2'
+  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.2
+  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.