552 lines
21 KiB
Python
552 lines
21 KiB
Python
"""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
|