q-runtime-core 0.9.0__py3-none-any.whl

qruntime/rails/x402_external.py

@@ -0,0 +1,575 @@
+"""Read-only external x402 probing and protocol/economic auditing for Q Runtime v0.5.
+
+No PAYMENT-SIGNATURE is ever sent by this module. It performs ordinary unpaid HTTP
+requests, records the observed 402 challenge, and evaluates wire-level invariants.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import base64
+import ipaddress
+import json
+from pathlib import Path
+import re
+from typing import Any, Mapping
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+from qruntime.rails.x402 import X402DecodeError, X402PaymentRequired, parse_payment_required
+
+
+class ExternalProbeError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AuditFinding:
+    severity: str  # info | warning | error
+    invariant: str
+    reason: str
+
+    def as_dict(self) -> dict[str, str]:
+        return {"severity": self.severity, "invariant": self.invariant, "reason": self.reason}
+
+
+@dataclass(frozen=True)
+class ExternalProbe:
+    request_url: str
+    final_url: str
+    method: str
+    status_code: int
+    captured_at: str
+    response_headers: dict[str, str]
+    body_text: str
+    challenge_source: str | None
+    challenge_wire: str | dict[str, Any] | None
+    payment_required: X402PaymentRequired | None
+    findings: tuple[AuditFinding, ...]
+    audit_mode: str = "strict"
+
+    @property
+    def passed(self) -> bool:
+        return not any(item.severity == "error" for item in self.findings)
+
+    @property
+    def classification(self) -> str:
+        if any(item.invariant == "LegacyX402V1Detected" for item in self.findings):
+            return "legacy_x402_v1"
+        if self.passed:
+            return "accepted_v2"
+        return "nonconformant"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "format": "qruntime-x402-external-audit-v2",
+            "audit_mode": self.audit_mode,
+            "classification": self.classification,
+            "source": {
+                "kind": "external_http",
+                "captured_at": self.captured_at,
+                "request_url": self.request_url,
+                "final_url": self.final_url,
+                "method": self.method,
+                "status_code": self.status_code,
+                "note": "Unpaid read-only probe. PAYMENT-SIGNATURE was never sent.",
+            },
+            "challenge_source": self.challenge_source,
+            "challenge": self.challenge_wire,
+            "findings": [item.as_dict() for item in self.findings],
+            "summary": {
+                "passed": self.passed,
+                "classification": self.classification,
+                "errors": sum(1 for item in self.findings if item.severity == "error"),
+                "warnings": sum(1 for item in self.findings if item.severity == "warning"),
+            },
+            "raw_exchange": {
+                "response_headers": self.response_headers,
+                "body_preview": self.body_text[:4000],
+            },
+        }
+
+
+# Formal CAIP-2 grammar (CAIP-2 Final): namespace 3-8 chars, reference 1-32 chars.
+_CAIP2 = re.compile(r"^[-a-z0-9]{3,8}:[-_A-Za-z0-9]{1,32}$")
+
+# x402's current network-support documentation (Sep 2026) explicitly publishes these
+# Algorand identifiers as its supported network strings, even though their base64
+# genesis-hash references fall outside the formal CAIP-2 reference grammar above.
+# Treat them as an upstream x402 profile exception, not as a defect in each service.
+_X402_DOCUMENTED_NETWORK_EXCEPTIONS = {
+    "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+    "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+}
+_EVM_ADDR = re.compile(r"^0x[0-9a-fA-F]{40}$")
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    name = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _body_json(body_text: str) -> dict[str, Any] | None:
+    try:
+        value = json.loads(body_text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def _decode_header_strict(value: str) -> dict[str, Any]:
+    raw = value.strip()
+    if raw.startswith("{"):
+        raise X402DecodeError("PAYMENT-REQUIRED header contains raw JSON; x402 v2 HTTP header must be base64 JSON")
+    padded = raw + "=" * (-len(raw) % 4)
+    try:
+        decoded = base64.b64decode(padded, validate=True)
+        parsed = json.loads(decoded.decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        raise X402DecodeError(f"invalid base64 JSON PAYMENT-REQUIRED header: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise X402DecodeError("PAYMENT-REQUIRED must decode to a JSON object")
+    return parsed
+
+
+def _is_public_https(url: str) -> bool:
+    parsed = urlparse(url)
+    if parsed.scheme.lower() != "https" or not parsed.hostname:
+        return False
+    host = parsed.hostname.lower()
+    if host in {"localhost", "localhost.localdomain"} or host.endswith(".local"):
+        return False
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return True
+    return not (ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved)
+
+
+def _resource_binding(request_url: str, resource_url: str) -> tuple[bool, bool]:
+    """Return (same_resource, query_fully_bound_in_url).
+
+    x402 ResourceInfo identifies the protected resource, but deployed services may bind
+    request parameters through extensions rather than reproducing the query string in
+    resource.url.  Origin/path mismatch is therefore a hard error; an omitted query is
+    recorded as a warning, not treated as a protocol failure.  When both URLs carry a
+    query, they must match exactly.
+    """
+    a = urlparse(request_url)
+    resolved_resource_url = urljoin(request_url, resource_url)
+    b = urlparse(resolved_resource_url)
+    same_base = (a.scheme.lower(), a.netloc.lower(), a.path or "/") == (
+        b.scheme.lower(), b.netloc.lower(), b.path or "/"
+    )
+    if not same_base:
+        return False, False
+    if b.query:
+        return a.query == b.query, a.query == b.query
+    return True, not bool(a.query)
+
+
+def audit_observed_exchange(
+    *,
+    request_url: str,
+    final_url: str,
+    method: str,
+    status_code: int,
+    response_headers: Mapping[str, str],
+    body_text: str,
+    mode: str = "strict",
+) -> tuple[str | None, str | dict[str, Any] | None, X402PaymentRequired | None, tuple[AuditFinding, ...]]:
+    if mode not in {"strict", "compatibility"}:
+        raise ExternalProbeError("audit mode must be 'strict' or 'compatibility'")
+
+    findings: list[AuditFinding] = []
+    header_wire = _header(response_headers, "PAYMENT-REQUIRED")
+    body_obj = _body_json(body_text)
+    body_candidate = body_obj if body_obj and ("x402Version" in body_obj or "accepts" in body_obj) else None
+
+    if status_code != 402:
+        findings.append(AuditFinding("error", "PaymentRequiredStatus", f"expected HTTP 402, received HTTP {status_code}"))
+        return None, None, None, tuple(findings)
+
+    challenge_source: str | None = None
+    challenge_wire: str | dict[str, Any] | None = None
+    raw_obj: dict[str, Any] | None = None
+
+    if header_wire is not None:
+        challenge_source = "header"
+        challenge_wire = header_wire
+        raw = header_wire.strip()
+        if raw.startswith("{"):
+            try:
+                candidate = json.loads(raw)
+            except json.JSONDecodeError:
+                candidate = None
+            if isinstance(candidate, dict) and candidate.get("x402Version") == 1:
+                # Root-cause aggregation: do not report a v2 encoding error on a v1 envelope.
+                raw_obj = candidate
+            else:
+                findings.append(AuditFinding(
+                    "error",
+                    "CanonicalPaymentRequiredEncoding",
+                    "PAYMENT-REQUIRED header contains raw JSON; x402 v2 HTTP header must be base64 JSON",
+                ))
+                raw_obj = candidate if isinstance(candidate, dict) else None
+        else:
+            try:
+                raw_obj = _decode_header_strict(header_wire)
+            except X402DecodeError as exc:
+                findings.append(AuditFinding("error", "CanonicalPaymentRequiredEncoding", str(exc)))
+    elif body_candidate is not None:
+        challenge_source = "body"
+        challenge_wire = body_candidate
+        raw_obj = body_candidate
+    else:
+        findings.append(AuditFinding("error", "PaymentRequirementKnownBeforeAuthorization", "HTTP 402 contained no parseable PAYMENT-REQUIRED challenge"))
+        return None, None, None, tuple(findings)
+
+    parsed: X402PaymentRequired | None = None
+    if raw_obj is not None:
+        version = raw_obj.get("x402Version")
+
+        if version == 1:
+            severity = "error" if mode == "strict" else "warning"
+            accepts = raw_obj.get("accepts") if isinstance(raw_obj.get("accepts"), list) else []
+            legacy_networks = [str(req.get("network")) for req in accepts if isinstance(req, dict) and req.get("network") is not None]
+            has_legacy_amount = any(isinstance(req, dict) and "maxAmountRequired" in req for req in accepts)
+            has_legacy_resource = any(isinstance(req, dict) and isinstance(req.get("resource"), str) for req in accepts)
+            derived = []
+            if challenge_source == "body":
+                derived.append("body-primary challenge")
+            if legacy_networks:
+                derived.append("legacy network identifier(s): " + ", ".join(legacy_networks[:3]))
+            if has_legacy_amount:
+                derived.append("maxAmountRequired instead of v2 amount")
+            if has_legacy_resource:
+                derived.append("resource embedded in PaymentRequirements instead of v2 top-level resource object")
+            reason = "x402 v1 legacy handshake detected; strict x402 v2 compatibility requires migration"
+            if derived:
+                reason += "; derived legacy shape: " + "; ".join(derived)
+            findings.append(AuditFinding(severity, "LegacyX402V1Detected", reason))
+            findings.append(AuditFinding(
+                "info",
+                "LegacyMigrationRequired",
+                "classify as one legacy root cause rather than separate v2 field failures",
+            ))
+        else:
+            if version != 2:
+                findings.append(AuditFinding("error", "X402VersionSupported", f"expected x402Version=2, observed {version!r}"))
+
+            if challenge_source == "body":
+                findings.append(AuditFinding(
+                    "error" if mode == "strict" else "warning",
+                    "CanonicalPaymentRequiredLocation",
+                    "HTTP 402 challenge was found only in the response body; x402 v2 canonical HTTP location is PAYMENT-REQUIRED header",
+                ))
+
+            accepts = raw_obj.get("accepts")
+            if not isinstance(accepts, list) or not accepts:
+                findings.append(AuditFinding("error", "NonEmptyPaymentRequirements", "accepts must be a non-empty array"))
+            else:
+                for idx, req in enumerate(accepts):
+                    prefix = f"accepts[{idx}]"
+                    if not isinstance(req, dict):
+                        findings.append(AuditFinding("error", "ValidPaymentRequirementShape", f"{prefix} is not an object"))
+                        continue
+                    amount = req.get("amount")
+                    if not isinstance(amount, str) or not amount.isdigit():
+                        findings.append(AuditFinding("error", "AtomicAmountCanonical", f"{prefix}.amount must be a decimal string of atomic units"))
+                    elif int(amount) <= 0:
+                        findings.append(AuditFinding("warning", "PositivePaymentAmount", f"{prefix}.amount is {amount}; a zero-priced resource should not require payment"))
+                    network = req.get("network")
+                    if not isinstance(network, str):
+                        findings.append(AuditFinding("error", "CanonicalNetworkIdentifier", f"{prefix}.network must be a string network identifier"))
+                    elif _CAIP2.fullmatch(network):
+                        pass
+                    elif network in _X402_DOCUMENTED_NETWORK_EXCEPTIONS:
+                        findings.append(AuditFinding(
+                            "info",
+                            "X402DocumentedNetworkProfileException",
+                            f"{prefix}.network={network!r} is documented by x402 as a supported Algorand network identifier but falls outside the formal CAIP-2 reference grammar; classify as an upstream standards-profile exception, not a service defect",
+                        ))
+                    else:
+                        findings.append(AuditFinding("error", "CanonicalNetworkIdentifier", f"{prefix}.network is not a recognized x402/CAIP-2 network identifier"))
+                    timeout = req.get("maxTimeoutSeconds")
+                    scheme = req.get("scheme")
+                    positive_timeout_schemes = {"exact", "upto", "batch-settlement"}
+                    if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout < 0:
+                        findings.append(AuditFinding("error", "LiveAuthorizationWindow", f"{prefix}.maxTimeoutSeconds must be a non-negative integer"))
+                    elif timeout == 0 and scheme in positive_timeout_schemes:
+                        findings.append(AuditFinding("error", "LiveAuthorizationWindow", f"{prefix}.maxTimeoutSeconds must be positive for x402 scheme {scheme!r}"))
+                    elif timeout == 0:
+                        findings.append(AuditFinding(
+                            "info",
+                            "SchemeSpecificTimeoutSemanticsUnknown",
+                            f"{prefix}.scheme={scheme!r} uses maxTimeoutSeconds=0; core v2 defines the field but scheme-specific zero semantics are not known to Q Runtime, so do not classify this custom scheme as invalid without its scheme specification",
+                        ))
+                    elif timeout > 86400:
+                        findings.append(AuditFinding("warning", "BoundedAuthorizationWindow", f"{prefix}.maxTimeoutSeconds={timeout} is longer than 24 hours"))
+                    if isinstance(network, str) and network.startswith("eip155:"):
+                        pay_to = req.get("payTo")
+                        asset = req.get("asset")
+                        if not isinstance(pay_to, str) or not _EVM_ADDR.fullmatch(pay_to):
+                            findings.append(AuditFinding("error", "ValidPaymentRecipient", f"{prefix}.payTo is not a 20-byte EVM address"))
+                        if not isinstance(asset, str) or not _EVM_ADDR.fullmatch(asset):
+                            findings.append(AuditFinding("error", "ValidPaymentAsset", f"{prefix}.asset is not a 20-byte EVM token address"))
+
+            resource = raw_obj.get("resource")
+            if not isinstance(resource, dict) or not isinstance(resource.get("url"), str) or not resource.get("url"):
+                findings.append(AuditFinding("error", "PaymentPayloadBoundToResource", "resource.url is missing"))
+            else:
+                same_resource, query_bound = _resource_binding(final_url, resource["url"])
+                if not same_resource:
+                    findings.append(AuditFinding(
+                        "error",
+                        "PaymentPayloadBoundToResource",
+                        f"advertised resource URL {resource['url']} does not match requested origin/path {final_url}",
+                    ))
+                elif not query_bound:
+                    findings.append(AuditFinding(
+                        "warning",
+                        "ResourceQueryBindingExternalized",
+                        "request query parameters are not reproduced in resource.url; verify that an extension or application policy binds them before authorization",
+                    ))
+
+            try:
+                parsed = parse_payment_required(raw_obj)
+            except X402DecodeError as exc:
+                findings.append(AuditFinding("error", "ValidX402WireData", str(exc)))
+
+    cache_control = _header(response_headers, "Cache-Control") or ""
+    directives = [part.strip().lower() for part in cache_control.split(",") if part.strip()]
+    has_no_store = "no-store" in directives
+    has_no_cache = "no-cache" in directives
+    has_must_revalidate = "must-revalidate" in directives or "proxy-revalidate" in directives
+    explicitly_public = "public" in directives
+    positive_max_age = False
+    freshness_directive_seen = False
+    for directive in directives:
+        if directive.startswith("max-age=") or directive.startswith("s-maxage="):
+            freshness_directive_seen = True
+            try:
+                value = int(directive.split("=", 1)[1].strip().strip('"'))
+            except ValueError:
+                value = 1  # malformed freshness directive: fail conservatively
+            positive_max_age = positive_max_age or value > 0
+
+    # no-store forbids storage; no-cache requires revalidation.  The legacy-compatible
+    # max-age=0,must-revalidate combination is effectively revalidation-on-every-use,
+    # so it must not be reported as stale-replay capable.
+    immediate_revalidation = has_must_revalidate and freshness_directive_seen and not positive_max_age
+    if not has_no_store and not has_no_cache and not immediate_revalidation and (explicitly_public or positive_max_age):
+        findings.append(AuditFinding(
+            "warning",
+            "NonCacheablePaymentChallenge",
+            f"402 response is cacheable ({cache_control}); stale payment requirements may be replayed by shared caches",
+        ))
+
+    if parsed is not None and not any(f.severity == "error" for f in findings):
+        findings.append(AuditFinding("info", "ExternalPaymentRequiredAccepted", "x402 v2 payment challenge passed current Q Runtime wire/economic checks"))
+
+    return challenge_source, challenge_wire, parsed, tuple(findings)
+
+def probe_external(
+    url: str,
+    *,
+    method: str = "GET",
+    timeout: float = 10.0,
+    request_headers: Mapping[str, str] | None = None,
+    json_body: Any | None = None,
+    require_public_https: bool = False,
+    mode: str = "strict",
+) -> ExternalProbe:
+    if require_public_https and not _is_public_https(url):
+        raise ExternalProbeError("external directory probes are restricted to public HTTPS URLs")
+    method = method.upper()
+    if method not in {"GET", "POST", "HEAD"}:
+        raise ExternalProbeError(f"unsupported probe method: {method}")
+
+    headers = {
+        "User-Agent": "q-runtime/0.5 external-audit",
+        "Accept": "application/json, */*",
+    }
+    data: bytes | None = None
+    if json_body is not None:
+        data = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    if request_headers:
+        for key, value in request_headers.items():
+            if key.lower() in {"payment-signature", "x-payment"}:
+                raise ExternalProbeError("Q Runtime external probe refuses to send payment authorization headers")
+            headers[str(key)] = str(value)
+
+    req = Request(url, data=data, headers=headers, method=method)
+    body = b""
+    final_url = url
+    try:
+        with urlopen(req, timeout=timeout) as response:  # noqa: S310 - URL chosen by operator/directory
+            status = int(response.status)
+            final_url = response.geturl()
+            response_headers = dict(response.headers.items())
+            if method != "HEAD":
+                body = response.read(65536)
+    except HTTPError as exc:
+        status = int(exc.code)
+        final_url = exc.geturl()
+        response_headers = dict(exc.headers.items()) if exc.headers else {}
+        if method != "HEAD":
+            body = exc.read(65536)
+    except URLError as exc:
+        raise ExternalProbeError(f"HTTP probe failed for {url}: {exc}") from exc
+
+    body_text = body.decode("utf-8", errors="replace")
+    source, wire, parsed, findings = audit_observed_exchange(
+        request_url=url,
+        final_url=final_url,
+        method=method,
+        status_code=status,
+        response_headers=response_headers,
+        body_text=body_text,
+        mode=mode,
+    )
+    return ExternalProbe(
+        request_url=url,
+        final_url=final_url,
+        method=method,
+        status_code=status,
+        captured_at=datetime.now(timezone.utc).isoformat(),
+        response_headers=response_headers,
+        body_text=body_text,
+        challenge_source=source,
+        challenge_wire=wire,
+        payment_required=parsed,
+        findings=findings,
+        audit_mode=mode,
+    )
+
+
+def write_external_probe(probe: ExternalProbe, path: str | Path) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(probe.as_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
+    return target
+
+
+def fetch_json(url: str, *, timeout: float = 10.0) -> dict[str, Any]:
+    req = Request(url, headers={"User-Agent": "q-runtime/0.5 directory-audit", "Accept": "application/json"})
+    try:
+        with urlopen(req, timeout=timeout) as response:  # noqa: S310
+            raw = response.read(2_000_000)
+    except (HTTPError, URLError) as exc:
+        raise ExternalProbeError(f"directory request failed for {url}: {exc}") from exc
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ExternalProbeError(f"directory returned invalid JSON for {url}") from exc
+    if not isinstance(parsed, dict):
+        raise ExternalProbeError("directory response must be a JSON object")
+    return parsed
+
+
+def _get(mapping: Mapping[str, Any], *names: str) -> Any:
+    for name in names:
+        if name in mapping:
+            return mapping[name]
+    return None
+
+
+def _extract_service_slugs(payload: Mapping[str, Any]) -> list[str]:
+    data = payload.get("data")
+    if not isinstance(data, list):
+        return []
+    out: list[str] = []
+    for item in data:
+        if not isinstance(item, Mapping):
+            continue
+        slug = _get(item, "slug", "service_slug", "id")
+        if isinstance(slug, str) and slug and "/" not in slug:
+            out.append(slug)
+    return out
+
+
+def _endpoint_candidates(detail: Mapping[str, Any]) -> list[tuple[str, str]]:
+    root = detail.get("data") if isinstance(detail.get("data"), Mapping) else detail
+    if not isinstance(root, Mapping):
+        return []
+    base = _get(root, "base_url", "baseUrl", "url")
+    endpoints = _get(root, "endpoints", "routes")
+    if not isinstance(base, str) or not isinstance(endpoints, list):
+        return []
+    out: list[tuple[str, str]] = []
+    for ep in endpoints:
+        if not isinstance(ep, Mapping):
+            continue
+        method = str(_get(ep, "method", "http_method") or "GET").upper()
+        path = _get(ep, "path", "route", "url")
+        if method != "GET" or not isinstance(path, str) or not path or "{" in path or "}" in path:
+            continue
+        absolute = path if path.startswith("http://") or path.startswith("https://") else urljoin(base.rstrip("/") + "/", path.lstrip("/"))
+        if _is_public_https(absolute):
+            out.append((method, absolute))
+    return out
+
+
+def audit_x402_list_directory(
+    *,
+    limit: int = 10,
+    timeout: float = 10.0,
+    directory_base: str = "https://x402-list.com/api/v1",
+    mode: str = "compatibility",
+) -> dict[str, Any]:
+    if limit < 1 or limit > 50:
+        raise ExternalProbeError("directory audit limit must be between 1 and 50")
+    listing = fetch_json(f"{directory_base}/services?status=online&sort=uptime&per_page=100&ref=qruntime", timeout=timeout)
+    slugs = _extract_service_slugs(listing)
+    results: list[dict[str, Any]] = []
+    skipped: list[dict[str, str]] = []
+
+    for slug in slugs:
+        if len(results) >= limit:
+            break
+        try:
+            detail = fetch_json(f"{directory_base}/services/{slug}?ref=qruntime", timeout=timeout)
+        except ExternalProbeError as exc:
+            skipped.append({"service": slug, "reason": str(exc)})
+            continue
+        candidates = _endpoint_candidates(detail)
+        if not candidates:
+            skipped.append({"service": slug, "reason": "no safe non-templated GET endpoint found"})
+            continue
+        method, url = candidates[0]
+        try:
+            probe = probe_external(url, method=method, timeout=timeout, require_public_https=True, mode=mode)
+            results.append({"service": slug, "endpoint": url, "audit": probe.as_dict()})
+        except ExternalProbeError as exc:
+            results.append({
+                "service": slug,
+                "endpoint": url,
+                "audit": {
+                    "summary": {"passed": False, "errors": 1, "warnings": 0},
+                    "findings": [{"severity": "error", "invariant": "ExternalReachability", "reason": str(exc)}],
+                },
+            })
+
+    error_count = sum(int(item["audit"]["summary"].get("errors", 0)) for item in results)
+    warning_count = sum(int(item["audit"]["summary"].get("warnings", 0)) for item in results)
+    legacy_count = sum(1 for item in results if item["audit"].get("classification") == "legacy_x402_v1" or item["audit"].get("summary", {}).get("classification") == "legacy_x402_v1")
+    return {
+        "format": "qruntime-x402-directory-audit-v1",
+        "directory": directory_base,
+        "captured_at": datetime.now(timezone.utc).isoformat(),
+        "safety": "GET only; public HTTPS only; no PAYMENT-SIGNATURE; no payment attempted",
+        "audit_mode": mode,
+        "requested_limit": limit,
+        "services_audited": len(results),
+        "errors": error_count,
+        "warnings": warning_count,
+        "legacy_x402_v1": legacy_count,
+        "results": results,
+        "skipped": skipped,
+    }

qruntime/rails/x402_external_suite.py

@@ -0,0 +1,65 @@
+"""Known independent x402 targets used as cross-implementation validation, not fixtures."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from qruntime.rails.x402_external import ExternalProbeError, probe_external
+
+
+@dataclass(frozen=True)
+class ExternalCase:
+    name: str
+    url: str
+    expected: str  # pass | error
+    expected_invariant: str | None = None
+
+
+DEFAULT_CASES = (
+    ExternalCase("querylines-production", "https://api.querylines.com/v1/premium?state=FL", "pass"),
+    ExternalCase("grug402-compliant", "https://grug402.dev/api/x402/compliant-get", "pass"),
+    ExternalCase("grug402-missing-header", "https://grug402.dev/api/x402/missing-payment-required", "error", "CanonicalPaymentRequiredLocation"),
+    ExternalCase("grug402-raw-json-header", "https://grug402.dev/api/x402/header-raw-json", "error", "CanonicalPaymentRequiredEncoding"),
+    ExternalCase("grug402-resource-host-mismatch", "https://grug402.dev/api/x402/resource-host-mismatch", "error", "PaymentPayloadBoundToResource"),
+)
+
+
+def run_external_suite(*, timeout: float = 10.0, mode: str = "strict") -> dict[str, Any]:
+    results: list[dict[str, Any]] = []
+    suite_passed = True
+    for case in DEFAULT_CASES:
+        try:
+            probe = probe_external(case.url, timeout=timeout, require_public_https=True, mode=mode)
+            observed_error_invariants = {f.invariant for f in probe.findings if f.severity == "error"}
+            if case.expected == "pass":
+                matched = probe.passed
+            else:
+                matched = (not probe.passed) and (
+                    case.expected_invariant is None or case.expected_invariant in observed_error_invariants
+                )
+            result = {
+                "name": case.name,
+                "url": case.url,
+                "expected": case.expected,
+                "expected_invariant": case.expected_invariant,
+                "matched_expectation": matched,
+                "audit": probe.as_dict(),
+            }
+        except ExternalProbeError as exc:
+            matched = False
+            result = {
+                "name": case.name,
+                "url": case.url,
+                "expected": case.expected,
+                "expected_invariant": case.expected_invariant,
+                "matched_expectation": False,
+                "error": str(exc),
+            }
+        suite_passed = suite_passed and matched
+        results.append(result)
+    return {
+        "format": "qruntime-x402-external-suite-v2",
+        "audit_mode": mode,
+        "suite_passed": suite_passed,
+        "cases": results,
+    }