recap/node_modules/@start9labs/start-sdk/base/lib/util/ip.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.CGNAT = exports.IPV6_LINK_LOCAL = exports.IPV6_LOOPBACK = exports.IPV4_LOOPBACK = exports.PRIVATE_IPV4_RANGES = exports.IpNet = exports.IpAddress = void 0;
/**
 * Represents an IPv4 or IPv6 address as raw octets with arithmetic and comparison operations.
 *
 * IPv4 addresses have 4 octets, IPv6 addresses have 16 octets.
 *
 * @example
 * ```ts
 * const ip = IpAddress.parse("192.168.1.1")
 * const next = ip.add(1) // 192.168.1.2
 * ```
 */
class IpAddress {
    constructor(octets, renderedAddress) {
        this.octets = octets;
        this.renderedAddress = renderedAddress;
        this.renderedOctets = [...octets];
    }
    /**
     * Parses an IP address string into an IpAddress instance.
     * Supports both IPv4 dotted-decimal and IPv6 colon-hex notation (including `::` shorthand).
     * @param address - The IP address string to parse
     * @returns A new IpAddress instance
     * @throws Error if the address format is invalid
     */
    static parse(address) {
        let octets;
        if (address.includes(':')) {
            octets = new Array(16).fill(0);
            const segs = address.split(':');
            let idx = 0;
            let octIdx = 0;
            while (segs[idx]) {
                const num = parseInt(segs[idx], 16);
                octets[octIdx++] = num >> 8;
                octets[octIdx++] = num & 255;
                idx += 1;
            }
            const lastSegIdx = segs.length - 1;
            if (idx < lastSegIdx) {
                idx = lastSegIdx;
                octIdx = 15;
                while (segs[idx]) {
                    const num = parseInt(segs[idx], 16);
                    octets[octIdx--] = num & 255;
                    octets[octIdx--] = num >> 8;
                    idx -= 1;
                }
            }
        }
        else {
            octets = address.split('.').map(Number);
            if (octets.length !== 4)
                throw new Error('invalid ipv4 address');
        }
        if (octets.some((o) => isNaN(o) || o > 255)) {
            throw new Error('invalid ip address');
        }
        return new IpAddress(octets, address);
    }
    /**
     * Creates an IpAddress from a raw octet array.
     * @param octets - Array of 4 octets (IPv4) or 16 octets (IPv6), each 0-255
     * @returns A new IpAddress instance
     * @throws Error if the octet array length is not 4 or 16, or any octet exceeds 255
     */
    static fromOctets(octets) {
        if (octets.length == 4) {
            if (octets.some((o) => o > 255)) {
                throw new Error('invalid ip address');
            }
            return new IpAddress(octets, octets.join('.'));
        }
        else if (octets.length == 16) {
            if (octets.some((o) => o > 255)) {
                throw new Error('invalid ip address');
            }
            let pre = octets.slice(0, 8);
            while (pre[pre.length - 1] == 0) {
                pre.pop();
            }
            let post = octets.slice(8);
            while (post[0] == 0) {
                post.unshift();
            }
            if (pre.length + post.length == 16) {
                return new IpAddress(octets, octets.join(':'));
            }
            else {
                return new IpAddress(octets, pre.join(':') + '::' + post.join(':'));
            }
        }
        else {
            throw new Error('invalid ip address');
        }
    }
    /** Returns true if this is an IPv4 address (4 octets). */
    isIpv4() {
        return this.octets.length === 4;
    }
    /** Returns true if this is an IPv6 address (16 octets). */
    isIpv6() {
        return this.octets.length === 16;
    }
    /** Returns true if this is a public IPv4 address (not in any private range). */
    isPublic() {
        return this.isIpv4() && !exports.PRIVATE_IPV4_RANGES.some((r) => r.contains(this));
    }
    /**
     * Returns a new IpAddress incremented by `n`.
     * @param n - The integer amount to add (fractional part is truncated)
     * @returns A new IpAddress with the result
     * @throws Error on overflow
     */
    add(n) {
        let octets = [...this.octets];
        n = Math.floor(n);
        for (let i = octets.length - 1; i >= 0; i--) {
            octets[i] += n;
            if (octets[i] > 255) {
                n = octets[i] >> 8;
                octets[i] &= 255;
            }
            else {
                break;
            }
        }
        if (octets[0] > 255) {
            throw new Error('overflow incrementing ip');
        }
        return IpAddress.fromOctets(octets);
    }
    /**
     * Returns a new IpAddress decremented by `n`.
     * @param n - The integer amount to subtract (fractional part is truncated)
     * @returns A new IpAddress with the result
     * @throws Error on underflow
     */
    sub(n) {
        let octets = [...this.octets];
        n = Math.floor(n);
        for (let i = octets.length - 1; i >= 0; i--) {
            octets[i] -= n;
            if (octets[i] < 0) {
                n = Math.ceil(Math.abs(octets[i]) / 256);
                octets[i] = ((octets[i] % 256) + 256) % 256;
            }
            else {
                break;
            }
        }
        if (octets[0] < 0) {
            throw new Error('underflow decrementing ip');
        }
        return IpAddress.fromOctets(octets);
    }
    /**
     * Compares this address to another, returning -1, 0, or 1.
     * @param other - An IpAddress instance or string to compare against
     * @returns -1 if this < other, 0 if equal, 1 if this > other
     */
    cmp(other) {
        if (typeof other === 'string')
            other = IpAddress.parse(other);
        const len = Math.max(this.octets.length, other.octets.length);
        for (let i = 0; i < len; i++) {
            const left = this.octets[i] || 0;
            const right = other.octets[i] || 0;
            if (left > right) {
                return 1;
            }
            else if (left < right) {
                return -1;
            }
        }
        return 0;
    }
    /** The string representation of this IP address (e.g. `"192.168.1.1"` or `"::1"`). Cached and recomputed only when octets change. */
    get address() {
        if (this.renderedOctets.length === this.octets.length &&
            this.renderedOctets.every((o, idx) => o === this.octets[idx])) {
            // already rendered
        }
        else if (this.octets.length === 4) {
            this.renderedAddress = this.octets.join('.');
            this.renderedOctets = [...this.octets];
        }
        else if (this.octets.length === 16) {
            const contigZeros = this.octets.reduce((acc, x, idx) => {
                if (x === 0) {
                    acc.current++;
                }
                else {
                    acc.current = 0;
                }
                if (acc.current > acc.end - acc.start) {
                    acc.end = idx + 1;
                    acc.start = acc.end - acc.current;
                }
                return acc;
            }, { start: 0, end: 0, current: 0 });
            if (contigZeros.end - contigZeros.start >= 2) {
                return `${this.octets.slice(0, contigZeros.start).join(':')}::${this.octets.slice(contigZeros.end).join(':')}`;
            }
            this.renderedAddress = this.octets.join(':');
            this.renderedOctets = [...this.octets];
        }
        else {
            console.warn('invalid octet length for IpAddress', this.octets);
        }
        return this.renderedAddress;
    }
}
exports.IpAddress = IpAddress;
/**
 * Represents an IP network (CIDR notation) combining an IP address with a prefix length.
 * Extends IpAddress with network-specific operations like containment checks and broadcast calculation.
 *
 * @example
 * ```ts
 * const net = IpNet.parse("192.168.1.0/24")
 * net.contains("192.168.1.100") // true
 * net.broadcast() // 192.168.1.255
 * ```
 */
