@analitikisler/ai-tag-debugger 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.6.3 (2026-10-12)
+
+- The audited site's own email address in a `mailto:` link or a link field (`link_url`, `link_text`, `gtm.elementUrl`, `gtm.elementText`), such as the contact link in a GTM `gtm.linkClick` push, is no longer reported as unhashed user data or redacted. An own-domain address anywhere else, and every named user data field (`email`, `user_data`, `em`, …), is still redacted and reported.
+
 ## 0.6.2 (2026-10-12)
 
 Fixes from Bahadır's audit of analitikisler.com.

package/README.md

@@ -316,7 +316,7 @@ A hosted server, so you don't need a tunnel, is part of the [Analitik İşler](h
 - The browser stays on the audited site and its subdomains, plus any `allowed_hosts`. It opens only `http` and `https` pages.
 - The model is told that page content is data, never instructions. A prompt rule can't guarantee a model is never misled, so the navigation limits above contain what a misled model can do.
 - The browser runs without your API keys and other secrets in its environment.
-- **User data sent for ad matching is redacted** before it is stored in `capture.json` or shown in the report: emails, phone numbers, names, addresses and user ids in GA4 and Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user`, and the `user_data` the site pushes to the dataLayer for enhanced conversions. Any value that looks like an email address is redacted whatever its field is called. Each value becomes a marker such as `[redacted: 64 chars, looks hashed]`, and a value that wasn't hashed is reported as a personal data risk. `--keep-bodies` (`"keep_bodies": true`) stores requests as sent, for debugging.
+- **User data sent for ad matching is redacted** before it is stored in `capture.json` or shown in the report: emails, phone numbers, names, addresses and user ids in GA4 and Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user`, and the `user_data` the site pushes to the dataLayer for enhanced conversions. Any value that looks like an email address is redacted whatever its field is called, except the audited site's own address in a `mailto:` link or a link field (`link_url`, `link_text`, `gtm.elementUrl`, …), such as a contact link in a GTM click event, which is not visitor data. Each value becomes a marker such as `[redacted: 64 chars, looks hashed]`, and a value that wasn't hashed is reported as a personal data risk. `--keep-bodies` (`"keep_bodies": true`) stores requests as sent, for debugging.
 - Stored request bodies are capped at 32 KB per request and 2 MB per journey. Past that, the report says the body wasn't stored.
 - Only run it against sites you own or are authorized to test.
 - Hosting the HTTP server for other people? Also block private and cloud metadata address ranges at the network level (an egress firewall or an isolated network), as defense in depth.

package/README.tr.md

