@tak-ps/node-safeurl 1.0.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { isSafeUrl, isPrivateIPv4, isPrivateIPv6 } from './lib/safeurl.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { isSafeUrl, isPrivateIPv4, isPrivateIPv6 } from './lib/safeurl.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/lib/safeurl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns true for IPv4 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export declare function isPrivateIPv4(hostname: string): boolean;
+/**
+ * Returns true for IPv6 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export declare function isPrivateIPv6(address: string): boolean;
+export declare function isSafeUrl(href: string): Promise<{
+    safe: boolean;
+    url?: URL;
+    reason?: string;
+}>;

package/dist/lib/safeurl.js

@@ -0,0 +1,106 @@
+import { lookup } from 'node:dns/promises';
+import { IPAddressRanges } from '@microsoft/antissrf';
+import ipaddr from 'ipaddr.js';
+const blocked = IPAddressRanges.recommendedLatest
+    .map((cidr) => {
+    try {
+        const r = ipaddr.parseCIDR(cidr);
+        return { cidr, range: r };
+    }
+    catch {
+        return null;
+    }
+})
+    .filter((e) => e !== null);
+/** Returns true when `address` matches any blocked (private/special-purpose) CIDR. */
+function isBlockedIP(address) {
+    let parsed;
+    try {
+        parsed = ipaddr.parse(address);
+    }
+    catch {
+        return false;
+    }
+    // If the address is an IPv4-mapped IPv6 (::ffff:x.x.x.x), unwrap to IPv4
+    // so it can be checked against IPv4 CIDR ranges.
+    if (parsed.kind() === 'ipv6' && parsed.isIPv4MappedAddress()) {
+        parsed = parsed.toIPv4Address();
+    }
+    for (const entry of blocked) {
+        // Only compare within the same address family
+        if (entry.range[0].kind() !== parsed.kind())
+            continue;
+        if (parsed.match(entry.range))
+            return true;
+    }
+    return false;
+}
+/**
+ * Returns true for IPv4 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export function isPrivateIPv4(hostname) {
+    // Must be exactly four segments; each must be non-empty, numeric, and within 0–255.
+    // Number() normalizes whitespace-padded and zero-prefixed strings (e.g. "01" → 1,
+    // "  10  " → 10), which handles forms that ipaddr.parse() would otherwise reject.
+    const segments = hostname.split('.');
+    if (segments.length !== 4)
+        return false;
+    const parts = segments.map(Number);
+    if (parts.some((p, i) => segments[i].trim() === '' || Number.isNaN(p) || p < 0 || p > 255))
+        return false;
+    return isBlockedIP(parts.join('.'));
+}
+/**
+ * Returns true for IPv6 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export function isPrivateIPv6(address) {
+    // Strip zone ID (e.g. %eth0) and normalise to lowercase
+    const addr = address.toLowerCase().split('%')[0];
+    if (!addr.includes(':'))
+        return false;
+    return isBlockedIP(addr);
+}
+export async function isSafeUrl(href) {
+    let url;
+    try {
+        url = new URL(href);
+    }
+    catch {
+        return { safe: false, reason: `invalid URL: ${href}` };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { safe: false, url, reason: `unsupported protocol: ${url.protocol}` };
+    }
+    // Strip IPv6 brackets and any trailing dot (trailing dot is valid per DNS but bypasses
+    // literal hostname checks — e.g. "localhost." has the same meaning as "localhost").
+    const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    // Block known-bad hostname literals, including all subdomains of localhost
+    // (modern OS resolvers route *.localhost to 127.0.0.1).
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '0.0.0.0') {
+        return { safe: false, url, reason: `blocked hostname: ${hostname}` };
+    }
+    // Block private / special-purpose IP literals via the antissrf block list.
+    // This catches addresses like 127.0.0.1, 10.x.x.x, 192.168.x.x, fc00::, ::1, etc.
+    if (isBlockedIP(hostname)) {
+        return { safe: false, url, reason: `blocked IP address: ${hostname}` };
+    }
+    // Resolve the hostname via DNS and reject any result that maps to a private address.
+    // This guards against SSRF via public-looking hostnames that resolve to internal IPs.
+    // Fail open on DNS errors so that unreachable-but-legitimate hosts are not silently
+    // blocked; the subsequent fetch will surface any connectivity issues on its own.
+    try {
+        const records = await lookup(hostname, { all: true });
+        for (const { address } of records) {
+            if (isBlockedIP(address)) {
+                return { safe: false, url, reason: `hostname resolves to blocked IP: ${address}` };
+            }
+        }
+    }
+    catch {
+        // DNS lookup failed (NXDOMAIN, no network) — allow and let the fetch fail
+    }
+    return { safe: true, url };
+}
+//# sourceMappingURL=safeurl.js.map

package/dist/lib/safeurl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeurl.js","sourceRoot":"","sources":["../../lib/safeurl.ts"],"names":[],"mappings":"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"}

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@tak-ps/node-safeurl",
+    "type": "module",
+    "version": "1.0.0",
+    "description": "SSRF-safe URL validation library for Node.js",
+    "author": "Nick Ingalls <nick@ingalls.ca>",
+    "types": "index.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "test": "c8 --reporter=lcov --reporter html tsx --test test/*.ts",
+        "lint": "eslint *.ts lib/ test/",
+        "doc": "typedoc index.ts",
+        "build": "tsc --build && cp package.json dist/",
+        "pretest": "npm run lint"
+    },
+    "engines": {
+        "node": ">= 22"
+    },
+    "dependencies": {
+        "@microsoft/antissrf": "^1.0.0",
+        "ipaddr.js": "^2.4.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^25.0.0",
+        "c8": "^11.0.0",
+        "eslint": "^10.0.0",
+        "tsx": "^4.20.3",
+        "typedoc": "^0.28.0",
+        "typescript": "^6.0.0",
+        "typescript-eslint": "^8.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/dfpc-coe/node-safeurl.git"
+    },
+    "keywords": [
+        "ssrf",
+        "url",
+        "validation",
+        "security",
+        "safe-url"
+    ],
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/dfpc-coe/node-safeurl/issues"
+    },
+    "homepage": "https://github.com/dfpc-coe/node-safeurl#readme"
+}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../index.ts","../test/safeurl.test.ts","../lib/safeurl.ts"],"version":"6.0.3"}

package/eslint.config.js

@@ -0,0 +1,15 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    {
+        ignores: ['dist/**', 'docs/**', 'coverage/**']
+    },
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        "rules": {
+            "@typescript-eslint/no-explicit-any": "warn"
+        }
+    }
+);

package/index.ts

@@ -0,0 +1 @@
+export { isSafeUrl, isPrivateIPv4, isPrivateIPv6 } from './lib/safeurl.js';

package/lib/safeurl.ts

@@ -0,0 +1,118 @@
+import { lookup } from 'node:dns/promises';
+import { IPAddressRanges } from '@microsoft/antissrf';
+import ipaddr from 'ipaddr.js';
+
+// Pre-built (CIDR, parsed-range) pairs from Microsoft's maintained SSRF-prevention
+// IP address database.  Covers loopback, RFC 1918, link-local, CGNAT, ULA,
+// multicast, and all other special-purpose address blocks.
+// Kept current by updating @microsoft/antissrf.
+interface BlockEntry {
+    cidr: string;
+    range: [ipaddr.IPv4 | ipaddr.IPv6, number];
+}
+
+const blocked: BlockEntry[] = IPAddressRanges.recommendedLatest
+    .map((cidr) => {
+        try {
+            const r = ipaddr.parseCIDR(cidr);
+            return { cidr, range: r };
+        } catch {
+            return null;
+        }
+    })
+    .filter((e): e is BlockEntry => e !== null);
+
+/** Returns true when `address` matches any blocked (private/special-purpose) CIDR. */
+function isBlockedIP(address: string): boolean {
+    let parsed: ipaddr.IPv4 | ipaddr.IPv6;
+    try {
+        parsed = ipaddr.parse(address);
+    } catch {
+        return false;
+    }
+
+    // If the address is an IPv4-mapped IPv6 (::ffff:x.x.x.x), unwrap to IPv4
+    // so it can be checked against IPv4 CIDR ranges.
+    if (parsed.kind() === 'ipv6' && (parsed as ipaddr.IPv6).isIPv4MappedAddress()) {
+        parsed = (parsed as ipaddr.IPv6).toIPv4Address();
+    }
+
+    for (const entry of blocked) {
+        // Only compare within the same address family
+        if (entry.range[0].kind() !== parsed.kind()) continue;
+        if (parsed.match(entry.range)) return true;
+    }
+    return false;
+}
+
+/**
+ * Returns true for IPv4 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export function isPrivateIPv4(hostname: string): boolean {
+    // Must be exactly four segments; each must be non-empty, numeric, and within 0–255.
+    // Number() normalizes whitespace-padded and zero-prefixed strings (e.g. "01" → 1,
+    // "  10  " → 10), which handles forms that ipaddr.parse() would otherwise reject.
+    const segments = hostname.split('.');
+    if (segments.length !== 4) return false;
+    const parts = segments.map(Number);
+    if (parts.some((p, i) => segments[i].trim() === '' || Number.isNaN(p) || p < 0 || p > 255)) return false;
+    return isBlockedIP(parts.join('.'));
+}
+
+/**
+ * Returns true for IPv6 addresses that fall in private / special-purpose ranges.
+ * Delegates to `@microsoft/antissrf` `IPAddressRanges.recommendedLatest`.
+ */
+export function isPrivateIPv6(address: string): boolean {
+    // Strip zone ID (e.g. %eth0) and normalise to lowercase
+    const addr = address.toLowerCase().split('%')[0];
+    if (!addr.includes(':')) return false;
+    return isBlockedIP(addr);
+}
+
+export async function isSafeUrl(href: string): Promise<{ safe: boolean; url?: URL; reason?: string }> {
+    let url: URL;
+    try {
+        url = new URL(href);
+    } catch {
+        return { safe: false, reason: `invalid URL: ${href}` };
+    }
+
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { safe: false, url, reason: `unsupported protocol: ${url.protocol}` };
+    }
+
+    // Strip IPv6 brackets and any trailing dot (trailing dot is valid per DNS but bypasses
+    // literal hostname checks — e.g. "localhost." has the same meaning as "localhost").
+    const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+
+    // Block known-bad hostname literals, including all subdomains of localhost
+    // (modern OS resolvers route *.localhost to 127.0.0.1).
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '0.0.0.0') {
+        return { safe: false, url, reason: `blocked hostname: ${hostname}` };
+    }
+
+    // Block private / special-purpose IP literals via the antissrf block list.
+    // This catches addresses like 127.0.0.1, 10.x.x.x, 192.168.x.x, fc00::, ::1, etc.
+    if (isBlockedIP(hostname)) {
+        return { safe: false, url, reason: `blocked IP address: ${hostname}` };
+    }
+
+    // Resolve the hostname via DNS and reject any result that maps to a private address.
+    // This guards against SSRF via public-looking hostnames that resolve to internal IPs.
+    // Fail open on DNS errors so that unreachable-but-legitimate hosts are not silently
+    // blocked; the subsequent fetch will surface any connectivity issues on its own.
+    try {
+        const records = await lookup(hostname, { all: true });
+        for (const { address } of records) {
+            if (isBlockedIP(address)) {
+                return { safe: false, url, reason: `hostname resolves to blocked IP: ${address}` };
+            }
+        }
+    } catch {
+        // DNS lookup failed (NXDOMAIN, no network) — allow and let the fetch fail
+    }
+
+    return { safe: true, url };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@tak-ps/node-safeurl",
+    "type": "module",
+    "version": "1.0.0",
+    "description": "SSRF-safe URL validation library for Node.js",
+    "author": "Nick Ingalls <nick@ingalls.ca>",
+    "types": "index.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "test": "c8 --reporter=lcov --reporter html tsx --test test/*.ts",
+        "lint": "eslint *.ts lib/ test/",
+        "doc": "typedoc index.ts",
+        "build": "tsc --build && cp package.json dist/",
+        "pretest": "npm run lint"
+    },
+    "engines": {
+        "node": ">= 22"
+    },
+    "dependencies": {
+        "@microsoft/antissrf": "^1.0.0",
+        "ipaddr.js": "^2.4.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^25.0.0",
+        "c8": "^11.0.0",
+        "eslint": "^10.0.0",
+        "tsx": "^4.20.3",
+        "typedoc": "^0.28.0",
+        "typescript": "^6.0.0",
+        "typescript-eslint": "^8.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/dfpc-coe/node-safeurl.git"
+    },
+    "keywords": [
+        "ssrf",
+        "url",
+        "validation",
+        "security",
+        "safe-url"
+    ],
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/dfpc-coe/node-safeurl/issues"
+    },
+    "homepage": "https://github.com/dfpc-coe/node-safeurl#readme"
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "strictNullChecks": true,
+        "declaration": true,
+        "module": "es2022",
+        "esModuleInterop": true,
+        "target": "es2022",
+        "lib": ["es2022", "dom"],
+        "skipLibCheck": true,
+        "noImplicitAny": true,
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "verbatimModuleSyntax": true,
+        "sourceMap": true,
+        "types": ["node"],
+        "outDir": "dist"
+    },
+    "include": [
+        "index.ts",
+        "test/**/*",
+        "lib/*.ts"
+    ]
+}