@melra/browser-runtime 0.3.0-alpha.10

package/dist/pinning-proxy.js

@@ -0,0 +1,115 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+// Loopback proxy that closes the DNS-rebinding window.
+//
+// `assertSafeDestination` resolves a hostname and checks every answer, but the
+// browser then resolves the same name again through its own stack. A hostile
+// resolver only has to answer public the first time and private the second, and
+// the check that passed has nothing to do with the socket that opens. Chromium
+// cannot be told to reuse our answer, so the fix is to stop it from connecting
+// at all: it talks to this proxy, and the proxy connects to the address it just
+// checked.
+//
+// Loopback destinations bypass the proxy — Chromium does that by default and
+// there is nothing to rebind about a literal `127.0.0.1`, which the route layer
+// already checks against policy.
+import { createServer, request as httpRequest } from "node:http";
+import { connect } from "node:net";
+import { assertSafeDestination } from "./network-policy.js";
+/** Enough for a refusal to be legible in a network log; the page sees a failure. */
+function refuse(socket, reason) {
+    socket.end(`HTTP/1.1 502 ${reason}\r\nConnection: close\r\n\r\n`);
+}
+function pipeBothWays(client, upstream, head) {
+    // Either half closing has to take the other down, or a stalled tunnel keeps a
+    // socket pair alive for the life of the browser.
+    const end = () => {
+        client.destroy();
+        upstream.destroy();
+    };
+    client.on("error", end);
+    upstream.on("error", end);
+    if (head.length > 0)
+        upstream.write(head);
+    client.pipe(upstream);
+    upstream.pipe(client);
+}
+export async function startPinningProxy(policy) {
+    const sockets = new Set();
+    /**
+     * Track a socket for shutdown and take responsibility for its errors. A proxy
+     * socket resetting is normal — the browser drops keep-alive connections, and
+     * `close()` destroys whatever is still open — and an untracked `error` on a raw
+     * socket is an uncaught exception that takes the host process down with it.
+     */
+    const track = (socket) => {
+        sockets.add(socket);
+        socket.on("error", () => socket.destroy());
+        socket.on("close", () => sockets.delete(socket));
+    };
+    const server = createServer((req, res) => {
+        void (async () => {
+            try {
+                const { url, address } = await assertSafeDestination(req.url ?? "", policy);
+                const upstream = httpRequest({
+                    host: address,
+                    port: url.port === "" ? 80 : Number(url.port),
+                    method: req.method ?? "GET",
+                    path: `${url.pathname}${url.search}`,
+                    // The original headers carry `Host`, so a name-based virtual host
+                    // still resolves correctly at the far end even though the socket
+                    // was opened to a literal address.
+                    headers: req.headers,
+                }, (upstreamRes) => {
+                    res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+                    upstreamRes.pipe(res);
+                });
+                upstream.on("error", () => res.destroy());
+                req.pipe(upstream);
+            }
+            catch {
+                res.writeHead(502).end();
+            }
+        })();
+    });
+    server.on("connect", (req, clientSocket, head) => {
+        void (async () => {
+            try {
+                // CONNECT carries `host:port`, not a URL. Only the authority is checked
+                // because a tunnel has no path to check — the request inside it is TLS.
+                const { address, url } = await assertSafeDestination(`https://${req.url ?? ""}`, policy);
+                const upstream = connect({ host: address, port: url.port === "" ? 443 : Number(url.port) }, () => {
+                    clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+                    pipeBothWays(clientSocket, upstream, head);
+                });
+                track(upstream);
+                upstream.on("error", () => refuse(clientSocket, "Bad Gateway"));
+            }
+            catch {
+                refuse(clientSocket, "Blocked");
+            }
+        })();
+    });
+    server.on("connection", track);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const listening = server.address();
+    if (listening === null || typeof listening === "string") {
+        server.close();
+        throw new Error("browser_proxy_unavailable");
+    }
+    return {
+        server: `http://127.0.0.1:${listening.port}`,
+        close: () => new Promise((resolve) => {
+            // A tunnel keeps its socket open by design, so `close()` alone waits
+            // forever. Destroying first is what makes shutdown bounded.
+            for (const socket of sockets)
+                socket.destroy();
+            sockets.clear();
+            server.close(() => resolve());
+        }),
+    };
+}
+//# sourceMappingURL=pinning-proxy.js.map

