import { assertEquals } from "@std/assert";
import { classifyAddress } from "@hertzg/ip";

// A guard that only checks loopback and link-local misses private, CGNAT,
// and multicast ranges; classification is one label from a closed set, so
// there's no list of booleans to keep in sync
function isSafeToFetch(host: string): boolean {
  const { classification } = classifyAddress(host); // v4, v6, or mapped, one call
  return classification === "public" || classification === "global-unicast";
}

assertEquals(isSafeToFetch("8.8.8.8"), true);
assertEquals(isSafeToFetch("2001:4860:4860::8888"), true);

assertEquals(isSafeToFetch("127.0.0.1"), false);
assertEquals(isSafeToFetch("10.0.0.1"), false);
assertEquals(isSafeToFetch("169.254.169.254"), false); // cloud metadata endpoint
assertEquals(isSafeToFetch("::ffff:127.0.0.1"), false); // mapped, unwrapped first

Trusted Network Allowlist

import { assert, assertEquals } from "@std/assert";
import { cidrContains, parseCidr, parseAddress } from "@hertzg/ip";

// The list may mix IP versions; each entry is only ever compared against an
// address of its own version, and a mismatch is a miss rather than an error
const trustedRanges = [
  "10.0.0.0/8",
  "172.16.0.0/12",
  "192.168.0.0/16",
  "fd00::/8",
].map((s) => parseCidr(s));

function isTrusted(ip: string): boolean {
  const address = parseAddress(ip).address;
  return trustedRanges.some((cidr) => cidrContains(cidr, address));
}

assert(isTrusted("192.168.1.100"));
assert(isTrusted("10.0.0.1"));
assert(isTrusted("::ffff:172.16.5.1")); // parseAddress unwrapped this to IPv4 first
assert(isTrusted("fd00::1")); // matched the IPv6 entry, no conversion involved

assertEquals(isTrusted("8.8.8.8"), false);
assertEquals(isTrusted("2001:db8::1"), false);

Dual-Stack Server

import { assertEquals } from "@std/assert";
import { classifyAddress, parseAddress, stringifyAddress } from "@hertzg/ip";

// Dual-stack servers (Deno, Node) report IPv4 clients as ::ffff:x.x.x.x
// parseAddress auto-unwraps mapped addresses to their IPv4 form
const remote1 = parseAddress("::ffff:192.168.1.50").address;
assertEquals(stringifyAddress(remote1), "192.168.1.50");

// Native IPv6 clients pass through unchanged
const remote2 = parseAddress("2001:db8::1").address;
assertEquals(stringifyAddress(remote2), "2001:db8::1");

// Classification works on both
assertEquals(classifyAddress(remote1).classification, "private");
assertEquals(classifyAddress(remote2).classification, "documentation");

IP Classification

import { assertEquals } from "@std/assert";
import { classifyAddress } from "@hertzg/ip";

// Classify any IP — result includes kind, numeric value, and label
const result = classifyAddress("192.168.1.1");
assertEquals(result.kind, "ipv4");
assertEquals(result.classification, "private");

assertEquals(classifyAddress("127.0.0.1").classification, "loopback");
assertEquals(classifyAddress("8.8.8.8").classification, "public");
assertEquals(classifyAddress("169.254.1.1").classification, "link-local");

// Works with IPv6 too
assertEquals(classifyAddress("::1").classification, "loopback");
assertEquals(classifyAddress("fe80::1").classification, "link-local");
assertEquals(classifyAddress("fd00::1").classification, "unique-local");

// Use with Zod as a custom validator that accepts allowed classifications:
//
// import { type Classificationv4, type Classificationv6,
//   classifyAddress } from "@hertzg/ip";
//
// function ipClassification(
//   ...allowed: (Classificationv4 | Classificationv6)[]
// ) {
//   const set = new Set(allowed);
//   return z.string().refine(
//     (val) => set.has(classifyAddress(val).classification),
//     { message: `IP must be: ${allowed.join(", ")}` },
//   );
// }
//
// const publicIp = ipClassification("public", "global-unicast");
// publicIp.parse("8.8.8.8");       // ok
// publicIp.parse("192.168.1.1");   // throws: private
//
// const internalIp = ipClassification("private", "loopback");
// internalIp.parse("10.0.0.1");    // ok
// internalIp.parse("8.8.8.8");     // throws: public

Sorting

