Give every alert code its own closing actions (section 26.4)

This commit is contained in:
ai-bot committed 2026-10-06 11:20:25 +00:00
1 parent 2d31163ce6
commit 4a4b1015a7
1 file changed
+116 -31
+116 -31
View File
@@ -10,19 +10,41 @@ performed. A recorded address path that does not match the key is treated the
same way, with its own code, so it is never merged with a real unavailable key same way, with its own code, so it is never merged with a real unavailable key
(section 25.1). (section 25.1).
Every alert names the actions that close it (section 25.3). A rotation replaces Every alert code has its own closing actions (section 26.4). A rotation replaces
the key, while a plain acknowledgement closes an alert until a newer check for the key and is confirmed in the settings, while the other actions close the
the same code and source raises it again. ``collect_alerts`` builds the alerts of alert where it is shown. The software an alert is about is named, so the link,
every saved check, merges them, and leaves out the acknowledged ones, which is the button, and the removal point at the right settings entry (section 26.7).
what the dashboard shows (sections 21 and 25.3). ``collect_alerts`` builds the alerts of every saved check, merges them, and
leaves out the acknowledged ones, which is what the dashboard shows
(sections 21 and 25.3).
An alert without an action is a bug, not a state the user can reach: the key
would be locked with no way out (section 26.1). ``_alert`` therefore refuses to
build one.
""" """
CRITICAL = "critical" CRITICAL = "critical"
INFO = "info" INFO = "info"
# The actions that can close an alert (section 25.3). # The actions that close an alert (section 26.4). A rotation replaces the key and
# is performed in the settings; the other actions close the alert where it is
# shown, after the user has confirmed the action.
ROTATE = "rotate" ROTATE = "rotate"
ACKNOWLEDGE = "acknowledge" REPLACE_HARDWARE = "replace_hardware"
REMOVE_SOFTWARE = "remove_software"
IGNORE = "ignore"
CONTACT_UPDATED = "contact_updated"
# The actions the acknowledgement endpoint performs. A rotation is not one of
# them: it goes through POST /api/keys/<id>/rotate, which requires a new address
# path, so an alert that only offers a rotation cannot be closed by a plain
# acknowledgement (sections 26.1, 26.3 and 26.4).
CLOSING_ACTIONS = frozenset({
REPLACE_HARDWARE,
REMOVE_SOFTWARE,
IGNORE,
CONTACT_UPDATED,
})
ALERT_ACTIONS = frozenset({ROTATE}) | CLOSING_ACTIONS
# Every alert code the app can raise. ``cloud_provider_problem`` and # Every alert code the app can raise. ``cloud_provider_problem`` and
# ``address_verification_failed`` are gone: the first could not be triggered from # ``address_verification_failed`` are gone: the first could not be triggered from
@@ -40,7 +62,7 @@ ALERT_CODES = frozenset({
}) })
# The codes a rotation closes. A security code is only closed by a rotation when # The codes a rotation closes. A security code is only closed by a rotation when
# its source is the key itself, because a problem in the software the key runs # its source is the key itself, because a problem in the software the key runs
# with is not resolved by replacing the key (section 25.3). # with is not resolved by replacing the key (sections 25.3 and 26.4).
ROTATION_CODES = frozenset({ ROTATION_CODES = frozenset({
"key_unavailable", "key_unavailable",
"address_path_mismatch", "address_path_mismatch",
@@ -60,6 +82,23 @@ _ADDRESS_PATH_MISMATCH_MESSAGE = (
"The recorded address path does not match this key. Replace the key before " "The recorded address path does not match this key. Replace the key before "
"continuing; the remaining checks for this key cannot be recorded." "continuing; the remaining checks for this key cannot be recorded."
) )
# The software that produced the result is named by the alert itself, so this
# message covers the software in general (section 26.7).
_SOFTWARE_INCOMPATIBLE_MESSAGE = (
"This wallet software no longer supports the hardware. Add another wallet "
"software in the settings, then remove this one to close the alert."
)
_VULNERABLE_MESSAGE = (
"Security status VULNERABLE: the firmware or security problem must be followed up."
)
_COMPROMISED_MESSAGE = "Security status COMPROMISED: follow the key loss procedure."
_CONTACT_MESSAGE = (
"The contact details for this key need an external update. "
"Update them in your external documentation, then close this alert."
)
# A saved check that predates the software column has no name to point at, so the
# alert falls back to this label and offers the settings link only.
_SOFTWARE_SOURCE = "Software compatibility"
# The stored contact status that asks for an update of the user's own records # The stored contact status that asks for an update of the user's own records
# (section 23.1). # (section 23.1).
_CONTACT_NEEDS_UPDATE = "Needs external update" _CONTACT_NEEDS_UPDATE = "Needs external update"
@@ -130,8 +169,8 @@ def rotation_alert_targets(records, key):
"""Return the (code, source) pairs that rotating one key closes. """Return the (code, source) pairs that rotating one key closes.
A rotation closes the alerts that this key's own checks raised and that a A rotation closes the alerts that this key's own checks raised and that a
replacement resolves (section 25.3). A security alert whose source is the replacement resolves (sections 25.3 and 26.4). A security alert whose source
software the key runs with is not closed by the rotation, because that is the software the key runs with is not closed by the rotation, because that
problem is about the software and not about the key. problem is about the software and not about the key.
""" """
targets = [] targets = []
@@ -148,6 +187,28 @@ def rotation_alert_targets(records, key):
return list(dict.fromkeys(targets)) return list(dict.fromkeys(targets))
def software_alert_targets(records, acknowledgements, names):
"""Return the (code, source) pairs that removing software closes.
Removing a wallet software from the settings closes the alerts the software
itself raised: software that no longer supports the hardware, and a security
status the software got (sections 26.4 and 26.7). Only the alerts that are
still open are returned, so removing a name never writes an acknowledgement
for an alert that is already closed.
"""
folded = {
name.strip().casefold() for name in names if isinstance(name, str)
}
targets = []
for alert in collect_alerts(records, acknowledgements):
software = alert.get("software")
if not software or software.casefold() not in folded:
continue
targets.append((alert["code"], alert["source"]))
# One entry per pair, so a name is closed once.
return list(dict.fromkeys(targets))
def _record_covers_key(record, key): def _record_covers_key(record, key):
"""Return True when a saved check recorded this key.""" """Return True when a saved check recorded this key."""
return any( return any(
@@ -184,19 +245,35 @@ def _recency_key(alert):
return (alert.get("checked_at") or "", alert.get("check_id") or 0) return (alert.get("checked_at") or "", alert.get("check_id") or 0)
def _alert(code, severity, source, message, actions, key_id=None): def _alert(code, severity, source, message, actions, key_id=None, software=None):
"""Return one alert, and refuse to build one without a closing action.
Every alert has to stay closable, or the key would be locked with no way out
(section 26.1). ``software`` names the wallet software the alert is about, so
the settings can remove the right entry, and it is None for every other alert
(section 26.7).
"""
actions = list(actions)
if not actions:
raise ValueError(f"alert {code} must offer at least one closing action")
return { return {
"code": code, "code": code,
"severity": severity, "severity": severity,
"source": source, "source": source,
"message": message, "message": message,
"actions": list(actions), "actions": actions,
"key_id": key_id, "key_id": key_id,
"software": software,
} }
def _key_alerts(key_check): def _key_alerts(key_check):
"""Return the alerts for one key check.""" """Return the alerts for one key check.
A key alert is closed by replacing the key. A hardware failure may also be
closed by replacing the hardware wallet, because the key and its address path
stay the same when the same seed is restored on a new device (section 26.4).
"""
source = f"Key {key_check.get('key_number')}: {key_check.get('name')}" source = f"Key {key_check.get('key_number')}: {key_check.get('name')}"
key_id = key_check.get("key_id") key_id = key_check.get("key_id")
if key_check.get("available") == 0: if key_check.get("available") == 0:
@@ -217,7 +294,7 @@ def _key_alerts(key_check):
CRITICAL, CRITICAL,
source, source,
"The hardware does not work. Test the seed backup on another compatible device.", "The hardware does not work. Test the seed backup on another compatible device.",
(ROTATE, ACKNOWLEDGE), (ROTATE, REPLACE_HARDWARE),
key_id, key_id,
)) ))
if key_check.get("seed_backup_verified") == "PROBLEM": if key_check.get("seed_backup_verified") == "PROBLEM":
@@ -245,17 +322,22 @@ def _key_alerts(key_check):
def _software_alerts(record): def _software_alerts(record):
"""Return the alert for software that no longer supports the hardware.""" """Return the alert for software that no longer supports the hardware.
if record.get("software_compatibility_status") == "PROBLEM":
The source is the software that produced the result, so the alert, the
settings link, and the removal point at the right entry (section 26.7).
"""
if record.get("software_compatibility_status") != "PROBLEM":
return []
software = (record.get("wallet_software") or "").strip() or None
return [_alert( return [_alert(
"software_incompatible", "software_incompatible",
CRITICAL, CRITICAL,
"Software compatibility", software or _SOFTWARE_SOURCE,
"The software no longer supports the hardware. Add alternative software " _SOFTWARE_INCOMPATIBLE_MESSAGE,
"in the settings, then close this alert.", (REMOVE_SOFTWARE,),
(ACKNOWLEDGE,), software=software,
)] )]
return []
def _security_alerts(security_check, key_ids): def _security_alerts(security_check, key_ids):
@@ -263,33 +345,37 @@ def _security_alerts(security_check, key_ids):
The source of a security alert is the provider. When that provider is the The source of a security alert is the provider. When that provider is the
key's own configured name, the key is the source and a rotation closes the key's own configured name, the key is the source and a rotation closes the
alert; otherwise the provider is the software the key runs with, and only a alert; otherwise the provider is the software the key runs with, so the alert
plain acknowledgement closes it (section 25.3). names it and is closed by removing it from the settings (sections 25.3, 26.4
and 26.7). A compromised key or software can never be ignored: the key must
be replaced, and the software must be removed.
""" """
provider = security_check.get("provider") provider = security_check.get("provider")
status = security_check.get("status") status = security_check.get("status")
key_id = key_ids.get(provider) key_id = key_ids.get(provider)
software = None if key_id is not None else provider
if status == "VULNERABLE": if status == "VULNERABLE":
actions = (ROTATE, ACKNOWLEDGE) if key_id is not None else (ACKNOWLEDGE,) actions = (ROTATE, IGNORE) if key_id is not None else (REMOVE_SOFTWARE, IGNORE)
return [_alert( return [_alert(
"security_vulnerable", "security_vulnerable",
CRITICAL, CRITICAL,
provider, provider,
"Security status VULNERABLE: the firmware or security problem must be followed up.", _VULNERABLE_MESSAGE,
actions, actions,
key_id, key_id,
software,
)] )]
if status == "COMPROMISED": if status == "COMPROMISED":
# A compromised key must be replaced, so closing is not enough there. actions = (ROTATE,) if key_id is not None else (REMOVE_SOFTWARE,)
actions = (ROTATE,) if key_id is not None else (ACKNOWLEDGE,)
return [_alert( return [_alert(
"security_compromised", "security_compromised",
CRITICAL, CRITICAL,
provider, provider,
"Security status COMPROMISED: follow the key loss procedure.", _COMPROMISED_MESSAGE,
actions, actions,
key_id, key_id,
software,
)] )]
return [] return []
@@ -305,8 +391,7 @@ def _contact_alerts(record):
"contact_info_unconfirmed", "contact_info_unconfirmed",
INFO, INFO,
"Contact information", "Contact information",
"The contact details for this key need an external update. " _CONTACT_MESSAGE,
"Update them in your external documentation, then close this alert.", (CONTACT_UPDATED,),
(ACKNOWLEDGE,),
)] )]
return [] return []