Validate the key setup and make the checks name- and type-driven (sections 23.2 and 23.3)

This commit is contained in:
ai-bot committed 2026-10-03 14:51:19 +00:00
1 parent f1fa1e3283
commit 516c6c4523
1 file changed
+110 -33
+110 -33
View File
@@ -1,4 +1,4 @@
"""Validation of incoming health check payloads. """Validation of incoming payloads.
One submission records one selected key only, as decided in section 19 of the 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 requirements. The next check date is derived on the server and never taken from
@@ -10,6 +10,10 @@ The stored status values are English (sections 19 and 21). General results use
explicit ``OK`` or ``PROBLEM`` for a hardware key (section 23.1), and the contact explicit ``OK`` or ``PROBLEM`` for a hardware key (section 23.1), and the contact
confirmation is ``Confirmed current`` or ``Needs external update``. 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, ``available`` is always recorded (section 22). When the key was not available,
the wallet software, the standards, and the security statuses are not recorded the wallet software, the standards, and the security statuses are not recorded
either, so they may be left out of the payload. either, so they may be left out of the payload.
@@ -17,6 +21,8 @@ either, so they may be left out of the payload.
from datetime import date from datetime import date
from database import KEY_COUNT
GENERAL_STATUSES = ("OK", "PROBLEM", "NOT_ASSESSED") GENERAL_STATUSES = ("OK", "PROBLEM", "NOT_ASSESSED")
# Software compatibility requires an active choice, so "not assessed" is not # Software compatibility requires an active choice, so "not assessed" is not
# submittable for a new registration (section 23.1). # submittable for a new registration (section 23.1).
@@ -25,9 +31,11 @@ VERIFICATION_STATUSES = ("OK", "PROBLEM")
STANDARDS_STATUSES = ("YES", "NO", "NOT_ASSESSED") STANDARDS_STATUSES = ("YES", "NO", "NOT_ASSESSED")
SECURITY_STATUSES = ("SECURE", "PATCHED", "VULNERABLE", "COMPROMISED") SECURITY_STATUSES = ("SECURE", "PATCHED", "VULNERABLE", "COMPROMISED")
CONTACT_STATUSES = ("Confirmed current", "Needs external update") CONTACT_STATUSES = ("Confirmed current", "Needs external update")
WALLET_SOFTWARE = ("Sparrow Wallet", "Nunchuk") KEY_TYPES = ("hardware", "cloud")
KEY_PRODUCTS = {1: "SeedSigner", 2: "Blockstream Jade", 3: "Nunchuk"} # The wallet software that is always available, whatever the key setup is
CLOUD_KEY_NUMBER = 3 # (section 23.3).
SPARROW_SOFTWARE = "Sparrow Wallet"
MAX_KEY_NAME_LENGTH = 60
MAX_VERSION_LENGTH = 100 MAX_VERSION_LENGTH = 100
MAX_PATH_LENGTH = 200 MAX_PATH_LENGTH = 200
MAX_NOTES_LENGTH = 2000 MAX_NOTES_LENGTH = 2000
@@ -35,7 +43,7 @@ MAX_COMMENTS_LENGTH = 4000
class ValidationError(ValueError): class ValidationError(ValueError):
"""Raised when a payload does not match the expected health check shape.""" """Raised when a payload does not match the expected shape."""
def next_check_due(checked_at): def next_check_due(checked_at):
@@ -47,6 +55,48 @@ def next_check_due(checked_at):
return checked.replace(year=checked.year + 1, day=28).isoformat() 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): def validate_health_check(payload, keys):
"""Return a normalized single-key health check ready for storage.""" """Return a normalized single-key health check ready for storage."""
if not isinstance(payload, dict): if not isinstance(payload, dict):
@@ -62,13 +112,14 @@ def validate_health_check(payload, keys):
# A key that was not available cannot be checked any further, so the wallet # A key that was not available cannot be checked any further, so the wallet
# software, the standards, and the security statuses stay empty (section 22). # software, the standards, and the security statuses stay empty (section 22).
unavailable = available == 0 unavailable = available == 0
wallet_software = _wallet_software(
payload.get("wallet_software"), key, keys, unavailable
)
return { return {
"checked_at": checked_at, "checked_at": checked_at,
"next_check_due": next_check_due(checked_at), "next_check_due": next_check_due(checked_at),
"wallet_software": _wallet_software( "wallet_software": wallet_software,
payload.get("wallet_software"), key, unavailable
),
"software_version": _text( "software_version": _text(
payload.get("software_version"), "software_version", MAX_VERSION_LENGTH payload.get("software_version"), "software_version", MAX_VERSION_LENGTH
), ),
@@ -82,14 +133,26 @@ def validate_health_check(payload, keys):
"comments": _text(payload.get("comments"), "comments", MAX_COMMENTS_LENGTH), "comments": _text(payload.get("comments"), "comments", MAX_COMMENTS_LENGTH),
"key_check": _key_check(entry, key, available), "key_check": _key_check(entry, key, available),
"tool_checks": _tool_checks( "tool_checks": _tool_checks(
payload.get("tool_checks"), key, payload.get("wallet_software"), unavailable payload.get("tool_checks"), key, wallet_software, unavailable
), ),
"ai_security_checks": _ai_security_checks( "ai_security_checks": _ai_security_checks(
payload.get("ai_security_checks"), key, unavailable 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): def _select_key(key_id, keys):
"""Return the configured key profile with the given id.""" """Return the configured key profile with the given id."""
if isinstance(key_id, bool) or not isinstance(key_id, int): if isinstance(key_id, bool) or not isinstance(key_id, int):
@@ -108,24 +171,39 @@ def _availability(value):
return available return available
def _wallet_software(value, key, unavailable): def _wallet_software_choices(keys):
"""Return the selected wallet software, fixed to Nunchuk for the cloud key. """Return the wallet software choices.
A key that was not available records no software, so the field must be left Sparrow is always available, and every configured cloud key contributes its
out then (section 22). 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 value is None or value == "":
if unavailable: if unavailable:
return None return None
raise ValidationError("wallet_software must be Sparrow Wallet or Nunchuk") raise ValidationError("wallet_software is required when the key is available")
if unavailable: if unavailable:
raise ValidationError( raise ValidationError(
"wallet_software cannot be recorded when the key was not available" "wallet_software cannot be recorded when the key was not available"
) )
if value not in WALLET_SOFTWARE: if key["type"] == "cloud":
raise ValidationError("wallet_software must be Sparrow Wallet or Nunchuk") if value != key["name"]:
if key["key_number"] == CLOUD_KEY_NUMBER and value != "Nunchuk": raise ValidationError("a cloud key records its own name as the wallet software")
raise ValidationError("Nunchuk is the only wallet software for the cloud key") 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 return value
@@ -173,16 +251,15 @@ def _require_nothing_recorded(entries, field):
raise ValidationError(f"{field} cannot be recorded when the key was not available") raise ValidationError(f"{field} cannot be recorded when the key was not available")
def _expected_products(key, wallet_software): def _expected_labels(key, wallet_software):
"""Return the products to record BIP327/SLIP39 for, without duplicates.""" """Return the labels a submission records, without duplicates.
return tuple(dict.fromkeys((KEY_PRODUCTS[key["key_number"]], wallet_software)))
Both the standards and the security statuses are recorded for the selected
def _expected_providers(key): key, by its configured name, and for the selected wallet software
"""Return the security status providers relevant to the selected key.""" (section 23.3). A cloud key that is named after its own software therefore
if key["key_number"] == CLOUD_KEY_NUMBER: contributes one label only.
return ("Nunchuk",) """
return (KEY_PRODUCTS[key["key_number"]], "Sparrow Wallet", "Nunchuk") return tuple(dict.fromkeys((key["name"], wallet_software)))
def _key_check(entry, key, available): def _key_check(entry, key, available):
@@ -289,13 +366,13 @@ def _text(value, field, max_length):
def _tool_checks(entries, key, wallet_software, unavailable): def _tool_checks(entries, key, wallet_software, unavailable):
"""Return the BIP327/SLIP39 rows for the key product and selected software.""" """Return the BIP327/SLIP39 rows for the selected key and wallet software."""
if unavailable: if unavailable:
_require_nothing_recorded(entries, "tool_checks") _require_nothing_recorded(entries, "tool_checks")
return [] return []
if not isinstance(entries, list): if not isinstance(entries, list):
raise ValidationError("tool_checks must be a list") raise ValidationError("tool_checks must be a list")
allowed = set(_expected_products(key, wallet_software)) allowed = set(_expected_labels(key, wallet_software))
seen = set() seen = set()
normalized = [] normalized = []
for entry in entries: for entry in entries:
@@ -321,14 +398,14 @@ def _tool_checks(entries, key, wallet_software, unavailable):
return normalized return normalized
def _ai_security_checks(entries, key, unavailable): def _ai_security_checks(entries, key, wallet_software, unavailable):
"""Return the security status rows relevant to the selected key.""" """Return the security status rows for the selected key and wallet software."""
if unavailable: if unavailable:
_require_nothing_recorded(entries, "ai_security_checks") _require_nothing_recorded(entries, "ai_security_checks")
return [] return []
if not isinstance(entries, list): if not isinstance(entries, list):
raise ValidationError("ai_security_checks must be a list") raise ValidationError("ai_security_checks must be a list")
allowed = set(_expected_providers(key)) allowed = set(_expected_labels(key, wallet_software))
seen = set() seen = set()
normalized = [] normalized = []
for entry in entries: for entry in entries: