"""Validation of incoming payloads. One submission records one selected key only, as decided in section 19 of the requirements. The next check date is derived on the server and never taken from the client. The stored status values are English (sections 19 and 21). ``NOT_ASSESSED`` survives only as the derived ``software_compatibility_status`` of a key that could not be checked; no other field offers or accepts it (section 24.1). The software compatibility result is an explicit ``OK`` or ``PROBLEM`` for an available hardware key (section 23.1), and the contact confirmation is ``Confirmed current`` or ``Needs external update``. The key setup is configured once and stored in the database (section 23.2). The configured name is the product label of a key, and the key's type decides which checks apply, never the key number (section 23.3). The address path is part of the key's identity (section 25.1). ``available`` is always recorded (section 22). When the key was not available, the wallet software and the security statuses are not recorded either, so they may be left out of the payload. The address path is recorded by the user and compared with the stored one by the server, which sets ``address_path_verified`` and never takes it from the client (section 25.1). A path that does not match makes the key uncheckable, which is treated exactly like an unavailable key. The wallet software choices are the settings list and the name of every configured cloud key (section 25.4), and the settings, the key rotation and the alert acknowledgements have their own payloads (sections 25.2, 25.3 and 25.4). The BIP327/SLIP39 results are gone, together with the rest of that function (section 24.2). """ from datetime import date from alerts import ALERT_CODES from database import KEY_COUNT # Software compatibility requires an active choice, so "not assessed" is not # submittable for a new registration (section 23.1). COMPATIBILITY_STATUSES = ("OK", "PROBLEM") VERIFICATION_STATUSES = ("OK", "PROBLEM") SECURITY_STATUSES = ("SECURE", "PATCHED", "VULNERABLE", "COMPROMISED") CONTACT_STATUSES = ("Confirmed current", "Needs external update") KEY_TYPES = ("hardware", "cloud") MAX_KEY_NAME_LENGTH = 60 MAX_VERSION_LENGTH = 100 MAX_PATH_LENGTH = 200 MAX_NOTES_LENGTH = 2000 MAX_COMMENTS_LENGTH = 4000 MAX_SOURCE_LENGTH = 200 class ValidationError(ValueError): """Raised when a payload does not match the expected shape.""" def next_check_due(checked_at): """Return the check date one calendar year later, clamping 29 February.""" checked = date.fromisoformat(checked_at) try: return checked.replace(year=checked.year + 1).isoformat() except ValueError: return checked.replace(year=checked.year + 1, day=28).isoformat() def validate_key_setup(payload): """Return the normalized key setup for the three key slots. The user names each key, picks its type, and records its address path once, and all three are locked after the setup is saved (sections 23.2 and 25.1). The names must be non-empty and unique, compared without regard to case. The same address path may be configured for more than one key, because the three keys of one multisig setup normally share their derivation path. """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") entries = payload.get("keys") if not isinstance(entries, list): raise ValidationError("keys must be a list") if len(entries) != KEY_COUNT: raise ValidationError(f"exactly {KEY_COUNT} keys must be configured") normalized = [] numbers = set() names = set() for entry in entries: if not isinstance(entry, dict): raise ValidationError("each key must be an object") number = entry.get("key_number") if isinstance(number, bool) or number not in range(1, KEY_COUNT + 1): raise ValidationError(f"key_number must be between 1 and {KEY_COUNT}") if number in numbers: raise ValidationError("each key number may only be configured once") numbers.add(number) name = _key_name(entry.get("name")) if name.casefold() in names: raise ValidationError("key names must be unique") names.add(name.casefold()) key_type = entry.get("type") if key_type not in KEY_TYPES: raise ValidationError("key type must be hardware or cloud") normalized.append({ "key_number": number, "name": name, "type": key_type, "address_path": _required_path(entry.get("address_path"), "address_path"), }) return sorted(normalized, key=lambda entry: entry["key_number"]) def validate_health_check(payload, keys, software_names=()): """Return a normalized single-key health check ready for storage. ``software_names`` is the wallet software list from the settings, which completes the choices together with the configured cloud key names (section 25.4). """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") entry = payload.get("key_check") if not isinstance(entry, dict): raise ValidationError("key_check must be an object") key = _select_key(entry.get("key_id"), keys) checked_at = _date(payload.get("checked_at"), "checked_at") available = _availability(entry.get("available")) # The server compares the recorded path with the stored one and derives the # verification result from that (section 25.1). address_path, mismatch = _address_path(entry.get("address_path"), key, available) # A key that was not available and a key whose address path does not match # are both uncheckable: nothing else about them can be recorded # (sections 22 and 25.1). uncheckable = available == 0 or mismatch wallet_software = _wallet_software( payload.get("wallet_software"), key, keys, software_names, uncheckable ) return { "checked_at": checked_at, "next_check_due": next_check_due(checked_at), "wallet_software": wallet_software, "software_version": _text( payload.get("software_version"), "software_version", MAX_VERSION_LENGTH ), "software_compatibility_status": _compatibility_status( payload.get("software_compatibility_status"), key, uncheckable ), "software_comments": _text( payload.get("software_comments"), "software_comments", MAX_NOTES_LENGTH ), "contact_info_verified": _contact_status(payload.get("contact_info_verified")), "comments": _text(payload.get("comments"), "comments", MAX_COMMENTS_LENGTH), "key_check": _key_check(entry, key, available, address_path, mismatch), "ai_security_checks": _ai_security_checks( payload.get("ai_security_checks"), key, wallet_software, uncheckable ), } def validate_key_settings(payload, keys): """Return the normalized settings of one key. The name is only a label and may be changed at any time; the address path is part of the key's identity and may only be changed while the key has no saved check, which the caller decides (sections 25.1 and 25.2). """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") key = _select_key(payload.get("key_id"), keys) name = _key_name(payload.get("name")) if any( other["id"] != key["id"] and other["name"].casefold() == name.casefold() for other in keys ): raise ValidationError("key names must be unique") return { "key_id": key["id"], "name": name, "address_path": _required_path(payload.get("address_path"), "address_path"), } def validate_wallet_software(payload, keys): """Return the normalized wallet software list from the settings. The list is stored whole, so it is validated as a whole: at least one name, every name non-empty, no repeated name, and no name that already comes from a configured cloud key (section 25.4). """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") entries = payload.get("wallet_software") if not isinstance(entries, list): raise ValidationError("wallet_software must be a list") if not entries: raise ValidationError("at least one wallet software name is required") cloud_names = { key["name"].casefold() for key in keys if key["type"] == "cloud" } names = [] seen = set() for entry in entries: name = _key_name(entry) folded = name.casefold() if folded in seen: raise ValidationError("wallet software names must be unique") if folded in cloud_names: raise ValidationError( "a configured cloud key already provides this wallet software name" ) seen.add(folded) names.append(name) return names def validate_rotation(payload, keys, key_id): """Return the confirmed rotation of one key. The user confirms that the hardware wallet has been replaced, chooses whether the name stays or changes, and confirms that the address path is unchanged. The type is locked and is never part of the payload (section 25.2). """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") key = _select_key(key_id, keys) if payload.get("replaced") is not True: raise ValidationError("the replacement of the key must be confirmed") if payload.get("address_path_unchanged") is not True: raise ValidationError("an unchanged address path must be confirmed") keep_name = payload.get("keep_name") if not isinstance(keep_name, bool): raise ValidationError("keep_name must be true or false") name = None if not keep_name: name = _key_name(payload.get("name")) if any( other["id"] != key["id"] and other["name"].casefold() == name.casefold() for other in keys ): raise ValidationError("key names must be unique") return {"key_id": key["id"], "keep_name": keep_name, "name": name} def validate_acknowledgement(payload): """Return the normalized acknowledgement of one alert. An acknowledgement closes a single alert, identified by its code and its source, and records why it was closed (section 25.3). """ if not isinstance(payload, dict): raise ValidationError("payload must be a JSON object") code = payload.get("code") if code not in ALERT_CODES: raise ValidationError("code is not a known alert") source = _text(payload.get("source"), "source", MAX_SOURCE_LENGTH) if source is None: raise ValidationError("source is required") reason = _text(payload.get("reason"), "reason", MAX_NOTES_LENGTH) if reason is None: raise ValidationError("reason is required") return {"code": code, "source": source, "reason": reason} def _key_name(value): """Return a configured key name, which must be non-empty text.""" if not isinstance(value, str): raise ValidationError("key name must be text") name = value.strip() if not name: raise ValidationError("key name must not be empty") if len(name) > MAX_KEY_NAME_LENGTH: raise ValidationError("key name is too long") return name def _required_path(value, field): """Return a non-empty address path. The path is a public derivation path and holds no secret (section 25.1). """ if not isinstance(value, str): raise ValidationError(f"{field} must be text") path = value.strip() if not path: raise ValidationError(f"{field} must not be empty") if len(path) > MAX_PATH_LENGTH: raise ValidationError(f"{field} is too long") return path def _select_key(key_id, keys): """Return the configured key profile with the given id.""" if isinstance(key_id, bool) or not isinstance(key_id, int): raise ValidationError("key_id must be a configured key") for key in keys: if key["id"] == key_id: return key raise ValidationError("key_id is not a configured key") def _availability(value): """Return 0 or 1. Availability is always recorded (section 22).""" available = _flag(value, "available") if available is None: raise ValidationError("available is required") return available def _address_path(value, key, available): """Return the recorded address path and whether it matches the key. The recorded path is compared with the path stored for the key, after stripping both: equal gives ``OK``, different gives ``PROBLEM`` (section 25.1). A key that was not available records no path at all, so no mismatch is reported for it. """ if available == 0: return None, False submitted = _text(value, "address_path", MAX_PATH_LENGTH) stored = (key.get("address_path") or "").strip() return submitted, (submitted or "") != stored def _wallet_software_choices(keys, software_names): """Return the wallet software choices. The settings list and the name of every configured cloud key. A hardware key name is never a software choice (sections 23.3 and 25.4). """ cloud_names = (key["name"] for key in keys if key["type"] == "cloud") return tuple(dict.fromkeys((*software_names, *cloud_names))) def _wallet_software(value, key, keys, software_names, uncheckable): """Return the selected wallet software. A cloud key records its own name, because the provider is the software for that key (section 23.3). A key that could not be checked records no software, so the field must be left out then (sections 22 and 25.1). """ if value is None or value == "": if uncheckable: return None raise ValidationError("wallet_software is required when the key is available") if uncheckable: raise ValidationError( "wallet_software cannot be recorded when the key could not be checked" ) if key["type"] == "cloud": if value != key["name"]: raise ValidationError("a cloud key records its own name as the wallet software") return value if value not in _wallet_software_choices(keys, software_names): raise ValidationError( "wallet_software must be one of the configured wallet software names" ) return value def _compatibility_status(value, key, uncheckable): """Return the software compatibility result. A key that could not be checked keeps the derived ``NOT_ASSESSED`` value, which is the only place it is allowed (sections 22, 24.1 and 25.1). A cloud key derives its result from availability (section 20), and an available hardware key requires an active ``OK`` or ``PROBLEM`` (section 23.1). """ if uncheckable: if value not in (None, "", "NOT_ASSESSED"): raise ValidationError( "software_compatibility_status cannot be recorded " "when the key could not be checked" ) return "NOT_ASSESSED" if key["type"] == "cloud": if value not in (None, "", "OK"): raise ValidationError( "software_compatibility_status is derived for the cloud key" ) return "OK" return _status(value, "software_compatibility_status", COMPATIBILITY_STATUSES) def _contact_status(value): """Return the contact confirmation for the selected key's holder. The confirmation is required, also when the key could not be checked, because the question is still asked (section 24.1). Only the status is recorded, never names, addresses, phone numbers, or credentials (section 23.1). """ if value is None or value == "": raise ValidationError("contact_info_verified is required") return _status(value, "contact_info_verified", CONTACT_STATUSES) def _require_nothing_recorded(entries, field): """Reject results for a key that could not be checked (sections 22 and 25.1).""" if entries is None or entries == []: return raise ValidationError(f"{field} cannot be recorded when the key could not be checked") def _expected_labels(key, wallet_software): """Return the labels a submission records, without duplicates. The security statuses are recorded for the selected key, by its configured name, and for the selected wallet software (section 23.3). A cloud key that is named after its own software therefore contributes one label only. """ return tuple(dict.fromkeys((key["name"], wallet_software))) def _key_check(entry, key, available, address_path, mismatch): """Return the normalized check for the selected key.""" check = { "key_id": key["id"], "available": available, "hardware_works": None, "firmware_version": None, "seed_backup_verified": None, "address_path_verified": None, "address_path": None, "comments": _text(entry.get("comments"), "comments", MAX_NOTES_LENGTH), } if available == 0: # The remaining checks could not be performed, so nothing is recorded # (section 22). return check if mismatch: # The recorded path does not match the key, so the key could not be # checked: the path itself, the key note, the contact confirmation and # the overall comment are kept, while everything else stays empty # (section 25.1). check["address_path"] = address_path check["address_path_verified"] = "PROBLEM" return check if key["type"] == "hardware": # Hardware works requires an active Yes or No, so leaving it out is a # 400 (section 24.1). check["hardware_works"] = _flag_required( entry.get("hardware_works"), "hardware_works" ) check["firmware_version"] = _text( entry.get("firmware_version"), "firmware_version", MAX_VERSION_LENGTH ) check["seed_backup_verified"] = _verification( entry.get("seed_backup_verified"), "seed_backup_verified" ) check["address_path"] = address_path # The comparison matched, so the verification result is OK (section 25.1). check["address_path_verified"] = "OK" return check def _date(value, field): if not isinstance(value, str): raise ValidationError(f"{field} must be an ISO date") try: parsed = date.fromisoformat(value) except ValueError as error: raise ValidationError(f"{field} must be an ISO date") from error return parsed.isoformat() def _status(value, field, allowed): if value not in allowed: raise ValidationError(f"{field} is not an allowed status") return value def _verification(value, field): """Return OK/PROBLEM, requiring an active choice.""" if value is None or value == "": raise ValidationError(f"{field} is required when the key is available") return _status(value, field, VERIFICATION_STATUSES) def _flag(value, field): """Return 0 or 1, or None when the value was left out.""" if value is None or value == "": return None if isinstance(value, bool): return int(value) if value in (0, 1): return int(value) raise ValidationError(f"{field} must be 0 or 1") def _flag_required(value, field): """Return 0 or 1, requiring an active choice (section 24.1).""" flag = _flag(value, field) if flag is None: raise ValidationError(f"{field} is required when the key is available") return flag def _text(value, field, max_length): if value is None: text = "" elif isinstance(value, str): text = value.strip() else: raise ValidationError(f"{field} must be text") if len(text) > max_length: raise ValidationError(f"{field} is too long") return text or None def _ai_security_checks(entries, key, wallet_software, uncheckable): """Return the security status rows for the selected key and wallet software.""" if uncheckable: _require_nothing_recorded(entries, "ai_security_checks") return [] if not isinstance(entries, list): raise ValidationError("ai_security_checks must be a list") allowed = set(_expected_labels(key, wallet_software)) seen = set() normalized = [] for entry in entries: if not isinstance(entry, dict): raise ValidationError("each security check must be an object") provider = entry.get("provider") if provider not in allowed: raise ValidationError("security check provider is not relevant for this submission") if provider in seen: raise ValidationError("each provider may only be checked once") seen.add(provider) normalized.append({ "provider": provider, "status": _status(entry.get("status"), "status", SECURITY_STATUSES), "comments": _text(entry.get("comments"), "comments", MAX_NOTES_LENGTH), }) if seen != allowed: raise ValidationError("every relevant provider must have a security status") return normalized