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
data/SECURITY.md ADDED
@@ -0,0 +1,25 @@
1
+ # Security
2
+
3
+ `sattleme-checkout` makes and checks Lightning invoices and on-chain payments for a sattle.me
4
+ merchant on an online shop's server. A flaw here could let an attacker be paid instead of the
5
+ merchant, mark an order paid that is not, or learn an integration's key: please report it
6
+ **privately**, never in a public issue, pull request or discussion.
7
+
8
+ ## How to report
9
+
10
+ - On GitHub: **Security** tab of this repository → **Report a vulnerability** (private
11
+ vulnerability reporting).
12
+ - Or by email: security@sattle.me, subject starting with `[security] checkout-ruby`.
13
+
14
+ Please include what you found, the version of the gem, and, when you can, the steps or the input
15
+ that show it. Do not test against real merchants' funds or keys.
16
+
17
+ ## What is in scope
18
+
19
+ - This gem: anything that, used as its README says, accepts a wrong invoice or payment, publishes
20
+ a record others could alter, or leaks a key.
21
+ - A rule of the specification itself goes to
22
+ [sattleme/checkout-spec](https://github.com/sattleme/checkout-spec/blob/main/SECURITY.md).
23
+
24
+ We will acknowledge your report, keep you informed, and credit you when the fix is published,
25
+ unless you prefer otherwise.
@@ -0,0 +1,195 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sattleme
4
+ module Checkout
5
+ # A call cancelled by its Cancellation: it stopped its requests (SPEC.md §4). Never an Error of
6
+ # SPEC.md §5: a program tells a cancellation from a failure.
7
+ class Cancelled < StandardError
8
+ # What the cancellation was given (`Cancellation#cancel(reason)`), nil when nothing.
9
+ attr_reader :reason
10
+
11
+ def initialize(reason = nil)
12
+ @reason = reason
13
+ super(reason.is_a?(String) ? reason : "The call was cancelled")
14
+ end
15
+ end
16
+
17
+ # The cancellation of one or more calls: every method takes one (`cancellation:`), and stops
18
+ # once it is cancelled, raising Cancelled. Thread-safe: cancel it from any thread.
19
+ #
20
+ # cancellation = Sattleme::Checkout::Cancellation.new
21
+ # Thread.new { sleep 5; cancellation.cancel("the customer left") }
22
+ # client.wait_for_payment(invoice, cancellation: cancellation)
23
+ #
24
+ # # Or bounded in time:
25
+ # client.wait_for_payment(invoice, cancellation: Sattleme::Checkout::Cancellation.after(600))
26
+ class Cancellation
27
+ # A cancellation that cancels itself `seconds` from now (with `reason`), unless it was before.
28
+ # One thread of the gem waits for every such deadline of the process, while one is pending:
29
+ # a cancellation cancelled before its time is forgotten at once.
30
+ def self.after(seconds, reason = "Timed out")
31
+ raise ArgumentError, "seconds: a number of seconds" unless seconds.is_a?(Numeric) && seconds >= 0
32
+
33
+ cancellation = new
34
+ Timer.schedule(cancellation, Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds, reason)
35
+ cancellation
36
+ end
37
+
38
+ # The deadlines of Cancellation.after: one thread cancels each in its time, the earliest first,
39
+ # and ends once none is left (it starts again with the next one).
40
+ module Timer
41
+ @mutex = Mutex.new
42
+ @changed = ConditionVariable.new
43
+ # Each cancellation waiting for its time: [its deadline (the monotonic clock), its reason].
44
+ @pending = {}.compare_by_identity
45
+ @thread = nil
46
+
47
+ class << self
48
+ def schedule(cancellation, deadline, reason)
49
+ @mutex.synchronize do
50
+ @pending[cancellation] = [deadline, reason]
51
+ @thread = start unless @thread&.alive?
52
+ @changed.signal
53
+ end
54
+ # Cancelled otherwise: nothing left to wait for.
55
+ cancellation.on_cancel { forget(cancellation) }
56
+ end
57
+
58
+ private
59
+
60
+ def forget(cancellation)
61
+ @mutex.synchronize do
62
+ @pending.delete(cancellation)
63
+ @changed.signal
64
+ end
65
+ end
66
+
67
+ def start
68
+ thread = Thread.new { run }
69
+ thread.name = "sattleme-checkout timer"
70
+ thread.report_on_exception = false
71
+ thread
72
+ end
73
+
74
+ def run
75
+ while (passed = due)
76
+ passed.each { |cancellation, reason| cancellation.cancel(reason) }
77
+ end
78
+ end
79
+
80
+ # Waits until a deadline passed, then forgets those that passed and gives them with their
81
+ # reasons; nil once none is left, and the thread ends.
82
+ def due
83
+ @mutex.synchronize do
84
+ loop do
85
+ if @pending.empty?
86
+ @thread = nil
87
+ return nil
88
+ end
89
+ now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
90
+ passed = @pending.select { |_, (deadline, _)| deadline <= now }
91
+ unless passed.empty?
92
+ passed.each_key { |cancellation| @pending.delete(cancellation) }
93
+ return passed.map { |cancellation, (_, reason)| [cancellation, reason] }
94
+ end
95
+ @changed.wait(@mutex, @pending.each_value.map(&:first).min - now)
96
+ end
97
+ end
98
+ end
99
+ end
100
+ end
101
+ private_constant :Timer
102
+
103
+ def initialize
104
+ @mutex = Mutex.new
105
+ @condition = ConditionVariable.new
106
+ @cancelled = false
107
+ @reason = nil
108
+ @callbacks = {}
109
+ @next = 0
110
+ end
111
+
112
+ # Cancels the calls that take this cancellation, with `reason` (a String becomes the
113
+ # message of their Cancelled). Idempotent: only the first reason counts.
114
+ def cancel(reason = nil)
115
+ callbacks = @mutex.synchronize do
116
+ return self if @cancelled
117
+
118
+ @cancelled = true
119
+ @reason = reason
120
+ @condition.broadcast
121
+ @callbacks.values.tap { @callbacks.clear }
122
+ end
123
+ callbacks.each do |callback|
124
+ callback.call
125
+ rescue StandardError
126
+ # The gem's own callbacks wake a wait or close a socket: none of them is the caller's
127
+ # concern, nor may it stop the others.
128
+ nil
129
+ end
130
+ self
131
+ end
132
+
133
+ def cancelled?
134
+ @mutex.synchronize { @cancelled }
135
+ end
136
+
137
+ # The reason it was cancelled with; nil before (or when none was given).
138
+ def reason
139
+ @mutex.synchronize { @reason }
140
+ end
141
+
142
+ # Raises Cancelled when it is cancelled.
143
+ def raise_if_cancelled
144
+ raise Cancelled, reason if cancelled?
145
+ end
146
+
147
+ # Waits until it is cancelled, `seconds` at most (nil: for ever): whether it is.
148
+ def wait(seconds = nil)
149
+ deadline = seconds && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds)
150
+ @mutex.synchronize do
151
+ until @cancelled
152
+ left = deadline && (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC))
153
+ break if left && left <= 0
154
+
155
+ @condition.wait(@mutex, left)
156
+ end
157
+ @cancelled
158
+ end
159
+ end
160
+
161
+ # Runs `block` once this is cancelled, in the thread that cancels it (at once, here, when it
162
+ # is already): a handle that #remove forgets. For the gem's own waits.
163
+ def on_cancel(&block)
164
+ handle = @mutex.synchronize do
165
+ next nil if @cancelled
166
+
167
+ @next += 1
168
+ @callbacks[@next] = block
169
+ @next
170
+ end
171
+ block.call if handle.nil?
172
+ handle
173
+ end
174
+
175
+ # Forgets a callback #on_cancel gave the handle of.
176
+ def remove(handle)
177
+ @mutex.synchronize { @callbacks.delete(handle) } if handle
178
+ nil
179
+ end
180
+
181
+ def inspect
182
+ "#<#{self.class.name}#{" cancelled" if cancelled?}>"
183
+ end
184
+ alias to_s inspect
185
+
186
+ # Never cancelled: the cancellation of a call given none.
187
+ NONE = new.tap do |none|
188
+ def none.cancel(_reason = nil) = raise(FrozenError, "Cancellation::NONE is never cancelled")
189
+
190
+ # Nothing to remember: it never runs a callback.
191
+ def none.on_cancel = nil
192
+ end
193
+ end
194
+ end
195
+ end