@frontmcp/utils 1.8.0 → 1.8.2

package/content/content.d.ts

@@ -14,7 +14,7 @@
  * - Error → { name, message, stack }
  * - Map → plain object
  * - Set → array
- * - Circular references → dropped (undefined)
+ * - Circular references → dropped (undefined); a value referenced more than once without a cycle is kept each time
  *
  * @param value - Any JavaScript value
  * @returns JSON-safe version of the value

package/env/browser-env.js

@@ -32,6 +32,23 @@ __export(browser_env_exports, {
   supportsAnsi: () => supportsAnsi
 });
 module.exports = __toCommonJS(browser_env_exports);
+
+// libs/utils/src/env/edge-scope.ts
+function hasEdgeGlobalScope() {
+  if (typeof globalThis === "undefined") return false;
+  if ("EdgeRuntime" in globalThis) return true;
+  if (!("caches" in globalThis) || "window" in globalThis) return false;
+  return !isBrowserWorkerScope();
+}
+function isBrowserWorkerScope() {
+  const userAgent = typeof navigator === "undefined" ? void 0 : navigator.userAgent;
+  if (userAgent === void 0 || userAgent === "Cloudflare-Workers") return false;
+  return ["DedicatedWorkerGlobalScope", "SharedWorkerGlobalScope", "ServiceWorkerGlobalScope"].some(
+    (scopeName) => scopeName in globalThis
+  );
+}
+
+// libs/utils/src/env/browser-env.ts
 function getEnv(_key, defaultValue) {
   return defaultValue;
 }
