subetha 0.1.0__py3-none-any.whl

subetha/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+"""subetha — pay for x402 (HTTP 402) APIs privately over SubEtha's zERC20 rail.
+
+Wire protocol: docs/PROTOCOL.md in the SubEtha repository (this package is the
+reference implementation written against that spec alone). Payer safety mirrors the
+TypeScript agent tools (docs/AGENT-TOOLS.md)."""
+
+from .client import SubethaClient
+from .policy import SpendingPolicy
+from .types import (
+    ApprovalRequest,
+    Offer,
+    Payment,
+    PayResult,
+    Quote,
+    Requirements,
+    SCHEME,
+    SubethaError,
+)
+
+__all__ = [
+    "SubethaClient",
+    "SpendingPolicy",
+    "ApprovalRequest",
+    "Offer",
+    "Payment",
+    "PayResult",
+    "Quote",
+    "Requirements",
+    "SCHEME",
+    "SubethaError",
+]

subetha/_redact.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Secret redaction, mirroring the TS agent-tools policy: exact known secrets by value,
+signature-grade hex (130+ chars) masked; a 64-hex transaction hash is legitimate output
+and passes through."""
+
+from __future__ import annotations
+
+import re
+
+_LONG_HEX = re.compile(r"0x[0-9a-fA-F]{130,}")
+
+
+def make_redactor(secrets: list[str]):
+    known = [s for s in secrets if s]
+
+    def redact(text: str) -> str:
+        out = _LONG_HEX.sub("0x[redacted]", text)
+        for secret in known:
+            out = out.replace(secret, "[redacted-secret]")
+        return out
+
+    return redact

subetha/client.py

@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SubethaClient — pay for x402 resources over SubEtha's private zERC20 rail.
+
+Wire behavior comes from docs/PROTOCOL.md (the normative spec this module was written
+against); payer safety mirrors the TS agent-tools engine (docs/AGENT-TOOLS.md): spending
+policy at two enforcement points, human approval above a threshold, accounting at the
+irreversibility point, one payment at a time, secrets redacted from every error."""
+
+from __future__ import annotations
+
+import os
+import re
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeout
+from typing import Callable, Optional
+
+import httpx
+from eth_account import Account
+
+from ._redact import make_redactor
+from .policy import SpendingPolicy
+from .rpc import Rpc
+from .signing import sign_burn_auth, sign_permit
+from .types import (
+    SCHEME,
+    ApprovalRequest,
+    Offer,
+    Payment,
+    PayResult,
+    Quote,
+    Requirements,
+    SubethaError,
+)
+from .wire import (
+    decode_payment_required,
+    decode_payment_response,
+    encode_payment_signature,
+    parse_requirements,
+)
+
+_RESERVED_HEADER = re.compile(r"^(payment-|x-payment)", re.IGNORECASE)
+_MAX_RESOURCE_BYTES = 64 * 1024
+_EXPIRY_MARGIN_S = 5
+
+
+class SubethaClient:
+    def __init__(
+        self,
+        *,
+        private_key: Optional[str] = None,
+        rpc_url: str = "http://127.0.0.1:8545",
+        mode: str = "permit",
+        policy: Optional[SpendingPolicy] = None,
+        approve_above: Optional[int] = None,
+        approve_payment: Optional[Callable[[ApprovalRequest], bool]] = None,
+        approval_timeout_s: float = 120.0,
+        timeout_s: float = 30.0,
+    ):
+        if mode not in ("permit", "self-transfer"):
+            raise SubethaError(f'mode must be "permit" or "self-transfer", got "{mode}"')
+        self.mode = mode
+        self.policy = policy or SpendingPolicy()
+        self.approve_above = approve_above
+        self.approve_payment = approve_payment
+        self.approval_timeout_s = approval_timeout_s
+        self._account = Account.from_key(private_key) if private_key else None
+        self._redact = make_redactor([private_key] if private_key else [])
+        self._rpc = Rpc(rpc_url, timeout_s)
+        self._http = httpx.Client(follow_redirects=False, timeout=timeout_s)
+        self._lock = threading.Lock()  # one payment at a time
+
+    @classmethod
+    def from_env(cls, env: Optional[dict] = None) -> "SubethaClient":
+        """Build from the SUBETHA_* environment (same variable names as the TS tools)."""
+        e = env if env is not None else dict(os.environ)
+        hosts_raw = e.get("SUBETHA_ALLOWED_HOSTS")
+        hosts: list[str] | str
+        if hosts_raw == "*":
+            hosts = "*"
+        elif hosts_raw:
+            hosts = [h.strip().lower() for h in hosts_raw.split(",") if h.strip()]
+        else:
+            hosts = ["localhost", "127.0.0.1"]
+        dec = lambda name: int(e[name]) if e.get(name) else None  # noqa: E731
+        return cls(
+            private_key=e.get("SUBETHA_PAYER_PK"),
+            rpc_url=e.get("SUBETHA_RPC_URL", "http://127.0.0.1:8545"),
+            mode=e.get("SUBETHA_MODE", "permit"),
+            policy=SpendingPolicy(
+                allowed_hosts=hosts,
+                allowed_network=e.get("SUBETHA_ALLOWED_NETWORK", "eip155:31337"),
+                allowed_token=e.get("SUBETHA_ALLOWED_TOKEN"),
+                max_per_payment=dec("SUBETHA_MAX_PER_PAYMENT"),
+                max_total=dec("SUBETHA_MAX_TOTAL"),
+            ),
+            approve_above=dec("SUBETHA_APPROVE_ABOVE"),
+            approval_timeout_s=int(e.get("SUBETHA_APPROVAL_TIMEOUT_MS", "120000")) / 1000,
+            timeout_s=int(e.get("SUBETHA_TIMEOUT_MS", "30000")) / 1000,
+        )
+
+    # ------------------------------------------------------------------ helpers
+
+    def _fail(self, message: str) -> SubethaError:
+        return SubethaError(self._redact(message))
+
+    def _request(self, url: str, method: str, body: Optional[str], headers: dict) -> httpx.Response:
+        hdrs = dict(headers)
+        if body is not None and not any(k.lower() == "content-type" for k in hdrs):
+            hdrs["content-type"] = "application/json"
+        try:
+            res = self._http.request(method, url, content=body, headers=hdrs)
+        except httpx.HTTPError as e:
+            raise self._fail(f"request failed: {e}") from None
+        if 300 <= res.status_code < 400:
+            raise self._fail(
+                f"redirect ({res.status_code}) refused: redirects are blocked so a payment cannot be steered off the allowlist"
+            )
+        return res
+
+    @staticmethod
+    def _bounded(res: httpx.Response) -> tuple[str, bool]:
+        raw = res.content
+        if len(raw) <= _MAX_RESOURCE_BYTES:
+            return raw.decode("utf-8", errors="replace"), False
+        return raw[:_MAX_RESOURCE_BYTES].decode("utf-8", errors="ignore"), True
+
+    def _check_headers(self, headers: Optional[dict]) -> dict:
+        for k in headers or {}:
+            if _RESERVED_HEADER.match(k):
+                raise self._fail(f'header "{k}" is reserved for the x402 protocol')
+        return dict(headers or {})
+
+    def _select_offer(self, url: str, res: httpx.Response) -> Requirements:
+        header = res.headers.get("PAYMENT-REQUIRED")
+        if not header:
+            raise self._fail("402 without a PAYMENT-REQUIRED header")
+        doc = decode_payment_required(header)
+        candidates = [a for a in doc["accepts"] if isinstance(a, dict) and a.get("scheme") == SCHEME]
+        if not candidates:
+            raise self._fail("no subetha-zerc20 offer in the 402")
+        parsed = [parse_requirements(c) for c in candidates]
+        allowed, reasons = self.policy.filter_offers(parsed)
+        if not allowed:
+            reason = f"spending policy rejected all offers: {'; '.join(reasons) or 'no acceptable offers'}"
+            self.policy.record_attempt(url, "rejected", reason)
+            raise self._fail(reason)
+        return allowed[0]
+
+    # ------------------------------------------------------------------ approval
+
+    def _approval_gate(self, url: str, req: Requirements) -> None:
+        """Equivalent of the TS applyApprovalGate (PR #34): threshold → callback with a
+        bounded wait → offer-bound identity re-check. Refusals raise; approval returns."""
+        if self.approve_above is None or req.amount <= self.approve_above:
+            return
+        snapshot = ApprovalRequest(
+            url=url,
+            quoted=str(req.amount),
+            token=req.asset,
+            network=req.network,
+            pay_to=req.pay_to,
+            challenge_nonce=req.challenge_nonce,
+            fee=(req.fee or {}).get("amount") if req.fee else None,
+        )
+        self.policy.record_attempt(url, "approval-requested", amount=snapshot.quoted)
+
+        def refuse(reason: str) -> None:
+            self.policy.record_attempt(url, "rejected", reason, snapshot.quoted)
+            raise self._fail(reason)
+
+        if self.approve_payment is None:
+            refuse(
+                f"approval required (quoted {snapshot.quoted} > approve_above={self.approve_above}) but no approval "
+                "channel is available — unset the threshold or pass approve_payment"
+            )
+        # No context manager: `with` would shutdown(wait=True) and defeat the timeout.
+        executor = ThreadPoolExecutor(max_workers=1)
+        try:
+            future = executor.submit(self.approve_payment, snapshot)
+            try:
+                approved = bool(future.result(timeout=self.approval_timeout_s))
+            except FutureTimeout:
+                refuse(f"approval timed out after {self.approval_timeout_s}s — payment not made")
+            except Exception:
+                refuse("approval cancelled (approver raised) — payment not made")
+        finally:
+            executor.shutdown(wait=False, cancel_futures=True)  # orphan worker is harmless
+        if not approved:
+            refuse("approval declined by human — payment not made")
+        # TOCTOU defense: what was approved must be what is about to be paid.
+        same = (
+            snapshot.quoted == str(req.amount)
+            and snapshot.token == req.asset
+            and snapshot.network == req.network
+            and snapshot.pay_to == req.pay_to
+            and snapshot.challenge_nonce == req.challenge_nonce
+        )
+        if not same:
+            refuse("approved offer no longer matches the offer being paid — refusing")
+        self.policy.record_attempt(url, "approval-approved", amount=snapshot.quoted)
+
+    # ------------------------------------------------------------------ payloads
+
+    def _check_expiry(self, req: Requirements) -> None:
+        now = time.time() + _EXPIRY_MARGIN_S
+        if req.expires_at <= now:
+            raise self._fail(f"offer expired (expiresAt={req.expires_at}) — obtain a fresh 402")
+        if self.mode == "permit" and req.deadline is not None and req.deadline <= now:
+            raise self._fail(f"permit deadline passed (deadline={req.deadline}) — obtain a fresh 402")
+
+    def _build_payload(self, req: Requirements) -> tuple[dict, str]:
+        """Returns (payload, kind). Accounts the spend at the irreversibility point."""
+        if self._account is None:
+            raise self._fail("private_key is required to pay (quote works without it)")
+        if self.mode == "permit":
+            if req.helper is None or req.deadline is None:
+                raise self._fail("offer has no helper/deadline — the gasless permit path is not offered (mode='permit' never degrades)")
+            token_name = self._rpc.token_name(req.asset)
+            nonce = self._rpc.permit_nonce(req.asset, self._account.address)
+            permit = sign_permit(
+                self._account, token=req.asset, token_name=token_name, chain_id=req.chain_id,
+                helper=req.helper, value=req.amount, nonce=nonce, deadline=req.deadline,
+            )
+            burn_auth = sign_burn_auth(
+                self._account, token=req.asset, chain_id=req.chain_id, helper=req.helper,
+                burn_address=req.pay_to, value=req.amount, challenge_nonce=req.challenge_nonce, deadline=req.deadline,
+            )
+            payload = {"challengeNonce": req.challenge_nonce, "payer": self._account.address, "permit": permit, "burnAuthSig": burn_auth}
+            self.policy.record_spend(req)  # reservation (released on definitive settle rejection)
+            return payload, "permit"
+        # self-transfer: the burn is money gone the moment it lands
+        onchain = self._rpc.chain_id()
+        if onchain != req.chain_id:
+            raise self._fail(f"RPC chain id {onchain} does not match the offer network {req.network}")
+        tx_hash = self._rpc.send_erc20_transfer(
+            self._account, token=req.asset, to=req.pay_to, amount=req.amount, chain_id=req.chain_id
+        )
+        self._rpc.wait_receipt(tx_hash)  # raises on revert/timeout — payload never sent
+        self.policy.record_spend(req)
+        return {"challengeNonce": req.challenge_nonce, "burnTxHash": tx_hash}, "self-transfer"
+
+    # ------------------------------------------------------------------ public API
+
+    def quote(self, url: str, method: str = "GET", body: Optional[str] = None) -> Quote:
+        reason = self.policy.check_url(url)
+        if reason:
+            raise self._fail(reason)
+        res = self._request(url, method, body, {})
+        if res.status_code != 402:
+            return Quote(status=res.status_code)
+        try:
+            req = self._select_offer(url, res)
+        except SubethaError as e:
+            return Quote(status=402, error=str(e))
+        approval_required = self.approve_above is not None and req.amount > self.approve_above
+        fee = req.fee or {}
+        return Quote(
+            status=402,
+            offer=Offer(
+                quoted=str(req.amount),
+                token=req.asset,
+                network=req.network,
+                gasless=req.helper is not None,
+                fee=fee.get("amount"),
+                bps=fee.get("bps"),
+                list_price=str(req.amount - int(fee["amount"])) if fee.get("amount") else None,
+                expires_at=req.expires_at,
+                approval_required=True if approval_required else None,
+            ),
+        )
+
+    def pay(self, url: str, method: str = "GET", body: Optional[str] = None, headers: Optional[dict] = None) -> PayResult:
+        with self._lock:
+            extra_headers = self._check_headers(headers)
+            reason = self.policy.check_url(url)
+            if reason:
+                self.policy.record_attempt(url, "rejected", reason)
+                raise self._fail(reason)
+
+            first = self._request(url, method, body, extra_headers)
+            if first.status_code != 402:
+                text, truncated = self._bounded(first)
+                return PayResult(status=first.status_code, resource=text, truncated=truncated)
+
+            req = self._select_offer(url, first)
+            self._approval_gate(url, req)
+            self._check_expiry(req)
+            try:
+                payload, kind = self._build_payload(req)
+            except SubethaError as e:
+                # RPC/node errors can echo request params (even the raw signed tx) —
+                # everything that reaches the caller or the report goes through _fail.
+                raise self._fail(str(e)) from None
+
+            paying_headers = dict(extra_headers)
+            paying_headers["PAYMENT-SIGNATURE"] = encode_payment_signature(req.raw, payload)
+            second = self._request(url, method, body, paying_headers)
+
+            if second.status_code == 402 and kind == "permit":
+                # definitive settle rejection ⇒ no funds moved ⇒ refund the reservation
+                self.policy.release(req)
+                detail = ""
+                reissued = decode_payment_required(second.headers.get("PAYMENT-REQUIRED", "")) if second.headers.get("PAYMENT-REQUIRED") else None
+                if isinstance(reissued, dict) and isinstance(reissued.get("error"), str):
+                    detail = f": {reissued['error']}"
+                # redact BEFORE recording — the report must never carry provider-supplied
+                # signature-grade material either
+                msg = self._redact(f"settle rejected by the facilitator (no funds moved){detail}")
+                self.policy.record_attempt(url, "failed", msg)
+                raise SubethaError(msg)
+            if second.status_code >= 400:
+                # money may have moved (a self-transfer burn definitely did) — keep the accounting
+                msg = f"paid request failed with HTTP {second.status_code} (spend kept in the budget on the safe side)"
+                self.policy.record_attempt(url, "failed", msg)
+                raise self._fail(msg)
+
+            text, truncated = self._bounded(second)
+            settle = decode_payment_response(second.headers.get("PAYMENT-RESPONSE"))
+            self.policy.record_payment(url, req)
+            return PayResult(
+                status=second.status_code,
+                resource=text,
+                truncated=truncated,
+                payment=Payment(
+                    amount=str(req.amount),
+                    token=req.asset,
+                    network=req.network,
+                    fee=(req.fee or {}).get("amount") if req.fee else None,
+                    burn_tx_hash=payload.get("burnTxHash"),
+                    settle=settle,
+                ),
+            )
+
+    def report(self) -> dict:
+        return self.policy.report()