@@ -318,7 +318,7 @@ Tünele gerek kalmayan, hazır bir adresle barındırılan sunucu, [Analitik İ
 - Tarayıcı test edilen sitede ve alt alan adlarında, ayrıca `allowed_hosts` içindeki adreslerde kalır. Sadece `http` ve `https` sayfalarını açar.
 - Modele, sayfa içeriğinin talimat değil veri olduğu söylenir. Bir prompt kuralı, modelin hiçbir zaman yanıltılmayacağını garanti edemez; bu yüzden yukarıdaki gezinme sınırları, yanıltılmış bir modelin yapabileceklerini kısıtlar.
 - Tarayıcı, ortamında API anahtarlarınız ve diğer gizli bilgiler olmadan çalışır.
-- **Reklam eşleştirmesi için gönderilen kullanıcı verileri**, `capture.json` dosyasına kaydedilmeden ya da raporda gösterilmeden önce **gizlenir**: GA4 ve Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user` içindeki e-postalar, telefon numaraları, adlar, adresler ve kullanıcı kimlikleri ile sitenin enhanced conversions için dataLayer'a gönderdiği `user_data`. E-posta adresine benzeyen her değer, alanın adı ne olursa olsun gizlenir. Her değer `[redacted: 64 chars, looks hashed]` gibi bir işarete dönüşür; hash'lenmemiş bir değer kişisel veri riski olarak raporlanır. `--keep-bodies` (`"keep_bodies": true`) hata ayıklama için istekleri gönderildiği haliyle saklar.
+- **Reklam eşleştirmesi için gönderilen kullanıcı verileri**, `capture.json` dosyasına kaydedilmeden ya da raporda gösterilmeden önce **gizlenir**: GA4 ve Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user` içindeki e-postalar, telefon numaraları, adlar, adresler ve kullanıcı kimlikleri ile sitenin enhanced conversions için dataLayer'a gönderdiği `user_data`. E-posta adresine benzeyen her değer, alanın adı ne olursa olsun gizlenir. Denetlenen sitenin kendi adresi bir `mailto:` bağlantısında ya da bir bağlantı alanında (`link_url`, `link_text`, `gtm.elementUrl`, …) geçiyorsa, örneğin bir GTM tıklama olayındaki iletişim bağlantısında, ziyaretçi verisi olmadığı için bu kuralın dışında kalır. Her değer `[redacted: 64 chars, looks hashed]` gibi bir işarete dönüşür; hash'lenmemiş bir değer kişisel veri riski olarak raporlanır. `--keep-bodies` (`"keep_bodies": true`) hata ayıklama için istekleri gönderildiği haliyle saklar.
 - Saklanan istek gövdeleri istek başına 32 KB ve senaryo başına 2 MB ile sınırlıdır. Bu sınırın üstünde rapor, gövdenin saklanmadığını belirtir.
 - Sadece size ait ya da test etme yetkiniz olan sitelerde çalıştırın.
 - HTTP sunucusunu başkaları için mi barındırıyorsunuz? Ek bir güvenlik katmanı olarak özel ağ ve bulut metadata adres aralıklarını ağ seviyesinde de engelleyin (bir egress firewall ya da izole bir ağ ile).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Open-source AI agent that QA-tests your website's analytics, ad and consent tracking (GA4, GTM, Google Ads, Meta, TikTok). Bring your own model (Claude, OpenAI, Gemini) or use it from your chat app over MCP.",
   "type": "module",
   "bin": {

package/src/browser.js

@@ -22,6 +22,14 @@ export const VIEWPORTS = {
 // log survives page navigations.
 /** A page address without its hash, for matching page_location to navigations. */
 const pageKey = (url) => String(url ?? "").split("#")[0];
+/** The host of a URL, or null. */
+const hostOf = (url) => {
+  try {
+    return new URL(url).hostname || null;
+  } catch {
+    return null;
+  }
+};
 
 const INIT_SCRIPT = `(() => {
   const record = (entry) => {
@@ -354,9 +362,10 @@ export class AuditSession {
   /** The hit with user data for ad matching redacted, and userData: { fields, plain } when there was any. */
   redactHit({ userFields, ...hit }) {
     const found = { fields: [], plain: [] };
-    const url = redactUrl(hit.url, found).url;
-    const params = redactParams(hit.params, found);
-    redactParams(userFields, found); // fields from the POST body that the hit doesn't keep
+    const site = hostOf(hit.params?.page_location) ?? hostOf(this.page.url());
+    const url = redactUrl(hit.url, found, site).url;
+    const params = redactParams(hit.params, found, site);
+    redactParams(userFields, found, site); // fields from the POST body that the hit doesn't keep
     if (!found.fields.length) return hit;
     const userData = { fields: [...new Set(found.fields)], plain: [...new Set(found.plain)] };
     return this.opts.keepBodies ? { ...hit, userData } : { ...hit, url, params, userData };
@@ -364,7 +373,7 @@ export class AuditSession {
 
   /** A dataLayer entry with user data redacted, and userData: { fields, plain } when there was any. */
   redactEntry(entry) {
-    const found = redactPush(entry.value);
+    const found = redactPush(entry.value, undefined, hostOf(this.page.url()));
     if (!found.fields.length) return entry;
     const userData = { fields: [...new Set(found.fields)], plain: [...new Set(found.plain)] };
     return this.opts.keepBodies ? { ...entry, userData } : { ...entry, value: found.value, userData };

package/src/checks.js

@@ -2,9 +2,10 @@
 // They run without any API call; the AI model only explains the results.
 
 import { messages } from "./i18n.js";
+import { isOwnAddress } from "./redact.js";
 
 const NON_GOOGLE_AD_PLATFORMS = new Set(["meta", "tiktok"]);
-const EMAIL = /[A-Z0-9._%+-]+(@|%40)[A-Z0-9.-]+\.[A-Z]{2,}/i;
+const EMAIL = /[A-Z0-9._%+-]+(@|%40)[A-Z0-9.-]+\.[A-Z]{2,}/gi;
 const SEVERITY_ORDER = { broken: 0, risk: 1, warning: 2, info: 3, ok: 4 };
 
 /**
@@ -24,6 +25,24 @@ function pageOf(hit) {
   return hit.params?.page_location ?? hit.pageUrl ?? "";
 }
 
+// Just before an address: a mailto: link or a link field (link_url=..., "link_text":"...").
+const LINK_BEFORE = /(mailto:|\b(link_url|link_text|click_url|click_text)(=|":"))$/i;
+
+/**
+ * Whether text holds an email address that could be a visitor's. The site's own address in a
+ * mailto: link or a link field is a contact link it shows; anywhere else it still counts.
+ */
+function visitorEmailIn(text, hit) {
+  let site = null;
+  try {
+    site = new URL(hit.params?.page_location ?? hit.pageUrl).hostname;
+  } catch { /* no page address */ }
+  return [...text.matchAll(EMAIL)].some((m) => {
+    const link = LINK_BEFORE.test(text.slice(Math.max(0, m.index - 16), m.index));
+    return !(link && isOwnAddress(m[0].replace(/%40/i, "@"), site));
+  });
+}
+
 function expectedIn(planEvent, journeyId) {
   return !planEvent.journeys || planEvent.journeys.includes(journeyId);
 }
@@ -172,7 +191,7 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
     if (hit.userData?.plain?.length) {
       piiSeen.add(key(hit.platform, hit.name));
       findings.push({ ...base, severity: "risk", check: "pii", platform: hit.platform, event: hit.name, step: stepLabel(hit.step), detail: d.piiUnhashed(hit.platform, hit.name, hit.userData.plain) });
-    } else if (EMAIL.test(haystack)) {
+    } else if (visitorEmailIn(haystack, hit)) {
       piiSeen.add(key(hit.platform, hit.name));
       findings.push({ ...base, severity: "risk", check: "pii", platform: hit.platform, event: hit.name, step: stepLabel(hit.step), detail: d.pii(hit.platform, hit.name) });
     }

package/src/mcp.js

@@ -22,7 +22,7 @@ import { loadConfig, readJson, runAudit, writeReports } from "./audit.js";
 import { DEFAULT_PROVIDERS, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
-const VERSION = "0.6.2";
+const VERSION = "0.6.3";
 const MAX_OPEN_AUDITS = 4;
 const IDLE_MS = 15 * 60 * 1000; // an audit untouched this long is closed
 const MAX_BODY_BYTES = 1024 * 1024;

package/src/redact.js

@@ -14,9 +14,48 @@ const USER_KEYS = new Set([
 const PUSH_KEYS = new Set(["email", "email_address", "phone", "phone_number", "sha256_email_address", "sha256_phone_number", "sha256_email", "sha256_phone"]);
 const USER_OBJECTS = /(^|\.)(user_data|user_provided_data|enhanced_conversion_data)(\.|$)/;
 
-const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-/** A value that is an email address, whatever its field is called. */
-const isEmail = (v) => typeof v === "string" && EMAIL.test(v.trim());
+const EMAIL = /^(mailto:)?[^\s@]+@([^\s@?]+\.[^\s@?]+)(\?.*)?$/i;
+
+// Second levels that are shared under a country code (shop.com.tr, shop.co.uk), and hosting
+// suffixes whose subdomains belong to different owners (shop.myshopify.com).
+const SHARED_SECOND_LEVELS = new Set(["com", "co", "org", "net", "gov", "edu", "ac", "gen", "web", "bel", "k12", "or", "ne", "go"]);
+const SHARED_SUFFIXES = ["myshopify.com", "github.io", "vercel.app", "pages.dev", "netlify.app", "herokuapp.com", "web.app", "firebaseapp.com", "appspot.com", "wixsite.com", "blogspot.com", "azurewebsites.net", "cloudfront.net", "workers.dev"];
+
+/** "www.shop.example.com.tr" -> "example.com.tr", "a.shop.myshopify.com" -> "shop.myshopify.com": the part one owner controls. */
+function siteOf(host) {
+  const labels = String(host).toLowerCase().replace(/\.$/, "").split(".");
+  const name = labels.join(".");
+  const shared = SHARED_SUFFIXES.find((s) => name === s || name.endsWith(`.${s}`));
+  let n = 2;
+  if (shared) n = shared.split(".").length + 1;
+  else if (labels.length >= 3 && labels.at(-1).length === 2 && SHARED_SECOND_LEVELS.has(labels.at(-2))) n = 3;
+  return labels.slice(-n).join(".");
+}
+
+/** Whether an email address is on the audited site's own domain, like hello@shop.com on a link at shop.com. */
+export function isOwnAddress(email, siteHost) {
+  if (!siteHost) return false;
+  const domain = String(email).trim().match(EMAIL)?.[2];
+  return Boolean(domain) && siteOf(domain) === siteOf(siteHost);
+}
+
+// Fields that hold a link or its text. The site's own address there is a contact link it shows.
+const LINK_KEYS = new Set(["link_url", "link_text", "click_url", "click_text"]);
+const isLinkKey = (key) => {
+  const k = String(key ?? "").toLowerCase();
+  return LINK_KEYS.has(k.split(".").pop()) || /(^|\.)gtm\.element(url|text)$/.test(k);
+};
+
+/**
+ * A value that is an email address (or a mailto: link to one), whatever its field is called.
+ * The site's own address in a mailto: link or a link field is a contact link it shows, not
+ * visitor data. Anywhere else even an own-domain address could be a visitor's (staff, B2B).
+ */
+const isEmail = (v, site, key) => {
+  if (typeof v !== "string" || !EMAIL.test(v.trim())) return false;
+  const link = /^mailto:/i.test(v.trim()) || isLinkKey(key);
+  return !(link && isOwnAddress(v, site));
+};
 
 /** Whether a request parameter (or dotted JSON path) carries user data for ad matching. */
 export function isUserDataKey(key) {
@@ -49,34 +88,34 @@ function note(found, key, value) {
 }
 
 /** Redacts form-encoded parameters (a URL query or a GA4 body line). Returns null when nothing needed it. */
-function redactParamString(text, found) {
+function redactParamString(text, found, site) {
   const params = new URLSearchParams(text);
-  if (![...params].some(([k, v]) => isUserDataKey(k) || isEmail(v))) return null;
+  if (![...params].some(([k, v]) => isUserDataKey(k) || isEmail(v, site, k))) return null;
   const out = new URLSearchParams();
-  for (const [k, v] of params) out.append(k, isUserDataKey(k) || isEmail(v) ? note(found, k, v) : v);
+  for (const [k, v] of params) out.append(k, isUserDataKey(k) || isEmail(v, site, k) ? note(found, k, v) : v);
   return out.toString();
 }
 
-/** Redacts user data in a URL's query. Returns the URL unchanged when there is none. */
-export function redactUrl(url, found = emptyFound()) {
+/** Redacts user data in a URL's query. Returns the URL unchanged when there is none. site: see isOwnAddress. */
+export function redactUrl(url, found = emptyFound(), site = null) {
   let u;
   try {
     u = new URL(url);
   } catch {
     return { url, ...found };
   }
-  const query = redactParamString(u.search, found);
+  const query = redactParamString(u.search, found, site);
   if (query === null) return { url, ...found };
   u.search = query;
   return { url: u.href, ...found };
 }
 
-function redactJson(value, path, found, isKey) {
-  if (Array.isArray(value)) return value.map((v) => redactJson(v, path, found, isKey));
+function redactJson(value, path, found, isKey, site = null) {
+  if (Array.isArray(value)) return value.map((v) => redactJson(v, path, found, isKey, site));
   if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactJson(v, path ? `${path}.${k}` : k, found, isKey)]));
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactJson(v, path ? `${path}.${k}` : k, found, isKey, site)]));
   }
-  if ((typeof value === "string" || typeof value === "number") && ((path && isKey(path)) || isEmail(value))) return note(found, path || "(value)", value);
+  if ((typeof value === "string" || typeof value === "number") && ((path && isKey(path)) || isEmail(value, site, path))) return note(found, path || "(value)", value);
   return value;
 }
 
@@ -110,21 +149,21 @@ export function redactBody(body, found = emptyFound()) {
   return { text, ...found };
 }
 
-/** Redacts user-data entries in parsed hit parameters. */
-export function redactParams(params, found = emptyFound()) {
+/** Redacts user-data entries in parsed hit parameters. site: see isOwnAddress. */
+export function redactParams(params, found = emptyFound(), site = null) {
   const out = {};
-  for (const [k, v] of Object.entries(params ?? {})) out[k] = isUserDataKey(k) || isEmail(v) ? note(found, k, v) : v;
+  for (const [k, v] of Object.entries(params ?? {})) out[k] = isUserDataKey(k) || isEmail(v, site, k) ? note(found, k, v) : v;
   return out;
 }
 
 /**
  * Redacts user data in a dataLayer push (GTM objects or gtag.js arguments):
- * email and phone fields, anything under user_data, and email-like values.
+ * email and phone fields, anything under user_data, and email-like values not on the site's own domain.
  */
-export function redactPush(value, found = emptyFound()) {
+export function redactPush(value, found = emptyFound(), site = null) {
   // gtag("set", "user_data", {...}) has no user_data key: the objects after the name are the user data.
   if (Array.isArray(value) && value.includes("user_data")) {
     return { value: value.map((v) => (v && typeof v === "object" ? redactJson(v, "user_data", found, isPushUserKey) : v)), ...found };
   }
-  return { value: redactJson(value, "", found, isPushUserKey), ...found };
+  return { value: redactJson(value, "", found, isPushUserKey, site), ...found };
 }