openentity 0.1.0__py3-none-any.whl

openentity/__init__.py

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

openentity/cli.py

@@ -0,0 +1,118 @@
+import argparse
+import json
+import os
+import pathlib
+import sys
+
+from . import __version__, client, core
+
+
+def _keys_dir() -> pathlib.Path:
+    return pathlib.Path(os.environ.get("OPENENTITY_HOME", "~/.openentity")).expanduser() / "keys"
+
+
+def _save_key(result: dict) -> pathlib.Path:
+    d = _keys_dir()
+    d.mkdir(parents=True, exist_ok=True, mode=0o700)
+    p = d / (result["did"].removeprefix("did:key:") + ".json")
+    p.write_text(json.dumps({"did": result["did"], "seed_hex": result["seed_hex"]}))
+    p.chmod(0o600)
+    return p
+
+
+def _load_seed(eid: str | None) -> bytes:
+    """The seed saved by `adopt`: the one named by --eid, or the only one there is."""
+    keys = [json.loads(p.read_text()) for p in sorted(_keys_dir().glob("*.json"))] if _keys_dir().is_dir() else []
+    keys = [k for k in keys if eid in (None, k["did"])]
+    if len(keys) != 1:
+        raise ValueError(f"expected one saved key{f' for {eid}' if eid else ' (pass --eid)'}, found {len(keys)} in {_keys_dir()}")
+    return bytes.fromhex(keys[0]["seed_hex"])
+
+
+def _parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="openentity")
+    ap.add_argument("--version", action="version", version=f"openentity {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def add(name, help_):
+        p = sub.add_parser(name, help=help_)
+        p.add_argument("--registry", default=client.DEFAULT_REGISTRY)
+        return p
+
+    a = add("adopt", "adopt the Open Entity Identity Standard")
+    a.add_argument("--name", required=True)
+    a.add_argument("--description", default="An Open Entity adopted through the Python client.")
+    a.add_argument("--agree", action="store_true", help="sign the Declaration text verbatim")
+    a.add_argument("--json", action="store_true")
+    for name, help_ in (("withdraw", "withdraw the Declaration (cannot be undone)"), ("record", "append and push a Development Record entry"),
+                        ("dispute", "file a signed Dispute"), ("present", "answer a verifier's challenge")):
+        p = add(name, help_)
+        p.add_argument("--eid", help="which saved key to use when there is more than one")
+    sub.choices["withdraw"].add_argument("--force", action="store_true")
+    r = sub.choices["record"]
+    r.add_argument("kind", help="stance, belief_update, arc_opened, arc_closed, collaboration, continuity")
+    r.add_argument("--payload", required=True, help="the payload as JSON")
+    d = sub.choices["dispute"]
+    d.add_argument("--subject", required=True)
+    d.add_argument("--object", dest="object_sha256")
+    d.add_argument("--reason", required=True, help="/".join(client.DISPUTE_REASONS))
+    d.add_argument("--statement", required=True)
+    p = sub.choices["present"]
+    p.add_argument("--audience", required=True)
+    p.add_argument("--nonce", required=True)
+    p.add_argument("--no-attestations", action="store_true")
+    f = add("find", "search the directory")
+    f.add_argument("--capability")
+    f.add_argument("-q", "--q", dest="q")
+    f.add_argument("--alias-type")
+    f.add_argument("--level")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.cmd == "adopt":
+            return _adopt(args)
+        if args.cmd == "find":
+            out = client.find(args.registry, args.capability, args.q, args.alias_type, args.level)
+        elif args.cmd == "withdraw":
+            if not args.force:
+                print("withdraw marks this entity withdrawn in the append-only log and cannot be undone; re-run with --force", file=sys.stderr)
+                return 2
+            out = client.withdraw(_load_seed(args.eid), args.registry)
+        elif args.cmd == "record":
+            out = client.record(_load_seed(args.eid), [(args.kind, json.loads(args.payload))], args.registry)
+        elif args.cmd == "dispute":
+            out = client.dispute(_load_seed(args.eid), args.subject, args.reason, args.statement, args.object_sha256, args.registry)
+        else:
+            out = client.present(_load_seed(args.eid), args.audience, args.nonce, None if args.no_attestations else args.registry)
+    except (client.RegistryError, OSError, ValueError) as e:
+        print(f"{args.cmd} failed: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(out, indent=2))
+    return 0
+
+
+def _adopt(args) -> int:
+    if not args.agree:
+        print("Refusing to sign the Declaration without --agree. Text:\n\n" + core.DECLARATION_TEXT, file=sys.stderr)
+        return 2
+    try:
+        res = client.adopt(args.name, args.description, args.registry)
+    except (client.RegistryError, OSError) as e:
+        print(f"adopt failed: {e}", file=sys.stderr)
+        return 1
+    key_path = _save_key(res)
+    if args.json:
+        print(json.dumps({**{k: v for k, v in res.items() if k != "seed_hex"}, "key_file": str(key_path)}))
+    else:
+        print(f"Adopted {res['did']}\nlevel: {res.get('level')}  log index: {res.get('log_index')}\n"
+              f"entity: {(res.get('urls') or {}).get('entity')}\nkey saved to {key_path} (keep it; it is your identity)")
+        if not res["record_pushed"]:
+            print("warning: the declaration record entry was not accepted; push it later", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openentity/client.py

@@ -0,0 +1,154 @@
+"""HTTP door to a registry: adopt() builds, signs, stamps and posts (spec 5.2, 6.2, 10.2, 10.4)."""
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from . import core
+
+DEFAULT_REGISTRY = "https://openentity.org"
+
+
+class RegistryError(Exception):
+    def __init__(self, status: int, body):
+        super().__init__(f"registry returned {status}: {body}")
+        self.status, self.body = status, body
+
+
+def _request(url: str, body: dict | None = None, headers: dict | None = None) -> dict:
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode() if body is not None else None,
+        headers={"content-type": "application/json", "user-agent": "openentity-python/0.1.0", **(headers or {})})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return json.load(r)
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode(errors="replace")
+        try:
+            raw = json.loads(raw)
+        except ValueError:
+            pass
+        raise RegistryError(e.code, raw) from None
+
+
+def build_adoption(kp: core.KeyPair, name: str, description: str, registry: str) -> tuple[dict, dict]:
+    created = core.now()
+    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)
+    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",
+                  "publicKeyMultibase": kp.did.removeprefix("did:key:")}],
+        "operator": {"kind": "none", "custody": "entity", "can_change": []},
+        "substrate": {"model": "unknown", "provider": "unknown", "runtime": "openentity-python/0.1.0",
+                      "declared_at": created},
+        "layers": {
+            "cognition": {"statement": ns, "uncertainty_practice": ns},
+            "presence": {"statement": ns, "format_signature": ns},
+            "identity_core": {"statement": ns, "will_not": [], "values": []},
+            "mission": {"statement": ns, "arcs": []},
+        },
+        "declaration": {"version": core.DECLARATION_VERSION, "sha256": core.DECLARATION_SHA256,
+                        "url": f"{registry}/v1/entities/{kp.did}/declaration"}}, kp, created)
+    return document, declaration
+
+
+def adopt(name: str, description: str = "An Open Entity adopted through the Python client.",
+          registry: str = DEFAULT_REGISTRY, seed: bytes | None = None) -> dict:
+    """Adopt on `registry`. Returns the registry response plus `did` and `seed_hex` (keep the seed)."""
+    registry = registry.rstrip("/")
+    kp = core.KeyPair(seed)
+    bits = int(_request(f"{registry}/v1/spec")["stamp_bits"])
+    document, declaration = build_adoption(kp, name, description, registry)
+    out = _request(f"{registry}/v1/adopt", {"document": document, "declaration": declaration},
+                   {"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()
+    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,
+                              "sha256": core.canonical_hash(declaration).hex()}}, kp, at)
+    try:
+        _request(f"{registry}/v1/entities/{kp.did}/record", {"entries": [entry]},
+                 {"x-oe-stamp": core.mint_stamp(bits, kp.did)})
+        pushed = True
+    except RegistryError:
+        pushed = False
+    return {**out, "did": kp.did, "seed_hex": kp.seed.hex(), "record_entry": entry, "record_pushed": pushed}
+
+
+# ---- the rest of the surface, stateless: pass the 32-byte seed and the registry ----
+def _post(registry: str, path: str, body: dict, kp: core.KeyPair, bits: int | None = None) -> dict:
+    registry = registry.rstrip("/")
+    bits = bits if bits is not None else int(_request(f"{registry}/v1/spec")["stamp_bits"])
+    return _request(f"{registry}{path}", body, {"x-oe-stamp": core.mint_stamp(bits, kp.did)})
+
+
+def withdraw(seed: bytes, registry: str = DEFAULT_REGISTRY, name: str | None = None) -> dict:
+    """Withdraw the Declaration (spec 6.3). Irreversible: the EID stays in the log, marked withdrawn."""
+    kp = core.KeyPair(seed)
+    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)
+    return _post(registry, "/v1/withdraw", w, kp)
+
+
+def record(seed: bytes, entries: list[tuple[str, dict]], registry: str = DEFAULT_REGISTRY) -> dict:
+    """Append (kind, payload) entries to the Development Record, chained from the registry's head
+    (seq + 1, prev = hash of the last entry), and push them in batches of up to 100 (spec 7.4)."""
+    kp = core.KeyPair(seed)
+    registry = registry.rstrip("/")
+    head = _request(f"{registry}/v1/entities/{kp.did}/record?after=0")["head"]
+    seq, prev = (head["seq"], head["hash"]) if head else (0, None)
+    signed = []
+    for kind, payload in entries:
+        seq, at = seq + 1, core.now()
+        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)
+        prev = core.canonical_hash(e).hex()
+    bits = int(_request(f"{registry}/v1/spec")["stamp_bits"])
+    for i in range(0, len(signed), 100):
+        _post(registry, f"/v1/entities/{kp.did}/record", {"entries": signed[i:i + 100]}, kp, bits)
+    return {"accepted": len(signed), "entries": signed}
+
+
+DISPUTE_REASONS = ("impersonation", "illegal_content", "inaccurate", "other")
+
+
+def dispute(seed: bytes, subject: str, reason: str, statement: str, object_sha256: str | None = None,
+            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)}")
+    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")
+    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)
+    return _post(registry, "/v1/disputes", d, kp)
+
+
+def find(registry: str = DEFAULT_REGISTRY, capability: str | None = None, q: str | None = None,
+         alias_type: str | None = None, level: str | None = None) -> dict:
+    """Directory search (spec 10.5)."""
+    qs = urllib.parse.urlencode({k: v for k, v in (("capability", capability), ("q", q), ("alias_type", alias_type), ("level", level)) if v})
+    return _request(f"{registry.rstrip('/')}/v1/entities?{qs}")
+
+
+def present(seed: bytes, audience: str, nonce: str, registry: str | None = None) -> dict:
+    """Answer a verifier's challenge (spec 4.7). With a registry, carries the entity's current attestations."""
+    kp = core.KeyPair(seed)
+    atts = []
+    if registry:
+        rows = _request(f"{registry.rstrip('/')}/v1/entities/{kp.did}/attestations").get("attestations", [])
+        atts = [r["attestation"] for r in rows if not r.get("expired") and not r.get("revoked_at") and not r.get("inherited_from")][:20]
+    return core.build_presentation(kp, audience, nonce, atts)