subetha/policy.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The spending policy — an equivalent port of the TS agent-tools SpendingPolicy
+(docs/AGENT-TOOLS.md): a hostname allowlist before any request leaves, offer filtering
+(network/token pins, per-payment and total caps) at payment selection, accounting at the
+irreversibility point, and an audit trail of attempts (including approval events)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+from urllib.parse import urlsplit
+
+from .types import Requirements
+
+_RING = 50
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class SpendingPolicy:
+    def __init__(
+        self,
+        *,
+        allowed_hosts: list[str] | str = ("localhost", "127.0.0.1"),
+        allowed_network: str = "eip155:31337",
+        allowed_token: Optional[str] = None,
+        max_per_payment: Optional[int] = None,
+        max_total: Optional[int] = None,
+    ):
+        self.allowed_hosts = allowed_hosts if allowed_hosts == "*" else [h.lower() for h in allowed_hosts]
+        self.allowed_network = allowed_network
+        self.allowed_token = allowed_token
+        self.max_per_payment = max_per_payment
+        self.max_total = max_total
+        self._spent: dict[str, int] = {}  # "network|token" -> base units
+        self._payments: list[dict] = []
+        self._attempts: list[dict] = []
+
+    # (b) pre-request gate
+    def check_url(self, raw_url: str) -> Optional[str]:
+        """Returns a refusal reason, or None when the URL is allowed."""
+        parts = urlsplit(raw_url)
+        if parts.scheme not in ("http", "https"):
+            return f"only http/https URLs are allowed (got {parts.scheme or 'none'})"
+        if self.allowed_hosts == "*":
+            return None
+        host = (parts.hostname or "").lower()
+        if host not in self.allowed_hosts:
+            return (
+                f'host "{host}" is not in SUBETHA_ALLOWED_HOSTS ({", ".join(self.allowed_hosts) or "empty"}). '
+                'Add it to the allowlist (or set SUBETHA_ALLOWED_HOSTS=* to allow all) to permit payments to this host.'
+            )
+        return None
+
+    @staticmethod
+    def _pair_key(network: str, token: str) -> str:
+        return f"{network}|{token.lower()}"
+
+    # (a) selection filter — same rules as the TS paymentPolicy
+    def filter_offers(self, offers: list[Requirements]) -> tuple[list[Requirements], list[str]]:
+        reasons: list[str] = []
+        allowed: list[Requirements] = []
+        for req in offers:
+            if req.network != self.allowed_network:
+                reasons.append(f"offer on {req.network} rejected (SUBETHA_ALLOWED_NETWORK={self.allowed_network})")
+                continue
+            if self.allowed_token and req.asset.lower() != self.allowed_token.lower():
+                reasons.append(f"offer asset {req.asset} rejected (SUBETHA_ALLOWED_TOKEN={self.allowed_token})")
+                continue
+            if self.max_per_payment is not None and req.amount > self.max_per_payment:
+                reasons.append(
+                    f"offer of {req.amount} exceeds SUBETHA_MAX_PER_PAYMENT={self.max_per_payment}. "
+                    "Raise the limit to allow this payment."
+                )
+                continue
+            if self.max_total is not None:
+                total = self._spent.get(self._pair_key(req.network, req.asset), 0) + req.amount
+                if total > self.max_total:
+                    reasons.append(
+                        f"paying {req.amount} would bring the session total to {total}, over "
+                        f"SUBETHA_MAX_TOTAL={self.max_total}. Raise the limit or start a new session."
+                    )
+                    continue
+            allowed.append(req)
+        return allowed, reasons
+
+    # accounting at the irreversibility point
+    def record_spend(self, req: Requirements) -> None:
+        key = self._pair_key(req.network, req.asset)
+        self._spent[key] = self._spent.get(key, 0) + req.amount
+
+    def release(self, req: Requirements) -> None:
+        """Refund a PERMIT reservation whose settle was definitively rejected."""
+        key = self._pair_key(req.network, req.asset)
+        current = self._spent.get(key, 0)
+        self._spent[key] = current - req.amount if current > req.amount else 0
+
+    def record_payment(self, url: str, req: Requirements) -> None:
+        self._payments.append(
+            {"url": url, "amount": str(req.amount), "token": req.asset, "network": req.network, "at": _now()}
+        )
+        self.record_attempt(url, "paid", amount=str(req.amount))
+
+    def record_attempt(self, url: str, outcome: str, reason: Optional[str] = None, amount: Optional[str] = None) -> None:
+        self._attempts.append({"url": url, "outcome": outcome, "reason": reason, "amount": amount, "at": _now()})
+        if len(self._attempts) > _RING:
+            self._attempts.pop(0)
+
+    def report(self) -> dict:
+        totals = []
+        for key, spent in self._spent.items():
+            network, token = key.split("|", 1)
+            totals.append({"network": network, "token": token, "spent": str(spent)})
+        return {
+            "totals": totals,
+            "payments": list(self._payments),
+            "attempts": list(self._attempts),
+            "limits": {
+                "per_payment": str(self.max_per_payment) if self.max_per_payment is not None else None,
+                "total": str(self.max_total) if self.max_total is not None else None,
+                "allowed_hosts": self.allowed_hosts,
+                "allowed_network": self.allowed_network,
+                "allowed_token": self.allowed_token,
+            },
+        }

