@juspay/neurolink 9.94.3 → 9.94.5

package/dist/utils/imageProcessor.d.ts

@@ -2,6 +2,7 @@
  * Image processing utilities for multimodal support
  * Handles format conversion for different AI providers
  */
+import { redactPathFromMessage } from "./logSanitize.js";
 import type { ProcessedImage, FileProcessingResult } from "../types/index.js";
 /**
  * Image processor class for handling provider-specific image formatting
@@ -59,9 +60,41 @@ export declare class ImageProcessor {
      */
     static detectImageType(input: string | Buffer): string;
     /**
-     * Validate image size (default 10MB limit)
+     * Throwing size guard for a raw byte length. Prevents memory exhaustion by
+     * rejecting an oversized input BEFORE an unbounded read/allocation happens
+     * (#257) — callers that can get a size cheaply (e.g. `fs.stat`) should
+     * validate it before ever reading the bytes into memory. Default limit is
+     * the canonical `SIZE_LIMITS_BYTES.IMAGE_MAX` (10 MB); there is no public
+     * way to raise it — `maxSize` is an internal-only override for advanced
+     * callers (e.g. video image inputs use a higher limit).
+     *
+     * @param size - Byte length to validate
+     * @param context - Short label identifying the source (unused in the
+     *   thrown message today, kept for call-site readability and future use)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`INVALID_IMAGE_SIZE`) if `size` is not a finite,
+     *   non-negative number
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if `size` exceeds `maxSize`
+     */
+    static validateSize(size: number, context: string, maxSize?: number): void;
+    /**
+     * Throwing size guard for image buffers. Prevents memory exhaustion by
+     * rejecting oversized buffers with a descriptive error BEFORE an unbounded
+     * `Buffer.toString("base64")` allocation (#257). Delegates to
+     * `validateSize` so buffer-based and pre-read (stat-based) callers share
+     * one implementation.
+     *
+     * @param buffer - Image buffer to validate
+     * @param context - Short label identifying the source (see `validateSize`)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if the buffer exceeds `maxSize`
+     */
+    static validateBufferSize(buffer: Buffer, context: string, maxSize?: number): void;
+    /**
+     * Size-guarded Buffer → base64. Use in place of `buffer.toString("base64")`
+     * on any path that converts a caller-supplied image buffer (#257).
      */
-    static validateImageSize(data: Buffer | string, maxSize?: number): boolean;
+    static safeBase64Convert(buffer: Buffer, context: string, maxSize?: number): string;
     /**
      * Validate image format
      */
@@ -126,13 +159,28 @@ export declare const imageUtils: {
      */
     formatFileSize: (bytes: number) => string;
     /**
-     * Convert Buffer to base64 string
+     * Convert Buffer to base64 string. Guarded by the same #257 size limit as
+     * every other conversion site (default `SIZE_LIMITS_BYTES.IMAGE_MAX`);
+     * pass `maxBytes` to override for a caller with a legitimate need for a
+     * different ceiling rather than silently accepting an unbounded buffer.
+     * `imageUtils`/`ImageProcessor` are internal-only — not re-exported from
+     * `src/lib/index.ts` or the package's public `exports` map — so this
+     * default does not change behavior for any external SDK consumer.
      */
-    bufferToBase64: (buffer: Buffer) => string;
+    bufferToBase64: (buffer: Buffer, maxBytes?: number) => string;
     /**
      * Convert base64 string to Buffer
      */
     base64ToBuffer: (base64: string) => Buffer;
+    /**
+     * Redact `filePath` (both as given and its `path.resolve()`'d form) from
+     * an error message. Exposed directly (not just used internally by
+     * {@link fileToBase64DataUri}) so the resolved-path branch can be verified
+     * by a deterministic unit test — real `fs` errors only ever embed the
+     * literal path as passed, never a resolved variant, so that branch isn't
+     * otherwise observable through the async file-reading API.
+     */
+    redactPathFromMessage: typeof redactPathFromMessage;
     /**
      * Convert file path to base64 data URI
      */

package/dist/utils/imageProcessor.js

@@ -2,11 +2,15 @@
  * Image processing utilities for multimodal support
  * Handles format conversion for different AI providers
  */
+import { basename } from "path";
 import { logger } from "./logger.js";
+import { redactPathFromMessage, redactUrlForError, redactUrlsInText, sanitizeErrorCause, } from "./logSanitize.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { withRetry } from "./retryHandler.js";
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { SIZE_LIMITS_BYTES } from "../processors/config/sizeLimits.js";
 import { getImageCache } from "./imageCache.js";
+import { ErrorFactory, NeuroLinkError } from "./errorHandling.js";
 /**
  * Network error codes that should trigger a retry
  */
@@ -56,6 +60,25 @@ function isRetryableDownloadError(error) {
     }
     return false;
 }
