@fgv/ts-extras 5.1.0-5 → 5.1.0-50

package/lib/packlets/record-jar/recordJarHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordJarHelpers.js","sourceRoot":"","sources":["../../../src/packlets/record-jar/recordJarHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2022 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, fail, isKeyOf, succeed } from '@fgv/ts-utils';\nimport { FileTree } from '@fgv/ts-json-base';\n\ninterface IRecordBody {\n  body: string;\n  isContinuation: boolean;\n}\n\n/**\n * Represents a single record in a JAR file\n * @public\n */\nexport type JarRecord = Record<string, string | string[]>;\n\n/**\n * @public\n */\nexport type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];\n\n/**\n * Options for a JAR record parser.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface JarRecordParserOptions {\n  readonly arrayFields?: string[] | JarFieldPicker;\n  readonly fixedContinuationSize?: number;\n}\n\nclass RecordParser {\n  public readonly records: JarRecord[] = [];\n  public readonly options: JarRecordParserOptions;\n\n  protected _fields: JarRecord = {};\n  protected _name: string | undefined = undefined;\n  protected _body: IRecordBody | undefined = undefined;\n\n  private constructor(options?: JarRecordParserOptions) {\n    this.options = options ?? {};\n  }\n\n  public static parse(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]> {\n    return new RecordParser(options)._parse(lines);\n  }\n\n  protected static _parseRecordBody(body: string): Result<IRecordBody> {\n    const isContinuation = body.endsWith('\\\\');\n    if (isContinuation) {\n      body = body.slice(0, body.length - 1);\n    }\n    if (this._hasEscapes(body)) {\n      const result = this._replaceEscapes(body);\n      if (result.isFailure()) {\n        return fail(result.message);\n      }\n      body = result.value;\n    }\n    return succeed({ body, isContinuation });\n  }\n\n  protected static _hasEscapes(from: string): boolean {\n    return from.includes('\\\\') || from.includes('&');\n  }\n\n  protected static _replaceEscapes(body: string): Result<string> {\n    const invalid: string[] = [];\n    const escaped = body.replace(/(\\\\.)|(&#x[a-fA-F0-9]{2,6};)/g, (match) => {\n      switch (match) {\n        case '\\\\\\\\':\n          return '\\\\';\n        case '\\\\&':\n          return '&';\n        case '\\\\r':\n          return '\\r';\n        case '\\\\n':\n          return '\\n';\n        case '\\\\t':\n          return '\\t';\n      }\n      if (match.startsWith('&')) {\n        const hexCode = `0x${match.slice(3, match.length - 1)}`;\n        const charCode = Number.parseInt(hexCode, 16);\n        return String.fromCharCode(charCode);\n      }\n      invalid.push(match);\n      return '\\\\';\n    });\n    if (invalid.length > 0) {\n      return fail(`unrecognized escape \"${invalid.join(', ')}\" in record-jar body`);\n    }\n    return succeed(escaped);\n  }\n\n  protected static _applyOptions(record: JarRecord, options: JarRecordParserOptions): JarRecord {\n    if (options.arrayFields) {\n      record = { ...record }; // don't edit incoming values\n      const arrayFields = Array.isArray(options.arrayFields)\n        ? options.arrayFields\n        : options.arrayFields(record);\n\n      for (const field of arrayFields) {\n        if (isKeyOf(field, record) && typeof record[field] === 'string') {\n          const current = record[field] as string;\n          record[field] = [current];\n        }\n      }\n    }\n    return record;\n  }\n\n  protected _parse(lines: string[]): Result<JarRecord[]> {\n    for (let n = 0; n < lines.length; n++) {\n      const line = lines[n];\n      if (line.startsWith('%%') && !this._body?.isContinuation) {\n        const result = this._writePendingRecord();\n        if (result.isFailure()) {\n          return fail(`${n}: ${result.message}`);\n        }\n      } else if (/^\\s*$/.test(line)) {\n        // ignore blank lines but cancel continuation\n        if (this._body) {\n          this._body.isContinuation = false;\n        }\n        continue;\n      } else if (this._body?.isContinuation || /^\\s+/.test(line)) {\n        // explicit continuation on previous line or implicit starts with whitespace\n        if (this._body === undefined) {\n          return fail(`${n}: continuation (\"${line}\") without prior value.`);\n        }\n        const result = this._parseContinuation(line);\n        if (result.isFailure()) {\n          return fail(`${n}: ${result.message}`);\n        }\n        this._body = result.value;\n      } else {\n        const result = this._parseField(line);\n        if (result.isFailure()) {\n          return fail(`${n}: ${result.message}`);\n        }\n      }\n    }\n\n    const result = this._writePendingRecord();\n    if (result.isFailure()) {\n      return fail(`${lines.length}: ${result.message}`);\n    }\n    return succeed(this.records);\n  }\n\n  protected _parseField(line: string): Result<boolean> {\n    const separatorIndex = line.indexOf(':');\n    if (separatorIndex < 1) {\n      return fail(`malformed line (\"${line}\") in record-jar.`);\n    }\n    const parts = [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)];\n\n    return this._writePendingField().onSuccess(() => {\n      this._name = parts[0].trimEnd();\n      return RecordParser._parseRecordBody(parts[1].trim()).onSuccess((body) => {\n        this._body = body;\n        return succeed(true);\n      });\n    });\n  }\n\n  protected _parseContinuation(line: string): Result<IRecordBody> {\n    let trimmed = line.trim();\n    if (!this._body!.isContinuation) {\n      /* c8 ignore next - functional code tested but coverage intermittently missed */\n      const fixedSize = this.options?.fixedContinuationSize ?? 0;\n      if (fixedSize > 0) {\n        if (trimmed.length < line.length - fixedSize) {\n          // oops, took too much\n          trimmed = line.slice(fixedSize);\n        }\n      }\n    }\n    return RecordParser._parseRecordBody(trimmed).onSuccess((newBody) => {\n      return succeed({\n        body: `${this._body!.body}${newBody.body}`,\n        isContinuation: newBody.isContinuation\n      });\n    });\n  }\n\n  protected _havePendingRecord(): boolean {\n    return Object.keys(this._fields).length > 0;\n  }\n\n  protected _writePendingRecord(): Result<JarRecord | undefined> {\n    return this._writePendingField().onSuccess(() => {\n      let record = this._havePendingRecord() ? this._fields : undefined;\n      if (record !== undefined) {\n        record = RecordParser._applyOptions(record, this.options);\n        this.records.push(record);\n        this._fields = {};\n      }\n      return succeed(undefined);\n    });\n  }\n\n  protected _writePendingField(): Result<boolean> {\n    if (this._name !== undefined) {\n      if (this._body!.body.length < 1) {\n        return fail('empty body value not allowed');\n      }\n      if (!isKeyOf(this._name, this._fields)) {\n        this._fields[this._name] = this._body!.body;\n      } else if (typeof this._fields[this._name] === 'string') {\n        const current = this._fields[this._name] as string;\n        this._fields[this._name] = [current, this._body!.body];\n      } else {\n        const current = this._fields[this._name] as string[];\n        current.push(this._body!.body);\n      }\n      this._name = undefined;\n      this._body = undefined;\n    }\n    return succeed(true);\n  }\n}\n\n/**\n * Reads a record-jar from an array of strings, each of which represents one\n * line in the source file.\n * @param lines - the array of strings to be parsed\n * @param options - Optional parser configuration\n * @returns a corresponding array of `Record<string, string>`\n * @public\n */\nexport function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]> {\n  return RecordParser.parse(lines, options);\n}\n\n/**\n * Reads a record-jar file from a FileTree.\n * @param fileTree - The FileTree to read from.\n * @param filePath - Path of the file within the tree.\n * @param options - Optional parser configuration\n * @returns The contents of the file as an array of `Record<string, string>`\n * @see https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01\n * @public\n */\nexport function readRecordJarFromTree(\n  fileTree: FileTree.FileTree,\n  filePath: string,\n  options?: JarRecordParserOptions\n): Result<JarRecord[]> {\n  return fileTree\n    .getFile(filePath)\n    .onSuccess((file) => file.getRawContents())\n    .onSuccess((contents) => {\n      const lines = contents.split(/\\r?\\n/);\n      return parseRecordJarLines(lines, options);\n    });\n}\n"]}

package/lib/packlets/safer-fetch/addressClassification.d.ts

@@ -0,0 +1,144 @@
+import { type Result } from '@fgv/ts-utils';
+/**
+ * The address family of a parsed IP address literal.
+ * @public
+ */
+export type AddressFamily = 'ipv4' | 'ipv6';
+/**
+ * The security-relevant classification of an IP address.
+ *
+ * `'public'` is the only classification that describes an address which is
+ * globally routable on the public internet; every other value names a
+ * special-purpose range that a server-side fetch reaching untrusted input
+ * should not be able to reach by default.
+ *
+ * @public
+ */
+export type AddressClassification = 
+/** Globally routable unicast — the only classification a default guard permits. */
+'public'
+/** `0.0.0.0/8` and `::` — "this host on this network"; routes to localhost on Linux. */
+ | 'unspecified'
+/** `127.0.0.0/8` and `::1`. */
+ | 'loopback'
+/**
+ * `169.254.0.0/16` and `fe80::/10`. The IPv4 range contains the cloud
+ * instance-metadata endpoint (`169.254.169.254`) and is the single
+ * highest-value SSRF target.
+ */
+ | 'link-local'
+/** RFC 1918 — `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`. */
+ | 'private'
+/** RFC 4193 IPv6 unique-local — `fc00::/7`. */
+ | 'unique-local'
+/** RFC 6598 carrier-grade NAT — `100.64.0.0/10`. Frequently carrier or container internal. */
+ | 'carrier-grade-nat'
+/** RFC 2544 benchmarking — `198.18.0.0/15`. */
+ | 'benchmarking'
+/** Documentation ranges — `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`. */
+ | 'documentation'
+/** IETF protocol assignments — `192.0.0.0/24` and `2001::/23`. */
+ | 'protocol-assignment'
+/** `224.0.0.0/4` and `ff00::/8`. */
+ | 'multicast'
+/** `255.255.255.255/32`. */
+ | 'broadcast'
+/** Every other special-purpose or future-use range (e.g. `240.0.0.0/4`, `fec0::/10`). */
+ | 'reserved';
+/**
+ * The way an IPv6 address carried the IPv4 address whose classification was used.
+ *
+ * Each of these is a documented SSRF bypass: an address such as
+ * `::ffff:169.254.169.254` is an IPv6 address by family, but the address the
+ * connection actually reaches is the embedded IPv4 one, so the embedded
+ * address is what must be classified.
+ *
+ * @public
+ */
+export type Ipv4EmbeddingKind = 
+/** `::ffff:0:0/96` — the IPv4-mapped IPv6 form. */
+'ipv4-mapped'
+/** `::/96` — the deprecated (RFC 4291) IPv4-compatible form. */
+ | 'ipv4-compatible'
+/** `64:ff9b::/96` — the RFC 6052 well-known NAT64 prefix. */
+ | 'nat64'
+/** `2002::/16` — the RFC 3056 6to4 form, whose IPv4 lives in bits 16..47. */
+ | '6to4';
+/**
+ * The IPv4 address an IPv6 address embedded, and the way it embedded it.
+ * @public
+ */
+export interface IEmbeddedIpv4 {
+    /** The encoding that carried the IPv4 address. */
+    readonly kind: Ipv4EmbeddingKind;
+    /** The dotted-quad form of the embedded IPv4 address. */
+    readonly address: string;
+}
+/**
+ * The result of classifying a single IP address literal.
+ * @public
+ */
+export interface IClassifiedAddress {
+    /** The address exactly as supplied to {@link classifyAddress}. */
+    readonly address: string;
+    /**
+     * A canonical textual form of the address: dotted-quad for IPv4, and
+     * lowercase RFC 5952 hex-group form (with `::` run compression) for IPv6.
+     * Note that IPv6 addresses embedding an IPv4 address canonicalize to their
+     * hex-group form (`::ffff:a9fe:a9fe`), not to the dotted-quad mixed form;
+     * `embeddedIpv4` carries the readable IPv4 value.
+     */
+    readonly canonical: string;
+    /** The address family of the literal as supplied — never the embedded family. */
+    readonly family: AddressFamily;
+    /**
+     * The classification used for policy decisions. For an IPv6 address that
+     * embeds an IPv4 address, this is the classification of the *embedded* IPv4
+     * address.
+     */
+    readonly classification: AddressClassification;
+    /**
+     * Present exactly when `classification` was derived from an IPv4 address
+     * embedded in this IPv6 address, and absent otherwise.
+     */
+    readonly embeddedIpv4?: IEmbeddedIpv4;
+}
+/**
+ * Classifies a single IP address literal.
+ *
+ * The function is pure, synchronous, and deterministic — it performs no name
+ * resolution and no I/O. Input that is not an IP address literal (a DNS
+ * hostname, for instance) fails; callers that accept hostnames should treat a
+ * failure here as "not a literal" and resolve the name, then classify each
+ * resolved address.
+ *
+ * Accepted forms:
+ *
+ * - dotted-quad IPv4 (`169.254.169.254`)
+ * - the shortened and non-decimal IPv4 forms the WHATWG URL parser accepts
+ *   (`127.1`, `2130706433`, `0177.0.0.1`, `0x7f.1`)
+ * - IPv6, with or without `::` compression, optionally bracketed as a URL
+ *   `hostname` is (`[::1]`) and optionally carrying a zone id (`fe80::1%eth0`)
+ * - IPv6 forms that embed an IPv4 address — IPv4-mapped, IPv4-compatible,
+ *   NAT64 and 6to4 — which are classified by their embedded IPv4 address
+ *
+ * A trailing dot is accepted on an IPv4 literal (`127.0.0.1.`), matching URL
+ * hostname normalization.
+ *
+ * **Classify a URL's `hostname`, never the raw URL text.** This function does
+ * not apply IDNA/Unicode normalization, and that step is not cosmetic: the
+ * platform's URL parser reads `http://１２７.０.０.１/`, `http://127。0。0。1/` and
+ * even `http://⑫7.0.0.1/` as the host `127.0.0.1`, because IDNA normalizes
+ * fullwidth digits, the ideographic full stop and circled numbers to their
+ * ASCII equivalents. Handed one of those strings directly this function fails —
+ * which is fail-closed, but only because the caller is then expected to treat
+ * "not a literal" as "resolve it as a name". Reading `new URL(...).hostname`
+ * gets the normalization for free and is the only supported use.
+ *
+ * @param address - the address literal to classify.
+ * @returns `Success` with the {@link IClassifiedAddress | classification},
+ * or `Failure` if the supplied text is not a well-formed IP address literal.
+ * @public
+ */
+export declare function classifyAddress(address: string): Result<IClassifiedAddress>;
+//# sourceMappingURL=addressClassification.d.ts.map

package/lib/packlets/safer-fetch/addressClassification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressClassification.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/addressClassification.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,eAAe,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB;AAC/B,mFAAmF;AACjF,QAAQ;AACV,wFAAwF;GACtF,aAAa;AACf,+BAA+B;GAC7B,UAAU;AACZ;;;;GAIG;GACD,YAAY;AACd,kEAAkE;GAChE,SAAS;AACX,+CAA+C;GAC7C,cAAc;AAChB,8FAA8F;GAC5F,mBAAmB;AACrB,+CAA+C;GAC7C,cAAc;AAChB,mGAAmG;GACjG,eAAe;AACjB,kEAAkE;GAChE,qBAAqB;AACvB,oCAAoC;GAClC,WAAW;AACb,4BAA4B;GAC1B,WAAW;AACb,yFAAyF;GACvF,UAAU,CAAC;AAEf;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB;AAC3B,mDAAmD;AACjD,aAAa;AACf,gEAAgE;GAC9D,iBAAiB;AACnB,6DAA6D;GAC3D,OAAO;AACT,6EAA6E;GAC3E,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;CACvC;AAsZD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,kBAAkB,CAAC,CA0B3E"}

package/lib/packlets/safer-fetch/addressClassification.js

@@ -0,0 +1,441 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyAddress = classifyAddress;
+// Address classification is prefix arithmetic: every range test is a mask and a
+// compare, and every IPv6 group/byte conversion is a shift. Spelling those as
+// arithmetic instead would be strictly harder to audit against the RFCs, which
+// is the opposite of what this file needs. The repo already takes per-site
+// disables for the same reason in `crypto-utils/keystore` and `ts-random`.
+/* eslint-disable no-bitwise */
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * IPv4 special-purpose ranges, most specific first. The broadcast address is
+ * listed ahead of `240.0.0.0/4` because it falls inside it.
+ */
+const IPV4_RANGES = [
+    { network: 0xffffffff, prefixLength: 32, classification: 'broadcast' },
+    { network: 0x00000000, prefixLength: 8, classification: 'unspecified' },
+    { network: 0x0a000000, prefixLength: 8, classification: 'private' },
+    { network: 0x64400000, prefixLength: 10, classification: 'carrier-grade-nat' },
+    { network: 0x7f000000, prefixLength: 8, classification: 'loopback' },
+    { network: 0xa9fe0000, prefixLength: 16, classification: 'link-local' },
+    { network: 0xac100000, prefixLength: 12, classification: 'private' },
+    { network: 0xc0000000, prefixLength: 24, classification: 'protocol-assignment' },
+    { network: 0xc0000200, prefixLength: 24, classification: 'documentation' },
+    { network: 0xc0586300, prefixLength: 24, classification: 'reserved' },
+    { network: 0xc0a80000, prefixLength: 16, classification: 'private' },
+    { network: 0xc6120000, prefixLength: 15, classification: 'benchmarking' },
+    { network: 0xc6336400, prefixLength: 24, classification: 'documentation' },
+    { network: 0xcb007100, prefixLength: 24, classification: 'documentation' },
+    { network: 0xe0000000, prefixLength: 4, classification: 'multicast' },
+    { network: 0xf0000000, prefixLength: 4, classification: 'reserved' }
+];
+/**
+ * IPv6 special-purpose ranges, most specific first. Ranges whose addresses
+ * embed an IPv4 address are handled separately, before this table is consulted,
+ * and anything outside global unicast (`2000::/3`) that matches nothing here is
+ * classified `'reserved'` — so this table only needs to name the ranges that
+ * deserve a more specific classification than that fallback gives them.
+ */
+const IPV6_RANGES = [
+    { prefix: [0x20, 0x01, 0x0d, 0xb8], prefixLength: 32, classification: 'documentation' },
+    { prefix: [0x20, 0x01, 0x00], prefixLength: 23, classification: 'protocol-assignment' },
+    { prefix: [0x3f, 0xff, 0x00], prefixLength: 20, classification: 'documentation' },
+    { prefix: [0xfc], prefixLength: 7, classification: 'unique-local' },
+    { prefix: [0xfe, 0x80], prefixLength: 10, classification: 'link-local' },
+    { prefix: [0xff], prefixLength: 8, classification: 'multicast' }
+];
+/** The first three bits of a global unicast IPv6 address (`2000::/3`). */
+const IPV6_GLOBAL_UNICAST_MASK = 0xe0;
+const IPV6_GLOBAL_UNICAST_VALUE = 0x20;
+/**
+ * Parses one component of an IPv4 literal using `inet_aton` conventions: a
+ * `0x`/`0X` prefix selects hexadecimal, an otherwise-leading `0` selects octal,
+ * and anything else is decimal.
+ *
+ * This is deliberately permissive about *radix* because the WHATWG URL parser
+ * is: `http://0177.0.0.1/` and `http://2130706433/` are both `127.0.0.1`, and a
+ * classifier that only understands dotted decimal is bypassed by either.
+ */
+function parseIpv4Component(text) {
+    if (text.length === 0) {
+        return undefined;
+    }
+    let radix = 10;
+    let digits = text;
+    if (text.length > 1 && (text[1] === 'x' || text[1] === 'X') && text[0] === '0') {
+        radix = 16;
+        digits = text.slice(2);
+    }
+    else if (text.length > 1 && text[0] === '0') {
+        radix = 8;
+        digits = text.slice(1);
+    }
+    // The WHATWG IPv4 number parser returns 0 when stripping the radix prefix
+    // leaves nothing behind, so a bare `0x` is zero: `127.0x.1` is `127.0.0.1`.
+    // Rejecting it here would leave a live encoding bypass.
+    if (digits.length === 0) {
+        return 0;
+    }
+    const allowed = radix === 16 ? /^[0-9a-fA-F]+$/ : radix === 8 ? /^[0-7]+$/ : /^[0-9]+$/;
+    if (!allowed.test(digits)) {
+        return undefined;
+    }
+    const value = Number.parseInt(digits, radix);
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+/**
+ * Parses an IPv4 literal in any of the forms the platform URL parser accepts
+ * (`a.b.c.d`, `a.b.c`, `a.b`, `a`), returning the address as an unsigned 32-bit
+ * value. The final component absorbs all remaining bytes, so `127.1` is
+ * `127.0.0.1` and `2130706433` is also `127.0.0.1`.
+ */
+function parseIpv4(text) {
+    const parts = text.split('.');
+    if (parts.length > 4) {
+        return undefined;
+    }
+    const values = [];
+    for (const part of parts) {
+        const value = parseIpv4Component(part);
+        if (value === undefined) {
+            return undefined;
+        }
+        values.push(value);
+    }
+    const leading = values.length - 1;
+    for (let i = 0; i < leading; i++) {
+        if (values[i] > 0xff) {
+            return undefined;
+        }
+    }
+    if (values[leading] > Math.pow(256, 4 - leading) - 1) {
+        return undefined;
+    }
+    let address = values[leading];
+    for (let i = 0; i < leading; i++) {
+        address += values[i] * Math.pow(256, 3 - i);
+    }
+    return address >>> 0;
+}
+/**
+ * Parses a strict dotted-quad IPv4 literal — exactly four decimal components,
+ * each `0..255`, with no octal or hexadecimal forms. This is the grammar RFC
+ * 4291 permits for the IPv4 tail of an IPv6 literal, and it is deliberately
+ * stricter than {@link parseIpv4}: an unparseable literal fails closed.
+ */
+function parseStrictDottedQuad(text) {
+    const parts = text.split('.');
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    let address = 0;
+    for (const part of parts) {
+        if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) {
+            return undefined;
+        }
+        const value = Number.parseInt(part, 10);
+        if (value > 0xff) {
+            return undefined;
+        }
+        address = address * 256 + value;
+    }
+    return address >>> 0;
+}
+/**
+ * Parses a colon-separated run of IPv6 groups, allowing a trailing embedded
+ * dotted-quad IPv4 literal which expands to the final two groups.
+ *
+ * @param allowEmbeddedIpv4 - whether this run may end in a dotted-quad IPv4
+ * literal. Only the run that ends the whole address may, so the run *before* a
+ * `::` never does: `1.2.3.4::` is malformed, not `102:304::`.
+ */
+function parseIpv6Groups(text, allowEmbeddedIpv4) {
+    if (text.length === 0) {
+        return [];
+    }
+    const parts = text.split(':');
+    const groups = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part.indexOf('.') >= 0) {
+            if (!allowEmbeddedIpv4 || i !== parts.length - 1) {
+                return undefined;
+            }
+            const embedded = parseStrictDottedQuad(part);
+            if (embedded === undefined) {
+                return undefined;
+            }
+            groups.push((embedded >>> 16) & 0xffff, embedded & 0xffff);
+            continue;
+        }
+        if (!/^[0-9a-fA-F]{1,4}$/.test(part)) {
+            return undefined;
+        }
+        groups.push(Number.parseInt(part, 16));
+    }
+    return groups;
+}
+/**
+ * Parses an IPv6 literal into its 16 constituent bytes.
+ */
+function parseIpv6(text) {
+    const doubleColon = text.indexOf('::');
+    let groups;
+    if (doubleColon >= 0) {
+        if (text.indexOf('::', doubleColon + 1) >= 0) {
+            return undefined;
+        }
+        const head = parseIpv6Groups(text.slice(0, doubleColon), false);
+        const tail = parseIpv6Groups(text.slice(doubleColon + 2), true);
+        if (head === undefined || tail === undefined) {
+            return undefined;
+        }
+        const elided = 8 - head.length - tail.length;
+        if (elided < 1) {
+            return undefined;
+        }
+        groups = head.concat(new Array(elided).fill(0), tail);
+    }
+    else {
+        groups = parseIpv6Groups(text, true);
+        if (groups === undefined || groups.length !== 8) {
+            return undefined;
+        }
+    }
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 8; i++) {
+        bytes[i * 2] = (groups[i] >>> 8) & 0xff;
+        bytes[i * 2 + 1] = groups[i] & 0xff;
+    }
+    return bytes;
+}
+function ipv4ToString(address) {
+    return [(address >>> 24) & 0xff, (address >>> 16) & 0xff, (address >>> 8) & 0xff, address & 0xff].join('.');
+}
+/**
+ * Renders the RFC 5952 canonical text form of an IPv6 address: lowercase, no
+ * leading zeros in a group, and the leftmost longest run of two or more
+ * all-zero groups replaced by `::`.
+ */
+function ipv6ToString(bytes) {
+    const groups = [];
+    for (let i = 0; i < 8; i++) {
+        groups.push((bytes[i * 2] << 8) | bytes[i * 2 + 1]);
+    }
+    let bestStart = -1;
+    let bestLength = 0;
+    let runStart = -1;
+    let runLength = 0;
+    for (let i = 0; i < 8; i++) {
+        if (groups[i] === 0) {
+            if (runStart < 0) {
+                runStart = i;
+                runLength = 0;
+            }
+            runLength++;
+            if (runLength > bestLength) {
+                bestStart = runStart;
+                bestLength = runLength;
+            }
+        }
+        else {
+            runStart = -1;
+            runLength = 0;
+        }
+    }
+    const rendered = groups.map((g) => g.toString(16));
+    if (bestLength < 2) {
+        return rendered.join(':');
+    }
+    const head = rendered.slice(0, bestStart).join(':');
+    const tail = rendered.slice(bestStart + bestLength).join(':');
+    return `${head}::${tail}`;
+}
+function classifyIpv4Value(address) {
+    for (const range of IPV4_RANGES) {
+        const mask = (0xffffffff << (32 - range.prefixLength)) >>> 0;
+        if ((address & mask) >>> 0 === range.network) {
+            return range.classification;
+        }
+    }
+    return 'public';
+}
+function matchesIpv6Range(bytes, range) {
+    const fullBytes = range.prefixLength >>> 3;
+    for (let i = 0; i < fullBytes; i++) {
+        if (bytes[i] !== range.prefix[i]) {
+            return false;
+        }
+    }
+    const remainingBits = range.prefixLength & 7;
+    if (remainingBits === 0) {
+        return true;
+    }
+    const mask = (0xff << (8 - remainingBits)) & 0xff;
+    return (bytes[fullBytes] & mask) === (range.prefix[fullBytes] & mask);
+}
+function allZero(bytes, start, end) {
+    for (let i = start; i < end; i++) {
+        if (bytes[i] !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+function readIpv4At(bytes, offset) {
+    return (((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0);
+}
+/**
+ * Detects the IPv4 address embedded in an IPv6 address, if any. `::` and `::1`
+ * are excluded before the IPv4-compatible check so that the unspecified and
+ * loopback addresses keep their own classifications.
+ */
+function detectIpv6Embedding(bytes) {
+    if (allZero(bytes, 0, 10) && bytes[10] === 0xff && bytes[11] === 0xff) {
+        return { kind: 'ipv4-mapped', value: readIpv4At(bytes, 12) };
+    }
+    if (bytes[0] === 0x00 &&
+        bytes[1] === 0x64 &&
+        bytes[2] === 0xff &&
+        bytes[3] === 0x9b &&
+        allZero(bytes, 4, 12)) {
+        return { kind: 'nat64', value: readIpv4At(bytes, 12) };
+    }
+    if (bytes[0] === 0x20 && bytes[1] === 0x02) {
+        return { kind: '6to4', value: readIpv4At(bytes, 2) };
+    }
+    if (allZero(bytes, 0, 12)) {
+        return { kind: 'ipv4-compatible', value: readIpv4At(bytes, 12) };
+    }
+    return undefined;
+}
+function classifyIpv6Bytes(bytes) {
+    const canonical = ipv6ToString(bytes);
+    if (allZero(bytes, 0, 16)) {
+        return { address: canonical, canonical, family: 'ipv6', classification: 'unspecified' };
+    }
+    if (allZero(bytes, 0, 15) && bytes[15] === 0x01) {
+        return { address: canonical, canonical, family: 'ipv6', classification: 'loopback' };
+    }
+    const embedding = detectIpv6Embedding(bytes);
+    if (embedding !== undefined) {
+        return {
+            address: canonical,
+            canonical,
+            family: 'ipv6',
+            classification: classifyIpv4Value(embedding.value),
+            embeddedIpv4: { kind: embedding.kind, address: ipv4ToString(embedding.value) }
+        };
+    }
+    for (const range of IPV6_RANGES) {
+        if (matchesIpv6Range(bytes, range)) {
+            return { address: canonical, canonical, family: 'ipv6', classification: range.classification };
+        }
+    }
+    // Only `2000::/3` is assigned as global unicast. Everything else that reached
+    // this point is unassigned or reserved for future use, so it is never public.
+    const classification = (bytes[0] & IPV6_GLOBAL_UNICAST_MASK) === IPV6_GLOBAL_UNICAST_VALUE ? 'public' : 'reserved';
+    return { address: canonical, canonical, family: 'ipv6', classification };
+}
+/**
+ * Normalizes the textual forms an address can arrive in before parsing:
+ * surrounding whitespace and the square brackets a URL `hostname` carries for
+ * an IPv6 literal. A zone identifier is *not* stripped here — it is stripped on
+ * the IPv6 path only, because `8.8.8.8%something` is not an address with a zone
+ * and must fail rather than be read as `8.8.8.8`.
+ */
+function normalizeAddressText(address) {
+    const text = address.trim();
+    if (text.length > 1 && text[0] === '[' && text[text.length - 1] === ']') {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+/** Strips an IPv6 zone identifier (`fe80::1%eth0`). */
+function stripIpv6Zone(text) {
+    const zone = text.indexOf('%');
+    return zone >= 0 ? text.slice(0, zone) : text;
+}
+/**
+ * Classifies a single IP address literal.
+ *
+ * The function is pure, synchronous, and deterministic — it performs no name
+ * resolution and no I/O. Input that is not an IP address literal (a DNS
+ * hostname, for instance) fails; callers that accept hostnames should treat a
+ * failure here as "not a literal" and resolve the name, then classify each
+ * resolved address.
+ *
+ * Accepted forms:
+ *
+ * - dotted-quad IPv4 (`169.254.169.254`)
+ * - the shortened and non-decimal IPv4 forms the WHATWG URL parser accepts
+ *   (`127.1`, `2130706433`, `0177.0.0.1`, `0x7f.1`)
+ * - IPv6, with or without `::` compression, optionally bracketed as a URL
+ *   `hostname` is (`[::1]`) and optionally carrying a zone id (`fe80::1%eth0`)
+ * - IPv6 forms that embed an IPv4 address — IPv4-mapped, IPv4-compatible,
+ *   NAT64 and 6to4 — which are classified by their embedded IPv4 address
+ *
+ * A trailing dot is accepted on an IPv4 literal (`127.0.0.1.`), matching URL
+ * hostname normalization.
+ *
+ * **Classify a URL's `hostname`, never the raw URL text.** This function does
+ * not apply IDNA/Unicode normalization, and that step is not cosmetic: the
+ * platform's URL parser reads `http://１２７.０.０.１/`, `http://127。0。0。1/` and
+ * even `http://⑫7.0.0.1/` as the host `127.0.0.1`, because IDNA normalizes
+ * fullwidth digits, the ideographic full stop and circled numbers to their
+ * ASCII equivalents. Handed one of those strings directly this function fails —
+ * which is fail-closed, but only because the caller is then expected to treat
+ * "not a literal" as "resolve it as a name". Reading `new URL(...).hostname`
+ * gets the normalization for free and is the only supported use.
+ *
+ * @param address - the address literal to classify.
+ * @returns `Success` with the {@link IClassifiedAddress | classification},
+ * or `Failure` if the supplied text is not a well-formed IP address literal.
+ * @public
+ */
+function classifyAddress(address) {
+    const text = normalizeAddressText(address);
+    if (text.length === 0) {
+        return (0, ts_utils_1.fail)(`"${address}": not a valid IP address literal (empty)`);
+    }
+    if (text.indexOf(':') >= 0) {
+        const bytes = parseIpv6(stripIpv6Zone(text));
+        if (bytes === undefined) {
+            return (0, ts_utils_1.fail)(`"${address}": not a valid IPv6 address literal`);
+        }
+        return (0, ts_utils_1.succeed)(Object.assign(Object.assign({}, classifyIpv6Bytes(bytes)), { address }));
+    }
+    const v4Text = text.length > 1 && text[text.length - 1] === '.' ? text.slice(0, -1) : text;
+    const value = parseIpv4(v4Text);
+    if (value === undefined) {
+        return (0, ts_utils_1.fail)(`"${address}": not a valid IP address literal`);
+    }
+    const canonical = ipv4ToString(value);
+    return (0, ts_utils_1.succeed)({
+        address,
+        canonical,
+        family: 'ipv4',
+        classification: classifyIpv4Value(value)
+    });
+}
+//# sourceMappingURL=addressClassification.js.map