datumesh 0.1.1__py3-none-any.whl

datumesh/__init__.py

@@ -0,0 +1,101 @@
+"""datumesh: verify Datumesh receipts (signed answers for addressable data cells).
+
+Implements the Datumesh protocol specification, revision ``spec-0.1.1``
+(https://github.com/datumesh-com/datumesh-spec): RFC 8785 canonical JSON,
+SHA-256 hashes, Ed25519 receipt signatures, cell URIs and key documents.
+Only :func:`fetch_keys` touches the network.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict, Optional
+
+from . import _model
+from ._errors import ERROR_CODES, DatumeshError
+from ._json import jcs_bytes
+from ._keys import Key, KeysResult, fetch_keys, key_id, keys_from_response
+from ._uri import format_uri, parse_uri, uri_to_https
+from ._verify import VerifyResult, load, payload_bytes, verify
+
+__version__ = "0.1.1"
+#: The specification revision this package conforms to.
+SPEC_VERSION = "spec-0.1.1"
+
+KINDS = ("scalar", "cell", "ref", "function", "receipt")
+
+__all__ = [
+    "SPEC_VERSION",
+    "ERROR_CODES",
+    "KINDS",
+    "DatumeshError",
+    "Key",
+    "KeysResult",
+    "VerifyResult",
+    "canonicalize",
+    "cell_hash",
+    "fetch_keys",
+    "format_uri",
+    "function_hash",
+    "jcs",
+    "key_id",
+    "keys_from_response",
+    "parse_uri",
+    "receipt_hash",
+    "receipt_payload",
+    "uri_to_https",
+    "verify",
+]
+
+
+def _validated(obj: Any, kind: Optional[str]) -> Dict[str, Any]:
+    value = load(obj)
+    if kind is None:
+        kind = _model.infer_kind(value)
+        if kind is None:
+            raise DatumeshError("E_SCHEMA", "cannot tell which kind of Datumesh object this is", "$")
+    elif kind not in KINDS:
+        raise ValueError(f"kind must be one of {KINDS}, not {kind!r}")
+    _model.VALIDATORS[kind](value)
+    out: Dict[str, Any] = value
+    return out
+
+
+def canonicalize(obj: Any, kind: Optional[str] = None) -> bytes:
+    """Validate ``obj`` as a Datumesh ``kind`` and return its RFC 8785 (JCS) bytes.
+
+    ``kind`` is ``"scalar"``, ``"cell"``, ``"ref"`` (cell reference),
+    ``"function"`` (descriptor) or ``"receipt"`` (the full receipt, ``sig``
+    included; steps 2-4 of SPEC 10.1 are checked). When omitted it is inferred
+    from the members present. ``obj`` is a parsed object or JSON text/bytes,
+    which is parsed strictly (SPEC 6.1). Raises :class:`DatumeshError`.
+    """
+    return jcs_bytes(_validated(obj, kind))
+
+
+def cell_hash(cell: Any) -> str:
+    """The cell id: SHA-256 of the cell's canonical bytes (SPEC 4.4), in lowercase hex. Slices are allowed."""
+    return hashlib.sha256(jcs_bytes(_validated(cell, "cell"))).hexdigest()
+
+
+def function_hash(descriptor: Any) -> str:
+    """The function hash: SHA-256 of the canonical descriptor (SPEC 7), in lowercase hex."""
+    return hashlib.sha256(jcs_bytes(_validated(descriptor, "function"))).hexdigest()
+
+
+def receipt_payload(receipt: Any) -> bytes:
+    """The bytes a receipt's signature covers: JCS of the receipt without ``sig`` (SPEC 8.3)."""
+    return payload_bytes(_validated(receipt, "receipt"))
+
+
+def receipt_hash(receipt: Any) -> str:
+    """The receipt hash: SHA-256 of the receipt without ``sig`` (SPEC 8.3), in lowercase hex.
+
+    The receipt is validated (steps 1-4) first; the signature is not checked.
+    """
+    return hashlib.sha256(receipt_payload(receipt)).hexdigest()
+
+
+def jcs(value: Any) -> bytes:
+    """RFC 8785 canonical bytes of any JSON value (parsed, or text parsed strictly). No Datumesh rules."""
+    return jcs_bytes(load(value))

datumesh/_errors.py

