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:36763bf9b4d3e14382b9624e95eeabc8401da4131e8b309d49fd3c0a2c1d8c3b","contract":["Address6.prototype.isInSubnet checks whether an IPv6 address falls within a target subnet network","Address6 subnet methods startAddress, endAddress, networkForm, and subnetMaskAddress compute network boundaries","Address6.fromAddress4 converts an IPv4 address to an IPv6-mapped address and to4in6 formats it as dotted-decimal","Address6.fromBigInt and bigInt perform lossless two-way conversion between 128-bit integers and IPv6 addresses","Address6.reverseForm generates standard ip6.arpa domain names and Address6.fromArpa parses them back to Address6","Address6.isValid validates full IPv6 addresses and CIDR subnets while rejecting invalid syntax and IPv4 strings"],"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 { Address6 } from 'ip-address';

/**
 * Checks if a candidate IPv6 address falls within a target subnet.
 *
 * @param {string} address - IPv6 address string.
 * @param {string} subnet - IPv6 network CIDR string.
 * @returns {boolean}
 */
export function isAddressInSubnet(address, subnet) {
  const addr = new Address6(address);
  const sub = new Address6(subnet);
  return addr.isInSubnet(sub);
}

/**
 * Calculates network boundaries for an IPv6 CIDR prefix.
 *
 * @param {string} cidrString - IPv6 CIDR string.
 * @returns {{ start: string, end: string, network: string, mask: string, wildcard: string }}
 */
export function getSubnetBoundaries(cidrString) {
  const addr = new Address6(cidrString);
  return {
    start: addr.startAddress().correctForm(),
    end: addr.endAddress().correctForm(),
    network: addr.networkForm(),
    mask: addr.subnetMaskAddress().correctForm(),
    wildcard: addr.wildcardMask().correctForm()
  };
}

/**
 * Maps an IPv4 address string to an IPv6-mapped address and formats it.
 *
 * @param {string} ipv4String - IPv4 dotted-decimal string.
 * @returns {{ mapped: string, dotted: string }}
 */
export function mapIpv4ToIpv6(ipv4String) {
  const addr6 = Address6.fromAddress4(ipv4String);
  return {
    mapped: addr6.correctForm(),
    dotted: addr6.to4in6()
  };
}

/**
 * Converts between a BigInt and an Address6 instance.
 *
 * @param {string | bigint} value
 * @returns {{ bigInt: bigint, correctForm: string }}
 */
export function convertBigIntIpv6(value) {
  if (typeof value === 'bigint') {
    const addr = Address6.fromBigInt(value);
    return { bigInt: value, correctForm: addr.correctForm() };
  }
  const addr = new Address6(value);
  return { bigInt: addr.bigInt(), correctForm: addr.correctForm() };
}

/**
 * Formats an IPv6 address as an ip6.arpa reverse DNS domain and parses it back.
 *
 * @param {string} address - IPv6 address string.
 * @returns {{ reverse: string, parsed: string }}
 */
export function handleReverseDns(address) {
  const addr = new Address6(address);
  const reverse = addr.reverseForm();
  const parsed = Address6.fromArpa(reverse);
  return {
    reverse,
    parsed: parsed.correctForm()
  };
}

/**
 * Validates whether the given string is a valid IPv6 address or CIDR notation.
 *
 * @param {string} input - Address string to validate.
 * @returns {boolean}
 */
export function validateIpv6(input) {
  return Address6.isValid(input);
}

export { Address6 };