subetha/rpc.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal JSON-RPC over httpx — everything the client needs from the chain, nothing
+more: eth_call reads for the permit path (token name, permit nonce), and the fixed
+self-transfer transaction recipe (requirements FR1): pending nonce, a9059cbb calldata,
+eth_estimateGas, legacy type-0 gas price, raw send, receipt polling with status==0x1
+required."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .types import SubethaError
+
+_TRANSFER_SELECTOR = "a9059cbb"
+_NAME_SELECTOR = "0x06fdde03"       # name()
+_NONCES_SELECTOR = "0x7ecebe00"     # nonces(address)
+
+
+def erc20_transfer_data(to: str, amount: int) -> str:
+    return "0x" + _TRANSFER_SELECTOR + to.removeprefix("0x").lower().rjust(64, "0") + format(amount, "x").rjust(64, "0")
+
+
+class Rpc:
+    def __init__(self, url: str, timeout_s: float = 30.0):
+        self.url = url
+        self._http = httpx.Client(timeout=timeout_s)
+        self._id = 0
+
+    def _call(self, method: str, params: list[Any]) -> Any:
+        self._id += 1
+        try:
+            res = self._http.post(self.url, json={"jsonrpc": "2.0", "id": self._id, "method": method, "params": params})
+            res.raise_for_status()
+            body = res.json()
+        except httpx.HTTPError as e:
+            raise SubethaError(f"RPC {method} failed: {e}") from None
+        if "error" in body:
+            raise SubethaError(f"RPC {method} error: {body['error'].get('message', body['error'])}")
+        return body.get("result")
+
+    def chain_id(self) -> int:
+        return int(self._call("eth_chainId", []), 16)
+
+    def eth_call(self, to: str, data: str) -> str:
+        return self._call("eth_call", [{"to": to, "data": data}, "latest"])
+
+    def token_name(self, token: str) -> str:
+        raw = bytes.fromhex(self.eth_call(token, _NAME_SELECTOR).removeprefix("0x"))
+        # ABI string: [offset:32][length:32][utf8...]
+        if len(raw) < 64:
+            raise SubethaError("token name() returned malformed data")
+        length = int.from_bytes(raw[32:64], "big")
+        return raw[64 : 64 + length].decode("utf-8")
+
+    def permit_nonce(self, token: str, owner: str) -> int:
+        data = _NONCES_SELECTOR + owner.removeprefix("0x").lower().rjust(64, "0")
+        return int(self.eth_call(token, data), 16)
+
+    def balance_of(self, token: str, owner: str) -> int:
+        data = "0x70a08231" + owner.removeprefix("0x").lower().rjust(64, "0")
+        return int(self.eth_call(token, data), 16)
+
+    def eth_balance(self, addr: str) -> int:
+        return int(self._call("eth_getBalance", [addr, "latest"]), 16)
+
+    # --- the fixed self-transfer recipe ------------------------------------------
+
+    def send_erc20_transfer(self, account: Any, *, token: str, to: str, amount: int, chain_id: int) -> str:
+        nonce = int(self._call("eth_getTransactionCount", [account.address, "pending"]), 16)
+        data = erc20_transfer_data(to, amount)
+        gas = int(self._call("eth_estimateGas", [{"from": account.address, "to": token, "data": data}]), 16)
+        gas_price = int(self._call("eth_gasPrice", []), 16)
+        tx = {
+            "nonce": nonce,
+            "gasPrice": gas_price,          # legacy type-0 (requirements FR1)
+            "gas": gas,
+            "to": token,
+            "value": 0,
+            "data": data,
+            "chainId": chain_id,
+        }
+        signed = account.sign_transaction(tx)
+        return self._call("eth_sendRawTransaction", ["0x" + signed.raw_transaction.hex()])
+
+    def wait_receipt(self, tx_hash: str, timeout_s: float = 60.0, poll_s: float = 0.5) -> dict:
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            receipt: Optional[dict] = self._call("eth_getTransactionReceipt", [tx_hash])
+            if receipt is not None:
+                if receipt.get("status") != "0x1":
+                    raise SubethaError(f"burn transaction {tx_hash} reverted — not paying")
+                return receipt
+            time.sleep(poll_s)
+        raise SubethaError(f"burn transaction {tx_hash} not mined within {timeout_s}s — not paying")

