CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ip-address

A library for parsing IPv4 and IPv6 IP addresses in node and the browser.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

special-analysis.mddocs/

Special Address Analysis

Advanced analysis of specialized address formats including Teredo tunneling and 6to4 transition mechanisms for IPv6 addresses.

Capabilities

Teredo Address Analysis

Teredo is an IPv6 transition mechanism that encapsulates IPv6 packets within IPv4 UDP datagrams. Teredo addresses contain embedded information about the Teredo server and client.

/**
 * Analyze Teredo address properties and extract embedded information
 * Available on Address6 instances
 * @returns TeredoProperties object with detailed Teredo information
 */
inspectTeredo(): TeredoProperties;

interface TeredoProperties {
  prefix: string;           // Teredo prefix (normally "2001:0000")
  server4: string;          // IPv4 address of Teredo server
  client4: string;          // IPv4 address of Teredo client (obfuscated)
  flags: string;            // 16-bit flags in binary
  coneNat: boolean;         // True if behind cone NAT
  microsoft: {              // Microsoft-specific flags
    reserved: boolean;      // Reserved bit
    universalLocal: boolean; // Universal/Local flag
    groupIndividual: boolean; // Individual/Group flag
    nonce: string;          // 12-bit random nonce
  };
  udpPort: string;          // UDP port (obfuscated)
}

Teredo Analysis Examples:

import { Address6 } from "ip-address";

// Example Teredo address
const teredoAddr = new Address6("2001:0:ce49:7601:e866:efff:62c3:fffe");

if (teredoAddr.isTeredo()) {
  const teredo = teredoAddr.inspectTeredo();
  
  console.log("Teredo Analysis:");
  console.log(`Prefix: ${teredo.prefix}`);           // "2001:0000"
  console.log(`Server IPv4: ${teredo.server4}`);     // "206.73.118.1"
  console.log(`Client IPv4: ${teredo.client4}`);     // "157.60.0.1"
  console.log(`UDP Port: ${teredo.udpPort}`);        // "40000"
  console.log(`Cone NAT: ${teredo.coneNat}`);        // true/false
  console.log(`Flags (binary): ${teredo.flags}`);    // 16-bit binary string
  
  // Microsoft-specific information
  console.log("Microsoft flags:");
  console.log(`  Reserved: ${teredo.microsoft.reserved}`);
  console.log(`  Universal/Local: ${teredo.microsoft.universalLocal}`);
  console.log(`  Group/Individual: ${teredo.microsoft.groupIndividual}`);
  console.log(`  Nonce: ${teredo.microsoft.nonce}`);
}

// Another Teredo example
const teredo2 = new Address6("2001:0:4137:9e76:8000:63bf:3fff:fdd2");
const info2 = teredo2.inspectTeredo();

console.log(`\nTeredo Server: ${info2.server4}`);    
console.log(`Teredo Client: ${info2.client4}`);      
console.log(`Behind Cone NAT: ${info2.coneNat}`);    
console.log(`Port: ${info2.udpPort}`);

Understanding Teredo Address Structure:

function explainTeredoStructure(teredoStr: string) {
  const addr = new Address6(teredoStr);
  
  if (!addr.isTeredo()) {
    console.log("Not a Teredo address");
    return;
  }
  
  const teredo = addr.inspectTeredo();
  
  console.log(`\nTeredo Address: ${addr.canonicalForm()}`);
  console.log("Structure breakdown:");
  console.log(`  Bits 0-31:   ${teredo.prefix} (Teredo prefix)`);
  console.log(`  Bits 32-63:  ${teredo.server4} (Server IPv4, embedded)`);
  console.log(`  Bits 64-79:  ${teredo.flags} (Flags)`);
  console.log(`  Bits 80-95:  Port ${teredo.udpPort} (obfuscated: inverted bits)`);
  console.log(`  Bits 96-127: ${teredo.client4} (Client IPv4, obfuscated: inverted bits)`);
  
  console.log("\nNAT and Microsoft Details:");
  console.log(`  Cone NAT detected: ${teredo.coneNat}`);
  if (teredo.microsoft.nonce !== "0") {
    console.log(`  Microsoft implementation detected`);
    console.log(`  Random nonce: ${teredo.microsoft.nonce}`);
  }
}

// Example usage
explainTeredoStructure("2001:0:ce49:7601:e866:efff:62c3:fffe");

6to4 Address Analysis

6to4 is an IPv6 transition mechanism that embeds IPv4 addresses within IPv6 addresses to enable communication between IPv6 islands over IPv4 infrastructure.

