abusezero 0.1.0__py3-none-any.whl

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.
abusezero/core.py ADDED
@@ -0,0 +1,375 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import base64
5
+ import hashlib
6
+ import hmac
7
+ import json
8
+ import math
9
+ import re
10
+ import time
11
+ import threading
12
+ from datetime import datetime, timezone
13
+ from email.utils import parsedate_to_datetime
14
+ from importlib.resources import files
15
+ from typing import Any
16
+ from urllib.parse import quote, urlencode, urlsplit
17
+
18
+ import httpx
19
+
20
+ OPERATIONS = json.loads(files(__package__).joinpath('operations.json').read_text())
21
+ SECRET = re.compile(r'^(?:sk|rk)_[1-9][0-9]{19}\.[A-Za-z0-9_-]{43}$')
22
+ CREDENTIAL_HEADER = re.compile(r'^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-auth-token|x-csrf-token|x-xsrf-token)$|(?:^|-)(token|secret|session|password|api-key|apikey)(?:-|$)', re.I)
23
+
24
+
25
+ class AbuseZeroError(Exception):
26
+ def __init__(self, code: str, message: str, status: int = 0, request_id: str | None = None, retryable: bool = False, docs_url: str | None = None):
27
+ super().__init__(message)
28
+ self.code, self.status, self.request_id, self.retryable, self.docs_url = code, status, request_id, retryable, docs_url
29
+
30
+
31
+ class WebhookVerificationError(ValueError):
32
+ pass
33
+
34
+
35
+ def incoming_request(method: str, url: str, headers: dict[str, str]) -> dict[str, Any]:
36
+ parsed = urlsplit(url)
37
+ if not re.fullmatch(r'[A-Za-z]{1,16}', method) or parsed.scheme not in ('http', 'https') or not parsed.hostname or parsed.username or parsed.password or len(url) > 4096:
38
+ raise ValueError('Provide the incoming HTTP method and URL without credentials.')
39
+ clean, size = {}, 0
40
+ for name, value in headers.items():
41
+ name = name.lower()
42
+ if CREDENTIAL_HEADER.search(name):
43
+ continue
44
+ if not re.fullmatch(r"[!#$%&'*+.^_`|~0-9a-z-]{1,128}", name) or not isinstance(value, str) or '\r' in value or '\n' in value:
45
+ continue
46
+ value = value[:8192]
47
+ if len(clean) >= 64 or size + len(name.encode()) + len(value.encode()) > 32768:
48
+ break
49
+ clean[name] = value
50
+ size += len(name.encode()) + len(value.encode())
51
+ return {'method': method, 'url': url, 'headers': clean}
52
+
53
+
54
+ def _hash(secret: str | bytes, key_version: str, value: str) -> dict[str, str]:
55
+ if not re.fullmatch(r'[\x21-\x7e]{1,128}', key_version):
56
+ raise ValueError('Use a printable key version with no spaces.')
57
+ return {'algorithm': 'hmac-sha256', 'key_version': key_version, 'value': hmac.new(secret.encode() if isinstance(secret, str) else secret, value.encode(), hashlib.sha256).hexdigest()}
58
+
59
+
60
+ def create_phone_hash(*, secret: str | bytes, key_version: str, e164: str) -> dict[str, str]:
61
+ if not re.fullmatch(r'\+[1-9][0-9]{7,14}', e164):
62
+ raise ValueError('Normalize the phone number to E.164 before hashing it.')
63
+ return _hash(secret, key_version, 'abusezero:phone:e164:v1:' + e164)
64
+
65
+
66
+ def create_custom_identifier(*, secret: str | bytes, key_version: str, key: str, value: str) -> dict[str, Any]:
67
+ if not re.fullmatch(r'[a-z][a-z0-9_]{0,63}', key) or not value:
68
+ raise ValueError('Provide a valid identifier key and nonempty value.')
69
+ return {'key': key, 'value_hash': _hash(secret, key_version, f'abusezero:custom:{key}:v1:{value}')}
70
+
71
+
72
+ def verify_webhook(*, payload: str | bytes, headers: dict[str, str], secret: str | list[str | None], tolerance_seconds: float = 300, now: float | None = None) -> dict[str, Any]:
73
+ if not math.isfinite(tolerance_seconds) or tolerance_seconds < 0:
74
+ raise ValueError('Use a nonnegative timestamp tolerance.')
75
+ keys = []
76
+ for item in ([secret] if isinstance(secret, str) else secret):
77
+ if item is None or not item.strip():
78
+ continue
79
+ if not re.fullmatch(r'whsk_[A-Za-z0-9+/]{43}=', item.strip()):
80
+ raise ValueError('Provide the complete webhook signing secret.')
81
+ keys.append(base64.b64decode(item.strip()[5:], validate=True))
82
+ if not keys:
83
+ raise ValueError('Provide a webhook signing secret.')
84
+ h = {k.lower(): v for k, v in headers.items()}
85
+ event_id, timestamp, signature = (h.get('abusezero-webhook-' + n, '') for n in ('id', 'timestamp', 'signature'))
86
+ if not event_id or not re.fullmatch(r'\d{1,12}', timestamp) or abs((time.time() if now is None else now) - int(timestamp)) > tolerance_seconds:
87
+ raise WebhookVerificationError('The webhook timestamp or headers are invalid.')
88
+ body = payload.encode() if isinstance(payload, str) else payload
89
+ signed = (event_id + '.' + timestamp + '.').encode() + body
90
+ expected = [base64.b64encode(hmac.new(k, signed, hashlib.sha256).digest()).decode() for k in keys]
91
+ if not any(hmac.compare_digest(s[3:], e) for s in signature.split() if s.startswith('v1,') for e in expected):
92
+ raise WebhookVerificationError('The webhook signature does not match.')
93
+ try:
94
+ event = json.loads(body)
95
+ if not isinstance(event, dict) or event.get('object') != 'event' or event.get('id') != event_id:
96
+ raise ValueError()
97
+ return event
98
+ except (ValueError, UnicodeError):
99
+ raise WebhookVerificationError('The webhook body is invalid.') from None
100
+
101
+
102
+ def _resolve(schema: Any, root: dict) -> Any:
103
+ while isinstance(schema, dict) and '$ref' in schema:
104
+ ref = root
105
+ for part in schema['$ref'][2:].split('/'):
106
+ ref = ref[part.replace('~1', '/').replace('~0', '~')]
107
+ schema = ref
108
+ return schema
109
+
110
+
111
+ def _unknown_kind(value: Any, variants: list, root: dict) -> bool:
112
+ """A response object whose variants all fix the same kind field, carrying a kind none of them knows yet."""
113
+ resolved = [_resolve(v, root) for v in variants]
114
+ if not isinstance(value, dict) or not all(isinstance(v, dict) and isinstance(v.get('properties'), dict) for v in resolved):
115
+ return False
116
+ fixed = [{k: _resolve(p, root)['const'] for k, p in v['properties'].items() if isinstance(_resolve(p, root), dict) and 'const' in _resolve(p, root)} for v in resolved]
117
+ objects = {f.get('object') for f in fixed}
118
+ if len(objects) != 1 or None in objects or value.get('object') not in objects:
119
+ return False
120
+ for key in set.intersection(*(set(f) for f in fixed)) - {'object'}:
121
+ if isinstance(value.get(key), str) and value[key] not in {f[key] for f in fixed}:
122
+ return True
123
+ return False
124
+
125
+
126
+ def _validate(value: Any, schema: dict, root: dict | None = None, response: bool = False, strict: bool = False, variant: bool = False) -> None:
127
+ # Within v1, responses can gain new values for codes and enums, new kinds of an object and new fields. A response
128
+ # keeps checking each object's own type and, inside a union, the fields that select a variant. A request may leave
129
+ # out a field that has a default.
130
+ root = root or schema
131
+ if '$ref' in schema:
132
+ return _validate(value, _resolve(schema, root), root, response, strict, variant)
133
+ variants = schema.get('anyOf', schema.get('oneOf'))
134
+ if variants:
135
+ matches_count = 0
136
+ for option in variants:
137
+ try:
138
+ _validate(value, option, root, response, strict, True)
139
+ matches_count += 1
140
+ except (ValueError, TypeError):
141
+ pass
142
+ if matches_count == 0 and not (response and _unknown_kind(value, variants, root)) or 'oneOf' in schema and not response and matches_count > 1:
143
+ raise ValueError('The value does not match the request schema.')
144
+ if matches_count == 0:
145
+ return
146
+ types = schema.get('type')
147
+ types = types if isinstance(types, list) else [types] if types else []
148
+ matches = {'null': value is None, 'string': isinstance(value, str), 'object': isinstance(value, dict), 'array': isinstance(value, list), 'integer': isinstance(value, int) and not isinstance(value, bool), 'number': isinstance(value, (float, int)) and not isinstance(value, bool) and math.isfinite(value), 'boolean': isinstance(value, bool)}
149
+ if types and not any(matches.get(t, False) for t in types):
150
+ raise ValueError('The value has the wrong type.')
151
+ if 'const' in schema and value != schema['const'] and (not response or strict) or 'enum' in schema and not response and value not in schema['enum']:
152
+ raise ValueError('The value is not an allowed choice.')
153
+ if isinstance(value, dict):
154
+ properties = schema.get('properties', {})
155
+ for k in schema.get('required', []):
156
+ if k not in value and (response or not isinstance(_resolve(properties.get(k), root), dict) or 'default' not in _resolve(properties.get(k), root)):
157
+ raise ValueError('A required field is missing.')
158
+ for k, v in value.items():
159
+ if 'propertyNames' in schema: _validate(k, schema['propertyNames'], root, response)
160
+ child = properties.get(k, schema.get('additionalProperties', {}))
161
+ if child is False:
162
+ raise ValueError('The request contains an unknown field.')
163
+ if isinstance(child, dict):
164
+ _validate(v, child, root, response, k == 'object' or variant)
165
+ if isinstance(value, list):
166
+ if len(value) < schema.get('minItems', 0) or len(value) > schema.get('maxItems', math.inf):
167
+ raise ValueError('The list has an invalid length.')
168
+ for item in value:
169
+ _validate(item, schema.get('items', {}), root, response)
170
+ if isinstance(value, str):
171
+ if len(value) < schema.get('minLength', 0) or len(value) > schema.get('maxLength', math.inf) or 'pattern' in schema and not re.search(schema['pattern'], value):
172
+ raise ValueError('The text does not match the request schema.')
173
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
174
+ if 'multipleOf' in schema and not math.isclose(value / schema['multipleOf'], round(value / schema['multipleOf']), abs_tol=1e-9):
175
+ raise ValueError('The number must be a permitted multiple.')
176
+ if value < schema.get('minimum', -math.inf) or value > schema.get('maximum', math.inf) or value <= schema.get('exclusiveMinimum', -math.inf) or value >= schema.get('exclusiveMaximum', math.inf):
177
+ raise ValueError('The number is outside the permitted range.')
178
+
179
+
180
+ class Base:
181
+ _public = False
182
+
183
+ def __init__(self, *, key: str | None = None, access_token: str | None = None, workspace: str | None = None, outage: str = 'throw', agent: str | None = None, base_url: str = 'https://api.abusezero.com', transport=None):
184
+ if not self._public and bool(key) == bool(access_token):
185
+ raise AbuseZeroError('CREDENTIAL_REQUIRED', 'Provide one server API key or OAuth access token.', 401)
186
+ if key and not SECRET.fullmatch(key):
187
+ raise AbuseZeroError('INVALID_KEY', 'Provide a server API key.', 401)
188
+ if access_token and (not isinstance(access_token,str) or not re.fullmatch(r'[\x21-\x7e]{1,8192}',access_token)):
189
+ raise AbuseZeroError('INVALID_TOKEN','Provide a valid OAuth access token.',401)
190
+ if access_token and not workspace:
191
+ raise AbuseZeroError('WORKSPACE_REQUIRED', 'Provide the selected workspace.', 422)
192
+ if workspace and not re.fullmatch(r'[1-9][0-9]{19}', workspace):
193
+ raise AbuseZeroError('INVALID_WORKSPACE', 'Provide the workspace ID.', 422)
194
+ if outage not in ('throw', 'allow', 'deny'):
195
+ raise ValueError('Set outage to throw, allow or deny.')
196
+ parsed = urlsplit(base_url)
197
+ if (parsed.scheme != 'https' and not (parsed.scheme == 'http' and parsed.hostname in ('localhost', '127.0.0.1', '::1'))) or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in ('', '/'):
198
+ raise ValueError('Use an HTTPS API origin, or HTTP on loopback for local testing.')
199
+ self._credential, self._workspace, self._outage = key or access_token, workspace, outage
200
+ self._key, self._base, self._transport = bool(key), base_url.rstrip('/'), transport
201
+ self._agent = ''.join(c for c in (agent or '') if ' ' <= c <= '~')[:512]
202
+
203
+ def _prepare(self, action, input, path, idempotency_key):
204
+ op, data = OPERATIONS[action], dict(input or {})
205
+ if op['public'] != self._public:
206
+ raise ValueError('Use the matching public or authenticated client.')
207
+ if self._key and op['scope'] == 'operations:management':
208
+ raise AbuseZeroError('OAUTH_REQUIRED', 'This action needs an OAuth sign-in.', 403)
209
+ if op['mutation'] and not idempotency_key or idempotency_key is not None and not re.fullmatch(r'[\x21-\x7e]{1,128}', idempotency_key):
210
+ raise AbuseZeroError('INVALID_IDEMPOTENCY_KEY', 'Provide an idempotency key: 1–128 printable characters with no spaces.', 422)
211
+ route, path = op['path'], path or {}
212
+ if set(path) != {p['name'] for p in op['paths']}:
213
+ raise ValueError('Pass exactly the path fields this method needs in path.')
214
+ for p in op['paths']:
215
+ value = path[p['name']]
216
+ try:
217
+ _validate(value, p['schema'])
218
+ except (ValueError, TypeError):
219
+ raise ValueError(f"The path field {p['name']} isn't valid.") from None
220
+ route = route.replace('{' + p['name'] + '}', quote(str(value), safe='/' if p['name']=='path' else ''))
221
+ if action.startswith('evaluations.') and 'context' in data and isinstance(data['context'], dict) and isinstance(data['context'].get('user_agent'), str):
222
+ data['context'] = {**data['context'], 'user_agent': data['context']['user_agent'][:512]}
223
+ if 'request' in data and isinstance(data['request'], dict):
224
+ data['request'] = incoming_request(**data['request'])
225
+ try:
226
+ _validate(data, op['input'])
227
+ except (ValueError, TypeError, KeyError):
228
+ raise AbuseZeroError('INVALID_REQUEST', 'Check the request against the API schema.', 422) from None
229
+ headers = {'Accept': 'application/json'}
230
+ if not self._public:
231
+ headers['Authorization'] = 'Bearer ' + self._credential
232
+ if self._workspace: headers['AbuseZero-Workspace'] = self._workspace
233
+ if self._agent: headers['AbuseZero-Agent'] = self._agent
234
+ if idempotency_key: headers['Idempotency-Key'] = idempotency_key
235
+ body = None
236
+ if op['method'] == 'GET':
237
+ query = [(k, json.dumps(v, separators=(',', ':')) if isinstance(v, (dict, list, bool)) or v is None else str(v)) for k,v in data.items()]
238
+ if query: route += '?' + urlencode(query)
239
+ else:
240
+ body = json.dumps(data, ensure_ascii=False, allow_nan=False, separators=(',', ':')).encode()
241
+ headers['Content-Type'] = 'application/json'
242
+ if action=='evaluations.create' and len(body)>49152:
243
+ raise AbuseZeroError('INVALID_REQUEST', 'The evaluation request is too large.', 422)
244
+ budget = op['timeout_ms'] / 1000
245
+ if action=='events.list': budget=max(budget, float(data.get('wait', 0))+5)
246
+ return op, self._base + route, headers, body, budget
247
+
248
+ def _response(self, op, response):
249
+ try: data = response.json()
250
+ except (ValueError, UnicodeError): data = None
251
+ if 200 <= response.status_code < 300:
252
+ if not isinstance(data, dict):
253
+ raise AbuseZeroError('INVALID_RESPONSE', 'AbuseZero returned an unreadable response.', 502, retryable=True)
254
+ if op['id'] in ('evaluations.create','evaluations.dry_run'):
255
+ if data.get('status')=='skipped' and isinstance(data.get('reason'), str) and re.fullmatch(r'[a-z][a-z0-9_]{0,63}',data['reason']):
256
+ return {**data, **({'source':'abusezero'} if op['id']=='evaluations.create' else {})}
257
+ risk=data.get('risk', {})
258
+ if data.get('result') not in ('allow','deny') or not isinstance(risk,dict) or not isinstance(risk.get('band'),str) or risk.get('score') is not None and (not isinstance(risk['score'],(int,float)) or isinstance(risk['score'],bool) or not 0<=risk['score']<=100):
259
+ raise AbuseZeroError('INVALID_RESPONSE', 'AbuseZero returned an unreadable evaluation.', 502, retryable=True)
260
+ if op['id']=='evaluations.create':
261
+ if data.get('object')!='evaluation' or not isinstance(data.get('id'),str) or not re.fullmatch(r'[1-9][0-9]{19}',data['id']):
262
+ raise AbuseZeroError('INVALID_RESPONSE','AbuseZero returned an unreadable evaluation.',502,retryable=True)
263
+ if data.get('outcome') is not None and not isinstance(data['outcome'],dict):
264
+ raise AbuseZeroError('INVALID_RESPONSE','AbuseZero returned an unreadable outcome.',502,retryable=True)
265
+ state = (data.get('outcome') or {}).get('state', response.headers.get('AbuseZero-Outcome-State'))
266
+ if state is not None and (not isinstance(state,str) or not re.fullmatch(r'[a-z][a-z0-9_]{0,63}',state)):
267
+ raise AbuseZeroError('INVALID_RESPONSE','AbuseZero returned an unreadable outcome state.',502,retryable=True)
268
+ data['outcome'] = {'state':state,'due_at':(data.get('outcome') or {}).get('due_at',response.headers.get('AbuseZero-Outcome-Due-At'))} if state else None
269
+ data['source']='abusezero'
270
+ elif data.get('object') != 'evaluation_dry_run' or data.get('dry_run') is not True:
271
+ raise AbuseZeroError('INVALID_RESPONSE','AbuseZero returned an unreadable evaluation.',502,retryable=True)
272
+ try:
273
+ _validate(data, op['response'], response=True)
274
+ except (ValueError, TypeError, KeyError):
275
+ raise AbuseZeroError('INVALID_RESPONSE','AbuseZero returned an unreadable response.',502,retryable=True) from None
276
+ return data
277
+ detail = data.get('error', {}) if isinstance(data,dict) else {}
278
+ if not isinstance(detail,dict): detail={}
279
+ raise AbuseZeroError(detail.get('code','HTTP_ERROR'), detail.get('message',"AbuseZero couldn't finish the request."),response.status_code,response.headers.get('X-Request-ID'),response.status_code not in (401,403) and not 300<=response.status_code<400 and (response.status_code in (429,502,503,504) or detail.get('retryable') is True),detail.get('docs_url'))
280
+
281
+ def _fallback(self, action, input, error):
282
+ if action=='evaluations.create' and self._outage!='throw' and error.retryable and error.status!=429:
283
+ return {'source':'local_outage','claim_id':input['claim_id'],'result':self._outage,'error':error}
284
+ raise error from None
285
+
286
+
287
+ def _retry_delay(response, attempt):
288
+ delay = (0.1,0.25)[attempt]
289
+ if response is not None:
290
+ value=response.headers.get('Retry-After','0')
291
+ try: delay=max(delay,float(value))
292
+ except ValueError:
293
+ try: delay=max(delay,parsedate_to_datetime(value).timestamp()-time.time())
294
+ except (ValueError,TypeError,OverflowError): pass
295
+ return delay
296
+
297
+
298
+ class _AsyncTransportAdapter(httpx.AsyncBaseTransport):
299
+ def __init__(self, transport): self.transport = transport
300
+ async def handle_async_request(self, request):
301
+ def send():
302
+ response = self.transport.handle_request(request)
303
+ try:
304
+ return httpx.Response(response.status_code, headers=response.headers, content=response.read(), extensions=response.extensions)
305
+ finally:
306
+ response.close()
307
+ return await asyncio.to_thread(send)
308
+ async def aclose(self): await asyncio.to_thread(self.transport.close)
309
+
310
+
311
+ class Core(Base):
312
+ """Synchronous interface with a pooled async transport and a cancellable total deadline."""
313
+ def __init__(self, **options):
314
+ transport = options.get('transport')
315
+ if transport is not None and not isinstance(transport, httpx.AsyncBaseTransport):
316
+ options = {**options, 'transport': _AsyncTransportAdapter(transport)}
317
+ self._client = AsyncCore(**options) if not self._public else _AsyncPublicCore(**options)
318
+ self._loop = asyncio.new_event_loop()
319
+ self._thread = threading.Thread(target=self._loop.run_forever, daemon=True)
320
+ self._thread.start()
321
+ self._closed = False
322
+
323
+ def close(self):
324
+ if self._closed: return
325
+ self._closed = True
326
+ try:
327
+ asyncio.run_coroutine_threadsafe(self._client.close(), self._loop).result()
328
+ asyncio.run_coroutine_threadsafe(self._loop.shutdown_asyncgens(), self._loop).result()
329
+ finally:
330
+ self._loop.call_soon_threadsafe(self._loop.stop)
331
+ self._thread.join()
332
+ self._loop.close()
333
+
334
+ def __enter__(self): return self
335
+ def __exit__(self,*args): self.close()
336
+ def _call(self, action, input, path, idempotency_key):
337
+ if self._closed: raise RuntimeError('The client is closed.')
338
+ return asyncio.run_coroutine_threadsafe(self._client._call(action,input,path,idempotency_key), self._loop).result()
339
+
340
+
341
+ class AsyncCore(Base):
342
+ def __init__(self, **options):
343
+ super().__init__(**options)
344
+ self._http=httpx.AsyncClient(transport=self._transport,follow_redirects=False,timeout=None)
345
+ async def close(self): await self._http.aclose()
346
+ async def __aenter__(self): return self
347
+ async def __aexit__(self,*args): await self.close()
348
+ async def _call(self,action,input,path,idempotency_key):
349
+ op,url,headers,body,budget=self._prepare(action,input,path,idempotency_key)
350
+ deadline=time.monotonic()+budget
351
+ error=None
352
+ rate_error=None
353
+ for attempt in range(3):
354
+ response=None
355
+ remaining=deadline-time.monotonic()
356
+ if remaining<=0:
357
+ error=AbuseZeroError('DEADLINE_EXCEEDED','The AbuseZero request budget expired. Try again with the same input and idempotency key.',retryable=True); break
358
+ try:
359
+ async with asyncio.timeout(remaining):
360
+ response=await self._http.request(op['method'],url,headers=headers,content=body,timeout=remaining)
361
+ return self._response(op,response)
362
+ except AbuseZeroError as exc:
363
+ error=exc
364
+ if exc.status==429: rate_error=exc
365
+ except (TimeoutError,httpx.TimeoutException): error=AbuseZeroError('DEADLINE_EXCEEDED','The AbuseZero request budget expired. Try again with the same input and idempotency key.',retryable=True)
366
+ except httpx.HTTPError: error=AbuseZeroError('TRANSPORT_ERROR',"AbuseZero couldn't be reached, or its response couldn't be read. Try again with the same input and idempotency key.",retryable=True)
367
+ if not error.retryable or attempt==2: break
368
+ delay=_retry_delay(response,attempt)
369
+ if time.monotonic()+delay>=deadline: break
370
+ await asyncio.sleep(delay)
371
+ return self._fallback(action,input,rate_error or error)
372
+
373
+
374
+ class _AsyncPublicCore(AsyncCore):
375
+ _public = True