nwc-ruby 0.2.0

data/lib/nwc_ruby/nip04/cipher.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP04
+    # NIP-04: legacy DM encryption. AES-256-CBC, PKCS7 padding, random 16-byte IV.
+    # Key is the raw ECDH X coordinate (no hashing).
+    # Payload format: "<base64_ciphertext>?iv=<base64_iv>"
+    #
+    # Deprecated in general, but still required for NWC because many wallet
+    # services have not migrated: they emit NIP-04 requests/responses (kind
+    # 23194/23195) and NIP-04 notifications (kind 23196) alongside or instead
+    # of NIP-44 v2.
+    module Cipher
+      module_function
+
+      def encrypt(plaintext, privkey_hex, pubkey_hex)
+        key = Crypto::ECDH.shared_x(privkey_hex, pubkey_hex)
+        iv  = SecureRandom.bytes(16)
+
+        cipher = OpenSSL::Cipher.new('aes-256-cbc').encrypt
+        cipher.key = key
+        cipher.iv  = iv
+        ct = cipher.update(plaintext.encode('UTF-8')) + cipher.final
+
+        "#{Base64.strict_encode64(ct)}?iv=#{Base64.strict_encode64(iv)}"
+      end
+
+      def decrypt(payload, privkey_hex, pubkey_hex)
+        raise EncryptionError, 'malformed NIP-04 payload' unless payload.include?('?iv=')
+
+        ct_b64, iv_b64 = payload.split('?iv=', 2)
+        ct = Base64.strict_decode64(ct_b64)
+        iv = Base64.strict_decode64(iv_b64)
+        raise EncryptionError, 'invalid IV length' unless iv.bytesize == 16
+
+        key = Crypto::ECDH.shared_x(privkey_hex, pubkey_hex)
+
+        cipher = OpenSSL::Cipher.new('aes-256-cbc').decrypt
+        cipher.key = key
+        cipher.iv  = iv
+        (cipher.update(ct) + cipher.final).force_encoding('UTF-8')
+      rescue OpenSSL::Cipher::CipherError, ArgumentError => e
+        raise EncryptionError, "NIP-04 decryption failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/nwc_ruby/nip44/cipher.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP44
+    # NIP-44 v2 encryption. The current Nostr DM encryption, and the one NWC
+    # wallet services advertise via `["encryption", "nip44_v2"]` on kind 13194.
+    #
+    # Algorithm (verbatim from the spec):
+    #   1. shared_x = X coordinate of ECDH(priv, pub)  -- 32 bytes, no hashing
+    #   2. conversation_key = HKDF-extract(IKM=shared_x, salt="nip44-v2")
+    #   3. keys = HKDF-expand(PRK=conversation_key, info=nonce32, L=76)
+    #      split into chacha_key[0..32] || chacha_nonce[32..44] || hmac_key[44..76]
+    #   4. Plaintext is prefixed with u16-BE length, then zero-padded to a
+    #      power-of-two chosen by a specific ladder (min 32 bytes, max 65536).
+    #   5. Encrypt with plain ChaCha20 (NOT ChaCha20-Poly1305).
+    #   6. mac = HMAC-SHA256(hmac_key, ciphertext, aad=nonce)
+    #   7. payload = base64( 0x02 || nonce32 || ciphertext || mac32 )
+    #
+    # Security-critical invariants:
+    #   - MAC is verified in constant time BEFORE decryption returns plaintext.
+    #   - Unknown version bytes are rejected.
+    #   - Padding is validated on decrypt (length prefix sanity + trailing zeros).
+    #
+    # Reference vectors: https://github.com/paulmillr/nip44/blob/main/nip44.vectors.json
+    module Cipher
+      module_function
+
+      VERSION          = 2
+      MIN_PLAINTEXT    = 1
+      MAX_PLAINTEXT    = 65_535
+      MIN_PADDED_LEN   = 32
+      SALT             = 'nip44-v2'
+
+      # @param plaintext [String] UTF-8 plaintext (1..65535 bytes)
+      # @param privkey_hex [String] our private key, 32-byte hex
+      # @param pubkey_hex [String] their x-only pubkey, 32-byte hex
+      # @param nonce [String, nil] optional 32-byte nonce (for tests); random if nil
+      # @return [String] base64 payload
+      def encrypt(plaintext, privkey_hex, pubkey_hex, nonce: nil)
+        pt_bytes = plaintext.to_s.dup.force_encoding('UTF-8').b
+        if pt_bytes.bytesize < MIN_PLAINTEXT || pt_bytes.bytesize > MAX_PLAINTEXT
+          raise EncryptionError, 'plaintext length must be 1..65535 bytes'
+        end
+
+        conversation_key = derive_conversation_key(privkey_hex, pubkey_hex)
+        nonce ||= SecureRandom.bytes(32)
+        raise EncryptionError, 'nonce must be 32 bytes' unless nonce.bytesize == 32
+
+        chacha_key, chacha_nonce, hmac_key = derive_message_keys(conversation_key, nonce)
+        padded     = pad(pt_bytes)
+        ciphertext = chacha20(chacha_key, chacha_nonce, padded)
+        mac        = OpenSSL::HMAC.digest('SHA256', hmac_key, nonce + ciphertext)
+
+        Base64.strict_encode64([VERSION].pack('C') + nonce + ciphertext + mac)
+      end
+
+      # @param payload [String] base64 NIP-44 payload
+      # @return [String] UTF-8 plaintext
+      # rubocop:disable Metrics/AbcSize
+      def decrypt(payload, privkey_hex, pubkey_hex)
+        raise EncryptionError, 'payload is nil or empty' if payload.nil? || payload.empty?
+        raise EncryptionError, "payload starts with '#' (not encrypted)" if payload.start_with?('#')
+
+        raw = begin
+          Base64.strict_decode64(payload)
+        rescue ArgumentError
+          raise EncryptionError, 'payload is not valid base64'
+        end
+
+        if raw.bytesize < 1 + 32 + MIN_PADDED_LEN + 32 || raw.bytesize > 1 + 32 + 65_536 + 32
+          raise EncryptionError, 'payload length out of range'
+        end
+
+        version = raw.byteslice(0, 1).unpack1('C')
+        raise EncryptionError, "unsupported NIP-44 version: #{version}" unless version == VERSION
+
+        nonce      = raw.byteslice(1, 32)
+        mac        = raw.byteslice(raw.bytesize - 32, 32)
+        ciphertext = raw.byteslice(33, raw.bytesize - 33 - 32)
+
+        conversation_key = derive_conversation_key(privkey_hex, pubkey_hex)
+        chacha_key, chacha_nonce, hmac_key = derive_message_keys(conversation_key, nonce)
+
+        expected_mac = OpenSSL::HMAC.digest('SHA256', hmac_key, nonce + ciphertext)
+        raise EncryptionError, 'NIP-44 MAC verification failed' unless secure_compare(mac, expected_mac)
+
+        padded = chacha20(chacha_key, chacha_nonce, ciphertext)
+        unpad(padded).force_encoding('UTF-8')
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # --- Internals ------------------------------------------------------
+
+      def derive_conversation_key(privkey_hex, pubkey_hex)
+        shared = Crypto::ECDH.shared_x(privkey_hex, pubkey_hex)
+        hkdf_extract(SALT.b, shared)
+      end
+
+      def derive_message_keys(conversation_key, nonce)
+        keys = hkdf_expand(conversation_key, nonce, 76)
+        [keys.byteslice(0, 32), keys.byteslice(32, 12), keys.byteslice(44, 32)]
+      end
+
+      # HKDF-extract(salt, IKM) = HMAC-SHA256(salt, IKM). Returns 32 bytes.
+      def hkdf_extract(salt, ikm)
+        OpenSSL::HMAC.digest('SHA256', salt, ikm)
+      end
+
+      # HKDF-expand(PRK, info, L). RFC 5869.
+      def hkdf_expand(prk, info, length)
+        out = String.new(encoding: Encoding::BINARY)
+        t   = String.new(encoding: Encoding::BINARY)
+        counter = 1
+        while out.bytesize < length
+          t = OpenSSL::HMAC.digest('SHA256', prk, t + info + [counter].pack('C'))
+          out << t
+          counter += 1
+        end
+        out.byteslice(0, length)
+      end
+
+      # Plain ChaCha20, 20 rounds, 96-bit nonce, 256-bit key.
+      def chacha20(key, nonce, data)
+        cipher = OpenSSL::Cipher.new('chacha20')
+        cipher.encrypt
+        # OpenSSL's "chacha20" wants a 16-byte IV: 4-byte counter (little-endian, 0) + 12-byte nonce.
+        cipher.key = key
+        cipher.iv  = [0].pack('V') + nonce
+        cipher.update(data) + cipher.final
+      end
+
+      # Pad plaintext: prepend u16-BE length, then zero-pad to `calc_padded_len(n)`.
+      def pad(pt_bytes)
+        n = pt_bytes.bytesize
+        padded_len = calc_padded_len(n)
+        prefix     = [n].pack('n') # u16 big-endian
+        zeros      = "\x00".b * (padded_len - n)
+        prefix + pt_bytes + zeros
+      end
+
+      # Spec's ladder: minimum 32, then power-of-two chunks.
+      def calc_padded_len(unpadded_len)
+        return MIN_PADDED_LEN if unpadded_len <= MIN_PADDED_LEN
+
+        # next_power = 1 << (ceil(log2(unpadded_len - 1)))
+        next_power = 1 << (unpadded_len - 1).bit_length
+        chunk = next_power <= 256 ? 32 : next_power / 8
+        (((unpadded_len - 1) / chunk) + 1) * chunk
+      end
+
+      def unpad(padded)
+        raise EncryptionError, 'padded data too short' if padded.bytesize < 2 + MIN_PADDED_LEN - 2
+
+        n = padded.byteslice(0, 2).unpack1('n')
+        raise EncryptionError, 'invalid padding length' if n < MIN_PLAINTEXT || n > MAX_PLAINTEXT
+
+        pt = padded.byteslice(2, n)
+        raise EncryptionError, 'truncated padded plaintext' if pt.nil? || pt.bytesize != n
+
+        expected_total = 2 + calc_padded_len(n)
+        raise EncryptionError, 'padded length mismatch' unless padded.bytesize == expected_total
+
+        pt
+      end
+
+      # Constant-time byte comparison.
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        acc = 0
+        a.bytes.zip(b.bytes) { |x, y| acc |= x ^ y }
+        acc.zero?
+      end
+    end
+  end
+end

