@fgv/ts-extras 5.1.0-46 → 5.1.0-48

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Erik Fortune
+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

package/README.md

@@ -86,6 +86,96 @@ const rawContents = file.value.getRawContents(); // Raw string
 
 **Note**: This implementation uses Node.js-specific dependencies (AdmZip, Buffer). For browser environments, see the browser-specific implementations in individual projects.
 
+### Safer Fetch
+
+An HTTP fetch primitive with an explicit threat model, exported from `@fgv/ts-extras/safer-fetch`.
+It is deliberately **not** a thin boundary over an upstream library — `fetch` is a platform global
+and there is nothing to wrap. The opinion is the product: the deadlines, the scheme refusal, the
+streaming size cap, the redirect posture, and the required address guard are the deliverable.
+
+```typescript
+import {
+  saferFetchJson,
+  blockPrivateNetworks,
+  allowContentTypes
+} from '@fgv/ts-extras/safer-fetch';
+
+const result = await saferFetchJson('https://api.example.com/thing', {
+  // Required, with no default: omitting it is a compile error, so no call site can inherit a
+  // guarantee it was never given. Every call site's posture is greppable in one search.
+  addressGuard: blockPrivateNetworks(),
+  responseHeadersGuard: allowContentTypes(['application/json']).orThrow(),
+  timeoutMs: 10_000,
+  maxResponseBytes: 1024 * 1024,
+  retry: { attempts: 2 }   // off unless asked for
+});
+```
+
+`addressGuard` has no default. `allowAnyAddress()` is the named, deliberately uncomfortable
+opt-out, and it is the only honest choice in a browser.
+
+#### The guarantee table
+
+This table is the artifact that keeps the primitive honest. It is reproduced verbatim in
+`@fgv/ts-web-extras`'s README.
+
+| Property | Node (`@fgv/ts-extras/safer-fetch`) | Browser (`@fgv/ts-web-extras`) |
+|---|---|---|
+| Overall + headers deadline | ✅ | ✅ |
+| Streaming size cap, enforced during read | ✅ | ✅ |
+| Content-type gate before body read | ✅ | ✅ |
+| Structured failure taxonomy | ✅ | ✅ |
+| Retry with idempotency + budget rules | ✅ | ✅ |
+| Scheme allowlist on URL₀ | ✅ | ✅ |
+| Host / port allowlist on URL₀ | ✅ (`blockPrivateNetworks({ allowHosts, allowPorts })`) | ✅ (caller-supplied guard) |
+| **Resolved-address (private-IP) guard** | ✅ | ❌ **impossible** — no DNS API |
+| **Per-hop revalidation of redirects** | ✅ | ❌ **impossible** — opaque redirect |
+| **Credential stripping on cross-origin hop** | ✅ | n/a — platform does it |
+| Reject-all-redirects mode | ✅ | ✅ (enforced; surfaces as `'redirect-opaque'`) |
+| DNS-rebinding resistance | ❌ **documented limit** | ❌ |
+
+Two rows differ from the design document they came from, and the difference is deliberate:
+
+- **Host / port allowlist.** `blockPrivateNetworks` takes `allowHosts` / `allowPorts` /
+  `allowInsecureHttp`. A host allowlist is the *recommended* posture, because it shrinks the
+  DNS-rebinding exposure below to "an allowlisted host's own resolver is hostile". `https:` is
+  required unless `allowInsecureHttp` is set; there is no default port restriction, since a
+  default of `{443}` would reject the very common `:8443` public endpoint with a failure that
+  reads as an SSRF block.
+- **Reject-all-redirects.** Both runtimes use `redirect: 'manual'` and reject the redirect
+  themselves. The *guarantee* is identical; the failure **reason** is not — Node reports
+  `'redirect-rejected'` with the status, a browser reports `'redirect-opaque'` because an opaque
+  response has no status to report. Callers branching on the reason under `'reject'` must handle
+  both.
+
+#### Stated limits
+
+Each of these is a hole in a guarantee this package makes, and each is documented rather than
+implied.
+
+- **DNS rebinding** — the guard validates a resolved address and the transport then re-resolves,
+  so hostile DNS can answer the two lookups differently. Closing it needs a pinning transport;
+  the seam (`IGuardVerdict.pinnedAddress` + `IFetchTransport`) exists, and
+  `platformFetchTransport` **fails** rather than silently ignoring a pin it cannot honor. A
+  strict `allowHosts` list is the recommended mitigation.
+- **The browser has no SSRF guard at all** — not a partial guarantee, an absent one. See the
+  table.
+- **Time-of-check/time-of-use beyond DNS** — the guard authorizes a *destination*, never the
+  *content* that comes back.
+- **The failure taxonomy is an information-disclosure surface** — a `'blocked-by-guard'` detail
+  names the URL, the hop and the guard, which is an internal-network scanning oracle if echoed
+  to an untrusted caller. Log it; return a coarse code.
+- **No egress accounting** — no per-host rate limiting or quota. A retry policy is not a rate
+  limiter.
+- **Loopback is blocked by default**, including for this repo's own local-development path. A
+  caller who wants it says so, and every deviation is independently greppable:
+  `blockPrivateNetworks({ allowLoopback: true, allowInsecureHttp: true, allowHosts: ['localhost'], allowPorts: [11434] })`.
+- **HTTP semantics not implemented** — no cookie jar, no cache, no conditional requests, no
+  proxy configuration beyond what the platform picks up from the environment.
+
+If your deployment has an egress proxy or firewall, that control is strictly stronger than this
+one; this is defense in depth for deployments that do not.
+
 ### Converters  
 
 Type-safe data conversion utilities for transforming between different data formats while maintaining type safety.

