ffn-verify 0.1.0__py3-none-any.whl

ffn_verify/__init__.py

@@ -0,0 +1,45 @@
+"""FFN Verified Business public verifier.
+
+verify_business(domain): registry record, both signatures, status, domain binding
+and delegation, no wallet needed. A port of @fofonet/verify-business; both replay
+the same test vectors (ffn-pass/vectors/business/v1.json).
+
+Data that mirrors the TS JSON (registry anchors, observed facts, presentation
+input, every result) uses the TS camelCase keys; Python names are snake_case.
+"""
+
+from ._version import __version__
+from .credential import CredentialError, verify_credential
+from .delegation import verify_delegation_chain
+from .did import DidResolver
+from .dns import doh_resolver, static_txt
+from .domain import IdentifierError, normalize_domain, normalize_phone
+from .fetch import urllib_fetch
+from .networks import FFN_BUSINESS_REGISTRY
+from .pin import PinnedRegistryResolver, key_thumbprint, pin_registry_keys
+from .presentation import verify_presentation
+from .status import StatusChecker
+from .verify import VerificationError, lookup_business, verify_business
+
+__all__ = [
+    "__version__",
+    "FFN_BUSINESS_REGISTRY",
+    "CredentialError",
+    "DidResolver",
+    "IdentifierError",
+    "PinnedRegistryResolver",
+    "StatusChecker",
+    "VerificationError",
+    "doh_resolver",
+    "key_thumbprint",
+    "lookup_business",
+    "normalize_domain",
+    "normalize_phone",
+    "pin_registry_keys",
+    "static_txt",
+    "urllib_fetch",
+    "verify_business",
+    "verify_credential",
+    "verify_delegation_chain",
+    "verify_presentation",
+]

ffn_verify/_egress.py

