@slashgear/gdpr-cookie-scanner 1.0.0

package/src/scanner/browser.ts

@@ -0,0 +1,52 @@
+import { chromium, type Browser, type BrowserContext, type Page } from "playwright";
+import type { ScanOptions } from "../types.js";
+
+export interface BrowserSession {
+  browser: Browser;
+  context: BrowserContext;
+  page: Page;
+}
+
+export async function createBrowser(options: ScanOptions): Promise<BrowserSession> {
+  const browser = await chromium.launch({
+    headless: true,
+    args: [
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+      "--disable-dev-shm-usage",
+      "--disable-blink-features=AutomationControlled",
+    ],
+  });
+
+  const context = await browser.newContext({
+    locale: options.locale,
+    viewport: { width: 1280, height: 900 },
+    userAgent:
+      options.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",
+      ].join(" "),
+    // Disable existing cookies to get a clean state
+    storageState: undefined,
+  });
+
+  // Block known resource types that we don't need (speed up)
+  await context.route("**/*.{woff,woff2,ttf,eot,ico}", (route) => route.abort());
+
+  const page = await context.newPage();
+
+  return { browser, context, page };
+}
+
+export async function clearState(context: BrowserContext): Promise<void> {
+  await context.clearCookies();
+  await context.clearPermissions();
+}
+
+export async function closeBrowser(session: BrowserSession): Promise<void> {
+  await session.page.close().catch(() => null);
+  await session.context.close().catch(() => null);
+  await session.browser.close().catch(() => null);
+}

package/src/scanner/consent-modal.ts

