insumer-verify 1.9.2__py3-none-any.whl

insumer_verify/__init__.py

@@ -0,0 +1,43 @@
+"""insumer-verify: verifier for InsumerAPI attestations and wallet trust profiles.
+
+    from insumer_verify import verify_attestation, verify_trust_profile
+
+    result = verify_attestation(response_json, jwks_url="https://insumermodel.com/.well-known/jwks.json")
+    if result["valid"] and response_json["data"]["attestation"]["pass"]:
+        ...
+
+Five independent verdicts on an attestation (signature, condition hashes,
+freshness, expiry, post-quantum companion), four on a trust profile. The
+Python and JavaScript packages implement the same specification and pass the
+same published test vectors.
+"""
+
+from ._jsjson import MAX_CANONICAL_DEPTH, CanonicalDepthError, canonicalize
+from ._keys import DEFAULT_JWKS_URL, PUBLIC_KEY_JWK
+from .verify import (
+    DEFAULT_CLOCK_SKEW_SECONDS,
+    EXPIRY_BINDING_GRACE_MS,
+    classical_attest_preimage,
+    classical_trust_preimage,
+    condition_hash,
+    verify_attestation,
+    verify_trust_profile,
+)
+
+__version__ = "1.9.2"
+
+__all__ = [
+    "verify_attestation",
+    "verify_trust_profile",
+    "classical_attest_preimage",
+    "classical_trust_preimage",
+    "condition_hash",
+    "canonicalize",
+    "CanonicalDepthError",
+    "DEFAULT_CLOCK_SKEW_SECONDS",
+    "EXPIRY_BINDING_GRACE_MS",
+    "MAX_CANONICAL_DEPTH",
+    "DEFAULT_JWKS_URL",
+    "PUBLIC_KEY_JWK",
+    "__version__",
+]

insumer_verify/_jsjson.py

