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

qruntime/policy.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyViolation:
+    code: str
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyDecision:
+    allowed: bool
+    violations: tuple[PolicyViolation, ...] = ()
+
+    @property
+    def reason_codes(self) -> tuple[str, ...]:
+        return tuple(
+            violation.code
+            for violation in self.violations
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Policy:
+    max_amount_atomic: int | None = None
+    allowed_origins: tuple[str, ...] | None = None
+    allowed_assets: tuple[str, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if self.max_amount_atomic is not None:
+            if (
+                isinstance(self.max_amount_atomic, bool)
+                or not isinstance(
+                    self.max_amount_atomic,
+                    int,
+                )
+                or self.max_amount_atomic <= 0
+            ):
+                raise ValueError(
+                    "max_amount_atomic must be "
+                    "a positive integer or None"
+                )
+
+        if self.allowed_origins is not None:
+            normalized_origins = tuple(
+                dict.fromkeys(
+                    _normalize_origin(origin)
+                    for origin in self.allowed_origins
+                )
+            )
+
+            object.__setattr__(
+                self,
+                "allowed_origins",
+                normalized_origins,
+            )
+
+        if self.allowed_assets is not None:
+            assets: list[str] = []
+
+            for asset in self.allowed_assets:
+                if not isinstance(asset, str):
+                    raise ValueError(
+                        "allowed_assets entries "
+                        "must be strings"
+                    )
+
+                value = asset.strip()
+
+                if not value:
+                    raise ValueError(
+                        "allowed_assets entries "
+                        "must not be empty"
+                    )
+
+                if value not in assets:
+                    assets.append(value)
+
+            object.__setattr__(
+                self,
+                "allowed_assets",
+                tuple(assets),
+            )
+
+
+def _normalize_origin(value: str) -> str:
+    if not isinstance(value, str):
+        raise ValueError(
+            "origin must be a string"
+        )
+
+    candidate = value.strip()
+
+    if not candidate:
+        raise ValueError(
+            "origin must not be empty"
+        )
+
+    parsed = urlsplit(candidate)
+
+    scheme = parsed.scheme.lower()
+
+    if scheme not in {"http", "https"}:
+        raise ValueError(
+            "origin must use http or https"
+        )
+
+    if parsed.hostname is None:
+        raise ValueError(
+            "origin must include a hostname"
+        )
+
+    if (
+        parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise ValueError(
+            "origin must not contain credentials"
+        )
+
+    hostname = parsed.hostname.lower()
+
+    if ":" in hostname:
+        hostname = f"[{hostname}]"
+
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError(
+            "origin contains an invalid port"
+        ) from exc
+
+    if (
+        port is None
+        or (scheme == "http" and port == 80)
+        or (scheme == "https" and port == 443)
+    ):
+        return f"{scheme}://{hostname}"
+
+    return f"{scheme}://{hostname}:{port}"
+
+
+def evaluate_policy(
+    policy: Policy,
+    *,
+    amount_atomic: int,
+    origin: str | None = None,
+    asset: str | None = None,
+) -> PolicyDecision:
+    if (
+        isinstance(amount_atomic, bool)
+        or not isinstance(amount_atomic, int)
+        or amount_atomic <= 0
+    ):
+        raise ValueError(
+            "amount_atomic must be a positive integer"
+        )
+
+    violations: list[PolicyViolation] = []
+
+    if (
+        policy.max_amount_atomic is not None
+        and amount_atomic > policy.max_amount_atomic
+    ):
+        violations.append(
+            PolicyViolation(
+                code="amount_exceeds_max",
+                message=(
+                    f"requested amount {amount_atomic} "
+                    "exceeds policy maximum "
+                    f"{policy.max_amount_atomic}"
+                ),
+            )
+        )
+
+    if policy.allowed_origins is not None:
+        if origin is None:
+            violations.append(
+                PolicyViolation(
+                    code="origin_missing",
+                    message=(
+                        "origin is required by policy"
+                    ),
+                )
+            )
+        else:
+            normalized_origin = _normalize_origin(
+                origin
+            )
+
+            if (
+                normalized_origin
+                not in policy.allowed_origins
+            ):
+                violations.append(
+                    PolicyViolation(
+                        code="origin_not_allowed",
+                        message=(
+                            f"origin {normalized_origin} "
+                            "is not allowed by policy"
+                        ),
+                    )
+                )
+
+    if policy.allowed_assets is not None:
+        if asset is None:
+            violations.append(
+                PolicyViolation(
+                    code="asset_missing",
+                    message=(
+                        "asset is required by policy"
+                    ),
+                )
+            )
+        else:
+            if not isinstance(asset, str):
+                raise ValueError(
+                    "asset must be a string"
+                )
+
+            candidate_asset = asset.strip()
+
+            if not candidate_asset:
+                raise ValueError(
+                    "asset must not be empty"
+                )
+
+            if (
+                candidate_asset
+                not in policy.allowed_assets
+            ):
+                violations.append(
+                    PolicyViolation(
+                        code="asset_not_allowed",
+                        message=(
+                            f"asset {candidate_asset} "
+                            "is not allowed by policy"
+                        ),
+                    )
+                )
+
+    return PolicyDecision(
+        allowed=not violations,
+        violations=tuple(violations),
+    )

qruntime/rails/simulated.py

@@ -0,0 +1,4 @@
+"""Placeholder rail for v0.1.
+
+The verifier operates on economic state before any real payment integration exists.
+"""

qruntime/rails/x402.py

@@ -0,0 +1,284 @@
+"""Offline x402 v2 decoder and economic normalizer for Q Runtime v0.6.
+
+This module deliberately does not sign, verify, settle, or broadcast payments.
+It only parses x402 wire objects and maps them into deterministic economic facts
+that can be checked before a real rail is allowed to execute.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+import base64
+import hashlib
+import json
+from typing import Any, Mapping
+
+
+class X402DecodeError(ValueError):
+    pass
+
+
+def _b64decode_json(value: str) -> dict[str, Any]:
+    raw = value.strip()
+    # Accept ordinary JSON too; fixtures and logs often store the decoded object.
+    if raw.startswith("{"):
+        obj = json.loads(raw)
+        if not isinstance(obj, dict):
+            raise X402DecodeError("x402 object must be a JSON object")
+        return obj
+
+    # x402 HTTP v2 uses Base64-encoded JSON headers. Accept URL-safe alphabet as
+    # a pragmatic log-decoding convenience while preserving strict JSON parsing.
+    padded = raw + "=" * (-len(raw) % 4)
+    try:
+        decoded = base64.b64decode(padded, altchars=b"-_", validate=False)
+        obj = json.loads(decoded.decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001 - convert all wire failures to one public error
+        raise X402DecodeError(f"invalid base64 JSON x402 header: {exc}") from exc
+    if not isinstance(obj, dict):
+        raise X402DecodeError("decoded x402 header must contain a JSON object")
+    return obj
+
+
+def _object(value: str | Mapping[str, Any]) -> dict[str, Any]:
+    if isinstance(value, str):
+        return _b64decode_json(value)
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise X402DecodeError(f"unsupported x402 input type: {type(value).__name__}")
+
+
+def encode_header(obj: Mapping[str, Any]) -> str:
+    """Encode a decoded x402 v2 object exactly as an HTTP payment header payload."""
+    raw = json.dumps(dict(obj), separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return base64.b64encode(raw).decode("ascii")
+
+
+def _required_string(obj: Mapping[str, Any], key: str) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str) or not value:
+        raise X402DecodeError(f"missing/invalid required field: {key}")
+    return value
+
+
+def _required_int(obj: Mapping[str, Any], key: str) -> int:
+    value = obj.get(key)
+    if isinstance(value, bool):
+        raise X402DecodeError(f"missing/invalid required integer field: {key}")
+    try:
+        return int(value)
+    except (TypeError, ValueError) as exc:
+        raise X402DecodeError(f"missing/invalid required integer field: {key}") from exc
+
+
+@dataclass(frozen=True)
+class X402Requirement:
+    scheme: str
+    network: str
+    amount_atomic: int
+    asset: str
+    pay_to: str
+    max_timeout_seconds: int
+    extra_json: str = "{}"
+
+    @staticmethod
+    def from_dict(raw: Mapping[str, Any]) -> "X402Requirement":
+        amount = _required_int(raw, "amount")
+        timeout = _required_int(raw, "maxTimeoutSeconds")
+        if amount < 0:
+            raise X402DecodeError("amount must be non-negative")
+        if timeout < 0:
+            raise X402DecodeError("maxTimeoutSeconds must be non-negative")
+        extra = raw.get("extra", {})
+        if not isinstance(extra, Mapping):
+            raise X402DecodeError("extra must be an object when present")
+        return X402Requirement(
+            scheme=_required_string(raw, "scheme"),
+            network=_required_string(raw, "network"),
+            amount_atomic=amount,
+            asset=_required_string(raw, "asset"),
+            pay_to=_required_string(raw, "payTo"),
+            max_timeout_seconds=timeout,
+            extra_json=json.dumps(dict(extra), sort_keys=True, separators=(",", ":")),
+        )
+
+    def canonical_dict(self) -> dict[str, Any]:
+        return {
+            "scheme": self.scheme,
+            "network": self.network,
+            "amount": str(self.amount_atomic),
+            "asset": self.asset,
+            "payTo": self.pay_to,
+            "maxTimeoutSeconds": self.max_timeout_seconds,
+            "extra": json.loads(self.extra_json),
+        }
+
+    def fingerprint(self) -> str:
+        raw = json.dumps(self.canonical_dict(), sort_keys=True, separators=(",", ":")).encode()
+        return hashlib.sha256(raw).hexdigest()
+
+
+@dataclass(frozen=True)
+class X402PaymentRequired:
+    version: int
+    resource_url: str
+    resource_description: str
+    accepts: tuple[X402Requirement, ...]
+    error: str = ""
+
+    def selected(self, index: int = 0) -> X402Requirement:
+        try:
+            return self.accepts[index]
+        except IndexError as exc:
+            raise X402DecodeError(f"accepts index out of range: {index}") from exc
+
+
+@dataclass(frozen=True)
+class X402PaymentPayload:
+    version: int
+    resource_url: str
+    accepted: X402Requirement
+    payload_json: str
+
+    def payload_fingerprint(self) -> str:
+        raw = json.dumps(
+            {
+                "version": self.version,
+                "resource_url": self.resource_url,
+                "accepted": self.accepted.canonical_dict(),
+                "payload": json.loads(self.payload_json),
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        return hashlib.sha256(raw).hexdigest()
+
+
+@dataclass(frozen=True)
+class X402SettlementResponse:
+    success: bool
+    transaction: str
+    network: str
+    error_reason: str = ""
+    payer: str = ""
+    amount_atomic: int | None = None
+
+    @property
+    def reconciliation_required(self) -> bool:
+        return (not self.success) and self.error_reason == "settlement_pending"
+
+
+@dataclass(frozen=True)
+class QPaymentRequiredEvent:
+    kind: str
+    resource_url: str
+    quote_fingerprint: str
+    scheme: str
+    network: str
+    asset: str
+    amount_atomic: int
+    pay_to: str
+    max_timeout_seconds: int
+
+
+def parse_payment_required(value: str | Mapping[str, Any]) -> X402PaymentRequired:
+    raw = _object(value)
+    version = _required_int(raw, "x402Version")
+    if version != 2:
+        raise X402DecodeError(f"unsupported x402Version={version}; v0.6 accepts x402 v2 only")
+    resource = raw.get("resource")
+    if not isinstance(resource, Mapping):
+        raise X402DecodeError("resource must be an object")
+    resource_url = _required_string(resource, "url")
+    accepts_raw = raw.get("accepts")
+    if not isinstance(accepts_raw, list) or not accepts_raw:
+        raise X402DecodeError("accepts must be a non-empty array")
+    accepts = tuple(X402Requirement.from_dict(item) for item in accepts_raw if isinstance(item, Mapping))
+    if len(accepts) != len(accepts_raw):
+        raise X402DecodeError("each accepts entry must be an object")
+    return X402PaymentRequired(
+        version=version,
+        resource_url=resource_url,
+        resource_description=str(resource.get("description", "")),
+        accepts=accepts,
+        error=str(raw.get("error", "")),
+    )
+
+
+def parse_payment_payload(value: str | Mapping[str, Any]) -> X402PaymentPayload:
+    raw = _object(value)
+    version = _required_int(raw, "x402Version")
+    if version != 2:
+        raise X402DecodeError(f"unsupported x402Version={version}; v0.6 accepts x402 v2 only")
+    accepted_raw = raw.get("accepted")
+    if not isinstance(accepted_raw, Mapping):
+        raise X402DecodeError("accepted must be an object")
+    payload = raw.get("payload")
+    if not isinstance(payload, Mapping):
+        raise X402DecodeError("payload must be an object")
+    resource = raw.get("resource") or {}
+    if not isinstance(resource, Mapping):
+        raise X402DecodeError("resource must be an object when present")
+    return X402PaymentPayload(
+        version=version,
+        resource_url=str(resource.get("url", "")),
+        accepted=X402Requirement.from_dict(accepted_raw),
+        payload_json=json.dumps(dict(payload), sort_keys=True, separators=(",", ":")),
+    )
+
+
+def parse_settlement_response(value: str | Mapping[str, Any]) -> X402SettlementResponse:
+    raw = _object(value)
+    if "success" not in raw or not isinstance(raw["success"], bool):
+        raise X402DecodeError("settlement response requires boolean success")
+    transaction = str(raw.get("transaction", ""))
+    network = _required_string(raw, "network")
+    error_reason = str(raw.get("errorReason", ""))
+    if error_reason == "settlement_pending" and not transaction:
+        raise X402DecodeError("settlement_pending requires a non-empty transaction hash")
+    amount = raw.get("amount")
+    amount_atomic = None if amount is None else _required_int(raw, "amount")
+    return X402SettlementResponse(
+        success=raw["success"],
+        transaction=transaction,
+        network=network,
+        error_reason=error_reason,
+        payer=str(raw.get("payer", "")),
+        amount_atomic=amount_atomic,
+    )
+
+
+def normalize_payment_required(value: str | Mapping[str, Any], accept_index: int = 0) -> QPaymentRequiredEvent:
+    parsed = parse_payment_required(value)
+    req = parsed.selected(accept_index)
+    return QPaymentRequiredEvent(
+        kind="PAYMENT_REQUIRED",
+        resource_url=parsed.resource_url,
+        quote_fingerprint=req.fingerprint(),
+        scheme=req.scheme,
+        network=req.network,
+        asset=req.asset,
+        amount_atomic=req.amount_atomic,
+        pay_to=req.pay_to,
+        max_timeout_seconds=req.max_timeout_seconds,
+    )
+
+
+def requirement_equal(a: X402Requirement, b: X402Requirement) -> bool:
+    return a.canonical_dict() == b.canonical_dict()
+
+
+def requirement_diff(old: X402Requirement, new: X402Requirement) -> dict[str, tuple[Any, Any]]:
+    a = old.canonical_dict()
+    b = new.canonical_dict()
+    return {key: (a.get(key), b.get(key)) for key in sorted(set(a) | set(b)) if a.get(key) != b.get(key)}
+
+
+def as_jsonable(obj: Any) -> Any:
+    if hasattr(obj, "__dataclass_fields__"):
+        data = asdict(obj)
+        if isinstance(obj, X402Requirement):
+            data["extra"] = json.loads(data.pop("extra_json"))
+        if isinstance(obj, X402PaymentPayload):
+            data["payload"] = json.loads(data.pop("payload_json"))
+        return data
+    return obj