import { assertEquals } from "@std/assert";
import { compareCidr, compareAddress, parseCidr, parseAddress, stringifyAddress, stringifyCidr } from "@hertzg/ip";

// All IPv4 sorts before all IPv6, numerically ascending within each version
const clients = ["2001:db8::1", "10.0.0.10", "::1", "10.0.0.2"].map((s) => parseAddress(s).address);
assertEquals(clients.toSorted(compareAddress).map(stringifyAddress), [
  "10.0.0.2",
  "10.0.0.10",
  "::1",
  "2001:db8::1",
]);

// CIDR blocks tie-break on prefix length: the larger block comes first
const ranges = ["10.0.0.0/16", "2001:db8::/32", "10.0.0.0/8"].map((s) => parseCidr(s));
assertEquals(ranges.toSorted(compareCidr).map(stringifyCidr), [
  "10.0.0.0/8",
  "10.0.0.0/16",
  "2001:db8::/32",
]);

Parsing and Stringifying

import { assertEquals } from "@std/assert";
import { parseAddressv4, parseAddressv6, stringifyAddressv4, stringifyAddressv6 } from "@hertzg/ip";

// IPv4: string <-> 32-bit number
const v4 = parseAddressv4("192.168.1.1").address;
assertEquals(v4, 3232235777);
assertEquals(stringifyAddressv4(v4), "192.168.1.1");
assertEquals(stringifyAddressv4(v4 + 1), "192.168.1.2");

// IPv6: string <-> 128-bit bigint
const v6 = parseAddressv6("2001:db8::1").address;
assertEquals(v6, 42540766411282592856903984951653826561n);
assertEquals(stringifyAddressv6(v6), "2001:db8::1");
assertEquals(stringifyAddressv6(v6 + 1n), "2001:db8::2");

CIDR Network Boundaries

import { assertEquals } from "@std/assert";
import {
  cidrv4BroadcastAddress,
  cidrv4NetworkAddress,
  cidrv4Size,
  parseCidrv4,
  stringifyAddressv4,
} from "@hertzg/ip";

const cidr = parseCidrv4("192.168.1.0/24");

assertEquals(stringifyAddressv4(cidrv4NetworkAddress(cidr)), "192.168.1.0");
assertEquals(stringifyAddressv4(cidrv4BroadcastAddress(cidr)), "192.168.1.255");
assertEquals(cidrv4Size(cidr), 256);

Containment Checking

import { assert, assertEquals } from "@std/assert";
import { cidrv4Contains, parseCidrv4, parseAddressv4 } from "@hertzg/ip";

const cidr = parseCidrv4("10.0.0.0/8");

assert(cidrv4Contains(cidr, parseAddressv4("10.0.0.1").address));
assert(cidrv4Contains(cidr, parseAddressv4("10.255.255.255").address));
assertEquals(cidrv4Contains(cidr, parseAddressv4("11.0.0.0").address), false);

Address Enumeration

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4, stringifyAddressv4 } from "@hertzg/ip";

const cidr = parseCidrv4("10.0.0.0/29"); // 8 addresses

// Iterate all addresses
const all = Array.from(cidrv4Addresses(cidr));
assertEquals(all.map(stringifyAddressv4), [
  "10.0.0.0", "10.0.0.1", "10.0.0.2", "10.0.0.3",
  "10.0.0.4", "10.0.0.5", "10.0.0.6", "10.0.0.7",
]);

// Skip network address, take first 3 usable
const usable = Array.from(cidrv4Addresses(cidr, { offset: 1, count: 3 }));
assertEquals(usable.map(stringifyAddressv4), ["10.0.0.1", "10.0.0.2", "10.0.0.3"]);

Wire Bytes

import { assertEquals } from "@std/assert";
import { addressv4FromBytes, addressv4ToBytes, stringifyAddressv4 } from "@hertzg/ip";

// deno-fmt-ignore
const packet = new Uint8Array([
  0x45, 0x00, 0x00, 0x54, 0x1c, 0x46, 0x40, 0x00,
  0x40, 0x06, 0x00, 0x00,
  10, 0, 0, 1,
  192, 168, 1, 1,
]);

// Read the source and destination fields in place
assertEquals(stringifyAddressv4(addressv4FromBytes(packet, 12)), "10.0.0.1");
assertEquals(stringifyAddressv4(addressv4FromBytes(packet, 16)), "192.168.1.1");

