@fungi.computer/oyster 0.2.0 → 0.3.1

package/dist/browser/page.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { CloudBrowserTimeout, CloudBrowserUpstreamError } from "./errors.js";
+import { cloudBrowserBounds, } from "./operations.js";
+/**
+ * Drive one page of a connected session through a closed set of CDP methods
+ * (navigate/snapshot/click/type/press/scroll/screenshot/pdf). Internal to the
+ * module: callers have already checked lease ownership and URL egress policy.
+ * The session-create response shape was confirmed by the live workerd smoke
+ * on 2026-10-03; see `test/browser/cdp-client.test.ts`.
+ */
+const targetSchema = z.object({ targetId: z.string(), type: z.string() });
+const getTargetsResultSchema = z.object({ targetInfos: z.array(targetSchema) });
+const attachResultSchema = z.object({ sessionId: z.string() });
+const navigateResultSchema = z.object({
+    frameId: z.string().optional(),
+    errorText: z.string().optional(),
+});
+const navigationHistorySchema = z.object({
+    currentIndex: z.number().int(),
+    entries: z.array(z.object({ url: z.string(), title: z.string().optional() })),
+});
+const axValueSchema = z.object({ value: z.json().optional() }).optional();
+const axNodeSchema = z.object({
+    role: axValueSchema,
+    name: axValueSchema,
+    value: axValueSchema,
+    ignored: z.boolean().optional(),
+});
+const axTreeSchema = z.object({ nodes: z.array(axNodeSchema) });
+const capturedDataSchema = z.object({ data: z.string() });
+/** Attach to the session's first page target (or a new blank one). */
+export async function attachPage(client) {
+    const targets = getTargetsResultSchema.parse(await client.call("Target.getTargets", {}));
+    const targetId = targets.targetInfos.find((target) => target.type === "page")?.targetId ??
+        z
+            .object({ targetId: z.string() })
+            .parse(await client.call("Target.createTarget", { url: "about:blank" }))
+            .targetId;
+    const { sessionId: cdpSessionId } = attachResultSchema.parse(await client.call("Target.attachToTarget", { targetId, flatten: true }));
+    await client.call("Page.enable", {}, { sessionId: cdpSessionId });
+    await client.call("Accessibility.enable", {}, { sessionId: cdpSessionId });
+    return { client, cdpSessionId, targetId };
+}
+/** The page's current history entry. */
+export async function pageLocation({ client, cdpSessionId }, fallbackUrl) {
+    const history = navigationHistorySchema.parse(await client.call("Page.getNavigationHistory", {}, { sessionId: cdpSessionId }));
+    const current = history.entries[history.currentIndex];
+    return { url: current?.url ?? fallbackUrl, title: current?.title ?? null };
+}
+/** Navigate to an already policy-checked URL and wait for its load event. */
+export async function navigatePage(page, url, timeoutMs) {
+    const { client, cdpSessionId } = page;
+    // Listen before navigating so a fast load is not missed; a navigation that
+    // fails never leaves a pending wait behind.
+    const load = { fired: false, notify: () => undefined };
+    const stop = client.on("Page.loadEventFired", (_params, sessionId) => {
+        if (sessionId !== cdpSessionId)
+            return;
+        load.fired = true;
+        load.notify();
+    });
+    let timer;
+    try {
+        const result = navigateResultSchema.parse(await client.call("Page.navigate", { url: url.href }, { sessionId: cdpSessionId }));
+        if (result.errorText !== undefined)
+            throw new CloudBrowserUpstreamError({
+                op: "navigate",
+                status: null,
+                message: result.errorText,
+            });
+        await new Promise((resolve, reject) => {
+            if (load.fired) {
+                resolve();
+                return;
+            }
+            load.notify = resolve;
+            timer = setTimeout(() => {
+                reject(new CloudBrowserTimeout({ op: "Page.loadEventFired", timeoutMs }));
+            }, timeoutMs);
+        });
+        return await pageLocation(page, url.href);
+    }
+    finally {
+        stop();
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function axText(value) {
+    const parsed = z.string().min(1).safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+export async function snapshotPage({ client, cdpSessionId }, leaseId, signal) {
+    const tree = axTreeSchema.parse(await client.call("Accessibility.getFullAXTree", {}, { sessionId: cdpSessionId, signal }));
+    const lines = [];
+    let joinedLength = 0;
+    let truncated = false;
+    for (const node of tree.nodes) {
+        if (node.ignored === true)
+            continue;
+        const role = axText(node.role?.value);
+        const name = axText(node.name?.value);
+        const value = axText(node.value?.value);
+        if (role === null && name === null)
+            continue;
+        const line = [role, name, value]
+            .filter((part) => part !== null)
+            .join(" · ");
+        if (joinedLength + line.length > cloudBrowserBounds.maxSnapshotBytes) {
+            truncated = true;
+            break;
+        }
+        joinedLength += (lines.length === 0 ? 0 : 1) + line.length;
+        lines.push(line);
+    }
+    return { leaseId, tree: lines.join("\n"), truncated };
+}
+export async function clickPage({ client, cdpSessionId }, x, y, signal) {
+    const options = { sessionId: cdpSessionId, signal };
+    for (const type of ["mousePressed", "mouseReleased"])
+        await client.call("Input.dispatchMouseEvent", { type, x, y, button: "left", clickCount: 1 }, options);
+}
+export async function typePage({ client, cdpSessionId }, text, signal) {
+    await client.call("Input.insertText", { text }, { sessionId: cdpSessionId, signal });
+}
+export async function pressPage({ client, cdpSessionId }, key, signal) {
+    const options = { sessionId: cdpSessionId, signal };
+    for (const type of ["keyDown", "keyUp"])
+        await client.call("Input.dispatchKeyEvent", { type, key }, options);
+}
+export async function scrollPage({ client, cdpSessionId }, deltaX, deltaY, signal) {
+    await client.call("Input.dispatchMouseEvent", { type: "mouseWheel", x: 1, y: 1, deltaX, deltaY }, { sessionId: cdpSessionId, signal });
+}
+function decodeBase64(data) {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+async function capture({ client, cdpSessionId }, input, leaseId, signal) {
+    const result = capturedDataSchema.parse(await client.call(input.method, input.params, {
+        sessionId: cdpSessionId,
+        signal,
+    }));
+    const bytes = decodeBase64(result.data);
+    if (bytes.byteLength > input.maxBytes)
+        throw new CloudBrowserUpstreamError({
+            op: input.op,
+            status: null,
+            message: `The ${input.op} exceeds the 8 MiB bound`,
+        });
+    return { leaseId, bytes, contentType: input.contentType };
+}
+export function screenshotPage(page, leaseId, signal) {
+    return capture(page, {
+        op: "screenshot",
+        method: "Page.captureScreenshot",
+        params: { format: "png" },
+        maxBytes: cloudBrowserBounds.maxScreenshotBytes,
+        contentType: "image/png",
+    }, leaseId, signal);
+}
+export function pdfPage(page, leaseId, signal) {
+    return capture(page, {
+        op: "pdf",
+        method: "Page.printToPDF",
+        params: {},
+        maxBytes: cloudBrowserBounds.maxPdfBytes,
+        contentType: "application/pdf",
+    }, leaseId, signal);
+}

package/dist/browser/quick-reads.d.ts

@@ -0,0 +1,29 @@
+import type { HttpFetch } from "./cdp-client.js";
+import { type ExtractResult, type LinksResult, type MarkdownResult, type ScrapeResult } from "./operations.js";
+/** The Browser Run account and API token a host's Quick Reads use. */
+export type BrowserRunQuickReadsConfig = Readonly<{
+    accountId: string;
+    apiToken: string;
+    fetch?: HttpFetch;
+}>;
+/** A read's result and the browser time the provider reports for it, if any. */
+export type QuickRead<Result> = Readonly<{
+    result: Result;
+    browserMs: number | null;
+}>;
+/**
+ * The stateless half of the host port; only `browserRunQuickReads` builds
+ * one. The caller (`browser.ts`) owns the deadline through `signal`.
+ */
+export type QuickReads = Readonly<{
+    /** Render a page as markdown, truncated to `maxChars`. */
+    markdown: (url: URL, maxChars: number, signal: AbortSignal) => Promise<QuickRead<MarkdownResult>>;
+    /** Render a page and return its links. */
+    links: (url: URL, signal: AbortSignal) => Promise<QuickRead<LinksResult>>;
+    /** Render a page and return elements matching CSS selectors. */
+    scrape: (url: URL, selectors: readonly string[], signal: AbortSignal) => Promise<QuickRead<ScrapeResult>>;
+    /** Render a page and extract structured data matching a prompt. */
+    extract: (url: URL, prompt: string, signal: AbortSignal) => Promise<QuickRead<ExtractResult>>;
+}>;
+/** Browser Run's REST Quick Actions as a host's `QuickReads`. */
+export declare function browserRunQuickReads(config: BrowserRunQuickReadsConfig): QuickReads;

package/dist/browser/quick-reads.js

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { CloudBrowserUpstreamError } from "./errors.js";
+import { cloudBrowserBounds, extractResultSchema, } from "./operations.js";
+/**
+ * Cloudflare Browser Run's stateless "Quick Actions" REST endpoints. A Workers
+ * BROWSER binding has no equivalent, so a binding host offers no Quick Reads.
+ * Each call is one POST with an account-scoped API token holding only the
+ * "Browser Rendering Edit" permission. Every URL arrives already checked by
+ * `browser.ts` against `url-policy.ts`; this file never sees a raw one.
+ *
+ * https://developers.cloudflare.com/browser-run/rest-api/
+ * https://developers.cloudflare.com/api/resources/browser_rendering/subresources/markdown/methods/create/
+ * https://developers.cloudflare.com/api/resources/browser_rendering/subresources/links/methods/create/
+ * https://developers.cloudflare.com/api/resources/browser_rendering/subresources/scrape/methods/create/
+ * https://developers.cloudflare.com/api/resources/browser_rendering/subresources/json/methods/create/
+ */
+const quickActionResponseSchema = z.object({
+    success: z.boolean(),
+    result: z.json().optional(),
+    errors: z
+        .array(z.object({ code: z.number(), message: z.string() }))
+        .optional(),
+});
+/**
+ * Browser Run reports each REST call's browser time in this header
+ * (https://developers.cloudflare.com/browser-run/rest-api/).
+ */
+const browserMsHeaderSchema = z
+    .string()
+    .regex(/^\d{1,15}$/u)
+    .transform(Number)
+    .pipe(z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER));
+function reportedBrowserMs(response) {
+    const parsed = browserMsHeaderSchema.safeParse(response.headers.get("x-browser-ms-used") ?? undefined);
+    return parsed.success ? parsed.data : null;
+}
+const scrapeElementSchema = z.object({
+    attributes: z
+        .array(z.object({ name: z.string(), value: z.string() }))
+        .optional(),
+    text: z.string().optional(),
+    html: z.string().optional(),
+});
+const scrapeEntrySchema = z.object({
+    selector: z.string(),
+    // Cloudflare's own examples are inconsistent about one match vs many; accept both.
+    results: z.union([scrapeElementSchema, z.array(scrapeElementSchema)]),
+});
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return { text, truncated: false };
+    return { text: `${text.slice(0, maxChars)}\n[truncated]`, truncated: true };
+}
+function boundScrape(entries) {
+    let remaining = cloudBrowserBounds.maxScrapeBytes;
+    let truncated = false;
+    const mapped = [];
+    outer: for (const entry of entries) {
+        const source = Array.isArray(entry.results)
+            ? entry.results
+            : [entry.results];
+        const elements = [];
+        for (const element of source) {
+            const text = element.text ?? "";
+            const html = element.html ?? "";
+            const size = text.length + html.length;
+            if (size > remaining) {
+                const share = Math.max(remaining, 0);
+                elements.push({
+                    text: text.slice(0, share),
+                    html: html.slice(0, Math.max(share - text.length, 0)),
+                });
+                truncated = true;
+                mapped.push({ selector: entry.selector, elements });
+                break outer;
+            }
+            remaining -= size;
+            elements.push({ text, html });
+        }
+        mapped.push({ selector: entry.selector, elements });
+    }
+    return { result: mapped, truncated };
+}
+/** Browser Run's REST Quick Actions as a host's `QuickReads`. */
+export function browserRunQuickReads(config) {
+    const fetcher = config.fetch ?? ((url, init) => fetch(url, init));
+    async function call(action, body, signal) {
+        const response = await fetcher(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(config.accountId)}/browser-rendering/${action}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${config.apiToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal,
+        });
+        const status = response.status;
+        let parsed;
+        try {
+            parsed = quickActionResponseSchema.parse(await response.json());
+        }
+        catch {
+            throw new CloudBrowserUpstreamError({
+                op: action,
+                status,
+                message: "Browser Run returned an unreadable response",
+            });
+        }
+        if (!response.ok || !parsed.success)
+            throw new CloudBrowserUpstreamError({
+                op: action,
+                status,
+                message: parsed.errors?.[0]?.message ??
+                    `Browser Run ${action} failed (HTTP ${String(status)})`,
+            });
+        return { result: parsed.result, browserMs: reportedBrowserMs(response) };
+    }
+    return {
+        markdown: async (url, maxChars, signal) => {
+            const { result, browserMs } = await call("markdown", { url: url.href }, signal);
+            const bound = truncate(z.string().parse(result), maxChars);
+            return {
+                result: { url: url.href, text: bound.text, truncated: bound.truncated },
+                browserMs,
+            };
+        },
+        links: async (url, signal) => {
+            const { result, browserMs } = await call("links", { url: url.href }, signal);
+            const all = z.array(z.string()).parse(result);
+            return {
+                result: {
+                    url: url.href,
+                    links: all.slice(0, cloudBrowserBounds.maxLinks),
+                    truncated: all.length > cloudBrowserBounds.maxLinks,
+                },
+                browserMs,
+            };
+        },
+        scrape: async (url, selectors, signal) => {
+            const { result, browserMs } = await call("scrape", {
+                url: url.href,
+                elements: selectors.map((selector) => ({ selector })),
+            }, signal);
+            return {
+                result: {
+                    url: url.href,
+                    ...boundScrape(z.array(scrapeEntrySchema).parse(result)),
+                },
+                browserMs,
+            };
+        },
+        extract: async (url, prompt, signal) => {
+            const { result, browserMs } = await call("json", { url: url.href, prompt }, signal);
+            return {
+                result: extractResultSchema.parse({ url: url.href, result }),
+                browserMs,
+            };
+        },
+    };
+}

package/dist/browser/sessions.d.ts

@@ -0,0 +1,52 @@
+import { type CdpClient, type CdpSocket, type HttpFetch } from "./cdp-client.js";
+/**
+ * One browser session's provider lifecycle: create, connect CDP, delete and
+ * confirm closure. Cloudflare Browser Run's REST API and a Workers BROWSER
+ * binding speak the same devtools protocol under different roots, so both
+ * hosts share this one implementation:
+ *
+ * - REST: `https://api.cloudflare.com/client/v4/accounts/{account}/browser-run/devtools`
+ *   with `Authorization: Bearer` (https://developers.cloudflare.com/browser-run/cdp/,
+ *   .../cdp/session-management/).
+ * - Binding: `binding.fetch("http://fake.host/v1/devtools/…")`, the endpoints
+ *   a Workers Browser Run binding answers.
+ *
+ * Provider session ids stay inside the module; agent leases use their own ids.
+ */
+export type AcquireOptions = Readonly<{
+    /** Provider idle keep-alive, clamped to Browser Run's 10s–20min range. */
+    keepAliveMs: number;
+    /** Provider guardrail: the only hosts this session may load. */
+    allowedDomains?: readonly string[];
+}>;
+/**
+ * The provider half of the host port. Built only by the two functions below.
+ * Each step is separate so `createBrowser` owns a provider session id from the
+ * moment it exists, including when its CDP connect then fails.
+ */
+export type BrowserSessions = Readonly<{
+    /** Create one provider session; resolves its provider id. @internal */
+    create: (options: AcquireOptions, signal: AbortSignal) => Promise<string>;
+    /** Connect the CDP socket of a created session, bounded by `signal`. @internal */
+    connect: (sessionId: string, signal: AbortSignal) => Promise<CdpClient>;
+    /** Ask the provider to delete a session; 404 is already gone. @internal */
+    release: (sessionId: string, signal: AbortSignal) => Promise<"closed" | "closing">;
+    /** Reads the provider's session record until it reports an end time. @internal */
+    confirmClosed: (sessionId: string, deadlineAt: number) => Promise<void>;
+}>;
+/** A Workers BROWSER binding (`Fetcher`), reduced to the call this module makes. */
+export type BrowserBinding = Readonly<{
+    fetch: HttpFetch;
+}>;
+/** Opens the CDP WebSocket for one provider session URL. */
+export type CdpConnect = (url: string, headers: Readonly<Record<string, string>>, signal: AbortSignal) => Promise<CdpSocket>;
+/** Cloudflare Browser Run over REST with an account token (Hub, any celld host). */
+export declare function browserRunSessions(config: Readonly<{
+    accountId: string;
+    apiToken: string;
+    fetch?: HttpFetch;
+    /** The CDP WebSocket transport; defaults to the outbound upgrade over `fetch`. */
+    connect?: CdpConnect;
+}>): BrowserSessions;
+/** A standalone Oyster's own Workers BROWSER binding. */
+export declare function bindingSessions(binding: BrowserBinding): BrowserSessions;

package/dist/browser/sessions.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { createCdpClient, openCdpSocket, } from "./cdp-client.js";
+import { CloudBrowserUpstreamError } from "./errors.js";
+const createdSchema = z.object({ sessionId: z.string().min(1).max(256) });
+const releasedSchema = z.object({ status: z.enum(["closing", "closed"]) });
+const sessionDetailsSchema = z
+    .object({ sessionId: z.string(), endTime: z.number().optional() })
+    .nullable();
+const minKeepAliveMs = 10_000;
+const maxKeepAliveMs = 1_200_000;
+function devtoolsSessions(input) {
+    const sessionUrl = (sessionId) => `${input.root}/browser/${encodeURIComponent(sessionId)}`;
+    async function create(options, signal) {
+        const keepAlive = Math.min(Math.max(options.keepAliveMs, minKeepAliveMs), maxKeepAliveMs);
+        const init = {
+            method: "POST",
+            headers: input.headers,
+            signal,
+        };
+        if (options.allowedDomains !== undefined) {
+            // Guardrails travel in the create body (the WebSocket upgrade for an
+            // existing session carries none).
+            init.headers = { ...input.headers, "content-type": "application/json" };
+            init.body = JSON.stringify({
+                guardrails: { allowedDomains: options.allowedDomains },
+            });
+        }
+        const response = await input.fetch(`${input.root}/browser?keep_alive=${String(keepAlive)}`, init);
+        if (!response.ok)
+            throw new CloudBrowserUpstreamError({
+                op: "open",
+                status: response.status,
+                message: "The browser provider refused to create a session",
+            });
+        const created = createdSchema.safeParse(await response.json());
+        if (!created.success)
+            throw new CloudBrowserUpstreamError({
+                op: "open",
+                status: null,
+                message: "The browser provider returned an unreadable session",
+            });
+        return created.data.sessionId;
+    }
+    async function deleteSession(sessionId, signal) {
+        const response = await input.fetch(sessionUrl(sessionId), {
+            method: "DELETE",
+            headers: input.headers,
+            signal,
+        });
+        if (response.status === 404)
+            return "closed";
+        if (!response.ok)
+            throw new CloudBrowserUpstreamError({
+                op: "close",
+                status: response.status,
+                message: "The browser provider refused to close the session",
+            });
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // An unreadable acknowledgement is not proof of closure.
+            return "closing";
+        }
+        const released = releasedSchema.safeParse(body);
+        return released.success ? released.data.status : "closing";
+    }
+    return {
+        create,
+        connect: async (sessionId, signal) => createCdpClient(await input.connect(sessionUrl(sessionId), input.headers, signal)),
+        release: deleteSession,
+        confirmClosed: async (sessionId, deadlineAt) => {
+            const url = `${input.root}/session/${encodeURIComponent(sessionId)}`;
+            while (Date.now() < deadlineAt) {
+                const response = await input.fetch(url, {
+                    method: "GET",
+                    headers: input.headers,
+                    signal: AbortSignal.timeout(Math.max(1, deadlineAt - Date.now())),
+                });
+                if (response.status !== 200)
+                    break;
+                const details = sessionDetailsSchema.safeParse(await response.json());
+                if (!details.success || details.data?.sessionId !== sessionId)
+                    break;
+                if ((details.data.endTime ?? 0) > 0)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadlineAt - Date.now()))));
+            }
+            throw new CloudBrowserUpstreamError({
+                op: "close.confirm",
+                status: null,
+                message: "The browser provider did not confirm the session closed",
+            });
+        },
+    };
+}
+/** Cloudflare Browser Run over REST with an account token (Hub, any celld host). */
+export function browserRunSessions(config) {
+    const fetcher = config.fetch ?? ((url, init) => fetch(url, init));
+    return devtoolsSessions({
+        root: `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(config.accountId)}/browser-run/devtools`,
+        fetch: fetcher,
+        headers: { authorization: `Bearer ${config.apiToken}` },
+        connect: config.connect ??
+            ((url, headers, signal) => openCdpSocket(fetcher, url, headers, signal)),
+    });
+}
+/** A standalone Oyster's own Workers BROWSER binding. */
+export function bindingSessions(binding) {
+    const fetcher = (url, init) => binding.fetch(url, init);
+    return devtoolsSessions({
+        root: "http://fake.host/v1/devtools",
+        fetch: fetcher,
+        headers: {},
+        connect: (url, headers, signal) => openCdpSocket(fetcher, url, headers, signal),
+    });
+}

