feat: capture MaxMind tracking token on session metadata at signup

Author: mattdjenkinson

.gitignore

@@ -1,21 +1,21 @@
-.DS_Store
-node_modules
-.turbo
-*.log
-.next
-dist
-dist-ssr
-*.local
-.env
-server/dist
-public/dist
-.vscode
-.idea
-.vercel
-.env*.local
-/blob-report/
-/out
-/docker
-/machinekey
-
-.cursor
+.DS_Store
+node_modules
+.turbo
+*.log
+.next
+dist
+dist-ssr
+*.local
+server/dist
+public/dist
+.vscode
+.idea
+.vercel
+.env*.local
+/blob-report/
+/out
+/docker
+/machinekey
+
+.cursor
+config.bat

apps/login/next-env-vars.d.ts

@@ -44,5 +44,12 @@ declare namespace NodeJS {
      * Optional: the Fathom analytics id
      */
     FATHOM_ID?: string;
+
+    /**
+     * Optional: the MaxMind minFraud account id used to load the
+     * device-tracking JavaScript snippet at signup. When unset, the
+     * tracker component is not rendered and no token is collected.
+     */
+    NEXT_PUBLIC_MAXMIND_ACCOUNT_ID?: string;
   }
 }

apps/login/package.json

@@ -1,77 +1,77 @@
-{
-  "name": "@zitadel/login",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "pnpm next dev --turbopack",
-    "test:unit": "pnpm vitest",
-    "test:unit:standalone": "pnpm test:unit",
-    "test:unit:watch": "pnpm test:unit --watch",
-    "lint": "pnpm exec eslint . && pnpm exec prettier --check .",
-    "lint:fix": "pnpm exec prettier --write .",
-    "lint-staged": "lint-staged",
-    "build": "pnpm exec next build",
-    "build:login:standalone": "NEXT_PUBLIC_BASE_PATH=/ui/v2/login NEXT_OUTPUT_MODE=standalone pnpm build",
-    "start": "pnpm build && pnpm exec next start",
-    "start:built": "pnpm exec next start",
-    "clean": "pnpm mock:stop && rm -rf .turbo && rm -rf node_modules && rm -rf .next"
-  },
-  "git": {
-    "pre-commit": "lint-staged"
-  },
-  "lint-staged": {
-    "*": "prettier --write --ignore-unknown"
-  },
-  "dependencies": {
-    "@headlessui/react": "^2.1.9",
-    "@heroicons/react": "2.1.3",
-    "@sentry/nextjs": "^10.34.0",
-    "@tailwindcss/forms": "0.5.7",
-    "@vercel/analytics": "^1.2.2",
-    "@zitadel/client": "workspace:*",
-    "@zitadel/proto": "workspace:*",
-    "clsx": "1.2.1",
-    "copy-to-clipboard": "^3.3.3",
-    "deepmerge": "^4.3.1",
-    "fathom-client": "^3.7.2",
-    "lucide-react": "0.469.0",
-    "moment": "^2.29.4",
-    "next": "16.2.3",
-    "next-intl": "^4.9.1",
-    "next-themes": "^0.4.6",
-    "nice-grpc": "2.0.1",
-    "qrcode.react": "^3.1.0",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "react-hook-form": "7.39.5",
-    "tinycolor2": "1.4.2",
-    "uuid": "^11.1.0"
-  },
-  "devDependencies": {
-    "@bufbuild/buf": "^1.53.0",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.3.0",
-    "@types/ms": "2.1.0",
-    "@types/node": "^22.14.1",
-    "@types/react": "19.2.3",
-    "@types/react-dom": "19.2.3",
-    "@types/tinycolor2": "1.4.3",
-    "@types/uuid": "^10.0.0",
-    "@vercel/git-hooks": "1.0.0",
-    "@zitadel/eslint-config": "workspace:*",
-    "@zitadel/prettier-config": "workspace:*",
-    "@zitadel/tailwind-config": "workspace:*",
-    "@zitadel/tsconfig": "workspace:*",
-    "autoprefixer": "10.4.21",
-    "grpc-tools": "1.13.0",
-    "jsdom": "^26.1.0",
-    "lint-staged": "15.5.1",
-    "make-dir-cli": "4.0.0",
-    "postcss": "8.5.3",
-    "prettier-plugin-tailwindcss": "0.6.11",
-    "sass": "^1.87.0",
-    "tailwindcss": "3.4.14",
-    "ts-proto": "^2.7.0",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "@zitadel/login",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm next dev --turbopack",
+    "test:unit": "pnpm vitest",
+    "test:unit:standalone": "pnpm test:unit",
+    "test:unit:watch": "pnpm test:unit --watch",
+    "lint": "pnpm exec eslint . && pnpm exec prettier --check .",
+    "lint:fix": "pnpm exec prettier --write .",
+    "lint-staged": "lint-staged",
+    "build": "pnpm exec next build",
+    "build:login:standalone": "NEXT_PUBLIC_BASE_PATH=/ui/v2/login NEXT_OUTPUT_MODE=standalone pnpm build",
+    "start": "pnpm build && pnpm exec next start",
+    "start:built": "pnpm exec next start",
+    "clean": "pnpm mock:stop && rm -rf .turbo && rm -rf node_modules && rm -rf .next"
+  },
+  "git": {
+    "pre-commit": "lint-staged"
+  },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown"
+  },
+  "dependencies": {
+    "@headlessui/react": "^2.1.9",
+    "@heroicons/react": "2.1.3",
+    "@sentry/nextjs": "^10.34.0",
+    "@tailwindcss/forms": "0.5.7",
+    "@vercel/analytics": "^1.2.2",
+    "@zitadel/client": "workspace:*",
+    "@zitadel/proto": "workspace:*",
+    "clsx": "1.2.1",
+    "copy-to-clipboard": "^3.3.3",
+    "deepmerge": "^4.3.1",
+    "fathom-client": "^3.7.2",
+    "lucide-react": "0.469.0",
+    "moment": "^2.29.4",
+    "next": "16.2.3",
+    "next-intl": "^4.9.1",
+    "next-themes": "^0.4.6",
+    "nice-grpc": "2.0.1",
+    "qrcode.react": "^3.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-hook-form": "7.39.5",
+    "tinycolor2": "1.4.2",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "^1.53.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/ms": "2.1.0",
+    "@types/node": "^22.14.1",
+    "@types/react": "19.2.3",
+    "@types/react-dom": "19.2.3",
+    "@types/tinycolor2": "1.4.3",
+    "@types/uuid": "^10.0.0",
+    "@vercel/git-hooks": "1.0.0",
+    "@zitadel/eslint-config": "workspace:*",
+    "@zitadel/prettier-config": "workspace:*",
+    "@zitadel/tailwind-config": "workspace:*",
+    "@zitadel/tsconfig": "workspace:*",
+    "autoprefixer": "10.4.21",
+    "grpc-tools": "1.13.0",
+    "jsdom": "^26.1.0",
+    "lint-staged": "15.5.1",
+    "make-dir-cli": "4.0.0",
+    "postcss": "8.5.3",
+    "prettier-plugin-tailwindcss": "0.6.11",
+    "sass": "^1.87.0",
+    "tailwindcss": "3.4.14",
+    "ts-proto": "^2.7.0",
+    "typescript": "^5.8.3"
+  }
+}