// Rewrite the destination in place; the return is only the bytes written
const written = addressv4ToBytes(addressv4FromBytes(packet, 12), packet, 16);
assertEquals(written, new Uint8Array([10, 0, 0, 1]));
assertEquals(stringifyAddressv4(addressv4FromBytes(packet, 16)), "10.0.0.1");

Reverse DNS

The names are relative -- no trailing dot. Append "." if a resolver requires an absolute name.

import { assertEquals } from "@std/assert";
import { addressToArpa, parseAddress } from "@hertzg/ip";

assertEquals(addressToArpa(parseAddress("192.168.0.1").address), "1.0.168.192.in-addr.arpa");
assertEquals(
  addressToArpa(parseAddress("2001:db8::1").address),
  "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa",
);

API Reference

Universal (auto-detect IPv4/IPv6)

• Address: An IP address of either version (number or bigint)
• ParsedAddress: What parseAddress returns, the address plus an optional zone ID
• ParseOptions: Options for the universal parsers, unmapToV4
• parseAddress: Parse any IP address string, with an optional zone ID, to number (IPv4) or bigint (IPv6)
• stringifyAddress: Convert an address, bare or parsed, to IP address string
• Cidr: A CIDR block of either version, in either dialect (prefix length or mask)
• ParsedCidr: What parseCidr returns, the block plus an optional zone ID
• Mask: A network mask of either version (number or bigint)
• PrefixLength: A prefix length of either version
• parseCidr: Parse any CIDR notation string, in either dialect and with an optional zone ID
• stringifyCidr: Convert a Cidr, parse result or address to CIDR notation string, in the dialect it stores
• cidrSize: Get total number of addresses in a CIDR block
• cidrFirstAddress: Get the first address of a CIDR block
• cidrLastAddress: Get the last address of a CIDR block
• cidrAddresses: Generate IP addresses in a CIDR block
• cidrContains: Check if a CIDR block contains an address
• cidrContainsCidr: Check if one CIDR fully contains another
• cidrOverlaps: Check if two CIDRs share at least one address
• cidrIntersect: Return the overlapping CIDR block, or null
• cidrSubtract: Return CIDR blocks in A but not in B
• cidrMerge: Merge CIDR blocks into the minimal covering set
• compareAddress: Compare two IP addresses of either version for sorting
• compareCidr: Compare two CIDR blocks of either version for sorting
• isValidAddress: Check if a string is a valid plain IP address (IPv4 or IPv6)
• isValidCidr: Check if a string is valid CIDR notation (IPv4 or IPv6)
• addressVersion: Report which IP version an address string is written in, or undefined
• cidrVersion: Report which IP version a CIDR string is written in, or undefined
• IpVersion: An IP version number, 4 or 6
• classifyAddress: Classify an IPv4 (number) or IPv6 (bigint) address
• ClassifiedAddress: Discriminated union result with kind, value, and classification
• ClassifiedAddressv4: Result type for IPv4 classification
• ClassifiedAddressv6: Result type for IPv6 classification

Notation

• splitNotation: Split address[%zoneId][/prefix] into its three slots without reading them
• Notation: The three slots as slices
• ZoneId: The zone ID after %, a string

IPv4

• Addressv4: An IPv4 address as a 32-bit unsigned integer
• ParsedAddressv4: What parseAddressv4 returns, the address plus an optional zone ID
• parseAddressv4: Parse dotted decimal notation, with an optional zone ID, to number
• stringifyAddressv4: Convert an IPv4 address, bare or parsed, to dotted decimal notation
• compareAddressv4: Compare two IPv4 addresses for sorting
• isValidAddressv4: Check if a string is a valid IPv4 address

IPv4 CIDR