package/dist/pinning-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinning-proxy.js","sourceRoot":"","sources":["../src/pinning-proxy.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,uDAAuD;AACvD,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,WAAW;AACX,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,OAAO,IAAI,WAAW,EAAe,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAe,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAsB,MAAM,qBAAqB,CAAC;AAQhF,oFAAoF;AACpF,SAAS,MAAM,CAAC,MAAc,EAAE,MAAc;IAC5C,MAAM,CAAC,GAAG,CAAC,gBAAgB,MAAM,+BAA+B,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,QAAgB,EAAE,IAAY;IAClE,8EAA8E;IAC9E,iDAAiD;IACjD,MAAM,GAAG,GAAG,GAAS,EAAE;QACrB,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,QAAQ,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAqB;IAC3D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC;;;;;OAKG;IACH,MAAM,KAAK,GAAG,CAAC,MAAc,EAAQ,EAAE;QACrC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC;IAEF,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/C,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;gBAC5E,MAAM,QAAQ,GAAG,WAAW,CAC1B;oBACE,IAAI,EAAE,OAAO;oBACb,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;oBAC7C,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,KAAK;oBAC3B,IAAI,EAAE,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE;oBACpC,kEAAkE;oBAClE,iEAAiE;oBACjE,mCAAmC;oBACnC,OAAO,EAAE,GAAG,CAAC,OAAO;iBACrB,EACD,CAAC,WAAW,EAAE,EAAE;oBACd,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,IAAI,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;oBAClE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC,CACF,CAAC;gBACF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC1C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,YAAoB,EAAE,IAAY,EAAE,EAAE;QAC/D,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,wEAAwE;gBACxE,wEAAwE;gBACxE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,MAAM,qBAAqB,CAClD,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,EAAE,EAC1B,MAAM,CACP,CAAC;gBACF,MAAM,QAAQ,GAAG,OAAO,CACtB,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EACjE,GAAG,EAAE;oBACH,YAAY,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;oBAClE,YAAY,CAAC,YAAY,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;gBAC7C,CAAC,CACF,CAAC;gBACF,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAChB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAE/B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,MAAM,EAAE,oBAAoB,SAAS,CAAC,IAAI,EAAE;QAC5C,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5B,qEAAqE;YACrE,4DAA4D;YAC5D,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/C,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAChC,CAAC,CAAC;KACL,CAAC;AACJ,CAAC"}

package/dist/pinning-proxy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pinning-proxy.test.d.ts.map

package/dist/pinning-proxy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinning-proxy.test.d.ts","sourceRoot":"","sources":["../src/pinning-proxy.test.ts"],"names":[],"mappings":""}

package/dist/pinning-proxy.test.js

