@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/env/socket.d.ts

@@ -1,231 +1,448 @@
 /**
- * @fileoverview Socket Security environment variable getters.
+ * @file Socket Security environment variable getters.
  */
 /**
- * SOCKET_ACCEPT_RISKS environment variable getter.
- * Whether to accept all Socket Security risks.
+ * 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).
  *
- * @returns `true` if risks are accepted, `false` otherwise
+ * @example
+ *   ;```typescript
+ *   import { getMcpHttpMode } from '@socketsecurity/lib/env/socket'
+ *
+ *   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 { getSocketAcceptRisks } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getMcpPort } from '@socketsecurity/lib/env/socket'
  *
- * if (getSocketAcceptRisks()) {
- *   console.log('All risks accepted')
- * }
- * ```
+ *   const port = getMcpPort()
+ *   ```
+ *
+ * @returns The MCP server port (default `3000`)
  */
-export declare function getSocketAcceptRisks(): boolean;
+export declare function getMcpPort(): number;
 /**
- * SOCKET_API_BASE_URL environment variable getter.
- * Socket Security API base URL.
+ * SOCKET_ACCEPT_RISKS environment variable getter. Whether to accept all Socket
+ * Security risks.
  *
- * @returns The API base URL, or `undefined` if not set
+ * @example
+ *   ;```typescript
+ *   import { getSocketAcceptRisks } from '@socketsecurity/lib/env/socket'
+ *
+ *   if (getSocketAcceptRisks()) {
+ *     console.log('All risks accepted')
+ *   }
+ *   ```
+ *
+ * @returns `true` if risks are accepted, `false` otherwise
+ */
+export declare function getSocketAcceptRisks(): boolean;
+/**
+ * SOCKET_API_BASE_URL environment variable getter. Socket Security API base
+ * URL.
  *
  * @example
- * ```typescript
- * import { getSocketApiBaseUrl } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketApiBaseUrl } from '@socketsecurity/lib/env/socket'
  *
- * const baseUrl = getSocketApiBaseUrl()
- * // e.g. 'https://api.socket.dev' or undefined
- * ```
+ *   const baseUrl = getSocketApiBaseUrl()
+ *   // e.g. 'https://api.socket.dev' or undefined
+ *   ```
+ *
+ * @returns The API base URL, or `undefined` if not set
  */
 export declare function getSocketApiBaseUrl(): string | undefined;
 /**
- * SOCKET_API_PROXY environment variable getter.
- * Proxy URL for Socket Security API requests.
- *
- * @returns The API proxy URL, or `undefined` if not set
+ * SOCKET_API_PROXY environment variable getter. Proxy URL for Socket Security
+ * API requests.
  *
  * @example
- * ```typescript
- * import { getSocketApiProxy } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketApiProxy } from '@socketsecurity/lib/env/socket'
  *
- * const proxy = getSocketApiProxy()
- * // e.g. 'http://proxy.example.com:8080' or undefined
- * ```
+ *   const proxy = getSocketApiProxy()
+ *   // e.g. 'http://proxy.example.com:8080' or undefined
+ *   ```
+ *
+ * @returns The API proxy URL, or `undefined` if not set
  */
 export declare function getSocketApiProxy(): string | undefined;
 /**
- * SOCKET_API_TIMEOUT environment variable getter.
- * Timeout in milliseconds for Socket Security API requests.
- *
- * @returns The timeout in milliseconds, or `0` if not set
+ * SOCKET_API_TIMEOUT environment variable getter. Timeout in milliseconds for
+ * Socket Security API requests.
  *
  * @example
- * ```typescript
- * import { getSocketApiTimeout } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketApiTimeout } from '@socketsecurity/lib/env/socket'
  *
- * const timeout = getSocketApiTimeout()
- * // e.g. 30000 or 0 if not set
- * ```
+ *   const timeout = getSocketApiTimeout()
+ *   // e.g. 30000 or 0 if not set
+ *   ```
+ *
+ * @returns The timeout in milliseconds, or `0` if not set
  */
 export declare function getSocketApiTimeout(): number;
 /**
- * SOCKET_API_TOKEN environment variable getter.
  * Socket Security API authentication token.
  *
- * @returns The API token, or `undefined` if not set
+ * Checks the canonical SOCKET_API_TOKEN first, then a chain of legacy aliases
+ * for full v1.x backward compatibility plus the bare SOCKET_API_KEY form used
+ * by older MCP-server installs:
+ *
+ * SOCKET_API_TOKEN → SOCKET_API_KEY → SOCKET_CLI_API_TOKEN → SOCKET_CLI_API_KEY
+ * → SOCKET_SECURITY_API_TOKEN → SOCKET_SECURITY_API_KEY.
  *
  * @example
- * ```typescript
- * import { getSocketApiToken } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketApiToken } from '@socketsecurity/lib/env/socket'
+ *
+ *   const token = getSocketApiToken()
+ *   // e.g. a Socket API token string or undefined
+ *   ```
  *
- * const token = getSocketApiToken()
- * // e.g. a Socket API token string or undefined
- * ```
+ * @returns The API token, or `undefined` if no name in the chain is set
  */
 export declare function getSocketApiToken(): string | undefined;
 /**
- * SOCKET_CACACHE_DIR environment variable getter.
- * Overrides the default Socket cacache directory location.
+ * Socket API endpoint URL override. SOCKET_API_URL — when set, replaces the
+ * app's default Socket API base. Each consumer composes its own default (e.g.
+ * socket-mcp's depscore endpoint vs. socket-cli's scan endpoints), so this
+ * helper returns the raw override and lets the caller fall back.
  *
- * @returns The cacache directory path, or `undefined` if not set
+ * @example
+ *   ;```typescript
+ *   import { getSocketApiUrl } from '@socketsecurity/lib/env/socket'
+ *
+ *   const apiUrl = getSocketApiUrl() ?? 'https://api.socket.dev/v0/...'
+ *   ```
+ *
+ * @returns The API URL override, or `undefined` if not set
+ */
+export declare function getSocketApiUrl(): string | undefined;
+/**
+ * Git branch name for the current Socket scan. SOCKET_BRANCH_NAME — set by CI /
+ * GHA to label the scan with the source branch. Used by basics and coana.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketBranchName } from '@socketsecurity/lib/env/socket'
+ *
+ *   const branch = getSocketBranchName()
+ *   ```
+ *
+ * @returns The branch name, or `undefined` if not set
+ */
+export declare function getSocketBranchName(): string | undefined;
+/**
+ * SOCKET_CACACHE_DIR environment variable getter. Overrides the default Socket
+ * cacache directory location.
  *
  * @example
- * ```typescript
- * import { getSocketCacacheDirEnv } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketCacacheDirEnv } from '@socketsecurity/lib/env/socket'
  *
- * const dir = getSocketCacacheDirEnv()
- * // e.g. '/tmp/.socket-cache' or undefined
- * ```
+ *   const dir = getSocketCacacheDirEnv()
+ *   // e.g. '/tmp/.socket-cache' or undefined
+ *   ```
+ *
+ * @returns The cacache directory path, or `undefined` if not set
  */
 export declare function getSocketCacacheDirEnv(): string | undefined;
 /**
- * SOCKET_CONFIG environment variable getter.
- * Socket Security configuration file path.
+ * SOCKET_CLOUD_AUTH_URL environment variable getter. SocketCloud OAuth
+ * authorization URL. depot's better-auth provider config reads this to override
+ * the default authorize endpoint when pointing at a staging or self-hosted
+ * SocketCloud server.
  *
- * @returns The config file path, or `undefined` if not set
+ * @example
+ *   ;```typescript
+ *   import { getSocketCloudAuthUrl } from '@socketsecurity/lib/env/socket'
+ *
+ *   const url =
+ *     getSocketCloudAuthUrl() ?? 'https://api.socket.dev/v1/oauth2/authorize'
+ *   ```
+ *
+ * @returns The override URL, or `undefined` when default applies
+ */
+export declare function getSocketCloudAuthUrl(): string | undefined;
+/**
+ * SOCKET_CLOUD_CLIENT_ID environment variable getter. OAuth client ID for
+ * SocketCloud. Required (alongside SOCKET_CLOUD_CLIENT_SECRET) to enable the
+ * SocketCloud auth provider. Returns `undefined` when not configured — callers
+ * should treat that as "SocketCloud auth disabled".
+ *
+ * @returns The client ID, or `undefined` if not set
+ */
+export declare function getSocketCloudClientId(): string | undefined;
+/**
+ * SOCKET_CLOUD_CLIENT_SECRET environment variable getter. OAuth client secret
+ * for SocketCloud. Required (alongside SOCKET_CLOUD_CLIENT_ID) to enable the
+ * SocketCloud auth provider. Returns `undefined` when not configured.
+ *
+ * @returns The client secret, or `undefined` if not set
+ */
+export declare function getSocketCloudClientSecret(): string | undefined;
+/**
+ * SOCKET_CLOUD_INTROSPECT_URL environment variable getter. SocketCloud OAuth
+ * token-introspection URL. depot uses this to verify access tokens against the
+ * SocketCloud authorization server. Defaults handled at the call site.
+ *
+ * @returns The override URL, or `undefined` when default applies
+ */
+export declare function getSocketCloudIntrospectUrl(): string | undefined;
+/**
+ * SOCKET_CLOUD_TOKEN_URL environment variable getter. SocketCloud OAuth
+ * token-exchange URL. depot's better-auth provider config reads this to
+ * override the default token endpoint.
+ *
+ * @returns The override URL, or `undefined` when default applies
+ */
+export declare function getSocketCloudTokenUrl(): string | undefined;
+/**
+ * SOCKET_CLOUD_USERINFO_URL environment variable getter. SocketCloud OAuth
+ * userinfo endpoint. depot uses this to fetch the authenticated principal's
+ * profile after an OAuth code exchange.
+ *
+ * @returns The override URL, or `undefined` when default applies
+ */
+export declare function getSocketCloudUserinfoUrl(): string | undefined;
+/**
+ * SOCKET_CONFIG environment variable getter. Socket Security configuration file
+ * path.
  *
  * @example
- * ```typescript
- * import { getSocketConfig } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketConfig } from '@socketsecurity/lib/env/socket'
  *
- * const config = getSocketConfig()
- * // e.g. '/tmp/project/socket.yml' or undefined
- * ```
+ *   const config = getSocketConfig()
+ *   // e.g. '/tmp/project/socket.yml' or undefined
+ *   ```
+ *
+ * @returns The config file path, or `undefined` if not set
  */
 export declare function getSocketConfig(): string | undefined;
 /**
- * SOCKET_DEBUG environment variable getter.
- * Controls Socket-specific debug output.
- *
- * @returns The Socket debug filter, or `undefined` if not set
+ * SOCKET_DEBUG environment variable getter. Controls Socket-specific debug
+ * output.
  *
  * @example
- * ```typescript
- * import { getSocketDebug } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketDebug } from '@socketsecurity/lib/env/socket'
  *
- * const debug = getSocketDebug()
- * // e.g. '*' or 'api' or undefined
- * ```
+ *   const debug = getSocketDebug()
+ *   // e.g. '*' or 'api' or undefined
+ *   ```
+ *
+ * @returns The Socket debug filter, or `undefined` if not set
  */
 export declare function getSocketDebug(): string | undefined;
 /**
- * SOCKET_DLX_DIR environment variable getter.
- * Overrides the default Socket DLX directory location.
- *
- * @returns The DLX directory path, or `undefined` if not set
+ * SOCKET_DLX_DIR environment variable getter. Overrides the default Socket DLX
+ * directory location.
  *
  * @example
- * ```typescript
- * import { getSocketDlxDirEnv } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketDlxDirEnv } from '@socketsecurity/lib/env/socket'
  *
- * const dlxDir = getSocketDlxDirEnv()
- * // e.g. '/tmp/.socket-dlx' or undefined
- * ```
+ *   const dlxDir = getSocketDlxDirEnv()
+ *   // e.g. '/tmp/.socket-dlx' or undefined
+ *   ```
+ *
+ * @returns The DLX directory path, or `undefined` if not set
  */
 export declare function getSocketDlxDirEnv(): string | undefined;
 /**
- * SOCKET_HOME environment variable getter.
- * Socket Security home directory path.
- *
- * @returns The Socket home directory, or `undefined` if not set
+ * SOCKET_HOME environment variable getter. Socket Security home directory path.
  *
  * @example
- * ```typescript
- * import { getSocketHome } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketHome } from '@socketsecurity/lib/env/socket'
  *
- * const home = getSocketHome()
- * // e.g. '/tmp/.socket' or undefined
- * ```
+ *   const home = getSocketHome()
+ *   // e.g. '/tmp/.socket' or undefined
+ *   ```
+ *
+ * @returns The Socket home directory, or `undefined` if not set
  */
 export declare function getSocketHome(): string | undefined;
 /**
- * SOCKET_NO_API_TOKEN environment variable getter.
- * Whether to skip Socket Security API token requirement.
- *
- * @returns `true` if the API token requirement is skipped, `false` otherwise
+ * SOCKET_NO_API_TOKEN environment variable getter. Whether to skip Socket
+ * Security API token requirement.
  *
  * @example
- * ```typescript
- * import { getSocketNoApiToken } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketNoApiToken } from '@socketsecurity/lib/env/socket'
  *
- * if (getSocketNoApiToken()) {
- *   console.log('API token requirement skipped')
- * }
- * ```
+ *   if (getSocketNoApiToken()) {
+ *     console.log('API token requirement skipped')
+ *   }
+ *   ```
+ *
+ * @returns `true` if the API token requirement is skipped, `false` otherwise
  */
 export declare function getSocketNoApiToken(): boolean;
 /**
- * SOCKET_NPM_REGISTRY environment variable getter.
- * Socket NPM registry URL (alternative name).
+ * SOCKET_NPM_REGISTRY environment variable getter. Socket NPM registry URL
+ * (alternative name).
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketNpmRegistry } from '@socketsecurity/lib/env/socket'
+ *
+ *   const registry = getSocketNpmRegistry()
+ *   // e.g. 'https://npm.socket.dev/' or undefined
+ *   ```
  *
  * @returns The Socket NPM registry URL, or `undefined` if not set
+ */
+export declare function getSocketNpmRegistry(): string | undefined;
+/**
+ * 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 { getSocketNpmRegistry } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketOauthIntrospectionClientId } from '@socketsecurity/lib/env/socket'
  *
- * const registry = getSocketNpmRegistry()
- * // e.g. 'https://npm.socket.dev/' or undefined
- * ```
+ *   const clientId = getSocketOauthIntrospectionClientId()
+ *   ```
+ *
+ * @returns The OAuth client ID, or `''` if not set
  */