@@ -0,0 +1,72 @@
+"""Error type and the error codes of SPEC.md 10.2."""
+
+from __future__ import annotations
+
+from typing import NoReturn, Optional
+
+#: Every error code SPEC.md 10.2 defines, in the order of its table.
+ERROR_CODES: tuple[str, ...] = (
+    "E_PARSE_JSON",
+    "E_PARSE_DUPLICATE_KEY",
+    "E_PARSE_URI",
+    "E_SCHEMA",
+    "E_CANON_NAME",
+    "E_CANON_ARG_NAME",
+    "E_CANON_ARG_DUPLICATE",
+    "E_CANON_ARG_ORDER",
+    "E_CANON_PERCENT",
+    "E_CANON_TYPE",
+    "E_CANON_NUMBER",
+    "E_CANON_DATE",
+    "E_CANON_INSTANT",
+    "E_CANON_STRING",
+    "E_CANON_HEX",
+    "E_CANON_LICENCE",
+    "E_CANON_SET",
+    "E_CANON_LIMIT",
+    "E_SLICE",
+    "E_PUBLISHER_MISMATCH",
+    "E_VALID_MISMATCH",
+    "E_TIME_ORDER",
+    "E_ARG_UNKNOWN",
+    "E_ARG_MISSING",
+    "E_KEY_UNAVAILABLE",
+    "E_KEY_DOC",
+    "E_KEY_UNKNOWN",
+    "E_KEY_NOT_VALID",
+    "E_SIGNATURE",
+    "E_FN_UNAVAILABLE",
+    "E_FN_HASH_MISMATCH",
+    "E_ARG_TYPE",
+    "E_RETURN_TYPE",
+    "E_INPUT_UNAVAILABLE",
+    "E_INPUT_INVALID",
+    "E_INPUT_UNDECLARED",
+    "E_VALUE_MISMATCH",
+)
+
+
+class DatumeshError(ValueError):
+    """An input broke a rule of the Datumesh specification.
+
+    ``code`` is one of :data:`ERROR_CODES`; ``path`` locates the offending
+    member (a JSON path such as ``$.cell.args.base.value``, or ``uri.path`` /
+    ``uri.query.<name>`` for cell URIs), or is ``None``.
+    """
+
+    code: str
+    path: Optional[str]
+    detail: str
+
+    def __init__(self, code: str, detail: str = "", path: Optional[str] = None) -> None:
+        if code not in ERROR_CODES:
+            raise AssertionError(f"unknown error code {code!r}")
+        self.code = code
+        self.detail = detail
+        self.path = path
+        where = f" at {path}" if path else ""
+        super().__init__(f"{code}{where}: {detail}" if detail else f"{code}{where}")
+
+
+def fail(code: str, detail: str, path: Optional[str] = None) -> NoReturn:
+    raise DatumeshError(code, detail, path)

datumesh/_json.py

