Files
vardkey/validation.py
T

417 lines
16 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 was
not available; no other field offers or accepts it (section 24.1). The software
compatibility result is an explicit ``OK`` or ``PROBLEM`` for a 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).
``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 BIP327/SLIP39 results are gone, together with the rest of that function
(section 24.2).
"""
from datetime import date
from database import KEY_COUNT
# The cloud health result is derived from availability, so it is only ever OK or
# PROBLEM. "Not assessed" is not offered or accepted for it either (section
# 24.1).
CLOUD_HEALTH_STATUSES = ("OK", "PROBLEM")
# 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")
# The wallet software that is always available, whatever the key setup is
# (section 23.3).
SPARROW_SOFTWARE = "Sparrow Wallet"
MAX_KEY_NAME_LENGTH = 60
MAX_VERSION_LENGTH = 100
MAX_PATH_LENGTH = 200
MAX_NOTES_LENGTH = 2000
MAX_COMMENTS_LENGTH = 4000
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 and picks its type once, and both are locked after
the setup is saved (section 23.2). The names must be non-empty and unique,
compared without regard to case.
"""
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})
return sorted(normalized, key=lambda entry: entry["key_number"])
def validate_health_check(payload, keys):
"""Return a normalized single-key health check ready for storage."""
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"))
# A key that was not available cannot be checked any further, so the wallet
# software and the security statuses stay empty (section 22).
unavailable = available == 0
wallet_software = _wallet_software(
payload.get("wallet_software"), key, keys, unavailable
)
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, unavailable
),
"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),
"ai_security_checks": _ai_security_checks(
payload.get("ai_security_checks"), key, wallet_software, unavailable
),
}
def _key_name(value):
"""Return the 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 _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 _wallet_software_choices(keys):
"""Return the wallet software choices.
Sparrow is always available, and every configured cloud key contributes its
own name. A hardware key name is never a software choice (section 23.3).
"""
names = (key["name"] for key in keys if key["type"] == "cloud")
return tuple(dict.fromkeys((SPARROW_SOFTWARE, *names)))
def _wallet_software(value, key, keys, unavailable):
"""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 was not available records no software,
so the field must be left out then (section 22).
"""
if value is None or value == "":
if unavailable:
return None
raise ValidationError("wallet_software is required when the key is available")
if unavailable:
raise ValidationError(
"wallet_software cannot be recorded when the key was not available"
)
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):
raise ValidationError(
f"wallet_software must be {SPARROW_SOFTWARE} or the name of a cloud key"
)
return value
def _compatibility_status(value, key, unavailable):
"""Return the software compatibility result.
The cloud key derives it from availability (section 20), so only the derived
value is accepted there. A hardware key requires an active ``OK`` or
``PROBLEM``, and a missing value is a ``400`` (section 23.1).
"""
if key["type"] == "cloud":
derived = "NOT_ASSESSED" if unavailable else "OK"
if value not in (None, "", derived):
raise ValidationError(
"software_compatibility_status is derived for the cloud key"
)
return derived
if unavailable:
# The remaining checks could not be performed, so the result stays not
# assessed and no other value may accompany it (section 22). This derived
# value is the only place NOT_ASSESSED is still allowed (section 24.1).
if value not in (None, "", "NOT_ASSESSED"):
raise ValidationError(
"software_compatibility_status cannot be recorded "
"when the key was not available"
)
return "NOT_ASSESSED"
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 was not available, 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 was not available (section 22)."""
if entries is None or entries == []:
return
raise ValidationError(f"{field} cannot be recorded when the key was not available")
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):
"""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,
"cloud_health_status": None,
"cloud_provider_operational": 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.
# The cloud key keeps its derived cloud results, because those describe
# the provider rather than a check that could not be run (section 20).
if key["type"] == "cloud":
check["cloud_health_status"] = _cloud_health_status(
entry.get("cloud_health_status"), "cloud_health_status"
)
check["cloud_provider_operational"] = _flag(
entry.get("cloud_provider_operational"), "cloud_provider_operational"
)
return check
required = available == 1
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", required
)
else:
check["cloud_health_status"] = _cloud_health_status(
entry.get("cloud_health_status"), "cloud_health_status"
)
check["cloud_provider_operational"] = _flag(
entry.get("cloud_provider_operational"), "cloud_provider_operational"
)
check["address_path_verified"] = _verification(
entry.get("address_path_verified"), "address_path_verified", required
)
check["address_path"] = _text(entry.get("address_path"), "address_path", MAX_PATH_LENGTH)
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 _cloud_health_status(value, field):
"""Return a derived cloud result, which is OK or PROBLEM, or None.
The cloud result is derived from availability, so "not assessed" is never
offered or accepted for it (section 24.1).
"""
if value is None or value == "":
return None
return _status(value, field, CLOUD_HEALTH_STATUSES)
def _verification(value, field, required):
"""Return OK/PROBLEM, requiring a value when the key was available."""
if value is None or value == "":
if required:
raise ValidationError(f"{field} is required when the key is available")
return None
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, unavailable):
"""Return the security status rows for the selected key and wallet software."""
if unavailable:
_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