sdata 1.5.0__py3-none-any.whl

sdata/did/__init__.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""``sdata.did`` – Decentralized Identifiers (DID) & Verifiable Credentials (VC).
+
+Dieses Subpackage bündelt eine schlanke, **pure-Python** Umsetzung gängiger
+SSI-Bausteine (Self-Sovereign Identity) rund um Ed25519:
+
+============================  ====================================================
+Bereich                       Modul / Funktionen
+============================  ====================================================
+Schlüssel (Ed25519/JWK)       :mod:`~sdata.did.keys` – :func:`gen_ed25519_jwk`, :func:`pub_from_priv_jwk`
+JWK / did:key / Thumbprint    :mod:`~sdata.did.utils_didkey`
+JOSE / Compact-JWS (EdDSA)    :mod:`~sdata.did.jose` – :func:`sign_compact`, :func:`verify_compact`
+VC / VP ausstellen            :mod:`~sdata.did.issue_vc` – :func:`issue_vc`, :func:`make_vp`
+VC / VP verifizieren          :mod:`~sdata.did.verify_vp` – :func:`verify_presentation`
+did:web                       :mod:`~sdata.did.did_web` – :func:`build_did_document`, :func:`resolve_did_web`
+did:key                       :mod:`~sdata.did.utils_didkey` – :func:`did_key_from_jwk_ed25519`, :func:`pub_jwk_from_did_key`
+did:peer:4                    :mod:`~sdata.did.did_peer4` – :func:`did_peer4_from_payload`, :func:`resolve_long_form`
+did:github                    :mod:`~sdata.did.did_github` – :func:`resolve_did_github`
+============================  ====================================================
+
+Unterstützte Standards: W3C DID Core, did:web, did:key, did:peer:4,
+W3C Verifiable Credentials (JWT-VC), JOSE/JWS (RFC 7515), EdDSA (RFC 8037),
+JWK-Thumbprint (RFC 7638).
+
+Installation
+------------
+Krypto (Ed25519) und base58btc sind **abhängigkeitsfrei** (reine
+Standardbibliothek) – siehe :mod:`~sdata.did.eddsa` und
+:mod:`~sdata.did.base58btc`. Auch die HTTP-Auflösung von ``did:web`` /
+``did:github`` läuft ohne externe Abhängigkeit: :mod:`~sdata.did._http` nutzt
+``requests`` falls installiert, sonst ``urllib`` (Standardbibliothek)::
+
+    pip install "sdata"          # voll funktionsfähig (urllib-HTTP-Backend)
+    pip install "sdata[http]"    # optional: 'requests' als HTTP-Backend
+
+.. warning::
+   **Sicherheit / SOTA-Hinweis.** Der produktive Krypto-Pfad nutzt die
+   pure-Python-Ed25519-Implementierung in :mod:`sdata.did.ed25519` (über den
+   Adapter :mod:`sdata.did.eddsa`). Sie ist abhängigkeitsfrei, aber **nicht
+   garantiert constant-time** und damit potenziell anfällig für
+   Timing-Seitenkanäle – genau wie das zuvor genutzte ``python-ecdsa``
+   (ebenfalls pure Python). Für hochsensible Umgebungen ein libsodium-Backend
+   (PyNaCl) oder ``cryptography`` (OpenSSL) erwägen. Korrektheit ist gegen die
+   offiziellen RFC-8032-Testvektoren abgesichert.
+
+Beispiel
+--------
+::
+
+    from sdata.did import (gen_ed25519_jwk, pub_from_priv_jwk,
+                           did_key_from_jwk_ed25519, sign_compact, verify_compact)
+
+    jwk = gen_ed25519_jwk()
+    did = did_key_from_jwk_ed25519(pub_from_priv_jwk(jwk))
+    kid = f"{did}#{did.split(':', 2)[2]}"
+    jws = sign_compact({"hello": "world"}, jwk, kid=kid, typ="JWT")
+    assert verify_compact(jws, pub_from_priv_jwk(jwk))["hello"] == "world"
+"""
+from __future__ import annotations
+
+import importlib
+
+# Lazy-Loading (PEP 562): Submodule werden erst beim Zugriff importiert. Vorteile:
+#   * ``python -m sdata.did.<modul>`` löst keine runpy-Doppelimport-Warnung aus,
+#   * ``import sdata.did`` ist leichtgewichtig – schwerere Submodule (z. B.
+#     ``did_web`` mit dem HTTP-Backend) werden erst geladen, wenn eine sie
+#     nutzende Funktion tatsächlich angefasst wird.
+# Mapping: exportierter Name -> "submodul"  oder  ("submodul", "originalname").
+_EXPORTS = {
+    # Fehler
+    "DidError": "errors", "EncodingError": "errors",
+    "ResolutionError": "errors", "VerificationError": "errors",
+    # Schlüssel / JWK / did:key
+    "gen_ed25519_jwk": "keys", "pub_from_priv_jwk": "keys",
+    "b64url": "utils_didkey", "b64url_decode": "utils_didkey",
+    "jwk_thumbprint_rfc7638": "utils_didkey",
+    "did_key_from_jwk_ed25519": "utils_didkey",
+    "did_key_fragment_from_jwk": "utils_didkey",
+    "pub_jwk_from_did_key": "utils_didkey",
+    "kid_for_did_web": "utils_didkey", "kid_for_did_key": "utils_didkey",
+    # JOSE / JWS
+    "sign_compact": "jose", "verify_compact": "jose", "decode_header": "jose",
+    # VC / VP
+    "issue_vc": "issue_vc", "make_vp": "issue_vc", "sign_compact_jws": "issue_vc",
+    "verify_presentation": "verify_vp", "jws_header": "verify_vp",
+    "jws_verify": "verify_vp", "resolve_public_jwk_for_kid": "verify_vp",
+    # DID-Methoden
+    "build_did_document": "did_web", "did_web_to_url": "did_web",
+    "resolve_did_web": ("did_web", "resolve_public_jwk_for_kid"),
+    "did_peer4_from_payload": "did_peer4", "resolve_long_form": "did_peer4",
+    "resolve_did_github": "did_github", "parse_did_github": "did_github",
+}
+
+
+def __getattr__(name):
+    """Importiere das zugehörige Submodul beim ersten Zugriff (PEP 562)."""
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(
+            "module {!r} has no attribute {!r}".format(__name__, name))
+    modname, attrname = target if isinstance(target, tuple) else (target, name)
+    mod = importlib.import_module("." + modname, __name__)
+    value = getattr(mod, attrname)
+    globals()[name] = value  # cachen, damit __getattr__ nur einmal feuert
+    return value
+
+
+def __dir__():
+    return sorted(__all__)
+
+
+__all__ = [
+    # Fehler
+    "DidError", "EncodingError", "ResolutionError", "VerificationError",
+    # Schlüssel / JWK / did:key
+    "gen_ed25519_jwk", "pub_from_priv_jwk",
+    "b64url", "b64url_decode", "jwk_thumbprint_rfc7638",
+    "did_key_from_jwk_ed25519", "did_key_fragment_from_jwk", "pub_jwk_from_did_key",
+    "kid_for_did_web", "kid_for_did_key",
+    # JOSE / JWS
+    "sign_compact", "verify_compact", "decode_header",
+    # VC / VP
+    "issue_vc", "make_vp", "sign_compact_jws",
+    "verify_presentation", "resolve_public_jwk_for_kid", "jws_header", "jws_verify",
+    # DID-Methoden
+    "build_did_document", "did_web_to_url", "resolve_did_web",
+    "did_peer4_from_payload", "resolve_long_form",
+    "resolve_did_github", "parse_did_github",
+]

sdata/did/_http.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""HTTP-GET mit optionalem ``requests``-Backend und ``urllib``-Fallback.
+
+Wenn ``requests`` installiert ist, wird es genutzt (gewohntes Verhalten,
+Connection-Pooling, certifi-CA-Bundle); andernfalls greift ein Fallback auf
+``urllib.request`` aus der Standardbibliothek. **Die TLS-Zertifikatsprüfung
+bleibt in beiden Fällen aktiv** (kein ``verify=False``).
+
+Damit ist ``requests`` für ``sdata.did`` rein optional – das Subpackage bleibt
+auch ohne die Abhängigkeit voll funktionsfähig.
+"""
+from __future__ import annotations
+
+import ssl
+import urllib.request
+import urllib.error
+from typing import Dict, Optional, Tuple
+
+try:  # bevorzugtes Backend, falls installiert
+    import requests as _requests
+except ImportError:  # pragma: no cover - abhängig vom Environment
+    _requests = None
+
+__all__ = ["http_get", "HttpError"]
+
+
+class HttpError(Exception):
+    """Transportfehler (DNS/Timeout/Verbindung) beim HTTP-GET – backend-neutral.
+
+    HTTP-Statuscodes (auch 4xx/5xx) sind *keine* ``HttpError`` – sie werden von
+    :func:`http_get` als ``status_code`` zurückgegeben.
+    """
+
+
+def http_get(url: str, headers: Optional[Dict[str, str]] = None,
+             timeout: float = 10.0) -> Tuple[int, str]:
+    """GET ``url`` und liefere ``(status_code, body_text)``.
+
+    Nutzt ``requests`` falls verfügbar, sonst ``urllib.request``.
+
+    Raises:
+        HttpError: bei Transportfehlern (DNS, Timeout, Verbindungsabbruch).
+    """
+    if _requests is not None:
+        return _get_requests(url, headers, timeout)
+    return _get_urllib(url, headers, timeout)
+
+
+def _get_requests(url, headers, timeout):
+    try:
+        resp = _requests.get(url, headers=headers, timeout=timeout)
+    except _requests.RequestException as exc:
+        raise HttpError(str(exc)) from exc
+    return resp.status_code, resp.text
+
+
+def _get_urllib(url, headers, timeout):
+    req = urllib.request.Request(url, headers=headers or {})
+    ctx = ssl.create_default_context()  # Zertifikats-/Hostname-Prüfung aktiv
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=ctx) as resp:
+            charset = resp.headers.get_content_charset() or "utf-8"
+            return resp.status, resp.read().decode(charset, "replace")
+    except urllib.error.HTTPError as exc:  # 4xx/5xx: Status, kein Transportfehler
+        return exc.code, exc.read().decode("utf-8", "replace")
+    except urllib.error.URLError as exc:   # DNS/Timeout/Verbindung
+        raise HttpError(str(exc)) from exc

