diff --git a/modules/.submodules.json b/modules/.submodules.json
index c6274fdcbfd..d87b73401cd 100644
--- a/modules/.submodules.json
+++ b/modules/.submodules.json
@@ -32,6 +32,7 @@
       "kinessoIdSystem",
       "liveIntentIdSystem",
       "lmpIdSystem",
+      "locIdSystem",
       "lockrAIMIdSystem",
       "lotamePanoramaIdSystem",
       "merkleIdSystem",
@@ -147,4 +148,4 @@
       "topLevelPaapi"
     ]
   }
-}
\ No newline at end of file
+}
diff --git a/modules/locIdSystem.js b/modules/locIdSystem.js
new file mode 100644
index 00000000000..5e06e29b302
--- /dev/null
+++ b/modules/locIdSystem.js
@@ -0,0 +1,676 @@
+/**
+ * This file is licensed under the Apache 2.0 license.
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/**
+ * This module adds LocID to the User ID module
+ * The {@link module:modules/userId} module is required.
+ * @module modules/locIdSystem
+ * @requires module:modules/userId
+ */
+
+import { logWarn, logError } from '../src/utils.js';
+import { submodule } from '../src/hook.js';
+import { gppDataHandler, uspDataHandler } from '../src/adapterManager.js';
+import { ajaxBuilder } from '../src/ajax.js';
+import { getStorageManager } from '../src/storageManager.js';
+import { VENDORLESS_GVLID } from '../src/consentHandler.js';
+import { MODULE_TYPE_UID } from '../src/activities/modules.js';
+
+const MODULE_NAME = 'locId';
+const LOG_PREFIX = 'LocID:';
+const DEFAULT_TIMEOUT_MS = 800;
+const DEFAULT_EID_SOURCE = 'locid.com';
+// EID atype: 1 = AdCOM AgentTypeWeb (agent type for web environments)
+const DEFAULT_EID_ATYPE = 1;
+const MAX_ID_LENGTH = 512;
+const MAX_CONNECTION_IP_LENGTH = 64;
+const DEFAULT_IP_CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const IP_CACHE_SUFFIX = '_ip';
+
+export const storage = getStorageManager({ moduleType: MODULE_TYPE_UID, moduleName: MODULE_NAME });
+
+/**
+ * Normalizes privacy mode config to a boolean flag.
+ * Supports both requirePrivacySignals (boolean) and privacyMode (string enum).
+ *
+ * Precedence: requirePrivacySignals (if true) takes priority over privacyMode.
+ * - privacyMode is the preferred high-level setting for new integrations.
+ * - requirePrivacySignals exists for backwards compatibility with integrators
+ *   who prefer a simple boolean.
+ *
+ * @param {Object} params - config.params
+ * @returns {boolean} true if privacy signals are required, false otherwise
+ */
+function shouldRequirePrivacySignals(params) {
+  // requirePrivacySignals=true takes precedence (backwards compatibility)
+  if (params?.requirePrivacySignals === true) {
+    return true;
+  }
+  if (params?.privacyMode === 'requireSignals') {
+    return true;
+  }
+  // Default: allowWithoutSignals
+  return false;
+}
+
+function getUspConsent(consentData) {
+  if (consentData && consentData.usp != null) {
+    return consentData.usp;
+  }
+  return consentData?.uspConsent;
+}
+
+function getGppConsent(consentData) {
+  if (consentData && consentData.gpp != null) {
+    return consentData.gpp;
+  }
+  return consentData?.gppConsent;
+}
+
+/**
+ * Checks if any privacy signals are present in consentData or data handlers.
+ *
+ * IMPORTANT: gdprApplies alone does NOT count as a privacy signal.
+ * A publisher may set gdprApplies=true without having a CMP installed.
+ * We only consider GDPR signals "present" when actual consent framework
+ * artifacts exist (consentString, vendorData). This supports LI-based
+ * operation where no TCF consent string is required.
+ *
+ * "Signals present" means ANY of the following are available:
+ * - consentString or gdpr.consentString (indicates CMP provided framework data)
+ * - vendorData or gdpr.vendorData (indicates CMP provided vendor data)
+ * - usp or uspConsent (US Privacy string)
+ * - gpp or gppConsent (GPP consent data)
+ * - Data from gppDataHandler or uspDataHandler
+ *
+ * @param {Object} consentData - The consent data object passed to getId
+ * @returns {boolean} true if any privacy signals are present
+ */
+function hasPrivacySignals(consentData) {
+  // Check GDPR-related signals (flat and nested)
+  // NOTE: gdprApplies alone is NOT a signal - it just indicates jurisdiction.
+  // A signal requires actual CMP artifacts (consentString or vendorData).
+  if (consentData?.consentString || consentData?.gdpr?.consentString) {
+    return true;
+  }
+  if (consentData?.vendorData || consentData?.gdpr?.vendorData) {
+    return true;
+  }
+
+  // Check USP consent
+  const uspConsent = getUspConsent(consentData);
+  if (uspConsent) {
+    return true;
+  }
+
+  // Check GPP consent
+  const gppConsent = getGppConsent(consentData);
+  if (gppConsent) {
+    return true;
+  }
+
+  // Check data handlers
+  const uspFromHandler = uspDataHandler.getConsentData();
+  if (uspFromHandler) {
+    return true;
+  }
+
+  const gppFromHandler = gppDataHandler.getConsentData();
+  if (gppFromHandler) {
+    return true;
+  }
+
+  return false;
+}
+
+function isValidId(id) {
+  return typeof id === 'string' && id.trim().length > 0 && id.length <= MAX_ID_LENGTH;
+}
+
+function isValidConnectionIp(ip) {
+  return typeof ip === 'string' && ip.length > 0 && ip.length <= MAX_CONNECTION_IP_LENGTH;
+}
+
+function normalizeStoredId(storedId) {
+  if (!storedId) {
+    return null;
+  }
+  if (typeof storedId === 'string') {
+    return null;
+  }
+  if (typeof storedId === 'object') {
+    // Preserve explicit null for id (means "empty tx_cloc, valid cached response").
+    // 'id' in storedId is needed because ?? treats null as nullish and would
+    // incorrectly fall through to tx_cloc.
+    const hasExplicitId = 'id' in storedId;
+    const id = hasExplicitId ? storedId.id : (storedId.tx_cloc ?? null);
+    const connectionIp = storedId.connectionIp ?? storedId.connection_ip;
+    return { ...storedId, id, connectionIp };
+  }
+  return null;
+}
+
+/**
+ * Checks privacy framework signals. Returns true if ID operations are allowed.
+ *
+ * LocID operates under Legitimate Interest and does not require a TCF consent
+ * string when no privacy framework is present. When privacy signals exist,
+ * framework processing restrictions are enforced.
+ *
+ * @param {Object} consentData - The consent data object from Prebid
+ * @param {Object} params - config.params for privacy mode settings
+ * @returns {boolean} true if ID operations are allowed
+ */
+function hasValidConsent(consentData, params) {
+  const requireSignals = shouldRequirePrivacySignals(params);
+  const signalsPresent = hasPrivacySignals(consentData);
+
+  // B) If privacy signals are NOT present
+  if (!signalsPresent) {
+    if (requireSignals) {
+      logWarn(LOG_PREFIX, 'Privacy signals required but none present');
+      return false;
+    }
+    // Default: allow operation without privacy signals (LI-based operation)
+    return true;
+  }
+
+  // A) Privacy signals ARE present - enforce applicable restrictions
+  //
+  // Note: privacy signals can come from GDPR, USP, or GPP. GDPR checks only
+  // apply when GDPR is flagged AND CMP artifacts (consentString/vendorData)
+  // are present. gdprApplies alone does not trigger GDPR enforcement.
+
+  // Check GDPR - support both flat and nested shapes
+  const gdprApplies = consentData?.gdprApplies === true || consentData?.gdpr?.gdprApplies === true;
+  const consentString = consentData?.consentString || consentData?.gdpr?.consentString;
+  const vendorData = consentData?.vendorData || consentData?.gdpr?.vendorData;
+  const gdprCmpArtifactsPresent = !!(consentString || vendorData);
+
+  if (gdprApplies && gdprCmpArtifactsPresent) {
+    // When GDPR applies AND we have CMP signals, require consentString
+    if (!consentString || consentString.length === 0) {
+      logWarn(LOG_PREFIX, 'GDPR framework data missing consent string');
+      return false;
+    }
+  }
+
+  // Check USP for processing restriction
+  const uspData = getUspConsent(consentData) ?? uspDataHandler.getConsentData();
+  if (uspData && uspData.length >= 3 && uspData.charAt(2) === 'Y') {
+    logWarn(LOG_PREFIX, 'US Privacy framework processing restriction detected');
+    return false;
+  }
+
+  // Check GPP for processing restriction
+  const gppData = getGppConsent(consentData) ?? gppDataHandler.getConsentData();
+  if (gppData?.applicableSections?.includes(7) &&
+    gppData?.parsedSections?.usnat?.KnownChildSensitiveDataConsents?.includes(1)) {
+    logWarn(LOG_PREFIX, 'GPP usnat KnownChildSensitiveDataConsents processing restriction detected');
+    return false;
+  }
+
+  return true;
+}
+
+function parseEndpointResponse(response) {
+  if (!response) {
+    return null;
+  }
+  try {
+    return typeof response === 'string' ? JSON.parse(response) : response;
+  } catch (e) {
+    logError(LOG_PREFIX, 'Error parsing endpoint response:', e.message);
+    return null;
+  }
+}
+
+/**
+ * Extracts LocID from endpoint response.
+ * Only tx_cloc is accepted.
+ */
+function extractLocIdFromResponse(parsed) {
+  if (!parsed) return null;
+
+  if (isValidId(parsed.tx_cloc)) {
+    return parsed.tx_cloc;
+  }
+
+  logWarn(LOG_PREFIX, 'Could not extract valid tx_cloc from response');
+  return null;
+}
+
+function extractConnectionIp(parsed) {
+  if (!parsed) {
+    return null;
+  }
+  const connectionIp = parsed.connection_ip ?? parsed.connectionIp;
+  return isValidConnectionIp(connectionIp) ? connectionIp : null;
+}
+
+function getIpCacheKey(config) {
+  const baseName = config?.storage?.name || '_locid';
+  return config?.params?.ipCacheName || (baseName + IP_CACHE_SUFFIX);
+}
+
+function getIpCacheTtlMs(config) {
+  const ttl = config?.params?.ipCacheTtlMs;
+  return (typeof ttl === 'number' && ttl > 0) ? ttl : DEFAULT_IP_CACHE_TTL_MS;
+}
+
+function readIpCache(config) {
+  try {
+    const key = getIpCacheKey(config);
+    const raw = storage.getDataFromLocalStorage(key);
+    if (!raw) return null;
+    const entry = JSON.parse(raw);
+    if (!entry || typeof entry !== 'object') return null;
+    if (!isValidConnectionIp(entry.ip)) return null;
+    if (typeof entry.expiresAt === 'number' && Date.now() > entry.expiresAt) return null;
+    return entry;
+  } catch (e) {
+    logWarn(LOG_PREFIX, 'Error reading IP cache:', e.message);
+    return null;
+  }
+}
+
+function writeIpCache(config, ip) {
+  if (!isValidConnectionIp(ip)) return;
+  try {
+    const key = getIpCacheKey(config);
+    const nowMs = Date.now();
+    const ttlMs = getIpCacheTtlMs(config);
+    const entry = {
+      ip: ip,
+      fetchedAt: nowMs,
+      expiresAt: nowMs + ttlMs
+    };
+    storage.setDataInLocalStorage(key, JSON.stringify(entry));
+  } catch (e) {
+    logWarn(LOG_PREFIX, 'Error writing IP cache:', e.message);
+  }
+}
+
+/**
+ * Parses an IP response from an IP-only endpoint.
+ * Supports JSON ({ip: "..."}, {connection_ip: "..."}) and plain text IP.
+ */
+function parseIpResponse(response) {
+  if (!response) return null;
+
+  if (typeof response === 'string') {
+    const trimmed = response.trim();
+    if (trimmed.charAt(0) === '{') {
+      try {
+        const parsed = JSON.parse(trimmed);
+        const ip = parsed.ip || parsed.connection_ip || parsed.connectionIp;
+        return isValidConnectionIp(ip) ? ip : null;
+      } catch (e) {
+        // Not valid JSON, try as plain text
+      }
+    }
+    return isValidConnectionIp(trimmed) ? trimmed : null;
+  }
+
+  if (typeof response === 'object') {
+    const ip = response.ip || response.connection_ip || response.connectionIp;
+    return isValidConnectionIp(ip) ? ip : null;
+  }
+
+  return null;
+}
+
+/**
+ * Checks if a stored tx_cloc entry is valid for reuse.
+ * Accepts both valid id strings AND null (empty tx_cloc is a valid cached result).
+ */
+function isStoredEntryReusable(normalizedStored, currentIp) {
+  if (!normalizedStored || !isValidConnectionIp(normalizedStored.connectionIp)) {
+    return false;
+  }
+  if (isExpired(normalizedStored)) {
+    return false;
+  }
+  if (currentIp && normalizedStored.connectionIp !== currentIp) {
+    return false;
+  }
+  // id must be either a valid string or explicitly null (empty tx_cloc)
+  return normalizedStored.id === null || isValidId(normalizedStored.id);
+}
+
+function getExpiresAt(config, nowMs) {
+  const expiresDays = config?.storage?.expires;
+  if (typeof expiresDays !== 'number' || expiresDays <= 0) {
+    return undefined;
+  }
+  return nowMs + (expiresDays * 24 * 60 * 60 * 1000);
+}
+
+function buildStoredId(id, connectionIp, config) {
+  const nowMs = Date.now();
+  return {
+    id,
+    connectionIp,
+    createdAt: nowMs,
+    updatedAt: nowMs,
+    expiresAt: getExpiresAt(config, nowMs)
+  };
+}
+
+function isExpired(storedEntry) {
+  return typeof storedEntry?.expiresAt === 'number' && Date.now() > storedEntry.expiresAt;
+}
+
+/**
+ * Builds the request URL, appending altId if configured.
+ * Preserves URL fragments by appending query params before the hash.
+ */
+function buildRequestUrl(endpoint, altId) {
+  if (!altId) {
+    return endpoint;
+  }
+
+  // Split on hash to preserve fragment
+  const hashIndex = endpoint.indexOf('#');
+  let base = endpoint;
+  let fragment = '';
+
+  if (hashIndex !== -1) {
+    base = endpoint.substring(0, hashIndex);
+    fragment = endpoint.substring(hashIndex);
+  }
+
+  const separator = base.includes('?') ? '&' : '?';
+  return `${base}${separator}alt_id=${encodeURIComponent(altId)}${fragment}`;
+}
+
+/**
+ * Fetches LocID from the configured endpoint (GET only).
+ */
+function fetchLocIdFromEndpoint(config, callback) {
+  const params = config?.params || {};
+  const endpoint = params.endpoint;
+  const timeoutMs = params.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+  if (!endpoint) {
+    logError(LOG_PREFIX, 'No endpoint configured');
+    callback(undefined);
+    return;
+  }
+
+  const requestUrl = buildRequestUrl(endpoint, params.altId);
+
+  const requestOptions = {
+    method: 'GET',
+    contentType: 'application/json',
+    withCredentials: params.withCredentials === true
+  };
+
+  // Add x-api-key header if apiKey is configured
+  if (params.apiKey) {
+    requestOptions.customHeaders = {
+      'x-api-key': params.apiKey
+    };
+  }
+
+  let callbackFired = false;
+  const safeCallback = (result) => {
+    if (!callbackFired) {
+      callbackFired = true;
+      callback(result);
+    }
+  };
+
+  const onSuccess = (response) => {
+    const parsed = parseEndpointResponse(response);
+    if (!parsed) {
+      safeCallback(undefined);
+      return;
+    }
+    const connectionIp = extractConnectionIp(parsed);
+    if (!connectionIp) {
+      logWarn(LOG_PREFIX, 'Missing or invalid connection_ip in response');
+      safeCallback(undefined);
+      return;
+    }
+    // tx_cloc may be null (empty/missing for this IP) -- this is a valid cacheable result.
+    // connection_ip is always required.
+    const locId = extractLocIdFromResponse(parsed);
+    writeIpCache(config, connectionIp);
+    safeCallback(buildStoredId(locId, connectionIp, config));
+  };
+
+  const onError = (error) => {
+    logWarn(LOG_PREFIX, 'Request failed:', error);
+    safeCallback(undefined);
+  };
+
+  try {
+    const ajax = ajaxBuilder(timeoutMs);
+    ajax(requestUrl, { success: onSuccess, error: onError }, null, requestOptions);
+  } catch (e) {
+    logError(LOG_PREFIX, 'Error initiating request:', e.message);
+    safeCallback(undefined);
+  }
+}
+
+/**
+ * Fetches the connection IP from a separate lightweight endpoint (GET only).
+ * Callback receives the IP string on success or null on failure.
+ */
+function fetchIpFromEndpoint(config, callback) {
+  const params = config?.params || {};
+  const ipEndpoint = params.ipEndpoint;
+  const timeoutMs = params.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+  if (!ipEndpoint) {
+    callback(null);
+    return;
+  }
+
+  let callbackFired = false;
+  const safeCallback = (result) => {
+    if (!callbackFired) {
+      callbackFired = true;
+      callback(result);
+    }
+  };
+
+  const onSuccess = (response) => {
+    const ip = parseIpResponse(response);
+    safeCallback(ip);
+  };
+
+  const onError = (error) => {
+    logWarn(LOG_PREFIX, 'IP endpoint request failed:', error);
+    safeCallback(null);
+  };
+
+  try {
+    const ajax = ajaxBuilder(timeoutMs);
+    const requestOptions = {
+      method: 'GET',
+      withCredentials: params.withCredentials === true
+    };
+    if (params.apiKey) {
+      requestOptions.customHeaders = {
+        'x-api-key': params.apiKey
+      };
+    }
+    ajax(ipEndpoint, { success: onSuccess, error: onError }, null, requestOptions);
+  } catch (e) {
+    logError(LOG_PREFIX, 'Error initiating IP request:', e.message);
+    safeCallback(null);
+  }
+}
+
+export const locIdSubmodule = {
+  name: MODULE_NAME,
+  aliasName: 'locid',
+  gvlid: VENDORLESS_GVLID,
+
+  /**
+   * Decode stored value into userId object.
+   */
+  decode(value) {
+    if (!value || typeof value !== 'object') {
+      return undefined;
+    }
+    const id = value?.id ?? value?.tx_cloc;
+    const connectionIp = value?.connectionIp ?? value?.connection_ip;
+    if (isValidId(id) && isValidConnectionIp(connectionIp)) {
+      return { locId: id };
+    }
+    return undefined;
+  },
+
+  /**
+   * Get the LocID from endpoint.
+   * Returns {id} for sync or {callback} for async per Prebid patterns.
+   *
+   * Two-tier cache: IP cache (4h default) and tx_cloc cache (7d default).
+   * IP is refreshed more frequently to detect network changes while keeping
+   * tx_cloc stable for its full cache period.
+   */
+  getId(config, consentData, storedId) {
+    const params = config?.params || {};
+
+    // Check privacy restrictions first
+    if (!hasValidConsent(consentData, params)) {
+      return undefined;
+    }
+
+    const normalizedStored = normalizeStoredId(storedId);
+    const cachedIp = readIpCache(config);
+
+    // Step 1: IP cache is valid -- check if tx_cloc matches
+    if (cachedIp) {
+      if (isStoredEntryReusable(normalizedStored, cachedIp.ip)) {
+        return { id: normalizedStored };
+      }
+      // IP cached but tx_cloc missing, expired, or IP mismatch -- full fetch
+      return {
+        callback: (callback) => {
+          fetchLocIdFromEndpoint(config, callback);
+        }
+      };
+    }
+
+    // Step 2: IP cache expired or missing
+    if (params.ipEndpoint) {
+      // Two-call optimization: lightweight IP check first
+      return {
+        callback: (callback) => {
+          fetchIpFromEndpoint(config, (freshIp) => {
+            if (!freshIp) {
+              // IP fetch failed; fall back to main endpoint
+              fetchLocIdFromEndpoint(config, callback);
+              return;
+            }
+            writeIpCache(config, freshIp);
+            // Check if stored tx_cloc matches the fresh IP
+            if (isStoredEntryReusable(normalizedStored, freshIp)) {
+              callback(normalizedStored);
+              return;
+            }
+            // IP changed or no valid tx_cloc -- full fetch
+            fetchLocIdFromEndpoint(config, callback);
+          });
+        }
+      };
+    }
+
+    // Step 3: No ipEndpoint configured -- call main endpoint to refresh IP.
+    // Only update tx_cloc if IP changed or tx_cloc cache expired.
+    return {
+      callback: (callback) => {
+        fetchLocIdFromEndpoint(config, (freshEntry) => {
+          if (!freshEntry) {
+            callback(undefined);
+            return;
+          }
+          // Honor empty tx_cloc: if the server returned null, use the fresh
+          // entry so stale identifiers are cleared (cached as id: null).
+          if (freshEntry.id === null) {
+            callback(freshEntry);
+            return;
+          }
+          // IP is already cached by fetchLocIdFromEndpoint's onSuccess.
+          // Check if we should preserve the existing tx_cloc (avoid churning it).
+          if (normalizedStored?.id !== null && isStoredEntryReusable(normalizedStored, freshEntry.connectionIp)) {
+            callback(normalizedStored);
+            return;
+          }
+          // IP changed or tx_cloc expired/missing -- use fresh entry
+          callback(freshEntry);
+        });
+      }
+    };
+  },
+
+  /**
+   * Extend existing LocID.
+   * Accepts id: null (empty tx_cloc) as a valid cached result.
+   * If IP cache is missing/expired/mismatched, return a callback to refresh.
+   */
+  extendId(config, consentData, storedId) {
+    const normalizedStored = normalizeStoredId(storedId);
+    if (!normalizedStored || !isValidConnectionIp(normalizedStored.connectionIp)) {
+      return undefined;
+    }
+    // Accept both valid id strings AND null (empty tx_cloc is a valid cached result)
+    if (normalizedStored.id !== null && !isValidId(normalizedStored.id)) {
+      return undefined;
+    }
+    if (isExpired(normalizedStored)) {
+      return undefined;
+    }
+    if (!hasValidConsent(consentData, config?.params)) {
+      return undefined;
+    }
+    const refreshInSeconds = config?.storage?.refreshInSeconds;
+    if (typeof refreshInSeconds === 'number' && refreshInSeconds > 0) {
+      const createdAt = normalizedStored.createdAt;
+      if (typeof createdAt !== 'number') {
+        return undefined;
+      }
+      const refreshAfterMs = refreshInSeconds * 1000;
+      if (Date.now() - createdAt >= refreshAfterMs) {
+        return undefined;
+      }
+    }
+    // Check IP cache -- if expired/missing or IP changed, trigger re-fetch
+    const cachedIp = readIpCache(config);
+    if (!cachedIp || cachedIp.ip !== normalizedStored.connectionIp) {
+      return {
+        callback: (callback) => {
+          fetchLocIdFromEndpoint(config, callback);
+        }
+      };
+    }
+    return { id: normalizedStored };
+  },
+
+  /**
+   * EID configuration following standard Prebid shape.
+   */
+  eids: {
+    locId: {
+      source: DEFAULT_EID_SOURCE,
+      atype: DEFAULT_EID_ATYPE,
+      getValue: function (data) {
+        if (typeof data === 'string') {
+          return data;
+        }
+        if (!data || typeof data !== 'object') {
+          return undefined;
+        }
+        return data?.id ?? data?.tx_cloc ?? data?.locId ?? data?.locid;
+      }
+    }
+  }
+};
+
+submodule('userId', locIdSubmodule);
diff --git a/modules/locIdSystem.md b/modules/locIdSystem.md
new file mode 100644
index 00000000000..6ffe02fe841
--- /dev/null
+++ b/modules/locIdSystem.md
@@ -0,0 +1,250 @@
+# LocID User ID Submodule
+
+## Overview
+
+The LocID User ID submodule retrieves a LocID from a configured first-party endpoint, honors applicable privacy framework processing restrictions when present, persists the identifier using Prebid's storage framework, and exposes the ID to bidders via the standard EIDs interface.
+
+LocID is a geospatial identifier provided by Digital Envoy. The endpoint is a publisher-controlled, first-party or on-premises service operated by the publisher, GrowthCode, or Digital Envoy. The endpoint derives location information server-side. The browser module does not transmit IP addresses.
+
+## Configuration
+
+```javascript
+pbjs.setConfig({
+  userSync: {
+    userIds: [{
+      name: 'locId',
+      params: {
+        endpoint: 'https://id.example.com/locid',
+        ipEndpoint: 'https://id.example.com/ip'  // optional: lightweight IP-only check
+      },
+      storage: {
+        type: 'html5',
+        name: '_locid',
+        expires: 7
+      }
+    }]
+  }
+});
+```
+
+## Parameters
+
+| Parameter               | Type    | Required | Default                 | Description                                                                   |
+| ----------------------- | ------- | -------- | ----------------------- | ----------------------------------------------------------------------------- |
+| `endpoint`              | String  | Yes      | –                       | First-party LocID endpoint (see Endpoint Requirements below)                  |
+| `ipEndpoint`            | String  | No       | –                       | Separate endpoint returning the connection IP (see IP Change Detection below) |
+| `ipCacheTtlMs`          | Number  | No       | `14400000` (4h)         | TTL for the IP cache entry in milliseconds                                    |
+| `ipCacheName`           | String  | No       | `{storage.name}_ip`     | localStorage key for the IP cache (auto-derived if not set)                   |
+| `altId`                 | String  | No       | –                       | Alternative identifier appended as `?alt_id=` query param                     |
+| `timeoutMs`             | Number  | No       | `800`                   | Request timeout in milliseconds                                               |
+| `withCredentials`       | Boolean | No       | `false`                 | Whether to include credentials on the request                                 |
+| `apiKey`                | String  | No       | –                       | API key sent as `x-api-key` header on `endpoint` and `ipEndpoint` requests    |
+| `requirePrivacySignals` | Boolean | No       | `false`                 | If `true`, requires privacy signals to be present                             |
+| `privacyMode`           | String  | No       | `'allowWithoutSignals'` | `'allowWithoutSignals'` or `'requireSignals'`                                 |
+
+**Note on privacy configuration:** `privacyMode` is the preferred high-level setting for new integrations. `requirePrivacySignals` exists for backwards compatibility with integrators who prefer a simple boolean. If `requirePrivacySignals: true` is set, it takes precedence.
+
+### Endpoint Requirements
+
+The `endpoint` parameter must point to a **first-party proxy** or **on-premises service**—not the raw LocID Encrypt API directly.
+
+The LocID Encrypt API (`GET /encrypt?ip=<IP>&alt_id=<ALT_ID>`) requires the client IP address as a parameter. Since browsers cannot reliably determine their own public IP, a server-side proxy is required to:
+
+1. Receive the request from the browser
+2. Extract the client IP from the incoming connection
+3. Forward the request to the LocID Encrypt API with the IP injected
+4. Return the response with `tx_cloc` and `connection_ip` to the browser (any `stable_cloc` is ignored client-side)
+
+This architecture ensures the browser never transmits IP addresses and the LocID service receives accurate location data.
+
+If you configure `altId`, the module appends it as `?alt_id=<value>` to the endpoint URL. Your proxy can then forward this to the LocID API.
+
+### CORS Configuration
+
+If your endpoint is on a different origin or you set `withCredentials: true`, ensure your server returns appropriate CORS headers:
+
+```http
+Access-Control-Allow-Origin: <your-origin>
+Access-Control-Allow-Credentials: true
+```
+
+When using `withCredentials`, the server cannot use `Access-Control-Allow-Origin: *`; it must specify the exact origin.
+
+### Storage Configuration
+
+| Parameter | Required | Description      |
+| --------- | -------- | ---------------- |
+| `type`    | Yes      | `'html5'`        |
+| `name`    | Yes      | Storage key name |
+| `expires` | No       | TTL in days      |
+
+### Stored Value Format
+
+The module stores a structured object (rather than a raw string) so it can track IP-aware metadata:
+
+```json
+{
+  "id": "<tx_cloc>",
+  "connectionIp": "203.0.113.42",
+  "createdAt": 1738147200000,
+  "updatedAt": 1738147200000,
+  "expiresAt": 1738752000000
+}
+```
+
+When the endpoint returns a valid `connection_ip` but no usable `tx_cloc` (`null`, missing, empty, or whitespace-only), `id` is stored as `null`. This caches the "no location for this IP" result for the full cache period without re-fetching. The `decode()` function returns `undefined` for `null` IDs, so no EID is emitted in bid requests.
+
+**Important:** String-only stored values are treated as invalid and are not emitted.
+
+### IP Cache Format
+
+The module maintains a separate IP cache entry in localStorage (default key: `{storage.name}_ip`) with a shorter TTL (default 4 hours):
+
+```json
+{
+  "ip": "203.0.113.42",
+  "fetchedAt": 1738147200000,
+  "expiresAt": 1738161600000
+}
+```
+
+This entry is managed by the module directly via Prebid's `storageManager` and is independent of the framework-managed tx_cloc cache.
+
+## Operation Flow
+
+The module uses a two-tier cache: an IP cache (default 4-hour TTL) and a tx_cloc cache (TTL defined by `storage.expires`). The IP is refreshed more frequently to detect network changes while keeping tx_cloc stable for its full cache period.
+
+1. The module checks the IP cache for a current connection IP.
+2. If the IP cache is valid, the module compares it against the stored tx_cloc entry's `connectionIp`.
+3. If the IPs match and the tx_cloc entry is not expired, the cached tx_cloc is reused (even if `null`).
+4. If the IP cache is expired or missing and `ipEndpoint` is configured, the module calls `ipEndpoint` to get the current IP, then compares with the stored tx_cloc. If the IPs match, the tx_cloc is reused without calling the main endpoint.
+5. If the IPs differ, or the tx_cloc is expired/missing, or `ipEndpoint` is not configured, the module calls the main endpoint to get a fresh tx_cloc and connection IP.
+6. The endpoint response may include a `null`, empty, whitespace-only, or missing `tx_cloc` (indicating no location for this IP). This is cached as `id: null` for the full cache period, and overrides any previously stored non-null ID for that same IP.
+7. Both the IP cache and tx_cloc cache are updated after each endpoint call.
+8. The ID is included in bid requests via the EIDs array. Entries with `null` tx_cloc are omitted from bid requests.
+
+## Endpoint Response Requirements
+
+The proxy must return:
+
+```json
+{
+  "tx_cloc": "<transactional locid>",
+  "connection_ip": "203.0.113.42"
+}
+```
+
+Notes:
+
+- `connection_ip` is always required. If missing, the entire response is treated as a failure.
+- `tx_cloc` may be `null`, missing, empty, or whitespace-only when no location is available for the IP. This is a valid response and will be cached as `id: null` for the configured cache period.
+- `tx_cloc` is the only value the browser module will store/transmit.
+- `stable_cloc` may exist in proxy responses for server-side caching, but the client ignores it.
+
+## IP Change Detection
+
+The module uses a two-tier cache to detect IP changes without churning the tx_cloc identifier:
+
+- **IP cache** (default 4-hour TTL): Tracks the current connection IP. Stored in a separate localStorage key (`{storage.name}_ip`).
+- **tx_cloc cache** (`storage.expires`): Stores the LocID. Managed by Prebid's userId framework.
+
+When the IP cache expires, the module refreshes the IP. If the IP is unchanged and the tx_cloc cache is still valid, the existing tx_cloc is reused without calling the main endpoint.
+
+### ipEndpoint (optional)
+
+When `ipEndpoint` is configured, the module calls it for lightweight IP-only checks. This avoids a full tx_cloc API call when only the IP needs refreshing. The endpoint should return the connection IP in one of these formats:
+
+- JSON: `{"ip": "203.0.113.42"}` or `{"connection_ip": "203.0.113.42"}`
+- Plain text: `203.0.113.42`
+
+If `apiKey` is configured, the `x-api-key` header is included on `ipEndpoint` requests using the same `customHeaders` mechanism as the main endpoint.
+
+When `ipEndpoint` is not configured, the module falls back to calling the main endpoint to refresh the IP, but only updates the stored tx_cloc when the IP has changed or the tx_cloc cache has expired. In this mode, IP changes are only detected when the IP cache is refreshed (for example when it expires and `extendId()` returns a refresh callback); there is no separate lightweight proactive IP probe.
+
+### Prebid Refresh Triggers
+
+When `storage.refreshInSeconds` is set, the module will reuse the cached ID until `createdAt + refreshInSeconds`; once due (or if `createdAt` is missing), `extendId()` returns `undefined` to indicate the cached ID should not be reused. The `extendId()` method also checks the IP cache: if the IP cache is expired or missing, or if the cached IP differs from the stored tx_cloc's IP, it returns a callback that refreshes via the main endpoint. This enforces the IP cache TTL (`ipCacheTtlMs`) even when the tx_cloc cache has not expired.
+
+## Consent Handling
+
+LocID operates under Legitimate Interest (LI). By default, the module proceeds when no privacy framework signals are present. When privacy signals exist, they are enforced. Privacy frameworks can only stop LocID via global processing restrictions; they do not enable it.
+For TCF integration, the module declares Prebid's vendorless GVL marker so purpose-level enforcement applies without vendor-ID checks.
+
+### Legal Basis and IP-Based Identifiers
+
+LocID is derived from IP-based geolocation. Because IP addresses are transient and shared, there is no meaningful IP-level choice to express. Privacy frameworks are only consulted to honor rare, publisher- or regulator-level instructions to stop all processing. When such a global processing restriction is signaled, LocID respects it by returning `undefined`.
+
+### Default Behavior (allowWithoutSignals)
+
+- **No privacy signals present**: Module proceeds and fetches the ID
+- **Privacy signals present**: Enforcement rules apply (see below)
+
+### Strict Mode (requireSignals)
+
+Set `requirePrivacySignals: true` or `privacyMode: 'requireSignals'` to require privacy signals:
+
+```javascript
+params: {
+  endpoint: 'https://id.example.com/locid',
+  requirePrivacySignals: true
+}
+```
+
+In strict mode, the module returns `undefined` if no privacy signals are present.
+
+### Privacy Signal Enforcement
+
+When privacy signals **are** present, the module does not fetch or return an ID if any of the following apply:
+
+- GDPR applies and vendorData is present, but consentString is missing or empty
+- The US Privacy string indicates a global processing restriction (third character is 'Y')
+- GPP signals indicate an applicable processing restriction
+
+When GDPR applies and `consentString` is present, the module proceeds unless a framework processing restriction is signaled.
+
+### Privacy Signals Detection
+
+The module considers privacy signals "present" if any of the following exist:
+
+- `consentString` (TCF consent string from CMP)
+- `vendorData` (TCF vendor data from CMP)
+- `usp` or `uspConsent` (US Privacy string)
+- `gpp` or `gppConsent` (GPP consent data)
+- Data from `uspDataHandler` or `gppDataHandler`
+
+**Important:** `gdprApplies` alone does NOT constitute a privacy signal. A publisher may indicate GDPR jurisdiction without having a CMP installed. TCF framework data is only required when actual CMP artifacts (`consentString` or `vendorData`) are present. This supports Legitimate Interest-based operation in deployments without a full TCF implementation.
+
+## EID Output
+
+When available, the LocID is exposed as:
+
+```javascript
+{
+  source: "locid.com",
+  uids: [{
+    id: "<locid-value>",
+    atype: 1 // AdCOM AgentTypeWeb
+  }]
+}
+```
+
+## Identifier Type
+
+- **`atype: 1`** — The AdCOM agent type for web (`AgentTypeWeb`). This is used in EID emission.
+
+`atype` is an OpenRTB agent type (environment), not an IAB GVL vendor ID.
+
+## Debugging
+
+```javascript
+pbjs.getUserIds().locId
+pbjs.refreshUserIds()
+localStorage.getItem('_locid')
+localStorage.getItem('_locid_ip')  // IP cache entry
+```
+
+## Validation Checklist
+
+- [ ] EID is present in bid requests when no processing restriction is signaled
+- [ ] No network request occurs when a global processing restriction is signaled
+- [ ] Stored IDs are reused across page loads
diff --git a/modules/userId/eids.md b/modules/userId/eids.md
index f6f62229f53..bdd8a0bb3e8 100644
--- a/modules/userId/eids.md
+++ b/modules/userId/eids.md
@@ -25,6 +25,14 @@ userIdAsEids = [
         }]
     },
 