data/lib/nwc_ruby/nip47/info.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP47
+    # Parses the kind 13194 "info" event — the wallet service's capability
+    # advertisement. The `content` is a plaintext space-separated list of
+    # supported methods. Tags optionally include:
+    #   ["encryption",    "nip44_v2 nip04"]   -- supported encryption schemes
+    #   ["notifications", "payment_received payment_sent"]
+    class Info
+      attr_reader :methods, :encryption_schemes, :notification_types, :event
+
+      def initialize(methods:, encryption_schemes:, notification_types:, event:)
+        @methods            = methods
+        @encryption_schemes = encryption_schemes
+        @notification_types = notification_types
+        @event              = event
+      end
+
+      def self.parse(event)
+        methods = event.content.to_s.strip.split(/\s+/).reject(&:empty?)
+
+        enc_tag = event.tags.find { |t| t[0] == 'encryption' }
+        schemes = if enc_tag
+                    enc_tag[1].to_s.strip.split(/\s+/)
+                  else
+                    # Spec: absence means nip04 only.
+                    ['nip04']
+                  end
+
+        notif_tag = event.tags.find { |t| t[0] == 'notifications' }
+        notif_types = notif_tag ? notif_tag[1].to_s.strip.split(/\s+/) : []
+
+        new(methods: methods, encryption_schemes: schemes, notification_types: notif_types, event: event)
+      end
+
+      def supports?(method)
+        @methods.include?(method)
+      end
+
+      def supports_nip44?
+        @encryption_schemes.include?('nip44_v2')
+      end
+
+      def supports_nip04?
+        @encryption_schemes.include?('nip04')
+      end
+
+      def preferred_encryption
+        supports_nip44? ? :nip44_v2 : :nip04
+      end
+
+      # True when the connection exposes no fund-moving methods.
+      def read_only?
+        !@methods.intersect?(Methods::MUTATING)
+      end
+
+      def read_write?
+        !read_only?
+      end
+
+      def supports_notifications?
+        !@notification_types.empty?
+      end
+    end
+  end
+end

