@reticlehq/server 3.8.2 → 3.9.0

package/dist/portal/input/real-input.js

@@ -14,11 +14,12 @@ import { DriveError } from './drive-error.js';
 import { pressViaKeyboard } from './real-input-press.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
 import { launchChromium } from '../../launch-chromium.js';
+import { pageViewportOptions } from '../../chromium-launch-options.js';
 import { chromiumLaunchHint, gotoOptions, SCREENSHOT_DETERMINISM, captureWithChromeHidden, } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
-import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, ClickButton, clickButtonFromArgs, InputMode, pressModifiersFromArgs, } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, ClickButton, clickButtonFromArgs, InputMode, pressModifiersFromArgs, RETICLE_CHROME_PASS_THROUGH_SCRIPT, RETICLE_CHROME_RESTORE_POINTER_SCRIPT, } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
 import { injectedConnectArgs } from '../pool/zero-install.js';
@@ -85,6 +86,27 @@ now = Date.now) {
             ...(heldMs > 0 ? { heldMs } : {}),
         };
     }
+    return withChromePassThrough(page, () => pointerGesture(page, action, box, args, sleep));
+}
+/**
+ * Run a real pointer gesture with Reticle's own UI out of the hit test, and put it back after.
+ *
+ * A real pointer goes to the topmost element under it. When the HUD sat over the app's control, a
+ * driven click went to the HUD and the verdict said the app did nothing; a drag ended short (#992).
+ * The restore runs whatever the gesture did, so the HUD does not stay unclickable for a person.
+ */
+export async function withChromePassThrough(page, gesture) {
+    await page.evaluate(RETICLE_CHROME_PASS_THROUGH_SCRIPT);
+    try {
+        return await gesture();
+    }
+    finally {
+        // A click that navigated takes the old page and its held values with it.
+        await page.evaluate(RETICLE_CHROME_RESTORE_POINTER_SCRIPT).catch(() => undefined);
+    }
+}
+/** The pointer half of `performGesture`: every action that lands at a point. */
+async function pointerGesture(page, action, box, args, sleep) {
     const center = boxCenter(box);
     const { cx, cy } = center;
     const real = (performed) => ({
@@ -352,6 +374,8 @@ export class CdpRealInputProvider {
     }
 }
 const INJECT_CONNECT_WAIT_MS = 8_000;
+/** True on a page whose Reticle SDK has loaded. */
+const SDK_PRESENT = '!!globalThis.__reticleInstance';
 /** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
 export const launchedChromium = async (headless) => {
     let mod;
@@ -386,6 +410,7 @@ export class LaunchedRealInputProvider {
     #injectConnect;
     #storageState;
     #onNetworkDetail;
+    #zeroInstallScript;
     #browser;
     #page;
     /** Pages collecting V8 coverage — see js-coverage.ts. */
@@ -399,10 +424,14 @@ export class LaunchedRealInputProvider {
         this.#injectConnect = options.injectConnect;
         this.#storageState = options.storageState;
         this.#onNetworkDetail = options.onNetworkDetail;
+        this.#zeroInstallScript = options.zeroInstallScript;
     }
     async navigate() {
         this.#browser = await this.#launch(this.#headless);
-        const page = await this.#browser.newPage(this.#storageState !== undefined ? { storageState: this.#storageState } : undefined);
+        const page = await this.#browser.newPage({
+            ...pageViewportOptions(this.#headless),
+            ...(this.#storageState !== undefined ? { storageState: this.#storageState } : {}),
+        });
         this.#page = page;
         // Capture CDP-authoritative response detail into the driven session's journal (best-effort).
         if (this.#onNetworkDetail !== undefined) {
@@ -420,8 +449,35 @@ export class LaunchedRealInputProvider {
         catch (e) {
             throw new DriveError(DriveErrorCode.NAVIGATE_FAILED, e instanceof Error ? e.message : String(e));
         }
+        await this.#supplyReader(page);
         await this.#tryInjectConnect(page);
     }
+    /**
+     * Give a page with no Reticle SDK the zero-install reader, so `verify` on an app with no `init`
+     * still gets a session. The wait for the page's own SDK comes first, as on a leased tab, and the
+     * script checks the singleton, so a page with an SDK never gets a second one.
+     */
+    async #supplyReader(page) {
+        const script = this.#zeroInstallScript?.();
+        if (script === undefined) {
+            return;
+        }
+        try {
+            await page.waitForFunction(SDK_PRESENT, { timeout: INJECT_CONNECT_WAIT_MS });
+            return;
+        }
+        catch {
+            // No SDK on the page: supply the reader below.
+        }
+        try {
+            // Also on every later document, so a full navigation keeps the session.
+            await page.addInitScript(script);
+            await page.evaluate(script);
+        }
+        catch {
+            // A page that refuses the reader has no session. verify's no-session guard reports it.
+        }
+    }
     /**
      * Wait for the page's Reticle singleton to exist, then re-invoke connect with our token + loopback
      * URL so a hosted (non-localhost) preview pairs to our bridge without the app being reconfigured.
@@ -433,7 +489,7 @@ export class LaunchedRealInputProvider {
             return;
         }
         try {
-            await page.waitForFunction('!!globalThis.__reticleInstance', {
+            await page.waitForFunction(SDK_PRESENT, {
                 timeout: INJECT_CONNECT_WAIT_MS,
             });
             const arg = JSON.stringify(injectedConnectArgs(opts));

package/dist/portal/input/viewport-tools.js

@@ -83,8 +83,8 @@ export const VIEWPORT_TOOLS = [
         },
         outputSchema: {
             applied: z.boolean(),
-            width: z.number(),
-            height: z.number(),
+            width: z.number().optional(),
+            height: z.number().optional(),
             observed: z.object({ width: z.number(), height: z.number() }).optional(),
             colorScheme: z.string().optional(),
             reducedMotion: z.string().optional(),
@@ -97,7 +97,10 @@ export const VIEWPORT_TOOLS = [
             if (media !== undefined && args['width'] === undefined && args['height'] === undefined) {
                 const session = deps.sessions.resolve(asString(args['sessionId']));
                 if (true === (await deps.pool?.emulateLease(session.id, media))) {
-                    return { applied: true, width: 0, height: 0, ...media };
+                    // No size was asked for, so answer the one the lease has; 0 by 0 reads as a broken
+                    // viewport (#1902). When the page cannot be read, leave the size out.
+                    const size = await deps.pool?.viewportOfLease(session.id);
+                    return { applied: true, ...size, ...media };
                 }
                 return { ...refused(), recommendation: MEDIA_NEEDS_A_LEASE };
             }

package/dist/portal/pool/browser-pool.d.ts

@@ -13,7 +13,7 @@ import { type SeedStorage } from '@reticlehq/core';
 import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
 import type { RealInputArgs, RealInputResult } from '../input/real-input.js';
 import { type LeaseEmulation, type LeaseMedia } from './lease-emulation.js';
-export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, } from './pool-contract.js';
+export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, PooledPage, PooledPageError, } from './pool-contract.js';
 import { type BrowserPoolOptions, type Lease } from './pool-lease.js';
 export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
 export type { Lease } from './pool-lease.js';
@@ -101,6 +101,8 @@ export declare class BrowserPool {
      * reaper take it out from under a diff.
      */
     screenshotLease(sessionId: string, opts?: ScreenshotOptions): Promise<Uint8Array | undefined>;
+    /** The reason {@link screenshotLease} last failed for this session, if it did. */
+    leaseCaptureError(sessionId: string): string | undefined;
     /** The URL a lease was opened on — the one that carries its Reticle identity. */
     leaseUrl(sessionId: string): string | undefined;
     /**
@@ -243,6 +245,8 @@ export declare class BrowserPool {
     lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
+    /** The origin added to this lease's page CSP `connect-src`, or undefined if none was (#2016). */
+    cspWidenedFor(sessionId: string): string | undefined;
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId: string): boolean;
     /** Whether this lease lives in the headed browser. */

package/dist/portal/pool/browser-pool.js

@@ -14,10 +14,11 @@ import { log } from '../../log.js';
 import { closeLeaseTab, LEASE_CLOSE_TIMED_OUT, settledWithin } from './bounded-close.js';
 import { seedStorageInto, targetOriginOf } from './storage-seed.js';
 import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
-import { grantLeasePermissions, readNotificationPermission } from './context-permissions.js';
+import { grantLeasePermissions, grantLocalNetworkAccess, readNotificationPermission, widenLeaseCsp, } from './context-permissions.js';
 import { readViewport } from './lease-emulation.js';
 import { NotHtmlDocumentError, READER_NOT_HTML } from './zero-install.js';
-import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
+import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, navStatusOf, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
+import { listenForPageErrors, reportLeaseClosed, } from './lease-page-error.js';
 export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
@@ -30,6 +31,8 @@ export class BrowserPool {
     #now;
     #ttl;
     #zeroInstall;
+    #daemonOrigin;
+    #pageErrorHooks;
     #navTimeout;
     #headless;
     #headed;
@@ -73,6 +76,8 @@ export class BrowserPool {
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
         this.#zeroInstall = opts.zeroInstallScript;
+        this.#daemonOrigin = opts.daemonOrigin;
+        this.#pageErrorHooks = { onPageError: opts.onPageError, onLeaseClosed: opts.onLeaseClosed };
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -109,17 +114,9 @@ export class BrowserPool {
             return undefined;
         }
         for (const [leaseId, lease] of this.#active) {
-            if (lease.owner !== owner) {
-                continue;
-            }
-            let leaseOrigin;
-            try {
-                leaseOrigin = new URL(lease.url).origin;
-            }
-            catch {
-                continue;
-            }
-            if (leaseOrigin !== origin) {
+            if (lease.owner !== owner ||
+                !URL.canParse(lease.url) ||
+                new URL(lease.url).origin !== origin) {
                 continue;
             }
             for (const [alias, id] of this.#aliases) {
@@ -247,15 +244,21 @@ export class BrowserPool {
             return undefined;
         }
         this.touch(sessionId);
+        delete lease.captureError;
         try {
             return await lease.page.screenshot(opts);
         }
-        catch {
-            // A capture that fails is not a broken lease. Report "could not capture" and leave the lease
-            // usable — the alternative is losing a working context to one bad frame.
+        catch (error) {
+            // A capture that fails is not a broken lease. Keep the reason and leave the lease usable,
+            // so the screenshot error says why the browser capture failed.
+            lease.captureError = error instanceof Error ? error.message : String(error);
             return undefined;
         }
     }
+    /** The reason {@link screenshotLease} last failed for this session, if it did. */
+    leaseCaptureError(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.captureError;
+    }
     /** The URL a lease was opened on — the one that carries its Reticle identity. */
     leaseUrl(sessionId) {
         return this.#active.get(this.#leaseIdOf(sessionId))?.url;
@@ -516,10 +519,10 @@ export class BrowserPool {
             if (opts.permissions !== undefined) {
                 await grantLeasePermissions(context, opts.permissions, url);
             }
+            await grantLocalNetworkAccess(context, url);
+            const csp = await widenLeaseCsp(context, url, this.#daemonOrigin);
             const page = await context.newPage();
-            // A caller-supplied init script is a stub of the bindings a desktop shell injects, and it has
-            // to exist before the app's first module runs. Installed here — before goto — so the very
-            // first document gets it, and kept for the lease (see hostStub) so a reload keeps it too.
+            // A desktop-shell stub must exist before the app's first module: added before goto, and kept.
             let hostStub;
             if (opts.initScript !== undefined) {
                 const added = await page.addInitScript?.(opts.initScript);
@@ -562,6 +565,8 @@ export class BrowserPool {
                 }
                 void dialog.dismiss();
             });
+            // Listener on BEFORE goto — an import-time throw lands during it (#1966).
+            listenForPageErrors(page, sessionId, this.#pageErrorHooks);
             const marker = leaseMarkerOf(url);
             if (marker?.session === sessionId) {
                 await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
@@ -593,24 +598,7 @@ export class BrowserPool {
             // Foreground it: a page opened beside other tabs can start hidden (#1351). Best-effort — a tab
             // that stays hidden is reported by name at the lease, which failing here would lose.
             await page.bringToFront?.().catch(() => undefined);
-            let navStatus;
-            if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
-                const s = navRes.status;
-                if ('function' === typeof s) {
-                    try {
-                        const code = s.call(navRes);
-                        if ('number' === typeof code) {
-                            navStatus = code;
-                        }
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
-                else if ('number' === typeof s) {
-                    navStatus = s;
-                }
-            }
+            const navStatus = navStatusOf(navRes);
             this.#active.set(sessionId, {
                 headed: slot.headed,
                 context,
@@ -620,6 +608,7 @@ export class BrowserPool {
                 touchedAt: this.#now(),
                 permissions: opts.permissions ?? [],
                 ignoresHTTPSErrors: true === opts.ignoreHTTPSErrors,
+                csp,
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
                 ...(hostStub === undefined || opts.initScript === undefined
@@ -632,7 +621,7 @@ export class BrowserPool {
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
                 injectReader: async () => {
-                    const script = this.#zeroInstall?.();
+                    const script = this.#zeroInstall?.(url);
                     if (script === undefined || page.evaluate === undefined) {
                         return false;
                     }
@@ -703,6 +692,7 @@ export class BrowserPool {
             return;
         } // already released or lost to a crash
         this.#active.delete(sessionId);
+        reportLeaseClosed(this.#pageErrorHooks, sessionId);
         // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
         // reusing that registered name would resolve to a context that is already closed.
         for (const [registered, leaseId] of this.#aliases) {
@@ -863,6 +853,10 @@ export class BrowserPool {
             waiter();
         } // let them re-claim + relaunch
     }
+    /** The origin added to this lease's page CSP `connect-src`, or undefined if none was (#2016). */
+    cspWidenedFor(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.csp.widenedFor;
+    }
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId) {
         return true === this.#active.get(this.#leaseIdOf(sessionId))?.ignoresHTTPSErrors;

package/dist/portal/pool/context-permissions.d.ts

@@ -1,20 +1,3 @@
-/**
- * Browser permissions on a leased context: granted before the first navigation, and read back where
- * the browser can contradict the grant.
- *
- * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
- * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
- * is. A different set means a fresh lease.
- *
- * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
- * is not handed the same grant as the app.
- *
- * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
- * when Playwright's own Chromium is installed — has no notification support: after a grant,
- * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
- * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
- * "granted" there would be reporting something the page cannot see.
- */
 import type { PooledContext, PooledPage } from './pool-contract.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export declare const NOTIFICATIONS_PERMISSION = "notifications";
@@ -31,6 +14,19 @@ export declare class LeasePermissionError extends Error {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export declare function grantLeasePermissions(context: PooledContext, permissions: readonly string[], url: string): Promise<void>;
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export declare function offLoopbackOrigin(url: string | undefined): string | undefined;
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export declare const LOCAL_NETWORK_ACCESS = "local-network-access";
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export declare function grantLocalNetworkAccess(context: PooledContext, url: string): Promise<void>;
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -39,3 +35,10 @@ export declare function grantLeasePermissions(context: PooledContext, permission
  * instead of holding the caller.
  */
 export declare function readNotificationPermission(page: PooledPage): Promise<string | undefined>;
+/**
+ * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
+ * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export declare function widenLeaseCsp(context: PooledContext, url: string, daemonOrigin: string | undefined): Promise<{
+    widenedFor?: string;
+}>;

package/dist/portal/pool/context-permissions.js

@@ -1,3 +1,21 @@
+/**
+ * Browser permissions on a leased context: granted before the first navigation, and read back where
+ * the browser can contradict the grant.
+ *
+ * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
+ * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
+ * is. A different set means a fresh lease.
+ *
+ * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
+ * is not handed the same grant as the app.
+ *
+ * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
+ * when Playwright's own Chromium is installed — has no notification support: after a grant,
+ * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
+ * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
+ * "granted" there would be reporting something the page cannot see.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export const NOTIFICATIONS_PERMISSION = 'notifications';
 /** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
@@ -19,8 +37,9 @@ function reasonOf(err) {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export async function grantLeasePermissions(context, permissions, url) {
-    if (0 === permissions.length)
+    if (0 === permissions.length) {
         return;
+    }
     if (context.grantPermissions === undefined) {
         throw new LeasePermissionError('this browser context cannot grant permissions');
     }
@@ -31,6 +50,36 @@ export async function grantLeasePermissions(context, permissions, url) {
         throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
     }
 }
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export function offLoopbackOrigin(url) {
+    if (url === undefined || !URL.canParse(url)) {
+        return undefined;
+    }
+    const target = new URL(url);
+    return isLoopbackHostname(target.hostname) ? undefined : target.origin;
+}
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export const LOCAL_NETWORK_ACCESS = 'local-network-access';
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export async function grantLocalNetworkAccess(context, url) {
+    const origin = offLoopbackOrigin(url);
+    if (context.grantPermissions === undefined || origin === undefined) {
+        return;
+    }
+    try {
+        await context.grantPermissions([LOCAL_NETWORK_ACCESS], { origin });
+    }
+    catch {
+        // An unknown permission name on an older Playwright: open the lease without it.
+    }
+}
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -57,3 +106,16 @@ export async function readNotificationPermission(page) {
         clearTimeout(timer);
     }
 }
+/**
+ * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
+ * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export async function widenLeaseCsp(context, url, daemonOrigin) {
+    const widening = {};
+    if (daemonOrigin !== undefined && offLoopbackOrigin(url) !== undefined) {
+        await context.widenCsp?.(daemonOrigin, () => {
+            widening.widenedFor = daemonOrigin;
+        });
+    }
+    return widening;
+}

package/dist/portal/pool/csp-widen.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+/** The result of a rewrite: the new text, and whether it differs from the text that came in. */
+export interface CspRewrite {
+    policy: string;
+    changed: boolean;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export declare function allowDaemonInCsp(policy: string, origin: string): CspRewrite;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export declare function allowDaemonInHtml(html: string, origin: string): {
+    html: string;
+    changed: boolean;
+};
+/** The part of a Playwright `Route` the rewrite uses. A real `Route` satisfies it. */
+export interface CspRoute<R extends CspResponse = CspResponse> {
+    request(): {
+        resourceType(): string;
+        frame(): {
+            parentFrame(): unknown;
+        };
+    };
+    fallback(): Promise<void>;
+    fetch(opts: {
+        maxRedirects: number;
+    }): Promise<R>;
+    fulfill(opts: {
+        response: R;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<void>;
+}
+/** The part of a Playwright `APIResponse` the rewrite uses. */
+export interface CspResponse {
+    headers(): Record<string, string>;
+    headersArray(): {
+        name: string;
+        value: string;
+    }[];
+    text(): Promise<string>;
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export declare function widenDocumentCsp<R extends CspResponse>(route: CspRoute<R>, origin: string, onWidened: () => void): Promise<void>;

package/dist/portal/pool/csp-widen.js

@@ -0,0 +1,132 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+const CONNECT_SRC = 'connect-src';
+const DEFAULT_SRC = 'default-src';
+const NONE_SOURCE = "'none'";
+const CSP_HEADER = 'content-security-policy';
+const DOCUMENT = 'document';
+const tokensOf = (directive) => directive.trim().split(/\s+/);
+const nameOf = (directive) => (tokensOf(directive)[0] ?? '').toLowerCase();
+/** `name` plus its sources plus `origin`. `'none'` goes, because it is valid only alone. */
+function withOrigin(name, sources, origin) {
+    const kept = sources.filter((s) => s.toLowerCase() !== NONE_SOURCE);
+    return [name, ...kept, origin].join(' ');
+}
+/** One policy (no commas). Only the first `connect-src` counts; a browser ignores a repeat. */
+function allowInOnePolicy(policy, origin) {
+    const directives = policy.split(';');
+    const connect = directives.findIndex((d) => nameOf(d) === CONNECT_SRC);
+    if (connect !== -1) {
+        const [name = CONNECT_SRC, ...sources] = tokensOf(directives[connect] ?? '');
+        if (sources.includes(origin)) {
+            return policy;
+        }
+        const lead = /^\s*/.exec(directives[connect] ?? '')?.[0] ?? '';
+        directives[connect] = `${lead}${withOrigin(name, sources, origin)}`;
+        return directives.join(';');
+    }
+    const fallback = directives.find((d) => nameOf(d) === DEFAULT_SRC);
+    if (fallback === undefined) {
+        return policy;
+    }
+    const head = policy.replace(/[\s;]+$/, '');
+    return `${head}; ${withOrigin(CONNECT_SRC, tokensOf(fallback).slice(1), origin)}`;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export function allowDaemonInCsp(policy, origin) {
+    const next = policy
+        .split(',')
+        .map((one) => allowInOnePolicy(one, origin))
+        .join(',');
+    return { policy: next, changed: next !== policy };
+}
+const META_TAG = /<meta\b[^>]*>/gi;
+const CSP_EQUIV = /\bhttp-equiv\s*=\s*["']?content-security-policy["']?(?=[\s/>])/i;
+const CONTENT_ATTR = /(\bcontent\s*=\s*)("([^"]*)"|'([^']*)')/i;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export function allowDaemonInHtml(html, origin) {
+    const next = html.replace(META_TAG, (tag) => {
+        if (!CSP_EQUIV.test(tag)) {
+            return tag;
+        }
+        return tag.replace(CONTENT_ATTR, (_all, prefix, quoted) => {
+            const quote = quoted.charAt(0);
+            const widened = allowDaemonInCsp(quoted.slice(1, -1), origin).policy;
+            return `${prefix}${quote}${widened}${quote}`;
+        });
+    });
+    return { html: next, changed: next !== html };
+}
+function isTopDocument(route) {
+    const request = route.request();
+    if (request.resourceType() !== DOCUMENT) {
+        return false;
+    }
+    try {
+        return null === request.frame().parentFrame();
+    }
+    catch {
+        // A request with no frame (a service worker's own fetch) is no page the reader runs in.
+        return false;
+    }
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export async function widenDocumentCsp(route, origin, onWidened) {
+    if (!isTopDocument(route)) {
+        await route.fallback();
+        return;
+    }
+    let response;
+    try {
+        // No redirects followed here: a redirect goes back to the browser, so the page URL stays true.
+        response = await route.fetch({ maxRedirects: 0 });
+    }
+    catch {
+        await route.fallback();
+        return;
+    }
+    const policies = response
+        .headersArray()
+        .filter((h) => h.name.toLowerCase() === CSP_HEADER)
+        .map((h) => h.value);
+    const header = allowDaemonInCsp(policies.join(', '), origin);
+    const isHtml = /html/i.test(response.headers()['content-type'] ?? '');
+    const meta = isHtml ? allowDaemonInHtml(await response.text(), origin) : undefined;
+    if (!header.changed && true !== meta?.changed) {
+        await route.fulfill({ response });
+        return;
+    }
+    const headers = { ...response.headers() };
+    if (header.changed) {
+        headers[CSP_HEADER] = header.policy;
+    }
+    if (true === meta?.changed) {
+        // The new body is plain text: the old encoding and length describe a body that is gone.
+        delete headers['content-encoding'];
+        delete headers['content-length'];
+        await route.fulfill({ response, headers, body: meta.html });
+    }
+    else {
+        await route.fulfill({ response, headers });
+    }
+    onWidened();
+}