openentity 0.1.0__tar.gz

openentity-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.astro/
+.wrangler/
+.dev.vars
+.env*
+!.env.example
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.DS_Store
+coverage/
+.claude/

openentity-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,21 @@
+# 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/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-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-0.1.0/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)