data/lib/nwc_ruby/nip47/methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP47
+    # NIP-47 kinds and methods.
+    module Methods
+      # Event kinds.
+      KIND_INFO                 = 13_194 # replaceable, plaintext capability list
+      KIND_REQUEST              = 23_194 # client -> wallet, encrypted
+      KIND_RESPONSE             = 23_195 # wallet -> client, encrypted
+      KIND_NOTIFICATION_NIP04   = 23_196 # wallet -> client, NIP-04 encrypted
+      KIND_NOTIFICATION_NIP44   = 23_197 # wallet -> client, NIP-44 v2 encrypted
+
+      # Methods (the payload `method` field). The info event advertises a
+      # space-separated subset of these.
+      PAY_INVOICE         = 'pay_invoice'
+      MULTI_PAY_INVOICE   = 'multi_pay_invoice'
+      PAY_KEYSEND         = 'pay_keysend'
+      MULTI_PAY_KEYSEND   = 'multi_pay_keysend'
+      MAKE_INVOICE        = 'make_invoice'
+      LOOKUP_INVOICE      = 'lookup_invoice'
+      LIST_TRANSACTIONS   = 'list_transactions'
+      GET_BALANCE         = 'get_balance'
+      GET_INFO            = 'get_info'
+      SIGN_MESSAGE        = 'sign_message'
+      NOTIFICATIONS       = 'notifications' # capability marker, not a method
+
+      ALL = [
+        PAY_INVOICE, MULTI_PAY_INVOICE, PAY_KEYSEND, MULTI_PAY_KEYSEND,
+        MAKE_INVOICE, LOOKUP_INVOICE, LIST_TRANSACTIONS,
+        GET_BALANCE, GET_INFO, SIGN_MESSAGE
+      ].freeze
+
+      # The set of methods that can move funds. A connection without any of
+      # these is "read-only".
+      MUTATING = [
+        PAY_INVOICE, MULTI_PAY_INVOICE, PAY_KEYSEND, MULTI_PAY_KEYSEND
+      ].freeze
+
+      NOTIFICATION_TYPES = %w[payment_received payment_sent].freeze
+    end
+  end
+end

