datumesh 0.4.2__tar.gz → 0.4.3__tar.gz

{datumesh-0.4.2 → datumesh-0.4.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datumesh
-Version: 0.4.2
-Summary: Verify Datumesh receipts (spec-0.4.2): RFC 8785 canonical JSON, Ed25519 signatures, slice-as-lineage, blobs, units, cell URIs, response envelopes (pending jobs, pins, slice pages, batches), key documents, mesh documents.
+Version: 0.4.3
+Summary: Verify Datumesh receipts (spec-0.4.3): RFC 8785 canonical JSON, Ed25519 signatures, slice-as-lineage, blobs, units, cell URIs, response envelopes (pending jobs, pins, slice pages, batches), key documents with declarations, mesh documents, licence inheritance and entitlement.
 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.4.2), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.4.2/SPEC.md
-Keywords: datumesh,spec-0.4.2,receipt,verification,ed25519,rfc8785,jcs,canonical-json
+Project-URL: Specification (spec-0.4.3), https://github.com/datumesh-com/datumesh-spec/blob/spec-0.4.3/SPEC.md
+Keywords: datumesh,spec-0.4.3,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 slice manifests, 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.4.2/SPEC.md) (revision `spec-0.4.2`) defines. It also checks a mesh's response envelope (including `pending` jobs), resolves the unit of a cell's value, and checks a host's mesh document for cross-mesh use.
+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 slice manifests, 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.4.3/SPEC.md) (revision `spec-0.4.3`) defines. It also checks a mesh's response envelope (including `pending` jobs), resolves the unit of a cell's value, checks a host's mesh document for cross-mesh use, and, separately from verification, checks a computed receipt's licence against the inheritance rule (the entitlement check).
 
 ```sh
 pip install datumesh
-git clone --depth 1 --branch spec-0.4.2 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
+git clone --depth 1 --branch spec-0.4.3 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
 ```
 
 ```python
@@ -52,16 +52,21 @@ Website: https://datumesh.com · Specification: https://github.com/datumesh-com/
 - `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`. Two codes come with success, at level `signed` (SPEC 10.1 step 7.6): `"E_EVAL_UNAVAILABLE"` when you pass `recompute` without a `value` because you could not evaluate the function (the other recomputation checks still run first), and `"E_INPUT_SUPERSEDED"` when your value differs but the evaluation's `lineage` shows that an input was replaced by a later version (the receipt is historical, not wrong). 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 (slice members included), the manifests of slice entries (`slice:<slice id>:<members hash>`), the value you computed and optionally the evaluation's lineage (the library does not evaluate functions, formulas included); `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). A `not_covered` envelope may carry a formula evaluation `fault` (exposed as `fault`). The envelope itself is unsigned: `stale`, `superseded_by`, a `verified` label and the currency `ok` asserts remain the mesh's claims.
 - Jobs (spec-0.4.1): a `pending` envelope (HTTP 202) carries `job`, `estimate_seconds` and `poll` (exposed on the result) and echoes your request, which must match. When you poll, pass the original request plus `"job": <the job id>`: the answer is checked against the original cell and `asof`, never the job URL, and only then may it be `bad_request` with `E_JOB_UNKNOWN` (ask again).
-- Pins, trust and the mesh asked (spec-0.4.2): a request description may carry `fn_hash` (you pinned the function: `parse_uri`/`format_uri` handle `fn_hash=`) and `mesh` (the host you asked). Answers to a pinned request must echo the pin; with `mesh`, `computed` (this mesh evaluated and signed it) is checked against the signer, and `poll` against the host. Without `mesh`, comparing them with the host you asked is your own check.
-- Slice pages (spec-0.4.2): `check_envelope` with `{"slice_id", "asof"?, "fn_hash"?, "mesh"?, "after"?}` checks a page of the slice endpoint: every member's receipt, its membership, `asof`, trust and key order (`result.members`, `result.next`).
-- `check_batch(status, body, keys, requests) -> BatchResult` (spec-0.4.2): the answer to `POST /cells`, checked as a whole, then item by item against each request (`result.items`); a refusal of the whole batch gives `result.outcome`.
+- Pins, trust and the mesh asked (spec-0.4.3): a request description may carry `fn_hash` (you pinned the function: `parse_uri`/`format_uri` handle `fn_hash=`) and `mesh` (the host you asked). Answers to a pinned request must echo the pin; with `mesh`, `computed` (this mesh evaluated and signed it) is checked against the signer, and `poll` against the host. Without `mesh`, comparing them with the host you asked is your own check.
+- Slice pages (spec-0.4.3): `check_envelope` with `{"slice_id", "asof"?, "fn_hash"?, "mesh"?, "after"?}` checks a page of the slice endpoint: every member's receipt, its membership, `asof`, trust and key order (`result.members`, `result.next`).
+- `check_batch(status, body, keys, requests) -> BatchResult` (spec-0.4.3): the answer to `POST /cells`, checked as a whole, then item by item against each request (`result.items`); a refusal of the whole batch gives `result.outcome`.
 - `resolve_mesh(host, keys, mesh) -> MeshResult`: checks a host's key document and mesh document (`/.well-known/datumesh-mesh.json`, SPEC 9.6) together, given each response as a `(status, body)` pair; the result has `bindings` and the known `endpoints`, or `E_KEY_UNAVAILABLE`, `E_KEY_DOC` or `E_MESH_DOC`. It uses no network, and verification never needs it.
