railgate 1.0.0__py3-none-any.whl

policy_gate/MANIFEST.sha256

@@ -0,0 +1,3 @@
+bdbff3b6c8a22b1c8d06e50a5043ae9cef9bc17f202085e3ae5d909fe9851dfb  policy.py
+6acc91164c89ae08003ba53fb77ca21c45439ca2fa68e3344c8c402b8ffd2298  store.py
+bdaec65f0a1cb3174e16ab6025a1f67c177b41102c3e1384dbe892059762185f  gate.py

policy_gate/__init__.py

@@ -0,0 +1,7 @@
+"""Pre-signing payment policy gate for x402 buyer agents (EXP-001)."""
+from .factory import GatedClient, create_gated_client
+from .gate import PolicyGate, PolicyRefusal
+from .policy import PaymentPolicy, PolicyError
+
+__all__ = ["GatedClient", "create_gated_client", "PolicyGate", "PolicyRefusal",
+           "PaymentPolicy", "PolicyError"]

policy_gate/factory.py

@@ -0,0 +1,80 @@
+"""Mandatory-construction factory for gated x402 clients (EXP-001).
+
+AgentBadge's evidence line is the spec: "a cap you can forget is a cap you
+will forget." So there is no code path here that builds a paying client
+without a policy — create_gated_client(policy=None) raises TypeError with
+the same shape AgentBadge used: refusing to create an uncapped paying
+client. The vendored SDK's own SpendControls are ALSO set from the same
+policy (defense in depth): the SDK filters non-allowlisted assets and
+over-cap accepts during selection, and this gate enforces the stateful
+layer (budgets, counterparty, velocity, intent, replay) at the
+pre-signing hook.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from x402 import x402Client
+from x402.mechanisms.evm.exact import ExactEvmScheme
+from x402.schemas import PaymentAbortedError
+
+from .gate import PolicyGate, PolicyRefusal
+from .policy import PaymentPolicy, usd_money_string
+
+
+@dataclass
+class GatedClient:
+    client: x402Client
+    gate: PolicyGate
+    policy: PaymentPolicy
+
+    async def pay(self, payment_required, *, intent: str | None = None,
+                  expected_pay_to: str | None = None,
+                  expected_resource: str | None = None):
+        """Create a payment payload through the gate.
+
+        Declares intent first when given. On policy denial raises
+        PolicyRefusal with the structured refusal dict (never a bare
+        exception string to parse).
+        """
+        if intent is not None:
+            self.gate.declare_intent(intent, expected_pay_to=expected_pay_to,
+                                     expected_resource=expected_resource)
+        self.gate.last_refusal = None
+        try:
+            return await self.client.create_payment_payload(payment_required)
+        except PaymentAbortedError:
+            if self.gate.last_refusal is not None:
+                raise PolicyRefusal(self.gate.last_refusal) from None
+            raise
+
+
+def create_gated_client(policy: PaymentPolicy | None, signer, *,
+                        store_path: str, audit_path: str | None = None,
+                        clock=None) -> GatedClient:
+    if policy is None:
+        raise TypeError("PaymentPolicy required — refusing to create an uncapped paying client")
+    if signer is None:
+        raise TypeError("signer required — refusing to create a paying client without a signer")
+    gate = PolicyGate(policy, store_path, audit_path=audit_path, clock=clock)
+    client = x402Client()
+    for network in policy.allowed_networks:
+        if ":*" in network:
+            raise ValueError("factory needs concrete networks to register schemes; "
+                             "wildcard network patterns are enforced by the gate but "
+                             "cannot be registered — list networks explicitly")
+        client.register(network, ExactEvmScheme(signer=signer))
+    allowed_assets = [
+        {"network": network, "asset": asset,
+         "max_amount_per_payment": str(policy.per_call_cap_atomic)}
+        for network in policy.allowed_networks
+        for asset in policy.allowed_assets
+    ]
+    client.set_spend_controls({
+        "max_amount_per_payment": usd_money_string(policy.per_call_cap_atomic, policy.asset_decimals),
+        "allowed_assets": allowed_assets,
+    })
+    client.on_before_payment_creation(gate.before_hook)
+    client.on_after_payment_creation(gate.after_hook)
+    client.on_payment_creation_failure(gate.failure_hook)
+    return GatedClient(client=client, gate=gate, policy=policy)

policy_gate/gate.py

@@ -0,0 +1,273 @@
+"""PolicyGate — the pre-signing enforcement layer (EXP-001).
+
+Sits on the REAL x402 client's payment-creation hooks:
+
+  before-hook  -> evaluate policy; on deny return AbortResult (the client
+                  raises PaymentAbortedError and the scheme/signer is NEVER
+                  invoked, so no signature exists); on allow, atomically
+                  reserve budget in the SpendStore.
+  after-hook   -> commit the reservation (a signature now exists).
+  failure-hook -> release the reservation (creation failed downstream).
+
+Every decision (allow and deny) is appended to an audit JSONL. Every denial
+builds a structured refusal {code, detail, amount, pay_to, network,
+suggested_action, ...} — MEMO-003 Q3: the caller never parses prose.
+
+Refusal actions:
+  do_not_retry           — same request can never pass (allowlist, mismatch)
+  escalate_to_operator   — a human/policy change is the way out (budgets, caps)
+  degrade_or_skip        — try a cheaper resource or proceed without it
+  retry_after_window     — velocity / replay window; wait, then retry
+  declare_intent_and_retry — intent was missing; declare it and retry
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from x402.schemas import AbortResult
+
+from .policy import PaymentPolicy, parse_atomic_amount
+from .store import SpendStore, StoreError
+
+_ACTION = {
+    "PER_CALL_CAP": "degrade_or_skip",
+    "SESSION_BUDGET": "escalate_to_operator",
+    "DAILY_BUDGET": "escalate_to_operator",
+    "COUNTERPARTY_CAP": "escalate_to_operator",
+    "COUNTERPARTY_NOT_ALLOWED": "escalate_to_operator",
+    "NETWORK_NOT_ALLOWED": "do_not_retry",
+    "ASSET_NOT_ALLOWED": "do_not_retry",
+    "VELOCITY": "retry_after_window",
+    "REPLAY_DUPLICATE": "retry_after_window",
+    "INTENT_REQUIRED": "declare_intent_and_retry",
+    "INTENT_MISMATCH": "do_not_retry",
+    "MALFORMED_AMOUNT": "do_not_retry",
+    "UNSUPPORTED_VERSION": "do_not_retry",
+    "INTERNAL_FAIL_CLOSED": "escalate_to_operator",
+}
+
+
+class PolicyRefusal(Exception):
+    """Structured refusal raised by GatedClient.pay(). Carries the refusal dict."""
+
+    def __init__(self, refusal: dict):
+        self.refusal = refusal
+        super().__init__(f"{refusal.get('code')}: {refusal.get('detail')}")
+
+
+class PolicyGate:
+    def __init__(self, policy: PaymentPolicy, store_path: str,
+                 audit_path: str | None = None, clock=None):
+        if policy is None:
+            raise TypeError("PaymentPolicy required — refusing to create an uncapped paying client")
+        self.policy = policy
+        self._clock = clock or time.time
+        self.session_id = uuid.uuid4().hex
+        self.store = SpendStore(store_path, self.session_id)
+        self._audit_path = audit_path
+        self._audit_lock = threading.Lock()
+        self._pending: dict[str, list[int]] = defaultdict(list)
+        self._pending_lock = threading.Lock()
+        # Intent state: a declaration authorizes payments that match it.
+        # Each declare_intent() bumps the declaration counter; the counter is
+        # part of the payment fingerprint, so re-declaring intent is what
+        # makes a deliberate repeat purchase distinguishable from a loop
+        # replaying one authorization forever (CARD-003 loss mode #1).
+        self._intent_text: str | None = None
+        self._intent_hash: str | None = None
+        self._intent_pay_to: str | None = None
+        self._intent_resource: str | None = None
+        self._intent_decl_id = 0
+        self.last_refusal: dict | None = None
+
+    # ---------------------------------------------------------------- intent
+    def declare_intent(self, text: str, *, expected_pay_to: str | None = None,
+                       expected_resource: str | None = None) -> int:
+        """Declare what the next payment(s) are FOR. Returns declaration id.
+
+        expected_pay_to / expected_resource bind the intent: a payment whose
+        counterparty or resource differs is refused INTENT_MISMATCH — the
+        signature is bound to the declared purpose before it exists.
+        """
+        if not isinstance(text, str) or not text.strip():
+            raise ValueError("intent text must be a non-empty string")
+        self._intent_text = text
+        self._intent_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        self._intent_pay_to = expected_pay_to.lower() if expected_pay_to else None
+        self._intent_resource = expected_resource
+        self._intent_decl_id += 1
+        return self._intent_decl_id
+
+    # ---------------------------------------------------------------- helpers
+    def _now(self) -> float:
+        return float(self._clock())
+
+    @staticmethod
+    def _day_start(now: float) -> float:
+        dt = datetime.fromtimestamp(now, tz=timezone.utc)
+        return dt.replace(hour=0, minute=0, second=0, microsecond=0).timestamp()
+
+    @staticmethod
+    def _fingerprint(*, intent_hash: str | None, decl_id: int, network: str,
+                     asset: str, pay_to: str, amount: int, resource_url: str | None) -> str:
+        raw = "|".join([intent_hash or "", str(decl_id), network, asset.lower(),
+                        pay_to.lower(), str(amount), resource_url or ""])
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    def _audit(self, record: dict) -> None:
+        if not self._audit_path:
+            return
+        record = {"ts": self._now(), "session_id": self.session_id, **record}
+        line = json.dumps(record, sort_keys=True)
+        with self._audit_lock:
+            with open(self._audit_path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+
+    def _deny(self, code: str, detail: str, *, amount=None, pay_to=None,
+              network=None, resource_url=None) -> AbortResult:
+        refusal = {
+            "code": code,
+            "detail": detail,
+            "suggested_action": _ACTION[code],
+            "amount_atomic": amount,
+            "pay_to": pay_to,
+            "network": network,
+            "resource_url": resource_url,
+            "session_id": self.session_id,
+        }
+        if code in ("VELOCITY", "REPLAY_DUPLICATE"):
+            refusal["retry_after_seconds"] = (
+                self.policy.window_seconds if code == "VELOCITY"
+                else self.policy.replay_window_seconds)
+        self.last_refusal = refusal
+        self._audit({"decision": "deny", **refusal})
+        return AbortResult(reason="policy_refusal:" + json.dumps(refusal, sort_keys=True))
+
+    # ---------------------------------------------------------------- hooks
+    def before_hook(self, ctx) -> AbortResult | None:
+        """x402 on_before_payment_creation hook. None = allow."""
+        req = ctx.selected_requirements
+        payment_required = ctx.payment_required
+        resource_url = None
+        if getattr(payment_required, "resource", None) is not None:
+            resource_url = payment_required.resource.url
+        try:
+            amount_raw = req.get_amount() if hasattr(req, "get_amount") else getattr(req, "amount", None)
+            pay_to = getattr(req, "pay_to", None)
+            network = getattr(req, "network", None)
+            asset = getattr(req, "asset", None)
+            if pay_to is None or network is None or asset is None:
+                return self._deny("UNSUPPORTED_VERSION",
+                                  "requirements shape not supported by the gate (V2 required)",
+                                  resource_url=resource_url)
+            amount = parse_atomic_amount(amount_raw)
+            if amount is None:
+                return self._deny("MALFORMED_AMOUNT",
+                                  f"amount {amount_raw!r} is not an integer atomic amount",
+                                  pay_to=pay_to, network=network, resource_url=resource_url)
+            p = self.policy
+            if not p.network_allowed(str(network)):
+                return self._deny("NETWORK_NOT_ALLOWED", f"network {network} not in policy allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if not p.asset_allowed(str(asset)):
+                return self._deny("ASSET_NOT_ALLOWED", f"asset {asset} not in policy allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if not p.counterparty_allowed(str(pay_to)):
+                return self._deny("COUNTERPARTY_NOT_ALLOWED", f"pay_to {pay_to} not in counterparty allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if amount > p.per_call_cap_atomic:
+                return self._deny("PER_CALL_CAP",
+                                  f"amount {amount} exceeds per-call cap {p.per_call_cap_atomic}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if amount <= 0:
+                return self._deny("MALFORMED_AMOUNT", "amount must be positive",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if p.intent_required and self._intent_hash is None:
+                return self._deny("INTENT_REQUIRED", "no intent declared for this payment",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if self._intent_pay_to is not None and str(pay_to).lower() != self._intent_pay_to:
+                return self._deny("INTENT_MISMATCH",
+                                  f"payment pay_to {pay_to} does not match intent-bound counterparty {self._intent_pay_to}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if self._intent_resource is not None and resource_url != self._intent_resource:
+                return self._deny("INTENT_MISMATCH",
+                                  f"payment resource {resource_url} does not match intent-bound resource {self._intent_resource}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            now = self._now()
+            fingerprint = self._fingerprint(
+                intent_hash=self._intent_hash, decl_id=self._intent_decl_id,
+                network=str(network), asset=str(asset), pay_to=str(pay_to),
+                amount=amount, resource_url=resource_url)
+            status, value = self.store.check_and_reserve(
+                fingerprint=fingerprint, intent_hash=self._intent_hash,
+                amount=amount, pay_to=str(pay_to), network=str(network),
+                asset=str(asset), resource_url=resource_url, now=now,
+                day_start=self._day_start(now),
+                session_budget=p.session_budget_atomic,
+                daily_budget=p.daily_budget_atomic,
+                per_counterparty_cap=p.per_counterparty_cap_atomic,
+                max_per_window=p.max_payments_per_window,
+                window_seconds=p.window_seconds,
+                replay_window=p.replay_window_seconds)
+            if status == "deny":
+                return self._deny(str(value), f"aggregate policy limit reached: {value}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            with self._pending_lock:
+                self._pending[fingerprint].append(int(value))
+            self._audit({"decision": "allow", "amount_atomic": amount, "pay_to": pay_to,
+                         "network": network, "resource_url": resource_url,
+                         "intent_hash": self._intent_hash, "reservation_id": int(value)})
+            return None
+        except StoreError as e:
+            return self._deny("INTERNAL_FAIL_CLOSED", f"spend store unavailable; failing closed: {e}",
+                              resource_url=resource_url)
+        except Exception as e:  # any unexpected gate error must fail closed, never open
+            return self._deny("INTERNAL_FAIL_CLOSED", f"gate evaluation error; failing closed: {e!r}",
+                              resource_url=resource_url)
+
+    def _pop_reservation(self, ctx) -> int | None:
+        req = ctx.selected_requirements
+        payment_required = ctx.payment_required
+        resource_url = None
+        if getattr(payment_required, "resource", None) is not None:
+            resource_url = payment_required.resource.url
+        amount = parse_atomic_amount(req.get_amount() if hasattr(req, "get_amount") else None)
+        if amount is None:
+            return None
+        fingerprint = self._fingerprint(
+            intent_hash=self._intent_hash, decl_id=self._intent_decl_id,
+            network=str(req.network), asset=str(req.asset), pay_to=str(req.pay_to),
+            amount=amount, resource_url=resource_url)
+        with self._pending_lock:
+            stack = self._pending.get(fingerprint)
+            if stack:
+                rid = stack.pop()
+                if not stack:
+                    del self._pending[fingerprint]
+                return rid
+        return None
+
+    def after_hook(self, ctx) -> None:
+        rid = self._pop_reservation(ctx)
+        if rid is not None:
+            try:
+                self.store.commit(rid)
+            except StoreError:
+                # Signature exists but ledger failed: keep counting it as
+                # reserved (it still counts against budgets). Never release.
+                pass
+
+    def failure_hook(self, ctx) -> None:
+        rid = self._pop_reservation(ctx)
+        if rid is not None:
+            try:
+                self.store.release(rid)
+            except StoreError:
+                pass
+        return None

policy_gate/policy.py

@@ -0,0 +1,174 @@
+"""Declarative payment policy for the pre-signing gate (EXP-001).
+
+One small JSON document expresses every control (MEMO-003 Q2). All money is
+integer atomic units (e.g. USDC has 6 decimals: $0.10 = 100000). No floats
+anywhere near money. Validation is strict: unknown fields, missing caps,
+non-positive caps and wrong types are all rejected at load time, because a
+policy that fails open is worse than no policy.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+_ATOMIC_RE = re.compile(r"^\d+$")
+
+_FIELDS = {
+    "per_call_cap_atomic",
+    "session_budget_atomic",
+    "daily_budget_atomic",
+    "per_counterparty_cap_atomic",
+    "allowed_networks",
+    "allowed_assets",
+    "counterparty_allowlist",
+    "max_payments_per_window",
+    "window_seconds",
+    "replay_window_seconds",
+    "intent_required",
+    "asset_decimals",
+}
+
+
+class PolicyError(ValueError):
+    """Raised when a policy document is invalid. Always fail closed."""
+
+
+def _require_int(doc: dict, key: str, *, allow_none: bool = False) -> int | None:
+    if key not in doc:
+        raise PolicyError(f"policy missing required field: {key}")
+    v = doc[key]
+    if v is None and allow_none:
+        return None
+    # bool is a subclass of int; a JSON true is never a money amount.
+    if isinstance(v, bool) or not isinstance(v, int):
+        raise PolicyError(f"policy field {key} must be an integer (atomic units), got {type(v).__name__}")
+    return v
+
+
+def _require_str_list(doc: dict, key: str) -> list[str]:
+    if key not in doc:
+        raise PolicyError(f"policy missing required field: {key}")
+    v = doc[key]
+    if not isinstance(v, list) or not v or not all(isinstance(x, str) and x for x in v):
+        raise PolicyError(f"policy field {key} must be a non-empty list of strings")
+    return list(v)
+
+
+@dataclass(frozen=True)
+class PaymentPolicy:
+    per_call_cap_atomic: int
+    session_budget_atomic: int
+    daily_budget_atomic: int
+    allowed_networks: tuple[str, ...]
+    allowed_assets: tuple[str, ...]  # stored lowercased
+    counterparty_allowlist: tuple[str, ...]  # stored lowercased; "*" = any payee
+    per_counterparty_cap_atomic: int | None = None
+    max_payments_per_window: int = 30
+    window_seconds: int = 60
+    replay_window_seconds: int = 300
+    intent_required: bool = True
+    asset_decimals: int = 6
+
+    @classmethod
+    def from_dict(cls, doc: dict) -> "PaymentPolicy":
+        if not isinstance(doc, dict):
+            raise PolicyError("policy must be a JSON object")
+        unknown = set(doc) - _FIELDS
+        if unknown:
+            raise PolicyError(f"unknown policy fields: {sorted(unknown)}")
+        per_call = _require_int(doc, "per_call_cap_atomic")
+        session = _require_int(doc, "session_budget_atomic")
+        daily = _require_int(doc, "daily_budget_atomic")
+        per_cp = _require_int(doc, "per_counterparty_cap_atomic", allow_none=True) \
+            if "per_counterparty_cap_atomic" in doc else None
+        for name, val in (("per_call_cap_atomic", per_call),
+                          ("session_budget_atomic", session),
+                          ("daily_budget_atomic", daily),
+                          ("per_counterparty_cap_atomic", per_cp)):
+            if val is not None and val <= 0:
+                raise PolicyError(f"policy field {name} must be > 0")
+        # NOTE: no ordering is imposed between caps and budgets. A session
+        # budget smaller than the per-call cap is a legitimate configuration
+        # (the tighter limit simply binds at runtime); EXP-001 audit pass 1
+        # removed an earlier session>=cap / daily>=session rule that rejected
+        # such policies.
+        mpw = doc.get("max_payments_per_window", 30)
+        ws = doc.get("window_seconds", 60)
+        rws = doc.get("replay_window_seconds", 300)
+        for name, val in (("max_payments_per_window", mpw), ("window_seconds", ws),
+                          ("replay_window_seconds", rws)):
+            if isinstance(val, bool) or not isinstance(val, int) or val <= 0:
+                raise PolicyError(f"policy field {name} must be a positive integer")
+        intent_required = doc.get("intent_required", True)
+        if not isinstance(intent_required, bool):
+            raise PolicyError("policy field intent_required must be a boolean")
+        decimals = doc.get("asset_decimals", 6)
+        if isinstance(decimals, bool) or not isinstance(decimals, int) or not (0 <= decimals <= 36):
+            raise PolicyError("policy field asset_decimals must be an integer 0..36")
+        return cls(
+            per_call_cap_atomic=per_call,
+            session_budget_atomic=session,
+            daily_budget_atomic=daily,
+            per_counterparty_cap_atomic=per_cp,
+            allowed_networks=tuple(_require_str_list(doc, "allowed_networks")),
+            allowed_assets=tuple(a.lower() for a in _require_str_list(doc, "allowed_assets")),
+            counterparty_allowlist=tuple(
+                a if a == "*" else a.lower()
+                for a in _require_str_list(doc, "counterparty_allowlist")),
+            max_payments_per_window=mpw,
+            window_seconds=ws,
+            replay_window_seconds=rws,
+            intent_required=intent_required,
+            asset_decimals=decimals,
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> "PaymentPolicy":
+        try:
+            doc = json.loads(text)
+        except json.JSONDecodeError as e:
+            raise PolicyError(f"policy is not valid JSON: {e}") from e
+        return cls.from_dict(doc)
+
+    @classmethod
+    def from_file(cls, path: str) -> "PaymentPolicy":
+        with open(path, encoding="utf-8") as f:
+            return cls.from_json(f.read())
+
+    def network_allowed(self, network: str) -> bool:
+        for pat in self.allowed_networks:
+            if pat.endswith(":*"):
+                if network.startswith(pat[:-1]):
+                    return True
+            elif network == pat:
+                return True
+        return False
+
+    def asset_allowed(self, asset: str) -> bool:
+        return asset.lower() in self.allowed_assets
+
+    def counterparty_allowed(self, pay_to: str) -> bool:
+        return "*" in self.counterparty_allowlist or pay_to.lower() in self.counterparty_allowlist
+
+
+def parse_atomic_amount(raw: object) -> int | None:
+    """Parse an x402 atomic amount string. Returns None when malformed.
+
+    x402 amounts are integer strings in the asset's smallest unit. Anything
+    else (decimals, signs, exponents, whitespace tricks, non-strings) is
+    malformed and the gate fails closed on it.
+    """
+    if not isinstance(raw, str) or not _ATOMIC_RE.fullmatch(raw):
+        return None
+    return int(raw)
+
+
+def usd_money_string(atomic: int, decimals: int) -> str:
+    """Render an atomic cap as an x402 Money string like "$1.50" (for SpendControls)."""
+    scale = 10 ** decimals
+    whole, frac = divmod(atomic, scale)
+    if frac == 0:
+        return f"${whole}"
+    frac_s = str(frac).rjust(decimals, "0").rstrip("0")
+    return f"${whole}.{frac_s}"