• Cidrv4: Type representing an IPv4 CIDR block, PrefixedCidrv4 or MaskedCidrv4
• Maskv4: An IPv4 network mask as a 32-bit unsigned integer
• PrefixLengthv4: An IPv4 prefix length, 0 to 32
• ParsedCidrv4: What parseCidrv4 returns, the block plus an optional zone ID
• parseCidrv4: Parse IPv4 CIDR notation, in either dialect and with an optional zone ID
• stringifyCidrv4: Convert a Cidrv4, parse result or address to CIDR notation string, in the dialect it stores
• cidrv4Mask: Get the network mask of a CIDR block or prefix length (0-32)
• cidrv4PrefixLength: Get the prefix length of a CIDR block or network mask, as a number or notation string
• cidrv4Contains: Check if IP is within CIDR block
• cidrv4ContainsCidr: Check if one IPv4 CIDR fully contains another
• cidrv4Overlaps: Check if two IPv4 CIDRs share at least one address
• cidrv4Intersect: Return the overlapping IPv4 CIDR block, or null
• cidrv4Subtract: Return IPv4 CIDR blocks in A but not in B
• cidrv4Merge: Merge IPv4 CIDR blocks into the minimal covering set
• cidrv4FirstAddress: Get first address in CIDR block
• cidrv4LastAddress: Get last address in CIDR block
• cidrv4NetworkAddress: Get the network address (first address) of a CIDR block
• cidrv4BroadcastAddress: Get the directed broadcast address (last address) of a CIDR block
• cidrv4FirstUsableAddress: Get first assignable address in CIDR block (RFC 3021 aware)
• cidrv4LastUsableAddress: Get last assignable address in CIDR block (RFC 3021 aware)
• cidrv4Size: Get total number of addresses in CIDR block
• cidrv4UsableSize: Get number of assignable addresses in CIDR block
• cidrv4Addresses: Generate IP addresses in CIDR block
• cidrv4UsableAddresses: Generate every assignable address in CIDR block
• compareCidrv4: Compare two IPv4 CIDR blocks for sorting
• isValidCidrv4: Check if a string is valid IPv4 CIDR notation

IPv6

• Addressv6: An IPv6 address as a 128-bit unsigned bigint
• ParsedAddressv6: What parseAddressv6 returns, the address plus an optional zone ID
• parseAddressv6: Parse colon-hexadecimal notation, with an optional zone ID, to bigint
• stringifyAddressv6: Convert an IPv6 address, bare or parsed, to compressed colon-hexadecimal
• stringifyAddressv6Expanded: Convert an IPv6 address, bare or parsed, to full uncompressed colon-hexadecimal
• compareAddressv6: Compare two IPv6 addresses for sorting
• isValidAddressv6: Check if a string is a valid IPv6 address

IPv6 CIDR

• Cidrv6: Type representing an IPv6 CIDR block, PrefixedCidrv6 or MaskedCidrv6
• Maskv6: An IPv6 network mask as a 128-bit unsigned bigint
• PrefixLengthv6: An IPv6 prefix length, 0 to 128
• ParsedCidrv6: What parseCidrv6 returns, the block plus an optional zone ID
• parseCidrv6: Parse IPv6 CIDR notation, in either dialect and with an optional zone ID
• stringifyCidrv6: Convert a Cidrv6, parse result or address to CIDR notation string, compressed, in the dialect it stores
• stringifyCidrv6Expanded: The same with the address written in full
• cidrv6Mask: Get the network mask of a CIDR block or prefix length (0-128)
• cidrv6PrefixLength: Get the prefix length of a CIDR block or network mask, as a bigint or notation string
• cidrv6Contains: Check if IP is within CIDR block
• cidrv6ContainsCidr: Check if one IPv6 CIDR fully contains another
• cidrv6Overlaps: Check if two IPv6 CIDRs share at least one address
• cidrv6Intersect: Return the overlapping IPv6 CIDR block, or null
• cidrv6Subtract: Return IPv6 CIDR blocks in A but not in B
• cidrv6Merge: Merge IPv6 CIDR blocks into the minimal covering set
• cidrv6FirstAddress: Get first address in CIDR block
• cidrv6LastAddress: Get last address in CIDR block
• cidrv6Size: Get total number of addresses in CIDR block
• cidrv6Addresses: Generate IP addresses in CIDR block
• compareCidrv6: Compare two IPv6 CIDR blocks for sorting
• isValidCidrv6: Check if a string is valid IPv6 CIDR notation

IPv4 Classification

• Classificationv4: Type for all IPv4 classification labels
• classifyAddressv4: Classify an IPv4 address into its well-known range
• isAddressv4Private: Check if address is private (RFC 1918)
• isAddressv4Loopback: Check if address is loopback (127.0.0.0/8)
• isAddressv4LinkLocal: Check if address is link-local (169.254.0.0/16)
• isAddressv4Multicast: Check if address is multicast (224.0.0.0/4)
• isAddressv4Reserved: Check if address is reserved (240.0.0.0/4)
• isAddressv4Broadcast: Check if address is broadcast (255.255.255.255)
• isAddressv4ThisNetwork: Check if address is "this network" (0.0.0.0/8)
• isAddressv4CgNat: Check if address is Carrier-Grade NAT (100.64.0.0/10)
• isAddressv4Benchmarking: Check if address is benchmarking (198.18.0.0/15)
• isAddressv4Documentation: Check if address is documentation (RFC 5737)
• isAddressv4Public: Check if address is publicly routable

