sattleme-checkout 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +66 -0
  3. data/LICENSE +21 -0
  4. data/README.md +754 -0
  5. data/SECURITY.md +25 -0
  6. data/lib/sattleme/checkout/cancellation.rb +195 -0
  7. data/lib/sattleme/checkout/client.rb +1438 -0
  8. data/lib/sattleme/checkout/errors.rb +165 -0
  9. data/lib/sattleme/checkout/http_client.rb +294 -0
  10. data/lib/sattleme/checkout/internal/bolt11.rb +187 -0
  11. data/lib/sattleme/checkout/internal/channel.rb +147 -0
  12. data/lib/sattleme/checkout/internal/checkout_link.rb +294 -0
  13. data/lib/sattleme/checkout/internal/concurrency.rb +450 -0
  14. data/lib/sattleme/checkout/internal/crypto.rb +63 -0
  15. data/lib/sattleme/checkout/internal/currencies.rb +47 -0
  16. data/lib/sattleme/checkout/internal/declaration.rb +135 -0
  17. data/lib/sattleme/checkout/internal/derive.rb +153 -0
  18. data/lib/sattleme/checkout/internal/event.rb +110 -0
  19. data/lib/sattleme/checkout/internal/http.rb +129 -0
  20. data/lib/sattleme/checkout/internal/json.rb +457 -0
  21. data/lib/sattleme/checkout/internal/key.rb +116 -0
  22. data/lib/sattleme/checkout/internal/lnurl.rb +238 -0
  23. data/lib/sattleme/checkout/internal/nip44.rb +113 -0
  24. data/lib/sattleme/checkout/internal/onchain/address.rb +58 -0
  25. data/lib/sattleme/checkout/internal/onchain/basics.rb +352 -0
  26. data/lib/sattleme/checkout/internal/onchain/lease.rb +326 -0
  27. data/lib/sattleme/checkout/internal/onchain/merchant_acceptance.rb +168 -0
  28. data/lib/sattleme/checkout/internal/onchain/node.rb +285 -0
  29. data/lib/sattleme/checkout/internal/onchain/payment.rb +345 -0
  30. data/lib/sattleme/checkout/internal/onchain/rest.rb +323 -0
  31. data/lib/sattleme/checkout/internal/onchain/watch.rb +119 -0
  32. data/lib/sattleme/checkout/internal/onchain/witness.rb +260 -0
  33. data/lib/sattleme/checkout/internal/order.rb +228 -0
  34. data/lib/sattleme/checkout/internal/protocol.rb +260 -0
  35. data/lib/sattleme/checkout/internal/rates.rb +373 -0
  36. data/lib/sattleme/checkout/internal/record.rb +179 -0
  37. data/lib/sattleme/checkout/internal/relay_pool.rb +823 -0
  38. data/lib/sattleme/checkout/internal/sales.rb +238 -0
  39. data/lib/sattleme/checkout/internal/secp256k1.rb +234 -0
  40. data/lib/sattleme/checkout/internal/text.rb +144 -0
  41. data/lib/sattleme/checkout/internal/urls.rb +172 -0
  42. data/lib/sattleme/checkout/models.rb +247 -0
  43. data/lib/sattleme/checkout/version.rb +9 -0
  44. data/lib/sattleme/checkout/websocket_client.rb +487 -0
  45. data/lib/sattleme/checkout.rb +72 -0
  46. metadata +112 -0