-export declare function getSocketNpmRegistry(): string | undefined;
+export declare function getSocketOauthIntrospectionClientId(): string;
 /**
- * SOCKET_ORG_SLUG environment variable getter.
- * Socket Security organization slug identifier.
+ * 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.
  *
- * @returns The organization slug, or `undefined` if not set
+ * @example
+ *   ;```typescript
+ *   import { getSocketOauthIntrospectionClientSecret } from '@socketsecurity/lib/env/socket'
+ *
+ *   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'
+ *
+ *   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'
+ *
+ *   const scopes = getSocketOauthRequiredScopes().split(/\s+/u)
+ *   ```
+ *
+ * @returns The required-scopes string, defaulting to `'packages:list'`
+ */
+export declare function getSocketOauthRequiredScopes(): string;
+/**
+ * SOCKET_ORG_SLUG environment variable getter. Socket Security organization
+ * slug identifier.
  *
  * @example
- * ```typescript
- * import { getSocketOrgSlug } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketOrgSlug } from '@socketsecurity/lib/env/socket'
+ *
+ *   const slug = getSocketOrgSlug()
+ *   // e.g. 'my-org' or undefined
+ *   ```
  *
- * const slug = getSocketOrgSlug()
- * // e.g. 'my-org' or undefined
- * ```
+ * @returns The organization slug, or `undefined` if not set
  */
 export declare function getSocketOrgSlug(): string | undefined;
 /**
- * SOCKET_REGISTRY_URL environment variable getter.
- * Socket Registry URL for package installation.
+ * SOCKET_REGISTRY_URL environment variable getter. Socket Registry URL for
+ * package installation.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketRegistryUrl } from '@socketsecurity/lib/env/socket'
+ *
+ *   const registryUrl = getSocketRegistryUrl()
+ *   // e.g. 'https://registry.socket.dev/' or undefined
+ *   ```
  *
  * @returns The Socket registry URL, or `undefined` if not set
+ */
+export declare function getSocketRegistryUrl(): string | undefined;
+/**
+ * Repository name for the current Socket scan. SOCKET_REPOSITORY_NAME
+ * (canonical) — set by CI / GHA to label the scan with the source repository.
+ * Also accepts `SOCKET_REPO_NAME` as an alias. Used by basics and coana.
  *
  * @example
- * ```typescript
- * import { getSocketRegistryUrl } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getSocketRepositoryName } from '@socketsecurity/lib/env/socket'
+ *
+ *   const repo = getSocketRepositoryName()
+ *   ```
  *
- * const registryUrl = getSocketRegistryUrl()
- * // e.g. 'https://registry.socket.dev/' or undefined
- * ```
+ * @returns The repository name, or `undefined` if neither is set
  */
