sdata 1.5.0__py3-none-any.whl

sdata/did/issue_vc.py

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""Ausstellung von Verifiable Credentials (VC) und Verifiable Presentations (VP).
+
+Signaturformat: **JWT-VC** als Compact-JWS (EdDSA/Ed25519) über
+:mod:`sdata.did.jose`. Der Issuer wird als ``did:web`` modelliert, der Holder
+wahlweise als ``did:key`` (Multibase) oder als beliebige DID.
+
+Das hier ausgestellte Credential ist ein einfacher **Digital Product Passport**
+(``ProductPassport``) im Sinne von GS1/EU-DPP: GTIN, Seriennummer, GS1 Digital
+Link sowie CO₂-Fußabdruck und Rezyklatanteil.
+
+CLI::
+
+    python -m sdata.did.issue_vc \\
+        --issuer-domain issuer.example --issuer-key issuer_key.json \\
+        --gtin 04012345678901 --serial SN-42 --co2 12.5 --recycled 80 \\
+        --out product.vc
+
+Referenzen:
+    * `W3C VC Data Model <https://www.w3.org/TR/vc-data-model/>`_
+    * `GS1 Digital Link <https://www.gs1.org/standards/gs1-digital-link>`_
+"""
+from __future__ import annotations
+
+import json
+import time
+import uuid
+import logging
+import argparse
+from typing import Any, Dict
+
+from . import jose
+from .keys import pub_from_priv_jwk
+from .utils_didkey import did_key_from_jwk_ed25519
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["issue_vc", "make_vp", "sign_compact_jws"]
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def _in_days(days: int) -> int:
+    return _now() + days * 24 * 3600
+
+
+def _load_priv_jwk(path: str) -> Dict:
+    with open(path, "r") as fh:
+        return json.load(fh)
+
+
+def sign_compact_jws(payload: Dict[str, Any], priv_jwk: Dict, kid: str, typ: str) -> str:
+    """Signiere ``payload`` als Compact-JWS.
+
+    Dünner Wrapper um :func:`sdata.did.jose.sign_compact`; aus Kompatibilität
+    mit dem bisherigen API-Namen erhalten geblieben.
+    """
+    return jose.sign_compact(payload, priv_jwk, kid=kid, typ=typ)
+
+
+def issue_vc(issuer_domain: str, issuer_key_path: str, gtin: str, serial: str,
+             co2: float, recycled: float,
+             subject_did: str = "did:example:product-xyz",
+             validity_days: int = 365 * 3) -> str:
+    """Stelle ein ``ProductPassport``-VC aus und gib es als Compact-JWS zurück.
+
+    Args:
+        issuer_domain: Domain des Issuers; ergibt ``did:web:<domain>``.
+        issuer_key_path: Pfad zum **privaten** Issuer-JWK.
+        gtin: GS1 GTIN (Global Trade Item Number).
+        serial: Seriennummer des Produkts.
+        co2: CO₂-Fußabdruck in kg CO₂e.
+        recycled: Rezyklatanteil in Prozent.
+        subject_did: DID des Credential-Subjects.
+        validity_days: Gültigkeitsdauer ab jetzt (Default: 3 Jahre).
+
+    Returns:
+        Das signierte VC als Compact-JWS (``vc+ld+jwt``).
+    """
+    issuer_did = "did:web:{}".format(issuer_domain)
+    kid = "{}#key-1".format(issuer_did)
+    jwk_priv = _load_priv_jwk(issuer_key_path)
+    payload = {
+        "iss": issuer_did,
+        "sub": subject_did,
+        "nbf": _now(),
+        "iat": _now(),
+        "exp": _in_days(validity_days),
+        "jti": "urn:uuid:{}".format(uuid.uuid4()),
+        "vc": {
+            "@context": ["https://www.w3.org/2018/credentials/v1"],
+            "type": ["VerifiableCredential", "ProductPassport"],
+            "credentialSubject": {
+                "gtin": gtin,
+                "serialNumber": serial,
+                "gs1DigitalLink": "https://id.gs1.org/01/{}/21/{}".format(gtin, serial),
+                "co2Footprint": {"value": co2, "unitText": "kg CO2e"},
+                "recycledContent": {"value": recycled, "unitText": "%"},
+            },
+            "credentialStatus": {
+                "id": "https://{}/status/pp-2025#1".format(issuer_domain),
+                "type": "StatusList2021Entry",
+            },
+        },
+    }
+    return sign_compact_jws(payload, jwk_priv, kid=kid, typ="vc+ld+jwt")
+
+
+def make_vp(holder_key_path: str, holder_did: str, vc_jws: str,
+            aud: str, nonce: str) -> str:
+    """Baue eine Verifiable Presentation um ein VC und signiere sie (Holder).
+
+    Für ``did:key``-Holder wird die konventionelle ``kid``
+    ``did:key:<mb>#<mb>`` gesetzt, sonst ``<holder_did>#key-1``.
+    """
+    holder_jwk = _load_priv_jwk(holder_key_path)
+    if holder_did.startswith("did:key:"):
+        frag = did_key_from_jwk_ed25519(pub_from_priv_jwk(holder_jwk)).split(":", 2)[2]
+        holder_kid = "{}#{}".format(holder_did, frag)
+    else:
+        holder_kid = "{}#key-1".format(holder_did)
+
+    payload = {
+        "holder": holder_did,
+        "vp": {"type": ["VerifiablePresentation"], "verifiableCredential": [vc_jws]},
+        "aud": aud,
+        "nonce": nonce,
+    }
+    return sign_compact_jws(payload, holder_jwk, kid=holder_kid, typ="vp+jwt")
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+def _build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(description="Verifiable Credential / Presentation ausstellen")
+    ap.add_argument("--issuer-domain", required=True)
+    ap.add_argument("--issuer-key", required=True)
+    ap.add_argument("--gtin", required=True)
+    ap.add_argument("--serial", required=True)
+    ap.add_argument("--co2", type=float, required=True)
+    ap.add_argument("--recycled", type=float, required=True)
+    ap.add_argument("--subject", default="did:example:product-xyz")
+    ap.add_argument("--out", required=True)
+
+    ap.add_argument("--make-vp", action="store_true")
+    ap.add_argument("--holder-key")
+    ap.add_argument("--holder-did", default=None)
+    ap.add_argument("--aud", default="https://verifier.example.org")
+    ap.add_argument("--nonce", default=None)
+    return ap
+
+
+def main(argv=None) -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    args = _build_parser().parse_args(argv)
+
+    vc_jws = issue_vc(
+        issuer_domain=args.issuer_domain,
+        issuer_key_path=args.issuer_key,
+        gtin=args.gtin,
+        serial=args.serial,
+        co2=args.co2,
+        recycled=args.recycled,
+        subject_did=args.subject,
+    )
+
+    if not args.make_vp:
+        with open(args.out, "w") as fh:
+            fh.write(vc_jws)
+        logger.info("✔ VC geschrieben: %s", args.out)
+        return
+
+    if not args.holder_key:
+        raise SystemExit("--make-vp benötigt --holder-key")
+
+    if args.holder_did:
+        holder_did = args.holder_did
+    else:
+        holder_jwk = _load_priv_jwk(args.holder_key)
+        holder_did = did_key_from_jwk_ed25519(pub_from_priv_jwk(holder_jwk))
+
+    nonce = args.nonce or str(uuid.uuid4())
+    vp_jws = make_vp(args.holder_key, holder_did, vc_jws, aud=args.aud, nonce=nonce)
+    with open(args.out, "w") as fh:
+        fh.write(vp_jws)
+    logger.info("✔ VP geschrieben: %s (enthält eingebettetes VC)", args.out)
+
+
+if __name__ == "__main__":
+    main()

sdata/did/jose.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Kompakte JWS-Schicht (JOSE) für EdDSA/Ed25519 – gemeinsame Basis für VC & VP.
+
+Diese Modul bündelt das Signieren/Verifizieren von **Compact-JWS**
+(``header.payload.signature``, base64url), das zuvor doppelt in
+``issue_vc`` und ``verify_vp`` implementiert war.
+
+Krypto-Backend: :mod:`sdata.did.eddsa` (reine Python-Ed25519-Implementierung,
+abhängigkeitsfrei).
+
+.. warning::
+   Das Ed25519-Backend ist nicht garantiert constant-time. Für hochsensible
+   Produktivumgebungen mit Seitenkanal-Anforderungen sollte ein
+   libsodium-basiertes Backend (PyNaCl) oder ``cryptography`` erwogen werden.
+   Siehe auch das Paket-Docstring von :mod:`sdata.did`.
+
+Referenzen:
+    * `RFC 7515 <https://www.rfc-editor.org/rfc/rfc7515>`_ – JWS
+    * `RFC 8037 <https://www.rfc-editor.org/rfc/rfc8037>`_ – EdDSA in JOSE
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+from .eddsa import SigningKey, VerifyingKey, Ed25519, BadSignatureError
+
+from .errors import EncodingError, VerificationError
+from .utils_didkey import b64url, b64url_decode
+
+__all__ = [
+    "b64url_json",
+    "protected_header",
+    "signing_key_from_jwk",
+    "verifying_key_from_jwk",
+    "sign_compact",
+    "decode_header",
+    "verify_compact",
+]
+
+
+def b64url_json(obj: Any) -> str:
+    """Serialisiere ``obj`` als kompaktes JSON und kodiere base64url (ohne Padding)."""
+    raw = json.dumps(obj, separators=(",", ":"), ensure_ascii=False).encode()
+    return b64url(raw)
+
+
+def protected_header(kid: str, typ: str, alg: str = "EdDSA") -> Dict[str, str]:
+    """Baue einen geschützten JWS-Header ``{alg, kid, typ}``."""
+    return {"alg": alg, "kid": kid, "typ": typ}
+
+
+def signing_key_from_jwk(jwk_priv: Dict) -> SigningKey:
+    """Erzeuge einen Ed25519-``SigningKey`` aus einem privaten JWK (Feld ``d``).
+
+    Raises:
+        EncodingError: wenn das private JWK ungültig ist oder ``d`` fehlt.
+    """
+    if not isinstance(jwk_priv, dict) or "d" not in jwk_priv:
+        raise EncodingError("privater JWK fehlt das Feld 'd'")
+    if jwk_priv.get("kty") != "OKP" or jwk_priv.get("crv") != "Ed25519":
+        raise EncodingError("nur OKP/Ed25519 wird unterstützt")
+    raw = b64url_decode(jwk_priv["d"])  # 32 Byte Seed
+    return SigningKey.from_string(raw, curve=Ed25519)
+
+
+def verifying_key_from_jwk(jwk_pub: Dict) -> VerifyingKey:
+    """Erzeuge einen Ed25519-``VerifyingKey`` aus einem öffentlichen JWK (Feld ``x``).
+
+    Raises:
+        EncodingError: wenn das öffentliche JWK ungültig ist oder ``x`` fehlt.
+    """
+    if not isinstance(jwk_pub, dict) or "x" not in jwk_pub:
+        raise EncodingError("öffentlicher JWK fehlt das Feld 'x'")
+    if jwk_pub.get("kty") != "OKP" or jwk_pub.get("crv") != "Ed25519":
+        raise EncodingError("nur OKP/Ed25519 wird unterstützt")
+    raw = b64url_decode(jwk_pub["x"])
+    return VerifyingKey.from_string(raw, curve=Ed25519)
+
+
+def sign_compact(payload: Dict[str, Any], priv_jwk: Dict, kid: str, typ: str,
+                 alg: str = "EdDSA") -> str:
+    """Signiere ``payload`` als Compact-JWS und gib ``header.payload.signature`` zurück."""
+    header_b64 = b64url_json(protected_header(kid, typ, alg))
+    payload_b64 = b64url_json(payload)
+    signing_input = "{}.{}".format(header_b64, payload_b64).encode()
+    sig = signing_key_from_jwk(priv_jwk).sign(signing_input)
+    return "{}.{}.{}".format(header_b64, payload_b64, b64url(sig))
+
+
+def decode_header(compact: str) -> Dict[str, Any]:
+    """Dekodiere (ohne Verifikation) den geschützten Header eines Compact-JWS.
+
+    Raises:
+        EncodingError: wenn das JWS strukturell ungültig ist.
+    """
+    parts = compact.split(".")
+    if len(parts) != 3:
+        raise EncodingError("kein gültiges Compact-JWS (erwarte 3 Segmente)")
+    try:
+        return json.loads(b64url_decode(parts[0]).decode())
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise EncodingError("JWS-Header nicht dekodierbar: {}".format(exc))
+
+
+def verify_compact(compact: str, pub_jwk: Dict) -> Dict[str, Any]:
+    """Verifiziere ein Compact-JWS gegen ``pub_jwk`` und gib das Payload zurück.
+
+    Raises:
+        EncodingError: bei strukturell ungültigem JWS.
+        VerificationError: wenn die Signatur ungültig ist.
+    """
+    parts = compact.split(".")
+    if len(parts) != 3:
+        raise EncodingError("kein gültiges Compact-JWS (erwarte 3 Segmente)")
+    header_b64, payload_b64, sig_b64 = parts
+    signing_input = "{}.{}".format(header_b64, payload_b64).encode()
+    vk = verifying_key_from_jwk(pub_jwk)
+    try:
+        vk.verify(b64url_decode(sig_b64), signing_input)
+    except BadSignatureError:
+        raise VerificationError("Signatur ungültig")
+    try:
+        return json.loads(b64url_decode(payload_b64).decode())
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise EncodingError("JWS-Payload nicht dekodierbar: {}".format(exc))

sdata/did/keys.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+"""Erzeugung und Verwaltung von Ed25519-Schlüsseln im JWK-Format.
+
+Schlüssel werden als JWK (RFC 8037, ``kty=OKP``, ``crv=Ed25519``) gehalten:
+
+* öffentlich: Feld ``x`` (raw 32 Byte, base64url),
+* privat:     zusätzlich Feld ``d`` (raw 32 Byte Seed, base64url – **geheim halten!**).
+
+CLI (das ``did``-Modul ist als Subpackage organisiert, daher via ``-m``)::
+
+    python -m sdata.did.keys gen   --out issuer_key.json
+    python -m sdata.did.keys pub   --in  issuer_key.json --out issuer_pub.json
+    python -m sdata.did.keys thumb --in  issuer_pub.json
+
+.. note::
+   ``gen`` schreibt einen **privaten** Schlüssel. Solche Dateien gehören nicht
+   ins Versionskontrollsystem (siehe ``.gitignore``).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import argparse
+from typing import Dict
+
+from .eddsa import SigningKey, Ed25519
+
+from .utils_didkey import b64url, jwk_thumbprint_rfc7638, did_key_from_jwk_ed25519
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["gen_ed25519_jwk", "pub_from_priv_jwk"]
+
+
+def gen_ed25519_jwk() -> Dict[str, str]:
+    """Erzeuge ein frisches privates Ed25519-JWK (mit Feldern ``x`` und ``d``)."""
+    sk = SigningKey.generate(curve=Ed25519)
+    vk = sk.get_verifying_key()
+    return {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": b64url(vk.to_string()),   # Public Key (raw 32 Byte)
+        "d": b64url(sk.to_string()),   # Private Key (raw 32 Byte – geheim halten!)
+    }
+
+
+def pub_from_priv_jwk(jwk_priv: Dict) -> Dict[str, str]:
+    """Leite den öffentlichen JWK (ohne ``d``) aus einem privaten JWK ab."""
+    return {"kty": jwk_priv["kty"], "crv": jwk_priv["crv"], "x": jwk_priv["x"]}
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+def _cmd_gen(args: argparse.Namespace) -> None:
+    with open(args.out, "w") as fh:
+        json.dump(gen_ed25519_jwk(), fh, indent=2)
+    logger.info("✔ Privates JWK gespeichert: %s", args.out)
+
+
+def _cmd_pub(args: argparse.Namespace) -> None:
+    with open(args.in_, "r") as fh:
+        jwk = json.load(fh)
+    with open(args.out, "w") as fh:
+        json.dump(pub_from_priv_jwk(jwk), fh, indent=2)
+    logger.info("✔ Öffentliches JWK gespeichert: %s", args.out)
+
+
+def _cmd_thumb(args: argparse.Namespace) -> None:
+    with open(args.in_, "r") as fh:
+        jwk_pub = json.load(fh)
+    logger.info("%s", json.dumps({
+        "thumbprint_rfc7638": jwk_thumbprint_rfc7638(jwk_pub),
+        "did_key": did_key_from_jwk_ed25519(jwk_pub),
+    }, indent=2))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(description="Ed25519-JWK-Schlüsselverwaltung")
+    sub = ap.add_subparsers(required=True)
+
+    p = sub.add_parser("gen", help="Ed25519-Key erzeugen")
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=_cmd_gen)
+
+    p = sub.add_parser("pub", help="Public-Part aus privatem JWK ableiten")
+    p.add_argument("--in", dest="in_", required=True)
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=_cmd_pub)
+
+    p = sub.add_parser("thumb", help="RFC-7638-Thumbprint + did:key aus Public-JWK")
+    p.add_argument("--in", dest="in_", required=True)
+    p.set_defaults(func=_cmd_thumb)
+    return ap
+
+
+def main(argv=None) -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    args = _build_parser().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