+/**
+ * Reject `detectImageType()`'s `application/octet-stream` sentinel — the
+ * honest "no known image signature (PNG/JPEG/GIF/WebP/BMP/TIFF/SVG/AVIF)
+ * matched" fallback (#261/#286). Packaging that sentinel into a data URI
+ * hands vision providers (OpenAI/Anthropic/Google) a MIME type they reject
+ * outright with an HTTP 400, so every public conversion path that turns
+ * unknown bytes into image output must fail loud here first instead of
+ * letting the sentinel slip through to a caller.
+ *
+ * @param mediaType - The MIME type returned by `detectImageType()`.
+ * @throws Error if `mediaType` is the octet-stream sentinel.
+ */
+function assertKnownImageType(mediaType) {
+    if (mediaType === "application/octet-stream") {
+        logger.error("Unable to detect a supported image format from file content");
+        throw new Error("Unsupported or corrupted image: no known image signature " +
+            "(PNG/JPEG/GIF/WebP/BMP/TIFF/SVG/AVIF) was found in the file content.");
+    }
+}
 /**
  * Image processor class for handling provider-specific image formatting
  */
@@ -75,7 +98,10 @@ export class ImageProcessor {
             throw new Error("Invalid image processing: buffer is empty");
         }
         const mediaType = this.detectImageType(content);
-        const base64 = content.toString("base64");
+        // #261/#286 follow-up: fail loud instead of packaging the octet-stream
+        // sentinel as a "valid" image (see assertKnownImageType() above).
+        assertKnownImageType(mediaType);
+        const base64 = ImageProcessor.safeBase64Convert(content, "image processing");
         const dataUri = `data:${mediaType};base64,${base64}`;
         // Validate output before returning
         this.validateProcessOutput(dataUri, base64, mediaType);
@@ -138,10 +164,15 @@ export class ImageProcessor {
                 return `data:image/jpeg;base64,${image}`;
             }
             // Handle Buffer - convert to data URI
