import { Address4 } from './ipv4'; import { Address6 } from './ipv6'; import { AddressError } from './address-error'; export interface ReverseFormOptions { omitSuffix?: boolean; } /** * Returns whether this address's *network* is contained within `address`, * i.e. whether every address this one can represent also falls inside * `address`. A network wider than `address` is not contained in it, so * `10.0.0.0/8` is not in `10.0.0.0/16`. * * To ask whether the address itself falls inside a range, ignoring any CIDR * suffix it was written with, use {@link isHostInSubnet} instead. That is the * question the special-use classifiers ask. */ export function isInSubnet(this: Address4 | Address6, address: Address4 | Address6) { if (this.subnetMask < address.subnetMask) { return false; } return isHostInSubnet.call(this, address); } /** * Returns whether this address's host bits fall inside `address`, ignoring * this address's own subnet mask. * * This is the primitive the special-use classifiers (`isLoopback`, * `isPrivate`, `isLinkLocal`, `getType`, …) are built on: they answer a * question about the address, so the answer must not change with the CIDR * suffix the caller happened to write. Use this rather than * {@link isInSubnet} when classifying a single address — notably when the * address came from untrusted input and the result backs a trust-boundary * decision such as an SSRF allow/deny filter. * * An address of one family is never inside a network of the other, so an * `Address4` against an `Address6` (or the reverse) is `false`. To compare * across families, convert first: `Address6.fromAddress4()`, `to4()`, or * `toAddress4Nat64()`. */ export function isHostInSubnet(this: Address4 | Address6, address: Address4 | Address6) { // mask() is a bit string of the family's width, and the leading bits of a // 32-bit string can coincide with those of a 128-bit one (a00::1 and // 10.0.0.0/8 both mask to 00001010), so the widths must agree before the // strings are compared. if (this.binaryZeroPad().length !== address.binaryZeroPad().length) { return false; } return this.mask(address.subnetMask) === address.mask(); } /** * One parsed row of an IANA special-purpose address registry: the block, and * whether the registry marks it globally reachable (`null` when the column is * blank, in which case the containing block answers). */ export interface SpecialPurposeEntry { subnet: A; reachable: boolean | null; } /** * Returns whether the registry marks this address globally reachable: the * answer of the most specific entry containing it that has one, or `true` * when no entry contains it. */ export function isGloballyReachable( this: A, entries: ReadonlyArray>, ): boolean { let best: SpecialPurposeEntry | null = null; for (let i = 0; i < entries.length; i++) { const entry = entries[i]; if ( entry.reachable !== null && isHostInSubnet.call(this, entry.subnet) && (best === null || entry.subnet.subnetMask > best.subnet.subnetMask) ) { best = entry; } } return best === null ? true : (best.reachable as boolean); } /** * Adds `n` to `value` and returns the result, throwing `AddressError` unless * `n` is an integer and the result stays within `[0, 2**bits - 1]`. */ export function offsetBigInt( value: bigint, n: number | bigint, bits: number, family: string, ): bigint { if (typeof n === 'number' && !Number.isSafeInteger(n)) { throw new AddressError(`${family} offset must be an integer`); } if (typeof n !== 'number' && typeof n !== 'bigint') { throw new AddressError(`${family} offset must be an integer`); } const result = value + BigInt(n); if (result < BigInt(0) || result > (BigInt(1) << BigInt(bits)) - BigInt(1)) { throw new AddressError(`${family} offset leaves the address space`); } return result; } export function isCorrect(defaultBits: number) { return function isCorrectForm(this: Address4 | Address6) { if (this.addressMinusSuffix !== this.correctForm()) { return false; } if (this.subnetMask === defaultBits && !this.parsedSubnet) { return true; } return this.parsedSubnet === String(this.subnetMask); }; } /** * Returns the prefix length (number of leading 1 bits) of a contiguous * subnet mask. Throws `AddressError` if the mask is non-contiguous (e.g. * `255.0.255.0`). */ export function prefixLengthFromMask(value: bigint, totalBits: number): number { const binary = value.toString(2).padStart(totalBits, '0'); if (binary.length > totalBits) { throw new AddressError('Invalid subnet mask.'); } const firstZero = binary.indexOf('0'); if (firstZero === -1) { return totalBits; } if (binary.slice(firstZero).includes('1')) { throw new AddressError('Invalid subnet mask.'); } return firstZero; } /** * Throws `AddressError` unless `bytes` holds exactly `byteCount` integers, * each from `minimum` to 255. Pass a `minimum` of `-128` where signed bytes * are accepted and folded to unsigned, and `0` where they are not. */ export function assertByteArray( bytes: number[], byteCount: number, family: 'IPv4' | 'IPv6', minimum: number, ): void { if (bytes.length !== byteCount) { throw new AddressError(`${family} addresses require exactly ${byteCount} bytes`); } for (let i = 0; i < bytes.length; i++) { if (!Number.isInteger(bytes[i]) || bytes[i] < minimum || bytes[i] > 255) { throw new AddressError(`All bytes must be integers between ${minimum} and 255`); } } } export function numberToPaddedHex(number: number) { return number.toString(16).padStart(2, '0'); } export function stringToPaddedHex(numberString: string) { return numberToPaddedHex(parseInt(numberString, 10)); } /** * @param binaryValue Binary representation of a value (e.g. `10`) * @param position Byte position, where 0 is the least significant bit */ export function testBit(binaryValue: string, position: number): boolean { const { length } = binaryValue; if (position >= length) { return false; } const positionInString = length - position - 1; return binaryValue.substring(positionInString, positionInString + 1) === '1'; }