agentcart 0.1.0__py3-none-any.whl

agentcart/__init__.py

@@ -0,0 +1,3 @@
+"""agentcart: security-first agentic checkout over MCP."""
+
+__version__ = "0.1.0"

agentcart/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agentcart/adapters/__init__.py

@@ -0,0 +1,33 @@
+"""Adapter registry. Adding a store = adding one module here (see docs/ADAPTERS.md)."""
+
+from __future__ import annotations
+
+from ..errors import CheckoutError
+from ..netsafe import dev_loopback_enabled, host_matches, registrable_host
+from .base import SiteAdapter
+from .demo import DemoShopAdapter
+
+
+def all_adapters() -> list[SiteAdapter]:
+    adapters: list[SiteAdapter] = []
+    if dev_loopback_enabled():
+        adapters.append(DemoShopAdapter())
+    return adapters
+
+
+def for_url(url: str) -> SiteAdapter:
+    host = registrable_host(url)
+    for a in all_adapters():
+        if any(host_matches(host, d) for d in a.domains):
+            return a
+    supported = ", ".join(d for a in all_adapters() for d in a.domains) or "none yet"
+    raise CheckoutError(
+        f"no checkout adapter for '{host}' yet (supported: {supported}). "
+        "fetch_product still works on any site; contributions welcome, see docs/ADAPTERS.md")
+
+
+def by_name(name: str) -> SiteAdapter:
+    for a in all_adapters():
+        if a.name == name:
+            return a
+    raise CheckoutError(f"unknown site '{name}'")

agentcart/adapters/base.py

