hardening: round-9 reviewer findings (int-boundary cross-lang parity)

Close cross-language byte-parity hole: Python's _reject_floats only walked for
float, while Node's stableStringify hard-rejects integers outside Number.MAX_SAFE_INTEGER
(2^53 - 1). A Python-signed profile with an oversized int produced a valid
self-verifying envelope that Node could not parse. Sign-time rejection on the
Python side now matches Node, plus a checked-in cross-lang fixture
(int-boundary) covers the safe-edge integer for both languages.

Renames _reject_floats to _reject_unsafe_numbers (private; not exported) and
extends it to raise ValueError for any int whose magnitude exceeds 2^53 - 1.
bool subclass of int still allowed; container walking (dict, list, tuple, set,
frozenset) preserved.

Tests: 7 new cases under TestUnsafeNumberRejection (max_safe boundary accept,
min_safe boundary accept, 2^53 reject, 2^60 reject, -(2^53) reject, nested
2^60 reject, bool accept). Existing float rejection tests kept intact under
the broader class name.

Cross-lang fixture: tests/fixtures/cross-lang/{py,node}-int-boundary.json
exercise max_safe_int / min_safe_int / small_int / neg_small_int / zero. Both
fixtures verify in both languages. node-int-boundary.json was generated by the
node-commerce companion script and copied here.

scripts/generate_int_boundary_fixture.py: one-shot regenerator.

Tests: 809 pass + 3 skipped, 95.22% coverage. ruff + ty clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

README.md

@@ -232,7 +232,7 @@ jwks = build_jwks_response([key.public_jwk])
 
 `verify_ucp_profile` enforces the JWS protected header `typ='ucp-profile+jws'`, restricts `alg` to `EdDSA`/`ES256`, requires a `kid`, rejects duplicate kids in the JWKS, and compares the canonical body bytes against the JWS payload to catch swap-after-sign tampering. Failures raise `UCPVerificationError` (a `ValueError` subclass) with a discriminated `code` attribute (`no_signature`/`missing_kid`/`kid_not_found`/`duplicate_kid`/`unsupported_alg`/`wrong_typ`/`signature_invalid`/`body_mismatch`/`malformed_jws`/`malformed_jwks`/`unusable_key`/`unrecognized_critical_header`).
 
-`sign_ucp_profile` rejects profiles containing `float` values: cross-language float canonicalization is not stable, so use decimal strings (e.g. `"9.99"`) for any monetary or fractional fields you put in `extras`.
+`sign_ucp_profile` rejects profiles containing `float` values and `int` values whose magnitude exceeds `Number.MAX_SAFE_INTEGER` (2^53 - 1): cross-language float canonicalization is not stable, and Python's arbitrary-width ints lose precision when JS verifiers reparse the canonical body. Use decimal strings (e.g. `"9.99"`) for monetary or fractional fields and for any integer that may exceed the safe range.
 
 **Persisting the private JWK.** Mint once via `generate_ucp_signing_key()`, serialize via `key.private_key.as_dict(private=True)`, store in your secret manager. On each container start, read the secret, `OKPKey.import_key(jwk_dict)` (or `ECKey.import_key` for ES256) to re-hydrate. Remote-signer flows (KMS-backed asymmetric keys) require subclassing the joserfc Key to delegate the sign hook; `OKPKey`/`ECKey` themselves only carry local key material.
 

agentscore_commerce/identity/ucp_jwks.py

@@ -41,6 +41,8 @@
 _ALLOWED_ALGS = ("EdDSA", "ES256")
 _UCP_TYP = "ucp-profile+jws"
 
+_MAX_SAFE_INT = 2**53 - 1
+
 
 @contextlib.contextmanager
 def _suppress_joserfc_eddsa_warning() -> Iterator[None]:
@@ -159,14 +161,22 @@ def generate_ucp_signing_key(*, kid: str, alg: Literal["EdDSA", "ES256"] = "EdDS
     return GeneratedUCPKey(private_key=priv, public_jwk=public_jwk)
 
 
-def _reject_floats(value: Any) -> None:
-    """Walk ``value`` and raise if any non-integer ``float`` is encountered.
+def _reject_unsafe_numbers(value: Any) -> None:
+    """Walk ``value`` and raise on any number that won't survive cross-language parity.
+
+    Two failure modes are rejected:
+
+    * Non-integer ``float`` values. Cross-language float canonicalization (RFC 8785
+      §3.2.2.3) diverges between Python's ``json.dumps`` and Node's ``JSON.stringify``
+      (e.g. ``1.0`` vs ``1``, ``1e-7`` vs ``1e-07``). Use decimal strings (``"9.99"``)
+      for monetary or fractional fields.
+    * ``int`` values whose magnitude exceeds ``Number.MAX_SAFE_INTEGER`` (2^53 - 1).
+      Python ints are arbitrary-width, but JS verifiers parse the canonical body via
+      ``JSON.parse`` which silently loses precision past 2^53. Use a decimal string
+      for any integer that may exceed the safe range.
 
-    Cross-language float canonicalization (RFC 8785 §3.2.2.3) diverges between
-    Python's ``json.dumps`` and Node's ``JSON.stringify`` (e.g. ``1.0`` vs ``1``,
-    ``1e-7`` vs ``1e-07``). Catching the drift at sign-time prevents
-    silent verifier-side failures in production. Use decimal strings (``"9.99"``)
-    for monetary or fractional fields.
+    Catching the drift at sign-time prevents silent verifier-side failures in
+    production.
     """
     if isinstance(value, bool):
         return  # bool subclasses int; allow.
@@ -177,12 +187,19 @@ def _reject_floats(value: Any) -> None:
             "to preserve cross-language byte-parity."
         )
         raise ValueError(msg)
+    if isinstance(value, int) and abs(value) > _MAX_SAFE_INT:
+        msg = (
+            f"UCP profile canonicalization rejects integer {value} that exceeds "
+            "Number.MAX_SAFE_INTEGER (2^53 - 1). JS verifiers cannot losslessly "
+            "parse this; use a decimal string to preserve cross-language byte-parity."
+        )
+        raise ValueError(msg)
     if isinstance(value, dict):
         for v in value.values():
-            _reject_floats(v)
+            _reject_unsafe_numbers(v)
     elif isinstance(value, list | tuple | set | frozenset):
         for v in value:
-            _reject_floats(v)
+            _reject_unsafe_numbers(v)
 
 
 def _canonicalize_profile(profile: dict[str, Any]) -> bytes:
@@ -192,13 +209,14 @@ def _canonicalize_profile(profile: dict[str, Any]) -> bytes:
     nesting level, returns UTF-8 JSON bytes. Cross-language byte-identical with the
     Node ``stableStringify`` output.
 
-    Throws ``ValueError`` on float input — see :func:`_reject_floats`.
+    Throws ``ValueError`` on float input or oversized int (see
+    :func:`_reject_unsafe_numbers`).
 
     UCP §6.2: "the JSON-serialized profile body, with ``signature`` removed and keys
     ordered lexicographically at every nesting level."
     """
     stripped = {k: v for k, v in profile.items() if k != "signature"}
-    _reject_floats(stripped)
+    _reject_unsafe_numbers(stripped)
     # ``ensure_ascii=False`` so non-ASCII characters travel as UTF-8 (matches Node's
     # JSON.stringify default). ``sort_keys=True`` sorts keys at every level. Compact
     # separators avoid whitespace drift.

scripts/generate_int_boundary_fixture.py

@@ -0,0 +1,61 @@
+"""One-shot generator for the int-boundary cross-lang fixture (Python side).
+
+Writes ``tests/fixtures/cross-lang/py-int-boundary.json``. The fixture exercises
+the safe-integer boundary that BOTH languages must round-trip identically:
+``Number.MAX_SAFE_INTEGER`` (2**53 - 1), its negative, zero, and small ints.
+Lossy values (>2**53) are NOT in the fixture (they're rejected at sign time);
+they're unit-tested in each language's signing path.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agentscore_commerce.identity.ucp_jwks import (
+    build_jwks_response,
+    generate_ucp_signing_key,
+    sign_ucp_profile,
+)
+
+OUT = Path(__file__).resolve().parent.parent / "tests" / "fixtures" / "cross-lang" / "py-int-boundary.json"
+
+KID = "py-int-boundary-EdDSA"
+
+
+def main() -> None:
+    key = generate_ucp_signing_key(kid=KID)
+
+    profile = {
+        "version": "2026-04-17",
+        "spec": "https://ucp.dev/",
+        "name": "Int Boundary Merchant",
+        "services": [{"type": "rest", "url": "https://i.example.com"}],
+        "capabilities": [],
+        "payment_handlers": [],
+        "signing_keys": [key.public_jwk],
+        "extras": {
+            "max_safe_int": 9007199254740991,
+            "min_safe_int": -9007199254740991,
+            "small_int": 42,
+            "neg_small_int": -42,
+            "zero": 0,
+        },
+    }
+
+    signed = sign_ucp_profile(profile, signing_key=key.private_key, kid=KID)
+
+    fixture = {
+        "profile": signed,
+        "jwks": build_jwks_response([key.public_jwk]),
+        "alg": "EdDSA",
+        "kid": KID,
+        "generator": "python",
+    }
+
+    OUT.write_text(json.dumps(fixture, indent=2) + "\n")
+    print(f"wrote {OUT}")
+
+
+if __name__ == "__main__":
+    main()

tests/fixtures/cross-lang/node-int-boundary.json

@@ -0,0 +1,46 @@
+{
+  "profile": {
+    "version": "2026-04-17",
+    "spec": "https://ucp.dev/",
+    "services": [
+      {
+        "type": "rest",
+        "url": "https://i.example.com"
+      }
+    ],
+    "capabilities": [],
+    "payment_handlers": [],
+    "signing_keys": [
+      {
+        "kid": "node-int-boundary-EdDSA",
+        "alg": "EdDSA",
+        "use": "sig",
+        "crv": "Ed25519",
+        "kty": "OKP",
+        "x": "uCH2zVsMZjpjmCGrrBSSmvWMftXFFCYDAUC5YG54XKw"
+      }
+    ],
+    "name": "Int Boundary Merchant",
+    "max_safe_int": 9007199254740991,
+    "min_safe_int": -9007199254740991,
+    "small_int": 42,
+    "neg_small_int": -42,
+    "zero": 0,
+    "signature": "eyJhbGciOiJFZERTQSIsImtpZCI6Im5vZGUtaW50LWJvdW5kYXJ5LUVkRFNBIiwidHlwIjoidWNwLXByb2ZpbGUrandzIn0.eyJjYXBhYmlsaXRpZXMiOltdLCJtYXhfc2FmZV9pbnQiOjkwMDcxOTkyNTQ3NDA5OTEsIm1pbl9zYWZlX2ludCI6LTkwMDcxOTkyNTQ3NDA5OTEsIm5hbWUiOiJJbnQgQm91bmRhcnkgTWVyY2hhbnQiLCJuZWdfc21hbGxfaW50IjotNDIsInBheW1lbnRfaGFuZGxlcnMiOltdLCJzZXJ2aWNlcyI6W3sidHlwZSI6InJlc3QiLCJ1cmwiOiJodHRwczovL2kuZXhhbXBsZS5jb20ifV0sInNpZ25pbmdfa2V5cyI6W3siYWxnIjoiRWREU0EiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoibm9kZS1pbnQtYm91bmRhcnktRWREU0EiLCJrdHkiOiJPS1AiLCJ1c2UiOiJzaWciLCJ4IjoidUNIMnpWc01aanBqbUNHcnJCU1NtdldNZnRYRkZDWURBVUM1WUc1NFhLdyJ9XSwic21hbGxfaW50Ijo0Miwic3BlYyI6Imh0dHBzOi8vdWNwLmRldi8iLCJ2ZXJzaW9uIjoiMjAyNi0wNC0xNyIsInplcm8iOjB9.MABQW9Af3K1ThGkncreJJk-Pv2JdRssGkhO0-UHcZpQmnlriPCJJskL91sgaANfBfNMFRvq6v0xqWeAiMWPqDg"
+  },
+  "jwks": {
+    "keys": [
+      {
+        "kid": "node-int-boundary-EdDSA",
+        "alg": "EdDSA",
+        "use": "sig",
+        "crv": "Ed25519",
+        "kty": "OKP",
+        "x": "uCH2zVsMZjpjmCGrrBSSmvWMftXFFCYDAUC5YG54XKw"
+      }
+    ]
+  },
+  "alg": "EdDSA",
+  "kid": "node-int-boundary-EdDSA",
+  "generator": "node"
+}

tests/fixtures/cross-lang/py-int-boundary.json

@@ -0,0 +1,48 @@
+{
+  "profile": {
+    "version": "2026-04-17",
+    "spec": "https://ucp.dev/",
+    "name": "Int Boundary Merchant",
+    "services": [
+      {
+        "type": "rest",
+        "url": "https://i.example.com"
+      }
+    ],
+    "capabilities": [],
+    "payment_handlers": [],
+    "signing_keys": [
+      {
+        "crv": "Ed25519",
+        "x": "orncEOVmokkWyFRnJFYk1TeRC9nrMQG1Ip9kloaOd98",
+        "kid": "py-int-boundary-EdDSA",
+        "alg": "EdDSA",
+        "use": "sig",
+        "kty": "OKP"
+      }
+    ],
+    "extras": {
+      "max_safe_int": 9007199254740991,
+      "min_safe_int": -9007199254740991,
+      "small_int": 42,
+      "neg_small_int": -42,
+      "zero": 0
+    },
+    "signature": "eyJhbGciOiJFZERTQSIsImtpZCI6InB5LWludC1ib3VuZGFyeS1FZERTQSIsInR5cCI6InVjcC1wcm9maWxlK2p3cyJ9.eyJjYXBhYmlsaXRpZXMiOltdLCJleHRyYXMiOnsibWF4X3NhZmVfaW50Ijo5MDA3MTk5MjU0NzQwOTkxLCJtaW5fc2FmZV9pbnQiOi05MDA3MTk5MjU0NzQwOTkxLCJuZWdfc21hbGxfaW50IjotNDIsInNtYWxsX2ludCI6NDIsInplcm8iOjB9LCJuYW1lIjoiSW50IEJvdW5kYXJ5IE1lcmNoYW50IiwicGF5bWVudF9oYW5kbGVycyI6W10sInNlcnZpY2VzIjpbeyJ0eXBlIjoicmVzdCIsInVybCI6Imh0dHBzOi8vaS5leGFtcGxlLmNvbSJ9XSwic2lnbmluZ19rZXlzIjpbeyJhbGciOiJFZERTQSIsImNydiI6IkVkMjU1MTkiLCJraWQiOiJweS1pbnQtYm91bmRhcnktRWREU0EiLCJrdHkiOiJPS1AiLCJ1c2UiOiJzaWciLCJ4Ijoib3JuY0VPVm1va2tXeUZSbkpGWWsxVGVSQzluck1RRzFJcDlrbG9hT2Q5OCJ9XSwic3BlYyI6Imh0dHBzOi8vdWNwLmRldi8iLCJ2ZXJzaW9uIjoiMjAyNi0wNC0xNyJ9.p4tNJUnyRRHUtEBN3_y4DtuKk4CLBQnMfmGHz76wYYaxiAYa0oN251EC4PrkAHrZ6OlgKagTS027yisUf3qeDA"
+  },
+  "jwks": {
+    "keys": [
+      {
+        "crv": "Ed25519",
+        "x": "orncEOVmokkWyFRnJFYk1TeRC9nrMQG1Ip9kloaOd98",
+        "kid": "py-int-boundary-EdDSA",
+        "alg": "EdDSA",
+        "use": "sig",
+        "kty": "OKP"
+      }
+    ]
+  },
+  "alg": "EdDSA",
+  "kid": "py-int-boundary-EdDSA",
+  "generator": "python"
+}

tests/test_ucp_cross_lang.py

@@ -45,5 +45,6 @@ def test_corpus_covers_canonical_scenarios() -> None:
             "unicode",
             "multikey",
             "emoji-keys",
+            "int-boundary",
         ):
             assert f"{lang}-{scenario}.json" in names, f"missing fixture {lang}-{scenario}.json"

tests/test_ucp_jwks.py

@@ -282,7 +282,7 @@ def test_es256_signing_is_non_deterministic_but_both_verify(self) -> None:
         assert verify_ucp_profile(b, build_jwks_response([signer.public_jwk])) is True
 
 
-class TestFloatRejection:
+class TestUnsafeNumberRejection:
     def test_rejects_float_in_profile(self) -> None:
         signer = generate_ucp_signing_key(kid="k")
         profile = {**_base_profile([signer.public_jwk]), "extras": {"rate": 0.0125}}
@@ -325,6 +325,48 @@ def test_rejects_float_in_frozenset(self) -> None:
         with pytest.raises(ValueError, match="rejects float"):
             sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
 
+    def test_accepts_max_safe_int_boundary(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"big": 2**53 - 1}}
+        signed = sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+        assert verify_ucp_profile(signed, build_jwks_response([signer.public_jwk])) is True
+
+    def test_accepts_min_safe_int_boundary(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"big": -(2**53 - 1)}}
+        signed = sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+        assert verify_ucp_profile(signed, build_jwks_response([signer.public_jwk])) is True
+
+    def test_rejects_int_above_max_safe_boundary(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"big": 2**53}}
+        with pytest.raises(ValueError, match="MAX_SAFE_INTEGER"):
+            sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+
+    def test_rejects_int_well_above_max_safe(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"big": 2**60}}
+        with pytest.raises(ValueError, match="MAX_SAFE_INTEGER"):
+            sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+
+    def test_rejects_int_below_min_safe(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"neg": -(2**53)}}
+        with pytest.raises(ValueError, match="MAX_SAFE_INTEGER"):
+            sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+
+    def test_rejects_oversized_int_in_nested_list(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"a": [{"b": 2**60}]}}
+        with pytest.raises(ValueError, match="MAX_SAFE_INTEGER"):
+            sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+
+    def test_accepts_bool_values(self) -> None:
+        signer = generate_ucp_signing_key(kid="k")
+        profile = {**_base_profile([signer.public_jwk]), "extras": {"flag": True, "other": False}}
+        signed = sign_ucp_profile(profile, signing_key=signer.private_key, kid="k")
+        assert verify_ucp_profile(signed, build_jwks_response([signer.public_jwk])) is True
+
 
 class TestUCPSigningKeyFromJWK:
     def test_round_trip_eddsa(self) -> None: