ip-address 10.7.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/ip-address@10.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ip-address@10.7.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:5fe9bfea02624f6b3815f421a1be250a8de06a6f79d22332859cbfab4e76c2c2","contract":["Address6.fromAddress4Nat64 and toAddress4Nat64 embed and extract IPv4 addresses with standard and custom NAT64 prefixes","Address6.fromURL parses bracketed IPv6 host addresses and port numbers from URL strings","Address4.offset and Address4.nextNetwork calculate sequential host addresses and adjacent subnets","Address4.fromWildcard and Address4.fromAddressAndWildcardMask construct addresses using Cisco wildcard masks","Address4.isGlobal determines global reachability while distinguishing private, loopback, and CGNAT blocks"],"goal":"verify pkg:npm/ip-address@10.7.0","kind":"HOW","packages":["pkg:npm/ip-address@10.7.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/ip-address@10.7.0"],"schemaVersion":1,"subject":"pkg:npm/ip-address@10.7.0","verifierAdapter":"node-typescript@1"}

import { Address4, Address6 } from 'ip-address';

/**
 * Embeds an IPv4 address into a NAT64 IPv6 address.
 * @param {string} ipv4String
 * @param {string} [prefix]
 * @returns {string}
 */
export function embedNat64(ipv4String, prefix) {
  const addr6 = Address6.fromAddress4Nat64(ipv4String, prefix);
  return addr6.correctForm();
}

/**
 * Extracts an embedded IPv4 address from a NAT64 IPv6 address.
 * @param {string} ipv6String
 * @param {string} [prefix]
 * @returns {string|null}
 */
export function extractNat64(ipv6String, prefix) {
  const addr6 = new Address6(ipv6String);
  const addr4 = addr6.toAddress4Nat64(prefix);
  return addr4 ? addr4.correctForm() : null;
}

/**
 * Parses an IPv6 address and optional port from a URL.
 * @param {string} urlString
 * @returns {{ address: string | null, canonical: string | null, port: number | null, error?: string }}
 */
export function parseIPv6URL(urlString) {
  const parsed = Address6.fromURL(urlString);
  if (parsed.error || !parsed.address) {
    return { address: null, canonical: null, port: null, error: parsed.error };
  }
  return {
    address: parsed.address.correctForm(),
    canonical: parsed.address.canonicalForm(),
    port: parsed.port
  };
}

/**
 * Steps an IPv4 address by n hosts and calculates the adjacent network.
 * @param {string} cidrString
 * @param {number} step
 * @returns {{ offsetAddress: string, nextNetwork: string }}
 */
export function stepNetwork(cidrString, step) {
  const addr4 = new Address4(cidrString);
  return {
    offsetAddress: addr4.offset(step).correctForm(),
    nextNetwork: addr4.nextNetwork().networkForm()
  };
}

/**
 * Classifies IPv4 address reachability.
 * @param {string} ipString
 * @returns {{ isGlobal: boolean, isPrivate: boolean, isCGNAT: boolean, isLoopback: boolean }}
 */
export function classifyIPv4(ipString) {
  const addr4 = new Address4(ipString);
  return {
    isGlobal: addr4.isGlobal(),
    isPrivate: addr4.isPrivate(),
    isCGNAT: addr4.isCGNAT(),
    isLoopback: addr4.isLoopback()
  };
}

{
  "name": "ip-address-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "ip-address-sample",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ip-address": "10.7.0"
      }
    },
    "node_modules/ip-address": {
      "version": "10.7.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.0.tgz",
      "integrity": "sha512-BGFsyJd5mpXp3rK6jIdADLNgpJUK1jnjzvYF8lK+VyDab9JAmqN0YOKDdP17HlgKb2+ehPgDc8EtnRLbGCAMhA==",
      "license": "MIT",
      "engines": {
        "node": ">= 12"
      }
    }
  }
}

{
  "name": "ip-address-sample",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "ip-address": "10.7.0"
  },
  "scripts": {
    "test": "node test/contract.mjs"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/ip-address@10.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ip-address@10.7.0"
  ]
}

import assert from 'node:assert/strict';
import { Address4, Address6 } from 'ip-address';
import {
  embedNat64,
  extractNat64,
  parseIPv6URL,
  stepNetwork,
  classifyIPv4
} from '../index.mjs';

