trooth 0.1.0__py3-none-any.whl

trooth_semanto_verify/cli.py

@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Trooth, LLC
+#
+# semanto-verify for Python: the same commands as verifier/js/cli.mjs. Prints
+# one line per check in plain words and exits 0 only when every check passed.
+#
+#   semanto-verify file <semanto.json> [--pages <dir>] [--keys <keys.json>] [--now <iso>] [--revocations <file>]
+#   semanto-verify page <url> [--trooth <base>] [--now <iso>] [--allow-unwitnessed] [--allow-unlogged] [--allow-unsigned]
+#   semanto-verify response <url> [--keys <keys.json>]
+#   semanto-verify log --from <n> --to <m> [--log <url>] [--keys <keys.json>]
+#
+# Keys are kept apart by role: the company's JWK Set (from its domain) checks
+# company signatures; Trooth's checks witness statements, tree heads and
+# revocation lists. `page` is strict by default: the version header must be
+# fetched, and a missing witness statement or log entry fails unless allowed.
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+from typing import Any, Optional
+from urllib.parse import urljoin, urlsplit
+
+from .jws import parse_dns_key_records
+from .verify import (
+    parse_link,
+    state_of,
+    verify_consistency,
+    verify_page_proof,
+    verify_response,
+    verify_revocation_list,
+    verify_semanto,
+    verify_tree_head,
+)
+
+TROOTH_API = "https://api.trooth.co"
+# Trooth's witness keys, served by the Semanto Worker; --trooth <base> reads <base>/.well-known/trooth-keys.json instead.
+TROOTH_KEYS_BASE = f"{TROOTH_API}/public/semanto"
+DEFAULT_LOG = f"{TROOTH_API}/public/semanto/log"
+
+
+def _read_json(path: str) -> Any:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _fetch(url: str, accept: str = "application/json") -> tuple[int, dict, bytes]:
+    req = urllib.request.Request(url, headers={"Accept": accept, "User-Agent": "semanto-verify/0.1 (python)"})
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in e.headers.items()}, e.read()
+
+
+def _fetch_json(url: str) -> Any:
+    status, _, body = _fetch(url)
+    if status != 200:
+        raise RuntimeError(f"{url} answered {status}")
+    return json.loads(body)
+
+
+def _print(result: dict, title: str) -> bool:
+    print(title)
+    for c in result.get("checks") or []:
+        print(f"  {'ok  ' if c['ok'] else 'FAIL'} {c['name']}: {c['detail']}")
+    if "checks" not in result:
+        print(f"  {'ok  ' if result['ok'] else 'FAIL'} {result.get('reason') or ''}")
+    for n in result.get("notes") or []:
+        print(f"  note {n}")
+    print("Every check passed." if result["ok"] else f"Failed: {result.get('reason')}.")
+    print()
+    return bool(result["ok"])
+
+
+def _load_keys(domain: str, args: argparse.Namespace) -> Any:
+    if args.keys:
+        return _read_json(args.keys)
+    keys: dict = {"company": {"keys": []}, "trooth": {"keys": []}}
+    for role, url in (("company", f"https://{domain}/.well-known/trooth-keys.json"), ("trooth", f"{args.trooth or TROOTH_KEYS_BASE}/.well-known/trooth-keys.json")):
+        try:
+            keys[role] = _fetch_json(url)
+            print(f"  ok   fetched the {'company' if role == 'company' else 'Trooth'} JWK Set at {url}")
+        except Exception as e:  # noqa: BLE001 - we report and continue
+            print(f"  note {url} could not be read ({e})")
+    return keys
+
+
+def _dns_note(domain: str, kid: Optional[str]) -> None:
+    if not kid:
+        return
+    try:
+        import subprocess
+
+        out = subprocess.run(["dig", "+short", "TXT", f"_trooth-keys.{domain}"], capture_output=True, text=True, timeout=10).stdout
+        kids = parse_dns_key_records([l.strip().strip('"') for l in out.splitlines()])
+    except Exception:  # noqa: BLE001
+        print(f"DNS binding\n  note _trooth-keys.{domain} was not checked (no dig on this machine).\n")
+        return
+    if kid in kids:
+        print(f"DNS binding\n  ok   _trooth-keys.{domain} TXT names key {kid}.\n")
+    elif kids:
+        print(f"DNS binding\n  note _trooth-keys.{domain} TXT names {', '.join(kids)}, not the signing key {kid}.\n")
+    else:
+        print(f"DNS binding\n  note _trooth-keys.{domain} has no v=trooth1 record.\n")
+
+
+def cmd_file(args: argparse.Namespace) -> int:
+    doc = _read_json(args.path)
+    file = doc.get("file", doc)
+    base = os.path.dirname(os.path.abspath(args.path))
+    if args.keys:
+        keys = _read_json(args.keys)
+    elif os.path.exists(os.path.join(base, "keys.json")):
+        keys = _read_json(os.path.join(base, "keys.json"))
+    elif args.offline:
+        keys = {}
+    else:
+        keys = _load_keys(file["header"]["identity"]["domain"], args)
+    pages_dir = args.pages or (os.path.join(base, "pages") if os.path.isdir(os.path.join(base, "pages")) else None)
+    pages: dict = {}
+    if pages_dir:
+        for p in file["header"]["pages_manifest"]:
+            f = os.path.join(pages_dir, f"{p['id']}.md")
+            if os.path.exists(f):
+                with open(f, "rb") as fh:
+                    pages[p["url"]] = fh.read()
+        print(f"Pages: {len(pages)} of {len(file['header']['pages_manifest'])} found in {pages_dir}.")
+    revocations = None
+    if args.revocations:
+        r = _read_json(args.revocations)
+        v = verify_revocation_list(r.get("jws", r), keys, now=args.now)
+        print(f"Revocation list: {'signed by Trooth' if v['ok'] else 'not accepted (' + v['reason'] + ')'}.")
+        if v["ok"]:
+            revocations = v["payload"]
+    result = verify_semanto(file, pages, keys, now=args.now or doc.get("now"), revocations=revocations)
+    return 0 if _print(result, f"Semanto file {args.path} (version {result.get('version_id') or 'unknown'})") else 1
+
+
+def cmd_response(args: argparse.Namespace, also_proof: bool = False) -> int:
+    status, headers, body = _fetch(args.url, accept="text/markdown")
+    print(f"GET {args.url} with Accept: text/markdown answered {status} {headers.get('content-type', '')}")
+    domain = urlsplit(args.url).hostname or ""
+    keys = _load_keys(domain, args)
+    resp = verify_response(status, headers, body, keys, now=args.now)
+    ok = _print(resp, "Signed response")
+    _dns_note(domain, resp.get("keyid"))
+    if also_proof:
+        links = parse_link(headers.get("link"))
+        proof_link = next((l for l in links if any(r in ("proof", "https://trooth.co/rel/proof") for r in (l["params"].get("rel") or "").split())), None)
+        if not proof_link:
+            print('Proof\n  FAIL the response has no Link rel="https://trooth.co/rel/proof".\n')
+            ok = False
+        else:
+            proof_url = urljoin(args.url, proof_link["url"])
+            try:
+                doc = _fetch_json(proof_url)
+                proof = doc.get("proof", doc)
+                header = doc.get("header")
+                if header is None and isinstance(proof.get("version"), int):
+                    import re as _re
+
+                    version_url = _re.sub(r"/pages/[^/]+/proof$", f"/versions/{proof['version']}", proof_url)
+                    try:
+                        header = _fetch_json(version_url).get("header")
+                        print(f"  ok   fetched the version header at {version_url}")
+                    except Exception as e:  # noqa: BLE001
+                        # Strict: a header that cannot be fetched is a failure, not a skip.
+                        print(f"  FAIL {version_url} could not be read ({e}); without the header the proof is not tied to a signed version.")
+                pr = verify_page_proof(proof, body, keys, now=args.now, header=header, allow_unwitnessed=getattr(args, "allow_unwitnessed", False), allow_unlogged=getattr(args, "allow_unlogged", False), allow_unsigned=getattr(args, "allow_unsigned", False))
+                ok = _print(pr, f"Proof at {proof_url}") and ok
+                if header:
+                    print(f"State now: {state_of({'header': header, 'root_hash': proof.get('root_hash'), 'signature': proof.get('signature')}, args.now)}.\n")
+            except Exception as e:  # noqa: BLE001
+                print(f"Proof\n  FAIL {proof_url} could not be read or parsed ({e}).\n")
+                ok = False
+    return 0 if ok else 1
+
+
+def cmd_log(args: argparse.Namespace) -> int:
+    log = args.log or DEFAULT_LOG
+    # Tree heads are Trooth's statements: only Trooth's keys check them.
+    keys = _read_json(args.keys) if args.keys else {"trooth": _fetch_json(f"{args.trooth or TROOTH_KEYS_BASE}/.well-known/trooth-keys.json")}
+    old = _fetch_json(f"{log}/tree-head?size={args.from_size}")
+    new = _fetch_json(f"{log}/tree-head?size={args.to_size}")
+    cons = _fetch_json(f"{log}/consistency?from={args.from_size}&to={args.to_size}")
+    ok = True
+    for name, head in ((f"Tree head at size {args.from_size}", old), (f"Tree head at size {args.to_size}", new)):
+        v = verify_tree_head(head, keys, now=args.now)
+        print(f"{name}: {'signed by Trooth key ' + v['kid'] + ', root ' + v['root_hash'] if v['ok'] else 'FAIL ' + v['reason']}")
+        ok = ok and v["ok"]
+    root_of = lambda head: (head.get("payload") or {}).get("root_hash") or head.get("root_hash")  # noqa: E731
+    c = verify_consistency({"from": args.from_size, "to": args.to_size, "old_root": root_of(old), "new_root": root_of(new), "path": cons.get("path", cons)})
+    print(f"Consistency {args.from_size} to {args.to_size}: " + ("the older tree is a prefix of the newer one; nothing was removed or rewritten" if c else "FAIL the proof does not connect the two roots"))
+    return 0 if ok and c else 1
+
+
+def main(argv: Optional[list] = None) -> int:
+    p = argparse.ArgumentParser(prog="semanto-verify", description="Check a Semanto file, a page, a signed response or the public log. Exit 0 means every check passed.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    f = sub.add_parser("file", help="check a Semanto file offline")
+    f.add_argument("path")
+    f.add_argument("--pages")
+    f.add_argument("--keys")
+    f.add_argument("--now")
+    f.add_argument("--revocations")
+    f.add_argument("--offline", action="store_true")
+    f.add_argument("--trooth")
+    for name in ("page", "response"):
+        s = sub.add_parser(name, help="fetch a url with Accept: text/markdown and check the signed answer" + (" and its proof" if name == "page" else ""))
+        s.add_argument("url")
+        s.add_argument("--keys")
+        s.add_argument("--now")
+        s.add_argument("--trooth")
+        if name == "page":
+            s.add_argument("--allow-unwitnessed", action="store_true")
+            s.add_argument("--allow-unlogged", action="store_true")
+            s.add_argument("--allow-unsigned", action="store_true")
+    l = sub.add_parser("log", help="check two tree heads and the consistency proof between them")
+    l.add_argument("--from", dest="from_size", type=int, required=True)
+    l.add_argument("--to", dest="to_size", type=int, required=True)
+    l.add_argument("--log")
+    l.add_argument("--keys")
+    l.add_argument("--now")
+    l.add_argument("--trooth")
+    args = p.parse_args(argv)
+    try:
+        if args.cmd == "file":
+            return cmd_file(args)
+        if args.cmd == "page":
+            return cmd_response(args, also_proof=True)
+        if args.cmd == "response":
+            return cmd_response(args)
+        if args.cmd == "log":
+            return cmd_log(args)
+    except Exception as e:  # noqa: BLE001
+        print(f"semanto-verify: {e}", file=sys.stderr)
+        return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trooth_semanto_verify/client.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Trooth, LLC
+"""SemantoClient: read a company's signed copy and check it in one call.
+
+It fetches the page as markdown, the company's key set on its domain and
+Trooth's, checks the response signature with verify_response, and checks the
+signing key against the domain's _trooth-keys TXT record over DNS over HTTPS.
+Key sets and DNS answers are kept in memory for cache_seconds (300 by default).
+The standard library does the HTTP; pass `fetch` to use your own.
+
+    from trooth_semanto_verify.client import SemantoClient
+    r = SemantoClient().read("https://acme.com/pricing")
+    if r["ok"]:
+        use(r["text"])
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .jws import parse_dns_key_records
+from .verify import verify_response
+
+TROOTH_API = "https://api.trooth.co"
+DOH_ENDPOINT = "https://cloudflare-dns.com/dns-query"
+
+# fetch(url, headers) -> (status, headers with lowercase names, body bytes)
+Fetch = Callable[[str, Dict[str, str]], Tuple[int, Dict[str, str], bytes]]
+
+
+def urllib_fetch(url: str, headers: Dict[str, str], timeout: float = 10.0) -> Tuple[int, Dict[str, str], bytes]:
+    req = urllib.request.Request(url, headers={**headers, "User-Agent": "trooth-semanto-verify-python"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (https URLs chosen by the caller)
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in e.headers.items()}, e.read()
+
+
+class SemantoClient:
+    def __init__(self, fetch: Optional[Fetch] = None, api_base: str = TROOTH_API, doh: Optional[str] = DOH_ENDPOINT, cache_seconds: int = 300, now: Optional[Callable[[], float]] = None):
+        self.fetch: Fetch = fetch or urllib_fetch
+        self.api_base = api_base.rstrip("/")
+        self.doh = doh
+        self.cache_seconds = cache_seconds
+        self.now = now or time.time
+        self._cache: Dict[str, Tuple[float, Any]] = {}
+
+    def _cached(self, key: str, load: Callable[[], Any]) -> Any:
+        hit = self._cache.get(key)
+        if hit and self.now() - hit[0] < self.cache_seconds:
+            return hit[1]
+        value = load()
+        self._cache[key] = (self.now(), value)
+        return value
+
+    def _json(self, url: str) -> Any:
+        status, _, body = self.fetch(url, {"Accept": "application/json"})
+        if status != 200:
+            raise ValueError(f"{url} answered {status}")
+        return json.loads(body)
+
+    def keys_for(self, domain: str) -> Dict[str, Any]:
+        def load() -> Dict[str, Any]:
+            keys: Dict[str, Any] = {"company": {"keys": []}, "trooth": {"keys": []}}
+            notes: List[str] = []
+            for role, url in (("company", f"https://{domain}/.well-known/trooth-keys.json"), ("trooth", f"{self.api_base}/public/semanto/.well-known/trooth-keys.json")):
+                try:
+                    keys[role] = self._json(url)
+                except Exception as e:  # noqa: BLE001 (any failure is a note, never a crash)
+                    notes.append(f"{url} could not be read ({e})")
+            return {"keys": keys, "notes": notes}
+
+        return self._cached(f"keys:{domain}", load)
+
+    def dns_kids(self, domain: str) -> Optional[List[str]]:
+        if not self.doh:
+            return None
+
+        def load() -> Optional[List[str]]:
+            try:
+                q = urllib.parse.urlencode({"name": f"_trooth-keys.{domain}", "type": "TXT"})
+                status, _, body = self.fetch(f"{self.doh}?{q}", {"Accept": "application/dns-json"})
+                if status != 200:
+                    return None
+                answers = json.loads(body).get("Answer") or []
+                txt = [str(a.get("data", "")).strip('"').replace('" "', "") for a in answers if a.get("type") == 16]
+                return parse_dns_key_records(txt)
+            except Exception:  # noqa: BLE001
+                return None
+
+        return self._cached(f"dns:{domain}", load)
+
+    def read(self, url: str, accept: str = "text/markdown") -> Dict[str, Any]:
+        """Read one URL and check it. ok is True only when the signature checks against a published key."""
+        domain = urllib.parse.urlsplit(url).hostname or ""
+        status, headers, body = self.fetch(url, {"Accept": accept})
+        loaded = self.keys_for(domain)
+        res = verify_response(status, headers, body, loaded["keys"], now=int(self.now()))
+        dns: Optional[bool] = None
+        if res.get("keyid") and (headers.get("trooth-signed-by") or "").lower() != "witness":
+            kids = self.dns_kids(domain)
+            dns = None if kids is None else res["keyid"] in kids
+        return {
+            "ok": res["ok"],
+            "reason": None if res["ok"] else res.get("reason"),
+            "status": status,
+            "text": body.decode("utf-8", "replace"),
+            "version": headers.get("trooth-semanto-version"),
+            "signed_by": headers.get("trooth-signed-by"),
+            "keyid": res.get("keyid"),
+            "dns": dns,
+            "checks": res.get("checks", []),
+            "notes": loaded["notes"],
+        }
+
+    def facts(self, trooth_id: str) -> Dict[str, Any]:
+        r = self.read(f"{self.api_base}/public/semanto/{urllib.parse.quote(trooth_id)}/facts.jsonld", accept="application/ld+json")
+        try:
+            r["data"] = json.loads(r["text"])
+        except ValueError:
+            r["data"] = None
+        return r

trooth_semanto_verify/httpsig.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Trooth, LLC
+#
+# HTTP Message Signatures, RFC 9421, with Content-Digest, RFC 9530. Verifies a
+# Semanto response (tag trooth-semanto) and a Web Bot Auth request (tag
+# web-bot-auth, draft-ietf-webbotauth-httpsig-protocol). Ed25519 only.
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterable, List, Optional
+from urllib.parse import urlsplit
+
+from .jws import ed25519_verify, key_valid_at_signing
+
+SEMANTO_RESPONSE_COMPONENTS = ["@status", "content-type", "content-digest", "trooth-semanto-version", "trooth-page-hash"]
+# Covered whenever the response carries them; the Trooth ones and Location must be covered when present.
+SEMANTO_RESPONSE_OPTIONAL_COMPONENTS = ["trooth-signed-page-hash", "trooth-signed-by", "trooth-semanto-state", "location", "content-signal", "link"]
+SEMANTO_RESPONSE_MUST_COVER_WHEN_PRESENT = ["trooth-signed-page-hash", "trooth-signed-by", "trooth-semanto-state", "location"]
+SEMANTO_RESPONSE_TAG = "trooth-semanto"
+WEB_BOT_AUTH_TAG = "web-bot-auth"
+WEB_BOT_AUTH_REQUIRED = ["@authority", "signature-agent"]
+
+_INPUT_RE = re.compile(r'([A-Za-z0-9_*.-]+)=\(((?:\s*"(?:[^"\\]|\\.)*")*)\s*\)((?:;[A-Za-z*][A-Za-z0-9_.*-]*(?:=(?:"(?:[^"\\]|\\.)*"|[^;,\s]+))?)*)')
+_COMP_RE = re.compile(r'"((?:[^"\\]|\\.)*)"')
+_PARAM_RE = re.compile(r';([A-Za-z*][A-Za-z0-9_.*-]*)(?:=("(?:[^"\\]|\\.)*"|[^;,\s]+))?')
+_SIG_RE = re.compile(r"([A-Za-z0-9_*.-]+)=:([A-Za-z0-9+/=]+):")
+
+
+def header_get(headers: Dict[str, Any], name: str) -> Optional[str]:
+    n = name.lower()
+    for k, v in headers.items():
+        if k.lower() == n:
+            if v is None:
+                return None
+            if isinstance(v, (list, tuple)):
+                return ", ".join(str(x).strip() for x in v)
+            return str(v)
+    return None
+
+
+def _canon_field(v: str) -> str:
+    return re.sub(r"[\r\n]+[ \t]+", " ", v).strip()
+
+
+def _sf_string(s: str) -> str:
+    if re.search(r"[^\x20-\x7e]", s):
+        raise ValueError("non-ASCII in structured field string")
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _derived(name: str, m: dict) -> str:
+    u = urlsplit(m["url"]) if m.get("url") else None
+    if name == "@method":
+        if m.get("kind") != "request" or not m.get("method"):
+            raise ValueError("@method needs a request")
+        return m["method"].upper()
+    if name == "@target-uri":
+        if not u:
+            raise ValueError("@target-uri needs a url")
+        return m["url"]
+    if name == "@authority":
+        if not u:
+            raise ValueError("@authority needs a url")
+        return u.netloc.lower()
+    if name == "@scheme":
+        if not u:
+            raise ValueError("@scheme needs a url")
+        return u.scheme.lower()
+    if name == "@path":
+        if not u:
+            raise ValueError("@path needs a url")
+        return u.path or "/"
+    if name == "@query":
+        if not u:
+            raise ValueError("@query needs a url")
+        return "?" + u.query if u.query else "?"
+    if name == "@status":
+        if m.get("kind") != "response" or m.get("status") is None:
+            raise ValueError("@status needs a response")
+        return str(m["status"])
+    raise ValueError(f"unsupported derived component {name}")
+
+
+def parse_signature_input(value: str) -> Dict[str, dict]:
+    out: Dict[str, dict] = {}
+    for m in _INPUT_RE.finditer(value):
+        label, comps_raw, params_raw = m.group(1), m.group(2), m.group(3)
+        components = [re.sub(r"\\(.)", r"\1", c) for c in _COMP_RE.findall(comps_raw)]
+        params: Dict[str, Any] = {}
+        for pm in _PARAM_RE.finditer(params_raw):
+            k, v = pm.group(1), pm.group(2)
+            if v is None:
+                v = ""
+            elif v.startswith('"'):
+                v = re.sub(r"\\(.)", r"\1", v[1:-1])
+            if k in ("created", "expires"):
+                # RFC 9421 2.3: Integers only; anything else is kept as "bad" and refused as malformed.
+                params[k] = int(v) if re.fullmatch(r"-?\d{1,15}", v) else "bad"
+            elif k in ("keyid", "alg", "nonce", "tag"):
+                params[k] = v
+        if "created" not in params or not isinstance(params.get("keyid"), str):
+            continue
+        out[label] = {"components": components, "params": params, "raw": f"({comps_raw.strip()}){params_raw}"}
+    return out
+
+
+def parse_signature(value: str) -> Dict[str, bytes]:
+    return {m.group(1): base64.b64decode(m.group(2)) for m in _SIG_RE.finditer(value)}
+
+
+def signature_base(m: dict, components: List[str], raw_params: str) -> str:
+    lines = []
+    seen = set()
+    for c in components:
+        key = c.lower()
+        if key in seen:
+            raise ValueError(f"duplicate component {c}")
+        seen.add(key)
+        if c.startswith("@"):
+            value = _derived(c, m)
+        else:
+            v = header_get(m["headers"], c)
+            if v is None:
+                raise ValueError(f"missing header {c}")
+            value = _canon_field(v)
+        lines.append(f"{_sf_string(key)}: {value}")
+    lines.append(f'"@signature-params": {raw_params}')
+    return "\n".join(lines)
+
+
+def verify_content_digest(header: Optional[str], body: bytes) -> bool:
+    if not header:
+        return False
+    m = re.search(r"sha-256=:([A-Za-z0-9+/=]+):", header)
+    if not m:
+        return False
+    return m.group(1) == base64.b64encode(hashlib.sha256(body).digest()).decode("ascii")
+
+
+def verify_message(
+    m: dict,
+    resolve_key: Callable[[str], Optional[dict]],
+    required: Optional[Iterable[str]] = None,
+    tag: Optional[str] = None,
+    now: Optional[int] = None,
+    max_age_seconds: Optional[int] = None,
+    skew_seconds: int = 60,
+    label: Optional[str] = None,
+) -> dict:
+    """m = {"kind": "request"|"response", "method", "url", "status", "headers"}.
+
+    label: verify that label only. The key is judged at the signature's created.
+    """
+    si = header_get(m["headers"], "signature-input")
+    sg = header_get(m["headers"], "signature")
+    if not si or not sg:
+        return {"ok": False, "reason": "no_signature"}
+    inputs = parse_signature_input(si)
+    sigs = parse_signature(sg)
+    labels = [l for l in inputs if l in sigs and (label is None or l == label)]
+    if not labels:
+        return {"ok": False, "reason": "malformed"}
+    now = int(time.time()) if now is None else now
+    last = {"ok": False, "reason": "malformed"}
+    req = [r.lower() for r in (required or [])]
+    for lb in labels:
+        components, params, raw = inputs[lb]["components"], inputs[lb]["params"], inputs[lb]["raw"]
+        if not isinstance(params.get("created"), int) or params.get("expires") == "bad":
+            last = {"ok": False, "reason": "malformed"}
+            continue
+        if params.get("alg") and params["alg"] != "ed25519":
+            last = {"ok": False, "reason": "unsupported_alg"}
+            continue
+        if tag and params.get("tag") != tag:
+            last = {"ok": False, "reason": "wrong_tag"}
+            continue
+        lower = [c.lower() for c in components]
+        if any(r not in lower for r in req):
+            last = {"ok": False, "reason": "missing_component"}
+            continue
+        if params.get("expires") is not None and now >= params["expires"]:
+            last = {"ok": False, "reason": "expired"}
+            continue
+        if params["created"] > now + skew_seconds:
+            last = {"ok": False, "reason": "not_yet_valid"}
+            continue
+        if max_age_seconds is not None and now - params["created"] > max_age_seconds:
+            last = {"ok": False, "reason": "too_old"}
+            continue
+        jwk = resolve_key(params["keyid"])
+        if jwk is None:
+            last = {"ok": False, "reason": "unknown_key"}
+            continue
+        try:
+            created_at = datetime.fromtimestamp(params["created"], tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            last = {"ok": False, "reason": "malformed"}
+            continue
+        kv = key_valid_at_signing(jwk, created_at)
+        if not kv["ok"]:
+            last = {"ok": False, "reason": kv["reason"]}
+            continue
+        try:
+            base = signature_base(m, components, raw)
+        except ValueError:
+            last = {"ok": False, "reason": "missing_component"}
+            continue
+        if not ed25519_verify(jwk, sigs[lb], base.encode("utf-8")):
+            last = {"ok": False, "reason": "bad_signature"}
+            continue
+        return {"ok": True, "label": lb, "keyid": params["keyid"], "params": params, "components": components, "notes": kv["notes"]}
+    return last