fix(models): enforce strict u64 range validation and normalize from_dict errors

Author: Karen Giannetto

src/shade/models/invoice.py

@@ -24,6 +24,35 @@
 _U64_FIELDS = ("id", "merchant_id")
 _I128_FIELDS = ("amount", "amount_paid", "amount_refunded")
 _TIMESTAMP_FIELDS = ("date_created", "date_paid", "expires_at")
+_U64_MAX = 2**64 - 1
+
+
+def _validate_u64(field: str, value: object) -> int:
+    """Coerce ``value`` to a strictly valid on-chain ``u64``.
+
+    Booleans and floats are rejected outright rather than coerced, since a
+    silent bool->int or float->int cast could hide a malformed contract
+    payload. Everything else is coerced via ``int()`` and range-checked
+    against ``[0, 2**64 - 1]``.
+    """
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be an integer, not a boolean")
+    if isinstance(value, float):
+        raise ValueError(f"{field} must be an integer, not a float")
+    if isinstance(value, int):
+        result = value
+    else:
+        try:
+            result = int(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"{field} must be an integer, got {type(value).__name__}"
+            ) from exc
+    if not 0 <= result <= _U64_MAX:
+        raise ValueError(
+            f"{field} must be between 0 and {_U64_MAX} (u64 range), got {result}"
+        )
+    return result
 
 
 class InvoiceStatus(str, Enum):
@@ -110,14 +139,20 @@ def _from_contract_dict(cls, data: dict) -> dict:
         (or ``None``) pass through untouched, so re-running a previously
         converted dict — as happens on a ``to_dict()`` -> ``from_dict()``
         round trip — is a no-op rather than a double conversion.
+
+        Raises:
+            ValueError: If a ``u64`` or timestamp field is a boolean, a
+                float, negative, or exceeds ``2**64 - 1``.
+            OverflowError: If a timestamp is within the valid ``u64`` range
+                but too large for :class:`~datetime.datetime` to represent.
         """
         converted = dict(data)
 
         for field in _U64_FIELDS:
             value = converted.get(field)
-            if value is None or isinstance(value, bool) or isinstance(value, int):
+            if value is None:
                 continue
-            converted[field] = int(value)
+            converted[field] = _validate_u64(field, value)
 
         for field in _I128_FIELDS:
             value = converted.get(field)
@@ -129,9 +164,8 @@ def _from_contract_dict(cls, data: dict) -> dict:
             value = converted.get(field)
             if value is None or isinstance(value, datetime):
                 continue
-            if isinstance(value, bool):
-                raise ValueError(f"{field} must be a unix timestamp, not a boolean")
-            converted[field] = datetime.fromtimestamp(int(value), tz=timezone.utc)
+            timestamp = _validate_u64(field, value)
+            converted[field] = datetime.fromtimestamp(timestamp, tz=timezone.utc)
 
         return converted
 
@@ -147,4 +181,10 @@ def from_dict(cls, data: dict) -> "Invoice":
                 f"{cls.__name__}.from_dict() expects a dict, got "
                 f"{type(data).__name__}"
             )
-        return cls(**cls._from_contract_dict(data))
+        try:
+            converted = cls._from_contract_dict(data)
+        except (ValueError, OverflowError) as err:
+            field = str(err).split(" ", 1)[0]
+            param = field if field in (*_U64_FIELDS, *_TIMESTAMP_FIELDS) else None
+            raise InvalidRequestError(str(err), param=param) from err
+        return cls(**converted)

tests/test_invoice.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from decimal import Decimal
 
 import pytest
@@ -11,8 +11,9 @@
 PAYER = Keypair.random().public_key
 
 NOW = int(datetime(2026, 8, 1, tzinfo=timezone.utc).timestamp())
-FUTURE = int(datetime(2026, 12, 1, tzinfo=timezone.utc).timestamp())
+FUTURE = int((datetime.now(timezone.utc) + timedelta(days=30)).timestamp())
 PAST = int(datetime(2020, 1, 1, tzinfo=timezone.utc).timestamp())
+U64_MAX = 2**64 - 1
 
 
 def _contract_response(**overrides):
@@ -161,6 +162,46 @@ def test_boolean_merchant_id_is_rejected():
     assert exc_info.value.param == "merchant_id"
 
 
+@pytest.mark.parametrize("field", ["id", "merchant_id"])
+def test_float_id_fields_are_rejected(field):
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(**{field: 1.9}))
+    assert exc_info.value.param == field
+
+
+@pytest.mark.parametrize("field", ["date_created", "date_paid", "expires_at"])
+def test_float_timestamp_fields_are_rejected(field):
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(**{field: 1.9}))
+    assert exc_info.value.param == field
+
+
+@pytest.mark.parametrize("field", ["id", "merchant_id"])
+def test_negative_id_fields_are_rejected(field):
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(**{field: -1}))
+    assert exc_info.value.param == field
+
+
+def test_negative_expires_at_is_rejected():
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(expires_at=-100))
+    assert exc_info.value.param == "expires_at"
+
+
+@pytest.mark.parametrize("field", ["id", "merchant_id"])
+def test_id_fields_exceeding_u64_max_are_rejected(field):
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(**{field: U64_MAX + 1}))
+    assert exc_info.value.param == field
+
+
+def test_expires_at_exceeding_u64_max_is_rejected():
+    with pytest.raises(InvalidRequestError) as exc_info:
+        Invoice.from_dict(_contract_response(expires_at=U64_MAX + 1))
+    assert exc_info.value.param == "expires_at"
+
+
 def test_from_dict_rejects_non_dict_input():
     with pytest.raises(InvalidRequestError) as excinfo:
         Invoice.from_dict(["id", 42])