+    {
+        source: 'locid.com',
+        uids: [{
+            id: 'some-random-id-value',
+            atype: 1
+        }]
+    },
+
     {
         source: 'adserver.org',
         uids: [{
diff --git a/modules/userId/userId.md b/modules/userId/userId.md
index 8ffd8f83043..f7bea8fd9f8 100644
--- a/modules/userId/userId.md
+++ b/modules/userId/userId.md
@@ -91,6 +91,16 @@ pbjs.setConfig({
                 name: '_li_pbid',
                 expires: 60
             }
+        }, {
+            name: 'locId',
+            params: {
+                endpoint: 'https://id.example.com/locid'
+            },
+            storage: {
+                type: 'html5',
+                name: '_locid',
+                expires: 7
+            }
         }, {
              name: 'criteo',
              storage: {             // It is best not to specify this parameter since the module needs to be called as many times as possible
diff --git a/test/build-logic/no_3384_spec.mjs b/test/build-logic/no_3384_spec.mjs
new file mode 100644
index 00000000000..94cc47227ef
--- /dev/null
+++ b/test/build-logic/no_3384_spec.mjs
@@ -0,0 +1,47 @@
+import {describe, it} from 'mocha';
+import {expect} from 'chai';
+import {execFileSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+describe('build hygiene checks', () => {
+  it('should not contain the forbidden legacy token in LocID files', () => {
+    const forbiddenToken = ['33', '84'].join('');
+    const scopeArgs = [
+      'ls-files',
+      '--',
+      ':(glob)modules/**/locId*',
+      ':(glob)test/spec/**/locId*',
+      'docs/modules/locid.md',
+      'modules/locIdSystem.md'
+    ];
+    const scopedPaths = execFileSync('git', scopeArgs, { cwd: repoRoot, encoding: 'utf8' })
+      .split('\n')
+      .map(filePath => filePath.trim())
+      .filter(Boolean);
+
+    expect(scopedPaths.length, 'No LocID files were selected for the 3384 guard').to.be.greaterThan(0);
+
+    const args = [
+      'grep',
+      '-n',
+      '-I',
+      '-E',
+      `\\b${forbiddenToken}\\b`,
+      '--',
+      ...scopedPaths
+    ];
+
+    try {
+      const output = execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+      expect(output.trim(), `Unexpected ${forbiddenToken} matches:\n${output}`).to.equal('');
+    } catch (e) {
+      if (e?.status === 1) {
+        return;
+      }
+      throw e;
+    }
+  });
+});
diff --git a/test/spec/modules/locIdSystem_spec.js b/test/spec/modules/locIdSystem_spec.js
new file mode 100644
index 00000000000..1b2fc02ddc8
--- /dev/null
+++ b/test/spec/modules/locIdSystem_spec.js
@@ -0,0 +1,2090 @@
+/**
+ * This file is licensed under the Apache 2.0 license.
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import { locIdSubmodule, storage } from 'modules/locIdSystem.js';
+import { createEidsArray } from 'modules/userId/eids.js';
+import { attachIdSystem } from 'modules/userId/index.js';
+import * as ajax from 'src/ajax.js';
+import { VENDORLESS_GVLID } from 'src/consentHandler.js';
+import { uspDataHandler, gppDataHandler } from 'src/adapterManager.js';
+import { expect } from 'chai/index.mjs';
+import sinon from 'sinon';
+
+const TEST_ID = 'SYybozbTuRaZkgGqCD7L7EE0FncoNUcx-om4xTfhJt36TFIAES2tF1qPH';
+const TEST_ENDPOINT = 'https://id.example.com/locid';
+const TEST_CONNECTION_IP = '203.0.113.42';
+
+describe('LocID System', () => {
+  let sandbox;
+  let ajaxStub;
+  let ajaxBuilderStub;
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox();
+    sandbox.stub(uspDataHandler, 'getConsentData').returns(null);
+    sandbox.stub(gppDataHandler, 'getConsentData').returns(null);
+    sandbox.stub(storage, 'getDataFromLocalStorage').returns(null);
+    sandbox.stub(storage, 'setDataInLocalStorage');
+    ajaxStub = sandbox.stub();
+    ajaxBuilderStub = sandbox.stub(ajax, 'ajaxBuilder').returns(ajaxStub);
+  });
+
+  afterEach(() => {
+    sandbox.restore();
+  });
+
+  describe('module properties', () => {
+    it('should expose correct module name', () => {
+      expect(locIdSubmodule.name).to.equal('locId');
+    });
+
+    it('should have eids configuration with correct defaults', () => {
+      expect(locIdSubmodule.eids).to.be.an('object');
+      expect(locIdSubmodule.eids.locId).to.be.an('object');
+      expect(locIdSubmodule.eids.locId.source).to.equal('locid.com');
+      // atype 1 = AdCOM AgentTypeWeb
+      expect(locIdSubmodule.eids.locId.atype).to.equal(1);
+    });
+
+    it('should register as a vendorless TCF module', () => {
+      expect(locIdSubmodule.gvlid).to.equal(VENDORLESS_GVLID);
+    });
+
+    it('should have getValue function that extracts ID', () => {
+      const getValue = locIdSubmodule.eids.locId.getValue;
+      expect(getValue('test-id')).to.equal('test-id');
+      expect(getValue({ id: 'id-shape' })).to.equal('id-shape');
+      expect(getValue({ locId: 'test-id' })).to.equal('test-id');
+      expect(getValue({ locid: 'legacy-id' })).to.equal('legacy-id');
+    });
+  });
+
+  describe('decode', () => {
+    it('should decode valid ID correctly', () => {
+      const result = locIdSubmodule.decode({ id: TEST_ID, connectionIp: TEST_CONNECTION_IP });
+      expect(result).to.deep.equal({ locId: TEST_ID });
+    });
+
+    it('should decode ID passed as object', () => {
+      const result = locIdSubmodule.decode({ id: TEST_ID, connectionIp: TEST_CONNECTION_IP });
+      expect(result).to.deep.equal({ locId: TEST_ID });
+    });
+
+    it('should return undefined for invalid values', () => {
+      [null, undefined, '', {}, [], 123, TEST_ID].forEach(value => {
+        expect(locIdSubmodule.decode(value)).to.be.undefined;
+      });
+    });
+
+    it('should return undefined when connection_ip is missing', () => {
+      expect(locIdSubmodule.decode({ id: TEST_ID })).to.be.undefined;
+    });
+
+    it('should return undefined for IDs exceeding max length', () => {
+      const longId = 'a'.repeat(513);
+      expect(locIdSubmodule.decode({ id: longId, connectionIp: TEST_CONNECTION_IP })).to.be.undefined;
+    });
+
+    it('should accept ID at exactly MAX_ID_LENGTH (512 characters)', () => {
+      const maxLengthId = 'a'.repeat(512);
+      const result = locIdSubmodule.decode({ id: maxLengthId, connectionIp: TEST_CONNECTION_IP });
+      expect(result).to.deep.equal({ locId: maxLengthId });
+    });
+  });
+
+  describe('getId', () => {
+    it('should return callback for async endpoint fetch', () => {
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+      const result = locIdSubmodule.getId(config, {});
+      expect(result).to.have.property('callback');
+      expect(result.callback).to.be.a('function');
+    });
+
+    it('should call endpoint and return tx_cloc on success', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.equal(TEST_ID);
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        expect(ajaxStub.calledOnce).to.be.true;
+        done();
+      });
+    });
+
+    it('should cache entry with null id when tx_cloc is missing but connection_ip is present', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ stable_cloc: 'stable-cloc-id-12345', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.be.null;
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should prefer tx_cloc over stable_cloc when both present', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({
+          tx_cloc: TEST_ID,
+          stable_cloc: 'stable-fallback',
+          connection_ip: TEST_CONNECTION_IP
+        }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.equal(TEST_ID);
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should return undefined on endpoint error', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.error('Network error');
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.undefined;
+        done();
+      });
+    });
+
+    it('should reuse storedId when valid and IP cache matches', () => {
+      // Set up IP cache matching stored entry's IP
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        },
+        storage: {
+          name: '_locid'
+        }
+      };
+      const storedId = {
+        id: 'existing-id',
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should not reuse storedId when expired', () => {
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+      const storedId = {
+        id: 'expired-id',
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: 1000,
+        updatedAt: 1000,
+        expiresAt: Date.now() - 1000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should not reuse storedId when connectionIp is missing', () => {
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+      const storedId = {
+        id: 'existing-id',
+        createdAt: 1000,
+        updatedAt: 1000,
+        expiresAt: 2000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should pass x-api-key header when apiKey is configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(options.customHeaders).to.deep.equal({ 'x-api-key': 'test-api-key' });
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          apiKey: 'test-api-key'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should not include customHeaders when apiKey is not configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(options.customHeaders).to.not.exist;
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should pass withCredentials when configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(options.withCredentials).to.be.true;
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          withCredentials: true
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should default withCredentials to false', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(options.withCredentials).to.be.false;
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should use default timeout of 800ms when timeoutMs is not configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        expect(ajaxBuilderStub.calledWith(800)).to.be.true;
+        done();
+      });
+    });
+
+    it('should use custom timeout when timeoutMs is configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          timeoutMs: 1500
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        expect(ajaxBuilderStub.calledWith(1500)).to.be.true;
+        done();
+      });
+    });
+
+    it('should always use GET method', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(options.method).to.equal('GET');
+        expect(body).to.be.null;
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should append alt_id query parameter when altId is configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal(TEST_ENDPOINT + '?alt_id=user123');
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          altId: 'user123'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should use & separator when endpoint already has query params', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal(TEST_ENDPOINT + '?existing=param&alt_id=user456');
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT + '?existing=param',
+          altId: 'user456'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should URL-encode altId value', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal(TEST_ENDPOINT + '?alt_id=user%40example.com');
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          altId: 'user@example.com'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should not append alt_id when altId is not configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal(TEST_ENDPOINT);
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should preserve URL fragment when appending alt_id', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal('https://id.example.com/locid?alt_id=user123#frag');
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: 'https://id.example.com/locid#frag',
+          altId: 'user123'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should preserve URL fragment when endpoint has existing query params', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        expect(url).to.equal('https://id.example.com/locid?x=1&alt_id=user456#frag');
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: 'https://id.example.com/locid?x=1#frag',
+          altId: 'user456'
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => done());
+    });
+
+    it('should return undefined via callback when endpoint is empty string', (done) => {
+      const config = {
+        params: {
+          endpoint: ''
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.undefined;
+        expect(ajaxStub.called).to.be.false;
+        done();
+      });
+    });
+  });
+
+  describe('extendId', () => {
+    const config = {
+      params: {
+        endpoint: TEST_ENDPOINT
+      }
+    };
+
+    it('should return stored id when valid and IP cache is current', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 14400000
+      }));
+      const storedId = { id: 'existing-id', connectionIp: TEST_CONNECTION_IP };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+    });
+
+    it('should reuse storedId when refreshInSeconds is configured but not due', () => {
+      const now = Date.now();
+      const refreshInSeconds = 60;
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: now,
+        expiresAt: now + 14400000
+      }));
+      const storedId = {
+        id: 'existing-id',
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: now - ((refreshInSeconds - 10) * 1000),
+        expiresAt: now + 10000
+      };
+      const refreshConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        },
+        storage: {
+          refreshInSeconds
+        }
+      };
+      const result = locIdSubmodule.extendId(refreshConfig, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+    });
+
+    it('should return undefined when refreshInSeconds is due', () => {
+      const now = Date.now();
+      const refreshInSeconds = 60;
+      const storedId = {
+        id: 'existing-id',
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: now - ((refreshInSeconds + 10) * 1000),
+        expiresAt: now + 10000
+      };
+      const refreshConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        },
+        storage: {
+          refreshInSeconds
+        }
+      };
+      const result = locIdSubmodule.extendId(refreshConfig, {}, storedId);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined when refreshInSeconds is configured and createdAt is missing', () => {
+      const now = Date.now();
+      const refreshInSeconds = 60;
+      const storedId = {
+        id: 'existing-id',
+        connectionIp: TEST_CONNECTION_IP,
+        expiresAt: now + 10000
+      };
+      const refreshConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        },
+        storage: {
+          refreshInSeconds
+        }
+      };
+      const result = locIdSubmodule.extendId(refreshConfig, {}, storedId);
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined when storedId is a string', () => {
+      const result = locIdSubmodule.extendId(config, {}, 'existing-id');
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined when connectionIp is missing', () => {
+      const result = locIdSubmodule.extendId(config, {}, { id: 'existing-id' });
+      expect(result).to.be.undefined;
+    });
+
+    it('should return undefined when stored entry is expired', () => {
+      const storedId = {
+        id: 'existing-id',
+        connectionIp: TEST_CONNECTION_IP,
+        expiresAt: Date.now() - 1000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.be.undefined;
+    });
+  });
+
+  describe('privacy framework handling', () => {
+    const config = {
+      params: {
+        endpoint: TEST_ENDPOINT
+      }
+    };
+
+    // --- Tests for no privacy signals (LI-based operation) ---
+    // LocID operates under Legitimate Interest and should proceed when no
+    // privacy framework is present, unless requirePrivacySignals is enabled.
+
+    it('should proceed when no consentData provided at all (default LI-based operation)', () => {
+      // When no privacy signals are present, module should proceed by default
+      const result = locIdSubmodule.getId(config, undefined);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when consentData is null (default LI-based operation)', () => {
+      const result = locIdSubmodule.getId(config, null);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when consentData is empty object (default LI-based operation)', () => {
+      // Empty object has no privacy signals, so should proceed
+      const result = locIdSubmodule.getId(config, {});
+      expect(result).to.have.property('callback');
+    });
+
+    it('should return undefined when no consentData and requirePrivacySignals=true', () => {
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          requirePrivacySignals: true
+        }
+      };
+      const result = locIdSubmodule.getId(strictConfig, undefined);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined when empty consentData and requirePrivacySignals=true', () => {
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          requirePrivacySignals: true
+        }
+      };
+      const result = locIdSubmodule.getId(strictConfig, {});
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined when no consentData and privacyMode=requireSignals', () => {
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          privacyMode: 'requireSignals'
+        }
+      };
+      const result = locIdSubmodule.getId(strictConfig, undefined);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should proceed when no consentData and privacyMode=allowWithoutSignals', () => {
+      const permissiveConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          privacyMode: 'allowWithoutSignals'
+        }
+      };
+      const result = locIdSubmodule.getId(permissiveConfig, undefined);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed with privacy signals present and requirePrivacySignals=true', () => {
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          requirePrivacySignals: true
+        }
+      };
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {}
+        }
+      };
+      const result = locIdSubmodule.getId(strictConfig, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should detect privacy signals from uspDataHandler and block on processing restriction', () => {
+      // Restore and re-stub to return USP processing restriction signal
+      uspDataHandler.getConsentData.restore();
+      sandbox.stub(uspDataHandler, 'getConsentData').returns('1YY-');
+
+      // Even with empty consentData, handler provides privacy signal
+      const result = locIdSubmodule.getId(config, {});
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should detect privacy signals from gppDataHandler and block on processing restriction', () => {
+      // Restore and re-stub to return GPP processing restriction signal
+      gppDataHandler.getConsentData.restore();
+      sandbox.stub(gppDataHandler, 'getConsentData').returns({
+        applicableSections: [7],
+        parsedSections: {
+          usnat: {
+            KnownChildSensitiveDataConsents: [1]
+          }
+        }
+      });
+
+      // Even with empty consentData, handler provides privacy signal
+      const result = locIdSubmodule.getId(config, {});
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should proceed when uspDataHandler returns non-restrictive value', () => {
+      // Restore and re-stub to return non-restrictive USP
+      uspDataHandler.getConsentData.restore();
+      sandbox.stub(uspDataHandler, 'getConsentData').returns('1NN-');
+
+      const result = locIdSubmodule.getId(config, {});
+      expect(result).to.have.property('callback');
+    });
+
+    // --- Tests for gdprApplies edge cases (LI-based operation) ---
+    // gdprApplies alone does NOT constitute a privacy signal.
+    // A GDPR signal requires actual CMP artifacts (consentString or vendorData).
+
+    it('should proceed when gdprApplies=true but no consentString/vendorData (default LI mode)', () => {
+      // gdprApplies alone is not a signal - allows LI-based operation without CMP
+      const consentData = {
+        gdprApplies: true
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when gdprApplies=true and usp is present but no GDPR CMP artifacts', () => {
+      const consentData = {
+        gdprApplies: true,
+        usp: '1NN-'
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when gdprApplies=true and consentString is empty (treated as absent CMP artifact)', () => {
+      // Empty consentString is treated as not present, so LI-mode behavior applies.
+      const consentData = {
+        gdprApplies: true,
+        consentString: ''
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should return undefined when gdprApplies=true, no CMP artifacts, and strict mode', () => {
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          requirePrivacySignals: true
+        }
+      };
+      const consentData = {
+        gdprApplies: true
+      };
+      const result = locIdSubmodule.getId(strictConfig, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined when gdprApplies=true, vendorData present but no consentString', () => {
+      // vendorData presence = CMP is present, so signals ARE present
+      // GDPR applies + signals present + no consentString → deny
+      const consentData = {
+        gdprApplies: true,
+        vendorData: {
+          vendor: {}
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should deny when gdprApplies=false and strict mode is enabled (gdprApplies alone is not a signal)', () => {
+      // gdprApplies=false alone is not a signal, so strict mode blocks
+      const strictConfig = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          requirePrivacySignals: true
+        }
+      };
+      const consentData = {
+        gdprApplies: false
+      };
+      const result = locIdSubmodule.getId(strictConfig, consentData);
+      // gdprApplies=false is not a signal, so strict mode denies
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    // --- Original tests for when privacy signals ARE present ---
+
+    it('should proceed with valid GDPR framework data', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string'
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR does not apply (no CMP artifacts)', () => {
+      // gdprApplies=false alone is not a signal - LI operation allowed
+      const consentData = {
+        gdprApplies: false
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR applies with consentString and vendor flags deny', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: { 999: false },
+            legitimateInterests: { 999: false }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should return undefined on US Privacy processing restriction and not call ajax', () => {
+      const consentData = {
+        usp: '1YY-'
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined on legacy US Privacy processing restriction and not call ajax', () => {
+      const consentData = {
+        uspConsent: '1YY-'
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined on GPP processing restriction and not call ajax', () => {
+      const consentData = {
+        gpp: {
+          applicableSections: [7],
+          parsedSections: {
+            usnat: {
+              KnownChildSensitiveDataConsents: [1]
+            }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should return undefined on legacy GPP processing restriction and not call ajax', () => {
+      const consentData = {
+        gppConsent: {
+          applicableSections: [7],
+          parsedSections: {
+            usnat: {
+              KnownChildSensitiveDataConsents: [1]
+            }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.be.undefined;
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should proceed when nested GDPR applies but no CMP artifacts (LI operation)', () => {
+      // Empty consentString in nested gdpr object is not a signal - LI operation allowed
+      const consentData = {
+        gdpr: {
+          gdprApplies: true,
+          consentString: ''
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed with valid nested GDPR framework data', () => {
+      const consentData = {
+        gdpr: {
+          gdprApplies: true,
+          consentString: 'valid-consent-string'
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR applies and vendorData is present', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: { 999: false },
+            legitimateInterests: { 999: false }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR applies and vendor is missing from consents', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: { 1234: true },
+            legitimateInterests: { 1234: true }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR applies and vendor consents object is present', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: { 999: true }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when GDPR applies and vendor legitimate interests object is present', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: { 999: false },
+            legitimateInterests: { 999: true }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when vendorData is not available (cannot determine vendor permission)', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string'
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should check nested vendorData when using gdpr object shape', () => {
+      const consentData = {
+        gdpr: {
+          gdprApplies: true,
+          consentString: 'valid-consent-string',
+          vendorData: {
+            vendor: {
+              consents: { 999: true }
+            }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when nested vendorData has explicit deny flags', () => {
+      const consentData = {
+        gdpr: {
+          gdprApplies: true,
+          consentString: 'valid-consent-string',
+          vendorData: {
+            vendor: {
+              consents: { 999: false },
+              legitimateInterests: {}
+            }
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when vendor consents is a function returning true', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: (id) => id === 999,
+            legitimateInterests: {}
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when vendor legitimateInterests is a function returning true', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: (id) => false,
+            legitimateInterests: (id) => id === 999
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+
+    it('should proceed when vendor consent callbacks both return false', () => {
+      const consentData = {
+        gdprApplies: true,
+        consentString: 'valid-consent-string',
+        vendorData: {
+          vendor: {
+            consents: (id) => false,
+            legitimateInterests: (id) => false
+          }
+        }
+      };
+      const result = locIdSubmodule.getId(config, consentData);
+      expect(result).to.have.property('callback');
+    });
+  });
+
+  describe('response parsing', () => {
+    it('should parse JSON string response', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success('{"tx_cloc":"parsed-id","connection_ip":"203.0.113.42"}');
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.equal('parsed-id');
+        expect(id.connectionIp).to.equal('203.0.113.42');
+        done();
+      });
+    });
+
+    it('should return undefined when connection_ip is missing', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.undefined;
+        done();
+      });
+    });
+
+    it('should return undefined for invalid JSON', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success('not valid json');
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.undefined;
+        done();
+      });
+    });
+
+    it('should cache entry with null id when tx_cloc is empty string', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: '', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.be.null;
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should cache entry with null id when tx_cloc is whitespace-only', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ tx_cloc: '   \n\t  ', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.be.null;
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should return undefined when tx_cloc is missing', (done) => {
+      ajaxStub.callsFake((url, callbacks, body, options) => {
+        callbacks.success(JSON.stringify({ other_field: 'value' }));
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT
+        }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.undefined;
+        done();
+      });
+    });
+  });
+
+  describe('empty tx_cloc handling', () => {
+    it('should decode null id as undefined (no EID emitted)', () => {
+      const result = locIdSubmodule.decode({ id: null, connectionIp: TEST_CONNECTION_IP });
+      expect(result).to.be.undefined;
+    });
+
+    it('should cache empty tx_cloc response for the full cache period', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { expires: 7 }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.be.null;
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        expect(id.expiresAt).to.be.a('number');
+        expect(id.expiresAt).to.be.greaterThan(Date.now());
+        done();
+      });
+    });
+
+    it('should reuse cached entry with null id on subsequent getId calls', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: null,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should not produce EID when tx_cloc is null', () => {
+      const decoded = locIdSubmodule.decode({ id: null, connectionIp: TEST_CONNECTION_IP });
+      expect(decoded).to.be.undefined;
+    });
+
+    it('should write IP cache when endpoint returns empty tx_cloc', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        expect(storage.setDataInLocalStorage.called).to.be.true;
+        const callArgs = storage.setDataInLocalStorage.getCall(0).args;
+        expect(callArgs[0]).to.equal('_locid_ip');
+        const ipEntry = JSON.parse(callArgs[1]);
+        expect(ipEntry.ip).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+  });
+
+  describe('IP cache management', () => {
+    const ipCacheConfig = {
+      params: { endpoint: TEST_ENDPOINT },
+      storage: { name: '_locid' }
+    };
+
+    it('should read valid IP cache entry', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      // If IP cache is valid and stored entry matches, should reuse
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.getId(ipCacheConfig, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+      expect(ajaxStub.called).to.be.false;
+    });
+
+    it('should treat expired IP cache as missing', (done) => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now() - 20000,
+        expiresAt: Date.now() - 1000
+      }));
+
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.getId(ipCacheConfig, {}, storedId);
+      // Expired IP cache → calls main endpoint
+      expect(result).to.have.property('callback');
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        done();
+      });
+    });
+
+    it('should handle corrupted IP cache JSON gracefully', (done) => {
+      storage.getDataFromLocalStorage.returns('not-valid-json');
+
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const result = locIdSubmodule.getId(ipCacheConfig, {});
+      expect(result).to.have.property('callback');
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+
+    it('should derive IP cache key from storage name', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: 'custom_key' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        const setCall = storage.setDataInLocalStorage.getCall(0);
+        expect(setCall.args[0]).to.equal('custom_key_ip');
+        done();
+      });
+    });
+
+    it('should use custom ipCacheName when configured', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT, ipCacheName: 'my_ip_cache' },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        const setCall = storage.setDataInLocalStorage.getCall(0);
+        expect(setCall.args[0]).to.equal('my_ip_cache');
+        done();
+      });
+    });
+
+    it('should use custom ipCacheTtlMs when configured', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT, ipCacheTtlMs: 7200000 },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback(() => {
+        const setCall = storage.setDataInLocalStorage.getCall(0);
+        const ipEntry = JSON.parse(setCall.args[1]);
+        // TTL should be ~2 hours
+        const ttl = ipEntry.expiresAt - ipEntry.fetchedAt;
+        expect(ttl).to.equal(7200000);
+        done();
+      });
+    });
+
+    it('should write IP cache on every successful main endpoint response', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: '10.0.0.1' }));
+      });
+
+      const result = locIdSubmodule.getId(ipCacheConfig, {});
+      result.callback(() => {
+        expect(storage.setDataInLocalStorage.called).to.be.true;
+        const ipEntry = JSON.parse(storage.setDataInLocalStorage.getCall(0).args[1]);
+        expect(ipEntry.ip).to.equal('10.0.0.1');
+        done();
+      });
+    });
+  });
+
+  describe('getId with ipEndpoint (two-call optimization)', () => {
+    it('should call ipEndpoint first when IP cache is expired', (done) => {
+      let callCount = 0;
+      ajaxStub.callsFake((url, callbacks) => {
+        callCount++;
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success(JSON.stringify({ ip: '10.0.0.1' }));
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: '10.0.0.1' }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        // IP changed (no stored entry) → 2 calls: ipEndpoint + main endpoint
+        expect(callCount).to.equal(2);
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+
+    it('should reuse cached tx_cloc when ipEndpoint returns same IP', (done) => {
+      let callCount = 0;
+      ajaxStub.callsFake((url, callbacks) => {
+        callCount++;
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success(JSON.stringify({ ip: TEST_CONNECTION_IP }));
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: 'new-id', connection_ip: TEST_CONNECTION_IP }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // IP unchanged → only 1 call (ipEndpoint), reuses stored tx_cloc
+        expect(callCount).to.equal(1);
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+
+    it('should call main endpoint when ipEndpoint returns different IP', (done) => {
+      let callCount = 0;
+      ajaxStub.callsFake((url, callbacks) => {
+        callCount++;
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success(JSON.stringify({ ip: '10.0.0.99' }));
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: 'new-id', connection_ip: '10.0.0.99' }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // IP changed → 2 calls: ipEndpoint + main endpoint
+        expect(callCount).to.equal(2);
+        expect(id.id).to.equal('new-id');
+        done();
+      });
+    });
+
+    it('should fall back to main endpoint when ipEndpoint fails', (done) => {
+      let callCount = 0;
+      ajaxStub.callsFake((url, callbacks) => {
+        callCount++;
+        if (url === 'https://ip.example.com/check') {
+          callbacks.error('Network error');
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(callCount).to.equal(2);
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+
+    it('should fall back to main endpoint when ipEndpoint returns invalid IP', (done) => {
+      let callCount = 0;
+      ajaxStub.callsFake((url, callbacks) => {
+        callCount++;
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success('not-an-ip!!!');
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(callCount).to.equal(2);
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+
+    it('should pass apiKey header to ipEndpoint when configured', (done) => {
+      ajaxStub.callsFake((url, callbacks, _body, options) => {
+        if (url === 'https://ip.example.com/check') {
+          expect(options.customHeaders).to.deep.equal({ 'x-api-key': 'test-key-123' });
+          callbacks.success(JSON.stringify({ ip: TEST_CONNECTION_IP }));
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check',
+          apiKey: 'test-key-123'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        done();
+      });
+    });
+
+    it('should parse plain text IP from ipEndpoint', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success(TEST_CONNECTION_IP);
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: 'new-id', connection_ip: TEST_CONNECTION_IP }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // IP same → reuses stored tx_cloc
+        expect(id.id).to.equal(TEST_ID);
+        done();
+      });
+    });
+  });
+
+  describe('getId tx_cloc preservation (no churn)', () => {
+    it('should preserve existing tx_cloc when main endpoint returns same IP', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // IP unchanged → preserve existing tx_cloc (don't churn)
+        expect(id.id).to.equal(TEST_ID);
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should use fresh non-null tx_cloc when stored entry is null for same IP', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: null,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        expect(id.id).to.equal('fresh-id');
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should use fresh tx_cloc when main endpoint returns different IP', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: '10.0.0.99' }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // IP changed → use fresh tx_cloc
+        expect(id.id).to.equal('fresh-id');
+        expect(id.connectionIp).to.equal('10.0.0.99');
+        done();
+      });
+    });
+
+    it('should use fresh tx_cloc when stored entry is expired even if IP matches', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now() - 86400000,
+        expiresAt: Date.now() - 1000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // tx_cloc expired → use fresh even though IP matches
+        expect(id.id).to.equal('fresh-id');
+        done();
+      });
+    });
+
+    it('should honor null tx_cloc from main endpoint even when stored entry is reusable', (done) => {
+      // Server returns connection_ip but no tx_cloc → freshEntry.id === null.
+      // The stored entry has a valid tx_cloc for the same IP, but the server
+      // now indicates no ID for this IP. The null response must be honored.
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      result.callback((id) => {
+        // Server said no tx_cloc → stored entry must NOT be preserved
+        expect(id.id).to.be.null;
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should use fresh entry on first load (no stored entry)', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: TEST_CONNECTION_IP }));
+      });
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id.id).to.equal(TEST_ID);
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+  });
+
+  describe('extendId with null id and IP cache', () => {
+    const config = {
+      params: { endpoint: TEST_ENDPOINT },
+      storage: { name: '_locid' }
+    };
+
+    it('should accept stored entry with null id (empty tx_cloc)', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 14400000
+      }));
+      const storedId = {
+        id: null,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+    });
+
+    it('should return refresh callback when IP cache shows different IP', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: '10.0.0.99' }));
+      });
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: '10.0.0.99',
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.have.property('callback');
+      result.callback((id) => {
+        expect(id.id).to.equal('fresh-id');
+        expect(id.connectionIp).to.equal('10.0.0.99');
+        done();
+      });
+    });
+
+    it('should extend when IP cache matches stored entry IP', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+    });
+
+    it('should return refresh callback when IP cache is missing', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: TEST_CONNECTION_IP }));
+      });
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.have.property('callback');
+      result.callback((id) => {
+        expect(id.id).to.equal('fresh-id');
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should return refresh callback when IP cache is expired', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        callbacks.success(JSON.stringify({ tx_cloc: 'fresh-id', connection_ip: TEST_CONNECTION_IP }));
+      });
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now() - 14400000,
+        expiresAt: Date.now() - 1000
+      }));
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.have.property('callback');
+      result.callback((id) => {
+        expect(id.id).to.equal('fresh-id');
+        expect(id.connectionIp).to.equal(TEST_CONNECTION_IP);
+        done();
+      });
+    });
+
+    it('should return undefined for undefined id (not null, not valid string)', () => {
+      const storedId = {
+        id: undefined,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.extendId(config, {}, storedId);
+      expect(result).to.be.undefined;
+    });
+  });
+
+  describe('normalizeStoredId with null id', () => {
+    it('should preserve explicit null id', () => {
+      // getId is the public interface; test via decode which uses normalized values
+      const stored = { id: null, connectionIp: TEST_CONNECTION_IP };
+      // decode returns undefined for null id (correct: no EID emitted)
+      const decoded = locIdSubmodule.decode(stored);
+      expect(decoded).to.be.undefined;
+    });
+
+    it('should preserve valid string id', () => {
+      const stored = { id: TEST_ID, connectionIp: TEST_CONNECTION_IP };
+      const decoded = locIdSubmodule.decode(stored);
+      expect(decoded).to.deep.equal({ locId: TEST_ID });
+    });
+
+    it('should fall back to tx_cloc when id key is absent', () => {
+      const stored = { tx_cloc: TEST_ID, connectionIp: TEST_CONNECTION_IP };
+      const decoded = locIdSubmodule.decode(stored);
+      expect(decoded).to.deep.equal({ locId: TEST_ID });
+    });
+
+    it('should handle connection_ip alias', () => {
+      const stored = { id: TEST_ID, connection_ip: TEST_CONNECTION_IP };
+      const decoded = locIdSubmodule.decode(stored);
+      expect(decoded).to.deep.equal({ locId: TEST_ID });
+    });
+  });
+
+  describe('parseIpResponse via ipEndpoint', () => {
+    it('should parse JSON with ip field', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success('{"ip":"1.2.3.4"}');
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: '1.2.3.4' }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        // IP fetched and used
+        expect(id).to.be.an('object');
+        done();
+      });
+    });
+
+    it('should parse JSON with connection_ip field', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success('{"connection_ip":"1.2.3.4"}');
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: '1.2.3.4' }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        done();
+      });
+    });
+
+    it('should parse plain text IP address', (done) => {
+      ajaxStub.callsFake((url, callbacks) => {
+        if (url === 'https://ip.example.com/check') {
+          callbacks.success('1.2.3.4\n');
+        } else {
+          callbacks.success(JSON.stringify({ tx_cloc: TEST_ID, connection_ip: '1.2.3.4' }));
+        }
+      });
+
+      const config = {
+        params: {
+          endpoint: TEST_ENDPOINT,
+          ipEndpoint: 'https://ip.example.com/check'
+        },
+        storage: { name: '_locid' }
+      };
+
+      const result = locIdSubmodule.getId(config, {});
+      result.callback((id) => {
+        expect(id).to.be.an('object');
+        done();
+      });
+    });
+  });
+
+  describe('backward compatibility', () => {
+    it('should work with existing stored entries that have string ids', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result).to.deep.equal({ id: storedId });
+    });
+
+    it('should work with stored entries using connection_ip alias', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        id: TEST_ID,
+        connection_ip: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result.id.connectionIp).to.equal(TEST_CONNECTION_IP);
+    });
+
+    it('should work with stored entries using tx_cloc alias', () => {
+      storage.getDataFromLocalStorage.returns(JSON.stringify({
+        ip: TEST_CONNECTION_IP,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + 1000
+      }));
+
+      const config = {
+        params: { endpoint: TEST_ENDPOINT },
+        storage: { name: '_locid' }
+      };
+      const storedId = {
+        tx_cloc: TEST_ID,
+        connectionIp: TEST_CONNECTION_IP,
+        createdAt: Date.now(),
+        expiresAt: Date.now() + 86400000
+      };
+      const result = locIdSubmodule.getId(config, {}, storedId);
+      expect(result.id.id).to.equal(TEST_ID);
+    });
+  });
+
+  describe('EID round-trip integration', () => {
+    before(() => {
+      attachIdSystem(locIdSubmodule);
+    });
+
+    it('should produce a valid EID from decode output via createEidsArray', () => {
+      // Simulate the full Prebid pipeline:
+      // 1. decode() returns { locId: "string" }
+      // 2. Prebid extracts idObj["locId"] -> the string
+      // 3. createEidsArray({ locId: "string" }) should produce a valid EID
+      const stored = { id: TEST_ID, connectionIp: TEST_CONNECTION_IP };
+      const decoded = locIdSubmodule.decode(stored);
+      expect(decoded).to.deep.equal({ locId: TEST_ID });
+
+      const eids = createEidsArray(decoded);
+      expect(eids.length).to.equal(1);
+      expect(eids[0]).to.deep.equal({
+        source: 'locid.com',
+        uids: [{ id: TEST_ID, atype: 1 }]
+      });
+      expect(eids[0].uids[0].atype).to.not.equal(Number('33' + '84'));
+    });
+
+    it('should not produce EID when decode returns undefined', () => {
+      const decoded = locIdSubmodule.decode(null);
+      expect(decoded).to.be.undefined;
+    });
+
+    it('should not produce EID when only stable_cloc is present', () => {
+      const decoded = locIdSubmodule.decode({
+        stable_cloc: 'stable-only-value',
+        connectionIp: TEST_CONNECTION_IP
+      });
+      expect(decoded).to.be.undefined;
+
+      const eids = createEidsArray({ locId: decoded?.locId });
+      expect(eids).to.deep.equal([]);
+    });
+
+    it('should not produce EID when tx_cloc is null', () => {
+      const decoded = locIdSubmodule.decode({ id: null, connectionIp: TEST_CONNECTION_IP });
+      expect(decoded).to.be.undefined;
+
+      const eids = createEidsArray({ locId: decoded?.locId });
+      expect(eids).to.deep.equal([]);
+    });
+
+    it('should not produce EID when tx_cloc is missing', () => {
+      const decoded = locIdSubmodule.decode({ connectionIp: TEST_CONNECTION_IP });
+      expect(decoded).to.be.undefined;
+
+      const eids = createEidsArray({ locId: decoded?.locId });
+      expect(eids).to.deep.equal([]);
+    });
+  });
+});