@resq-systems/security 1.0.5 → 2.0.0

package/lib/controls/address.mjs

@@ -0,0 +1,533 @@
+//#region src/controls/address.ts
+/** Four octets, or `null` when the text is not a dotted-quad IPv4 address. */
+function parseIpv4(host) {
+	const parts = host.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [];
+	for (const part of parts) {
+		if (part.length === 0 || part.length > 3 || !/^\d+$/.test(part)) return null;
+		const value = Number(part);
+		if (value > 255) return null;
+		octets.push(value);
+	}
+	return octets;
+}
+/**
+* Eight 16-bit groups, or `null` when the text is not an IPv6 address.
+*
+* Accepts the bracketed, zero-compressed form `URL.hostname` produces, and the
+* dotted-quad tail of an IPv4-mapped address.
+*/
+function parseIpv6(host) {
+	let text = host;
+	if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+	const zone = text.indexOf("%");
+	if (zone !== -1) text = text.slice(0, zone);
+	if (!text.includes(":")) return null;
+	let tail = [];
+	const lastColon = text.lastIndexOf(":");
+	const suffix = text.slice(lastColon + 1);
+	if (suffix.includes(".")) {
+		const octets = parseIpv4(suffix);
+		if (octets === null) return null;
+		tail = [octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]];
+		text = text.slice(0, lastColon);
+		if (!text.endsWith(":")) text += ":";
+		text = text.slice(0, -1);
+		if (text.length === 0) text = "::";
+	}
+	const halves = text.split("::");
+	if (halves.length > 2) return null;
+	const toGroups = (part) => {
+		if (part.length === 0) return [];
+		const groups = [];
+		for (const piece of part.split(":")) {
+			if (piece.length === 0 || piece.length > 4 || !/^[0-9a-f]+$/i.test(piece)) return null;
+			groups.push(Number.parseInt(piece, 16));
+		}
+		return groups;
+	};
+	const head = toGroups(halves[0] ?? "");
+	if (head === null) return null;
+	if (halves.length === 1) {
+		const all = [...head, ...tail];
+		return all.length === 8 ? all : null;
+	}
+	const rest = toGroups(halves[1] ?? "");
+	if (rest === null) return null;
+	const known = head.length + rest.length + tail.length;
+	if (known > 8) return null;
+	return [
+		...head,
+		...new Array(8 - known).fill(0),
+		...rest,
+		...tail
+	];
+}
+/** IPv4 special-purpose ranges, as `[network, prefixLength, classification]`. */
+const IPV4_RANGES = [
+	[
+		[
+			0,
+			0,
+			0,
+			0
+		],
+		8,
+		"unspecified"
+	],
+	[
+		[
+			10,
+			0,
+			0,
+			0
+		],
+		8,
+		"private"
+	],
+	[
+		[
+			100,
+			64,
+			0,
+			0
+		],
+		10,
+		"carrier_nat"
+	],
+	[
+		[
+			127,
+			0,
+			0,
+			0
+		],
+		8,
+		"loopback"
+	],
+	[
+		[
+			169,
+			254,
+			0,
+			0
+		],
+		16,
+		"link_local"
+	],
+	[
+		[
+			172,
+			16,
+			0,
+			0
+		],
+		12,
+		"private"
+	],
+	[
+		[
+			192,
+			0,
+			2,
+			0
+		],
+		24,
+		"documentation"
+	],
+	[
+		[
+			192,
+			88,
+			99,
+			0
+		],
+		24,
+		"reserved"
+	],
+	[
+		[
+			192,
+			0,
+			0,
+			0
+		],
+		24,
+		"reserved"
+	],
+	[
+		[
+			192,
+			168,
+			0,
+			0
+		],
+		16,
+		"private"
+	],
+	[
+		[
+			198,
+			18,
+			0,
+			0
+		],
+		15,
+		"benchmarking"
+	],
+	[
+		[
+			198,
+			51,
+			100,
+			0
+		],
+		24,
+		"documentation"
+	],
+	[
+		[
+			203,
+			0,
+			113,
+			0
+		],
+		24,
+		"documentation"
+	],
+	[
+		[
+			224,
+			0,
+			0,
+			0
+		],
+		4,
+		"multicast"
+	],
+	[
+		[
+			255,
+			255,
+			255,
+			255
+		],
+		32,
+		"broadcast"
+	],
+	[
+		[
+			240,
+			0,
+			0,
+			0
+		],
+		4,
+		"reserved"
+	]
+];
+/** IPv6 special-purpose ranges, as `[groups, prefixLength, classification]`. */
+const IPV6_RANGES = [
+	[
+		[
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			1
+		],
+		128,
+		"loopback"
+	],
+	[
+		[
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		128,
+		"unspecified"
+	],
+	[
+		[
+			100,
+			65435,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		96,
+		"nat64"
+	],
+	[
+		[
+			256,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		64,
+		"reserved"
+	],
+	[
+		[
+			8193,
+			3512,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		32,
+		"documentation"
+	],
+	[
+		[
+			8193,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		32,
+		"teredo"
+	],
+	[
+		[
+			8194,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		16,
+		"six_to_four"
+	],
+	[
+		[
+			64512,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		7,
+		"unique_local"
+	],
+	[
+		[
+			65152,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		10,
+		"link_local"
+	],
+	[
+		[
+			65280,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0,
+			0
+		],
+		8,
+		"multicast"
+	]
+];
+/** Whether `parts` sits inside `network/prefix`, given `bits` per part. */
+function withinPrefix(parts, network, prefix, bits) {
+	let remaining = prefix;
+	for (let index = 0; index < parts.length && remaining > 0; index++) {
+		const width = Math.min(bits, remaining);
+		const shift = bits - width;
+		if (parts[index] >>> shift !== network[index] >>> shift) return false;
+		remaining -= width;
+	}
+	return true;
+}
+/** IPv4-mapped IPv6 prefix, `::ffff:0:0/96`. */
+const IPV4_MAPPED = [
+	0,
+	0,
+	0,
+	0,
+	0,
+	65535,
+	0,
+	0
+];
+/** Classify four octets against the IPv4 table. */
+function classifyIpv4(octets) {
+	for (const [network, prefix, classification] of IPV4_RANGES) if (withinPrefix(octets, network, prefix, 8)) return classification;
+	return "public";
+}
+/**
+* Classify a host as an IP address range, or `null` when it is not an IP literal.
+*
+* `null` is the answer for every domain name, and a caller must treat it as *unknown*
+* rather than safe — conflating the two is the classic fail-open in this kind of check.
+* {@link assertOutboundUrl} handles it explicitly.
+*
+* IPv4-mapped IPv6 addresses are unwrapped and classified by the address they carry, so
+* `::ffff:169.254.169.254` is `link_local` rather than merely "some IPv6 address". That
+* form matters in practice: `new URL("http://[::ffff:169.254.169.254]/").hostname`
+* returns the bracketed, hex-compressed `[::ffff:a9fe:a9fe]`, which a string check misses.
+*
+* @param host - Hostname or IP literal, with or without IPv6 brackets.
+* @returns The classification, or `null` when `host` is not an IP literal.
+*
+* @example
+* ```ts
+* classifyAddress("169.254.169.254");      // "link_local"
+* classifyAddress("172.32.0.1");           // "public" — just outside 172.16/12
+* classifyAddress("[::ffff:a9fe:a9fe]");   // "link_local"
+* classifyAddress("metadata.example.com"); // null — a name, not an address
+* ```
+*/
+function classifyAddress(host) {
+	if (typeof host !== "string" || host.length === 0) return null;
+	const octets = parseIpv4(host);
+	if (octets !== null) return classifyIpv4(octets);
+	const groups = parseIpv6(host);
+	if (groups === null) return null;
+	if (withinPrefix(groups, IPV4_MAPPED, 96, 16)) {
+		const high = groups[6];
+		const low = groups[7];
+		return classifyIpv4([
+			high >>> 8,
+			high & 255,
+			low >>> 8,
+			low & 255
+		]);
+	}
+	for (const [network, prefix, classification] of IPV6_RANGES) if (withinPrefix(groups, network, prefix, 16)) return classification;
+	return "public";
+}
+/**
+* Whether a host is an IP literal in a publicly routable range.
+*
+* @param host - Hostname or IP literal.
+* @returns `true` only for a routable IP literal. A domain name returns `false`, because
+*   this function cannot know what it resolves to.
+*/
+function isPubliclyRoutableAddress(host) {
+	return classifyAddress(host) === "public";
+}
+/** Default schemes. `https:` only — a server fetching over `http:` is its own problem. */
+const DEFAULT_PROTOCOLS = ["https:"];
+/**
+* Decide whether a server may fetch a caller-supplied URL.
+*
+* The control the SSRF rules name. Those rules match literal addresses inside a string;
+* this decides whether the request should be made at all.
+*
+* **Default deny, exhaustively.** Every path ends in an explicit allow or an explicit
+* refusal. That is deliberate: `classifyAddress` returns `null` for every domain name, so
+* a policy shaped "reject non-public *literals*" silently permits every name — the exact
+* fail-open this control exists to prevent. With no `allowedHosts` and `allowPublicHosts`
+* off, a name is refused.
+*
+* **A pre-connection check, and it cannot be more.** The name is resolved by the network
+* stack after this returns, so DNS may answer differently then (rebinding); redirects
+* need the same check applied per hop; neither is closable by a synchronous function.
+* Network-layer egress control remains the durable fix — this narrows the window rather
+* than shutting it.
+*
+* @param candidate - The URL to fetch, as text or a parsed `URL`.
+* @param policy - See {@link OutboundUrlPolicy}. Defaults refuse everything not named.
+* @returns A discriminated verdict. Never throws.
+*
+* @example
+* ```ts
+* const verdict = assertOutboundUrl(webhookUrl, { allowedHosts: ["hooks.partner.example"] });
+* if (!verdict.allowed) return reject(verdict.reason);
+* await fetch(verdict.url);
+* ```
+*/
+function assertOutboundUrl(candidate, policy = {}) {
+	let url;
+	try {
+		url = candidate instanceof URL ? candidate : new URL(String(candidate));
+	} catch {
+		return {
+			allowed: false,
+			reason: "malformed"
+		};
+	}
+	if (!(policy.allowedProtocols ?? DEFAULT_PROTOCOLS).includes(url.protocol)) return {
+		allowed: false,
+		reason: "protocol_not_allowed"
+	};
+	if (url.port !== "") {
+		const port = Number(url.port);
+		if (!(policy.allowedPorts ?? []).includes(port)) return {
+			allowed: false,
+			reason: "port_not_allowed"
+		};
+	}
+	const host = url.hostname.toLowerCase();
+	const named = (policy.allowedHosts ?? []).some((allowed) => allowed.trim().toLowerCase() === host);
+	const classification = classifyAddress(host);
+	if (classification !== null) {
+		if (classification !== "public") return {
+			allowed: false,
+			reason: "address_not_routable"
+		};
+		return named || policy.allowPublicHosts === true ? {
+			allowed: true,
+			url,
+			classification
+		} : {
+			allowed: false,
+			reason: "host_not_allowed"
+		};
+	}
+	return named || policy.allowPublicHosts === true ? {
+		allowed: true,
+		url,
+		classification: null
+	} : {
+		allowed: false,
+		reason: "host_not_allowed"
+	};
+}
+//#endregion
+export { assertOutboundUrl, classifyAddress, isPubliclyRoutableAddress };
+
+//# sourceMappingURL=address.mjs.map

package/lib/controls/address.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.mjs","names":[],"sources":["../../src/controls/address.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview IP address classification and outbound-URL policy — the SSRF control\n * the detection rules name but cannot themselves provide.\n *\n * The signatures in `threats/rules/system.ts` match literal addresses. A hostname whose\n * DNS record resolves to `169.254.169.254` passes every one of them, which is why those\n * rules point here instead.\n *\n * @module @resq-systems/security/controls/address\n */\n\n//#region Types\n\n/**\n * What an address is reserved for, per the IANA special-purpose registries.\n *\n * `public` means \"in no special-purpose range\" — routable on the internet. Every other\n * value is a reason not to fetch it from a server.\n */\nexport type AddressClassification =\n\t| \"unspecified\"\n\t| \"loopback\"\n\t| \"private\"\n\t| \"link_local\"\n\t| \"carrier_nat\"\n\t| \"multicast\"\n\t| \"broadcast\"\n\t| \"documentation\"\n\t| \"benchmarking\"\n\t| \"unique_local\"\n\t| \"teredo\"\n\t| \"six_to_four\"\n\t| \"nat64\"\n\t| \"reserved\"\n\t| \"public\";\n\n/** Why an outbound URL was refused. */\nexport type OutboundRejectionReason =\n\t/** Not parseable as a URL. */\n\t| \"malformed\"\n\t/** Scheme outside the permitted set. */\n\t| \"protocol_not_allowed\"\n\t/** Port outside the permitted set. */\n\t| \"port_not_allowed\"\n\t/** An IP literal in a range that is not publicly routable. */\n\t| \"address_not_routable\"\n\t/** A routable address, or a name, that policy does not permit. */\n\t| \"host_not_allowed\";\n\n/** Outcome of {@link assertOutboundUrl}. */\nexport type OutboundUrlVerdict =\n\t| {\n\t\t\treadonly allowed: true;\n\t\t\treadonly url: URL;\n\t\t\t/** `null` when the host is a name rather than an IP literal. */\n\t\t\treadonly classification: AddressClassification | null;\n\t  }\n\t| { readonly allowed: false; readonly reason: OutboundRejectionReason };\n\n/** Policy for {@link assertOutboundUrl}. */\nexport interface OutboundUrlPolicy {\n\t/**\n\t * Hosts permitted regardless of classification, compared case-insensitively against\n\t * the parsed host. The allowlist the OWASP cheat sheet asks for.\n\t */\n\treadonly allowedHosts?: readonly string[];\n\t/** Schemes permitted. Defaults to `[\"https:\"]`. */\n\treadonly allowedProtocols?: readonly string[];\n\t/** Ports permitted in addition to the scheme's default. Defaults to none. */\n\treadonly allowedPorts?: readonly number[];\n\t/**\n\t * Permit any host not in a reserved range — every public address, and every name.\n\t *\n\t * Defaults to `false`, and that default is the point. A name is not an address: this\n\t * function cannot know whether `metadata.example.com` resolves to a public address or\n\t * to `169.254.169.254`. With no allowlist and this flag off, a name is refused.\n\t * Turning it on converts the control from an allowlist into a denylist over literals\n\t * only, which does not stop DNS from pointing inward.\n\t */\n\treadonly allowPublicHosts?: boolean;\n}\n\n//#endregion\n\n//#region Parsing\n\n/** Four octets, or `null` when the text is not a dotted-quad IPv4 address. */\nfunction parseIpv4(host: string): readonly number[] | null {\n\tconst parts = host.split(\".\");\n\tif (parts.length !== 4) return null;\n\n\tconst octets: number[] = [];\n\tfor (const part of parts) {\n\t\t// Rejects empty, signed, hex, octal and over-long forms. `new URL` already\n\t\t// canonicalises those for a parsed hostname; this matters for a caller handing a\n\t\t// raw string straight to `classifyAddress`.\n\t\tif (part.length === 0 || part.length > 3 || !/^\\d+$/.test(part)) return null;\n\t\tconst value = Number(part);\n\t\tif (value > 255) return null;\n\t\toctets.push(value);\n\t}\n\treturn octets;\n}\n\n/**\n * Eight 16-bit groups, or `null` when the text is not an IPv6 address.\n *\n * Accepts the bracketed, zero-compressed form `URL.hostname` produces, and the\n * dotted-quad tail of an IPv4-mapped address.\n */\nfunction parseIpv6(host: string): readonly number[] | null {\n\tlet text = host;\n\tif (text.startsWith(\"[\") && text.endsWith(\"]\")) text = text.slice(1, -1);\n\n\t// A zone identifier is not part of the address.\n\tconst zone = text.indexOf(\"%\");\n\tif (zone !== -1) text = text.slice(0, zone);\n\n\tif (!text.includes(\":\")) return null;\n\n\t// A trailing dotted quad contributes the final two groups.\n\tlet tail: number[] = [];\n\tconst lastColon = text.lastIndexOf(\":\");\n\tconst suffix = text.slice(lastColon + 1);\n\tif (suffix.includes(\".\")) {\n\t\tconst octets = parseIpv4(suffix);\n\t\tif (octets === null) return null;\n\t\ttail = [\n\t\t\t((octets[0] as number) << 8) | (octets[1] as number),\n\t\t\t((octets[2] as number) << 8) | (octets[3] as number),\n\t\t];\n\t\ttext = text.slice(0, lastColon);\n\t\tif (!text.endsWith(\":\")) text += \":\";\n\t\ttext = text.slice(0, -1);\n\t\tif (text.length === 0) text = \"::\";\n\t}\n\n\tconst halves = text.split(\"::\");\n\tif (halves.length > 2) return null;\n\n\tconst toGroups = (part: string): number[] | null => {\n\t\tif (part.length === 0) return [];\n\t\tconst groups: number[] = [];\n\t\tfor (const piece of part.split(\":\")) {\n\t\t\tif (piece.length === 0 || piece.length > 4 || !/^[0-9a-f]+$/i.test(piece)) return null;\n\t\t\tgroups.push(Number.parseInt(piece, 16));\n\t\t}\n\t\treturn groups;\n\t};\n\n\tconst head = toGroups(halves[0] ?? \"\");\n\tif (head === null) return null;\n\n\tif (halves.length === 1) {\n\t\tconst all = [...head, ...tail];\n\t\treturn all.length === 8 ? all : null;\n\t}\n\n\tconst rest = toGroups(halves[1] ?? \"\");\n\tif (rest === null) return null;\n\n\tconst known = head.length + rest.length + tail.length;\n\tif (known > 8) return null;\n\treturn [...head, ...(new Array(8 - known).fill(0) as number[]), ...rest, ...tail];\n}\n\n//#endregion\n\n//#region Classification\n\n/** IPv4 special-purpose ranges, as `[network, prefixLength, classification]`. */\nconst IPV4_RANGES: readonly (readonly [readonly number[], number, AddressClassification])[] = [\n\t[[0, 0, 0, 0], 8, \"unspecified\"],\n\t[[10, 0, 0, 0], 8, \"private\"],\n\t[[100, 64, 0, 0], 10, \"carrier_nat\"],\n\t[[127, 0, 0, 0], 8, \"loopback\"],\n\t[[169, 254, 0, 0], 16, \"link_local\"],\n\t[[172, 16, 0, 0], 12, \"private\"],\n\t[[192, 0, 2, 0], 24, \"documentation\"],\n\t[[192, 88, 99, 0], 24, \"reserved\"],\n\t[[192, 0, 0, 0], 24, \"reserved\"],\n\t[[192, 168, 0, 0], 16, \"private\"],\n\t[[198, 18, 0, 0], 15, \"benchmarking\"],\n\t[[198, 51, 100, 0], 24, \"documentation\"],\n\t[[203, 0, 113, 0], 24, \"documentation\"],\n\t[[224, 0, 0, 0], 4, \"multicast\"],\n\t[[255, 255, 255, 255], 32, \"broadcast\"],\n\t[[240, 0, 0, 0], 4, \"reserved\"],\n];\n\n/** IPv6 special-purpose ranges, as `[groups, prefixLength, classification]`. */\nconst IPV6_RANGES: readonly (readonly [readonly number[], number, AddressClassification])[] = [\n\t[[0, 0, 0, 0, 0, 0, 0, 1], 128, \"loopback\"],\n\t[[0, 0, 0, 0, 0, 0, 0, 0], 128, \"unspecified\"],\n\t[[0x64, 0xff9b, 0, 0, 0, 0, 0, 0], 96, \"nat64\"],\n\t[[0x100, 0, 0, 0, 0, 0, 0, 0], 64, \"reserved\"],\n\t[[0x2001, 0x0db8, 0, 0, 0, 0, 0, 0], 32, \"documentation\"],\n\t// Teredo. Absent from the first draft of this table, which classified it public.\n\t[[0x2001, 0, 0, 0, 0, 0, 0, 0], 32, \"teredo\"],\n\t[[0x2002, 0, 0, 0, 0, 0, 0, 0], 16, \"six_to_four\"],\n\t[[0xfc00, 0, 0, 0, 0, 0, 0, 0], 7, \"unique_local\"],\n\t[[0xfe80, 0, 0, 0, 0, 0, 0, 0], 10, \"link_local\"],\n\t[[0xff00, 0, 0, 0, 0, 0, 0, 0], 8, \"multicast\"],\n];\n\n/** Whether `parts` sits inside `network/prefix`, given `bits` per part. */\nfunction withinPrefix(\n\tparts: readonly number[],\n\tnetwork: readonly number[],\n\tprefix: number,\n\tbits: number,\n): boolean {\n\tlet remaining = prefix;\n\tfor (let index = 0; index < parts.length && remaining > 0; index++) {\n\t\tconst width = Math.min(bits, remaining);\n\t\tconst shift = bits - width;\n\t\tif ((parts[index] as number) >>> shift !== (network[index] as number) >>> shift) return false;\n\t\tremaining -= width;\n\t}\n\treturn true;\n}\n\n/** IPv4-mapped IPv6 prefix, `::ffff:0:0/96`. */\nconst IPV4_MAPPED: readonly number[] = [0, 0, 0, 0, 0, 0xffff, 0, 0];\n\n/** Classify four octets against the IPv4 table. */\nfunction classifyIpv4(octets: readonly number[]): AddressClassification {\n\tfor (const [network, prefix, classification] of IPV4_RANGES) {\n\t\tif (withinPrefix(octets, network, prefix, 8)) return classification;\n\t}\n\treturn \"public\";\n}\n\n/**\n * Classify a host as an IP address range, or `null` when it is not an IP literal.\n *\n * `null` is the answer for every domain name, and a caller must treat it as *unknown*\n * rather than safe — conflating the two is the classic fail-open in this kind of check.\n * {@link assertOutboundUrl} handles it explicitly.\n *\n * IPv4-mapped IPv6 addresses are unwrapped and classified by the address they carry, so\n * `::ffff:169.254.169.254` is `link_local` rather than merely \"some IPv6 address\". That\n * form matters in practice: `new URL(\"http://[::ffff:169.254.169.254]/\").hostname`\n * returns the bracketed, hex-compressed `[::ffff:a9fe:a9fe]`, which a string check misses.\n *\n * @param host - Hostname or IP literal, with or without IPv6 brackets.\n * @returns The classification, or `null` when `host` is not an IP literal.\n *\n * @example\n * ```ts\n * classifyAddress(\"169.254.169.254\");      // \"link_local\"\n * classifyAddress(\"172.32.0.1\");           // \"public\" — just outside 172.16/12\n * classifyAddress(\"[::ffff:a9fe:a9fe]\");   // \"link_local\"\n * classifyAddress(\"metadata.example.com\"); // null — a name, not an address\n * ```\n */\nexport function classifyAddress(host: string): AddressClassification | null {\n\tif (typeof host !== \"string\" || host.length === 0) return null;\n\n\tconst octets = parseIpv4(host);\n\tif (octets !== null) return classifyIpv4(octets);\n\n\tconst groups = parseIpv6(host);\n\tif (groups === null) return null;\n\n\tif (withinPrefix(groups, IPV4_MAPPED, 96, 16)) {\n\t\tconst high = groups[6] as number;\n\t\tconst low = groups[7] as number;\n\t\treturn classifyIpv4([high >>> 8, high & 0xff, low >>> 8, low & 0xff]);\n\t}\n\n\tfor (const [network, prefix, classification] of IPV6_RANGES) {\n\t\tif (withinPrefix(groups, network, prefix, 16)) return classification;\n\t}\n\treturn \"public\";\n}\n\n/**\n * Whether a host is an IP literal in a publicly routable range.\n *\n * @param host - Hostname or IP literal.\n * @returns `true` only for a routable IP literal. A domain name returns `false`, because\n *   this function cannot know what it resolves to.\n */\nexport function isPubliclyRoutableAddress(host: string): boolean {\n\treturn classifyAddress(host) === \"public\";\n}\n\n//#endregion\n\n//#region Outbound policy\n\n/** Default schemes. `https:` only — a server fetching over `http:` is its own problem. */\nconst DEFAULT_PROTOCOLS: readonly string[] = [\"https:\"];\n\n/**\n * Decide whether a server may fetch a caller-supplied URL.\n *\n * The control the SSRF rules name. Those rules match literal addresses inside a string;\n * this decides whether the request should be made at all.\n *\n * **Default deny, exhaustively.** Every path ends in an explicit allow or an explicit\n * refusal. That is deliberate: `classifyAddress` returns `null` for every domain name, so\n * a policy shaped \"reject non-public *literals*\" silently permits every name — the exact\n * fail-open this control exists to prevent. With no `allowedHosts` and `allowPublicHosts`\n * off, a name is refused.\n *\n * **A pre-connection check, and it cannot be more.** The name is resolved by the network\n * stack after this returns, so DNS may answer differently then (rebinding); redirects\n * need the same check applied per hop; neither is closable by a synchronous function.\n * Network-layer egress control remains the durable fix — this narrows the window rather\n * than shutting it.\n *\n * @param candidate - The URL to fetch, as text or a parsed `URL`.\n * @param policy - See {@link OutboundUrlPolicy}. Defaults refuse everything not named.\n * @returns A discriminated verdict. Never throws.\n *\n * @example\n * ```ts\n * const verdict = assertOutboundUrl(webhookUrl, { allowedHosts: [\"hooks.partner.example\"] });\n * if (!verdict.allowed) return reject(verdict.reason);\n * await fetch(verdict.url);\n * ```\n */\nexport function assertOutboundUrl(\n\tcandidate: string | URL,\n\tpolicy: OutboundUrlPolicy = {},\n): OutboundUrlVerdict {\n\tlet url: URL;\n\ttry {\n\t\turl = candidate instanceof URL ? candidate : new URL(String(candidate));\n\t} catch {\n\t\treturn { allowed: false, reason: \"malformed\" };\n\t}\n\n\tconst protocols = policy.allowedProtocols ?? DEFAULT_PROTOCOLS;\n\tif (!protocols.includes(url.protocol)) {\n\t\treturn { allowed: false, reason: \"protocol_not_allowed\" };\n\t}\n\n\t// An empty `port` means the scheme default, which is always acceptable.\n\tif (url.port !== \"\") {\n\t\tconst port = Number(url.port);\n\t\tif (!(policy.allowedPorts ?? []).includes(port)) {\n\t\t\treturn { allowed: false, reason: \"port_not_allowed\" };\n\t\t}\n\t}\n\n\tconst host = url.hostname.toLowerCase();\n\tconst named = (policy.allowedHosts ?? []).some(\n\t\t(allowed) => allowed.trim().toLowerCase() === host,\n\t);\n\tconst classification = classifyAddress(host);\n\n\t// An IP literal is judged on its range first: naming a loopback address in an\n\t// allowlist should not turn it into a route back into the host.\n\tif (classification !== null) {\n\t\tif (classification !== \"public\") return { allowed: false, reason: \"address_not_routable\" };\n\t\treturn named || policy.allowPublicHosts === true\n\t\t\t? { allowed: true, url, classification }\n\t\t\t: { allowed: false, reason: \"host_not_allowed\" };\n\t}\n\n\t// A name. Nothing available here can tell what it resolves to.\n\treturn named || policy.allowPublicHosts === true\n\t\t? { allowed: true, url, classification: null }\n\t\t: { allowed: false, reason: \"host_not_allowed\" };\n}\n\n//#endregion\n"],"mappings":"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"}

package/lib/controls/csrf.d.mts

@@ -0,0 +1,91 @@
+//#region src/controls/csrf.d.ts
+/**
+ * Copyright 2026 ResQ Systems, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Options for {@link createCsrfToken}. */
+interface CsrfTokenOptions {
+  /**
+   * Session identifier to bind the token to. Strongly recommended: without it, a
+   * token minted by any user verifies for every other user.
+   */
+  readonly sessionId?: string;
+  /** Lifetime in milliseconds. Defaults to two hours. */
+  readonly ttlMs?: number;
+}
+/**
+ * Mint a signed CSRF token.
+ *
+ * Send it to the client in a readable cookie *and* require it back in a header or form
+ * field. A cross-origin page can cause the cookie to be sent but cannot read it, so it
+ * cannot populate the second copy.
+ *
+ * @param secret - Server-side signing secret. Must be non-empty; use at least 32 bytes
+ *   of entropy from a secret manager, and never a value shipped to the client.
+ * @param options - See {@link CsrfTokenOptions}.
+ * @returns An opaque token safe to place in a cookie, header, or hidden form field.
+ * @throws {TypeError} If `secret` is empty, if `sessionId` is present but is not a
+ *   well-formed string, or if `ttlMs` is not a positive integer. Each of the three is
+ *   a programming error that would otherwise weaken the token silently — a non-string
+ *   `sessionId` binds every session to the same signature, and a fractional `ttlMs`
+ *   injects the field separator into the expiry.
+ *
+ * @example
+ * ```ts
+ * const token = createCsrfToken(process.env.CSRF_SECRET!, { sessionId: session.id });
+ * res.setHeader("Set-Cookie", `csrf=${token}; Path=/; SameSite=Lax`);
+ * ```
+ */
+declare function createCsrfToken(secret: string, options?: CsrfTokenOptions): string;
+/** Why a CSRF token was rejected. */
+type CsrfFailureReason = "malformed" | "expired" | "signature_mismatch" | "missing_token" | "missing_secret";
+/** Outcome of {@link verifyCsrfToken}. */
+type CsrfVerification = {
+  readonly valid: true;
+} | {
+  readonly valid: false;
+  readonly reason: CsrfFailureReason;
+};
+/** Options for {@link verifyCsrfToken}. */
+interface CsrfVerifyOptions {
+  /** Session the token must be bound to. Must match the value used at mint time. */
+  readonly sessionId?: string;
+}
+/**
+ * Verify a signed CSRF token.
+ *
+ * Checks the signature in constant time, then the expiry. The failure `reason` is for
+ * server-side logging — do not return it to the client, since it distinguishes
+ * "expired" from "forged" for anyone probing the endpoint.
+ *
+ * @param token - The token submitted with the request.
+ * @param secret - The same signing secret used at mint time.
+ * @param options - See {@link CsrfVerifyOptions}.
+ * @returns `{ valid: true }`, or `{ valid: false, reason }`. Never throws.
+ *
+ * @example
+ * ```ts
+ * const result = verifyCsrfToken(req.headers["x-csrf-token"], secret, {
+ *   sessionId: session.id,
+ * });
+ * if (!result.valid) {
+ *   logger.warn("csrf rejected", { reason: result.reason });
+ *   return new Response("Forbidden", { status: 403 });
+ * }
+ * ```
+ */
+declare function verifyCsrfToken(token: string | undefined | null, secret: string, options?: CsrfVerifyOptions): CsrfVerification;
+//#endregion
+export { CsrfFailureReason, CsrfTokenOptions, CsrfVerification, CsrfVerifyOptions, createCsrfToken, verifyCsrfToken };
+//# sourceMappingURL=csrf.d.mts.map

package/lib/controls/csrf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.mts","names":[],"sources":["../../src/controls/csrf.ts"],"mappings":";;;;;;;;;;;;;;;;;UA4DiB;;;;;WAKP;;WAEA;;;;;;;;;;;;;;;;;;;;;;;;;iBA4EM,gBAAgB,gBAAgB,UAAS;;KAmC7C;;KAQA;WACE;;WACA;WAAuB,QAAQ;;;UAG5B;;WAEP;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCM,gBACf,kCACA,gBACA,UAAS,oBACP"}