@push.rocks/smartpuppeteer 2.2.0 → 2.3.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -1,4 +1,13 @@
 import { getEnvAwareBrowserInstance } from './smartpuppeteer.classes.smartpuppeteer.js';
+import {
+  delay,
+  type IOwnedProcessIdentity,
+  killFrozenOwnedProcessGroup,
+  listOwnedProcessGroupMembers,
+  readOwnedProcessIdentity,
+  signalOwnedProcessIdentity,
+  signalOwnedProcessGroup,
+} from './smartpuppeteer.helpers.process.js';
 import type {
   ILiveBrowserClickOptions,
   ILiveBrowserCreateTabOptions,
@@ -18,11 +27,14 @@ import type {
   ILiveBrowserObserveOptions,
   ILiveBrowserOperationOptions,
   ILiveBrowserPressOptions,
+  ILiveBrowserProcessState,
   ILiveBrowserSessionOptions,
   ILiveBrowserSnapshot,
   ILiveBrowserSnapshotOptions,
   ILiveBrowserState,
   ILiveBrowserTabState,
+  ILiveBrowserTerminationOptions,
+  ILiveBrowserTerminationResult,
   ILiveBrowserViewport,
   ILiveBrowserWheelInput,
   TLiveBrowserEvent,
@@ -60,10 +72,52 @@ const maxEvaluationObjectKeys = 10000;
 const evaluationBootstrapKey = '__smartpuppeteerEvaluate';
 const evaluationCancelKey = '__smartpuppeteerCancel';
 const evaluationCleanupKey = '__smartpuppeteerCleanup';
+const maxProxySecuritySessions = 256;
+const maxTrackedProxyRequests = 1024;
+const maxTotalTrackedProxyRequests = 4096;
+const maxProxySecurityOperations = 2048;
+const proxySeedTargetTypes = new Set([
+  'background_page',
+  'page',
+  'service_worker',
+  'shared_worker',
+  'webview',
+]);
+const proxyFetchUnsupportedTargetTypes = new Set(['tab', 'worker']);
 
 type TScreencastFrameEvent = plugins.puppeteer.Protocol.Page.ScreencastFrameEvent;
 type TScreencastFrameListener = (event: TScreencastFrameEvent) => void;
 type TCdpSessionDetachedListener = (session: plugins.puppeteer.CDPSession) => void;
+type TOwnedChildProcess = NonNullable<ReturnType<plugins.puppeteer.Browser['process']>>;
+type TProxyAuthRequiredEvent = plugins.puppeteer.Protocol.Fetch.AuthRequiredEvent;
+type TProxyRequestPausedEvent = plugins.puppeteer.Protocol.Fetch.RequestPausedEvent;
+type TNetworkLoadingFinishedEvent = plugins.puppeteer.Protocol.Network.LoadingFinishedEvent;
+type TNetworkLoadingFailedEvent = plugins.puppeteer.Protocol.Network.LoadingFailedEvent;
+
+interface IProxySecuritySession {
+  session: plugins.puppeteer.CDPSession;
+  generation: number;
+  targetId?: string;
+  targetType?: string;
+  fetchEnabled: boolean;
+  allowLiveTargetDetach: boolean;
+  ownedByProxySecurity: boolean;
+  attemptedAuthentications: Set<string>;
+  requestIdsByNetworkId: Map<string, string>;
+  authRequiredListener: (event: TProxyAuthRequiredEvent) => void;
+  requestPausedListener: (event: TProxyRequestPausedEvent) => void;
+  loadingFinishedListener: (event: TNetworkLoadingFinishedEvent) => void;
+  loadingFailedListener: (event: TNetworkLoadingFailedEvent) => void;
+  setupPromise: Promise<void>;
+}
+
+interface IOwnedBrowserProcess {
+  generation: number;
+  childProcess: TOwnedChildProcess;
+  identity?: IOwnedProcessIdentity;
+  exitPromise: Promise<void>;
+  forceSignalled: boolean;
+}
 
 interface IPrivateLiveBrowserTab {
   id: string;
@@ -318,6 +372,20 @@ export class LiveBrowserSession {
   private browserContext?: plugins.puppeteer.BrowserContext;
   private browserLifetimeController?: AbortController;
   private browserDisconnectedListener?: () => void;
+  private browserTargetCreatedListener?: (target: plugins.puppeteer.Target) => void;
+  private browserSecurityCdpSession?: plugins.puppeteer.CDPSession;
+  private browserSecurityConnection?: plugins.puppeteer.Connection;
+  private browserSecuritySessionAttachedListener?: (session: plugins.puppeteer.CDPSession) => void;
+  private browserSecuritySessionDetachedListener?: TCdpSessionDetachedListener;
+  private readonly proxySecuritySessions = new Map<string, IProxySecuritySession>();
+  private readonly proxySecurityOperations = new Set<Promise<void>>();
+  private proxySecurityGeneration = 0;
+  private proxySecurityStopping = false;
+  private ownedBrowserProcess?: IOwnedBrowserProcess;
+  private processGeneration = 0;
+  private startRequestCount = 0;
+  private terminationSettled = true;
+  private terminationPromise?: Promise<ILiveBrowserTerminationResult>;
   private readonly operationQueue: IQueuedOperation[] = [];
   private activeOperation?: IQueuedOperation;
   private operationRunning = false;
@@ -351,8 +419,31 @@ export class LiveBrowserSession {
       throw new Error('LiveBrowserSession owns launch cancellation; launchOptions.signal is unsupported');
     }
     validateOptionalBoolean(optionsArg.allowEvaluation, 'allowEvaluation');
-    for (const [name, value] of Object.entries(optionsArg.security ?? {})) {
-      validateOptionalBoolean(value, `security.${name}`);
+    for (const name of [
+      'denyDownloads',
+      'denyFileChoosers',
+      'denyPermissions',
+      'httpNavigationOnly',
+    ] as const) {
+      validateOptionalBoolean(optionsArg.security?.[name], `security.${name}`);
+    }
+    const proxyCredentials = optionsArg.security?.proxyCredentials;
+    if (proxyCredentials !== undefined) {
+      if (!proxyCredentials || typeof proxyCredentials !== 'object') {
+        throw new Error('security.proxyCredentials must be an object');
+      }
+      validateBoundedString(
+        proxyCredentials.username,
+        'security.proxyCredentials.username',
+        1,
+        256,
+      );
+      validateBoundedString(
+        proxyCredentials.password,
+        'security.proxyCredentials.password',
+        1,
+        1024,
+      );
     }
     const launchViewport = optionsArg.launchOptions?.defaultViewport;
     const viewport = normalizeViewport(
@@ -377,7 +468,12 @@ export class LiveBrowserSession {
       },
       viewport,
       screencast: optionsArg.screencast ? { ...optionsArg.screencast } : undefined,
-      security: optionsArg.security ? { ...optionsArg.security } : undefined,
+      security: optionsArg.security
+        ? {
+            ...optionsArg.security,
+            proxyCredentials: proxyCredentials ? { ...proxyCredentials } : undefined,
+          }
+        : undefined,
     };
     this.viewport = { ...viewport };
     this.validateScreencastOptions();
@@ -404,12 +500,86 @@ export class LiveBrowserSession {
     };
   }
 
-  public async start(operationOptions: ILiveBrowserOperationOptions = {}): Promise<void> {
-    return this.enqueuePublicOperation(async (signal) => {
+  public getProcessState(): ILiveBrowserProcessState {
+    const ownedProcess = this.ownedBrowserProcess;
+    if (!ownedProcess) {
+      return {
+        generation: this.processGeneration,
+        pid: null,
+        processGroupId: null,
+        running: false,
+        exitCode: null,
+        signalCode: null,
+      };
+    }
+    const childProcess = ownedProcess.childProcess;
+    return {
+      generation: ownedProcess.generation,
+      pid: childProcess.pid ?? null,
+      processGroupId: ownedProcess.identity?.processGroupId ?? null,
+      running: childProcess.exitCode === null && childProcess.signalCode === null,
+      exitCode: childProcess.exitCode,
+      signalCode: childProcess.signalCode,
+    };
+  }
+
+  public terminate(
+    optionsArg: ILiveBrowserTerminationOptions = {},
+  ): Promise<ILiveBrowserTerminationResult> {
+    if (this.terminationPromise) {
+      return this.terminationPromise;
+    }
+    const gracefulTimeoutMs = optionsArg.gracefulTimeoutMs === undefined
+      ? 5000
+      : validateInteger(optionsArg.gracefulTimeoutMs, 'gracefulTimeoutMs', 1, 60000);
+    const forceTimeoutMs = optionsArg.forceTimeoutMs === undefined
+      ? 5000
+      : validateInteger(optionsArg.forceTimeoutMs, 'forceTimeoutMs', 1, 60000);
+    let resolveTermination!: (result: ILiveBrowserTerminationResult) => void;
+    let rejectTermination!: (error: unknown) => void;
+    const terminationPromise = new Promise<ILiveBrowserTerminationResult>((resolve, reject) => {
+      resolveTermination = resolve;
+      rejectTermination = reject;
+    });
+    this.terminationPromise = terminationPromise;
+    this.terminationSettled = false;
+    void this.terminateInternal(gracefulTimeoutMs, forceTimeoutMs).then(
+      (result) => {
+        this.terminationSettled = true;
+        resolveTermination(result);
+      },
+      (error) => {
+        if (this.terminationPromise === terminationPromise) {
+          this.terminationPromise = undefined;
+        }
+        this.terminationSettled = true;
+        rejectTermination(error);
+      },
+    );
+    return terminationPromise;
+  }
+
+  public start(operationOptions: ILiveBrowserOperationOptions = {}): Promise<void> {
+    if (!this.terminationSettled) {
+      return Promise.reject(new Error('A browser termination is still in progress'));
+    }
+    if (!this.ownedBrowserProcess && this.status === 'stopped') {
+      this.terminationPromise = undefined;
+    }
+    this.startRequestCount += 1;
+    const startPromise = this.enqueuePublicOperation(async (signal) => {
       if (this.status === 'running' || this.status === 'starting') {
         return;
       }
 
+      await this.releaseExitedOwnedProcess();
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      if (this.ownedBrowserProcess) {
+        throw new Error('A previous owned Chromium process has not been confirmed dead');
+      }
+
       this.normalStopRequested = false;
       this.lastError = undefined;
       this.viewportRevision = 1;
@@ -445,10 +615,56 @@ export class LiveBrowserSession {
         } finally {
           signal.removeEventListener('abort', abortBrowserLaunch);
         }
+        const childProcess = this.browser.process();
+        if (!childProcess?.pid) {
+          throw new Error('LiveBrowserSession did not receive an owned Chromium process');
+        }
+        const exitPromise = new Promise<void>((resolve) => {
+          if (childProcess.exitCode !== null || childProcess.signalCode !== null) {
+            resolve();
+            return;
+          }
+          childProcess.once('exit', () => resolve());
+        });
+        this.processGeneration += 1;
+        this.ownedBrowserProcess = {
+          generation: this.processGeneration,
+          childProcess,
+          exitPromise,
+          forceSignalled: false,
+        };
+        const identity = process.platform === 'linux'
+          ? await readOwnedProcessIdentity(childProcess.pid)
+          : undefined;
+        if (process.platform === 'linux' && !identity) {
+          throw new Error('The owned Chromium process exited before its identity was captured');
+        }
+        if (
+          identity
+          && (identity.processGroupId !== childProcess.pid || identity.sessionId !== childProcess.pid)
+        ) {
+          throw new Error('Chromium was not launched as a dedicated process-group leader');
+        }
+        this.ownedBrowserProcess.identity = identity;
         if (signal.aborted) {
           throw signal.reason;
         }
         this.browserContext = this.browser.defaultBrowserContext();
+        this.browserTargetCreatedListener = (target) => {
+          if (target.type() !== 'page' || target.browserContext() !== this.browserContext) {
+            return;
+          }
+          void target.page().then((page) => {
+            if (page) {
+              this.scheduleDiscoveredPageRegistration(page);
+            }
+          }).catch((error) => {
+            if (!this.normalStopRequested && this.status !== 'stopped' && this.status !== 'stopping') {
+              this.handleDiscoveredPageFailure(error);
+            }
+          });
+        };
+        this.browser.on('targetcreated', this.browserTargetCreatedListener);
         await this.configureBrowserSecurity(this.browser);
         this.browserDisconnectedListener = () => {
           if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
@@ -497,7 +713,14 @@ export class LiveBrowserSession {
         }
       } catch (error) {
         if (signal.aborted || this.normalStopRequested) {
-          await this.stopInternal();
+          try {
+            await this.stopInternal();
+          } catch (cleanupError) {
+            throw new AggregateError(
+              [error, cleanupError],
+              'Cancelled browser startup cleanup was incomplete',
+            );
+          }
           throw error;
         }
         const startError: ILiveBrowserError = {
@@ -506,10 +729,20 @@ export class LiveBrowserSession {
           fatal: true,
         };
         this.emitError(startError);
-        await this.stopInternal(startError);
+        try {
+          await this.stopInternal(startError);
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'Browser startup failed and cleanup was incomplete',
+          );
+        }
         throw error;
       }
     }, operationOptions);
+    return startPromise.finally(() => {
+      this.startRequestCount -= 1;
+    });
   }
 
   public async stop(): Promise<void> {
@@ -1070,6 +1303,7 @@ export class LiveBrowserSession {
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.resolveActionTab(optionsArg.tabId);
       const cdpSession = await tab.page.createCDPSession();
+      this.allowOperationalCdpSessionDetach(cdpSession);
       let executionContextId: number | undefined;
       let cancellationPromise: Promise<void> | undefined;
       let terminationPromise: Promise<void> | undefined;
@@ -1346,7 +1580,25 @@ export class LiveBrowserSession {
       return Promise.reject(new Error('LiveBrowserSession operation queue is full'));
     }
     this.admittedPublicOperations += 1;
-    return this.enqueueQueuedOperation('public', operation, false, callerSignal);
+    return this.enqueueQueuedOperation('public', async (signal) => {
+      this.assertProxySecurityReady();
+      return operation(signal);
+    }, false, callerSignal);
+  }
+
+  private assertProxySecurityReady(): void {
+    if (!this.options.security?.proxyCredentials || this.status !== 'running') {
+      return;
+    }
+    if (
+      !this.browserSecurityConnection
+      || !this.browserSecurityCdpSession
+      || this.browserSecurityCdpSession.detached
+    ) {
+      const error = new Error('Authenticated proxy security is not attached');
+      this.handleProxySecurityFailure('proxy_security_unavailable', error);
+      throw error;
+    }
   }
 
   private enqueueInternalOperation(
@@ -1509,7 +1761,8 @@ export class LiveBrowserSession {
   }
 
   private requestShutdown(error?: ILiveBrowserError): Promise<void> {
-    if (this.status === 'stopped') {
+    if (this.status === 'stopped' && !this.operationRunning && this.startRequestCount === 0) {
+      this.normalStopRequested = false;
       return Promise.resolve();
     }
     if (this.shutdownPromise) {
@@ -1622,6 +1875,248 @@ export class LiveBrowserSession {
     };
   }
 
+  private async releaseExitedOwnedProcess(): Promise<void> {
+    const ownedProcess = this.ownedBrowserProcess;
+    if (!ownedProcess) {
+      return;
+    }
+    if (
+      ownedProcess.childProcess.exitCode === null
+      && ownedProcess.childProcess.signalCode === null
+    ) {
+      await Promise.race([ownedProcess.exitPromise, delay(100)]);
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        return;
+      }
+    }
+    if (process.platform === 'linux' && !ownedProcess.identity) {
+      return;
+    }
+    if (ownedProcess.identity) {
+      const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (members.length > 0) {
+        return;
+      }
+    }
+    this.ownedBrowserProcess = undefined;
+  }
+
+  private async terminateInternal(
+    gracefulTimeoutMs: number,
+    forceTimeoutMs: number,
+  ): Promise<ILiveBrowserTerminationResult> {
+    const errors: string[] = [];
+    let shutdownSettled = this.status === 'stopped';
+    const shutdownObserved = this.stop().then(
+      () => {
+        shutdownSettled = true;
+      },
+      (error) => {
+        errors.push(normalizeErrorMessage(error));
+        shutdownSettled = true;
+      },
+    );
+    const createConfirmedResult = (
+      ownedProcess: IOwnedBrowserProcess | undefined,
+      forced: boolean,
+    ): ILiveBrowserTerminationResult => {
+      const childProcess = ownedProcess?.childProcess;
+      const result: ILiveBrowserTerminationResult = {
+        generation: ownedProcess?.generation ?? this.processGeneration,
+        pid: childProcess?.pid ?? null,
+        processGroupId: ownedProcess?.identity?.processGroupId ?? null,
+        running: false,
+        exitCode: childProcess?.exitCode ?? null,
+        signalCode: childProcess?.signalCode ?? null,
+        forced: forced || Boolean(ownedProcess?.forceSignalled),
+        shutdownComplete: true,
+        confirmedDead: true,
+        errors,
+      };
+      if (this.ownedBrowserProcess === ownedProcess) {
+        this.ownedBrowserProcess = undefined;
+      }
+      return result;
+    };
+    const isConfirmedDead = async (
+      ownedProcess: IOwnedBrowserProcess | undefined,
+    ): Promise<boolean> => {
+      if (!ownedProcess) {
+        return true;
+      }
+      if (process.platform !== 'linux' || !ownedProcess.identity) {
+        if (process.platform === 'linux' && this.startRequestCount > 0) {
+          return false;
+        }
+        throw new Error('Confirmed browser process-group termination is supported on Linux only');
+      }
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        return false;
+      }
+      const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (members.length > 0) {
+        return false;
+      }
+      return true;
+    };
+
+    const gracefulDeadline = Date.now() + gracefulTimeoutMs;
+    while (Date.now() < gracefulDeadline) {
+      const ownedProcess = this.ownedBrowserProcess;
+      if (
+        await isConfirmedDead(ownedProcess)
+        && shutdownSettled
+        && this.status === 'stopped'
+      ) {
+        return createConfirmedResult(ownedProcess, false);
+      }
+      if (shutdownSettled) {
+        await delay(100);
+      } else {
+        await Promise.race([shutdownObserved, delay(100)]);
+      }
+    }
+
+    const ownedProcess = this.ownedBrowserProcess;
+    let forced = false;
+    if (ownedProcess) {
+      if (process.platform !== 'linux') {
+        throw new Error('Confirmed browser process-group termination is supported on Linux only');
+      }
+      if (ownedProcess.identity) {
+        const membersBeforeFreeze = await listOwnedProcessGroupMembers(ownedProcess.identity);
+        if (membersBeforeFreeze.length > 0) {
+          forced = true;
+          const groupStopped = await signalOwnedProcessGroup(ownedProcess.identity, 'SIGSTOP');
+          if (groupStopped) {
+            killFrozenOwnedProcessGroup(ownedProcess.identity);
+          } else {
+            await this.killOwnedProcessGroupSurvivors(ownedProcess.identity, membersBeforeFreeze);
+          }
+        }
+      } else if (this.startRequestCount === 0) {
+        throw new Error('Owned Chromium process identity was never confirmed');
+      }
+    }
+
+    const forceDeadline = Date.now() + forceTimeoutMs;
+    while (Date.now() < forceDeadline) {
+      const currentOwnedProcess = this.ownedBrowserProcess;
+      if (
+        await isConfirmedDead(currentOwnedProcess)
+        && shutdownSettled
+        && this.status === 'stopped'
+      ) {
+        return createConfirmedResult(currentOwnedProcess, forced);
+      }
+      if (shutdownSettled) {
+        await delay(100);
+      } else {
+        await Promise.race([shutdownObserved, delay(100)]);
+      }
+    }
+
+    const remainingOwnedProcess = this.ownedBrowserProcess;
+    if (remainingOwnedProcess?.identity) {
+      const survivors = await listOwnedProcessGroupMembers(remainingOwnedProcess.identity);
+      if (survivors.length > 0) {
+        throw new Error(
+          `Owned Chromium process group did not terminate: ${survivors.map((item) => item.pid).join(', ')}`,
+        );
+      }
+    }
+    if (!shutdownSettled || this.status !== 'stopped') {
+      throw new Error(
+        'Owned Chromium process group exited but LiveBrowserSession shutdown did not settle',
+      );
+    }
+    throw new Error('Owned Chromium process exit was not confirmed by Node.js');
+  }
+
+  private async killOwnedProcessGroupSurvivors(
+    rootIdentity: IOwnedProcessIdentity,
+    initialMembers: IOwnedProcessIdentity[],
+  ): Promise<void> {
+    let previousKeys = new Set(initialMembers.map((member) => `${member.pid}:${member.startTime}`));
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      const members = await listOwnedProcessGroupMembers(rootIdentity);
+      if (members.length === 0) {
+        return;
+      }
+      for (const member of members) {
+        await signalOwnedProcessIdentity(member, 'SIGSTOP');
+      }
+      await delay(10);
+      const frozenMembers = await listOwnedProcessGroupMembers(rootIdentity);
+      const currentKeys = new Set(
+        frozenMembers.map((member) => `${member.pid}:${member.startTime}`),
+      );
+      const sameMembers = currentKeys.size === previousKeys.size
+        && [...currentKeys].every((key) => previousKeys.has(key));
+      const allFrozen = frozenMembers.every((member) => (
+        member.state === 'T' || member.state === 't' || member.state === 'Z'
+      ));
+      if (sameMembers && allFrozen) {
+        for (const member of frozenMembers) {
+          await signalOwnedProcessIdentity(member, 'SIGKILL');
+        }
+        return;
+      }
+      previousKeys = currentKeys;
+    }
+    throw new Error('Unable to stabilize the surviving Chromium process group');
+  }
+
+  private async forceOwnedBrowserProcessGroup(
+    ownedProcess: IOwnedBrowserProcess,
+  ): Promise<void> {
+    ownedProcess.forceSignalled = true;
+    if (process.platform !== 'linux') {
+      ownedProcess.childProcess.kill('SIGKILL');
+      await Promise.race([ownedProcess.exitPromise, delay(5000)]);
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        throw new Error('Owned Chromium process did not exit after SIGKILL');
+      }
+      return;
+    }
+    if (!ownedProcess.identity) {
+      throw new Error('Owned Chromium process identity was never confirmed');
+    }
+    const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+    if (members.length > 0) {
+      const groupStopped = await signalOwnedProcessGroup(ownedProcess.identity, 'SIGSTOP');
+      if (groupStopped) {
+        killFrozenOwnedProcessGroup(ownedProcess.identity);
+      } else {
+        await this.killOwnedProcessGroupSurvivors(ownedProcess.identity, members);
+      }
+    }
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+      const survivors = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (survivors.length === 0) {
+        await Promise.race([ownedProcess.exitPromise, delay(100)]);
+        if (
+          ownedProcess.childProcess.exitCode !== null
+          || ownedProcess.childProcess.signalCode !== null
+        ) {
+          return;
+        }
+      }
+      await delay(100);
+    }
+    throw new Error('Owned Chromium process group survived forced startup cleanup');
+  }
+
   private async stopInternal(error?: ILiveBrowserError): Promise<void> {
     if (this.status === 'stopped') {
       return;
@@ -1636,12 +2131,21 @@ export class LiveBrowserSession {
     }
 
     const browser = this.browser;
+    if (browser && this.browserTargetCreatedListener) {
+      browser.off('targetcreated', this.browserTargetCreatedListener);
+    }
+    this.browserTargetCreatedListener = undefined;
     if (browser && this.browserDisconnectedListener) {
       browser.off('disconnected', this.browserDisconnectedListener);
     }
     this.browserDisconnectedListener = undefined;
 
     const shutdownErrors: unknown[] = [];
+    try {
+      await this.teardownProxySecurity();
+    } catch (cleanupError) {
+      shutdownErrors.push(cleanupError);
+    }
     for (const tab of [...this.tabs.values()]) {
       tab.closing = true;
       const securityCdpSession = tab.securityCdpSession;
@@ -1675,6 +2179,14 @@ export class LiveBrowserSession {
         await browser.close();
       } catch (closeError) {
         shutdownErrors.push(closeError);
+        const ownedProcess = this.ownedBrowserProcess;
+        if (ownedProcess) {
+          try {
+            await this.forceOwnedBrowserProcessGroup(ownedProcess);
+          } catch (forceError) {
+            shutdownErrors.push(forceError);
+          }
+        }
       }
     }
 
@@ -1689,7 +2201,7 @@ export class LiveBrowserSession {
     this.activeTabId = null;
     this.status = 'stopped';
     this.emitState();
-    if (shutdownErrors.length > 0 && !error) {
+    if (shutdownErrors.length > 0) {
       throw new AggregateError(shutdownErrors, 'LiveBrowserSession shutdown was incomplete');
     }
   }
@@ -1697,17 +2209,442 @@ export class LiveBrowserSession {
   private async configureBrowserSecurity(
     browser: plugins.puppeteer.Browser,
   ): Promise<void> {
-    if (!this.options.security?.denyPermissions) {
+    const denyPermissions = this.options.security?.denyPermissions;
+    const proxyCredentials = this.options.security?.proxyCredentials;
+    if (!denyPermissions && !proxyCredentials) {
       return;
     }
     const cdpSession = await browser.target().createCDPSession();
+    if (!proxyCredentials) {
+      try {
+        if (denyPermissions) {
+          await cdpSession.send('Browser.grantPermissions', { permissions: [] });
+        }
+      } finally {
+        if (!cdpSession.detached) {
+          await cdpSession.detach();
+        }
+      }
+      return;
+    }
+
+    const generation = this.ownedBrowserProcess?.generation;
+    if (generation === undefined) {
+      throw new Error('Proxy security requires an owned browser generation');
+    }
+    this.proxySecurityStopping = false;
+    this.proxySecurityGeneration = generation;
+    this.browserSecurityCdpSession = cdpSession;
     try {
-      await cdpSession.send('Browser.grantPermissions', { permissions: [] });
-    } finally {
-      if (!cdpSession.detached) {
-        await cdpSession.detach();
+      if (denyPermissions) {
+        await cdpSession.send('Browser.grantPermissions', { permissions: [] });
+      }
+      const browserSecurityConnection = cdpSession.connection();
+      if (!browserSecurityConnection) {
+        throw new Error('Browser security CDP session has no connection');
+      }
+      this.browserSecurityConnection = browserSecurityConnection;
+      this.browserSecuritySessionAttachedListener = (attachedSession) => {
+        this.trackProxySecurityOperation(
+          this.configureProxySecuritySession(attachedSession, generation),
+          generation,
+          'proxy_security_session_setup_failed',
+        );
+      };
+      this.browserSecuritySessionDetachedListener = (detachedSession) => {
+        if (detachedSession === cdpSession) {
+          this.handleProxySecurityFailure(
+            'proxy_security_browser_session_detached',
+            new Error('Browser security CDP session detached unexpectedly'),
+            generation,
+          );
+          return;
+        }
+        this.trackProxySecurityOperation(
+          this.verifyProxySecuritySessionDetached(detachedSession, generation),
+          generation,
+          'proxy_security_detach_verification_failed',
+        );
+      };
+      browserSecurityConnection.on(
+        'sessionattached',
+        this.browserSecuritySessionAttachedListener,
+      );
+      browserSecurityConnection.on(
+        'sessiondetached',
+        this.browserSecuritySessionDetachedListener,
+      );
+
+      for (const target of browser.targets()) {
+        if (!proxySeedTargetTypes.has(target.type())) {
+          continue;
+        }
+        const securitySession = await target.createCDPSession();
+        const securityRecord = this.proxySecuritySessions.get(securitySession.id());
+        if (!securityRecord) {
+          throw new Error(`Proxy security did not observe session ${securitySession.id()}`);
+        }
+        securityRecord.ownedByProxySecurity = true;
+        await securityRecord.setupPromise;
+      }
+    } catch (error) {
+      await this.teardownProxySecurity();
+      throw error;
+    }
+  }
+
+  private configureProxySecuritySession(
+    session: plugins.puppeteer.CDPSession,
+    generation: number,
+  ): Promise<void> {
+    const existing = this.proxySecuritySessions.get(session.id());
+    if (existing) {
+      if (existing.generation !== generation) {
+        return Promise.reject(new Error(`CDP session ${session.id()} crossed browser generations`));
+      }
+      return existing.setupPromise;
+    }
+    if (this.proxySecuritySessions.size >= maxProxySecuritySessions) {
+      return Promise.reject(
+        new Error(`Proxy security exceeded ${maxProxySecuritySessions} CDP sessions`),
+      );
+    }
+
+    const attemptedAuthentications = new Set<string>();
+    const requestIdsByNetworkId = new Map<string, string>();
+    const handleProtocolFailure = (operation: string, error: unknown): void => {
+      this.handleProxySecurityFailure(
+        'proxy_security_protocol_failed',
+        new Error(`${operation}: ${normalizeErrorMessage(error)}`),
+        generation,
+      );
+    };
+    const authRequiredListener = (event: TProxyAuthRequiredEvent): void => {
+      const credentials = this.options.security?.proxyCredentials;
+      const totalTrackedRequests = [...this.proxySecuritySessions.values()].reduce(
+        (total, record) => total
+          + record.attemptedAuthentications.size
+          + record.requestIdsByNetworkId.size,
+        0,
+      );
+      const hasTrackingCapacity = attemptedAuthentications.size < maxTrackedProxyRequests
+        && totalTrackedRequests < maxTotalTrackedProxyRequests;
+      const isFirstProxyAttempt = event.authChallenge.source === 'Proxy'
+        && !attemptedAuthentications.has(event.requestId)
+        && hasTrackingCapacity;
+      if (isFirstProxyAttempt) {
+        attemptedAuthentications.add(event.requestId);
+      } else if (
+        event.authChallenge.source === 'Proxy'
+        && !attemptedAuthentications.has(event.requestId)
+        && !hasTrackingCapacity
+      ) {
+        handleProtocolFailure(
+          'Proxy authentication tracking failed',
+          new Error(`A security session exceeded ${maxTrackedProxyRequests} tracked requests`),
+        );
+      }
+      const authChallengeResponse = isFirstProxyAttempt && credentials
+        ? {
+            response: 'ProvideCredentials' as const,
+            username: credentials.username,
+            password: credentials.password,
+          }
+        : { response: 'CancelAuth' as const };
+      this.trackProxySecurityOperation(
+        session.send('Fetch.continueWithAuth', {
+          requestId: event.requestId,
+          authChallengeResponse,
+        }).then(() => undefined),
+        generation,
+        'proxy_security_protocol_failed',
+      );
+    };
+    const requestPausedListener = (event: TProxyRequestPausedEvent): void => {
+      if (event.networkId) {
+        const totalTrackedRequests = [...this.proxySecuritySessions.values()].reduce(
+          (total, record) => total
+            + record.attemptedAuthentications.size
+            + record.requestIdsByNetworkId.size,
+          0,
+        );
+        if (
+          !requestIdsByNetworkId.has(event.networkId)
+          && (
+            requestIdsByNetworkId.size >= maxTrackedProxyRequests
+            || totalTrackedRequests >= maxTotalTrackedProxyRequests
+          )
+        ) {
+          handleProtocolFailure(
+            'Proxy request tracking failed',
+            new Error(`A security session exceeded ${maxTrackedProxyRequests} tracked requests`),
+          );
+        } else {
+          const previousRequestId = requestIdsByNetworkId.get(event.networkId);
+          if (previousRequestId && previousRequestId !== event.requestId) {
+            attemptedAuthentications.delete(previousRequestId);
+          }
+          requestIdsByNetworkId.set(event.networkId, event.requestId);
+        }
+      }
+      this.trackProxySecurityOperation(
+        session.send('Fetch.continueRequest', { requestId: event.requestId }).then(() => undefined),
+        generation,
+        'proxy_security_protocol_failed',
+      );
+    };
+    const forgetAuthentication = (networkId: string): void => {
+      const requestId = requestIdsByNetworkId.get(networkId);
+      if (!requestId) {
+        return;
+      }
+      requestIdsByNetworkId.delete(networkId);
+      attemptedAuthentications.delete(requestId);
+    };
+    const loadingFinishedListener = (event: TNetworkLoadingFinishedEvent): void => {
+      forgetAuthentication(event.requestId);
+    };
+    const loadingFailedListener = (event: TNetworkLoadingFailedEvent): void => {
+      forgetAuthentication(event.requestId);
+    };
+    session.on('Fetch.authRequired', authRequiredListener);
+    session.on('Fetch.requestPaused', requestPausedListener);
+    session.on('Network.loadingFinished', loadingFinishedListener);
+    session.on('Network.loadingFailed', loadingFailedListener);
+
+    const proxySecuritySession: IProxySecuritySession = {
+      session,
+      generation,
+      fetchEnabled: false,
+      allowLiveTargetDetach: false,
+      ownedByProxySecurity: false,
+      attemptedAuthentications,
+      requestIdsByNetworkId,
+      authRequiredListener,
+      requestPausedListener,
+      loadingFinishedListener,
+      loadingFailedListener,
+      setupPromise: Promise.resolve(),
+    };
+    const targetInfoPromise = session.send('Target.getTargetInfo');
+    const networkEnablePromise = session.send('Network.enable');
+    const fetchEnablePromise = session.send('Fetch.enable', {
+      handleAuthRequests: true,
+      patterns: [{ urlPattern: '*' }],
+    });
+    const commandResultsPromise = Promise.allSettled([
+      targetInfoPromise,
+      networkEnablePromise,
+      fetchEnablePromise,
+    ]);
+    const setupPromise = (async (): Promise<void> => {
+      try {
+        const [targetInfoResult, networkResult, fetchResult] = await commandResultsPromise;
+        if (targetInfoResult.status === 'rejected') {
+          throw targetInfoResult.reason;
+        }
+        const { targetInfo } = targetInfoResult.value;
+        proxySecuritySession.targetId = targetInfo.targetId;
+        proxySecuritySession.targetType = targetInfo.type;
+        if (fetchResult.status === 'rejected') {
+          const unsupportedTarget = proxyFetchUnsupportedTargetTypes.has(targetInfo.type)
+            && fetchResult.reason instanceof plugins.puppeteer.ProtocolError
+            && fetchResult.reason.originalMessage === "'Fetch.enable' wasn't found";
+          if (unsupportedTarget) {
+            this.removeProxySecuritySession(proxySecuritySession);
+            return;
+          }
+          throw fetchResult.reason;
+        }
+        if (networkResult.status === 'rejected') {
+          throw networkResult.reason;
+        }
+        proxySecuritySession.fetchEnabled = true;
+      } catch (error) {
+        this.removeProxySecuritySession(proxySecuritySession);
+        if (session.detached || this.proxySecurityStopping || this.normalStopRequested) {
+          return;
+        }
+        throw error;
+      }
+    })();
+    proxySecuritySession.setupPromise = setupPromise;
+    this.proxySecuritySessions.set(session.id(), proxySecuritySession);
+    return setupPromise;
+  }
+
+  private async verifyProxySecuritySessionDetached(
+    session: plugins.puppeteer.CDPSession,
+    generation: number,
+  ): Promise<void> {
+    const proxySecuritySession = this.proxySecuritySessions.get(session.id());
+    if (!proxySecuritySession || proxySecuritySession.generation !== generation) {
+      return;
+    }
+    this.removeProxySecuritySession(proxySecuritySession);
+    if (this.proxySecurityStopping || this.normalStopRequested || this.status !== 'running') {
+      return;
+    }
+    if (proxySecuritySession.allowLiveTargetDetach) {
+      return;
+    }
+    if (!proxySecuritySession.targetId) {
+      throw new Error(`Proxy security session detached before target identification: ${session.id()}`);
+    }
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const generationSessions = [...this.proxySecuritySessions.values()].filter((candidate) => (
+        candidate.generation === generation
+      ));
+      await Promise.allSettled(generationSessions.map((candidate) => candidate.setupPromise));
+      const hasReplacement = [...this.proxySecuritySessions.values()].some((candidate) => (
+        candidate.generation === generation
+        && candidate.targetId === proxySecuritySession.targetId
+        && candidate.fetchEnabled
+        && !candidate.session.detached
+      ));
+      if (hasReplacement) {
+        return;
+      }
+      if (attempt < 2) {
+        await delay(25);
+      }
+    }
+    const browserSecurityCdpSession = this.browserSecurityCdpSession;
+    if (!browserSecurityCdpSession || browserSecurityCdpSession.detached) {
+      throw new Error('Browser security CDP session detached unexpectedly');
+    }
+    const { targetInfos } = await browserSecurityCdpSession.send('Target.getTargets');
+    if (targetInfos.some((targetInfo) => targetInfo.targetId === proxySecuritySession.targetId)) {
+      throw new Error(
+        `Proxy security detached from live target ${proxySecuritySession.targetId}`,
+      );
+    }
+  }
+
+  private removeProxySecuritySession(proxySecuritySession: IProxySecuritySession): void {
+    if (this.proxySecuritySessions.get(proxySecuritySession.session.id()) !== proxySecuritySession) {
+      return;
+    }
+    proxySecuritySession.session.off('Fetch.authRequired', proxySecuritySession.authRequiredListener);
+    proxySecuritySession.session.off('Fetch.requestPaused', proxySecuritySession.requestPausedListener);
+    proxySecuritySession.session.off(
+      'Network.loadingFinished',
+      proxySecuritySession.loadingFinishedListener,
+    );
+    proxySecuritySession.session.off(
+      'Network.loadingFailed',
+      proxySecuritySession.loadingFailedListener,
+    );
+    proxySecuritySession.attemptedAuthentications.clear();
+    proxySecuritySession.requestIdsByNetworkId.clear();
+    this.proxySecuritySessions.delete(proxySecuritySession.session.id());
+  }
+
+  private allowOperationalCdpSessionDetach(session: plugins.puppeteer.CDPSession): void {
+    const proxySecuritySession = this.proxySecuritySessions.get(session.id());
+    if (proxySecuritySession) {
+      proxySecuritySession.allowLiveTargetDetach = true;
+    }
+  }
+
+  private trackProxySecurityOperation(
+    operation: Promise<void>,
+    generation: number,
+    errorCode: string,
+  ): void {
+    if (this.proxySecurityOperations.size >= maxProxySecurityOperations) {
+      void operation.catch(() => undefined);
+      this.handleProxySecurityFailure(
+        'proxy_security_operation_capacity_exceeded',
+        new Error(`Proxy security exceeded ${maxProxySecurityOperations} protocol operations`),
+        generation,
+      );
+      return;
+    }
+    let trackedOperation: Promise<void>;
+    trackedOperation = operation.catch((error) => {
+      this.handleProxySecurityFailure(errorCode, error, generation);
+    }).finally(() => {
+      this.proxySecurityOperations.delete(trackedOperation);
+    });
+    this.proxySecurityOperations.add(trackedOperation);
+  }
+
+  private handleProxySecurityFailure(
+    code: string,
+    error: unknown,
+    generation = this.proxySecurityGeneration,
+  ): void {
+    if (
+      generation !== this.proxySecurityGeneration
+      || this.proxySecurityStopping
+      || this.normalStopRequested
+      || this.status === 'stopped'
+      || this.status === 'stopping'
+    ) {
+      return;
+    }
+    const liveBrowserError: ILiveBrowserError = {
+      code,
+      message: normalizeErrorMessage(error),
+      fatal: true,
+    };
+    this.emitError(liveBrowserError);
+    this.beginShutdown(true);
+    void this.terminate().catch((terminationError) => {
+      this.emitError({
+        code: 'proxy_security_termination_failed',
+        message: normalizeErrorMessage(terminationError),
+        fatal: true,
+      });
+    });
+  }
+
+  private async teardownProxySecurity(): Promise<void> {
+    this.proxySecurityStopping = true;
+    if (this.browserSecurityConnection && this.browserSecuritySessionAttachedListener) {
+      this.browserSecurityConnection.off(
+        'sessionattached',
+        this.browserSecuritySessionAttachedListener,
+      );
+    }
+    if (this.browserSecurityConnection && this.browserSecuritySessionDetachedListener) {
+      this.browserSecurityConnection.off(
+        'sessiondetached',
+        this.browserSecuritySessionDetachedListener,
+      );
+    }
+    this.browserSecuritySessionAttachedListener = undefined;
+    this.browserSecuritySessionDetachedListener = undefined;
+    this.browserSecurityConnection = undefined;
+    const ownedSessions = [...this.proxySecuritySessions.values()]
+      .filter((record) => record.ownedByProxySecurity)
+      .map((record) => record.session);
+    for (const proxySecuritySession of [...this.proxySecuritySessions.values()]) {
+      this.removeProxySecuritySession(proxySecuritySession);
+    }
+    for (const ownedSession of ownedSessions) {
+      if (!ownedSession.detached) {
+        try {
+          await ownedSession.detach();
+        } catch {
+          // Browser shutdown can close a target before explicit detach settles.
+        }
+      }
+    }
+    const browserSecurityCdpSession = this.browserSecurityCdpSession;
+    this.browserSecurityCdpSession = undefined;
+    if (browserSecurityCdpSession && !browserSecurityCdpSession.detached) {
+      try {
+        await browserSecurityCdpSession.detach();
+      } catch {
+        // Browser shutdown can detach the browser target first.
       }
     }
+    while (this.proxySecurityOperations.size > 0) {
+      await Promise.allSettled([...this.proxySecurityOperations]);
+    }
+    this.proxySecurityGeneration = 0;
   }
 
   private requireBrowserContext(): plugins.puppeteer.BrowserContext {
@@ -1776,6 +2713,68 @@ export class LiveBrowserSession {
     }
   }
 
+  private scheduleDiscoveredPageRegistration(page: plugins.puppeteer.Page): void {
+    if (
+      page.isClosed()
+      || this.tabIdsByPage.has(page)
+      || this.normalStopRequested
+      || this.status === 'stopped'
+      || this.status === 'stopping'
+    ) {
+      return;
+    }
+    const wasScheduled = this.scheduleOperation(async () => {
+      if (page.isClosed() || this.tabIdsByPage.has(page)) {
+        return;
+      }
+      const previousActiveTabId = this.activeTabId;
+      let discoveredTab: IPrivateLiveBrowserTab | undefined;
+      try {
+        discoveredTab = await this.registerPage(page);
+        await this.activateTabInternal(discoveredTab.id);
+      } catch (error) {
+        const rollbackError = await this.rollbackCreatedPage(
+          page,
+          discoveredTab,
+          previousActiveTabId,
+        );
+        if (rollbackError) {
+          const aggregateError = new AggregateError(
+            [error, rollbackError],
+            'Discovered page registration rollback failed',
+          );
+          this.handleDiscoveredPageFailure(aggregateError);
+          throw aggregateError;
+        }
+        throw error;
+      }
+    }, 'discovered_page_registration_failed', undefined, true);
+    if (!wasScheduled) {
+      this.handleDiscoveredPageFailure(
+        new Error('A discovered page could not be admitted to the internal operation queue'),
+      );
+    }
+  }
+
+  private handleDiscoveredPageFailure(error: unknown): void {
+    if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
+      return;
+    }
+    const liveBrowserError: ILiveBrowserError = {
+      code: 'untracked_page_detected',
+      message: normalizeErrorMessage(error),
+      fatal: true,
+    };
+    this.emitError(liveBrowserError);
+    void this.requestShutdown(liveBrowserError).catch((shutdownError) => {
+      this.emitError({
+        code: 'untracked_page_shutdown_failed',
+        message: normalizeErrorMessage(shutdownError),
+        fatal: true,
+      });
+    });
+  }
+
   private async registerPage(page: plugins.puppeteer.Page): Promise<IPrivateLiveBrowserTab> {
     const existingTabId = this.tabIdsByPage.get(page);
     if (existingTabId) {
@@ -1807,6 +2806,7 @@ export class LiveBrowserSession {
     try {
       if (this.options.security?.denyFileChoosers) {
         const securityCdpSession = await page.createCDPSession();
+        this.allowOperationalCdpSessionDetach(securityCdpSession);
         tab.securityCdpSession = securityCdpSession;
         await securityCdpSession.send('Page.enable', {
           enableFileChooserOpenedEvent: true,
@@ -2270,6 +3270,7 @@ export class LiveBrowserSession {
     await this.ensureTabViewport(tab);
 
     const cdpSession = await tab.page.createCDPSession();
+    this.allowOperationalCdpSessionDetach(cdpSession);
     const generation = tab.generation + 1;
     const frameListener: TScreencastFrameListener = (event) => {
       this.handleScreencastFrame(tab, cdpSession, generation, event);