@@ -0,0 +1,153 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sattleme
4
+ module Checkout
5
+ module Internal
6
+ # The merchant's registry, as the integration's channel gives it: the registry key (32 bytes)
7
+ # and the public half of the merchant's reading key (hex).
8
+ Registry = Data.define(:key, :reader) do
9
+ include Redacted
10
+
11
+ def inspect = "#<Registry reader=#{reader}>"
12
+ alias_method :to_s, :inspect
13
+ end
14
+
15
+ # Everything the sale of `ref` needs, derived once: its keys, its taker tag and the
16
+ # conversation key (ECDH) of its declarations' inside with the merchant's reading key.
17
+ # Secrets but `ref`, `author` and `taker`.
18
+ class Sale
19
+ include Redacted
20
+
21
+ attr_reader :ref, :key, :secret_key, :author, :taker, :registry, :inner_key
22
+
23
+ def initialize(ref:, key:, secret_key:, author:, taker:, registry:, inner_key:)
24
+ @ref = ref
25
+ @key = key
26
+ @secret_key = secret_key
27
+ @author = author
28
+ @taker = taker
29
+ @registry = registry
30
+ @inner_key = inner_key
31
+ freeze
32
+ end
33
+
34
+ def inspect = "#<Sale ref=#{ref} author=#{author}>"
35
+ alias to_s inspect
36
+ end
37
+
38
+ # The keys an integration's server derives (SPEC.md §10), HKDF-SHA256, 32 bytes, salt and
39
+ # info in UTF-8. They never change: the integration's channel, its sales and their
40
+ # declarations derive from them, in the merchant's app as here.
41
+ module Derive
42
+ # The keys of an invoice's rest records (SPEC.md §31, "Rest records"): the rest key (its
43
+ # checkout links' records carry it), the rest secret (it signs the records; only the
44
+ # integration key derives it), its public key, the author, and the records' encryption key.
45
+ RestKeys = Data.define(:key, :secret_key, :author, :encryption_key) do
46
+ include Redacted
47
+
48
+ def inspect = "#<RestKeys author=#{author}>"
49
+ alias_method :to_s, :inspect
50
+ end
51
+
52
+ # The integration's witnesses' keys (SPEC.md §31, "Witnesses"): the seen secret (it signs
53
+ # them), its public key (their author), the key of their addresses and order tags, and the
54
+ # channel's encryption key (their conversation key). Secrets but `author`.
55
+ SeenKeys = Data.define(:secret_key, :author, :address_key, :encryption_key) do
56
+ include Redacted
57
+
58
+ def inspect = "#<SeenKeys author=#{author}>"
59
+ alias_method :to_s, :inspect
60
+ end
61
+
62
+ module_function
63
+
64
+ def key(secret, salt, info)
65
+ Crypto.hkdf(secret, salt, info)
66
+ end
67
+
68
+ # The integration's channel: its `d` tag (hex) and its NIP-44 conversation key.
69
+ def channel_keys(integration_key)
70
+ [Text.hex(key(integration_key, Protocol::INTEGRATION_SALT, Protocol::CHANNEL_ADDRESS_INFO)),
71
+ key(integration_key, Protocol::INTEGRATION_SALT, Protocol::CHANNEL_ENCRYPTION_INFO)]
72
+ end
73
+
74
+ # Where the integration's lot of deposit addresses is: its `d` tag (hex).
75
+ def lot_address(integration_key)
76
+ Text.hex(key(integration_key, Protocol::INTEGRATION_SALT, Protocol::LOT_ADDRESS_INFO))
77
+ end
78
+
79
+ def seen_keys(integration_key)
80
+ secret = key(integration_key, Protocol::INTEGRATION_SALT, Protocol::SEEN_SECRET_INFO)
81
+ SeenKeys.new(secret_key: secret, author: Events.public_key(secret),
82
+ address_key: key(integration_key, Protocol::INTEGRATION_SALT, Protocol::SEEN_ADDRESS_KEY_INFO),
83
+ encryption_key: channel_keys(integration_key)[1])
84
+ end
85
+
86
+ # The key that marks the integration's declarations ("By" in the app).
87
+ def taker_key(integration_key)
88
+ key(integration_key, Protocol::INTEGRATION_SALT, Protocol::TAKER_INFO)
89
+ end
90
+
91
+ # The sale of an order: its own key, its Nostr secret and public key (its records' author).
92
+ def sale_keys(integration_key, ref)
93
+ sale_key = key(integration_key, Protocol::INTEGRATION_SALT, Protocol.sale_info(ref))
94
+ secret = key(sale_key, Protocol::SALE_SALT, Protocol::SALE_NOSTR_SECRET_INFO)
95
+ [sale_key, secret, Events.public_key(secret)]
96
+ end
97
+
98
+ def rest_keys(integration_key, ref, address, expires_at)
99
+ rest_key = key(integration_key, Protocol::INTEGRATION_SALT, Protocol.rest_key_info(ref, address, expires_at))
100
+ secret = key(integration_key, Protocol::INTEGRATION_SALT,
101
+ Protocol.rest_secret_info(ref, address, expires_at))
102
+ RestKeys.new(key: rest_key, secret_key: secret, author: Events.public_key(secret),
103
+ encryption_key: key(rest_key, Protocol::CHECKOUT_SALT, Protocol::REST_ENCRYPTION_INFO))
104
+ end
105
+
106
+ # The `d` tag (hex) of the rest record of the invoice whose payment hash is `hash`.
107
+ def rest_record_address(rest_key, hash)
108
+ Text.hex(key(rest_key, Protocol::CHECKOUT_SALT, Protocol.rest_address_info(hash)))
109
+ end
110
+
111
+ # The `d` tag (hex) of the acceptance record of the invoice whose rest key is `rest_key`.
112
+ def acceptance_record_address(rest_key)
113
+ Text.hex(key(rest_key, Protocol::CHECKOUT_SALT, Protocol::ACCEPTANCE_ADDRESS_INFO))
114
+ end
115
+
116
+ # The `d` tag (hex) of the merchant's acceptance of the invoice of the sale `sale_author`
117
+ # with the deposit address `address` and the end `expires_at` (SPEC.md §31, "The merchant's
118
+ # acceptance"): one per invoice.
119
+ def merchant_acceptance_address(integration_key, sale_author, address, expires_at)
120
+ Text.hex(key(integration_key, Protocol::INTEGRATION_SALT,
121
+ Protocol.merchant_acceptance_info(sale_author, address, expires_at)))
122
+ end
123
+
124
+ # d(H): where the declarations of the payment hash `hash` (hex) are.
125
+ def registry_address(registry_key, hash)
126
+ Text.hex(Crypto.hmac(registry_key, Text.hex_bytes(hash)))
127
+ end
128
+
129
+ # The outer key of a record at `address` by `author` (hex).
130
+ def outer_key(registry_key, address, author)
131
+ key(registry_key, Protocol::DECLARATION_SALT, Protocol.outer_info(address, author))
132
+ end
133
+
134
+ # Who took a sale: the first 16 bytes of HMAC-SHA256(taker key, author), hex.
135
+ def taker_tag(taker_key, sale_author)
136
+ Text.hex(Crypto.hmac(taker_key, Text.hex_bytes(sale_author)).byteslice(0, Protocol::TAKER_TAG_BYTES))
137
+ end
138
+
139
+ # The registry of a channel's hex fields.
140
+ def registry(registry_key, registry_reader)
141
+ Registry.new(key: Text.hex_bytes(registry_key), reader: registry_reader)
142
+ end
143
+
144
+ def sale(integration_key, registry, ref)
145
+ sale_key, secret, author = sale_keys(integration_key, ref)
146
+ Sale.new(ref: ref, key: sale_key, secret_key: secret, author: author,
147
+ taker: taker_tag(taker_key(integration_key), author), registry: registry,
148
+ inner_key: Nip44.conversation_key(secret, registry.reader))
149
+ end
150
+ end
151
+ end
152
+ end
153
+ end
@@ -0,0 +1,110 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sattleme
4
+ module Checkout
5
+ module Internal
6
+ # A signed Nostr event (NIP-01): what the gem makes, and what a relay sent once its id checked
7
+ # out (its numbers then integers).
8
+ Event = Data.define(:id, :pubkey, :created_at, :kind, :tags, :content, :sig) do
9
+ # The event as JSON holds it.
10
+ def to_h
11
+ { "id" => id, "pubkey" => pubkey, "created_at" => created_at, "kind" => kind, "tags" => tags,
12
+ "content" => content, "sig" => sig }
13
+ end
14
+
15
+ # The value of its first `d` tag, nil without one.
16
+ def d_tag
17
+ tags.find { |tag| tag[0] == "d" }&.[](1)
18
+ end
19
+ end
20
+
21
+ # Nostr events (SPEC.md §11): their id, their BIP-340 signature with fresh auxiliary random
22
+ # data, and the checks of an event a relay sent, which is never trusted.
23
+ module Events
24
+ module_function
25
+
26
+ # The NIP-01 serialization of an event (SPEC.md §11): the JSON array [0, pubkey, created_at,
27
+ # kind, tags, content] without whitespace, its numbers written as integers whatever their
28
+ # spelling, its strings as JSON.stringify writes them.
29
+ def serialization(pubkey, created_at, kind, tags, content)
30
+ Json.generate([0, pubkey, created_at, kind, tags, content])
31
+ end
32
+
33
+ # The event id: SHA-256 of the UTF-8 of its serialization.
34
+ def hash_of(pubkey, created_at, kind, tags, content)
35
+ Crypto.sha256(serialization(pubkey, created_at, kind, tags, content).b)
36
+ end
37
+
38
+ # The x-only public key (hex) of a BIP-340 secret key.
39
+ def public_key(secret)
40
+ Text.hex(Secp256k1.public_key(secret))
41
+ end
42
+
43
+ # Whether `value` is an x-only public key (lowercase hex) of a point of secp256k1 (BIP-340
44
+ # `lift_x`).
45
+ def public_key?(value)
46
+ Text.hex32?(value) && Secp256k1.xonly?(Text.hex_bytes(value))
47
+ end
48
+
49
+ # The event of `kind`, `tags`, `content` at `created_at`, signed by `secret` with 32 random
50
+ # bytes of `random` as auxiliary data (BIP-340).
51
+ def sign(secret, random, created_at:, kind:, tags:, content:)
52
+ pubkey = public_key(secret)
53
+ hash = hash_of(pubkey, created_at, kind, tags, content)
54
+ Event.new(id: Text.hex(hash), pubkey: pubkey, created_at: created_at, kind: kind, tags: tags,
55
+ content: content, sig: Text.hex(Secp256k1.sign(hash, secret, random.call(32))))
56
+ end
57
+
58
+ # `value` as a Hash of an event's fields (a relay's JSON object, or an Event).
59
+ def fields(value)
60
+ value.is_a?(Event) ? value.to_h : value
61
+ end
62
+
63
+ # Whether `value` has the shape of an event and its id is its hash: what is checked of a
64
+ # record before anything else where anybody may write (SPEC.md §31, "Opening a lease"),
65
+ # its signature only where it decides. A string of its content or tags holding a lone
66
+ # surrogate has no UTF-8, which its hash needs: such an event does not check out.
67
+ def valid_id?(value)
68
+ event = fields(value)
69
+ return false unless event.is_a?(Hash)
70
+ return false unless Text.hex32?(event["id"]) && Text.hex32?(event["pubkey"]) && Text.hex64?(event["sig"])
71
+ return false unless Json.safe_integer?(event["created_at"]) && Json.integer?(event["kind"])
72
+ return false unless Text.well_formed?(event["content"]) && tags?(event["tags"])
73
+
74
+ Text.hex(hash_of(event["pubkey"], event["created_at"], event["kind"], event["tags"], event["content"])) ==
75
+ event["id"]
76
+ end
77
+
78
+ def tags?(tags)
79
+ tags.is_a?(Array) && tags.all? { |tag| tag.is_a?(Array) && tag.all? { |item| Text.well_formed?(item) } }
80
+ end
81
+
82
+ # The NIP-01 members of `value`, a relay's event that checked out, and nothing else: what a
83
+ # relay adds to an event (its id and its signature cover none of it) is never kept (SPEC.md
84
+ # §13, Limits).
85
+ def nip01_members(value)
86
+ value.slice("id", "pubkey", "created_at", "kind", "tags", "content", "sig")
87
+ end
88
+
89
+ # Whether the signature of `value`, whose id was checked, verifies (BIP-340).
90
+ def signature_checks?(value)
91
+ event = fields(value)
92
+ Secp256k1.verify(Text.hex_bytes(event["sig"]), Text.hex_bytes(event["id"]), Text.hex_bytes(event["pubkey"]))
93
+ end
94
+
95
+ # Whether `value` is an event whose id and signature check out. Relays are never trusted.
96
+ def valid?(value)
97
+ valid_id?(value) && signature_checks?(value)
98
+ end
99
+
100
+ # The Event of a value whose id checked out (valid_id?).
101
+ def from(value)
102
+ return value if value.is_a?(Event)
103
+
104
+ Event.new(id: value["id"], pubkey: value["pubkey"], created_at: value["created_at"].to_i,
105
+ kind: value["kind"].to_i, tags: value["tags"], content: value["content"], sig: value["sig"])
106
+ end
107
+ end
108
+ end
109
+ end
110
+ end
@@ -0,0 +1,129 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sattleme
4
+ module Checkout
5
+ module Internal
6
+ # HTTP as every implementation asks it (SPEC.md §15): a GET asking for JSON, with the
7
+ # User-Agent of every implementation, through the client given (the platform's by default,
8
+ # HttpClient). An https URL only, but for the merchant's Bitcoin node (a context whose `node`
9
+ # is true: the explorer reading a URL of a node URL, CallExplorer), whose URL follows a rule of
10
+ # its own (NodeUrl: `http` for a local host): every other rule holds for it too. No redirect is
11
+ # followed: each URL is checked before it is asked, a redirect
12
+ # would skip the check, so a redirect is no answer. The body is read up to 1 MiB, one leading
13
+ # byte order mark ignored. The whole request is bounded by its timeout, and stopped with its
14
+ # call: each runs in a thread of its own, given up when its time runs out or its call stops
15
+ # (the client is told: its cancellation), then waited for until it ended, STOP_GRACE_SECONDS
16
+ # at most: a client that does not stop when it is told is left behind, never the call.
17
+ module Http
18
+ # The way to the network: the client, each request's timeout (milliseconds), the call's stop,
19
+ # and whether it asks the merchant's Bitcoin node (`http` allowed to a local one).
20
+ Context = Data.define(:client, :timeout_ms, :stop, :node) do
21
+ def initialize(client:, timeout_ms:, stop:, node: false)
22
+ super
23
+ end
24
+
25
+ def with_stop(stop) = with(stop: stop)
26
+ end
27
+
28
+ # An answer: its HTTP status, and its body read as JSON (nil when it is not JSON in UTF-8).
29
+ Answer = Data.define(:status, :body) do
30
+ def ok? = status.between?(200, 299)
31
+ end
32
+
33
+ # An answer whose body is text (an explorer's height): nil when it is not UTF-8.
34
+ TextAnswer = Data.define(:status, :text) do
35
+ def ok? = status.between?(200, 299)
36
+ end
37
+
38
+ # The body was larger than MAX_HTTP_BODY_BYTES.
39
+ class TooLarge < StandardError; end
40
+
41
+ BOM = "\xEF\xBB\xBF".b
42
+
43
+ module_function
44
+
45
+ # GET `url` asking for JSON: its status and its body as JSON (nil when it is not JSON in
46
+ # UTF-8). NetworkError when there is no answer in time, a redirect or a body too large.
47
+ def get_json(url, context, headers = {})
48
+ status, bytes = get_bytes(url, context, headers)
49
+ text = Text.decode_utf8(bytes)
50
+ Answer.new(status: status, body: text && Json.parse_or(text))
51
+ end
52
+
53
+ # GET `url` as get_json does, for the one plain-text answer (an explorer's height).
54
+ def get_text(url, context, headers = {})
55
+ status, bytes = get_bytes(url, context, headers)
56
+ TextAnswer.new(status: status, text: Text.decode_utf8(bytes))
57
+ end
58
+
59
+ def get_bytes(url, context, headers)
60
+ stop = context.stop
61
+ stop.check!
62
+ # Checked before (an https URL, SPEC.md §15; the node's own rule, SPEC.md §31), and again
63
+ # here whatever the client: an https URL, or, read by the explorer, a URL under a node URL
64
+ # (in clear HTTP to a local node alone).
65
+ unless askable?(url, context.node)
66
+ raise NetworkError, "No answer from #{Urls.host_of(url)}: it cannot be asked"
67
+ end
68
+
69
+ timeout = context.timeout_ms / 1000.0
70
+ deadline = Clock.now + timeout
71
+ request = Cancellation.new
72
+ all_headers = headers.merge("Accept" => "application/json", "User-Agent" => Protocol::USER_AGENT)
73
+ future = Future.spawn("sattleme-checkout http", call: false) do
74
+ ask(context.client, url, all_headers, timeout, request)
75
+ end
76
+ answered = begin
77
+ future.wait(stop, deadline)
78
+ ensure
79
+ # Stopped, out of time or cancelled: the client's request with it. Either way, its thread
80
+ # has ended when the call goes on.
81
+ request.cancel unless future.settled?
82
+ Internal.join(future.thread, STOP_GRACE_SECONDS)
83
+ end
84
+ raise NetworkError, "No answer from #{Urls.host_of(url)} in time" unless answered
85
+
86
+ state, result = future.outcome
87
+ if state == :error
88
+ stop.check!
89
+ raise NetworkError.new("No answer from #{Urls.host_of(url)}"), cause: result
90
+ end
91
+ if result == :too_large
92
+ raise NetworkError, "#{Urls.host_of(url)} answered more than #{Protocol::MAX_HTTP_BODY_BYTES} bytes"
93
+ end
94
+
95
+ status, bytes = result
96
+ raise NetworkError, "#{Urls.host_of(url)} answered a redirect (HTTP #{status})" if status.between?(300, 399)
97
+
98
+ # One byte order mark is ignored, as WHATWG's UTF-8 decode (and so fetch) ignores it.
99
+ [status, bytes.start_with?(BOM) ? bytes.byteslice(3..) : bytes]
100
+ end
101
+
102
+ # Whether `url` may be asked: an https URL (Urls.https_url), or, of the merchant's Bitcoin node
103
+ # (`node`), a URL whose scheme and authority are a node URL's (NodeUrl.origin_of).
104
+ def askable?(url, node)
105
+ return true if Urls.https_url(url)
106
+
107
+ node && url.match?(%r{\Ahttps?://}) && !NodeUrl.origin_of(url).nil?
108
+ end
109
+
110
+ # The client's answer: [status, body], or :too_large.
111
+ def ask(client, url, headers, timeout, cancellation)
112
+ chunks = []
113
+ size = 0
114
+ status = client.get(url, headers: headers, timeout: timeout, cancellation: cancellation) do |chunk|
115
+ size += chunk.bytesize
116
+ raise TooLarge if size > Protocol::MAX_HTTP_BODY_BYTES
117
+
118
+ chunks << chunk.b
119
+ end
120
+ raise TypeError, "An HTTP client's get gives the status, an Integer" unless status.is_a?(Integer)
121
+
122
+ [status, chunks.join]
123
+ rescue TooLarge
124
+ :too_large
125
+ end
126
+ end
127
+ end
128
+ end
129
+ end