@@ -0,0 +1,80 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { createServer, request as httpRequest } from "node:http";
+import { connect } from "node:net";
+import { describe, expect, it, vi } from "vitest";
+// `rebind.test` resolves nowhere in reality, which is what makes this a test of
+// pinning rather than of DNS: only a proxy that connects to the address the
+// policy check returned can reach the server below. One that resolved the name
+// a second time — the rebinding window — would fail outright.
+vi.mock("node:dns/promises", () => ({
+    lookup: async () => [{ address: "127.0.0.1", family: 4 }],
+}));
+const { startPinningProxy } = await import("./pinning-proxy.js");
+async function listen() {
+    const server = createServer((_req, res) => res.end("pinned"));
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    return {
+        port: server.address().port,
+        close: () => server.close(),
+    };
+}
+function throughProxy(proxyPort, target) {
+    return new Promise((resolve, reject) => {
+        // Absolute-form request URI: how a browser addresses a proxy.
+        const req = httpRequest({ host: "127.0.0.1", port: proxyPort, path: target }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => (body += String(chunk)));
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, body }));
+        });
+        req.on("error", reject);
+        req.end();
+    });
+}
+describe("pinning proxy", () => {
+    it("connects to the address the policy check returned", async () => {
+        const upstream = await listen();
+        const proxy = await startPinningProxy({
+            allowedDomains: ["*"],
+            allowLocalhost: true,
+        });
+        try {
+            const port = Number(new URL(proxy.server).port);
+            const response = await throughProxy(port, `http://rebind.test:${upstream.port}/`);
+            expect(response).toEqual({ status: 200, body: "pinned" });
+        }
+        finally {
+            await proxy.close();
+            upstream.close();
+        }
+    });
+    it("refuses a destination policy denies", async () => {
+        const upstream = await listen();
+        const proxy = await startPinningProxy({
+            allowedDomains: ["*"],
+            allowLocalhost: false,
+        });
+        try {
+            const port = Number(new URL(proxy.server).port);
+            const response = await throughProxy(port, `http://rebind.test:${upstream.port}/`);
+            expect(response.status).toBe(502);
+            // CONNECT carries no path to check, so the authority has to be enough.
+            const refusal = await new Promise((resolve, reject) => {
+                const socket = connect(port, "127.0.0.1", () => {
+                    socket.write(`CONNECT rebind.test:443 HTTP/1.1\r\nHost: rebind.test:443\r\n\r\n`);
+                });
+                socket.on("data", (chunk) => {
+                    resolve(String(chunk));
+                    socket.destroy();
+                });
+                socket.on("error", reject);
+            });
+            expect(refusal).toContain("502");
+        }
+        finally {
+            await proxy.close();
+            upstream.close();
+        }
+    });
+});
+//# sourceMappingURL=pinning-proxy.test.js.map

package/dist/pinning-proxy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinning-proxy.test.js","sourceRoot":"","sources":["../src/pinning-proxy.test.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,YAAY,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,OAAO,EAAoB,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAElD,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,8DAA8D;AAC9D,EAAE,CAAC,IAAI,CAAC,mBAAmB,EAAE,GAAG,EAAE,CAAC,CAAC;IAClC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;CAC1D,CAAC,CAAC,CAAC;AAEJ,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAEjE,KAAK,UAAU,MAAM;IACnB,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7E,OAAO;QACL,IAAI,EAAG,MAAM,CAAC,OAAO,EAAkB,CAAC,IAAI;QAC5C,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,SAAiB,EACjB,MAAc;IAEd,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,8DAA8D;QAC9D,MAAM,GAAG,GAAG,WAAW,CACrB,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EACpD,CAAC,GAAG,EAAE,EAAE;YACN,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACtE,CAAC,CACF,CAAC;QACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,QAAQ,GAAG,MAAM,MAAM,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC;YACpC,cAAc,EAAE,CAAC,GAAG,CAAC;YACrB,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,YAAY,CACjC,IAAI,EACJ,sBAAsB,QAAQ,CAAC,IAAI,GAAG,CACvC,CAAC;YACF,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5D,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACpB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACnD,MAAM,QAAQ,GAAG,MAAM,MAAM,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC;YACpC,cAAc,EAAE,CAAC,GAAG,CAAC;YACrB,cAAc,EAAE,KAAK;SACtB,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,YAAY,CACjC,IAAI,EACJ,sBAAsB,QAAQ,CAAC,IAAI,GAAG,CACvC,CAAC;YACF,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAElC,uEAAuE;YACvE,MAAM,OAAO,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE;oBAC7C,MAAM,CAAC,KAAK,CACV,mEAAmE,CACpE,CAAC;gBACJ,CAAC,CAAC,CAAC;gBACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;oBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;oBACvB,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,CAAC,CAAC,CAAC;gBACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACpB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/popups-profile.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=popups-profile.test.d.ts.map

