craftdriver 1.7.0 → 1.9.0

package/dist/lib/browserContext.js

@@ -17,8 +17,11 @@
  *   - `browser.defaultContext` — the implicit context the browser
  *     started in (id = `'default'`).
  */
-import fs from 'node:fs/promises';
+import { writeSecureFile } from './secureFile.js';
+import { CraftdriverError, ErrorCode } from './errors.js';
+import { parseSessionState, hasNonEmptySessionStorage, isStorageStateError, nonEmptyOrigins, normalizeCookieForRestore, storageStateDetail, } from './sessionStateValidation.js';
 import { Page } from './page.js';
+import { AUTH_STATE_HYDRATE_PATH, publicPageInitScript } from './initScript.js';
 export class BrowserContext {
     /** Monotonic counter for synthetic route ids returned by `route()`. */
     static _routeCounter = 0;
@@ -31,12 +34,6 @@ export class BrowserContext {
     _hooks;
     /** Per-context config (baseURL, extraHTTPHeaders). Read by Page for URL resolution. */
     _config;
-    /**
-     * Preload-script id installed by {@link loadStorageState} to write
-     * localStorage entries on first navigation to each captured origin.
-     * Tracked so a subsequent call replaces (rather than stacks) the script.
-     */
-    _localStoragePreloadId;
     /** Preload-script ids registered via {@link addInitScript}. */
     _initScriptIds = new Set();
     /**
@@ -58,6 +55,23 @@ export class BrowserContext {
      * after the `browsingContext.contextCreated` event arrives.
      */
     _notifiedPageIds = new Set();
+    /**
+     * Ids of internal (hydration) top-level contexts that must stay invisible to
+     * page tracking — never surfaced as a `'page'`, added to `_pageIds`, or given
+     * user routes/headers. See {@link _hydrateLocalStorage}.
+     */
+    _internalPageIds = new Set();
+    /**
+     * `> 0` while an internal `browsingContext.create` is awaiting its id.
+     * Top-level `contextCreated` events that arrive in that window are quarantined
+     * (the event can beat the create response), then the internal one is dropped
+     * and the rest replayed in order once the id is known.
+     */
+    _internalCreateInFlight = 0;
+    _quarantinedCreated = [];
+    _internalClassificationWaiters = new Set();
+    /** Settled tail used to serialize state overlays within this user context. */
+    _restoreTail = Promise.resolve();
     /**
      * The in-flight promise from the most recent call to {@link _ensurePageTracking}.
      * Doubles as the "is tracking armed?" flag — truthy after the first call,
@@ -103,7 +117,6 @@ export class BrowserContext {
     /** @internal Used by Page to keep preload-backed navigations on BiDi. */
     _hasInitScriptsForNavigation() {
         return (this._initScriptIds.size > 0 ||
-            this._localStoragePreloadId !== undefined ||
             this._hooks?.hasBrowserInitScripts?.() === true);
     }
     /** BiDi partition descriptor for storage operations scoped to this user context. */
@@ -146,8 +159,11 @@ export class BrowserContext {
     async pages() {
         this.assertOpen();
         const tree = await this.conn.send('browsingContext.getTree', { maxDepth: 0 });
+        // The create event can beat the command response that tells us which id is
+        // internal. Wait for that classification before exposing this tree.
+        await this._waitForInternalClassification();
         return (tree.contexts ?? [])
-            .filter((c) => c.userContext === this._id && !c.parent)
+            .filter((c) => c.userContext === this._id && !c.parent && !this._internalPageIds.has(c.context))
             .map((c) => new Page(this.driver, c.context, this.getDefaultTimeout, this.conn, this));
     }
     /**
@@ -165,7 +181,9 @@ export class BrowserContext {
         if (this._trackingPromise)
             await this._trackingPromise;
         return new Promise((resolve, reject) => {
+            let settled = false;
             const timer = setTimeout(() => {
+                settled = true;
                 off();
                 reject(new Error(`waitForPage() timed out after ${timeout}ms`));
             }, timeout);
@@ -174,11 +192,27 @@ export class BrowserContext {
                     return; // nested frames
                 if (params.userContext !== this._id)
                     return;
-                clearTimeout(timer);
-                off();
-                resolve(new Page(this.driver, params.context, this.getDefaultTimeout, this.conn, this));
+                const id = params.context;
+                void this._isInternalPageContext(id).then((internal) => {
+                    if (internal || settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    off();
+                    resolve(new Page(this.driver, id, this.getDefaultTimeout, this.conn, this));
+                }).catch((err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    off();
+                    reject(err);
+                });
             });
             action().catch((err) => {
+                if (settled)
+                    return;
+                settled = true;
                 clearTimeout(timer);
                 off();
                 reject(err);
@@ -190,8 +224,7 @@ export class BrowserContext {
      * Return cookies scoped to this user context.
      *
      * Optionally filter by URL(s): only cookies whose `domain`/`path` would
-     * be sent on a request to that URL are returned. Mirrors Playwright's
-     * `BrowserContext.cookies(urls)` shape.
+     * be sent on a request to that URL are returned.
      *
      * @example
      * ```ts
@@ -270,13 +303,12 @@ export class BrowserContext {
             partition: this.partition(),
         });
     }
-    // ── Storage state (Playwright-shape JSON) ────────────────────────────────
+    // ── Storage state (CraftDriver-native JSON) ─────────────────────────────
     /**
      * Snapshot cookies + localStorage for this context.
      *
-     * Returns `{ cookies, localStorage }` — a superset of Playwright's
-     * `storageState()` JSON shape, kept close enough that dumped files
-     * are interchangeable on a best-effort basis.
+     * Returns `{ cookies, localStorage }` in CraftDriver's native
+     * {@link SessionState} shape. It is not a cross-tool interchange format.
      *
      * **Limitation.** localStorage can only be read for origins that a page
      * in this context is currently visiting — BiDi has no out-of-band
@@ -307,59 +339,73 @@ export class BrowserContext {
      * const alice = await browser.newContext();
      * const page = await alice.newPage({ url: 'https://app.example.com/login' });
      * await loginAs(page, 'alice');
-     * await alice.saveStorageState('auth/alice.json');
+     * await alice.saveStorageState('.auth/alice.json');
      * await alice.close();
      * ```
      */
     async saveStorageState(path, opts) {
         const state = await this.storageState(opts);
-        await fs.writeFile(path, JSON.stringify(state, null, 2), 'utf-8');
+        await writeSecureFile(path, JSON.stringify(state, null, 2));
         return state;
     }
     /**
      * Apply a previously-captured snapshot to this context.
      *
      * - Cookies are written immediately.
-     * - localStorage entries are installed via a preload script that runs
-     *   on first navigation to each origin, before any page script. This
-     *   matches the way Playwright restores localStorage and survives full
-     *   reloads.
-     *
-     * Calling `loadStorageState` again replaces the previous preload
-     * script; it does not stack.
+     * - localStorage is seeded once per captured origin through a private,
+     *   intercepted same-origin document (BiDi has no "set localStorage for
+     *   origin" command). Because it runs once — not as a per-navigation
+     *   preload — the application owns the values afterward, so its own writes
+     *   survive a reload.
      *
      * @param source A `SessionState` object, or a path to a JSON file
      *   produced by {@link saveStorageState}.
      */
     async loadStorageState(source) {
+        return this._loadStorageState(source, 'BrowserContext.loadStorageState');
+    }
+    /** @internal Same public contract with an owning API name for structured errors. */
+    async _loadStorageState(source, operation) {
         this.assertOpen();
-        const state = typeof source === 'string'
-            ? JSON.parse(await fs.readFile(source, 'utf-8'))
-            : source;
-        if (state.cookies?.length) {
-            // Sanitize: a snapshot may contain cookies with sameSite:'none' and
-            // secure:false because some engines report that combo for cookies
-            // originally set via document.cookie. BiDi rejects it. Drop the
-            // sameSite field on those so the engine picks its default.
-            const sanitized = state.cookies.map((c) => {
-                if (c.sameSite === 'none' && !c.secure) {
-                    const { sameSite: _drop, ...rest } = c;
-                    return rest;
-                }
-                return c;
+        const errorContext = this._storageStateErrorContext(operation);
+        const state = await parseSessionState(source, errorContext);
+        // A context/launch restore cannot carry tab-scoped sessionStorage to the
+        // caller's future pages — reject before any mutation rather than silently
+        // dropping it. (browser.loadState() takes the active-page path for that.)
+        if (hasNonEmptySessionStorage(state)) {
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'restoring sessionStorage is not supported for context/launch APIs (it is ' +
+                'tab-scoped); use browser.loadState() after navigating to the origin', {
+                detail: storageStateDetail(errorContext, 'validation', { section: 'sessionStorage' }),
+                hint: 'Navigate to the origin and call browser.loadState(), or omit sessionStorage.',
             });
-            await this.addCookies(sanitized);
-        }
-        // Replace any previously-installed localStorage preload.
-        if (this._localStoragePreloadId) {
-            await this.conn
-                .send('script.removePreloadScript', { script: this._localStoragePreloadId })
-                .catch(() => { });
-            this._localStoragePreloadId = undefined;
-        }
-        if (state.localStorage && Object.keys(state.localStorage).length > 0) {
-            this._localStoragePreloadId = await this.installLocalStoragePreload(state.localStorage);
         }
+        await this._runSerializedRestore(async () => {
+            let partialApplied = false;
+            // localStorage first — its private hydration page is where a restore failure
+            // would surface; applying cookies last means a hydration failure never
+            // leaves cookies behind.
+            if (nonEmptyOrigins(state.localStorage).length > 0) {
+                try {
+                    partialApplied = await this._hydrateLocalStorage(state.localStorage, errorContext);
+                }
+                catch (err) {
+                    if (isStorageStateError(err))
+                        throw err;
+                    throw this._restoreDriverError(err, errorContext, 'localStorage', partialApplied);
+                }
+            }
+            if (state.cookies?.length) {
+                for (const captured of state.cookies) {
+                    try {
+                        await this.addCookies([normalizeCookieForRestore(captured)]);
+                        partialApplied = true;
+                    }
+                    catch (err) {
+                        throw this._restoreDriverError(err, errorContext, 'cookies', partialApplied);
+                    }
+                }
+            }
+        });
     }
     /**
      * Remove this user context. All of its pages are closed and any
@@ -381,12 +427,6 @@ export class BrowserContext {
             await this.conn.send('script.removePreloadScript', { script: id }).catch(() => { });
         }
         this._initScriptIds.clear();
-        if (this._localStoragePreloadId) {
-            await this.conn
-                .send('script.removePreloadScript', { script: this._localStoragePreloadId })
-                .catch(() => { });
-            this._localStoragePreloadId = undefined;
-        }
         if (this._hooks && this._routes.size > 0) {
             const net = this._hooks.getNetwork();
             for (const entry of this._routes.values()) {
@@ -402,6 +442,8 @@ export class BrowserContext {
             off();
         this._trackingOffs = [];
         this._trackingPromise = undefined;
+        this._internalPageIds.clear();
+        this._resolveInternalClassificationWaiters();
         await this.conn.send('browser.removeUserContext', { userContext: this._id });
         this._closed = true;
         // Fire close listeners last, after the context is fully gone.
@@ -454,7 +496,7 @@ export class BrowserContext {
         this.assertOpen();
         const fnDecl = typeof script === 'function' ? script.toString() : `() => { ${script} }`;
         const result = await this.conn.send('script.addPreloadScript', {
-            functionDeclaration: fnDecl,
+            functionDeclaration: publicPageInitScript(fnDecl),
             userContexts: [this._id],
         });
         this._initScriptIds.add(result.script);
@@ -757,35 +799,197 @@ export class BrowserContext {
         return byOrigin;
     }
     /**
-     * Install a preload script (scoped to this user context) that, on first
-     * navigation to each captured origin, writes the localStorage entries
-     * before any page script runs.
+     * Seed localStorage for each captured origin exactly once.
+     *
+     * BiDi has no command to set localStorage for an arbitrary origin, so we
+     * visit each origin in a throwaway top-level context whose navigation is
+     * fulfilled locally (never reaching the network), write the entries, and
+     * close it. Unlike a preload script this runs once — the application owns the
+     * values afterward, so its own writes survive a reload.
+     *
+     * The private context is created at the connection level (not via `newPage`),
+     * so it never enters `_pageIds`, the `'page'` event, routes, or active-page
+     * selection. The intercept is scoped to it, and navigation is forced onto
+     * BiDi — a Classic-initiated navigation would stall against a BiDi intercept.
      */
-    async installLocalStoragePreload(localStorage) {
-        // Serialize the origin → entries map into the function body. Safe because
-        // we control the JSON shape (strings only).
-        const payload = JSON.stringify(localStorage);
-        const fnSrc = `() => {
-      try {
-        const data = ${payload};
-        const entries = data[location.origin];
-        if (!entries) return;
-        for (const k in entries) {
-          try { window.localStorage.setItem(k, entries[k]); } catch (e) { /* quota / opaque origin */ }
-        }
-      } catch (e) { /* never break user pages */ }
-    }`;
-        const result = await this.conn.send('script.addPreloadScript', {
-            functionDeclaration: fnSrc,
-            userContexts: [this._id],
+    async _hydrateLocalStorage(byOrigin, errorContext) {
+        const origins = Object.keys(byOrigin).filter((o) => byOrigin[o] && Object.keys(byOrigin[o]).length > 0);
+        if (origins.length === 0)
+            return false;
+        const net = this._hooks?.getNetwork();
+        if (!net) {
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'restoring localStorage requires a BiDi session with network interception', { detail: storageStateDetail(errorContext, 'setup', { section: 'localStorage' }) });
+        }
+        // Reserve the internal-context slot before the create so page tracking hides
+        // it even if its contextCreated event beats the create response.
+        this._internalCreateInFlight++;
+        let privId;
+        try {
+            const created = await this.conn.send('browsingContext.create', {
+                type: 'tab',
+                userContext: this._id,
+            });
+            privId = created.context;
+            this._internalPageIds.add(privId);
+        }
+        catch (err) {
+            throw this._restoreDriverError(err, errorContext, 'localStorage', false);
+        }
+        finally {
+            this._internalCreateInFlight--;
+            this._drainQuarantine();
+            this._resolveInternalClassificationWaiters();
+        }
+        if (!privId)
+            return false;
+        const priv = new Page(this.driver, privId, this.getDefaultTimeout, this.conn, this);
+        let interceptId;
+        let partialApplied = false;
+        try {
+            // Fulfil this private context's top-level navigations with a minimal
+            // document, locally — the request never reaches the network. The pattern
+            // is specific (a bare `**/*` does not register a working intercept): only
+            // this context's deterministic hydrate URL is fulfilled, and the intercept
+            // is scoped to `privId`, so no user page is ever touched.
+            interceptId = await net.intercept(`**${AUTH_STATE_HYDRATE_PATH}*`, () => ({
+                status: 200,
+                headers: { 'content-type': 'text/html' },
+                body: '<!doctype html><html><head></head><body></body></html>',
+            }), ['beforeRequestSent'], [privId], { strict: true } // never let a hydration request reach the real network
+            );
+            for (const origin of origins) {
+                // The path is fixed and irrelevant — the intercept fulfils it locally.
+                // `domcontentloaded` forces the BiDi navigate path so the intercept
+                // applies (a default-context Classic `load` navigation would stall).
+                await priv.navigateTo(`${origin}${AUTH_STATE_HYDRATE_PATH}`, {
+                    waitUntil: 'domcontentloaded',
+                });
+                // Confirm the realm is on the requested origin (an HSTS upgrade or other
+                // rewrite could land elsewhere), then write the entries in one call. The
+                // values travel as structured string arguments — never interpolated into
+                // the source; the source is a string, so the DOM globals it names are the
+                // browser's, not Node's.
+                const res = await this.conn.send('script.callFunction', {
+                    functionDeclaration: 'function (expected, json) {' +
+                        ' if (location.origin !== expected) return "MISMATCH:" + location.origin;' +
+                        ' var e = JSON.parse(json);' +
+                        ' for (var k in e) localStorage.setItem(k, e[k]);' +
+                        ' return "OK"; }',
+                    target: { context: privId },
+                    arguments: [
+                        { type: 'string', value: origin },
+                        { type: 'string', value: JSON.stringify(byOrigin[origin]) },
+                    ],
+                    awaitPromise: false,
+                });
+                const value = res.type === 'success' ? res.result?.value : undefined;
+                if (value !== 'OK') {
+                    const mismatch = new CraftdriverError(ErrorCode.STATE_INVALID, `could not hydrate localStorage for origin ${origin}`, { detail: storageStateDetail(errorContext, 'localStorage', { origin }) });
+                    if (!partialApplied)
+                        throw mismatch;
+                    throw this._restoreDriverError(mismatch, errorContext, 'localStorage', true, { origin });
+                }
+                partialApplied = true;
+            }
+            return partialApplied;
+        }
+        catch (err) {
+            if (isStorageStateError(err))
+                throw err;
+            throw this._restoreDriverError(err, errorContext, 'localStorage', partialApplied);
+        }
+        finally {
+            if (interceptId)
+                await net.removeIntercept(interceptId).catch(() => { });
+            await this.conn.send('browsingContext.close', { context: privId }).catch(() => { });
+        }
+    }
+    /** @internal Serialize restores without coupling independent user contexts. */
+    _runSerializedRestore(task) {
+        const run = this._restoreTail.then(task, task);
+        this._restoreTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** @internal Synchronous filter for events emitted after an internal id is known. */
+    _isInternalPageId(id) {
+        return typeof id === 'string' && this._internalPageIds.has(id);
+    }
+    /** @internal Wait through the create-response race, then classify an event id. */
+    async _isInternalPageContext(id) {
+        await this._waitForInternalClassification();
+        return this._internalPageIds.has(id);
+    }
+    _waitForInternalClassification() {
+        if (this._internalCreateInFlight === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => this._internalClassificationWaiters.add(resolve));
+    }
+    _resolveInternalClassificationWaiters() {
+        if (this._internalCreateInFlight !== 0)
+            return;
+        for (const resolve of this._internalClassificationWaiters)
+            resolve();
+        this._internalClassificationWaiters.clear();
+    }
+    _storageStateErrorContext(operation) {
+        return {
+            operation,
+            browserName: this._hooks?.getBrowserName?.() ?? 'unknown',
+            protocol: 'bidi',
+        };
+    }
+    _restoreDriverError(cause, context, phase, partialApplied, extra) {
+        return new CraftdriverError(ErrorCode.DRIVER_ERROR, `storage state restore failed while applying ${phase}`, {
+            cause,
+            detail: storageStateDetail(context, phase, { partialApplied, ...extra }),
+            hint: partialApplied
+                ? 'Restore into a fresh browser context when failure isolation is required.'
+                : undefined,
         });
-        return result.script;
     }
     /**
      * Subscribe (once) to BiDi page-creation / page-destruction events and
      * seed `_pageIds` with currently-open pages in this context. Powers
      * both the `'page'` event and route membership filtering.
      */
+    /** Apply the normal new-page handling (tracking, headers, routes, the `'page'`
+     *  event) for a real top-level context. */
+    _handleContextCreated(id) {
+        this._pageIds.add(id);
+        // Headers must be applied before the first request from this page.
+        this._applyExtraHeadersTo([id]).catch(() => { });
+        // Register every existing route on the new page.
+        for (const sid of this._routes.keys()) {
+            this._registerRouteOnPage(sid, id).catch(() => { });
+        }
+        // Notify page listeners exactly once per page.
+        if (this._notifiedPageIds.has(id))
+            return;
+        this._notifiedPageIds.add(id);
+        if (this._pageListeners.size > 0) {
+            const page = new Page(this.driver, id, this.getDefaultTimeout, this.conn, this);
+            for (const fn of this._pageListeners) {
+                try {
+                    fn(page);
+                }
+                catch { /* listener errors must not break events */ }
+            }
+        }
+    }
+    /** Replay contextCreated events buffered during an internal create, once none
+     *  is in flight — dropping any that turned out to be internal. */
+    _drainQuarantine() {
+        if (this._internalCreateInFlight > 0)
+            return;
+        const buffered = this._quarantinedCreated;
+        this._quarantinedCreated = [];
+        for (const params of buffered) {
+            const id = params.context;
+            if (this._internalPageIds.has(id))
+                continue; // internal → stay hidden
+            this._handleContextCreated(id);
+        }
+    }
     _ensurePageTracking() {
         if (this._closed)
             return Promise.resolve();
@@ -805,31 +1009,25 @@ export class BrowserContext {
             if (params.userContext !== this._id)
                 return;
             const id = params.context;
-            this._pageIds.add(id);
-            // Headers must be applied before the first request from this page.
-            this._applyExtraHeadersTo([id]).catch(() => { });
-            // Register every existing route on the new page.
-            for (const sid of this._routes.keys()) {
-                this._registerRouteOnPage(sid, id).catch(() => { });
-            }
-            // Notify page listeners exactly once per page.
-            if (this._notifiedPageIds.has(id))
+            // Internal hydration context — stays invisible to page tracking.
+            if (this._internalPageIds.has(id))
+                return;
+            // Its id may not be known yet (the event can beat the create response):
+            // quarantine every top-level create in this context while one is in
+            // flight, then drop the internal one and replay the rest.
+            if (this._internalCreateInFlight > 0) {
+                this._quarantinedCreated.push(params);
                 return;
-            this._notifiedPageIds.add(id);
-            if (this._pageListeners.size > 0) {
-                const page = new Page(this.driver, id, this.getDefaultTimeout, this.conn, this);
-                for (const fn of this._pageListeners) {
-                    try {
-                        fn(page);
-                    }
-                    catch { /* listener errors must not break events */ }
-                }
             }
+            this._handleContextCreated(id);
         };
         const onDestroyed = (params) => {
             if (params.parent)
                 return;
             const id = params.context;
+            if (this._internalPageIds.has(id)) {
+                return; // internal hydration context — never tracked, nothing to tear down
+            }
             this._pageIds.delete(id);
             this._notifiedPageIds.delete(id);
             // Tear down any per-page intercepts registered against this page.
@@ -853,8 +1051,11 @@ export class BrowserContext {
         // miss a contextCreated event that races with this seeding.
         try {
             const tree = await this.conn.send('browsingContext.getTree', { maxDepth: 0 });
+            await this._waitForInternalClassification();
             for (const c of tree.contexts ?? []) {
-                if (c.userContext === this._id && !c.parent) {
+                if (c.userContext === this._id &&
+                    !c.parent &&
+                    !this._internalPageIds.has(c.context)) {
                     this._pageIds.add(c.context);
                 }
             }