IPv6 Classification

• Classificationv6: Type for all IPv6 classification labels
• classifyAddressv6: Classify an IPv6 address into its well-known range
• isAddressv6Loopback: Check if address is loopback (::1)
• isAddressv6Unspecified: Check if address is unspecified (::)
• isAddressv6LinkLocal: Check if address is link-local (fe80::/10)
• isAddressv6Multicast: Check if address is multicast (ff00::/8)
• isAddressv6UniqueLocal: Check if address is unique local (fc00::/7)
• isAddressv6GlobalUnicast: Check if address is global unicast (2000::/3)
• isAddressv6Mapped: Check if address is IPv4-mapped (::ffff:0:0/96)
• isAddressv6Translated: Check if address is IPv4-translated (64:ff9b::/96)
• isAddressv6Documentation: Check if address is documentation (2001:db8::/32)
• isAddressv6Teredo: Check if address is Teredo (2001::/32)
• isAddressv6Benchmarking: Check if address is benchmarking (2001:2::/48)
• isAddressv6Orchidv2: Check if address is ORCHIDv2 (2001:20::/28)

IPv4-Mapped IPv6 Conversion (addressv6, cidrv6)

• mapFromAddressv4: Convert IPv4 number to IPv4-mapped IPv6 bigint
• unmapToAddressv4: Extract IPv4 number from IPv4-mapped IPv6 bigint
• mapFromCidrv4: Convert IPv4 CIDR to IPv4-mapped IPv6 CIDR
• unmapToCidrv4: Convert IPv4-mapped IPv6 CIDR to IPv4 CIDR

Universal Wire Byte Conversion (bytes)

• addressFromBytes: Read a 4- or 16-byte address, version from its length
• addressToBytes: Write an address as its wire bytes, width from its type

IPv4 Wire Byte Conversion (bytesv4)

• addressv4FromBytes: Read a 4-byte IPv4 address from a buffer
• addressv4ToBytes: Write a 4-byte IPv4 address to a buffer

IPv6 Wire Byte Conversion (bytesv6)

• addressv6FromBytes: Read a 16-byte IPv6 address from a buffer
• addressv6ToBytes: Write a 16-byte IPv6 address to a buffer

Universal Reverse DNS Pointer Names (arpa)

• addressToArpa: Build the pointer name of an address of either version

IPv4 Reverse DNS Pointer Names (arpav4)

• addressv4ToArpa: Build the in-addr.arpa pointer name of an IPv4 address

IPv6 Reverse DNS Pointer Names (arpav6)

• addressv6ToArpa: Build the ip6.arpa pointer name of an IPv6 address

Submodules

• notation: The structural layer of notation via splitNotation
• address: Universal IP parsing via parseAddress, stringifyAddress, compareAddress
• cidr: Universal CIDR parsing via parseCidr, stringifyCidr, compareCidr
• addressv4: IPv4 parsing, sorting, and validation
• cidrv4: IPv4 CIDR utilities, sorting, and validation
• addressv6: IPv6 parsing, sorting, validation, and IPv4-mapped conversion
• cidrv6: IPv6 CIDR utilities, sorting, validation, and IPv4-mapped conversion
• classify: Universal classifier via classifyAddress
• classifyv4: IPv4 classification via classifyAddressv4, isAddressv4Private, etc.
• classifyv6: IPv6 classification via classifyAddressv6, isAddressv6Loopback, etc.
• validate: Universal validation via isValidAddress, isValidCidr
• version: IP version detection via addressVersion, cidrVersion
• bytes: Universal wire byte conversion via addressFromBytes, addressToBytes
• bytesv4: IPv4 wire byte conversion via addressv4FromBytes, addressv4ToBytes
• bytesv6: IPv6 wire byte conversion via addressv6FromBytes, addressv6ToBytes
• arpa: Universal reverse DNS pointer names via addressToArpa
• arpav4: IPv4 reverse DNS pointer names via addressv4ToArpa
• arpav6: IPv6 reverse DNS pointer names via addressv6ToArpa