@frontmcp/utils 1.11.3 → 1.12.0-rc.1

package/README.md

@@ -42,12 +42,14 @@ await storage.get('ticket:T-1'); // 'open'
 | Naming           | `splitWords`, `toCase`, `shortHash`, `ensureMaxLen`, `idFromString`                                                                                                       |
 | URIs             | `isValidMcpUri`, `extractUriScheme`, `parseUriTemplate`, `matchUriTemplate`, `expandUriTemplate`, `extractTemplateParams` (RFC 3986 URIs, RFC 6570 templates)             |
 | Paths            | `trimSlashes`, `joinPath`, and cross-platform `pathJoin`, `pathResolve`, `basename`, `dirname`, `extname`                                                                 |
-| Content          | `sanitizeToJson`, `inferMimeType`, `safeStringify`                                                                                                                        |
+| Content          | `sanitizeToJson`, `inferMimeType`, `safeStringify`, `canonicalJson`                                                                                                       |
 | HTTP             | `validateBaseUrl`, `buildSetCookie`, `parseCookies`, `getCookie`, `isLocalhost`, `isSecureRequest`                                                                        |
-| Network          | `classifyIpAddress`, `parseIpv4`, `expandIpv6`, `isRedirectResponse`, for SSRF (server-side request forgery) checks                                                       |
+| Network          | `classifyIpAddress`, `isGloballyRoutableIp`, `parseIpv4`, `expandIpv6`, `isRedirectResponse`, for SSRF (server-side request forgery) checks                               |
+| Outbound HTTP    | `validateOutboundUrl`, `sendOutboundRequest`, `outboundFailureCategory`, for a request to a URL that a client chose                                                       |
 | Escaping         | `escapeHtml`, `escapeHtmlAttr`, `escapeJsString`, `safeJsonForScript`                                                                                                     |
 | Crypto           | `sha256`, `sha256Hex`, `hmacSha256`, `hkdfSha256`, `encryptAesGcm`, `decryptAesGcm`, `randomBytes`, `randomUUID`, `timingSafeEqual`, `base64urlEncode`, `base64urlDecode` |
 | PKCE             | `generateCodeVerifier`, `generateCodeChallenge`, `verifyCodeChallenge`, `generatePkcePair` (RFC 7636)                                                                     |
+| Webhooks         | `signWebhookMessage`, `webhookSignatureHeaders`, `verifyWebhookSignature`, `isStandardWebhookSecret`, `generateWebhookMessageId` (Standard Webhooks)                      |
 | Encryption, keys | `encryptValue`, `decryptValue`, `signData`, `verifyData`, `KeyPersistence`, `createKeyPersistence`                                                                        |
 | Storage          | `createStorage`, `createMemoryStorage`, `TypedStorage`, `EncryptedTypedStorage`, and adapters for memory, Redis, Vercel KV, Upstash and the file system                   |
 | File system      | `readFile`, `writeFile`, `mkdir`, `stat`, `fileExists`, `readJSON`, `writeJSON`, `ensureDir`, `isDirEmpty`, `runCmd` and more. Node.js only; `fs` loads on first use.     |

package/browser/crypto/index.mjs

@@ -50,6 +50,19 @@ import {
   isSignedData,
   verifyOrParseData
 } from "./hmac-signing.mjs";