// Contract 1: Address6.fromAddress4Nat64 and toAddress4Nat64 embed and extract IPv4 addresses with standard and custom NAT64 prefixes
{
  // Standard prefix: 64:ff9b::/96
  const embedded = embedNat64('192.0.2.33');
  assert.equal(embedded, '64:ff9b::c000:221');

  const extracted = extractNat64('64:ff9b::c000:221');
  assert.equal(extracted, '192.0.2.33');

  // Custom prefix: 2001:db8::/32
  const customEmbedded = embedNat64('192.0.2.33', '2001:db8::/32');
  assert.equal(customEmbedded, '2001:db8:c000:221::');

  const customExtracted = extractNat64('2001:db8:c000:221::', '2001:db8::/32');
  assert.equal(customExtracted, '192.0.2.33');

  // Direct Address6 API
  const directNat64 = Address6.fromAddress4Nat64('10.0.0.1');
  assert.equal(directNat64.correctForm(), '64:ff9b::a00:1');
  assert.equal(directNat64.toAddress4Nat64()?.correctForm(), '10.0.0.1');

  // Non-NAT64 address returns null
  const nonNat64 = new Address6('2001:db8::1');
  assert.equal(nonNat64.toAddress4Nat64(), null);
}

// Contract 2: Address6.fromURL parses bracketed IPv6 host addresses and port numbers from URL strings
{
  const withPort = parseIPv6URL('http://[2001:db8::1]:8080/resource');
  assert.equal(withPort.address, '2001:db8::1');
  assert.equal(withPort.canonical, '2001:0db8:0000:0000:0000:0000:0000:0001');
  assert.equal(withPort.port, 8080);

  const withoutPort = parseIPv6URL('https://[fe80::1]/index.html');
  assert.equal(withoutPort.address, 'fe80::1');
  assert.equal(withoutPort.port, null);

  const invalidUrl = parseIPv6URL('not-a-valid-url');
  assert.equal(invalidUrl.address, null);
  assert.equal(invalidUrl.port, null);

  // Direct Address6.fromURL API
  const directParsed = Address6.fromURL('http://[::1]:3000');
  assert.equal(directParsed.address.correctForm(), '::1');
  assert.equal(directParsed.port, 3000);
}

// Contract 3: Address4.offset and Address4.nextNetwork calculate sequential host addresses and adjacent subnets
{
  const network = stepNetwork('192.168.1.10/24', 5);
  assert.equal(network.offsetAddress, '192.168.1.15');
  assert.equal(network.nextNetwork, '192.168.2.0/24');

  const negativeStep = stepNetwork('192.168.1.10/24', -10);
  assert.equal(negativeStep.offsetAddress, '192.168.1.0');

  // Direct Address4 offset & nextNetwork
  const addr = new Address4('10.0.0.0/16');
  assert.equal(addr.offset(1).correctForm(), '10.0.0.1');
  assert.equal(addr.nextNetwork().networkForm(), '10.1.0.0/16');
  assert.equal(addr.nextNetwork().subnetMask, 16);
}

// Contract 4: Address4.fromWildcard and Address4.fromAddressAndWildcardMask construct addresses using Cisco wildcard masks
{
  const wildcard24 = Address4.fromWildcard('192.168.0.*');
  assert.equal(wildcard24.subnet, '/24');
  assert.equal(wildcard24.subnetMask, 24);

  const wildcard16 = Address4.fromWildcard('10.0.*.*');
  assert.equal(wildcard16.subnet, '/16');
  assert.equal(wildcard16.subnetMask, 16);

  const fromMask = Address4.fromAddressAndWildcardMask('172.16.0.1', '0.0.255.255');
  assert.equal(fromMask.subnetMask, 16);
  assert.equal(fromMask.correctForm(), '172.16.0.1');
}

// Contract 5: Address4.isGlobal determines global reachability while distinguishing private, loopback, and CGNAT blocks
{
  const publicIp = classifyIPv4('8.8.8.8');
  assert.equal(publicIp.isGlobal, true);
  assert.equal(publicIp.isPrivate, false);
  assert.equal(publicIp.isCGNAT, false);
  assert.equal(publicIp.isLoopback, false);

  const privateIp = classifyIPv4('192.168.1.1');
  assert.equal(privateIp.isGlobal, false);
  assert.equal(privateIp.isPrivate, true);

  const cgnatIp = classifyIPv4('100.64.0.1');
  assert.equal(cgnatIp.isGlobal, false);
  assert.equal(cgnatIp.isCGNAT, true);

  const loopbackIp = classifyIPv4('127.0.0.1');
  assert.equal(loopbackIp.isGlobal, false);
  assert.equal(loopbackIp.isLoopback, true);
}

console.log('All contract assertions verified successfully.');