@@ -0,0 +1,95 @@
+"""Site adapter contract. One adapter per store; see docs/ADAPTERS.md."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass, field
+from decimal import Decimal
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from playwright.async_api import Page
+
+from ..errors import CheckoutError
+
+
+@dataclass
+class LineItem:
+    name: str
+    quantity: int
+    unit_price: Decimal
+
+
+@dataclass
+class Quote:
+    items: list[LineItem]
+    subtotal: Decimal
+    shipping: Decimal
+    total: Decimal
+    currency: str
+    deliver_to: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+    def to_public(self) -> dict[str, Any]:
+        d = asdict(self)
+        for k in ("subtotal", "shipping", "total"):
+            d[k] = str(d[k])
+        for it in d["items"]:
+            it["unit_price"] = str(it["unit_price"])
+        return d
+
+
+@dataclass
+class UpiIntent:
+    payee_vpa: str
+    payee_name: str | None
+    amount: Decimal | None
+    currency: str | None
+    raw: str
+
+
+def parse_upi_intent(uri: str) -> UpiIntent:
+    parts = urlsplit(uri)
+    if parts.scheme != "upi" or parts.netloc.lower() != "pay":
+        raise CheckoutError("payment link is not a upi://pay intent")
+    q = {k: v[0] for k, v in parse_qs(parts.query).items()}
+    if "pa" not in q or "@" not in q["pa"]:
+        raise CheckoutError("UPI intent has no valid payee address")
+    amt = Decimal(q["am"]).quantize(Decimal("0.01")) if q.get("am") else None
+    return UpiIntent(q["pa"], q.get("pn"), amt, q.get("cu"), uri)
+
+
+@dataclass
+class OrderResult:
+    order_id: str | None
+    status: str
+    total: Decimal | None
+
+
+class SiteAdapter(ABC):
+    #: short id used for profiles and CLI ('agentcart login <name>')
+    name: str
+    #: domains this adapter handles (bare, no www.)
+    domains: tuple[str, ...]
+    #: True only if the adapter implements pay_with_balance against a pre-funded store balance
+    supports_autopay: bool = False
+
+    @abstractmethod
+    async def prepare_checkout(self, page: Page, product_url: str, quantity: int) -> Quote:
+        """Add the product to cart and stop on the payment-method page. Never pays."""
+
+    async def select_upi(self, page: Page, quote: Quote) -> UpiIntent | None:
+        """Choose UPI as the payment method and return the upi:// intent if the page exposes one.
+
+        Returning None is fine: the user pays in the visible browser window instead.
+        """
+        return None
+
+    async def pay_with_balance(self, page: Page, quote: Quote) -> OrderResult:
+        raise CheckoutError(f"{self.name} does not support auto-pay")
+
+    async def order_status(self, page: Page) -> OrderResult:
+        raise CheckoutError(f"{self.name} cannot report order status yet")
+
+    async def login_url(self) -> str:
+        return f"https://{self.domains[0]}/"

agentcart/adapters/demo.py

@@ -0,0 +1,73 @@
+"""Adapter for the bundled demo shop (loopback only). Also the reference implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from urllib.parse import urlsplit
+
+from playwright.async_api import Page
+
+from ..errors import CheckoutError
+from ..sanitize import clean_text, parse_money
+from .base import LineItem, OrderResult, Quote, SiteAdapter, UpiIntent, parse_upi_intent
+
+
+async def _money(page: Page, testid: str) -> Decimal:
+    v = parse_money(await page.get_by_test_id(testid).inner_text())
+    if v is None:
+        raise CheckoutError(f"could not read '{testid}' amount from the page")
+    return v
+
+
+class DemoShopAdapter(SiteAdapter):
+    name = "demo"
+    domains = ("127.0.0.1", "localhost")
+    supports_autopay = True
+
+    async def prepare_checkout(self, page: Page, product_url: str, quantity: int) -> Quote:
+        await page.goto(product_url)
+        await page.get_by_test_id("qty").fill(str(quantity))
+        await page.get_by_test_id("add-to-cart").click()
+        await page.wait_for_url("**/checkout")
+        qty = int(await page.get_by_test_id("item-qty").inner_text())
+        if qty != quantity:
+            raise CheckoutError(f"cart has quantity {qty}, expected {quantity}")
+        quote = Quote(
+            items=[LineItem(clean_text(await page.get_by_test_id("item-name").inner_text(), 200) or "?",
+                            qty, await _money(page, "item-price"))],
+            subtotal=await _money(page, "subtotal"),
+            shipping=await _money(page, "shipping"),
+            total=await _money(page, "total"),
+            currency="INR",
+            deliver_to=clean_text(await page.get_by_test_id("address").inner_text(), 200),
+        )
+        await page.get_by_test_id("to-payment").click()
+        await page.wait_for_url("**/payment")
+        due = await _money(page, "due")
+        if due != quote.total:
+            raise CheckoutError(f"payment page amount ₹{due} differs from cart total ₹{quote.total}")
+        return quote
+
+    async def select_upi(self, page: Page, quote: Quote) -> UpiIntent | None:
+        await page.get_by_test_id("method-upi").check()
+        href = await page.get_by_test_id("upi-intent").get_attribute("href")
+        return parse_upi_intent(href) if href else None
+
+    async def pay_with_balance(self, page: Page, quote: Quote) -> OrderResult:
+        if await _money(page, "due") != quote.total:
+            raise CheckoutError("amount changed before payment; aborted")
+        await page.get_by_test_id("pay-balance").click()
+        await page.wait_for_load_state()
+        return await self.order_status(page)
+
+    async def order_status(self, page: Page) -> OrderResult:
+        if "/order/" not in urlsplit(page.url).path:
+            if await page.get_by_test_id("error").count():
+                return OrderResult(None, "FAILED: " + (await page.get_by_test_id("error").inner_text()),
+                                   None)
+            return OrderResult(None, "PENDING", None)
+        return OrderResult(
+            clean_text(await page.get_by_test_id("order-id").inner_text(), 40),
+            clean_text(await page.get_by_test_id("order-status").inner_text(), 40) or "UNKNOWN",
+            await _money(page, "order-total"),
+        )

agentcart/audit.py

