From 375b56396198a8d99f1048381e5befa730e81ced Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:35:12 +0900 Subject: [PATCH] fix(contracts): refuse IPv6, mapped, CGNAT and internal hosts at admission (Q-6.7-10) Production admission only knew IPv4 private ranges and `localhost`, so `[::ffff:127.0.0.1]`, `[fd00::1]`, `[fe80::1]`, `100.64.0.1`, `0.1.2.3`, `api.internal`, `printer.local` and a trailing-dot `localhost.` were all admitted as public API endpoints. isNonPublicHost now also refuses 0.0.0.0/8, 100.64.0.0/10 (CGNAT), IPv6 unique-local (fc00::/7), link-local (fe80::/10), every IPv4-mapped address (::ffff:0:0/96), and `.local` / `.internal` names, after stripping one trailing dot. URL.hostname already canonicalises the literals, so no separate IP parser is needed. The loopback list that allows plain http (`localhost`, `127.0.0.1`, `[::1]`) now lives once in deployment-admission.ts (LOOPBACK_HOSTNAMES / isLoopbackHostname); rest-profiles.ts and browser-rpc.ts use it instead of their own copies (same list, no behavior change there). Verified: new cases in tests/unit/deployment-admission.test.ts; a probe showed 13 of the 14 forms admitted before and all refused after, while 2001:db8::1, fec0::1, 100.63/100.128 and *.example.com names stay admitted. Gates green except the known removal-fixture test. Co-Authored-By: Claude Opus 5.5 --- src/contracts/browser-rpc.ts | 3 +- src/contracts/deployment-admission.ts | 47 +++++++++++++++++++---- src/contracts/rest-profiles.ts | 3 +- tests/unit/deployment-admission.test.ts | 50 ++++++++++++++++++++++--- 4 files changed, 87 insertions(+), 16 deletions(-) diff --git a/src/contracts/browser-rpc.ts b/src/contracts/browser-rpc.ts index 7f93614f..03774152 100644 --- a/src/contracts/browser-rpc.ts +++ b/src/contracts/browser-rpc.ts @@ -7,6 +7,7 @@ import { decodeOwnDataRecord, snapshotExactArray, } from "./exact-snapshot.ts"; +import { isLoopbackHostname } from "./deployment-admission.ts"; import type { InstalledBoundaryMapper } from "./boundary-mapper.ts"; import type { RuntimeSchemaCodec } from "./schema-registry.ts"; @@ -744,7 +745,7 @@ function validateProviderProfile(profile: BrowserRpcProviderProfile): void { } const localHttp = endpoint.protocol === "http:" && - ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname); + isLoopbackHostname(endpoint.hostname); if ( !REGISTRY_ID.test(profile.runtimeProfileId) || !REGISTRY_ID.test(profile.providerId) || diff --git a/src/contracts/deployment-admission.ts b/src/contracts/deployment-admission.ts index 08139100..09fd3ae3 100644 --- a/src/contracts/deployment-admission.ts +++ b/src/contracts/deployment-admission.ts @@ -131,30 +131,61 @@ function publicEndpointViolations( return violations; } +/** + * Q-6.7-10. The one list of loopback hosts (in `URL.hostname` form) on which + * a REST or browser RPC provider may use plain `http:`. + */ +export const LOOPBACK_HOSTNAMES = Object.freeze([ + "localhost", + "127.0.0.1", + "[::1]", +] as const); + +export function isLoopbackHostname(hostname: string): boolean { + return (LOOPBACK_HOSTNAMES as readonly string[]).includes(hostname); +} + /** * Hosts that only resolve inside the machine or network that built the * artifact. A deployment pointing at one of these is a developer configuration - * that escaped, not a production endpoint. + * that escaped, not a production endpoint. `hostname` comes from `URL`, so + * IPv4 and IPv6 literals are already in canonical form. */ function isNonPublicHost(hostname: string): boolean { - const host = hostname.toLowerCase().replace(/^\[|\]$/gu, ""); + if (isLoopbackHostname(hostname)) return true; + const host = hostname + .toLowerCase() + .replace(/^\[|\]$/gu, "") + .replace(/\.$/u, ""); if ( host === "localhost" || host.endsWith(".localhost") || - host === "::1" || - host === "0.0.0.0" || - host === "::" + host.endsWith(".local") || + host.endsWith(".internal") ) { return true; } + if (host.includes(":")) return isNonPublicIpv6(host); const octets = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(host); if (!octets) return false; const [first, second] = [Number(octets[1]), Number(octets[2])]; return ( - first === 127 || + first === 0 || first === 10 || - (first === 192 && second === 168) || + first === 127 || + (first === 100 && second >= 64 && second <= 127) || + (first === 169 && second === 254) || (first === 172 && second >= 16 && second <= 31) || - (first === 169 && second === 254) + (first === 192 && second === 168) ); } + +/** Unspecified, loopback, IPv4-mapped, unique-local (fc00::/7), link-local (fe80::/10). */ +function isNonPublicIpv6(host: string): boolean { + if (host === "::" || host === "::1") return true; + if (/^::ffff:[0-9a-f]{1,4}:[0-9a-f]{1,4}$/u.test(host)) return true; + const first = host.startsWith(":") + ? 0 + : Number.parseInt(host.slice(0, host.indexOf(":")), 16); + return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80; +} diff --git a/src/contracts/rest-profiles.ts b/src/contracts/rest-profiles.ts index ad8e581b..9010708a 100644 --- a/src/contracts/rest-profiles.ts +++ b/src/contracts/rest-profiles.ts @@ -3,6 +3,7 @@ import { type ReadOnlyRegistry, } from "./read-only-registry.ts"; import { snapshotExactArray, snapshotExactObject } from "./exact-snapshot.ts"; +import { isLoopbackHostname } from "./deployment-admission.ts"; export type FetchCredentialsMode = "omit" | "same-origin" | "include"; @@ -248,7 +249,7 @@ export function createRestProviderProfile( const parsed = new URL(baseUrl); const localHttp = parsed.protocol === "http:" && - ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname); + isLoopbackHostname(parsed.hostname); if ( !providerId || (parsed.protocol !== "https:" && !localHttp) || diff --git a/tests/unit/deployment-admission.test.ts b/tests/unit/deployment-admission.test.ts index eb44038e..b0e71a39 100644 --- a/tests/unit/deployment-admission.test.ts +++ b/tests/unit/deployment-admission.test.ts @@ -80,13 +80,51 @@ describe("deployment admission", () => { } }); - it("permits a routable public host", () => { - expect( - findAdmissionViolations("production", { + it("refuses IPv6, mapped, CGNAT, 0/8 and internal-name hosts (Q-6.7-10)", () => { + for (const host of [ + "https://[::ffff:127.0.0.1]/", + "https://[::ffff:8.8.8.8]/", + "https://[fd00::1]/", + "https://[fc12:3456::1]/", + "https://[fe80::1]/", + "https://[febf::1]/", + "https://[0:0:0:0:0:0:0:1]/", + "https://100.64.0.1/", + "https://100.127.255.254/", + "https://0.1.2.3/", + "https://api.internal/", + "https://printer.local/", + "https://localhost./", + "https://api.internal./", + ]) { + const violations = findAdmissionViolations("production", { ...PRODUCTION_ARTIFACT, - API_BASE_URL: "https://api.172.16.example.com/", - } as AdmissionInput), - ).toEqual([]); + API_BASE_URL: host, + } as AdmissionInput); + expect(violations.map((violation) => violation.field), host).toContain( + "API_BASE_URL", + ); + } + }); + + it("permits a routable public host", () => { + for (const host of [ + "https://api.172.16.example.com/", + "https://100.128.0.1/", + "https://100.63.255.255/", + "https://[2001:db8::1]/", + "https://[fec0::1]/", + "https://internal.example.com/", + "https://local.example.com/", + ]) { + expect( + findAdmissionViolations("production", { + ...PRODUCTION_ARTIFACT, + API_BASE_URL: host, + } as AdmissionInput), + host, + ).toEqual([]); + } }); it("refuses a placeholder identity on a public target", () => {