@socketsecurity/lib 5.18.1 → 5.19.0

package/dist/github.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -49,6 +50,42 @@ var import_spawn = require("./spawn");
 const GITHUB_API_BASE_URL = "https://api.github.com";
 const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
 let _githubCache;
+async function fetchRefSha(owner, repo, ref, options) {
+  const fetchOptions = {
+    token: options.token
+  };
+  try {
+    const tagUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`;
+    const tagData = await fetchGitHub(tagUrl, fetchOptions);
+    if (tagData.object.type === "tag") {
+      const tagObject = await fetchGitHub(
+        tagData.object.url,
+        fetchOptions
+      );
+      return tagObject.object.sha;
+    }
+    return tagData.object.sha;
+  } catch {
+    try {
+      const branchUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`;
+      const branchData = await fetchGitHub(branchUrl, fetchOptions);
+      return branchData.object.sha;
+    } catch {
+      try {
+        const commitUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`;
+        const commitData = await fetchGitHub(
+          commitUrl,
+          fetchOptions
+        );
+        return commitData.sha;
+      } catch (e) {
+        throw new Error(
+          `failed to resolve ref "${ref}" for ${owner}/${repo}: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+    }
+  }
+}
 function getGithubCache() {
   if (_githubCache === void 0) {
     _githubCache = (0, import_cache_with_ttl.createTtlCache)({
@@ -59,8 +96,38 @@ function getGithubCache() {
   }
   return _githubCache;
 }
-function getGitHubToken() {
-  return (0, import_github.getGithubToken)() || (0, import_github.getGhToken)() || (0, import_socket_cli.getSocketCliGithubToken)() || void 0;
+async function cacheFetchGhsa(ghsaId, options) {
+  const cache = getGithubCache();
+  const key = `ghsa:${ghsaId}`;
+  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
+    return await fetchGhsaDetails(ghsaId, options);
+  }
+  return await cache.getOrFetch(key, async () => {
+    return await fetchGhsaDetails(ghsaId, options);
+  });
+}
+async function clearRefCache() {
+  if (_githubCache) {
+    await _githubCache.clear({ memoOnly: true });
+  }
+}
+async function fetchGhsaDetails(ghsaId, options) {
+  const url = `https://api.github.com/advisories/${ghsaId}`;
+  const data = await fetchGitHub(url, options);
+  return {
+    ghsaId: data.ghsa_id,
+    summary: data.summary,
+    details: data.details,
+    severity: data.severity,
+    aliases: data.aliases || [],
+    publishedAt: data.published_at,
+    updatedAt: data.updated_at,
+    withdrawnAt: data.withdrawn_at,
+    references: data.references || [],
+    vulnerabilities: data.vulnerabilities || [],
+    cvss: data.cvss,
+    cwes: data.cwes || []
+  };
 }
 async function fetchGitHub(url, options) {
   const opts = { __proto__: null, ...options };
@@ -105,60 +172,11 @@ Response may be malformed or incomplete.`,
     );
   }
 }
-async function resolveRefToSha(owner, repo, ref, options) {
-  const opts = {
-    __proto__: null,
-    ...options
-  };
-  const cacheKey = `${owner}/${repo}@${ref}`;
-  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
-    return await fetchRefSha(owner, repo, ref, opts);
-  }
-  const cache = getGithubCache();
-  return await cache.getOrFetch(cacheKey, async () => {
-    return await fetchRefSha(owner, repo, ref, opts);
-  });
-}
-async function fetchRefSha(owner, repo, ref, options) {
-  const fetchOptions = {
-    token: options.token
-  };
-  try {
-    const tagUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`;
-    const tagData = await fetchGitHub(tagUrl, fetchOptions);
-    if (tagData.object.type === "tag") {
-      const tagObject = await fetchGitHub(
-        tagData.object.url,
-        fetchOptions
-      );
-      return tagObject.object.sha;
-    }
-    return tagData.object.sha;
-  } catch {
-    try {
-      const branchUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`;
-      const branchData = await fetchGitHub(branchUrl, fetchOptions);
-      return branchData.object.sha;
-    } catch {
-      try {
-        const commitUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`;
-        const commitData = await fetchGitHub(
-          commitUrl,
-          fetchOptions
-        );
-        return commitData.sha;
-      } catch (e) {
-        throw new Error(
-          `failed to resolve ref "${ref}" for ${owner}/${repo}: ${e instanceof Error ? e.message : String(e)}`
-        );
-      }
-    }
-  }
+function getGhsaUrl(ghsaId) {
+  return `https://github.com/advisories/${ghsaId}`;
 }
-async function clearRefCache() {
-  if (_githubCache) {
-    await _githubCache.clear({ memoOnly: true });
-  }
+function getGitHubToken() {
+  return (0, import_github.getGithubToken)() || (0, import_github.getGhToken)() || (0, import_socket_cli.getSocketCliGithubToken)() || void 0;
 }
 async function getGitHubTokenFromGitConfig(options) {
   try {
@@ -176,35 +194,18 @@ async function getGitHubTokenFromGitConfig(options) {
 async function getGitHubTokenWithFallback() {
   return getGitHubToken() || await getGitHubTokenFromGitConfig();
 }
-function getGhsaUrl(ghsaId) {
-  return `https://github.com/advisories/${ghsaId}`;
-}
-async function fetchGhsaDetails(ghsaId, options) {
-  const url = `https://api.github.com/advisories/${ghsaId}`;
-  const data = await fetchGitHub(url, options);
-  return {
-    ghsaId: data.ghsa_id,
-    summary: data.summary,
-    details: data.details,
-    severity: data.severity,
-    aliases: data.aliases || [],
-    publishedAt: data.published_at,
-    updatedAt: data.updated_at,
-    withdrawnAt: data.withdrawn_at,
-    references: data.references || [],
-    vulnerabilities: data.vulnerabilities || [],
-    cvss: data.cvss,
-    cwes: data.cwes || []
+async function resolveRefToSha(owner, repo, ref, options) {
+  const opts = {
+    __proto__: null,
+    ...options
   };
-}
-async function cacheFetchGhsa(ghsaId, options) {
-  const cache = getGithubCache();
-  const key = `ghsa:${ghsaId}`;
+  const cacheKey = `${owner}/${repo}@${ref}`;
   if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
-    return await fetchGhsaDetails(ghsaId, options);
+    return await fetchRefSha(owner, repo, ref, opts);
   }
-  return await cache.getOrFetch(key, async () => {
-    return await fetchGhsaDetails(ghsaId, options);
+  const cache = getGithubCache();
+  return await cache.getOrFetch(cacheKey, async () => {
+    return await fetchRefSha(owner, repo, ref, opts);
   });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/globs.d.ts

@@ -1,4 +1,7 @@
-// Type definitions
+/**
+ * @fileoverview Glob pattern matching utilities with default ignore patterns.
+ * Provides file filtering and glob matcher functions for npm-like behavior.
+ */
 type Pattern = string;
 interface FastGlobOptions {
     absolute?: boolean;
@@ -31,29 +34,30 @@ export interface GlobOptions extends FastGlobOptions {
 export type { Pattern, FastGlobOptions };
 export declare const defaultIgnore: readonly string[];
 /**
- * Create a stream of license file paths matching glob patterns.
+ * Return a glob-matcher function, memoized by pattern + options.
  *
- * @example
- * ```typescript
- * const stream = globStreamLicenses('/tmp/my-package')
- * for await (const licensePath of stream) {
- *   console.log(licensePath)
- * }
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function globStreamLicenses(dirname: string, options?: GlobOptions): NodeJS.ReadableStream;
-/**
- * Get a cached glob matcher function.
+ * The returned function is a fast synchronous predicate built on picomatch.
+ * Results are memoized — calling `getGlobMatcher(['*.ts'])` a thousand times
+ * in a loop returns the same compiled matcher each time, so callers do not
+ * need to hoist it themselves.
+ *
+ * The cache is LRU with a cap of 100 entries. Cache keys fold together the
+ * (sorted) pattern list and (sorted) option set, so arguments that differ
+ * only in ordering share a matcher.
+ *
+ * Default options: `dot: true`, `nocase: true`. Patterns starting with `!`
+ * become ignore patterns.
  *
  * @example
  * ```typescript
  * const isMatch = getGlobMatcher('*.ts')
  * isMatch('index.ts')  // true
  * isMatch('index.js')  // false
+ *
+ * // With negation
+ * const isSource = getGlobMatcher(['src/**', '!**\/*.test.ts'])
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
     dot?: boolean;
     nocase?: boolean;
@@ -69,8 +73,19 @@ export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
  * console.log(files) // ['src/index.ts', 'src/utils.ts']
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function glob(patterns: Pattern | Pattern[], options?: FastGlobOptions): Promise<string[]>;
+/**
+ * Create a stream of license file paths matching glob patterns.
+ *
+ * @example
+ * ```typescript
+ * const stream = globStreamLicenses('/tmp/my-package')
+ * for await (const licensePath of stream) {
+ *   console.log(licensePath)
+ * }
+ * ```
+ */
+export declare function globStreamLicenses(dirname: string, options?: GlobOptions): NodeJS.ReadableStream;
 /**
  * Synchronously find files matching glob patterns.
  * Wrapper around fast-glob.sync.
@@ -81,5 +96,4 @@ export declare function glob(patterns: Pattern | Pattern[], options?: FastGlobOp
  * console.log(files) // ['package.json', 'tsconfig.json']
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function globSync(patterns: Pattern | Pattern[], options?: FastGlobOptions): string[];

package/dist/globs.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -29,21 +30,9 @@ module.exports = __toCommonJS(globs_exports);
 var import_objects = require("./objects");
 var import_globs = require("./paths/globs");
 let _fastGlob;
-// @__NO_SIDE_EFFECTS__
-function getFastGlob() {
-  if (_fastGlob === void 0) {
-    _fastGlob = require("./external/fast-glob.js");
-  }
-  return _fastGlob;
-}
 let _picomatch;
-// @__NO_SIDE_EFFECTS__
-function getPicomatch() {
-  if (_picomatch === void 0) {
-    _picomatch = require("./external/picomatch.js");
-  }
-  return _picomatch;
-}
+const MATCHER_CACHE_MAX_SIZE = 100;
+const matcherCache = /* @__PURE__ */ new Map();
 const defaultIgnore = (0, import_objects.objectFreeze)([
   // Most of these ignored files can be included specifically if included in the
   // files globs. Exceptions to this are:
@@ -85,43 +74,18 @@ const defaultIgnore = (0, import_objects.objectFreeze)([
   "**/bower_components"
 ]);
 // @__NO_SIDE_EFFECTS__
-function globStreamLicenses(dirname, options) {
-  const {
-    ignore: ignoreOpt,
-    ignoreOriginals,
-    recursive,
-    ...globOptions
-  } = { __proto__: null, ...options };
-  const ignore = [
-    ...Array.isArray(ignoreOpt) ? ignoreOpt : defaultIgnore,
-    "**/*.{cjs,cts,js,json,mjs,mts,ts}"
-  ];
-  if (ignoreOriginals) {
-    ignore.push(import_globs.LICENSE_ORIGINAL_GLOB_RECURSIVE);
+function getFastGlob() {
+  if (_fastGlob === void 0) {
+    _fastGlob = require("./external/fast-glob.js");
   }
-  const fastGlob = /* @__PURE__ */ getFastGlob();
-  return fastGlob.globStream(
-    [recursive ? import_globs.LICENSE_GLOB_RECURSIVE : import_globs.LICENSE_GLOB],
-    {
-      __proto__: null,
-      absolute: true,
-      caseSensitiveMatch: false,
-      cwd: dirname,
-      ...globOptions,
-      ...ignore ? { ignore } : {}
-    }
-  );
+  return _fastGlob;
 }
-const MATCHER_CACHE_MAX_SIZE = 100;
-const matcherCache = /* @__PURE__ */ new Map();
-const matcherAccessOrder = [];
-function evictLRUMatcher() {
-  if (matcherCache.size >= MATCHER_CACHE_MAX_SIZE && matcherAccessOrder.length > 0) {
-    const oldest = matcherAccessOrder.shift();
-    if (oldest) {
-      matcherCache.delete(oldest);
-    }
+// @__NO_SIDE_EFFECTS__
+function getPicomatch() {
+  if (_picomatch === void 0) {
+    _picomatch = require("./external/picomatch.js");
   }
+  return _picomatch;
 }
 // @__NO_SIDE_EFFECTS__
 function getGlobMatcher(glob2, options) {
@@ -129,16 +93,18 @@ function getGlobMatcher(glob2, options) {
   const sortedPatterns = [...patterns].sort();
   const sortedOptions = options ? Object.keys(options).sort().map((k) => `${k}:${JSON.stringify(options[k])}`).join(",") : "";
   const key = `${sortedPatterns.join("|")}:${sortedOptions}`;
-  let matcher = matcherCache.get(key);
-  if (matcher) {
-    const index = matcherAccessOrder.indexOf(key);
-    if (index !== -1) {
-      matcherAccessOrder.splice(index, 1);
-      matcherAccessOrder.push(key);
+  const existing = matcherCache.get(key);
+  if (existing) {
+    matcherCache.delete(key);
+    matcherCache.set(key, existing);
+    return existing;
+  }
+  if (matcherCache.size >= MATCHER_CACHE_MAX_SIZE) {
+    const oldest = matcherCache.keys().next().value;
+    if (oldest !== void 0) {
+      matcherCache.delete(oldest);
     }
-    return matcher;
   }
-  evictLRUMatcher();
   const positivePatterns = patterns.filter((p) => !p.startsWith("!"));
   const negativePatterns = patterns.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
   const matchOptions = {
@@ -148,12 +114,11 @@ function getGlobMatcher(glob2, options) {
     ...negativePatterns.length > 0 ? { ignore: negativePatterns } : {}
   };
   const picomatch = /* @__PURE__ */ getPicomatch();
-  matcher = picomatch(
+  const matcher = picomatch(
     positivePatterns.length > 0 ? positivePatterns : patterns,
     matchOptions
   );
   matcherCache.set(key, matcher);
-  matcherAccessOrder.push(key);
   return matcher;
 }
 // @__NO_SIDE_EFFECTS__
@@ -162,6 +127,34 @@ function glob(patterns, options) {
   return fastGlob.glob(patterns, options);
 }
 // @__NO_SIDE_EFFECTS__
+function globStreamLicenses(dirname, options) {
+  const {
+    ignore: ignoreOpt,
+    ignoreOriginals,
+    recursive,
+    ...globOptions
+  } = { __proto__: null, ...options };
+  const ignore = [
+    ...Array.isArray(ignoreOpt) ? ignoreOpt : defaultIgnore,
+    "**/*.{cjs,cts,js,json,mjs,mts,ts}"
+  ];
+  if (ignoreOriginals) {
+    ignore.push(import_globs.LICENSE_ORIGINAL_GLOB_RECURSIVE);
+  }
+  const fastGlob = /* @__PURE__ */ getFastGlob();
+  return fastGlob.globStream(
+    [recursive ? import_globs.LICENSE_GLOB_RECURSIVE : import_globs.LICENSE_GLOB],
+    {
+      __proto__: null,
+      absolute: true,
+      caseSensitiveMatch: false,
+      cwd: dirname,
+      ...globOptions,
+      ...ignore ? { ignore } : {}
+    }
+  );
+}
+// @__NO_SIDE_EFFECTS__
 function globSync(patterns, options) {
   const fastGlob = /* @__PURE__ */ getFastGlob();
   return fastGlob.globSync(patterns, options);

package/dist/http-request.d.ts

@@ -13,13 +13,13 @@
  * - Timeout support for all operations.
  * - Zero dependencies on external HTTP libraries.
  */
+import type { IncomingHttpHeaders, IncomingMessage } from 'node:http';
 import type { Readable } from 'node:stream';
-import type { IncomingHttpHeaders, IncomingMessage } from 'http';
+import type { Logger } from './logger';
 /** IncomingMessage received as a response to a client request (http.request callback). */
 export type IncomingResponse = IncomingMessage;
 /** IncomingMessage received as a request in a server handler (http.createServer callback). */
 export type IncomingRequest = IncomingMessage;
-import type { Logger } from './logger.js';
 /**
  * Information passed to the onRequest hook before each request attempt.
  */
@@ -422,22 +422,6 @@ export interface HttpResponse {
      */
     rawResponse?: IncomingResponse | undefined;
 }
-/**
- * Read and buffer a client-side IncomingResponse into an HttpResponse.
- *
- * Useful when you have a raw response from code that bypasses
- * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
- * or responses from third-party HTTP libraries) and need to convert it
- * into the standard HttpResponse interface.
- *
- * @example
- * ```typescript
- * const raw = await makeRawRequest('https://example.com/api')
- * const response = await readIncomingResponse(raw)
- * console.log(response.status, response.body.toString('utf8'))
- * ```
- */
-export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
 /**
  * Error thrown when an HTTP response has a non-2xx status code
  * and `throwOnError` is enabled. Carries the full `HttpResponse`
@@ -447,47 +431,6 @@ export declare class HttpResponseError extends Error {
     response: HttpResponse;
     constructor(response: HttpResponse, message?: string | undefined);
 }
-/**
- * Parse a `Retry-After` HTTP header value into milliseconds.
- *
- * Supports both formats defined in RFC 7231 §7.1.3:
- * - **delay-seconds**: integer number of seconds (e.g., `"120"`)
- * - **HTTP-date**: an absolute date/time (e.g., `"Fri, 31 Dec 2027 23:59:59 GMT"`)
- *
- * When the header is an array (multiple values), the first element is used.
- *
- * @param value - The raw Retry-After header value(s)
- * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
- *
- * @example
- * ```ts
- * const delay = parseRetryAfterHeader(response.headers['retry-after'])
- * if (delay !== undefined) {
- *   await new Promise(resolve => setTimeout(resolve, delay))
- * }
- * ```
- */
-export declare function parseRetryAfterHeader(value: string | string[] | undefined): number | undefined;
-/**
- * Redact sensitive HTTP headers for safe logging and telemetry.
- *
- * Replaces values of sensitive headers (Authorization, Cookie, etc.)
- * with `[REDACTED]`. Non-sensitive headers are passed through unchanged.
- * Array values are joined with `', '`.
- *
- * @param headers - HTTP headers to sanitize
- * @returns A new object with sensitive values redacted
- *
- * @example
- * ```ts
- * const safe = sanitizeHeaders({
- *   'authorization': 'Bearer secret',
- *   'content-type': 'application/json'
- * })
- * // { authorization: '[REDACTED]', 'content-type': 'application/json' }
- * ```
- */
-export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;
 /**
  * Configuration options for file downloads.
  */
@@ -704,32 +647,6 @@ export interface HttpDownloadResult {
  * ```
  */
 export type Checksums = Record<string, string>;
-/**
- * Parse a checksums file text into a filename-to-hash map.
- *
- * Supports standard checksums file formats:
- * - BSD style: "SHA256 (filename) = hash"
- * - GNU style: "hash  filename" (two spaces)
- * - Simple style: "hash filename" (single space)
- *
- * Lines starting with '#' are treated as comments and ignored.
- * Empty lines are ignored.
- *
- * @param text - Raw text content of a checksums file
- * @returns Map of filenames to lowercase SHA256 hashes
- *
- * @example
- * ```ts
- * const text = `
- * # SHA256 checksums
- * e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  file.zip
- * abc123def456...  other.tar.gz
- * `
- * const checksums = parseChecksums(text)
- * console.log(checksums['file.zip']) // 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
- * ```
- */
-export declare function parseChecksums(text: string): Checksums;
 /**
  * Options for fetching checksums from a URL.
  */
@@ -749,6 +666,20 @@ export interface FetchChecksumsOptions {
      */
     timeout?: number | undefined;
 }
+/**
+ * Build an enriched error message based on the error code.
+ * Generic guidance (no product-specific branding).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch('https://api.example.com')
+ * } catch (err) {
+ *   console.error(enrichErrorMessage('https://api.example.com', 'GET', err))
+ * }
+ * ```
+ */
+export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**
  * Fetch and parse a checksums file from a URL.
  *
@@ -776,20 +707,6 @@ export interface FetchChecksumsOptions {
  * ```
  */
 export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
-/**
- * Build an enriched error message based on the error code.
- * Generic guidance (no product-specific branding).
- *
- * @example
- * ```typescript
- * try {
- *   await fetch('https://api.example.com')
- * } catch (err) {
- *   console.error(enrichErrorMessage('https://api.example.com', 'GET', err))
- * }
- * ```
- */
-export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**
  * Download a file from a URL to a local path with redirect support, retry logic, and progress callbacks.
  * Uses streaming to avoid loading entire file in memory.
@@ -973,3 +890,86 @@ export declare function httpRequest(url: string, options?: HttpRequestOptions |
  * ```
  */
 export declare function httpText(url: string, options?: HttpRequestOptions | undefined): Promise<string>;
+/**
+ * Parse a checksums file text into a filename-to-hash map.
+ *
+ * Supports standard checksums file formats:
+ * - BSD style: "SHA256 (filename) = hash"
+ * - GNU style: "hash  filename" (two spaces)
+ * - Simple style: "hash filename" (single space)
+ *
+ * Lines starting with '#' are treated as comments and ignored.
+ * Empty lines are ignored.
+ *
+ * @param text - Raw text content of a checksums file
+ * @returns Map of filenames to lowercase SHA256 hashes
+ *
+ * @example
+ * ```ts
+ * const text = `
+ * # SHA256 checksums
+ * e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  file.zip
+ * abc123def456...  other.tar.gz
+ * `
+ * const checksums = parseChecksums(text)
+ * console.log(checksums['file.zip']) // 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ * ```
+ */
+export declare function parseChecksums(text: string): Checksums;
+/**
+ * Parse a `Retry-After` HTTP header value into milliseconds.
+ *
+ * Supports both formats defined in RFC 7231 §7.1.3:
+ * - **delay-seconds**: integer number of seconds (e.g., `"120"`)
+ * - **HTTP-date**: an absolute date/time (e.g., `"Fri, 31 Dec 2027 23:59:59 GMT"`)
+ *
+ * When the header is an array (multiple values), the first element is used.
+ *
+ * @param value - The raw Retry-After header value(s)
+ * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
+ *
+ * @example
+ * ```ts
+ * const delay = parseRetryAfterHeader(response.headers['retry-after'])
+ * if (delay !== undefined) {
+ *   await new Promise(resolve => setTimeout(resolve, delay))
+ * }
+ * ```
+ */
+export declare function parseRetryAfterHeader(value: string | string[] | undefined): number | undefined;
+/**
+ * Read and buffer a client-side IncomingResponse into an HttpResponse.
+ *
+ * Useful when you have a raw response from code that bypasses
+ * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
+ * or responses from third-party HTTP libraries) and need to convert it
+ * into the standard HttpResponse interface.
+ *
+ * @example
+ * ```typescript
+ * const raw = await makeRawRequest('https://example.com/api')
+ * const response = await readIncomingResponse(raw)
+ * console.log(response.status, response.body.toString('utf8'))
+ * ```
+ */
+export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
+/**
+ * Redact sensitive HTTP headers for safe logging and telemetry.
+ *
+ * Replaces values of sensitive headers (Authorization, Cookie, etc.)
+ * with `[REDACTED]`. Non-sensitive headers are passed through unchanged.
+ * Array values are joined with `', '`.
+ *
+ * @param headers - HTTP headers to sanitize
+ * @returns A new object with sensitive values redacted
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeHeaders({
+ *   'authorization': 'Bearer secret',
+ *   'content-type': 'application/json'
+ * })
+ * // { authorization: '[REDACTED]', 'content-type': 'application/json' }
+ * ```
+ */
+export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;