package/dist/browser/url-policy.d.ts

@@ -0,0 +1,18 @@
+import { type HostResolver } from "@fungi.computer/veil/model-key-network";
+export type UrlCheckOptions = Readonly<{
+    resolve?: HostResolver;
+    signal: AbortSignal;
+}>;
+/**
+ * The egress and URL policy every cloud-browser call checks before it reaches
+ * Cloudflare Browser Run: http(s) only, no embedded credentials, and the
+ * resolved name must be public unicast. This reuses the exact SSRF defence
+ * Veil's public-fetch door and the Team's BYO model-key intake already use
+ * (`@fungi.computer/veil/model-key-network`): a literal like `127.0.0.1` or
+ * `169.254.169.254`, a private range like `10/8`, the box's own address, and
+ * a rebinding hostname (one whose DNS answer is private) are all refused
+ * here, before Cloudflare ever sees the URL. The name is resolved once; the
+ * caller never connects to it directly — Cloudflare does, so this is a policy
+ * gate, not a proxy.
+ */
+export declare function assertCloudBrowserUrlAllowed(raw: string, options: UrlCheckOptions): Promise<URL>;

package/dist/browser/url-policy.js

@@ -0,0 +1,58 @@
+import { VeilError } from "@fungi.computer/veil";
+import { createDnsOverHttpsResolver, resolvePublicAddresses, } from "@fungi.computer/veil/model-key-network";
+import { CloudBrowserUrlDenied } from "./errors.js";
+/**
+ * The egress and URL policy every cloud-browser call checks before it reaches
+ * Cloudflare Browser Run: http(s) only, no embedded credentials, and the
+ * resolved name must be public unicast. This reuses the exact SSRF defence
+ * Veil's public-fetch door and the Team's BYO model-key intake already use
+ * (`@fungi.computer/veil/model-key-network`): a literal like `127.0.0.1` or
+ * `169.254.169.254`, a private range like `10/8`, the box's own address, and
+ * a rebinding hostname (one whose DNS answer is private) are all refused
+ * here, before Cloudflare ever sees the URL. The name is resolved once; the
+ * caller never connects to it directly — Cloudflare does, so this is a policy
+ * gate, not a proxy.
+ */
+export async function assertCloudBrowserUrlAllowed(raw, options) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CloudBrowserUrlDenied({
+            reason: "invalid_url",
+            message: `${raw} is not a URL`,
+        });
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new CloudBrowserUrlDenied({
+            reason: "unsupported_scheme",
+            message: "only http(s) URLs are fetched",
+        });
+    if (url.username !== "" || url.password !== "")
+        throw new CloudBrowserUrlDenied({
+            reason: "credentials_in_url",
+            message: "URLs with credentials are refused",
+        });
+    const resolve = options.resolve ?? createDnsOverHttpsResolver();
+    try {
+        await resolvePublicAddresses(url.hostname, resolve, options.signal);
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        if (error instanceof VeilError && error.code === "denied")
+            throw new CloudBrowserUrlDenied({
+                reason: "not_public",
+                message: `${url.hostname} is not a public address`,
+            });
+        if (error instanceof VeilError)
+            throw new CloudBrowserUrlDenied({
+                reason: "dns_unavailable",
+                message: `${url.hostname} did not resolve`,
+            });
+        throw error;
+    }
+    url.hash = "";
+    return url;
+}

package/dist/build/app-imports.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Find runtime package imports in the App, not in its authoring tools or in
+ * package export siblings. esbuild follows local modules and erases type-only
+ * imports; packages stay external until their declared products are compiled.
+ * parse5 owns HTML syntax, including inline module scripts.
+ */
+export declare function appRuntimeImports(options: {
+    readonly root: string;
+    readonly entry: string;
+    readonly backendEntry?: string | undefined;
+    readonly shellEntry?: string | undefined;
+}): Promise<ReadonlySet<string>>;