@nextop-os/browser-node 0.0.8

package/dist/electron-main/index.d.ts

@@ -0,0 +1,125 @@
+import { B as BrowserNodeActivationInput, j as BrowserNodeNodeIdInput, b as BrowserNodeDebugDump, i as BrowserNodeNavigateInput, l as BrowserNodePrepareSessionInput, m as BrowserNodeRegisterGuestInput, r as BrowserNodeUnregisterGuestInput, f as BrowserNodeEvent } from '../types-4cyQPaaT.js';
+import { BrowserWindow, WebPreferences, WebContents } from 'electron';
+
+interface BrowserNodePreviewRoute {
+    readonly sourceUrl: string;
+    readonly targetUrl: string;
+}
+interface BrowserNodePreviewRouteResolver {
+    resolveRoutes(input: {
+        nodeId: string;
+        url: string;
+    }): BrowserNodePreviewRoute[] | Promise<BrowserNodePreviewRoute[]>;
+}
+declare function createNoopBrowserNodePreviewRouteResolver(): BrowserNodePreviewRouteResolver;
+
+interface BrowserGuestManager {
+    activate(input: BrowserNodeActivationInput): Promise<void>;
+    capturePreview(input: BrowserNodeNodeIdInput): Promise<string | null>;
+    close(input: BrowserNodeNodeIdInput): Promise<void>;
+    debugDump(input: BrowserNodeNodeIdInput): BrowserNodeDebugDump | null;
+    goBack(input: BrowserNodeNodeIdInput): Promise<void>;
+    goForward(input: BrowserNodeNodeIdInput): Promise<void>;
+    navigate(input: BrowserNodeNavigateInput): Promise<void>;
+    prepareSession(input: BrowserNodePrepareSessionInput): Promise<void>;
+    registerGuest(input: BrowserNodeRegisterGuestInput): Promise<void>;
+    reload(input: BrowserNodeNodeIdInput): Promise<void>;
+    unregisterGuest(input: BrowserNodeUnregisterGuestInput): Promise<void>;
+}
+interface BrowserGuestManagerInput {
+    emit: (event: BrowserNodeEvent) => void;
+    logger?: BrowserNodeElectronLogger;
+    openExternal: (url: string) => Promise<void> | void;
+    previewRouteResolver?: BrowserNodePreviewRouteResolver;
+    resolveWebContents: (webContentsId: number) => BrowserGuestWebContents | null;
+}
+interface BrowserNodeElectronLogger {
+    debug?(message: string, metadata?: Record<string, unknown>): void;
+    warn?(message: string, metadata?: Record<string, unknown>): void;
+}
+interface BrowserGuestWebContents {
+    readonly id?: number;
+    canGoBack(): boolean;
+    canGoForward(): boolean;
+    capturePage?(): Promise<BrowserGuestNativeImage>;
+    getTitle(): string;
+    getURL(): string;
+    goBack(): void;
+    goForward(): void;
+    isDestroyed(): boolean;
+    isLoading(): boolean;
+    loadURL(url: string): Promise<void>;
+    off(event: string, listener: (...args: unknown[]) => void): this;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    reload(): void;
+    setWindowOpenHandler?(handler: (details: {
+        url: string;
+    }) => {
+        action: "allow" | "deny";
+    }): void;
+}
+interface BrowserGuestNativeImage {
+    getSize?(): {
+        height: number;
+        width: number;
+    };
+    isEmpty?(): boolean;
+    resize?(options: {
+        height?: number;
+        quality?: "best" | "good" | "better" | "nearest";
+        width?: number;
+    }): BrowserGuestNativeImage;
+    toDataURL(): string;
+}
+
+declare function createBrowserGuestManager({ emit, logger, openExternal, previewRouteResolver, resolveWebContents }: BrowserGuestManagerInput): BrowserGuestManager;
+
+interface BrowserNodeElectronMainChannels {
+    readonly activate: string;
+    readonly capturePreview?: string;
+    readonly close: string;
+    readonly debugDump?: string;
+    readonly event: string;
+    readonly goBack: string;
+    readonly goForward: string;
+    readonly navigate: string;
+    readonly prepareSession: string;
+    readonly registerGuest: string;
+    readonly reload: string;
+    readonly unregisterGuest: string;
+}
+interface RegisterBrowserNodeElectronMainInput {
+    readonly channels: BrowserNodeElectronMainChannels;
+    readonly getOwnerWindow: (event: unknown) => BrowserWindow | null;
+    readonly logger?: BrowserNodeElectronLogger;
+    readonly openExternal: (url: string) => Promise<void> | void;
+    readonly registerHandler: <TPayload, TResult>(channel: string, handler: (event: unknown, payload: TPayload) => Promise<TResult> | TResult) => void;
+    readonly resolveWebContents: (input: {
+        event: unknown;
+        ownerWindow: BrowserWindow;
+        webContentsId: number;
+    }) => BrowserGuestWebContents | null;
+}
+declare function registerBrowserNodeElectronMain(input: RegisterBrowserNodeElectronMainInput): void;
+
+interface BrowserWebviewSecurityInput {
+    params: Record<string, string>;
+    webPreferences: WebPreferences;
+}
+interface BrowserWebviewSecurityResult {
+    allowed: boolean;
+    reason: string | null;
+}
+type BrowserNodeWebviewMatcher = (params: Record<string, string>) => boolean;
+declare function isBrowserNodeWebviewAttach(params: Record<string, string>): boolean;
+declare function enforceBrowserWebviewSecurity({ params, webPreferences }: BrowserWebviewSecurityInput): BrowserWebviewSecurityResult;
+interface InstallBrowserWebviewSecurityInput {
+    contents: WebContents;
+    logger?: BrowserNodeElectronLogger;
+    onGuestAttached?: (guestContents: WebContents) => void;
+    openExternal: (url: string) => Promise<void> | void;
+    shouldHandleWebview?: BrowserNodeWebviewMatcher;
+}
+declare function installBrowserWebviewSecurity({ contents, logger, onGuestAttached, openExternal, shouldHandleWebview }: InstallBrowserWebviewSecurityInput): () => void;
+
+export { type BrowserGuestManager, type BrowserGuestManagerInput, type BrowserGuestNativeImage, type BrowserGuestWebContents, type BrowserNodeElectronLogger, type BrowserNodeElectronMainChannels, type BrowserNodePreviewRoute, type BrowserNodePreviewRouteResolver, type BrowserNodeWebviewMatcher, type BrowserWebviewSecurityInput, type BrowserWebviewSecurityResult, type InstallBrowserWebviewSecurityInput, type RegisterBrowserNodeElectronMainInput, createBrowserGuestManager, createNoopBrowserNodePreviewRouteResolver, enforceBrowserWebviewSecurity, installBrowserWebviewSecurity, isBrowserNodeWebviewAttach, registerBrowserNodeElectronMain };