@@ -0,0 +1,167 @@
+"""Which URLs the verifier fetches on someone else's say-so.
+
+A status list URI and a did:web come from credentials and records, so a hostile one
+could point the verifier at the network it runs in. Before any request to such a URL:
+
+* it must be ``https:``;
+* its host must not be an IP literal in a private, loopback, link-local, CGNAT,
+  multicast, unspecified or reserved range (IPv4 or IPv6, IPv4-mapped included), nor
+  ``localhost``, ``*.localhost``, ``*.local``, ``*.internal`` or a single-label name
+  (``metadata``, ``printer``), which resolves through the local search domains.
+
+This checks the URL, not where its name resolves: a public name whose DNS answers with
+a private address (DNS rebinding) passes. Run the verifier behind an egress proxy
+that refuses private destinations if that matters where it runs.
+
+The host is read with the WHATWG parser (as the TS verifier and browsers read it).
+Python's own HTTP stack splits URLs differently in a few places (``\\``, ``@`` and
+non-ASCII in the authority), so a URL whose authority holds any of those is refused
+rather than fetched under two readings.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+
+from .url import URL, URLError
+
+
+class RefusedURL(ValueError):
+    """The URL is not one the verifier fetches. No request was made."""
+
+
+_V4_REFUSED = tuple(ipaddress.IPv4Network(n) for n in (
+    "0.0.0.0/8",  # "this network", unspecified
+    "10.0.0.0/8",  # private
+    "100.64.0.0/10",  # CGNAT shared address space
+    "127.0.0.0/8",  # loopback
+    "169.254.0.0/16",  # link-local
+    "172.16.0.0/12",  # private
+    "192.0.0.0/24",  # IETF protocol assignments
+    "192.0.2.0/24",  # documentation
+    "192.88.99.0/24",  # 6to4 relay anycast (deprecated)
+    "192.168.0.0/16",  # private
+    "198.18.0.0/15",  # benchmarking
+    "198.51.100.0/24",  # documentation
+    "203.0.113.0/24",  # documentation
+    "224.0.0.0/4",  # multicast
+    "240.0.0.0/4",  # reserved, and the broadcast address
+))
+# IPv6: only global unicast (2000::/3) is ever public; inside it, these are not.
+_V6_GLOBAL_UNICAST = ipaddress.IPv6Network("2000::/3")
+_V6_REFUSED_IN_GLOBAL = tuple(ipaddress.IPv6Network(n) for n in (
+    "2001::/23",  # IETF protocol assignments (Teredo, benchmarking, ORCHID)
+    "2001:db8::/32",  # documentation
+    "3fff::/20",  # documentation
+    "2002::/16",  # 6to4
+))
+_V6_NAT64 = ipaddress.IPv6Network("64:ff9b::/96")  # well-known prefix: the low 32 bits are an IPv4 address
+
+_LOCAL_NAMES = ("localhost",)
+_LOCAL_SUFFIXES = (".localhost", ".local", ".internal")
+
+
+def refused_ip(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    """Is this address one the verifier never fetches from?"""
+    if isinstance(ip, ipaddress.IPv4Address):
+        return any(ip in n for n in _V4_REFUSED)
+    if ip.ipv4_mapped is not None:
+        return refused_ip(ip.ipv4_mapped)
+    if ip in _V6_NAT64:
+        return refused_ip(ipaddress.IPv4Address(int(ip) & 0xFFFF_FFFF))
+    if ip not in _V6_GLOBAL_UNICAST:
+        return True  # unspecified, loopback, mapped/compatible, ULA, link-local, multicast, reserved
+    return any(ip in n for n in _V6_REFUSED_IN_GLOBAL)
+
+
+def _ip_literal(hostname: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    """The address a WHATWG-parsed hostname names, or None for a domain name."""
+    if hostname.startswith("[") and hostname.endswith("]"):
+        return ipaddress.IPv6Address(hostname[1:-1])
+    if re.fullmatch(r"[0-9]+(\.[0-9]+){3}", hostname):
+        return ipaddress.IPv4Address(hostname)  # the parser has already normalized every IPv4 form
+    return None
+
+
+def _name(hostname: str) -> str:
+    return hostname.lower().rstrip(".")
+
+
+def refused_host(hostname: str) -> bool:
+    """A WHATWG ``URL.hostname`` the verifier never fetches from."""
+    ip = _ip_literal(hostname)
+    if ip is not None:
+        return refused_ip(ip)
+    name = _name(hostname)
+    if name in _LOCAL_NAMES or name.endswith(_LOCAL_SUFFIXES):
+        return True
+    # A single label (metadata, printer) resolves through the local search domains,
+    # i.e. inside the network the verifier runs in.
+    return "." not in name
+
+
+def is_loopback_host(hostname: str) -> bool:
+    """127.0.0.0/8, ::1 (or IPv4-mapped loopback), ``localhost`` or ``*.localhost``:
+    where plain http is allowed, for a registry under local test."""
+    try:
+        ip = _ip_literal(hostname)
+    except ValueError:
+        return False
+    if ip is None:
+        name = _name(hostname)
+        return name == "localhost" or name.endswith(".localhost")
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    return ip.is_loopback
+
+
+_UNSAFE_IN_AUTHORITY = re.compile(r"[^\x21-\x7e]|[@\\]")
+
+
+def check_public_https(url: str, what: str = "URL") -> URL:
+    """Raise RefusedURL unless ``url`` is an https URL on a public host (see the module doc)."""
+    if not isinstance(url, str) or not url.startswith("https://"):
+        raise RefusedURL(f"{what} must be https")
+    if re.search(r"[\x00-\x20\x7f]", url):
+        raise RefusedURL(f"{what} is not a plain URL")
+    _check_authority(url, what)
+    try:
+        parsed = URL(url)
+    except (URLError, ValueError):
+        raise RefusedURL(f"{what} is not a valid URL") from None
+    try:
+        refused = refused_host(parsed.hostname)
+    except ValueError:
+        refused = True
+    if refused:
+        raise RefusedURL(f"{what} points at a private or local host")
+    return parsed
+
+
+def _check_authority(url: str, what: str) -> None:
+    """The authority as written, before any parser normalizes it (up to the first / ? or
+    #): empty, or holding @, \\, whitespace, a control character or non-ASCII, it could
+    be read two ways."""
+    m = re.match(r"[A-Za-z][A-Za-z0-9+.\-]*://([^/?#]*)", url)
+    if not m or not m.group(1) or _UNSAFE_IN_AUTHORITY.search(m.group(1)):
+        raise RefusedURL(f"{what} is not a plain URL")
+
+
+def check_registry_origin(origin: str) -> URL:
+    """The registry origin a caller pins: https, or http on a loopback host
+    (``localhost`` included) for local tests. The caller chooses it, so unlike the
+    hosts a record or presentation names, a single-label name is allowed, as in
+    door-core's net.ts."""
+    try:
+        if not isinstance(origin, str):
+            raise TypeError
+        _check_authority(origin, "the registry origin")
+        parsed = URL(origin)
+    except (URLError, ValueError, TypeError):
+        raise ValueError(f"the registry origin is not a plain URL: {origin!r}") from None
+    if parsed.scheme == "https" and parsed.hostname:
+        return parsed
+    if parsed.scheme == "http" and is_loopback_host(parsed.hostname):
+        return parsed
+    raise ValueError("the registry origin must be https (plain http only on a loopback host)")

ffn_verify/_js.py

@@ -0,0 +1,135 @@
+"""The few JavaScript semantics the TypeScript verifier leans on.
+
+The verifier reads JSON from untrusted hosts. Where the TS code relies on a JS
+behaviour that Python doesn't share (truthiness of ``{}`` and ``[]``,
+``String(x)`` in a template literal, ``obj.key`` on ``null`` throwing), these
+helpers reproduce it, so odd input fails or passes the same way in both.
+
+JSON ``null`` and a missing key both read as ``None`` here. Where the TS code
+tells them apart (``x !== undefined``), the caller checks ``key in obj``.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from typing import Any
+
+# JS WhiteSpace and LineTerminator: what String.prototype.trim() strips and \s matches.
+JS_WHITESPACE = (
+    "\t\n\v\f\r           "
+    "   

  　"
+)
+JS_WS_CLASS = "[" + "".join(f"\\u{ord(c):04x}" for c in JS_WHITESPACE) + "]"
+
+
+def trim(s: str) -> str:
+    return s.strip(JS_WHITESPACE)
+
+
+def is_num(v: Any) -> bool:
+    """typeof v === 'number' (JSON never yields NaN or Infinity)."""
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def truthy(v: Any) -> bool:
+    if v is None or v is False:
+        return False
+    if is_num(v):
+        return v != 0 and not (isinstance(v, float) and math.isnan(v))
+    if isinstance(v, str):
+        return v != ""
+    return True  # objects and arrays, even empty ones
+
+
+def prop(obj: Any, key: str) -> Any:
+    """obj.key: throws on null/undefined, undefined on anything that isn't an object."""
+    if obj is None:
+        raise TypeError(f"Cannot read properties of null (reading '{key}')")
+    return obj.get(key) if isinstance(obj, dict) else None
+
+
+def opt(obj: Any, key: str) -> Any:
+    """obj?.key"""
+    return None if obj is None else prop(obj, key)
+
+
+def array(v: Any, what: str = "value") -> list:
+    """What .map/.filter/.some on a non-array would throw for."""
+    if not isinstance(v, list):
+        raise TypeError(f"{what} is not an array")
+    return v
+
+
+def iterable(v: Any, what: str = "value") -> list:
+    """for...of and spread: arrays, and strings by code point."""
+    if isinstance(v, list):
+        return v
+    if isinstance(v, str):
+        return list(v)
+    raise TypeError(f"{what} is not iterable")
+
+
+def same(a: Any, b: Any) -> bool:
+    """SameValueZero for JSON values (no bool/number mixing, 2 == 2.0)."""
+    if is_num(a) and is_num(b):
+        return a == b
+    return type(a) is type(b) and a == b
+
+
+def includes(container: Any, item: Any) -> bool:
+    """Array.prototype.includes, or String.prototype.includes when it's a string."""
+    if isinstance(container, list):
+        return any(same(x, item) for x in container)
+    if isinstance(container, str):
+        return js_str(item) in container
+    raise TypeError("includes is not a function")
+
+
+def js_str(v: Any) -> str:
+    """String(v), as a template literal renders it."""
+    if v is None:
+        return "null"
+    if v is True:
+        return "true"
+    if v is False:
+        return "false"
+    if isinstance(v, str):
+        return v
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, float):
+        if v.is_integer() and abs(v) < 1e21:
+            return str(int(v))
+        return repr(v)
+    if isinstance(v, list):
+        return ",".join("" if x is None else js_str(x) for x in v)
+    return "[object Object]"
+
+
+def template(obj: Any, key: str) -> str:
+    """`${obj.key}`: a missing member renders as "undefined", null as "null"."""
+    prop(obj, key)  # null throws
+    return js_str(obj[key]) if isinstance(obj, dict) and key in obj else "undefined"
+
+
+def nullish(v: Any, default: Any) -> Any:
+    """v ?? default"""
+    return default if v is None else v
+
+
+def join(values: list, sep: str) -> str:
+    """Array.prototype.join: null and undefined become empty strings."""
+    return sep.join("" if v is None else js_str(v) for v in values)
+
+
+def utf16_key(v: Any) -> bytes:
+    """Sort key matching Array.prototype.sort()'s default (UTF-16 code units of String(v))."""
+    return js_str(v).encode("utf-16-be", "surrogatepass")
+
+
+def iso(seconds: float) -> str:
+    """new Date(seconds * 1000).toISOString()"""
+    ms = int(seconds * 1000)  # Date truncates toward zero
+    dt = datetime.fromtimestamp(ms // 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S") + f".{ms % 1000:03d}Z"

ffn_verify/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ffn_verify/binding.py

@@ -0,0 +1,68 @@
+"""Domain binding records, as door-core's binding.ts.
+
+The registry lists the business's official domains, and each domain points back:
+
+    https://<domain>/.well-known/did.json   the business DID document, with a service
+                                             entry naming its registry record
+    _ffn.<domain>  TXT  "v=ffn1; did=<did>; registry=<registry host>"
+
+A lookalike domain fails both directions. Verifiers trust the registry they already
+know, never what the page says.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ._js import JS_WS_CLASS, prop, trim
+
+FFN_SERVICE_TYPE = "FfnVerifiedBusiness"
+FFN_TXT_PREFIX = "_ffn"
+
+
+def registry_entries_of(doc: dict) -> list[str]:
+    """Registry record URLs the DID document points at (service entries of type FfnVerifiedBusiness).
+    A ``service`` that isn't an array, and entries that aren't objects, point nowhere."""
+    out: list[str] = []
+    services = doc.get("service")
+    if not isinstance(services, list):
+        return out
+    for s in services:
+        if not isinstance(s, dict):
+            continue
+        types = prop(s, "type")
+        types = types if isinstance(types, list) else [types]
+        if FFN_SERVICE_TYPE not in [t for t in types if isinstance(t, str)]:
+            continue
+        ends = prop(s, "serviceEndpoint")
+        for e in ends if isinstance(ends, list) else [ends]:
+            if isinstance(e, str):
+                out.append(e)
+    return out
+
+
+def ffn_txt_name(domain: str) -> str:
+    return f"{FFN_TXT_PREFIX}.{domain}"
+
+
+_SPLIT_QUOTES = re.compile('"' + JS_WS_CLASS + '*"')
+
+
+def unquote_txt(value: str) -> str:
+    # DNS answers may arrive quoted or split into 255-byte strings.
+    return re.sub(r'^"|"\Z', "", _SPLIT_QUOTES.sub("", value))
+
+
+def parse_ffn_txt(value: Any) -> dict | None:
+    """{v, did, registry} from a _ffn TXT value, or None when it isn't one."""
+    if not isinstance(value, str):
+        raise TypeError("value.replace is not a function")
+    fields = {}
+    for part in unquote_txt(value).split(";"):
+        kv = trim(part).split("=")
+        if len(kv) >= 2:
+            fields[trim(kv[0])] = trim("=".join(kv[1:]))
+    if fields.get("v") != "ffn1" or not fields.get("did") or not fields.get("registry"):
+        return None
+    return {"v": "ffn1", "did": fields["did"], "registry": fields["registry"]}

ffn_verify/business.py

@@ -0,0 +1,60 @@
+"""FFN Verified Business credential kinds, levels and labels, as door-core's business.ts.
+
+A business holds several narrow credentials rather than one big one, so each
+expires and is revoked on its own schedule. The business signs its own profile and
+its delegations; SPT signs only the attestations.
+"""
+
+from __future__ import annotations
+
+VCT_BASE = "https://pass.fofo.network/vct"
+
+BUSINESS_KINDS = {
+    "businessProfile": f"{VCT_BASE}/business-profile/v1",
+    "delegation": f"{VCT_BASE}/delegation/v1",
+    "businessIdentity": f"{VCT_BASE}/business-identity/v1",
+    "officialChannels": f"{VCT_BASE}/official-channels/v1",
+    "license": f"{VCT_BASE}/license/v1",
+    "insurance": f"{VCT_BASE}/insurance/v1",
+    "representative": f"{VCT_BASE}/representative/v1",
+}
+
+ATTESTATION_KINDS = ("businessIdentity", "officialChannels", "license", "insurance", "representative")
+
+KIND_LABELS = {
+    "businessProfile": "Business profile",
+    "delegation": "Delegation",
+    "businessIdentity": "Business identity",
+    "officialChannels": "Official channels",
+    "license": "License",
+    "insurance": "Insurance",
+    "representative": "Verified representative",
+}
+
+LEVEL_NAMES = {0: "Not verified", 1: "Registered", 2: "Licensed and insured", 3: "Owner verified"}
+
+# What each level needs, cumulatively.
+LEVEL_REQUIREMENTS = {
+    1: ("businessIdentity", "officialChannels"),
+    2: ("businessIdentity", "officialChannels", "license", "insurance"),
+    3: ("businessIdentity", "officialChannels", "license", "insurance", "representative"),
+}
+
+# The delegation every listing carries: the business lets the registry publish and serve its record.
+REGISTRY_SCOPES = ("registry:publish", "registry:serve")
+
+BUSINESS_RECORD_TYP = "ffn-business-record+jwt"
+
+
+def kind_for_vct(vct: str) -> str | None:
+    for kind, value in BUSINESS_KINDS.items():
+        if value == vct:
+            return kind
+    return None
+
+
+def level_for(valid: set[str]) -> int:
+    for level in (3, 2, 1):
+        if all(k in valid for k in LEVEL_REQUIREMENTS[level]):
+            return level
+    return 0

ffn_verify/credential.py

@@ -0,0 +1,100 @@
+"""Verifying an SD-JWT VC outside the OpenID4VC flows, as door-core's credential.ts:
+a business's own profile, SPT's attestations for the registry, an agent presenting
+a delegation over plain HTTP. No wallet or trust registry needed to check one.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+
+from . import sdjwt
+from ._js import is_num, opt, prop, truthy
+from .did import DidResolver
+from .jose import b64u_encode, decode_jwt, header_kid, jwk_thumbprint, sha256
+
+
+class CredentialError(Exception):
+    def __init__(self, message: str, code: str = "invalid_credential"):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def issuer_jwt_of(compact: str) -> str:
+    """Issuer-signed part of a compact SD-JWT (everything before the first '~')."""
+    return compact.split("~")[0]
+
+
+def credential_hash(compact: str) -> str:
+    """Base64url SHA-256 of the issuer-signed JWT: how a child delegation names its parent."""
+    return b64u_encode(sha256(issuer_jwt_of(compact)))
+
+
+def same_key(a: Any, b: Any) -> bool:
+    """Same key? Thumbprints, so member order and extra members don't matter."""
+    return jwk_thumbprint(a) == jwk_thumbprint(b)
+
+
+def verify_credential(compact: str, *, resolver: DidResolver, now: float | None = None, skew_seconds: float = 60,
+                      key_binding: dict | None = None) -> dict:
+    """Verify the issuer signature (key from the issuer's DID document), every disclosure,
+    the time claims and, when ``key_binding`` ({nonce, audience, maxAgeSeconds}) is given,
+    the holder's key binding. Status is separate (see StatusChecker) because callers treat
+    an unreachable status list differently.
+
+    Returns {header, claims, iss, vct, cnfJwk, issuerKey, kb?}. Raises CredentialError.
+    """
+    try:
+        header, payload, _, _ = decode_jwt(issuer_jwt_of(compact))
+    except Exception:
+        raise CredentialError("malformed credential") from None
+    iss, vct = prop(payload, "iss"), prop(payload, "vct")
+    if not isinstance(iss, str) or not isinstance(vct, str):
+        raise CredentialError("credential has no issuer or type")
+    if prop(header, "alg") != "ES256":
+        raise CredentialError("unsupported alg")
+    cnf_jwk = opt(prop(payload, "cnf"), "jwk")
+    if not truthy(cnf_jwk):
+        raise CredentialError("credential is not key-bound")
+
+    try:
+        issuer_key = resolver.assertion_key(iss, header_kid(header))
+    except Exception as err:
+        raise CredentialError(f"issuer key not found: {err}", "untrusted_issuer") from None
+
+    now = int(time.time()) if now is None else now
+    skew = skew_seconds
+    kb_options = None
+    if key_binding is not None:
+        max_age = key_binding.get("maxAgeSeconds")
+        kb_options = {**key_binding, "maxAgeSeconds": 300 if max_age is None else max_age}
+    try:
+        claims, kb_payload = sdjwt.verify(compact, issuer_key=issuer_key, cnf_jwk=cnf_jwk, now=now, skew=skew,
+                                          key_binding=kb_options)
+    except Exception as err:
+        message = str(err)
+        code = "expired" if re.search(r"\bis expired\b", message, re.ASCII) else "invalid_credential"
+        raise CredentialError(f"credential failed verification: {message}", code) from None
+    # Belt and braces on time: the library's checks read the disclosed claims.
+    exp, nbf = payload.get("exp"), payload.get("nbf")
+    if is_num(exp) and now - skew > exp:
+        raise CredentialError("credential expired", "expired")
+    if is_num(nbf) and now + skew < nbf:
+        raise CredentialError("credential not yet valid")
+
+    result = {"header": header, "claims": claims, "iss": iss, "vct": vct, "cnfJwk": cnf_jwk, "issuerKey": issuer_key}
+    if kb_options is not None:
+        if kb_payload is None:
+            raise CredentialError("key binding missing")
+        if kb_payload.get("aud") != kb_options.get("audience"):
+            raise CredentialError("key binding audience mismatch")
+        if kb_payload.get("nonce") != kb_options.get("nonce"):
+            raise CredentialError("key binding nonce mismatch")
+        iat = kb_payload.get("iat")
+        age = now - (0 if iat is None else iat)
+        if age > kb_options["maxAgeSeconds"] + skew or age < -skew:
+            raise CredentialError("key binding is stale")
+        result["kb"] = {"aud": kb_payload["aud"], "nonce": kb_payload["nonce"], "iat": iat}
+    return result