askrobots / dbbasic-browser
Public
A desktop browser with x402 built in: when a page asks for payment, it pays in stablecoins and shows the content.
danq9
site icons (favicons) in tabs, address bar suggestions and the bookmarks panel
7249579
15 hours, 58 minutes ago
History
engine.ts · 5.9 KB · 165 lines
| 1 | /** |
| 2 | * The pay-and-retry orchestrator. |
| 3 | * |
| 4 | * Deliberately depends on nothing but `fetch`. The Electron `protocol.handle()` hook |
| 5 | * and the local proxy are both thin adapters over this, which means the payment path |
| 6 | * a user's browser takes is byte-for-byte the one the agent runtime takes, and both |
| 7 | * are testable headlessly with no browser at all. |
| 8 | */ |
| 9 | |
| 10 | import type { LocalAccount } from "viem"; |
| 11 | import { formatUsd } from "./assets.js"; |
| 12 | import { Ledger, type Receipt } from "./ledger.js"; |
| 13 | import { PolicyEngine, type PolicyContext, type Verdict } from "./policy.js"; |
| 14 | import { quoteFrom, signExactEvm } from "./schemes/exact-evm.js"; |
| 15 | import type { Quote } from "./types.js"; |
| 16 | import { encodePaymentSignature, parsePaymentRequired, parseSettlement } from "./wire.js"; |
| 17 | |
| 18 | export interface PromptRequest { |
| 19 | quote: Quote; |
| 20 | ctx: PolicyContext; |
| 21 | resourceUrl: string; |
| 22 | reason: string; |
| 23 | } |
| 24 | |
| 25 | /** Ask the human. Return true to pay once. The browser wires this to the URL-bar prompt. */ |
| 26 | export type Approver = (req: PromptRequest) => Promise<boolean>; |
| 27 | |
| 28 | export interface EngineOptions { |
| 29 | account: LocalAccount; |
| 30 | policy?: PolicyEngine; |
| 31 | ledger?: Ledger; |
| 32 | approve?: Approver; |
| 33 | fetchImpl?: typeof fetch; |
| 34 | onEvent?: (e: EngineEvent) => void; |
| 35 | } |
| 36 | |
| 37 | export type EngineEvent = |
| 38 | | { type: "quoted"; resourceUrl: string; quotes: Quote[]; rejected: string[] } |
| 39 | | { type: "decided"; resourceUrl: string; verdict: Verdict; quote: Quote } |
| 40 | | { type: "paid"; receipt: Receipt } |
| 41 | | { type: "skipped"; resourceUrl: string; reason: string }; |
| 42 | |
| 43 | export interface PayResult { |
| 44 | response: Response; |
| 45 | receipt?: Receipt; |
| 46 | /** Set when we saw an x402 challenge but chose not to (or could not) pay it. */ |
| 47 | declined?: string; |
| 48 | } |
| 49 | |
| 50 | export class X402Engine { |
| 51 | readonly policy: PolicyEngine; |
| 52 | readonly ledger: Ledger; |
| 53 | private readonly account: LocalAccount; |
| 54 | private readonly approve: Approver; |
| 55 | private readonly fetchImpl: typeof fetch; |
| 56 | private readonly onEvent: (e: EngineEvent) => void; |
| 57 | |
| 58 | constructor(opts: EngineOptions) { |
| 59 | this.account = opts.account; |
| 60 | this.policy = opts.policy ?? new PolicyEngine(); |
| 61 | this.ledger = opts.ledger ?? new Ledger(); |
| 62 | this.approve = opts.approve ?? (async () => false); |
| 63 | this.fetchImpl = opts.fetchImpl ?? fetch; |
| 64 | this.onEvent = opts.onEvent ?? (() => {}); |
| 65 | } |
| 66 | |
| 67 | /** |
| 68 | * Issue a request; if it comes back 402 with an x402 challenge, pay and retry once. |
| 69 | * Never retries more than once — a server that 402s the paid request is either |
| 70 | * broken or trying to bill twice, and neither deserves a second signature. |
| 71 | */ |
| 72 | async fetch(request: Request, topOrigin = ""): Promise<PayResult> { |
| 73 | const first = await this.fetchImpl(request.clone()); |
| 74 | if (first.status !== 402) return { response: first }; |
| 75 | |
| 76 | // A 402 body may be a v1 challenge, so we have to read it — but only if it's JSON, |
| 77 | // and we must not consume a body we might need to hand back to the caller. |
| 78 | const probe = first.clone(); |
| 79 | let body: unknown; |
| 80 | if (probe.headers.get("content-type")?.includes("json")) { |
| 81 | body = await probe.json().catch(() => undefined); |
| 82 | } |
| 83 | |
| 84 | const challenge = parsePaymentRequired(n => first.headers.get(n), body); |
| 85 | if (!challenge) return { response: first, declined: "402 without an x402 challenge" }; |
| 86 | |
| 87 | const resourceUrl = challenge.resource?.url ?? request.url; |
| 88 | const destOrigin = new URL(request.url).origin; |
| 89 | const ctx: PolicyContext = { topOrigin, destOrigin }; |
| 90 | |
| 91 | const { quotes, rejected } = quoteFrom(challenge); |
| 92 | this.onEvent({ type: "quoted", resourceUrl, quotes, rejected }); |
| 93 | |
| 94 | if (quotes.length === 0) { |
| 95 | const why = `no payable option (${rejected.join("; ") || "empty accepts[]"})`; |
| 96 | this.onEvent({ type: "skipped", resourceUrl, reason: why }); |
| 97 | return { response: first, declined: why }; |
| 98 | } |
| 99 | |
| 100 | // Cheapest wins. The server orders `accepts` in its own interest, not ours. |
| 101 | const quote = quotes.reduce((a, b) => (b.priceUsdMicro < a.priceUsdMicro ? b : a)); |
| 102 | |
| 103 | const verdict = this.policy.evaluate(quote, ctx); |
| 104 | this.onEvent({ type: "decided", resourceUrl, verdict, quote }); |
| 105 | |
| 106 | if (verdict.action === "deny") { |
| 107 | this.onEvent({ type: "skipped", resourceUrl, reason: verdict.reason }); |
| 108 | return { response: first, declined: verdict.reason }; |
| 109 | } |
| 110 | if (verdict.action === "prompt") { |
| 111 | const ok = await this.approve({ quote, ctx, resourceUrl, reason: verdict.reason }); |
| 112 | if (!ok) { |
| 113 | const why = `declined by user (${verdict.reason})`; |
| 114 | this.onEvent({ type: "skipped", resourceUrl, reason: why }); |
| 115 | return { response: first, declined: why }; |
| 116 | } |
| 117 | } |
| 118 | |
| 119 | const payload = await signExactEvm(this.account, quote, { |
| 120 | maxAuthorizationLifetimeSeconds: this.policy.limits.maxAuthorizationLifetimeSeconds, |
| 121 | }); |
| 122 | |
| 123 | // Record before sending: once the signature leaves us, the money is exposed |
| 124 | // regardless of what comes back. |
| 125 | const receipt = this.ledger.open({ |
| 126 | quote, |
| 127 | topOrigin, |
| 128 | destOrigin, |
| 129 | resourceUrl, |
| 130 | requestedUrl: request.url, |
| 131 | authorization: payload.payload.authorization, |
| 132 | signature: payload.payload.signature, |
| 133 | }); |
| 134 | this.policy.record(quote, ctx); |
| 135 | |
| 136 | const retry = new Request(request.clone(), { |
| 137 | headers: mergeHeaders(request.headers, encodePaymentSignature(payload)), |
| 138 | }); |
| 139 | |
| 140 | let paid: Response; |
| 141 | try { |
| 142 | paid = await this.fetchImpl(retry); |
| 143 | } catch (e) { |
| 144 | this.ledger.fail(receipt.id, `retry failed: ${String(e)}`); |
| 145 | throw e; |
| 146 | } |
| 147 | |
| 148 | const settlement = parseSettlement(n => paid.headers.get(n)); |
| 149 | this.ledger.settle(receipt.id, settlement, paid.ok); |
| 150 | this.onEvent({ type: "paid", receipt }); |
| 151 | |
| 152 | return { response: paid, receipt }; |
| 153 | } |
| 154 | |
| 155 | /** What the URL bar shows: total spent in the current window. */ |
| 156 | spentLabel(): string { |
| 157 | return formatUsd(this.policy.spentUsdMicro()); |
| 158 | } |
| 159 | } |
| 160 | |
| 161 | function mergeHeaders(base: Headers, extra: Record<string, string>): Headers { |
| 162 | const h = new Headers(base); |
| 163 | for (const [k, v] of Object.entries(extra)) h.set(k, v); |
| 164 | return h; |
| 165 | } |