datumesh 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datumesh
-Version: 0.2.1
-Summary: Verify Datumesh receipts (spec-0.2.1): 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.1), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.1/SPEC.md
-Keywords: datumesh,spec-0.2.1,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.1/SPEC.md) (revision `spec-0.2.1`) 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.1 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.1 → 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.1/SPEC.md) (revision `spec-0.2.1`) 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.1 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.1 → datumesh-0.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datumesh"
-version = "0.2.1"
-description = "Verify Datumesh receipts (spec-0.2.1): 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.1", "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.1)" = "https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.1/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.1 → 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.1``
+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.1"
+__version__ = "0.3.0"
 #: The specification revision this package conforms to.
-SPEC_VERSION = "spec-0.2.1"
+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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → datumesh-0.3.0/src/datumesh.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datumesh
-Version: 0.2.1
-Summary: Verify Datumesh receipts (spec-0.2.1): 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.1), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.2.1/SPEC.md
-Keywords: datumesh,spec-0.2.1,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.1/SPEC.md) (revision `spec-0.2.1`) 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.1 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.1 → datumesh-0.3.0}/src/datumesh.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ 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.1 → 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.1")
-        self.assertEqual(datumesh.__version__, "0.2.1")
-        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]
 

{datumesh-0.2.1 → datumesh-0.3.0}/tests/test_conformance.py

@@ -8,7 +8,7 @@ import subprocess
 import sys
 import unittest
 
-from util import ROOT, blob_of, env_keys, expected_output, load_vectors, runner, vectors_of
+from util import ROOT, blob_of, env_keys, expected_output, load_vectors, recompute_of, runner, vectors_of
 
 import datumesh
 
@@ -16,9 +16,9 @@ import datumesh
 class ConformanceTest(unittest.TestCase):
     def test_vector_count(self) -> None:
         counts = collections.Counter(v["kind"] for v in load_vectors())
-        self.assertEqual(sum(counts.values()), 339, counts)
+        self.assertEqual(sum(counts.values()), 365, counts)
         self.assertEqual(counts["unit"], 13, counts)
