@juspay/neurolink 9.94.3 → 9.94.5

package/dist/lib/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

package/dist/lib/utils/messageBuilder.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, statSync } from "fs";
+import { readFile as readFileAsync, stat as statAsync } from "fs/promises";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
@@ -6,8 +7,10 @@ import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { enforceAggregateFileBudget, FILE_READ_BUDGET_PERCENT, } from "../context/fileTokenBudget.js";
 import { SIZE_TIER_THRESHOLDS } from "../types/index.js";
 import { tracers, ATTR, withSpan } from "../telemetry/index.js";
+import { NeuroLinkError } from "./errorHandling.js";
 import { FileDetector } from "./fileDetector.js";
 import { getImageCache } from "./imageCache.js";
+import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
 import { PDFImageConverter, PDFProcessor } from "./pdfProcessor.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
@@ -1396,13 +1399,38 @@ function detectMimeTypeFromBuffer(buffer) {
 /**
  * Convert file path to raw base64 string.
  * Returns raw base64 (not a data: URI) to avoid SSRF validation in AI SDK v6.
+ * Uses async fs so a large/slow-filesystem image never blocks the event loop
+ * while the size guard (below) or the read itself is in flight.
  */
-function convertFilePathToBase64(filePath) {
-    if (!existsSync(filePath)) {
-        throw new Error(`Image file not found: ${filePath}`);
+async function convertFilePathToBase64(filePath) {
+    let stats;
+    try {
+        stats = await statAsync(filePath);
     }
-    const buffer = readFileSync(filePath);
-    return buffer.toString("base64");
+    catch (error) {
+        // Only ENOENT means "not found" — EACCES/ELOOP/etc. are real access or
+        // filesystem problems that must not be misreported as a missing file.
+        const code = error instanceof Error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT") {
+            throw new Error(`Image file not found: ${filePath}`, { cause: error });
+        }
+        throw new Error(`Cannot access image file ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!stats.isFile()) {
+        throw new Error(`Image path is not a file: ${filePath}`);
+    }
+    // #257: check the file size via stat BEFORE reading it into memory, so a
+    // huge image path never triggers an unbounded read + base64 allocation.
+    // Delegates to ImageProcessor's shared guard (no local reimplementation).
+    const context = `image file "${filePath}"`;
+    ImageProcessor.validateSize(stats.size, context);
+    const buffer = await readFileAsync(filePath);
+    // TOCTOU: the file can grow, or a symlink can be swapped, between the stat
+    // above and this read completing. Re-validate the bytes actually read
+    // (not just the pre-read stat) before the base64 allocation.
+    return ImageProcessor.safeBase64Convert(buffer, context);
 }
 /**
  * Process a single image input and convert to raw base64 format.
@@ -1413,7 +1441,7 @@ function convertFilePathToBase64(filePath) {
  * Passing raw base64 avoids this because `new URL(base64string)` throws and
  * the SDK treats the string as inline base64 data instead.
  */
-function processImageToBase64(image, index) {
+async function processImageToBase64(image, index) {
     let imageData;
     let mimeType = "image/jpeg"; // Default mime type
     if (typeof image === "string") {
@@ -1444,7 +1472,7 @@ function processImageToBase64(image, index) {
         else {
             // File path string - convert to raw base64
             try {
-                imageData = convertFilePathToBase64(image);
+                imageData = await convertFilePathToBase64(image);
                 mimeType = getMimeTypeFromExtension(image);
             }
             catch (error) {
@@ -1452,6 +1480,11 @@ function processImageToBase64(image, index) {
                     index,
                     filePath: image,
                 });
+                // 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;
+                }
                 throw new Error(`Failed to convert file path to base64: ${image}. ${error}`, { cause: error });
             }
         }
@@ -1462,6 +1495,9 @@ function processImageToBase64(image, index) {
         if (detectedMimeType) {
             mimeType = detectedMimeType;
         }
+        // #257: guard the buffer size before the unbounded base64 conversion.
+        // Delegates to ImageProcessor's shared guard (no local reimplementation).
+        ImageProcessor.validateBufferSize(image, `image input at index ${index}`);
         imageData = image.toString("base64");
     }
     return { imageData, mimeType };
@@ -1524,11 +1560,13 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
     const content = [
         { type: "text", text: enhancedText },
     ];
-    // Process all images (including downloaded URLs) for Vercel AI SDK
-    actualImages.forEach(({ data: image }, index) => {
+    // Process all images (including downloaded URLs) for Vercel AI SDK.
+    // Sequential for...of (not Promise.all) to preserve image ordering and
+    // keep the original forEach's one-at-a-time error semantics.
+    for (const [index, { data: image }] of actualImages.entries()) {
         try {
             // Use helper function to process image and reduce nesting depth
-            const { imageData, mimeType } = processImageToBase64(image, index);
+            const { imageData, mimeType } = await processImageToBase64(image, index);
             content.push({
                 type: "image",
                 image: imageData,
@@ -1542,7 +1580,7 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
             });
             throw error;
         }
-    });
+    }
     return content;
 }
 /**

package/dist/utils/errorHandling.d.ts

@@ -34,6 +34,7 @@ export declare const ERROR_CODES: {
     readonly IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
     readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
     readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
+    readonly INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
@@ -199,6 +200,14 @@ export declare class ErrorFactory {
      * Create an image too large error
      */
     static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
+    /**
+     * Create an invalid image size error (NaN/Infinity/negative byte length).
+     * Distinct from `imageTooLarge` — this rejects a malformed size value
+     * before it reaches the max-size comparison, since `NaN > maxSize` and
+     * `-1 > maxSize` both evaluate to `false` and would otherwise let a
+     * corrupted stat/header value silently skip the guard.
+     */
+    static invalidImageSize(size: number): NeuroLinkError;
     /**
      * Create an image too small error
      */

package/dist/utils/errorHandling.js

@@ -45,6 +45,7 @@ export const ERROR_CODES = {
     IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
     IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
     INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
+    INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
     // Rate limiter errors
@@ -570,6 +571,26 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * Create an invalid image size error (NaN/Infinity/negative byte length).
+     * Distinct from `imageTooLarge` — this rejects a malformed size value
+     * before it reaches the max-size comparison, since `NaN > maxSize` and
+     * `-1 > maxSize` both evaluate to `false` and would otherwise let a
+     * corrupted stat/header value silently skip the guard.
+     */
+    static invalidImageSize(size) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_SIZE,
+            message: `Invalid image size: ${size} (must be a finite, non-negative number)`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                size,
+            },
+        });
+    }
     /**
      * Create an image too small error
      */

package/dist/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/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)),
             });
         }
     }