@socketsecurity/lib 6.0.7 → 6.0.9

package/dist/strings/format.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_primordials_math = require('../primordials/math.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_math = require('../primordials/math.js');
 const require_ansi_strip = require('../ansi/strip.js');
 
 //#region src/strings/format.ts

package/dist/strings/search.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_primordials_math = require('../primordials/math.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_math = require('../primordials/math.js');
 
 //#region src/strings/search.ts
 /**

package/dist/temporal/instant.js

@@ -2,8 +2,8 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
-const require_primordials_json = require('../primordials/json.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_json = require('../primordials/json.js');
 const require_primordials_globals = require('../primordials/globals.js');
 const require_temporal_slots = require('./slots.js');
 
@@ -72,7 +72,7 @@ function describe(value) {
 	if (typeof value === "bigint") return `${value}n`;
 	if (typeof value === "object") {
 		const ctor = value.constructor;
-		return ctor && ctor.name ? `<${ctor.name}>` : "<object>";
+		return ctor?.name ? `<${ctor.name}>` : "<object>";
 	}
 	return typeof value === "string" ? require_primordials_json.JSONStringify(value) : String(value);
 }

package/dist/themes/context.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Theme } from './types';
 import type { ThemeName } from './themes';
-import type * as AsyncHooks from 'node:async_hooks';
+import { getNodeAsyncHooks } from '../node/async-hooks';
 /**
  * Theme change event listener signature.
  */
@@ -16,11 +16,13 @@ export type ThemeChangeListener = (theme: Theme) => void;
  */
 export declare function emitThemeChange(theme: Theme): void;
 /**
- * Lazily load the async_hooks module to avoid Webpack errors.
+ * Lazily load the async_hooks module. Aliases the canonical `node/async-hooks`
+ * accessor (single owner of the bundler-safe require); kept as an export so
+ * this module's surface is unchanged.
  *
  * @private
  */
-export declare function getAsyncHooks(): typeof AsyncHooks;
+export declare const getAsyncHooks: typeof getNodeAsyncHooks;
 /**
  * Get the active theme from context.
  *

package/dist/themes/context.js

@@ -1,11 +1,11 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_node_async_hooks = require('../node/async-hooks.js');
 const require_primordials_map_set = require('../primordials/map-set.js');
 const require_themes_themes = require('./themes.js');
 
 //#region src/themes/context.ts
-let asyncHooks;
 /**
 * Emit theme change event to listeners.
 *
@@ -15,14 +15,13 @@ function emitThemeChange(theme) {
 	for (const listener of listeners) listener(theme);
 }
 /**
-* Lazily load the async_hooks module to avoid Webpack errors.
+* Lazily load the async_hooks module. Aliases the canonical `node/async-hooks`
+* accessor (single owner of the bundler-safe require); kept as an export so
+* this module's surface is unchanged.
 *
 * @private
 */
-function getAsyncHooks() {
-	if (asyncHooks === void 0) asyncHooks = /*@__PURE__*/ require("node:async_hooks");
-	return asyncHooks;
-}
+const getAsyncHooks = require_node_async_hooks.getNodeAsyncHooks;
 /**
 * AsyncLocalStorage for theme context isolation.
 */

package/dist/url/assert-safe.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file SSRF guard for operator- or issuer-supplied URLs — `assertSafeHttpUrl`
+ *   parses a raw URL, rejects non-HTTP(S) schemes, and refuses hosts that
+ *   resolve to loopback / private / link-local ranges (cloud metadata, redis,
+ *   internal services). A server that fetches a URL it did not author (an OAuth
+ *   issuer, an introspection endpoint advertised in its metadata, a webhook
+ *   target) runs the candidate through this before the request leaves the box.
+ */
+import type { AssertSafeHttpUrlOptions } from './types';
+/**
+ * Parse `rawUrl` and assert it is safe to fetch server-side, returning the
+ * parsed `URL`. Throws when the value does not parse, uses a scheme other than
+ * `http:` / `https:`, or resolves to a loopback / private / link-local host.
+ * Set `allowLocalhost` to permit `localhost` / `127.0.0.1` / `::1` for
+ * local-stack development. `label` names the subject in the thrown message.
+ *
+ * @example
+ *   ;```typescript
+ *   assertSafeHttpUrl('https://api.example.com', { label: 'OAuth issuer' })
+ *   // → URL { href: 'https://api.example.com/' }
+ *
+ *   assertSafeHttpUrl('http://169.254.169.254/latest/meta-data')
+ *   // → throws: resolves to a private/loopback host
+ *
+ *   assertSafeHttpUrl('ftp://example.com')
+ *   // → throws: must use http(s)
+ *   ```
+ */
+export declare function assertSafeHttpUrl(rawUrl: string, options?: AssertSafeHttpUrlOptions | undefined): URL;

package/dist/url/assert-safe.js

@@ -0,0 +1,54 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_url_predicates = require('./predicates.js');
+
+//#region src/url/assert-safe.ts
+/**
+* @file SSRF guard for operator- or issuer-supplied URLs — `assertSafeHttpUrl`
+*   parses a raw URL, rejects non-HTTP(S) schemes, and refuses hosts that
+*   resolve to loopback / private / link-local ranges (cloud metadata, redis,
+*   internal services). A server that fetches a URL it did not author (an OAuth
+*   issuer, an introspection endpoint advertised in its metadata, a webhook
+*   target) runs the candidate through this before the request leaves the box.
+*/
+const UrlCtor = URL;
+/**
+* Parse `rawUrl` and assert it is safe to fetch server-side, returning the
+* parsed `URL`. Throws when the value does not parse, uses a scheme other than
+* `http:` / `https:`, or resolves to a loopback / private / link-local host.
+* Set `allowLocalhost` to permit `localhost` / `127.0.0.1` / `::1` for
+* local-stack development. `label` names the subject in the thrown message.
+*
+* @example
+*   ;```typescript
+*   assertSafeHttpUrl('https://api.example.com', { label: 'OAuth issuer' })
+*   // → URL { href: 'https://api.example.com/' }
+*
+*   assertSafeHttpUrl('http://169.254.169.254/latest/meta-data')
+*   // → throws: resolves to a private/loopback host
+*
+*   assertSafeHttpUrl('ftp://example.com')
+*   // → throws: must use http(s)
+*   ```
+*/
+function assertSafeHttpUrl(rawUrl, options) {
+	const { allowLocalhost = false, label = "URL" } = {
+		__proto__: null,
+		...options
+	};
+	let url;
+	try {
+		url = new UrlCtor(rawUrl);
+	} catch {
+		throw new Error(`${label} is not a valid URL: ${rawUrl}. Provide an absolute http(s) URL.`);
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`${label} must use http(s): ${rawUrl}. Got scheme "${url.protocol}"; use http: or https:.`);
+	const { hostname } = url;
+	if (allowLocalhost && require_url_predicates.isLoopbackHost(hostname)) return url;
+	if (require_url_predicates.isPrivateHost(hostname)) throw new Error(`${label} resolves to a private/loopback host and is refused: ${rawUrl}. Point it at a public host.`);
+	return url;
+}
+
+//#endregion
+exports.assertSafeHttpUrl = assertSafeHttpUrl;

package/dist/url/predicates.d.ts

@@ -1,7 +1,37 @@
 /**
  * @file URL type-guard predicates — `isUrl` answers whether a value parses as a
- *   valid URL via `parseUrl`.
+ *   valid URL via `parseUrl`. `isLoopbackHost` / `isPrivateHost` classify a
+ *   hostname for SSRF guards: a server that fetches an operator- or
+ *   issuer-supplied URL uses these to refuse hosts that resolve to the local
+ *   machine or an internal network (cloud metadata, redis, link-local).
  */
+/**
+ * Check whether a hostname is a loopback address — `localhost`, `127.0.0.1`, or
+ * IPv6 `::1`. Compares case-insensitively; pass a bare hostname, not a URL.
+ *
+ * @example
+ *   ;```typescript
+ *   isLoopbackHost('localhost') // true
+ *   isLoopbackHost('127.0.0.1') // true
+ *   isLoopbackHost('example.com') // false
+ *   ```
+ */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Check whether a hostname resolves to a private / loopback / link-local
+ * address an SSRF probe would target (the local machine, RFC 1918 ranges, IPv6
+ * loopback / ULA / link-local). Loopback hosts count as private. Compares
+ * case-insensitively; pass a bare hostname, not a URL.
+ *
+ * @example
+ *   ;```typescript
+ *   isPrivateHost('127.0.0.1') // true
+ *   isPrivateHost('10.0.0.5') // true
+ *   isPrivateHost('169.254.169.254') // true
+ *   isPrivateHost('example.com') // false
+ *   ```
+ */
+export declare function isPrivateHost(hostname: string): boolean;
 /**
  * Check if a value is a valid URL.
  *

package/dist/url/predicates.js

@@ -1,13 +1,52 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_string = require('../primordials/string.js');
+const require_primordials_regexp = require('../primordials/regexp.js');
 const require_url_parse = require('./parse.js');
 
 //#region src/url/predicates.ts
 /**
 * @file URL type-guard predicates — `isUrl` answers whether a value parses as a
-*   valid URL via `parseUrl`.
+*   valid URL via `parseUrl`. `isLoopbackHost` / `isPrivateHost` classify a
+*   hostname for SSRF guards: a server that fetches an operator- or
+*   issuer-supplied URL uses these to refuse hosts that resolve to the local
+*   machine or an internal network (cloud metadata, redis, link-local).
 */
+const PRIVATE_HOST_REGEXP = /^(?:0\.0\.0\.0$|10\.|127\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|\[?::1\]?$|\[?fc00:|\[?fd|\[?fe80:)/u;
+/**
+* Check whether a hostname is a loopback address — `localhost`, `127.0.0.1`, or
+* IPv6 `::1`. Compares case-insensitively; pass a bare hostname, not a URL.
+*
+* @example
+*   ;```typescript
+*   isLoopbackHost('localhost') // true
+*   isLoopbackHost('127.0.0.1') // true
+*   isLoopbackHost('example.com') // false
+*   ```
+*/
+function isLoopbackHost(hostname) {
+	const host = require_primordials_string.StringPrototypeToLowerCase(hostname);
+	return host === "::1" || host === "127.0.0.1" || host === "localhost";
+}
+/**
+* Check whether a hostname resolves to a private / loopback / link-local
+* address an SSRF probe would target (the local machine, RFC 1918 ranges, IPv6
+* loopback / ULA / link-local). Loopback hosts count as private. Compares
+* case-insensitively; pass a bare hostname, not a URL.
+*
+* @example
+*   ;```typescript
+*   isPrivateHost('127.0.0.1') // true
+*   isPrivateHost('10.0.0.5') // true
+*   isPrivateHost('169.254.169.254') // true
+*   isPrivateHost('example.com') // false
+*   ```
+*/
+function isPrivateHost(hostname) {
+	const host = require_primordials_string.StringPrototypeToLowerCase(hostname);
+	return isLoopbackHost(host) || require_primordials_regexp.RegExpPrototypeTest(PRIVATE_HOST_REGEXP, host);
+}
 /**
 * Check if a value is a valid URL.
 *
@@ -23,4 +62,6 @@ function isUrl(value) {
 }
 
 //#endregion
+exports.isLoopbackHost = isLoopbackHost;
+exports.isPrivateHost = isPrivateHost;
 exports.isUrl = isUrl;

package/dist/url/types.d.ts

@@ -3,6 +3,10 @@
  *   `createRelativeUrl`, `urlSearchParamsAs*`, and `urlSearchParamsGet*`. Pure
  *   types, no runtime side effects.
  */
+export interface AssertSafeHttpUrlOptions {
+    label?: string | undefined;
+    allowLocalhost?: boolean | undefined;
+}
 export interface CreateRelativeUrlOptions {
     base?: string | undefined;
 }