+- Licences (spec-0.4.3): `inherit_licence(licences, declarations, fn, issued, mesh_licence) -> LicenceResult` applies the inheritance rule of SPEC 8.5 (the strictest input licence wins; a restricted licence only where the function's publisher declared it, open at `issued`) and gives `licence` (None for a refusal, which a mesh answers `unlicensed`) and `reason`. `check_entitlement(receipt, licences, keys) -> EntitlementResult` (SPEC 10.3) says whether a verified computed receipt's licence is the one the rule gives, with one of eight reasons; `keys` is the key document of the publisher's host (the host of `cell.ns`), and another host's is a `ValueError`. `input_licences(receipt, receipts, manifests=None, keys=None)` collects the input licences through the receipts and slice manifests you have. None of this is verification: a receipt that is not entitled is still signature-valid.
+- Key documents may carry `declarations` (spec-0.4.3, SPEC 9.2): `KeysResult.declarations` maps each declared function name to its `Declaration` entries (`licence`, `valid_from`, `valid_to`). A malformed one rejects the whole document (`E_KEY_DOC`); otherwise they change nothing in verification.
+- `E_FOREIGN_UNAVAILABLE` (spec-0.4.3): an `error` envelope at HTTP 502 saying another mesh could not be reached, with `detail` (exposed as `error_detail`): one of `FOREIGN_DETAILS` (`offline`, `network`, `dns`, `tls`, `timeout`, `refused`). `is_unrooted(namespace)` tells names under `.invalid` (SPEC 2.5), whose receipts verify only against a key document supplied out of band.
 - `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.
 - `canonicalize(obj, kind=None) -> bytes`, `cell_hash`, `function_hash`, `receipt_hash`, `receipt_payload`, `jcs`: validation, RFC 8785 canonical bytes and SHA-256 hashes. Kinds `"slice"` and `"manifest"`, with `slice_id`, `members_hash` and `slice_entry`, cover slice objects and manifests (SPEC 4.4, 15.13).
 - `parse_uri(uri, signature)`, `format_uri(ref)`, `uri_to_https(uri, mesh)`: cell URIs (SPEC 5).
-- `DatumeshError` (with `.code` and `.path`), `ERROR_CODES`, `SUCCESS_CODES`, `FAULT_CODES`, `SPEC_VERSION`, `UNITS`, `CURRENCIES`.
+- `DatumeshError` (with `.code` and `.path`), `ERROR_CODES`, `SUCCESS_CODES`, `FAULT_CODES`, `FOREIGN_DETAILS`, `REASONS`, `SPEC_VERSION`, `UNITS`, `CURRENCIES`.
+
+Changes are listed in [CHANGELOG.md](CHANGELOG.md).
 
 Requires Python 3.10 or later and PyNaCl. String rules use Unicode 15.1 tables shipped with the package, so results do not depend on the Python version's own Unicode database; the unit list is copied from the specification's `units.md`. Choosing which publishers to trust is up to you: a valid signature only means the key holder made the statement.
 

{datumesh-0.4.2 → datumesh-0.4.3}/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 slice manifests, 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.4.2/SPEC.md) (revision `spec-0.4.2`) defines. It also checks a mesh's response envelope (including `pending` jobs), resolves the unit of a cell's value, and checks a host's mesh document for cross-mesh use.
+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 slice manifests, 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.4.3/SPEC.md) (revision `spec-0.4.3`) defines. It also checks a mesh's response envelope (including `pending` jobs), resolves the unit of a cell's value, checks a host's mesh document for cross-mesh use, and, separately from verification, checks a computed receipt's licence against the inheritance rule (the entitlement check).
 
 ```sh
 pip install datumesh
-git clone --depth 1 --branch spec-0.4.2 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
+git clone --depth 1 --branch spec-0.4.3 https://github.com/datumesh-com/datumesh-spec && cd datumesh-spec
 ```
 
 ```python
@@ -25,16 +25,21 @@ Website: https://datumesh.com · Specification: https://github.com/datumesh-com/
 - `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`. Two codes come with success, at level `signed` (SPEC 10.1 step 7.6): `"E_EVAL_UNAVAILABLE"` when you pass `recompute` without a `value` because you could not evaluate the function (the other recomputation checks still run first), and `"E_INPUT_SUPERSEDED"` when your value differs but the evaluation's `lineage` shows that an input was replaced by a later version (the receipt is historical, not wrong). 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 (slice members included), the manifests of slice entries (`slice:<slice id>:<members hash>`), the value you computed and optionally the evaluation's lineage (the library does not evaluate functions, formulas included); `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). A `not_covered` envelope may carry a formula evaluation `fault` (exposed as `fault`). The envelope itself is unsigned: `stale`, `superseded_by`, a `verified` label and the currency `ok` asserts remain the mesh's claims.
 - Jobs (spec-0.4.1): a `pending` envelope (HTTP 202) carries `job`, `estimate_seconds` and `poll` (exposed on the result) and echoes your request, which must match. When you poll, pass the original request plus `"job": <the job id>`: the answer is checked against the original cell and `asof`, never the job URL, and only then may it be `bad_request` with `E_JOB_UNKNOWN` (ask again).
-- Pins, trust and the mesh asked (spec-0.4.2): a request description may carry `fn_hash` (you pinned the function: `parse_uri`/`format_uri` handle `fn_hash=`) and `mesh` (the host you asked). Answers to a pinned request must echo the pin; with `mesh`, `computed` (this mesh evaluated and signed it) is checked against the signer, and `poll` against the host. Without `mesh`, comparing them with the host you asked is your own check.
-- Slice pages (spec-0.4.2): `check_envelope` with `{"slice_id", "asof"?, "fn_hash"?, "mesh"?, "after"?}` checks a page of the slice endpoint: every member's receipt, its membership, `asof`, trust and key order (`result.members`, `result.next`).
-- `check_batch(status, body, keys, requests) -> BatchResult` (spec-0.4.2): the answer to `POST /cells`, checked as a whole, then item by item against each request (`result.items`); a refusal of the whole batch gives `result.outcome`.
+- Pins, trust and the mesh asked (spec-0.4.3): a request description may carry `fn_hash` (you pinned the function: `parse_uri`/`format_uri` handle `fn_hash=`) and `mesh` (the host you asked). Answers to a pinned request must echo the pin; with `mesh`, `computed` (this mesh evaluated and signed it) is checked against the signer, and `poll` against the host. Without `mesh`, comparing them with the host you asked is your own check.
+- Slice pages (spec-0.4.3): `check_envelope` with `{"slice_id", "asof"?, "fn_hash"?, "mesh"?, "after"?}` checks a page of the slice endpoint: every member's receipt, its membership, `asof`, trust and key order (`result.members`, `result.next`).
+- `check_batch(status, body, keys, requests) -> BatchResult` (spec-0.4.3): the answer to `POST /cells`, checked as a whole, then item by item against each request (`result.items`); a refusal of the whole batch gives `result.outcome`.
 - `resolve_mesh(host, keys, mesh) -> MeshResult`: checks a host's key document and mesh document (`/.well-known/datumesh-mesh.json`, SPEC 9.6) together, given each response as a `(status, body)` pair; the result has `bindings` and the known `endpoints`, or `E_KEY_UNAVAILABLE`, `E_KEY_DOC` or `E_MESH_DOC`. It uses no network, and verification never needs it.
+- Licences (spec-0.4.3): `inherit_licence(licences, declarations, fn, issued, mesh_licence) -> LicenceResult` applies the inheritance rule of SPEC 8.5 (the strictest input licence wins; a restricted licence only where the function's publisher declared it, open at `issued`) and gives `licence` (None for a refusal, which a mesh answers `unlicensed`) and `reason`. `check_entitlement(receipt, licences, keys) -> EntitlementResult` (SPEC 10.3) says whether a verified computed receipt's licence is the one the rule gives, with one of eight reasons; `keys` is the key document of the publisher's host (the host of `cell.ns`), and another host's is a `ValueError`. `input_licences(receipt, receipts, manifests=None, keys=None)` collects the input licences through the receipts and slice manifests you have. None of this is verification: a receipt that is not entitled is still signature-valid.
+- Key documents may carry `declarations` (spec-0.4.3, SPEC 9.2): `KeysResult.declarations` maps each declared function name to its `Declaration` entries (`licence`, `valid_from`, `valid_to`). A malformed one rejects the whole document (`E_KEY_DOC`); otherwise they change nothing in verification.
+- `E_FOREIGN_UNAVAILABLE` (spec-0.4.3): an `error` envelope at HTTP 502 saying another mesh could not be reached, with `detail` (exposed as `error_detail`): one of `FOREIGN_DETAILS` (`offline`, `network`, `dns`, `tls`, `timeout`, `refused`). `is_unrooted(namespace)` tells names under `.invalid` (SPEC 2.5), whose receipts verify only against a key document supplied out of band.
 - `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.
 - `canonicalize(obj, kind=None) -> bytes`, `cell_hash`, `function_hash`, `receipt_hash`, `receipt_payload`, `jcs`: validation, RFC 8785 canonical bytes and SHA-256 hashes. Kinds `"slice"` and `"manifest"`, with `slice_id`, `members_hash` and `slice_entry`, cover slice objects and manifests (SPEC 4.4, 15.13).
 - `parse_uri(uri, signature)`, `format_uri(ref)`, `uri_to_https(uri, mesh)`: cell URIs (SPEC 5).
-- `DatumeshError` (with `.code` and `.path`), `ERROR_CODES`, `SUCCESS_CODES`, `FAULT_CODES`, `SPEC_VERSION`, `UNITS`, `CURRENCIES`.
+- `DatumeshError` (with `.code` and `.path`), `ERROR_CODES`, `SUCCESS_CODES`, `FAULT_CODES`, `FOREIGN_DETAILS`, `REASONS`, `SPEC_VERSION`, `UNITS`, `CURRENCIES`.
+
+Changes are listed in [CHANGELOG.md](CHANGELOG.md).
 
 Requires Python 3.10 or later and PyNaCl. String rules use Unicode 15.1 tables shipped with the package, so results do not depend on the Python version's own Unicode database; the unit list is copied from the specification's `units.md`. Choosing which publishers to trust is up to you: a valid signature only means the key holder made the statement.
 

{datumesh-0.4.2 → datumesh-0.4.3}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datumesh"
-version = "0.4.2"
-description = "Verify Datumesh receipts (spec-0.4.2): RFC 8785 canonical JSON, Ed25519 signatures, slice-as-lineage, blobs, units, cell URIs, response envelopes (pending jobs, pins, slice pages, batches), key documents, mesh documents."
+version = "0.4.3"
+description = "Verify Datumesh receipts (spec-0.4.3): RFC 8785 canonical JSON, Ed25519 signatures, slice-as-lineage, blobs, units, cell URIs, response envelopes (pending jobs, pins, slice pages, batches), key documents with declarations, mesh documents, licence inheritance and entitlement."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "Datumesh" }]
-keywords = ["datumesh", "spec-0.4.2", "receipt", "verification", "ed25519", "rfc8785", "jcs", "canonical-json"]
+keywords = ["datumesh", "spec-0.4.3", "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.4.2)" = "https://github.com/datumesh-com/datumesh-spec/blob/spec-0.4.2/SPEC.md"
+"Specification (spec-0.4.3)" = "https://github.com/datumesh-com/datumesh-spec/blob/spec-0.4.3/SPEC.md"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{datumesh-0.4.2 → datumesh-0.4.3}/src/datumesh/__init__.py

@@ -1,12 +1,15 @@
 """datumesh: verify Datumesh receipts (signed answers for addressable data cells).
 
-Implements the Datumesh protocol specification, revision ``spec-0.4.2``
+Implements the Datumesh protocol specification, revision ``spec-0.4.3``
 (https://github.com/datumesh-com/datumesh-spec), as a verifier library: RFC 8785
 canonical JSON, SHA-256 hashes, Ed25519 receipt signatures, blob content, units,
 cell URIs (pins included), response envelopes, slice pages and batches, key
 documents, and slice-as-lineage (slice entries,
 slice objects and manifests), and, separately from verification, cross-mesh
-resolution of a host's mesh document (:func:`resolve_mesh`). It evaluates no
+resolution of a host's mesh document (:func:`resolve_mesh`), and since spec-0.4.3 the
+publisher's ``declarations`` in key documents, licence inheritance (:func:`inherit_licence`), the
+licence entitlement check (:func:`check_entitlement`) and unrooted namespaces
+(:func:`is_unrooted`). It evaluates no
 function, formulas included: the evaluated value comes from the caller. Only
 :func:`fetch_keys` touches the network.
 """
@@ -18,16 +21,18 @@ from typing import Any, Dict, Optional
 
 from . import _model, _units
 from ._envelope import TRUST, BatchResult, EnvelopeResult, MemberResult, check_batch, check_envelope
-from ._errors import ERROR_CODES, FAULT_CODES, SUCCESS_CODES, DatumeshError, fail
+from ._errors import ERROR_CODES, FAULT_CODES, FOREIGN_DETAILS, SUCCESS_CODES, DatumeshError, fail
 from ._json import jcs_bytes
-from ._keys import Key, KeysResult, fetch_keys, key_id, keys_from_response
+from ._keys import Declaration, Key, KeysResult, fetch_keys, key_id, keys_from_response
+from ._licence import (ATTRIBUTION, ENTITLED_REASONS, PUBLIC_DOMAIN, REASONS, SHARE_ALIKE, EntitlementResult,
+                       LicenceResult, check_entitlement, inherit_licence, input_licences, is_unrooted, licence_tier)
 from ._mesh import MESH_ENDPOINTS, MESH_WELL_KNOWN_PATH, MeshResult, resolve_mesh
 from ._uri import format_uri, parse_uri, uri_to_https
 from ._verify import VerifyResult, load, payload_bytes, verify
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 #: The specification revision this package conforms to.
-SPEC_VERSION = "spec-0.4.2"
+SPEC_VERSION = "spec-0.4.3"
 #: 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.
@@ -39,6 +44,20 @@ KINDS = ("scalar", "cell", "ref", "function", "receipt", "slice", "manifest")
 
 __all__ = [
     "SPEC_VERSION",
+    "ATTRIBUTION",
+    "Declaration",
+    "ENTITLED_REASONS",
+    "EntitlementResult",
+    "FOREIGN_DETAILS",
+    "LicenceResult",
+    "PUBLIC_DOMAIN",
+    "REASONS",
+    "SHARE_ALIKE",
+    "check_entitlement",
+    "inherit_licence",
+    "input_licences",
+    "is_unrooted",
+    "licence_tier",
     "BatchResult",
     "MemberResult",
     "TRUST",

{datumesh-0.4.2 → datumesh-0.4.3}/src/datumesh/_envelope.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, List, Mapping, NoReturn, Optional, Sequence, Tuple
 from . import _lexical as lx
 from . import _model
 from . import _units
-from ._errors import ERROR_CODES, FAULT_CODES, DatumeshError, fail
+from ._errors import ERROR_CODES, FAULT_CODES, FOREIGN_DETAILS, DatumeshError, fail
 from ._json import jcs_bytes, number_tree, numbers_of, parse_json
 from ._keys import _Source, key_sources
 from ._verify import _signed
@@ -25,7 +25,7 @@ OUTCOMES: Dict[str, Tuple[range, Tuple[str, ...], Tuple[str, ...]]] = {
     "payment_required": (range(402, 403), ("quote",), ("fn_hash",)),
     "rate_limited": (range(429, 430), ("retry_after_seconds",), ("fn_hash",)),
     "bad_request": (range(400, 401), ("error",), ("fn_hash",)),
-    "error": (range(500, 600), ("error",), ("fn_hash",)),
+    "error": (range(500, 600), ("error",), ("detail", "fn_hash")),  # detail: spec-0.4.3
     "pending": (range(202, 203), ("estimate_seconds", "job", "poll", "request"), ()),  # spec-0.4.1
 }
 #: A page of the slice endpoint (SPEC 5.6, spec-0.4.2): an ``ok`` with these members instead.
@@ -51,6 +51,9 @@ LIMIT_NEXT = 512
 #: The trust values (SPEC 5.5); ``computed`` since spec-0.4.2.
 TRUST = ("primary", "verified", "unverified", "computed")
 MAX_SECONDS = 2 ** 53 - 1
+#: spec-0.4.3: a foreign mesh could not be reached; an ``error`` envelope's code, with ``detail``, at HTTP 502.
+FOREIGN = "E_FOREIGN_UNAVAILABLE"
+FOREIGN_STATUS = 502
 
 
 @dataclass(frozen=True)
@@ -82,6 +85,9 @@ class EnvelopeResult:
     echoes (or None); ``error``, the code an ``error``, ``bad_request`` or ``not_covered``
     envelope carries (``E_NAME_UNBOUND`` for the last); and for a page of the slice
     endpoint, ``members`` (a :class:`MemberResult` per member, in order) and ``next``.
+    ``error_detail`` (spec-0.4.3): with ``E_FOREIGN_UNAVAILABLE``, the envelope's ``detail`` (one of
+    ``FOREIGN_DETAILS``: why the foreign mesh could not be reached); else None. (``detail`` is this result's
+    human-readable text, as before.)
     """
 
     ok: bool
@@ -99,6 +105,7 @@ class EnvelopeResult:
     error: Optional[str] = None
     members: Tuple[MemberResult, ...] = ()
     next: Optional[str] = None
+    error_detail: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -212,10 +219,15 @@ def _members(env: Any, numbers: Dict[str, str], path: str, at_slice: bool, membe
         _bad("reason is only present with superseded_by", f"{path}.reason")
     if "fault" in env and "error" in env:
         _bad("not_covered carries fault or error, not both", f"{path}.error")
+    if (env.get("error") == FOREIGN) != ("detail" in env):  # spec-0.4.3
+        _bad("detail is present exactly when error is E_FOREIGN_UNAVAILABLE", f"{path}.detail")
     for name in sorted(env):  # JCS order (all names are ASCII)
         v, p = env[name], f"{path}.{name}"
         if name in ("age_seconds", "retry_after_seconds", "estimate_seconds"):
             _seconds(v, numbers.get(name), p)
+        elif name == "detail":
+            if not isinstance(v, str) or v not in FOREIGN_DETAILS:
+                _bad(f"detail is one of {', '.join(FOREIGN_DETAILS)}", p)
         elif name == "error":
             if outcome == "bad_request":
                 allowed_codes = BAD_REQUEST_CODES | {"E_JOB_UNKNOWN"}
@@ -391,6 +403,9 @@ def _check_parsed(status: Any, env_v: Any, tree: Any, sources: Tuple[_Source, ..
         _bad("a batch is refused whole only by a refusal outcome", f"{path}.outcome")
     if isinstance(status, bool) or not isinstance(status, int) or status not in OUTCOMES[outcome][0]:
         _bad(f"HTTP status {status!r} does not match outcome {outcome!r}", "status" if path == "$" else path)
+    if env.get("error") == FOREIGN and status != FOREIGN_STATUS:  # spec-0.4.3
+        _bad(f"E_FOREIGN_UNAVAILABLE is answered with HTTP {FOREIGN_STATUS}, not {status}",
+             "status" if path == "$" else path)
     # step 3a (SPEC 5.5, a468606): what the request decides without the receipt, in this order
     if env.get("error") == "E_JOB_UNKNOWN" and req.job is None:
         _bad("E_JOB_UNKNOWN answers a job URL only, not a /cell request", f"{path}.error")
@@ -435,12 +450,13 @@ def _check_parsed(status: Any, env_v: Any, tree: Any, sources: Tuple[_Source, ..
     fault, error = env.get("fault"), env.get("error")
     detail = "well-formed envelope" + ("; receipt signature-valid" if h else "") + (
         f"; evaluation fault {fault}" if fault else "") + (f"; job {env['job']}" if outcome == "pending" else "") + (
-        f"; a page of {len(members)} members" if page else "")
+        f"; a page of {len(members)} members" if page else "") + (
+        f"; foreign mesh unavailable ({env['detail']})" if "detail" in env else "")
     if outcome == "pending":
         return EnvelopeResult(True, "OK", outcome, None, None, detail, None, None, env["job"],
                               int(numbers_of(tree)["estimate_seconds"]), env["poll"])
     return EnvelopeResult(True, "OK", outcome, trust, h, detail, None, fault, None, None, None, env.get("fn_hash"),
-                          error, members, env.get("next"))
+                          error, members, env.get("next"), env.get("detail"))
 
 
 def _check_page(env: Dict[str, Any], tree: Any, sources: Tuple[_Source, ...], req: _Request,

{datumesh-0.4.2 → datumesh-0.4.3}/src/datumesh/_errors.py

@@ -6,9 +6,10 @@ from typing import NoReturn, Optional
 
 #: Every error code SPEC.md 10.2 defines, in the order of its table. Two, ``E_EVAL_UNAVAILABLE`` and
 #: ``E_INPUT_SUPERSEDED``, are not failures: :func:`verify` reports them with success (SPEC 10.1 step 7.6).
-#: The last four (spec-0.4.1 and spec-0.4.2) are not verification results: ``E_JOB_UNKNOWN``,
-#: ``E_SLICE_AT_CELL`` and ``E_NAME_UNBOUND`` are a mesh's answers about a request, in an envelope (5.5), and
-#: ``E_MESH_DOC`` a result of cross-mesh resolution (9.6).
+#: The last five (spec-0.4.1, spec-0.4.2 and spec-0.4.3) are not verification results: ``E_JOB_UNKNOWN``,
+#: ``E_SLICE_AT_CELL`` and ``E_NAME_UNBOUND`` are a mesh's answers about a request, in an envelope (5.5),
+#: ``E_MESH_DOC`` a result of cross-mesh resolution (9.6), and ``E_FOREIGN_UNAVAILABLE`` a mesh's or resolver's
+#: answer, in an ``error`` envelope with HTTP 502, that a foreign mesh could not be reached (5.5).
 ERROR_CODES: tuple[str, ...] = (
     "E_PARSE_JSON",
     "E_PARSE_DUPLICATE_KEY",
@@ -58,6 +59,7 @@ ERROR_CODES: tuple[str, ...] = (
     "E_MESH_DOC",
     "E_SLICE_AT_CELL",
     "E_NAME_UNBOUND",
+    "E_FOREIGN_UNAVAILABLE",
 )
 
 
@@ -70,6 +72,11 @@ FAULT_CODES: tuple[str, ...] = ("E_FORMULA_DIV_ZERO", "E_FORMULA_DOMAIN", "E_FOR
                                 "E_FORMULA_ABSENT", "E_FORMULA_FUTURE")
 
 
+#: The ``detail`` an ``error`` envelope carries with ``E_FOREIGN_UNAVAILABLE``, and only with it (SPEC 5.5,
+#: spec-0.4.3): why the foreign mesh could not be reached.
+FOREIGN_DETAILS: tuple[str, ...] = ("offline", "network", "dns", "tls", "timeout", "refused")
+
+
 class DatumeshError(ValueError):
     """An input broke a rule of the Datumesh specification.
 

{datumesh-0.4.2 → datumesh-0.4.3}/src/datumesh/_keys.py

@@ -8,7 +8,8 @@ import ssl
 import urllib.error
 import urllib.request
 from dataclasses import dataclass, field
-from typing import Any, Dict, Optional, Tuple, Union
+from types import MappingProxyType
+from typing import Any, Dict, List, Mapping, Optional, Tuple, Union
 
 from . import _lexical as lx
 from ._errors import DatumeshError, fail
@@ -44,6 +45,32 @@ class Key:
         return self.valid_to is None or issued < self.valid_to
 
 
+@dataclass(frozen=True)
+class Declaration:
+    """One entry of a key document's ``declarations`` (SPEC 9.2, spec-0.4.3): the publisher permits its function
+    to be computed over inputs under ``licence`` (a restricted licence, 8.5) from ``valid_from`` until
+    ``valid_to`` (None: open-ended)."""
+
+    licence: str
+    valid_from: str
+    valid_to: Optional[str] = None
+
+    def open_at(self, issued: str) -> bool:
+        """SPEC 8.5 step 4, as a key's window (9.5): ``valid_from <= issued`` and, if present, ``issued < valid_to``."""
+        return self.valid_from <= issued and (self.valid_to is None or issued < self.valid_to)
+
+    def as_dict(self) -> Dict[str, str]:
+        """The entry as the key document writes it."""
+        d = {"licence": self.licence, "valid_from": self.valid_from}
+        if self.valid_to is not None:
+            d["valid_to"] = self.valid_to
+        return d
+
+
+#: A key document's declarations: full function name to its entries, in document order.
+Declarations = Mapping[str, Tuple[Declaration, ...]]
+
+
 @dataclass(frozen=True)
 class KeysResult:
     """The outcome of resolving a host's keys (SPEC 9.3).
@@ -51,6 +78,9 @@ class KeysResult:
     ``ok`` is True and ``code`` is ``"OK"`` when ``keys`` holds the host's
     validated keys; otherwise ``code`` is ``E_KEY_UNAVAILABLE`` or ``E_KEY_DOC``
     and ``keys`` is empty. ``host`` is the host the keys belong to.
+    ``declarations`` (spec-0.4.3): the document's ``declarations`` (SPEC 9.2), a read-only mapping from full
+    function name to a tuple of :class:`Declaration`, or None when the document has none (or is not ok).
+    They change nothing in verification.
     """
 
     ok: bool
@@ -58,21 +88,70 @@ class KeysResult:
     host: Optional[str]
     detail: str = ""
     keys: Tuple[Key, ...] = field(default_factory=tuple)
+    declarations: Optional[Declarations] = field(default=None, hash=False)
 
     @property
     def key_ids(self) -> Tuple[str, ...]:
         return tuple(k.id for k in self.keys)
 
+    def declarations_json(self) -> Optional[Dict[str, List[Dict[str, str]]]]:
+        """The declarations as the document gives them (a ``keys`` vector's output), or None."""
+        if self.declarations is None:
+            return None
+        return {name: [e.as_dict() for e in entries] for name, entries in self.declarations.items()}
+
 
 def _doc_error(host: Optional[str], detail: str) -> KeysResult:
     return KeysResult(False, "E_KEY_DOC", host, detail)
 
 
+def declaration_entries(entries: Any, path: str) -> Tuple[Declaration, ...]:
+    """One declared name's entries (SPEC 9.2): an array of 1 to 16 objects with exactly ``licence`` (8.1),
+    ``valid_from`` and optionally ``valid_to`` (instants, ``valid_to`` later), all strings. Raises
+    DatumeshError (the caller maps it to E_KEY_DOC)."""
+    if not isinstance(entries, list) or not 1 <= len(entries) <= lx.LIMIT_DECLARATION_ENTRIES:
+        fail("E_SCHEMA", f"a declared name has an array of 1 to {lx.LIMIT_DECLARATION_ENTRIES} entries", path)
+    out = []
+    for i, e in enumerate(entries):
+        p = f"{path}[{i}]"
+        require_object(e, p, ("licence", "valid_from"), ("valid_to",))
+        for name in ("licence", "valid_from", "valid_to"):
+            if name in e and not isinstance(e[name], str):
+                fail("E_SCHEMA", f"{name} must be a string", f"{p}.{name}")
+        lx.check_licence(e["licence"], f"{p}.licence")
+        lx.check_instant(e["valid_from"], f"{p}.valid_from")
+        valid_to = e.get("valid_to")
+        if valid_to is not None:
+            lx.check_instant(valid_to, f"{p}.valid_to")
+            if not valid_to > e["valid_from"]:
+                fail("E_SCHEMA", "valid_to must be later than valid_from", f"{p}.valid_to")
+        out.append(Declaration(e["licence"], e["valid_from"], valid_to))
+    return tuple(out)
+
+
+def _declarations(v: Any, doc_host: str) -> Declarations:
+    """SPEC 9.2 (spec-0.4.3): ``declarations`` is an object of 1 to 64 members, each a full function name (2.3)
+    whose namespace's host is ``doc_host`` exactly (a subdomain is another host)."""
+    if not isinstance(v, dict) or not 1 <= len(v) <= lx.LIMIT_DECLARATIONS:
+        fail("E_SCHEMA", f"declarations is an object of 1 to {lx.LIMIT_DECLARATIONS} function names",
+             "$.declarations")
+    out: Dict[str, Tuple[Declaration, ...]] = {}
+    for name, entries in v.items():
+        p = f"$.declarations[{name!r}]"
+        lx.check_function_name(name, p)
+        if lx.host_of(name) != doc_host:
+            fail("E_SCHEMA", f"{name!r} is not a function under the document's host {doc_host!r}", p)
+        out[name] = declaration_entries(entries, p)
+    return MappingProxyType(out)
+
+
 def validate_key_document(doc: Any, host: Optional[str]) -> KeysResult:
     """Check a parsed key document against SPEC 9.2. ``host`` is the host it was
-    fetched from (None: take the document's own ``host`` member)."""
+    fetched from (None: take the document's own ``host`` member). The optional
+    ``declarations`` (spec-0.4.3) are checked with the rest: anything malformed
+    rejects the whole document (E_KEY_DOC)."""
     try:
-        require_object(doc, "$", ("host", "keys", "proto"))
+        require_object(doc, "$", ("host", "keys", "proto"), ("declarations",))
         if doc["proto"] != PROTO:
             fail("E_SCHEMA", f"proto must be {PROTO!r}", "$.proto")
         doc_host = doc["host"]
@@ -110,7 +189,8 @@ def validate_key_document(doc: Any, host: Optional[str]) -> KeysResult:
             seen_ids.add(entry["id"])
             seen_public.add(entry["public"])
             out.append(Key(entry["id"], entry["public"], entry["valid_from"], valid_to))
-        return KeysResult(True, "OK", doc_host, "", tuple(out))
+        decls = _declarations(doc["declarations"], doc_host) if "declarations" in doc else None
+        return KeysResult(True, "OK", doc_host, "", tuple(out), decls)
     except DatumeshError as e:
         where = f" at {e.path}" if e.path else ""
         return _doc_error(host if host is not None else (doc.get("host") if isinstance(doc, dict) and isinstance(doc.get("host"), str) else None),

{datumesh-0.4.2 → datumesh-0.4.3}/src/datumesh/_lexical.py

@@ -31,6 +31,8 @@ LIMIT_LICENCE_URL = 512
 LIMIT_KEYS = 64
 LIMIT_EXTENT = 4096  # values in an argument's extent (spec-0.4.0)
 LIMIT_MEMBERS = 1048576  # member receipt hashes in a slice manifest (spec-0.4.0)
+LIMIT_DECLARATIONS = 64  # function names in a key document's declarations (spec-0.4.3)
+LIMIT_DECLARATION_ENTRIES = 16  # entries for one declared name (spec-0.4.3)
 LIMIT_DNS = 253
 LIMIT_BLOB_LENGTH = 2 ** 53 - 1
 LIMIT_MEDIA_TYPE = 128