/**
 * Analyze 6to4 address properties and extract embedded IPv4 information
 * Available on Address6 instances
 * @returns SixToFourProperties object with 6to4 information
 */
inspect6to4(): SixToFourProperties;

interface SixToFourProperties {
  prefix: string;     // 6to4 prefix (normally "2002")
  gateway: string;    // IPv4 address of 6to4 gateway
}

6to4 Analysis Examples:

// Example 6to4 addresses
const sixToFour1 = new Address6("2002:c000:0204::"); // 192.0.2.4 embedded
const sixToFour2 = new Address6("2002:cb00:7101::"); // 203.0.113.1 embedded

if (sixToFour1.is6to4()) {
  const info1 = sixToFour1.inspect6to4();
  console.log("6to4 Analysis:");
  console.log(`Prefix: ${info1.prefix}`);          // "2002"
  console.log(`Gateway IPv4: ${info1.gateway}`);   // "192.0.2.4"
}

if (sixToFour2.is6to4()) {
  const info2 = sixToFour2.inspect6to4();
  console.log(`\n6to4 Gateway: ${info2.gateway}`);  // "203.0.113.1"
}

// Convert IPv4 to 6to4 format
function ipv4To6to4(ipv4Str: string): string {
  const ipv4 = new Address4(ipv4Str);
  const hex = ipv4.toHex().replace(/:/g, '');
  return `2002:${hex.substring(0,4)}:${hex.substring(4,8)}::`;
}

console.log(ipv4To6to4("192.0.2.4"));    // "2002:c000:0204::"
console.log(ipv4To6to4("203.0.113.1"));  // "2002:cb00:7101::"

Understanding 6to4 Address Structure:

function explain6to4Structure(addr6to4Str: string) {
  const addr = new Address6(addr6to4Str);
  
  if (!addr.is6to4()) {
    console.log("Not a 6to4 address");
    return;
  }
  
  const info = addr.inspect6to4();
  
  console.log(`\n6to4 Address: ${addr.canonicalForm()}`);
  console.log("Structure breakdown:");
  console.log(`  Bits 0-15:   ${info.prefix} (6to4 prefix)`);
  console.log(`  Bits 16-47:  ${info.gateway} (Gateway IPv4, embedded in hex)`);
  console.log(`  Bits 48-127: Site-specific addressing`);
  
  // Show hex representation of embedded IPv4
  const ipv4 = new Address4(info.gateway);
  console.log(`  IPv4 as hex:  ${ipv4.toHex().replace(/:/g, '')}`);
}

// Example usage
explain6to4Structure("2002:c000:0204:1234::5678");

URL Parsing with IPv6

Extract IPv6 addresses and ports from URLs, handling the bracket notation required for IPv6 in URLs.

/**
 * Parse IPv6 address and port from URL string
 * Available as static method on Address6
 * @param url - URL containing IPv6 address in brackets
 * @returns Object with address and port properties, or error information
 */
static fromURL(url: string): {
  address: Address6;
  port: number | null;
} | {
  error: string;
  address: null;
  port: null;
};

URL Parsing Examples:

// URLs with IPv6 addresses
const urls = [
  "http://[2001:db8::1]/",
  "https://[2001:db8::1]:8080/path",
  "http://[::ffff:192.168.1.1]:3000/api",
  "ftp://[2001:db8:1234::abcd]:21/files",
  "[2001:db8::1]:8080",  // Just address and port
  "2001:db8::1",         // Just address
];

urls.forEach(url => {
  console.log(`\nParsing: ${url}`);
  const result = Address6.fromURL(url);
  
  if ('error' in result) {
    console.log(`Error: ${result.error}`);
  } else {
    console.log(`Address: ${result.address.correctForm()}`);
    console.log(`Port: ${result.port || 'none'}`);
    
    // Additional analysis
    if (result.address.isTeredo()) {
      console.log("  -> Teredo address detected");
    }
    if (result.address.is6to4()) {
      console.log("  -> 6to4 address detected");
    }
    if (result.address.is4()) {
      console.log(`  -> Contains IPv4: ${result.address.address4?.correctForm()}`);
    }
  }
});

Comprehensive Special Address Analysis

Combine multiple analysis techniques for complete specialized address evaluation.