sdata/did/base58btc.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""base58btc-Kodierung (Bitcoin-Alphabet) – reine Standardbibliothek.
+
+Ersetzt die externe ``base58``-Abhängigkeit im ``did``-Subpackage. Die
+Funktionen sind bewusst klein und an die multibase-/``did:key``-Nutzung
+angepasst (führende Nullbytes bleiben als ``1`` erhalten).
+
+Referenz: https://datatracker.ietf.org/doc/html/draft-msporny-base58
+"""
+from __future__ import annotations
+
+__all__ = ["b58encode", "b58decode"]
+
+# Bitcoin-/IPFS-Alphabet (ohne 0, O, I, l)
+_B58_ALPHABET = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_B58_INDEX = {ch: i for i, ch in enumerate(_B58_ALPHABET)}
+
+
+def b58encode(b: bytes) -> str:
+    """Kodiere Bytes als base58btc (führende Nullbytes bleiben als ``1`` erhalten)."""
+    n = int.from_bytes(b, "big", signed=False)
+    out = bytearray()
+    while n > 0:
+        n, r = divmod(n, 58)
+        out.append(_B58_ALPHABET[r])
+    pad = 0
+    for byte in b:
+        if byte == 0:
+            pad += 1
+        else:
+            break
+    return ("1" * pad) + out[::-1].decode()
+
+
+def b58decode(s: str) -> bytes:
+    """Dekodiere einen base58btc-String zurück zu Bytes.
+
+    Raises:
+        ValueError: bei Zeichen ausserhalb des base58-Alphabets.
+    """
+    n = 0
+    for ch in s.encode():
+        try:
+            n = n * 58 + _B58_INDEX[ch]
+        except KeyError:
+            raise ValueError("ungültiges base58-Zeichen: {!r}".format(chr(ch)))
+    pad = len(s) - len(s.lstrip("1"))
+    full = n.to_bytes((n.bit_length() + 7) // 8, "big") if n else b""
+    return b"\x00" * pad + full

sdata/did/did_github.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""``did:github``: DID-Dokumente aus GitHub-Repositories auflösen.
+
+Eine ``did:github``-DID verweist auf ein ``did.json`` in einem GitHub-Repo und
+wird über ``raw.githubusercontent.com`` geladen. Formen::
+
+    did:github:<user>:<repo>
+    did:github:<user>:<repo>:<ref>
+    did:github:<user>:<repo>:<ref>:<subpath>
+
+Im ``subpath`` darf ``__`` als ``/``-Ersatz verwendet werden (CLI-freundlich).
+Gesucht werden ``<subpath>/.well-known/did.json``, ``<subpath>/did.json`` sowie
+die Repo-Wurzel – in dieser Reihenfolge, für die Refs ``<ref>``, ``main``, ``master``.
+
+Ein optionales ``GITHUB_TOKEN`` (Umgebungsvariable) erhöht das Rate-Limit und
+erlaubt Zugriff auf private Repos.
+
+.. note::
+   ``did:github`` ist **keine** registrierte W3C-DID-Methode, sondern eine
+   pragmatische, projektspezifische Auflösung über GitHub-Rohinhalte.
+"""
+from __future__ import annotations
+
+import os
+import re
+import json
+import logging
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import List, Optional, Tuple
+
+from ._http import http_get
+from .errors import EncodingError, ResolutionError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["DidGithub", "parse_did_github", "resolve_did_github"]
+
+DID_GITHUB_METHOD = "did:github"
+RAW_BASE = "https://raw.githubusercontent.com"
+HTTP_TIMEOUT = 10
+
+
+@dataclass(frozen=True)
+class DidGithub:
+    """Geparste ``did:github``-Identität."""
+    user: str
+    repo: str
+    ref: Optional[str] = None       # z. B. "main", "master", Tag oder Commit
+    subpath: Optional[str] = None   # optionaler Unterordner im Repo
+
+    @property
+    def did(self) -> str:
+        parts = [DID_GITHUB_METHOD, self.user, self.repo]
+        if self.ref:
+            parts.append(self.ref)
+        if self.subpath:
+            parts.append(self.subpath)
+        return ":".join(parts)
+
+
+def make_subpath(raw: Optional[str]) -> Optional[str]:
+    """Mappe ``__`` auf ``/`` (echte Slashes bleiben erhalten)."""
+    if not raw:
+        return None
+    return raw.replace("__", "/")
+
+
+def parse_did_github(did: str) -> DidGithub:
+    """Parse eine ``did:github``-DID.
+
+    Raises:
+        EncodingError: wenn ``did`` keine gültige ``did:github``-DID ist.
+    """
+    if not did.startswith(DID_GITHUB_METHOD + ":"):
+        raise EncodingError("kein did:github-Identifier")
+    parts = did.split(":")
+    if len(parts) < 4:
+        raise EncodingError("Form: did:github:<user>:<repo>[:<ref>[:<subpath>]]")
+    _, _, user, repo, *rest = parts
+    ref = rest[0] if rest else None
+    subpath = make_subpath(":".join(rest[1:]) if len(rest) > 1 else None)
+    return DidGithub(user=user, repo=repo, ref=ref, subpath=subpath)
+
+
+def candidate_paths(dg: DidGithub) -> List[Tuple[str, str]]:
+    """Geordnete ``(ref, path)``-Kandidaten für die Auflösung."""
+    well_known, root = ".well-known/did.json", "did.json"
+    sub_candidates = []
+    if dg.subpath:
+        base = dg.subpath.rstrip("/")
+        sub_candidates = ["{}/{}".format(base, well_known), "{}/{}".format(base, root)]
+    paths = sub_candidates + [well_known, root]
+    refs = [r for r in [dg.ref, "main", "master"] if r]
+    return [(r, p) for r in refs for p in paths]
+
+
+def _raw_url(user: str, repo: str, ref: str, path: str) -> str:
+    return "{}/{}/{}/{}/{}".format(RAW_BASE, user, repo, ref, path)
+
+
+def _headers() -> dict:
+    headers = {"Accept": "application/json"}
+    token = os.getenv("GITHUB_TOKEN")
+    if token:
+        headers["Authorization"] = "Bearer {}".format(token)
+    return headers
+
+
+def _strip_json_comments(text: str) -> str:
+    """Entferne ``/* … */`` und ``// …`` (rudimentär, für einfache Fälle)."""
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+    text = re.sub(r"//.*?$", "", text, flags=re.M)
+    return text
+
+
+@lru_cache(maxsize=256)
+def fetch_json(url: str) -> Optional[dict]:
+    """Lade JSON von ``url`` (mit kleinem Cache); ``None`` bei Status != 200."""
+    status, text = http_get(url, headers=_headers(), timeout=HTTP_TIMEOUT)
+    if status != 200:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return json.loads(_strip_json_comments(text))
+
+
+def resolve_did_github(did: str) -> dict:
+    """Löse eine ``did:github``-DID zum DID-Dokument auf.
+
+    Raises:
+        EncodingError: bei ungültiger DID.
+        ResolutionError: wenn kein gültiges ``did.json`` gefunden wird.
+        EncodingError: wenn ein gefundenes Dokument ``@context``/``id`` vermisst.
+    """
+    dg = parse_did_github(did)
+    tried = []
+    for ref, path in candidate_paths(dg):
+        url = _raw_url(dg.user, dg.repo, ref, path)
+        tried.append(url)
+        doc = fetch_json(url)
+        if doc is None:
+            continue
+        if "@context" not in doc:
+            raise EncodingError("DID-Dokument ohne @context ({})".format(url))
+        if "id" not in doc:
+            raise EncodingError("DID-Dokument ohne id ({})".format(url))
+        logger.debug("did:github aufgelöst via %s", url)
+        return doc
+    raise ResolutionError(
+        "did:github konnte nicht aufgelöst werden. Versucht:\n- " + "\n- ".join(tried))