package/dist/index.browser.js

@@ -31,11 +31,13 @@ import * as Hash from './packlets/hash/index.browser';
 import * as Mustache from './packlets/mustache';
 // eslint-disable-next-line @rushstack/packlets/mechanics
 import * as RecordJar from './packlets/record-jar/index.browser';
+// eslint-disable-next-line @rushstack/packlets/mechanics
+import * as SaferFetch from './packlets/safer-fetch/index.browser';
 import * as Yaml from './packlets/yaml';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
 // Browser-safe exports - Node.js crypto-based providers excluded
 // Use BrowserCryptoProvider from @fgv/ts-web-extras for browser crypto
-export { AiAssist, Converters, CryptoUtils, CryptoUtils as Crypto, Csv, Experimental, Hash, Mustache, RecordJar, Yaml, ZipFileTree };
+export { AiAssist, Converters, CryptoUtils, CryptoUtils as Crypto, Csv, Experimental, Hash, Mustache, RecordJar, SaferFetch, Yaml, ZipFileTree };
 /* c8 ignore stop */
 //# sourceMappingURL=index.browser.js.map

package/dist/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,kFAAkF;AAClF,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,yDAAyD;AACzD,OAAO,KAAK,WAAW,MAAM,uCAAuC,CAAC;AACrE,yDAAyD;AACzD,OAAO,KAAK,GAAG,MAAM,8BAA8B,CAAC;AACpD,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,yDAAyD;AACzD,OAAO,KAAK,IAAI,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,yDAAyD;AACzD,OAAO,KAAK,SAAS,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,iEAAiE;AACjE,uEAAuE;AACvE,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,IAAI,MAAM,EACrB,GAAG,EACH,YAAY,EACZ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,WAAW,EACZ,CAAC;AACF,oBAAoB","sourcesContent":["/*\n * Copyright (c) 2020 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\n/* c8 ignore start - Browser-specific export used conditionally in package.json */\nimport * as AiAssist from './packlets/ai-assist';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as CryptoUtils from './packlets/crypto-utils/index.browser';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Csv from './packlets/csv/index.browser';\nimport * as Experimental from './packlets/experimental';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Hash from './packlets/hash/index.browser';\nimport * as Mustache from './packlets/mustache';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as RecordJar from './packlets/record-jar/index.browser';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\n// Browser-safe exports - Node.js crypto-based providers excluded\n// Use BrowserCryptoProvider from @fgv/ts-web-extras for browser crypto\nexport {\n  AiAssist,\n  Converters,\n  CryptoUtils,\n  CryptoUtils as Crypto,\n  Csv,\n  Experimental,\n  Hash,\n  Mustache,\n  RecordJar,\n  Yaml,\n  ZipFileTree\n};\n/* c8 ignore stop */\n"]}
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,kFAAkF;AAClF,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,yDAAyD;AACzD,OAAO,KAAK,WAAW,MAAM,uCAAuC,CAAC;AACrE,yDAAyD;AACzD,OAAO,KAAK,GAAG,MAAM,8BAA8B,CAAC;AACpD,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,yDAAyD;AACzD,OAAO,KAAK,IAAI,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,yDAAyD;AACzD,OAAO,KAAK,SAAS,MAAM,qCAAqC,CAAC;AACjE,yDAAyD;AACzD,OAAO,KAAK,UAAU,MAAM,sCAAsC,CAAC;AACnE,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,iEAAiE;AACjE,uEAAuE;AACvE,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,IAAI,MAAM,EACrB,GAAG,EACH,YAAY,EACZ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,UAAU,EACV,IAAI,EACJ,WAAW,EACZ,CAAC;AACF,oBAAoB","sourcesContent":["/*\n * Copyright (c) 2020 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\n/* c8 ignore start - Browser-specific export used conditionally in package.json */\nimport * as AiAssist from './packlets/ai-assist';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as CryptoUtils from './packlets/crypto-utils/index.browser';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Csv from './packlets/csv/index.browser';\nimport * as Experimental from './packlets/experimental';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as Hash from './packlets/hash/index.browser';\nimport * as Mustache from './packlets/mustache';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as RecordJar from './packlets/record-jar/index.browser';\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport * as SaferFetch from './packlets/safer-fetch/index.browser';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\n// Browser-safe exports - Node.js crypto-based providers excluded\n// Use BrowserCryptoProvider from @fgv/ts-web-extras for browser crypto\nexport {\n  AiAssist,\n  Converters,\n  CryptoUtils,\n  CryptoUtils as Crypto,\n  Csv,\n  Experimental,\n  Hash,\n  Mustache,\n  RecordJar,\n  SaferFetch,\n  Yaml,\n  ZipFileTree\n};\n/* c8 ignore stop */\n"]}