+import {
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  signingKeyOf,
+  isStandardWebhookSecret,
+  generateStandardWebhookSecret,
+  generateWebhookMessageId,
+  signWebhookMessage,
+  webhookSignatureHeaders,
+  verifyWebhookSignature
+} from "./standard-webhooks.mjs";
 import {
   asymmetricAlgSchema,
   secretKeyDataSchema,
@@ -208,6 +221,10 @@ export {
   MAX_CODE_VERIFIER_LENGTH,
   MIN_CODE_VERIFIER_LENGTH,
   PkceError,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  WEBHOOK_TIMESTAMP_HEADER,
   anyKeyDataSchema,
   assertNode,
   asymmetricAlgSchema,
@@ -234,6 +251,8 @@ export {
   generatePkcePair,
   generateRsaKeyPair2 as generateRsaKeyPair,
   generateSecret,
+  generateStandardWebhookSecret,
+  generateWebhookMessageId,
   getCrypto,
   getOrCreateSecret,
   hkdfSha256,
@@ -246,6 +265,7 @@ export {
   isSecretKeyData,
   isSecretPersistenceEnabled,
   isSignedData,
+  isStandardWebhookSecret,
   isValidCodeChallenge,
   isValidCodeVerifier,
   isValidEncryptedBlob,
@@ -269,6 +289,8 @@ export {
   sha256Base64url,
   sha256Hex,
   signData,
+  signWebhookMessage,
+  signingKeyOf,
   timingSafeEqual,
   tryDecryptValue,
   tryDeserializeAndDecrypt,
@@ -277,5 +299,7 @@ export {
   validateSecretData,
   verifyCodeChallenge,
   verifyData,
-  verifyOrParseData
+  verifyOrParseData,
+  verifyWebhookSignature,
+  webhookSignatureHeaders
 };

package/browser/crypto/standard-webhooks.mjs

@@ -0,0 +1,96 @@
+// libs/utils/src/crypto/standard-webhooks.ts
+import { base64Decode, base64Encode, base64urlEncode, hmacSha256, randomBytes, timingSafeEqual } from "./index.mjs";
+var WEBHOOK_ID_HEADER = "webhook-id";
+var WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+var WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+var WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+var SECRET_PREFIX = "whsec_";
+var MIN_SECRET_BYTES = 24;
+var MAX_SECRET_BYTES = 64;
+var GENERATED_SECRET_BYTES = 32;
+var MESSAGE_ID_RANDOM_BYTES = 18;
+var BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+var WELL_FORMED_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;
+var TIMESTAMP_PATTERN = /^\d{1,12}$/;
+var MESSAGE_KIND_PATTERN = /^[A-Za-z0-9_-]+$/;
+var SIGNATURE_VERSION = "v1";
+var encoder = new TextEncoder();
+function decodedKeyOf(secret) {
+  if (!secret.startsWith(SECRET_PREFIX)) return encoder.encode(secret);
+  const encoded = secret.slice(SECRET_PREFIX.length);
+  if (!BASE64_PATTERN.test(encoded)) throw new TypeError("not base64");
+  return base64Decode(encoded);
+}
+function signingKeyOf(secret) {
+  const signingKey = decodedKeyOf(secret);
+  if (signingKey.length === 0) throw new TypeError("empty signing key");
+  return signingKey;
+}
+function isStandardWebhookSecret(secret) {
+  if (!secret.startsWith(SECRET_PREFIX)) return false;
+  const encoded = secret.slice(SECRET_PREFIX.length);
+  if (!WELL_FORMED_BASE64_PATTERN.test(encoded)) return false;
+  const symbolCount = encoded.split("=")[0].length;
+  const byteCount = Math.floor(symbolCount * 3 / 4);
+  return byteCount >= MIN_SECRET_BYTES && byteCount <= MAX_SECRET_BYTES;
+}
+function generateStandardWebhookSecret() {
+  return `${SECRET_PREFIX}${base64Encode(randomBytes(GENERATED_SECRET_BYTES))}`;
+}
+function generateWebhookMessageId(kind) {
+  const random = base64urlEncode(randomBytes(MESSAGE_ID_RANDOM_BYTES));
+  if (kind === void 0) return `msg_${random}`;
+  if (!MESSAGE_KIND_PATTERN.test(kind)) {
+    throw new TypeError('a webhook message kind holds only ASCII letters, digits, "_" and "-"');
+  }
+  return `msg_${kind}_${random}`;
+}
+function signatureOf(signingKey, id, timestamp, body) {
+  return base64Encode(hmacSha256(signingKey, encoder.encode(`${id}.${timestamp}.${body}`)));
+}
+function signWebhookMessage(message, signingKeys) {
+  const timestamp = String(message.timestamp);
+  if (!message.id || !TIMESTAMP_PATTERN.test(timestamp) || signingKeys.length === 0) {
+    throw new TypeError("a webhook signature needs a message id, a timestamp in whole seconds and a signing key");
+  }
+  return signingKeys.map((signingKey) => `${SIGNATURE_VERSION},${signatureOf(signingKey, message.id, timestamp, message.body)}`).join(" ");
+}
+function webhookSignatureHeaders(message, signingKeys) {
+  return {
+    [WEBHOOK_ID_HEADER]: message.id,
+    [WEBHOOK_TIMESTAMP_HEADER]: String(message.timestamp),
+    [WEBHOOK_SIGNATURE_HEADER]: signWebhookMessage(message, signingKeys)
+  };
+}
+function isSameSignature(provided, expected) {
+  return provided.length === expected.length && timingSafeEqual(provided, expected);
+}
+function verifyWebhookSignature(message, signingKeys, now = Date.now()) {
+  const { id, timestamp, signature, body } = message;
+  if (!id || !timestamp || !signature) return "missing";
+  const isTimestamp = TIMESTAMP_PATTERN.test(timestamp);
+  if (!isTimestamp || Math.abs(now / 1e3 - Number(timestamp)) > WEBHOOK_SIGNATURE_TOLERANCE_SECONDS) return "stale";
+  const expectedSignatures = signingKeys.map(
+    (signingKey) => encoder.encode(signatureOf(signingKey, id, timestamp, body))
+  );
+  const matches = signature.split(" ").some((entry) => {
+    const [version, value] = entry.split(",");
+    if (version !== SIGNATURE_VERSION || value === void 0) return false;
+    const provided = encoder.encode(value);
+    return expectedSignatures.some((expected) => isSameSignature(provided, expected));
+  });
+  return matches ? "valid" : "mismatch";
+}
+export {
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  WEBHOOK_TIMESTAMP_HEADER,
+  generateStandardWebhookSecret,
+  generateWebhookMessageId,
+  isStandardWebhookSecret,
+  signWebhookMessage,
+  signingKeyOf,
+  verifyWebhookSignature,
+  webhookSignatureHeaders
+};

package/browser/fs/index.mjs

@@ -31,7 +31,9 @@ import {
   watchFile,
   getSpawnFn
 } from "./fs.mjs";
+import { watchFiles, WATCH_FILES_RETRY_MS } from "./watch-files.mjs";
 export {
+  WATCH_FILES_RETRY_MS,
   access,
   appendFile,
   chmod,
@@ -60,6 +62,7 @@ export {
   symlink,
   unlink,
   watchFile,
+  watchFiles,
   writeFile,
   writeJSON
 };

package/browser/fs/watch-files.mjs

@@ -0,0 +1,177 @@
+// libs/utils/src/fs/watch-files.ts
+import { assertNode } from "../crypto/runtime.mjs";
+import { dirname, pathJoin, pathResolve } from "../path/index.mjs";
+import { readdir, stat, watchFile } from "./fs.mjs";
+var WATCH_FILES_RETRY_MS = 500;
+var DEFAULT_DEBOUNCE_MS = 100;
+function fingerprintOf(stats) {
+  return `${stats.ino}:${stats.size}:${stats.mtimeMs}`;
+}
+function isAbsence(error) {
+  const code = error.code;
+  return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+async function statsOf(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (isAbsence(error)) return void 0;
+    throw error;
+  }
+}
+async function entriesOf(directory) {
+  try {
+    return await readdir(directory);
+  } catch (error) {
+    if (isAbsence(error)) return [];
+    throw error;
+  }
+}
+async function entryFingerprintOf(entry, known) {
+  try {
+    const stats = await statsOf(entry);
+    return stats?.isFile() ? fingerprintOf(stats) : void 0;
+  } catch {
+    return known;
+  }
+}
+async function lookAt(target, before) {
+  const files = /* @__PURE__ */ new Map();
+  const stats = await statsOf(target);
+  if (stats?.isDirectory()) {
+    for (const name of await entriesOf(target)) {
+      const child = pathJoin(target, name);
+      const fingerprint = await entryFingerprintOf(child, before?.get(child));
+      if (fingerprint !== void 0) files.set(child, fingerprint);
+    }
+    return { files, directory: target };
+  }
+  if (stats?.isFile()) files.set(target, fingerprintOf(stats));
+  const parent = dirname(target);
+  const parentStats = await statsOf(parent);
+  return { files, directory: parentStats?.isDirectory() ? parent : void 0 };
+}
+function changesBetween(before, after) {
+  const changes = [];
+  for (const [path, fingerprint] of after) {
+    const known = before.get(path);
+    if (known === void 0) changes.push({ type: "add", path });
+    else if (known !== fingerprint) changes.push({ type: "change", path });
+  }
+  for (const path of before.keys()) {
+    if (!after.has(path)) changes.push({ type: "unlink", path });
+  }
+  return changes;
+}
+var WatchedPath = class {
+  /** Takes the path to watch, how long to wait for changes to settle, and where to report each one. */
+  constructor(target, debounceMs, report) {
+    this.target = target;
+    this.debounceMs = debounceMs;
+    this.report = report;
+  }
+  target;
+  debounceMs;
+  report;
+  files;
+  watched;
+  timer;
+  looking = Promise.resolve();
+  closed = false;
+  /** Take the first look, which reports nothing, and start watching. */
+  start() {
+    return this.lookAgain();
+  }
+  /** Stop watching and looking. */
+  close() {
+    this.closed = true;
+    clearTimeout(this.timer);
+    this.watched?.handle.close();
+  }
+  /** Look again once `delayMs` passed without another reason to. */
+  lookLater(delayMs) {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.looking = this.looking.then(() => this.lookAgain());
+    }, delayMs);
+    this.timer.unref?.();
+  }
+  /** Report what changed since the last look, if any; a path that cannot be read keeps its last look until it can. */
+  async lookAgain() {
+    const sighting = await lookAt(this.target, this.files).catch(() => void 0);
+    if (this.closed) return;
+    if (!sighting) {
+      this.lookLater(WATCH_FILES_RETRY_MS);
+      return;
+    }
+    if (this.files) for (const change of changesBetween(this.files, sighting.files)) this.report(change);
+    this.files = sighting.files;
+    this.follow(sighting.directory);
+  }
+  /** Watch the directory that shows the path's changes; while there is none, look again after a wait. */
+  follow(directory) {
+    if (this.watched?.directory !== directory) {
+      this.watched?.handle.close();
+      this.watched = directory === void 0 ? void 0 : this.watch(directory);
+    }
+    if (!this.watched) this.lookLater(WATCH_FILES_RETRY_MS);
+  }
+  /** Open a watcher on a directory, dropped for a new one when it fails; nothing when the directory went away. */
+  watch(directory) {
+    try {
+      const handle = watchFile(directory, () => this.lookLater(this.debounceMs));
+      const watched = { directory, handle };
+      handle.onError(() => {
+        if (this.watched !== watched) return;
+        handle.close();
+        this.watched = void 0;
+        this.lookLater(this.debounceMs);
+      });
+      return watched;
+    } catch {
+      return void 0;
+    }
+  }
+};
+async function* watchFiles(paths, options = {}) {
+  assertNode("watchFiles");
+  const { events, debounceMs = DEFAULT_DEBOUNCE_MS, signal } = options;
+  const pending = [];
+  let wake;
+  const wakeUp = () => wake?.();
+  const report = (event) => {
+    if (events && !events.includes(event.type)) return;
+    pending.push(event);
+    wakeUp();
+  };
+  const targets = Array.isArray(paths) ? paths : [paths];
+  const watchedPaths = targets.map((path) => new WatchedPath(pathResolve(path), debounceMs, report));
+  const closeWatchers = () => {
+    for (const watchedPath of watchedPaths) watchedPath.close();
+  };
+  const endOnAbort = () => {
+    closeWatchers();
+    wakeUp();
+  };
+  signal?.addEventListener("abort", endOnAbort, { once: true });
+  try {
+    await Promise.all(watchedPaths.map((watchedPath) => watchedPath.start()));
+    while (!signal?.aborted) {
+      const event = pending.shift();
+      if (event) {
+        yield event;
+        continue;
+      }
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  } finally {
+    signal?.removeEventListener("abort", endOnAbort);
+    closeWatchers();
+  }
+}
+export {
+  WATCH_FILES_RETRY_MS,
+  watchFiles
+};

package/browser/index.mjs

@@ -24,7 +24,19 @@ import {
 } from "./path/index.mjs";
 import { sanitizeToJson, inferMimeType, findNonFiniteNumber, findDroppedKeys } from "./content/index.mjs";
 import { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost, isSecureRequest } from "./http/index.mjs";
-import { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4, isRedirectResponse } from "./net/index.mjs";
+import {
+  classifyIpAddress,
+  expandIpv6,
+  extractEmbeddedIpv4,
+  isGloballyRoutableIp,
+  parseIpv4,
+  isRedirectResponse,
+  validateOutboundUrl,
+  sendOutboundRequest,
+  outboundFailureCategory,
+  OUTBOUND_TIMEOUT_MS,
+  OUTBOUND_MAX_REQUEST_BYTES
+} from "./net/index.mjs";
 import {
   readFile,
   readFileSync,
@@ -55,6 +67,7 @@ import {
   isDirEmpty,
   runCmd,
   watchFile,
+  watchFiles,
   getSpawnFn
 } from "./fs/index.mjs";
 import {
@@ -83,7 +96,7 @@ import {
 import { redactFields, redactJson } from "./redaction/index.mjs";
 import { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from "./escape/index.mjs";
 import { brandClass, isBrandedInstance } from "./class-brand/index.mjs";
-import { safeStringify } from "./serialization/index.mjs";
+import { safeStringify, canonicalJson } from "./serialization/index.mjs";
 import {
   getCrypto,
   rsaVerify,
@@ -149,6 +162,17 @@ import {
   verifyData,
   isSignedData,
   verifyOrParseData,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  signingKeyOf,
+  isStandardWebhookSecret,
+  generateStandardWebhookSecret,
+  generateWebhookMessageId,
+  signWebhookMessage,
+  webhookSignatureHeaders,
+  verifyWebhookSignature,
   asymmetricAlgSchema,
   secretKeyDataSchema,
   asymmetricKeyDataSchema,
@@ -283,6 +307,8 @@ export {
   MemoryStorageAdapter,
   NAMESPACE_SEPARATOR,
   NamespacedStorageImpl,
+  OUTBOUND_MAX_REQUEST_BYTES,
+  OUTBOUND_TIMEOUT_MS,
   OwnedProcessError,
   PkceError,
   REDOS_THRESHOLDS,
@@ -298,6 +324,10 @@ export {
   TypedStorage,
   UpstashStorageAdapter,
   VercelKvStorageAdapter,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  WEBHOOK_TIMESTAMP_HEADER,
   access,
   analyzePattern,
   anyKeyDataSchema,
@@ -316,6 +346,7 @@ export {
   buildPrefix,
   buildSetCookie,
   bytesToHex,
+  canonicalJson,
   checkEntryAvailability,
   chmod,
   classifyIpAddress,
@@ -377,6 +408,8 @@ export {
   generatePkcePair,
   generateRsaKeyPair,
   generateSecret,
+  generateStandardWebhookSecret,
+  generateWebhookMessageId,
   getAsyncContextMode,
   getCookie,
   getCrypto,
@@ -406,6 +439,7 @@ export {
   isEdgeRuntime,
   isEntryAvailable,
   isExpired,
+  isGloballyRoutableIp,
   isInputLengthSafe,
   isLocalhost,
   isNode,
@@ -420,6 +454,7 @@ export {
   isSecureRequest,
   isServerless,
   isSignedData,
+  isStandardWebhookSecret,
   isUriTemplate,
   isValidCodeChallenge,
   isValidCodeVerifier,
@@ -438,6 +473,7 @@ export {
   mkdir,
   mkdtemp,
   normalizeTTL,
+  outboundFailureCategory,
   parseCookies,
   parseIpv4,
   parseKeyData,
@@ -480,6 +516,7 @@ export {
   saveSecret,
   secretDataSchema,
   secretKeyDataSchema,
+  sendOutboundRequest,
   sep,
   sepFor,
   serializeBlob,
@@ -490,7 +527,9 @@ export {
   sha256Hex,
   shortHash,
   signData,
+  signWebhookMessage,
   signalProcessTree,
+  signingKeyOf,
   spawnOwned,
   splitWords,
   stat,
@@ -512,15 +551,19 @@ export {
   validateBaseUrl,
   validateKeyData,
   validateOptionalTTL,
+  validateOutboundUrl,
   validatePattern,
   validateSecretData,
   validateTTL,
   verifyCodeChallenge,
   verifyData,
   verifyOrParseData,
+  verifyWebhookSignature,
   watchFile,
+  watchFiles,
   watchParent,
   watchPath,
+  webhookSignatureHeaders,
   writeFile,
   writeJSON
 };

package/browser/net/index.mjs

@@ -1,10 +1,23 @@
 // libs/utils/src/net/index.ts
-import { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4 } from "./ip-address.mjs";
+import { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, isGloballyRoutableIp, parseIpv4 } from "./ip-address.mjs";
 import { isRedirectResponse } from "./redirect.mjs";
+import { validateOutboundUrl } from "./outbound-url.mjs";
+import {
+  OUTBOUND_MAX_REQUEST_BYTES,
+  OUTBOUND_TIMEOUT_MS,
+  outboundFailureCategory,
+  sendOutboundRequest
+} from "./outbound-request.mjs";
 export {
+  OUTBOUND_MAX_REQUEST_BYTES,
+  OUTBOUND_TIMEOUT_MS,
   classifyIpAddress,
   expandIpv6,
   extractEmbeddedIpv4,
+  isGloballyRoutableIp,
   isRedirectResponse,
-  parseIpv4
+  outboundFailureCategory,
+  parseIpv4,
+  sendOutboundRequest,
+  validateOutboundUrl
 };

package/browser/net/ip-address.mjs

@@ -32,6 +32,25 @@ var IPV6_BLOCKS = compileBlocks(
   ],
   expandIpv6
 );
+var UNROUTED_IPV4_BLOCKS = compileBlocks(
+  [
+    ["192.0.2.0/24", "documentation"],
+    ["198.51.100.0/24", "documentation"],
+    ["203.0.113.0/24", "documentation"]
+  ],
+  parseIpv4
+);
+var UNROUTED_IPV6_BLOCKS = compileBlocks(
+  [
+    ["100::/64", "discard-only"],
+    ["100:0:0:1::/64", "dummy-prefix"],
+    ["2001::/23", "ietf-protocol"],
+    ["2001:db8::/32", "documentation"],
+    ["3fff::/20", "documentation"],
+    ["5f00::/16", "segment-routing"]
+  ],
+  expandIpv6
+);
 var IPV4_EMBEDDINGS = compileBlocks(
   [
     ["::ffff:0:0/96", 6],
@@ -85,6 +104,16 @@ function classifyIpAddress(address) {
   if (!embeddedOctets) return { family: 6, range: "public" };
   return { ...classifyIpv4(embeddedOctets), family: 6, embeddedIpv4: embeddedOctets.join(".") };
 }
+function isGloballyRoutableIp(address) {
+  const classification = classifyIpAddress(address);
+  if (classification?.range !== "public") return false;
+  const isBracketed = address.startsWith("[") && address.endsWith("]");
+  const bareAddress = isBracketed ? address.slice(1, -1) : address;
+  const octets = parseIpv4(classification.embeddedIpv4 ?? bareAddress);
+  if (octets) return !UNROUTED_IPV4_BLOCKS.some((block) => matchesBlock(octets, block, 8));
+  const groups = expandIpv6(bareAddress);
+  return groups !== void 0 && !UNROUTED_IPV6_BLOCKS.some((block) => matchesBlock(groups, block, 16));
+}
 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" };
@@ -124,5 +153,6 @@ export {
   classifyIpAddress,
   expandIpv6,
   extractEmbeddedIpv4,
+  isGloballyRoutableIp,
   parseIpv4
 };