@aluvia/sdk 1.1.0 → 1.3.0

package/dist/esm/client/BlockDetection.js

@@ -0,0 +1,482 @@
+// BlockDetection - Website block detection with weighted scoring
+const DEFAULT_CHALLENGE_SELECTORS = [
+    "#challenge-form",
+    "#challenge-running",
+    ".cf-browser-verification",
+    'iframe[src*="recaptcha"]',
+    ".g-recaptcha",
+    "#px-captcha",
+    'iframe[src*="hcaptcha"]',
+    ".h-captcha",
+];
+const TITLE_KEYWORDS = [
+    "access denied",
+    "blocked",
+    "forbidden",
+    "security check",
+    "attention required",
+    "just a moment",
+];
+const STRONG_TEXT_KEYWORDS = [
+    "captcha",
+    "access denied",
+    "verify you are human",
+    "bot detection",
+];
+const WEAK_TEXT_KEYWORDS = [
+    "blocked",
+    "forbidden",
+    "cloudflare",
+    "please verify",
+    "unusual activity",
+];
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const WEAK_TEXT_REGEXES = WEAK_TEXT_KEYWORDS.map((keyword) => ({
+    keyword,
+    regex: new RegExp("\\b" + escapeRegex(keyword) + "\\b", "i"),
+}));
+const CHALLENGE_DOMAIN_PATTERNS = [
+    "/cdn-cgi/challenge-platform/",
+    "challenges.cloudflare.com",
+    "geo.captcha-delivery.com",
+];
+/**
+ * BlockDetection handles detection of website blocks, CAPTCHAs, and WAF challenges
+ * using a weighted scoring system across multiple signal types.
+ */
+export class BlockDetection {
+    constructor(config, logger) {
+        // Persistent block tracking
+        this.retriedUrls = new Set();
+        this.persistentHostnames = new Set();
+        this.logger = logger;
+        this.config = {
+            enabled: config.enabled ?? true,
+            challengeSelectors: config.challengeSelectors ?? DEFAULT_CHALLENGE_SELECTORS,
+            extraKeywords: config.extraKeywords ?? [],
+            extraStatusCodes: config.extraStatusCodes ?? [],
+            networkIdleTimeoutMs: config.networkIdleTimeoutMs ?? 3000,
+            autoUnblock: config.autoUnblock ?? false,
+            autoUnblockOnSuspected: config.autoUnblockOnSuspected ?? false,
+            onDetection: config.onDetection,
+        };
+        // Pre-compute for hot-path performance
+        this.statusCodeSet = new Set([403, 429, ...this.config.extraStatusCodes]);
+        this.allTitleKeywords = [...TITLE_KEYWORDS, ...this.config.extraKeywords];
+    }
+    getNetworkIdleTimeoutMs() {
+        return this.config.networkIdleTimeoutMs;
+    }
+    isEnabled() {
+        return this.config.enabled;
+    }
+    getOnDetection() {
+        return this.config.onDetection;
+    }
+    isAutoUnblock() {
+        return this.config.autoUnblock;
+    }
+    isAutoUnblockOnSuspected() {
+        return this.config.autoUnblockOnSuspected;
+    }
+    // --- Scoring Engine ---
+    computeScore(signals) {
+        if (signals.length === 0)
+            return { score: 0, blockStatus: "clear" };
+        const score = 1 - signals.reduce((product, s) => product * (1 - s.weight), 1);
+        const blockStatus = score >= 0.7 ? "blocked" : score >= 0.4 ? "suspected" : "clear";
+        return { score, blockStatus };
+    }
+    // --- Fast-pass Signal Detectors ---
+    detectHttpStatus(response) {
+        const status = response?.status?.() ?? 0;
+        if (status === 0)
+            return null;
+        if (this.statusCodeSet.has(status)) {
+            return {
+                name: `http_status_${status}`,
+                weight: 0.85,
+                details: `HTTP ${status} response`,
+                source: "fast",
+            };
+        }
+        if (status === 503) {
+            return {
+                name: "http_status_503",
+                weight: 0.6,
+                details: "HTTP 503 response",
+                source: "fast",
+            };
+        }
+        return null;
+    }
+    detectResponseHeaders(response) {
+        const signals = [];
+        if (!response)
+            return signals;
+        try {
+            const headers = response.headers?.() ?? {};
+            const cfMitigated = headers["cf-mitigated"];
+            if (cfMitigated &&
+                cfMitigated.toLowerCase().includes("challenge")) {
+                signals.push({
+                    name: "waf_header_cf_mitigated",
+                    weight: 0.9,
+                    details: `cf-mitigated: ${cfMitigated}`,
+                    source: "fast",
+                });
+            }
+            const server = headers["server"];
+            if (server && server.toLowerCase().includes("cloudflare")) {
+                signals.push({
+                    name: "waf_header_cloudflare",
+                    weight: 0.1,
+                    details: `server: ${server}`,
+                    source: "fast",
+                });
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return signals;
+    }
+    // --- Full-pass Signal Detectors ---
+    async detectTitleKeywords(page) {
+        try {
+            const title = (await page.title()).toLowerCase();
+            for (const keyword of this.allTitleKeywords) {
+                if (title.includes(keyword.toLowerCase())) {
+                    return {
+                        name: "title_keyword",
+                        weight: 0.8,
+                        details: `Title contains "${keyword}"`,
+                        source: "full",
+                    };
+                }
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return null;
+    }
+    async detectChallengeSelectors(page) {
+        try {
+            const selectors = this.config.challengeSelectors;
+            const found = await page.evaluate((sels) => {
+                for (const sel of sels) {
+                    if (document.querySelector(sel))
+                        return sel;
+                }
+                return null;
+            }, selectors);
+            if (found) {
+                return {
+                    name: "challenge_selector",
+                    weight: 0.8,
+                    details: `Challenge selector found: ${found}`,
+                    source: "full",
+                };
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return null;
+    }
+    async detectVisibleText(page, useInnerText = false) {
+        const signals = [];
+        try {
+            const text = useInnerText
+                ? await page.evaluate(() => document.body?.innerText ?? "")
+                : await page.evaluate(() => document.body?.textContent ?? "");
+            const textLower = text.toLowerCase();
+            if (text.length < 50) {
+                signals.push({
+                    name: "visible_text_short",
+                    weight: 0.2,
+                    details: `Visible text very short (${text.length} chars)`,
+                    source: "full",
+                });
+            }
+            // Strong keywords (substring match, short page < 500 chars)
+            if (text.length < 500) {
+                const allStrong = [
+                    ...STRONG_TEXT_KEYWORDS,
+                    ...this.config.extraKeywords,
+                ];
+                for (const keyword of allStrong) {
+                    if (textLower.includes(keyword.toLowerCase())) {
+                        signals.push({
+                            name: "visible_text_keyword_strong",
+                            weight: 0.6,
+                            details: `Strong keyword "${keyword}" on short page`,
+                            source: "full",
+                        });
+                        break;
+                    }
+                }
+            }
+            // Weak keywords (word-boundary match, pre-compiled regexes)
+            for (const { keyword, regex } of WEAK_TEXT_REGEXES) {
+                if (regex.test(text)) {
+                    signals.push({
+                        name: "visible_text_keyword_weak",
+                        weight: 0.15,
+                        details: `Weak keyword "${keyword}" found with word boundary`,
+                        source: "full",
+                    });
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return signals;
+    }
+    async detectTextToHtmlRatio(page) {
+        try {
+            const result = await page.evaluate(() => {
+                const html = document.documentElement?.outerHTML ?? "";
+                const text = document.body?.textContent ?? "";
+                return { htmlLength: html.length, textLength: text.length };
+            });
+            if (result.htmlLength >= 1000 &&
+                result.textLength / result.htmlLength < 0.03) {
+                return {
+                    name: "low_text_ratio",
+                    weight: 0.2,
+                    details: `Low text/HTML ratio: ${result.textLength}/${result.htmlLength}`,
+                    source: "full",
+                };
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return null;
+    }
+    detectRedirectChain(response) {
+        const chain = [];
+        const signals = [];
+        try {
+            if (!response)
+                return { signals, chain };
+            // Walk redirect chain backwards
+            let req = response.request?.();
+            const hops = [];
+            while (req) {
+                const redirectedFrom = req.redirectedFrom?.();
+                if (!redirectedFrom)
+                    break;
+                const redirectResponse = redirectedFrom.response?.();
+                hops.push({
+                    url: redirectedFrom.url?.() ?? "",
+                    statusCode: redirectResponse?.status?.() ?? 0,
+                });
+                req = redirectedFrom;
+            }
+            // Reverse to get chronological order
+            hops.reverse();
+            chain.push(...hops);
+            // Check if any hop URL matches challenge domain patterns
+            for (const hop of chain) {
+                for (const pattern of CHALLENGE_DOMAIN_PATTERNS) {
+                    if (hop.url.includes(pattern)) {
+                        signals.push({
+                            name: "redirect_to_challenge",
+                            weight: 0.7,
+                            details: `Redirect through challenge domain: ${hop.url}`,
+                            source: "full",
+                        });
+                        return { signals, chain };
+                    }
+                }
+            }
+            // Also check the final response URL
+            const finalUrl = response.url?.() ?? "";
+            for (const pattern of CHALLENGE_DOMAIN_PATTERNS) {
+                if (finalUrl.includes(pattern)) {
+                    signals.push({
+                        name: "redirect_to_challenge",
+                        weight: 0.7,
+                        details: `Final URL is challenge domain: ${finalUrl}`,
+                        source: "full",
+                    });
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return { signals, chain };
+    }
+    async detectMetaRefresh(page) {
+        try {
+            const refreshUrl = await page.evaluate(() => {
+                const meta = document.querySelector('meta[http-equiv="refresh"]');
+                if (!meta)
+                    return null;
+                const content = meta.getAttribute("content") ?? "";
+                const match = content.match(/url\s*=\s*(.+)/i);
+                return match ? match[1].trim() : null;
+            });
+            if (refreshUrl) {
+                for (const pattern of CHALLENGE_DOMAIN_PATTERNS) {
+                    if (refreshUrl.includes(pattern)) {
+                        return {
+                            name: "meta_refresh_challenge",
+                            weight: 0.65,
+                            details: `Meta refresh to challenge URL: ${refreshUrl}`,
+                            source: "full",
+                        };
+                    }
+                }
+            }
+        }
+        catch (err) {
+            this.logger.debug(`Detection check failed: ${err.message}`);
+        }
+        return null;
+    }
+    // --- Two-Pass Analysis API ---
+    /**
+     * Fast pass - runs at domcontentloaded. Only HTTP status + response headers.
+     * If score >= 0.9, caller should trigger remediation immediately.
+     */
+    async analyzeFast(page, response) {
+        const url = page.url();
+        const hostname = this.extractHostname(url);
+        if (!this.config.enabled) {
+            return this.makeResult(url, hostname, [], "fast", []);
+        }
+        const signals = [];
+        const statusSignal = this.detectHttpStatus(response);
+        if (statusSignal)
+            signals.push(statusSignal);
+        const headerSignals = this.detectResponseHeaders(response);
+        signals.push(...headerSignals);
+        const result = this.makeResult(url, hostname, signals, "fast", []);
+        this.logResult(result);
+        return result;
+    }
+    /**
+     * Run all content-based detectors in parallel.
+     * Shared by analyzeFull and analyzeSpa.
+     */
+    async runContentDetectors(page) {
+        const [titleSignal, challengeSignal, textSignals, ratioSignal, metaSignal] = await Promise.all([
+            this.detectTitleKeywords(page),
+            this.detectChallengeSelectors(page),
+            this.detectVisibleText(page, false),
+            this.detectTextToHtmlRatio(page),
+            this.detectMetaRefresh(page),
+        ]);
+        const signals = [];
+        if (titleSignal)
+            signals.push(titleSignal);
+        if (challengeSignal)
+            signals.push(challengeSignal);
+        signals.push(...textSignals);
+        if (ratioSignal)
+            signals.push(ratioSignal);
+        if (metaSignal)
+            signals.push(metaSignal);
+        return signals;
+    }
+    /**
+     * Full pass - runs after networkidle. Runs all detectors and merges with fast pass.
+     */
+    async analyzeFull(page, response, fastResult) {
+        const url = page.url();
+        const hostname = this.extractHostname(url);
+        if (!this.config.enabled) {
+            return this.makeResult(url, hostname, [], "full", []);
+        }
+        // Start with fast-pass signals
+        const signals = fastResult
+            ? [...fastResult.signals]
+            : [];
+        // If no fast pass was done and we have a response, run fast detectors
+        if (!fastResult && response) {
+            const statusSignal = this.detectHttpStatus(response);
+            if (statusSignal)
+                signals.push(statusSignal);
+            const headerSignals = this.detectResponseHeaders(response);
+            signals.push(...headerSignals);
+        }
+        signals.push(...await this.runContentDetectors(page));
+        const { signals: redirectSignals, chain } = this.detectRedirectChain(response);
+        signals.push(...redirectSignals);
+        return this.reEvaluateIfSuspected(page, url, hostname, signals, chain);
+    }
+    /**
+     * SPA navigation analysis - content-based detectors only, no HTTP signals.
+     */
+    async analyzeSpa(page) {
+        const url = page.url();
+        const hostname = this.extractHostname(url);
+        if (!this.config.enabled) {
+            return this.makeResult(url, hostname, [], "full", []);
+        }
+        const signals = await this.runContentDetectors(page);
+        return this.reEvaluateIfSuspected(page, url, hostname, signals, []);
+    }
+    async reEvaluateIfSuspected(page, url, hostname, signals, redirectChain) {
+        const preliminary = this.computeScore(signals);
+        if (preliminary.score >= 0.4 && preliminary.score < 0.7) {
+            const nonTextSignals = signals.filter((s) => !s.name.startsWith("visible_text_"));
+            const innerTextSignals = await this.detectVisibleText(page, true);
+            nonTextSignals.push(...innerTextSignals);
+            const result = this.makeResult(url, hostname, nonTextSignals, "full", redirectChain);
+            this.logResult(result);
+            return result;
+        }
+        const result = this.makeResult(url, hostname, signals, "full", redirectChain);
+        this.logResult(result);
+        return result;
+    }
+    // --- Utility Methods ---
+    makeResult(url, hostname, signals, pass, redirectChain) {
+        const { score, blockStatus } = this.computeScore(signals);
+        return {
+            url,
+            hostname,
+            blockStatus,
+            score,
+            signals,
+            pass,
+            persistentBlock: false,
+            redirectChain,
+        };
+    }
+    logResult(result) {
+        if (!this.logger.isDebug)
+            return;
+        this.logger.debug(`Detection result: ${JSON.stringify({
+            url: result.url,
+            blockStatus: result.blockStatus,
+            score: result.score,
+            signals: result.signals.map((s) => ({
+                name: s.name,
+                weight: s.weight,
+                source: s.source,
+            })),
+            pass: result.pass,
+        })}`);
+    }
+    extractHostname(url) {
+        try {
+            const parsed = new URL(url);
+            return parsed.hostname || url;
+        }
+        catch {
+            return url;
+        }
+    }
+}

package/dist/esm/client/ConfigManager.js

@@ -2,9 +2,8 @@
 import { Logger } from './logger.js';
 import { InvalidApiKeyError, ApiError } from '../errors.js';
 import { requestCore } from '../api/request.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
+import { isRecord, throwIfAuthError } from '../api/apiUtils.js';
+import { normalizeRules } from './rules.js';
 function toAccountConnectionApiResponse(value) {
     if (!isRecord(value))
         return {};
@@ -45,6 +44,10 @@ function toValidationErrors(value) {
  * - Providing current config to ProxyServer
  */
 export class ConfigManager {
+    /** Public read-only access to the account connection ID. */
+    get connectionId() {
+        return this.accountConnectionId;
+    }
     constructor(options) {
         this.config = null;
         this.timer = null;
@@ -62,7 +65,7 @@ export class ConfigManager {
      */
     async init() {
         if (this.options.connectionId) {
-            this.accountConnectionId = this.options.connectionId ?? null;
+            this.accountConnectionId = this.options.connectionId;
             this.logger.info(`Using account connection API (connection id: ${this.accountConnectionId})`);
             let result;
             try {
@@ -79,9 +82,7 @@ export class ConfigManager {
                 const msg = err instanceof Error ? err.message : String(err);
                 throw new ApiError(`Failed to fetch account connection config: ${msg}`);
             }
-            if (result.status === 401 || result.status === 403) {
-                throw new InvalidApiKeyError(`Authentication failed with status ${result.status}`);
-            }
+            throwIfAuthError(result.status);
             if (result.status === 200 && result.body) {
                 this.config = this.buildConfigFromAny(result.body, result.etag);
                 this.logger.info('Configuration loaded successfully');
@@ -100,12 +101,11 @@ export class ConfigManager {
                 path: '/account/connections',
                 body: {},
             });
-            if (created.status === 401 || created.status === 403) {
-                throw new InvalidApiKeyError(`Authentication failed with status ${created.status}`);
-            }
+            throwIfAuthError(created.status);
             if ((created.status === 200 || created.status === 201) && created.body) {
                 const createdResponse = toAccountConnectionApiResponse(created.body);
-                this.accountConnectionId = Number(createdResponse.data?.connection_id);
+                const rawId = Number(createdResponse.data?.connection_id);
+                this.accountConnectionId = Number.isFinite(rawId) ? rawId : undefined;
                 if (this.accountConnectionId != null) {
                     this.logger.info(`Account connection created (connection id: ${this.accountConnectionId})`);
                 }
@@ -165,6 +165,7 @@ export class ConfigManager {
                 this.pollInFlight = false;
             }
         }, this.options.pollIntervalMs);
+        this.timer.unref();
     }
     /**
      * Stop polling for configuration updates.
@@ -184,6 +185,9 @@ export class ConfigManager {
         return this.config;
     }
     async setConfig(body) {
+        if (this.accountConnectionId == null || !Number.isFinite(this.accountConnectionId)) {
+            throw new ApiError('Cannot update config: no account connection ID. Ensure init() succeeds first.');
+        }
         this.logger.debug(`Setting config: ${JSON.stringify(body)}`);
         let result;
         try {
@@ -201,9 +205,7 @@ export class ConfigManager {
             const msg = err instanceof Error ? err.message : String(err);
             throw new ApiError(`Failed to update account connection config: ${msg}`);
         }
-        if (result.status === 401 || result.status === 403) {
-            throw new InvalidApiKeyError(`Authentication failed with status ${result.status}`);
-        }
+        throwIfAuthError(result.status);
         if (result.status === 200 && result.body) {
             this.config = this.buildConfigFromAny(result.body, result.etag);
             this.logger.debug('Configuration updated from API');
@@ -223,8 +225,8 @@ export class ConfigManager {
      * Called by the polling timer.
      */
     async pollOnce() {
-        if (!this.config) {
-            this.logger.warn('No config available, skipping poll');
+        if (!this.config || this.accountConnectionId == null) {
+            this.logger.warn('No config or connection ID available, skipping poll');
             return;
         }
         try {
@@ -260,8 +262,8 @@ export class ConfigManager {
         const rules = Array.isArray(data?.rules) ? data.rules : [];
         const sessionId = data?.session_id ?? null;
         const targetGeo = data?.target_geo ?? null;
-        const username = data?.proxy_username ?? null;
-        const password = data?.proxy_password ?? null;
+        const username = (data?.proxy_username ?? '').trim() || null;
+        const password = (data?.proxy_password ?? '').trim() || null;
         if (!username || !password) {
             throw new ApiError('Account connection response missing proxy credentials (data.proxy_username and data.proxy_password are required)', 500);
         }
@@ -274,6 +276,7 @@ export class ConfigManager {
                 password,
             },
             rules,
+            normalizedRules: normalizeRules(rules),
             sessionId,
             targetGeo,
             etag,