@@ -0,0 +1,221 @@
+"""Strict JSON parsing (SPEC.md 6.1, I-JSON) and RFC 8785 canonical serialisation (SPEC.md 6.2)."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Dict, List, Tuple, Union
+
+from ._errors import DatumeshError, fail
+
+JSONText = Union[str, bytes, bytearray, memoryview]
+
+
+class _Duplicate(Exception):
+    def __init__(self, key: str) -> None:
+        self.key = key
+
+
+def _pairs(pairs: List[Tuple[str, Any]]) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    for k, v in pairs:
+        if k in out:
+            raise _Duplicate(k)
+        out[k] = v
+    return out
+
+
+def _number(literal: str) -> float:
+    value = float(literal)
+    if math.isinf(value):
+        raise ValueError(f"number out of IEEE 754 double range: {literal}")
+    return value
+
+
+def _constant(name: str) -> Any:
+    raise ValueError(f"{name} is not JSON")
+
+
+def _has_surrogate(s: str) -> bool:
+    for ch in s:
+        if "\ud800" <= ch <= "\udfff":
+            return True
+    return False
+
+
+def parse_json(data: JSONText, path: str = "$") -> Any:
+    """Parse JSON text strictly per SPEC.md 6.1.
+
+    ``data`` is bytes (must be UTF-8 without a byte order mark) or str (must not
+    start with U+FEFF). Duplicate member names raise E_PARSE_DUPLICATE_KEY; every
+    other failure (syntax, lone surrogates, NaN/Infinity, numbers outside the
+    double range, invalid UTF-8) raises E_PARSE_JSON. Numbers become floats.
+    """
+    if isinstance(data, (bytes, bytearray, memoryview)):
+        raw = bytes(data)
+        if raw.startswith(b"\xef\xbb\xbf"):
+            fail("E_PARSE_JSON", "byte order mark", path)
+        try:
+            text = raw.decode("utf-8", errors="strict")
+        except UnicodeDecodeError as e:
+            fail("E_PARSE_JSON", f"invalid UTF-8: {e.reason}", path)
+    elif isinstance(data, str):
+        text = data
+        if text.startswith(""):
+            fail("E_PARSE_JSON", "byte order mark", path)
+    else:
+        raise TypeError(f"JSON text must be str or bytes, not {type(data).__name__}")
+    try:
+        value = json.loads(
+            text,
+            object_pairs_hook=_pairs,
+            parse_float=_number,
+            parse_int=_number,
+            parse_constant=_constant,
+        )
+    except _Duplicate as e:
+        fail("E_PARSE_DUPLICATE_KEY", f"duplicate member {e.key!r}", path)
+    except RecursionError:
+        fail("E_PARSE_JSON", "nesting too deep", path)
+    except ValueError as e:  # json.JSONDecodeError is a ValueError
+        fail("E_PARSE_JSON", str(e), path)
+    check_json_value(value, path)
+    return value
+
+
+def check_json_value(value: Any, path: str = "$") -> None:
+    """Check that an already-parsed value is I-JSON: dict/list/str/float/int/bool/None only,
+    string keys, no lone surrogates, finite numbers within the double range."""
+    stack: List[Tuple[Any, str]] = [(value, path)]
+    while stack:
+        v, p = stack.pop()
+        if v is None or isinstance(v, bool):
+            continue
+        if isinstance(v, str):
+            if _has_surrogate(v):
+                fail("E_PARSE_JSON", "lone surrogate", p)
+        elif isinstance(v, float):
+            if not math.isfinite(v):
+                fail("E_PARSE_JSON", "NaN and infinities are not JSON", p)
+        elif isinstance(v, int):
+            try:
+                float(v)
+            except OverflowError:
+                fail("E_PARSE_JSON", "number out of IEEE 754 double range", p)
+        elif isinstance(v, dict):
+            for k, item in v.items():
+                if not isinstance(k, str):
+                    fail("E_PARSE_JSON", f"member name {k!r} is not a string", p)
+                if _has_surrogate(k):
+                    fail("E_PARSE_JSON", "lone surrogate in member name", p)
+                stack.append((item, f"{p}.{k}"))
+        elif isinstance(v, list):
+            for i, item in enumerate(v):
+                stack.append((item, f"{p}[{i}]"))
+        else:
+            fail("E_PARSE_JSON", f"{type(v).__name__} is not a JSON value", p)
+
+
+# ---------------------------------------------------------------- RFC 8785
+
+
+def _escape(s: str) -> str:
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif o < 0x20:
+            out.append({"\b": "\\b", "\t": "\\t", "\n": "\\n", "\f": "\\f", "\r": "\\r"}.get(ch, "\\u%04x" % o))
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def format_number(value: float) -> str:
+    """ECMAScript Number.prototype.toString for a finite double (RFC 8785 3.2.2.3)."""
+    if not math.isfinite(value):
+        raise DatumeshError("E_PARSE_JSON", "NaN and infinities have no JSON form")
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    # repr() gives the shortest digit string that round-trips, choosing the closest
+    # when several exist: the same digits ECMAScript's algorithm selects.
+    mantissa, _, exp = repr(abs(value)).partition("e")
+    int_part, _, frac_part = mantissa.partition(".")
+    all_digits = int_part + frac_part
+    # value = 0.<all_digits> * 10**point
+    point = len(int_part) + (int(exp) if exp else 0)
+    leading = len(all_digits) - len(all_digits.lstrip("0"))
+    digits = all_digits[leading:].rstrip("0")
+    n = point - leading  # ECMAScript's n: value = 0.<digits> * 10**n
+    k = len(digits)
+    if k <= n <= 21:
+        s = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        s = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        s = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        es = ("+" if e >= 0 else "-") + str(abs(e))
+        s = digits[0] + ("." + digits[1:] if k > 1 else "") + "e" + es
+    return sign + s
+
+
+def _utf16_key(s: str) -> bytes:
+    return s.encode("utf-16-be", errors="surrogatepass")
+
+
+def _serialise(value: Any, out: List[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, str):
+        out.append(_escape(value))
+    elif isinstance(value, float):
+        out.append(format_number(value))
+    elif isinstance(value, int):
+        out.append(format_number(float(value)))
+    elif isinstance(value, dict):
+        out.append("{")
+        first = True
+        for k in sorted(value, key=_utf16_key):
+            if not first:
+                out.append(",")
+            first = False
+            out.append(_escape(k))
+            out.append(":")
+            _serialise(value[k], out)
+        out.append("}")
+    elif isinstance(value, list):
+        out.append("[")
+        for i, item in enumerate(value):
+            if i:
+                out.append(",")
+            _serialise(item, out)
+        out.append("]")
+    else:
+        raise DatumeshError("E_PARSE_JSON", f"{type(value).__name__} is not a JSON value")
+
+
+def jcs_bytes(value: Any) -> bytes:
+    """RFC 8785 serialisation of an I-JSON value (checked first), as UTF-8 bytes."""
+    check_json_value(value)
+    out: List[str] = []
+    try:
+        _serialise(value, out)
+    except RecursionError:
+        fail("E_PARSE_JSON", "nesting too deep")
+    return "".join(out).encode("utf-8")
+
+
+def sort_key(name: str) -> bytes:
+    """The JCS member order (UTF-16 code units)."""
+    return _utf16_key(name)

datumesh/_keys.py

@@ -0,0 +1,262 @@
+"""Keys (SPEC.md section 9): key ids, key documents, and their retrieval over HTTPS."""
+
+from __future__ import annotations
+
+import hashlib
+import socket
+import ssl
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple, Union
+
+from . import _lexical as lx
+from ._errors import DatumeshError, fail
+from ._json import parse_json
+from ._model import PROTO, require_object
+
+WELL_KNOWN_PATH = "/.well-known/datumesh.json"
+MAX_DOCUMENT_BYTES = 1 << 20
+
+
+def key_id(public: str) -> str:
+    """The key id of an Ed25519 public key given as 64 lowercase hex digits (SPEC 9.1)."""
+    if not isinstance(public, str):
+        raise TypeError("public must be a str of 64 lowercase hex digits")
+    lx.check_hex(public, 64, "public")
+    return hashlib.sha256(bytes.fromhex(public)).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Key:
+    """One published key. ``valid_from``/``valid_to`` are instants, or None for keys
+    supplied as a bare ``{key id: public key}`` mapping (no validity window)."""
+
+    id: str
+    public: str
+    valid_from: Optional[str] = None
+    valid_to: Optional[str] = None
+
+    def usable_at(self, issued: str) -> bool:
+        """SPEC 9.5: ``valid_from <= issued`` and, if present, ``issued < valid_to``."""
+        if self.valid_from is not None and not self.valid_from <= issued:
+            return False
+        return self.valid_to is None or issued < self.valid_to
+
+
+@dataclass(frozen=True)
+class KeysResult:
+    """The outcome of resolving a host's keys (SPEC 9.3).
+
+    ``ok`` is True and ``code`` is ``"OK"`` when ``keys`` holds the host's
+    validated keys; otherwise ``code`` is ``E_KEY_UNAVAILABLE`` or ``E_KEY_DOC``
+    and ``keys`` is empty. ``host`` is the host the keys belong to.
+    """
+
+    ok: bool
+    code: str
+    host: Optional[str]
+    detail: str = ""
+    keys: Tuple[Key, ...] = field(default_factory=tuple)
+
+    @property
+    def key_ids(self) -> Tuple[str, ...]:
+        return tuple(k.id for k in self.keys)
+
+
+def _doc_error(host: Optional[str], detail: str) -> KeysResult:
+    return KeysResult(False, "E_KEY_DOC", host, detail)
+
+
+def validate_key_document(doc: Any, host: Optional[str]) -> KeysResult:
+    """Check a parsed key document against SPEC 9.2. ``host`` is the host it was
+    fetched from (None: take the document's own ``host`` member)."""
+    try:
+        require_object(doc, "$", ("host", "keys", "proto"))
+        if doc["proto"] != PROTO:
+            fail("E_SCHEMA", f"proto must be {PROTO!r}", "$.proto")
+        doc_host = doc["host"]
+        if not isinstance(doc_host, str):
+            fail("E_SCHEMA", "host must be a string", "$.host")
+        lx.check_dns_name(doc_host, "$.host")
+        if host is not None and doc_host != host:
+            fail("E_SCHEMA", f"document is for host {doc_host!r}, fetched from {host!r}", "$.host")
+        keys = doc["keys"]
+        if not isinstance(keys, list) or not 1 <= len(keys) <= lx.LIMIT_KEYS:
+            fail("E_SCHEMA", f"keys must be an array of 1 to {lx.LIMIT_KEYS} keys", "$.keys")
+        out = []
+        seen_ids: set[str] = set()
+        seen_public: set[str] = set()
+        for i, entry in enumerate(keys):
+            p = f"$.keys[{i}]"
+            require_object(entry, p, ("alg", "id", "public", "valid_from"), ("valid_to",))
+            for name in ("alg", "id", "public", "valid_from", "valid_to"):
+                if name in entry and not isinstance(entry[name], str):
+                    fail("E_SCHEMA", f"{name} must be a string", f"{p}.{name}")
+            if entry["alg"] != "ed25519":
+                fail("E_SCHEMA", "alg must be 'ed25519'", f"{p}.alg")
+            lx.check_hex(entry["id"], 16, f"{p}.id")
+            lx.check_hex(entry["public"], 64, f"{p}.public")
+            if key_id(entry["public"]) != entry["id"]:
+                fail("E_SCHEMA", "id is not the key id of public", f"{p}.id")
+            lx.check_instant(entry["valid_from"], f"{p}.valid_from")
+            valid_to = entry.get("valid_to")
+            if valid_to is not None:
+                lx.check_instant(valid_to, f"{p}.valid_to")
+                if not valid_to > entry["valid_from"]:
+                    fail("E_SCHEMA", "valid_to must be later than valid_from", f"{p}.valid_to")
+            if entry["id"] in seen_ids or entry["public"] in seen_public:
+                fail("E_SCHEMA", "the same key appears twice", p)
+            seen_ids.add(entry["id"])
+            seen_public.add(entry["public"])
+            out.append(Key(entry["id"], entry["public"], entry["valid_from"], valid_to))
+        return KeysResult(True, "OK", doc_host, "", tuple(out))
+    except DatumeshError as e:
+        where = f" at {e.path}" if e.path else ""
+        return _doc_error(host if host is not None else (doc.get("host") if isinstance(doc, dict) and isinstance(doc.get("host"), str) else None),
+                          f"{e.code}{where}: {e.detail}")
+
+
+def keys_from_response(host: str, status: Optional[int], body: Union[str, bytes, None]) -> KeysResult:
+    """Interpret the response to ``GET https://<host>/.well-known/datumesh.json`` (SPEC 9.3).
+
+    ``status`` is the HTTP status, or None for a network, DNS, TLS or timeout
+    failure. Any status other than 200 (redirects and 404 included) is
+    E_KEY_UNAVAILABLE; a 200 whose body is not a valid key document for
+    ``host`` is E_KEY_DOC. Never raises.
+    """
+    if not isinstance(host, str):
+        return KeysResult(False, "E_KEY_UNAVAILABLE", None, f"host must be a str, not {type(host).__name__}")
+    try:
+        lx.check_dns_name(host, "host")
+    except DatumeshError as e:
+        return KeysResult(False, "E_KEY_UNAVAILABLE", host, f"cannot retrieve keys for an invalid host: {e.detail}")
+    if status is None:
+        return KeysResult(False, "E_KEY_UNAVAILABLE", host, "network, DNS, TLS or timeout failure")
+    if isinstance(status, bool) or not isinstance(status, int) or status != 200:
+        return KeysResult(False, "E_KEY_UNAVAILABLE", host, f"HTTP status {status!r}")
+    if body is None:
+        return _doc_error(host, "200 response without a body")
+    if not isinstance(body, (str, bytes, bytearray, memoryview)):
+        return _doc_error(host, f"body must be str or bytes, not {type(body).__name__}")
+    try:
+        doc = parse_json(body)
+    except DatumeshError as e:
+        return _doc_error(host, f"{e.code}: {e.detail}")
+    return validate_key_document(doc, host)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None  # urllib then raises HTTPError with the 3xx status
+
+
+def _fetch_url(url: str, timeout: float, context: Optional[ssl.SSLContext] = None) -> Tuple[Optional[int], Optional[bytes]]:
+    """One GET without following redirects. Returns (status, body); status None on any failure."""
+    ctx = context if context is not None else ssl.create_default_context()
+    opener = urllib.request.build_opener(_NoRedirect(), urllib.request.HTTPSHandler(context=ctx))
+    req = urllib.request.Request(url, method="GET", headers={
+        "Accept": "application/json",
+        "User-Agent": "datumesh-py",
+    })
+    try:
+        with opener.open(req, timeout=timeout) as resp:
+            body = resp.read(MAX_DOCUMENT_BYTES + 1)
+            return resp.status, body
+    except urllib.error.HTTPError as e:
+        try:
+            e.close()
+        except Exception:  # pragma: no cover
+            pass
+        return e.code, None
+    except (urllib.error.URLError, ssl.SSLError, socket.timeout, TimeoutError, ConnectionError, OSError, ValueError):
+        return None, None
+
+
+def fetch_keys(host: str, timeout: float = 10.0) -> KeysResult:
+    """Fetch and validate ``https://<host>/.well-known/datumesh.json`` (SPEC 9.3, 9.4).
+
+    One GET; the TLS certificate is verified against the system trust store;
+    redirects are not followed (a 3xx is E_KEY_UNAVAILABLE); ``timeout`` is in
+    seconds. This is the only function in the package that uses the network,
+    and nothing else calls it.
+    """
+    if not isinstance(host, str):
+        raise TypeError(f"host must be a str, not {type(host).__name__}")
+    try:
+        lx.check_dns_name(host, "host")
+    except DatumeshError as e:
+        return KeysResult(False, "E_KEY_UNAVAILABLE", host, f"cannot retrieve keys for an invalid host: {e.detail}")
+    status, body = _fetch_url(f"https://{host}{WELL_KNOWN_PATH}", timeout)
+    if status == 200 and body is not None and len(body) > MAX_DOCUMENT_BYTES:
+        return _doc_error(host, f"key document larger than {MAX_DOCUMENT_BYTES} bytes")
+    return keys_from_response(host, status, body)
+
+
+# ---------------------------------------------------------------- key sources for verify
+
+
+@dataclass(frozen=True)
+class _Source:
+    host: Optional[str]  # None: covers every host
+    result: KeysResult
+    by_id: Dict[str, Key]
+
+
+def _source_from_result(r: KeysResult) -> _Source:
+    return _Source(r.host, r, {k.id: k for k in r.keys})
+
+
+def _source_from_mapping(m: Dict[Any, Any]) -> _Source:
+    keys = []
+    for kid in sorted(m, key=str):
+        pub = m[kid]
+        if not isinstance(kid, str) or not isinstance(pub, str):
+            return _source_from_result(_doc_error(None, "a key mapping maps key id strings to public key strings"))
+        try:
+            lx.check_hex(kid, 16, kid)
+            if key_id(pub) != kid:
+                fail("E_SCHEMA", f"{kid} is not the key id of {pub}", kid)
+        except DatumeshError as e:
+            return _source_from_result(_doc_error(None, f"bad key mapping entry {kid!r}: {e.detail}"))
+        keys.append(Key(kid, pub))
+    r = KeysResult(True, "OK", None, "key id mapping (no validity windows, any host)", tuple(keys))
+    return _source_from_result(r)
+
+
+def key_sources(keys: Any) -> Tuple[_Source, ...]:
+    """Normalise the ``keys`` argument of verify. Raises TypeError only for argument types it cannot accept."""
+    out = []
+
+    def add(item: Any, depth: int) -> None:
+        if isinstance(item, KeysResult):
+            out.append(_source_from_result(item))
+        elif isinstance(item, dict):
+            if any(k in item for k in ("host", "keys", "proto")):
+                out.append(_source_from_result(validate_key_document(item, None)))
+            else:
+                out.append(_source_from_mapping(item))
+        elif isinstance(item, (list, tuple)) and depth == 0:
+            for x in item:
+                add(x, 1)
+        else:
+            raise TypeError("keys must be a key document (dict), a KeysResult, a {key id: public key} dict, "
+                            f"or a list of those; got {type(item).__name__}")
+
+    add(keys, 0)
+    return tuple(out)
+
+
+def find_key(sources: Tuple[_Source, ...], host: str, kid: str, issued: str) -> Key:
+    """SPEC 10.1 step 5. Raises DatumeshError with a key code."""
+    for s in sources:
+        if s.host is None or s.host == host:
+            if not s.result.ok:
+                fail(s.result.code, f"keys for {host}: {s.result.detail}", "$.computed_by")
+            key = s.by_id.get(kid)
+            if key is None:
+                fail("E_KEY_UNKNOWN", f"{host} publishes no key {kid}", "$.computed_by")
+            if not key.usable_at(issued):
+                fail("E_KEY_NOT_VALID", "issued is outside the key's validity window", "$.issued")
+            return key
+    fail("E_KEY_UNAVAILABLE", f"no keys supplied for host {host}", "$.computed_by")