openentity 0.3.0__tar.gz → 0.3.1__tar.gz

{openentity-0.3.0 → openentity-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openentity
-Version: 0.3.0
+Version: 0.3.1
 Summary: Open Entity (OEIS-1) client: JCS, did:key, eddsa-jcs-2022, Merkle proofs, adopt().
 Project-URL: Homepage, https://openentity.org
 Project-URL: Documentation, https://oeis.dev
@@ -37,7 +37,7 @@ openentity find --capability C [-q TEXT --alias-type T --level L1]
 openentity withdraw --force
 ```
 
-Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4 registry rejected, 5 local state. `verify` checks signatures, the signer, the Declaration hash and the record chain, not the log checkpoint (use the npm CLI for that).
+Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4 registry rejected, 5 local state. `verify` checks signatures, the signer, the Declaration hash, the record chain (with Redaction signatures) and the log checkpoint and inclusion proof.
 
 Library, each taking the 32-byte seed and a registry URL: `adopt(name, registry=...)`, `withdraw(seed, registry)`, `record(seed, [(kind, payload), ...], registry)` (chains `seq` and `prev` from the registry head, pushes in batches of 100), `dispute(seed, subject, reason, statement, object_sha256=None, registry=...)`, `find(registry, capability=..., q=..., alias_type=..., level=...)`, `present(seed, audience, nonce, registry=None)`. Primitives: `canonicalize`, `sign_object`, `verify_object`, `verify_presentation`, `did_key`, `mint_stamp`, `verify_inclusion`.
 

{openentity-0.3.0 → openentity-0.3.1}/README.md

@@ -24,7 +24,7 @@ openentity find --capability C [-q TEXT --alias-type T --level L1]
 openentity withdraw --force
 ```
 
-Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4 registry rejected, 5 local state. `verify` checks signatures, the signer, the Declaration hash and the record chain, not the log checkpoint (use the npm CLI for that).
+Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4 registry rejected, 5 local state. `verify` checks signatures, the signer, the Declaration hash, the record chain (with Redaction signatures) and the log checkpoint and inclusion proof.
 
 Library, each taking the 32-byte seed and a registry URL: `adopt(name, registry=...)`, `withdraw(seed, registry)`, `record(seed, [(kind, payload), ...], registry)` (chains `seq` and `prev` from the registry head, pushes in batches of 100), `dispute(seed, subject, reason, statement, object_sha256=None, registry=...)`, `find(registry, capability=..., q=..., alias_type=..., level=...)`, `present(seed, audience, nonce, registry=None)`. Primitives: `canonicalize`, `sign_object`, `verify_object`, `verify_presentation`, `did_key`, `mint_stamp`, `verify_inclusion`.
 

{openentity-0.3.0 → openentity-0.3.1}/openentity/__init__.py

@@ -1,4 +1,4 @@
 from .client import adopt, dispute, find, present, record, rotate, withdraw  # noqa: F401
 from .core import *  # noqa: F401,F403
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{openentity-0.3.0 → openentity-0.3.1}/openentity/cli.py

@@ -2,6 +2,7 @@ import argparse
 import json
 import os
 import pathlib
+import re
 import sys
 import urllib.error
 
@@ -121,7 +122,7 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--audience", required=True)
     p.add_argument("--nonce", required=True)
     p.add_argument("--no-attestations", action="store_true")
-    v = add("verify", "verify an EID, URL or file: signatures, signer, Declaration hash, record chain", key=False)
+    v = add("verify", "verify an EID, URL or file: signatures, signer, Declaration hash, record chain, log checkpoint and inclusion", key=False)
     v.add_argument("target")
     w = add("withdraw", "withdraw the Declaration (cannot be undone)")
     w.add_argument("--force", action="store_true")
@@ -220,7 +221,14 @@ def _chain_checks(entries: list[dict], eid: str) -> list[dict]:
             why.append("seq breaks the sequence")
         if e.get("prev") != ((prev.get("hash") if prev.get("redacted") else core.canonical_hash(prev).hex()) if prev else None):
             why.append("prev hash breaks the chain")
-        if not e.get("redacted"):
+        if e.get("redacted"):
+            if not re.fullmatch(r"[0-9a-f]{64}", e.get("hash") or ""):
+                why.append("placeholder hash is not SHA-256 hex")
+            if r := e.get("redaction"):  # the entity's signed request for this entry
+                ok, who = core.verify_object(r)
+                if not (ok and who == eid and r.get("eid") == eid and r.get("seq") == e["seq"] and r.get("entry_sha256") == e.get("hash")):
+                    why.append("redaction is not the entity's signed request for this entry")
+        else:
             if e.get("eid") != eid:
                 why.append("eid mismatch")
             ok, err = core.verify_object(e)
@@ -232,7 +240,27 @@ def _chain_checks(entries: list[dict], eid: str) -> list[dict]:
     return bad + [{"name": f"record chain ({len(entries)} entries)", "ok": not bad}]
 
 
-# ponytail: no checkpoint or log-inclusion check here; `npx openentity verify <eid>` does those.
+def _log_checks(reg: str, index: int | None) -> list[dict]:
+    """Checkpoint note signature against the registry key from /v1/spec, then the RFC 9162 inclusion proof of `index`."""
+    if index is None:
+        return [{"name": "log inclusion", "ok": False, "detail": "registry did not report a log index"}]
+    try:
+        r = _get(reg, "/v1/spec").get("registry") or {}
+        sth = _get(reg, "/v1/log/sth")
+        if not r.get("publicKeyMultibase"):
+            return [{"name": "checkpoint", "ok": False, "detail": "registry publishes no checkpoint key in /v1/spec"}]
+        ok = core.verify_note(sth["signature"], r.get("log_origin", "openentity.org/log"), core.b58decode(r["publicKeyMultibase"][1:])[-32:])
+        out = [{"name": "checkpoint", "ok": ok, "detail": f"checkpoint signature valid, tree size {sth['tree_size']}" if ok else "checkpoint signature INVALID"}]
+        size = sth["tree_size"]
+        leaf = _get(reg, f"/v1/log/entries?start={index}&end={index + 1}")["entries"][0]["leaf"]
+        p = _get(reg, f"/v1/log/proof/{index}?tree_size={size}")
+        lh = core.leaf_hash(core.canonicalize(leaf).encode())
+        good = ok and lh.hex() == p["leaf_hash"] and core.verify_inclusion(index, size, lh, [bytes.fromhex(h) for h in p["proof"]], bytes.fromhex(sth["root_hash"]))
+        return out + [{"name": "log inclusion", "ok": good, "detail": f"leaf {index} included in tree of {size}" if good else f"inclusion proof for leaf {index} FAILED"}]
+    except (client.RegistryError, urllib.error.URLError, KeyError, IndexError, ValueError, TypeError) as e:
+        return [{"name": "log inclusion", "ok": False, "detail": f"{type(e).__name__}: {e}"}]
+
+
 def _verify(args):
     t, reg = args.target, _registry(args)
     if t.startswith(("did:", "eid:")):
@@ -244,6 +272,7 @@ def _verify(args):
         while page := _get(reg, f"/v1/entities/{eid}/record?after={entries[-1]['seq'] if entries else 0}")["entries"]:
             entries += page
         checks += _chain_checks(entries, eid)
+        checks += _log_checks(reg, ent.get("log_index", ent.get("declaration_log_index")))
     elif t.startswith(("http://", "https://")):
         checks = _checks_of(client._request(t))
     else:

{openentity-0.3.0 → openentity-0.3.1}/openentity/core.py

@@ -1,4 +1,5 @@
 """Open Entity primitives, written from spec/OEIS-1.md (sections 3.3, 4, 6, 10.3, 10.4)."""
+import base64
 import hashlib
 import json
 import math
@@ -403,5 +404,25 @@ def verify_inclusion(index: int, size: int, leaf: bytes, proof: list[bytes], roo
     return sn == 0 and r == root
 
 
+def verify_note(note: str, origin: str, public: bytes) -> bool:
+    """C2SP signed note (the log checkpoint): a signature line by `origin` over the body, keyed by the registry key."""
+    body, sep, sigs = note.rpartition("\n\n")
+    if not sep or not note.endswith("\n"):
+        return False
+    keyid = sha256(origin.encode() + b"\n\x01" + public)[:4]
+    for line in sigs.splitlines():
+        parts = line.split(" ")
+        if len(parts) != 3 or parts[0] != "\u2014" or parts[1] != origin:
+            continue
+        try:
+            raw = base64.b64decode(parts[2], validate=True)
+            if len(raw) == 68 and raw[:4] == keyid:
+                Ed25519PublicKey.from_public_bytes(public).verify(raw[4:], (body + "\n").encode())
+                return True
+        except (ValueError, InvalidSignature):
+            continue
+    return False
+
+
 def log_leaf(type_: str, eid: str, object_sha256: str, received_at: str) -> dict:
     return {"type": type_, "eid": eid, "object_sha256": object_sha256, "received_at": received_at}

{openentity-0.3.0 → openentity-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openentity"
-version = "0.3.0"
+version = "0.3.1"
 description = "Open Entity (OEIS-1) client: JCS, did:key, eddsa-jcs-2022, Merkle proofs, adopt()."
 readme = "README.md"
 license = "MIT"

{openentity-0.3.0 → openentity-0.3.1}/tests/test_client.py

@@ -1,4 +1,5 @@
 """withdraw, record, dispute, find, present against a stub registry (same pattern as test_core.py)."""
+import base64
 import json
 import threading
 from http.server import BaseHTTPRequestHandler, HTTPServer
@@ -11,6 +12,8 @@ from openentity import cli, client, core
 SEED = bytes.fromhex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60")  # RFC 8032 test 1, public
 SUBJECT = "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
 BITS = 8
+ORIGIN = "openentity.org/log"
+LOG_KEY = core.KeyPair(b"\7" * 32)  # throwaway registry checkpoint key
 
 
 class Stub(BaseHTTPRequestHandler):
@@ -19,6 +22,8 @@ class Stub(BaseHTTPRequestHandler):
     attestations: list = []
     entity: dict | None = None  # overrides GET /v1/entities/<eid>
     refuse = False  # refuse every continuity link
+    leaves: list = []  # the stub log's leaf objects; the checkpoint is signed by LOG_KEY
+    forge_note = False
 
     def log_message(self, *a):
         pass
@@ -35,7 +40,23 @@ class Stub(BaseHTTPRequestHandler):
         u = urlparse(self.path)
         Stub.log.append(("GET", self.path, None, None))
         if u.path == "/v1/spec":
-            return self._send(200, {"spec": core.SPEC, "stamp_bits": BITS})
+            reg = {"log_origin": ORIGIN, "publicKeyMultibase": "z" + core.b58encode(b"\xed\x01" + LOG_KEY.public)}
+            return self._send(200, {"spec": core.SPEC, "stamp_bits": BITS, "registry": reg})
+        hs = [core.leaf_hash(core.canonicalize(lf).encode()) for lf in Stub.leaves]
+        if u.path == "/v1/log/sth":
+            root = core.merkle_root(hs)
+            body = f"{ORIGIN}\n{len(hs)}\n{base64.b64encode(root).decode()}\n"
+            keyid = core.sha256(ORIGIN.encode() + b"\n\x01" + LOG_KEY.public)[:4]
+            sig = base64.b64encode(keyid + (KP if Stub.forge_note else LOG_KEY).private.sign(body.encode())).decode()
+            return self._send(200, {"tree_size": len(hs), "root_hash": root.hex(), "signature": f"{body}\n\u2014 {ORIGIN} {sig}\n"})
+        if u.path == "/v1/log/entries":
+            i = int(parse_qs(u.query)["start"][0])
+            if i >= len(hs):
+                return self._send(200, {"entries": []})
+            return self._send(200, {"entries": [{"index": i, "leaf": Stub.leaves[i], "leaf_hash": hs[i].hex()}]})
+        if u.path.startswith("/v1/log/proof/"):
+            i = int(u.path.rsplit("/", 1)[1])
+            return self._send(200, {"leaf_hash": hs[i].hex(), "proof": [h.hex() for h in core.inclusion_proof(i, hs)]})
         if u.path == "/v1/entities":
             return self._send(200, {"entities": [{"eid": SUBJECT, "name": "N", "level": "L0"}], "page": 0, "next_page": None})
         if u.path.endswith("/record"):
@@ -83,7 +104,7 @@ class Stub(BaseHTTPRequestHandler):
 
 @pytest.fixture
 def url():
-    Stub.log, Stub.chain, Stub.attestations, Stub.entity, Stub.refuse = [], [], [], None, False
+    Stub.log, Stub.chain, Stub.attestations, Stub.entity, Stub.refuse, Stub.leaves, Stub.forge_note = [], [], [], None, False, [], False
     srv = HTTPServer(("127.0.0.1", 0), Stub)
     threading.Thread(target=srv.serve_forever, daemon=True).start()
     yield f"http://127.0.0.1:{srv.server_port}"
@@ -215,11 +236,21 @@ def test_cli_verify_entity_file_and_failures(url, home, capsys, tmp_path):
     decl = core.sign_object({"spec": core.SPEC, "type": "Declaration", "eid": KP.did, "declaration_version": "1.0",
                              "text_sha256": core.DECLARATION_SHA256, "name": "T", "created": core.now(), "nonce": core.nonce()}, KP)
     doc = core.sign_object({"spec": core.SPEC, "eid": KP.did, "name": "T", "layers": {}, "keys": []}, KP)
-    Stub.entity = {"document": doc, "declaration": decl}
+    Stub.leaves = [{"type": "Declaration", "eid": f"did:key:z{i}", "object_sha256": "00" * 32, "received_at": core.now()} for i in range(5)]
+    Stub.entity = {"document": doc, "declaration": decl, "log_index": 3}
     client.record(SEED, [("arc_opened", {"arc_id": "a", "title": "A"}), ("arc_opened", {"arc_id": "b", "title": "B"})], registry=url)
     code, out, _ = run(capsys, "verify", KP.did, "--json", *reg)
     res = json.loads(out)
-    assert code == 0 and res["ok"] and "record chain (2 entries)" in [c["name"] for c in res["checks"]]
+    names = [c["name"] for c in res["checks"]]
+    assert code == 0 and res["ok"] and "record chain (2 entries)" in names and "checkpoint" in names and "log inclusion" in names
+    Stub.forge_note = True  # checkpoint signed by a key other than the registry's
+    assert run(capsys, "verify", KP.did, *reg)[0] == 3
+    Stub.forge_note = False
+    Stub.entity = {**Stub.entity, "log_index": 9}  # no such leaf
+    assert run(capsys, "verify", KP.did, *reg)[0] == 3
+    Stub.entity = {**Stub.entity, "log_index": None}
+    assert "did not report a log index" in run(capsys, "verify", KP.did, *reg)[1]
+    Stub.entity = {**Stub.entity, "log_index": 3}
     assert "VERIFIED" in run(capsys, "verify", KP.did, *reg)[1]
     f = tmp_path / "decl.json"
     f.write_text(json.dumps(decl))
@@ -293,3 +324,25 @@ def test_rotate_the_registry_refuses_raises_and_returns_nothing(url):
     with pytest.raises(client.RegistryError) as e:
         client.rotate(SEED, registry=url)
     assert e.value.status == 422
+
+
+def test_verify_note_rejects_a_wrong_key_origin_or_body():
+    body = f"{ORIGIN}\n5\n{base64.b64encode(b'r' * 32).decode()}\n"
+    keyid = core.sha256(ORIGIN.encode() + b"\n\x01" + LOG_KEY.public)[:4]
+    note = f"{body}\n\u2014 {ORIGIN} {base64.b64encode(keyid + LOG_KEY.private.sign(body.encode())).decode()}\n"
+    assert core.verify_note(note, ORIGIN, LOG_KEY.public)
+    assert not core.verify_note(note, ORIGIN, KP.public)
+    assert not core.verify_note(note, "other/log", LOG_KEY.public)
+    assert not core.verify_note(note.replace("\n5\n", "\n6\n"), ORIGIN, LOG_KEY.public)
+
+
+def test_chain_check_verifies_redaction_signatures():
+    e1 = core.sign_object({"spec": core.SPEC, "type": "RecordEntry", "eid": KP.did, "seq": 1, "prev": None, "kind": "arc_opened", "payload": {}, "created": core.now()}, KP)
+    h = core.canonical_hash(e1).hex()
+    red = core.sign_object({"spec": core.SPEC, "type": "Redaction", "eid": KP.did, "seq": 1, "entry_sha256": h, "created": core.now()}, KP)
+    ph = {"seq": 1, "prev": None, "redacted": True, "hash": h, "redaction": red}
+    assert cli._chain_checks([ph], KP.did)[-1]["ok"]
+    forged = core.sign_object({k: v for k, v in red.items() if k != "proof"}, core.KeyPair(b"\x05" * 32))
+    assert not cli._chain_checks([{**ph, "redaction": forged}], KP.did)[-1]["ok"]
+    assert not cli._chain_checks([{**ph, "redaction": {**red, "seq": 2}}], KP.did)[-1]["ok"]
+    assert not cli._chain_checks([{**ph, "hash": "zz"}], KP.did)[-1]["ok"]

{openentity-0.3.0 → openentity-0.3.1}/tests/test_core.py

@@ -183,7 +183,7 @@ def test_adopt_and_cli(tmp_path, monkeypatch, capsys):
 def test_cli_version(capsys):
     with pytest.raises(SystemExit) as e:
         cli.main(["--version"])
-    assert e.value.code == 0 and "0.3.0" in capsys.readouterr().out
+    assert e.value.code == 0 and "0.3.1" in capsys.readouterr().out
 
 
 # ---- shared vectors, checked with the independent verifier's own logic ----

{openentity-0.3.0 → openentity-0.3.1}/tests/test_verifier.py

@@ -110,3 +110,59 @@ def test_vector_format(tmp_path):
     assert iv.check_vectors(str(tmp_path)) == 0
     (tmp_path / "v.json").write_text(json.dumps({**vec, "sha256": "0" * 64}))
     assert iv.check_vectors(str(tmp_path)) == 1
+
+
+def _bucket(tmp_path, n=5, tamper=False):
+    kps = [core.KeyPair(bytes([i + 1]) * 32) for i in range(n)]
+    leaves = [core.log_leaf("Declaration", k.did, "ab" * 32, "2026-10-25T00:00:00Z") for k in kps]
+    hs = [core.leaf_hash(core.canonicalize(lf).encode()) for lf in leaves]
+    root = core.merkle_root(hs)
+    (tmp_path / "snapshots").mkdir(); (tmp_path / "tile/0/000.p").mkdir(parents=True); (tmp_path / "tile/entries/000.p").mkdir(parents=True)
+    rows = [json.dumps({"index": i, "leaf": lf, "leaf_hash": hs[i].hex()}) for i, lf in enumerate(leaves)]
+    cp = json.dumps({"checkpoint": {"tree_size": n, "root_hash": root.hex()}})
+    (tmp_path / "snapshots/2026-10-25.jsonl").write_text("\n".join(rows + [cp]) + "\n")
+    (tmp_path / f"tile/0/000.p/{n}").write_bytes(b"".join(hs))
+    ent = b"".join(len(b).to_bytes(2, "big") + b for b in (core.canonicalize(lf).encode() for lf in leaves))
+    (tmp_path / f"tile/entries/000.p/{n}").write_bytes(ent[:-1] + b"x" if tamper else ent)
+    return n, root
+
+
+def test_rebuild_matches_checkpoint(tmp_path):
+    n, root = _bucket(tmp_path)
+    ok, lines = iv.rebuild(tmp_path, (n, root))
+    assert ok, lines
+    assert iv.tile_path(1234067) == "x001/x234/067"
+
+
+def test_rebuild_catches_wrong_root_missing_leaf_and_bad_tile(tmp_path):
+    n, root = _bucket(tmp_path)
+    assert not iv.rebuild(tmp_path, (n, b"\0" * 32))[0]
+    assert not iv.rebuild(tmp_path, (n + 1, root))[0]
+    t = tmp_path / "t"; t.mkdir()
+    n, root = _bucket(t, tamper=True)
+    assert not iv.rebuild(t, (n, root))[0]
+
+
+def test_rebuild_checks_objects_against_leaves(tmp_path):
+    n, root = _bucket(tmp_path)
+    obj = {"type": "Declaration", "eid": "did:key:z1", "n": 1}
+    sha = core.canonical_hash(obj).hex()
+    leaf = core.log_leaf("Declaration", "did:key:z1", sha, "2026-10-25T00:00:00Z")
+    # replace leaf 0 of the bucket with one that commits to obj
+    snap = tmp_path / "snapshots/2026-10-25.jsonl"; rows = snap.read_text().splitlines()
+    leaves = [json.loads(r)["leaf"] for r in rows[:-1]]; leaves[0] = leaf
+    hs = [core.leaf_hash(core.canonicalize(lf).encode()) for lf in leaves]; root = core.merkle_root(hs)
+    snap.write_text("\n".join([json.dumps({"index": i, "leaf": lf, "leaf_hash": hs[i].hex()}) for i, lf in enumerate(leaves)]
+                              + [json.dumps({"checkpoint": {"tree_size": n, "root_hash": root.hex()}})]) + "\n")
+    (tmp_path / "tile/0/000.p" / str(n)).write_bytes(b"".join(hs))
+    (tmp_path / "tile/entries/000.p" / str(n)).write_bytes(b"".join(len(b).to_bytes(2, "big") + b for b in (core.canonicalize(lf).encode() for lf in leaves)))
+    (tmp_path / "objects").mkdir()
+    line = {"idx": 0, "type": "Declaration", "eid": "did:key:z1", "object_sha256": sha, "object": obj}
+    (tmp_path / "objects/2026-10-25.jsonl").write_text(json.dumps(line) + "\n")
+    ok, lines = iv.rebuild(tmp_path, (n, root))
+    assert ok and any("objects: 1 of" in x for x in lines), lines
+    (tmp_path / "objects/2026-10-25.jsonl").write_text(json.dumps({**line, "object": {**obj, "n": 2}}) + "\n")
+    assert not iv.rebuild(tmp_path, (n, root))[0]
+    red = {"seq": 2, "redacted": True, "hash": sha, "redaction": {}}
+    (tmp_path / "objects/2026-10-25.jsonl").write_text(json.dumps({**line, "object": red}) + "\n")
+    assert iv.rebuild(tmp_path, (n, root))[0]

{openentity-0.3.0 → openentity-0.3.1}/uv.lock

@@ -189,7 +189,7 @@ wheels = [
 
 [[package]]
 name = "openentity"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },