openvc-core 0.1.0__py3-none-any.whl

openvc/__init__.py

@@ -0,0 +1,5 @@
+"""openvc — generic Verifiable Credentials core."""
+
+# Single source of truth for the version (pyproject reads it by AST — keep it a
+# plain string literal). The /release skill bumps this line.
+__version__ = "0.1.0"

openvc/did/__init__.py

@@ -0,0 +1 @@
+"""openvc.did — DID resolution (key, web, + ebsi plugin)."""

openvc/did/base.py

@@ -0,0 +1,103 @@
+"""
+openvc.did.base — core DID resolution primitives.
+
+Home of the generic types every DID method shares: VerificationMethod, DidDocument,
+the DidResolver protocol, a shared W3C DID-document parser, and a registry that
+dispatches a DID to the backend that supports it. No network, no method specifics.
+
+(These types used to live in the EBSI plugin; they are generic to did:key,
+did:web and did:ebsi alike, so they belong in the core.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+# --------------------------------------------------------------------------- #
+# Model
+# --------------------------------------------------------------------------- #
+
+@dataclass(frozen=True)
+class VerificationMethod:
+    id: str                       # e.g. did:...#key-1
+    type: str
+    controller: str
+    public_key_jwk: dict[str, Any]
+
+    @property
+    def kid(self) -> str:
+        return self.id.split("#", 1)[-1]
+
+
+@dataclass(frozen=True)
+class DidDocument:
+    id: str
+    verification_methods: list[VerificationMethod]
+    raw: dict[str, Any]
+
+    def key_by_kid(self, kid: str | None) -> VerificationMethod | None:
+        """Match on the full verificationMethod id or its fragment (a JWS `kid`
+        may carry either). If kid is None, fall back to the sole key if unique."""
+        if kid is None:
+            return self.verification_methods[0] if len(self.verification_methods) == 1 else None
+        fragment = kid.split("#", 1)[-1]
+        return next(
+            (vm for vm in self.verification_methods if vm.id == kid or vm.kid == fragment),
+            None,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Errors + protocol
+# --------------------------------------------------------------------------- #
+
+class DidError(Exception): ...
+class UnsupportedDidMethod(DidError): ...
+class DidResolutionError(DidError): ...
+
+
+@runtime_checkable
+class DidResolver(Protocol):
+    def supports(self, did: str) -> bool: ...
+    def resolve(self, did: str) -> DidDocument: ...
+
+
+# --------------------------------------------------------------------------- #
+# Shared W3C DID-document parser (used by did:web and the EBSI DID Registry)
+# --------------------------------------------------------------------------- #
+
+def parse_did_document(raw: dict[str, Any]) -> DidDocument:
+    """Parse a W3C DID document. Tolerates a `didDocument` wrapper or a bare doc
+    (the EBSI DID Registry returns it bare, as application/did+ld+json)."""
+    doc = raw.get("didDocument", raw)
+    vms = [
+        VerificationMethod(
+            id=vm["id"],
+            type=vm.get("type", ""),
+            controller=vm.get("controller", doc.get("id", "")),
+            public_key_jwk=vm["publicKeyJwk"],
+        )
+        for vm in doc.get("verificationMethod", [])
+        if "publicKeyJwk" in vm
+    ]
+    return DidDocument(id=doc.get("id", ""), verification_methods=vms, raw=doc)
+
+
+# --------------------------------------------------------------------------- #
+# Registry — dispatch a DID to the first backend that supports it
+# --------------------------------------------------------------------------- #
+
+class DidResolverRegistry:
+    def __init__(self, resolvers: list[DidResolver] | None = None) -> None:
+        self._resolvers: list[DidResolver] = list(resolvers or [])
+
+    def register(self, resolver: DidResolver) -> None:
+        self._resolvers.append(resolver)
+
+    def resolve(self, did: str) -> DidDocument:
+        for r in self._resolvers:
+            if r.supports(did):
+                return r.resolve(did)
+        raise UnsupportedDidMethod(f"no resolver for {did!r}")

openvc/did/did_key.py

@@ -0,0 +1,98 @@
+"""
+openvc.did.did_key — offline resolver for the did:key method (Ed25519, P-256).
+
+did:key is self-contained: the public key is encoded in the identifier itself, so
+resolution is pure decoding — no network. Format:
+
+    did:key:z<base58btc( <multicodec-varint> || <raw-public-key> )>
+
+Supported multicodecs:
+    0xed   Ed25519 public key   -> OKP / Ed25519 JWK
+    0x1200 P-256   public key   -> EC  / P-256  JWK (from the compressed point)
+"""
+
+from __future__ import annotations
+
+import base64
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from .base import DidDocument, DidResolutionError, VerificationMethod
+
+# base58btc (Bitcoin) alphabet
+_B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_B58_INDEX = {c: i for i, c in enumerate(_B58_ALPHABET)}
+
+# multicodec codes (unsigned-varint encoded in the key bytes)
+_MC_ED25519_PUB = 0xED
+_MC_P256_PUB = 0x1200
+
+
+def _b58decode(s: str) -> bytes:
+    num = 0
+    for ch in s:
+        try:
+            num = num * 58 + _B58_INDEX[ch]
+        except KeyError:
+            raise DidResolutionError(f"invalid base58 character {ch!r}") from None
+    body = num.to_bytes((num.bit_length() + 7) // 8, "big") if num else b""
+    n_leading = len(s) - len(s.lstrip("1"))          # each leading '1' == 0x00
+    return b"\x00" * n_leading + body
+
+
+def _read_varint(data: bytes) -> tuple[int, int]:
+    result = shift = 0
+    for i, byte in enumerate(data):
+        result |= (byte & 0x7F) << shift
+        if not byte & 0x80:
+            return result, i + 1
+        shift += 7
+    raise DidResolutionError("truncated multicodec varint")
+
+
+def _b64url(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+class DidKeyResolver:
+    def supports(self, did: str) -> bool:
+        return did.startswith("did:key:z")
+
+    def resolve(self, did: str) -> DidDocument:
+        multibase = did[len("did:key:"):]
+        if not multibase.startswith("z"):
+            raise DidResolutionError("did:key must use base58btc ('z') multibase")
+
+        raw = _b58decode(multibase[1:])
+        code, offset = _read_varint(raw)
+        key_bytes = raw[offset:]
+
+        if code == _MC_ED25519_PUB:
+            jwk = {"kty": "OKP", "crv": "Ed25519", "x": _b64url(key_bytes)}
+        elif code == _MC_P256_PUB:
+            pub = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), key_bytes)
+            nums = pub.public_numbers()
+            jwk = {
+                "kty": "EC", "crv": "P-256",
+                "x": _b64url(nums.x.to_bytes(32, "big")),
+                "y": _b64url(nums.y.to_bytes(32, "big")),
+            }
+        else:
+            raise DidResolutionError(f"unsupported did:key multicodec 0x{code:x}")
+
+        # For did:key the verification method fragment IS the multibase value.
+        vm_id = f"{did}#{multibase}"
+        vm = VerificationMethod(
+            id=vm_id, type="JsonWebKey2020", controller=did, public_key_jwk=jwk
+        )
+        raw_doc = {
+            "@context": ["https://www.w3.org/ns/did/v1"],
+            "id": did,
+            "verificationMethod": [
+                {"id": vm_id, "type": "JsonWebKey2020", "controller": did,
+                 "publicKeyJwk": jwk}
+            ],
+            "authentication": [vm_id],
+            "assertionMethod": [vm_id],
+        }
+        return DidDocument(id=did, verification_methods=[vm], raw=raw_doc)

openvc/did/did_web.py

@@ -0,0 +1,54 @@
+"""
+openvc.did.did_web — resolver for the did:web method.
+
+did:web maps a DID to an https URL and fetches the DID document from the issuer's
+own domain:
+
+    did:web:example.edu                 -> https://example.edu/.well-known/did.json
+    did:web:example.edu:issuers:physics -> https://example.edu/issuers/physics/did.json
+    did:web:example.edu%3A3000          -> https://example.edu:3000/.well-known/did.json
+
+SSRF note
+---------
+did:web is *intentionally* cross-host — the whole point is to resolve a controller's
+own domain — so a fixed host allow-list does NOT apply here (unlike the EBSI client).
+Pass a general-purpose `fetch` for this resolver, ideally one that still enforces
+https and blocks private/link-local address ranges. Do NOT reuse the EBSI client,
+whose allow-list would reject every legitimate did:web host.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+from urllib.parse import unquote
+
+from .base import DidDocument, DidResolutionError, parse_did_document
+
+Fetch = Callable[[str], dict[str, Any]]
+
+
+class DidWebResolver:
+    def __init__(self, fetch: Fetch) -> None:
+        self._fetch = fetch
+
+    def supports(self, did: str) -> bool:
+        return did.startswith("did:web:")
+
+    def resolve(self, did: str) -> DidDocument:
+        raw = self._fetch(self._did_to_url(did))
+        doc = parse_did_document(raw)
+        if doc.id and doc.id != did:                    # basic integrity check
+            raise DidResolutionError(f"document id {doc.id!r} != requested {did!r}")
+        return doc
+
+    @staticmethod
+    def _did_to_url(did: str) -> str:
+        msi = did[len("did:web:"):]
+        if not msi:
+            raise DidResolutionError("empty did:web identifier")
+        parts = msi.split(":")                          # ':' separates path segments
+        host = unquote(parts[0])                        # %3A -> ':' for an explicit port
+        segments = [unquote(p) for p in parts[1:]]
+        if segments:
+            return f"https://{host}/" + "/".join(segments) + "/did.json"
+        return f"https://{host}/.well-known/did.json"

