@slashgear/gdpr-cookie-scanner 2.0.4 → 3.1.0

package/tests/classifiers/cookie-classifier.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect } from "vitest";
+import { classifyCookie } from "../../src/classifiers/cookie-classifier.js";
+
+describe("classifyCookie", () => {
+  // ── Strictly necessary ───────────────────────────────────────────
+
+  describe("strictly-necessary", () => {
+    it.each(["PHPSESSID", "JSESSIONID", "ASP.NET_SessionId", "__session"])(
+      "classifies %s as strictly-necessary",
+      (name) => {
+        const result = classifyCookie(name, "example.com", "abc123");
+        expect(result).toEqual({ category: "strictly-necessary", requiresConsent: false });
+      },
+    );
+
+    it("classifies session_id as strictly-necessary", () => {
+      expect(classifyCookie("session_id", "example.com", "xyz")).toEqual({
+        category: "strictly-necessary",
+        requiresConsent: false,
+      });
+    });
+
+    it.each(["csrf_token", "xsrf_token", "_token", "authenticity_token"])(
+      "classifies CSRF cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "token")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+
+    it.each(["auth_token", "authenticated", "login_session", "logged_in"])(
+      "classifies auth cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "1")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+
+    it.each(["cart_id", "basket", "checkout_token"])(
+      "classifies cart/checkout cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "abc")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+
+    it.each(["lang", "locale", "language", "country", "currency"])(
+      "classifies preference cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "fr")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+
+    it.each(["cookieconsent_status", "cookie_consent", "cc_cookie"])(
+      "classifies CMP storage cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "granted")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+
+    it.each(["axeptio_cookies", "didomi_token", "CookieConsent", "tarteaucitron"])(
+      "classifies known CMP cookie %s as strictly-necessary",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "{}")).toEqual({
+          category: "strictly-necessary",
+          requiresConsent: false,
+        });
+      },
+    );
+  });
+
+  // ── Analytics ────────────────────────────────────────────────────
+
+  describe("analytics", () => {
+    it.each(["_ga", "_gid"])(
+      "classifies Google Analytics cookie %s as analytics requiring consent",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "GA1.2.xxx")).toEqual({
+          category: "analytics",
+          requiresConsent: true,
+        });
+      },
+    );
+
+    it("classifies _ga_XXXXX (GA4 stream) as analytics", () => {
+      expect(classifyCookie("_ga_K1A2B3C4D5", "example.com", "GS1.1.xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it.each(["_gat", "_gat_UA-123456"])(
+      "classifies GA rate-limiter cookie %s as analytics",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "1")).toEqual({
+          category: "analytics",
+          requiresConsent: true,
+        });
+      },
+    );
+
+    it.each(["_utma", "_utmb", "_utmz"])("classifies legacy UTM cookie %s as analytics", (name) => {
+      expect(classifyCookie(name, "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies __utmz as analytics", () => {
+      expect(classifyCookie("__utmz", "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies Matomo _pk_ cookie as analytics", () => {
+      expect(classifyCookie("_pk_id.1.1fff", "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies Amplitude amp_ cookie as analytics", () => {
+      expect(classifyCookie("amp_abc123", "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies Hotjar _hj cookie as analytics", () => {
+      expect(classifyCookie("_hjSessionUser_123", "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies Microsoft Clarity CLID as analytics", () => {
+      expect(classifyCookie("CLID", "example.com", "xxx")).toEqual({
+        category: "analytics",
+        requiresConsent: true,
+      });
+    });
+  });
+
+  // ── Advertising ──────────────────────────────────────────────────
+
+  describe("advertising", () => {
+    it.each(["_fbp", "_fbc", "fb_id"])(
+      "classifies Meta/Facebook cookie %s as advertising",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "xxx")).toEqual({
+          category: "advertising",
+          requiresConsent: true,
+        });
+      },
+    );
+
+    it.each(["IDE", "NID", "DSID", "ANID", "__gads", "__gpi", "FCNEC"])(
+      "classifies Google Ads cookie %s as advertising",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "xxx")).toEqual({
+          category: "advertising",
+          requiresConsent: true,
+        });
+      },
+    );
+
+    it("classifies MUID (Microsoft) as advertising", () => {
+      expect(classifyCookie("MUID", "example.com", "xxx")).toEqual({
+        category: "advertising",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies li_fat_id (LinkedIn) as advertising", () => {
+      expect(classifyCookie("li_fat_id", "example.com", "xxx")).toEqual({
+        category: "advertising",
+        requiresConsent: true,
+      });
+    });
+
+    it("classifies _ttp (TikTok) as advertising", () => {
+      expect(classifyCookie("_ttp", "example.com", "xxx")).toEqual({
+        category: "advertising",
+        requiresConsent: true,
+      });
+    });
+  });
+
+  // ── Social ───────────────────────────────────────────────────────
+
+  describe("social", () => {
+    it("classifies fbsr_ (Facebook login) as social", () => {
+      expect(classifyCookie("fbsr_123456", "example.com", "xxx")).toEqual({
+        category: "social",
+        requiresConsent: true,
+      });
+    });
+
+    it.each(["YSC", "VISITOR_INFO1_LIVE", "GPS"])(
+      "classifies YouTube cookie %s as social",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "xxx")).toEqual({
+          category: "social",
+          requiresConsent: true,
+        });
+      },
+    );
+  });
+
+  // ── Personalization ──────────────────────────────────────────────
+
+  describe("personalization", () => {
+    it.each(["ab_test", "abt_variant", "abtest_bucket"])(
+      "classifies A/B test cookie %s as personalization",
+      (name) => {
+        expect(classifyCookie(name, "example.com", "variant_b")).toEqual({
+          category: "personalization",
+          requiresConsent: true,
+        });
+      },
+    );
+
+    it("classifies optimizely cookie as personalization", () => {
+      expect(classifyCookie("optimizely_data", "example.com", "xxx")).toEqual({
+        category: "personalization",
+        requiresConsent: true,
+      });
+    });
+  });
+
+  // ── Unknown / heuristics ─────────────────────────────────────────
+
+  describe("unknown", () => {
+    it("classifies unrecognised long-name cookie as unknown without consent", () => {
+      expect(classifyCookie("my_custom_app_cookie", "example.com", "somevalue=abc")).toEqual({
+        category: "unknown",
+        requiresConsent: false,
+      });
+    });
+
+    it("classifies short-name cookie (≤4 chars, no = in value) as unknown requiring consent", () => {
+      // Heuristic: suspicious session-like short cookie
+      expect(classifyCookie("sid", "example.com", "abc123")).toEqual({
+        category: "unknown",
+        requiresConsent: true,
+      });
+    });
+
+    it("does NOT flag short-name cookie as suspicious when value contains =", () => {
+      // Base64-encoded values contain = — should not be flagged
+      expect(classifyCookie("tok", "example.com", "abc=def")).toEqual({
+        category: "unknown",
+        requiresConsent: false,
+      });
+    });
+  });
+});

package/tests/classifiers/network-classifier.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { classifyNetworkRequest } from "../../src/classifiers/network-classifier.js";
+
+describe("classifyNetworkRequest", () => {
+  // ── Known trackers (exact hostname match) ────────────────────────
+
+  describe("tracker database — exact match", () => {
+    it("identifies Google Analytics", () => {
+      const result = classifyNetworkRequest("https://google-analytics.com/collect", "xhr");
+      expect(result.trackerCategory).toBe("analytics");
+      expect(result.trackerName).toBe("Google Analytics");
+      expect(result.requiresConsent).toBe(true);
+      expect(result.isThirdParty).toBe(true);
+    });
+
+    it("identifies Google Tag Manager", () => {
+      const result = classifyNetworkRequest(
+        "https://googletagmanager.com/gtm.js?id=GTM-XXXX",
+        "script",
+      );
+      expect(result.trackerCategory).toBe("analytics");
+      expect(result.trackerName).toBe("Google Tag Manager");
+      expect(result.requiresConsent).toBe(true);
+    });
+
+    it("identifies Meta Pixel (pixel.facebook.com)", () => {
+      const result = classifyNetworkRequest("https://pixel.facebook.com/tr?id=123", "xhr");
+      expect(result.trackerCategory).toBe("advertising");
+      expect(result.trackerName).toBe("Meta Pixel");
+      expect(result.requiresConsent).toBe(true);
+    });
+
+    it("identifies LinkedIn Insight Tag", () => {
+      const result = classifyNetworkRequest(
+        "https://snap.licdn.com/li.lms-analytics/insight.min.js",
+        "script",
+      );
+      expect(result.trackerCategory).toBe("advertising");
+      expect(result.requiresConsent).toBe(true);
+    });
+
+    it("identifies Hotjar", () => {
+      const result = classifyNetworkRequest("https://hotjar.com/api/v2/event", "xhr");
+      expect(result.trackerCategory).toBe("analytics");
+      expect(result.trackerName).toBe("Hotjar");
+    });
+
+    it("identifies Microsoft Clarity", () => {
+      const result = classifyNetworkRequest("https://clarity.ms/collect", "xhr");
+      expect(result.trackerCategory).toBe("analytics");
+      expect(result.requiresConsent).toBe(true);
+    });
+  });
+
+  // ── Subdomain suffix match ────────────────────────────────────────
+
+  describe("tracker database — subdomain match", () => {
+    it("matches subdomain of google-analytics.com", () => {
+      const result = classifyNetworkRequest("https://stats.google-analytics.com/r/collect", "xhr");
+      expect(result.trackerName).toBe("Google Analytics");
+      expect(result.isThirdParty).toBe(true);
+    });
+
+    it("strips www. before matching", () => {
+      const result = classifyNetworkRequest("https://www.google-analytics.com/collect", "xhr");
+      expect(result.trackerCategory).toBe("analytics");
+    });
+  });
+
+  // ── Pixel pattern matching ────────────────────────────────────────
+
+  describe("pixel patterns", () => {
+    it("identifies tracking pixels by URL pattern", () => {
+      const result = classifyNetworkRequest(
+        "https://track.example.com/pixel.gif?uid=123&ev=pageview",
+        "image",
+      );
+      // Either caught by pixel pattern or image heuristic
+      expect(result.trackerCategory).toBe("pixel");
+      expect(result.requiresConsent).toBe(true);
+    });
+  });
+
+  // ── Image heuristic ───────────────────────────────────────────────
+
+  describe("image resource heuristic", () => {
+    it("flags 1×1 gif with tracking params as pixel", () => {
+      const result = classifyNetworkRequest(
+        "https://metrics.unknown-vendor.com/track.gif?uid=abc&ts=1234",
+        "image",
+      );
+      expect(result.trackerCategory).toBe("pixel");
+      expect(result.requiresConsent).toBe(true);
+    });
+
+    it("does NOT flag regular image without tracking params", () => {
+      const result = classifyNetworkRequest("https://cdn.unknown-vendor.com/hero.png", "image");
+      expect(result.trackerCategory).toBeNull();
+      expect(result.requiresConsent).toBe(false);
+    });
+  });
+
+  // ── CDN — consent not required ────────────────────────────────────
+
+  describe("CDN entries", () => {
+    it("marks CDN requests as not requiring consent", () => {
+      // fbcdn.net is category 'social' not cdn, but let's test the cdn logic
+      // by checking that consentRequired=false entries in TRACKER_DB are respected
+      // Google fonts is not in the DB, so test a generic unknown
+      const result = classifyNetworkRequest("https://totally-unknown-cdn.io/lib.js", "script");
+      expect(result.requiresConsent).toBe(false);
+      expect(result.trackerCategory).toBeNull();
+    });
+  });
+
+  // ── Unknown / safe requests ───────────────────────────────────────
+
+  describe("unknown requests", () => {
+    it("returns null classification for an unknown domain", () => {
+      const result = classifyNetworkRequest("https://api.my-own-backend.com/data", "xhr");
+      expect(result.trackerCategory).toBeNull();
+      expect(result.trackerName).toBeNull();
+      expect(result.requiresConsent).toBe(false);
+      expect(result.isThirdParty).toBe(false);
+    });
+
+    it("returns safe fallback for an invalid URL", () => {
+      const result = classifyNetworkRequest("not-a-url", "xhr");
+      expect(result.trackerCategory).toBeNull();
+      expect(result.requiresConsent).toBe(false);
+      expect(result.isThirdParty).toBe(false);
+    });
+
+    it("returns safe fallback for an empty string", () => {
+      const result = classifyNetworkRequest("", "xhr");
+      expect(result.trackerCategory).toBeNull();
+      expect(result.requiresConsent).toBe(false);
+    });
+  });
+});

package/tests/e2e/scanner.test.ts

@@ -117,19 +117,16 @@ describe("Scanner E2E", { timeout: E2E_TIMEOUT }, () => {
       expect(result.privacyPolicyUrl).toBeTruthy();
     });
 
-    it("assigns grade F when no modal is detected", async () => {
+    it("assigns grade A — no consent mechanism needed for a tracking-free site", async () => {
       const scanner = new Scanner(makeOptions("no-modal-site.html"));
       const result = await scanner.run();
-      expect(result.compliance.grade).toBe("F");
+      expect(result.compliance.grade).toBe("A");
     });
 
-    it("raises a critical no-reject-button issue", async () => {
+    it("raises no compliance issues for a tracking-free site without a modal", async () => {
       const scanner = new Scanner(makeOptions("no-modal-site.html"));
       const result = await scanner.run();
-      const issue = result.compliance.issues.find(
-        (i) => i.type === "no-reject-button" && i.severity === "critical",
-      );
-      expect(issue).toBeDefined();
+      expect(result.compliance.issues).toHaveLength(0);
     });
   });
 });

package/tests/unit/compliance.test.ts

@@ -74,6 +74,7 @@ function makeRequest(
   url: string,
   trackerCategory: NetworkRequest["trackerCategory"],
   capturedAt: NetworkRequest["capturedAt"],
+  requiresConsent?: boolean,
 ): NetworkRequest {
   return {
     url,
@@ -83,6 +84,7 @@ function makeRequest(
     isThirdParty: trackerCategory !== null,
     trackerCategory,
     trackerName: trackerCategory ? "Tracker" : null,
+    requiresConsent: requiresConsent ?? (trackerCategory !== null && trackerCategory !== "cdn"),
     capturedAt,
     responseStatus: 200,
     contentType: null,
@@ -103,25 +105,52 @@ const emptyInputBase = {
 
 describe("analyzeCompliance", () => {
   describe("no consent modal detected", () => {
-    it("scores 0 on consentValidity, easyRefusal, and transparency", () => {
-      const result = analyzeCompliance({
+    describe("when non-essential cookies are present (consent required)", () => {
+      const inputWithCookies = {
         ...emptyInputBase,
+        cookiesAfterAccept: [makeCookie("_ga", "analytics", true, "after-accept")],
         modal: makeModal({ detected: false }),
+      };
+
+      it("scores 0 on consentValidity, easyRefusal, and transparency", () => {
+        const result = analyzeCompliance(inputWithCookies);
+
+        expect(result.breakdown.consentValidity).toBe(0);
+        expect(result.breakdown.easyRefusal).toBe(0);
+        expect(result.breakdown.transparency).toBe(0);
       });
 
-      expect(result.breakdown.consentValidity).toBe(0);
-      expect(result.breakdown.easyRefusal).toBe(0);
-      expect(result.breakdown.transparency).toBe(0);
+      it("issues a critical no-reject-button issue", () => {
+        const result = analyzeCompliance(inputWithCookies);
+        const issue = result.issues.find((i) => i.type === "no-reject-button");
+        expect(issue).toBeDefined();
+        expect(issue?.severity).toBe("critical");
+      });
     });
 
-    it("issues a critical no-reject-button issue", () => {
-      const result = analyzeCompliance({
-        ...emptyInputBase,
-        modal: makeModal({ detected: false }),
+    describe("when no non-essential cookies or trackers are present (consent not required)", () => {
+      it("scores full marks — no consent mechanism needed", () => {
+        const result = analyzeCompliance({
+          ...emptyInputBase,
+          modal: makeModal({ detected: false }),
+        });
+
+        expect(result.breakdown.consentValidity).toBe(25);
+        expect(result.breakdown.easyRefusal).toBe(25);
+        expect(result.breakdown.transparency).toBe(25);
+        expect(result.breakdown.cookieBehavior).toBe(25);
+        expect(result.total).toBe(100);
+        expect(result.grade).toBe("A");
+      });
+
+      it("raises no compliance issues", () => {
+        const result = analyzeCompliance({
+          ...emptyInputBase,
+          modal: makeModal({ detected: false }),
+        });
+
+        expect(result.issues).toHaveLength(0);
       });
-      const issue = result.issues.find((i) => i.type === "no-reject-button");
-      expect(issue).toBeDefined();
-      expect(issue?.severity).toBe("critical");
     });
   });
 
@@ -292,12 +321,14 @@ describe("analyzeCompliance", () => {
   });
 
   describe("missing privacy policy link on page", () => {
-    it("deducts 3 from transparency and raises a missing-info warning", () => {
+    it("deducts 3 from transparency and raises a missing-info warning when consent is required", () => {
       // hasGranularControls: true so only -3 deduction (no -10 for granular)
+      // A non-essential cookie is present so consentRequired = true → deduction applies
       const result = analyzeCompliance({
         ...emptyInputBase,
         privacyPolicyUrl: null,
         modal: makeModal({ hasGranularControls: true }),
+        cookiesAfterAccept: [makeCookie("_ga", "analytics", true, "after-accept")],
       });
 
       // 25 - 3 (no page privacy link) = 22
@@ -307,6 +338,21 @@ describe("analyzeCompliance", () => {
       );
       expect(issue).toBeDefined();
     });
+
+    it("does not deduct when no consent is required (tracking-free site)", () => {
+      const result = analyzeCompliance({
+        ...emptyInputBase,
+        privacyPolicyUrl: null,
+        modal: makeModal({ hasGranularControls: true }),
+      });
+
+      // No non-essential cookies/trackers → consentRequired = false → no deduction
+      expect(result.breakdown.transparency).toBe(25);
+      const issue = result.issues.find(
+        (i) => i.type === "missing-info" && i.description.includes("page"),
+      );
+      expect(issue).toBeUndefined();
+    });
   });
 
   describe("non-essential cookies before consent", () => {
@@ -457,4 +503,44 @@ describe("analyzeCompliance", () => {
       expect(result.grade).toBe("F");
     });
   });
+
+  describe("consent-exempt tracker (Plausible-like)", () => {
+    const plausibleRequest = makeRequest(
+      "https://plausible.io/api/event",
+      "analytics",
+      "before-interaction",
+      false, // requiresConsent: false — CNIL ePrivacy exemption
+    );
+
+    it("does not deduct from cookieBehavior when a pre-interaction tracker is consent-exempt", () => {
+      const result = analyzeCompliance({
+        ...emptyInputBase,
+        modal: makeModal({ hasGranularControls: true }),
+        networkBeforeInteraction: [plausibleRequest],
+      });
+
+      expect(result.breakdown.cookieBehavior).toBe(25);
+      const autoConsentIssue = result.issues.find((i) => i.type === "auto-consent");
+      expect(autoConsentIssue).toBeUndefined();
+    });
+
+    it("consentRequired is false when only a consent-exempt tracker is present", () => {
+      // No modal, only Plausible → should score full marks (no consent needed)
+      const result = analyzeCompliance({
+        ...emptyInputBase,
+        modal: makeModal({ detected: false }),
+        networkBeforeInteraction: [plausibleRequest],
+        networkAfterAccept: [
+          makeRequest("https://plausible.io/api/event", "analytics", "after-accept", false),
+        ],
+      });
+
+      expect(result.breakdown.consentValidity).toBe(25);
+      expect(result.breakdown.easyRefusal).toBe(25);
+      expect(result.breakdown.transparency).toBe(25);
+      expect(result.breakdown.cookieBehavior).toBe(25);
+      expect(result.total).toBe(100);
+      expect(result.grade).toBe("A");
+    });
+  });
 });

package/tests/unit/network-classifier.test.ts

@@ -61,6 +61,7 @@ describe("classifyNetworkRequest", () => {
       expect(result.isThirdParty).toBe(false);
       expect(result.trackerCategory).toBeNull();
       expect(result.trackerName).toBeNull();
+      expect(result.requiresConsent).toBe(false);
     });
 
     it("does not flag CDN requests for known CDN domains", () => {
@@ -78,6 +79,7 @@ describe("classifyNetworkRequest", () => {
       expect(result.isThirdParty).toBe(false);
       expect(result.trackerCategory).toBeNull();
       expect(result.trackerName).toBeNull();
+      expect(result.requiresConsent).toBe(false);
     });
   });
 
@@ -88,4 +90,29 @@ describe("classifyNetworkRequest", () => {
       expect(result.trackerCategory).toBe("analytics");
     });
   });
+
+  describe("requiresConsent field", () => {
+    it("Plausible Analytics (/api/event) is classified as analytics but does not require consent", () => {
+      const result = classifyNetworkRequest("https://plausible.io/api/event", "xhr");
+      expect(result.isThirdParty).toBe(true);
+      expect(result.trackerCategory).toBe("analytics");
+      expect(result.trackerName).toBe("Plausible Analytics");
+      expect(result.requiresConsent).toBe(false);
+    });
+
+    it("Google Analytics requires consent", () => {
+      const result = classifyNetworkRequest(
+        "https://www.google-analytics.com/j/collect?v=1&t=event",
+        "xhr",
+      );
+      expect(result.requiresConsent).toBe(true);
+    });
+
+    it("CDN domain (akamaized.net) does not require consent", () => {
+      const result = classifyNetworkRequest("https://assets.akamaized.net/bundle.js", "script");
+      expect(result.isThirdParty).toBe(true);
+      expect(result.trackerCategory).toBe("cdn");
+      expect(result.requiresConsent).toBe(false);
+    });
+  });
 });