-export declare function getSocketRegistryUrl(): string | undefined;
+export declare function getSocketRepositoryName(): string | undefined;
 /**
- * SOCKET_VIEW_ALL_RISKS environment variable getter.
- * Whether to view all Socket Security risks.
+ * SOCKET_VIEW_ALL_RISKS environment variable getter. Whether to view all Socket
+ * Security risks.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getSocketViewAllRisks } from '@socketsecurity/lib/env/socket'
+ *
+ *   if (getSocketViewAllRisks()) {
+ *     console.log('Viewing all risks')
+ *   }
+ *   ```
  *
  * @returns `true` if viewing all risks, `false` otherwise
+ */
+export declare function getSocketViewAllRisks(): boolean;
+/**
+ * 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 { getSocketViewAllRisks } from '@socketsecurity/lib/env/socket'
+ *   ;```typescript
+ *   import { getTrustProxy } from '@socketsecurity/lib/env/socket'
+ *
+ *   if (getTrustProxy()) { ... }
+ *   ```
  *
- * if (getSocketViewAllRisks()) {
- *   console.log('Viewing all risks')
- * }
- * ```
+ * @returns `true` if proxy headers are trusted, `false` otherwise
  */
-export declare function getSocketViewAllRisks(): boolean;
+export declare function getTrustProxy(): boolean;