class IpNet extends IpAddress {
    constructor(octets, prefix, address) {
        super(octets, address);
        this.prefix = prefix;
    }
    /**
     * Creates an IpNet from an IpAddress and prefix length.
     * @param ip - The base IP address
     * @param prefix - The CIDR prefix length (0-32 for IPv4, 0-128 for IPv6)
     * @returns A new IpNet instance
     * @throws Error if prefix exceeds the address bit length
     */
    static fromIpPrefix(ip, prefix) {
        if (prefix > ip.octets.length * 8) {
            throw new Error('invalid prefix');
        }
        return new IpNet(ip.octets, prefix, ip.address);
    }
    /**
     * Parses a CIDR notation string (e.g. `"192.168.1.0/24"`) into an IpNet.
     * @param ipnet - The CIDR string to parse
     * @returns A new IpNet instance
     */
    static parse(ipnet) {
        const [address, prefixStr] = ipnet.split('/', 2);
        const ip = IpAddress.parse(address);
        const prefix = Number(prefixStr);
        return IpNet.fromIpPrefix(ip, prefix);
    }
    /**
     * Checks whether this network contains the given address or subnet.
     * @param address - An IP address or subnet (string, IpAddress, or IpNet)
     * @returns True if the address falls within this network's range
     */
    contains(address) {
        if (typeof address === 'string')
            address = IpAddress.parse(address);
        if (address instanceof IpNet && address.prefix < this.prefix)
            return false;
        if (this.octets.length !== address.octets.length)
            return false;
        let prefix = this.prefix;
        let idx = 0;
        while (idx < this.octets.length && prefix >= 8) {
            if (this.octets[idx] !== address.octets[idx]) {
                return false;
            }
            idx += 1;
            prefix -= 8;
        }
        if (prefix === 0 || idx >= this.octets.length)
            return true;
        const mask = 255 ^ (255 >> prefix);
        return (this.octets[idx] & mask) === (address.octets[idx] & mask);
    }
    /** Returns the network address (all host bits zeroed) for this subnet. */
    zero() {
        let octets = [];
        let prefix = this.prefix;
        for (let idx = 0; idx < this.octets.length; idx++) {
            if (prefix >= 8) {
                octets[idx] = this.octets[idx];
                prefix -= 8;
            }
            else {
                const mask = 255 ^ (255 >> prefix);
                octets[idx] = this.octets[idx] & mask;
                prefix = 0;
            }
        }
        return IpAddress.fromOctets(octets);
    }
    /** Returns the broadcast address (all host bits set to 1) for this subnet. */
    broadcast() {
        let octets = [];
        let prefix = this.prefix;
        for (let idx = 0; idx < this.octets.length; idx++) {
            if (prefix >= 8) {
                octets[idx] = this.octets[idx];
                prefix -= 8;
            }
            else {
                const mask = 255 >> prefix;
                octets[idx] = this.octets[idx] | mask;
                prefix = 0;
            }
        }
        return IpAddress.fromOctets(octets);
    }
    /** The CIDR notation string for this network (e.g. `"192.168.1.0/24"`). */
    get ipnet() {
        return `${this.address}/${this.prefix}`;
    }
}
exports.IpNet = IpNet;
/** All private IPv4 ranges: loopback (127.0.0.0/8), Class A (10.0.0.0/8), Class B (172.16.0.0/12), Class C (192.168.0.0/16). */
exports.PRIVATE_IPV4_RANGES = [
    IpNet.parse('127.0.0.0/8'),
    IpNet.parse('10.0.0.0/8'),
    IpNet.parse('172.16.0.0/12'),
    IpNet.parse('192.168.0.0/16'),
];
/** IPv4 loopback network (127.0.0.0/8). */
exports.IPV4_LOOPBACK = IpNet.parse('127.0.0.0/8');
/** IPv6 loopback address (::1/128). */
exports.IPV6_LOOPBACK = IpNet.parse('::1/128');
/** IPv6 link-local network (fe80::/10). */
exports.IPV6_LINK_LOCAL = IpNet.parse('fe80::/10');
/** Carrier-Grade NAT (CGNAT) address range (100.64.0.0/10), per RFC 6598. */
exports.CGNAT = IpNet.parse('100.64.0.0/10');
//# sourceMappingURL=ip.js.map