@@ -0,0 +1,106 @@
+"""Append-only, hash-chained audit log of every money-related action.
+
+Each line is JSON: {"seq", "ts", "event", "data", "prev", "hash"} where
+hash = sha256(prev || canonical_json(seq, ts, event, data)). The first entry's prev is the vault's
+random genesis value. Any edit, reordering or deletion in the middle breaks the chain; on a broken
+chain auto-pay fails closed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import sys
+from collections.abc import Iterator
+from datetime import UTC, datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from . import paths
+from .errors import TamperError
+
+
+def _canon(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str).encode()
+
+
+@contextlib.contextmanager
+def _locked(path: Path) -> Iterator[None]:
+    lock = path.with_suffix(".lock")
+    fd = os.open(lock, os.O_RDWR | os.O_CREAT | paths.O_BINARY, 0o600)
+    try:
+        if sys.platform == "win32":  # pragma: no cover
+            import msvcrt
+
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            yield  # released on close
+    finally:
+        os.close(fd)
+
+
+def read_verified(genesis: str, path: Path | None = None) -> list[dict[str, Any]]:
+    path = path or paths.audit_file()
+    if not path.exists():
+        return []
+    entries: list[dict[str, Any]] = []
+    prev = genesis
+    for n, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            e = json.loads(line)
+        except ValueError as err:
+            raise TamperError(f"audit log line {n} is not valid JSON") from err
+        body = {k: e.get(k) for k in ("seq", "ts", "event", "data")}
+        expect = hashlib.sha256(prev.encode() + _canon(body)).hexdigest()
+        if e.get("prev") != prev or e.get("hash") != expect or e.get("seq") != len(entries):
+            raise TamperError(f"audit log chain broken at line {n}")
+        entries.append(e)
+        prev = e["hash"]
+    return entries
+
+
+def append(genesis: str, event: str, data: dict[str, Any], path: Path | None = None) -> dict[str, Any]:
+    path = path or paths.audit_file()
+    with _locked(path):
+        entries = read_verified(genesis, path)
+        prev = entries[-1]["hash"] if entries else genesis
+        body = {"seq": len(entries), "ts": datetime.now(UTC).isoformat(), "event": event,
+                "data": json.loads(_canon(data))}
+        entry = {**body, "prev": prev, "hash": hashlib.sha256(prev.encode() + _canon(body)).hexdigest()}
+        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | paths.O_BINARY, 0o600)
+        try:
+            os.write(fd, _canon(entry) + b"\n")
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        return entry
+
+
+def autopay_spend(entries: list[dict[str, Any]], now: datetime | None = None) -> tuple[Decimal, int]:
+    """Return (INR spent via auto-pay this calendar month, auto-pay orders in the last 24h)."""
+    now = now or datetime.now(UTC)
+    month_total, day_count = Decimal("0"), 0
+    for e in entries:
+        if e["event"] not in ("autopay_attempt",):
+            continue
+        ts = datetime.fromisoformat(e["ts"])
+        amount = Decimal(str(e["data"]["amount"]))
+        if (ts.year, ts.month) == (now.year, now.month):
+            month_total += amount
+        if (now - ts).total_seconds() < 86400:
+            day_count += 1
+    return month_total, day_count

agentcart/browser.py

@@ -0,0 +1,139 @@
+"""Hardened Playwright browser sessions.
+
+* one persistent profile per site, stored on-device (0700) -- you log in once yourself with
+  'agentcart login <site>'; agentcart never sees or stores your password
+* headed (visible) by default so you can always watch what the agent does
+* main-frame navigations outside the adapter's own domains (plus known payment gateways) are blocked
+* downloads, geolocation, camera, mic, notifications and clipboard are denied
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import os
+import sys
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+from playwright.async_api import BrowserContext, Page, Playwright, Route, async_playwright
+
+from . import paths
+from .netsafe import dev_loopback_enabled, host_matches
+
+# Hosted payment pages Indian merchants commonly redirect to. Navigation to these is allowed.
+PAYMENT_GATEWAYS = (
+    "razorpay.com", "payu.in", "payumoney.com", "cashfree.com", "ccavenue.com", "paytm.in",
+    "paytm.com", "phonepe.com", "juspay.in", "billdesk.com", "stripe.com", "easebuzz.in",
+)
+
+
+def _executable() -> str | None:
+    explicit = os.environ.get("AGENTCART_CHROMIUM")
+    if explicit:
+        return explicit
+    return None
+
+
+_MISSING_BROWSER = "Executable doesn't exist"
+
+
+async def _install_chromium() -> None:
+    """One-time download of Playwright's Chromium (fixed command, no user-controlled input)."""
+    print("agentcart: first run, downloading Chromium (one time, ~150 MB)...", file=sys.stderr)
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable, "-m", "playwright", "install", "chromium",
+        stdout=sys.stderr, stderr=sys.stderr,
+    )
+    if await proc.wait() != 0:
+        raise RuntimeError("Chromium download failed; run 'uvx playwright install chromium' manually")
+
+
+@dataclass
+class Session:
+    context: BrowserContext
+    page: Page
+
+
+class BrowserManager:
+    def __init__(self) -> None:
+        self._pw: Playwright | None = None
+
+    async def _playwright(self) -> Playwright:
+        if self._pw is None:
+            self._pw = await async_playwright().start()
+        return self._pw
+
+    async def open(self, site: str, domains: tuple[str, ...], headless: bool | None = None) -> Session:
+        pw = await self._playwright()
+        if headless is None:
+            headless = os.environ.get("AGENTCART_HEADLESS") == "1"
+        profile = paths.ensure_private_dir(paths.profiles_dir() / site)
+        kwargs: dict[str, Any] = {
+            "headless": headless,
+            "accept_downloads": False,
+            "permissions": [],
+            "service_workers": "block",
+            "locale": "en-IN",
+            "timezone_id": "Asia/Kolkata",
+        }
+        exe = _executable()
+        if exe:
+            kwargs["executable_path"] = exe
+        try:
+            ctx = await pw.chromium.launch_persistent_context(str(profile), **kwargs)
+        except Exception as e:
+            if exe or _MISSING_BROWSER not in str(e):
+                raise
+            await _install_chromium()
+            ctx = await pw.chromium.launch_persistent_context(str(profile), **kwargs)
+        allowed = tuple(domains) + PAYMENT_GATEWAYS
+
+        async def guard(route: Route) -> None:
+            req = route.request
+            if req.is_navigation_request():
+                main = req.frame.parent_frame is None
+                # Top-level page: only the store + payment gateways. Iframes (captcha, 3-D Secure,
+                # gateway widgets) may be any https origin, never plain http or private hosts.
+                ok = (_navigation_allowed(req.url, allowed) if main
+                      else _navigation_allowed(req.url, None))
+                if not ok:
+                    await route.abort("blockedbyclient")
+                    return
+            await route.continue_()
+
+        await ctx.route("**/*", guard)
+        page = ctx.pages[0] if ctx.pages else await ctx.new_page()
+        page.set_default_timeout(20_000)
+        return Session(ctx, page)
+
+    async def close(self) -> None:
+        if self._pw is not None:
+            await self._pw.stop()
+            self._pw = None
+
+
+def _navigation_allowed(url: str, allowed: tuple[str, ...] | None) -> bool:
+    """allowed=None means 'any public https origin' (used for iframes)."""
+    parts = urlsplit(url)
+    if parts.scheme in ("about", "data") and url.startswith(("about:blank", "data:text/html")):
+        return url == "about:blank"
+    host = (parts.hostname or "").lower()
+    if dev_loopback_enabled():
+        try:
+            if ipaddress.ip_address(host).is_loopback:
+                return parts.scheme in ("http", "https")
+        except ValueError:
+            if host == "localhost":
+                return True
+    if parts.scheme != "https" or _is_private_literal(host) or host == "localhost":
+        return False
+    return allowed is None or any(host_matches(host, d) for d in allowed)
+
+
+def _is_private_literal(host: str) -> bool:
+    try:
+        return not ipaddress.ip_address(host.strip("[]")).is_global
+    except ValueError:
+        return False