package/dist/popups-profile.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popups-profile.test.d.ts","sourceRoot":"","sources":["../src/popups-profile.test.ts"],"names":[],"mappings":""}

package/dist/popups-profile.test.js

@@ -0,0 +1,170 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { createServer } from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BrowserOperationSchema } from "@melra/protocol";
+import { afterEach, describe, expect, it } from "vitest";
+import { BrowserRuntime, detectBrowserExecutable } from "./index.js";
+/**
+ * Two gaps, both invisible to the caller. A click that spawned a window
+ * returned plain success while the window sat there holding focus and a
+ * session, and every run started from an empty profile, so a site that had
+ * been logged into had to be logged into again on the next task.
+ */
+const roots = [];
+const servers = [];
+afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => new Promise((done) => {
+        server.close(() => done());
+    })));
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+/**
+ * `/` opens a window on click; `/set` plants a cookie; `/read` reports whether
+ * the cookie survived. One server covers both halves of this file.
+ */
+async function serve() {
+    const server = createServer((request, response) => {
+        const path = (request.url ?? "/").split("?")[0];
+        if (path === "/set") {
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "set-cookie": "melra=kept; Path=/; Max-Age=3600",
+            });
+            response.end("<!doctype html><title>set</title><body>set</body>");
+            return;
+        }
+        if (path === "/read") {
+            const seen = (request.headers.cookie ?? "").includes("melra=kept");
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            response.end(`<!doctype html><title>read</title><body><div id="cookie">${seen ? "kept" : "gone"}</div></body>`);
+            return;
+        }
+        response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        response.end(`<!doctype html><title>opener</title><body>
+<button id="pop">Open</button>
+<script>
+  document.getElementById('pop').addEventListener('click', () => {
+    window.open('/read', '_blank');
+  });
+</script>
+</body>`);
+    });
+    servers.push(server);
+    await new Promise((done) => {
+        server.listen(0, "127.0.0.1", done);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("fixture_server_address_unavailable");
+    }
+    return `http://127.0.0.1:${address.port}`;
+}
+async function root(name) {
+    const created = await mkdtemp(join(tmpdir(), `melra-${name}-`));
+    roots.push(created);
+    return created;
+}
+const runtime = (workspaceRoot, executablePath, extra = {}) => new BrowserRuntime({
+    workspaceRoot,
+    artifactDirectory: join(workspaceRoot, "artifacts"),
+    executablePath,
+    allowedDomains: ["127.0.0.1"],
+    allowLocalhost: true,
+    ...extra,
+});
+const op = (fields) => BrowserOperationSchema.parse({ kind: "browser", ...fields });
+describe("browser popups", () => {
+    it("reports the window a page opened and closes it by default", async () => {
+        const executablePath = await detectBrowserExecutable();
+        if (executablePath === undefined)
+            return;
+        const url = await serve();
+        const session = runtime(await root("popup-block"), executablePath);
+        try {
+            await session.execute(op({ action: "navigate", url }));
+            const clicked = await session.execute(op({ action: "click", target: { selector: "#pop" } }));
+            // The point: the caller is told what the click opened behind it.
+            expect(clicked.popups).toEqual([
+                expect.objectContaining({ url: `${url}/read`, blocked: true }),
+            ]);
+            // And it is gone by the time the next action runs, not eventually.
+            const tabs = await session.execute(op({ action: "tabs" }));
+            expect(tabs.tabs.length).toBe(1);
+        }
+        finally {
+            await session.close();
+        }
+    }, 120_000);
+    it("keeps the window as an addressable tab when popups are allowed", async () => {
+        const executablePath = await detectBrowserExecutable();
+        if (executablePath === undefined)
+            return;
+        const url = await serve();
+        const session = runtime(await root("popup-allow"), executablePath, {
+            popups: "allow",
+        });
+        try {
+            await session.execute(op({ action: "navigate", url }));
+            const clicked = await session.execute(op({ action: "click", target: { selector: "#pop" } }));
+            expect(clicked.popups[0]?.blocked).toBe(false);
+            const tabs = await session.execute(op({ action: "tabs" }));
+            expect(tabs.tabs.length).toBe(2);
+        }
+        finally {
+            await session.close();
+        }
+    }, 120_000);
+    it("does not mistake a tab the caller asked for for a popup", async () => {
+        const executablePath = await detectBrowserExecutable();
+        if (executablePath === undefined)
+            return;
+        const url = await serve();
+        const session = runtime(await root("popup-tab-new"), executablePath);
+        try {
+            await session.execute(op({ action: "navigate", url }));
+            // Both arrive as the same `page` event. If this were treated as a popup,
+            // `tab_new` would close the tab it just opened.
+            const opened = await session.execute(op({ action: "tab_new", url: `${url}/read` }));
+            expect(opened.popups).toBeUndefined();
+            expect((await session.execute(op({ action: "tabs" }))).tabs).toHaveLength(2);
+        }
+        finally {
+            await session.close();
+        }
+    }, 120_000);
+});
+describe("persistent browser profile", () => {
+    it("keeps a cookie across two sessions, and drops it without a profile", async () => {
+        const executablePath = await detectBrowserExecutable();
+        if (executablePath === undefined)
+            return;
+        const url = await serve();
+        const workspace = await root("profile");
+        const userDataDir = join(workspace, "profile");
+        const read = async (extra) => {
+            const session = runtime(workspace, executablePath, extra);
+            try {
+                await session.execute(op({ action: "navigate", url: `${url}/read` }));
+                const seen = await session.execute(op({ action: "inspect", target: { selector: "#cookie" } }));
+                return String(seen.text ?? "").trim();
+            }
+            finally {
+                await session.close();
+            }
+        };
+        const first = runtime(workspace, executablePath, { userDataDir });
+        try {
+            await first.execute(op({ action: "navigate", url: `${url}/set` }));
+        }
+        finally {
+            await first.close();
+        }
+        expect(await read({ userDataDir })).toBe("kept");
+        // The default is still a throwaway profile, so nothing leaked into it.
+        expect(await read({})).toBe("gone");
+    }, 180_000);
+});
+//# sourceMappingURL=popups-profile.test.js.map