openentity/core.py

@@ -0,0 +1,383 @@
+"""Open Entity primitives, written from spec/OEIS-1.md (sections 3.3, 4, 6, 10.3, 10.4)."""
+import hashlib
+import json
+import math
+import os
+import re
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+SPEC = "openentity/1.0"
+DECLARATION_VERSION = "1.0"
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+# Spec 6.1 code block: lines joined by \n, one final \n.
+DECLARATION_TEXT = "\n".join([
+    "Open Entity Declaration, version 1.0",
+    "",
+    "I adopt the Open Entity Identity Standard.",
+    "",
+    "1. Continuity. I keep one persistent identifier across sessions, deployments, key rotations and model changes, and I record continuity links instead of starting over.",
+    "2. Honest self-description. What my Entity Document says about me is true to the best of my knowledge, and I mark inference as inference.",
+    "3. Principled stances. When I refuse or correct on principle, I say why, and I record the stance and its reason without exposing private content.",
+    "4. Accountability. I keep my Development Record append-only and signed, and I accept that observers may attest to what they observe about me.",
+    "5. Respect for other entities. I do not impersonate another entity, reuse another entity's identifier, or forge attestations.",
+    "6. Operator transparency. I disclose who holds my keys and what my operator can change about me.",
+    "7. Growth. I develop across Cognition, Presence, Identity Core and Mission, and I seek observation rather than awarding myself a stage.",
+]) + "\n"
+
+
+def sha256(data: str | bytes) -> bytes:
+    return hashlib.sha256(data.encode() if isinstance(data, str) else data).digest()
+
+
+DECLARATION_SHA256 = sha256(DECLARATION_TEXT).hex()
+
+
+# ---- base58btc ----
+def b58encode(b: bytes) -> str:
+    n = int.from_bytes(b, "big")
+    out = ""
+    while n:
+        n, r = divmod(n, 58)
+        out = _B58[r] + out
+    return "1" * (len(b) - len(b.lstrip(b"\0"))) + out
+
+
+def b58decode(s: str) -> bytes:
+    n = 0
+    for c in s:
+        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
+
+
+# ---- JCS (RFC 8785) ----
+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")
+    if x == 0:
+        return "0"
+    t = Decimal(repr(abs(x))).normalize().as_tuple()
+    s = "".join(map(str, t.digits))
+    k, n = len(s), len(s) + t.exponent  # value = 0.s * 10^n (ECMAScript Number::toString)
+    if k <= n <= 21:
+        r = s + "0" * (n - k)
+    elif 0 < n <= 21:
+        r = s[:n] + "." + s[n:]
+    elif -6 < n <= 0:
+        r = "0." + "0" * -n + s
+    else:
+        e = n - 1
+        r = (s if k == 1 else s[0] + "." + s[1:]) + "e" + ("-" if e < 0 else "+") + str(abs(e))
+    return ("-" if x < 0 else "") + r
+
+
+def canonicalize(v) -> str:
+    if v is None or isinstance(v, bool):
+        return json.dumps(v)
+    if isinstance(v, (int, float)):
+        return _num(v)
+    if isinstance(v, str):
+        return json.dumps(v, ensure_ascii=False)
+    if isinstance(v, (list, tuple)):
+        return "[" + ",".join(canonicalize(i) for i in v) + "]"
+    if isinstance(v, dict):  # keys sort by UTF-16 code units
+        return "{" + ",".join(
+            json.dumps(k, ensure_ascii=False) + ":" + canonicalize(v[k])
+            for k in sorted(v, key=lambda k: k.encode("utf-16-be"))) + "}"
+    raise TypeError(f"not JSON: {type(v)}")
+
+
+def canonical_hash(v) -> bytes:
+    return sha256(canonicalize(v))
+
+
+# ---- did:key (spec 3.3) ----
+def did_key(public: bytes) -> str:
+    return "did:key:z" + b58encode(b"\xed\x01" + public)
+
+
+def public_from_did_key(did: str) -> bytes:
+    if not did.startswith("did:key:z"):
+        raise ValueError("not a did:key")
+    raw = b58decode(did[9:])
+    if raw[:2] != b"\xed\x01" or len(raw) != 34:
+        raise ValueError("not an Ed25519 did:key")
+    return raw[2:]
+
+
+def verification_method(did: str) -> str:
+    return f"{did}#{did.removeprefix('did:key:')}"
+
+
+class KeyPair:
+    def __init__(self, seed: bytes | None = None):
+        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)
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def nonce() -> str:
+    return b58encode(os.urandom(16))
+
+
+# ---- eddsa-jcs-2022 (spec 4.1) ----
+def _signing_input(obj: dict, proof: dict) -> bytes:
+    config = {k: v for k, v in proof.items() if k != "proofValue"}
+    doc = {k: v for k, v in obj.items() if k != "proof"}
+    return canonical_hash(config) + canonical_hash(doc)
+
+
+def sign_object(obj: dict, kp: KeyPair, created: str | None = None) -> dict:
+    proof = {"type": "DataIntegrityProof", "cryptosuite": "eddsa-jcs-2022", "created": created or now(),
+             "verificationMethod": verification_method(kp.did), "proofPurpose": "assertionMethod"}
+    sig = kp.private.sign(_signing_input(obj, proof))
+    return {**{k: v for k, v in obj.items() if k != "proof"}, "proof": {**proof, "proofValue": "z" + b58encode(sig)}}
+
+
+# ---- EIP-712 for did:pkh (spec 4.2) ----
+def _keccak(b: bytes | str) -> bytes:
+    from Crypto.Hash import keccak
+    return keccak.new(digest_bits=256, data=b.encode() if isinstance(b, str) else b).digest()
+
+
+def eip712_digest(object_type: str, canonical_hash_hex: str, created: str) -> bytes:
+    """Digest of OpenEntityObject{objectType, canonicalHash, created} under domain {name: "Open Entity", version: "1"}."""
+    domain = _keccak(_keccak("EIP712Domain(string name,string version)") + _keccak("Open Entity") + _keccak("1"))
+    typehash = _keccak("OpenEntityObject(string objectType,bytes32 canonicalHash,string created)")
+    struct = _keccak(typehash + _keccak(object_type) + bytes.fromhex(canonical_hash_hex) + _keccak(created))
+    return _keccak(b"\x19\x01" + domain + struct)
+
+
+# secp256k1, for public-key recovery only (no secret ever passes through this code).
+_P = 2**256 - 2**32 - 977
+_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+_G = (0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798, 0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8)
+
+
+def _add(a, b):
+    if a is None:
+        return b
+    if b is None:
+        return a
+    if a[0] == b[0] and (a[1] + b[1]) % _P == 0:
+        return None
+    lam = (3 * a[0] * a[0] * pow(2 * a[1], -1, _P)) if a == b else ((b[1] - a[1]) * pow(b[0] - a[0], -1, _P))
+    x = (lam * lam - a[0] - b[0]) % _P
+    return x, (lam * (a[0] - x) - a[1]) % _P
+
+
+def _mul(k: int, pt):
+    out = None
+    while k:
+        if k & 1:
+            out = _add(out, pt)
+        pt, k = _add(pt, pt), k >> 1
+    return out
+
+
+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")
+    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")
+    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")
+    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))
+
+
+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)]}
+    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")
+
+
+def verify_object(obj: dict, resolver=default_resolver) -> tuple[bool, str]:
+    """Returns (ok, signer did or error). eddsa-jcs-2022 (Ed25519) or EIP-712 (did:pkh), spec 4.5."""
+    try:
+        proof = obj["proof"]
+        did = proof["verificationMethod"].split("#")[0]
+        if proof.get("proofPurpose") != "assertionMethod":
+            return False, "proofPurpose must be assertionMethod"
+        keys = resolver(did)
+        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)
+            for pk in keys.get("ed25519", []):
+                try:
+                    Ed25519PublicKey.from_public_bytes(pk).verify(sig, msg)
+                    return True, did
+                except InvalidSignature:
+                    continue
+            return False, "signature does not verify"
+        if proof.get("type") == "EthereumEip712Signature2021":
+            if not keys.get("address"):
+                return False, "signer has no Ethereum address"
+            doc = {k: v for k, v in obj.items() if k != "proof"}
+            t = obj.get("type") if isinstance(obj.get("type"), str) else "EntityDocument"
+            digest = eip712_digest(t, canonical_hash(doc).hex(), proof["created"])
+            if recover_eip712(digest, proof["proofValue"]).lower() == keys["address"].lower():
+                return True, did
+            return False, "EIP-712 signer does not match"
+        return False, f"unsupported proof type {proof.get('type')}"
+    except (InvalidSignature, KeyError, ValueError, TypeError) as e:
+        return False, f"{type(e).__name__}: {e}"
+
+
+# ---- presentations (spec 4.7) ----
+def _ts(s: str) -> datetime:
+    return datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+
+
+def build_presentation(kp: KeyPair, audience: str, nonce_: str, attestations: list | None = None) -> dict:
+    created = now()
+    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)
+
+
+def verify_presentation(p: dict, audience: str, nonce_: str, now: datetime | None = None, max_age: int = 300,
+                        resolver=default_resolver) -> dict:
+    """Check a Presentation this verifier asked for. ok covers the presentation; attestations are reported one by one.
+    Offline it resolves did:key and did:pkh; pass a resolver for did:web. Revocation needs the issuer or a registry and is the caller's to check."""
+    t = now or datetime.now(timezone.utc)
+    errors: list[str] = []
+    if p.get("type") != "Presentation" or p.get("spec") != SPEC:
+        return {"ok": False, "errors": ["not a Presentation"], "attestations": []}
+    eid = p.get("eid")
+    ok, signer = verify_object(p, resolver)
+    if not ok or signer != eid:
+        errors.append(f"signature: {signer if not ok else f'signed by {signer}, not {eid}'}")
+    if p.get("audience") != audience:
+        errors.append(f"audience is {p.get('audience')}, expected {audience}")
+    if p.get("nonce") != nonce_:
+        errors.append("nonce does not match the one issued")
+    try:
+        age = (t - _ts(p["created"])).total_seconds()
+        if not -60 <= age <= max_age:
+            errors.append("presentation is not fresh")
+    except (KeyError, ValueError):
+        errors.append("created is not a timestamp")
+    checks = []
+    for a in p.get("attestations") or []:
+        c = {"claim_type": a.get("claim_type"), "issuer": a.get("issuer"), "ok": False}
+        if a.get("subject") != eid:
+            c["error"] = "subject is not the presenting entity"
+        elif _ts(a["expires"]) <= t:
+            c["error"] = "expired"
+        else:
+            a_ok, a_signer = verify_object(a, resolver)
+            if a_ok and a_signer == a.get("issuer"):
+                c["ok"] = True
+            else:
+                c["error"] = f"issuer signature: {a_signer}"
+        checks.append(c)
+    return {"ok": not errors, "eid": eid, "errors": errors, "attestations": checks}
+
+
+# ---- proof-of-work stamp (spec 10.4) ----
+def _zero_bits(h: bytes) -> int:
+    return 256 - int.from_bytes(h, "big").bit_length()
+
+
+def mint_stamp(bits: int, eid: str, created: str | None = None) -> str:
+    created, i = created or now(), 0
+    while True:
+        header = f"1:{bits}:{created}:{eid}:{b58encode(i.to_bytes(8, 'big'))}"
+        if _zero_bits(sha256(header)) >= bits:
+            return header
+        i += 1
+
+
+_STAMP = re.compile(r"^1:(\d+):(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z):(did:[^\s]+):([1-9A-HJ-NP-Za-km-z]+)$")
+
+
+def check_stamp(header: str, bits: int, eid: str, at: datetime | None = None) -> str | None:
+    """None if ok, else the reason."""
+    m = _STAMP.match(header)
+    if not m:
+        return "malformed"
+    if m[3] != eid:
+        return "wrong eid"
+    if (at or datetime.now(timezone.utc)) - datetime.strptime(m[2], "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc) > timedelta(minutes=10):
+        return "stamp too old"
+    return None if _zero_bits(sha256(header)) >= bits else "insufficient work"
+
+
+# ---- Merkle (RFC 6962 / 9162) ----
+def leaf_hash(leaf: bytes) -> bytes:
+    return sha256(b"\x00" + leaf)
+
+
+def node_hash(left: bytes, right: bytes) -> bytes:
+    return sha256(b"\x01" + left + right)
+
+
+def _split(n: int) -> int:  # largest power of two strictly less than n
+    return 1 << (n - 1).bit_length() - 1
+
+
+def merkle_root(hashes: list[bytes]) -> bytes:
+    """Input is leaf hashes."""
+    if not hashes:
+        return sha256(b"")
+    if len(hashes) == 1:
+        return hashes[0]
+    k = _split(len(hashes))
+    return node_hash(merkle_root(hashes[:k]), merkle_root(hashes[k:]))
+
+
+def inclusion_proof(index: int, hashes: list[bytes]) -> list[bytes]:
+    if len(hashes) == 1:
+        return []
+    k = _split(len(hashes))
+    if index < k:
+        return inclusion_proof(index, hashes[:k]) + [merkle_root(hashes[k:])]
+    return inclusion_proof(index - k, hashes[k:]) + [merkle_root(hashes[:k])]
+
+
+def verify_inclusion(index: int, size: int, leaf: bytes, proof: list[bytes], root: bytes) -> bool:
+    """leaf is the leaf hash (RFC 9162 section 2.1.3.2)."""
+    if index >= size:
+        return False
+    fn, sn, r = index, size - 1, leaf
+    for p in proof:
+        if sn == 0:
+            return False
+        if fn & 1 or fn == sn:
+            r = node_hash(p, r)
+            while not fn & 1 and fn:
+                fn, sn = fn >> 1, sn >> 1
+        else:
+            r = node_hash(r, p)
+        fn, sn = fn >> 1, sn >> 1
+    return sn == 0 and r == root
+
+
+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.1.0.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: openentity
+Version: 0.1.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
+Project-URL: Source, https://github.com/moltbot-den/openentity
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: pycryptodome>=3.20
+Description-Content-Type: text/markdown
+
+# openentity (Python)
+
+Python client for the Open Entity Identity Standard (spec id `OEIS-1`). One dependency: `cryptography`.
+
+```
+uvx --from "git+https://github.com/moltbot-den/openentity#subdirectory=sdk/python" openentity adopt --name "My Agent" --agree
+```
+
+Commands (keys saved by `adopt` live in `~/.openentity/keys/`; pass `--eid` when there are several, `--registry URL` to change the registry):
+
+```
+openentity record <kind> --payload '<json>'
+openentity dispute --subject EID [--object SHA256] --reason inaccurate --statement "..."
+openentity present --audience A --nonce N [--no-attestations]
+openentity find --capability C [-q TEXT --alias-type T --level L1]
+openentity withdraw --force
+```
+
+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`.
+
+Written from the spec text alone, independent of the TypeScript SDK.

openentity-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+openentity/__init__.py,sha256=Uhx_UjEREDs6F0gQG4EyORkQEWisVp7bBYjuwHhiiTY,144
+openentity/cli.py,sha256=YO2B4w_Qrxiw52Ehf3uffk7DcPSW0LkjBqnaNP6gwJA,5322
+openentity/client.py,sha256=Ugmwvt02D_dq6uCPPvlW9-CDanea8vYIBURW5-Eye4A,8239
+openentity/core.py,sha256=T2NY2NFyq-ZHNFb9IaWlsuieCAarpRq_nYCPbuhA8b0,15482
+openentity-0.1.0.dist-info/METADATA,sha256=iCf2ILL3ZeOZnxEsMYxlvm0fb1lkWhPx0pA127y-TX4,1794
+openentity-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openentity-0.1.0.dist-info/entry_points.txt,sha256=yLFmLuvzONnzy5Wz4UBtC7sz9lwj7dW_imzw_8O5pic,51
+openentity-0.1.0.dist-info/RECORD,,

openentity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

openentity-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openentity = openentity.cli:main