Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,276 @@
const DEFAULT_OUTBOUND_HTTP_TIMEOUT_MS = 10_000;
const DEFAULT_OUTBOUND_HTTP_REDIRECT_LIMIT = 5;
const DEFAULT_OUTBOUND_HTTP_RESPONSE_LIMIT_BYTES = 16_384;
const INTERNAL_OUTBOUND_HOST_SUFFIXES = [".localhost", ".local", ".internal", ".lan", ".home", ".corp", ".intranet", ".svc"] as const;
export class OutboundHttpUrlValidationError extends Error {
constructor(message: string) {
super(message);
this.name = "OutboundHttpUrlValidationError";
}
}
export type OutboundHttpFetchOptions = {
fetchImpl?: typeof fetch;
addressResolver?: OutboundHttpAddressResolver;
timeoutMs?: number;
redirectLimit?: number;
};
export type LimitedResponseBody = {
body: string;
truncated: boolean;
};
export type OutboundHttpAddressResolver = (hostname: string) => Promise<ReadonlyArray<string>>;
export async function fetchOutboundHttpWithRedirects(input: string, init: RequestInit, options: OutboundHttpFetchOptions = {}): Promise<Response> {
const fetchImpl = options.fetchImpl ?? fetch;
const addressResolver = options.addressResolver ?? resolveOutboundHttpAddresses;
const redirectLimit = options.redirectLimit ?? DEFAULT_OUTBOUND_HTTP_REDIRECT_LIMIT;
let currentUrl = validateOutboundHttpUrl(input);
let currentInit = init;
for (let redirects = 0; redirects <= redirectLimit; redirects += 1) {
await assertOutboundHttpResolvedAddresses(currentUrl, addressResolver);
const response = await fetchOutboundHttpWithTimeout(fetchImpl, currentUrl, currentInit, options.timeoutMs ?? DEFAULT_OUTBOUND_HTTP_TIMEOUT_MS);
if (!isRedirectResponse(response.status)) {
return response;
}
const location = response.headers.get("location");
if (!location) {
return response;
}
if (redirects === redirectLimit) {
throw new OutboundHttpUrlValidationError("Outbound HTTP redirect limit exceeded.");
}
currentUrl = resolveOutboundHttpRedirect(currentUrl, location);
currentInit = buildRedirectRequestInit(currentInit, response.status);
}
throw new OutboundHttpUrlValidationError("Outbound HTTP redirect limit exceeded.");
}
export async function readLimitedResponseText(response: Response, limitBytes = DEFAULT_OUTBOUND_HTTP_RESPONSE_LIMIT_BYTES): Promise<LimitedResponseBody> {
if (!response.body) {
return { body: "", truncated: false };
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
const chunks: string[] = [];
let bytes = 0;
let truncated = false;
while (bytes < limitBytes) {
const result = await reader.read();
if (result.done) {
chunks.push(decoder.decode());
return { body: chunks.join(""), truncated };
}
const chunk = result.value;
const remaining = limitBytes - bytes;
const slice = chunk.byteLength > remaining ? chunk.slice(0, remaining) : chunk;
chunks.push(decoder.decode(slice, { stream: chunk.byteLength <= remaining }));
bytes += slice.byteLength;
if (chunk.byteLength > remaining) {
truncated = true;
await reader.cancel();
break;
}
}
chunks.push(decoder.decode());
return { body: chunks.join(""), truncated: truncated || bytes >= limitBytes };
}
export function validateOutboundHttpUrl(endpoint: string): string {
let url: URL;
try {
url = new URL(endpoint);
} catch {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint must be an absolute URL.");
}
if (url.protocol !== "http:" && url.protocol !== "https:") {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint must use http or https.");
}
if (isBlockedOutboundHostname(url.hostname)) {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint host is not allowed.");
}
return url.toString();
}
async function assertOutboundHttpResolvedAddresses(endpoint: string, addressResolver: OutboundHttpAddressResolver): Promise<void> {
const url = new URL(endpoint);
const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
if (parseIpv4Address(hostname) || parseIpv6Address(hostname)) {
return;
}
let addresses: ReadonlyArray<string>;
try {
addresses = await addressResolver(hostname);
} catch {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint host could not be resolved.");
}
if (addresses.length === 0) {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint host could not be resolved.");
}
if (addresses.some((address) => isBlockedOutboundHostname(address))) {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint resolved to a blocked address.");
}
}
async function resolveOutboundHttpAddresses(hostname: string): Promise<ReadonlyArray<string>> {
const dns = await import("node:dns/promises");
const addresses = await dns.lookup(hostname, { all: true, verbatim: false });
return addresses.map((address) => address.address);
}
async function fetchOutboundHttpWithTimeout(fetchImpl: typeof fetch, input: Parameters<typeof fetch>[0], init: RequestInit, timeoutMs: number): Promise<Response> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetchImpl(input, { ...init, redirect: "manual", signal: controller.signal });
} finally {
clearTimeout(timeout);
}
}
function resolveOutboundHttpRedirect(currentUrl: string, location: string): string {
let redirectUrl: URL;
try {
redirectUrl = new URL(location, currentUrl);
} catch {
throw new OutboundHttpUrlValidationError("Outbound HTTP redirect location must be a valid URL.");
}
return validateOutboundHttpUrl(redirectUrl.toString());
}
function isRedirectResponse(status: number): boolean {
return status >= 300 && status < 400;
}
function buildRedirectRequestInit(init: RequestInit, status: number): RequestInit {
const method = typeof init.method === "string" ? init.method.toUpperCase() : undefined;
if (status === 303 || ((status === 301 || status === 302) && method === "POST")) {
const headers = new Headers(init.headers);
headers.delete("content-type");
headers.delete("content-length");
return { ...init, method: "GET", body: undefined, headers };
}
return init;
}
function isBlockedOutboundHostname(hostname: string): boolean {
const normalizedHostname = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
if (!normalizedHostname) {
return true;
}
const ipv4 = parseIpv4Address(normalizedHostname);
if (ipv4) {
return isBlockedIpv4Address(ipv4);
}
const ipv6 = parseIpv6Address(normalizedHostname);
if (ipv6) {
return isBlockedIpv6Address(ipv6);
}
return (
normalizedHostname === "localhost" ||
!normalizedHostname.includes(".") ||
INTERNAL_OUTBOUND_HOST_SUFFIXES.some((suffix) => normalizedHostname.endsWith(suffix))
);
}
function parseIpv4Address(hostname: string): [number, number, number, number] | undefined {
const parts = hostname.split(".");
if (parts.length !== 4) {
return undefined;
}
const octets = parts.map((part) => Number(part));
if (octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
return undefined;
}
return octets as [number, number, number, number];
}
function isBlockedIpv4Address([first, second]: [number, number, number, number]): boolean {
return (
first === 0 ||
first === 10 ||
first === 127 ||
first >= 224 ||
(first === 100 && second >= 64 && second <= 127) ||
(first === 169 && second === 254) ||
(first === 172 && second >= 16 && second <= 31) ||
(first === 192 && second === 168) ||
(first === 198 && (second === 18 || second === 19))
);
}
function parseIpv6Address(hostname: string): number[] | undefined {
if (!hostname.includes(":")) {
return undefined;
}
const [head = "", tail = "", extra] = hostname.split("::");
if (extra !== undefined) {
return undefined;
}
const headParts = head ? head.split(":") : [];
const tailParts = tail ? tail.split(":") : [];
const missingPartCount = 8 - headParts.length - tailParts.length;
if (missingPartCount < 0 || (!hostname.includes("::") && missingPartCount !== 0)) {
return undefined;
}
const parts = [...headParts, ...Array(missingPartCount).fill("0"), ...tailParts];
if (parts.length !== 8) {
return undefined;
}
const hextets = parts.map((part) => Number.parseInt(part, 16));
if (hextets.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff)) {
return undefined;
}
return hextets;
}
function isBlockedIpv6Address(hextets: number[]): boolean {
const first = hextets[0] ?? 0;
const isUnspecified = hextets.every((part) => part === 0);
const isLoopback = hextets.slice(0, 7).every((part) => part === 0) && hextets[7] === 1;
const isUniqueLocal = (first & 0xfe00) === 0xfc00;
const isLinkLocal = (first & 0xffc0) === 0xfe80;
const isIpv4Mapped = hextets.slice(0, 5).every((part) => part === 0) && hextets[5] === 0xffff;
const isIpv4Compatible = hextets.slice(0, 6).every((part) => part === 0);
if (isUnspecified || isLoopback || isUniqueLocal || isLinkLocal) {
return true;
}
if (isIpv4Mapped || isIpv4Compatible) {
const ipv4: [number, number, number, number] = [hextets[6] >> 8, hextets[6] & 0xff, hextets[7] >> 8, hextets[7] & 0xff];
return isBlockedIpv4Address(ipv4);
}
return false;
}