-            const base64 = image.toString("base64");
+            const base64 = ImageProcessor.safeBase64Convert(image, "OpenAI image input");
             return `data:image/jpeg;base64,${base64}`;
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for OpenAI:", error);
             throw new Error(`Image processing failed for OpenAI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -170,7 +201,7 @@ export class ImageProcessor {
                 }
             }
             else {
-                base64Data = image.toString("base64");
+                base64Data = ImageProcessor.safeBase64Convert(image, "provider image input");
             }
             return {
                 mimeType,
@@ -178,6 +209,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Google AI:", error);
             throw new Error(`Image processing failed for Google AI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -206,7 +242,7 @@ export class ImageProcessor {
                 }
             }
             else {
-                base64Data = image.toString("base64");
+                base64Data = ImageProcessor.safeBase64Convert(image, "provider image input");
             }
             return {
                 mediaType,
@@ -214,6 +250,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Anthropic:", error);
             throw new Error(`Image processing failed for Anthropic: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -238,6 +279,11 @@ export class ImageProcessor {
             }
         }
         catch (error) {
+            // Preserve typed errors bubbling up from processImageForGoogle/
+            // processImageForAnthropic (e.g. IMAGE_TOO_LARGE) as-is.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Vertex AI:", error);
             throw new Error(`Image processing failed for Vertex AI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -305,37 +351,111 @@ export class ImageProcessor {
                         return "image/svg+xml";
                     }
                 }
-                // AVIF: check for "ftypavif" signature at bytes 4-11
+                // AVIF (ISOBMFF): "ftyp" box at offset 4, major brand at offset 8.
+                // Accept the AVIF-spec brand variants — 'avif' (still image), 'avis'
+                // (image sequence), and 'avio' (intra-only AV1 image/sequence — the
+                // spec lists it under compatible_brands rather than major_brand, but
+                // real-world encoders emit it as major_brand too, so it's accepted
+                // here) — and compare bytes directly rather than via Buffer.toString()
+                // (which would utf-8-decode non-ASCII bytes) so the check is exact
+                // (#286).
                 if (input.length >= 12) {
-                    const ftyp = input.subarray(4, 8).toString();
-                    const brand = input.subarray(8, 12).toString();
-                    if (ftyp === "ftyp" && brand === "avif") {
+                    const isFtyp = input[4] === 0x66 && // 'f'
+                        input[5] === 0x74 && // 't'
+                        input[6] === 0x79 && // 'y'
+                        input[7] === 0x70; // 'p'
+                    const brand = String.fromCharCode(input[8], input[9], input[10], input[11]);
+                    if (isFtyp &&
+                        (brand === "avif" || brand === "avis" || brand === "avio")) {
                         return "image/avif";
                     }
                 }
+                // BMP: "BM" magic (0x42 0x4D)
+                if (input[0] === 0x42 && input[1] === 0x4d) {
+                    return "image/bmp";
+                }
+                // TIFF: little-endian "II*\0" or big-endian "MM\0*"
+                if ((input[0] === 0x49 &&
+                    input[1] === 0x49 &&
+                    input[2] === 0x2a &&
+                    input[3] === 0x00) ||
+                    (input[0] === 0x4d &&
+                        input[1] === 0x4d &&
+                        input[2] === 0x00 &&
+                        input[3] === 0x2a)) {
+                    return "image/tiff";
+                }
             }
-            return "image/jpeg"; // Default fallback
+            // No known image signature matched. Return a safe, honest sentinel
+            // rather than mislabeling arbitrary bytes as JPEG (#261): a wrong
+            // image/jpeg label silently corrupts the downstream provider request.
+            logger.warn("Could not detect image type from magic bytes; using application/octet-stream");
+            return "application/octet-stream";
         }
         catch (error) {
             logger.warn("Failed to detect image type, using default:", error);
-            return "image/jpeg";
+            return "application/octet-stream";
         }
     }
     /**
-     * Validate image size (default 10MB limit)
+     * Throwing size guard for a raw byte length. Prevents memory exhaustion by
+     * rejecting an oversized input BEFORE an unbounded read/allocation happens
+     * (#257) — callers that can get a size cheaply (e.g. `fs.stat`) should
+     * validate it before ever reading the bytes into memory. Default limit is
+     * the canonical `SIZE_LIMITS_BYTES.IMAGE_MAX` (10 MB); there is no public
+     * way to raise it — `maxSize` is an internal-only override for advanced
+     * callers (e.g. video image inputs use a higher limit).
+     *
+     * @param size - Byte length to validate
+     * @param context - Short label identifying the source (unused in the
+     *   thrown message today, kept for call-site readability and future use)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`INVALID_IMAGE_SIZE`) if `size` is not a finite,
+     *   non-negative number
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if `size` exceeds `maxSize`
      */