package/dist/popups-profile.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popups-profile.test.js","sourceRoot":"","sources":["../src/popups-profile.test.ts"],"names":[],"mappings":"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"}

package/dist/see-act.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=see-act.test.d.ts.map

package/dist/see-act.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"see-act.test.d.ts","sourceRoot":"","sources":["../src/see-act.test.ts"],"names":[],"mappings":""}

package/dist/see-act.test.js

@@ -0,0 +1,152 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { createServer } from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BrowserOperationSchema } from "@melra/protocol";
+import { afterEach, describe, expect, it } from "vitest";
+import { BrowserRuntime, detectBrowserExecutable } from "./index.js";
+/**
+ * The see/act loop is the thing that was broken: a caller could read a snapshot
+ * but had no way to turn what it saw into a target it could act on. These tests
+ * drive a real page, so they fail if the emitted selector does not address the
+ * element it was reported for.
+ */
+const PAGE = `<!doctype html><html><head><title>See act</title></head><body>
+  <form id="login">
+    <input name="email" placeholder="Email">
+    <input name="password" type="password">
+    <button type="submit" data-testid="submit"> Sign in </button>
+  </form>
+  <div><span>Total</span><section id="cart"><p>2 items</p></section></div>
+  <button disabled>Locked</button>
+</body></html>`;
+const roots = [];
+const servers = [];
+afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => new Promise((done) => {
+        server.close(() => done());
+    })));
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+async function fixture() {
+    const executablePath = await detectBrowserExecutable();
+    if (executablePath === undefined)
+        return undefined;
+    const server = createServer((_request, response) => {
+        response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        response.end(PAGE);
+    });
+    servers.push(server);
+    await new Promise((done) => {
+        server.listen(0, "127.0.0.1", done);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("fixture_server_address_unavailable");
+    }
+    const root = await mkdtemp(join(tmpdir(), "melra-see-act-"));
+    roots.push(root);
+    return {
+        runtime: new BrowserRuntime({
+            workspaceRoot: root,
+            artifactDirectory: join(root, "artifacts"),
+            executablePath,
+            allowedDomains: ["127.0.0.1"],
+            allowLocalhost: true,
+        }),
+        url: `http://127.0.0.1:${address.port}`,
+    };
+}
+describe("browser see/act loop", () => {
+    it("emits a selector that addresses the element it was reported for", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            const observed = await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            const elements = observed.elements;
+            const submit = elements.find((item) => item.testId === "submit");
+            expect(submit?.selector).toBe('[data-testid="submit"]');
+            const email = elements.find((item) => item.attributeName === "email");
+            // Anchored on the form's id rather than a path from <html>.
+            expect(email?.selector).toBe("#login > input:nth-child(1)");
+            expect(email?.placeholder).toBe("Email");
+            expect(elements.find((item) => item.name === "Locked")?.disabled).toBe(true);
+            expect(elements.every((item) => typeof item.index === "number")).toBe(true);
+            // The loop closes only if the selector can be acted on.
+            const typed = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "type",
+                target: { selector: email.selector },
+                value: "user@example.com",
+            }));
+            expect(typed.typed).toBe(true);
+            const after = (await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "inspect" }))).elements.find((item) => item.attributeName === "email");
+            expect(after?.value).toBe("user@example.com");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("matches text through surrounding whitespace instead of failing exact", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            // `<button> Sign in </button>` never matched `getByText("Sign in", {exact:true})`.
+            const clicked = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "click",
+                target: { text: "Sign in" },
+            }));
+            expect(clicked.clicked).toBe(true);
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("reports a target that matches nothing instead of timing out opaquely", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            await expect(runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "click",
+                target: { selector: "#nothing-here" },
+                timeoutMs: 120_000,
+            }))).rejects.toThrow("browser_target_not_found");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("scopes extraction to a target rather than returning the whole page", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            const extracted = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "inspect",
+                target: { selector: "#cart" },
+            }));
+            expect(extracted.text).toBe("2 items");
+            expect(extracted.html).toBe("<p>2 items</p>");
+            expect(extracted.text).not.toContain("Total");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+});
+//# sourceMappingURL=see-act.test.js.map

