@pablovitasso/szkrabok 1.0.10

package/packages/runtime/sessions.js

@@ -0,0 +1,77 @@
+// Session management helpers for callers that don't hold the launch() handle.
+
+import * as pool from './pool.js';
+import * as storage from './storage.js';
+import { log } from './logger.js';
+
+/**
+ * Close a session by profile name.
+ * Saves state, closes the context, removes from pool.
+ */
+export const closeSession = async profile => {
+  try {
+    const session = pool.get(profile);
+
+    const state = await session.context.storageState();
+    await storage.saveState(profile, state);
+    await storage.updateMeta(profile, { lastUsed: Date.now() });
+    await session.context.close();
+    pool.remove(profile);
+
+    return { success: true, profile };
+  } catch (err) {
+    if (pool.has(profile)) pool.remove(profile);
+
+    if (err.message?.includes('closed')) {
+      log(`Session ${profile} was already closed`);
+      return { success: true, profile, alreadyClosed: true };
+    }
+
+    throw err;
+  }
+};
+
+/**
+ * Get a session entry from the pool.
+ * Returns { context, page, cdpPort, preset, label, createdAt }.
+ */
+export const getSession = profile => pool.get(profile);
+
+/**
+ * List all active sessions in pool.
+ */
+export const listSessions = () => pool.list();
+
+/**
+ * List all session IDs stored on disk (active or inactive).
+ */
+export const listStoredSessions = () => storage.listSessions();
+
+/**
+ * Update session metadata on disk (e.g. lastUrl after navigation).
+ */
+export const updateSessionMeta = (profile, updates) => storage.updateMeta(profile, updates);
+
+/**
+ * Delete a session's storage from disk (profile dir, state.json, meta.json).
+ * If the session is open, it is closed first.
+ */
+export const deleteStoredSession = async profile => {
+  if (pool.has(profile)) {
+    await closeSession(profile).catch(() => {});
+  }
+  await storage.deleteSession(profile);
+};
+
+/**
+ * Close all open sessions (used on server shutdown).
+ */
+export const closeAllSessions = () => pool.closeAll();
+
+/**
+ * Update the active page for a session (e.g. after tabs.select switches focus).
+ */
+export const updateSessionPage = (profile, page) => {
+  const session = pool.get(profile);
+  pool.add(profile, session.context, page, session.cdpPort, session.preset, session.label);
+};

package/packages/runtime/stealth.js