openvc/fetch.py

@@ -0,0 +1,143 @@
+"""
+openvc.fetch — an SSRF-guarded, stdlib-only https JSON fetch for did:web.
+
+did:web is intentionally cross-host (it resolves a controller's own domain), so
+it cannot use a host allow-list like the EBSI client. This fetch instead blocks
+the *dangerous* targets: it requires https, resolves the host and refuses any
+private / loopback / link-local / reserved / multicast address (the cloud
+metadata endpoint 169.254.169.254 is link-local, so it is covered), and refuses
+HTTP redirects — a common SSRF pivot.
+
+DNS-rebinding is closed, not just documented: the connection is **pinned to the
+validated IP** (we resolve, validate every resolved address, then open the TCP
+socket to that exact IP) while TLS SNI, certificate validation, and the Host
+header still use the hostname. So an attacker who flips DNS between the check and
+the connect cannot redirect us to an internal address — we never re-resolve.
+
+Dependency-light on purpose: pure stdlib (http.client + ssl + socket +
+ipaddress). Pass ``https_json_fetch`` wherever a ``Fetch`` is expected, or use
+``default_did_web_resolver()``.
+"""
+from __future__ import annotations
+
+import http.client
+import ipaddress
+import json
+import socket
+import ssl
+from typing import Any
+from urllib.parse import urlparse
+
+from .did.base import DidResolutionError
+from .did.did_web import DidWebResolver
+
+DEFAULT_TIMEOUT_S = 10.0
+MAX_RESPONSE_BYTES = 1_048_576  # 1 MiB — DID documents are small; bound memory.
+_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+
+
+class UnsafeUrlError(DidResolutionError):
+    """The URL or a resolved address is not allowed (scheme, host, or IP range)."""
+
+
+def _ip_is_forbidden(ip_str: str) -> bool:
+    """True for any non-globally-routable / SSRF-sensitive address."""
+    ip = ipaddress.ip_address(ip_str)
+    return (
+        ip.is_private or ip.is_loopback or ip.is_link_local
+        or ip.is_reserved or ip.is_multicast or ip.is_unspecified
+    )
+
+
+def _resolve_public_ips(host: str, port: int) -> list[str]:
+    """Resolve *host* and return its addresses, raising if ANY is SSRF-sensitive
+    (fail closed: one bad address rejects the host)."""
+    try:
+        infos = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+    except socket.gaierror as exc:
+        raise UnsafeUrlError(f"cannot resolve host {host!r}: {exc}") from exc
+    ips = [str(info[4][0]) for info in infos]
+    if not ips:
+        raise UnsafeUrlError(f"host {host!r} did not resolve")
+    for addr in ips:
+        if _ip_is_forbidden(addr):
+            raise UnsafeUrlError(
+                f"host {host!r} resolves to blocked address {addr}")
+    return ips
+
+
+def _https_get(
+    hostname: str, ip: str, port: int, target: str, *,
+    timeout: float, max_bytes: int,
+) -> tuple[int, bytes]:
+    """GET *target* over https, TCP-pinned to *ip* but with TLS SNI, certificate
+    validation and Host header for *hostname*. Returns (status, body). Reads at
+    most ``max_bytes + 1`` so the caller can detect oversize."""
+    context = ssl.create_default_context()
+    conn = http.client.HTTPSConnection(hostname, port, timeout=timeout, context=context)
+
+    def _connect_to_validated_ip(address: Any, timeout: Any = None,
+                                 source_address: Any = None) -> socket.socket:
+        # Ignore the (hostname, port) address http.client would use; connect to
+        # the IP we validated. wrap_socket still uses hostname for SNI + cert.
+        return socket.create_connection((ip, port), timeout=timeout,
+                                        source_address=source_address)
+
+    setattr(conn, "_create_connection", _connect_to_validated_ip)
+    try:
+        conn.request("GET", target, headers={
+            "Accept": "application/did+ld+json, application/json"})
+        resp = conn.getresponse()
+        return resp.status, resp.read(max_bytes + 1)
+    except (OSError, http.client.HTTPException) as exc:
+        raise DidResolutionError(f"fetch failed for https://{hostname}{target}: {exc}") from exc
+    finally:
+        conn.close()
+
+
+def https_json_fetch(
+    url: str,
+    *,
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+    max_bytes: int = MAX_RESPONSE_BYTES,
+) -> dict[str, Any]:
+    """Fetch *url* as JSON with the SSRF guards above. Returns the parsed object.
+
+    Raises :class:`UnsafeUrlError` for a disallowed scheme/host/address or a
+    redirect (a subclass of :class:`~openvc.did.base.DidResolutionError`), and
+    ``DidResolutionError`` for transport / oversize / non-JSON failures.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme != "https":
+        raise UnsafeUrlError(f"only https is allowed, got scheme {parsed.scheme!r}")
+    if not parsed.hostname:
+        raise UnsafeUrlError("URL has no host")
+    port = parsed.port or 443
+    ip = _resolve_public_ips(parsed.hostname, port)[0]
+
+    target = parsed.path or "/"
+    if parsed.query:
+        target += "?" + parsed.query
+
+    status, raw = _https_get(parsed.hostname, ip, port, target,
+                             timeout=timeout_s, max_bytes=max_bytes)
+    if status in _REDIRECT_STATUSES:
+        raise UnsafeUrlError(f"redirect ({status}) not followed (SSRF guard)")
+    if status != 200:
+        raise DidResolutionError(f"unexpected status {status} for {url!r}")
+    if len(raw) > max_bytes:
+        raise DidResolutionError(f"response exceeds {max_bytes} bytes")
+    try:
+        data = json.loads(raw)
+    except (ValueError, json.JSONDecodeError) as exc:
+        raise DidResolutionError(f"response is not JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise DidResolutionError("DID document must be a JSON object")
+    return data
+
+
+def default_did_web_resolver() -> DidWebResolver:
+    """A :class:`~openvc.did.did_web.DidWebResolver` wired to the SSRF-guarded
+    fetch — the batteries-included way to resolve did:web offline of any HTTP
+    client dependency."""
+    return DidWebResolver(https_json_fetch)

openvc/keys.py

@@ -0,0 +1,218 @@
+"""
+openvc.keys — key backends implementing the SigningKey protocol.
+
+Two software backends are provided:
+
+  * Ed25519SigningKey  -> alg "EdDSA"   (default for general OB 3.0 issuance)
+  * P256SigningKey     -> alg "ES256"   (P-256, required for EBSI/EUDI)
+
+Both produce **JWS-compatible** signatures, which is the subtle part:
+
+  * Ed25519 : cryptography already returns the raw 64-byte signature — no change.
+  * ES256   : cryptography returns a DER-encoded ECDSA signature. JOSE requires the
+              fixed-length raw form R||S (32 + 32 = 64 bytes). We convert on sign
+              and back to DER on verify. Getting this wrong is the classic reason a
+              locally-produced ES256 token fails to verify in another stack.
+
+HSM / Vault backends: anything implementing SigningKey (alg, kid, sign returning
+R||S for ES256) is a drop-in replacement — e.g. a PKCS#11 or Vault Transit backend
+whose `sign` performs the operation without the private key ever entering the
+process. These software classes are for dev, tests, and low-assurance issuance.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519
+from cryptography.hazmat.primitives.asymmetric.utils import (
+    decode_dss_signature,
+    encode_dss_signature,
+)
+
+P256_COORD_BYTES = 32  # a P-256 coordinate / scalar is 32 bytes
+
+
+class KeyBackendError(Exception): ...
+class InvalidKey(KeyBackendError): ...
+
+
+# --------------------------------------------------------------------------- #
+# base64url + integer helpers
+# --------------------------------------------------------------------------- #
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(segment: str) -> bytes:
+    return base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4))
+
+
+def _int_to_fixed(n: int, length: int) -> bytes:
+    """Big-endian fixed-length encoding (preserves leading zeros — the whole
+    point of JOSE's fixed-width R and S)."""
+    return n.to_bytes(length, "big")
+
+
+# --------------------------------------------------------------------------- #
+# Ed25519 (EdDSA)
+# --------------------------------------------------------------------------- #
+
+class Ed25519SigningKey:
+    alg = "EdDSA"
+
+    def __init__(self, private_key: ed25519.Ed25519PrivateKey, kid: str) -> None:
+        self._sk = private_key
+        self._kid = kid
+
+    @property
+    def kid(self) -> str:
+        return self._kid
+
+    def sign(self, signing_input: bytes) -> bytes:
+        # cryptography returns the raw 64-byte signature; JOSE-ready as-is.
+        return self._sk.sign(signing_input)
+
+    def public_jwk(self) -> dict[str, Any]:
+        raw = self._sk.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+        return {"kty": "OKP", "crv": "Ed25519", "x": _b64url_encode(raw)}
+
+    def public_key_raw(self) -> bytes:
+        """Raw 32-byte public key (used by the did:key encoder, multicodec 0xed01)."""
+        return self._sk.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+
+    # -- constructors ------------------------------------------------------ #
+
+    @classmethod
+    def generate(cls, kid: str) -> "Ed25519SigningKey":
+        return cls(ed25519.Ed25519PrivateKey.generate(), kid)
+
+    @classmethod
+    def from_jwk(cls, jwk: dict[str, Any], kid: str) -> "Ed25519SigningKey":
+        if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519" or "d" not in jwk:
+            raise InvalidKey("not an Ed25519 private JWK")
+        sk = ed25519.Ed25519PrivateKey.from_private_bytes(_b64url_decode(jwk["d"]))
+        return cls(sk, kid)
+
+    @classmethod
+    def from_pem(cls, pem: bytes, kid: str, password: bytes | None = None) -> "Ed25519SigningKey":
+        sk = serialization.load_pem_private_key(pem, password=password)
+        if not isinstance(sk, ed25519.Ed25519PrivateKey):
+            raise InvalidKey("PEM is not an Ed25519 private key")
+        return cls(sk, kid)
+
+
+# --------------------------------------------------------------------------- #
+# P-256 (ES256)
+# --------------------------------------------------------------------------- #
+
+class P256SigningKey:
+    alg = "ES256"
+
+    def __init__(self, private_key: ec.EllipticCurvePrivateKey, kid: str) -> None:
+        if not isinstance(private_key.curve, ec.SECP256R1):
+            raise InvalidKey("ES256 requires a P-256 (secp256r1) key")
+        self._sk = private_key
+        self._kid = kid
+
+    @property
+    def kid(self) -> str:
+        return self._kid
+
+    def sign(self, signing_input: bytes) -> bytes:
+        der = self._sk.sign(signing_input, ec.ECDSA(hashes.SHA256()))
+        r, s = decode_dss_signature(der)                       # DER -> (int, int)
+        return _int_to_fixed(r, P256_COORD_BYTES) + _int_to_fixed(s, P256_COORD_BYTES)
+
+    def public_jwk(self) -> dict[str, Any]:
+        nums = self._sk.public_key().public_numbers()
+        return {
+            "kty": "EC",
+            "crv": "P-256",
+            "x": _b64url_encode(_int_to_fixed(nums.x, P256_COORD_BYTES)),
+            "y": _b64url_encode(_int_to_fixed(nums.y, P256_COORD_BYTES)),
+        }
+
+    def public_key_raw(self, *, compressed: bool = True) -> bytes:
+        """SEC1 point (compressed by default) — used by the did:key encoder
+        (multicodec 0x1200 for P-256)."""
+        fmt = (serialization.PublicFormat.CompressedPoint if compressed
+               else serialization.PublicFormat.UncompressedPoint)
+        return self._sk.public_key().public_bytes(serialization.Encoding.X962, fmt)
+
+    # -- constructors ------------------------------------------------------ #
+
+    @classmethod
+    def generate(cls, kid: str) -> "P256SigningKey":
+        return cls(ec.generate_private_key(ec.SECP256R1()), kid)
+
+    @classmethod
+    def from_jwk(cls, jwk: dict[str, Any], kid: str) -> "P256SigningKey":
+        if jwk.get("kty") != "EC" or jwk.get("crv") != "P-256" or "d" not in jwk:
+            raise InvalidKey("not a P-256 private JWK")
+        d = int.from_bytes(_b64url_decode(jwk["d"]), "big")
+        return cls(ec.derive_private_key(d, ec.SECP256R1()), kid)
+
+    @classmethod
+    def from_pem(cls, pem: bytes, kid: str, password: bytes | None = None) -> "P256SigningKey":
+        sk = serialization.load_pem_private_key(pem, password=password)
+        if not isinstance(sk, ec.EllipticCurvePrivateKey):
+            raise InvalidKey("PEM is not an EC private key")
+        return cls(sk, kid)
+
+
+# --------------------------------------------------------------------------- #
+# Dependency-light verification (for did:key self-contained verify + tests)
+# --------------------------------------------------------------------------- #
+
+def verify_signature(
+    *, alg: str, public_jwk: dict[str, Any], signing_input: bytes, signature: bytes
+) -> bool:
+    """Verify a JOSE signature directly from a public JWK, without PyJWT.
+
+    Handy for did:key (where the key is inside the DID) and for round-trip tests.
+    The VC verification path uses the proof suite instead; this is complementary.
+    """
+    try:
+        if alg == "EdDSA":
+            raw = _b64url_decode(public_jwk["x"])
+            ed25519.Ed25519PublicKey.from_public_bytes(raw).verify(signature, signing_input)
+            return True
+        if alg == "ES256":
+            if len(signature) != 2 * P256_COORD_BYTES:
+                raise InvalidKey("ES256 signature must be 64-byte R||S")
+            r = int.from_bytes(signature[:P256_COORD_BYTES], "big")
+            s = int.from_bytes(signature[P256_COORD_BYTES:], "big")
+            der = encode_dss_signature(r, s)                   # R||S -> DER for verify
+            pub = ec.EllipticCurvePublicNumbers(
+                int.from_bytes(_b64url_decode(public_jwk["x"]), "big"),
+                int.from_bytes(_b64url_decode(public_jwk["y"]), "big"),
+                ec.SECP256R1(),
+            ).public_key()
+            pub.verify(der, signing_input, ec.ECDSA(hashes.SHA256()))
+            return True
+        raise InvalidKey(f"unsupported alg {alg!r}")
+    except InvalidSignature:
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# Convenience factory
+# --------------------------------------------------------------------------- #
+
+def signing_key_from_jwk(jwk: dict[str, Any], kid: str):
+    """Dispatch to the right backend from a private JWK."""
+    kty, crv = jwk.get("kty"), jwk.get("crv")
+    if kty == "OKP" and crv == "Ed25519":
+        return Ed25519SigningKey.from_jwk(jwk, kid)
+    if kty == "EC" and crv == "P-256":
+        return P256SigningKey.from_jwk(jwk, kid)
+    raise InvalidKey(f"unsupported key type kty={kty!r} crv={crv!r}")