@web-auto/camo 0.1.18 → 0.1.20

package/src/services/browser-service/internal/fingerprint.js

@@ -0,0 +1,203 @@
+/**
+ * 浏览器指纹管理器
+ * 提供稳定的指纹生成、应用和管理功能
+ */
+import { randomBytes } from 'crypto';
+import { writeFile, readFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+function resolveFingerprintDir() {
+    const envDir = String(process.env.CAMO_PATHS_FINGERPRINTS || '').trim();
+    if (envDir)
+        return envDir;
+    const portableRoot = String(process.env.CAMO_PORTABLE_ROOT || process.env.CAMO_ROOT || '').trim();
+    if (portableRoot)
+        return join(portableRoot, '.camo', 'fingerprints');
+    return join(homedir(), '.camo', 'fingerprints');
+}
+const PLATFORM_FINGERPRINTS = {
+    windows: [
+        {
+            userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            platform: 'Win32',
+            osVersion: '10.0',
+        },
+        {
+            userAgent: 'Mozilla/5.0 (Windows NT 11.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            platform: 'Win32',
+            osVersion: '11.0',
+        },
+    ],
+    macos: [
+        {
+            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            platform: 'MacIntel',
+            osVersion: '10.15.7',
+        },
+        {
+            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+            platform: 'MacIntel',
+            osVersion: '14.6.1',
+        },
+    ],
+};
+export function generateFingerprint(profileId = 'default', options = {}) {
+    const { platform = null, seed = null } = options;
+    const hash = randomBytes(16).toString('hex');
+    let base;
+    if (platform === 'windows') {
+        base = PLATFORM_FINGERPRINTS.windows[hash.charCodeAt(0) % PLATFORM_FINGERPRINTS.windows.length];
+    }
+    else if (platform === 'macos') {
+        base = PLATFORM_FINGERPRINTS.macos[hash.charCodeAt(0) % PLATFORM_FINGERPRINTS.macos.length];
+    }
+    else {
+        const useWindows = hash.charCodeAt(0) % 2 === 0;
+        const pool = useWindows ? PLATFORM_FINGERPRINTS.windows : PLATFORM_FINGERPRINTS.macos;
+        base = pool[hash.charCodeAt(1) % pool.length];
+    }
+    return {
+        profileId,
+        userAgent: base.userAgent,
+        platform: base.platform,
+        osVersion: base.osVersion,
+        languages: ['zh-CN', 'zh', 'en-US', 'en'],
+        language: 'zh-CN',
+        hardwareConcurrency: [4, 6, 8, 12, 16][hash.charCodeAt(1) % 5],
+        deviceMemory: [4, 8, 16, 32][hash.charCodeAt(2) % 4],
+        viewport: {
+            width: [1366, 1440, 1536, 1920][hash.charCodeAt(3) % 4],
+            height: [768, 900, 864, 1080][hash.charCodeAt(4) % 4],
+        },
+        timezoneId: 'Asia/Shanghai',
+        maxTouchPoints: 0,
+        vendor: 'Google Inc.',
+        renderer: 'ANGLE (NVIDIA, NVIDIA GeForce, D3D11)',
+        originalPlatform: platform || (base.platform === 'Win32' ? 'windows' : 'macos'),
+        // 增加一个随机噪声用于区分 profile
+        fingerprintSalt: hash.slice(0, 8),
+    };
+}
+export async function applyFingerprint(context, fingerprint) {
+    if (!context || !fingerprint)
+        return;
+    try {
+        // 设置User-Agent
+        if (fingerprint.userAgent) {
+            await context.addInitScript(`
+                Object.defineProperty(navigator, 'userAgent', {
+                    get: () => '${fingerprint.userAgent}',
+                    configurable: true
+                });
+                Object.defineProperty(navigator, 'platform', {
+                    get: () => '${fingerprint.platform}',
+                    configurable: true
+                });
+                Object.defineProperty(navigator, 'osVersion', {
+                    get: () => '${fingerprint.osVersion || ''}',
+                    configurable: true
+                });
+            `);
+        }
+        if (fingerprint.vendor) {
+            await context.addInitScript(`
+                Object.defineProperty(navigator, 'vendor', {
+                    get: () => '${fingerprint.vendor}',
+                    configurable: true
+                });
+            `);
+        }
+        // 设置语言
+        if (fingerprint.languages && fingerprint.language) {
+            await context.addInitScript(`
+                Object.defineProperty(navigator, 'language', {
+                    get: () => '${fingerprint.language}',
+                    configurable: true
+                });
+
+                Object.defineProperty(navigator, 'languages', {
+                    get: () => ${JSON.stringify(fingerprint.languages)},
+                    configurable: true
+                });
+            `);
+        }
+        // 设置硬件信息
+        if (fingerprint.hardwareConcurrency) {
+            await context.addInitScript(`
+                Object.defineProperty(navigator, 'hardwareConcurrency', {
+                    get: () => ${fingerprint.hardwareConcurrency},
+                    configurable: true
+                });
+            `);
+        }
+        // 设置设备内存
+        if (fingerprint.deviceMemory) {
+            await context.addInitScript(`
+                Object.defineProperty(navigator, 'deviceMemory', {
+                    get: () => ${fingerprint.deviceMemory},
+                    configurable: true
+                });
+            `);
+        }
+        // 设置视口 (Camoufox 已在启动时应用，无需重新设置)
+        // if (fingerprint.viewport) {
+        //     await context.setViewportSize?.(fingerprint.viewport);
+        // }
+        // 设置时区
+        if (fingerprint.timezoneId) {
+            context.timezoneId = fingerprint.timezoneId;
+        }
+        // 移除webdriver标识
+        await context.addInitScript(`
+            Object.defineProperty(navigator, 'webdriver', {
+                get: () => undefined,
+                configurable: true
+            });
+
+            delete navigator.__proto__.webdriver;
+        `);
+    }
+    catch (error) {
+        console.warn('Failed to apply some fingerprint properties:', error?.message || error);
+    }
+}
+export async function loadFingerprint(fingerprintPath) {
+    try {
+        const data = await readFile(fingerprintPath, 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveFingerprint(fingerprintPath, fingerprint) {
+    try {
+        await mkdir(dirname(fingerprintPath), { recursive: true });
+        await writeFile(fingerprintPath, JSON.stringify(fingerprint, null, 2));
+        return true;
+    }
+    catch (error) {
+        console.error('Failed to save fingerprint:', error);
+        return false;
+    }
+}
+export function getFingerprintPath(profileId) {
+    return join(resolveFingerprintDir(), `${profileId}.json`);
+}
+export async function generateAndSaveFingerprint(profileId, options = {}) {
+    const fingerprint = generateFingerprint(profileId, options);
+    const path = getFingerprintPath(profileId);
+    await saveFingerprint(path, fingerprint);
+    return { fingerprint, path };
+}
+export async function loadOrGenerateFingerprint(profileId, options = {}) {
+    const path = getFingerprintPath(profileId);
+    let fingerprint = await loadFingerprint(path);
+    if (!fingerprint) {
+        fingerprint = generateFingerprint(profileId, options);
+        await saveFingerprint(path, fingerprint);
+    }
+    return fingerprint;
+}
+export const FINGERPRINT_DIR = resolveFingerprintDir();
+//# sourceMappingURL=fingerprint.js.map

package/src/services/browser-service/internal/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../../../../modules/camo-backend/src/internal/fingerprint.ts"],"names":[],"mappings":"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"}

package/src/services/browser-service/internal/heartbeat.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR, ensureDir } from '../../../utils/config.mjs';
+
+function resolveNumber(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return parsed;
+}
+
+function resolveHeartbeatFile(filePath) {
+  const explicit = String(filePath || '').trim();
+  if (explicit) return explicit;
+  const envPath = String(process.env.CAMO_HEARTBEAT_FILE || '').trim();
+  if (envPath) return envPath;
+  return path.join(CONFIG_DIR, 'run', 'camo-heartbeat.json');
+}
+
+function readHeartbeat(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object') return null;
+    return {
+      ts: typeof data.ts === 'string' ? data.ts : undefined,
+      status: typeof data.status === 'string' ? data.status : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function startHeartbeatWriter(options = {}) {
+  const filePath = resolveHeartbeatFile(options.filePath);
+  const intervalMs = resolveNumber(
+    options.intervalMs ?? process.env.CAMO_HEARTBEAT_INTERVAL_MS,
+    5000,
+  );
+  const staleMs = resolveNumber(
+    options.staleMs ?? process.env.CAMO_HEARTBEAT_STALE_MS,
+    45000,
+  );
+  let status = String(options.initialStatus || 'running');
+
+  process.env.CAMO_HEARTBEAT_FILE = filePath;
+  process.env.CAMO_HEARTBEAT_INTERVAL_MS = String(intervalMs);
+  process.env.CAMO_HEARTBEAT_STALE_MS = String(staleMs);
+
+  try {
+    ensureDir(path.dirname(filePath));
+  } catch {
+    // ignore
+  }
+
+  const write = (nextStatus) => {
+    if (nextStatus) status = String(nextStatus);
+    const payload = {
+      pid: process.pid,
+      ts: new Date().toISOString(),
+      status,
+    };
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(payload));
+    } catch {
+      // ignore
+    }
+  };
+
+  write(status);
+  const timer = setInterval(() => write(), intervalMs);
+  timer.unref();
+
+  const stop = () => {
+    write('stopped');
+    clearInterval(timer);
+  };
+
+  process.on('exit', stop);
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+
+  const setStatus = (nextStatus) => {
+    write(nextStatus || 'running');
+  };
+
+  return { stop, filePath, intervalMs, staleMs, setStatus };
+}
+
+export function startHeartbeatWatcher(options = {}) {
+  const filePath = options.filePath || process.env.CAMO_HEARTBEAT_FILE;
+  if (!filePath) return () => {};
+
+  const staleMs = resolveNumber(options.staleMs ?? process.env.CAMO_HEARTBEAT_STALE_MS, 45000);
+  const intervalMs = resolveNumber(options.intervalMs ?? process.env.CAMO_HEARTBEAT_INTERVAL_MS, Math.max(2000, Math.floor(staleMs / 3)));
+  const serviceName = options.serviceName || 'service';
+  const startAt = Date.now();
+
+  const timer = setInterval(() => {
+    let ts = 0;
+    let status = '';
+
+    const payload = readHeartbeat(filePath);
+    if (payload) {
+      status = String(payload.status || '');
+      ts = payload.ts ? Date.parse(payload.ts) : 0;
+    }
+
+    if (!ts) {
+      try {
+        const stat = fs.statSync(filePath);
+        ts = Number(stat.mtimeMs || 0);
+      } catch (err) {
+        if (err?.code === 'ENOENT') {
+          if (Date.now() - startAt > staleMs) {
+            console.warn(`[heartbeat] ${serviceName} exit: heartbeat file missing (${filePath})`);
+            process.exit(0);
+          }
+        }
+        return;
+      }
+    }
+
+    if (status === 'stopped') {
+      console.warn(`[heartbeat] ${serviceName} exit: main process stopped`);
+      process.exit(0);
+    }
+
+    const age = Date.now() - ts;
+    if (age > staleMs) {
+      console.warn(`[heartbeat] ${serviceName} exit: heartbeat stale ${age}ms > ${staleMs}ms`);
+      process.exit(0);
+    }
+  }, intervalMs);
+
+  timer.unref();
+  return () => clearInterval(timer);
+}

package/src/services/browser-service/internal/logging.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR, ensureDir } from '../../../utils/config.mjs';
+
+const LOG_DIR = String(process.env.CAMO_LOG_DIR || '').trim() || path.join(CONFIG_DIR, 'logs');
+const DEBUG_LOG_FILE = path.join(LOG_DIR, 'debug.jsonl');
+let debugReady = false;
+
+function isDebugEnabled() {
+  return (
+    process.env.DEBUG === '1'
+    || process.env.debug === '1'
+    || process.env.CAMO_DEBUG === '1'
+    || process.env.CAMO_DEBUG === '1'
+    || process.env.CAMO_DEBUG === '1'
+  );
+}
+
+function ensureDebugLogDir() {
+  if (debugReady) return;
+  try {
+    ensureDir(LOG_DIR);
+    debugReady = true;
+  } catch {
+    // ignore
+  }
+}
+
+export function logDebug(module, event, data = {}) {
+  if (!isDebugEnabled()) return;
+  ensureDebugLogDir();
+  const entry = {
+    ts: Date.now(),
+    level: 'debug',
+    module,
+    event,
+    data,
+  };
+  try {
+    fs.appendFileSync(DEBUG_LOG_FILE, `${JSON.stringify(entry)}\n`, 'utf8');
+  } catch {
+    // ignore
+  }
+}
+
+export { DEBUG_LOG_FILE };