sdata/did/did_peer4.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""``did:peer:4``: statische, self-zertifizierende Peer-DIDs (Long-/Short-Form).
+
+Diese Implementierung ist bewusst **abhängigkeitsfrei** (nur Standardbibliothek)
+und bringt eine eigene base58btc- und varint-Kodierung mit – passend zum
+pure-Python-Designziel des Subpackages.
+
+Aufbau einer Long-Form::
+
+    did:peer:4{hash}:{encoded_document}
+
+* ``encoded_document`` = multibase(base58btc, multicodec(JSON) + kanonisches JSON),
+* ``hash``             = multibase(base58btc, multihash(sha2-256, encoded_document)).
+
+Die Short-Form ``did:peer:4{hash}`` ist self-zertifizierend: beim Auflösen der
+Long-Form wird der Hash gegen das eingebettete Dokument validiert.
+
+Referenzen:
+    * `did:peer Method, Variante 4 <https://identity.foundation/peer-did-method-spec/>`_
+"""
+from __future__ import annotations
+
+import json
+import hashlib
+from typing import Dict, Tuple
+
+from .errors import EncodingError, VerificationError
+# base58btc liegt jetzt zentral im eigenen Modul (frühere Inline-Variante);
+# Re-Export aus Kompatibilitätsgründen.
+from .base58btc import b58encode, b58decode
+
+__all__ = ["did_peer4_from_payload", "resolve_long_form", "b58encode", "b58decode"]
+
+
+# --- Varint (LEB128, wie in multicodec) -----------------------------------
+def varint_encode(n: int) -> bytes:
+    """Kodiere ``n`` als unsigned LEB128-varint."""
+    out = bytearray()
+    while True:
+        to_write = n & 0x7F
+        n >>= 7
+        if n:
+            out.append(to_write | 0x80)
+        else:
+            out.append(to_write)
+            break
+    return bytes(out)
+
+
+def varint_decode(b: bytes) -> Tuple[int, int]:
+    """Dekodiere einen unsigned LEB128-varint; gibt ``(wert, gelesene_bytes)`` zurück."""
+    shift = 0
+    value = 0
+    for i, byte in enumerate(b):
+        value |= (byte & 0x7F) << shift
+        if not (byte & 0x80):
+            return value, i + 1
+        shift += 7
+    raise EncodingError("ungültiger varint")
+
+
+# --- Multicodec- & Multihash-Konstanten -----------------------------------
+MULTICODEC_JSON = 0x0200   # multicodec-Code für JSON
+MH_SHA256 = 0x12           # multihash: sha2-256
+MH_SHA256_LEN = 32
+
+
+def _canonical_json_bytes(payload: Dict) -> bytes:
+    """Deterministische JSON-Serialisierung (Keys sortiert, ohne Whitespace)."""
+    s = json.dumps(payload, separators=(",", ":"), sort_keys=True, ensure_ascii=False)
+    return s.encode("utf-8")
+
+
+def encode_document(payload: Dict) -> bytes:
+    """Multicodec-Framing: ``varint(JSON-Code) + kanonisches JSON``."""
+    return varint_encode(MULTICODEC_JSON) + _canonical_json_bytes(payload)
+
+
+def multibase_b58btc(data: bytes) -> str:
+    """Präfix ``z`` (base58btc) gemäß Multibase."""
+    return "z" + b58encode(data)
+
+
+def multihash_sha256(data: bytes) -> bytes:
+    """``multihash(sha2-256, data)`` = ``0x12 0x20 || sha256(data)``."""
+    return bytes([MH_SHA256, MH_SHA256_LEN]) + hashlib.sha256(data).digest()
+
+
+# --- did:peer:4 Erzeugung & Auflösung -------------------------------------
+def did_peer4_from_payload(payload: Dict) -> Tuple[str, str, Dict]:
+    """Erzeuge Long-Form, Short-Form und kontextualisiertes DID-Dokument.
+
+    Args:
+        payload: DID-Dokument **ohne** ``id`` (relative Fragmente wie ``#key-0``
+            sind erlaubt).
+
+    Returns:
+        ``(long_form, short_form, did_document)``.
+    """
+    encoded_doc_bytes = encode_document(payload)
+    encoded_doc_mb = multibase_b58btc(encoded_doc_bytes)
+    mh_mb = multibase_b58btc(multihash_sha256(encoded_doc_bytes))
+
+    long_form = "did:peer:4{}:{}".format(mh_mb, encoded_doc_mb)
+    short_form = "did:peer:4{}".format(mh_mb)
+    did_doc = _contextualize_did_doc(payload, did_long=long_form, did_short=short_form)
+    return long_form, short_form, did_doc
+
+
+def resolve_long_form(did_long: str) -> Dict:
+    """Löse eine Long-Form ``did:peer:4`` auf und validiere den Hash.
+
+    Raises:
+        EncodingError: bei strukturell ungültiger DID oder falschem multicodec/multihash.
+        VerificationError: wenn der eingebettete Hash nicht zum Dokument passt.
+    """
+    if not did_long.startswith("did:peer:4"):
+        raise EncodingError("keine did:peer:4")
+    try:
+        _, rest = did_long.split("did:peer:4", 1)
+        hash_mb, doc_mb = rest.split(":", 1)
+    except ValueError:
+        raise EncodingError("erwarte Long-Form: did:peer:4{hash}:{doc}")
+
+    if not (hash_mb.startswith("z") and doc_mb.startswith("z")):
+        raise EncodingError("erwarte multibase base58btc ('z'-Präfix)")
+
+    mh = b58decode(hash_mb[1:])
+    encoded_doc_bytes = b58decode(doc_mb[1:])
+
+    code, offset = varint_decode(encoded_doc_bytes)
+    if code != MULTICODEC_JSON:
+        raise EncodingError("multicodec-Code ist nicht JSON (0x0200)")
+    json_bytes = encoded_doc_bytes[offset:]
+
+    if len(mh) < 2 or mh[0] != MH_SHA256 or mh[1] != MH_SHA256_LEN:
+        raise EncodingError("multihash ist nicht sha2-256/32")
+    if mh[2:] != hashlib.sha256(encoded_doc_bytes).digest():
+        raise VerificationError("Hash-Validierung fehlgeschlagen")
+
+    payload = json.loads(json_bytes.decode("utf-8"))
+    did_short = "did:peer:4{}".format(multibase_b58btc(mh))
+    return _contextualize_did_doc(payload, did_long=did_long, did_short=did_short)
+
+
+def _contextualize_did_doc(payload: Dict, *, did_long: str, did_short: str) -> Dict:
+    """Setze ``id``/``alsoKnownAs`` und ergänze fehlende ``controller``-Felder."""
+    doc = json.loads(json.dumps(payload))  # tiefe Kopie
+    doc["id"] = did_long
+    doc.setdefault("alsoKnownAs", [])
+    if did_short not in doc["alsoKnownAs"]:
+        doc["alsoKnownAs"].append(did_short)
+    for vm in doc.get("verificationMethod", []):
+        vm.setdefault("controller", did_long)
+    return doc