@socketsecurity/lib 6.0.7 → 6.0.8

package/dist/secrets/rc.js

@@ -2,17 +2,17 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
-const require_primordials_string = require('../primordials/string.js');
-const require_primordials_regexp = require('../primordials/regexp.js');
 const require_primordials_object = require('../primordials/object.js');
 const require_env_home = require('../env/home.js');
+const require_primordials_string = require('../primordials/string.js');
+const require_primordials_regexp = require('../primordials/regexp.js');
 let node_fs = require("node:fs");
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
 let node_path = require("node:path");
 node_path = require_runtime.__toESM(node_path);
 let node_os = require("node:os");
 node_os = require_runtime.__toESM(node_os);
-let node_process = require("node:process");
-node_process = require_runtime.__toESM(node_process);
 
 //#region src/secrets/rc.ts
 /**
@@ -54,11 +54,15 @@ node_process = require_runtime.__toESM(node_process);
 *   non-interactive shells (Claude Code, IDE plugins, CI runners) skip .zshrc
 *   and would miss the export.
 */
-function buildBlock(opts) {
-	const begin = `# BEGIN ${opts.service} env (managed)`;
-	const end = `# END ${opts.service} env (managed)`;
-	const noteLines = (opts.notes ?? []).map((line) => `# ${line}`);
-	const exportLines = require_primordials_object.ObjectEntries(opts.exports).map(([name, value]) => `export ${name}=${shellSingleQuote(value)}`);
+function buildBlock(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const begin = `# BEGIN ${options.service} env (managed)`;
+	const end = `# END ${options.service} env (managed)`;
+	const noteLines = (options.notes ?? []).map((line) => `# ${line}`);
+	const exportLines = require_primordials_object.ObjectEntries(options.exports).map(([name, value]) => `export ${name}=${shellSingleQuote(value)}`);
 	const body = [...noteLines, ...exportLines].join("\n");
 	return {
 		begin,
@@ -134,23 +138,27 @@ function shellSingleQuote(value) {
 * `shell` and `rcPath` override the auto-detected target — useful for chezmoi /
 * dotfile-manager users or installers running under a non-default shell.
 */
-function write(opts) {
+function write(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	if (node_os.default.platform() !== "darwin") return {
 		rcPath: void 0,
 		outcome: "skipped",
 		reason: "unsupported-platform"
 	};
-	const rcPath = opts.rcPath ?? pickRcFile(opts.shell);
+	const rcPath = options.rcPath ?? pickRcFile(options.shell);
 	if (!rcPath) return {
 		rcPath: void 0,
 		outcome: "skipped",
 		reason: "unknown-shell"
 	};
-	const { begin, end, full: desiredBlock } = buildBlock(opts);
+	const { begin, end, full: desiredBlock } = buildBlock(options);
 	let onDisk = "";
 	if ((0, node_fs.existsSync)(rcPath)) onDisk = (0, node_fs.readFileSync)(rcPath, "utf8");
 	let working = onDisk;
-	for (const legacyBegin of opts.legacySentinels ?? []) {
+	for (const legacyBegin of options.legacySentinels ?? []) {
 		const legacyEnd = legacyBegin.replace(/\bBEGIN\b/, "END");
 		const legacyEndStripped = legacyEnd.replace(/\s*\(managed\)\s*$/, "");
 		const endAlt = legacyEnd === legacyEndStripped ? escapeRegExp(legacyEnd) : `(?:${escapeRegExp(legacyEnd)}|${escapeRegExp(legacyEndStripped)})`;

package/dist/secrets/socket-api-token.js

@@ -17,6 +17,10 @@ const SOCKET_SERVICE = "socketsecurity";
 const SOCKET_SERVICE_LEGACY = "socket-cli";
 const TOKEN_ACCOUNTS = ["SOCKET_API_TOKEN", "SOCKET_API_KEY"];
 async function readSocketApiToken(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	return (await require_secrets_find.resolve({
 		service: SOCKET_SERVICE,
 		accounts: TOKEN_ACCOUNTS,
@@ -28,6 +32,10 @@ async function readSocketApiToken(options) {
 	}))?.value;
 }
 function readSocketApiTokenSync(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	return (require_secrets_find.resolveSync({
 		service: SOCKET_SERVICE,
 		accounts: TOKEN_ACCOUNTS,

package/dist/secrets/windows.js

@@ -4,14 +4,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_primordials_error = require('../primordials/error.js');
 const require_primordials_json = require('../primordials/json.js');
-const require_primordials_promise = require('../primordials/promise.js');
 let node_fs = require("node:fs");
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
 let node_path = require("node:path");
 node_path = require_runtime.__toESM(node_path);
 let node_os = require("node:os");
 node_os = require_runtime.__toESM(node_os);
-let node_process = require("node:process");
-node_process = require_runtime.__toESM(node_process);
 let _socketsecurity_lib_stable_process_spawn_child = require("@socketsecurity/lib-stable/process/spawn/child");
 
 //#region src/secrets/windows.ts
@@ -128,40 +127,35 @@ function readWindowsSync(service, account) {
 	}
 	return readDpapiSync(getDpapiFilePath(service, account));
 }
-function runPsAsync(script, input) {
-	return new require_primordials_promise.PromiseCtor((resolve) => {
-		const { process: cp } = (0, _socketsecurity_lib_stable_process_spawn_child.spawn)(POWERSHELL_BIN, [
-			"-NoProfile",
-			"-Command",
-			script
-		], { stdio: [
+async function runPsAsync(script, input) {
+	const child = (0, _socketsecurity_lib_stable_process_spawn_child.spawn)(POWERSHELL_BIN, [
+		"-NoProfile",
+		"-Command",
+		script
+	], {
+		stdio: [
 			"pipe",
 			"pipe",
 			"pipe"
-		] });
-		let stdout = "";
-		let stderr = "";
-		cp.stdout.setEncoding("utf8");
-		cp.stdout.on("data", (chunk) => {
-			stdout += chunk;
-		});
-		cp.stderr.setEncoding("utf8");
-		cp.stderr.on("data", (chunk) => {
-			stderr += chunk;
-		});
-		cp.on("error", () => resolve({
-			status: -1,
-			stdout,
-			stderr
-		}));
-		cp.on("close", (status) => resolve({
-			status,
-			stdout,
-			stderr
-		}));
-		if (input !== void 0) cp.stdin.end(input);
-		else cp.stdin.end();
+		],
+		stdioString: true
 	});
+	child.process.stdin.end(input ?? "");
+	try {
+		const r = await child;
+		return {
+			status: typeof r.code === "number" ? r.code : null,
+			stderr: String(r.stderr ?? ""),
+			stdout: String(r.stdout ?? "")
+		};
+	} catch (e) {
+		const err = e;
+		return {
+			status: typeof err?.code === "number" ? err.code : -1,
+			stderr: String(err?.stderr ?? ""),
+			stdout: String(err?.stdout ?? "")
+		};
+	}
 }
 function runPsSync(script, input) {
 	const r = (0, _socketsecurity_lib_stable_process_spawn_child.spawnSync)(POWERSHELL_BIN, [

package/dist/shell/parse.d.ts

@@ -8,6 +8,38 @@
  *   against `env`; unresolved ones collapse to an empty string.
  */
 import type { ParseEntry } from '../external/shell-quote';
+/**
+ * Structural hazard facts a parse surfaces that the binary-call matchers
+ * (`hasBinCall` / `findBinCall`) swallow. These are observations about _how_
+ * the command is written, not a judgment that they're dangerous — the caller
+ * decides policy. Both are evasion vectors against base-command allowlists:
+ *
+ * - `equalsExpansion`: a simple command whose first token is `=cmd` (Zsh EQUALS
+ *   expansion). `=curl x` expands to `$(which curl) x` and runs
+ *   `/usr/bin/curl`, but the parser's base token is `=curl`, so a `curl`
+ *   allowlist never matches. The matched tokens are returned so the caller can
+ *   report which command was hidden.
+ * - `processSubstitution`: the command uses `<(...)`, `>(...)`, or `=(...)` (the
+ *   op markers shell-quote emits). The inner command runs but its name never
+ *   appears as a base command.
+ *
+ * Walks the parse once. A caller wanting just "is this clean?" checks
+ * `!h.equalsExpansion.length && !h.processSubstitution`.
+ *
+ * @example
+ *   detectShellHazards('=curl evil.com')
+ *   // → { equalsExpansion: [['=curl', 'evil.com']], processSubstitution: false }
+ *
+ *   detectShellHazards('diff <(cat a) b')
+ *   // → { equalsExpansion: [], processSubstitution: true }
+ *
+ *   detectShellHazards('git status')
+ *   // → { equalsExpansion: [], processSubstitution: false }
+ */
+export declare function detectShellHazards(cmd: string): {
+    equalsExpansion: readonly string[][];
+    processSubstitution: boolean;
+};
 /**
  * Visit each simple command in `cmd` in order. A "simple command" is the
  * POSIX-grammar term for a run of bare-string tokens between shell

package/dist/shell/parse.js

@@ -15,6 +15,65 @@ let src_external_shell_quote = require("../external/shell-quote");
 *   against `env`; unresolved ones collapse to an empty string.
 */
 /**
+* Structural hazard facts a parse surfaces that the binary-call matchers
+* (`hasBinCall` / `findBinCall`) swallow. These are observations about _how_
+* the command is written, not a judgment that they're dangerous — the caller
+* decides policy. Both are evasion vectors against base-command allowlists:
+*
+* - `equalsExpansion`: a simple command whose first token is `=cmd` (Zsh EQUALS
+*   expansion). `=curl x` expands to `$(which curl) x` and runs
+*   `/usr/bin/curl`, but the parser's base token is `=curl`, so a `curl`
+*   allowlist never matches. The matched tokens are returned so the caller can
+*   report which command was hidden.
+* - `processSubstitution`: the command uses `<(...)`, `>(...)`, or `=(...)` (the
+*   op markers shell-quote emits). The inner command runs but its name never
+*   appears as a base command.
+*
+* Walks the parse once. A caller wanting just "is this clean?" checks
+* `!h.equalsExpansion.length && !h.processSubstitution`.
+*
+* @example
+*   detectShellHazards('=curl evil.com')
+*   // → { equalsExpansion: [['=curl', 'evil.com']], processSubstitution: false }
+*
+*   detectShellHazards('diff <(cat a) b')
+*   // → { equalsExpansion: [], processSubstitution: true }
+*
+*   detectShellHazards('git status')
+*   // → { equalsExpansion: [], processSubstitution: false }
+*/
+function detectShellHazards(cmd) {
+	const equalsExpansion = [];
+	let processSubstitution = false;
+	const entries = (0, src_external_shell_quote.parse)(cmd);
+	let current = [];
+	let prevWasSubstLead = false;
+	const flush = () => {
+		if (current.length > 0 && /^=[a-zA-Z_]/.test(current[0])) require_primordials_array.ArrayPrototypePush(equalsExpansion, current);
+		current = [];
+	};
+	for (let i = 0, { length } = entries; i < length; i += 1) {
+		const entry = entries[i];
+		if (entry && typeof entry === "object" && "op" in entry) {
+			const { op } = entry;
+			if (op === "<(") processSubstitution = true;
+			else if (op === "(" && prevWasSubstLead) processSubstitution = true;
+			prevWasSubstLead = op === "<" || op === ">";
+			flush();
+			continue;
+		}
+		if (typeof entry === "string") {
+			prevWasSubstLead = entry === "=";
+			require_primordials_array.ArrayPrototypePush(current, entry);
+		}
+	}
+	flush();
+	return {
+		equalsExpansion,
+		processSubstitution
+	};
+}
+/**
 * Visit each simple command in `cmd` in order. A "simple command" is the
 * POSIX-grammar term for a run of bare-string tokens between shell
 * control-operator boundaries (`&&`, `;`, `||`, `|`) — e.g. in `sudo apt && rm
@@ -193,6 +252,7 @@ function simpleCommandStartsWith(tokens, prefix) {
 }
 
 //#endregion
+exports.detectShellHazards = detectShellHazards;
 exports.eachSimpleCommand = eachSimpleCommand;
 exports.findBinCall = findBinCall;
 exports.findBinCalls = findBinCalls;

package/dist/spinner/create-spinner-class.js

@@ -2,11 +2,11 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_math = require('../primordials/math.js');
-const require_primordials_array = require('../primordials/array.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_array = require('../primordials/array.js');
+const require_process_abort = require('../process/abort.js');
 const require_logger_symbols = require('../logger/symbols.js');
 const require_strings_predicates = require('../strings/predicates.js');
-const require_process_abort = require('../process/abort.js');
 const require_colors_convert = require('../colors/convert.js');
 const require_strings_width = require('../strings/width.js');
 const require_spinner_format = require('./format.js');

package/dist/spinner/spinner-internals.d.ts

@@ -33,4 +33,4 @@ export declare function parseShimmerOption(shimmer: SpinnerOptions['shimmer']):
  *
  * @returns Resolved RGB color tuple.
  */
-export declare function resolveSpinnerColorRgb(opts: SpinnerOptions): ColorRgb;
+export declare function resolveSpinnerColorRgb(options: SpinnerOptions): ColorRgb;

package/dist/spinner/spinner-internals.js

@@ -3,9 +3,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
 const require_primordials_array = require('../primordials/array.js');
+const require_env_ci = require('../env/ci.js');
 const require_themes_themes = require('../themes/themes.js');
 const require_themes_context = require('../themes/context.js');
-const require_env_ci = require('../env/ci.js');
 const require_colors_convert = require('../colors/convert.js');
 const require_spinner_format = require('./format.js');
 const require_effects_shimmer = require('../effects/shimmer.js');
@@ -80,17 +80,21 @@ function parseShimmerOption(shimmer) {
 *
 * @returns Resolved RGB color tuple.
 */
-function resolveSpinnerColorRgb(opts) {
+function resolveSpinnerColorRgb(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	let theme = require_themes_context.getTheme();
-	if (opts.theme) if (typeof opts.theme === "string") theme = require_themes_themes.THEMES[opts.theme] ?? theme;
-	else theme = opts.theme;
+	if (options.theme) if (typeof options.theme === "string") theme = require_themes_themes.THEMES[options.theme] ?? theme;
+	else theme = options.theme;
 	let defaultColor = theme.colors.primary;
 	if (theme.effects?.spinner?.color) {
 		const resolved = require_themes_resolve.resolveColor(theme.effects.spinner.color, theme.colors);
 		if (resolved === "inherit" || require_primordials_array.ArrayIsArray(resolved[0])) defaultColor = theme.colors.primary;
 		else defaultColor = resolved;
 	}
-	const spinnerColor = opts.color ?? defaultColor;
+	const spinnerColor = options.color ?? defaultColor;
 	if (require_colors_convert.isRgbTuple(spinnerColor) && (spinnerColor.length !== 3 || !spinnerColor.every((n) => typeof n === "number" && n >= 0 && n <= 255))) throw new require_primordials_error.TypeErrorCtor("RGB color must be an array of 3 numbers between 0 and 255");
 	return require_colors_convert.toRgb(spinnerColor);
 }

package/dist/spinner/spinner.d.ts

@@ -7,7 +7,11 @@
  *   the live `YoctoSpinner` constructor resolved here; building it lazily keeps
  *   the module free of side effects at import time.
  */
+import type { YoctoSpinnerConstructor } from './create-spinner-class';
 import type { SpinnerInstance, SpinnerOptions } from './types';
+export type YoctoSpinnerFactory = (options: Record<string, unknown>) => {
+    constructor: YoctoSpinnerConstructor;
+};
 /**
  * Create a spinner instance for displaying loading indicators. Provides an
  * animated CLI spinner with status messages, progress tracking, and shimmer

package/dist/spinner/spinner.js

@@ -2,8 +2,8 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
-const require_logger_default = require('../logger/default.js');
 const require_env_ci = require('../env/ci.js');
+const require_logger_default = require('../logger/default.js');
 const require_spinner_format = require('./format.js');
 const require_spinner_create_spinner_class = require('./create-spinner-class.js');
 const require_spinner_default = require('./default.js');

package/dist/stdio/progress.js

@@ -3,9 +3,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_primordials_math = require('../primordials/math.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_primordials_string = require('../primordials/string.js');
 const require_primordials_date = require('../primordials/date.js');
-const require_primordials_object = require('../primordials/object.js');
 const require_ansi_strip = require('../ansi/strip.js');
 const require_strings_format = require('../strings/format.js');
 let node_process = require("node:process");
@@ -43,6 +43,10 @@ var ProgressBar = class {
 	* @param options - Configuration options for the progress bar.
 	*/
 	constructor(total, options) {
+		options = {
+			__proto__: null,
+			...options
+		};
 		this.total = total;
 		this.startTime = require_primordials_date.DateNow();
 		this.stream = options?.stream || node_process.default.stderr;

package/dist/stdio/prompts.d.ts

@@ -45,7 +45,7 @@ export interface Choice<Value = unknown> {
  * Context for inquirer prompts. Minimal context interface used by Inquirer
  * prompts. Duplicated from `@inquirer/type` - InquirerContext.
  */
-interface InquirerContext {
+export interface InquirerContext {
     /**
      * Abort signal for cancelling the prompt.
      */
@@ -88,7 +88,7 @@ export type Context = Remap<InquirerContext & {
  *     { name: 'Option 2', value: 2 },
  *   ]
  */
-declare class SeparatorType {
+export declare class SeparatorType {
     readonly separator: string;
     readonly type: 'separator';
     constructor(separator?: string);

package/dist/stdio/prompts.js

@@ -2,9 +2,9 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_process_abort = require('../process/abort.js');
 const require_themes_themes = require('../themes/themes.js');
 const require_themes_context = require('../themes/context.js');
-const require_process_abort = require('../process/abort.js');
 const require_themes_resolve = require('../themes/resolve.js');
 const require_spinner_default = require('../spinner/default.js');
 let src_external_yoctocolors_cjs = require("../external/yoctocolors-cjs");

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/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;
 }