datumesh 0.2.0__tar.gz → 0.3.0__tar.gz

{datumesh-0.2.0/src/datumesh.egg-info → datumesh-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datumesh
-Version: 0.2.0
-Summary: Verify Datumesh receipts (spec-0.2.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents.
+Version: 0.3.0
+Summary: Verify Datumesh receipts (spec-0.3.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents.
 Author: Datumesh
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://datumesh.com
 Project-URL: Repository, https://github.com/datumesh-com/datumesh-verify-py
-Project-URL: Specification (spec-0.2.0), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md
-Keywords: datumesh,spec-0.2.0,receipt,verification,ed25519,rfc8785,jcs,canonical-json
+Project-URL: Specification (spec-0.3.0), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md
+Keywords: datumesh,spec-0.3.0,receipt,verification,ed25519,rfc8785,jcs,canonical-json
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -27,11 +27,11 @@ Dynamic: license-file
 
 # datumesh
 
-Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md) (revision `spec-0.2.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
+Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md) (revision `spec-0.3.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
 
 ```sh
 pip install datumesh
-git clone --depth 1 --branch spec-0.2.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
+git clone --depth 1 --branch spec-0.3.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
 ```
 
 ```python
@@ -49,8 +49,8 @@ Website: https://datumesh.com · Specification: https://github.com/datumesh-com/
 
 ## API
 
-- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor, the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
-- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; a stale receipt may answer an earlier `asof`). The envelope itself is unsigned: `stale`, `superseded_by` and a `verified` label remain the mesh's claims.
+- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. One code comes with success: when you pass `recompute` without a `value` because you could not evaluate the function, the other recomputation checks still run, and if they pass the result is ok at level `signed` with `code` `"E_EVAL_UNAVAILABLE"` (SPEC 10.1 step 7.6). It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor (leave it out if you have none; `None` is a JSON null and fails the hash check), the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
+- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; the receipt's `asof` must be at or before it, for `ok` and `stale` alike). The envelope itself is unsigned: `stale`, `superseded_by`, a `verified` label and the currency `ok` asserts remain the mesh's claims.
 - `resolved_unit(descriptor, cell) -> str | None`: the unit of a cell's value, such as `USD/EUR` (SPEC 7.1, units.md).
 - `keys_from_response(host, status, body) -> KeysResult`: interprets a response for `https://<host>/.well-known/datumesh.json` (SPEC 9.3).
 - `fetch_keys(host, timeout=10.0) -> KeysResult`: the only function that uses the network. One GET, TLS verified, redirects not followed.

{datumesh-0.2.0 → datumesh-0.3.0}/README.md

@@ -1,10 +1,10 @@
 # datumesh
 
-Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md) (revision `spec-0.2.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
+Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md) (revision `spec-0.3.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
 
 ```sh
 pip install datumesh
-git clone --depth 1 --branch spec-0.2.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
+git clone --depth 1 --branch spec-0.3.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
 ```
 
 ```python
@@ -22,8 +22,8 @@ Website: https://datumesh.com · Specification: https://github.com/datumesh-com/
 
 ## API
 
-- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor, the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
-- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; a stale receipt may answer an earlier `asof`). The envelope itself is unsigned: `stale`, `superseded_by` and a `verified` label remain the mesh's claims.
+- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. One code comes with success: when you pass `recompute` without a `value` because you could not evaluate the function, the other recomputation checks still run, and if they pass the result is ok at level `signed` with `code` `"E_EVAL_UNAVAILABLE"` (SPEC 10.1 step 7.6). It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor (leave it out if you have none; `None` is a JSON null and fails the hash check), the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
+- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; the receipt's `asof` must be at or before it, for `ok` and `stale` alike). The envelope itself is unsigned: `stale`, `superseded_by`, a `verified` label and the currency `ok` asserts remain the mesh's claims.
 - `resolved_unit(descriptor, cell) -> str | None`: the unit of a cell's value, such as `USD/EUR` (SPEC 7.1, units.md).
 - `keys_from_response(host, status, body) -> KeysResult`: interprets a response for `https://<host>/.well-known/datumesh.json` (SPEC 9.3).
 - `fetch_keys(host, timeout=10.0) -> KeysResult`: the only function that uses the network. One GET, TLS verified, redirects not followed.

{datumesh-0.2.0 → datumesh-0.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datumesh"
-version = "0.2.0"
-description = "Verify Datumesh receipts (spec-0.2.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents."
+version = "0.3.0"
+description = "Verify Datumesh receipts (spec-0.3.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "Datumesh" }]
-keywords = ["datumesh", "spec-0.2.0", "receipt", "verification", "ed25519", "rfc8785", "jcs", "canonical-json"]
+keywords = ["datumesh", "spec-0.3.0", "receipt", "verification", "ed25519", "rfc8785", "jcs", "canonical-json"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -30,7 +30,7 @@ dependencies = ["pynacl>=1.5.0"]
 [project.urls]
 Homepage = "https://datumesh.com"
 Repository = "https://github.com/datumesh-com/datumesh-verify-py"
-"Specification (spec-0.2.0)" = "https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md"
+"Specification (spec-0.3.0)" = "https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/__init__.py

@@ -1,6 +1,6 @@
 """datumesh: verify Datumesh receipts (signed answers for addressable data cells).
 
-Implements the Datumesh protocol specification, revision ``spec-0.2.0``
+Implements the Datumesh protocol specification, revision ``spec-0.3.0``
 (https://github.com/datumesh-com/datumesh-spec): RFC 8785 canonical JSON,
 SHA-256 hashes, Ed25519 receipt signatures, blob content, units, cell URIs,
 response envelopes and key documents. Only :func:`fetch_keys` touches the network.
@@ -19,9 +19,9 @@ 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.2.0"
+__version__ = "0.3.0"
 #: The specification revision this package conforms to.
-SPEC_VERSION = "spec-0.2.0"
+SPEC_VERSION = "spec-0.3.0"
 #: Every literal unit listed in units.md (index units, ``index:<period>=<value>``, are a pattern and not listed).
 UNITS = tuple(sorted(_units.LITERALS))
 #: The currency codes of units.md 2.1.

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_envelope.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import hashlib
 import re
 from dataclasses import dataclass
-from typing import Any, Dict, Mapping, Optional, Tuple, Union
+from typing import Any, Dict, Mapping, NoReturn, Optional, Tuple, Union
 
 from . import _lexical as lx
 from . import _units
@@ -59,7 +59,7 @@ class EnvelopeResult:
     path: Optional[str]
 
 
-def _bad(detail: str, path: str) -> None:
+def _bad(detail: str, path: str) -> NoReturn:
     fail("E_ENVELOPE", detail, path)
 
 
@@ -183,8 +183,8 @@ def check_envelope(status: Any, body: Union[str, bytes, bytearray, memoryview],
     of 5.5 (``E_ENVELOPE``); the status matches the outcome (``E_ENVELOPE``); an
     embedded receipt is verified through step 6 of 10.1 with ``keys`` (the forms
     :func:`verify` takes) and keeps that procedure's codes; the receipt answers
-    the request: same cell id, and when an ``asof`` was requested the same ``asof``
-    for ``ok`` or one at or before it for ``stale`` (``E_ENVELOPE``); then ``trust`` is checked against the receipt (``primary``
+    the request: same cell id, and when an ``asof`` was requested a receipt
+    ``asof`` at or before it, for ``ok`` and ``stale`` alike (``E_ENVELOPE``); then ``trust`` is checked against the receipt (``primary``
     exactly when the signer's host is the namespace's host and there are no
     inputs) and ``superseded_by`` must not be the receipt's own hash (``E_ENVELOPE``).
 
@@ -214,14 +214,11 @@ def check_envelope(status: Any, body: Union[str, bytes, bytearray, memoryview],
                 raise DatumeshError(e.code, e.detail, path) from None
             if hashlib.sha256(jcs_bytes(r["cell"])).hexdigest() != want_cell:
                 _bad("the receipt's cell is not the cell requested", "$.receipt.cell")
-            # ok: the same asof; stale: at or before it (instants compare as strings, SPEC 3.3).
-            if want_asof is not None:
-                if outcome == "stale" and not r["asof"] <= want_asof:
-                    _bad(f"a stale receipt answers as of {r['asof']}, after the requested {want_asof}",
-                         "$.receipt.asof")
-                if outcome == "ok" and r["asof"] != want_asof:
-                    _bad(f"the receipt answers as of {r['asof']}, the request asked for {want_asof}",
-                         "$.receipt.asof")
+            # ok and stale alike: the receipt's asof at or before the requested one (D31, spec-0.3.0;
+            # canonical instants compare as strings, SPEC 3.3). No requested asof: any.
+            if want_asof is not None and r["asof"] > want_asof:
+                _bad(f"the {outcome} receipt answers as of {r['asof']}, after the requested {want_asof}",
+                     "$.receipt.asof")
             trust = env["trust"]
             if (trust == "primary") != _is_primary(r):
                 _bad("trust is primary exactly when the signer's host is the namespace's host and there are no "

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_errors.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 from typing import NoReturn, Optional
 
-#: Every error code SPEC.md 10.2 defines, in the order of its table.
+#: Every error code SPEC.md 10.2 defines, in the order of its table. One, ``E_EVAL_UNAVAILABLE``,
+#: is not a failure: :func:`verify` reports it with success (SPEC 10.1 step 7.6).
 ERROR_CODES: tuple[str, ...] = (
     "E_PARSE_JSON",
     "E_PARSE_DUPLICATE_KEY",
@@ -45,6 +46,7 @@ ERROR_CODES: tuple[str, ...] = (
     "E_INPUT_INVALID",
     "E_INPUT_UNDECLARED",
     "E_VALUE_MISMATCH",
+    "E_EVAL_UNAVAILABLE",
     "E_BLOB_MISMATCH",
     "E_ENVELOPE",
 )

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_json.py

@@ -4,12 +4,31 @@ from __future__ import annotations
 
 import json
 import math
+import re
 from typing import Any, Dict, List, Tuple, Union
 
 from ._errors import DatumeshError, fail
 
 JSONText = Union[str, bytes, bytearray, memoryview]
 
+#: SPEC 6.1: at most 64 levels of ``[`` and ``{`` open at once, counted outside strings.
+MAX_DEPTH = 64
+# A string (possibly unterminated) or a bracket; brackets inside strings are skipped with the string.
+_DEPTH_TOKEN = re.compile(r'"(?:[^"\\]|\\.)*"?|[\[\]{}]', re.S)
+
+
+def _too_deep(text: str) -> bool:
+    depth = 0
+    for m in _DEPTH_TOKEN.finditer(text):
+        c = m.group()
+        if c in "[{":
+            depth += 1
+            if depth > MAX_DEPTH:
+                return True
+        elif c in "]}":
+            depth -= 1
+    return False
+
 
 class _Duplicate(Exception):
     def __init__(self, key: str) -> None:
@@ -49,7 +68,11 @@ def parse_json(data: JSONText, path: str = "$") -> Any:
     ``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.
+    double range, invalid UTF-8, nesting deeper than 64) raises E_PARSE_JSON.
+    Numbers become floats. Failures are reported in the order of SPEC 6.1: byte
+    order mark, invalid UTF-8, nesting, then the first in text order of a syntax
+    error, NaN/Infinity, an overflowing number or a duplicate member (detected when
+    its object closes), and lone surrogates last.
     """
     if isinstance(data, (bytes, bytearray, memoryview)):
         raw = bytes(data)
@@ -65,6 +88,8 @@ def parse_json(data: JSONText, path: str = "$") -> Any:
             fail("E_PARSE_JSON", "byte order mark", path)
     else:
         raise TypeError(f"JSON text must be str or bytes, not {type(data).__name__}")
+    if _too_deep(text):
+        fail("E_PARSE_JSON", f"nesting deeper than {MAX_DEPTH} levels", path)
     try:
         value = json.loads(
             text,
@@ -102,10 +127,15 @@ def number_texts(data: JSONText) -> Dict[str, str]:
 
 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)]
+    string keys, no lone surrogates, finite numbers within the double range, and at most
+    64 levels of arrays and objects (as its text would be, SPEC 6.1)."""
+    stack: List[Tuple[Any, str, int]] = [(value, path, 0)]
     while stack:
-        v, p = stack.pop()
+        v, p, depth = stack.pop()
+        if isinstance(v, (dict, list)):
+            depth += 1
+            if depth > MAX_DEPTH:
+                fail("E_PARSE_JSON", f"nesting deeper than {MAX_DEPTH} levels", p)
         if v is None or isinstance(v, bool):
             continue
         if isinstance(v, str):
@@ -125,10 +155,10 @@ def check_json_value(value: Any, path: str = "$") -> None:
                     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}"))
+                stack.append((item, f"{p}.{k}", depth))
         elif isinstance(v, list):
             for i, item in enumerate(v):
-                stack.append((item, f"{p}[{i}]"))
+                stack.append((item, f"{p}[{i}]", depth))
         else:
             fail("E_PARSE_JSON", f"{type(v).__name__} is not a JSON value", p)
 

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_keys.py

@@ -123,18 +123,20 @@ def keys_from_response(host: str, status: Optional[int], body: Union[str, bytes,
     ``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.
+    ``host``, or any 200 for a host that is not a DNS name, 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}")
+    try:
+        lx.check_dns_name(host, "host")
+    except DatumeshError as e:
+        # SPEC 9.3: a response offered for a host that is not a DNS name cannot satisfy 9.2.
+        return _doc_error(host, f"a document for a host that is not a DNS name cannot satisfy 9.2: {e.detail}")
     if body is None:
         return _doc_error(host, "200 response without a body")
     if not isinstance(body, (str, bytes, bytearray, memoryview)):

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_lexical.py

@@ -9,7 +9,7 @@ licences); characters, NFC, then length (strings, SPEC 3.5).
 from __future__ import annotations
 
 import re
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
 
 from ._errors import fail
 from ._unicode import is_assigned, is_nfc
@@ -152,7 +152,7 @@ def check_blob(s: str, path: Optional[str]) -> None:
              f"at most {LIMIT_MEDIA_TYPE} characters>", path)
 
 
-def blob_parts(s: str) -> tuple:
+def blob_parts(s: str) -> Tuple[str, int, str]:
     """(sha256 hex, length, media type) of a blob value already checked with :func:`check_blob`."""
     digest, length, media = s.split(":", 2)
     return digest, int(length), media

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_unitlist.py

@@ -1,6 +1,6 @@
-"""The unit list of spec/units.md (spec-0.2.0). Generated by tools/gen_units.py; do not edit."""
+"""The unit list of spec/units.md (spec-0.3.0). Generated by tools/gen_units.py; do not edit."""
 
-SOURCE_SHA256 = "6c9f21e0a219525c8616d2fce08136a747d38627ff183d9d513be029d6e85738"
+SOURCE_SHA256 = "cf165af78779a95a21e1ad35e235e490f2dd125a562ede7652e97b9a5d4bb5ab"
 
 #: ```units-currency``` blocks, in file order (ISO 4217 List One without XXX, then withdrawn codes).
 CURRENCY = (

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_uri.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 from . import _lexical as lx
 from ._errors import fail
+from ._json import sort_key
 from ._model import SLICE, validate_ref
 
 SCHEME = "cell://"
@@ -48,10 +49,17 @@ def _encode(text: str) -> str:
 
 
 def _declared_types(signature: Any) -> Dict[str, str]:
-    args = signature.get("args") if isinstance(signature, dict) else None
-    if not isinstance(args, dict) or not all(
-            isinstance(a, dict) and isinstance(a.get("type"), str) for a in args.values()):
-        raise TypeError('signature must be {"args": {<name>: {"type": <type name>, ...}}, ...}')
+    """SPEC 5.4 step 5: read the argument types; an unreadable signature is E_SCHEMA."""
+    if not isinstance(signature, dict):
+        fail("E_SCHEMA", "the signature is an object", "signature")
+    args = signature.get("args")
+    if not isinstance(args, dict):
+        fail("E_SCHEMA", "the signature has an args object", "signature" if "args" not in signature
+             else "signature.args")
+    for name in sorted(args, key=sort_key):
+        a = args[name]
+        if not isinstance(a, dict) or not isinstance(a.get("type"), str):
+            fail("E_SCHEMA", "an argument declaration is an object with a string type", f"signature.args.{name}")
     return {name: a["type"] for name, a in args.items()}
 
 
@@ -61,12 +69,11 @@ def parse_uri(uri: str, signature: Dict[str, Any]) -> Dict[str, Any]:
     ``signature`` is the ``signature`` member of the function's descriptor; it
     supplies each argument's type. As SPEC 5.4 says, it is taken as given (it comes
     from a descriptor already checked under section 7): only its argument types are
-    read, and a signature from which they cannot be read is a TypeError. Checks run
-    in the order of SPEC 5.4 and the first failure is raised as DatumeshError.
+    read, in step 5, and a signature from which they cannot be read is E_SCHEMA.
+    Checks run in the order of SPEC 5.4 and the first failure is raised as DatumeshError.
     """
     if not isinstance(uri, str):
         raise TypeError(f"uri must be a str, not {type(uri).__name__}")
-    declared = _declared_types(signature)
 
     # 1. Outer grammar.
     if not uri.startswith(SCHEME) or "#" in uri:
@@ -120,7 +127,8 @@ def parse_uri(uri: str, signature: Dict[str, Any]) -> Dict[str, Any]:
     if len(params) > lx.LIMIT_ARGS:
         fail("E_CANON_LIMIT", f"more than {lx.LIMIT_ARGS} arguments", "uri.query")
 
-    # 5. Arguments against the signature: unknown, then missing.
+    # 5. The signature (read, not checked: SPEC 5.4), then the arguments against it: unknown, then missing.
+    declared = _declared_types(signature)
     present = {name for name, _ in params}
     for name, _ in params:
         if name not in declared:

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh/_verify.py

@@ -23,12 +23,16 @@ class VerifyResult:
     """The outcome of :func:`verify`.
 
     ``ok``: the receipt verified. ``code``: ``"OK"`` or the first failing
-    error code. ``level``: ``"signed"`` (steps 1-6) or ``"recomputed"`` (step 7
+    error code; on success it is ``"E_EVAL_UNAVAILABLE"`` instead of ``"OK"``
+    when recomputation was asked for without an evaluated ``value`` (SPEC 10.1
+    step 7.6: steps 7.1-7.5 passed, nothing was compared, the level stays
+    ``signed``). ``level``: ``"signed"`` (steps 1-6) or ``"recomputed"`` (step 7
     too) when ok, else None. ``hash``: the receipt hash once the receipt is in
     canonical form (steps 1-3 passed), else None. ``key``: the ``computed_by``
     value when ok. ``detail``: human-readable text. ``path``: where the
-    failure is (a JSON path) or None. ``blob_checked``: True only when blob
-    content was supplied and step 7.7 ran and passed (the level is unchanged).
+    failure is (a JSON path), ``"$.value"`` with ``E_EVAL_UNAVAILABLE``, or None.
+    ``blob_checked``: True only when blob content was supplied and step 7.7 ran
+    and passed (the level and the code are unchanged).
     """
 
     ok: bool
@@ -76,13 +80,14 @@ def _signed(receipt: Any, sources: Tuple[_Source, ...]) -> Tuple[Dict[str, Any],
     return r, h
 
 
-def _recompute(r: Dict[str, Any], recompute: Mapping[str, Any], sources: Tuple[_Source, ...]) -> None:
-    """Step 7. Raises DatumeshError."""
-    # 7.1 descriptor
-    desc = recompute.get("descriptor")
-    if desc is None:
+def _recompute(r: Dict[str, Any], recompute: Mapping[str, Any], sources: Tuple[_Source, ...]) -> bool:
+    """Step 7.1-7.6. Raises DatumeshError. Returns False when 7.1-7.5 passed and there is no
+    evaluated value to compare (E_EVAL_UNAVAILABLE), True when 7.6 passed."""
+    # 7.1 descriptor: only an absent member is "none obtained". Whatever is obtained is a JSON
+    # value (None is JSON null); text or bytes are parsed strictly first.
+    if "descriptor" not in recompute:
         fail("E_FN_UNAVAILABLE", "no descriptor supplied for cell.fn_hash", "$.cell.fn_hash")
-    desc = load(desc, "descriptor")
+    desc = load(recompute["descriptor"], "descriptor")
     if hashlib.sha256(jcs_bytes(desc)).hexdigest() != r["cell"]["fn_hash"]:
         fail("E_FN_HASH_MISMATCH", "the descriptor does not hash to cell.fn_hash", "$.cell.fn_hash")
     _model.validate_function(desc, "descriptor")
@@ -124,16 +129,20 @@ def _recompute(r: Dict[str, Any], recompute: Mapping[str, Any], sources: Tuple[_
         fqn = f"{sub['cell']['ns']}/{sub['cell']['fn']}"
         if fqn not in declared_inputs:
             fail("E_INPUT_UNDECLARED", f"input {h} is a cell of {fqn}, which the descriptor does not declare", p)
-        if sub["asof"] != r["asof"]:
-            fail("E_TIME_ORDER", f"input {h} has asof {sub['asof']}, not {r['asof']}", p)
+        # at or before the receipt's asof (D17, spec-0.3.0); canonical instants compare as strings (3.3)
+        if sub["asof"] > r["asof"]:
+            fail("E_TIME_ORDER", f"input {h} has asof {sub['asof']}, after the receipt's {r['asof']}", p)
         if latest_tx is None or sub["tx"] > latest_tx:
             latest_tx = sub["tx"]
     if latest_tx is not None and r["tx"] != latest_tx:
         fail("E_TIME_ORDER", f"a computed cell's tx is the latest input tx ({latest_tx})", "$.tx")
-    # 7.6 value
+    # 7.6 value; without one, evaluation is unavailable (not a failure)
+    if "value" not in recompute:
+        return False
     v = dict(recompute["value"])
     if not _model.same_scalar(v, {"type": r["type"], "value": r["value"]}):
         fail("E_VALUE_MISMATCH", "the recomputed value differs from the receipt's", "$.value")
+    return True
 
 
 def check_blob_content(r: Dict[str, Any], content: bytes) -> None:
@@ -149,10 +158,12 @@ def _check_recompute_arg(recompute: Any) -> None:
     if recompute is None:
         return
     if not isinstance(recompute, Mapping):
-        raise TypeError("recompute must be a mapping with 'value' and optional 'descriptor' and 'inputs'")
-    v = recompute.get("value")
-    if not isinstance(v, Mapping) or "type" not in v or "value" not in v:
-        raise TypeError("recompute['value'] must be {'type': ..., 'value': ...}: the evaluated result")
+        raise TypeError("recompute must be a mapping with optional 'descriptor', 'inputs' and 'value'")
+    if "value" in recompute:
+        v = recompute["value"]
+        if not isinstance(v, Mapping) or "type" not in v or "value" not in v:
+            raise TypeError("recompute['value'] must be {'type': ..., 'value': ...}: the evaluated result "
+                            "(leave it out when the function could not be evaluated)")
     inputs = recompute.get("inputs")
     if inputs is not None and not isinstance(inputs, Mapping):
         raise TypeError("recompute['inputs'] must be a mapping of receipt hash to receipt JSON text")
@@ -168,11 +179,21 @@ def verify(receipt: Any, keys: Any, recompute: Optional[Mapping[str, Any]] = Non
     validity windows), or a list of those; the first source that covers the
     ``computed_by`` host is used. ``recompute`` (optional) enables step 7:
     ``{"descriptor": ..., "inputs": {hash: receipt text}, "value": {"type", "value"}}``.
+    ``descriptor`` is the descriptor obtained for ``cell.fn_hash``: a parsed JSON
+    value, or JSON text/bytes (parsed strictly); leave it out when none was
+    obtained (E_FN_UNAVAILABLE). Any other value, ``None`` (JSON null)
+    included, is a descriptor offered and must hash to ``cell.fn_hash``
+    (E_FN_HASH_MISMATCH). ``value`` is what evaluating the function gave; leave
+    it out when the function could not be evaluated: once steps 7.1-7.5 pass,
+    the result is then ok at level ``signed`` with ``code`` ``"E_EVAL_UNAVAILABLE"``
+    and ``path`` ``"$.value"`` (SPEC 10.1 step 7.6).
     ``blob`` (optional): the content bytes of a blob value. Step 7.7 then runs
     last (after step 7 if ``recompute`` is given, else directly after step 6):
     the receipt's ``type`` must be ``blob`` (E_SCHEMA otherwise) and the content
     must have the blob's length and SHA-256 (E_BLOB_MISMATCH). The level stays
-    ``signed`` or ``recomputed``; ``blob_checked`` reports that 7.7 passed.
+    ``signed`` or ``recomputed``; ``blob_checked`` reports that 7.7 passed. 7.7
+    also runs after E_EVAL_UNAVAILABLE: if it passes the code is kept, if it
+    fails its failure is reported instead.
 
     Never raises for an invalid receipt or bad key material: the outcome is in
     the returned :class:`VerifyResult`. Raises TypeError only for arguments of
@@ -188,9 +209,14 @@ def verify(receipt: Any, keys: Any, recompute: Optional[Mapping[str, Any]] = Non
     try:
         r, h = _signed(receipt, sources)
         level, detail = "signed", "signature-valid"
+        code, path = "OK", None
         if recompute is not None:
-            _recompute(r, recompute, sources)
-            level, detail = "recomputed", "fully verified by recomputation"
+            if _recompute(r, recompute, sources):
+                level, detail = "recomputed", "fully verified by recomputation"
+            else:
+                code, path = "E_EVAL_UNAVAILABLE", "$.value"
+                detail = ("signature-valid; recomputation checks 7.1-7.5 passed, but the function was not "
+                          "evaluated (no value supplied)")
         checked = False
         if blob is not None:
             if r["type"] != "blob":
@@ -198,7 +224,7 @@ def verify(receipt: Any, keys: Any, recompute: Optional[Mapping[str, Any]] = Non
             check_blob_content(r, bytes(blob))
             detail += "; blob content matches"
             checked = True
-        return VerifyResult(True, "OK", level, h, r["computed_by"], detail, None, checked)
+        return VerifyResult(True, code, level, h, r["computed_by"], detail, path, checked)
     except DatumeshError as e:
         h = h or getattr(e, "receipt_hash", None)
         return VerifyResult(False, e.code, None, h, None, e.detail, e.path)

{datumesh-0.2.0 → datumesh-0.3.0/src/datumesh.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datumesh
-Version: 0.2.0
-Summary: Verify Datumesh receipts (spec-0.2.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents.
+Version: 0.3.0
+Summary: Verify Datumesh receipts (spec-0.3.0): RFC 8785 canonical JSON, Ed25519 signatures, blobs, units, cell URIs, response envelopes, key documents.
 Author: Datumesh
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://datumesh.com
 Project-URL: Repository, https://github.com/datumesh-com/datumesh-verify-py
-Project-URL: Specification (spec-0.2.0), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md
-Keywords: datumesh,spec-0.2.0,receipt,verification,ed25519,rfc8785,jcs,canonical-json
+Project-URL: Specification (spec-0.3.0), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md
+Keywords: datumesh,spec-0.3.0,receipt,verification,ed25519,rfc8785,jcs,canonical-json
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -27,11 +27,11 @@ Dynamic: license-file
 
 # datumesh
 
-Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.0/SPEC.md) (revision `spec-0.2.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
+Verify [Datumesh](https://datumesh.com) receipts in Python. A receipt is a signed answer for one addressable data cell; this library checks its canonical form (RFC 8785 JSON) and its Ed25519 signature against the signer's published keys, and optionally the recomputation checks (function descriptor, input receipts, and a value you computed) and the content of a blob value, as the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec/blob/spec-0.3.0/SPEC.md) (revision `spec-0.3.0`) defines. It also checks a mesh's response envelope and resolves the unit of a cell's value.
 
 ```sh
 pip install datumesh
-git clone --depth 1 --branch spec-0.2.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
+git clone --depth 1 --branch spec-0.3.0 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
 ```
 
 ```python
@@ -49,8 +49,8 @@ Website: https://datumesh.com · Specification: https://github.com/datumesh-com/
 
 ## API
 
-- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor, the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
-- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; a stale receipt may answer an earlier `asof`). The envelope itself is unsigned: `stale`, `superseded_by` and a `verified` label remain the mesh's claims.
+- `verify(receipt, keys, recompute=None, blob=None) -> VerifyResult`: runs the verification procedure of SPEC 10.1. Never raises for an invalid receipt or bad key material; the result has `ok`, `code` (`"OK"` or an error code), `level` (`"signed"` or `"recomputed"`), `hash`, `key`, `detail` and `path`. One code comes with success: when you pass `recompute` without a `value` because you could not evaluate the function, the other recomputation checks still run, and if they pass the result is ok at level `signed` with `code` `"E_EVAL_UNAVAILABLE"` (SPEC 10.1 step 7.6). It uses no network: keys are an argument (a key document, a `KeysResult`, a `{key id: public key}` mapping, or a list of these). `recompute` takes the descriptor (leave it out if you have none; `None` is a JSON null and fails the hash check), the input receipts and the value you computed (the library does not evaluate functions); `blob` takes the content bytes of a blob value, whose length and SHA-256 are then checked (step 7.7, reported as `blob_checked`).
+- `check_envelope(status, body, keys, request) -> EnvelopeResult`: checks a mesh's response to `https://<mesh>/cell/...` (SPEC 5.5), verifies the receipt inside it, and checks that it answers your request (`request` is `{"cell_id": ..., "asof": ...}`, `asof` only if you asked for one; the receipt's `asof` must be at or before it, for `ok` and `stale` alike). The envelope itself is unsigned: `stale`, `superseded_by`, a `verified` label and the currency `ok` asserts remain the mesh's claims.
 - `resolved_unit(descriptor, cell) -> str | None`: the unit of a cell's value, such as `USD/EUR` (SPEC 7.1, units.md).
 - `keys_from_response(host, status, body) -> KeysResult`: interprets a response for `https://<host>/.well-known/datumesh.json` (SPEC 9.3).
 - `fetch_keys(host, timeout=10.0) -> KeysResult`: the only function that uses the network. One GET, TLS verified, redirects not followed.

{datumesh-0.2.0 → datumesh-0.3.0}/src/datumesh.egg-info/SOURCES.txt

@@ -27,6 +27,8 @@ tests/test_conformance.py
 tests/test_envelope.py
 tests/test_jcs.py
 tests/test_keys.py
+tests/test_spec_0_2_1.py
+tests/test_spec_0_3_0.py
 tests/test_unicode.py
 tests/test_units.py
 tests/test_uri.py

{datumesh-0.2.0 → datumesh-0.3.0}/tests/test_api.py

@@ -18,11 +18,11 @@ LINEAGE = next(v for v in vectors_of("receipt", True) if v["id"] == "receipt/com
 
 class ApiTest(unittest.TestCase):
     def test_constants(self) -> None:
-        self.assertEqual(datumesh.SPEC_VERSION, "spec-0.2.0")
-        self.assertEqual(datumesh.__version__, "0.2.0")
-        self.assertEqual(len(datumesh.ERROR_CODES), 41)
-        self.assertEqual(len(set(datumesh.ERROR_CODES)), 41)
-        for code in ("E_CANON_UNIT", "E_CANON_BLOB", "E_BLOB_MISMATCH", "E_ENVELOPE"):
+        self.assertEqual(datumesh.SPEC_VERSION, "spec-0.3.0")
+        self.assertEqual(datumesh.__version__, "0.3.0")
+        self.assertEqual(len(datumesh.ERROR_CODES), 42)
+        self.assertEqual(len(set(datumesh.ERROR_CODES)), 42)
+        for code in ("E_CANON_UNIT", "E_CANON_BLOB", "E_BLOB_MISMATCH", "E_ENVELOPE", "E_EVAL_UNAVAILABLE"):
             self.assertIn(code, datumesh.ERROR_CODES)
         for name in ("resolved_unit", "check_envelope", "EnvelopeResult", "UNITS"):
             self.assertIn(name, datumesh.__all__)
@@ -88,9 +88,12 @@ class ApiTest(unittest.TestCase):
         # descriptor as JSON text
         rc2 = dict(rc, descriptor=json.dumps(rc["descriptor"]))
         self.assertEqual(verify(LINEAGE["input"], keys, rc2).level, "recomputed")
-        # descriptor None or absent
-        self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, descriptor=None)).code, "E_FN_UNAVAILABLE")
+        # descriptor absent (E_FN_UNAVAILABLE), or None: a JSON null offered (E_FN_HASH_MISMATCH, spec-0.3.0)
+        self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, descriptor=None)).code, "E_FN_HASH_MISMATCH")
         self.assertEqual(verify(LINEAGE["input"], keys, {"value": rc["value"]}).code, "E_FN_UNAVAILABLE")
+        # value absent: evaluation unavailable (spec-0.3.0), success at level signed
+        res = verify(LINEAGE["input"], keys, {"descriptor": rc["descriptor"], "inputs": rc["inputs"]})
+        self.assertEqual((res.ok, res.code, res.level), (True, "E_EVAL_UNAVAILABLE", "signed"))
         # inputs missing, given as parsed objects, or tampered
         self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, inputs={})).code, "E_INPUT_UNAVAILABLE")
         parsed = {h: json.loads(t) for h, t in rc["inputs"].items()}
@@ -98,7 +101,7 @@ class ApiTest(unittest.TestCase):
         # boolean vs string values are different
         self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, value={"type": "number", "value": "108.920"})).code,
                          "E_VALUE_MISMATCH")
-        for bad in ([], {"descriptor": rc["descriptor"]}, {"value": "108.92"}, dict(rc, inputs=[])):
+        for bad in ([], dict(rc, value=None), {"value": "108.92"}, dict(rc, inputs=[])):
             with self.subTest(bad=str(bad)[:40]), self.assertRaises(TypeError):
                 verify(LINEAGE["input"], keys, bad)  # type: ignore[arg-type]