-        self.assertEqual(counts["envelope"], 50, counts)
+        self.assertEqual(counts["envelope"], 60, counts)
         # every vector's id is its path, and every kind is one the runner knows
         for v in load_vectors():
             self.assertIn(v["kind"], ("jcs", "scalar", "cell", "ref", "function", "uri", "keyid", "keys",
@@ -67,20 +67,20 @@ class ConformanceTest(unittest.TestCase):
     def test_receipts_through_verify(self) -> None:
         for v in vectors_of("receipt"):
             with self.subTest(v["id"]):
-                res = datumesh.verify(v["input"], env_keys(v["keys"]), v.get("recompute"), blob_of(v))
+                rc = recompute_of(v)
+                res = datumesh.verify(v["input"], env_keys(v["keys"]), rc, blob_of(v))
                 if v["valid"]:
                     self.assertTrue(res.ok, res)
-                    self.assertEqual(res.code, "OK")
+                    # SPEC 10.1 step 7.6 (spec-0.3.0): E_EVAL_UNAVAILABLE is reported with success, at $.value
+                    self.assertEqual(res.code, v.get("code", "OK"))
                     self.assertEqual(res.level, v["level"])
                     self.assertEqual(res.hash, v["sha256"])
                     self.assertEqual(res.blob_checked, "blob_hex" in v)
                     self.assertEqual(res.key, json.loads(v["input"])["computed_by"])
-                    self.assertIsNone(res.path)
+                    self.assertEqual(res.path, "$.value" if "code" in v else None)
                     # bytes input and parsed input give the same result
-                    self.assertEqual(datumesh.verify(v["input"].encode(), env_keys(v["keys"]), v.get("recompute"),
-                                                     blob_of(v)), res)
-                    self.assertEqual(datumesh.verify(json.loads(v["input"]), env_keys(v["keys"]), v.get("recompute"),
-                                                     blob_of(v)), res)
+                    self.assertEqual(datumesh.verify(v["input"].encode(), env_keys(v["keys"]), rc, blob_of(v)), res)
+                    self.assertEqual(datumesh.verify(json.loads(v["input"]), env_keys(v["keys"]), rc, blob_of(v)), res)
                     self.assertEqual(datumesh.receipt_hash(v["input"]), v["sha256"])
                     self.assertEqual(datumesh.receipt_payload(v["input"]).decode(), v["canonical"])
                 else:

{datumesh-0.2.1 → datumesh-0.3.0}/tests/test_envelope.py

@@ -60,7 +60,7 @@ class EnvelopeVectorTest(unittest.TestCase):
                 else:
                     self.assertEqual((res.ok, res.code), (False, v["error"]))
                 n += 1
-        self.assertEqual(n, 50)
+        self.assertEqual(n, 60)
 
     def test_valid_bodies_with_wrong_status(self) -> None:
         total = 0
@@ -245,7 +245,7 @@ class EnvelopeRulesTest(unittest.TestCase):
 
 
 class RequestBindingTest(unittest.TestCase):
-    """SPEC 5.5 step 5: the receipt answers the request (same cell id; same asof when one was asked for)."""
+    """SPEC 5.5 step 5: the receipt answers the request (same cell id; an asof at or before the one asked for)."""
 
     def code(self, body: dict, request: dict, status: int = 200) -> str:
         return check_envelope(status, json.dumps(body), KEYS, request).code
@@ -254,7 +254,8 @@ class RequestBindingTest(unittest.TestCase):
         self.assertEqual(self.code(ok(), {"cell_id": CELL_ID, "asof": R["asof"]}), "OK")
         self.assertEqual(self.code(ok(), {"cell_id": CELL_ID}), "OK")  # no asof asked: the mesh's now
         self.assertEqual(self.code(ok(), {"cell_id": "0" * 64}), "E_ENVELOPE")
-        self.assertEqual(self.code(ok(), {"cell_id": CELL_ID, "asof": "2024-03-17T09:00:00.000000Z"}), "E_ENVELOPE")
+        # ok (SPEC 5.5 step 5, spec-0.3.0): like stale, the receipt's asof is at or before the requested asof.
+        self.assertEqual(self.code(ok(), {"cell_id": CELL_ID, "asof": "2024-03-17T09:00:00.000000Z"}), "OK")
         self.assertEqual(self.code(stale(), {"cell_id": "0" * 64}), "E_ENVELOPE")
         # stale (SPEC 5.5 step 5, spec 240a830): the receipt's asof is at or before the requested asof.
         self.assertEqual(self.code(stale(), {"cell_id": CELL_ID, "asof": "2024-03-17T09:00:00.000000Z"}), "OK")
@@ -262,11 +263,11 @@ class RequestBindingTest(unittest.TestCase):
         self.assertEqual(self.code(stale(), {"cell_id": CELL_ID}), "OK")
         self.assertEqual(self.code(stale(), {"cell_id": CELL_ID, "asof": "2024-03-16T08:59:59.999999Z"}), "E_ENVELOPE")
         self.assertEqual(self.code(stale(), {"cell_id": CELL_ID, "asof": "2020-01-01T00:00:00.000000Z"}), "E_ENVELOPE")
-        # ok still needs the same asof
+        # ok: a receipt asof after the requested one fails
         self.assertEqual(self.code(ok(), {"cell_id": CELL_ID, "asof": "2024-03-16T08:59:59.999999Z"}), "E_ENVELOPE")
         res = check_envelope(200, json.dumps(ok()), KEYS, {"cell_id": "0" * 64})
         self.assertEqual(res.path, "$.receipt.cell")
-        res = check_envelope(200, json.dumps(ok()), KEYS, {"cell_id": CELL_ID, "asof": "2024-03-17T09:00:00.000000Z"})
+        res = check_envelope(200, json.dumps(ok()), KEYS, {"cell_id": CELL_ID, "asof": "2024-03-16T08:59:59.999999Z"})
         self.assertEqual(res.path, "$.receipt.asof")
 
     def test_order(self) -> None:

{datumesh-0.2.1 → datumesh-0.3.0}/tests/test_keys.py

@@ -13,7 +13,7 @@ import unittest
 from typing import Any, Dict, List, Optional
 from unittest import mock
 
-from util import FIXTURES, env_keys, vectors_of
+from util import FIXTURES, env_keys, recompute_of, vectors_of
 
 import datumesh
 from datumesh import KeysResult, keys_from_response, verify
@@ -178,7 +178,7 @@ class VerifyKeyHandlingTest(unittest.TestCase):
         with self.assertRaises(TypeError):
             verify(5, DOC)  # type: ignore[arg-type]
         with self.assertRaises(TypeError):
-            verify(VECTOR["input"], DOC, {"descriptor": None})
+            verify(VECTOR["input"], DOC, {"descriptor": None, "value": None})
 
 
 # ---------------------------------------------------------------- fetch_keys
@@ -305,7 +305,7 @@ class FetchKeysTest(unittest.TestCase):
                 mock.patch.object(socket, "socket", side_effect=AssertionError("socket opened")), \
                 mock.patch.object(socket, "create_connection", side_effect=AssertionError("socket opened")):
             for v in vectors_of("receipt"):
-                datumesh.verify(v["input"], env_keys(v["keys"]), v.get("recompute"))
+                datumesh.verify(v["input"], env_keys(v["keys"]), recompute_of(v))
             datumesh.verify(VECTOR["input"], [])
 
 

datumesh-0.3.0/tests/test_spec_0_3_0.py

@@ -0,0 +1,274 @@
+"""The changes of spec-0.3.0, each tested through the API (the vectors are run by test_conformance).
+
+- D17 revised (8.2, 10.1 step 7.5): an input receipt's asof is at or before the receipt's.
+- D31 revised (5.5 step 5): for ok as for stale, the receipt's asof is at or before the requested one.
+- E_EVAL_UNAVAILABLE (10.1 step 7.6, 10.2, 11): success at level signed, with the code at $.value.
+- 10.1 step 7.1 / 11 (DEF-17): a null descriptor is a descriptor offered (E_FN_HASH_MISMATCH).
+- 9.3 / 11 (DEF-16(b)): only the integer 200 is a retrieved key document.
+- 3.7: the 128-character media type limit is on the whole media type.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import unittest
+from typing import Any, Dict
+
+from nacl.signing import SigningKey
+
+from util import ROOT, env_keys, recompute_of, runner, vectors_of
+
+import datumesh
+from datumesh import DatumeshError, canonicalize, check_envelope, keys_from_response, verify
+
+
+def vector(vid: str) -> Dict[str, Any]:
+    v: Dict[str, Any] = json.loads((ROOT / "spec" / "vectors" / f"{vid}.json").read_text(encoding="utf-8"))
+    return v
+
+
+EARLIER = vector("receipt/computed-inputs-earlier-asof")
+EVAL_STORED = vector("receipt/eval-unavailable-stored")
+EVAL_COMPUTED = vector("receipt/eval-unavailable-computed")
+EVAL_BLOB = vector("receipt/eval-unavailable-blob-checked")
+STORED = vector("receipt/stored-number")
+LINEAGE = vector("receipt/computed-with-lineage")
+
+
+def resign(v: Dict[str, Any], **changes: Any) -> str:
+    """The vector's receipt with ``changes``, signed again with the vector's keypair."""
+    r = json.loads(v["input"])
+    r.update(changes)
+    payload = datumesh.jcs({k: x for k, x in r.items() if k != "sig"})
+    r["sig"] = SigningKey(bytes.fromhex(v["keypair"]["seed"])).sign(payload).signature.hex()
+    return json.dumps(r)
+
+
+def without_value(v: Dict[str, Any]) -> Dict[str, Any]:
+    rc = copy.deepcopy(v["recompute"])
+    rc.pop("value", None)
+    return rc
+
+
+class InputAsofTest(unittest.TestCase):
+    """D17 revised: an input's asof at or before the receipt's; only a later one is E_TIME_ORDER."""
+
+    def test_boundaries(self) -> None:
+        keys = env_keys(EARLIER["keys"])
+        rc = EARLIER["recompute"]
+        latest_input_asof = max(json.loads(t)["asof"] for t in rc["inputs"].values())
+        self.assertEqual(latest_input_asof, "2024-03-16T09:00:00.000000Z")
+        # the vector as it is: inputs at earlier asofs
+        self.assertEqual(verify(EARLIER["input"], keys, rc).level, "recomputed")
+        # the receipt's asof equal to the latest input asof
+        res = verify(resign(EARLIER, asof=latest_input_asof), keys, rc)
+        self.assertEqual((res.ok, res.code, res.level), (True, "OK", "recomputed"))
+        # one microsecond earlier: that input is later than the receipt
+        res = verify(resign(EARLIER, asof="2024-03-16T08:59:59.999999Z"), keys, rc)
+        self.assertEqual((res.ok, res.code, res.path), (False, "E_TIME_ORDER", "$.inputs[0]"))
+        # still reported when evaluation is unavailable: 7.5 comes before 7.6
+        res = verify(resign(EARLIER, asof="2024-03-16T08:59:59.999999Z"), keys, without_value(EARLIER))
+        self.assertEqual((res.ok, res.code), (False, "E_TIME_ORDER"))
+
+    def test_tx_is_still_the_latest_input_tx(self) -> None:
+        keys = env_keys(EARLIER["keys"])
+        res = verify(resign(EARLIER, tx="2024-03-15T16:00:00.000000Z"), keys, EARLIER["recompute"])
+        self.assertEqual((res.code, res.path), ("E_TIME_ORDER", "$.tx"))
+
+
+class EvalUnavailableTest(unittest.TestCase):
+    """E_EVAL_UNAVAILABLE: recompute without value, after 7.1-7.5 pass."""
+
+    def test_error_code_list(self) -> None:
+        codes = datumesh.ERROR_CODES
+        self.assertIn("E_EVAL_UNAVAILABLE", codes)
+        i = codes.index("E_EVAL_UNAVAILABLE")
+        self.assertEqual((codes[i - 1], codes[i + 1]), ("E_VALUE_MISMATCH", "E_BLOB_MISMATCH"))
+        self.assertEqual(DatumeshError("E_EVAL_UNAVAILABLE").code, "E_EVAL_UNAVAILABLE")
+
+    def test_stored_and_computed(self) -> None:
+        for v in (EVAL_STORED, EVAL_COMPUTED):
+            with self.subTest(v["id"]):
+                res = verify(v["input"], env_keys(v["keys"]), v["recompute"])
+                self.assertEqual(
+                    (res.ok, res.code, res.level, res.hash, res.key, res.path, res.blob_checked),
+                    (True, "E_EVAL_UNAVAILABLE", "signed", v["sha256"], json.loads(v["input"])["computed_by"],
+                     "$.value", False))
+                self.assertIn("not evaluated", res.detail)
+
+    def test_existing_vectors_without_value(self) -> None:
+        # Every valid recomputed vector, with value removed, is signed with E_EVAL_UNAVAILABLE.
+        for v in vectors_of("receipt", True):
+            if v.get("level") != "recomputed":
+                continue
+            with self.subTest(v["id"]):
+                blob = bytes.fromhex(v["blob_hex"]) if "blob_hex" in v else None
+                res = verify(v["input"], env_keys(v["keys"]), without_value(v), blob)
+                self.assertEqual((res.ok, res.code, res.level, res.path, res.blob_checked),
+                                 (True, "E_EVAL_UNAVAILABLE", "signed", "$.value", blob is not None))
+
+    def test_failures_before_7_6_are_reported_instead(self) -> None:
+        keys = env_keys(LINEAGE["keys"])
+        rc = without_value(LINEAGE)
+        self.assertEqual(verify(LINEAGE["input"], keys, {}).code, "E_FN_UNAVAILABLE")
+        self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, inputs={})).code, "E_INPUT_UNAVAILABLE")
+        self.assertEqual(verify(LINEAGE["input"], keys, dict(rc, descriptor=None)).code, "E_FN_HASH_MISMATCH")
+        # a receipt that is not signature-valid fails as before
+        r = json.loads(LINEAGE["input"])
+        r["summary"] = "changed"
+        res = verify(r, keys, rc)
+        self.assertEqual((res.ok, res.code, res.level), (False, "E_SIGNATURE", None))
+
+    def test_blob_after_eval_unavailable(self) -> None:
+        keys = env_keys(EVAL_BLOB["keys"])
+        content = bytes.fromhex(EVAL_BLOB["blob_hex"])
+        rc = EVAL_BLOB["recompute"]
+        res = verify(EVAL_BLOB["input"], keys, rc, content)
+        self.assertEqual((res.ok, res.code, res.level, res.path, res.blob_checked),
+                         (True, "E_EVAL_UNAVAILABLE", "signed", "$.value", True))
+        # 7.7 fails: an ordinary failure replaces the code
+        res = verify(EVAL_BLOB["input"], keys, rc, content + b"x")
+        self.assertEqual((res.ok, res.code, res.level, res.blob_checked), (False, "E_BLOB_MISMATCH", None, False))
+        # content for a value that is not a blob: E_SCHEMA, also after E_EVAL_UNAVAILABLE
+        res = verify(EVAL_STORED["input"], env_keys(EVAL_STORED["keys"]), EVAL_STORED["recompute"], b"x")
+        self.assertEqual((res.ok, res.code), (False, "E_SCHEMA"))
+        # no content: the code, and blob_checked false
+        res = verify(EVAL_BLOB["input"], keys, rc)
+        self.assertEqual((res.ok, res.code, res.blob_checked), (True, "E_EVAL_UNAVAILABLE", False))
+
+    def test_value_none_is_a_caller_error(self) -> None:
+        # Only an absent value means unavailable; a value that is not {"type", "value"} is a TypeError.
+        for bad in (None, "1.0892", {"type": "number"}):
+            with self.subTest(bad=bad), self.assertRaises(TypeError):
+                verify(EVAL_STORED["input"], env_keys(EVAL_STORED["keys"]), dict(EVAL_STORED["recompute"], value=bad))
+
+    def test_runner_reports_code_only_with_it(self) -> None:
+        run = runner().run_vector
+        for v in vectors_of("receipt"):
+            with self.subTest(v["id"]):
+                out = run(v)
+                if v["valid"] and v.get("code"):
+                    self.assertEqual(out.get("code"), "E_EVAL_UNAVAILABLE")
+                    self.assertEqual(out["level"], "signed")
+                else:
+                    self.assertNotIn("code", out)
+
+    def test_envelope_error_may_carry_it(self) -> None:
+        body = json.dumps({"outcome": "error", "error": "E_EVAL_UNAVAILABLE"})
+        res = check_envelope(503, body, [], {"cell_id": "0" * 64})
+        self.assertEqual((res.ok, res.outcome), (True, "error"))
+        body = json.dumps({"outcome": "bad_request", "error": "E_EVAL_UNAVAILABLE"})
+        self.assertEqual(check_envelope(400, body, [], {"cell_id": "0" * 64}).code, "E_ENVELOPE")
+
+
+class DescriptorOfferedTest(unittest.TestCase):
+    """10.1 step 7.1: what is obtained is a JSON value; only obtaining nothing is E_FN_UNAVAILABLE."""
+
+    def test_forms(self) -> None:
+        keys = env_keys(STORED["keys"])
+        rc = STORED["recompute"]
+        desc = rc["descriptor"]
+        cases = [
+            ({"inputs": {}, "value": rc["value"]}, "E_FN_UNAVAILABLE", "$.cell.fn_hash"),  # nothing obtained
+            (dict(rc, descriptor=None), "E_FN_HASH_MISMATCH", "$.cell.fn_hash"),  # JSON null
+            (dict(rc, descriptor=0), "E_FN_HASH_MISMATCH", "$.cell.fn_hash"),
+            (dict(rc, descriptor=[]), "E_FN_HASH_MISMATCH", "$.cell.fn_hash"),
+            (dict(rc, descriptor="null"), "E_FN_HASH_MISMATCH", "$.cell.fn_hash"),  # text of null
+            # a JSON string value holding the descriptor's text, given as JSON text: a string
+            (dict(rc, descriptor=json.dumps(json.dumps(desc))), "E_FN_HASH_MISMATCH", "$.cell.fn_hash"),
+            # bytes or text are parsed strictly first, with the parse codes
+            (dict(rc, descriptor=b"{"), "E_PARSE_JSON", None),
+            (dict(rc, descriptor='{"a":1,"a":1}'), "E_PARSE_DUPLICATE_KEY", None),
+        ]
+        for recompute, code, path in cases:
+            with self.subTest(recompute=str(recompute.get("descriptor", "<absent>"))[:30]):
+                res = verify(STORED["input"], keys, recompute)
+                self.assertEqual(res.code, code)
+                if path is not None:
+                    self.assertEqual(res.path, path)
+        # the descriptor as a parsed value, as text, and as bytes
+        for d in (desc, json.dumps(desc), json.dumps(desc).encode()):
+            self.assertEqual(verify(STORED["input"], keys, dict(rc, descriptor=d)).level, "recomputed")
+
+    def test_vectors(self) -> None:
+        for vid in ("invalid/receipt-descriptor-null", "invalid/receipt-descriptor-text"):
+            v = vector(vid)
+            with self.subTest(vid):
+                self.assertEqual(verify(v["input"], env_keys(v["keys"]), recompute_of(v)).code, "E_FN_HASH_MISMATCH")
+
+
+class OkAsofTest(unittest.TestCase):
+    """D31 revised: ok binds to an asof at or before the requested one, like stale."""
+
+    def test_ok_and_stale(self) -> None:
+        v = vector("envelope/served-ok")
+        s = vector("envelope/served-stale")
+        req = v["request"]
+        receipt = json.loads(v["input"])["receipt"]
+        keys = env_keys(v["keys"])
+        self.assertLess(receipt["asof"], req["asof"])
+        for body in (v["input"], s["input"]):
+            env = json.loads(body)
+            for asof, ok in ((req["asof"], True), (receipt["asof"], True), (None, True),
+                             ("2024-03-16T08:59:59.999999Z", False), ("2020-01-01T00:00:00.000000Z", False)):
+                request = {"cell_id": req["cell_id"]} if asof is None else {"cell_id": req["cell_id"], "asof": asof}
+                with self.subTest(outcome=env["outcome"], asof=asof):
+                    res = check_envelope(200, body, keys, request)
+                    self.assertEqual(res.ok, ok, res)
+                    if not ok:
+                        self.assertEqual((res.code, res.path), ("E_ENVELOPE", "$.receipt.asof"))
+
+    def test_age_seconds_still_tells_them_apart(self) -> None:
+        v = vector("envelope/served-ok")
+        env = json.loads(v["input"])
+        keys = env_keys(v["keys"])
+        self.assertEqual(check_envelope(200, json.dumps(dict(env, age_seconds=5)), keys, v["request"]).code,
+                         "E_ENVELOPE")
+        self.assertEqual(check_envelope(200, json.dumps(dict(env, outcome="stale")), keys, v["request"]).code,
+                         "E_ENVELOPE")
+
+
+class KeyStatusTest(unittest.TestCase):
+    """9.3 / 11: only the integer 200 is a retrieved document."""
+
+    def test_status_forms(self) -> None:
+        body = json.loads(next(v for v in vectors_of("keys", True))["env"]["https"]["body"])
+        host = body["host"]
+        text = json.dumps(body)
+        self.assertTrue(keys_from_response(host, 200, text).ok)
+        for status in ("200", 200.0, True, None, b"200", [200]):
+            with self.subTest(status=status):
+                res = keys_from_response(host, status, text)  # type: ignore[arg-type]
+                self.assertEqual((res.ok, res.code), (False, "E_KEY_UNAVAILABLE"))
+
+
+class MediaTypeLengthTest(unittest.TestCase):
+    """3.7: 128 characters for the whole media type; no per-name limit."""
+
+    def test_limits(self) -> None:
+        h = hashlib.sha256(b"").hexdigest()
+
+        def code(media: str) -> Any:
+            try:
+                canonicalize({"type": "blob", "value": f"{h}:0:{media}"}, "scalar")
+                return None
+            except DatumeshError as e:
+                return e.code
+
+        self.assertIsNone(code("a/" + "b" * 126))
+        self.assertEqual(code("a/" + "b" * 127), "E_CANON_BLOB")
+        self.assertIsNone(code("a" * 126 + "/b"))
+        self.assertEqual(code("a" * 127 + "/b"), "E_CANON_BLOB")
+        self.assertIsNone(code("a" * 63 + "/" + "b" * 64))
+
+
+class VersionTest(unittest.TestCase):
+    def test_versions(self) -> None:
+        self.assertEqual(datumesh.SPEC_VERSION, "spec-0.3.0")
+        self.assertEqual(datumesh.__version__, "0.3.0")
+
+
+if __name__ == "__main__":
+    unittest.main()

{datumesh-0.2.1 → datumesh-0.3.0}/tests/test_unicode.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import json
-import pathlib
 import sys
 import unicodedata
 import unittest