@@ -0,0 +1,232 @@
+import { addExtra } from 'playwright-extra';
+import StealthPlugin from 'puppeteer-extra-plugin-stealth';
+import UserAgentOverride from 'puppeteer-extra-plugin-stealth/evasions/user-agent-override/index.js';
+import NavigatorVendor from 'puppeteer-extra-plugin-stealth/evasions/navigator.vendor/index.js';
+import NavigatorHardwareConcurrency from 'puppeteer-extra-plugin-stealth/evasions/navigator.hardwareConcurrency/index.js';
+import NavigatorLanguages from 'puppeteer-extra-plugin-stealth/evasions/navigator.languages/index.js';
+import WebGLVendor from 'puppeteer-extra-plugin-stealth/evasions/webgl.vendor/index.js';
+import { STEALTH_CONFIG } from './config.js';
+import { log, logDebug } from './logger.js';
+
+const CONFIGURABLE_EVASIONS = [
+  'user-agent-override',
+  'navigator.vendor',
+  'navigator.hardwareConcurrency',
+  'navigator.languages',
+  'webgl.vendor',
+];
+
+export const enhanceWithStealth = (browser, presetConfig = {}) => {
+  log('Initializing puppeteer-extra-plugin-stealth');
+
+  try {
+    const enhanced = addExtra(browser);
+    const stealth = StealthPlugin();
+
+    for (const name of CONFIGURABLE_EVASIONS) {
+      stealth.enabledEvasions.delete(name);
+    }
+    stealth.enabledEvasions.delete('user-data-dir');
+
+    for (const [name, enabled] of Object.entries(STEALTH_CONFIG.evasions)) {
+      if (enabled) {
+        stealth.enabledEvasions.add(name);
+      } else {
+        stealth.enabledEvasions.delete(name);
+      }
+    }
+
+    enhanced.use(stealth);
+
+    const uaConfig = STEALTH_CONFIG['user-agent-override'];
+    const overrideUA = presetConfig.overrideUserAgent ?? uaConfig.enabled ?? true;
+    if (overrideUA) {
+      enhanced.use(
+        UserAgentOverride({
+          userAgent: presetConfig.userAgent || undefined,
+          locale: presetConfig.locale || undefined,
+          maskLinux: uaConfig.mask_linux ?? true,
+        })
+      );
+    }
+
+    const vendorConfig = STEALTH_CONFIG['navigator.vendor'];
+    if (vendorConfig.enabled ?? true) {
+      enhanced.use(NavigatorVendor({ vendor: vendorConfig.vendor ?? 'Google Inc.' }));
+    }
+
+    const hwConfig = STEALTH_CONFIG['navigator.hardwareConcurrency'];
+    if (hwConfig.enabled ?? true) {
+      enhanced.use(NavigatorHardwareConcurrency({ hardwareConcurrency: hwConfig.hardware_concurrency ?? 4 }));
+    }
+
+    const langConfig = STEALTH_CONFIG['navigator.languages'];
+    if (langConfig.enabled ?? true) {
+      const locale = presetConfig.locale || 'en-US';
+      const languages = langConfig.languages ?? [locale, locale.split('-')[0]].filter(Boolean);
+      enhanced.use(NavigatorLanguages({ languages }));
+    }
+
+    const webglConfig = STEALTH_CONFIG['webgl.vendor'];
+    if (webglConfig.enabled ?? true) {
+      enhanced.use(
+        WebGLVendor({
+          vendor: webglConfig.vendor ?? 'Intel Inc.',
+          renderer: webglConfig.renderer ?? 'Intel Iris OpenGL Engine',
+        })
+      );
+    }
+
+    return enhanced;
+  } catch (err) {
+    log('Stealth plugin failed, using vanilla Playwright', err.message);
+    return browser;
+  }
+};
+
+export const applyStealthToExistingPage = async (page, presetConfig = {}) => {
+  try {
+    logDebug('applyStealthToExistingPage called', { presetConfig });
+    const uaConfig = STEALTH_CONFIG['user-agent-override'];
+    const overrideUA = presetConfig.overrideUserAgent ?? uaConfig.enabled ?? true;
+    const hwConfig = STEALTH_CONFIG['navigator.hardwareConcurrency'];
+    const webglConfig = STEALTH_CONFIG['webgl.vendor'];
+    const langConfig = STEALTH_CONFIG['navigator.languages'];
+
+    const client = await page.context().newCDPSession(page);
+
+    if (overrideUA) {
+      const ua = presetConfig.userAgent || '';
+      const chromeMatch = ua.match(/Chrome\/([\d.]+)/);
+      const uaVersion = chromeMatch ? chromeMatch[1] : '120.0.0.0';
+      const seed = parseInt(uaVersion.split('.')[0]);
+
+      const order = [
+        [0, 1, 2],
+        [0, 2, 1],
+        [1, 0, 2],
+        [1, 2, 0],
+        [2, 0, 1],
+        [2, 1, 0],
+      ][seed % 6];
+      const escapedChars = [' ', ' ', ';'];
+      const greaseyBrand = `${escapedChars[order[0]]}Not${escapedChars[order[1]]}A${escapedChars[order[2]]}Brand`;
+      const brands = [];
+      brands[order[0]] = { brand: greaseyBrand, version: '99' };
+      brands[order[1]] = { brand: 'Chromium', version: String(seed) };
+      brands[order[2]] = { brand: 'Google Chrome', version: String(seed) };
+
+      const maskLinux = uaConfig.mask_linux ?? true;
+      let platform = 'Win32';
+      let extPlatform = 'Windows';
+      let platformVersion = '10.0';
+      if (ua.includes('Mac OS X')) {
+        platform = 'MacIntel';
+        extPlatform = 'Mac OS X';
+        const macMatch = ua.match(/Mac OS X ([^)]+)/);
+        platformVersion = macMatch ? macMatch[1] : '10_15_7';
+      } else if (ua.includes('Android')) {
+        platform = 'Android';
+        extPlatform = 'Android';
+        const andMatch = ua.match(/Android ([^;]+)/);
+        platformVersion = andMatch ? andMatch[1] : '14';
+      } else if (ua.includes('Linux') && !maskLinux) {
+        platform = 'Linux x86_64';
+        extPlatform = 'Linux';
+        platformVersion = '';
+      }
+
+      const locale = presetConfig.locale || 'en-US';
+
+      await client.send('Network.setUserAgentOverride', {
+        userAgent: ua,
+        acceptLanguage: `${locale},${locale.split('-')[0]};q=0.9`,
+        platform,
+        userAgentMetadata: {
+          brands,
+          fullVersion: uaVersion,
+          platform: extPlatform,
+          platformVersion,
+          architecture: 'x86',
+          model: '',
+          mobile: false,
+          bitness: '64',
+        },
+      });
+
+      const brandsJson = JSON.stringify(brands);
+      const fullVersion = uaVersion;
+      await page.addInitScript(`
+(function() {
+  const _brands = ${brandsJson};
+  const _uad = {
+    brands: _brands,
+    mobile: false,
+    platform: 'Windows',
+    getHighEntropyValues: async (hints) => {
+      const result = {};
+      if (hints.includes('brands')) result.brands = _brands;
+      if (hints.includes('mobile')) result.mobile = false;
+      if (hints.includes('platform')) result.platform = 'Windows';
+      if (hints.includes('platformVersion')) result.platformVersion = '10.0.0';
+      if (hints.includes('architecture')) result.architecture = 'x86';
+      if (hints.includes('bitness')) result.bitness = '64';
+      if (hints.includes('model')) result.model = '';
+      if (hints.includes('uaFullVersion')) result.uaFullVersion = ${JSON.stringify(fullVersion)};
+      if (hints.includes('fullVersionList')) result.fullVersionList = _brands.map(b => ({ brand: b.brand, version: b.version + '.0.0.0' }));
+      return result;
+    },
+    toJSON: () => ({ brands: _brands, mobile: false, platform: 'Windows' }),
+  };
+  try {
+    Object.defineProperty(Navigator.prototype, 'userAgentData', { get: () => _uad, configurable: true });
+  } catch(e) {}
+})();`);
+    }
+
+    if (hwConfig.enabled ?? true) {
+      const concurrency = hwConfig.hardware_concurrency ?? 4;
+      logDebug('registering hardwareConcurrency init script', { concurrency });
+      await page.addInitScript(`(function(){
+  try {
+    Object.defineProperty(Navigator.prototype, 'hardwareConcurrency', { get: () => ${concurrency}, configurable: true });
+  } catch(e) {}
+})()`);
+    }
+
+    if (langConfig.enabled ?? true) {
+      const locale = presetConfig.locale || 'en-US';
+      const languages = langConfig.languages ?? [locale, locale.split('-')[0]].filter(Boolean);
+      const langsJson = JSON.stringify(languages);
+      await page.addInitScript(
+        `Object.defineProperty(Navigator.prototype, 'languages', { get: () => ${langsJson}, configurable: true });`
+      );
+    }
+
+    if (webglConfig.enabled ?? true) {
+      const vendor = webglConfig.vendor ?? 'Intel Inc.';
+      const renderer = webglConfig.renderer ?? 'Intel Iris OpenGL Engine';
+      await page.addInitScript(`
+(function() {
+  const _getParameter = WebGLRenderingContext.prototype.getParameter;
+  WebGLRenderingContext.prototype.getParameter = function(p) {
+    if (p === 37445) return ${JSON.stringify(vendor)};
+    if (p === 37446) return ${JSON.stringify(renderer)};
+    return _getParameter.call(this, p);
+  };
+  if (typeof WebGL2RenderingContext !== 'undefined') {
+    const _get2 = WebGL2RenderingContext.prototype.getParameter;
+    WebGL2RenderingContext.prototype.getParameter = function(p) {
+      if (p === 37445) return ${JSON.stringify(vendor)};
+      if (p === 37446) return ${JSON.stringify(renderer)};
+      return _get2.call(this, p);
+    };
+  }
+})()`);
+    }
+
+    log('Applied stealth evasions to existing page via CDP');
+  } catch (err) {
+    log('applyStealthToExistingPage failed', err.message);
+  }
+};

