@pooriaarab/foxpay 0.0.0-stage → 0.1.0

package/dist/card.js

@@ -0,0 +1,241 @@
+// Card fill: read the checkout total from the merchant page, then fill a
+// card from foxvault into the top document and submit, after approval
+// (docs/failure-modes.md C1-C10).
+import { matchesPattern, normalizeHost, parsePattern } from "foxgate";
+import { PayRefusal } from "./intent.js";
+// The page functions below run in the merchant page through
+// scripting.executeScript. Firefox sends them as source text, so each one
+// must not use anything from outside its own body.
+export function readTotal(selector, host) {
+    if (location.hostname !== host)
+        return null;
+    return document.querySelector(selector)?.textContent ?? null;
+}
+export function fillDetails(expSelector, cvcSelector, exp, cvc, host) {
+    if (location.hostname !== host)
+        return "host-changed";
+    const exp1 = document.querySelector(expSelector);
+    const cvc1 = document.querySelector(cvcSelector);
+    if (!(exp1 instanceof HTMLInputElement) || !(cvc1 instanceof HTMLInputElement))
+        return "not-found";
+    for (const [field, value] of [[exp1, exp], [cvc1, cvc]]) {
+        field.focus();
+        field.value = value;
+        field.dispatchEvent(new Event("input", { bubbles: true }));
+        field.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    return "filled";
+}
+export function submitCheckout(submitSelector, totalSelector, totalText, host) {
+    if (location.hostname !== host)
+        return "host-changed";
+    if ((document.querySelector(totalSelector)?.textContent ?? null) !== totalText)
+        return "amount-changed";
+    const button = document.querySelector(submitSelector);
+    if (!(button instanceof HTMLElement))
+        return "not-found";
+    button.click();
+    return "submitted";
+}
+export function clearFields(selectors, host) {
+    if (location.hostname !== host)
+        return "host-changed";
+    for (const selector of selectors) {
+        const field = document.querySelector(selector);
+        if (!(field instanceof HTMLInputElement))
+            continue;
+        field.value = "";
+        field.dispatchEvent(new Event("input", { bubbles: true }));
+        field.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    return "cleared";
+}
+/** Whole minor units from a total such as `Total $26.00`, or undefined when the text has not exactly one amount. */
+export function parseTotal(text, decimals = 2) {
+    const found = (text ?? "").match(/\d[\d,]*(?:\.\d+)?/g);
+    if (!found || found.length !== 1)
+        return undefined;
+    const [whole = "", frac = ""] = found[0].replace(/,/g, "").split(".");
+    if (frac.length > decimals)
+        return undefined;
+    const value = Number(whole) * 10 ** decimals + Number(frac.padEnd(decimals, "0") || "0");
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+const allows = (domains, host) => domains.some((d) => {
+    try {
+        return matchesPattern(host, parsePattern(d));
+    }
+    catch {
+        return false;
+    }
+});
+export function cardFill(options) {
+    const { vault, browser, card, provider, fields, currency } = options;
+    if (!card === !provider)
+        throw new TypeError("cardFill needs exactly one of card and provider.");
+    const decimals = options.decimals ?? 2;
+    const waitMs = options.waitMs ?? 10_000;
+    // The top document of the tab, when it is the merchant page.
+    async function topPage(tabId, merchant) {
+        const frame = await browser.webNavigation.getFrame({ tabId, frameId: 0 }).catch(() => undefined);
+        if (!frame)
+            throw new PayRefusal("no-tab", "The tab is not there.");
+        let url;
+        try {
+            url = new URL(frame.url);
+        }
+        catch {
+            throw new PayRefusal("merchant-mismatch", "The tab does not show a web page.");
+        }
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && options.allowHttp))
+            throw new PayRefusal(url.protocol === "http:" ? "http" : "merchant-mismatch", "The checkout page must use https.");
+        // URL gives the punycode host, so a Unicode look-alike is a different host (C2).
+        if (normalizeHost(url.hostname) !== merchant)
+            throw new PayRefusal("merchant-mismatch", `The tab shows ${url.hostname}, not ${merchant}.`);
+        if (!frame.documentId)
+            throw new PayRefusal("page-changed", "The tab has no document id.");
+        return { url: url.href, host: url.hostname, documentId: frame.documentId };
+    }
+    const run = async (tabId, documentId, func, args) => {
+        try {
+            return (await browser.scripting.executeScript({ target: { tabId, documentIds: [documentId] }, func, args }))[0]?.result;
+        }
+        catch {
+            throw new PayRefusal("page-changed", "The checkout page changed.");
+        }
+    };
+    const total = async (tabId, page) => {
+        const text = await run(tabId, page.documentId, readTotal, [options.total, page.host]);
+        const value = parseTotal(typeof text === "string" ? text : null, decimals);
+        if (value === undefined)
+            throw new PayRefusal("no-total", "The page has no total that foxpay can read.");
+        return { text: text, value };
+    };
+    // The same page and the same total as at quote time (C3, C4).
+    async function samePage(intent, hold) {
+        const page = await topPage(hold.tabId, intent.merchant);
+        if (page.documentId !== hold.documentId)
+            throw new PayRefusal("page-changed", "The tab shows a new page since the approval.");
+        if ((await total(hold.tabId, page)).text !== hold.totalText)
+            throw new PayRefusal("amount-changed", "The checkout total changed since the approval.");
+        return page;
+    }
+    async function quote(intent) {
+        const tabId = intent.target?.tabId;
+        if (!Number.isSafeInteger(tabId) || tabId < 0)
+            throw new PayRefusal("bad-target", "Card fill needs target.tabId.");
+        const page = await topPage(tabId, intent.merchant);
+        if (card) {
+            const stored = (await vault.list()).filter((s) => s.handle === card.number || s.handle === card.details);
+            if (stored.length !== 2)
+                throw new PayRefusal("no-card", "The vault does not hold the card.");
+            if (!stored.every((s) => allows(s.domains, page.host)))
+                throw new PayRefusal("domain", `The stored card does not allow ${page.host}.`);
+        }
+        const { text, value } = await total(tabId, page);
+        const hold = { tabId: tabId, documentId: page.documentId, totalText: text };
+        return { amount: value, currency, payee: page.host, hold };
+    }
+    async function check({ intent, quote: q }) {
+        try {
+            await samePage(intent, q.hold);
+        }
+        catch (error) {
+            if (error instanceof PayRefusal)
+                return error.reason;
+            throw error;
+        }
+        if ((await vault.status()) === "unlocked")
+            return undefined;
+        // Device mode unlocks with no passphrase. Passphrase mode stays locked (I17).
+        return vault.unlock().then(() => undefined, () => "locked");
+    }
+    async function fill(intent, hold, handles, state) {
+        // The page can change after the check. Check it again before the number goes out (C11),
+        // and pin the foxvault fill to the checked document, so a later load gets nothing (C16).
+        await samePage(intent, hold);
+        // oxlint-disable-next-line unicorn/no-array-fill-with-reference-type -- this is foxvault fill, not Array#fill
+        const filled = await vault.fill({ handle: handles.number, tabId: hold.tabId, selector: fields.number, documentId: hold.documentId });
+        if (filled.status !== "filled")
+            return filled.status === "refused" ? filled.reason : "fill-asks";
+        state.filled = true;
+        const page = await samePage(intent, hold);
+        const details = await vault.use(handles.details, async (value, info) => {
+            if (!allows(info.domains, page.host))
+                return "domain";
+            const [exp = "", cvc = ""] = value.split(" ");
+            return run(hold.tabId, hold.documentId, fillDetails, [fields.exp, fields.cvc, exp, cvc, page.host]);
+        });
+        if (details !== "filled")
+            return String(details);
+        // Once the submit script starts, a lost result can still mean a placed order (C13).
+        const submitted = await run(hold.tabId, hold.documentId, submitCheckout, [options.submit, options.total, hold.totalText, page.host]).catch(() => "submit-unknown");
+        return String(submitted);
+    }
+    // The page after submit: wait until the tab has a new document.
+    async function after(hold) {
+        for (let waited = 0; waited <= waitMs; waited += 100) {
+            const frame = await browser.webNavigation.getFrame({ tabId: hold.tabId, frameId: 0 }).catch(() => undefined);
+            if (frame && frame.documentId !== hold.documentId)
+                return frame.url;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return undefined;
+    }
+    async function pay({ id, intent, quote: q }) {
+        const hold = q.hold;
+        let handles = card;
+        let proof = {};
+        let vcard;
+        if (provider) {
+            let made;
+            try {
+                made = await provider.createCard({ intentId: id, merchant: intent.merchant, amount: { value: q.amount, currency: q.currency } });
+            }
+            catch {
+                return { status: "failed", reason: "provider-error" };
+            }
+            const name = `vault:fpy-vc-${crypto.randomUUID().slice(0, 8)}`;
+            handles = { number: name, details: `${name}.details` };
+            proof = { last4: made.number.slice(-4), card: made.id };
+            vcard = made;
+        }
+        else {
+            proof = { last4: await vault.use(card.number, (value) => value.slice(-4)), card: card.number };
+        }
+        const state = { filled: false };
+        let failed;
+        try {
+            if (vcard) {
+                // Inside the try, so a half-stored card is removed too (C12).
+                await vault.set(handles.number, vcard.number, { domains: [q.payee], allowHttp: options.allowHttp ?? false });
+                await vault.set(handles.details, `${vcard.exp} ${vcard.cvc}`, { domains: [q.payee], allowHttp: options.allowHttp ?? false });
+            }
+            const result = await fill(intent, hold, handles, state);
+            if (result === "submitted") {
+                const page = await after(hold);
+                return { status: "submitted", proof: { ...proof, ...(page && { page }) } };
+            }
+            if (result === "submit-unknown")
+                return { status: "unsettled", reason: result, proof };
+            failed = { status: "failed", reason: result, proof };
+        }
+        catch (error) {
+            const reason = error instanceof PayRefusal ? error.reason : error.code === "bad-value" ? "provider-card" : "fill-error";
+            failed = { status: "failed", reason, proof };
+        }
+        finally {
+            // A virtual card is for this payment only (C10).
+            if (provider)
+                for (const handle of [handles.number, handles.details])
+                    await vault.remove(handle).catch(() => false);
+        }
+        // Nothing was submitted: take the card out of the form, and close a virtual card (C14, C15).
+        if (state.filled)
+            await run(hold.tabId, hold.documentId, clearFields, [[fields.number, fields.exp, fields.cvc], q.payee]).catch(() => undefined);
+        if (vcard)
+            await provider.cancelCard?.(vcard.id).catch(() => undefined);
+        return failed;
+    }
+    return { quote, check, pay };
+}

package/dist/eip712.d.ts

@@ -0,0 +1,26 @@
+/** The token contract that checks the signature. For USDC on Base Sepolia: name "USDC", version "2", chainId 84532. */
+export interface TokenDomain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+/** EIP-3009 TransferWithAuthorization. Numbers are decimal strings, as in x402. */
+export interface Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** The EIP-55 mixed-case form of an address. */
+export declare function checksumAddress(value: string): string;
+/** The 32-byte EIP-712 digest that the wallet signs. */
+export declare function authorizationDigest(domain: TokenDomain, auth: Authorization): Uint8Array;
+/** The address of a wallet key. */
+export declare function addressOf(privateKey: string): string;
+/** Sign the authorization. Returns 0x and 130 hex digits: r, s, v. */
+export declare function signAuthorization(privateKey: string, domain: TokenDomain, auth: Authorization): string;
+/** The address that signed the authorization. Throws for a signature that is not valid, also for a high s. */
+export declare function recoverAuthorizer(domain: TokenDomain, auth: Authorization, signature: string): string;

package/dist/eip712.js

@@ -0,0 +1,96 @@
+// The minimal EIP-712 signing that x402 "exact" on EVM needs: one struct,
+// EIP-3009 TransferWithAuthorization, signed with secp256k1 (failure mode X13).
+// It uses @noble/curves and @noble/hashes (MIT, audited) and nothing else.
+//
+// digest = keccak256(0x19 0x01 || domainSeparator || structHash)
+// domainSeparator = keccak256(abi.encode(DOMAIN_TYPEHASH, keccak256(name), keccak256(version), chainId, verifyingContract))
+// structHash = keccak256(abi.encode(TYPEHASH, from, to, value, validAfter, validBefore, nonce))
+// The signature is r || s || v, with v = 27 + recovery bit and a low s.
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+const text = new TextEncoder();
+const keccak = (bytes) => keccak_256(bytes);
+const DOMAIN_TYPEHASH = keccak(text.encode("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"));
+const TYPEHASH = keccak(text.encode("TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"));
+const MAX_UINT = 2n ** 256n - 1n;
+// Errors name the field, never its value, so a key cannot end up in a message.
+function bytesOf(hex, length, field) {
+    if (typeof hex !== "string" || !new RegExp(`^0x[0-9a-fA-F]{${length * 2}}$`).test(hex))
+        throw new TypeError(`${field} must be 0x and ${length * 2} hex digits.`);
+    return Uint8Array.from(hex.slice(2).match(/../g), (b) => parseInt(b, 16));
+}
+function word(value) {
+    const out = new Uint8Array(32);
+    for (let i = 31, v = value; i >= 0; i--, v >>= 8n)
+        out[i] = Number(v & 0xffn);
+    return out;
+}
+function uint(value, field) {
+    if (typeof value !== "string" || !/^(0|[1-9]\d{0,77})$/.test(value) || BigInt(value) > MAX_UINT)
+        throw new TypeError(`${field} must be a decimal uint256.`);
+    return word(BigInt(value));
+}
+const address = (value, field) => {
+    const out = new Uint8Array(32);
+    out.set(bytesOf(value, 20, field), 12);
+    return out;
+};
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+const toHex = (bytes) => `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+/** The EIP-55 mixed-case form of an address. */
+export function checksumAddress(value) {
+    const lower = toHex(bytesOf(value, 20, "address")).slice(2);
+    const hash = toHex(keccak(text.encode(lower))).slice(2);
+    return `0x${[...lower].map((c, i) => (parseInt(hash[i], 16) >= 8 ? c.toUpperCase() : c)).join("")}`;
+}
+function domainSeparator(domain) {
+    if (!Number.isSafeInteger(domain.chainId) || domain.chainId <= 0)
+        throw new TypeError("chainId must be a positive whole number.");
+    if (typeof domain.name !== "string" || typeof domain.version !== "string")
+        throw new TypeError("name and version must be strings.");
+    return keccak(concat(DOMAIN_TYPEHASH, keccak(text.encode(domain.name)), keccak(text.encode(domain.version)), word(BigInt(domain.chainId)), address(domain.verifyingContract, "verifyingContract")));
+}
+/** The 32-byte EIP-712 digest that the wallet signs. */
+export function authorizationDigest(domain, auth) {
+    const struct = keccak(concat(TYPEHASH, address(auth.from, "from"), address(auth.to, "to"), uint(auth.value, "value"), uint(auth.validAfter, "validAfter"), uint(auth.validBefore, "validBefore"), bytesOf(auth.nonce, 32, "nonce")));
+    return keccak(concat(Uint8Array.of(0x19, 0x01), domainSeparator(domain), struct));
+}
+function secretKey(privateKey) {
+    const key = bytesOf(privateKey, 32, "The wallet key");
+    if (!secp256k1.utils.isValidSecretKey(key))
+        throw new TypeError("The wallet key is not a valid secp256k1 key.");
+    return key;
+}
+const addressOfPublic = (publicKey) => checksumAddress(toHex(keccak(publicKey.slice(1)).slice(12)));
+/** The address of a wallet key. */
+export function addressOf(privateKey) {
+    return addressOfPublic(secp256k1.getPublicKey(secretKey(privateKey), false));
+}
+/** Sign the authorization. Returns 0x and 130 hex digits: r, s, v. */
+export function signAuthorization(privateKey, domain, auth) {
+    const digest = authorizationDigest(domain, auth);
+    const sig = secp256k1.sign(digest, secretKey(privateKey), { prehash: false, lowS: true, format: "recovered" });
+    return toHex(concat(sig.slice(1), Uint8Array.of(27 + sig[0])));
+}
+/** The address that signed the authorization. Throws for a signature that is not valid, also for a high s. */
+export function recoverAuthorizer(domain, auth, signature) {
+    const sig = bytesOf(signature, 65, "signature");
+    const v = sig[64];
+    if (v !== 27 && v !== 28)
+        throw new TypeError("v must be 27 or 28.");
+    const digest = authorizationDigest(domain, auth);
+    const recovered = concat(Uint8Array.of(v - 27), sig.slice(0, 64));
+    const publicKey = secp256k1.recoverPublicKey(recovered, digest, { prehash: false });
+    // recoverPublicKey accepts a high s. EIP-2 and USDC do not, so refuse it here.
+    if (!secp256k1.verify(sig.slice(0, 64), digest, publicKey, { prehash: false, lowS: true }))
+        throw new TypeError("The signature is not valid.");
+    return addressOfPublic(secp256k1.Point.fromBytes(publicKey).toBytes(false));
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { GATE_CURRENCY, PAY_TOOL, PayRefusal, createFoxpay, payTools } from "./intent.js";
+export type { CompleteResult, Foxpay, FoxpayOptions, Intent, PayContext, PayEvent, PayMethod, PayOutcome, PayStatus, Quote, Receipt, RequestResult } from "./intent.js";
+export { cardFill } from "./card.js";
+export type { CardBrowser, CardFillOptions, VirtualCardProvider } from "./card.js";
+export { addressOf, authorizationDigest, checksumAddress, recoverAuthorizer, signAuthorization } from "./eip712.js";
+export type { Authorization, TokenDomain } from "./eip712.js";
+export { BASE_SEPOLIA, decodeHeader, encodeHeader, x402 } from "./x402.js";
+export type { PaymentPayload, PaymentRequirements, X402Options } from "./x402.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// The public API of foxpay.
+export { GATE_CURRENCY, PAY_TOOL, PayRefusal, createFoxpay, payTools } from "./intent.js";
+export { cardFill } from "./card.js";
+export { addressOf, authorizationDigest, checksumAddress, recoverAuthorizer, signAuthorization } from "./eip712.js";
+export { BASE_SEPOLIA, decodeHeader, encodeHeader, x402 } from "./x402.js";

package/dist/intent.d.ts

@@ -0,0 +1,134 @@
+import { type Gate, type Store, type ToolSpec } from "foxgate";
+/** The foxgate tool name of every payment. Register it with `payTools()`. */
+export declare const PAY_TOOL = "foxpay.pay";
+/**
+ * foxgate takes 3-letter currency codes. Test USDC on Base Sepolia counts as
+ * XTS, the ISO 4217 code for testing, in whole atomic units (6 decimals).
+ */
+export declare const GATE_CURRENCY: Readonly<Record<string, string>>;
+/** The foxgate tool registry for foxpay. The amount comes from the quote, which foxpay puts in the args. */
+export declare function payTools(): Record<string, ToolSpec>;
+/** One wish to pay, from the planner. */
+export interface Intent {
+    /** The merchant host, for example `shop.example.com`. */
+    merchant: string;
+    /** Whole minor units: cents for USD, atomic units for USDC. */
+    amount: number;
+    currency: string;
+    /** Why the agent pays. The human sees it. 1 to 200 characters. */
+    reason: string;
+    /** The name of a method in `createFoxpay({ methods })`. */
+    method: string;
+    /** The same key for every retry of this payment. 8 to 128 characters. */
+    idempotencyKey: string;
+    /** What the method needs to find the payment: `{ tabId }` for card fill, `{ url }` for x402. */
+    target?: Record<string, unknown>;
+}
+/** What the host reads itself, from the merchant page or the 402 answer. */
+export interface Quote {
+    amount: number;
+    currency: string;
+    /** Who gets the money, as the human sees it. */
+    payee: string;
+    /** More facts that the human must see, for example the URL that a payment is for. The token binds them. */
+    details?: Record<string, string>;
+    /** Plain JSON that the method keeps for check and pay. It goes into the store, so never a secret. */
+    hold?: unknown;
+}
+export interface PayContext {
+    id: string;
+    intent: Intent;
+    quote: Quote;
+}
+export type PayStatus = "paid" | "submitted" | "unsettled" | "failed";
+export interface PayOutcome {
+    status: PayStatus;
+    reason?: string;
+    /** Plain JSON, never a secret: last 4 digits, a transaction hash, a page URL. */
+    proof?: Record<string, unknown>;
+    /** The response body, for x402. It is not stored. */
+    body?: string;
+}
+/**
+ * A way to pay. Throw `PayRefusal` to refuse with a reason. From `pay`, throw
+ * it only before any money can move: foxpay records it as `failed`. Any other
+ * error from `pay` is recorded as `unsettled`.
+ */
+export interface PayMethod {
+    quote(intent: Intent): Promise<Quote>;
+    /** Runs before foxgate uses the token. Return a reason to stop, for example `amount-changed` or `locked`. */
+    check?(context: PayContext): Promise<string | undefined>;
+    pay(context: PayContext): Promise<PayOutcome>;
+}
+/** Throw it from a method to refuse with a reason that callers can switch on. From `pay`, only before any money can move. */
+export declare class PayRefusal extends Error {
+    readonly reason: string;
+    constructor(reason: string, message?: string);
+}
+export interface Receipt {
+    id: string;
+    merchant: string;
+    amount: number;
+    currency: string;
+    reason: string;
+    method: string;
+    payee: string;
+    status: PayStatus;
+    failure?: string;
+    requestId?: string;
+    paidAt: number;
+    proof: Record<string, unknown>;
+}
+/** A foxtrail-compatible entry: pass `log.append` as `onEvent`. */
+export interface PayEvent {
+    actor: "foxpay";
+    kind: "pay.request" | "pay.ask" | "pay.refused" | "pay.start" | "pay.approved" | "pay.result";
+    data: Record<string, unknown>;
+}
+export type RequestResult = {
+    status: "ask";
+    id: string;
+    requestId: string;
+} | {
+    status: "refused";
+    id?: string;
+    reason: string;
+    message: string;
+} | {
+    status: PayStatus;
+    id: string;
+    receipt: Receipt;
+    body?: string;
+};
+export type CompleteResult = Exclude<RequestResult, {
+    status: "ask";
+}>;
+export interface FoxpayOptions {
+    /** A foxgate gate made with `payTools()`. */
+    gate: Gate;
+    methods: Record<string, PayMethod>;
+    /** Where intents and receipts live. Use the same store as foxgate. */
+    store: Store;
+    onEvent?: (event: PayEvent) => void | Promise<void>;
+    now?: () => number;
+}
+export declare function createFoxpay(options: FoxpayOptions): Readonly<{
+    /** Check an intent, quote it, and ask foxgate. A retry with the same key gives the same answer. */
+    request: (input: unknown) => Promise<RequestResult>;
+    /** Pay an approved intent with the foxgate token. It pays one time; later calls give the receipt. */
+    complete: (id: string, token: string) => Promise<CompleteResult>;
+    /** Every intent that waits, runs, or ran, with its quote and status. */
+    intents: () => Promise<{
+        id: string;
+        merchant: string;
+        amount: number;
+        currency: string;
+        reason: string;
+        method: string;
+        payee: string;
+        status: "awaiting" | "paying" | PayStatus;
+        requestId?: string | undefined;
+    }[]>;
+    receipts: () => Promise<Receipt[]>;
+}>;
+export type Foxpay = ReturnType<typeof createFoxpay>;