@juspay/neurolink 9.94.4 → 9.94.6

package/dist/utils/imageProcessor.js

@@ -2,13 +2,32 @@
  * 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";
+/**
+ * Minimum bytes required just to detect an image format from magic bytes (#293).
+ */
+export const MIN_IMAGE_SIZE = 12;
+/**
+ * Minimum plausible byte size for a non-empty image of each format (#293). A
+ * buffer that carries a format's magic bytes but is smaller than this is
+ * truncated/corrupt and would fail (or render blank) downstream — reject early
+ * with a clear message instead.
+ */
+export const MIN_VALID_IMAGE_SIZE = {
+    "image/png": 67,
+    "image/jpeg": 125,
+    "image/gif": 43,
+    "image/webp": 20,
+    "image/avif": 100,
+};
 /**
  * Network error codes that should trigger a retry
  */
@@ -58,6 +77,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
  */
@@ -71,12 +109,12 @@ export class ImageProcessor {
      * @returns Processed image as data URI
      */
     static async process(content, _options) {
-        // Validate content is non-empty before processing
-        if (content.length === 0) {
-            logger.error("Empty buffer provided");
-            throw new Error("Invalid image processing: buffer is empty");
-        }
-        const mediaType = this.detectImageType(content);
+        // #293: reject empty AND small/truncated buffers (not just 0 bytes) before
+        // processing; returns the detected media type.
+        const mediaType = this.validateBufferNotEmpty(content);
+        // #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
@@ -91,6 +129,73 @@ export class ImageProcessor {
             },
         };
     }
+    /**
+     * Strict magic-byte match: does `content` actually begin with `mediaType`'s
+     * signature? `detectImageType` returns `image/jpeg` as a *fallback* for
+     * unrecognized data, so a per-format minimum must only be enforced when the
+     * bytes genuinely match — otherwise valid BMP/TIFF/unknown buffers would be
+     * wrongly rejected as "truncated jpeg" (#293 review).
+     */
+    static hasStrictImageMagic(content, mediaType) {
+        const b = content;
+        switch (mediaType) {
+            case "image/png":
+                return (b.length >= 4 &&
+                    b[0] === 0x89 &&
+                    b[1] === 0x50 &&
+                    b[2] === 0x4e &&
+                    b[3] === 0x47);
+            case "image/jpeg":
+                return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
+            case "image/gif":
+                return b.length >= 3 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46;
+            case "image/webp":
+                return (b.length >= 12 &&
+                    b.subarray(0, 4).toString("latin1") === "RIFF" &&
+                    b.subarray(8, 12).toString("latin1") === "WEBP");
+            case "image/avif":
+                return (b.length >= 12 &&
+                    b.subarray(4, 8).toString("latin1") === "ftyp" &&
+                    b.subarray(8, 12).toString("latin1").startsWith("avif"));
+            default:
+                return false;
+        }
+    }
+    /**
+     * Validate that a buffer is a plausibly-complete image (#293): non-empty and,
+     * for a strictly-identified raster format, at least the minimum plausible byte
+     * size. Returns the detected media type.
+     *
+     * @throws Error when the buffer is empty or a recognized format is truncated.
+     */
+    static validateBufferNotEmpty(content) {
+        if (content.length === 0) {
+            logger.error("Empty buffer provided");
+            throw ErrorFactory.imageBufferInvalid("Invalid image processing: buffer is empty");
+        }
+        const mediaType = this.detectImageType(content);
+        // SVG is text and can be legitimately tiny (e.g. `<svg/>`), so the raster
+        // size floors don't apply to it (#293 review).
+        if (mediaType === "image/svg+xml") {
+            return mediaType;
+        }
+        // A buffer too small to carry any raster header is not a usable image.
+        if (content.length < MIN_IMAGE_SIZE) {
+            throw ErrorFactory.imageBufferInvalid(`Invalid image processing: buffer too small (${content.length} bytes) — ` +
+                `a minimum of ${MIN_IMAGE_SIZE} bytes is required for a valid image.`);
+        }
+        // Only enforce a per-format minimum when the format was strictly identified
+        // from magic bytes (never from detectImageType's jpeg fallback), so valid
+        // BMP/TIFF/unknown buffers are not mis-rejected as "truncated jpeg".
+        const minForFormat = MIN_VALID_IMAGE_SIZE[mediaType];
+        if (minForFormat !== undefined &&
+            content.length < minForFormat &&
+            this.hasStrictImageMagic(content, mediaType)) {
+            throw ErrorFactory.imageBufferInvalid(`Invalid image processing: ${mediaType} buffer is truncated ` +
+                `(${content.length} bytes, minimum ${minForFormat} for a valid ${mediaType}).`);
+        }
+        return mediaType;
+    }
     /**
      * Validate processed output meets required format
      * Checks:
@@ -327,20 +432,50 @@ 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";
         }
     }
     /**
@@ -415,6 +550,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());
     }
@@ -495,7 +636,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;
@@ -687,6 +840,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
      */