apps/login/src/app/(main)/layout.tsx

@@ -7,6 +7,7 @@ import { FathomAnalytics } from "@/components/fathom/fathom";
 import { LanguageProvider } from "@/components/language-provider";
 import { Loader } from "@/components/loader";
 import MarkerIoEmbed from "@/components/markerio/markerio";
+import { MaxMindTracker } from "@/components/maxmind/maxmind-tracker";
 import { ThemeProvider } from "@/components/theme-provider";
 import { SITE_CONFIG } from "@/config/site";
 import { alliance, canelaText, frontliner } from "@/lib/fonts/fonts";
@@ -64,6 +65,12 @@ export default async function RootLayout({
         </ThemeProvider>
         <FathomAnalytics />
 
+        {process.env.NEXT_PUBLIC_MAXMIND_ACCOUNT_ID && (
+          <MaxMindTracker
+            accountId={process.env.NEXT_PUBLIC_MAXMIND_ACCOUNT_ID}
+          />
+        )}
+
         {process.env.MARKER_IO_PROJECT_ID && (
           <MarkerIoEmbed projectId={process.env.MARKER_IO_PROJECT_ID} />
         )}

apps/login/src/components/maxmind/maxmind-tracker.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * sessionStorage key under which we stash the MaxMind device-tracking token
+ * captured by device.js. The register form reads it just before submitting so
+ * the value can be forwarded to Zitadel as session metadata.
+ */
+export const MAXMIND_TOKEN_STORAGE_KEY = "datum.maxmind.trackingToken";
+
+/**
+ * Cookie set by MaxMind's device.js after a successful fingerprint exchange.
+ * The cookie value is the tracking token; we mirror it into sessionStorage so
+ * we don't have to parse document.cookie at submit time.
+ */
+const MAXMIND_COOKIE_NAME = "__mmapiwsid";
+
+function readMaxMindCookie(): string {
+  if (typeof document === "undefined") return "";
+  const prefix = `${MAXMIND_COOKIE_NAME}=`;
+  for (const part of document.cookie.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(prefix)) {
+      return decodeURIComponent(trimmed.slice(prefix.length));
+    }
+  }
+  return "";
+}
+
+/**
+ * MaxMindTracker loads the MaxMind minFraud device.js snippet on mount and
+ * polls for the resulting __mmapiwsid cookie, mirroring it into
+ * sessionStorage. Rendering is gated by NEXT_PUBLIC_MAXMIND_ACCOUNT_ID — if
+ * unset the component is a no-op, so dev and preview deployments never
+ * contact MaxMind.
+ */
+export function MaxMindTracker({ accountId }: { accountId: string }) {
+  useEffect(() => {
+    if (!accountId) return;
+    if (typeof window === "undefined") return;
+
+    const w = window as unknown as {
+      __mmapiws?: { accountId?: string };
+    };
+    w.__mmapiws = w.__mmapiws || {};
+    w.__mmapiws.accountId = accountId;
+
+    // Load device.js (idempotent — guard against StrictMode double-mount).
+    if (!document.querySelector('script[data-maxmind="device"]')) {
+      const script = document.createElement("script");
+      script.src = "https://device.maxmind.com/js/device.js";
+      script.async = true;
+      script.dataset.maxmind = "device";
+      document.body.appendChild(script);
+    }
+
+    // Poll briefly for the tracking-token cookie. device.js sets it after
+    // an async fingerprint exchange, typically within a few hundred ms.
+    let attempts = 0;
+    const maxAttempts = 30; // ~6 seconds at 200ms cadence
+    const handle = window.setInterval(() => {
+      attempts++;
+      const token = readMaxMindCookie();
+      if (token) {
+        try {
+          window.sessionStorage.setItem(MAXMIND_TOKEN_STORAGE_KEY, token);
+        } catch {
+          // sessionStorage may be disabled (private mode). Best-effort only.
+        }
+        window.clearInterval(handle);
+        return;
+      }
+      if (attempts >= maxAttempts) {
+        window.clearInterval(handle);
+      }
+    }, 200);
+
+    return () => window.clearInterval(handle);
+  }, [accountId]);
+
+  return null;
+}
+
+/**
+ * Returns the MaxMind device-tracking token captured during the session, or
+ * undefined when none is available (sessionStorage blocked, MaxMind script
+ * not yet finished, or NEXT_PUBLIC_MAXMIND_ACCOUNT_ID unset).
+ */
+export function readMaxMindTrackingToken(): string | undefined {
+  if (typeof window === "undefined") return undefined;
+  try {
+    const value = window.sessionStorage.getItem(MAXMIND_TOKEN_STORAGE_KEY);
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}

apps/login/src/components/register-form-idp-incomplete.tsx

@@ -8,6 +8,7 @@ import { Alert } from "./alert";
 import { BackButton } from "./back-button";
 import { Button, ButtonVariants } from "./button";
 import { TextInput } from "./input";
+import { readMaxMindTrackingToken } from "./maxmind/maxmind-tracker";
 import { Spinner } from "./spinner";
 import { Translated } from "./translated";
 
@@ -71,6 +72,7 @@ export function RegisterFormIDPIncomplete({
       organization: organization,
       requestId: requestId,
       idpIntent: idpIntent,
+      deviceTrackingToken: readMaxMindTrackingToken(),
     })
       .catch(() => {
         setError("Could not register user");

apps/login/src/components/register-form.tsx

@@ -16,6 +16,7 @@ import {
 } from "./authentication-method-radio";
 import { FormActions } from "./form-actions";
 import { TextInput } from "./input";
+import { readMaxMindTrackingToken } from "./maxmind/maxmind-tracker";
 import { Translated } from "./translated";
 
 type Inputs =
@@ -68,6 +69,7 @@ export function RegisterForm({
       lastName: values.lastname,
       organization: organization,
       requestId: requestId,
+      deviceTrackingToken: readMaxMindTrackingToken(),
     })
       .catch(() => {
         setError("Could not register user");

apps/login/src/components/set-register-password-form.tsx

@@ -14,6 +14,7 @@ import { FieldValues, useForm } from "react-hook-form";
 import { Alert } from "./alert";
 import { FormActions } from "./form-actions";
 import { TextInput } from "./input";
+import { readMaxMindTrackingToken } from "./maxmind/maxmind-tracker";
 import { PasswordComplexity } from "./password-complexity";
 import { Translated } from "./translated";
 
@@ -64,6 +65,7 @@ export function SetRegisterPasswordForm({
       organization: organization,
       requestId: requestId,
       password: values.password,
+      deviceTrackingToken: readMaxMindTrackingToken(),
     })
       .catch(() => {
         setError("Could not register user");