@@ -0,0 +1,276 @@
+import type { Page } from "playwright";
+import type { ConsentModal, ConsentButton, ConsentCheckbox, ConsentButtonType } from "../types.js";
+import { analyzeButtonWording } from "../analyzers/wording.js";
+import type { ScanOptions } from "../types.js";
+
+/**
+ * Ordered list of CSS selectors to try for detecting a consent modal/banner.
+ * Covers major CMP platforms (Axeptio, Cookiebot, OneTrust, Didomi, Tarteaucitron, etc.)
+ */
+const MODAL_SELECTORS = [
+  // Well-known CMPs
+  "#axeptio_overlay",
+  "#axeptio-root",
+  "#CybotCookiebotDialog",
+  "#onetrust-consent-sdk",
+  "#onetrust-banner-sdk",
+  ".didomi-popup-container",
+  ".didomi-consent-popup",
+  "#didomi-host",
+  "#tarteaucitronRoot",
+  "#tarteaucitron",
+  "#usercentrics-root",
+  "#sp-cc",
+  "#gdpr-consent-tool-wrapper",
+  ".cc-banner",
+  ".cc-window",
+  "#cookieConsent",
+  "#cookie-consent",
+  "#cookie-banner",
+  "#cookie-notice",
+  "#cookie-law-info-bar",
+  // Generic heuristics
+  "[class*='cookie'][class*='banner']",
+  "[class*='cookie'][class*='modal']",
+  "[class*='cookie'][class*='popup']",
+  "[class*='consent'][class*='banner']",
+  "[class*='consent'][class*='modal']",
+  "[id*='cookie'][id*='banner']",
+  "[id*='cookie'][id*='modal']",
+  "[id*='consent']",
+  "[aria-label*='cookie' i]",
+  "[aria-label*='consent' i]",
+  "[aria-label*='cookies' i]",
+  "[role='dialog'][aria-label*='cookie' i]",
+  "[role='alertdialog']",
+];
+
+const ACCEPT_PATTERNS = [
+  /\b(accept|accepter|acceptez|tout accepter|accept all|j'accepte|i accept|agree|ok\b|d'accord|continuer|continue|valider|confirmer)\b/i,
+];
+
+const REJECT_PATTERNS = [
+  /\b(refus|refuse|refuser|reject|deny|decline|tout refuser|reject all|non merci|no thanks|continuer sans accepter|skip)\b/i,
+];
+
+const PREFERENCES_PATTERNS = [
+  /\b(param[eè]tres|pr[eé]f[eé]rences|personnaliser|customise|customize|manage|g[eé]rer|options|choose|choisir|configure)\b/i,
+];
+
+export async function detectConsentModal(page: Page, options: ScanOptions): Promise<ConsentModal> {
+  // Try each selector until we find a visible modal
+  let foundSelector: string | null = null;
+
+  for (const selector of MODAL_SELECTORS) {
+    try {
+      const element = await page.$(selector);
+      if (!element) continue;
+      const isVisible = await element.isVisible();
+      if (isVisible) {
+        foundSelector = selector;
+        break;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // Fallback: look for any large fixed/sticky element with cookie-related text
+  if (!foundSelector) {
+    foundSelector = await page.evaluate(() => {
+      const candidates = document.querySelectorAll("div, section, aside, dialog");
+      const keywords = /cookie|consent|consentement|rgpd|gdpr|privacy|vie priv/i;
+
+      for (const el of candidates) {
+        const style = window.getComputedStyle(el);
+        const isFixed = style.position === "fixed" || style.position === "sticky";
+        const text = el.textContent ?? "";
+        const hasCookieText = keywords.test(text);
+        const isLargeEnough = el.getBoundingClientRect().width > 200;
+
+        if (isFixed && hasCookieText && isLargeEnough) {
+          // Generate a unique selector
+          if (el.id) return `#${el.id}`;
+          const classes = Array.from(el.classList).slice(0, 2).join(".");
+          if (classes) return `${el.tagName.toLowerCase()}.${classes}`;
+        }
+      }
+      return null;
+    });
+  }
+
+  if (!foundSelector) {
+    return {
+      detected: false,
+      selector: null,
+      text: "",
+      buttons: [],
+      checkboxes: [],
+      hasGranularControls: false,
+      layerCount: 0,
+      screenshotPath: null,
+    };
+  }
+
+  // Extract modal text
+  const modalText = await page.$eval(foundSelector, (el) => el.textContent ?? "").catch(() => "");
+
+  // Find all buttons and interactive elements within the modal
+  const buttons = await extractButtons(page, foundSelector);
+
+  // Find checkboxes / toggles
+  const checkboxes = await extractCheckboxes(page, foundSelector);
+
+  // Detect if there are nested layers (e.g., "more options" behind a click)
+  const hasGranularControls =
+    checkboxes.length > 0 || buttons.some((b) => b.type === "preferences");
+
+  return {
+    detected: true,
+    selector: foundSelector,
+    text: modalText.trim().replace(/\s+/g, " "),
+    buttons,
+    checkboxes,
+    hasGranularControls,
+    layerCount: hasGranularControls ? 2 : 1,
+    screenshotPath: null,
+  };
+}
+
+async function extractButtons(page: Page, modalSelector: string): Promise<ConsentButton[]> {
+  const buttonEls = await page.$$(
+    `${modalSelector} button, ${modalSelector} [role="button"], ${modalSelector} a[href="#"]`,
+  );
+
+  const buttons: ConsentButton[] = [];
+
+  for (const el of buttonEls) {
+    try {
+      const text = ((await el.textContent()) ?? "").trim();
+      if (!text) continue;
+
+      const isVisible = await el.isVisible();
+      const box = await el.boundingBox();
+
+      const computedStyle = await el.evaluate((node) => {
+        const style = window.getComputedStyle(node as Element);
+        return {
+          fontSize: parseFloat(style.fontSize),
+          backgroundColor: style.backgroundColor,
+          color: style.color,
+        };
+      });
+
+      const type = classifyButtonType(text);
+
+      // Build a unique selector for this button
+      const selector = await el.evaluate((node) => {
+        const el = node as Element;
+        if (el.id) return `#${el.id}`;
+        const classes = Array.from(el.classList).slice(0, 3).join(".");
+        const tag = el.tagName.toLowerCase();
+        // Try to build a text-based selector as fallback
+        const escapedText = el.textContent?.trim().substring(0, 30) ?? "";
+        return classes ? `${tag}.${classes}` : `${tag}:has-text("${escapedText}")`;
+      });
+
+      const contrastRatio = computeContrastRatio(
+        computedStyle.color,
+        computedStyle.backgroundColor,
+      );
+
+      buttons.push({
+        type,
+        text,
+        selector,
+        isVisible,
+        boundingBox: box,
+        fontSize: computedStyle.fontSize || null,
+        backgroundColor: computedStyle.backgroundColor,
+        textColor: computedStyle.color,
+        contrastRatio,
+        clickDepth: 1,
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return buttons;
+}
+
+async function extractCheckboxes(page: Page, modalSelector: string): Promise<ConsentCheckbox[]> {
+  return page
+    .evaluate((selector) => {
+      const modal = document.querySelector(selector);
+      if (!modal) return [];
+
+      const checkboxes: ConsentCheckbox[] = [];
+      const inputs = modal.querySelectorAll(
+        'input[type="checkbox"], input[type="radio"], [role="switch"], [role="checkbox"]',
+      );
+
+      for (const input of inputs) {
+        const el = input as HTMLInputElement;
+        // Find associated label
+        let label = "";
+        if (el.id) {
+          const labelEl = document.querySelector(`label[for="${el.id}"]`);
+          label = labelEl?.textContent?.trim() ?? "";
+        }
+        if (!label) {
+          const parent = el.closest("label") ?? el.parentElement;
+          label = parent?.textContent?.trim() ?? "";
+        }
+
+        checkboxes.push({
+          name: el.name || el.id || "",
+          label: label.substring(0, 100),
+          isCheckedByDefault: el.checked || el.getAttribute("aria-checked") === "true",
+          category: "unknown", // will be classified later
+          selector: el.id ? `#${el.id}` : "",
+        });
+      }
+
+      return checkboxes;
+    }, modalSelector)
+    .catch(() => [] as ConsentCheckbox[]);
+}
+
+function classifyButtonType(text: string): ConsentButtonType {
+  if (ACCEPT_PATTERNS.some((p) => p.test(text))) return "accept";
+  if (REJECT_PATTERNS.some((p) => p.test(text))) return "reject";
+  if (PREFERENCES_PATTERNS.some((p) => p.test(text))) return "preferences";
+  if (/\b(ferm|close|×|✕)\b/i.test(text)) return "close";
+  return "unknown";
+}
+
+/**
+ * Basic contrast ratio computation from RGB strings.
+ * Returns null if colors cannot be parsed.
+ */
+function computeContrastRatio(fg: string, bg: string): number | null {
+  const fgRgb = parseRgb(fg);
+  const bgRgb = parseRgb(bg);
+  if (!fgRgb || !bgRgb) return null;
+
+  const fgL = relativeLuminance(fgRgb);
+  const bgL = relativeLuminance(bgRgb);
+  const lighter = Math.max(fgL, bgL);
+  const darker = Math.min(fgL, bgL);
+  return parseFloat(((lighter + 0.05) / (darker + 0.05)).toFixed(2));
+}
+
+function parseRgb(color: string): [number, number, number] | null {
+  const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+  if (!match) return null;
+  return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+
+function relativeLuminance([r, g, b]: [number, number, number]): number {
+  const toLinear = (c: number) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}

package/src/scanner/cookies.ts

@@ -0,0 +1,43 @@
+import type { BrowserContext } from "playwright";
+import type { ScannedCookie } from "../types.js";
+import { classifyCookie } from "../classifiers/cookie-classifier.js";
+
+type CapturePhase = ScannedCookie["capturedAt"];
+
+export async function captureCookies(
+  context: BrowserContext,
+  phase: CapturePhase,
+): Promise<ScannedCookie[]> {
+  const rawCookies = await context.cookies();
+
+  return rawCookies.map((c) => {
+    const classification = classifyCookie(c.name, c.domain, c.value);
+    return {
+      name: c.name,
+      domain: c.domain,
+      path: c.path,
+      value: c.value.substring(0, 100), // truncate long values
+      expires: c.expires === -1 ? null : c.expires,
+      httpOnly: c.httpOnly,
+      secure: c.secure,
+      sameSite: c.sameSite ?? null,
+      category: classification.category,
+      requiresConsent: classification.requiresConsent,
+      capturedAt: phase,
+    };
+  });
+}
+
+export function diffCookies(
+  before: ScannedCookie[],
+  after: ScannedCookie[],
+): { added: ScannedCookie[]; removed: ScannedCookie[]; persisted: ScannedCookie[] } {
+  const beforeKeys = new Set(before.map((c) => `${c.domain}|${c.name}`));
+  const afterKeys = new Set(after.map((c) => `${c.domain}|${c.name}`));
+
+  return {
+    added: after.filter((c) => !beforeKeys.has(`${c.domain}|${c.name}`)),
+    removed: before.filter((c) => !afterKeys.has(`${c.domain}|${c.name}`)),
+    persisted: after.filter((c) => beforeKeys.has(`${c.domain}|${c.name}`)),
+  };
+}

package/src/scanner/index.ts

@@ -0,0 +1,163 @@
+import { mkdir } from "fs/promises";
+import { join } from "path";
+import type { ScanOptions, ScanResult } from "../types.js";
+import { createBrowser, clearState, closeBrowser } from "./browser.js";
+import { captureCookies } from "./cookies.js";
+import { createNetworkInterceptor } from "./network.js";
+import { detectConsentModal } from "./consent-modal.js";
+import { analyzeCompliance } from "../analyzers/compliance.js";
+
+type PhaseCallback = (message: string) => void;
+
+export class Scanner {
+  constructor(private readonly options: ScanOptions) {}
+
+  async run(onPhase: PhaseCallback = () => {}): Promise<ScanResult> {
+    const startTime = Date.now();
+    const screenshotPaths: string[] = [];
+    const errors: string[] = [];
+
+    if (this.options.screenshots) {
+      await mkdir(this.options.outputDir, { recursive: true });
+    }
+
+    // ────────────────────────────────────────────────────────────
+    // Phase 1 — Load page, capture state BEFORE any interaction
+    // ────────────────────────────────────────────────────────────
+    onPhase("Phase 1/4 — Loading page (no interaction)...");
+    const session1 = await createBrowser(this.options);
+    const interceptor1 = createNetworkInterceptor(session1.page, "before-interaction");
+
+    try {
+      await session1.page.goto(this.options.url, {
+        waitUntil: "networkidle",
+        timeout: this.options.timeout,
+      });
+    } catch (err) {
+      errors.push(`Navigation timeout or error: ${String(err)}`);
+    }
+
+    // Give a moment for late-loading scripts
+    await session1.page.waitForTimeout(2000);
+
+    const cookiesBeforeInteraction = await captureCookies(session1.context, "before-interaction");
+    const networkBeforeInteraction = interceptor1.getRequests();
+    interceptor1.stop();
+
+    // ────────────────────────────────────────────────────────────
+    // Phase 2 — Detect and analyze the consent modal
+    // ────────────────────────────────────────────────────────────
+    onPhase("Phase 2/4 — Analyzing consent modal...");
+    const modal = await detectConsentModal(session1.page, this.options);
+
+    if (this.options.screenshots && modal.detected) {
+      const screenshotPath = join(this.options.outputDir, "modal-initial.png");
+      await session1.page.screenshot({ path: screenshotPath, fullPage: false });
+      screenshotPaths.push(screenshotPath);
+      modal.screenshotPath = screenshotPath;
+    }
+
+    // ────────────────────────────────────────────────────────────
+    // Phase 3 — Click REJECT, capture state after
+    // ────────────────────────────────────────────────────────────
+    onPhase("Phase 3/4 — Testing reject button...");
+    const interceptor3 = createNetworkInterceptor(session1.page, "after-reject");
+
+    let cookiesAfterReject = cookiesBeforeInteraction;
+    let networkAfterReject: typeof networkBeforeInteraction = [];
+
+    const rejectButton = modal.buttons.find((b) => b.type === "reject");
+    if (rejectButton) {
+      try {
+        await session1.page.click(rejectButton.selector, { timeout: 5000 });
+        await session1.page.waitForTimeout(2000);
+        cookiesAfterReject = await captureCookies(session1.context, "after-reject");
+        networkAfterReject = interceptor3.getRequests();
+      } catch (err) {
+        errors.push(`Could not click reject button: ${String(err)}`);
+      }
+    } else {
+      errors.push("No reject button found — could not test rejection flow");
+    }
+    interceptor3.stop();
+
+    if (this.options.screenshots) {
+      const screenshotPath = join(this.options.outputDir, "after-reject.png");
+      await session1.page.screenshot({ path: screenshotPath, fullPage: false });
+      screenshotPaths.push(screenshotPath);
+    }
+
+    await closeBrowser(session1);
+
+    // ────────────────────────────────────────────────────────────
+    // Phase 4 — Fresh session, click ACCEPT, capture state after
+    // ────────────────────────────────────────────────────────────
+    onPhase("Phase 4/4 — Testing accept button...");
+    const session2 = await createBrowser(this.options);
+    await clearState(session2.context);
+    const interceptor4 = createNetworkInterceptor(session2.page, "after-accept");
+
+    let cookiesAfterAccept = cookiesBeforeInteraction;
+    let networkAfterAccept: typeof networkBeforeInteraction = [];
+
+    try {
+      await session2.page.goto(this.options.url, {
+        waitUntil: "networkidle",
+        timeout: this.options.timeout,
+      });
+      await session2.page.waitForTimeout(2000);
+
+      const modal2 = await detectConsentModal(session2.page, this.options);
+      const acceptButton = modal2.buttons.find((b) => b.type === "accept");
+
+      if (acceptButton) {
+        await session2.page.click(acceptButton.selector, { timeout: 5000 });
+        await session2.page.waitForTimeout(3000);
+        cookiesAfterAccept = await captureCookies(session2.context, "after-accept");
+        networkAfterAccept = interceptor4.getRequests();
+      } else {
+        errors.push("No accept button found — could not test acceptance flow");
+      }
+    } catch (err) {
+      errors.push(`Accept phase error: ${String(err)}`);
+    }
+    interceptor4.stop();
+
+    if (this.options.screenshots) {
+      const screenshotPath = join(this.options.outputDir, "after-accept.png");
+      await session2.page.screenshot({ path: screenshotPath, fullPage: false });
+      screenshotPaths.push(screenshotPath);
+    }
+
+    await closeBrowser(session2);
+
+    // ────────────────────────────────────────────────────────────
+    // Analyze compliance
+    // ────────────────────────────────────────────────────────────
+    const compliance = analyzeCompliance({
+      modal,
+      cookiesBeforeInteraction,
+      cookiesAfterAccept,
+      cookiesAfterReject,
+      networkBeforeInteraction,
+      networkAfterAccept,
+      networkAfterReject,
+    });
+
+    return {
+      url: this.options.url,
+      scanDate: new Date().toISOString(),
+      duration: Date.now() - startTime,
+      modal,
+      cookiesBeforeInteraction,
+      cookiesAfterAccept,
+      cookiesAfterReject,
+      networkBeforeInteraction,
+      networkAfterAccept,
+      networkAfterReject,
+      compliance,
+      screenshotPaths,
+      errors,
+    };
+  }
+}

package/src/scanner/network.ts

@@ -0,0 +1,51 @@
+import type { Page, Request, Response } from "playwright";
+import type { NetworkRequest } from "../types.js";
+import { classifyNetworkRequest } from "../classifiers/network-classifier.js";
+
+export type NetworkPhase = "before-interaction" | "after-accept" | "after-reject";
+
+export function createNetworkInterceptor(page: Page, phase: NetworkPhase) {
+  const captured: NetworkRequest[] = [];
+  const responseMap = new Map<string, { status: number; contentType: string | null }>();
+
+  const onResponse = (response: Response) => {
+    responseMap.set(response.request().url(), {
+      status: response.status(),
+      contentType: response.headers()["content-type"] ?? null,
+    });
+  };
+
+  const onRequest = (request: Request) => {
+    const url = request.url();
+
+    // Skip data URIs and internal chrome requests
+    if (url.startsWith("data:") || url.startsWith("chrome-extension:")) return;
+
+    const classification = classifyNetworkRequest(url, request.resourceType());
+    const meta = responseMap.get(url) ?? null;
+
+    captured.push({
+      url,
+      method: request.method(),
+      resourceType: request.resourceType(),
+      initiator: null,
+      isThirdParty: classification.isThirdParty,
+      trackerCategory: classification.trackerCategory,
+      trackerName: classification.trackerName,
+      capturedAt: phase,
+      responseStatus: meta?.status ?? null,
+      contentType: meta?.contentType ?? null,
+    });
+  };
+
+  page.on("response", onResponse);
+  page.on("request", onRequest);
+
+  return {
+    stop: () => {
+      page.off("response", onResponse);
+      page.off("request", onRequest);
+    },
+    getRequests: () => [...captured],
+  };
+}