@@ -706,11 +868,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;
         }
     },
     /**
@@ -796,14 +985,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

package/dist/utils/logSanitize.js

@@ -15,6 +15,7 @@
  *     jina_ (Jina), fish- (Fish Audio)
  *   - Generic key=value pairs: api_key=…, access_token: …, secret_key=…
  */
+import { basename, resolve as resolvePath } from "path";
 const TOKEN_PREFIXES = [
     "sk",
     "pk",
@@ -156,12 +157,161 @@ export function safeDebugSerialize(value, maxLen = 10_000) {
  * 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 function redactUrlCredentials(url) {
-    return url.replace(/\/\/[^/@]+@/g, "//***@");
+    const wellFormed = url.replace(/\/\/[^/\s"'<>]*@/g, "//***@");
+    return wellFormed.replace(/\/\/(?:(?!\/\/)[^\s"'<>])*@/g, "//***@");
+}
+/**
+ * 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 function redactUrlForError(url) {
+    const truncate = (s) => s.length > 200 ? `${s.slice(0, 200)}…` : s;
+    try {
+        const parsed = new URL(url);
+        // Reconstruct explicitly from protocol + host + pathname — never
+        // parsed.username/parsed.password, and never parsed.href (which
+        // re-serializes any embedded userinfo) — so a `user:pass@host` in the
+        // input can't leak into a diagnostic error message.
+        return truncate(`${parsed.protocol}//${parsed.host}${parsed.pathname}`);
+    }
+    catch {
+        // Unparseable input: `new URL()` gave us nothing to work with, so
+        // best-effort drop the query/fragment (where secrets like tokens live)
+        // and strip any `//user:pass@` segment before falling back to the raw
+        // string — never echo the input completely unredacted.
+        const withoutQueryOrFragment = url.split(/[?#]/)[0];
+        return truncate(redactUrlCredentials(withoutQueryOrFragment));
+    }
+}
+/**
+ * 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 function redactUrlsInText(text) {
+    return text.replace(/[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"'<>)]+/g, (match) => redactUrlForError(match));
+}
+/**
+ * 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 function redactPathFromMessage(message, filePath) {
+    const safeName = basename(filePath);
+    // Longest-first: the resolved (absolute) form always contains the relative
+    // form as a substring, so redacting the relative form first would only
+    // strip the trailing segment of an absolute path and leave its parent
+    // directory behind (e.g. "/Users/me/project/foo/bar.png" redacting
+    // "foo/bar.png" first leaves "/Users/me/project/bar.png"). Redacting the
+    // longer resolved variant first removes the whole absolute path in one
+    // pass, so the shorter relative pass below has nothing left to match.
+    return message
+        .split(resolvePath(filePath))
+        .join(safeName)
+        .split(filePath)
+        .join(safeName);
+}
+/**
+ * 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 function sanitizeErrorCause(error, options) {
+    const redact = (text) => {
+        const urlSafe = redactUrlsInText(text);
+        return options?.filePath
+            ? redactPathFromMessage(urlSafe, options.filePath)
+            : urlSafe;
+    };
+    if (!(error instanceof Error)) {
+        return new Error(redact(String(error)));
+    }
+    const sanitized = new Error(redact(error.message));
+    sanitized.name = error.name;
+    const code = error.code;
+    if (code !== undefined) {
+        sanitized.code = code;
+    }
+    return sanitized;
 }
 /**
  * Recursively sanitize a record/array, returning a structurally identical