subetha/signing.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+"""EIP-712 signatures for the subetha-zerc20 permit path (docs/PROTOCOL.md §3.1):
+the EIP-2612 Permit (spender = the PermitBurner helper) and SubEtha's burn-bind
+BurnAuthorization. Both sign and recover directions — recovery exists so the test suite
+proves signature compatibility without a chain."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+_PERMIT_TYPES = {
+    "Permit": [
+        {"name": "owner", "type": "address"},
+        {"name": "spender", "type": "address"},
+        {"name": "value", "type": "uint256"},
+        {"name": "nonce", "type": "uint256"},
+        {"name": "deadline", "type": "uint256"},
+    ]
+}
+
+_BURN_AUTH_TYPES = {
+    "BurnAuthorization": [
+        {"name": "token", "type": "address"},
+        {"name": "payer", "type": "address"},
+        {"name": "burnAddress", "type": "address"},
+        {"name": "value", "type": "uint256"},
+        {"name": "challengeNonce", "type": "bytes32"},
+        {"name": "deadline", "type": "uint256"},
+    ]
+}
+
+
+def _permit_message(
+    *, token: str, token_name: str, chain_id: int, helper: str, payer: str, value: int, nonce: int, deadline: int
+) -> tuple[dict, dict, dict]:
+    domain = {"name": token_name, "version": "1", "chainId": chain_id, "verifyingContract": token}
+    message = {"owner": payer, "spender": helper, "value": value, "nonce": nonce, "deadline": deadline}
+    return domain, _PERMIT_TYPES, message
+
+
+def _burn_auth_message(
+    *, token: str, chain_id: int, helper: str, payer: str, burn_address: str, value: int, challenge_nonce: str, deadline: int
+) -> tuple[dict, dict, dict]:
+    domain = {"name": "SubEthaPermitBurner", "version": "1", "chainId": chain_id, "verifyingContract": helper}
+    message = {
+        "token": token,
+        "payer": payer,
+        "burnAddress": burn_address,
+        "value": value,
+        "challengeNonce": bytes.fromhex(challenge_nonce.removeprefix("0x")),
+        "deadline": deadline,
+    }
+    return domain, _BURN_AUTH_TYPES, message
+
+
+def sign_permit(
+    account: Any, *, token: str, token_name: str, chain_id: int, helper: str, value: int, nonce: int, deadline: int
+) -> dict:
+    """Returns the wire `permit` object: decimal-string numbers, v int, r/s hex."""
+    domain, types, message = _permit_message(
+        token=token, token_name=token_name, chain_id=chain_id, helper=helper,
+        payer=account.address, value=value, nonce=nonce, deadline=deadline,
+    )
+    signed = account.sign_typed_data(domain_data=domain, message_types=types, message_data=message)
+    return {
+        "value": str(value),
+        "nonce": str(nonce),
+        "deadline": str(deadline),
+        "v": signed.v,
+        "r": "0x" + signed.r.to_bytes(32, "big").hex(),
+        "s": "0x" + signed.s.to_bytes(32, "big").hex(),
+    }
+
+
+def sign_burn_auth(
+    account: Any, *, token: str, chain_id: int, helper: str, burn_address: str, value: int, challenge_nonce: str, deadline: int
+) -> str:
+    """Returns the wire `burnAuthSig`: the 65-byte r‖s‖v signature as 0x hex."""
+    domain, types, message = _burn_auth_message(
+        token=token, chain_id=chain_id, helper=helper, payer=account.address,
+        burn_address=burn_address, value=value, challenge_nonce=challenge_nonce, deadline=deadline,
+    )
+    signed = account.sign_typed_data(domain_data=domain, message_types=types, message_data=message)
+    return "0x" + signed.signature.hex()
+
+
+# --- recovery (test-side proof of signature compatibility) ---------------------------
+
+def recover_permit(
+    permit: dict, *, token: str, token_name: str, chain_id: int, helper: str, payer: str
+) -> str:
+    domain, types, message = _permit_message(
+        token=token, token_name=token_name, chain_id=chain_id, helper=helper,
+        payer=payer, value=int(permit["value"]), nonce=int(permit["nonce"]), deadline=int(permit["deadline"]),
+    )
+    sig = bytes.fromhex(permit["r"].removeprefix("0x")) + bytes.fromhex(permit["s"].removeprefix("0x")) + bytes([permit["v"]])
+    return Account.recover_message(
+        encode_typed_data(domain_data=domain, message_types=types, message_data=message), signature=sig
+    )
+
+
+def recover_burn_auth(
+    burn_auth_sig: str, *, token: str, chain_id: int, helper: str, payer: str, burn_address: str, value: int,
+    challenge_nonce: str, deadline: int
+) -> str:
+    domain, types, message = _burn_auth_message(
+        token=token, chain_id=chain_id, helper=helper, payer=payer,
+        burn_address=burn_address, value=value, challenge_nonce=challenge_nonce, deadline=deadline,
+    )
+    return Account.recover_message(
+        encode_typed_data(domain_data=domain, message_types=types, message_data=message),
+        signature=bytes.fromhex(burn_auth_sig.removeprefix("0x")),
+    )

subetha/types.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public result types (field-equivalent to the TS agent-tools payer, snake_case) and
+scheme constants. docs/PROTOCOL.md is the wire authority."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+SCHEME = "subetha-zerc20"
+X402_VERSION = 2
+
+
+class SubethaError(Exception):
+    """All client failures normalize to this (message already redacted)."""
+
+
+@dataclass
+class Offer:
+    quoted: str
+    token: str
+    network: str
+    gasless: bool
+    list_price: Optional[str] = None
+    fee: Optional[str] = None
+    bps: Optional[int] = None
+    expires_at: Optional[int] = None
+    approval_required: Optional[bool] = None
+
+
+@dataclass
+class Quote:
+    status: int
+    offer: Optional[Offer] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class Payment:
+    amount: str
+    token: str
+    network: str
+    fee: Optional[str] = None
+    burn_tx_hash: Optional[str] = None
+    settle: Optional[dict] = None
+
+
+@dataclass
+class PayResult:
+    status: int
+    resource: str
+    truncated: bool
+    payment: Optional[Payment] = None
+
+
+@dataclass
+class ApprovalRequest:
+    """What the human is asked to approve — also the identity the approval is bound to."""
+
+    url: str
+    quoted: str
+    token: str
+    network: str
+    pay_to: str
+    challenge_nonce: str
+    fee: Optional[str] = None
+
+
+@dataclass
+class Requirements:
+    """Validated view of a subetha-zerc20 PaymentRequirements. `raw` keeps the exact dict
+    received in the 402 — the PAYMENT-SIGNATURE envelope must echo it verbatim."""
+
+    raw: dict[str, Any]
+    pay_to: str
+    asset: str
+    amount: int
+    chain_id: int
+    network: str
+    challenge_nonce: str
+    expires_at: int
+    helper: Optional[str] = None
+    deadline: Optional[int] = None
+    fee: Optional[dict] = field(default=None)

subetha/wire.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+"""x402 v2 wire encoding for the subetha-zerc20 scheme, implemented from
+docs/PROTOCOL.md: PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers
+(base64 JSON) and the PaymentRequirements validation rules."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+from typing import Any, Optional
+
+from .types import SCHEME, X402_VERSION, Requirements, SubethaError
+
+_ADDR = re.compile(r"^0x[0-9a-fA-F]{40}$")
+_HEX32 = re.compile(r"^0x[0-9a-fA-F]{64}$")
+_DEC = re.compile(r"^\d+$")
+_NETWORK = re.compile(r"^eip155:(\d+)$")
+
+
+def _b64_json(header: str) -> Any:
+    return json.loads(base64.b64decode(header, validate=True).decode("utf-8"))
+
+
+def decode_payment_required(header: str) -> dict:
+    try:
+        doc = _b64_json(header)
+    except (ValueError, binascii.Error) as e:
+        raise SubethaError(f"PAYMENT-REQUIRED header is not decodable: {e}") from None
+    if not isinstance(doc, dict) or not isinstance(doc.get("accepts"), list):
+        raise SubethaError("PAYMENT-REQUIRED is missing the accepts list")
+    return doc
+
+
+def parse_requirements(req: dict) -> Requirements:
+    """Validate + narrow one subetha-zerc20 offer (PROTOCOL.md §2). Keeps the raw dict —
+    the PAYMENT-SIGNATURE envelope echoes it verbatim (PROTOCOL.md §3)."""
+    if req.get("scheme") != SCHEME:
+        raise SubethaError(f"scheme mismatch: expected {SCHEME}, got {req.get('scheme')}")
+    pay_to = req.get("payTo")
+    if not isinstance(pay_to, str) or not _ADDR.match(pay_to):
+        raise SubethaError(f"payTo is not an address: {pay_to}")
+    asset = req.get("asset")
+    if not isinstance(asset, str) or not _ADDR.match(asset):
+        raise SubethaError(f"asset is not an address: {asset}")
+    amount = req.get("amount")
+    if not isinstance(amount, str) or not _DEC.match(amount):
+        raise SubethaError(f"amount is not a base-unit integer: {amount}")
+    network = req.get("network", "")
+    m = _NETWORK.match(network) if isinstance(network, str) else None
+    if not m:
+        raise SubethaError(f"not an eip155 CAIP-2 network id: {network}")
+    extra = req.get("extra") or {}
+    if not isinstance(extra, dict):
+        raise SubethaError("extra malformed (expect an object)")
+    nonce = extra.get("challengeNonce")
+    if not isinstance(nonce, str) or not _HEX32.match(nonce):
+        raise SubethaError("extra.challengeNonce missing or malformed (expect 32-byte hex)")
+    expires_at = extra.get("expiresAt")
+    if not isinstance(expires_at, int):
+        raise SubethaError("extra.expiresAt missing (unix seconds)")
+    helper = extra.get("helper")
+    if helper is not None and (not isinstance(helper, str) or not _ADDR.match(helper)):
+        raise SubethaError("extra.helper is not an address")
+    deadline = extra.get("deadline")
+    if deadline is not None and not isinstance(deadline, int):
+        raise SubethaError("extra.deadline is not a number")
+    fee = extra.get("fee")
+    if fee is not None:
+        if not isinstance(fee, dict) or not isinstance(fee.get("amount"), str) or not _DEC.match(fee["amount"]) or not isinstance(fee.get("bps"), int):
+            raise SubethaError("extra.fee malformed (expect { amount: decimal string, bps: number })")
+    return Requirements(
+        raw=req,
+        pay_to=pay_to,
+        asset=asset,
+        amount=int(amount),
+        chain_id=int(m.group(1)),
+        network=network,
+        challenge_nonce=nonce,
+        expires_at=expires_at,
+        helper=helper,
+        deadline=deadline,
+        fee=fee,
+    )
+
+
+def encode_payment_signature(accepted: dict, payload: dict) -> str:
+    """PROTOCOL.md §3: { x402Version: 2, accepted: <the offer echoed verbatim>, payload }.
+    `accepted` must be the exact dict received in the 402 — the middleware deep-equal
+    matches it against its own record."""
+    envelope = {"x402Version": X402_VERSION, "accepted": accepted, "payload": payload}
+    return base64.b64encode(json.dumps(envelope, separators=(",", ":")).encode("utf-8")).decode("ascii")
+
+
+def decode_payment_response(header: Optional[str]) -> Optional[dict]:
+    """SettleResponse from PAYMENT-RESPONSE; decode failures are non-fatal (None)."""
+    if not header:
+        return None
+    try:
+        doc = _b64_json(header)
+        return doc if isinstance(doc, dict) else None
+    except (ValueError, binascii.Error):
+        return None

