@socketsecurity/lib 6.0.5 → 6.0.7

package/dist/env/node-version-managers.js

@@ -0,0 +1,90 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_env_rewire = require('./rewire.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/env/node-version-managers.ts
+/**
+* @file Detect which Node version manager is active on this machine and emit a
+*   targeted upgrade hint. Used when a tool needs Node ≥ X and wants to tell
+*   the user the exact command to run instead of a generic "install newer Node"
+*   line. Detection is best-effort:
+*
+*   1. **process.execPath** — the running Node binary's path is the most reliable
+*      signal. `~/.nvm/versions/node/...`, `~/.volta/tools/...`, `~/.fnm/...`,
+*      `~/.asdf/installs/nodejs/...`, `~/n/...` each have well-known directory
+*      shapes.
+*   2. **Environment variables** — `NVM_DIR`, `FNM_DIR`, `FNM_MULTISHELL_PATH`,
+*      `VOLTA_HOME`, `ASDF_DIR`, `N_PREFIX`. These are set by the shell
+*      integration each manager ships.
+*   3. **Corepack** — Node's bundled package-manager shim. Detected via
+*      `COREPACK_*` env vars or by the Node binary being under
+*      `corepack/shims/`. If none match, the manager is reported as `'system'`
+*      (Homebrew, apt, the .pkg installer, etc.) — for those, the upgrade hint
+*      is generic. This module does NOT shell out — every probe is in-process
+*      (env reads + path string inspection). That keeps it cheap to call and
+*      safe for the native-messaging host context, where stdout is reserved for
+*      the Chrome protocol.
+*/
+/**
+* Detect the Node version manager currently providing `process.execPath`.
+* Returns `'system'` when no manager is detected — the user is running a Node
+* installed by the OS package manager, the official .pkg/.msi installer, or a
+* manually placed binary.
+*
+* @example
+*   ;```typescript
+*   detectActiveNodeManager() // 'nvm' | 'fnm' | 'volta' | 'asdf' | 'n' | 'corepack' | 'system'
+*   ```
+*/
+function detectActiveNodeManager() {
+	const exec = node_process.default.execPath;
+	if (/[/\\]\.nvm[/\\]versions[/\\]node[/\\]/.test(exec)) return "nvm";
+	if (/[/\\]\.fnm[/\\]/.test(exec) || /[/\\]fnm_multishells[/\\]/.test(exec)) return "fnm";
+	if (/[/\\]\.volta[/\\]tools[/\\]/.test(exec)) return "volta";
+	if (/[/\\]\.asdf[/\\]installs[/\\]nodejs[/\\]/.test(exec)) return "asdf";
+	if (/[/\\]n[/\\]versions[/\\]node[/\\]/.test(exec)) return "n";
+	if (/[/\\]corepack[/\\]shims[/\\]/.test(exec)) return "corepack";
+	if (require_env_rewire.getEnvValue("NVM_DIR")) return "nvm";
+	if (require_env_rewire.getEnvValue("FNM_DIR") || require_env_rewire.getEnvValue("FNM_MULTISHELL_PATH")) return "fnm";
+	if (require_env_rewire.getEnvValue("VOLTA_HOME")) return "volta";
+	if (require_env_rewire.getEnvValue("ASDF_DIR")) return "asdf";
+	if (require_env_rewire.getEnvValue("N_PREFIX")) return "n";
+	if (require_env_rewire.getEnvValue("COREPACK_HOME")) return "corepack";
+	return "system";
+}
+/**
+* Produce the exact shell command a user should run to install + activate
+* `targetVersion` under the named manager. The command is single-line and
+* intended to be embedded in an error message verbatim.
+*
+* @example
+*   ;```typescript
+*   nodeManagerUpgradeHint('nvm', '22.6.0')
+*   // 'nvm install 22.6.0 && nvm use 22.6.0'
+*
+*   nodeManagerUpgradeHint('system', '22.6.0')
+*   // 'Install Node 22.6.0+ from https://nodejs.org/'
+*   ```
+*
+* @param manager - The detected Node version manager.
+* @param targetVersion - Semver-shaped version, e.g. `'22.6.0'` or `'22'`.
+*/
+function nodeManagerUpgradeHint(manager, targetVersion) {
+	switch (manager) {
+		case "asdf": return `asdf install nodejs ${targetVersion} && asdf global nodejs ${targetVersion}`;
+		case "corepack": return `Corepack manages package managers, not Node. Install Node ${targetVersion}+ via nvm/fnm/volta or from https://nodejs.org/`;
+		case "fnm": return `fnm install ${targetVersion} && fnm use ${targetVersion}`;
+		case "n": return `n ${targetVersion}`;
+		case "nvm": return `nvm install ${targetVersion} && nvm use ${targetVersion}`;
+		case "volta": return `volta install node@${targetVersion}`;
+		default: return `Install Node ${targetVersion}+ from https://nodejs.org/`;
+	}
+}
+
+//#endregion
+exports.detectActiveNodeManager = detectActiveNodeManager;
+exports.nodeManagerUpgradeHint = nodeManagerUpgradeHint;

package/dist/env/npm.js

@@ -22,7 +22,6 @@ const require_env_rewire = require('./rewire.js');
 *
 * @returns The configured NPM registry URL, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getNpmConfigRegistry() {
 	return require_env_rewire.getEnvValue("npm_config_registry");
 }
@@ -40,7 +39,6 @@ function getNpmConfigRegistry() {
 *
 * @returns The package manager user agent string, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getNpmConfigUserAgent() {
 	return require_env_rewire.getEnvValue("npm_config_user_agent");
 }
@@ -58,7 +56,6 @@ function getNpmConfigUserAgent() {
 *
 * @returns The current lifecycle event name, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getNpmLifecycleEvent() {
 	return require_env_rewire.getEnvValue("npm_lifecycle_event");
 }
@@ -75,7 +72,6 @@ function getNpmLifecycleEvent() {
 *
 * @returns The NPM registry URL override, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getNpmRegistry() {
 	return require_env_rewire.getEnvValue("NPM_REGISTRY");
 }
@@ -92,7 +88,6 @@ function getNpmRegistry() {
 *
 * @returns The NPM auth token, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getNpmToken() {
 	return require_env_rewire.getEnvValue("NPM_TOKEN");
 }

package/dist/env/number.js

@@ -31,7 +31,6 @@ const require_primordials_number = require('../primordials/number.js');
 *
 * @returns The parsed number, or the default value if parsing fails
 */
-/* @__NO_SIDE_EFFECTS__ */
 function envAsNumber(value, defaultValueOrOptions = 0) {
 	const { allowInfinity = false, defaultValue = 0, mode = "int" } = typeof defaultValueOrOptions === "number" ? { defaultValue: defaultValueOrOptions } : defaultValueOrOptions ?? {};
 	if (value === void 0 || value === null) return defaultValue;

package/dist/env/package-manager.js

@@ -37,11 +37,10 @@ node_process = require_runtime.__toESM(node_process);
 *
 * @returns The detected package manager or null if unable to determine
 */
-/* @__NO_SIDE_EFFECTS__ */
 function detectPackageManager() {
-	const userAgent = /* @__PURE__ */ getPackageManagerUserAgent();
+	const userAgent = getPackageManagerUserAgent();
 	if (userAgent) {
-		const match = userAgent.match(/^(npm|pnpm|yarn|bun)\//);
+		const match = userAgent.match(/^(bun|npm|pnpm|yarn)\//);
 		if (match) return match[1];
 	}
 	/* c8 ignore start - argv0-based PM fallback only fires when
@@ -67,9 +66,8 @@ function detectPackageManager() {
 *
 * @returns Object with name and version, or null if not available
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getPackageManagerInfo() {
-	const userAgent = /* @__PURE__ */ getPackageManagerUserAgent();
+	const userAgent = getPackageManagerUserAgent();
 	if (!userAgent) return;
 	const match = userAgent.match(/^([^/]+)\/([^\s]+)/);
 	if (match?.[1] && match[2]) return {
@@ -91,7 +89,6 @@ function getPackageManagerInfo() {
 *
 * @returns The user agent string or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getPackageManagerUserAgent() {
 	return require_env_rewire.getEnvValue("npm_config_user_agent");
 }

package/dist/env/path.js

@@ -22,7 +22,6 @@ const require_env_rewire = require('./rewire.js');
 *
 * @returns The system executable search paths, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getPath() {
 	return require_env_rewire.getEnvValue("PATH");
 }

package/dist/env/pre-commit.js

@@ -24,9 +24,8 @@ const require_env_rewire = require('./rewire.js');
 *
 * @returns `true` if running in a pre-commit hook, `false` otherwise
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getPreCommit() {
-	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("PRE_COMMIT"));
+	return require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("PRE_COMMIT"));
 }
 
 //#endregion

package/dist/env/rewire.d.ts

@@ -8,12 +8,7 @@
  *   - Compatible with vi.stubEnv() - reads from process.env as final fallback
  *   - Thread-safe for concurrent test execution
  */
-/**
- * Lazily load the async_hooks module to avoid Webpack errors.
- *
- * @private
- */
-export declare function getAsyncHooks(): typeof import('node:async_hooks');
+import type * as asyncHooksModule from 'node:async_hooks';
 /**
  * Clear a specific environment variable override.
  *
@@ -28,6 +23,12 @@ export declare function getAsyncHooks(): typeof import('node:async_hooks');
  * @param key - The environment variable name to clear.
  */
 export declare function clearEnv(key: string): void;
+/**
+ * Lazily load the async_hooks module to avoid Webpack errors.
+ *
+ * @private
+ */
+export declare function getAsyncHooks(): typeof asyncHooksModule;
 /**
  * Get an environment variable value, checking overrides first.
  *

package/dist/env/rewire.js

@@ -20,23 +20,13 @@ node_process = require_runtime.__toESM(node_process);
 *   - Compatible with vi.stubEnv() - reads from process.env as final fallback
 *   - Thread-safe for concurrent test execution
 */
-let _async_hooks;
-/**
-* Lazily load the async_hooks module to avoid Webpack errors.
-*
-* @private
-*/
-/* @__NO_SIDE_EFFECTS__ */
-function getAsyncHooks() {
-	if (_async_hooks === void 0) _async_hooks = /* @__PURE__ */ require("node:async_hooks");
-	return _async_hooks;
-}
-const { AsyncLocalStorage } = /* @__PURE__ */ getAsyncHooks();
+let asyncHooks;
+const { AsyncLocalStorage } = getAsyncHooks();
 const isolatedOverridesStorage = new AsyncLocalStorage();
 const sharedOverridesSymbol = Symbol.for("@socketsecurity/lib/env/rewire/test-overrides");
-const _globalThis = globalThis;
-if (/* @__PURE__ */ require_env_boolean.envAsBoolean(node_process.default.env["VITEST"]) && !_globalThis[sharedOverridesSymbol]) _globalThis[sharedOverridesSymbol] = new require_primordials_map_set.MapCtor();
-const sharedOverrides = _globalThis[sharedOverridesSymbol];
+const globalThisRef = globalThis;
+if (require_env_boolean.envAsBoolean(node_process.default.env["VITEST"]) && !globalThisRef[sharedOverridesSymbol]) globalThisRef[sharedOverridesSymbol] = new require_primordials_map_set.MapCtor();
+const sharedOverrides = globalThisRef[sharedOverridesSymbol];
 /**
 * Clear a specific environment variable override.
 *
@@ -54,6 +44,15 @@ function clearEnv(key) {
 	sharedOverrides?.delete(key);
 }
 /**
+* Lazily load the async_hooks module to avoid Webpack errors.
+*
+* @private
+*/
+function getAsyncHooks() {
+	if (asyncHooks === void 0) asyncHooks = /*@__PURE__*/ require("node:async_hooks");
+	return asyncHooks;
+}
+/**
 * Get an environment variable value, checking overrides first.
 *
 * Resolution order: 1. Isolated overrides (temporary - set via
@@ -116,7 +115,7 @@ function hasOverride(key) {
 function isInEnv(key) {
 	if (isolatedOverridesStorage.getStore()?.has(key)) return true;
 	if (sharedOverrides?.has(key)) return true;
-	return /* @__PURE__ */ require_objects_predicates.hasOwn(node_process.default.env, key);
+	return require_objects_predicates.hasOwn(node_process.default.env, key);
 }
 /**
 * Clear all environment variable overrides. Useful in afterEach hooks to ensure

package/dist/env/shell.js

@@ -22,7 +22,6 @@ const require_env_rewire = require('./rewire.js');
 *
 * @returns The user's default shell path, or `undefined` if not set
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getShell() {
 	return require_env_rewire.getEnvValue("SHELL");
 }

package/dist/env/socket-cli.js

@@ -24,9 +24,8 @@ const require_env_number = require('./number.js');
 *
 * @returns Whether to accept all risks
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliAcceptRisks() {
-	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_ACCEPT_RISKS"));
+	return require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_ACCEPT_RISKS"));
 }
 /**
 * Socket CLI API base URL (alternative name). Checks SOCKET_CLI_API_BASE_URL
@@ -42,7 +41,6 @@ function getSocketCliAcceptRisks() {
 *
 * @returns API base URL or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliApiBaseUrl() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_API_BASE_URL") || require_env_rewire.getEnvValue("SOCKET_SECURITY_API_BASE_URL");
 }
@@ -62,7 +60,6 @@ function getSocketCliApiBaseUrl() {
 *
 * @returns API proxy URL or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliApiProxy() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_API_PROXY") || require_env_rewire.getEnvValue("SOCKET_SECURITY_API_PROXY") || require_env_rewire.getEnvValue("HTTPS_PROXY") || require_env_rewire.getEnvValue("https_proxy") || require_env_rewire.getEnvValue("HTTP_PROXY") || require_env_rewire.getEnvValue("http_proxy");
 }
@@ -79,9 +76,8 @@ function getSocketCliApiProxy() {
 *
 * @returns API timeout in milliseconds
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliApiTimeout() {
-	return /* @__PURE__ */ require_env_number.envAsNumber(require_env_rewire.getEnvValue("SOCKET_CLI_API_TIMEOUT"));
+	return require_env_number.envAsNumber(require_env_rewire.getEnvValue("SOCKET_CLI_API_TIMEOUT"));
 }
 /**
 * Bootstrap cache directory path. Set by bootstrap wrappers to pass dlx cache
@@ -97,7 +93,6 @@ function getSocketCliApiTimeout() {
 *
 * @returns Bootstrap cache directory or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliBootstrapCacheDir() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_BOOTSTRAP_CACHE_DIR");
 }
@@ -115,7 +110,6 @@ function getSocketCliBootstrapCacheDir() {
 *
 * @returns Bootstrap package spec or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliBootstrapSpec() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_BOOTSTRAP_SPEC");
 }
@@ -132,7 +126,6 @@ function getSocketCliBootstrapSpec() {
 *
 * @returns Config file path or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliConfig() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_CONFIG");
 }
@@ -149,7 +142,6 @@ function getSocketCliConfig() {
 *
 * @returns Fix mode value or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliFix() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_FIX");
 }
@@ -167,7 +159,6 @@ function getSocketCliFix() {
 *
 * @returns GitHub token or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliGithubToken() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_GITHUB_TOKEN") || require_env_rewire.getEnvValue("SOCKET_SECURITY_GITHUB_PAT") || require_env_rewire.getEnvValue("GITHUB_TOKEN");
 }
@@ -185,9 +176,8 @@ function getSocketCliGithubToken() {
 *
 * @returns Whether to skip API token requirement
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliNoApiToken() {
-	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_NO_API_TOKEN"));
+	return require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_NO_API_TOKEN"));
 }
 /**
 * Controls Socket CLI optimization mode.
@@ -203,9 +193,8 @@ function getSocketCliNoApiToken() {
 *
 * @returns Whether optimization mode is enabled
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliOptimize() {
-	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_OPTIMIZE"));
+	return require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_OPTIMIZE"));
 }
 /**
 * Socket CLI organization slug identifier (alternative name). Checks
@@ -221,7 +210,6 @@ function getSocketCliOptimize() {
 *
 * @returns Organization slug or undefined
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliOrgSlug() {
 	return require_env_rewire.getEnvValue("SOCKET_CLI_ORG_SLUG") || require_env_rewire.getEnvValue("SOCKET_ORG_SLUG");
 }
@@ -239,9 +227,8 @@ function getSocketCliOrgSlug() {
 *
 * @returns Whether to view all risks
 */
-/* @__NO_SIDE_EFFECTS__ */
 function getSocketCliViewAllRisks() {
-	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_VIEW_ALL_RISKS"));
+	return require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("SOCKET_CLI_VIEW_ALL_RISKS"));
 }
 
 //#endregion

package/dist/env/socket-mcp.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @file Socket MCP HTTP server environment variable getters. Covers the MCP
+ *   transport (HTTP mode, port) and the OAuth credentials / proxy-trust
+ *   settings the MCP HTTP server reads at startup.
+ */
+/**
+ * Whether the MCP server should run in HTTP mode. MCP_HTTP_MODE — when set to
+ * the literal string `'true'`, the MCP server serves over HTTP instead of
+ * stdio. Returns `false` for any other value (including unset).
+ *
+ * @example
+ *   ;```typescript
+ *   import { getMcpHttpMode } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   if (getMcpHttpMode()) {
+ *     startHttpServer()
+ *   }
+ *   ```
+ *
+ * @returns `true` if HTTP mode is enabled, `false` otherwise
+ */
+export declare function getMcpHttpMode(): boolean;
+/**
+ * MCP HTTP server listen port. MCP_PORT — port the MCP HTTP server binds to.
+ * Defaults to `3000` (matches socket-mcp's documented default). Invalid /
+ * non-numeric values also fall back to `3000`.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getMcpPort } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   const port = getMcpPort()
+ *   ```
+ *
+ * @returns The MCP server port (default `3000`)
+ */
+export declare function getMcpPort(): number;
+/**
+ * OAuth introspection client ID for the MCP HTTP server.
+ * SOCKET_OAUTH_INTROSPECTION_CLIENT_ID — client credential used to call the
+ * issuer's introspection endpoint. Empty string when unset.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketOauthIntrospectionClientId } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   const clientId = getSocketOauthIntrospectionClientId()
+ *   ```
+ *
+ * @returns The OAuth client ID, or `''` if not set
+ */
+export declare function getSocketOauthIntrospectionClientId(): string;
+/**
+ * OAuth introspection client secret for the MCP HTTP server.
+ * SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET — paired with the client ID for
+ * authenticated introspection requests. Empty string when unset.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketOauthIntrospectionClientSecret } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   const clientSecret = getSocketOauthIntrospectionClientSecret()
+ *   ```
+ *
+ * @returns The OAuth client secret, or `''` if not set
+ */
+export declare function getSocketOauthIntrospectionClientSecret(): string;
+/**
+ * OAuth issuer URL for the MCP HTTP server. SOCKET_OAUTH_ISSUER — issuer to
+ * validate inbound OAuth tokens against. Returns the empty string when unset;
+ * callers treat empty as "no issuer configured".
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketOauthIssuer } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   const issuer = getSocketOauthIssuer()
+ *   if (issuer) { ... }
+ *   ```
+ *
+ * @returns The OAuth issuer URL, or `''` if not set
+ */
+export declare function getSocketOauthIssuer(): string;
+/**
+ * Required OAuth scopes for the MCP HTTP server. SOCKET_OAUTH_REQUIRED_SCOPES —
+ * whitespace-separated list of scopes inbound tokens must carry. Defaults to
+ * `'packages:list'` (the minimum scope socket-mcp's depscore tool needs).
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketOauthRequiredScopes } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   const scopes = getSocketOauthRequiredScopes().split(/\s+/u)
+ *   ```
+ *
+ * @returns The required-scopes string, defaulting to `'packages:list'`
+ */
+export declare function getSocketOauthRequiredScopes(): string;
+/**
+ * Whether the MCP HTTP server should trust upstream proxy headers. TRUST_PROXY
+ * — when set to the literal string `'true'`, the server honors
+ * `X-Forwarded-Host` / `X-Forwarded-Proto` when composing OAuth metadata URLs.
+ * Off by default to prevent header spoofing when no upstream proxy is present.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getTrustProxy } from '@socketsecurity/lib/env/socket-mcp'
+ *
+ *   if (getTrustProxy()) { ... }
+ *   ```
+ *
+ * @returns `true` if proxy headers are trusted, `false` otherwise
+ */
+export declare function getTrustProxy(): boolean;

package/dist/env/socket-mcp.js

@@ -0,0 +1,146 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_number = require('../primordials/number.js');
+const require_env_rewire = require('./rewire.js');
+const require_env_number = require('./number.js');
+
+//#region src/env/socket-mcp.ts
+/**
+* @file Socket MCP HTTP server environment variable getters. Covers the MCP
+*   transport (HTTP mode, port) and the OAuth credentials / proxy-trust
+*   settings the MCP HTTP server reads at startup.
+*/
+/**
+* Whether the MCP server should run in HTTP mode. MCP_HTTP_MODE — when set to
+* the literal string `'true'`, the MCP server serves over HTTP instead of
+* stdio. Returns `false` for any other value (including unset).
+*
+* @example
+*   ;```typescript
+*   import { getMcpHttpMode } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   if (getMcpHttpMode()) {
+*     startHttpServer()
+*   }
+*   ```
+*
+* @returns `true` if HTTP mode is enabled, `false` otherwise
+*/
+function getMcpHttpMode() {
+	return require_env_rewire.getEnvValue("MCP_HTTP_MODE") === "true";
+}
+/**
+* MCP HTTP server listen port. MCP_PORT — port the MCP HTTP server binds to.
+* Defaults to `3000` (matches socket-mcp's documented default). Invalid /
+* non-numeric values also fall back to `3000`.
+*
+* @example
+*   ;```typescript
+*   import { getMcpPort } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   const port = getMcpPort()
+*   ```
+*
+* @returns The MCP server port (default `3000`)
+*/
+function getMcpPort() {
+	const parsed = require_env_number.envAsNumber(require_env_rewire.getEnvValue("MCP_PORT"));
+	return require_primordials_number.NumberIsFinite(parsed) && parsed > 0 ? parsed : 3e3;
+}
+/**
+* OAuth introspection client ID for the MCP HTTP server.
+* SOCKET_OAUTH_INTROSPECTION_CLIENT_ID — client credential used to call the
+* issuer's introspection endpoint. Empty string when unset.
+*
+* @example
+*   ;```typescript
+*   import { getSocketOauthIntrospectionClientId } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   const clientId = getSocketOauthIntrospectionClientId()
+*   ```
+*
+* @returns The OAuth client ID, or `''` if not set
+*/
+function getSocketOauthIntrospectionClientId() {
+	return require_env_rewire.getEnvValue("SOCKET_OAUTH_INTROSPECTION_CLIENT_ID") ?? "";
+}
+/**
+* OAuth introspection client secret for the MCP HTTP server.
+* SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET — paired with the client ID for
+* authenticated introspection requests. Empty string when unset.
+*
+* @example
+*   ;```typescript
+*   import { getSocketOauthIntrospectionClientSecret } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   const clientSecret = getSocketOauthIntrospectionClientSecret()
+*   ```
+*
+* @returns The OAuth client secret, or `''` if not set
+*/
+function getSocketOauthIntrospectionClientSecret() {
+	return require_env_rewire.getEnvValue("SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET") ?? "";
+}
+/**
+* OAuth issuer URL for the MCP HTTP server. SOCKET_OAUTH_ISSUER — issuer to
+* validate inbound OAuth tokens against. Returns the empty string when unset;
+* callers treat empty as "no issuer configured".
+*
+* @example
+*   ;```typescript
+*   import { getSocketOauthIssuer } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   const issuer = getSocketOauthIssuer()
+*   if (issuer) { ... }
+*   ```
+*
+* @returns The OAuth issuer URL, or `''` if not set
+*/
+function getSocketOauthIssuer() {
+	return require_env_rewire.getEnvValue("SOCKET_OAUTH_ISSUER") ?? "";
+}
+/**
+* Required OAuth scopes for the MCP HTTP server. SOCKET_OAUTH_REQUIRED_SCOPES —
+* whitespace-separated list of scopes inbound tokens must carry. Defaults to
+* `'packages:list'` (the minimum scope socket-mcp's depscore tool needs).
+*
+* @example
+*   ;```typescript
+*   import { getSocketOauthRequiredScopes } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   const scopes = getSocketOauthRequiredScopes().split(/\s+/u)
+*   ```
+*
+* @returns The required-scopes string, defaulting to `'packages:list'`
+*/
+function getSocketOauthRequiredScopes() {
+	return require_env_rewire.getEnvValue("SOCKET_OAUTH_REQUIRED_SCOPES") ?? "packages:list";
+}
+/**
+* Whether the MCP HTTP server should trust upstream proxy headers. TRUST_PROXY
+* — when set to the literal string `'true'`, the server honors
+* `X-Forwarded-Host` / `X-Forwarded-Proto` when composing OAuth metadata URLs.
+* Off by default to prevent header spoofing when no upstream proxy is present.
+*
+* @example
+*   ;```typescript
+*   import { getTrustProxy } from '@socketsecurity/lib/env/socket-mcp'
+*
+*   if (getTrustProxy()) { ... }
+*   ```
+*
+* @returns `true` if proxy headers are trusted, `false` otherwise
+*/
+function getTrustProxy() {
+	return require_env_rewire.getEnvValue("TRUST_PROXY") === "true";
+}
+
+//#endregion
+exports.getMcpHttpMode = getMcpHttpMode;
+exports.getMcpPort = getMcpPort;
+exports.getSocketOauthIntrospectionClientId = getSocketOauthIntrospectionClientId;
+exports.getSocketOauthIntrospectionClientSecret = getSocketOauthIntrospectionClientSecret;
+exports.getSocketOauthIssuer = getSocketOauthIssuer;
+exports.getSocketOauthRequiredScopes = getSocketOauthRequiredScopes;
+exports.getTrustProxy = getTrustProxy;