package/dist/index.js

@@ -26,8 +26,9 @@ import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash';
 import * as Mustache from './packlets/mustache';
 import * as RecordJar from './packlets/record-jar';
+import * as SaferFetch from './packlets/safer-fetch';
 import * as Yaml from './packlets/yaml';
 import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, Yaml, ZipFileTree };
+export { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, SaferFetch, Yaml, ZipFileTree };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 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 * as AiAssist from './packlets/ai-assist';\nimport * as CryptoUtils from './packlets/crypto-utils';\nimport * as Csv from './packlets/csv';\nimport * as Experimental from './packlets/experimental';\nimport * as Hash from './packlets/hash';\nimport * as Mustache from './packlets/mustache';\nimport * as RecordJar from './packlets/record-jar';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\nexport { AiAssist, Converters, CryptoUtils, Csv, Experimental, Hash, Mustache, RecordJar, Yaml, ZipFileTree };\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EACL,QAAQ,EACR,UAAU,EACV,WAAW,EACX,GAAG,EACH,YAAY,EACZ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,UAAU,EACV,IAAI,EACJ,WAAW,EACZ,CAAC","sourcesContent":["/*\n * Copyright (c) 2020 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 * as AiAssist from './packlets/ai-assist';\nimport * as CryptoUtils from './packlets/crypto-utils';\nimport * as Csv from './packlets/csv';\nimport * as Experimental from './packlets/experimental';\nimport * as Hash from './packlets/hash';\nimport * as Mustache from './packlets/mustache';\nimport * as RecordJar from './packlets/record-jar';\nimport * as SaferFetch from './packlets/safer-fetch';\nimport * as Yaml from './packlets/yaml';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\nexport {\n  AiAssist,\n  Converters,\n  CryptoUtils,\n  Csv,\n  Experimental,\n  Hash,\n  Mustache,\n  RecordJar,\n  SaferFetch,\n  Yaml,\n  ZipFileTree\n};\n"]}

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

@@ -0,0 +1,438 @@
+// 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.
+// 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 */
+import { fail, succeed } from '@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
+ */
+export function classifyAddress(address) {
+    const text = normalizeAddressText(address);
+    if (text.length === 0) {
+        return fail(`"${address}": not a valid IP address literal (empty)`);
+    }
+    if (text.indexOf(':') >= 0) {
+        const bytes = parseIpv6(stripIpv6Zone(text));
+        if (bytes === undefined) {
+            return fail(`"${address}": not a valid IPv6 address literal`);
+        }
+        return 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 fail(`"${address}": not a valid IP address literal`);
+    }
+    const canonical = ipv4ToString(value);
+    return succeed({
+        address,
+        canonical,
+        family: 'ipv4',
+        classification: classifyIpv4Value(value)
+    });
+}
+//# sourceMappingURL=addressClassification.js.map