sdata/did/utils_didkey.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+"""Hilfsfunktionen rund um ``did:key``, JWK und RFC-7638-Thumbprints (Ed25519).
+
+Funktionsumfang:
+
+* Base64url-Kodierung ohne Padding (RFC 7515 §2),
+* RFC-7638-Thumbprint: kanonisches JSON ``{crv,kty,x}`` → SHA-256 → base64url,
+* ``did:key`` für Ed25519 erzeugen (multicodec ``0xED 0x01`` + multibase ``z``-base58btc),
+* ``did:key`` (bzw. nackte Multibase) zurück zu einem Public-JWK auflösen,
+* konventionelle ``kid``-Bildung für ``did:web`` und ``did:key``.
+
+Es werden ausschließlich **öffentliche** Schlüssel verarbeitet; private Schlüssel
+tauchen hier nicht auf. Abhängigkeitsfrei (nur Standardbibliothek + die eigene
+base58btc-Kodierung in :mod:`sdata.did.base58btc`).
+
+Referenzen:
+    * `RFC 7638 <https://www.rfc-editor.org/rfc/rfc7638>`_ – JWK Thumbprint
+    * `did:key Method <https://w3c-ccg.github.io/did-method-key/>`_
+    * `Multicodec <https://github.com/multiformats/multicodec>`_ (ed25519-pub = 0xED)
+"""
+from __future__ import annotations
+
+import json
+import base64
+import hashlib
+from typing import Dict
+
+from .base58btc import b58encode, b58decode
+from .errors import EncodingError
+
+__all__ = [
+    "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",
+]
+
+# multicodec-Präfix (unsigned varint) für einen öffentlichen Ed25519-Schlüssel.
+_ED25519_PUB_PREFIX = bytes([0xED, 0x01])
+
+
+# --------------------------------------------------------------------------
+# Base64url-Helfer (ohne Padding, RFC 7515)
+# --------------------------------------------------------------------------
+def b64url(data: bytes) -> str:
+    """Kodiere ``data`` als base64url ohne ``=``-Padding."""
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def b64url_decode(s: str) -> bytes:
+    """Dekodiere einen base64url-String; fehlendes Padding wird ergänzt."""
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+# --------------------------------------------------------------------------
+# Validierung
+# --------------------------------------------------------------------------
+def _assert_ed25519_jwk_pub(jwk_pub: Dict) -> None:
+    """Stelle sicher, dass ``jwk_pub`` ein gültiger öffentlicher Ed25519-JWK ist.
+
+    Raises:
+        EncodingError: bei falschem Typ, ``kty``/``crv`` oder Schlüssellänge.
+    """
+    if not isinstance(jwk_pub, dict):
+        raise EncodingError("jwk_pub muss ein dict sein")
+    if jwk_pub.get("kty") != "OKP" or jwk_pub.get("crv") != "Ed25519":
+        raise EncodingError("nur OKP/Ed25519 wird unterstützt")
+    if "x" not in jwk_pub:
+        raise EncodingError("JWK fehlt das Feld 'x' (Public Key)")
+    raw = b64url_decode(jwk_pub["x"])
+    if len(raw) != 32:
+        raise EncodingError(
+            "Ed25519 Public Key muss 32 Byte sein (war {})".format(len(raw)))
+
+
+def _strip_didkey_multibase(did_or_mb: str) -> str:
+    """Normalisiere ``did:key:z…``, ``#z…`` oder ``z…`` auf die nackte Multibase ``z…``."""
+    s = did_or_mb
+    if s.startswith("did:key:"):
+        s = s.split(":", 2)[2]
+    if s.startswith("#"):
+        s = s[1:]
+    return s
+
+
+# --------------------------------------------------------------------------
+# RFC-7638-Thumbprint
+# --------------------------------------------------------------------------
+def jwk_thumbprint_rfc7638(jwk_pub: Dict) -> str:
+    """Berechne den RFC-7638-Thumbprint eines öffentlichen Ed25519-JWK.
+
+    Kanonisiert wird über die Pflichtfelder ``{crv, kty, x}`` (lexikografisch
+    sortiert, ohne Whitespace); davon der SHA-256, base64url-kodiert.
+
+    Returns:
+        Der Thumbprint als base64url-String (ohne Padding).
+    """
+    _assert_ed25519_jwk_pub(jwk_pub)
+    data = {"crv": jwk_pub["crv"], "kty": jwk_pub["kty"], "x": jwk_pub["x"]}
+    canon = json.dumps(data, separators=(",", ":"), sort_keys=True).encode()
+    return b64url(hashlib.sha256(canon).digest())
+
+
+# --------------------------------------------------------------------------
+# did:key  <->  JWK
+# --------------------------------------------------------------------------
+def did_key_from_jwk_ed25519(jwk_pub: Dict) -> str:
+    """Erzeuge eine ``did:key``-DID aus einem öffentlichen Ed25519-JWK."""
+    _assert_ed25519_jwk_pub(jwk_pub)
+    raw = b64url_decode(jwk_pub["x"])  # 32 Byte
+    mb = "z" + b58encode(_ED25519_PUB_PREFIX + raw)
+    return "did:key:{}".format(mb)
+
+
+def did_key_fragment_from_jwk(jwk_pub: Dict) -> str:
+    """Liefere den Multibase-Teil (``z…``) – praktisch als ``kid``-Fragment."""
+    _assert_ed25519_jwk_pub(jwk_pub)
+    raw = b64url_decode(jwk_pub["x"])
+    return "z" + b58encode(_ED25519_PUB_PREFIX + raw)
+
+
+def pub_jwk_from_did_key(did_key_or_mb: str) -> Dict[str, str]:
+    """Gewinne den öffentlichen JWK aus einer ``did:key``-DID oder Multibase zurück.
+
+    Akzeptiert ``did:key:z…``, ``#z…`` oder die nackte Multibase ``z…``.
+
+    Raises:
+        EncodingError: bei fehlendem ``z``-Präfix oder falschem multicodec.
+    """
+    mb = _strip_didkey_multibase(did_key_or_mb)
+    if not mb.startswith("z"):
+        raise EncodingError("did:key erwartet base58btc (z-Codec)")
+    raw = b58decode(mb[1:])  # 'z' entfernen
+    if not (len(raw) >= 34 and raw[0] == 0xED and raw[1] == 0x01):
+        raise EncodingError("unerwartetes multicodec-Präfix für ed25519-pub")
+    pubkey = raw[2:34]
+    return {"kty": "OKP", "crv": "Ed25519", "x": b64url(pubkey)}
+
+
+# --------------------------------------------------------------------------
+# kid-Helfer (konventionell)
+# --------------------------------------------------------------------------
+def kid_for_did_web(did_web: str, key_id: str = "key-1") -> str:
+    """``kid_for_did_web('did:web:example.com')`` → ``'did:web:example.com#key-1'``."""
+    return "{}#{}".format(did_web, key_id)
+
+
+def kid_for_did_key(did_key: str, jwk_pub: Dict = None) -> str:
+    """Bilde die konventionelle ``kid`` ``did:key:<mb>#<mb>``.
+
+    Wird ``jwk_pub`` übergeben, wird das Fragment aus dem JWK abgeleitet,
+    andernfalls die Multibase aus ``did_key`` wiederverwendet.
+    """
+    mb = _strip_didkey_multibase(did_key)
+    frag = mb if not jwk_pub else did_key_fragment_from_jwk(jwk_pub)
+    return "did:key:{}#{}".format(mb, frag)