Skip to content
Browsa
  1. Blog
  2. Open source

How we built a shopping agent that can't buy without your approval

Open Shopping Agent searches the stores, compares offers and fills the carts. Placing the order is the step that matters, so the model never decides it. An approval names one store and one total in cents, and three separate checks have to agree.

Browsa team7 min readOpen source

Open Shopping Agent (OSA) is an MIT-licensed agent that takes one request, like "usb-c hub with hdmi and a 6 ft hdmi cable under $60". It searches Amazon, Walmart, eBay, Best Buy, Target and Shopify stores, compares the offers and fills the carts. It can also place the order. That last step is the one that matters, and this post covers how we built it so it can't happen without you.

In short: the model never decides to pay. Approval is data, not a prompt. It names one store and one total in cents. Three separate places check it, and the last check reads the total from the store's page a moment before the click.

The excerpts below are from commit 7e4d689, trimmed. Each file link opens the cited lines.

The model never holds the trigger

OSA reads pages with plain code first: one adapter file per store. An AI model takes over only when a page changed and the code failed. Either way, the store adapter only reads pages and clicks. The engine ranks offers, applies limits and asks for approval. Only one line in the whole codebase calls an adapter's placeOrder(), and it sits behind the approval check in src/core/engine.ts:

src/core/engine.ts:777-794
async approve(store: StoreId, approval: Approval, domain?: string): Promise<OrderResult> {
  const review = shop ? this.reviews.get(shop.key) : undefined;
  const problem = approvalProblem({ store, review, approval, limits: this.limits,
    budget: this.budget, placed: this.placedTotal(), ordered: this.ordered });
  if (problem || !shop || !review) throw new LimitError("approval", `Order not placed: ${problem ?? "no store"}`);
  // Mark first so a second approve() for the same store cannot race this one.
  this.ordered.add(store === "shopify" ? `${store}:${shop.domain}` : store);
  result = await withTimeout(shop.adapter.placeOrder(shop.ctx, approval), ...);

The ordered.add comes before the await for a reason. Without it, two quick clicks on Approve, or a client that retries, could start two orders. Now the second call fails with "an order was already placed for this store in this run".

What an approval has to match

An Approval is a small object: store, approvedTotal in integer cents with a currency, a timestamp, and by: "user". The front ends build it from the review the person saw. approvalProblem() in src/core/limits.ts is a pure function, so it is easy to test exhaustively:

src/core/limits.ts:96-122
if (limits.requireApproval !== true) return "requireApproval must be true";
if (approval.store !== store) return `the approval is for ${approval.store}, not ${store}`;
if (!review) return "there is no checkout review for this store in this run; call reviewCheckout first";
if (review.needsUser) return `the store needs the person first: ${review.needsUser.message}`;
if (at.currency !== review.total.currency || at.cents !== review.total.cents)
  return `the approved total ${formatMoney(at)} does not match the review total ${formatMoney(review.total)}`;
if (review.total.cents <= 0) return "the review total is zero; refusing to place an order that cannot be checked";
if (now.getTime() - reviewed > (c.maxReviewAgeMs ?? 20 * 60_000)) return "the review is too old; review the checkout again";
if (!Number.isFinite(approvedAt) || approvedAt + 5_000 < reviewed) return "the approval was given before this review";
const bad = forbiddenLines(review.lines);
if (bad.length) return `the checkout has a ${bad[0].why} line: ${bad[0].line.title}`;

A few of these rules came from real store behaviour:

  • Exact match, not "at most". A lower total also fails. If the total moved, something on the page changed that you didn't see, such as a different seller, a dropped item or a new shipping option. The safe answer is to show the review again.
  • Reviews expire after 20 minutes. Prices and stock change, and an approval from an old tab shouldn't carry over.
  • Membership and subscription lines block the order. Stores add "subscribe and save", Prime or Walmart+ trials to carts. The agent picks one-time purchase. If one of those lines still shows up at checkout, the order can't be approved at all.
  • A zero total is refused. If the adapter misread the page, $0.00 would otherwise "match".

Before the engine runs its check, the run hub that the web app, CLI and MCP all go through compares the total the person approved with the pending review (src/web/session.ts:188-193). So that check happens twice before any browser code runs.

Read the total again, on the store

The engine's check uses the review it captured earlier. Between that review and your click, the store page is still live. So every adapter's placeOrder() starts by reading the checkout again. Walmart's, from src/stores/walmart.ts:

src/stores/walmart.ts:517-526
async placeOrder(ctx, approval) {
  if (approval.store !== "walmart") throw new Error("approval is for another store");
  const review = await walmartCheckoutReview(ctx);
  if (review.needsUser) return { store: "walmart", placed: false, needsUser: review.needsUser };
  if (!approvalMatches(review.total, approval)) {
    return { store: "walmart", placed: false, total: review.total,
      error: `Walmart total is now ${formatMoney(review.total)}, approved ${formatMoney(approval.approvedTotal)}; order not placed` };
  }
  const clicked = await clickFirstVisible(page, ["[data-automation-id=\"place-order-button\"]", ...], 15_000);

approvalMatches (src/stores/util.ts:549) compares currency and cents exactly. The adapter contract (src/stores/adapter.ts:86-90) says a changed total returns { placed: false, error } and must not throw. The engine turns a throw into the same result anyway, so a bug in one adapter can't turn into "click and hope".

Why it never types card data

The agent stops at the store's checkout. Your saved card (shown as the store's own hint, like "Visa ending 1234") or your own typing does the rest. Sign-in, one-time codes and 3-D Secure are handed to you in the live browser. We chose this for two reasons. A card number in an agent's context can end up in logs, model providers and screenshots. And if the agent never has the number, it can't leak it.

The adapters have no code that fills payment or password fields. The AI fallback that runs on your own browser has a code-level guard on top of its prompt, in src/core/providers/agent-loop.ts:

src/core/providers/agent-loop.ts:38-39, 148-152
const FORBIDDEN = /place (your )?order|pay now|^pay\b|buy now|complete (order|purchase)|submit order|confirm (order|purchase)|sign ?in|log ?in|start (free )?trial|join prime|subscribe/i;
const CARD_FIELD = /card number|cvv|cvc|security code|expir/i;
...
if (FORBIDDEN.test(label)) throw new Error("refused: the agent never places orders, pays or signs in");
if (CARD_FIELD.test(a.name ?? "")) throw new Error("refused: the agent never types card details");

A regex on accessible names is a backstop, not a guarantee. The real guarantee is structural: the fallback has no route to placeOrder().

MCP: placing orders is off by default

Over MCP, an AI client drives the agent. The place_order tool description says "ALWAYS ask the human first". That sentence only asks the model to behave; nothing enforces it. The agent reads untrusted store pages, and any of them could contain text written to steer a model. So the tool is off unless the person who set up the server opts in, in src/mcp/server.ts:

src/mcp/server.ts:16-19
export function mcpOrdersAllowed(env: NodeJS.ProcessEnv = process.env): boolean {
  return /^(1|true|on|yes)$/i.test((env.OSA_MCP_ALLOW_ORDERS ?? "").trim());
}

Without the flag, Claude or Cursor can search, compare, fill carts and show you the checkout review. The order is finished in the web app or the CLI. With the flag on, approved_total still has to match the review to the cent, and the adapter still re-reads the total.

DNS rebinding on the local web app

npx open-shopping-agent web serves a local app on port 4319 with no login. It listens on 127.0.0.1, which feels safe, but it isn't enough. A malicious site can point its own hostname at 127.0.0.1 (DNS rebinding). The browser then treats requests to your agent as same-origin requests to that site. Approve is one of those requests.

The fix is to check the Host header. A rebinding page still sends its own name, as src/web/server.ts shows:

src/web/server.ts:283-287, 329-333
// Without a token the server trusts this machine only. A page on another site that points its own
// name at 127.0.0.1 (DNS rebinding) sends its own Host, so anything but a loopback name is refused.
if (!opts.token && !loopbackHostHeader(req.headers.host)) {
  return send(res, 403, ...);
}
export function loopbackHostHeader(host: string | undefined): boolean {
  if (!host) return false;
  const name = host.startsWith("[") ? host.slice(1, host.indexOf("]")) : host.replace(/:\d+$/, "");
  return isLoopback(name.toLowerCase());
}

On any non-loopback address (Docker, for example), the server generates a random token at start. It requires the token as an HttpOnly; SameSite=Strict cookie or a bearer header. Requests that change state are also refused when their Origin doesn't match the Host.

Lessons

  • Write money rules as pure functions over data. approvalProblem() has no I/O, so every rule has a test, and the error strings are what the user reads.
  • Let the code that clicks decide nothing. Adapters read pages and click; the engine decides. Contributors adding a store can't accidentally write one that buys.
  • An instruction to a model is not a control. Anything that spends money over MCP should be off until a human turns it on outside the chat.
  • "Localhost only" needs a Host check.

Limits

  • No real order has gone through it end to end yet. Every run, bench task and test stops before buying. The click path has been tested against fakes and saved pages (344 tests, offline), not against a real purchase.
  • Hosted fallback. On Browsa's hosted AI fallback, the "never pay, never type card details" rule lives in the task instructions (src/core/browsers.ts:806), not in a code guard like the local loop's. It still can't reach placeOrder(), because that function is only called from the engine.
  • US stores only. Store pages change, so adapters break. A bench in the repo records search, cart and checkout per store so we notice.
  • Stores block automated browsers. On your own Chrome you solve those checks in the window. For stores that block outright, OSA can run each store in a Browsa cloud browser instead. That's optional, and everything above works the same either way.
  • Store terms. It runs as you, in your browser, for your own purchases, and every order needs your approval. Captcha solving only happens on the optional cloud browsers, and you can turn it off.

Run it

The code is at github.com/browsa-io/open-shopping-agent. It needs Node 20 or later:

Terminal
npx open-shopping-agent web

Issues and adapter PRs are welcome.

Try it

Start free with 100 credits. No card.