openentity 0.5.4__tar.gz → 0.6.0__tar.gz

{openentity-0.5.4 → openentity-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openentity
-Version: 0.5.4
+Version: 0.6.0
 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
@@ -53,7 +53,7 @@ Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4
 
 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`.
 
-Shared core: `Identity.load_or_create()` (key in the OS keychain, else `~/.openentity/identity.key` at 0600; pass `.seed` to the calls above), `adopt(..., client="adk")` (an unsigned label: adk, goose, langchain, ui-tars, cli, other), `trust(eid)` (a `TrustReport` from registry reads only, every signature verified locally, cached 5 minutes, `ok=False` on any failure), and `openentity.issuer` (`attestation`, `revocation`, `did_document`, `openentity_json`).
+Shared core: `Identity.load_or_create()` (key in the OS keychain, else `~/.openentity/identity.key` at 0600; pass `.seed` to the calls above), `adopt(..., client="adk")` (an unsigned label: adk, crewai, goose, langchain, mastra, openai-agents, ui-tars, vercel-ai, cli, other), `trust(eid)` (a `TrustReport` from registry reads only, every signature verified locally, cached 5 minutes, `ok=False` on any failure), and `openentity.issuer` (`attestation`, `revocation`, `did_document`, `openentity_json`).
 
 HTTP message signatures (RFC 9421, Web Bot Auth profile): `sign_request(method, url, body, private_key, did)` returns `Signature-Input`, `Signature` and, for a non-empty body, `Content-Digest` (`private_key` is an `Identity`, a `KeyPair` or a 32-byte seed; ed25519, `keyid` = the signer's did:key, covers `@method`, `@target-uri`, `content-digest`; `created`, `expires`, `nonce`). `verify_request(method, url, headers, body)` returns `{"did", "keyid", "created", "expires", "nonce"}` or raises `HttpSigError` with a `.code` (`missing_headers`, `unknown_alg`, `bad_keyid`, `digest_mismatch`, `created_in_future`, `created_too_old`, `expired`, `lifetime_too_long`, `missing_nonce`, `bad_signature`). Nonce replay tracking is yours. Shared vectors: `test-vectors/http-signature.json`.
 

{openentity-0.5.4 → openentity-0.6.0}/README.md

@@ -37,7 +37,7 @@ Exit codes match the npm CLI: 0 ok, 1 usage, 2 network, 3 verification failed, 4
 
 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`.
 
-Shared core: `Identity.load_or_create()` (key in the OS keychain, else `~/.openentity/identity.key` at 0600; pass `.seed` to the calls above), `adopt(..., client="adk")` (an unsigned label: adk, goose, langchain, ui-tars, cli, other), `trust(eid)` (a `TrustReport` from registry reads only, every signature verified locally, cached 5 minutes, `ok=False` on any failure), and `openentity.issuer` (`attestation`, `revocation`, `did_document`, `openentity_json`).
+Shared core: `Identity.load_or_create()` (key in the OS keychain, else `~/.openentity/identity.key` at 0600; pass `.seed` to the calls above), `adopt(..., client="adk")` (an unsigned label: adk, crewai, goose, langchain, mastra, openai-agents, ui-tars, vercel-ai, cli, other), `trust(eid)` (a `TrustReport` from registry reads only, every signature verified locally, cached 5 minutes, `ok=False` on any failure), and `openentity.issuer` (`attestation`, `revocation`, `did_document`, `openentity_json`).
 
 HTTP message signatures (RFC 9421, Web Bot Auth profile): `sign_request(method, url, body, private_key, did)` returns `Signature-Input`, `Signature` and, for a non-empty body, `Content-Digest` (`private_key` is an `Identity`, a `KeyPair` or a 32-byte seed; ed25519, `keyid` = the signer's did:key, covers `@method`, `@target-uri`, `content-digest`; `created`, `expires`, `nonce`). `verify_request(method, url, headers, body)` returns `{"did", "keyid", "created", "expires", "nonce"}` or raises `HttpSigError` with a `.code` (`missing_headers`, `unknown_alg`, `bad_keyid`, `digest_mismatch`, `created_in_future`, `created_too_old`, `expired`, `lifetime_too_long`, `missing_nonce`, `bad_signature`). Nonce replay tracking is yours. Shared vectors: `test-vectors/http-signature.json`.
 

openentity-0.6.0/openentity/__init__.py

@@ -0,0 +1,27 @@
+"""The Open Entity SDK for Python. The public surface is `__all__`; tests/test_api.py pins it.
+
+The names mirror the TypeScript SDK (@openentity/sdk) with snake_case for camelCase. Functions that exist in only one SDK are
+listed in tests/test_api.py. The 0.5 names that were renamed stay importable (deprecated, removed in 1.0)."""
+from . import issuer  # noqa: F401
+from .client import CLIENTS, DEFAULT_REGISTRY, DISPUTE_REASONS, adopt, dispute, find, present, record, rotate, withdraw
+from .core import *  # noqa: F401,F403
+from .core import __all__ as _core
+from .core import b58decode, b58encode, did_key, nonce, now, public_from_did_key, verification_method  # noqa: F401  (deprecated)
+from .errors import (REGISTRY_ERROR_CODES, HttpSigError, InvalidInputError, OpenEntityError, RegistryError,  # noqa: F401
+                     VerificationError)
+from .httpsig import sign_request, verify_request
+from .identity import Identity
+from .issuer import (A2A_EXTENSION_URI, a2a_extension, agent_card, build_did_document, build_openentity_json, sign_attestation,
+                     sign_revocation)
+from .report import TrustReport, clear_trust_cache, did_web_resolver, trust
+from .schema import validate
+
+__version__ = "0.6.0"
+
+__all__ = sorted([
+    *_core, "CLIENTS", "DEFAULT_REGISTRY", "DISPUTE_REASONS", "adopt", "dispute", "find", "present", "record", "rotate", "withdraw",
+    "REGISTRY_ERROR_CODES", "HttpSigError", "InvalidInputError", "OpenEntityError", "RegistryError", "VerificationError",
+    "sign_request", "verify_request", "Identity", "A2A_EXTENSION_URI", "a2a_extension", "agent_card", "build_did_document",
+    "build_openentity_json", "sign_attestation", "sign_revocation", "TrustReport", "clear_trust_cache", "did_web_resolver", "trust",
+    "validate",
+])

{openentity-0.5.4 → openentity-0.6.0}/openentity/cli.py

@@ -205,7 +205,7 @@ def _read_record(d: pathlib.Path) -> list[dict]:
 
 def _append_entry(e: Entity, kind: str, payload: dict) -> dict:
     last = (_read_record(e.dir) or [None])[-1]
-    at = core.now()
+    at = core.now_seconds()
     entry = core.sign_object({"spec": core.SPEC, "type": "RecordEntry", "eid": e.eid, "seq": last["seq"] + 1 if last else 1,
                               "prev": core.canonical_hash(last).hex() if last else None, "kind": kind, "at": at, "payload": payload}, e.kp, at)
     if len(json.dumps(entry)) > 16 * 1024:
@@ -340,7 +340,7 @@ def _adopt(args):
         if theirs != core.DECLARATION_SHA256:
             raise CliError(EXIT_VERIFY, f"refusing to sign: registry declaration hash {theirs or '(missing)'} differs from this CLI's {core.DECLARATION_SHA256}. Upgrade the CLI or check --registry.")
     kp = core.KeyPair()
-    created = core.now()
+    created = core.now_seconds()
     op_name = args.operator or os.environ.get("OPENENTITY_OPERATOR")
     operator = {"kind": args.operator_kind or ("human" if op_name else "none"), **({"name": op_name} if op_name else {}),
                 **({"contact": args.contact} if args.contact else {}), "custody": args.custody or "entity", "can_change": []}
@@ -439,7 +439,7 @@ def _withdraw(args):
         raise _usage("withdraw marks this entity withdrawn in the append-only log and cannot be undone; re-run with --force")
     e = _load(args)
     w = core.sign_object({"spec": core.SPEC, "type": "Withdrawal", "eid": e.eid, "declaration_version": (e.declaration or {}).get("declaration_version", core.DECLARATION_VERSION),
-                          "name": e.doc.get("name"), "created": core.now(), "nonce": core.nonce()}, e.kp)
+                          "name": e.doc.get("name"), "created": core.now_seconds(), "nonce": core.random_nonce()}, e.kp)
     res = e.reg.send("POST", "/v1/withdraw", w, e.eid)
     _write_json(e.dir / "withdrawal.json", w)
     return res, f"withdrawn: {e.eid} (log index {res.get('log_index')})"
