@juspay/neurolink 9.94.4 → 9.94.5

package/dist/lib/utils/fileDetector.js

@@ -4,7 +4,7 @@
  * Uses multi-strategy approach for reliable type identification
  */
 import { open, readFile, realpath } from "fs/promises";
-import { isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
+import { basename, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 // Lazy-loaded processor singletons — avoids loading heavy media deps
 // (mediabunny, fluent-ffmpeg, music-metadata, adm-zip) on every generate() call.
@@ -24,6 +24,7 @@ import { tracers, ATTR, withSpan } from "../telemetry/index.js";
 import { CSVProcessor } from "./csvProcessor.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
+import { redactUrlForError, sanitizeErrorCause } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
 /**
@@ -1338,25 +1339,55 @@ export class FileDetector {
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
         return withRetry(async () => {
-            const response = await request(url, {
-                dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
-                method: "GET",
-                headersTimeout: timeout,
-                bodyTimeout: timeout,
-            });
-            if (response.statusCode !== 200) {
-                throw new Error(`HTTP ${response.statusCode} fetching ${url}`);
-            }
-            const chunks = [];
-            let totalSize = 0;
-            for await (const chunk of response.body) {
-                totalSize += chunk.length;
-                if (totalSize > maxSize) {
-                    throw new Error(`File too large: ${formatFileSize(totalSize)} (max: ${formatFileSize(maxSize)})`);
+            try {
+                const response = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "GET",
+                    headersTimeout: timeout,
+                    bodyTimeout: timeout,
+                });
+                if (response.statusCode !== 200) {
+                    // Query string / fragment stripped — a presigned URL's token must
+                    // not be echoed into a thrown error.
+                    throw new Error(`HTTP ${response.statusCode} fetching ${redactUrlForError(url)}`);
                 }
-                chunks.push(chunk);
+                const chunks = [];
+                let totalSize = 0;
+                for await (const chunk of response.body) {
+                    totalSize += chunk.length;
+                    if (totalSize > maxSize) {
+                        throw new Error(`File too large: ${formatFileSize(totalSize)} (max: ${formatFileSize(maxSize)})`);
+                    }
+                    chunks.push(chunk);
+                }
+                return Buffer.concat(chunks);
+            }
+            catch (error) {
+                // Node/undici DNS, TLS, and connect-timeout errors embed the full
+                // request URL (including a presigned query token) in
+                // `error.message`. Redact into a NEW error instead of mutating the
+                // original in place, so anything that still holds a reference to
+                // the original — debug logs, telemetry spans, upstream callers —
+                // keeps seeing the real message. `.code` is copied onto the new
+                // error so `isRetryableNetworkError`'s retry check in the outer
+                // `withRetry` catch still classifies it correctly. The raw
+                // original 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). `cause` instead gets its own sanitized copy.
+                // `sanitizeErrorCause` handles non-`Error` thrown values too (a raw
+                // string/object can just as easily carry the full URL), so there is
+                // no unconditional `throw error` fallback that would bypass
+                // redaction for that case.
+                const cause = sanitizeErrorCause(error);
+                const redacted = new Error(cause.message, { cause });
+                redacted.name = cause.name;
+                const code = cause.code;
+                if (code !== undefined) {
+                    redacted.code = code;
+                }
+                throw redacted;
             }
-            return Buffer.concat(chunks);
         }, { maxRetries, retryDelay });
     }
     /**
@@ -1374,6 +1405,13 @@ export class FileDetector {
         // the base dir pointing outside cannot bypass containment. The
         // path.relative check (not a string prefix) correctly handles the root dir
         // ("/") and sibling-prefix ("/app" vs "/app-evil") edge cases.
+        //
+        // The actual open() below MUST target this validated `real` path, not the
+        // original `filePath` — otherwise a symlink swapped between the realpath()
+        // check and the open() call routes the read outside the sandbox even
+        // though validation passed (TOCTOU). With no sandbox configured there's no
+        // boundary to defend, so the original path is used as given.
+        let pathToOpen = filePath;
         if (options?.allowedBaseDir) {
             let base;
             let real;
@@ -1381,24 +1419,66 @@ export class FileDetector {
                 base = await realpath(resolvePath(options.allowedBaseDir));
                 real = await realpath(filePath);
             }
-            catch {
-                throw new Error(`Access denied: "${filePath}" could not be resolved within the allowed base directory`);
+            catch (error) {
+                // Full path stays in the debug log; the thrown (potentially
+                // client-facing) error only gets the basename to avoid leaking the
+                // host's directory layout to an untrusted caller. The cause is
+                // sanitized too — Node's realpath ENOENT/EACCES messages embed the
+                // full path verbatim, which would otherwise survive on the cause
+                // chain (cause-aware logging, telemetry) even though the outer
+                // message is already redacted.
+                logger.debug("loadFromPath: realpath resolution failed", {
+                    filePath,
+                    error,
+                });
+                // Assigned to a variable before the throw (rather than an inline
+                // `{ cause: sanitizeErrorCause(...) }`) so the sanitized, path-redacted
+                // copy is unambiguously the attached cause — the raw `error`, whose
+                // message still embeds the full path, is never reachable from the
+                // thrown result.
+                const cause = sanitizeErrorCause(error, { filePath });
+                const denied = new Error(`Access denied: "${basename(filePath)}" could not be resolved within the allowed base directory`, { cause });
+                throw denied;
             }
             const rel = relativePath(base, real);
             if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolutePath(rel)) {
-                throw new Error(`Access denied: "${filePath}" resolves outside the allowed base directory`);
+                logger.debug("loadFromPath: path resolves outside allowed base dir", {
+                    filePath,
+                    real,
+                });
+                throw new Error(`Access denied: "${basename(filePath)}" resolves outside the allowed base directory`);
             }
+            pathToOpen = real;
         }
         // Open a handle and stat/read through the SAME descriptor so a symlink
         // swap between the size check and the read cannot occur (TOCTOU).
-        const handle = await open(filePath, "r");
+        let handle;
+        try {
+            handle = await open(pathToOpen, "r");
+        }
+        catch (error) {
+            // A failed open (ENOENT/EACCES/…) embeds the opened path verbatim in
+            // its message. When a sandbox is configured `pathToOpen` is the
+            // realpath-resolved target (`real`), which differs from both `filePath`
+            // and its resolved form — so redact `pathToOpen` specifically, or the
+            // full host path would survive on both the thrown message and the cause
+            // chain despite this PR's path-redaction hardening.
+            const cause = sanitizeErrorCause(error, { filePath: pathToOpen });
+            const failed = new Error(cause.message, { cause });
+            failed.name = cause.name;
+            const code = cause.code;
+            if (code !== undefined) {
+                failed.code = code;
+            }
+            throw failed;
+        }
         try {
             const statInfo = await handle.stat();
             if (!statInfo.isFile()) {
-                throw new Error(`Not a file: ${filePath}`);
+                throw new Error(`Not a file: ${basename(filePath)}`);
             }
             if (statInfo.size > maxSize) {
-                throw new Error(`File too large: ${filePath} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+                throw new Error(`File too large: ${basename(filePath)} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
             }
             return await handle.readFile();
         }
@@ -1450,6 +1530,15 @@ class MagicBytesStrategy {
             input[6] === 0x79 &&
             input[7] === 0x70) {
             const brand = input.length >= 12 ? input.toString("latin1", 8, 12) : "";
+            // AVIF images share the ISO-BMFF ftyp box with MP4/MOV; the major brand
+            // ('avif' still, 'avis' sequence, 'avio' intra-only AV1 image/sequence
+            // — spec-listed under compatible_brands but also emitted as
+            // major_brand by real encoders) distinguishes them. Detect before the
+            // audio/video branches so an AVIF buffer isn't misrouted to the video
+            // pipeline (#286).
+            if (/^(avif|avis|avio)/.test(brand)) {
+                return this.result("image", "image/avif", 95);
+            }
             if (/^(M4A|M4B|M4P|F4A|F4B)/.test(brand)) {
                 return this.result("audio", "audio/mp4", 95);
             }

package/dist/lib/utils/imageCache.js

@@ -14,6 +14,7 @@
  */
 import { createHash } from "crypto";
 import { logger } from "./logger.js";
+import { redactUrlForError } from "./logSanitize.js";
 /**
  * LRU Cache for downloaded images
  *
@@ -142,7 +143,9 @@ export class ImageCache {
         const entry = this.cache.get(normalizedUrl);
         if (!entry) {
             this.stats.misses++;
-            logger.debug("Image cache miss", { url: normalizedUrl.substring(0, 50) });
+            logger.debug("Image cache miss", {
+                url: redactUrlForError(normalizedUrl),
+            });
             return null;
         }
         // Check TTL expiration
@@ -150,7 +153,7 @@ export class ImageCache {
             this.stats.expirations++;
             this.delete(normalizedUrl);
             logger.debug("Image cache entry expired", {
-                url: normalizedUrl.substring(0, 50),
+                url: redactUrlForError(normalizedUrl),
             });
             return null;
         }
@@ -162,7 +165,7 @@ export class ImageCache {
         this.cache.set(normalizedUrl, entry);
         this.stats.hits++;
         logger.debug("Image cache hit", {
-            url: normalizedUrl.substring(0, 50),
+            url: redactUrlForError(normalizedUrl),
             accessCount: entry.accessCount,
         });
         return entry;
@@ -192,7 +195,7 @@ export class ImageCache {
         // Skip caching if image exceeds max size
         if (size > this.maxImageSize) {
             logger.debug("Image too large to cache", {
-                url: normalizedUrl.substring(0, 50),
+                url: redactUrlForError(normalizedUrl),
                 size,
                 maxSize: this.maxImageSize,
             });
@@ -211,8 +214,8 @@ export class ImageCache {
                 // Update content hash index to point to the new URL as well
                 this.contentHashIndex.set(contentHash, normalizedUrl);
                 logger.debug("Image cache dedup hit", {
-                    newUrl: normalizedUrl.substring(0, 50),
-                    existingUrl: existingUrl.substring(0, 50),
+                    newUrl: redactUrlForError(normalizedUrl),
+                    existingUrl: redactUrlForError(existingUrl),
                 });
                 return;
             }
@@ -234,7 +237,7 @@ export class ImageCache {
         this.cache.set(normalizedUrl, entry);
         this.contentHashIndex.set(contentHash, normalizedUrl);
         logger.debug("Image cached", {
-            url: normalizedUrl.substring(0, 50),
+            url: redactUrlForError(normalizedUrl),
             size,
             contentHash: contentHash.substring(0, 8),
             cacheSize: this.cache.size,
@@ -272,7 +275,7 @@ export class ImageCache {
             this.cache.delete(oldestKey);
             this.stats.evictions++;
             logger.debug("Image cache eviction", {
-                url: String(oldestKey).substring(0, 50),
+                url: redactUrlForError(String(oldestKey)),
             });
         }
     }

package/dist/lib/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
@@ -171,6 +172,15 @@ export declare const imageUtils: {
      * 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/lib/utils/imageProcessor.js

@@ -2,7 +2,9 @@
  * 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";
@@ -58,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
  */
@@ -77,6 +98,9 @@ export class ImageProcessor {
             throw new Error("Invalid image processing: buffer is empty");
         }
         const mediaType = this.detectImageType(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
@@ -327,20 +351,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 +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());
     }
@@ -495,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;
@@ -687,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
      */
@@ -706,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;
         }
     },
     /**
@@ -796,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/lib/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