host-consensus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tamer Kalla
+
+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.

package/README.md

@@ -0,0 +1,158 @@
+# host-consensus
+
+**`http://example.com\@evil.com` is `example.com` to JavaScript and `evil.com` to Python.**
+
+[![build](https://github.com/tamerkalla/host-consensus/actions/workflows/release.yml/badge.svg)](https://github.com/tamerkalla/host-consensus/actions/workflows/release.yml)
+[![npm](https://img.shields.io/npm/v/host-consensus.svg)](https://www.npmjs.com/package/host-consensus)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![provenance](https://img.shields.io/badge/provenance-attested-brightgreen.svg)](https://www.npmjs.com/package/host-consensus)
+
+A runtime-path library — you import it into request-validation code and ship it.
+Zero runtime dependencies. TypeScript, ES2022, dual ESM/CJS, with a small CLI.
+
+```bash
+npm install host-consensus
+```
+
+|  | reads the host as |
+|---|---|
+| `new URL()` — WHATWG, what every browser and Node run | **example.com** |
+| `urllib.parse` — RFC 3986, what most of the non-browser world runs | **evil.com** |
+
+Validate that URL in Node against an allowlist and it passes as `example.com`.
+Hand the same *string* to a Python service, a Go proxy, or anything else built
+on RFC 3986, and the request goes to `evil.com`.
+
+Neither parser is broken. WHATWG URL says a backslash is a path separator in a
+special scheme; RFC 3986 says it is an ordinary character, so the authority runs
+to `@` and the userinfo is `example.com\`. Both are behaving exactly as
+specified.
+
+## What it does
+
+```js
+import { inspect, agrees, assertConsensus } from 'host-consensus';
+
+agrees('https://example.com/a');            // true
+agrees('http://example.com\\@evil.com');    // false
+
+assertConsensus('http://example.com\\@evil.com');
+// throws HostDisagreementError:
+//   "http://example.com\@evil.com" is read as different hosts
+//   (whatwg=example.com, rfc3986=evil.com)
+```
+
+`inspect` returns both readings so you can log what actually differed:
+
+```js
+inspect('http://example.com\\@evil.com');
+```
+
+```json
+{
+  "input": "http://example.com\\@evil.com",
+  "verdict": "host-differs",
+  "host": null,
+  "readings": [
+    { "convention": "whatwg",  "host": "example.com", "port": "", "origin": "http://example.com" },
+    { "convention": "rfc3986", "host": "evil.com",    "port": "", "origin": "http://evil.com" }
+  ]
+}
+```
+
+From the command line:
+
+```console
+$ npx host-consensus 'http://example.com\@evil.com'
+http://example.com\@evil.com
+  whatwg   example.com
+  rfc3986  evil.com
+  verdict  host-differs
+$ echo $?
+1
+```
+
+## The seven constructions
+
+Over a deterministic enumeration of 312 URLs — 2 schemes x 26 authority
+constructions x 6 path suffixes — **84 rows** are read as a different host by
+the two conventions. Seven distinct authority constructions sit behind them, and
+each is a different mechanism:
+
+| authority | WHATWG reads | RFC 3986 reads | why |
+|---|---|---|---|
+| `example.com\@evil.com` | `example.com` | `evil.com` | backslash is a slash in a special scheme |
+| `0x7f.1` | `127.0.0.1` | `0x7f.1` | hexadecimal IPv4 canonicalisation |
+| `017700000001` | `127.0.0.1` | `017700000001` | octal IPv4 canonicalisation |
+| `2130706433` | `127.0.0.1` | `2130706433` | decimal IPv4 canonicalisation |
+| `①.com` | `1.com` | `①.com` | UTS-46 mapping |
+| `exаmple.com` (Cyrillic а) | `xn--exmple-4nf.com` | `exаmple.com` | IDNA to ASCII |
+| `example。com` (U+3002) | `example.com` | `example。com` | ideographic full stop separates labels |
+
+The IPv4 rows run the other way from the backslash row: `http://2130706433` is
+`127.0.0.1` to a private-range filter written against `new URL()`, and an opaque
+hostname to anything RFC-derived. Whichever side does the blocking, the other
+side disagrees about what it is blocking.
+
+A further **48 rows** across four constructions are an *acceptance* difference —
+one convention refuses the URL outright and the other returns a host:
+`exa mple.com`, `example.com:65536`, `example.com:+80`, `example.com: 80`.
+
+The remaining **180 rows** are reported as agreeing. That matters as much as the
+rest: differences in spelling — IPv6 brackets, host case — are normalised away
+and never reported, so ordinary URLs come back clean.
+
+## What this does not do
+
+It does not resolve DNS, classify addresses as private, or make requests. Those
+are a different job, and [`request-filtering-agent`](https://www.npmjs.com/package/request-filtering-agent)
+does them well — it blocks requests to private ranges at the agent level. Use it
+for that; use this to check that the URL string you validated is the one your
+next hop will read.
+
+The two are complementary: a private-range filter answers "is this address
+safe", and `host-consensus` answers "will the next parser agree this is even the
+same address".
+
+## API
+
+```ts
+function inspect(url: string): Consensus;
+function agrees(url: string): boolean;
+function assertConsensus(url: string): string;   // the agreed host, or throws
+class HostDisagreementError extends Error { readonly consensus: Consensus }
+```
+
+`verdict` is one of:
+
+- `'agreed'` — every convention names the same host.
+- `'host-differs'` — all parsed, and they name different hosts.
+- `'acceptance-differs'` — at least one refused and at least one accepted.
+
+`inspect` throws `TypeError` on a non-string and nothing else. `agrees` never
+throws on a malformed URL: a predicate that throws gets read as `false` by the
+next person to use it, and "this URL is dangerous" must not be reachable by
+accident. `assertConsensus` also throws when both conventions refuse, because
+there is no host to return.
+
+`inspect` performs no I/O — no network, no filesystem, no clock — and is a pure
+function of its argument.
+
+## How the RFC 3986 reading is checked
+
+It is not checked against anybody's reading of the specification. `src/corpus.ts`
+records the host and port that **CPython 3.11.15's `urllib.parse.urlsplit`**
+returned for all 312 URLs, and the test suite asserts this package matches real
+CPython on every one of them. See [VERIFY.md](VERIFY.md) to reproduce the
+headline claim from a clean install in under a minute.
+
+## Also from this author
+
+[`yaml-drift`](https://www.npmjs.com/package/yaml-drift) reports every value
+whose meaning changed converting YAML to JSON; `host-consensus` reports hosts
+that two URL conventions read differently. Same shape — a boundary that silently
+changes meaning — at a different boundary.
+
+## License
+
+MIT

package/VERIFY.md

@@ -0,0 +1,97 @@
+# Verify the headline claim
+
+The claim on the front of this package is that one URL string names two
+different hosts depending on which convention reads it, and that
+`host-consensus` catches that.
+
+Reproduce it from a clean directory. Nothing here needs a checkout of this
+repository — it installs the published package from the registry.
+
+## 1. Install
+
+```bash
+mkdir -p /tmp/host-consensus-verify && cd /tmp/host-consensus-verify
+npm init -y >/dev/null
+npm install host-consensus@latest
+```
+
+## 2. Run the check
+
+```bash
+npx host-consensus 'http://example.com\@evil.com'
+echo "exit=$?"
+```
+
+Expected output, exactly:
+
+```
+http://example.com\@evil.com
+  whatwg   example.com
+  rfc3986  evil.com
+  verdict  host-differs
+exit=1
+```
+
+## 3. Confirm an ordinary URL is not flagged
+
+A tool that flags everything would pass step 2 and still be useless.
+
+```bash
+npx host-consensus 'https://example.com/a'
+echo "exit=$?"
+```
+
+Expected output, exactly:
+
+```
+https://example.com/a
+  whatwg   example.com
+  rfc3986  example.com
+  verdict  agreed
+exit=0
+```
+
+## 4. Confirm the library agrees with the CLI, in both module formats
+
+```bash
+node --input-type=module -e "
+import { agrees } from 'host-consensus';
+console.log('esm', agrees('https://example.com/a'), agrees('http://example.com\\\\@evil.com'));
+"
+node --input-type=commonjs -e "
+const { agrees } = require('host-consensus');
+console.log('cjs', agrees('https://example.com/a'), agrees('http://example.com\\\\@evil.com'));
+"
+```
+
+Expected output, exactly:
+
+```
+esm true false
+cjs true false
+```
+
+## 5. Check it against a second implementation, if you have Python
+
+This is the same comparison the package's own test suite makes against
+CPython 3.11.15, and it needs no extra packages.
+
+```bash
+python3 -c "
+from urllib.parse import urlsplit
+print('python sees:', urlsplit('http://example.com\\\\@evil.com').hostname)
+"
+node -e "
+console.log('node sees:  ', new URL('http://example.com\\\\@evil.com').hostname);
+"
+```
+
+Expected output, exactly:
+
+```
+python sees: evil.com
+node sees:   example.com
+```
+
+If those two lines differ from each other, the package's reason for existing is
+reproduced on your machine.

package/dist/cli.cjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  main: () => main,
+  run: () => run
+});
+module.exports = __toCommonJS(cli_exports);
+
+// src/compare.ts
+function normaliseHost(host) {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  return unbracketed.toLowerCase();
+}
+function verdictOf(readings) {
+  const accepted = readings.filter((r) => r.host !== null);
+  if (accepted.length !== 0 && accepted.length !== readings.length) {
+    return "acceptance-differs";
+  }
+  const keys = new Set(
+    readings.map((r) => r.host === null ? "\0none" : normaliseHost(r.host))
+  );
+  return keys.size === 1 ? "agreed" : "host-differs";
+}
+function consensusOf(input, readings) {
+  const verdict = verdictOf(readings);
+  const host = verdict === "agreed" ? readings[0].host : null;
+  return { input, verdict, host, readings };
+}
+
+// src/rfc3986.ts
+var SCHEME_CHARS = /^[A-Za-z][A-Za-z0-9+\-.]*$/;
+function stripUnsafe(url) {
+  return url.replace(/[\t\r\n]/g, "");
+}
+function trimC0(url) {
+  let start = 0;
+  let end = url.length;
+  while (start < end && url.charCodeAt(start) <= 32) start++;
+  while (end > start && url.charCodeAt(end - 1) <= 32) end--;
+  return url.slice(start, end);
+}
+function splitScheme(url) {
+  const i = url.indexOf(":");
+  if (i > 0 && SCHEME_CHARS.test(url.slice(0, i))) {
+    return { scheme: url.slice(0, i).toLowerCase(), rest: url.slice(i + 1) };
+  }
+  return { scheme: "", rest: url };
+}
+function netlocOf(rest) {
+  if (!rest.startsWith("//")) return null;
+  const after = rest.slice(2);
+  let end = after.length;
+  for (const c of ["/", "?", "#"]) {
+    const i = after.indexOf(c);
+    if (i !== -1 && i < end) end = i;
+  }
+  return after.slice(0, end);
+}
+function hostInfo(netloc) {
+  const at = netloc.lastIndexOf("@");
+  const hostinfo = at === -1 ? netloc : netloc.slice(at + 1);
+  const open = hostinfo.indexOf("[");
+  if (open !== -1) {
+    const bracketed = hostinfo.slice(open + 1);
+    const close = bracketed.indexOf("]");
+    const host = close === -1 ? bracketed : bracketed.slice(0, close);
+    const afterBracket = close === -1 ? "" : bracketed.slice(close + 1);
+    const colon2 = afterBracket.indexOf(":");
+    return { host, port: colon2 === -1 ? "" : afterBracket.slice(colon2 + 1) };
+  }
+  const colon = hostinfo.indexOf(":");
+  if (colon === -1) return { host: hostinfo, port: "" };
+  return { host: hostinfo.slice(0, colon), port: hostinfo.slice(colon + 1) };
+}
+function lowerHost(host) {
+  const pct = host.indexOf("%");
+  if (pct === -1) return host.toLowerCase();
+  return host.slice(0, pct).toLowerCase() + host.slice(pct);
+}
+function normalisePort(port) {
+  if (port === "") return "";
+  if (!/^[0-9]+$/.test(port)) return null;
+  const n = Number(port);
+  if (n < 0 || n > 65535) return null;
+  return String(n);
+}
+function readRfc3986(url) {
+  const cleaned = trimC0(stripUnsafe(url));
+  const { scheme, rest } = splitScheme(cleaned);
+  const netloc = netlocOf(rest);
+  if (netloc === null) {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "no authority component"
+    };
+  }
+  const { host, port } = hostInfo(netloc);
+  if (host === "") {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const lowered = lowerHost(host);
+  const normalisedPort = normalisePort(port);
+  const origin = scheme === "" ? null : `${scheme}://${lowered}${normalisedPort ? `:${normalisedPort}` : ""}`;
+  return { convention: "rfc3986", host: lowered, port: normalisedPort, origin };
+}
+
+// src/whatwg.ts
+function readWhatwg(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (parsed.hostname === "") {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const origin = parsed.origin === "null" ? null : parsed.origin;
+  return {
+    convention: "whatwg",
+    host: parsed.hostname,
+    port: parsed.port,
+    origin
+  };
+}
+
+// src/index.ts
+function requireString(url, fn) {
+  if (typeof url !== "string") {
+    throw new TypeError(`${fn}(url) requires a string, received ${typeof url}`);
+  }
+}
+function inspect(url) {
+  requireString(url, "inspect");
+  return consensusOf(url, [readWhatwg(url), readRfc3986(url)]);
+}
+
+// src/cli.ts
+var USAGE = `Usage: host-consensus <url>
+
+Reads <url> by both URL-parsing conventions and prints the host each one names.
+
+Exit codes:
+  0  every convention agrees on the host
+  1  the conventions disagree
+  2  usage error`;
+function main(argv, out) {
+  const args = argv.filter((a) => a !== "");
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    out(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  if (args.length > 1) {
+    out(`host-consensus: expected one URL, received ${args.length}
+
+${USAGE}`);
+    return 2;
+  }
+  const result = inspect(args[0]);
+  const width = Math.max(...result.readings.map((r) => r.convention.length));
+  out(result.input);
+  for (const reading of result.readings) {
+    const host = reading.host === null ? `<rejected: ${reading.rejected}>` : reading.host;
+    const port = reading.port ? `:${reading.port}` : "";
+    out(`  ${reading.convention.padEnd(width)}  ${host}${port}`);
+  }
+  out(`  ${"verdict".padEnd(width)}  ${result.verdict}`);
+  return result.verdict === "agreed" ? 0 : 1;
+}
+function run() {
+  process.exitCode = main(process.argv.slice(2), (s) => console.log(s));
+}
+run();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  run
+});

package/dist/cli.d.cts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+declare function main(argv: readonly string[], out: (s: string) => void): number;
+declare function run(): void;
+
+export { main, run };

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+declare function main(argv: readonly string[], out: (s: string) => void): number;
+declare function run(): void;
+
+export { main, run };

package/dist/cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+
+// src/compare.ts
+function normaliseHost(host) {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  return unbracketed.toLowerCase();
+}
+function verdictOf(readings) {
+  const accepted = readings.filter((r) => r.host !== null);
+  if (accepted.length !== 0 && accepted.length !== readings.length) {
+    return "acceptance-differs";
+  }
+  const keys = new Set(
+    readings.map((r) => r.host === null ? "\0none" : normaliseHost(r.host))
+  );
+  return keys.size === 1 ? "agreed" : "host-differs";
+}
+function consensusOf(input, readings) {
+  const verdict = verdictOf(readings);
+  const host = verdict === "agreed" ? readings[0].host : null;
+  return { input, verdict, host, readings };
+}
+
+// src/rfc3986.ts
+var SCHEME_CHARS = /^[A-Za-z][A-Za-z0-9+\-.]*$/;
+function stripUnsafe(url) {
+  return url.replace(/[\t\r\n]/g, "");
+}
+function trimC0(url) {
+  let start = 0;
+  let end = url.length;
+  while (start < end && url.charCodeAt(start) <= 32) start++;
+  while (end > start && url.charCodeAt(end - 1) <= 32) end--;
+  return url.slice(start, end);
+}
+function splitScheme(url) {
+  const i = url.indexOf(":");
+  if (i > 0 && SCHEME_CHARS.test(url.slice(0, i))) {
+    return { scheme: url.slice(0, i).toLowerCase(), rest: url.slice(i + 1) };
+  }
+  return { scheme: "", rest: url };
+}
+function netlocOf(rest) {
+  if (!rest.startsWith("//")) return null;
+  const after = rest.slice(2);
+  let end = after.length;
+  for (const c of ["/", "?", "#"]) {
+    const i = after.indexOf(c);
+    if (i !== -1 && i < end) end = i;
+  }
+  return after.slice(0, end);
+}
+function hostInfo(netloc) {
+  const at = netloc.lastIndexOf("@");
+  const hostinfo = at === -1 ? netloc : netloc.slice(at + 1);
+  const open = hostinfo.indexOf("[");
+  if (open !== -1) {
+    const bracketed = hostinfo.slice(open + 1);
+    const close = bracketed.indexOf("]");
+    const host = close === -1 ? bracketed : bracketed.slice(0, close);
+    const afterBracket = close === -1 ? "" : bracketed.slice(close + 1);
+    const colon2 = afterBracket.indexOf(":");
+    return { host, port: colon2 === -1 ? "" : afterBracket.slice(colon2 + 1) };
+  }
+  const colon = hostinfo.indexOf(":");
+  if (colon === -1) return { host: hostinfo, port: "" };
+  return { host: hostinfo.slice(0, colon), port: hostinfo.slice(colon + 1) };
+}
+function lowerHost(host) {
+  const pct = host.indexOf("%");
+  if (pct === -1) return host.toLowerCase();
+  return host.slice(0, pct).toLowerCase() + host.slice(pct);
+}
+function normalisePort(port) {
+  if (port === "") return "";
+  if (!/^[0-9]+$/.test(port)) return null;
+  const n = Number(port);
+  if (n < 0 || n > 65535) return null;
+  return String(n);
+}
+function readRfc3986(url) {
+  const cleaned = trimC0(stripUnsafe(url));
+  const { scheme, rest } = splitScheme(cleaned);
+  const netloc = netlocOf(rest);
+  if (netloc === null) {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "no authority component"
+    };
+  }
+  const { host, port } = hostInfo(netloc);
+  if (host === "") {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const lowered = lowerHost(host);
+  const normalisedPort = normalisePort(port);
+  const origin = scheme === "" ? null : `${scheme}://${lowered}${normalisedPort ? `:${normalisedPort}` : ""}`;
+  return { convention: "rfc3986", host: lowered, port: normalisedPort, origin };
+}
+
+// src/whatwg.ts
+function readWhatwg(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (parsed.hostname === "") {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const origin = parsed.origin === "null" ? null : parsed.origin;
+  return {
+    convention: "whatwg",
+    host: parsed.hostname,
+    port: parsed.port,
+    origin
+  };
+}
+
+// src/index.ts
+function requireString(url, fn) {
+  if (typeof url !== "string") {
+    throw new TypeError(`${fn}(url) requires a string, received ${typeof url}`);
+  }
+}
+function inspect(url) {
+  requireString(url, "inspect");
+  return consensusOf(url, [readWhatwg(url), readRfc3986(url)]);
+}
+
+// src/cli.ts
+var USAGE = `Usage: host-consensus <url>
+
+Reads <url> by both URL-parsing conventions and prints the host each one names.
+
+Exit codes:
+  0  every convention agrees on the host
+  1  the conventions disagree
+  2  usage error`;
+function main(argv, out) {
+  const args = argv.filter((a) => a !== "");
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    out(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  if (args.length > 1) {
+    out(`host-consensus: expected one URL, received ${args.length}
+
+${USAGE}`);
+    return 2;
+  }
+  const result = inspect(args[0]);
+  const width = Math.max(...result.readings.map((r) => r.convention.length));
+  out(result.input);
+  for (const reading of result.readings) {
+    const host = reading.host === null ? `<rejected: ${reading.rejected}>` : reading.host;
+    const port = reading.port ? `:${reading.port}` : "";
+    out(`  ${reading.convention.padEnd(width)}  ${host}${port}`);
+  }
+  out(`  ${"verdict".padEnd(width)}  ${result.verdict}`);
+  return result.verdict === "agreed" ? 0 : 1;
+}
+function run() {
+  process.exitCode = main(process.argv.slice(2), (s) => console.log(s));
+}
+run();
+export {
+  main,
+  run
+};

package/dist/index.cjs

@@ -0,0 +1,214 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HostDisagreementError: () => HostDisagreementError,
+  agrees: () => agrees,
+  assertConsensus: () => assertConsensus,
+  inspect: () => inspect,
+  normaliseHost: () => normaliseHost
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/compare.ts
+function normaliseHost(host) {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  return unbracketed.toLowerCase();
+}
+function verdictOf(readings) {
+  const accepted = readings.filter((r) => r.host !== null);
+  if (accepted.length !== 0 && accepted.length !== readings.length) {
+    return "acceptance-differs";
+  }
+  const keys = new Set(
+    readings.map((r) => r.host === null ? "\0none" : normaliseHost(r.host))
+  );
+  return keys.size === 1 ? "agreed" : "host-differs";
+}
+function consensusOf(input, readings) {
+  const verdict = verdictOf(readings);
+  const host = verdict === "agreed" ? readings[0].host : null;
+  return { input, verdict, host, readings };
+}
+
+// src/rfc3986.ts
+var SCHEME_CHARS = /^[A-Za-z][A-Za-z0-9+\-.]*$/;
+function stripUnsafe(url) {
+  return url.replace(/[\t\r\n]/g, "");
+}
+function trimC0(url) {
+  let start = 0;
+  let end = url.length;
+  while (start < end && url.charCodeAt(start) <= 32) start++;
+  while (end > start && url.charCodeAt(end - 1) <= 32) end--;
+  return url.slice(start, end);
+}
+function splitScheme(url) {
+  const i = url.indexOf(":");
+  if (i > 0 && SCHEME_CHARS.test(url.slice(0, i))) {
+    return { scheme: url.slice(0, i).toLowerCase(), rest: url.slice(i + 1) };
+  }
+  return { scheme: "", rest: url };
+}
+function netlocOf(rest) {
+  if (!rest.startsWith("//")) return null;
+  const after = rest.slice(2);
+  let end = after.length;
+  for (const c of ["/", "?", "#"]) {
+    const i = after.indexOf(c);
+    if (i !== -1 && i < end) end = i;
+  }
+  return after.slice(0, end);
+}
+function hostInfo(netloc) {
+  const at = netloc.lastIndexOf("@");
+  const hostinfo = at === -1 ? netloc : netloc.slice(at + 1);
+  const open = hostinfo.indexOf("[");
+  if (open !== -1) {
+    const bracketed = hostinfo.slice(open + 1);
+    const close = bracketed.indexOf("]");
+    const host = close === -1 ? bracketed : bracketed.slice(0, close);
+    const afterBracket = close === -1 ? "" : bracketed.slice(close + 1);
+    const colon2 = afterBracket.indexOf(":");
+    return { host, port: colon2 === -1 ? "" : afterBracket.slice(colon2 + 1) };
+  }
+  const colon = hostinfo.indexOf(":");
+  if (colon === -1) return { host: hostinfo, port: "" };
+  return { host: hostinfo.slice(0, colon), port: hostinfo.slice(colon + 1) };
+}
+function lowerHost(host) {
+  const pct = host.indexOf("%");
+  if (pct === -1) return host.toLowerCase();
+  return host.slice(0, pct).toLowerCase() + host.slice(pct);
+}
+function normalisePort(port) {
+  if (port === "") return "";
+  if (!/^[0-9]+$/.test(port)) return null;
+  const n = Number(port);
+  if (n < 0 || n > 65535) return null;
+  return String(n);
+}
+function readRfc3986(url) {
+  const cleaned = trimC0(stripUnsafe(url));
+  const { scheme, rest } = splitScheme(cleaned);
+  const netloc = netlocOf(rest);
+  if (netloc === null) {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "no authority component"
+    };
+  }
+  const { host, port } = hostInfo(netloc);
+  if (host === "") {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const lowered = lowerHost(host);
+  const normalisedPort = normalisePort(port);
+  const origin = scheme === "" ? null : `${scheme}://${lowered}${normalisedPort ? `:${normalisedPort}` : ""}`;
+  return { convention: "rfc3986", host: lowered, port: normalisedPort, origin };
+}
+
+// src/whatwg.ts
+function readWhatwg(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (parsed.hostname === "") {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const origin = parsed.origin === "null" ? null : parsed.origin;
+  return {
+    convention: "whatwg",
+    host: parsed.hostname,
+    port: parsed.port,
+    origin
+  };
+}
+
+// src/index.ts
+function requireString(url, fn) {
+  if (typeof url !== "string") {
+    throw new TypeError(`${fn}(url) requires a string, received ${typeof url}`);
+  }
+}
+function inspect(url) {
+  requireString(url, "inspect");
+  return consensusOf(url, [readWhatwg(url), readRfc3986(url)]);
+}
+function agrees(url) {
+  requireString(url, "agrees");
+  return inspect(url).verdict === "agreed";
+}
+var HostDisagreementError = class _HostDisagreementError extends Error {
+  name = "HostDisagreementError";
+  consensus;
+  constructor(consensus) {
+    super(_HostDisagreementError.describe(consensus));
+    this.consensus = consensus;
+  }
+  static describe(consensus) {
+    const readings = consensus.readings.map((r) => `${r.convention}=${r.host === null ? `<rejected: ${r.rejected}>` : r.host}`).join(", ");
+    if (consensus.verdict === "agreed") {
+      return `${JSON.stringify(consensus.input)} names no host (${readings})`;
+    }
+    return `${JSON.stringify(consensus.input)} is read as different hosts (${readings})`;
+  }
+};
+function assertConsensus(url) {
+  requireString(url, "assertConsensus");
+  const consensus = inspect(url);
+  if (consensus.verdict !== "agreed" || consensus.host === null) {
+    throw new HostDisagreementError(consensus);
+  }
+  return consensus.host;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HostDisagreementError,
+  agrees,
+  assertConsensus,
+  inspect,
+  normaliseHost
+});

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+/** The two URL-parsing conventions in live use. */
+type Convention = 'whatwg' | 'rfc3986';
+interface Reading {
+    convention: Convention;
+    /** The host this convention says the URL names. `null` when it names none. */
+    host: string | null;
+    /**
+     * The port as a string; `''` when the URL carries no port. `null` when this
+     * convention produced no usable port — either because it refused the URL, or
+     * because the port is present but not an integer in 0-65535.
+     */
+    port: string | null;
+    /** `scheme://host[:port]`, or `null` where this convention defines none. */
+    origin: string | null;
+    /** Present only when `host` is `null`: why this convention produced no host. */
+    rejected?: string;
+}
+type Verdict = 
+/** Every convention names the same host. */
+'agreed'
+/** All conventions parsed, but they name different hosts. */
+ | 'host-differs'
+/** At least one convention refused the URL and at least one accepted it. */
+ | 'acceptance-differs';
+interface Consensus {
+    input: string;
+    verdict: Verdict;
+    /** The agreed host. `null` unless `verdict` is `'agreed'` with a host. */
+    host: string | null;
+    readings: Reading[];
+}
+
+/**
+ * Normalise a host for comparison only. Surrounding IPv6 brackets are removed
+ * and ASCII case is folded; nothing else. A difference that survives this is a
+ * disagreement about which host is named. A difference that does not survive it
+ * is a difference in spelling, and reporting those would make the tool
+ * unusable — it would flag every IPv6 URL in the world.
+ */
+declare function normaliseHost(host: string): string;
+
+/**
+ * Read `url` by both conventions and report whether they name the same host.
+ *
+ * Performs no I/O: no network, no filesystem, no clock. Pure in its argument.
+ */
+declare function inspect(url: string): Consensus;
+/**
+ * `true` when every convention names the same host.
+ *
+ * Never throws on a malformed URL — a predicate that throws gets read as
+ * `false` by the next person to use it, and "this URL is dangerous" must not
+ * be reachable by accident.
+ */
+declare function agrees(url: string): boolean;
+declare class HostDisagreementError extends Error {
+    readonly name: "HostDisagreementError";
+    readonly consensus: Consensus;
+    constructor(consensus: Consensus);
+    private static describe;
+}
+/**
+ * Return the host every convention agrees on, or throw `HostDisagreementError`.
+ *
+ * This is the guard: put it in front of anything that will hand the URL
+ * *string* to another system, which will parse it again by its own rules.
+ */
+declare function assertConsensus(url: string): string;
+
+export { type Consensus, type Convention, HostDisagreementError, type Reading, type Verdict, agrees, assertConsensus, inspect, normaliseHost };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/** The two URL-parsing conventions in live use. */
+type Convention = 'whatwg' | 'rfc3986';
+interface Reading {
+    convention: Convention;
+    /** The host this convention says the URL names. `null` when it names none. */
+    host: string | null;
+    /**
+     * The port as a string; `''` when the URL carries no port. `null` when this
+     * convention produced no usable port — either because it refused the URL, or
+     * because the port is present but not an integer in 0-65535.
+     */
+    port: string | null;
+    /** `scheme://host[:port]`, or `null` where this convention defines none. */
+    origin: string | null;
+    /** Present only when `host` is `null`: why this convention produced no host. */
+    rejected?: string;
+}
+type Verdict = 
+/** Every convention names the same host. */
+'agreed'
+/** All conventions parsed, but they name different hosts. */
+ | 'host-differs'
+/** At least one convention refused the URL and at least one accepted it. */
+ | 'acceptance-differs';
+interface Consensus {
+    input: string;
+    verdict: Verdict;
+    /** The agreed host. `null` unless `verdict` is `'agreed'` with a host. */
+    host: string | null;
+    readings: Reading[];
+}
+
+/**
+ * Normalise a host for comparison only. Surrounding IPv6 brackets are removed
+ * and ASCII case is folded; nothing else. A difference that survives this is a
+ * disagreement about which host is named. A difference that does not survive it
+ * is a difference in spelling, and reporting those would make the tool
+ * unusable — it would flag every IPv6 URL in the world.
+ */
+declare function normaliseHost(host: string): string;
+
+/**
+ * Read `url` by both conventions and report whether they name the same host.
+ *
+ * Performs no I/O: no network, no filesystem, no clock. Pure in its argument.
+ */
+declare function inspect(url: string): Consensus;
+/**
+ * `true` when every convention names the same host.
+ *
+ * Never throws on a malformed URL — a predicate that throws gets read as
+ * `false` by the next person to use it, and "this URL is dangerous" must not
+ * be reachable by accident.
+ */
+declare function agrees(url: string): boolean;
+declare class HostDisagreementError extends Error {
+    readonly name: "HostDisagreementError";
+    readonly consensus: Consensus;
+    constructor(consensus: Consensus);
+    private static describe;
+}
+/**
+ * Return the host every convention agrees on, or throw `HostDisagreementError`.
+ *
+ * This is the guard: put it in front of anything that will hand the URL
+ * *string* to another system, which will parse it again by its own rules.
+ */
+declare function assertConsensus(url: string): string;
+
+export { type Consensus, type Convention, HostDisagreementError, type Reading, type Verdict, agrees, assertConsensus, inspect, normaliseHost };

package/dist/index.js

@@ -0,0 +1,183 @@
+// src/compare.ts
+function normaliseHost(host) {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  return unbracketed.toLowerCase();
+}
+function verdictOf(readings) {
+  const accepted = readings.filter((r) => r.host !== null);
+  if (accepted.length !== 0 && accepted.length !== readings.length) {
+    return "acceptance-differs";
+  }
+  const keys = new Set(
+    readings.map((r) => r.host === null ? "\0none" : normaliseHost(r.host))
+  );
+  return keys.size === 1 ? "agreed" : "host-differs";
+}
+function consensusOf(input, readings) {
+  const verdict = verdictOf(readings);
+  const host = verdict === "agreed" ? readings[0].host : null;
+  return { input, verdict, host, readings };
+}
+
+// src/rfc3986.ts
+var SCHEME_CHARS = /^[A-Za-z][A-Za-z0-9+\-.]*$/;
+function stripUnsafe(url) {
+  return url.replace(/[\t\r\n]/g, "");
+}
+function trimC0(url) {
+  let start = 0;
+  let end = url.length;
+  while (start < end && url.charCodeAt(start) <= 32) start++;
+  while (end > start && url.charCodeAt(end - 1) <= 32) end--;
+  return url.slice(start, end);
+}
+function splitScheme(url) {
+  const i = url.indexOf(":");
+  if (i > 0 && SCHEME_CHARS.test(url.slice(0, i))) {
+    return { scheme: url.slice(0, i).toLowerCase(), rest: url.slice(i + 1) };
+  }
+  return { scheme: "", rest: url };
+}
+function netlocOf(rest) {
+  if (!rest.startsWith("//")) return null;
+  const after = rest.slice(2);
+  let end = after.length;
+  for (const c of ["/", "?", "#"]) {
+    const i = after.indexOf(c);
+    if (i !== -1 && i < end) end = i;
+  }
+  return after.slice(0, end);
+}
+function hostInfo(netloc) {
+  const at = netloc.lastIndexOf("@");
+  const hostinfo = at === -1 ? netloc : netloc.slice(at + 1);
+  const open = hostinfo.indexOf("[");
+  if (open !== -1) {
+    const bracketed = hostinfo.slice(open + 1);
+    const close = bracketed.indexOf("]");
+    const host = close === -1 ? bracketed : bracketed.slice(0, close);
+    const afterBracket = close === -1 ? "" : bracketed.slice(close + 1);
+    const colon2 = afterBracket.indexOf(":");
+    return { host, port: colon2 === -1 ? "" : afterBracket.slice(colon2 + 1) };
+  }
+  const colon = hostinfo.indexOf(":");
+  if (colon === -1) return { host: hostinfo, port: "" };
+  return { host: hostinfo.slice(0, colon), port: hostinfo.slice(colon + 1) };
+}
+function lowerHost(host) {
+  const pct = host.indexOf("%");
+  if (pct === -1) return host.toLowerCase();
+  return host.slice(0, pct).toLowerCase() + host.slice(pct);
+}
+function normalisePort(port) {
+  if (port === "") return "";
+  if (!/^[0-9]+$/.test(port)) return null;
+  const n = Number(port);
+  if (n < 0 || n > 65535) return null;
+  return String(n);
+}
+function readRfc3986(url) {
+  const cleaned = trimC0(stripUnsafe(url));
+  const { scheme, rest } = splitScheme(cleaned);
+  const netloc = netlocOf(rest);
+  if (netloc === null) {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "no authority component"
+    };
+  }
+  const { host, port } = hostInfo(netloc);
+  if (host === "") {
+    return {
+      convention: "rfc3986",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const lowered = lowerHost(host);
+  const normalisedPort = normalisePort(port);
+  const origin = scheme === "" ? null : `${scheme}://${lowered}${normalisedPort ? `:${normalisedPort}` : ""}`;
+  return { convention: "rfc3986", host: lowered, port: normalisedPort, origin };
+}
+
+// src/whatwg.ts
+function readWhatwg(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (parsed.hostname === "") {
+    return {
+      convention: "whatwg",
+      host: null,
+      port: null,
+      origin: null,
+      rejected: "empty host"
+    };
+  }
+  const origin = parsed.origin === "null" ? null : parsed.origin;
+  return {
+    convention: "whatwg",
+    host: parsed.hostname,
+    port: parsed.port,
+    origin
+  };
+}
+
+// src/index.ts
+function requireString(url, fn) {
+  if (typeof url !== "string") {
+    throw new TypeError(`${fn}(url) requires a string, received ${typeof url}`);
+  }
+}
+function inspect(url) {
+  requireString(url, "inspect");
+  return consensusOf(url, [readWhatwg(url), readRfc3986(url)]);
+}
+function agrees(url) {
+  requireString(url, "agrees");
+  return inspect(url).verdict === "agreed";
+}
+var HostDisagreementError = class _HostDisagreementError extends Error {
+  name = "HostDisagreementError";
+  consensus;
+  constructor(consensus) {
+    super(_HostDisagreementError.describe(consensus));
+    this.consensus = consensus;
+  }
+  static describe(consensus) {
+    const readings = consensus.readings.map((r) => `${r.convention}=${r.host === null ? `<rejected: ${r.rejected}>` : r.host}`).join(", ");
+    if (consensus.verdict === "agreed") {
+      return `${JSON.stringify(consensus.input)} names no host (${readings})`;
+    }
+    return `${JSON.stringify(consensus.input)} is read as different hosts (${readings})`;
+  }
+};
+function assertConsensus(url) {
+  requireString(url, "assertConsensus");
+  const consensus = inspect(url);
+  if (consensus.verdict !== "agreed" || consensus.host === null) {
+    throw new HostDisagreementError(consensus);
+  }
+  return consensus.host;
+}
+export {
+  HostDisagreementError,
+  agrees,
+  assertConsensus,
+  inspect,
+  normaliseHost
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "host-consensus",
+  "version": "0.1.0",
+  "description": "Reports whether every URL-parsing convention agrees on the host a URL names.",
+  "keywords": [
+    "url",
+    "ssrf",
+    "hostname",
+    "whatwg-url",
+    "rfc3986",
+    "security",
+    "validation",
+    "parser"
+  ],
+  "license": "MIT",
+  "author": "Tamer Kalla <tamerkalla@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tamerkalla/host-consensus.git"
+  },
+  "homepage": "https://github.com/tamerkalla/host-consensus#readme",
+  "bugs": {
+    "url": "https://github.com/tamerkalla/host-consensus/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "host-consensus": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "VERIFY.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "22.18.12",
+    "js-yaml": "4.3.2",
+    "tsup": "8.5.0",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
+  }
+}