subetha-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: subetha
+Version: 0.1.0
+Summary: Pay for x402 (HTTP 402) APIs privately over SubEtha's zERC20 rail — Python payer client
+Project-URL: Homepage, https://github.com/peaceandwhisky/SubEtha
+Project-URL: Repository, https://github.com/peaceandwhisky/SubEtha
+Project-URL: Issues, https://github.com/peaceandwhisky/SubEtha/issues
+Project-URL: Changelog, https://github.com/peaceandwhisky/SubEtha/blob/main/python/CHANGELOG.md
+Project-URL: Documentation, https://github.com/peaceandwhisky/SubEtha/blob/main/docs/PROTOCOL.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,http-402,payments,privacy,x402,zerc20
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: eth-account>=0.13
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# subetha (Python) — private x402 payments for Python agents
+
+Pay for x402 (HTTP 402) paywalled APIs over SubEtha's zERC20 rail so that **no on-chain
+trail links the payer to the payee**: the burn itself is public (amounts stay
+transparent), but nothing on-chain connects it to the provider's treasury. This is the
+Python counterpart of the TypeScript agent tools
+([docs/AGENT-TOOLS.md](https://github.com/peaceandwhisky/SubEtha/blob/main/docs/AGENT-TOOLS.md)):
+the same wire protocol
+([docs/PROTOCOL.md](https://github.com/peaceandwhisky/SubEtha/blob/main/docs/PROTOCOL.md) —
+this package is a reference implementation written against that spec), the same
+spending-policy semantics.
+
+## Status
+
+**Experimental (0.x).** The API may change in breaking ways between 0.x minor
+releases while integrations (agent frameworks, plugins) shape it. If you depend on
+this package, **pin a minor**: `subetha>=0.1,<0.2`. Stability will be declared at
+1.0. Changes are recorded in
+[CHANGELOG.md](https://github.com/peaceandwhisky/SubEtha/blob/main/python/CHANGELOG.md).
+
+## Scope
+
+This package is the **payer side only**: decode a 402 offer, decide under an
+operator-configured spending policy, sign, pay, report. That is a deliberate,
+stable boundary — it is also what the API-stability promise will cover at 1.0.
+
+The provider, facilitator, and settlement layers are TypeScript and live in the
+[same repository](https://github.com/peaceandwhisky/SubEtha); there is no plan to
+port them. Paying touches no zk code and no BUSL code: this package depends only on
+`httpx` and `eth-account`.
+
+## Install
+
+```bash
+pip install subetha
+```
+
+For development (from a repository checkout):
+
+```bash
+uv pip install -e python/          # from the repository root
+# or: pip install -e python/
+```
+
+Dependencies: `httpx`, `eth-account` (no web3.py). Python ≥ 3.11.
+
+## Use
+
+```python
+from subetha import SubethaClient, SpendingPolicy
+
+client = SubethaClient(
+    private_key="0x…",                    # the paying account (permit: only signs, no gas)
+    rpc_url="http://127.0.0.1:8545",
+    mode="permit",                         # gasless (default); or "self-transfer"
+    policy=SpendingPolicy(
+        allowed_hosts=["127.0.0.1"],       # first line of defense — keep it tight
+        max_per_payment=100_000,           # token base units
+        max_total=5_000_000,
+    ),
+    approve_above=10_000,                                  # optional human-in-the-loop
+    approve_payment=lambda info: ask_human(info),          # True = approve
+)
+
+q = client.quote("http://127.0.0.1:4031/api/complete", method="POST", body='{"prompt":"hi"}')
+print(q.offer.quoted, q.offer.fee, q.offer.approval_required)
+
+r = client.pay("http://127.0.0.1:4031/api/complete", method="POST", body='{"prompt":"hi"}')
+print(r.status, r.payment.amount, r.resource)
+
+print(client.report())                     # totals / payments / attempts (incl. approvals)
+```
+
+`SubethaClient.from_env()` reads the same `SUBETHA_*` variables as the TypeScript tools
+(`SUBETHA_PAYER_PK`, `SUBETHA_RPC_URL`, `SUBETHA_MODE`, `SUBETHA_ALLOWED_HOSTS`,
+`SUBETHA_ALLOWED_NETWORK`, `SUBETHA_ALLOWED_TOKEN`, `SUBETHA_MAX_PER_PAYMENT`,
+`SUBETHA_MAX_TOTAL`, `SUBETHA_APPROVE_ABOVE`, `SUBETHA_APPROVAL_TIMEOUT_MS`,
+`SUBETHA_TIMEOUT_MS`).
+
+### Semantics you can rely on
+
+- **Policy before money**: host allowlist before any request; per-payment / total caps
+  and network/token pins at offer selection. Refusals raise `SubethaError` with the
+  reason; nothing is paid.
+- **Approval**: payments quoted above `approve_above` call `approve_payment` (bounded by
+  `approval_timeout_s`, default 120 s). Decline / timeout / a raising callback / no
+  callback ⇒ refused. The approval is bound to the exact offer.
+- **Accounting at the point of no return**: a self-transfer burn is counted the moment it
+  lands; a permit reservation is released only when settle is definitively rejected.
+- **One payment at a time**; errors are redacted (the key never appears in messages).
+- `mode="permit"` fail-fasts when the offer lacks the gasless path — it never silently
+  degrades to a gas-paying transfer.
+
+## Key management & safety
+
+This client signs with a raw private key. Treat that as the threat model:
+
+- **At runtime the key exists decrypted in process memory.** Encrypted config or
+  secret stores protect the key *at rest* — anything that can read your agent
+  process (or its crash dumps) can read the key. Plan accordingly.
+- **Use a dedicated hot wallet.** Fund the paying account with small amounts, top it
+  up as needed, and keep it separate from any treasury or personal wallet. If it
+  leaks, the loss is bounded by the balance and your `max_total`.
+- **The spending policy is the operator's, not the agent's.** Allowlist, caps, and
+  `approve_above` are configuration the human sets; agents cannot raise their own
+  limits. Keep `allowed_hosts` as tight as your deployment allows.
+- **Redaction is scoped.** This package keeps the key out of its own errors and
+  reports; whatever *you* log around it (request dumps, env printouts) is your
+  responsibility.
+- Report vulnerabilities privately via
+  [GitHub Security Advisories](https://github.com/peaceandwhisky/SubEtha/security/advisories)
+  (see [SECURITY.md](https://github.com/peaceandwhisky/SubEtha/blob/main/SECURITY.md)).
+
+## LangChain (Python) example
+
+No extra dependency in this package — wrap the client yourself:
+
+```python
+from langchain_core.tools import tool
+from subetha import SubethaClient, SubethaError
+
+client = SubethaClient.from_env()
+
+@tool
+def subetha_x402_pay(url: str, method: str = "GET", body: str | None = None) -> str:
+    """Pay for an x402 resource privately under the configured spending policy."""
+    try:
+        r = client.pay(url, method=method, body=body)
+        return f"HTTP {r.status}; paid {r.payment.amount if r.payment else 0}; {r.resource[:2000]}"
+    except SubethaError as e:
+        return f"ERROR: {e}"   # let the agent read the refusal instead of crashing
+```
+
+## Tests
+
+```bash
+uv run --project python pytest python/tests -q          # unit (no chain needed)
+# cross-language live e2e (real stack + the TypeScript provider/facilitator):
+PERMIT_BURNER_ADDRESS=0x… pnpm --filter @subetha/demo-official exec tsx ../../python/scripts/live-e2e.ts
+```
+
+## License
+
+Apache-2.0 (this package). Note that operating a SubEtha facilitator commercially / in
+production requires a separate use grant from the zERC20 team — see the License section
+of the [repository README](https://github.com/peaceandwhisky/SubEtha#license).

subetha-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+subetha/__init__.py,sha256=rDcdGZKIbjAyKG2bxH4Z9o0sU7Yg6eCKqe6jBriPb2Y,738
+subetha/_redact.py,sha256=aLhV-_T224P1LkPznJHxUFdTONKfV_kn4WUGMQKk9XI,622
+subetha/client.py,sha256=Z-Skw2gkNb9hYUOlc9_2Bw26sw4q-5jMhEDCb79dXwE,15742
+subetha/policy.py,sha256=aeSvuqpAH4M_Zi4pEl-cClIeZ42JaaUxYWtFtlsQjns,5705
+subetha/rpc.py,sha256=le0FvtBva7T-9ayB4ZBDrnB7CRdlvidq6MCw7ZhQNSs,4176
+subetha/signing.py,sha256=d_wvNQo9RLmjLXnKTP68AGH7UqjLS1a6uGyIHkCZgOY,4836
+subetha/types.py,sha256=EPoP1byOdEjWNmqO5e2_IW5JLZDY4HkaPzpXtMFVB4w,1865
+subetha/wire.py,sha256=t_21YIHIkQsVbz2BbCtrDeGNZViZeApN3tclQvK__jg,4411
+subetha-0.1.0.dist-info/METADATA,sha256=oCNgWiR-mM5FINySkDol49Ccwk4URsc2bxk9-uSktOM,7677
+subetha-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+subetha-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+subetha-0.1.0.dist-info/RECORD,,

subetha-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

subetha-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.