function analyzeSpecialAddress(addrStr: string) {
  try {
    const addr = new Address6(addrStr);
    
    console.log(`\n=== Analysis of ${addrStr} ===`);
    console.log(`Canonical form: ${addr.canonicalForm()}`);
    console.log(`Correct form: ${addr.correctForm()}`);
    console.log(`Type: ${addr.getType()}`);
    console.log(`Scope: ${addr.getScope()}`);
    
    // Check for special address types
    if (addr.isTeredo()) {
      console.log("\n🔍 TEREDO ANALYSIS:");
      const teredo = addr.inspectTeredo();
      console.log(`  Server: ${teredo.server4}`);
      console.log(`  Client: ${teredo.client4}`);
      console.log(`  Port: ${teredo.udpPort}`);
      console.log(`  Cone NAT: ${teredo.coneNat}`);
      console.log(`  Flags: ${teredo.flags}`);
      
      if (teredo.microsoft.nonce !== "0") {
        console.log(`  Microsoft nonce: ${teredo.microsoft.nonce}`);
      }
    }
    
    if (addr.is6to4()) {
      console.log("\n🔍 6TO4 ANALYSIS:");
      const sixToFour = addr.inspect6to4();
      console.log(`  Gateway: ${sixToFour.gateway}`);
      console.log(`  Prefix: ${sixToFour.prefix}`);
    }
    
    if (addr.is4()) {
      console.log("\n🔍 IPv4-IN-IPv6 ANALYSIS:");
      console.log(`  Embedded IPv4: ${addr.address4?.correctForm()}`);
      console.log(`  v4-in-v6 form: ${addr.to4in6()}`);
      
      // Check if we can create 6to4 from this
      const sixToFour = addr.to6to4();
      if (sixToFour) {
        console.log(`  Equivalent 6to4: ${sixToFour.correctForm()}`);
      }
    }
    
    // Microsoft transcription for all addresses
    console.log(`\nMicrosoft UNC: ${addr.microsoftTranscription()}`);
    
    // Reverse DNS
    console.log(`Reverse DNS: ${addr.reverseForm()}`);
    
  } catch (error) {
    console.log(`Error analyzing ${addrStr}: ${error.message}`);
  }
}

// Test various special addresses
const testAddresses = [
  "2001:0:ce49:7601:e866:efff:62c3:fffe",    // Teredo
  "2001:0:4137:9e76:8000:63bf:3fff:fdd2",    // Teredo with cone NAT
  "2002:c000:0204::",                        // 6to4
  "2002:cb00:7101:1234::5678",              // 6to4 with site addressing
  "::ffff:192.168.1.1",                     // IPv4-mapped
  "::192.168.1.1",                          // IPv4-compatible (deprecated)
  "2001:db8::1",                            // Regular global unicast
];

testAddresses.forEach(analyzeSpecialAddress);

Practical Applications

Common use cases for special address analysis in networking applications.

Network Monitoring:

function categorizeTraffic(addresses: string[]) {
  const categories = {
    teredo: [],
    sixToFour: [],
    ipv4Mapped: [],
    linkLocal: [],
    regular: []
  };
  
  addresses.forEach(addrStr => {
    try {
      const addr = new Address6(addrStr);
      
      if (addr.isTeredo()) {
        const teredo = addr.inspectTeredo();
        categories.teredo.push({
          address: addrStr,
          server: teredo.server4,
          client: teredo.client4
        });
      } else if (addr.is6to4()) {
        const info = addr.inspect6to4();
        categories.sixToFour.push({
          address: addrStr,
          gateway: info.gateway
        });
      } else if (addr.is4()) {
        categories.ipv4Mapped.push({
          address: addrStr,
          ipv4: addr.address4?.correctForm()
        });
      } else if (addr.isLinkLocal()) {
        categories.linkLocal.push(addrStr);
      } else {
        categories.regular.push(addrStr);
      }
    } catch (e) {
      // Skip invalid addresses
    }
  });
  
  return categories;
}

Transition Mechanism Detection:

function detectTransitionMechanisms(logEntries: string[]) {
  const mechanisms = new Set();
  
  logEntries.forEach(entry => {
    // Extract IPv6 addresses from log entry (simplified)
    const ipv6Match = entry.match(/[0-9a-f:]+::[0-9a-f:]*/gi);
    
    if (ipv6Match) {
      ipv6Match.forEach(addrStr => {
        try {
          const addr = new Address6(addrStr);
          
          if (addr.isTeredo()) {
            mechanisms.add('Teredo');
          } else if (addr.is6to4()) {
            mechanisms.add('6to4');
          } else if (addr.is4()) {
            mechanisms.add('IPv4-in-IPv6');
          }
        } catch (e) {
          // Ignore parsing errors
        }
      });
    }
  });
  
  return Array.from(mechanisms);
}

docs

address-types.md

format-conversion.md

index.md

ipv4.md

ipv6.md

special-analysis.md

subnet-operations.md

tile.json