@@ -0,0 +1,325 @@
+"""JavaScript-compatible JSON serialization.
+
+Every preimage and condition hash InsumerAPI signs is defined by the bytes
+``JSON.stringify`` produces in the issuer's runtime. Python's ``json`` module
+differs from it in corners that change those bytes: how non-integral and very
+large numbers are printed, the order in which object keys are emitted when some
+of them look like array indexes, how keys are sorted (code units, not code
+points), and how an array "replacer" filters nested objects. This module
+reproduces the JavaScript behaviour exactly rather than approximating it with
+``json.dumps``.
+
+Nothing here is specific to attestations. It is the serializer the verifier
+needs, kept separate so that it can be tested against known JavaScript output.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, List, Optional, Sequence
+
+#: Maximum nesting depth this verifier will canonicalize.
+#:
+#: Canonicalization runs alongside signature verification, not after it, so the
+#: recursive walk below is reachable by anyone holding an artifact: a signature
+#: does not have to be valid to get here. 128 open containers matches the bound
+#: the JavaScript reference verifier applies, so a verifier that refuses here
+#: refuses what it refuses. The deepest artifact in the published conformance
+#: corpus nests 9 levels.
+MAX_CANONICAL_DEPTH = 128
+
+
+class CanonicalDepthError(ValueError):
+    """Raised when an artifact nests past :data:`MAX_CANONICAL_DEPTH`.
+
+    Callers turn this into a failed check: it is a refusal to verify, never a
+    passing verdict.
+    """
+
+    def __init__(self, limit: int = MAX_CANONICAL_DEPTH) -> None:
+        super().__init__(f"Artifact nests deeper than {limit} levels; refusing to canonicalize")
+        self.limit = limit
+
+
+# ── Strings ──────────────────────────────────────────────────────────
+
+_SHORT_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def js_string(s: str) -> str:
+    """``JSON.stringify`` of a string.
+
+    Escapes the quote, the backslash, the five short control escapes, every
+    other control character below U+0020 as ``\\u00xx`` (lowercase hex), and a
+    lone surrogate as ``\\udxxx`` (well-formed ``JSON.stringify``, ES2019).
+    Everything else, including non-ASCII text, is emitted as-is.
+    """
+    out: List[str] = ['"']
+    for ch in s:
+        esc = _SHORT_ESCAPES.get(ch)
+        if esc is not None:
+            out.append(esc)
+            continue
+        o = ord(ch)
+        if o < 0x20 or 0xD800 <= o <= 0xDFFF:
+            out.append("\\u%04x" % o)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+# ── Numbers ──────────────────────────────────────────────────────────
+
+_MAX_SAFE_INTEGER = 2**53
+
+
+def js_number(n: Any) -> str:
+    """``JSON.stringify`` of a number: ECMAScript ``Number::toString`` in base 10.
+
+    Integers up to 2**53 print as themselves. Anything else is treated as the
+    IEEE double JavaScript would hold, printed with the shortest digit string
+    that round-trips, in plain decimal notation for exponents between -7 and
+    21 and in ``d.ddde+xx`` form outside that range. NaN and the infinities
+    print as ``null``, as ``JSON.stringify`` does.
+    """
+    if isinstance(n, bool):
+        raise TypeError("booleans are not numbers")
+    if isinstance(n, int):
+        if abs(n) < _MAX_SAFE_INTEGER:
+            return str(n)
+        n = float(n)
+    if not isinstance(n, float):
+        raise TypeError(f"not a number: {type(n).__name__}")
+    if math.isnan(n) or math.isinf(n):
+        return "null"
+    if n == 0:
+        return "0"  # JavaScript prints -0 as "0"
+
+    sign = "-" if n < 0 else ""
+    text = repr(abs(n))  # shortest round-trip digits
+    if "e" in text:
+        mantissa, exp_text = text.split("e")
+        exponent = int(exp_text)
+    else:
+        mantissa, exponent = text, 0
+    if "." in mantissa:
+        int_part, frac_part = mantissa.split(".")
+    else:
+        int_part, frac_part = mantissa, ""
+    digits = int_part + frac_part
+    exponent -= len(frac_part)  # value = int(digits) * 10**exponent
+    digits = digits.lstrip("0")
+    stripped = len(digits) - len(digits.rstrip("0"))
+    digits = digits[: len(digits) - stripped] if stripped else digits
+    exponent += stripped
+    k = len(digits)  # number of significant digits
+    pos = k + exponent  # ECMAScript "n": value = 0.digits * 10**pos
+
+    if k <= pos <= 21:
+        return sign + digits + "0" * (pos - k)
+    if 0 < pos <= 21:
+        return sign + digits[:pos] + "." + digits[pos:]
+    if -6 < pos <= 0:
+        return sign + "0." + "0" * (-pos) + digits
+    e = pos - 1
+    e_text = ("+" if e >= 0 else "-") + str(abs(e))
+    if k == 1:
+        return sign + digits + "e" + e_text
+    return sign + digits[0] + "." + digits[1:] + "e" + e_text
+
+
+# ── Property order ───────────────────────────────────────────────────
+
+
+def _is_array_index(key: str) -> bool:
+    # A canonical numeric string below 2**32 - 1: ASCII digits, no leading zero
+    # (except "0" itself), and in range.
+    if not key or not key.isascii() or not key.isdigit():
+        return False
+    if len(key) > 1 and key[0] == "0":
+        return False
+    return int(key) < 2**32 - 1
+
+
+def js_keys(obj: dict) -> List[str]:
+    """``Object.keys`` order: integer-like keys ascending, then the rest in insertion order.
+
+    ``JSON.parse`` applies the same rule, so a verifier that reproduces an
+    insertion-order preimage must honour it even though ordinary attestation
+    fields never look like array indexes.
+    """
+    indexes: List[str] = []
+    rest: List[str] = []
+    for key in obj:
+        if not isinstance(key, str):
+            raise TypeError("JSON object keys must be strings")
+        (indexes if _is_array_index(key) else rest).append(key)
+    indexes.sort(key=int)
+    return indexes + rest
+
+
+def utf16_sort_key(key: str) -> bytes:
+    """Sort key reproducing the default ``Array.prototype.sort`` on strings.
+
+    JavaScript compares strings by UTF-16 code units. For characters outside the
+    Basic Multilingual Plane that order differs from Python's code-point order,
+    so the keys are compared as big-endian UTF-16 bytes instead.
+    """
+    return key.encode("utf-16-be", "surrogatepass")
+
+
+# ── Serializers ──────────────────────────────────────────────────────
+
+
+def js_stringify(value: Any, depth: int = 0, allow: Optional[Sequence[str]] = None) -> str:
+    """``JSON.stringify(value)`` or, with ``allow``, ``JSON.stringify(value, allow)``.
+
+    With an allow list (JavaScript's array replacer) every object at every
+    nesting level emits only the listed properties, in the list's order. Depth
+    is bounded by :data:`MAX_CANONICAL_DEPTH`.
+    """
+    if depth > MAX_CANONICAL_DEPTH:
+        raise CanonicalDepthError()
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return js_number(value)
+    if isinstance(value, str):
+        return js_string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(js_stringify(v, depth + 1, allow) for v in value) + "]"
+    if isinstance(value, dict):
+        if allow is None:
+            keys: Sequence[str] = js_keys(value)
+        else:
+            keys = [k for k in allow if k in value]
+        parts = [js_string(k) + ":" + js_stringify(value[k], depth + 1, allow) for k in keys]
+        return "{" + ",".join(parts) + "}"
+    raise TypeError(f"cannot serialize {type(value).__name__}")
+
+
+def canonicalize(value: Any, depth: int = 0) -> str:
+    """Canonical JSON as the v2 signing scheme defines it.
+
+    Arrays keep their order and canonicalize each element; objects emit their
+    keys sorted as JavaScript sorts them (UTF-16 code units), each as
+    ``JSON.stringify(key) + ":" + canonicalize(value)``; every other value is
+    ``JSON.stringify(value)``. No whitespace. The sort applies at every nesting
+    level. Depth is bounded by :data:`MAX_CANONICAL_DEPTH`.
+    """
+    if depth > MAX_CANONICAL_DEPTH:
+        raise CanonicalDepthError()
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonicalize(v, depth + 1) for v in value) + "]"
+    if isinstance(value, dict):
+        keys = sorted(js_keys(value), key=utf16_sort_key)
+        return "{" + ",".join(js_string(k) + ":" + canonicalize(value[k], depth + 1) for k in keys) + "}"
+    return js_stringify(value)
+
+
+def assert_depth(value: Any, depth: int = 0) -> None:
+    """Depth check for the v1 (bare JSON) paths.
+
+    v1 preimages are frozen, so the serializer must not alter their bytes. This
+    walks the value only to enforce the same bound the v2 path enforces.
+    """
+    if depth > MAX_CANONICAL_DEPTH:
+        raise CanonicalDepthError()
+    if isinstance(value, (list, tuple)):
+        for v in value:
+            assert_depth(v, depth + 1)
+    elif isinstance(value, dict):
+        for v in value.values():
+            assert_depth(v, depth + 1)
+
+
+def js_object_keys(value: Any) -> List[str]:
+    """``Object.keys(value)`` for any JSON value: an array yields its indexes, a primitive nothing."""
+    if isinstance(value, dict):
+        return js_keys(value)
+    if isinstance(value, (list, tuple)):
+        return [str(i) for i in range(len(value))]
+    return []
+
+
+def v1_condition_canonical(evaluated_condition: Any) -> str:
+    """``JSON.stringify(evaluatedCondition, Object.keys(evaluatedCondition).sort())``.
+
+    The v1 condition-hash preimage. The sorted top-level key list is passed as
+    the replacer array, so top-level keys come out sorted, and a nested object
+    (none exists in a real v1 condition) would be filtered to those same names.
+    A value that is not an object is serialized the way ``JSON.stringify`` would
+    serialize it with that replacer, so the two verifiers agree on every shape.
+    """
+    assert_depth(evaluated_condition)
+    allow = sorted(js_object_keys(evaluated_condition), key=utf16_sort_key)
+    return js_stringify(evaluated_condition, allow=allow)
+
+
+# ── Structural comparison ────────────────────────────────────────────
+
+
+def _same_primitive(a: Any, b: Any) -> bool:
+    # JavaScript strict equality on JSON primitives: a boolean never equals a
+    # number (Python's True == 1 must not leak in), numbers compare by value,
+    # strings and null by identity of kind and value.
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b
+    if a is None or b is None:
+        return a is None and b is None
+    return isinstance(a, str) and isinstance(b, str) and a == b
+
+
+def first_claim_difference(a: Any, b: Any, path: str = "", depth: int = 0) -> Optional[str]:
+    """First path at which two parsed JSON values differ, or ``None`` when deeply equal.
+
+    Objects are compared without regard to member order, arrays in order,
+    primitives by value; a member present on one side only is a difference.
+    Depth-bounded like every other walker here.
+    """
+    if depth > MAX_CANONICAL_DEPTH:
+        raise CanonicalDepthError()
+    a_obj = isinstance(a, (dict, list, tuple))
+    b_obj = isinstance(b, (dict, list, tuple))
+    if not a_obj and not b_obj:
+        return None if _same_primitive(a, b) else path
+    if not a_obj or not b_obj:
+        return path
+    a_arr = isinstance(a, (list, tuple))
+    b_arr = isinstance(b, (list, tuple))
+    if a_arr != b_arr:
+        return path
+    if a_arr:
+        if len(a) != len(b):
+            return path
+        for i, (x, y) in enumerate(zip(a, b)):
+            d = first_claim_difference(x, y, f"{path}[{i}]", depth + 1)
+            if d is not None:
+                return d
+        return None
+    for k in js_keys(a):
+        if k not in b:
+            return f"{path}.{k}" if path else k
+    for k in js_keys(b):
+        if k not in a:
+            return f"{path}.{k}" if path else k
+    for k in js_keys(a):
+        d = first_claim_difference(a[k], b[k], f"{path}.{k}" if path else k, depth + 1)
+        if d is not None:
+            return d
+    return None

insumer_verify/_keys.py

@@ -0,0 +1,225 @@
+"""Key material: the built-in ECDSA key, JWKS resolution by ``kid``, and the signature primitives.
+
+The JWKS holds keys of two types. The first three entries are one ECDSA P-256
+key under three ``kid`` values; the last two are RFC 9964 ``AKP`` entries for
+the ML-DSA-65 post-quantum companion key. Keys are selected by ``kid`` and
+never by position.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import (
+    decode_dss_signature,
+    encode_dss_signature,
+)
+
+#: InsumerAPI's ECDSA P-256 public key in JWK form. The same key is published
+#: at https://insumermodel.com/.well-known/jwks.json under three kids.
+PUBLIC_KEY_JWK: Dict[str, str] = {
+    "kty": "EC",
+    "crv": "P-256",
+    "x": "JtHPhDPnv8AfP0JSlGutxbOlxreV2Chey27Z76q3V2c",
+    "y": "kn34HaxVSJfn8NxwNEBjjLkcrM_GDw1lgnqyADGuc4c",
+}
+
+DEFAULT_JWKS_URL = "https://insumermodel.com/.well-known/jwks.json"
+JWKS_FETCH_TIMEOUT_SECONDS = 15
+
+# Which classical kids may sign which artifact. Attestations and trust profiles
+# share the v1 kid (one frozen scheme) but have distinct v2 kids; a trust kid on
+# an attestation, or the reverse, is a mislabelled artifact and fails Check 1
+# rather than being re-interpreted.
+ATTEST_KIDS = frozenset({"insumer-attest-v1", "insumer-attest-v2"})
+TRUST_KIDS = frozenset({"insumer-attest-v1", "insumer-trust-v2"})
+KNOWN_PQ_KIDS = frozenset({"insumer-attest-pq1", "insumer-trust-pq1"})
+KNOWN_CLASSICAL_KIDS = ATTEST_KIDS | TRUST_KIDS
+
+
+# ── Encoding helpers ─────────────────────────────────────────────────
+
+
+def b64_decode(text: str) -> bytes:
+    """Standard base64 (what ``atob`` reads), padding tolerated."""
+    if not isinstance(text, str):
+        raise ValueError("expected a base64 string")
+    cleaned = "".join(text.split())
+    pad = (-len(cleaned)) % 4
+    if pad == 3:
+        raise ValueError("invalid base64 length")
+    return base64.b64decode(cleaned + "=" * pad, validate=True)
+
+
+def b64url_decode(text: str) -> bytes:
+    """base64url with or without padding."""
+    if not isinstance(text, str):
+        raise ValueError("expected a base64url string")
+    cleaned = text.replace("-", "+").replace("_", "/")
+    return b64_decode(cleaned)
+
+
+def b64url_decode_text(text: str) -> str:
+    return b64url_decode(text).decode("utf-8")
+
+
+# ── JWKS loading and selection ───────────────────────────────────────
+
+
+def load_jwks(options: Dict[str, Any], fallback_url: Optional[str] = None) -> Tuple[Dict[str, Any], str]:
+    """The key set to resolve against: a supplied object (nothing fetched) or the JWKS at a URL.
+
+    Returns the set and a label naming its source for error messages.
+    """
+    supplied = options.get("jwks")
+    if supplied is not None:
+        if not isinstance(supplied, dict) or not isinstance(supplied.get("keys"), list):
+            raise ValueError("Supplied jwks has no keys array")
+        return supplied, "supplied JWKS"
+    url = options.get("jwks_url") or fallback_url or DEFAULT_JWKS_URL
+    fetch: Callable[[str], Dict[str, Any]] = options.get("_fetch_json") or _fetch_json
+    return fetch(url), f"JWKS at {url}"
+
+
+def _fetch_json(url: str) -> Dict[str, Any]:
+    request = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": "insumer-verify-python"})
+    try:
+        with urllib.request.urlopen(request, timeout=JWKS_FETCH_TIMEOUT_SECONDS) as response:  # noqa: S310 (https URL supplied by the caller)
+            status = getattr(response, "status", 200)
+            if status != 200:
+                raise ValueError(f"JWKS fetch failed: {status} {getattr(response, 'reason', '')}".rstrip())
+            body = response.read()
+    except urllib.error.HTTPError as e:
+        raise ValueError(f"JWKS fetch failed: {e.code} {e.reason}") from None
+    except urllib.error.URLError as e:
+        raise ValueError(f"JWKS fetch failed: {e.reason}") from None
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise ValueError(f"JWKS fetch failed: response is not JSON ({e})") from None
+    if not isinstance(parsed, dict):
+        raise ValueError("JWKS fetch failed: response is not a JSON object")
+    return parsed
+
+
+def fetch_jwks_key(options: Dict[str, Any], kid: Optional[str]) -> Dict[str, str]:
+    """The P-256 JWK the response's kid names, or an error naming why none could be selected."""
+    jwks, label = load_jwks(options)
+    keys = jwks.get("keys")
+    if not isinstance(keys, list) or not keys:
+        raise ValueError("JWKS response contains no keys")
+    # A kid that resolves to nothing is a failure, not a reason to fall back: the
+    # first key in the document is not the key the signature claims. A response
+    # with no kid cannot select a key at all (spec Section 3.4 makes kid
+    # mandatory): the set holds keys of two types, and position is not a contract.
+    if not kid:
+        raise ValueError("Response carries no kid; the signing key cannot be selected")
+    key = next((k for k in keys if isinstance(k, dict) and k.get("kid") == kid), None)
+    if key is None:
+        raise ValueError(f'{label} has no key matching kid "{kid}"')
+    if key.get("kty") != "EC" or key.get("crv") != "P-256":
+        raise ValueError(f'JWKS key "{kid}" is not a P-256 EC key; a classical signature cannot be verified with it')
+    return {"kty": "EC", "crv": "P-256", "x": str(key.get("x")), "y": str(key.get("y"))}
+
+
+def select_jwks_key(options: Dict[str, Any], kid: Optional[str]) -> Tuple[Optional[Dict[str, str]], Optional[str]]:
+    """Key selection as a verdict, not an escape.
+
+    When a key set is in play and the response's kid selects no usable key in
+    it, the failure belongs to the signature verdict alone: the other checks
+    need no key and are still performed. Returns ``(key, None)`` or
+    ``(None, reason)``. Nothing is ever substituted.
+    """
+    try:
+        return fetch_jwks_key(options, kid), None
+    except Exception as e:  # noqa: BLE001 (every failure is a reason, never an escape)
+        return None, f"JWKS fetch error: {e}"
+
+
+def fetch_pq_key(options: Dict[str, Any], pq_kid: str) -> bytes:
+    """The raw ML-DSA-65 public key the JWKS lists under ``pq_kid`` (RFC 9964 ``AKP``)."""
+    jwks, label = load_jwks(options)
+    keys = jwks.get("keys") or []
+    key = next((k for k in keys if isinstance(k, dict) and k.get("kid") == pq_kid), None)
+    if key is None:
+        raise ValueError(f'{label} has no key matching pqKid "{pq_kid}"')
+    if key.get("kty") != "AKP" or key.get("alg") != "ML-DSA-65" or not isinstance(key.get("pub"), str):
+        raise ValueError(f'JWKS key "{pq_kid}" is not an RFC 9964 ML-DSA-65 key')
+    return b64url_decode(key["pub"])
+
+
+# ── ECDSA P-256 ──────────────────────────────────────────────────────
+
+
+def ec_public_key(jwk: Dict[str, str]) -> ec.EllipticCurvePublicKey:
+    x = int.from_bytes(b64url_decode(jwk["x"]), "big")
+    y = int.from_bytes(b64url_decode(jwk["y"]), "big")
+    return ec.EllipticCurvePublicNumbers(x, y, ec.SECP256R1()).public_key()
+
+
+def _der_from_signature(sig: bytes, accept_der: bool) -> bytes:
+    if len(sig) == 64:
+        r = int.from_bytes(sig[:32], "big")
+        s = int.from_bytes(sig[32:], "big")
+        return encode_dss_signature(r, s)
+    if accept_der and sig[:1] == b"\x30":
+        r, s = decode_dss_signature(sig)  # raises on malformed DER
+        return encode_dss_signature(r, s)
+    raise ValueError(f"signature is {len(sig)} bytes; expected 64 (P1363 r || s)")
+
+
+def ecdsa_verify(jwk: Dict[str, str], signature: bytes, message: bytes, accept_der: bool = False) -> bool:
+    """ECDSA P-256 / SHA-256 over ``message``.
+
+    ``signature`` is raw P1363 ``r || s`` (what the API emits); on the JWT path
+    a DER-encoded signature is accepted too. Returns ``False`` for a signature
+    that does not verify and raises for a key or encoding that cannot be used.
+    """
+    key = ec_public_key(jwk)
+    der = _der_from_signature(signature, accept_der)
+    try:
+        key.verify(der, message, ec.ECDSA(hashes.SHA256()))
+        return True
+    except InvalidSignature:
+        return False
+
+
+# ── ML-DSA-65 (post-quantum companion) ───────────────────────────────
+
+_ml_dsa_loaded = False
+_ml_dsa_verify: Optional[Callable[[bytes, bytes, bytes], bool]] = None
+
+
+def load_ml_dsa() -> Optional[Callable[[bytes, bytes, bytes], bool]]:
+    """``verify(signature, message, public_key) -> bool`` for ML-DSA-65, or ``None``.
+
+    ML-DSA is not in the standard library, so verification uses ``dilithium-py``
+    when it is installed (``pip install insumer-verify[pq]``). Without it the
+    companion is reported ``unverifiable``: never a silent pass, never a silent
+    failure. FIPS 204 pure mode with an empty context, as the issuer signs.
+    """
+    global _ml_dsa_loaded, _ml_dsa_verify
+    if _ml_dsa_loaded:
+        return _ml_dsa_verify
+    _ml_dsa_loaded = True
+    try:
+        from dilithium_py.ml_dsa import ML_DSA_65  # type: ignore[import-not-found]
+    except Exception:  # noqa: BLE001 (any import problem means "not available")
+        _ml_dsa_verify = None
+        return None
+
+    def verify(signature: bytes, message: bytes, public_key: bytes) -> bool:
+        return bool(ML_DSA_65.verify(public_key, message, signature))
+
+    _ml_dsa_verify = verify
+    return verify
+
+
+PQ_UNAVAILABLE_REASON = "ML-DSA verifier unavailable in this runtime (install dilithium-py, or insumer-verify[pq])"

insumer_verify/_time.py

@@ -0,0 +1,76 @@
+"""Timestamps the way JavaScript's ``Date`` reads them.
+
+The verifier compares ISO 8601 strings from the issuer against the caller's
+clock and the caller's own dates. ``Date.parse`` accepts a date-only form as
+UTC and a date-time form without an offset as local time; this module mirrors
+that so a cutoff a caller writes behaves the same in both verifiers. Anything
+unparsable is ``None`` where JavaScript would have ``NaN``.
+"""
+
+from __future__ import annotations
+
+import calendar
+import re
+import time
+from datetime import date, datetime, timezone
+from typing import Any, Optional
+
+_ISO = re.compile(
+    r"^\s*(\d{4})-(\d{2})-(\d{2})"
+    r"(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?"
+    r"\s*(Z|z|[+-]\d{2}:?\d{2})?\s*$"
+)
+
+
+def now_ms() -> int:
+    """Current wall-clock time in milliseconds since the Unix epoch."""
+    return int(time.time() * 1000)
+
+
+def parse_time_ms(value: Any) -> Optional[int]:
+    """Milliseconds since the epoch for an ISO 8601 string, a datetime, or a number.
+
+    Returns ``None`` when the value cannot be read as a time, which is what the
+    checks treat as JavaScript's ``NaN``.
+    """
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, datetime):
+        return int(value.timestamp() * 1000)
+    if isinstance(value, date):
+        return int(calendar.timegm(value.timetuple()) * 1000)
+    if isinstance(value, (int, float)):
+        return int(value)
+    if not isinstance(value, str):
+        return None
+    m = _ISO.match(value)
+    if not m:
+        return None
+    year, month, day = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    has_time = m.group(4) is not None
+    hour = int(m.group(4) or 0)
+    minute = int(m.group(5) or 0)
+    second = int(m.group(6) or 0)
+    frac = m.group(7) or ""
+    millis = int((frac + "000")[:3]) if frac else 0
+    offset = m.group(8)
+    try:
+        if not has_time or offset is not None:
+            # Date-only is UTC; an explicit offset is applied.
+            base = calendar.timegm((year, month, day, hour, minute, second, 0, 0, 0))
+            if offset and offset not in ("Z", "z"):
+                sign = -1 if offset[0] == "-" else 1
+                digits = offset[1:].replace(":", "")
+                base -= sign * (int(digits[:2]) * 3600 + int(digits[2:]) * 60)
+            return base * 1000 + millis
+        # Date-time with no offset: local time, as Date.parse reads it.
+        local = datetime(year, month, day, hour, minute, second)
+        return int(local.timestamp() * 1000) + millis
+    except (ValueError, OverflowError):
+        return None
+
+
+def iso_from_ms(ms: int) -> str:
+    """``Date.prototype.toISOString`` for a millisecond timestamp."""
+    dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"