package/packages/runtime/storage.js

@@ -0,0 +1,64 @@
+import { readFile, writeFile, mkdir, rm, readdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+// Sessions dir: SZKRABOK_SESSIONS_DIR env > cwd/sessions
+const getSessionsDir = () =>
+  process.env.SZKRABOK_SESSIONS_DIR ?? join(process.cwd(), 'sessions');
+
+const getSessionDir = id => join(getSessionsDir(), id);
+const getStatePath = id => join(getSessionDir(id), 'state.json');
+const getMetaPath = id => join(getSessionDir(id), 'meta.json');
+
+export const getUserDataDir = id => join(getSessionDir(id), 'profile');
+
+export const ensureSessionsDir = async () => {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+};
+
+export const sessionExists = id => existsSync(getSessionDir(id));
+
+export const loadState = async id => {
+  const path = getStatePath(id);
+  if (!existsSync(path)) return null;
+  return JSON.parse(await readFile(path, 'utf-8'));
+};
+
+export const saveState = async (id, state) => {
+  await mkdir(getSessionDir(id), { recursive: true });
+  await writeFile(getStatePath(id), JSON.stringify(state, null, 2));
+};
+
+export const loadMeta = async id => {
+  const path = getMetaPath(id);
+  if (!existsSync(path)) return null;
+  return JSON.parse(await readFile(path, 'utf-8'));
+};
+
+export const saveMeta = async (id, meta) => {
+  await mkdir(getSessionDir(id), { recursive: true });
+  await writeFile(getMetaPath(id), JSON.stringify(meta, null, 2));
+};
+
+export const updateMeta = async (id, updates) => {
+  const meta = (await loadMeta(id)) || {};
+  const updated = { ...meta, ...updates, lastUsed: Date.now() };
+  await saveMeta(id, updated);
+  return updated;
+};
+
+export const deleteSession = async id => {
+  const dir = getSessionDir(id);
+  if (existsSync(dir)) {
+    await rm(dir, { recursive: true });
+  }
+};
+
+export const listSessions = async () => {
+  await ensureSessionsDir();
+  const dirs = await readdir(getSessionsDir(), { withFileTypes: true });
+  return dirs.filter(d => d.isDirectory()).map(d => d.name);
+};

package/scripts/detect_browsers.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# detect_browsers.sh — find Chrome/Chromium binaries and echo szkrabok.config.toml lines
+#
+# Usage:
+#   bash scripts/detect_browsers.sh
+#
+# Output:
+#   For each detected browser: its version + the TOML executablePath line to use.
+#   If nothing useful is found: installation suggestions.
+#
+# Copy the executablePath line you want into szkrabok.config.toml [default] section.
+# Google Chrome stable is best for stealth (native brands). Ungoogled-chromium is a
+# good second choice. The Playwright bundled binary (Chrome for Testing) should be
+# avoided in production — it brands itself as automation tooling.
+
+set -euo pipefail
+
+FOUND=()
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+get_version() {
+  # Run binary with --version, strip leading "Chromium ", "Google Chrome " etc.
+  timeout 5 "$1" --version 2>/dev/null | head -1 | sed 's/^[^0-9]*//' || true
+}
+
+check_binary() {
+  local label="$1" path="$2"
+  if [[ -x "$path" ]]; then
+    local ver
+    ver="$(get_version "$path")"
+    if [[ -n "$ver" ]]; then
+      echo "  FOUND  $label — $ver"
+      echo "         executablePath = \"$path\""
+      echo ""
+      FOUND+=("$label")
+    fi
+  fi
+}
+
+check_flatpak() {
+  local label="$1" app_id="$2"
+  if command -v flatpak >/dev/null 2>&1 && flatpak info "$app_id" >/dev/null 2>&1; then
+    local ver
+    ver="$(timeout 5 flatpak run "$app_id" --version 2>/dev/null | head -1 | sed 's/^[^0-9]*//' || true)"
+    if [[ -n "$ver" ]]; then
+      # Write a small wrapper path check — flatpak run is the executable path
+      local wrapper
+      wrapper="$(command -v flatpak)"
+      echo "  FOUND  $label — $ver"
+      echo "         # flatpak binary — use a wrapper script or the flatpak run command:"
+      echo "         executablePath = \"$HOME/.local/bin/$(echo "$app_id" | tr '.' '-' | tr '[:upper:]' '[:lower:]')\""
+      echo "         # (create that wrapper: echo '#!/bin/sh' > the path, then:"
+      echo "         #  echo 'exec flatpak run $app_id \"\$@\"' >> the path, chmod +x)"
+      echo ""
+      FOUND+=("$label")
+    fi
+  fi
+}
+
+check_snap() {
+  local label="$1" snap_name="$2" snap_bin="$3"
+  if [[ -x "$snap_bin" ]]; then
+    local ver
+    ver="$(get_version "$snap_bin")"
+    if [[ -n "$ver" ]]; then
+      echo "  FOUND  $label — $ver"
+      echo "         executablePath = \"$snap_bin\""
+      echo ""
+      FOUND+=("$label")
+    fi
+  fi
+}
+
+# ── scan ──────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "=== szkrabok browser detection ==="
+echo ""
+echo "Scanning for usable Chrome/Chromium binaries..."
+echo ""
+
+# Google Chrome stable (best for stealth — native brands)
+check_binary "Google Chrome stable"       "/usr/bin/google-chrome"
+check_binary "Google Chrome stable"       "/usr/bin/google-chrome-stable"
+check_binary "Google Chrome stable"       "/opt/google/chrome/chrome"
+check_binary "Google Chrome stable"       "/opt/google/chrome/google-chrome"
+
+# Chromium (distro package)
+check_binary "Chromium (distro)"          "/usr/bin/chromium"
+check_binary "Chromium (distro)"          "/usr/bin/chromium-browser"
+
+# Ungoogled-chromium — common wrapper locations
+check_binary "Ungoogled-chromium"         "$HOME/.local/bin/ungoogled-chromium"
+check_binary "Ungoogled-chromium"         "/usr/bin/ungoogled-chromium"
+
+# Ungoogled-chromium via flatpak — only if no wrapper binary was found above
+if [[ ! -x "$HOME/.local/bin/ungoogled-chromium" && ! -x "/usr/bin/ungoogled-chromium" ]]; then
+  check_flatpak "Ungoogled-chromium (flatpak)" "io.github.ungoogled_software.ungoogled_chromium"
+fi
+
+# Chromium via snap
+check_snap "Chromium (snap)"              "chromium" "/snap/bin/chromium"
+
+# Brave
+check_binary "Brave"                      "/usr/bin/brave-browser"
+check_binary "Brave"                      "/usr/bin/brave-browser-stable"
+check_binary "Brave"                      "/opt/brave.com/brave/brave"
+
+# Microsoft Edge (Chromium-based)
+check_binary "Microsoft Edge"             "/usr/bin/microsoft-edge"
+check_binary "Microsoft Edge"             "/usr/bin/microsoft-edge-stable"
+check_binary "Microsoft Edge"             "/opt/microsoft/msedge/msedge"
+
+# ── results ───────────────────────────────────────────────────────────────────
+
+if [[ ${#FOUND[@]} -eq 0 ]]; then
+  echo "  NONE FOUND — no usable Chrome/Chromium binary detected."
+  echo ""
+  echo "  szkrabok will fall back to the Playwright bundled 'Chrome for Testing'."
+  echo "  This works but is detectable as automation tooling (brands itself as"
+  echo "  'Chrome for Testing' in navigator.userAgentData)."
+  echo ""
+  echo "  Recommended installations:"
+  echo ""
+  echo "  1. Google Chrome stable (best stealth — native brands):"
+  echo "       https://www.google.com/chrome/"
+  echo "       wget -qO- https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -"
+  echo "       sudo sh -c 'echo \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" > /etc/apt/sources.list.d/google-chrome.list'"
+  echo "       sudo apt-get update && sudo apt-get install google-chrome-stable"
+  echo ""
+  echo "  2. Ungoogled-chromium via flatpak (no Google services, good stealth):"
+  echo "       flatpak install flathub io.github.ungoogled_software.ungoogled_chromium"
+  echo "       # then create a wrapper: ~/.local/bin/ungoogled-chromium"
+  echo "       # with: exec flatpak run io.github.ungoogled_software.ungoogled_chromium \"\$@\""
+  echo ""
+else
+  echo "  Copy one executablePath line above into szkrabok.config.toml [default]."
+  echo ""
+  echo "  Stealth ranking (best first):"
+  echo "    1. Google Chrome stable — native 'Google Chrome' brands, most trusted"
+  echo "    2. Ungoogled-chromium   — no Google services; needs greasy brands patch"
+  echo "    3. Chromium (distro)    — same as ungoogled; needs greasy brands patch"
+  echo "    4. Chrome for Testing   — avoid in production (automation-branded)"
+fi
+
+echo ""