@x1id/resolve 0.23.0 → 0.44.0

package/dist/checkout.js

@@ -0,0 +1,327 @@
+/**
+ * X1ID Pay checkout widget ([Pay 7], docs/x1id-pay-checkout.md): the
+ * postMessage protocol between a merchant page and the X1 Pay invoice page (app.x1pay.me),
+ * plus the merchant-side controller that opens the checkout popup.
+ *
+ * The widget only PAYS an invoice that already exists on chain. The merchant
+ * creates the invoice (itself, or with a merchant-delegate key on its server),
+ * opens checkout for it, and then verifies payment SERVER-SIDE by reading the
+ * Invoice account ({@link verifyInvoicePaid} in pay.ts). What this protocol
+ * reports back to the merchant's browser is a UX hint only: a browser result
+ * can be forged by anyone who controls the merchant's page, so it must never
+ * release goods by itself.
+ *
+ * Flow (all messages are plain JSON-able objects, see {@link CheckoutMessage}):
+ *
+ *   merchant page (origin M)              popup: X1 Pay app (origin A)
+ *   ───────────────────────               ──────────────────────────
+ *   window.open(A/invoice?address=…&embed=1&origin=M&sid=S)
+ *                                    ◀──  ready  {sid, invoice}   (targetOrigin M)
+ *   ack {sid}  (targetOrigin A)       ──▶
+ *                                    ◀──  result {sid, invoice, status, signature}
+ *   popup closed without a result → status "closed" (detected locally)
+ *
+ * Origin checks on BOTH sides:
+ * - the popup posts only to `window.opener` with `targetOrigin` = the
+ *   merchant origin it was opened for, so the browser drops the message if the
+ *   opener is anything else; it trusts an `ack` only when `event.source` is
+ *   its opener and `event.origin` is exactly that origin;
+ * - the merchant accepts a message only when `event.source` is the popup it
+ *   opened, `event.origin` is exactly the X1 Pay app origin, and the session id
+ *   (`sid`, 128 random bits per checkout) and invoice match.
+ *
+ * No iframe mode: the X1 Pay app keeps `frame-ancestors 'none'` /
+ * `X-Frame-Options: DENY` (clickjacking), and wallet extensions work in a
+ * top-level window.
+ *
+ * Dependency-free on purpose (no SDK imports), so the browser widget bundle
+ * stays tiny.
+ */
+/** Protocol tag on every message. */
+export const CHECKOUT_PROTOCOL = "x1id-checkout";
+/** Protocol version on every message. */
+export const CHECKOUT_VERSION = 1;
+/** Where the hosted checkout lives. */
+export const DEFAULT_CHECKOUT_APP_ORIGIN = "https://app.x1pay.me";
+// ---------------------------------------------------------------------------
+// validation
+// ---------------------------------------------------------------------------
+const B58 = "[1-9A-HJ-NP-Za-km-z]";
+const ADDRESS_RE = new RegExp(`^${B58}{32,44}$`);
+const SIGNATURE_RE = new RegExp(`^${B58}{64,88}$`);
+const SID_RE = /^[0-9a-f]{32}$/;
+/** Shape check for a base58 account address (32-44 chars). */
+export function isCheckoutAddress(s) {
+    return typeof s === "string" && ADDRESS_RE.test(s);
+}
+/** Shape check for a base58 transaction signature (64-88 chars). */
+export function isCheckoutSignature(s) {
+    return typeof s === "string" && SIGNATURE_RE.test(s);
+}
+/** A checkout session id: 32 lowercase hex chars (128 bits). */
+export function isCheckoutSid(s) {
+    return typeof s === "string" && SID_RE.test(s);
+}
+/** 128 fresh random bits as a checkout session id (CSPRNG). */
+export function newCheckoutSid() {
+    const c = globalThis.crypto;
+    if (!c?.getRandomValues)
+        throw new Error("No CSPRNG available (globalThis.crypto.getRandomValues)");
+    return Array.from(c.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * A web origin the protocol will talk to, or null. It must be exactly an
+ * origin (`scheme://host[:port]`, no path, query, fragment or credentials),
+ * `https:`, or `http:` on a loopback host for local development. `"null"`
+ * (sandboxed / `file:` pages) is refused: messages could not be pinned to it.
+ */
+export function normalizeCheckoutOrigin(raw) {
+    if (typeof raw !== "string" || raw.length === 0 || raw.length > 255)
+        return null;
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (u.origin === "null" || u.origin !== raw)
+        return null;
+    if (u.protocol === "https:")
+        return u.origin;
+    if (u.protocol === "http:" && LOOPBACK.has(u.hostname))
+        return u.origin;
+    return null;
+}
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Parse an incoming `event.data` as a protocol message, or null. Strict:
+ * right protocol tag and version, a known `type`, only the fields that type
+ * carries, each well-formed. Says nothing about WHO sent it: check
+ * `event.origin` and `event.source` too (see {@link acceptCheckoutResult} and
+ * {@link acceptCheckoutAck}).
+ */
+export function parseCheckoutMessage(data) {
+    if (!isPlainObject(data))
+        return null;
+    if (data.protocol !== CHECKOUT_PROTOCOL || data.version !== CHECKOUT_VERSION)
+        return null;
+    if (!isCheckoutSid(data.sid))
+        return null;
+    const keys = Object.keys(data).sort().join(",");
+    switch (data.type) {
+        case "ready":
+            if (keys !== "invoice,protocol,sid,type,version" || !isCheckoutAddress(data.invoice))
+                return null;
+            return { protocol: CHECKOUT_PROTOCOL, version: CHECKOUT_VERSION, type: "ready", sid: data.sid, invoice: data.invoice };
+        case "ack":
+            if (keys !== "protocol,sid,type,version")
+                return null;
+            return { protocol: CHECKOUT_PROTOCOL, version: CHECKOUT_VERSION, type: "ack", sid: data.sid };
+        case "result": {
+            if (keys !== "invoice,protocol,sid,signature,status,type,version" || !isCheckoutAddress(data.invoice))
+                return null;
+            const status = data.status;
+            if (status !== "paid" && status !== "cancelled")
+                return null;
+            const signature = data.signature;
+            if (signature !== null && !isCheckoutSignature(signature))
+                return null;
+            // Only a payment carries a signature.
+            if (status === "cancelled" && signature !== null)
+                return null;
+            return {
+                protocol: CHECKOUT_PROTOCOL,
+                version: CHECKOUT_VERSION,
+                type: "result",
+                sid: data.sid,
+                invoice: data.invoice,
+                status,
+                signature,
+            };
+        }
+        default:
+            return null;
+    }
+}
+export function checkoutReadyMessage(sid, invoice) {
+    if (!isCheckoutSid(sid))
+        throw new Error("bad checkout sid");
+    if (!isCheckoutAddress(invoice))
+        throw new Error("bad invoice address");
+    return { protocol: CHECKOUT_PROTOCOL, version: CHECKOUT_VERSION, type: "ready", sid, invoice };
+}
+export function checkoutAckMessage(sid) {
+    if (!isCheckoutSid(sid))
+        throw new Error("bad checkout sid");
+    return { protocol: CHECKOUT_PROTOCOL, version: CHECKOUT_VERSION, type: "ack", sid };
+}
+export function checkoutResultMessage(p) {
+    const msg = {
+        protocol: CHECKOUT_PROTOCOL,
+        version: CHECKOUT_VERSION,
+        type: "result",
+        sid: p.sid,
+        invoice: p.invoice,
+        status: p.status,
+        signature: p.status === "paid" ? p.signature : null,
+    };
+    if (!parseCheckoutMessage(msg))
+        throw new Error("bad checkout result");
+    return msg;
+}
+/**
+ * Merchant side: the result carried by `ev`, or null unless it comes from
+ * exactly `expect.source` (the popup window this page opened) at exactly
+ * `expect.appOrigin`, for this checkout's `sid` and `invoice`.
+ */
+export function acceptCheckoutResult(ev, expect) {
+    if (expect.source == null || ev.source !== expect.source || ev.origin !== expect.appOrigin)
+        return null;
+    const msg = parseCheckoutMessage(ev.data);
+    if (!msg || msg.type !== "result" || msg.sid !== expect.sid || msg.invoice !== expect.invoice)
+        return null;
+    return { invoice: msg.invoice, signature: msg.signature, status: msg.status };
+}
+/**
+ * Popup side: true when `ev` is this checkout's `ack`, sent by the window that
+ * opened the popup (`expect.opener`) from exactly `expect.origin`.
+ */
+export function acceptCheckoutAck(ev, expect) {
+    if (expect.opener == null || ev.source !== expect.opener || ev.origin !== expect.origin)
+        return false;
+    const msg = parseCheckoutMessage(ev.data);
+    return !!msg && msg.type === "ack" && msg.sid === expect.sid;
+}
+// ---------------------------------------------------------------------------
+// URLs
+// ---------------------------------------------------------------------------
+/** The hosted checkout URL for an invoice. */
+export function buildCheckoutUrl(p) {
+    const app = normalizeCheckoutOrigin(p.appOrigin ?? DEFAULT_CHECKOUT_APP_ORIGIN);
+    if (!app)
+        throw new Error("appOrigin must be an https origin");
+    const origin = normalizeCheckoutOrigin(p.origin);
+    if (!origin)
+        throw new Error("checkout needs an https page (or http://localhost); this page's origin cannot receive results");
+    if (!isCheckoutAddress(p.invoice))
+        throw new Error("invoice must be a base58 invoice address");
+    if (!isCheckoutSid(p.sid))
+        throw new Error("bad checkout sid");
+    const q = new URLSearchParams({ address: p.invoice, embed: "1", origin, sid: p.sid });
+    return `${app}/invoice?${q.toString()}`;
+}
+/** Popup side: the checkout parameters of an invoice page URL, or null when it
+ *  is not an embedded checkout (or any parameter is malformed). */
+export function parseCheckoutParams(get) {
+    if (get("embed") !== "1")
+        return null;
+    const origin = normalizeCheckoutOrigin(get("origin"));
+    const sid = get("sid");
+    if (!origin || !isCheckoutSid(sid))
+        return null;
+    return { origin, sid };
+}
+/** Thrown by {@link openCheckout} when the browser blocked the popup (call it
+ *  straight from a click handler). */
+export class CheckoutPopupBlockedError extends Error {
+    constructor() {
+        super("The browser blocked the X1 Pay checkout window. Open checkout from a click handler.");
+        this.name = "CheckoutPopupBlockedError";
+    }
+}
+/**
+ * Open the hosted checkout for `opts.invoice` in a popup and listen for its
+ * result. Call it synchronously from a user gesture (a click), or the browser
+ * blocks the popup ({@link CheckoutPopupBlockedError}).
+ *
+ * The result is a HINT for your UI. Before you ship anything, have your server
+ * call `verifyInvoicePaid` with the invoice address and terms YOU stored when
+ * you created the invoice.
+ */
+export function openCheckout(host, opts) {
+    const appOrigin = normalizeCheckoutOrigin(opts.appOrigin ?? DEFAULT_CHECKOUT_APP_ORIGIN);
+    if (!appOrigin)
+        throw new Error("appOrigin must be an https origin");
+    const sid = opts.sid ?? newCheckoutSid();
+    const url = buildCheckoutUrl({ invoice: opts.invoice, origin: host.location.origin, sid, appOrigin });
+    const width = opts.width ?? 440;
+    const height = opts.height ?? 720;
+    const left = Math.max(0, Math.round((host.screenX ?? 0) + ((host.outerWidth ?? width) - width) / 2));
+    const top = Math.max(0, Math.round((host.screenY ?? 0) + ((host.outerHeight ?? height) - height) / 2));
+    // NOT `noopener`: the popup reports back through window.opener.
+    const popup = host.open(url, `x1id-checkout-${sid}`, `popup=yes,width=${width},height=${height},left=${left},top=${top}`);
+    if (!popup)
+        throw new CheckoutPopupBlockedError();
+    let settled = false;
+    let closedSeen = false;
+    let resolveFn;
+    let rejectFn;
+    const result = new Promise((res, rej) => {
+        resolveFn = res;
+        rejectFn = rej;
+    });
+    const listener = (ev) => {
+        if (settled || ev.source !== popup || ev.origin !== appOrigin)
+            return;
+        const msg = parseCheckoutMessage(ev.data);
+        if (!msg || msg.sid !== sid)
+            return;
+        if (msg.type === "ready" && msg.invoice === opts.invoice) {
+            popup.postMessage(checkoutAckMessage(sid), appOrigin);
+            opts.onReady?.();
+            return;
+        }
+        const r = acceptCheckoutResult(ev, { appOrigin, source: popup, sid, invoice: opts.invoice });
+        if (r)
+            finish(r);
+    };
+    const timer = host.setInterval(() => {
+        if (settled)
+            return;
+        if (!popup.closed)
+            return;
+        // Give a result the popup posted just before closing one more tick to
+        // arrive (message delivery is queued) before reporting "closed".
+        if (!closedSeen) {
+            closedSeen = true;
+            return;
+        }
+        finish({ invoice: opts.invoice, signature: null, status: "closed" });
+    }, opts.pollMs ?? 400);
+    function cleanup() {
+        settled = true;
+        host.removeEventListener("message", listener);
+        host.clearInterval(timer);
+    }
+    function finish(r) {
+        if (settled)
+            return;
+        cleanup();
+        resolveFn(r);
+    }
+    host.addEventListener("message", listener);
+    popup.focus?.();
+    return {
+        sid,
+        result,
+        abort() {
+            if (settled)
+                return;
+            cleanup();
+            try {
+                popup.close();
+            }
+            catch {
+                /* already gone */
+            }
+            rejectFn(new Error("checkout aborted"));
+        },
+    };
+}