-    static validateImageSize(data, maxSize = 10 * 1024 * 1024) {
-        try {
-            const size = typeof data === "string"
-                ? Buffer.byteLength(data, "base64")
-                : data.length;
-            return size <= maxSize;
-        }
-        catch (error) {
-            logger.warn("Failed to validate image size:", error);
-            return false;
+    static validateSize(size, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        // Reject a malformed maxSize before it's ever compared: `size > NaN` and
+        // `size > Infinity` (for a negative maxSize) can both evaluate `false`,
+        // which would let a corrupted/negative limit bypass the guard entirely.
+        if (!Number.isFinite(maxSize) || maxSize < 0) {
+            throw ErrorFactory.invalidConfiguration("maxSize", "must be a finite, non-negative byte count", { maxSize, context });
+        }
+        // Fail closed on malformed sizes first: `NaN > maxSize` and
+        // `-1 > maxSize` both evaluate to `false`, which would otherwise let a
+        // corrupted stat/header value silently skip the guard below.
+        if (!Number.isFinite(size) || size < 0) {
+            throw ErrorFactory.invalidImageSize(size);
+        }
+        if (size > maxSize) {
+            const mb = (size / (1024 * 1024)).toFixed(1);
+            const maxMb = (maxSize / (1024 * 1024)).toFixed(0);
+            throw ErrorFactory.imageTooLarge(mb, maxMb);
         }
     }
+    /**
+     * Throwing size guard for image buffers. Prevents memory exhaustion by
+     * rejecting oversized buffers with a descriptive error BEFORE an unbounded
+     * `Buffer.toString("base64")` allocation (#257). Delegates to
+     * `validateSize` so buffer-based and pre-read (stat-based) callers share
+     * one implementation.
+     *
+     * @param buffer - Image buffer to validate
+     * @param context - Short label identifying the source (see `validateSize`)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if the buffer exceeds `maxSize`
+     */
+    static validateBufferSize(buffer, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        ImageProcessor.validateSize(buffer.length, context, maxSize);
+    }
+    /**
+     * Size-guarded Buffer → base64. Use in place of `buffer.toString("base64")`
+     * on any path that converts a caller-supplied image buffer (#257).
+     */
+    static safeBase64Convert(buffer, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        ImageProcessor.validateBufferSize(buffer, context, maxSize);
+        return buffer.toString("base64");
+    }
     /**
      * Validate image format
      */
@@ -349,6 +469,12 @@ export class ImageProcessor {
             "image/tiff",
             "image/svg+xml",
             "image/avif",
+            // Deliberately excludes "application/octet-stream": that's
+            // detectImageType()'s honest sentinel for bytes matching no known
+            // image signature (#261), not a real image format. Vision providers
+            // (OpenAI/Anthropic/Google) reject it outright with an HTTP 400, so
+            // process() must fail loud instead of packaging it as a valid image
+            // (see the octet-stream guard in process() below).
         ];
         return supportedFormats.includes(mediaType.toLowerCase());
     }
@@ -429,7 +555,19 @@ export class ImageProcessor {
      */
     static processImage(image, provider, model) {
         try {
+            // #257: reject an oversized buffer before any format-detection or
+            // conversion work runs on it — mirrors the guard every
+            // `processImageForX()` branch below already applies via
+            // `safeBase64Convert()`, so the typed IMAGE_TOO_LARGE error surfaces
+            // here too instead of being pre-empted by the octet-stream check next.
+            if (Buffer.isBuffer(image)) {
+                ImageProcessor.validateBufferSize(image, "image processing");
+            }
             const mediaType = ImageProcessor.detectImageType(image);
+            // #261/#286 follow-up: reject the octet-stream sentinel here too — the
+            // returned ProcessedImage.mediaType is what callers use to build a
+            // data URI, so this is a separate public path that must not emit it.
+            assertKnownImageType(mediaType);
             const size = typeof image === "string"
                 ? Buffer.byteLength(image, "base64")
                 : image.length;
@@ -467,7 +605,7 @@ export class ImageProcessor {
                             : image;
                     }
                     else {
-                        data = image.toString("base64");
+                        data = ImageProcessor.safeBase64Convert(image, "image input");
                     }
                     format = "base64";
             }
@@ -479,6 +617,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) bubbling up from the
+            // provider-specific branches above as-is.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error(`Failed to process image for ${provider}:`, error);
             throw new Error(`Image processing failed: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -597,10 +740,16 @@ export const imageUtils = {
         return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
     },
     /**
-     * Convert Buffer to base64 string
+     * Convert Buffer to base64 string. Guarded by the same #257 size limit as
+     * every other conversion site (default `SIZE_LIMITS_BYTES.IMAGE_MAX`);
+     * pass `maxBytes` to override for a caller with a legitimate need for a
+     * different ceiling rather than silently accepting an unbounded buffer.
+     * `imageUtils`/`ImageProcessor` are internal-only — not re-exported from
+     * `src/lib/index.ts` or the package's public `exports` map — so this
+     * default does not change behavior for any external SDK consumer.
      */
-    bufferToBase64: (buffer) => {
-        return buffer.toString("base64");
+    bufferToBase64: (buffer, maxBytes = SIZE_LIMITS_BYTES.IMAGE_MAX) => {
+        return ImageProcessor.safeBase64Convert(buffer, "buffer-to-base64", maxBytes);
     },
     /**
      * Convert base64 string to Buffer
@@ -610,6 +759,15 @@ export const imageUtils = {
         const cleanBase64 = base64.includes(",") ? base64.split(",")[1] : base64;
         return Buffer.from(cleanBase64, "base64");
     },
+    /**
+     * Redact `filePath` (both as given and its `path.resolve()`'d form) from
+     * an error message. Exposed directly (not just used internally by
+     * {@link fileToBase64DataUri}) so the resolved-path branch can be verified
+     * by a deterministic unit test — real `fs` errors only ever embed the
+     * literal path as passed, never a resolved variant, so that branch isn't
+     * otherwise observable through the async file-reading API.
+     */
+    redactPathFromMessage,
     /**
      * Convert file path to base64 data URI
      */
@@ -629,11 +787,38 @@ export const imageUtils = {
             // Enhanced MIME detection: try buffer content first, fallback to filename
             const mimeType = ImageProcessor.detectImageType(buffer) ||
                 ImageProcessor.detectImageType(filePath);
+            // #261/#286 follow-up: reject the octet-stream sentinel here too —
+            // this is a third public path (alongside process() and
+            // processImage()) that can otherwise package unknown bytes into a
+            // `data:application/octet-stream;base64,...` URI a vision provider
+            // rejects outright.
+            assertKnownImageType(mimeType);
             const base64 = buffer.toString("base64");
             return `data:${mimeType};base64,${base64}`;
         }
         catch (error) {
-            throw new Error(`Failed to convert file to base64: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
+            // Full path stays in the debug log; the thrown (potentially
+            // client-facing) error only gets the basename. The underlying fs
+            // error's own message is scrubbed too — Node's ENOENT/EACCES text
+            // embeds the full path verbatim (e.g. "no such file or directory,
+            // stat '/full/path'"), which would otherwise leak the host's
+            // directory layout right back through the "reason" suffix. The raw
+            // `error` is never attached as `cause` either — that would leave the
+            // unredacted path reachable via `error.cause.message` for anything
+            // that walks the cause chain (cause-aware logging, telemetry); a
+            // sanitized copy (via the shared `sanitizeErrorCause`) is attached
+            // instead, mirroring `urlToBase64DataUri` below.
+            logger.debug("fileToBase64DataUri failed", { filePath, error });
+            const safeName = basename(filePath);
+            const cause = sanitizeErrorCause(error, { filePath });
+            const reason = error instanceof Error ? cause.message : "Unknown error";
+            // Assigned to a variable before throwing (rather than `throw new
+            // Error(...)` inline) so the sanitized `cause` — a deliberately NEW,
+            // redacted Error — isn't mistaken by tooling for a dropped/altered
+            // reference to the originally caught `error`; the raw error is never
+            // reachable from the thrown result at all, by design.
+            const wrapped = new Error(`Failed to convert file to base64 (${safeName}): ${reason}`, { cause });
+            throw wrapped;
         }
     },
     /**
@@ -719,14 +904,31 @@ export const imageUtils = {
                 maxDelay: SYSTEM_LIMITS.DEFAULT_MAX_DELAY,
                 retryCondition: isRetryableDownloadError,
                 onRetry: (attempt, error) => {
-                    const message = error instanceof Error ? error.message : String(error);
+                    // Some fetch/DNS/TLS errors embed the full request URL (including
+                    // a presigned query token) in `error.message` — redact that text
+                    // too, not just the explicit `url` interpolation below. The
+                    // non-Error branch is sanitized too: String(error) on a thrown
+                    // non-Error value (e.g. a raw string or object) can just as
+                    // easily carry the same signed URL.
+                    const message = redactUrlsInText(error instanceof Error ? error.message : String(error));
                     const attemptsLeft = maxAttempts - attempt;
-                    logger.warn(`⚠️ Image download attempt ${attempt} failed for ${url}: ${message}. ${attemptsLeft} ${attemptsLeft === 1 ? "attempt" : "attempts"} remaining...`);
+                    logger.warn(`⚠️ Image download attempt ${attempt} failed for ${redactUrlForError(url)}: ${message}. ${attemptsLeft} ${attemptsLeft === 1 ? "attempt" : "attempts"} remaining...`);
                 },
             });
         }
         catch (error) {
-            throw new Error(`Failed to download and convert URL to base64: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
+            // Query string / fragment stripped — a presigned S3/GCS URL or SAS
+            // token embedded there must not be echoed into a thrown error. The
+            // underlying error's own message is scrubbed too, since fetch/DNS/TLS
+            // errors often embed the full URL (query string and all) themselves.
+            // The raw `error` is never attached as `cause` — that would leave the
+            // unredacted URL reachable via `error.cause.message` for anything
+            // that walks the cause chain (cause-aware logging, telemetry); a
+            // sanitized copy is attached instead.
+            const sourceUrl = redactUrlForError(url);
+            const cause = sanitizeErrorCause(error);
+            const wrapped = new Error(`Failed to download and convert URL to base64 (${sourceUrl}): ${cause.message}`, { cause });
+            throw wrapped;
         }
     },
     /**

package/dist/utils/logSanitize.d.ts

@@ -61,11 +61,110 @@ export declare function safeDebugSerialize(value: unknown, maxLen?: number): str
  * for diagnostics. Use this for any `baseURL`/endpoint a caller may have
  * supplied with inline credentials. The match is global, so every `//…@`
  * authority in the string is redacted (e.g. a proxy chain or a URL embedded
- * in a query parameter), not just the first.
+ * in a query parameter), not just the first. IPv6 literal hosts (`//u:p@[::1]/x`)
+ * and percent-encoded userinfo (`//u:p%40x@host/x`) are handled naturally —
+ * neither `[`/`]` nor `%` stop either pass below, so the bracketed host or
+ * encoded byte just rides along as part of the (non-redacted) remainder.
+ *
+ * This is best-effort defense-in-depth for free-form logging, deliberately
+ * regex-based so it can scrub *multiple* embedded authorities out of
+ * arbitrary text (a real URL parser only ever parses one URL at a time).
+ * It is NOT the primary protection for user-facing errors — that's
+ * {@link redactUrlForError}, which parses the single input via `new URL()`
+ * and reconstructs from protocol+host+pathname, never touching userinfo at
+ * all. Prefer that function whenever the input is known to be exactly one
+ * URL.
+ *
+ * Two passes, deliberately:
+ *  1. Well-formed authorities — credentials with no raw `/` — bounded at the
+ *     authority's first `/` (or string end). Greedy backtracking naturally
+ *     absorbs multiple `@` segments within one authority (e.g. `//a@b@host`
+ *     → `//***@host`) while leaving a second, separate `//...@` authority
+ *     elsewhere in the string (e.g. one embedded in a query parameter)
+ *     untouched, because pass 1's own exclusion of `/` stops it at the first
+ *     `/`, before it can ever reach a nested authority.
+ *  2. Malformed authorities whose credentials contain an unescaped `/`
+ *     (e.g. `//user:sec/ret@host/path`) — pass 1 can't find an `@` before
+ *     hitting that `/`, so this pass allows `/` and redacts up to the last
+ *     remaining `@`. It stops before any *nested* `//` (via a negative
+ *     lookahead) rather than excluding a specific character like `*` —
+ *     excluding a literal character is what let a password containing both
+ *     `/` and `*` (e.g. `//user:pa*ss/word@host/path`, legal under RFC 3986)
+ *     slip through both passes entirely in an earlier version of this
+ *     function.
  *
  * @param url - The URL (or URL-shaped string) to redact.
  */
 export declare function redactUrlCredentials(url: string): string;
+/**
+ * Reduce a URL to its origin + pathname for safe inclusion in error messages
+ * and logs, dropping the query string and fragment — where presigned-URL
+ * signatures, SAS tokens, and other secrets commonly live — while keeping
+ * enough of the URL (scheme, host, path) for the error to stay diagnostic.
+ *
+ * Falls back to a best-effort redacted string (query/fragment and
+ * `user:pass@` stripped) when the input isn't a parseable absolute URL.
+ * Either way the result is capped at 200 chars so a very long host/path
+ * can't blow up the error message.
+ *
+ * @param url - The URL (or URL-shaped string) to redact.
+ */
+export declare function redactUrlForError(url: string): string;
+/**
+ * Scrub any embedded absolute URLs out of free-form text — typically the
+ * `.message` of an underlying network/DNS/TLS error thrown by `fetch`,
+ * undici's `request()`, or Node's resolver, all of which frequently embed
+ * the full request URL (query string, credentials, and all) verbatim.
+ * Interpolating that message raw into a thrown or logged error would leak a
+ * presigned URL's token even after the explicit URL argument was already
+ * redacted via {@link redactUrlForError}. Finds each `scheme://…` run in the
+ * text and replaces it with its redacted form.
+ *
+ * @param text - Free-form text (typically `Error.message`) to scrub.
+ */
+export declare function redactUrlsInText(text: string): string;
+/**
+ * Redact every occurrence of `filePath` from an error message, checking both
+ * the path exactly as given and its `path.resolve()`'d form.
+ *
+ * Node's own fs errors (ENOENT/EACCES) embed the exact string passed to the
+ * fs call, so a plain substring match usually suffices — but wrapped or
+ * lower-level errors sometimes normalize the path first (relative→absolute,
+ * trailing-slash variations), which an exact-match-only redaction would miss.
+ * This is defense-in-depth, not a guarantee: a `realpath`-resolved (symlink-
+ * following) variant can still differ from both forms and would slip through.
+ *
+ * @param message  - The error message to scrub.
+ * @param filePath - The path to redact (both as given and resolved).
+ */
+export declare function redactPathFromMessage(message: string, filePath: string): string;
+/**
+ * Build a sanitized copy of a network/URL/file error, safe to attach as
+ * `Error.cause` on a rethrow.
+ *
+ * Redacting only the OUTER thrown error's message isn't enough: if the RAW
+ * underlying error is attached as `cause`, anything that walks the cause
+ * chain (cause-aware logging, telemetry spans) can still recover an
+ * unredacted URL/path/secret via `error.cause.message`. This returns a NEW
+ * `Error` whose message has been through {@link redactUrlsInText} — and,
+ * when `options.filePath` is supplied, {@link redactPathFromMessage} too, so
+ * a filesystem error's ENOENT/EACCES text doesn't leak the host's directory
+ * layout via the cause chain the way the outer message already avoids.
+ * `.name` and `.code` (`NodeJS.ErrnoException`) are copied over so retry
+ * classification (e.g. `isRetryableNetworkError`) still works when it
+ * inspects the cause. The raw original is never referenced by the result.
+ *
+ * Handles non-`Error` thrown values too (a raw string/object can just as
+ * easily carry an unredacted URL or path) by running their `String()` form
+ * through the same redaction before wrapping.
+ *
+ * @param error   - The raw underlying error (or thrown value) to sanitize.
+ * @param options - `filePath`: a known filesystem path to redact to its
+ *                  basename, in addition to URL redaction.
+ */
+export declare function sanitizeErrorCause(error: unknown, options?: {
+    filePath?: string;
+}): Error;
 /**
  * Recursively sanitize a record/array, returning a structurally identical
  * value with sensitive keys redacted and string values run through