package/dist/electron-main/index.js

@@ -0,0 +1,509 @@
+import {
+  normalizeBrowserComparableUrl,
+  resolveBrowserNavigationUrl
+} from "../chunk-2ZAMKGGP.js";
+import {
+  isBrowserSessionPartitionAllowed
+} from "../chunk-OTK5YBCK.js";
+
+// src/electron-main/previewRoute.ts
+function createNoopBrowserNodePreviewRouteResolver() {
+  return {
+    resolveRoutes: () => []
+  };
+}
+
+// src/electron-main/guestManager.ts
+var browserPreviewMaxWidth = 260;
+var browserPreviewMaxHeight = 170;
+var abortedNavigationErrorCode = -3;
+function resolveBrowserNodeUrlError(resolved) {
+  if (resolved.errorCode === "invalid-url") {
+    return { code: "invalid-url" };
+  }
+  if (resolved.errorCode === "unsupported-protocol") {
+    return {
+      code: "unsupported-protocol",
+      params: resolved.errorParams
+    };
+  }
+  return { code: "unsupported-url" };
+}
+function resizeBrowserPreviewImage(image) {
+  if (image.isEmpty?.() === true || !image.resize || !image.getSize) {
+    return image;
+  }
+  const size = image.getSize();
+  if (size.width <= 0 || size.height <= 0) {
+    return image;
+  }
+  const scale = Math.min(
+    1,
+    browserPreviewMaxWidth / size.width,
+    browserPreviewMaxHeight / size.height
+  );
+  if (scale >= 1) {
+    return image;
+  }
+  return image.resize({
+    height: Math.max(1, Math.round(size.height * scale)),
+    quality: "good",
+    width: Math.max(1, Math.round(size.width * scale))
+  });
+}
+function isAbortedNavigationError(input) {
+  return input.errorCode === abortedNavigationErrorCode || input.errorDescription === "ERR_ABORTED";
+}
+function createBrowserGuestManager({
+  emit,
+  logger,
+  openExternal,
+  previewRouteResolver = createNoopBrowserNodePreviewRouteResolver(),
+  resolveWebContents
+}) {
+  const sessions = /* @__PURE__ */ new Map();
+  const nodeIdByWebContentsId = /* @__PURE__ */ new Map();
+  const getSession = (nodeId, input) => {
+    const existing = sessions.get(nodeId);
+    if (existing) {
+      if (input?.profileId !== void 0) {
+        existing.profileId = input.profileId;
+      }
+      if (input?.sessionMode !== void 0) {
+        existing.sessionMode = input.sessionMode;
+      }
+      if (input?.url !== void 0) {
+        existing.desiredUrl = input.url;
+      }
+      return existing;
+    }
+    const session = {
+      contents: null,
+      desiredUrl: input?.url ?? "about:blank",
+      lifecycle: "cold",
+      listeners: [],
+      nodeId,
+      profileId: input?.profileId ?? null,
+      sessionMode: input?.sessionMode ?? "shared",
+      webContentsId: null
+    };
+    sessions.set(nodeId, session);
+    return session;
+  };
+  const publishState = (session) => {
+    const contents = session.contents && !session.contents.isDestroyed() ? session.contents : null;
+    emit({
+      canGoBack: contents ? contents.canGoBack() : false,
+      canGoForward: contents ? contents.canGoForward() : false,
+      isAttachedToWindow: Boolean(contents),
+      isLoading: contents ? contents.isLoading() : false,
+      isOccluded: session.lifecycle === "cold",
+      lifecycle: session.lifecycle,
+      nodeId: session.nodeId,
+      title: contents ? contents.getTitle() || null : null,
+      type: "state",
+      url: contents ? contents.getURL() || session.desiredUrl : session.desiredUrl
+    });
+  };
+  const detachGuest = (session) => {
+    const contents = session.contents;
+    const webContentsId = session.webContentsId;
+    if (contents) {
+      for (const record of session.listeners) {
+        contents.off(record.event, record.listener);
+      }
+    }
+    session.listeners = [];
+    session.contents = null;
+    session.webContentsId = null;
+    if (webContentsId !== null && nodeIdByWebContentsId.get(webContentsId) === session.nodeId) {
+      nodeIdByWebContentsId.delete(webContentsId);
+    }
+    publishState(session);
+  };
+  const attachGuestListeners = (session) => {
+    const contents = session.contents;
+    if (!contents) {
+      return;
+    }
+    const onStateChange = () => publishState(session);
+    const onFailLoad = (...args) => {
+      const errorCode = typeof args[1] === "number" ? args[1] : void 0;
+      const errorDescription = typeof args[2] === "string" ? args[2] : void 0;
+      if (isAbortedNavigationError({ errorCode, errorDescription })) {
+        publishState(session);
+        return;
+      }
+      emit({
+        code: "navigation-failed",
+        diagnosticMessage: errorDescription,
+        nodeId: session.nodeId,
+        params: errorCode === void 0 ? void 0 : { errorCode },
+        type: "error"
+      });
+      publishState(session);
+    };
+    const onDestroyed = () => detachGuest(session);
+    const records = [
+      { event: "did-start-loading", listener: onStateChange },
+      { event: "did-stop-loading", listener: onStateChange },
+      { event: "did-navigate", listener: onStateChange },
+      { event: "did-navigate-in-page", listener: onStateChange },
+      { event: "page-title-updated", listener: onStateChange },
+      { event: "did-fail-load", listener: onFailLoad },
+      { event: "destroyed", listener: onDestroyed }
+    ];
+    for (const record of records) {
+      contents.on(record.event, record.listener);
+    }
+    session.listeners = records;
+  };
+  const loadDesiredUrl = async (session) => {
+    const contents = session.contents;
+    if (!contents || contents.isDestroyed()) {
+      publishState(session);
+      return;
+    }
+    const resolved = resolveBrowserNavigationUrl(session.desiredUrl);
+    if (!resolved.url) {
+      emit({
+        ...resolveBrowserNodeUrlError(resolved),
+        nodeId: session.nodeId,
+        type: "error"
+      });
+      publishState(session);
+      return;
+    }
+    const routes = await previewRouteResolver.resolveRoutes({
+      nodeId: session.nodeId,
+      url: resolved.url
+    });
+    const routedUrl = routes.find((route) => route.sourceUrl === resolved.url)?.targetUrl ?? resolved.url;
+    const currentComparable = normalizeBrowserComparableUrl(contents.getURL());
+    const nextComparable = normalizeBrowserComparableUrl(routedUrl);
+    if (currentComparable && currentComparable === nextComparable) {
+      publishState(session);
+      return;
+    }
+    await contents.loadURL(routedUrl);
+    publishState(session);
+  };
+  const openExternalFromGuest = (url) => {
+    const resolved = resolveBrowserNavigationUrl(url);
+    if (resolved.url) {
+      void Promise.resolve(openExternal(resolved.url)).catch(
+        (error) => {
+          logger?.warn?.("Browser Node openExternal failed", {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      );
+    }
+    return { action: "deny" };
+  };
+  return {
+    async activate(input) {
+      const resolved = resolveBrowserNavigationUrl(input.url);
+      if (!resolved.url) {
+        throw new Error("Browser Node rejected navigation URL");
+      }
+      const session = getSession(input.nodeId, {
+        profileId: input.profileId,
+        sessionMode: input.sessionMode,
+        url: resolved.url
+      });
+      session.lifecycle = "active";
+      await loadDesiredUrl(session);
+    },
+    async capturePreview(input) {
+      const session = sessions.get(input.nodeId);
+      const contents = session?.contents && !session.contents.isDestroyed() ? session.contents : null;
+      if (!contents?.capturePage) {
+        return null;
+      }
+      const image = await contents.capturePage();
+      if (image.isEmpty?.() === true) {
+        return null;
+      }
+      return resizeBrowserPreviewImage(image).toDataURL();
+    },
+    close(input) {
+      const session = sessions.get(input.nodeId);
+      if (session) {
+        detachGuest(session);
+        sessions.delete(input.nodeId);
+      }
+      emit({ nodeId: input.nodeId, type: "closed" });
+      return Promise.resolve();
+    },
+    debugDump(input) {
+      const session = sessions.get(input.nodeId);
+      if (!session) {
+        return null;
+      }
+      const contents = session.contents && !session.contents.isDestroyed() ? session.contents : null;
+      return {
+        canGoBack: contents ? contents.canGoBack() : false,
+        canGoForward: contents ? contents.canGoForward() : false,
+        currentUrl: contents ? contents.getURL() : null,
+        desiredUrl: session.desiredUrl,
+        isAttachedToWindow: Boolean(contents),
+        isLoading: contents ? contents.isLoading() : false,
+        lifecycle: session.lifecycle,
+        nodeId: session.nodeId,
+        profileId: session.profileId,
+        sessionMode: session.sessionMode,
+        title: contents ? contents.getTitle() : null,
+        webContentsDestroyed: session.contents ? session.contents.isDestroyed() : null,
+        webContentsId: session.webContentsId
+      };
+    },
+    goBack(input) {
+      const contents = sessions.get(input.nodeId)?.contents;
+      if (contents && !contents.isDestroyed() && contents.canGoBack()) {
+        contents.goBack();
+      }
+      return Promise.resolve();
+    },
+    goForward(input) {
+      const contents = sessions.get(input.nodeId)?.contents;
+      if (contents && !contents.isDestroyed() && contents.canGoForward()) {
+        contents.goForward();
+      }
+      return Promise.resolve();
+    },
+    async navigate(input) {
+      const resolved = resolveBrowserNavigationUrl(input.url);
+      if (!resolved.url) {
+        throw new Error("Browser Node rejected navigation URL");
+      }
+      const session = getSession(input.nodeId, { url: resolved.url });
+      session.lifecycle = "active";
+      await loadDesiredUrl(session);
+    },
+    prepareSession(input) {
+      getSession(input.nodeId, {
+        profileId: input.profileId,
+        sessionMode: input.sessionMode
+      });
+      return Promise.resolve();
+    },
+    async registerGuest(input) {
+      const contents = resolveWebContents(input.webContentsId);
+      if (!contents || contents.isDestroyed()) {
+        throw new Error(
+          `Browser Node guest ${input.webContentsId} is not available`
+        );
+      }
+      const ownerNodeId = nodeIdByWebContentsId.get(input.webContentsId);
+      if (ownerNodeId && ownerNodeId !== input.nodeId) {
+        throw new Error(
+          `Browser Node guest ${input.webContentsId} is already registered`
+        );
+      }
+      const session = getSession(input.nodeId, {
+        profileId: input.profileId,
+        sessionMode: input.sessionMode
+      });
+      if (session.webContentsId === input.webContentsId && session.contents === contents) {
+        publishState(session);
+        return;
+      }
+      if (session.contents && session.contents !== contents) {
+        detachGuest(session);
+      }
+      session.contents = contents;
+      session.webContentsId = input.webContentsId;
+      nodeIdByWebContentsId.set(input.webContentsId, input.nodeId);
+      session.lifecycle = "active";
+      contents.setWindowOpenHandler?.(({ url }) => openExternalFromGuest(url));
+      attachGuestListeners(session);
+      await loadDesiredUrl(session);
+    },
+    reload(input) {
+      const contents = sessions.get(input.nodeId)?.contents;
+      if (contents && !contents.isDestroyed()) {
+        contents.reload();
+      }
+      return Promise.resolve();
+    },
+    unregisterGuest(input) {
+      const session = sessions.get(input.nodeId);
+      if (!session || session.webContentsId !== input.webContentsId) {
+        return Promise.resolve();
+      }
+      session.lifecycle = "cold";
+      detachGuest(session);
+      return Promise.resolve();
+    }
+  };
+}
+
+// src/electron-main/registerElectronMain.ts
+function registerBrowserNodeElectronMain(input) {
+  const managersByWindow = /* @__PURE__ */ new WeakMap();
+  const resolveManager = (event) => {
+    const ownerWindow = input.getOwnerWindow(event);
+    if (!ownerWindow) {
+      throw new Error("Browser Node IPC requires an owner window");
+    }
+    const existing = managersByWindow.get(ownerWindow);
+    if (existing) {
+      return existing;
+    }
+    const manager = createBrowserGuestManager({
+      emit(browserEvent) {
+        if (!ownerWindow.isDestroyed()) {
+          ownerWindow.webContents.send(input.channels.event, browserEvent);
+        }
+      },
+      logger: input.logger,
+      openExternal: input.openExternal,
+      resolveWebContents: (webContentsId) => input.resolveWebContents({
+        event,
+        ownerWindow,
+        webContentsId
+      })
+    });
+    managersByWindow.set(ownerWindow, manager);
+    return manager;
+  };
+  input.registerHandler(
+    input.channels.prepareSession,
+    (event, payload) => resolveManager(event).prepareSession(
+      payload
+    )
+  );
+  input.registerHandler(
+    input.channels.activate,
+    (event, payload) => resolveManager(event).activate(payload)
+  );
+  if (input.channels.capturePreview) {
+    input.registerHandler(
+      input.channels.capturePreview,
+      (event, payload) => resolveManager(event).capturePreview(payload)
+    );
+  }
+  input.registerHandler(
+    input.channels.registerGuest,
+    (event, payload) => resolveManager(event).registerGuest(
+      payload
+    )
+  );
+  input.registerHandler(
+    input.channels.unregisterGuest,
+    (event, payload) => resolveManager(event).unregisterGuest(
+      payload
+    )
+  );
+  input.registerHandler(
+    input.channels.navigate,
+    (event, payload) => resolveManager(event).navigate(payload)
+  );
+  input.registerHandler(
+    input.channels.goBack,
+    (event, payload) => resolveManager(event).goBack(payload)
+  );
+  input.registerHandler(
+    input.channels.goForward,
+    (event, payload) => resolveManager(event).goForward(payload)
+  );
+  input.registerHandler(
+    input.channels.reload,
+    (event, payload) => resolveManager(event).reload(payload)
+  );
+  input.registerHandler(
+    input.channels.close,
+    (event, payload) => resolveManager(event).close(payload)
+  );
+  if (input.channels.debugDump) {
+    input.registerHandler(
+      input.channels.debugDump,
+      (event, payload) => resolveManager(event).debugDump(payload)
+    );
+  }
+}
+
+// src/electron-main/webviewSecurity.ts
+function isBrowserNodeWebviewAttach(params) {
+  return params["data-browser-node-webview"] === "true" || isBrowserSessionPartitionAllowed(params.partition);
+}
+function enforceBrowserWebviewSecurity({
+  params,
+  webPreferences
+}) {
+  webPreferences.allowRunningInsecureContent = false;
+  webPreferences.contextIsolation = true;
+  webPreferences.javascript = true;
+  webPreferences.nodeIntegration = false;
+  webPreferences.plugins = false;
+  webPreferences.sandbox = true;
+  webPreferences.webSecurity = true;
+  delete webPreferences.preload;
+  const partition = params.partition;
+  if (!partition || !isBrowserSessionPartitionAllowed(partition)) {
+    return {
+      allowed: false,
+      reason: "Unsupported Browser Node session partition"
+    };
+  }
+  const resolved = resolveBrowserNavigationUrl(params.src ?? "about:blank");
+  if (!resolved.url) {
+    return {
+      allowed: false,
+      reason: "Unsupported browser URL"
+    };
+  }
+  params.src = resolved.url;
+  return { allowed: true, reason: null };
+}
+function installBrowserWebviewSecurity({
+  contents,
+  logger,
+  onGuestAttached,
+  openExternal,
+  shouldHandleWebview = isBrowserNodeWebviewAttach
+}) {
+  let pendingBrowserAttachCount = 0;
+  const handleWillAttachWebview = (event, webPreferences, params) => {
+    if (!shouldHandleWebview(params)) {
+      return;
+    }
+    pendingBrowserAttachCount += 1;
+    const result = enforceBrowserWebviewSecurity({ params, webPreferences });
+    if (!result.allowed) {
+      pendingBrowserAttachCount = Math.max(0, pendingBrowserAttachCount - 1);
+      logger?.warn?.("Browser Node webview blocked", { reason: result.reason });
+      event.preventDefault();
+    }
+  };
+  const handleDidAttachWebview = (_event, guestContents) => {
+    if (pendingBrowserAttachCount <= 0) {
+      return;
+    }
+    pendingBrowserAttachCount -= 1;
+    onGuestAttached?.(guestContents);
+    guestContents.setWindowOpenHandler(({ url }) => {
+      const resolved = resolveBrowserNavigationUrl(url);
+      if (resolved.url) {
+        void Promise.resolve(openExternal(resolved.url)).catch(() => void 0);
+      }
+      return { action: "deny" };
+    });
+  };
+  contents.on("will-attach-webview", handleWillAttachWebview);
+  contents.on("did-attach-webview", handleDidAttachWebview);
+  return () => {
+    contents.off("will-attach-webview", handleWillAttachWebview);
+    contents.off("did-attach-webview", handleDidAttachWebview);
+  };
+}
+export {
+  createBrowserGuestManager,
+  createNoopBrowserNodePreviewRouteResolver,
+  enforceBrowserWebviewSecurity,
+  installBrowserWebviewSecurity,
+  isBrowserNodeWebviewAttach,
+  registerBrowserNodeElectronMain
+};
+//# sourceMappingURL=index.js.map