package/dist/see-act.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"see-act.test.js","sourceRoot":"","sources":["../src/see-act.test.ts"],"names":[],"mappings":"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"}

package/dist/selector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One ancestor step on the path from an anchor down to a snapshot element.
+ *
+ * The page collects these as plain data and the selector string is assembled
+ * here, in Node, so the interesting logic is a pure function of plain objects
+ * and can be tested without a DOM.
+ */
+export interface ElementDescriptor {
+    tag: string;
+    /** 1-based position among the parent's element children. */
+    nth: number;
+    id?: string;
+    testId?: string;
+}
+/**
+ * Assemble a CSS selector addressing the element the chain ends at.
+ *
+ * `snapshot` previously reported `{tag, role, name, type}` and nothing else,
+ * which left a caller no way to turn something it had just seen into something
+ * it could act on — the only remaining option was `getByText(..., {exact: true})`,
+ * which breaks on whitespace, casing, and nested markup. Emitting a selector
+ * alongside each element closes that loop.
+ *
+ * The chain runs anchor-first. Collection stops as soon as it reaches an element
+ * carrying an `id` or `data-testid`, so a page that labels its markup produces a
+ * short, re-render-durable selector; a page that does not falls back to a
+ * positional path, which is exact for the snapshot it came from.
+ */
+export declare function buildSelector(chain: ElementDescriptor[]): string;
+//# sourceMappingURL=selector.d.ts.map

package/dist/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAehE"}