agentcart/checkout.py

@@ -0,0 +1,194 @@
+"""Checkout orchestration shared by the MCP server and the CLI. All security decisions live here."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import secrets
+import time
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any
+
+import segno
+
+from . import audit, paths, policy, vault
+from .adapters import for_url
+from .adapters.base import OrderResult, Quote, SiteAdapter, UpiIntent
+from .browser import BrowserManager, Session
+from .errors import AgentCartError, CheckoutError, PolicyViolation
+from .extract import Product, extract_product
+from .netsafe import fetch_html, registrable_host, validate_url_syntax
+from .sanitize import UNTRUSTED_NOTE
+
+MAX_SESSIONS = 3
+SESSION_TTL_S = 20 * 60
+MAX_QTY = 10
+
+
+async def fetch_product(url: str) -> dict[str, Any]:
+    res = await fetch_html(url)
+    product = extract_product(res.text, res.final_url)
+    return {"source_url": res.final_url, "note": UNTRUSTED_NOTE, "untrusted": product.to_public(),
+            "found": bool(product.name or product.price)}
+
+
+@dataclass
+class Checkout:
+    id: str
+    adapter: SiteAdapter
+    session: Session
+    host: str
+    product_url: str
+    quote: Quote
+    listed_price: Decimal | None
+    upi: UpiIntent | None
+    created: float = field(default_factory=time.monotonic)
+    state: str = "awaiting_payment"
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+
+def _audit(event: str, data: dict[str, Any]) -> None:
+    """Best-effort log when no vault exists yet (Flow 1 works without a vault); strict otherwise."""
+    if not vault.exists():
+        return
+    pol = policy.load()
+    if pol.genesis:
+        audit.append(pol.genesis, event, data)
+
+
+class CheckoutManager:
+    def __init__(self) -> None:
+        self.browser = BrowserManager()
+        self.checkouts: dict[str, Checkout] = {}
+
+    async def _reap(self) -> None:
+        now = time.monotonic()
+        for cid, c in list(self.checkouts.items()):
+            if now - c.created > SESSION_TTL_S and c.state != "paying":
+                await self._close(cid)
+
+    async def _close(self, cid: str) -> None:
+        c = self.checkouts.pop(cid, None)
+        if c:
+            with contextlib.suppress(Exception):  # closing a dead browser is fine
+                await c.session.context.close()
+
+    def _get(self, cid: str) -> Checkout:
+        c = self.checkouts.get(cid)
+        if not c:
+            raise CheckoutError("unknown or expired checkout_id; start a new checkout")
+        return c
+
+    async def start(self, url: str, quantity: int) -> dict[str, Any]:
+        validate_url_syntax(url)
+        if not 1 <= quantity <= MAX_QTY:
+            raise CheckoutError(f"quantity must be between 1 and {MAX_QTY}")
+        await self._reap()
+        if len(self.checkouts) >= MAX_SESSIONS:
+            raise CheckoutError("too many open checkouts; cancel one first")
+        adapter = for_url(url)
+        listed: Product | None = None
+        try:
+            res = await fetch_html(url)
+            listed = extract_product(res.text, res.final_url)
+        except AgentCartError:
+            listed = None
+        if any(c.adapter.name == adapter.name for c in self.checkouts.values()):
+            raise CheckoutError(f"a checkout on {adapter.name} is already open; finish or cancel it")
+        session = await self.browser.open(adapter.name, adapter.domains)
+        try:
+            quote = await adapter.prepare_checkout(session.page, url, quantity)
+            upi = await adapter.select_upi(session.page, quote)
+        except Exception:
+            await session.context.close()
+            raise
+        warnings: list[str] = []
+        listed_price = listed.price if listed else None
+        if listed_price is not None and quote.items and quote.items[0].unit_price > listed_price:
+            warnings.append(f"cart price ₹{quote.items[0].unit_price} is higher than listed ₹{listed_price}")
+        if upi:
+            if upi.amount != quote.total:
+                warnings.append(f"UPI request amount {upi.amount} does not match total {quote.total} — "
+                                "do NOT pay")
+            if (upi.currency or "INR") != "INR":
+                warnings.append("UPI request is not in INR — do NOT pay")
+        cid = "co_" + secrets.token_urlsafe(9)
+        self.checkouts[cid] = Checkout(cid, adapter, session, registrable_host(url), url, quote,
+                                       listed_price, upi)
+        _audit("checkout_started", {"id": cid, "site": adapter.name, "total": str(quote.total)})
+        out: dict[str, Any] = {
+            "checkout_id": cid,
+            "site": adapter.name,
+            "quote": quote.to_public(),
+            "warnings": warnings,
+            "how_to_pay": (
+                "Flow 1 (default): the browser window is open on the payment page. Scan the UPI QR "
+                "there (or the QR below) with your UPI app, CHECK the payee name and amount, and "
+                "enter your UPI PIN on your phone. agentcart never sees your PIN."),
+            "autopay_available": adapter.supports_autopay,
+        }
+        if upi:
+            qr_path = paths.ensure_private_dir(paths.home() / "qr") / f"{cid}.png"
+            qr = segno.make(upi.raw, error="m")
+            qr.save(str(qr_path), scale=8)
+            out["upi"] = {"payee_vpa": upi.payee_vpa, "payee_name": upi.payee_name,
+                          "amount": str(upi.amount) if upi.amount is not None else None,
+                          "qr_png": str(qr_path)}
+        return out
+
+    async def autopay(self, cid: str) -> dict[str, Any]:
+        """Flow 2. Every rule is enforced here; any failure falls back to Flow 1."""
+        c = self._get(cid)
+        async with c.lock:
+            if c.state != "awaiting_payment":
+                raise CheckoutError(f"checkout is '{c.state}', cannot pay again")
+            if not c.adapter.supports_autopay:
+                raise PolicyViolation(f"{c.adapter.name} does not support auto-pay; pay with UPI instead")
+            pol = policy.load()  # verifies signature; TamperError fails closed
+            listed_total = (c.listed_price * sum(i.quantity for i in c.quote.items) + c.quote.shipping
+                            if c.listed_price is not None else Decimal(0))
+            d = policy.evaluate_autopay(pol, c.host, c.quote.total, c.quote.currency, listed_total)
+            if not d.allowed:
+                if pol.genesis:
+                    audit.append(pol.genesis, "autopay_denied",
+                                 {"id": cid, "amount": str(c.quote.total), "reasons": d.reasons})
+                raise PolicyViolation("auto-pay blocked: " + "; ".join(d.reasons) +
+                                      ". You can still pay manually with UPI (Flow 1).")
+            # Log BEFORE paying so a crash mid-payment still counts against the caps.
+            audit.append(pol.genesis, "autopay_attempt", {"id": cid, "site": c.adapter.name,
+                                                          "amount": str(c.quote.total)})
+            c.state = "paying"
+            try:
+                result: OrderResult = await c.adapter.pay_with_balance(c.session.page, c.quote)
+            except Exception as e:
+                c.state = "unknown"
+                audit.append(pol.genesis, "autopay_error", {"id": cid, "error": type(e).__name__})
+                raise CheckoutError("payment step failed; check the browser window and your store "
+                                    "account before retrying") from e
+            c.state = "paid" if result.order_id else "unknown"
+            audit.append(pol.genesis, "autopay_result", {"id": cid, "order_id": result.order_id,
+                                                         "status": result.status})
+            return {"checkout_id": cid, "order_id": result.order_id, "status": result.status,
+                    "paid_inr": str(result.total) if result.total is not None else None}
+
+    async def status(self, cid: str) -> dict[str, Any]:
+        c = self._get(cid)
+        r = await c.adapter.order_status(c.session.page)
+        if r.order_id and c.state == "awaiting_payment":
+            c.state = "paid"
+            _audit("manual_payment_confirmed", {"id": cid, "order_id": r.order_id})
+        return {"checkout_id": cid, "state": c.state, "order_id": r.order_id, "status": r.status}
+
+    async def cancel(self, cid: str) -> dict[str, Any]:
+        c = self._get(cid)
+        if c.state == "paying":
+            raise CheckoutError("payment in progress; cannot cancel now")
+        await self._close(cid)
+        _audit("checkout_cancelled", {"id": cid})
+        return {"checkout_id": cid, "state": "cancelled"}
+
+    async def shutdown(self) -> None:
+        for cid in list(self.checkouts):
+            await self._close(cid)
+        await self.browser.close()