abusezero 0.1.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.
@@ -0,0 +1,313 @@
1
+ require 'json'
2
+ require 'net/http'
3
+ require 'openssl'
4
+ require 'base64'
5
+ require 'uri'
6
+ require 'time'
7
+ require 'timeout'
8
+ require 'thread'
9
+
10
+ module AbuseZero
11
+ class Error < StandardError
12
+ attr_reader :code, :status, :request_id, :retryable, :docs_url
13
+ def initialize(code, message, status: 0, request_id: nil, retryable: false, docs_url: nil)
14
+ super(message)
15
+ @code, @status, @request_id, @retryable, @docs_url = code, status, request_id, retryable, docs_url
16
+ end
17
+ end
18
+ class WebhookVerificationError < StandardError; end
19
+ OPERATIONS = JSON.parse(File.read(File.join(__dir__, 'operations.json'), encoding: 'UTF-8')).freeze
20
+ KEY = /\A(?:sk|rk)_[1-9][0-9]{19}\.[A-Za-z0-9_-]{43}\z/
21
+ OPAQUE = /\A[\x21-\x7e]{1,128}\z/
22
+ CREDENTIAL_HEADER = /\A(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-auth-token|x-csrf-token|x-xsrf-token)\z|(?:\A|-)(?:token|secret|session|password|api-key|apikey)(?:-|\z)/i
23
+
24
+ def self.incoming_request(method:, url:, headers:)
25
+ begin
26
+ uri = URI.parse(url)
27
+ rescue URI::InvalidURIError
28
+ raise ArgumentError, 'Provide the incoming HTTP method and URL without credentials.', cause: nil
29
+ end
30
+ unless method.match?(/\A[A-Za-z]{1,16}\z/) && %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && url.length <= 4096
31
+ raise ArgumentError, 'Provide the incoming HTTP method and URL without credentials.'
32
+ end
33
+ clean, size = {}, 0
34
+ headers.each do |name, value|
35
+ name = name.downcase
36
+ next if CREDENTIAL_HEADER.match?(name) || !name.match?(/\A[!#$%&'*+.^_`|~0-9a-z-]{1,128}\z/) || !value.is_a?(String) || value.match?(/[\r\n]/)
37
+ value = value[0, 8192]
38
+ next if clean.size >= 64 || size + name.bytesize + value.bytesize > 32768
39
+ clean[name] = value
40
+ size += name.bytesize + value.bytesize
41
+ end
42
+ { 'method' => method, 'url' => url, 'headers' => clean }
43
+ end
44
+
45
+ def self.keyed_hash(secret, key_version, value)
46
+ raise ArgumentError, 'Use a printable key version with no spaces.' unless key_version.match?(OPAQUE)
47
+ { 'algorithm' => 'hmac-sha256', 'key_version' => key_version, 'value' => OpenSSL::HMAC.hexdigest('SHA256', secret, value) }
48
+ end
49
+ private_class_method :keyed_hash
50
+ def self.create_phone_hash(secret:, key_version:, e164:)
51
+ raise ArgumentError, 'Normalize the phone number to E.164 before hashing it.' unless e164.match?(/\A\+[1-9][0-9]{7,14}\z/)
52
+ keyed_hash(secret, key_version, "abusezero:phone:e164:v1:#{e164}")
53
+ end
54
+ def self.create_custom_identifier(secret:, key_version:, key:, value:)
55
+ raise ArgumentError, 'Provide a valid identifier key and nonempty value.' unless key.match?(/\A[a-z][a-z0-9_]{0,63}\z/) && !value.empty?
56
+ { 'key' => key, 'value_hash' => keyed_hash(secret, key_version, "abusezero:custom:#{key}:v1:#{value}") }
57
+ end
58
+ def self.verify_webhook(payload:, headers:, secret:, tolerance_seconds: 300, now: Time.now.to_f)
59
+ raise ArgumentError, 'Use a nonnegative timestamp tolerance.' unless tolerance_seconds.is_a?(Numeric) && tolerance_seconds.finite? && tolerance_seconds >= 0
60
+ keys = Array(secret).compact.reject { |s| s.strip.empty? }.map do |s|
61
+ raise ArgumentError, 'Provide the complete webhook signing secret.' unless s.strip.match?(/\Awhsk_[A-Za-z0-9+\/]{43}=\z/)
62
+ Base64.strict_decode64(s.strip[5..])
63
+ end
64
+ raise ArgumentError, 'Provide a webhook signing secret.' if keys.empty?
65
+ h = headers.transform_keys(&:downcase)
66
+ id, timestamp, signatures = %w[id timestamp signature].map { |n| h["abusezero-webhook-#{n}"].to_s }
67
+ unless !id.empty? && timestamp.match?(/\A[0-9]{1,12}\z/) && (now - timestamp.to_i).abs <= tolerance_seconds
68
+ raise WebhookVerificationError, 'The webhook timestamp or headers are invalid.'
69
+ end
70
+ offered = signatures.split.filter_map { |s| Base64.strict_decode64(s[3..]) if s.start_with?('v1,') rescue nil }
71
+ matches = keys.any? do |key|
72
+ expected = OpenSSL::HMAC.digest('SHA256', key, "#{id}.#{timestamp}.".b + payload.b)
73
+ offered.any? { |value| value.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(value, expected) }
74
+ end
75
+ raise WebhookVerificationError, 'The webhook signature does not match.' unless matches
76
+ begin
77
+ event = JSON.parse(payload)
78
+ raise JSON::ParserError unless event.is_a?(Hash) && event['object'] == 'event' && event['id'] == id
79
+ event
80
+ rescue JSON::ParserError
81
+ raise WebhookVerificationError, 'The webhook body is invalid.'
82
+ end
83
+ end
84
+
85
+ def self.defaulted?(schema, root)
86
+ schema = schema['$ref'].sub(%r{\A#/}, '').split('/').reduce(root) { |v, k| v.fetch(k.gsub('~1', '/').gsub('~0', '~')) } while schema.is_a?(Hash) && schema['$ref']
87
+ schema.is_a?(Hash) && schema.key?('default')
88
+ end
89
+ private_class_method :defaulted?
90
+
91
+ # A new kind of object within v1, such as a new lookup match kind: every variant fixes the same discriminator, the
92
+ # value carries one none of them knows, and it keeps the shared object type. It passes through unchanged.
93
+ def self.unknown_variant?(value, variants)
94
+ return false unless value.is_a?(Hash) && variants.all? { |v| v['type'] == 'object' && v['properties'].is_a?(Hash) }
95
+ fixed = ->(v) { v['properties'].select { |k, p| k != 'object' && p.is_a?(Hash) && p.key?('const') }.keys }
96
+ keys = variants.map(&fixed).reduce(:&)
97
+ types = variants.map { |v| v['properties'].dig('object', 'const') }.uniq
98
+ keys.any? { |k| value[k].is_a?(String) && variants.none? { |v| v['properties'][k]['const'] == value[k] } } &&
99
+ (types == [nil] || types.size == 1 && value['object'] == types.first)
100
+ end
101
+ private_class_method :unknown_variant?
102
+
103
+ # Responses can gain new values for codes and enums within v1, so a response accepts an enum or fixed value it
104
+ # doesn't know, except an object's own object type. Requests stay strict.
105
+ def self.validate(value, schema, root = schema, response: false, field: nil)
106
+ if schema['$ref']
107
+ ref = schema['$ref'].sub(%r{\A#/}, '').split('/').reduce(root) { |v, k| v.fetch(k.gsub('~1', '/').gsub('~0', '~')) }
108
+ return validate(value, ref, root, response: response, field: field)
109
+ end
110
+ variants = schema['anyOf'] || schema['oneOf']
111
+ if variants
112
+ count = variants.count { |v| validate(value, v, root, response: response, field: field) rescue false }
113
+ return true if count.zero? && response && unknown_variant?(value, variants)
114
+ raise ArgumentError, 'The value does not match the request schema.' if count.zero? || schema['oneOf'] && !response && count != 1
115
+ end
116
+ types = Array(schema['type'])
117
+ matches = { 'null' => value.nil?, 'string' => value.is_a?(String), 'object' => value.is_a?(Hash), 'array' => value.is_a?(Array), 'integer' => value.is_a?(Integer), 'number' => value.is_a?(Numeric) && value.finite?, 'boolean' => [true, false].include?(value) }
118
+ raise ArgumentError unless types.empty? || types.any? { |t| matches[t] }
119
+ raise ArgumentError if schema.key?('const') && value != schema['const'] && (!response || field == 'object') || !response && schema['enum'] && !schema['enum'].include?(value)
120
+ if value.is_a?(Hash)
121
+ # A request may leave out a field the API fills with its default.
122
+ required = Array(schema['required'])
123
+ required = required.reject { |k| defaulted?(schema.fetch('properties', {})[k], root) } unless response
124
+ raise ArgumentError if required.any? { |k| !value.key?(k) }
125
+ value.each do |k, v|
126
+ validate(k, schema['propertyNames'], root, response: response) if schema['propertyNames']
127
+ child = schema.fetch('properties', {}).fetch(k, schema.fetch('additionalProperties', {}))
128
+ raise ArgumentError if child == false
129
+ validate(v, child, root, response: response, field: k) if child.is_a?(Hash)
130
+ end
131
+ elsif value.is_a?(Array)
132
+ raise ArgumentError if value.size < schema.fetch('minItems', 0) || value.size > schema.fetch('maxItems', Float::INFINITY)
133
+ value.each { |v| validate(v, schema.fetch('items', {}), root, response: response) }
134
+ elsif value.is_a?(String)
135
+ raise ArgumentError if value.length < schema.fetch('minLength', 0) || value.length > schema.fetch('maxLength', Float::INFINITY) || schema['pattern'] && !Regexp.new(schema['pattern']).match?(value)
136
+ elsif value.is_a?(Numeric)
137
+ raise ArgumentError if schema['multipleOf'] && (value.to_f / schema['multipleOf'] - (value.to_f / schema['multipleOf']).round).abs > 1e-9
138
+ raise ArgumentError if value < schema.fetch('minimum', -Float::INFINITY) || value > schema.fetch('maximum', Float::INFINITY) || value <= schema.fetch('exclusiveMinimum', -Float::INFINITY) || value >= schema.fetch('exclusiveMaximum', Float::INFINITY)
139
+ end
140
+ true
141
+ end
142
+
143
+ class Core
144
+ def initialize(key: nil, access_token: nil, workspace: nil, outage: 'throw', agent: nil, base_url: 'https://api.abusezero.com', transport: nil)
145
+ @public = self.class::PUBLIC
146
+ raise Error.new('CREDENTIAL_REQUIRED', 'Provide one server API key or OAuth access token.', status: 401) if !@public && (!!key == !!access_token)
147
+ raise Error.new('INVALID_KEY', 'Provide a server API key.', status: 401) if key && !KEY.match?(key)
148
+ raise Error.new('INVALID_TOKEN', 'Provide a valid OAuth access token.', status: 401) if access_token && !access_token.match?(/\A[\x21-\x7e]{1,8192}\z/)
149
+ raise Error.new('WORKSPACE_REQUIRED', 'Provide the selected workspace.', status: 422) if access_token && !workspace
150
+ raise ArgumentError, 'Provide the workspace ID.' if workspace && !workspace.match?(/\A[1-9][0-9]{19}\z/)
151
+ raise ArgumentError, 'Set outage to throw, allow or deny.' unless %w[throw allow deny].include?(outage)
152
+ begin
153
+ uri = URI.parse(base_url)
154
+ rescue URI::InvalidURIError
155
+ raise ArgumentError, 'Use an HTTPS API origin, or HTTP on loopback for local testing.', cause: nil
156
+ end
157
+ unless uri.host && !uri.userinfo && !uri.query && !uri.fragment && ['', '/'].include?(uri.path) && (uri.scheme == 'https' || uri.scheme == 'http' && %w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host))
158
+ raise ArgumentError, 'Use an HTTPS API origin, or HTTP on loopback for local testing.'
159
+ end
160
+ @credential, @workspace, @outage, @key, @base, @transport = key || access_token, workspace, outage, !!key, base_url.sub(%r{/$}, ''), transport
161
+ @agent = agent.to_s.gsub(/[^\x20-\x7e]/, '')[0, 512]
162
+ @mutex = Mutex.new
163
+ @http = Net::HTTP.new(uri.hostname, uri.port)
164
+ @http.use_ssl = uri.scheme == 'https'
165
+ @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
166
+ @http.max_retries = 0
167
+ @http.keep_alive_timeout = 50
168
+ end
169
+ def inspect
170
+ "#<#{self.class}>"
171
+ end
172
+ def close
173
+ @mutex.synchronize { @http.finish if @http.started? }
174
+ end
175
+ private
176
+ def call_operation(id, input, path, key)
177
+ op = OPERATIONS.fetch(id)
178
+ raise ArgumentError, 'Use the matching API client.' unless op['public'] == @public
179
+ raise Error.new('OAUTH_REQUIRED', "This method needs an OAuth access token. An API key alone can't run it.", status: 403) if @key && op['scope'] == 'operations:management'
180
+ raise Error.new('INVALID_IDEMPOTENCY_KEY', 'Provide an idempotency key of 1–128 printable characters with no spaces.', status: 422) if op['mutation'] && !key || key && !key.match?(OPAQUE)
181
+ data = JSON.parse(JSON.generate(input))
182
+ route = op['path'].dup
183
+ path = path.transform_keys(&:to_s)
184
+ unless path.keys.sort == op['paths'].map { |p| p['name'] }.sort
185
+ raise ArgumentError, "Pass every path field this method needs, such as path: { 'id' => id }."
186
+ end
187
+ op['paths'].each do |p|
188
+ value = path.fetch(p['name'])
189
+ begin
190
+ AbuseZero.validate(value, p['schema'])
191
+ rescue ArgumentError, KeyError
192
+ hint = p['schema']['pattern'] == '^[1-9][0-9]{19}$' ? ' IDs are 20-digit strings.' : ''
193
+ raise ArgumentError, "Check path['#{p['name']}'].#{hint}", cause: nil
194
+ end
195
+ encoded = URI.encode_www_form_component(value.to_s).gsub('+', '%20')
196
+ encoded = encoded.gsub('%2F', '/') if p['name'] == 'path'
197
+ route.sub!("{#{p['name']}}", encoded)
198
+ end
199
+ data['context']['user_agent'] = data['context']['user_agent'][0, 512] if id.start_with?('evaluations.') && data.dig('context', 'user_agent').is_a?(String)
200
+ if data['request'].is_a?(Hash)
201
+ r = data['request']
202
+ data['request'] = AbuseZero.incoming_request(method: r['method'], url: r['url'], headers: r['headers'])
203
+ end
204
+ begin
205
+ AbuseZero.validate(data, op['input'])
206
+ rescue ArgumentError, KeyError
207
+ raise Error.new('INVALID_REQUEST', 'Check the request against the API schema.', status: 422)
208
+ end
209
+ body = nil
210
+ if op['method'] == 'GET'
211
+ query = URI.encode_www_form(data.map { |k, v| [k, v.is_a?(String) ? v : JSON.generate(v)] })
212
+ route += '?' + query unless query.empty?
213
+ else
214
+ body = JSON.generate(data)
215
+ raise Error.new('PAYLOAD_TOO_LARGE', 'The evaluation request is larger than 48 KiB.', status: 413) if id == 'evaluations.create' && body.bytesize > 49152
216
+ end
217
+ headers = { 'Accept' => 'application/json' }
218
+ unless @public
219
+ headers['Authorization'] = 'Bearer ' + @credential
220
+ headers['AbuseZero-Workspace'] = @workspace if @workspace
221
+ headers['AbuseZero-Agent'] = @agent unless @agent.empty?
222
+ end
223
+ headers['Content-Type'] = 'application/json' if body
224
+ headers['Idempotency-Key'] = key if key
225
+ budget = op['timeout_ms'] / 1000.0
226
+ budget = [budget, data.fetch('wait', 0) + 5].max if id == 'events.list'
227
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + budget
228
+ failure = nil
229
+ rate_error = nil
230
+ 3.times do |attempt|
231
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
232
+ response = nil
233
+ begin
234
+ raise Timeout::Error if remaining <= 0
235
+ response = Timeout.timeout(remaining, Timeout::Error) do
236
+ if @transport
237
+ @transport.call(op['method'], @base + route, headers, body, remaining)
238
+ else
239
+ @mutex.synchronize do
240
+ begin
241
+ @http.open_timeout = @http.read_timeout = @http.write_timeout = remaining
242
+ @http.start unless @http.started?
243
+ request = Net::HTTPGenericRequest.new(op['method'], !body.nil?, true, route, headers)
244
+ request.body = body if body
245
+ @http.request(request)
246
+ rescue Timeout::Error, IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse
247
+ @http.finish if @http.started?
248
+ raise
249
+ end
250
+ end
251
+ end
252
+ end
253
+ return read_response(op, response)
254
+ rescue Error => e
255
+ failure = e
256
+ rate_error = e if e.status == 429
257
+ rescue Timeout::Error
258
+ failure = Error.new('DEADLINE_EXCEEDED', 'The request ran out of time.', retryable: true)
259
+ rescue IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse
260
+ failure = Error.new('TRANSPORT_ERROR', "AbuseZero couldn't be reached, or the response didn't arrive complete.", retryable: true)
261
+ end
262
+ break unless failure.retryable && attempt < 2
263
+ delay = [0.1, 0.25][attempt]
264
+ if response && response['Retry-After']
265
+ value = response['Retry-After']
266
+ seconds = Float(value) rescue (Time.httpdate(value).to_f - Time.now.to_f rescue 0)
267
+ delay = [delay, seconds].max
268
+ end
269
+ break if Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay >= deadline
270
+ sleep(delay)
271
+ end
272
+ failure = rate_error || failure
273
+ if id == 'evaluations.create' && @outage != 'throw' && failure.retryable && failure.status != 429
274
+ return { 'source' => 'local_outage', 'claim_id' => data['claim_id'], 'result' => @outage, 'error' => failure }
275
+ end
276
+ raise failure
277
+ end
278
+ def read_response(op, response)
279
+ data = JSON.parse(response.body) rescue nil
280
+ status = response.code.to_i
281
+ if status.between?(200, 299)
282
+ raise Error.new('INVALID_RESPONSE', 'AbuseZero returned an unreadable response.', status: 502, retryable: true) unless data.is_a?(Hash)
283
+ if %w[evaluations.create evaluations.dry_run].include?(op['id'])
284
+ if data['status'] == 'skipped' && data['reason'].is_a?(String) && data['reason'].match?(/\A[a-z][a-z0-9_]{0,63}\z/)
285
+ data['source'] = 'abusezero' if op['id'] == 'evaluations.create'
286
+ return data
287
+ end
288
+ risk = data['risk']
289
+ valid = %w[allow deny].include?(data['result']) && risk.is_a?(Hash) && risk['band'].is_a?(String) && (risk['score'].nil? || risk['score'].is_a?(Numeric) && risk['score'].between?(0, 100))
290
+ if op['id'] == 'evaluations.create'
291
+ valid &&= data['object'] == 'evaluation' && data['id'].is_a?(String) && data['id'].match?(/\A[1-9][0-9]{19}\z/)
292
+ reported = data['outcome']
293
+ raise Error.new('INVALID_RESPONSE', 'AbuseZero returned an unreadable outcome.', status: 502, retryable: true) unless reported.nil? || reported.is_a?(Hash)
294
+ state = reported&.fetch('state', nil) || response['AbuseZero-Outcome-State']
295
+ raise Error.new('INVALID_RESPONSE', 'AbuseZero returned an unreadable outcome state.', status: 502, retryable: true) if state && !(state.is_a?(String) && state.match?(/\A[a-z][a-z0-9_]{0,63}\z/))
296
+ data['outcome'] = state ? { 'state' => state, 'due_at' => reported&.fetch('due_at', nil) || response['AbuseZero-Outcome-Due-At'] } : nil
297
+ data['source'] = 'abusezero'
298
+ end
299
+ valid &&= data['object'] == 'evaluation_dry_run' && data['dry_run'] == true if op['id'] == 'evaluations.dry_run'
300
+ raise Error.new('INVALID_RESPONSE', 'AbuseZero returned an unreadable evaluation.', status: 502, retryable: true) unless valid
301
+ end
302
+ begin
303
+ AbuseZero.validate(data, op['response'], response: true)
304
+ rescue ArgumentError, KeyError
305
+ raise Error.new('INVALID_RESPONSE', 'AbuseZero returned an unreadable response.', status: 502, retryable: true)
306
+ end
307
+ return data
308
+ end
309
+ detail = data.is_a?(Hash) && data['error'].is_a?(Hash) ? data['error'] : {}
310
+ raise Error.new(detail.fetch('code', 'HTTP_ERROR'), detail.fetch('message', 'AbuseZero could not finish the request.'), status: status, request_id: response['X-Request-ID'], retryable: ![401, 403].include?(status) && !status.between?(300, 399) && ([429, 502, 503, 504].include?(status) || detail['retryable'] == true), docs_url: detail['docs_url'])
311
+ end
312
+ end
313
+ end