{
  "name": "ip-address-ipv6-subnet-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "ip-address-ipv6-subnet-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-ipv6-subnet-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 {
  Address6,
  isAddressInSubnet,
  getSubnetBoundaries,
  mapIpv4ToIpv6,
  convertBigIntIpv6,
  handleReverseDns,
  validateIpv6
} from '../index.mjs';

// Contract 1: Address6.prototype.isInSubnet checks whether an IPv6 address falls within a target subnet network
{
  const targetSubnet = new Address6('2001:db8::/32');
  const insideHost = new Address6('2001:db8:abcd::1');
  const edgeHost = new Address6('2001:db8:ffff:ffff:ffff:ffff:ffff:ffff');
  const outsideHost = new Address6('2001:db9::1');

  assert.equal(insideHost.isInSubnet(targetSubnet), true);
  assert.equal(edgeHost.isInSubnet(targetSubnet), true);
  assert.equal(outsideHost.isInSubnet(targetSubnet), false);

  assert.equal(isAddressInSubnet('2001:db8:1234::1', '2001:db8::/32'), true);
  assert.equal(isAddressInSubnet('fe80::1', '2001:db8::/32'), false);
}

// Contract 2: Address6 subnet methods startAddress, endAddress, networkForm, and subnetMaskAddress compute network boundaries
{
  const cidr = new Address6('2001:db8:abcd:1234::5/64');
  assert.equal(cidr.startAddress().correctForm(), '2001:db8:abcd:1234::');
  assert.equal(cidr.endAddress().correctForm(), '2001:db8:abcd:1234:ffff:ffff:ffff:ffff');
  assert.equal(cidr.networkForm(), '2001:db8:abcd:1234::/64');
  assert.equal(cidr.subnetMaskAddress().correctForm(), 'ffff:ffff:ffff:ffff::');
  assert.equal(cidr.wildcardMask().correctForm(), '::ffff:ffff:ffff:ffff');

  const bounds = getSubnetBoundaries('2001:db8:abcd:1234::5/64');
  assert.equal(bounds.start, '2001:db8:abcd:1234::');
  assert.equal(bounds.end, '2001:db8:abcd:1234:ffff:ffff:ffff:ffff');
  assert.equal(bounds.network, '2001:db8:abcd:1234::/64');
  assert.equal(bounds.mask, 'ffff:ffff:ffff:ffff::');
  assert.equal(bounds.wildcard, '::ffff:ffff:ffff:ffff');
}

// Contract 3: Address6.fromAddress4 converts an IPv4 address to an IPv6-mapped address and to4in6 formats it as dotted-decimal
{
  const v4Str = '192.168.1.100';
  const mapped = Address6.fromAddress4(v4Str);
  assert.equal(mapped.correctForm(), '::ffff:c0a8:164');
  assert.equal(mapped.to4in6(), '::ffff:192.168.1.100');

  const helperRes = mapIpv4ToIpv6('10.0.0.1');
  assert.equal(helperRes.mapped, '::ffff:a00:1');
  assert.equal(helperRes.dotted, '::ffff:10.0.0.1');
}

// Contract 4: Address6.fromBigInt and bigInt perform lossless two-way conversion between 128-bit integers and IPv6 addresses
{
  const original = new Address6('2001:db8::1');
  const bi = original.bigInt();
  assert.equal(bi, 42540766411282592856903984951653826561n);

  const restored = Address6.fromBigInt(bi);
  assert.equal(restored.correctForm(), '2001:db8::1');

  const helper = convertBigIntIpv6('::1');
  assert.equal(helper.bigInt, 1n);
  assert.equal(helper.correctForm, '::1');

  const helperFromBi = convertBigIntIpv6(1n);
  assert.equal(helperFromBi.bigInt, 1n);
  assert.equal(helperFromBi.correctForm, '::1');
}

// Contract 5: Address6.reverseForm generates standard ip6.arpa domain names and Address6.fromArpa parses them back to Address6
{
  const addr = new Address6('2001:db8::1');
  const reverseStr = addr.reverseForm();
  assert.equal(reverseStr, '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.');

  const parsedBack = Address6.fromArpa(reverseStr);
  assert.equal(parsedBack.correctForm(), '2001:db8::1');

  const dnsHelper = handleReverseDns('2001:db8::abcd');
  assert.equal(dnsHelper.reverse, 'd.c.b.a.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.');
  assert.equal(dnsHelper.parsed, '2001:db8::abcd');
}

// Contract 6: Address6.isValid validates full IPv6 addresses and CIDR subnets while rejecting invalid syntax and IPv4 strings
{
  assert.equal(validateIpv6('2001:db8::1'), true);
  assert.equal(validateIpv6('2001:db8::/32'), true);
  assert.equal(validateIpv6('::1'), true);
  assert.equal(validateIpv6('fe80::1ff:fe23:4567:890a'), true);

  assert.equal(validateIpv6('192.168.1.1'), false);
  assert.equal(validateIpv6('2001:::1'), false);
  assert.equal(validateIpv6('invalid-ip-string'), false);
  assert.equal(validateIpv6(''), false);
}

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