@slashgear/gdpr-cookie-scanner 3.6.0 → 3.8.0

package/src/report/html.ts

@@ -1,6 +1,7 @@
 import { basename } from "path";
 import type { ScanResult, ScannedCookie, DarkPatternIssue, ConsentButton } from "../types.js";
 import { lookupCookie } from "../classifiers/cookie-lookup.js";
+import { IAB_PURPOSES, IAB_SPECIAL_FEATURES } from "../analyzers/tcf-decoder.js";
 
 const GRADE_COLOR: Record<string, string> = {
   A: "#16a34a",
@@ -418,6 +419,8 @@ export function generateHtmlReport(result: ScanResult): string {
 
   ${buildNetworkSection(result)}
 
+  ${buildTcfSection(result)}
+
   ${buildRecommendationsSection(result)}
 
   ${buildChecklistSection(result)}
@@ -754,6 +757,149 @@ function buildNetworkSection(result: ScanResult): string {
 </div>`;
 }
 
+// ── IAB TCF ───────────────────────────────────────────────────────────────────
+
+function buildTcfSection(result: ScanResult): string {
+  const { tcf } = result;
+
+  const infoNote = `<p style="margin:0 0 16px;font-size:12px;color:var(--text-muted);font-style:italic">Informational only — does not affect the compliance score.</p>`;
+
+  if (!tcf.detected) {
+    return `<div class="section">
+  <div class="section-header">
+    <h2>IAB TCF</h2>
+    <span class="badge badge-muted">Not detected</span>
+  </div>
+  <div class="section-body">
+    ${infoNote}
+    <p style="color:var(--text-muted);font-size:13px;margin:0">No IAB Transparency &amp; Consent Framework implementation found on this page.</p>
+  </div>
+</div>`;
+  }
+
+  const versionBadge = tcf.version
+    ? `<span class="badge badge-ok">TCF v${tcf.version}</span>`
+    : `<span class="badge badge-ok">Detected</span>`;
+
+  const metaRows = [
+    [
+      "CMP API (<code>__tcfapi</code>)",
+      tcf.apiPresent
+        ? `<span class="status-ok">✓ Present</span>`
+        : `<span class="status-warn">✗ Not present</span>`,
+    ],
+    [
+      "Locator frame (<code>__tcfapiLocator</code>)",
+      tcf.locatorFramePresent
+        ? `<span class="status-ok">✓ Present</span>`
+        : `<span class="status-warn">✗ Not present</span>`,
+    ],
+    [
+      "Consent string cookie",
+      tcf.cookieName
+        ? `<code>${esc(tcf.cookieName)}</code>`
+        : `<span style="color:var(--text-muted)">—</span>`,
+    ],
+    [
+      "CMP ID",
+      tcf.cmpId !== null ? String(tcf.cmpId) : `<span style="color:var(--text-muted)">—</span>`,
+    ],
+  ]
+    .map(
+      ([label, value]) =>
+        `<tr><td style="font-weight:500;width:40%">${label}</td><td>${value}</td></tr>`,
+    )
+    .join("\n");
+
+  const cs = tcf.consentString;
+
+  let consentStringHtml = `<p style="color:var(--text-muted);font-size:13px;margin-top:16px">No consent string could be decoded.</p>`;
+
+  if (cs) {
+    const decodedRows = [
+      ["Version", `TCF v${cs.version}`],
+      ["Created", cs.created.toISOString().split("T")[0]],
+      ["Last updated", cs.lastUpdated.toISOString().split("T")[0]],
+      ["CMP ID", String(cs.cmpId)],
+      ["CMP version", String(cs.cmpVersion)],
+      ["Consent language", cs.consentLanguage],
+      ["Vendor list version", String(cs.vendorListVersion)],
+      ...(cs.tcfPolicyVersion !== undefined
+        ? [["TCF policy version", String(cs.tcfPolicyVersion)]]
+        : []),
+      ...(cs.isServiceSpecific !== undefined
+        ? [["Service specific", cs.isServiceSpecific ? "Yes" : "No"]]
+        : []),
+      ...(cs.publisherCC ? [["Publisher country", cs.publisherCC]] : []),
+    ]
+      .map(
+        ([label, value]) =>
+          `<tr><td style="font-weight:500;width:40%">${esc(label)}</td><td>${esc(value)}</td></tr>`,
+      )
+      .join("\n");
+
+    const purposesConsentHtml =
+      cs.purposesConsent.length > 0
+        ? `<div style="margin-top:20px">
+    <div style="font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.04em;color:var(--text-muted);margin-bottom:8px">Purposes with consent</div>
+    <table class="data-table">
+      <thead><tr><th>ID</th><th>Purpose</th></tr></thead>
+      <tbody>${cs.purposesConsent.map((id) => `<tr><td>${id}</td><td>${esc(IAB_PURPOSES[id] ?? "Unknown")}</td></tr>`).join("")}</tbody>
+    </table>
+  </div>`
+        : `<p style="margin-top:16px;font-size:13px;color:var(--text-muted)">No purposes with explicit consent.</p>`;
+
+    const purposesLiHtml =
+      cs.purposesLegitimateInterest.length > 0
+        ? `<div style="margin-top:20px">
+    <div style="font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.04em;color:var(--text-muted);margin-bottom:8px">Purposes with legitimate interest</div>
+    <table class="data-table">
+      <thead><tr><th>ID</th><th>Purpose</th></tr></thead>
+      <tbody>${cs.purposesLegitimateInterest.map((id) => `<tr><td>${id}</td><td>${esc(IAB_PURPOSES[id] ?? "Unknown")}</td></tr>`).join("")}</tbody>
+    </table>
+  </div>`
+        : "";
+
+    const specialFeaturesHtml =
+      cs.specialFeatureOptins.length > 0
+        ? `<div style="margin-top:20px">
+    <div style="font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.04em;color:var(--text-muted);margin-bottom:8px">Special features opted in</div>
+    <table class="data-table">
+      <thead><tr><th>ID</th><th>Feature</th></tr></thead>
+      <tbody>${cs.specialFeatureOptins.map((id) => `<tr><td>${id}</td><td>${esc(IAB_SPECIAL_FEATURES[id] ?? "Unknown")}</td></tr>`).join("")}</tbody>
+    </table>
+  </div>`
+        : "";
+
+    consentStringHtml = `<div style="margin-top:20px">
+    <div style="font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.04em;color:var(--text-muted);margin-bottom:8px">Decoded consent string</div>
+    <table class="data-table">
+      <thead><tr><th>Field</th><th>Value</th></tr></thead>
+      <tbody>${decodedRows}</tbody>
+    </table>
+  </div>
+  ${purposesConsentHtml}
+  ${purposesLiHtml}
+  ${specialFeaturesHtml}`;
+  }
+
+  return `<div class="section">
+  <div class="section-header">
+    <h2>IAB TCF</h2>
+    ${versionBadge}
+    ${tcf.cmpId !== null ? `<span class="badge badge-muted">CMP ${tcf.cmpId}</span>` : ""}
+  </div>
+  <div class="section-body">
+    ${infoNote}
+    <table class="data-table">
+      <thead><tr><th>Property</th><th>Value</th></tr></thead>
+      <tbody>${metaRows}</tbody>
+    </table>
+    ${consentStringHtml}
+  </div>
+</div>`;
+}
+
 // ── Recommendations ───────────────────────────────────────────────────────────
 
 function buildRecommendationsSection(result: ScanResult): string {

package/src/scanner/consent-modal.ts

@@ -467,8 +467,10 @@ function classifyButtonType(
   reject: RegExp[],
   preferences: RegExp[],
 ): ConsentButtonType {
-  if (accept.some((p) => p.test(text))) return "accept";
+  // Reject is tested first: phrases like "continuer sans accepter" contain "accepter"
+  // which would otherwise match the accept pattern before reaching the reject pattern.
   if (reject.some((p) => p.test(text))) return "reject";
+  if (accept.some((p) => p.test(text))) return "accept";
   if (preferences.some((p) => p.test(text))) return "preferences";
   // Close buttons: word-form match OR standalone symbol (× ✕ ✗ ✖ ✘)
   if (

package/src/scanner/index.ts

@@ -6,6 +6,7 @@ import { captureCookies } from "./cookies.js";
 import { createNetworkInterceptor } from "./network.js";
 import { detectConsentModal, findPrivacyPolicyUrl } from "./consent-modal.js";
 import { analyzeCompliance } from "../analyzers/compliance.js";
+import { detectTcf } from "./tcf.js";
 
 type PhaseCallback = (message: string) => void;
 
@@ -52,6 +53,9 @@ export class Scanner {
     const networkBeforeInteraction = interceptor1.getRequests();
     interceptor1.stop();
 
+    // Detect IAB TCF implementation (informational, does not affect score)
+    const tcfInfo = await detectTcf(session1.page, cookiesBeforeInteraction);
+
     // Look for a privacy policy link anywhere on the page (typically footer/nav)
     const privacyPolicyUrl = await findPrivacyPolicyUrl(session1.page);
 
@@ -202,6 +206,7 @@ export class Scanner {
       compliance,
       screenshotPaths,
       errors,
+      tcf: tcfInfo,
     };
   }
 }

package/src/scanner/tcf.ts

@@ -0,0 +1,80 @@
+import type { Page } from "playwright";
+import type { ScannedCookie, TcfInfo } from "../types.js";
+import { decodeTcfConsentString } from "../analyzers/tcf-decoder.js";
+
+/**
+ * Detect the IAB TCF (Transparency and Consent Framework) implementation on the page.
+ * Called at the end of Phase 1, after the initial page load and timeout.
+ * Purely informational — results do not affect the compliance score.
+ */
+export async function detectTcf(page: Page, cookies: ScannedCookie[]): Promise<TcfInfo> {
+  // Step 1: Check for TCF v2 (__tcfapi) and v1 (__cmp) API
+  let apiPresent = false;
+  try {
+    apiPresent = await page.evaluate(() => {
+      const w = window as unknown as Record<string, unknown>;
+      return typeof w["__tcfapi"] === "function" || typeof w["__cmp"] === "function";
+    });
+  } catch {
+    // Page context may have been destroyed
+  }
+
+  // Step 2: Check for __tcfapiLocator iframe
+  const locatorFramePresent = page.frames().some((f) => f.name() === "__tcfapiLocator");
+
+  // Step 3: Look for euconsent cookies already captured
+  const euconsentV2 = cookies.find((c) => c.name === "euconsent-v2");
+  const euconsentV1 = cookies.find((c) => c.name === "euconsent");
+  const consentCookie = euconsentV2 ?? euconsentV1;
+  const cookieName = consentCookie?.name ?? null;
+
+  // Step 4: Try to obtain the consent string via __tcfapi if the API is present
+  let tcString: string | null = consentCookie?.value ?? null;
+
+  if (apiPresent && !tcString) {
+    try {
+      const result = await page.evaluate(() => {
+        return new Promise<string | null>((resolve) => {
+          const timeout = setTimeout(() => resolve(null), 3000);
+          try {
+            const w = window as unknown as Record<string, unknown>;
+            const tcfApi = w["__tcfapi"] as (
+              command: string,
+              version: number,
+              callback: (tcData: Record<string, unknown>, success: boolean) => void,
+            ) => void;
+            tcfApi("getTCData", 2, (tcData, success) => {
+              clearTimeout(timeout);
+              if (success && typeof tcData["tcString"] === "string") {
+                resolve(tcData["tcString"] as string);
+              } else {
+                resolve(null);
+              }
+            });
+          } catch {
+            clearTimeout(timeout);
+            resolve(null);
+          }
+        });
+      });
+      if (result) tcString = result;
+    } catch {
+      // page.evaluate() may throw if the page navigated
+    }
+  }
+
+  // Step 5: Decode the consent string
+  const consentString = tcString ? decodeTcfConsentString(tcString) : null;
+
+  const detected = apiPresent || locatorFramePresent || cookieName !== null;
+
+  return {
+    detected,
+    version: consentString?.version ?? (euconsentV2 ? 2 : euconsentV1 ? 1 : null),
+    apiPresent,
+    locatorFramePresent,
+    cookieName,
+    cmpId: consentString?.cmpId ?? null,
+    consentString,
+  };
+}

package/src/types.ts

@@ -130,6 +130,34 @@ export interface ScanOptions {
   strict?: boolean;
 }
 
+export interface TcfConsentString {
+  raw: string;
+  version: 1 | 2;
+  created: Date;
+  lastUpdated: Date;
+  cmpId: number;
+  cmpVersion: number;
+  consentLanguage: string;
+  vendorListVersion: number;
+  // TCF v2 only:
+  tcfPolicyVersion?: number;
+  isServiceSpecific?: boolean;
+  specialFeatureOptins: number[]; // IDs of opted-in special features
+  purposesConsent: number[]; // IDs of purposes with consent
+  purposesLegitimateInterest: number[]; // IDs of purposes with legitimate interest
+  publisherCC?: string;
+}
+
+export interface TcfInfo {
+  detected: boolean;
+  version: 1 | 2 | null;
+  apiPresent: boolean; // window.__tcfapi found
+  locatorFramePresent: boolean; // iframe __tcfapiLocator found
+  cookieName: string | null; // "euconsent-v2" or "euconsent"
+  cmpId: number | null;
+  consentString: TcfConsentString | null;
+}
+
 export interface ScanResult {
   url: string;
   scanDate: string;
@@ -145,4 +173,5 @@ export interface ScanResult {
   compliance: ComplianceScore;
   screenshotPaths: string[];
   errors: string[];
+  tcf: TcfInfo;
 }

package/tests/analyzers/colour.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from "vitest";
+import { rgbToHsl, classifyHue, detectColourNudging } from "../../src/analyzers/colour.js";
+
+// ── rgbToHsl ──────────────────────────────────────────────────────────────────
+
+describe("rgbToHsl", () => {
+  it("converts pure red", () => {
+    const [h, s, l] = rgbToHsl(255, 0, 0);
+    expect(h).toBe(0);
+    expect(s).toBe(100);
+    expect(l).toBe(50);
+  });
+
+  it("converts pure green", () => {
+    const [h, s, l] = rgbToHsl(0, 255, 0);
+    expect(h).toBe(120);
+    expect(s).toBe(100);
+    expect(l).toBe(50);
+  });
+
+  it("converts pure blue", () => {
+    const [h, s, l] = rgbToHsl(0, 0, 255);
+    expect(h).toBe(240);
+    expect(s).toBe(100);
+    expect(l).toBe(50);
+  });
+
+  it("converts white", () => {
+    const [_h, s, l] = rgbToHsl(255, 255, 255);
+    expect(s).toBe(0);
+    expect(l).toBe(100);
+  });
+
+  it("converts black", () => {
+    const [_h, s, l] = rgbToHsl(0, 0, 0);
+    expect(s).toBe(0);
+    expect(l).toBe(0);
+  });
+
+  it("converts medium grey", () => {
+    const [, s, l] = rgbToHsl(128, 128, 128);
+    expect(s).toBe(0);
+    expect(l).toBeCloseTo(50, 0);
+  });
+});
+
+// ── classifyHue ───────────────────────────────────────────────────────────────
+
+describe("classifyHue", () => {
+  describe("green", () => {
+    it("classifies a vivid green accept button colour", () => {
+      // rgb(34, 197, 94) — typical Tailwind green-500
+      expect(classifyHue(34, 197, 94)).toBe("green");
+    });
+
+    it("classifies a darker CMP green", () => {
+      // rgb(22, 163, 74) — green-600
+      expect(classifyHue(22, 163, 74)).toBe("green");
+    });
+
+    it("classifies a yellow-green as green", () => {
+      // h ≈ 100 — still in the green range
+      expect(classifyHue(100, 200, 50)).toBe("green");
+    });
+  });
+
+  describe("grey", () => {
+    it("classifies a mid-grey reject button", () => {
+      expect(classifyHue(160, 160, 160)).toBe("grey");
+    });
+
+    it("classifies a light grey (s very low)", () => {
+      expect(classifyHue(220, 222, 220)).toBe("grey");
+    });
+
+    it("classifies a dark grey", () => {
+      // l ≈ 25%, s ≈ 0
+      expect(classifyHue(60, 60, 60)).toBe("grey");
+    });
+  });
+
+  describe("red", () => {
+    it("classifies pure red", () => {
+      expect(classifyHue(255, 0, 0)).toBe("red");
+    });
+
+    it("classifies a muted red / crimson", () => {
+      // rgb(185, 28, 28) — red-700
+      expect(classifyHue(185, 28, 28)).toBe("red");
+    });
+
+    it("classifies a high-hue pink/magenta near 340° as red", () => {
+      // h ≈ 348
+      expect(classifyHue(220, 38, 100)).toBe("red");
+    });
+  });
+
+  describe("blue", () => {
+    it("classifies a standard blue CTA button", () => {
+      // rgb(59, 130, 246) — blue-500
+      expect(classifyHue(59, 130, 246)).toBe("blue");
+    });
+
+    it("classifies a darker navy blue", () => {
+      expect(classifyHue(30, 64, 175)).toBe("blue");
+    });
+  });
+
+  describe("neutral", () => {
+    it("returns neutral for white (l > 93)", () => {
+      expect(classifyHue(255, 255, 255)).toBe("neutral");
+    });
+
+    it("returns neutral for near-black (l < 10)", () => {
+      expect(classifyHue(10, 10, 10)).toBe("neutral");
+    });
+
+    it("returns neutral for an orange hue (not a defined category)", () => {
+      // h ≈ 30, s ≈ 90% — orange
+      expect(classifyHue(255, 140, 0)).toBe("neutral");
+    });
+  });
+});
+
+// ── detectColourNudging ───────────────────────────────────────────────────────
+
+describe("detectColourNudging", () => {
+  const GREEN = "rgb(34, 197, 94)";
+  const GREY = "rgb(160, 160, 160)";
+  const RED = "rgb(185, 28, 28)";
+  const BLUE = "rgb(59, 130, 246)";
+
+  describe("nudging detected", () => {
+    it("flags green accept + grey reject", () => {
+      const { isNudging, acceptHue, rejectHue } = detectColourNudging(GREEN, GREY);
+      expect(isNudging).toBe(true);
+      expect(acceptHue).toBe("green");
+      expect(rejectHue).toBe("grey");
+    });
+
+    it("flags green accept + red reject", () => {
+      const { isNudging, acceptHue, rejectHue } = detectColourNudging(GREEN, RED);
+      expect(isNudging).toBe(true);
+      expect(acceptHue).toBe("green");
+      expect(rejectHue).toBe("red");
+    });
+  });
+
+  describe("no nudging", () => {
+    it("does not flag blue accept + grey reject (blue ≠ green)", () => {
+      const { isNudging } = detectColourNudging(BLUE, GREY);
+      expect(isNudging).toBe(false);
+    });
+
+    it("does not flag green accept + green reject (same hue, no asymmetry)", () => {
+      const { isNudging } = detectColourNudging(GREEN, GREEN);
+      expect(isNudging).toBe(false);
+    });
+
+    it("does not flag green accept + blue reject", () => {
+      const { isNudging } = detectColourNudging(GREEN, BLUE);
+      expect(isNudging).toBe(false);
+    });
+
+    it("returns isNudging false when acceptBg is null", () => {
+      const { isNudging, acceptHue } = detectColourNudging(null, GREY);
+      expect(isNudging).toBe(false);
+      expect(acceptHue).toBeNull();
+    });
+
+    it("returns isNudging false when rejectBg is null", () => {
+      const { isNudging, rejectHue } = detectColourNudging(GREEN, null);
+      expect(isNudging).toBe(false);
+      expect(rejectHue).toBeNull();
+    });
+
+    it("returns isNudging false when both are null", () => {
+      const { isNudging } = detectColourNudging(null, null);
+      expect(isNudging).toBe(false);
+    });
+
+    it("does not flag unparseable CSS strings", () => {
+      const { isNudging } = detectColourNudging("transparent", "inherit");
+      expect(isNudging).toBe(false);
+    });
+  });
+});

package/tests/analyzers/compliance.test.ts

@@ -287,6 +287,108 @@ describe("easyRefusal dimension", () => {
     });
     expect(result.issues.some((i) => i.type === "nudging")).toBe(true);
   });
+
+  it("deducts 5 for indirect reject label ('continuer sans accepter' dark pattern)", () => {
+    const modal = makeModal({
+      buttons: [
+        makeButton("accept", "Tout accepter", 1),
+        makeButton("reject", "Continuer sans accepter", 1),
+      ],
+    });
+    const result = analyzeCompliance({
+      modal,
+      privacyPolicyUrl: "https://example.com/privacy",
+      cookiesBeforeInteraction: [],
+      cookiesAfterAccept: [makeCookie("_ga", true, "after-accept")],
+      cookiesAfterReject: [],
+      networkBeforeInteraction: [],
+      networkAfterAccept: [],
+      networkAfterReject: [],
+    });
+    expect(result.breakdown.easyRefusal).toBeLessThanOrEqual(20);
+    expect(
+      result.issues.some((i) => i.type === "misleading-wording" && i.severity === "warning"),
+    ).toBe(true);
+  });
+
+  it("does NOT deduct for an explicit reject label", () => {
+    const modal = makeModal({
+      buttons: [makeButton("accept", "Tout accepter", 1), makeButton("reject", "Tout refuser", 1)],
+    });
+    const result = analyzeCompliance({
+      modal,
+      privacyPolicyUrl: "https://example.com/privacy",
+      cookiesBeforeInteraction: [],
+      cookiesAfterAccept: [makeCookie("_ga", true, "after-accept")],
+      cookiesAfterReject: [],
+      networkBeforeInteraction: [],
+      networkAfterAccept: [],
+      networkAfterReject: [],
+    });
+    expect(result.breakdown.easyRefusal).toBe(25);
+  });
+
+  it("deducts 5 for colour nudging (green accept + grey reject)", () => {
+    const modal = makeModal({
+      buttons: [
+        makeButton("accept", "Accept all", 1, { backgroundColor: "rgb(34, 197, 94)" }),
+        makeButton("reject", "Reject all", 1, { backgroundColor: "rgb(160, 160, 160)" }),
+      ],
+    });
+    const result = analyzeCompliance({
+      modal,
+      privacyPolicyUrl: "https://example.com/privacy",
+      cookiesBeforeInteraction: [],
+      cookiesAfterAccept: [makeCookie("_ga", true, "after-accept")],
+      cookiesAfterReject: [],
+      networkBeforeInteraction: [],
+      networkAfterAccept: [],
+      networkAfterReject: [],
+    });
+    expect(result.breakdown.easyRefusal).toBeLessThanOrEqual(20);
+    expect(result.issues.some((i) => i.type === "nudging" && i.severity === "warning")).toBe(true);
+  });
+
+  it("deducts 5 for colour nudging (green accept + red reject)", () => {
+    const modal = makeModal({
+      buttons: [
+        makeButton("accept", "Accept all", 1, { backgroundColor: "rgb(34, 197, 94)" }),
+        makeButton("reject", "Reject all", 1, { backgroundColor: "rgb(185, 28, 28)" }),
+      ],
+    });
+    const result = analyzeCompliance({
+      modal,
+      privacyPolicyUrl: "https://example.com/privacy",
+      cookiesBeforeInteraction: [],
+      cookiesAfterAccept: [makeCookie("_ga", true, "after-accept")],
+      cookiesAfterReject: [],
+      networkBeforeInteraction: [],
+      networkAfterAccept: [],
+      networkAfterReject: [],
+    });
+    expect(result.breakdown.easyRefusal).toBeLessThanOrEqual(20);
+    expect(result.issues.some((i) => i.type === "nudging")).toBe(true);
+  });
+
+  it("does NOT flag colour nudging when accept is blue (not green)", () => {
+    const modal = makeModal({
+      buttons: [
+        makeButton("accept", "Accept all", 1, { backgroundColor: "rgb(59, 130, 246)" }),
+        makeButton("reject", "Reject all", 1, { backgroundColor: "rgb(160, 160, 160)" }),
+      ],
+    });
+    const result = analyzeCompliance({
+      modal,
+      privacyPolicyUrl: "https://example.com/privacy",
+      cookiesBeforeInteraction: [],
+      cookiesAfterAccept: [makeCookie("_ga", true, "after-accept")],
+      cookiesAfterReject: [],
+      networkBeforeInteraction: [],
+      networkAfterAccept: [],
+      networkAfterReject: [],
+    });
+    expect(result.breakdown.easyRefusal).toBe(25);
+  });
 });
 
 // ── C. Transparency ───────────────────────────────────────────────────────────