@verifyhash/ip-cidr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# ip-cidr
+
+A tiny, **zero-dependency** IPv4 (and basic IPv6) address/CIDR toolkit for
+Node.js. It does the boring arithmetic you always end up rewriting: validate an
+address, parse a CIDR block, ask whether a block contains an IP, and compute the
+network/broadcast/first/last host and host count of a subnet — plus lossless
+ip↔integer conversion.
+
+No network access, no runtime dependencies, no servers. Just math on the bits.
+
+> **Package name is a placeholder.** The manifest name is
+> `PLACEHOLDER-ip-cidr`. TODO: the owner picks the final npm name/scope before
+> any publish. This library is **not published** — graduation to npm is a
+> human-gated step.
+
+## Who it's for
+
+- Anyone writing allow/deny lists, firewall-ish rules, or geo/ASN buckets who
+  needs a correct `contains(cidr, ip)` without pulling a dependency tree.
+- Tools and CLIs that display subnet facts (network, broadcast, usable range,
+  host count) for an operator.
+- Code that stores IPs as integers (databases, bitmaps) and needs a reliable
+  round-trip to/from dotted-quad.
+
+## Install & usage
+
+There is nothing to install beyond Node (uses only built-in `assert` for
+tests). Once vendored/published under its final name you would:
+
+```js
+const ip = require('ip-cidr'); // during development: require('./index.js')
+
+// Containment
+ip.contains('10.0.0.0/8', '10.1.2.3');      // => true
+ip.contains('192.168.1.0/24', '192.168.2.9'); // => false
+
+// Subnet facts
+const net = ip.parseCidr('192.168.1.10/24');
+net.network;    // '192.168.1.0'
+net.broadcast;  // '192.168.1.255'
+net.firstHost;  // '192.168.1.1'
+net.lastHost;   // '192.168.1.254'
+net.hostCount;  // 254   (usable hosts)
+net.size;       // 256   (total addresses)
+
+// Address <-> integer (lossless, unsigned 32-bit)
+ip.ipv4ToInt('192.168.1.1'); // 3232235777
+ip.intToIpv4(3232235777);    // '192.168.1.1'
+
+// Validation / dispatch
+ip.isValidIPv4('1.2.3.256'); // false
+ip.ipVersion('::1');          // 6
+ip.parse('8.8.8.8');          // { version: 4, address: '8.8.8.8', int: 134744072 }
+```
+
+## API
+
+### IPv4 core
+- `isValidIPv4(str) → boolean` — strict dotted-quad. Rejects leading zeros
+  (`01.2.3.4`), out-of-range octets (`1.2.3.256`), and wrong segment counts.
+- `ipv4ToInt(str) → number` — unsigned 32-bit integer (throws on invalid).
+- `intToIpv4(int) → string` — inverse (throws if outside `0 … 4294967295`).
+
+### IPv6 core
+- `isValidIPv6(str) → boolean` — supports `::` compression and an embedded
+  IPv4 tail (`::ffff:192.168.0.1`). Zone ids (`%eth0`) are rejected.
+- `ipv6ToBigInt(str) → bigint` / `bigIntToIpv6(bigint) → string` — lossless
+  round-trip via `BigInt`. `bigIntToIpv6` returns the **fully expanded**
+  (uncompressed) form, e.g. `0:0:0:0:0:0:0:1`, not `::1`.
+
+### Unified
+- `ipVersion(str) → 4 | 6 | null`
+- `parse(str) → { version, address, int }` for v4 or
+  `{ version, address, big }` for v6 (throws on invalid).
+- `parseCidr(str) → object` — see fields below (throws on invalid).
+- `contains(cidr, ip) → boolean` — throws only if `cidr`/`ip` can't be parsed;
+  returns `false` (never throws) when the two are different address families.
+
+### `parseCidr` result
+
+IPv4 blocks return numeric and string forms:
+
+| field | example (`192.168.1.10/24`) | notes |
+|-------|------------------------------|-------|
+| `network` / `networkInt` | `192.168.1.0` / `3232235776` | masked base address |
+| `broadcast` / `broadcastInt` | `192.168.1.255` / … | all-ones host |
+| `firstHost` / `lastHost` | `192.168.1.1` / `192.168.1.254` | usable range |
+| `size` | `256` | total addresses in the block |
+| `hostCount` | `254` | usable hosts (`size − 2`, except `/31`,`/32`) |
+| `prefix` | `24` | |
+
+IPv6 blocks return `network`, `firstHost`, `lastHost` (strings) plus
+`networkBig`, `firstHostBig`, `lastHostBig`, `size`, and `hostCount` as
+`BigInt`. There is **no** `broadcast` for IPv6 — broadcast is not an IPv6
+concept.
+
+### `/31` and `/32` edge cases
+
+`/32` is treated as a single usable host (`hostCount: 1`). `/31` follows
+RFC 3021: both addresses are usable point-to-point endpoints, so
+`hostCount: 2` with no network/broadcast reservation. Wider IPv4 blocks use the
+conventional `size − 2` usable-host count.
+
+## IPv6 support scope (honest limits)
+
+IPv6 is **partial by design**. Fully supported:
+
+- **Validation & parsing** — `isValidIPv6`, `ipv6ToBigInt`, including `::`
+  compression and embedded-IPv4 tails.
+- **Containment** — `contains(cidr, ip)` and `parseCidr` work for v6 using
+  `BigInt`, so there is no precision loss across the full 128-bit space.
+
+Intentionally **not** provided for IPv6:
+
+- No `broadcast`/first-usable/last-usable *reservation* semantics (v6 has no
+  broadcast). `firstHost`/`lastHost` are just the block's low/high addresses.
+- `bigIntToIpv6` emits the expanded form only — it does **not** produce the
+  RFC 5952 shortest/canonical `::` form.
+- No zone identifiers (`fe80::1%eth0`), no scoped/link-local special handling,
+  no CIDR aggregation/summarization, and no IPv4-mapped normalization beyond
+  parsing the embedded-IPv4 syntax.
+
+If you need full IPv6 canonicalization or aggregation, use a dedicated library.
+IPv4 is the first-class, fully-featured path here.
+
+## Running the tests
+
+One command, no framework (Node's built-in `assert`):
+
+```sh
+node test/index.test.js
+# or
+npm test
+```
+
+The suite covers: containment true/false cases, `/31` and `/32` edges,
+network/broadcast math for known blocks, ip↔int round-trips, invalid-input
+rejection (bad octets, out-of-range masks, malformed strings), and the IPv6
+validate/parse/contain paths.
+
+## License
+
+MIT — see `LICENSE` (owner name is a placeholder until graduation).

package/index.js

@@ -0,0 +1,359 @@
+'use strict';
+
+/**
+ * ip-cidr — zero-dependency IPv4 (+ basic IPv6) address/CIDR toolkit.
+ *
+ * Design notes:
+ *   - IPv4 is fully supported: validate/parse, CIDR math (network, broadcast,
+ *     first/last host, host count), ip<->integer conversion, and containment.
+ *   - IPv6 support is intentionally limited to validate/parse and containment
+ *     (see README "IPv6 support scope"). We use BigInt for IPv6 so no
+ *     precision is lost, but we do not expose broadcast/first/last helpers for
+ *     v6 because "broadcast" is not an IPv6 concept.
+ *   - No network access, no dependencies, no I/O.
+ */
+
+// ---------------------------------------------------------------------------
+// IPv4 address <-> integer
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a dotted-quad IPv4 string. Requires exactly four octets, each an
+ * integer 0-255 with no leading zeros (so "01.2.3.4" and "1.2.3.256" are
+ * rejected). Returns true/false and never throws.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isValidIPv4(str) {
+  if (typeof str !== 'string') return false;
+  const parts = str.split('.');
+  if (parts.length !== 4) return false;
+  for (const part of parts) {
+    // Must be 1-3 digits, no leading zero (except the single char "0").
+    if (!/^\d{1,3}$/.test(part)) return false;
+    if (part.length > 1 && part[0] === '0') return false;
+    const n = Number(part);
+    if (n < 0 || n > 255) return false;
+  }
+  return true;
+}
+
+/**
+ * Convert a valid IPv4 string to its unsigned 32-bit integer value.
+ * @param {string} str
+ * @returns {number} 0 .. 4294967295
+ * @throws {Error} on invalid input
+ */
+function ipv4ToInt(str) {
+  if (!isValidIPv4(str)) throw new Error('invalid IPv4 address: ' + str);
+  const [a, b, c, d] = str.split('.').map(Number);
+  // >>> 0 forces the result to an unsigned 32-bit integer.
+  return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+}
+
+/**
+ * Convert an unsigned 32-bit integer to a dotted-quad IPv4 string.
+ * @param {number} int 0 .. 4294967295
+ * @returns {string}
+ * @throws {Error} on out-of-range / non-integer input
+ */
+function intToIpv4(int) {
+  if (!Number.isInteger(int) || int < 0 || int > 0xffffffff) {
+    throw new Error('integer out of IPv4 range: ' + int);
+  }
+  return [
+    (int >>> 24) & 0xff,
+    (int >>> 16) & 0xff,
+    (int >>> 8) & 0xff,
+    int & 0xff,
+  ].join('.');
+}
+
+// ---------------------------------------------------------------------------
+// IPv6 address <-> BigInt  (validate/parse + containment only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an IPv6 string, supporting "::" compression and an optional
+ * embedded IPv4 tail (e.g. "::ffff:192.168.0.1"). Returns true/false, never
+ * throws. Zone identifiers ("%eth0") are not accepted.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isValidIPv6(str) {
+  try {
+    ipv6ToBigInt(str);
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Convert an IPv6 string to a BigInt (0 .. 2**128-1). Supports "::"
+ * compression and an embedded IPv4 tail.
+ * @param {string} str
+ * @returns {bigint}
+ * @throws {Error} on invalid input
+ */
+function ipv6ToBigInt(str) {
+  if (typeof str !== 'string' || str.length === 0) {
+    throw new Error('invalid IPv6 address: not a string');
+  }
+  if (str.indexOf('%') !== -1) {
+    throw new Error('invalid IPv6 address: zone id not supported');
+  }
+
+  // At most one "::".
+  const doubleColonCount = str.split('::').length - 1;
+  if (doubleColonCount > 1) throw new Error('invalid IPv6 address: multiple "::"');
+
+  let head;
+  let tail;
+  if (doubleColonCount === 1) {
+    const [left, right] = str.split('::');
+    head = left.length ? left.split(':') : [];
+    tail = right.length ? right.split(':') : [];
+  } else {
+    head = str.split(':');
+    tail = [];
+  }
+
+  // Expand a trailing embedded IPv4 group (must be the last group) into two
+  // 16-bit hextets.
+  function expandGroups(groups) {
+    if (groups.length === 0) return [];
+    const out = [];
+    for (let i = 0; i < groups.length; i++) {
+      const g = groups[i];
+      if (g.indexOf('.') !== -1) {
+        // Only allowed as the very last group.
+        if (i !== groups.length - 1) {
+          throw new Error('invalid IPv6 address: embedded IPv4 not at end');
+        }
+        if (!isValidIPv4(g)) throw new Error('invalid IPv6 address: bad embedded IPv4');
+        const v = ipv4ToInt(g);
+        out.push(((v >>> 16) & 0xffff).toString(16));
+        out.push((v & 0xffff).toString(16));
+      } else {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(g)) {
+          throw new Error('invalid IPv6 address: bad hextet "' + g + '"');
+        }
+        out.push(g);
+      }
+    }
+    return out;
+  }
+
+  const headExp = expandGroups(head);
+  const tailExp = expandGroups(tail);
+
+  let groups;
+  if (doubleColonCount === 1) {
+    const missing = 8 - (headExp.length + tailExp.length);
+    if (missing < 1) {
+      // "::" must stand for at least one zero group.
+      throw new Error('invalid IPv6 address: "::" compresses nothing');
+    }
+    groups = headExp.concat(new Array(missing).fill('0'), tailExp);
+  } else {
+    groups = headExp;
+  }
+
+  if (groups.length !== 8) {
+    throw new Error('invalid IPv6 address: expected 8 groups, got ' + groups.length);
+  }
+
+  let result = 0n;
+  for (const g of groups) {
+    result = (result << 16n) | BigInt(parseInt(g, 16));
+  }
+  return result;
+}
+
+/**
+ * Convert a BigInt (0 .. 2**128-1) to a fully-expanded (uncompressed) IPv6
+ * string. This is a canonical form, not the shortest form.
+ * @param {bigint} value
+ * @returns {string}
+ * @throws {Error} on out-of-range input
+ */
+function bigIntToIpv6(value) {
+  if (typeof value !== 'bigint' || value < 0n || value > (1n << 128n) - 1n) {
+    throw new Error('value out of IPv6 range');
+  }
+  const groups = [];
+  for (let i = 7; i >= 0; i--) {
+    const hextet = (value >> BigInt(i * 16)) & 0xffffn;
+    groups.push(hextet.toString(16));
+  }
+  return groups.join(':');
+}
+
+// ---------------------------------------------------------------------------
+// Address family detection + unified parse
+// ---------------------------------------------------------------------------
+
+/**
+ * Return 4 if str is a valid IPv4 address, 6 if a valid IPv6 address, else
+ * null. Never throws.
+ * @param {string} str
+ * @returns {4|6|null}
+ */
+function ipVersion(str) {
+  if (isValidIPv4(str)) return 4;
+  if (isValidIPv6(str)) return 6;
+  return null;
+}
+
+/**
+ * Parse any IPv4 or IPv6 address into a descriptor object, or throw.
+ * @param {string} str
+ * @returns {{version:4, address:string, int:number}|{version:6, address:string, big:bigint}}
+ * @throws {Error} on invalid input
+ */
+function parse(str) {
+  const v = ipVersion(str);
+  if (v === 4) return { version: 4, address: str, int: ipv4ToInt(str) };
+  if (v === 6) return { version: 6, address: str, big: ipv6ToBigInt(str) };
+  throw new Error('invalid IP address: ' + str);
+}
+
+// ---------------------------------------------------------------------------
+// CIDR parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a CIDR string ("10.0.0.0/24" or "2001:db8::/32").
+ *
+ * For IPv4 returns a descriptor with numeric network/broadcast/first/last host
+ * and host count. For IPv6 returns network/first/last/count as BigInt strings
+ * plus a numeric prefix (no broadcast — not an IPv6 concept).
+ *
+ * @param {string} str
+ * @returns {object} see README for the full shape
+ * @throws {Error} on invalid input
+ */
+function parseCidr(str) {
+  if (typeof str !== 'string') throw new Error('invalid CIDR: not a string');
+  const slash = str.indexOf('/');
+  if (slash === -1) throw new Error('invalid CIDR: missing "/" in ' + str);
+  const addr = str.slice(0, slash);
+  const prefixStr = str.slice(slash + 1);
+  if (!/^\d{1,3}$/.test(prefixStr)) {
+    throw new Error('invalid CIDR: bad prefix in ' + str);
+  }
+  const prefix = Number(prefixStr);
+  const v = ipVersion(addr);
+  if (v === 4) return _parseCidr4(addr, prefix);
+  if (v === 6) return _parseCidr6(addr, prefix);
+  throw new Error('invalid CIDR: bad address in ' + str);
+}
+
+function _parseCidr4(addr, prefix) {
+  if (prefix < 0 || prefix > 32) {
+    throw new Error('invalid CIDR: IPv4 prefix must be 0-32, got ' + prefix);
+  }
+  const ipInt = ipv4ToInt(addr);
+  // Mask as unsigned 32-bit. prefix 0 => 0 mask (avoid <<32 UB).
+  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+  const network = (ipInt & mask) >>> 0;
+  const broadcast = (network | (~mask >>> 0)) >>> 0;
+  const size = prefix === 0 ? 0x100000000 : Math.pow(2, 32 - prefix);
+
+  let firstHost;
+  let lastHost;
+  let usableHosts;
+  if (prefix >= 31) {
+    // /31 (RFC 3021 point-to-point) and /32 have no "network/broadcast"
+    // reservation, so every address is usable.
+    firstHost = network;
+    lastHost = broadcast;
+    usableHosts = size; // /32 => 1, /31 => 2
+  } else {
+    firstHost = (network + 1) >>> 0;
+    lastHost = (broadcast - 1) >>> 0;
+    usableHosts = size - 2;
+  }
+
+  return {
+    version: 4,
+    cidr: intToIpv4(network) + '/' + prefix,
+    prefix: prefix,
+    network: intToIpv4(network),
+    networkInt: network,
+    broadcast: intToIpv4(broadcast),
+    broadcastInt: broadcast,
+    firstHost: intToIpv4(firstHost),
+    firstHostInt: firstHost,
+    lastHost: intToIpv4(lastHost),
+    lastHostInt: lastHost,
+    size: size, // total addresses in the block
+    hostCount: usableHosts, // usable host count
+  };
+}
+
+function _parseCidr6(addr, prefix) {
+  if (prefix < 0 || prefix > 128) {
+    throw new Error('invalid CIDR: IPv6 prefix must be 0-128, got ' + prefix);
+  }
+  const ipBig = ipv6ToBigInt(addr);
+  const full = (1n << 128n) - 1n;
+  const mask = prefix === 0 ? 0n : (full << BigInt(128 - prefix)) & full;
+  const network = ipBig & mask;
+  const last = network | (~mask & full);
+  const size = 1n << BigInt(128 - prefix);
+
+  return {
+    version: 6,
+    cidr: bigIntToIpv6(network) + '/' + prefix,
+    prefix: prefix,
+    network: bigIntToIpv6(network),
+    networkBig: network,
+    firstHost: bigIntToIpv6(network),
+    firstHostBig: network,
+    lastHost: bigIntToIpv6(last),
+    lastHostBig: last,
+    size: size, // BigInt total addresses
+    hostCount: size, // IPv6 has no broadcast reservation
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Containment
+// ---------------------------------------------------------------------------
+
+/**
+ * Does the CIDR block contain the given IP? Both must be the same family.
+ * Returns a boolean; never throws for a well-formed cidr/ip of matching
+ * family. Throws only if either argument is not parseable.
+ * @param {string} cidr e.g. "10.0.0.0/24"
+ * @param {string} ip   e.g. "10.0.0.5"
+ * @returns {boolean}
+ * @throws {Error} if cidr or ip cannot be parsed
+ */
+function contains(cidr, ip) {
+  const block = parseCidr(cidr);
+  const addr = parse(ip);
+  if (block.version !== addr.version) return false; // cross-family never matches
+  if (block.version === 4) {
+    return addr.int >= block.networkInt && addr.int <= block.broadcastInt;
+  }
+  return addr.big >= block.networkBig && addr.big <= block.lastHostBig;
+}
+
+module.exports = {
+  // IPv4 core
+  isValidIPv4,
+  ipv4ToInt,
+  intToIpv4,
+  // IPv6 core
+  isValidIPv6,
+  ipv6ToBigInt,
+  bigIntToIpv6,
+  // unified
+  ipVersion,
+  parse,
+  parseCidr,
+  contains,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@verifyhash/ip-cidr",
+  "version": "0.1.0",
+  "description": "Zero-dependency IPv4 (and basic IPv6) address/CIDR toolkit for Node.js: validate/parse, CIDR math (network, broadcast, first/last host, host count), ip<->integer, and containment.",
+  "keywords": [
+    "ip",
+    "ipv4",
+    "ipv6",
+    "cidr",
+    "subnet",
+    "netmask",
+    "network",
+    "broadcast",
+    "contains",
+    "ip-to-int"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "ip-cidr"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/ip-cidr#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}