"""Strict contract validation and resource-bound cursors.""" import base64 import binascii import hashlib import hmac import json import re from datetime import datetime, timezone from uuid import UUID class ApiError(Exception): def __init__(self, status, code, message, headers=None): self.status, self.code, self.message = status, code, message self.headers = headers or {} def invalid(message='Invalid request'): raise ApiError(400, 'invalid_request', message) def uuid_value(value): if not isinstance(value, str) or not re.fullmatch( r'[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}', value ): invalid('Invalid UUID') return str(UUID(value)) def string(value, maximum, *, blank=False): if not isinstance(value, str) or len(value) > maximum or (not blank and not value.strip()): invalid('Invalid string') # JSON can encode unpaired surrogates; they are not Unicode scalar values. try: value.encode('utf-8') except UnicodeError: invalid('Invalid Unicode') return value def object_fields(value, required, optional=()): if not isinstance(value, dict) or not set(required) <= value.keys() or value.keys() - set(required) - set(optional): invalid('Invalid fields') return value def timestamp(): return datetime.now(timezone.utc).isoformat(timespec='microseconds').replace('+00:00', 'Z') def encode_cursor(resource, key, secret): data = json.dumps([resource, *key], separators=(',', ':')).encode() return base64.urlsafe_b64encode(data + hmac.digest(secret, data, 'sha256')).decode().rstrip('=') def decode_cursor(value, resource, secret): try: if len(value) > 1024 or not re.fullmatch(r'[A-Za-z0-9_-]+', value): raise ValueError() raw = base64.b64decode(value + '=' * (-len(value) % 4), altchars=b'-_', validate=True) data, signature = raw[:-32], raw[-32:] if not hmac.compare_digest(hmac.digest(secret, data, 'sha256'), signature): raise ValueError() scope, created, identifier = json.loads(data) if scope != resource or not isinstance(created, str) or not created.endswith('Z'): raise ValueError() datetime.fromisoformat(created.replace('Z', '+00:00')) UUID(identifier) return created, identifier except (ValueError, TypeError, binascii.Error, UnicodeError): invalid('Invalid cursor') def pagination(request, resource, secret): if any(len(request.query_params.getlist(k)) != 1 for k in request.query_params): invalid('Duplicate query parameter') if set(request.query_params) - {'limit', 'cursor'}: invalid('Unknown query parameter') value = request.query_params.get('limit', '50') if not re.fullmatch(r'[0-9]{1,3}', value) or not 1 <= int(value) <= 100: invalid('Limit must be 1..100') cursor = request.query_params.get('cursor') return int(value), decode_cursor(cursor, resource, secret) if cursor is not None else None async def json_body(request): if request.headers.get('content-type', '').split(';')[0].strip().lower() != 'application/json': raise ApiError(415, 'unsupported_media_type', 'Expected application/json') def unique_pairs(pairs): result = {} for key, value in pairs: if key in result: raise ValueError('duplicate key') result[key] = value return result def no_constant(value): raise ValueError('non-finite number') try: return json.loads((await request.body()).decode('utf-8'), object_pairs_hook=unique_pairs, parse_constant=no_constant) except (ValueError, UnicodeError, RecursionError): invalid('Invalid JSON')