data/lib/nwc_ruby/nip47/notification.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP47
+    # Parses kind 23196 (NIP-04) or 23197 (NIP-44 v2) notification events.
+    #
+    # Inner payload shape:
+    #   { "notification_type": "payment_received"|"payment_sent",
+    #     "notification":      { ...transaction fields... } }
+    class Notification
+      attr_reader :type, :data, :event
+
+      def initialize(type:, data:, event:)
+        @type  = type
+        @data  = data
+        @event = event
+      end
+
+      def payment_hash
+        @data['payment_hash']
+      end
+
+      def amount_msats
+        @data['amount']
+      end
+
+      def payment_received?
+        @type == 'payment_received'
+      end
+
+      def payment_sent?
+        @type == 'payment_sent'
+      end
+
+      def self.parse(event, client_privkey, wallet_pubkey)
+        plaintext = case event.kind
+                    when Methods::KIND_NOTIFICATION_NIP44
+                      NIP44::Cipher.decrypt(event.content, client_privkey, wallet_pubkey)
+                    when Methods::KIND_NOTIFICATION_NIP04
+                      NIP04::Cipher.decrypt(event.content, client_privkey, wallet_pubkey)
+                    else
+                      raise ArgumentError, "not a notification kind: #{event.kind}"
+                    end
+
+        data = JSON.parse(plaintext)
+        new(type: data['notification_type'], data: data['notification'] || {}, event: event)
+      end
+    end
+  end
+end