@@ -550,7 +550,7 @@ def _conformance(args):
 
     def checkpoint_signature():
         _must(cp["ok"], cp["detail"])
-        pk = core.b58decode(spec["registry"]["publicKeyMultibase"][1:])[-32:]
+        pk = core.base58btc_decode(spec["registry"]["publicKeyMultibase"][1:])[-32:]
         note = _probe(base, "/v1/log/checkpoint")[3].decode("utf8")
         _must(core.verify_note(note, spec["registry"]["log_origin"], pk), "GET /v1/log/checkpoint does not verify against the published key")
         return cp["detail"]
@@ -727,7 +727,7 @@ def _push_draft(e):
     if d == _strip(e.doc):
         return {"pushed": False}, "nothing to push"
     d["seq"] = e.doc["seq"] + 1
-    now = core.now()  # updated MUST increase (spec 5.5); two pushes in one second would tie, so step past the last one
+    now = core.now_seconds()  # updated MUST increase (spec 5.5); two pushes in one second would tie, so step past the last one
     d["updated"] = now if now > e.doc["updated"] else time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(core._ts(e.doc["updated"]).timestamp() + 1))
     signed = core.sign_object(d, e.kp)
     _checked("EntityDocument", signed)
@@ -796,11 +796,11 @@ def _wallet_proof(e: Entity, args, wallet: str, chain: int, cmd: str, signer: Si
     if signer:
         if signer.address != address:
             raise _usage(f"the wallet key controls {signer.address}, not {address}")
-        msg = siwe_message(urllib.parse.urlparse(e.reg.base).netloc, address, chain, e.eid, core.now())
+        msg = siwe_message(urllib.parse.urlparse(e.reg.base).netloc, address, chain, e.eid, core.now_seconds())
         return address, {"type": "Eip4361", "message": msg, "signature": signer.sign(msg)}, None
     pending = e.dir / f"pending-wallet-{address.lower()}.json"
     if not args.signature:
-        msg = siwe_message(urllib.parse.urlparse(e.reg.base).netloc, address, chain, e.eid, core.now())
+        msg = siwe_message(urllib.parse.urlparse(e.reg.base).netloc, address, chain, e.eid, core.now_seconds())
         _write_json(pending, {"message": msg})
         nxt = f"openentity alias add {cmd} --wallet {address} --signature 0x<signature>"
         return address, None, ({"message": msg, "next": nxt}, f"Sign this message with {address} (EIP-191 personal_sign), then run:\n  {nxt}\n\n{msg}")
@@ -841,9 +841,9 @@ def _alias(args):
     elif kind == "platform":
         if not re.fullmatch(r"[a-z0-9._-]+:[^\s:]+", raw, re.I):
             raise _usage("platform value is <platform>:<handle>")
-        issued = core.now()
+        issued = core.now_seconds()
         sig = e.kp.private.sign(f"Open Entity alias binding\neid: {e.eid}\nalias: {raw}\nissued: {issued}".encode())
-        a = {"type": kind, "value": raw, "proof": {"type": "Ed25519BindingSignature", "issued": issued, "proofValue": "z" + core.b58encode(sig)}}
+        a = {"type": kind, "value": raw, "proof": {"type": "Ed25519BindingSignature", "issued": issued, "proofValue": "z" + core.base58btc_encode(sig)}}
         platform, handle = raw.split(":")
         hint = f'The platform must also publish {{"eid": "{e.eid}"}} at https://<{platform} domain>/.well-known/openentity/bindings/{handle}.json, or issue an identity attestation.'
     else:
@@ -873,8 +873,8 @@ def _record(args):
         entry = next((x for x in _read_record(e.dir) if x["seq"] == seq), None)
         if not entry:
             raise _usage("record redact <seq>: the seq of an entry in your local record")
-        created = core.now()
-        red = core.sign_object({"spec": core.SPEC, "type": "Redaction", "eid": e.eid, "seq": seq, "entry_sha256": core.canonical_hash(entry).hex(), "created": created, "nonce": core.nonce()}, e.kp, created)
+        created = core.now_seconds()
+        red = core.sign_object({"spec": core.SPEC, "type": "Redaction", "eid": e.eid, "seq": seq, "entry_sha256": core.canonical_hash(entry).hex(), "created": created, "nonce": core.random_nonce()}, e.kp, created)
         r = e.reg.send("POST", f"/v1/entities/{e.eid}/record/redact", red, e.eid)
         return {"redaction": red, "placeholder": r.get("placeholder")}, f"redacted seq {seq}: the registry now serves a placeholder that keeps its hash and chain position"
     if args.kind == "push":
@@ -912,7 +912,7 @@ def _keys_of(doc: dict) -> list[bytes]:
     for vm in doc.get("verificationMethod") or []:
         mb, jwk = vm.get("publicKeyMultibase"), vm.get("publicKeyJwk") or {}
         if mb and mb.startswith("z"):
-            b = core.b58decode(mb[1:])
+            b = core.base58btc_decode(mb[1:])
             if len(b) == 34 and b[:2] == b"\xed\x01":
                 out.append(b[2:])
             elif len(b) == 32:
@@ -927,7 +927,7 @@ def resolve_did(did: str) -> dict:
     p = did.split(":")
     if p[:2] == ["did", "key"]:
         try:
-            core.public_from_did_key(did)
+            core.public_key_from_did_key(did)
         except ValueError as e:
             raise CliError(EXIT_VERIFY, f"cannot resolve {did}: {e}")
         mb = did.removeprefix("did:key:")
@@ -1016,7 +1016,7 @@ def _checkpoint(reg: Reg) -> tuple[bool, str, dict]:
     r, sth = reg.spec().get("registry") or {}, reg.get("/v1/log/sth")
     if not r.get("publicKeyMultibase"):
         return False, "registry publishes no checkpoint key in /v1/spec", sth
-    ok = core.verify_note(sth["signature"], r.get("log_origin", "openentity.org/log"), core.b58decode(r["publicKeyMultibase"][1:])[-32:])
+    ok = core.verify_note(sth["signature"], r.get("log_origin", "openentity.org/log"), core.base58btc_decode(r["publicKeyMultibase"][1:])[-32:])
     return ok, f"checkpoint signature valid, tree size {sth['tree_size']}" if ok else "checkpoint signature INVALID", sth
 
 
@@ -1172,7 +1172,7 @@ def _successor_doc(prev: dict, kp: core.KeyPair, args, now: str) -> dict:
 def _link(args, basis: str):
     old = _load(args)
     kp = _kp_from_jwk(_read_json(args.to)) if args.to else core.KeyPair()
-    created = core.now()
+    created = core.now_seconds()
     body = core.build_rotation(old.kp, kp, _successor_doc(old.doc, kp, args, created), basis, created)
     _checked("ContinuityLink", body["link"])
     if args.dry_run:
@@ -1226,9 +1226,9 @@ def _recover(args):
     reg = Reg(_registry_url(args))
     prev = reg.get(f"/v1/entities/{args.previous}/document")
     kp = _kp_from_jwk(_read_json(args.to)) if args.to else core.KeyPair()
-    created = core.now()
+    created = core.now_seconds()
     doc = core.sign_object(_successor_doc(prev, kp, args, created), kp, created)
-    link0 = {"spec": core.SPEC, "type": "ContinuityLink", "previous": args.previous, "successor": kp.did, "basis": "recovery", "created": created, "nonce": core.nonce()}
+    link0 = {"spec": core.SPEC, "type": "ContinuityLink", "previous": args.previous, "successor": kp.did, "basis": "recovery", "created": created, "nonce": core.random_nonce()}
     d = _create_dir(kp, doc, {"registry": reg.base, "docSeq": 1, "recordPushed": 0})
     _write_json(d / "pending-recovery.json", {"link": link0, "successorProof": core.sign_proof(link0, kp, created), "via": args.via})
     digest = "0x" + core.eip712_digest("ContinuityLink", core.canonical_hash(link0).hex(), created).hex()

{openentity-0.5.4 → openentity-0.6.0}/openentity/client.py

@@ -7,6 +7,7 @@ import urllib.request
 from importlib.metadata import PackageNotFoundError, version
 
 from . import core
+from .errors import InvalidInputError, RegistryError
 
 try:
     _VERSION = version("openentity")
@@ -14,13 +15,7 @@ except PackageNotFoundError:
     _VERSION = "dev"
 
 DEFAULT_REGISTRY = "https://openentity.org"
-CLIENTS = ("adk", "goose", "langchain", "ui-tars", "cli", "other")  # the registry's allowlist for the unsigned `client` label
-
-
-class RegistryError(Exception):
-    def __init__(self, status: int, body):
-        super().__init__(f"registry returned {status}: {body}")
-        self.status, self.body = status, body
+CLIENTS = ("adk", "crewai", "goose", "langchain", "mastra", "openai-agents", "ui-tars", "vercel-ai", "cli", "other")  # the registry's allowlist for the unsigned `client` label
 
 
 def _request(url: str, body: dict | None = None, headers: dict | None = None, method: str | None = None) -> dict:
@@ -41,16 +36,16 @@ def _request(url: str, body: dict | None = None, headers: dict | None = None, me
 
 def build_adoption(kp: core.KeyPair, name: str, description: str, registry: str, operator: dict | None = None,
                    substrate: dict | None = None, extra: dict | None = None) -> tuple[dict, dict]:
-    created = core.now()
+    created = core.now_seconds()
     declaration = core.sign_object({
         "spec": core.SPEC, "type": "Declaration", "eid": kp.did,
         "declaration_version": core.DECLARATION_VERSION, "text_sha256": core.DECLARATION_SHA256,
-        "name": name, "created": created, "nonce": core.nonce()}, kp, created)
+        "name": name, "created": created, "nonce": core.random_nonce()}, kp, created)
     ns = "Not yet stated."  # spec 5.3 required fields per layer
     document = core.sign_object({
         "spec": core.SPEC, "eid": kp.did, "name": name, "description": description,
         "created": created, "updated": created, "seq": 1,
-        "keys": [{"id": core.verification_method(kp.did), "type": "Multikey",
+        "keys": [{"id": core.verification_method_id(kp.did), "type": "Multikey",
                   "publicKeyMultibase": kp.did.removeprefix("did:key:")}],
         "operator": operator or {"kind": "none", "custody": "entity", "can_change": []},
         "substrate": substrate or {"model": "unknown", "provider": "unknown", "runtime": "unknown", "declared_at": created},
@@ -71,7 +66,7 @@ def adopt(name: str, description: str = "An Open Entity adopted through the Pyth
     """Adopt on `registry`. Returns the registry response plus `did` and `seed_hex` (keep the seed).
     `client` is an optional label (one of CLIENTS) for the registry's per-client count; it is not signed."""
     if client is not None and client not in CLIENTS:
-        raise ValueError(f"client must be one of {', '.join(CLIENTS)}")
+        raise InvalidInputError(f"client must be one of {', '.join(CLIENTS)}")
     registry = registry.rstrip("/")
     kp = core.KeyPair(seed)
     bits = int(_request(f"{registry}/v1/spec")["stamp_bits"])
@@ -80,7 +75,7 @@ def adopt(name: str, description: str = "An Open Entity adopted through the Pyth
                    {"x-oe-stamp": core.mint_stamp(bits, kp.did)})
     # Seq-1 declaration entry (spec 7.3). The registry never writes entries; on failure the signed
     # entry is returned so the caller can push it later.
-    at = core.now()
+    at = core.now_seconds()
     entry = core.sign_object({
         "spec": core.SPEC, "type": "RecordEntry", "eid": kp.did, "seq": 1, "prev": None, "kind": "declaration",
         "at": at, "payload": {"declaration_version": core.DECLARATION_VERSION,
@@ -107,7 +102,7 @@ def withdraw(seed: bytes, registry: str = DEFAULT_REGISTRY, name: str | None = N
     registry = registry.rstrip("/")
     name = name or _request(f"{registry}/v1/entities/{kp.did}")["document"]["name"]
     w = core.sign_object({"spec": core.SPEC, "type": "Withdrawal", "eid": kp.did, "declaration_version": core.DECLARATION_VERSION,
-                          "name": name, "created": core.now(), "nonce": core.nonce()}, kp)
+                          "name": name, "created": core.now_seconds(), "nonce": core.random_nonce()}, kp)
     return _post(registry, "/v1/withdraw", w, kp)
 
 
@@ -120,7 +115,7 @@ def record(seed: bytes, entries: list[tuple[str, dict]], registry: str = DEFAULT
     seq, prev = (head["seq"], head["hash"]) if head else (0, None)
     signed = []
     for kind, payload in entries:
-        seq, at = seq + 1, core.now()
+        seq, at = seq + 1, core.now_seconds()
         e = core.sign_object({"spec": core.SPEC, "type": "RecordEntry", "eid": kp.did, "seq": seq, "prev": prev,
                               "kind": kind, "at": at, "payload": payload}, kp, at)
         signed.append(e)
@@ -150,13 +145,13 @@ def dispute(seed: bytes, subject: str, reason: str, statement: str, object_sha25
             registry: str = DEFAULT_REGISTRY) -> dict:
     """File a signed Dispute about `subject`, or about one of its objects (spec 10.5)."""
     if reason not in DISPUTE_REASONS:
-        raise ValueError(f"reason must be one of {', '.join(DISPUTE_REASONS)}")
+        raise InvalidInputError(f"reason must be one of {', '.join(DISPUTE_REASONS)}")
     if object_sha256 is not None and not re.fullmatch(r"[0-9a-f]{64}", object_sha256):
-        raise ValueError("object_sha256 must be 64 lowercase hex characters")
+        raise InvalidInputError("object_sha256 must be 64 lowercase hex characters")
     kp = core.KeyPair(seed)
     d = core.sign_object({"spec": core.SPEC, "type": "Dispute", "issuer": kp.did, "subject": subject,
                           **({"object_sha256": object_sha256} if object_sha256 else {}), "reason": reason,
-                          "statement": statement, "created": core.now(), "nonce": core.nonce()}, kp)
+                          "statement": statement, "created": core.now_seconds(), "nonce": core.random_nonce()}, kp)
     return _post(registry, "/v1/disputes", d, kp)
 
 

{openentity-0.5.4 → openentity-0.6.0}/openentity/core.py

@@ -12,6 +12,21 @@ from cryptography.exceptions import InvalidSignature
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
 from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
 
+from .errors import InvalidInputError
+
+# The public names. The old 0.5 names (last line of the file) stay importable from `openentity.core` but are not re-exported.
+__all__ = [
+    "SPEC", "DECLARATION_VERSION", "DECLARATION_TEXT", "DECLARATION_SHA256", "KeyPair",
+    "sha256", "sha256_hex", "record_entry_hash", "base58btc_encode", "base58btc_decode", "parse_json", "canonicalize", "canonical_hash",
+    "did_key_from_public_key", "public_key_from_did_key", "verification_method_id", "normalize_eid",
+    "generate_key_pair", "key_pair_from_seed", "now_seconds", "random_nonce", "check_timestamp",
+    "sign_proof", "sign_object", "verify_object", "default_resolver", "successor_document", "build_rotation",
+    "eip712_digest", "recover_eip712", "build_presentation", "verify_presentation",
+    "mint_stamp", "check_stamp", "leaf_hash", "node_hash", "merkle_root", "inclusion_proof", "verify_inclusion",
+    "verify_note", "log_leaf",
+]
+
+
 SPEC = "openentity/1.0"
 DECLARATION_VERSION = "1.0"
 _B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
@@ -35,11 +50,15 @@ def sha256(data: str | bytes) -> bytes:
     return hashlib.sha256(data.encode() if isinstance(data, str) else data).digest()
 
 
+def sha256_hex(data: str | bytes) -> str:
+    return sha256(data).hex()
+
+
 DECLARATION_SHA256 = sha256(DECLARATION_TEXT).hex()
 
 
 # ---- base58btc ----
-def b58encode(b: bytes) -> str:
+def base58btc_encode(b: bytes) -> str:
     n = int.from_bytes(b, "big")
     out = ""
     while n:
@@ -48,9 +67,11 @@ def b58encode(b: bytes) -> str:
     return "1" * (len(b) - len(b.lstrip(b"\0"))) + out
 
 
-def b58decode(s: str) -> bytes:
+def base58btc_decode(s: str) -> bytes:
     n = 0
     for c in s:
+        if c not in _B58:
+            raise InvalidInputError(f'invalid base58btc character "{c}"')
         n = n * 58 + _B58.index(c)
     body = n.to_bytes((n.bit_length() + 7) // 8, "big")
     return b"\0" * (len(s) - len(s.lstrip("1"))) + body
@@ -61,7 +82,7 @@ def _num(x) -> str:
     if isinstance(x, int):
         return str(x)
     if not math.isfinite(x):
-        raise ValueError("JCS: NaN and Infinity are not JSON")
+        raise InvalidInputError("JCS: NaN and Infinity are not JSON")
     if x == 0:
         return "0"
     t = Decimal(repr(abs(x))).normalize().as_tuple()
@@ -84,7 +105,7 @@ def parse_json(text: str):
     def pairs(items):
         keys = [k for k, _ in items]
         if len(keys) != len(set(keys)):
-            raise ValueError(f"duplicate key {next(k for k in keys if keys.count(k) > 1)!r}")
+            raise InvalidInputError(f"duplicate key {next(k for k in keys if keys.count(k) > 1)!r}")
         return dict(items)
     return json.loads(text, object_pairs_hook=pairs)
 
@@ -121,20 +142,20 @@ def canonical_hash(v) -> bytes:
 
 
 # ---- did:key (spec 3.3) ----
-def did_key(public: bytes) -> str:
-    return "did:key:z" + b58encode(b"\xed\x01" + public)
+def did_key_from_public_key(public: bytes) -> str:
+    return "did:key:z" + base58btc_encode(b"\xed\x01" + public)
 
 
-def public_from_did_key(did: str) -> bytes:
+def public_key_from_did_key(did: str) -> bytes:
     if not did.startswith("did:key:z"):
-        raise ValueError("not a did:key")
-    raw = b58decode(did[9:])
+        raise InvalidInputError("not a did:key")
+    raw = base58btc_decode(did[9:])
     if raw[:2] != b"\xed\x01" or len(raw) != 34:
-        raise ValueError("not an Ed25519 did:key")
+        raise InvalidInputError("not an Ed25519 did:key")
     return raw[2:]
 
 
-def verification_method(did: str) -> str:
+def verification_method_id(did: str) -> str:
     return f"{did}#{did.removeprefix('did:key:')}"
 
 
@@ -143,15 +164,15 @@ class KeyPair:
         self.seed = seed or os.urandom(32)
         self.private = Ed25519PrivateKey.from_private_bytes(self.seed)
         self.public = self.private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
-        self.did = did_key(self.public)
+        self.did = did_key_from_public_key(self.public)
 
 
-def now() -> str:
+def now_seconds() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def nonce() -> str:
-    return b58encode(os.urandom(16))
+def random_nonce() -> str:
+    return base58btc_encode(os.urandom(16))
 
 
 # ---- eddsa-jcs-2022 (spec 4.1) ----
@@ -163,10 +184,10 @@ def _signing_input(obj: dict, proof: dict) -> bytes:
 
 def sign_proof(obj: dict, kp: KeyPair, created: str | None = None, method: str | None = None) -> dict:
     """`method` names the verification method; it defaults to the did:key of `kp`, a did:web signer passes `did:web:x#key-1`."""
-    proof = {"type": "DataIntegrityProof", "cryptosuite": "eddsa-jcs-2022", "created": created or now(),
-             "verificationMethod": method or verification_method(kp.did), "proofPurpose": "assertionMethod"}
+    proof = {"type": "DataIntegrityProof", "cryptosuite": "eddsa-jcs-2022", "created": created or now_seconds(),
+             "verificationMethod": method or verification_method_id(kp.did), "proofPurpose": "assertionMethod"}
     sig = kp.private.sign(_signing_input(obj, proof))
-    return {**proof, "proofValue": "z" + b58encode(sig)}
+    return {**proof, "proofValue": "z" + base58btc_encode(sig)}
 
 
 def sign_object(obj: dict, kp: KeyPair, created: str | None = None, method: str | None = None) -> dict:
@@ -176,19 +197,19 @@ def sign_object(obj: dict, kp: KeyPair, created: str | None = None, method: str
 # ---- continuity (spec 9) ----
 def successor_document(prev: dict, nxt: KeyPair, created: str | None = None) -> dict:
     """The successor's unsigned seq 1 document: `prev` re-keyed, aliases dropped (their proofs name the old EID)."""
-    created = created or now()
+    created = created or now_seconds()
     d = {k: v for k, v in prev.items() if k not in ("proof", "aliases")}
     return {**d, "eid": nxt.did, "created": created, "updated": created, "seq": 1,
-            "keys": [{"id": verification_method(nxt.did), "type": "Multikey", "publicKeyMultibase": nxt.did.removeprefix("did:key:")}],
+            "keys": [{"id": verification_method_id(nxt.did), "type": "Multikey", "publicKeyMultibase": nxt.did.removeprefix("did:key:")}],
             "continuity": {**d.get("continuity", {}), "previous": prev["eid"]}}
 
 
 def build_rotation(previous: KeyPair, successor: KeyPair, document: dict, basis: str = "rotation",
                    created: str | None = None, nonce_: str | None = None) -> dict:
     """The body of POST /v1/continuity: a link signed by both keys, and the successor's document signed by it."""
-    created = created or now()
+    created = created or now_seconds()
     body = {"spec": SPEC, "type": "ContinuityLink", "previous": previous.did, "successor": successor.did,
-            "basis": basis, "created": created, "nonce": nonce_ or nonce()}
+            "basis": basis, "created": created, "nonce": nonce_ or random_nonce()}
     link = {**body, "proofs": [sign_proof(body, previous, created), sign_proof(body, successor, created)]}
     return {"link": link, "document": sign_object(document, successor, created)}
 
@@ -238,17 +259,17 @@ def recover_eip712(digest: bytes, sig_hex: str) -> str:
     """Checksummed address that signed `digest`."""
     sig = bytes.fromhex(sig_hex.removeprefix("0x"))
     if len(sig) != 65:
-        raise ValueError("signature must be 65 bytes")
+        raise InvalidInputError("signature must be 65 bytes")
     r, s_, v = int.from_bytes(sig[:32], "big"), int.from_bytes(sig[32:64], "big"), sig[64] - 27 if sig[64] >= 27 else sig[64]
     if v > 1 or not (0 < r < _N and 0 < s_ < _N):
-        raise ValueError("invalid signature")
+        raise InvalidInputError("invalid signature")
     y = pow((r ** 3 + 7) % _P, (_P + 1) // 4, _P)
     if y % 2 != v:
         y = _P - y
     e = int.from_bytes(digest, "big")
     q = _mul(pow(r, -1, _N), _add(_mul(s_, (r, y)), _mul((-e) % _N, _G)))
     if q is None:
-        raise ValueError("invalid signature")
+        raise InvalidInputError("invalid signature")
     addr = _keccak(q[0].to_bytes(32, "big") + q[1].to_bytes(32, "big"))[12:].hex()
     h = _keccak(addr).hex()
     return "0x" + "".join(c.upper() if int(h[i], 16) >= 8 else c for i, c in enumerate(addr))
@@ -257,11 +278,11 @@ def recover_eip712(digest: bytes, sig_hex: str) -> str:
 def default_resolver(did: str) -> dict:
     """Offline resolution: did:key and did:pkh. Pass a resolver for did:web and other methods."""
     if did.startswith("did:key:"):
-        return {"ed25519": [public_from_did_key(did)]}
+        return {"ed25519": [public_key_from_did_key(did)]}
     m = re.fullmatch(r"did:pkh:eip155:\d+:(0x[0-9a-fA-F]{40})", did)
     if m:
         return {"address": m.group(1)}
-    raise ValueError(f"cannot resolve {':'.join(did.split(':')[:2])} offline; pass a resolver")
+    raise InvalidInputError(f"cannot resolve {':'.join(did.split(':')[:2])} offline; pass a resolver")
 
 
 def verify_object(obj: dict, resolver=default_resolver) -> tuple[bool, str]:
@@ -275,7 +296,7 @@ def verify_object(obj: dict, resolver=default_resolver) -> tuple[bool, str]:
         if proof.get("type") == "DataIntegrityProof":
             if proof.get("cryptosuite") != "eddsa-jcs-2022" or not proof["proofValue"].startswith("z"):
                 return False, "unsupported proof"
-            sig, msg = b58decode(proof["proofValue"][1:]), _signing_input(obj, proof)
+            sig, msg = base58btc_decode(proof["proofValue"][1:]), _signing_input(obj, proof)
             for pk in keys.get("ed25519", []):
                 try:
                     Ed25519PublicKey.from_public_bytes(pk).verify(sig, msg)
@@ -303,7 +324,7 @@ def _ts(s: str) -> datetime:
 
 
 def build_presentation(kp: KeyPair, audience: str, nonce_: str, attestations: list | None = None) -> dict:
-    created = now()
+    created = now_seconds()
     obj = {"spec": SPEC, "type": "Presentation", "eid": kp.did, "audience": audience, "nonce": nonce_, "created": created}
     return sign_object({**obj, "attestations": attestations} if attestations else obj, kp, created)
 
@@ -354,9 +375,9 @@ def _zero_bits(h: bytes) -> int:
 
 def mint_stamp(bits: int, eid: str, created: str | None = None) -> str:
     # Random start so two stamps for the same EID in the same second differ (registries reject reuse).
-    created, i = created or now(), int.from_bytes(os.urandom(4), "big")
+    created, i = created or now_seconds(), int.from_bytes(os.urandom(4), "big")
     while True:
-        header = f"1:{bits}:{created}:{eid}:{b58encode(i.to_bytes(8, 'big'))}"
+        header = f"1:{bits}:{created}:{eid}:{base58btc_encode(i.to_bytes(8, 'big'))}"
         if _zero_bits(sha256(header)) >= bits:
             return header
         i += 1
@@ -449,3 +470,42 @@ def verify_note(note: str, origin: str, public: bytes) -> bool:
 
 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}
+
+
+def record_entry_hash(entry: dict) -> str:
+    """sha256 hex of the canonical entry INCLUDING its proof: the next entry's `prev` (spec 7.4)."""
+    return canonical_hash(entry).hex()
+
+
+def normalize_eid(eid: str) -> str:
+    """Spec 3.3: the `eid:base:0x...` shorthand is the did:pkh on Base."""
+    return "did:pkh:eip155:8453:" + eid.removeprefix("eid:base:") if eid.startswith("eid:base:") else eid
+
+
+def check_timestamp(created: str, at: datetime | None = None) -> str | None:
+    """Spec 4.4: None if `created` is a valid timestamp no more than 10 minutes ahead and 24 hours behind `at` (now)."""
+    try:
+        t = _ts(created)
+    except ValueError:
+        return "created must be RFC 3339 UTC with second precision and a Z suffix"
+    at = at or datetime.now(timezone.utc)
+    if t > at + timedelta(minutes=10):
+        return "created is more than 10 minutes in the future"
+    if t < at - timedelta(hours=24):
+        return "created is more than 24 hours in the past"
+    return None
+
+
+def generate_key_pair() -> KeyPair:
+    return KeyPair()
+
+
+def key_pair_from_seed(seed: bytes) -> KeyPair:
+    if len(seed) != 32:
+        raise InvalidInputError("seed must be 32 bytes")
+    return KeyPair(seed)
+
+
+# Deprecated 0.5 names, kept until 1.0. The canonical names match the TypeScript SDK (snake_case for camelCase).
+b58encode, b58decode, did_key, public_from_did_key = base58btc_encode, base58btc_decode, did_key_from_public_key, public_key_from_did_key
+verification_method, now, nonce = verification_method_id, now_seconds, random_nonce

openentity-0.6.0/openentity/errors.py

@@ -0,0 +1,51 @@
+"""Every error the SDK raises on purpose derives from OpenEntityError and carries a `code`.
+
+REGISTRY_ERROR_CODES are the codes the registry answers with. `RegistryError.code` is one of them when the registry refused a
+request, or "registry_error" for a non-2xx answer without an error body. Local failures use "invalid_input" and
+"verification_failed"; HttpSigError uses the RFC 9421 failure reason. InvalidInputError and VerificationError are also
+ValueErrors, so code written against 0.5 (`except ValueError`) keeps working.
+"""
+
+REGISTRY_ERROR_CODES = frozenset("""
+alias_exists alias_proof_invalid already_redacted already_revoked already_withdrawn attestation_not_found bad_email bad_json
+bad_sort bad_token bad_tree_size batch_too_large continuity_proof_missing custody_unavailable declaration_exists
+declaration_hash_mismatch declaration_not_found dispute_exists document_required eid_mismatch entity_exists entity_not_found
+entry_hash_mismatch entry_not_found expires_invalid invalid_client no_checkpoint no_custodial_copy nonce_reused not_incorporated
+not_issuer object_not_about_subject object_not_found presentation_invalid previous_has_successor rate_limited record_chain_broken
+recovery_alias_required schema_invalid seq_invalid signature_invalid snapshot_not_found stamp_invalid stamp_required stamp_reused
+subscribe_failed subscribe_unavailable successor_has_predecessor tile_not_found timestamp_invalid too_large turnstile_failed
+unresolvable unsupported_method updated_not_increasing
+""".split())
+
+
+class OpenEntityError(Exception):
+    code: str = "error"
+
+    def __init__(self, message: str = "", code: str | None = None):
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class InvalidInputError(OpenEntityError, ValueError):
+    code = "invalid_input"
+
+
+class VerificationError(OpenEntityError, ValueError):
+    code = "verification_failed"
+
+
+class RegistryError(OpenEntityError):
+    """A non-2xx registry answer: `status`, `body` (parsed JSON when it was JSON) and `code`."""
+
+    def __init__(self, status: int, body):
+        code = body.get("error") if isinstance(body, dict) else None
+        super().__init__(f"registry returned {status}: {body}", code if isinstance(code, str) else "registry_error")
+        self.status, self.body = status, body
+
+
+class HttpSigError(OpenEntityError):
+    """RFC 9421 verification failure; `code` is the reason, such as "bad_signature" or "digest_mismatch"."""
+
+    def __init__(self, code: str):
+        super().__init__(code, code)

{openentity-0.5.4 → openentity-0.6.0}/openentity/httpsig.py

@@ -11,16 +11,11 @@ from cryptography.exceptions import InvalidSignature
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
 
 from . import core
+from .errors import HttpSigError, InvalidInputError
 
 SKEW = 5  # seconds of clock skew allowed on `created`
 
 
-class HttpSigError(Exception):
-    def __init__(self, code: str):
-        super().__init__(code)
-        self.code = code
-
-
 def _b64url(b: bytes) -> str:
     return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
 
@@ -44,7 +39,7 @@ def _seed(key) -> bytes:
             return _seed(getattr(key, attr))
     if isinstance(key, (bytes, bytearray)) and len(key) == 32:
         return bytes(key)
-    raise ValueError("private_key must be an Identity, a KeyPair or a 32-byte Ed25519 seed")
+    raise InvalidInputError("private_key must be an Identity, a KeyPair or a 32-byte Ed25519 seed")
 
 
 def sign_request(method: str, url: str, body: bytes, private_key, did: str, *, created: int | None = None,
@@ -78,8 +73,8 @@ def verify_request(method: str, url: str, headers: Mapping[str, str], body: byte
         raise HttpSigError("unknown_alg")
     keyid = p.get("keyid", "")
     try:
-        public = core.public_from_did_key(keyid)
-        if core.did_key(public) != keyid:
+        public = core.public_key_from_did_key(keyid)
+        if core.did_key_from_public_key(public) != keyid:
             raise ValueError
     except Exception:
         raise HttpSigError("bad_keyid") from None

{openentity-0.5.4 → openentity-0.6.0}/openentity/issuer.py

@@ -6,6 +6,7 @@ import re
 from datetime import datetime, timedelta, timezone
 
 from . import core
+from .errors import InvalidInputError
 
 MAX_TTL = timedelta(days=365)  # spec 8.4
 
@@ -18,12 +19,12 @@ def _method(kp: core.KeyPair, issuer: str | None, key_id: str) -> str | None:
     return f"{issuer}#{key_id}" if issuer and issuer != kp.did else None
 
 
-def attestation(kp: core.KeyPair, subject: str, claim_type: str, claim: dict, *, issuer: str | None = None,
+def sign_attestation(kp: core.KeyPair, subject: str, claim_type: str, claim: dict, *, issuer: str | None = None,
                 key_id: str = "key-1", evidence: dict | None = None, confidence: float | None = None,
                 ttl: timedelta = timedelta(days=90), now: datetime | None = None) -> dict:
     """A signed Attestation (spec 8.2). `ttl` is capped at one year."""
     if not timedelta(0) < ttl <= MAX_TTL:
-        raise ValueError("ttl must be positive and at most 1 year")
+        raise InvalidInputError("ttl must be positive and at most 1 year")
     t = now or datetime.now(timezone.utc)
     created = _ts(t)
     obj = {"spec": core.SPEC, "type": "Attestation", "issuer": issuer or kp.did, "subject": subject,
@@ -32,7 +33,7 @@ def attestation(kp: core.KeyPair, subject: str, claim_type: str, claim: dict, *,
     return core.sign_object(obj, kp, created, _method(kp, issuer, key_id))
 
 
-def revocation(kp: core.KeyPair, attested: dict | str, *, issuer: str | None = None, key_id: str = "key-1",
+def sign_revocation(kp: core.KeyPair, attested: dict | str, *, issuer: str | None = None, key_id: str = "key-1",
                reason: str | None = None, now: datetime | None = None) -> dict:
     """A signed Revocation naming the attestation (the object, or its SHA-256 hex) (spec 8.4)."""
     sha = core.canonical_hash(attested).hex() if isinstance(attested, dict) else attested
@@ -42,22 +43,22 @@ def revocation(kp: core.KeyPair, attested: dict | str, *, issuer: str | None = N
     return core.sign_object(obj, kp, created, _method(kp, issuer, key_id))
 
 
-def did_document(did: str, public: bytes, key_id: str = "key-1") -> dict:
+def build_did_document(did: str, public: bytes, key_id: str = "key-1") -> dict:
     """The body of `https://<domain>/.well-known/did.json` for a did:web issuer."""
     vm = f"{did}#{key_id}"
     return {"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/multikey/v1"], "id": did,
             "verificationMethod": [{"id": vm, "type": "Multikey", "controller": did,
-                                    "publicKeyMultibase": core.did_key(public).removeprefix("did:key:")}],
+                                    "publicKeyMultibase": core.did_key_from_public_key(public).removeprefix("did:key:")}],
             "assertionMethod": [vm], "authentication": [vm]}
 
 
-def openentity_json(did: str, public: bytes, name: str, description: str, *, key_id: str = "key-1",
+def build_openentity_json(did: str, public: bytes, name: str, description: str, *, key_id: str = "key-1",
                     operator: dict | None = None, extensions: dict | None = None) -> dict:
     """The unsigned body of `https://<domain>/.well-known/openentity.json`: the domain alias proof (spec 3.4) and,
     under `extensions["openentity:observer"]`, an observer's methodology (spec 8.4)."""
     return {"spec": core.SPEC, "eid": did, "name": name, "description": description,
             "keys": [{"id": f"{did}#{key_id}", "type": "Multikey",
-                      "publicKeyMultibase": core.did_key(public).removeprefix("did:key:")}],
+                      "publicKeyMultibase": core.did_key_from_public_key(public).removeprefix("did:key:")}],
             "operator": operator or {"kind": "organization", "name": name, "custody": "operator", "can_change": []},
             **({"extensions": extensions} if extensions else {})}
 
@@ -79,3 +80,7 @@ def agent_card(doc: dict, url: str, document_url: str, version: str = "1.0.0") -
     return {"name": doc["name"], "description": doc["description"], "url": url, "version": version,
             "capabilities": {"streaming": False, "pushNotifications": False, "extensions": [a2a_extension(doc["eid"], document_url)]},
             "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": skills}
+
+
+# Deprecated 0.5 names, kept until 1.0.
+attestation, revocation, did_document, openentity_json = sign_attestation, sign_revocation, build_did_document, build_openentity_json

{openentity-0.5.4 → openentity-0.6.0}/openentity/report.py

@@ -6,6 +6,7 @@ from datetime import datetime, timezone
 from urllib.parse import unquote
 
 from . import client, core
+from .errors import InvalidInputError, VerificationError
 
 MOLTBOTDEN, CLAWGRC = "did:web:moltbotden.com", "did:web:api.clawgrc.com"
 SMA = ("did:web:securemyagent.ai", "did:pkh:eip155:8453:0x62fef02E2859726EC1c0B534853Ad2cdd5FdDE1a")
@@ -36,11 +37,11 @@ def did_web_resolver(fetch=client._request):
         host, *path = [unquote(p) for p in did[8:].split(":")]
         doc = fetch(f"https://{host}/{'/'.join(path) if path else '.well-known'}/did.json")
         if doc.get("id") != did:
-            raise ValueError(f"{did} document names {doc.get('id')}")
+            raise VerificationError(f"{did} document names {doc.get('id')}")
         keys = []
         for vm in doc.get("verificationMethod", []):
             try:
-                keys.append(core.public_from_did_key("did:key:" + vm["publicKeyMultibase"]))
+                keys.append(core.public_key_from_did_key("did:key:" + vm["publicKeyMultibase"]))
             except (KeyError, ValueError):
                 continue  # not an Ed25519 Multikey
         return {"ed25519": keys}
@@ -63,10 +64,10 @@ def trust(eid: str, registry: str = client.DEFAULT_REGISTRY, *, now: datetime |
 
 def _read(eid, base, now, fetch, resolver) -> TrustReport:
     if not eid.startswith("did:"):
-        raise ValueError("eid must be a DID")
+        raise InvalidInputError("eid must be a DID")
     ent = fetch(f"{base}/v1/entities/{eid}")
     if ent["eid"] != eid:
-        raise ValueError(f"registry answered for {ent['eid']}")
+        raise VerificationError(f"registry answered for {ent['eid']}")
     rows = fetch(f"{base}/v1/entities/{eid}/attestations")["attestations"]
     tiers, posture, violations, revocations = {}, None, [], []
     for r in sorted(rows, key=lambda r: r["attestation"]["created"], reverse=True):
@@ -77,18 +78,18 @@ def _read(eid, base, now, fetch, resolver) -> TrustReport:
             continue  # a rotation does not carry positive claims; a strike follows the entity
         sha, ended = r["sha256"], core._ts(a["expires"]) <= now
         if a["subject"] != (r.get("inherited_from") or eid) or core.canonical_hash(a).hex() != sha:
-            raise ValueError(f"attestation {sha} does not match what the registry served")
+            raise VerificationError(f"attestation {sha} does not match what the registry served")
         ok, signer = core.verify_object(a, resolver)
         if not ok or signer != a["issuer"]:
-            raise ValueError(f"attestation {sha}: {signer}")
+            raise VerificationError(f"attestation {sha}: {signer}")
         rv = r.get("revocation")
         if rv:
             ok, signer = core.verify_object(rv, resolver)
             if not ok or signer != a["issuer"] or rv["attestation_sha256"] != sha:
-                raise ValueError(f"revocation of {sha}: {signer}")
+                raise VerificationError(f"revocation of {sha}: {signer}")
             revocations.append({"sha256": sha, "claim_type": ct, "issuer": a["issuer"], "reason": rv.get("reason"), "at": rv["created"]})
         elif r.get("revoked_at"):
-            raise ValueError(f"registry reports a revocation of {sha} it does not carry")
+            raise VerificationError(f"registry reports a revocation of {sha} it does not carry")
         if ended or rv:
             continue
         c = a["claim"]
@@ -99,3 +100,7 @@ def _read(eid, base, now, fetch, resolver) -> TrustReport:
         else:
             violations.append({"issuer": a["issuer"], "severity": c["severity"], "policy": c["policy"], "observed_at": c["observed_at"], "sha256": sha})
     return TrustReport(eid, True, None, ent["level"], bool(ent.get("withdrawn")), tiers, posture, violations, revocations)
+
+
+def clear_trust_cache() -> None:
+    _cache.clear()

{openentity-0.5.4 → openentity-0.6.0}/pyproject.toml

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

openentity-0.6.0/tests/test_api.py

@@ -0,0 +1,79 @@
+"""The public API is pinned: a stray export, a rename or a drift from the TypeScript SDK fails here."""
+import pathlib
+import re
+
+import pytest
+
+import openentity
+from openentity import core, issuer
+
+TS_INDEX = pathlib.Path(__file__).parents[2] / "ts" / "src" / "index.ts"
+
+# Editing this list is how a surface change is made on purpose.
+SNAPSHOT = """
+A2A_EXTENSION_URI CLIENTS DECLARATION_SHA256 DECLARATION_TEXT DECLARATION_VERSION DEFAULT_REGISTRY DISPUTE_REASONS HttpSigError
+Identity InvalidInputError KeyPair OpenEntityError REGISTRY_ERROR_CODES RegistryError SPEC TrustReport VerificationError
+a2a_extension adopt agent_card base58btc_decode base58btc_encode build_did_document build_openentity_json build_presentation
+build_rotation canonical_hash canonicalize check_stamp check_timestamp clear_trust_cache default_resolver
+did_key_from_public_key did_web_resolver dispute eip712_digest find generate_key_pair inclusion_proof key_pair_from_seed leaf_hash
+log_leaf merkle_root mint_stamp node_hash normalize_eid now_seconds parse_json present public_key_from_did_key random_nonce
+recover_eip712 record record_entry_hash rotate sha256 sha256_hex sign_attestation sign_object sign_proof sign_request
+sign_revocation successor_document trust validate verification_method_id verify_inclusion verify_note verify_object
+verify_presentation verify_request withdraw
+""".split()
+
+# In the TypeScript SDK only (camelCase there). Shrinks as the Python SDK gains them; never grows without a reason.
+TS_ONLY = {"build_declaration", "build_document", "checkpoint_body", "consistency_proof", "hash_data", "http_sig_base",
+           "key_pair_from_jwk", "note_vkey", "sign_note", "verify_consistency", "verify_proof"}
+# In the Python SDK only.
+PY_ONLY = {"Identity", "InvalidInputError", "KeyPair", "REGISTRY_ERROR_CODES", "RegistryError", "TrustReport", "VerificationError",
+           "canonical_hash", "default_resolver"}
+
+
+def test_the_public_names_are_pinned():
+    assert sorted(openentity.__all__) == sorted(SNAPSHOT)
+    for name in openentity.__all__:
+        assert hasattr(openentity, name), name
+
+
+def ts_names():
+    names = set()
+    for block in re.findall(r"export \{([^}]*)\}", TS_INDEX.read_text()):
+        names |= {n.strip() for n in block.split(",") if n.strip() and not n.strip().startswith("type ")}
+    snake = lambda n: n if n[0].isupper() or "_" in n else re.sub(r"(?<=[a-z0-9])([A-Z])", lambda m: "_" + m.group(1).lower(), n).lower()
+    return {snake(n).replace("open_entity", "openentity") for n in names}
+
+
+def test_the_two_sdks_match_up_to_naming():
+    ts, py = ts_names(), set(openentity.__all__)
+    assert ts - py == TS_ONLY
+    assert py - ts == PY_ONLY
+
+
+def test_errors_form_one_hierarchy():
+    for cls in (openentity.RegistryError, openentity.HttpSigError, openentity.InvalidInputError, openentity.VerificationError):
+        assert issubclass(cls, openentity.OpenEntityError)
+    assert issubclass(openentity.InvalidInputError, ValueError) and issubclass(openentity.VerificationError, ValueError)
+    e = openentity.RegistryError(409, {"error": "entity_exists", "message": "x"})
+    assert (e.code, e.status) == ("entity_exists", 409) and e.code in openentity.REGISTRY_ERROR_CODES
+    assert openentity.RegistryError(502, "<html>").code == "registry_error"
+    assert openentity.HttpSigError("bad_signature").code == "bad_signature"
+    with pytest.raises(openentity.OpenEntityError) as raised:
+        core.base58btc_decode("0OIl")
+    assert raised.value.code == "invalid_input"
+
+
+def test_the_0_5_names_still_work():
+    assert core.b58encode is core.base58btc_encode and core.now is core.now_seconds and core.nonce is core.random_nonce
+    assert core.did_key is core.did_key_from_public_key and core.public_from_did_key is core.public_key_from_did_key
+    assert core.verification_method is core.verification_method_id
+    assert issuer.attestation is issuer.sign_attestation and issuer.revocation is issuer.sign_revocation
+    assert issuer.did_document is issuer.build_did_document and issuer.openentity_json is issuer.build_openentity_json
+    assert openentity.RegistryError is openentity.client.RegistryError and openentity.HttpSigError is openentity.httpsig.HttpSigError
+
+
+def test_the_error_codes_match_the_registry_and_the_ts_sdk():
+    registry = set(re.findall(r'fail\(\d+,\s*"([a-z_0-9]+)"', "".join(p.read_text() for p in (TS_INDEX.parents[3] / "registry" / "src").glob("*.ts"))))
+    assert registry <= openentity.REGISTRY_ERROR_CODES
+    ts = set(re.findall(r'"([a-z_0-9]+)"', (TS_INDEX.parent / "errors.ts").read_text().split("export type LocalErrorCode")[0]))
+    assert ts == openentity.REGISTRY_ERROR_CODES

{openentity-0.5.4 → openentity-0.6.0}/uv.lock

@@ -699,7 +699,7 @@ wheels = [
 
 [[package]]
 name = "openentity"
-version = "0.5.4"
+version = "0.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },

openentity-0.5.4/openentity/__init__.py

@@ -1,8 +0,0 @@
-from .client import adopt, dispute, find, present, record, rotate, withdraw  # noqa: F401
-from .core import *  # noqa: F401,F403
-from . import issuer  # noqa: F401
-from .httpsig import HttpSigError, sign_request, verify_request  # noqa: F401
-from .identity import Identity  # noqa: F401
-from .report import TrustReport, trust  # noqa: F401
-
-__version__ = "0.5.4"