@@ -53,9 +70,7 @@ function isDebug() {
 function setEnv(_key, _value) {
 }
 function isEdgeRuntime() {
-  if (typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis) return true;
-  if (typeof globalThis !== "undefined" && "caches" in globalThis && !("window" in globalThis)) return true;
-  return false;
+  return hasEdgeGlobalScope();
 }
 function isServerless() {
   return false;

package/env/edge-scope.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the global scope looks like an edge runtime (Cloudflare Workers, Vercel Edge, Deno Deploy):
+ * `EdgeRuntime` is defined, or `caches` is present without `window`. A browser Web Worker also has
+ * `caches` and no `window`, and defines its dedicated, shared or service worker scope. Cloudflare's workerd
+ * defines `ServiceWorkerGlobalScope` too, so it is told apart by its user agent, or by having no `navigator`.
+ */
+export declare function hasEdgeGlobalScope(): boolean;

package/env/node-env.js

@@ -32,6 +32,23 @@ __export(node_env_exports, {
   supportsAnsi: () => supportsAnsi
 });
 module.exports = __toCommonJS(node_env_exports);
+
+// libs/utils/src/env/edge-scope.ts
+function hasEdgeGlobalScope() {
+  if (typeof globalThis === "undefined") return false;
+  if ("EdgeRuntime" in globalThis) return true;
+  if (!("caches" in globalThis) || "window" in globalThis) return false;
+  return !isBrowserWorkerScope();
+}
+function isBrowserWorkerScope() {
+  const userAgent = typeof navigator === "undefined" ? void 0 : navigator.userAgent;
+  if (userAgent === void 0 || userAgent === "Cloudflare-Workers") return false;
+  return ["DedicatedWorkerGlobalScope", "SharedWorkerGlobalScope", "ServiceWorkerGlobalScope"].some(
+    (scopeName) => scopeName in globalThis
+  );
+}
+
+// libs/utils/src/env/node-env.ts
 function getEnv(key, defaultValue) {
   return process.env[key] ?? defaultValue;
 }
@@ -55,8 +72,7 @@ function setEnv(key, value) {
   process.env[key] = value;
 }
 function isEdgeRuntime() {
-  if (typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis) return true;
-  if (typeof globalThis !== "undefined" && "caches" in globalThis && !("window" in globalThis)) return true;
+  if (hasEdgeGlobalScope()) return true;
   return process.env["EDGE_RUNTIME"] !== void 0 && process.env["VERCEL_ENV"] !== void 0;
 }
 function isServerless() {

package/esm/env/browser-env.mjs

@@ -1,5 +1,20 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
 const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
+// libs/utils/src/env/edge-scope.ts
+function hasEdgeGlobalScope() {
+  if (typeof globalThis === "undefined") return false;
+  if ("EdgeRuntime" in globalThis) return true;
+  if (!("caches" in globalThis) || "window" in globalThis) return false;
+  return !isBrowserWorkerScope();
+}
+function isBrowserWorkerScope() {
+  const userAgent = typeof navigator === "undefined" ? void 0 : navigator.userAgent;
+  if (userAgent === void 0 || userAgent === "Cloudflare-Workers") return false;
+  return ["DedicatedWorkerGlobalScope", "SharedWorkerGlobalScope", "ServiceWorkerGlobalScope"].some(
+    (scopeName) => scopeName in globalThis
+  );
+}
+
 // libs/utils/src/env/browser-env.ts
 function getEnv(_key, defaultValue) {
   return defaultValue;
@@ -22,9 +37,7 @@ function isDebug() {
 function setEnv(_key, _value) {
 }
 function isEdgeRuntime() {
-  if (typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis) return true;
-  if (typeof globalThis !== "undefined" && "caches" in globalThis && !("window" in globalThis)) return true;
-  return false;
+  return hasEdgeGlobalScope();
 }
 function isServerless() {
   return false;

package/esm/env/node-env.mjs

@@ -1,5 +1,20 @@
 import { createRequire as __frontmcpCreateRequire } from 'module';
 const require = __frontmcpCreateRequire(import.meta.url || 'file:///');
+// libs/utils/src/env/edge-scope.ts
+function hasEdgeGlobalScope() {
+  if (typeof globalThis === "undefined") return false;
+  if ("EdgeRuntime" in globalThis) return true;
+  if (!("caches" in globalThis) || "window" in globalThis) return false;
+  return !isBrowserWorkerScope();
+}
+function isBrowserWorkerScope() {
+  const userAgent = typeof navigator === "undefined" ? void 0 : navigator.userAgent;
+  if (userAgent === void 0 || userAgent === "Cloudflare-Workers") return false;
+  return ["DedicatedWorkerGlobalScope", "SharedWorkerGlobalScope", "ServiceWorkerGlobalScope"].some(
+    (scopeName) => scopeName in globalThis
+  );
+}
+
 // libs/utils/src/env/node-env.ts
 function getEnv(key, defaultValue) {
   return process.env[key] ?? defaultValue;
@@ -24,8 +39,7 @@ function setEnv(key, value) {
   process.env[key] = value;
 }
 function isEdgeRuntime() {
-  if (typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis) return true;
-  if (typeof globalThis !== "undefined" && "caches" in globalThis && !("window" in globalThis)) return true;
+  if (hasEdgeGlobalScope()) return true;
   return process.env["EDGE_RUNTIME"] !== void 0 && process.env["VERCEL_ENV"] !== void 0;
 }
 function isServerless() {

package/esm/index.mjs

@@ -4378,7 +4378,18 @@ import { pathToFileURL } from "url";
 
 // libs/utils/src/content/content.ts
 function sanitizeToJson(value) {
-  const seen = /* @__PURE__ */ new WeakSet();
+  const ancestors = /* @__PURE__ */ new WeakSet();
+  function withinAncestors(container, build) {
+    if (ancestors.has(container)) {
+      return void 0;
+    }
+    ancestors.add(container);
+    try {
+      return build();
+    } finally {
+      ancestors.delete(container);
+    }
+  }
   function sanitize(val) {
     if (typeof val === "function" || typeof val === "symbol") {
       return void 0;
@@ -4397,35 +4408,31 @@ function sanitizeToJson(value) {
       };
     }
     if (val instanceof Map) {
-      const obj = {};
-      for (const [k, v] of val.entries()) {
-        obj[String(k)] = sanitize(v);
-      }
-      return obj;
+      return withinAncestors(val, () => {
+        const obj = {};
+        for (const [k, v] of val.entries()) {
+          obj[String(k)] = sanitize(v);
+        }
+        return obj;
+      });
     }
     if (val instanceof Set) {
-      return Array.from(val).map(sanitize);
+      return withinAncestors(val, () => Array.from(val).map(sanitize));
     }
     if (Array.isArray(val)) {
-      if (seen.has(val)) {
-        return void 0;
-      }
-      seen.add(val);
-      return val.map(sanitize);
+      return withinAncestors(val, () => val.map(sanitize));
     }
     if (val && typeof val === "object") {
-      if (seen.has(val)) {
-        return void 0;
-      }
-      seen.add(val);
-      const sanitized = {};
-      for (const [key, value2] of Object.entries(val)) {
-        const clean = sanitize(value2);
-        if (clean !== void 0) {
-          sanitized[key] = clean;
+      return withinAncestors(val, () => {
+        const sanitized = {};
+        for (const [key, value2] of Object.entries(val)) {
+          const clean = sanitize(value2);
+          if (clean !== void 0) {
+            sanitized[key] = clean;
+          }
         }
-      }
-      return sanitized;
+        return sanitized;
+      });
     }
     return val;
   }
@@ -4587,6 +4594,134 @@ function getCookie(cookieHeader, name) {
   return parseCookies(cookieHeader)[name];
 }
 
+// libs/utils/src/net/ip-address.ts
+var IPV4_OCTET_PATTERN = /^(0|[1-9]\d{0,2})$/;
+var IPV6_GROUP_PATTERN = /^[0-9a-f]{1,4}$/;
+var IPV4_BLOCKS = compileBlocks(
+  [
+    ["0.0.0.0/8", "this-network"],
+    ["10.0.0.0/8", "private"],
+    ["100.64.0.0/10", "carrier-grade-nat"],
+    ["127.0.0.0/8", "loopback"],
+    ["169.254.0.0/16", "link-local"],
+    ["172.16.0.0/12", "private"],
+    ["192.0.0.0/24", "ietf-protocol"],
+    ["192.168.0.0/16", "private"],
+    ["198.18.0.0/15", "benchmarking"],
+    ["224.0.0.0/4", "multicast"],
+    ["255.255.255.255/32", "reserved"],
+    ["240.0.0.0/4", "reserved"]
+  ],
+  parseIpv4
+);
+var IPV6_BLOCKS = compileBlocks(
+  [
+    ["::/128", "unspecified"],
+    ["::1/128", "loopback"],
+    ["fd00:ec2::254/128", "cloud-metadata"],
+    ["fc00::/7", "private"],
+    ["fe80::/10", "link-local"],
+    ["fec0::/10", "site-local"],
+    // RFC 8215 local-use NAT64: where the IPv4 address sits depends on the operator's prefix length.
+    ["64:ff9b:1::/48", "local-use-nat64"],
+    ["ff00::/8", "multicast"]
+  ],
+  expandIpv6
+);
+var IPV4_EMBEDDINGS = compileBlocks(
+  [
+    ["::ffff:0:0/96", 6],
+    ["::ffff:0:0:0/96", 6],
+    ["::/96", 6],
+    ["64:ff9b::/96", 6],
+    ["2002::/16", 1]
+  ],
+  expandIpv6
+);
+function parseIpv4(address) {
+  const parts = address.split(".");
+  if (parts.length !== 4 || !parts.every((part) => IPV4_OCTET_PATTERN.test(part))) return void 0;
+  const octets = parts.map(Number);
+  return octets.every((octet) => octet <= 255) ? octets : void 0;
+}
+function expandIpv6(address) {
+  const zoneIndex = address.indexOf("%");
+  let text = (zoneIndex === -1 ? address : address.slice(0, zoneIndex)).toLowerCase();
+  const lastColonIndex = text.lastIndexOf(":");
+  const trailingSegment = text.slice(lastColonIndex + 1);
+  if (lastColonIndex !== -1 && trailingSegment.includes(".")) {
+    const octets = parseIpv4(trailingSegment);
+    if (!octets) return void 0;
+    const highGroup = (octets[0] << 8 | octets[1]).toString(16);
+    const lowGroup = (octets[2] << 8 | octets[3]).toString(16);
+    text = `${text.slice(0, lastColonIndex + 1)}${highGroup}:${lowGroup}`;
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return void 0;
+  const head = parseIpv6Groups(halves[0]);
+  if (!head) return void 0;
+  if (halves.length === 1) return head.length === 8 ? head : void 0;
+  const tail = parseIpv6Groups(halves[1]);
+  if (!tail || head.length + tail.length > 7) return void 0;
+  return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+}
+function extractEmbeddedIpv4(groups) {
+  const octets = findEmbeddedIpv4Octets(groups);
+  return octets ? octets.join(".") : void 0;
+}
+function classifyIpAddress(address) {
+  const isBracketed = address.startsWith("[") && address.endsWith("]");
+  const octets = isBracketed ? void 0 : parseIpv4(address);
+  if (octets) return classifyIpv4(octets);
+  const groups = expandIpv6(isBracketed ? address.slice(1, -1) : address);
+  if (!groups) return void 0;
+  const block = IPV6_BLOCKS.find((candidate) => matchesBlock(groups, candidate, 16));
+  if (block) return { family: 6, range: block.value, cidr: block.cidr };
+  const embeddedOctets = findEmbeddedIpv4Octets(groups);
+  if (!embeddedOctets) return { family: 6, range: "public" };
+  return { ...classifyIpv4(embeddedOctets), family: 6, embeddedIpv4: embeddedOctets.join(".") };
+}
+function classifyIpv4(octets) {
+  const block = IPV4_BLOCKS.find((candidate) => matchesBlock(octets, candidate, 8));
+  return block ? { family: 4, range: block.value, cidr: block.cidr } : { family: 4, range: "public" };
+}
+function findEmbeddedIpv4Octets(groups) {
+  const embedding = IPV4_EMBEDDINGS.find((block) => matchesBlock(groups, block, 16));
+  if (!embedding) return void 0;
+  const highGroup = groups[embedding.value];
+  const lowGroup = groups[embedding.value + 1];
+  return [highGroup >> 8, highGroup & 255, lowGroup >> 8, lowGroup & 255];
+}
+function parseIpv6Groups(part) {
+  if (part === "") return [];
+  const groups = part.split(":");
+  if (!groups.every((group) => IPV6_GROUP_PATTERN.test(group))) return void 0;
+  return groups.map((group) => parseInt(group, 16));
+}
+function matchesBlock(words, block, bitsPerWord) {
+  let remainingBits = block.prefixLength;
+  for (let index = 0; remainingBits > 0; index++) {
+    const comparedBits = Math.min(bitsPerWord, remainingBits);
+    const ignoredBits = bitsPerWord - comparedBits;
+    if (words[index] >> ignoredBits !== block.network[index] >> ignoredBits) return false;
+    remainingBits -= comparedBits;
+  }
+  return true;
+}
+function compileBlocks(entries, parseNetwork) {
+  return entries.map(([cidr, value]) => {
+    const [networkText, prefixText] = cidr.split("/");
+    const network = parseNetwork(networkText);
+    if (!network) throw new Error(`Invalid network in address block "${cidr}"`);
+    return { cidr, network, prefixLength: Number(prefixText), value };
+  });
+}
+
+// libs/utils/src/net/redirect.ts
+function isRedirectResponse(response) {
+  return response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+}
+
 // libs/utils/src/index.ts
 init_fs2();
 
@@ -5776,6 +5911,7 @@ export {
   buildSetCookie,
   bytesToHex,
   checkEntryAvailability,
+  classifyIpAddress,
   clearCachedSecret,
   collapseChar,
   collapseWhitespace,
@@ -5808,11 +5944,13 @@ export {
   escapeHtmlAttr,
   escapeJsString,
   escapeScriptClose,
+  expandIpv6,
   expandTemplate,
   expandUriTemplate,
   expiresAtToTTL,
   extname,
   extractBracedParams,
+  extractEmbeddedIpv4,
   extractTemplateParams,
   extractUriScheme,
   fileExists,
@@ -5852,6 +5990,7 @@ export {
   isNode,
   isPatternSafe,
   isProduction,
+  isRedirectResponse,
   isRsaPssAlg,
   isSecretCached,
   isSecretKeyData,
@@ -5874,6 +6013,7 @@ export {
   mkdtemp,
   normalizeTTL,
   parseCookies,
+  parseIpv4,
   parseKeyData,
   parseSecretData,
   parseUriTemplate,

package/index.d.ts

@@ -13,6 +13,8 @@ export { trimSlashes, joinPath, pathResolve, pathJoin, basename, dirname, extnam
 export { sanitizeToJson, inferMimeType, findNonFiniteNumber } from './content';
 export { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost, isSecureRequest } from './http';
 export type { CookieOptions, SecureDetectionRequest } from './http';
+export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4, isRedirectResponse } from './net';
+export type { IpAddressClassification, IpAddressRange, SpecialPurposeIpRange, RedirectCandidate } from './net';
 export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
 export type { FileWatcherHandle } from './fs';
 export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';

package/index.js

@@ -4022,6 +4022,7 @@ __export(index_exports, {
   buildSetCookie: () => buildSetCookie,
   bytesToHex: () => bytesToHex,
   checkEntryAvailability: () => checkEntryAvailability,
+  classifyIpAddress: () => classifyIpAddress,
   clearCachedSecret: () => clearCachedSecret,
   collapseChar: () => collapseChar,
   collapseWhitespace: () => collapseWhitespace,
@@ -4054,11 +4055,13 @@ __export(index_exports, {
   escapeHtmlAttr: () => escapeHtmlAttr,
   escapeJsString: () => escapeJsString,
   escapeScriptClose: () => escapeScriptClose,
+  expandIpv6: () => expandIpv6,
   expandTemplate: () => expandTemplate,
   expandUriTemplate: () => expandUriTemplate,
   expiresAtToTTL: () => expiresAtToTTL,
   extname: () => import_path.extname,
   extractBracedParams: () => extractBracedParams,
+  extractEmbeddedIpv4: () => extractEmbeddedIpv4,
   extractTemplateParams: () => extractTemplateParams,
   extractUriScheme: () => extractUriScheme,
   fileExists: () => fileExists,
@@ -4098,6 +4101,7 @@ __export(index_exports, {
   isNode: () => isNode,
   isPatternSafe: () => isPatternSafe,
   isProduction: () => import_env3.isProduction,
+  isRedirectResponse: () => isRedirectResponse,
   isRsaPssAlg: () => isRsaPssAlg,
   isSecretCached: () => isSecretCached,
   isSecretKeyData: () => isSecretKeyData,
@@ -4120,6 +4124,7 @@ __export(index_exports, {
   mkdtemp: () => mkdtemp,
   normalizeTTL: () => normalizeTTL,
   parseCookies: () => parseCookies,
+  parseIpv4: () => parseIpv4,
   parseKeyData: () => parseKeyData,
   parseSecretData: () => parseSecretData,
   parseUriTemplate: () => parseUriTemplate,
@@ -4603,7 +4608,18 @@ var import_url = require("url");
 
 // libs/utils/src/content/content.ts
 function sanitizeToJson(value) {
-  const seen = /* @__PURE__ */ new WeakSet();
+  const ancestors = /* @__PURE__ */ new WeakSet();
+  function withinAncestors(container, build) {
+    if (ancestors.has(container)) {
+      return void 0;
+    }
+    ancestors.add(container);
+    try {
+      return build();
+    } finally {
+      ancestors.delete(container);
+    }
+  }
   function sanitize(val) {
     if (typeof val === "function" || typeof val === "symbol") {
       return void 0;
@@ -4622,35 +4638,31 @@ function sanitizeToJson(value) {
       };
     }
     if (val instanceof Map) {
-      const obj = {};
-      for (const [k, v] of val.entries()) {
-        obj[String(k)] = sanitize(v);
-      }
-      return obj;
+      return withinAncestors(val, () => {
+        const obj = {};
+        for (const [k, v] of val.entries()) {
+          obj[String(k)] = sanitize(v);
+        }
+        return obj;
+      });
     }
     if (val instanceof Set) {
-      return Array.from(val).map(sanitize);
+      return withinAncestors(val, () => Array.from(val).map(sanitize));
     }
     if (Array.isArray(val)) {
-      if (seen.has(val)) {
-        return void 0;
-      }
-      seen.add(val);
-      return val.map(sanitize);
+      return withinAncestors(val, () => val.map(sanitize));
     }
     if (val && typeof val === "object") {
-      if (seen.has(val)) {
-        return void 0;
-      }
-      seen.add(val);
-      const sanitized = {};
-      for (const [key, value2] of Object.entries(val)) {
-        const clean = sanitize(value2);
-        if (clean !== void 0) {
-          sanitized[key] = clean;
+      return withinAncestors(val, () => {
+        const sanitized = {};
+        for (const [key, value2] of Object.entries(val)) {
+          const clean = sanitize(value2);
+          if (clean !== void 0) {
+            sanitized[key] = clean;
+          }
         }
-      }
-      return sanitized;
+        return sanitized;
+      });
     }
     return val;
   }
@@ -4812,6 +4824,134 @@ function getCookie(cookieHeader, name) {
   return parseCookies(cookieHeader)[name];
 }
 
+// libs/utils/src/net/ip-address.ts
+var IPV4_OCTET_PATTERN = /^(0|[1-9]\d{0,2})$/;
+var IPV6_GROUP_PATTERN = /^[0-9a-f]{1,4}$/;
+var IPV4_BLOCKS = compileBlocks(
+  [
+    ["0.0.0.0/8", "this-network"],
+    ["10.0.0.0/8", "private"],
+    ["100.64.0.0/10", "carrier-grade-nat"],
+    ["127.0.0.0/8", "loopback"],
+    ["169.254.0.0/16", "link-local"],
+    ["172.16.0.0/12", "private"],
+    ["192.0.0.0/24", "ietf-protocol"],
+    ["192.168.0.0/16", "private"],
+    ["198.18.0.0/15", "benchmarking"],
+    ["224.0.0.0/4", "multicast"],
+    ["255.255.255.255/32", "reserved"],
+    ["240.0.0.0/4", "reserved"]
+  ],
+  parseIpv4
+);
+var IPV6_BLOCKS = compileBlocks(
+  [
+    ["::/128", "unspecified"],
+    ["::1/128", "loopback"],
+    ["fd00:ec2::254/128", "cloud-metadata"],
+    ["fc00::/7", "private"],
+    ["fe80::/10", "link-local"],
+    ["fec0::/10", "site-local"],
+    // RFC 8215 local-use NAT64: where the IPv4 address sits depends on the operator's prefix length.
+    ["64:ff9b:1::/48", "local-use-nat64"],
+    ["ff00::/8", "multicast"]
+  ],
+  expandIpv6
+);
+var IPV4_EMBEDDINGS = compileBlocks(
+  [
+    ["::ffff:0:0/96", 6],
+    ["::ffff:0:0:0/96", 6],
+    ["::/96", 6],
+    ["64:ff9b::/96", 6],
+    ["2002::/16", 1]
+  ],
+  expandIpv6
+);
+function parseIpv4(address) {
+  const parts = address.split(".");
+  if (parts.length !== 4 || !parts.every((part) => IPV4_OCTET_PATTERN.test(part))) return void 0;
+  const octets = parts.map(Number);
+  return octets.every((octet) => octet <= 255) ? octets : void 0;
+}
+function expandIpv6(address) {
+  const zoneIndex = address.indexOf("%");
+  let text = (zoneIndex === -1 ? address : address.slice(0, zoneIndex)).toLowerCase();
+  const lastColonIndex = text.lastIndexOf(":");
+  const trailingSegment = text.slice(lastColonIndex + 1);
+  if (lastColonIndex !== -1 && trailingSegment.includes(".")) {
+    const octets = parseIpv4(trailingSegment);
+    if (!octets) return void 0;
+    const highGroup = (octets[0] << 8 | octets[1]).toString(16);
+    const lowGroup = (octets[2] << 8 | octets[3]).toString(16);
+    text = `${text.slice(0, lastColonIndex + 1)}${highGroup}:${lowGroup}`;
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return void 0;
+  const head = parseIpv6Groups(halves[0]);
+  if (!head) return void 0;
+  if (halves.length === 1) return head.length === 8 ? head : void 0;
+  const tail = parseIpv6Groups(halves[1]);
+  if (!tail || head.length + tail.length > 7) return void 0;
+  return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+}
+function extractEmbeddedIpv4(groups) {
+  const octets = findEmbeddedIpv4Octets(groups);
+  return octets ? octets.join(".") : void 0;
+}
+function classifyIpAddress(address) {
+  const isBracketed = address.startsWith("[") && address.endsWith("]");
+  const octets = isBracketed ? void 0 : parseIpv4(address);
+  if (octets) return classifyIpv4(octets);
+  const groups = expandIpv6(isBracketed ? address.slice(1, -1) : address);
+  if (!groups) return void 0;
+  const block = IPV6_BLOCKS.find((candidate) => matchesBlock(groups, candidate, 16));
+  if (block) return { family: 6, range: block.value, cidr: block.cidr };
+  const embeddedOctets = findEmbeddedIpv4Octets(groups);
+  if (!embeddedOctets) return { family: 6, range: "public" };
+  return { ...classifyIpv4(embeddedOctets), family: 6, embeddedIpv4: embeddedOctets.join(".") };
+}
+function classifyIpv4(octets) {
+  const block = IPV4_BLOCKS.find((candidate) => matchesBlock(octets, candidate, 8));
+  return block ? { family: 4, range: block.value, cidr: block.cidr } : { family: 4, range: "public" };
+}
+function findEmbeddedIpv4Octets(groups) {
+  const embedding = IPV4_EMBEDDINGS.find((block) => matchesBlock(groups, block, 16));
+  if (!embedding) return void 0;
+  const highGroup = groups[embedding.value];
+  const lowGroup = groups[embedding.value + 1];
+  return [highGroup >> 8, highGroup & 255, lowGroup >> 8, lowGroup & 255];
+}
+function parseIpv6Groups(part) {
+  if (part === "") return [];
+  const groups = part.split(":");
+  if (!groups.every((group) => IPV6_GROUP_PATTERN.test(group))) return void 0;
+  return groups.map((group) => parseInt(group, 16));
+}
+function matchesBlock(words, block, bitsPerWord) {
+  let remainingBits = block.prefixLength;
+  for (let index = 0; remainingBits > 0; index++) {
+    const comparedBits = Math.min(bitsPerWord, remainingBits);
+    const ignoredBits = bitsPerWord - comparedBits;
+    if (words[index] >> ignoredBits !== block.network[index] >> ignoredBits) return false;
+    remainingBits -= comparedBits;
+  }
+  return true;
+}
+function compileBlocks(entries, parseNetwork) {
+  return entries.map(([cidr, value]) => {
+    const [networkText, prefixText] = cidr.split("/");
+    const network = parseNetwork(networkText);
+    if (!network) throw new Error(`Invalid network in address block "${cidr}"`);
+    return { cidr, network, prefixLength: Number(prefixText), value };
+  });
+}
+
+// libs/utils/src/net/redirect.ts
+function isRedirectResponse(response) {
+  return response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+}
+
 // libs/utils/src/index.ts
 init_fs2();
 
@@ -5991,6 +6131,7 @@ function setMachineIdOverride(id) {
   buildSetCookie,
   bytesToHex,
   checkEntryAvailability,
+  classifyIpAddress,
   clearCachedSecret,
   collapseChar,
   collapseWhitespace,
@@ -6023,11 +6164,13 @@ function setMachineIdOverride(id) {
   escapeHtmlAttr,
   escapeJsString,
   escapeScriptClose,
+  expandIpv6,
   expandTemplate,
   expandUriTemplate,
   expiresAtToTTL,
   extname,
   extractBracedParams,
+  extractEmbeddedIpv4,
   extractTemplateParams,
   extractUriScheme,
   fileExists,
@@ -6067,6 +6210,7 @@ function setMachineIdOverride(id) {
   isNode,
   isPatternSafe,
   isProduction,
+  isRedirectResponse,
   isRsaPssAlg,
   isSecretCached,
   isSecretKeyData,
@@ -6089,6 +6233,7 @@ function setMachineIdOverride(id) {
   mkdtemp,
   normalizeTTL,
   parseCookies,
+  parseIpv4,
   parseKeyData,
   parseSecretData,
   parseUriTemplate,

package/net/index.d.ts

@@ -0,0 +1,4 @@
+export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4 } from './ip-address';
+export type { IpAddressClassification, IpAddressRange, SpecialPurposeIpRange } from './ip-address';
+export { isRedirectResponse } from './redirect';
+export type { RedirectCandidate } from './redirect';

package/net/ip-address.d.ts

@@ -0,0 +1,35 @@
+/**
+ * IP-literal parsing and special-purpose range classification, shared by every SSRF guard.
+ *
+ * An IPv6 address has many spellings of the same destination (`::ffff:169.254.169.254`,
+ * `[::ffff:a9fe:a9fe]`, `0:0:0:0:0:ffff:a9fe:a9fe`) and several forms that carry an IPv4 address
+ * a translator or tunnel will reach. Guards therefore classify the parsed value, never the text.
+ */
+export type SpecialPurposeIpRange = 'unspecified' | 'this-network' | 'loopback' | 'private' | 'carrier-grade-nat' | 'link-local' | 'cloud-metadata' | 'ietf-protocol' | 'benchmarking' | 'site-local' | 'multicast' | 'local-use-nat64' | 'reserved';
+export type IpAddressRange = 'public' | SpecialPurposeIpRange;
+/**
+ * `cidr` is the special-purpose block that matched (e.g. `172.16.0.0/12`); `embeddedIpv4` is the
+ * IPv4 address an IPv6 address carries (mapped, translated, compatible, NAT64 or 6to4).
+ */
+export type IpAddressClassification = {
+    family: 4 | 6;
+    embeddedIpv4?: string;
+} & ({
+    range: 'public';
+} | {
+    range: SpecialPurposeIpRange;
+    cidr: string;
+});
+/** Parse a strict dotted-quad IPv4 address; leading zeros are refused because some stacks read them as octal. */
+export declare function parseIpv4(address: string): number[] | undefined;
+/** Expand an IPv6 address (zone id stripped, trailing dotted quad allowed) to its eight 16-bit groups. */
+export declare function expandIpv6(address: string): number[] | undefined;
+/** The IPv4 address carried by an expanded IPv6 address, where it carries one. */
+export declare function extractEmbeddedIpv4(groups: readonly number[]): string | undefined;
+/**
+ * Classify an IPv4 or IPv6 literal (IPv6 optionally in URL brackets) by the special-purpose block
+ * it falls in. An IPv6 address that carries an IPv4 address is judged by that IPv4 address.
+ *
+ * @returns undefined when the input is not a well-formed IP literal.
+ */
+export declare function classifyIpAddress(address: string): IpAddressClassification | undefined;

package/net/redirect.d.ts

@@ -0,0 +1,9 @@
+export interface RedirectCandidate {
+    status: number;
+    type?: string;
+}
+/**
+ * Whether a `fetch` response made with `redirect: 'manual'` is a redirect. Browser runtimes return
+ * an `opaqueredirect` response with status 0 and no readable `Location`, so status alone misses it.
+ */
+export declare function isRedirectResponse(response: RedirectCandidate): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.8.0",
+    "@frontmcp/lazy-zod": "1.8.2",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"
   },