data/lib/nwc_ruby/nip47/request.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP47
+    # Builds a signed kind 23194 request event with the JSON-RPC payload
+    # encrypted using either NIP-44 v2 or NIP-04.
+    module Request
+      module_function
+
+      # @param method [String] NIP-47 method name
+      # @param params [Hash] method-specific params
+      # @param client_privkey [String] hex
+      # @param wallet_pubkey [String] hex
+      # @param encryption [Symbol] :nip44_v2 or :nip04
+      # @param expiration [Integer, nil] optional unix timestamp
+      # @return [Event]
+      def build(method:, params:, client_privkey:, wallet_pubkey:, encryption: :nip44_v2, expiration: nil)
+        payload = JSON.generate({ 'method' => method, 'params' => params })
+        ciphertext = case encryption
+                     when :nip44_v2 then NIP44::Cipher.encrypt(payload, client_privkey, wallet_pubkey)
+                     when :nip04    then NIP04::Cipher.encrypt(payload, client_privkey, wallet_pubkey)
+                     else raise ArgumentError, "unknown encryption: #{encryption}"
+                     end
+
+        tags = [['p', wallet_pubkey]]
+        tags << %w[encryption nip44_v2] if encryption == :nip44_v2
+        tags << ['expiration', expiration.to_s] if expiration
+
+        client_pubkey = Crypto::Keys.public_key_from_private(client_privkey)
+        event = Event.new(pubkey: client_pubkey, kind: Methods::KIND_REQUEST, content: ciphertext, tags: tags)
+        event.sign!(client_privkey)
+      end
+    end
+  end
+end

data/lib/nwc_ruby/nip47/response.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module NwcRuby
+  module NIP47
+    # Parses an incoming kind 23195 response event.
+    class Response
+      attr_reader :result_type, :result, :error, :request_id, :event
+
+      def initialize(result_type:, result:, error:, request_id:, event:)
+        @result_type = result_type
+        @result      = result
+        @error       = error
+        @request_id  = request_id
+        @event       = event
+      end
+
+      def success?
+        @error.nil? && !@result.nil?
+      end
+
+      def error_code
+        @error && @error['code']
+      end
+
+      def error_message
+        @error && @error['message']
+      end
+
+      # @param event [Event] the kind 23195 event (already signature-verified)
+      # @param client_privkey [String] hex
+      # @param wallet_pubkey [String] hex
+      # @return [Response]
+      def self.parse(event, client_privkey, wallet_pubkey)
+        # Tags: ["p", client_pubkey], ["e", request_event_id]
+        e_tag = event.tags.find { |t| t[0] == 'e' }
+        request_id = e_tag && e_tag[1]
+
+        plaintext = decrypt(event.content, client_privkey, wallet_pubkey)
+        data = JSON.parse(plaintext)
+
+        new(
+          result_type: data['result_type'],
+          result: data['result'],
+          error: data['error'],
+          request_id: request_id,
+          event: event
+        )
+      end
+
+      # Try NIP-44 v2 first; fall back to NIP-04 if the version byte is wrong.
+      def self.decrypt(content, client_privkey, wallet_pubkey)
+        NIP44::Cipher.decrypt(content, client_privkey, wallet_pubkey)
+      rescue EncryptionError
+        NIP04::Cipher.decrypt(content, client_privkey, wallet_pubkey)
+      end
+    end
+  end
+end