fix(media): normalize cross-platform media paths

vincentkoc · vincentkoc · commit ca7349b585dc · 2026-05-14T12:43:15.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,10 @@ Docs: https://docs.openclaw.ai
 - Telegram/WhatsApp: keep Telegram same-chat replies ordered behind active no-delay turns without blocking WhatsApp follow-up message dispatch.
 - Codex migration: avoid duplicate cached plugin bundle warnings when app-server plugin inventory is available.
 - Agents: suppress aborted embedded assistant partials, reasoning text, reply directives, and stale prior replies before user-facing delivery while preserving clean timeout/error payloads. Fixes #48241. Thanks @BunsDev, @andyliu, and @yassinebkr.
+- Agents: allow dot-dot-prefixed filenames such as `..file.txt` inside workspace and sandbox path policy while still rejecting real parent traversal.
+- Native image input: detect Windows drive image paths in plain prompts so `C:\...\screenshot.png` references are not missed.
+- Media: normalize Windows-style filename hints before staging attachments, remote media, audio transcodes, and saved-media display names, so POSIX hosts do not preserve drive or directory text in generated filenames.
+- Media references: resolve first-level inbound media files whose IDs start with dots instead of treating names like `..photo.png` as parent traversal.
 - iOS/chat: resize PhotosPicker image attachments to capped JPEGs before staging and sending, stripping source metadata and keeping oversized camera photos under the chat upload budget. Fixes #68524. Thanks @BunsDev.
 - Control UI: keep shared form, config, and usage text-entry controls at 16px on touch-primary devices while preserving chat composer input sizing, so iOS Safari no longer auto-zooms focused fields. Fixes #64651; carries forward #64673. Thanks @NianJiuZst and @BunsDev.
 - Codex harness: classify native app-server token-refresh logout and relogin failures as authentication refresh errors, so users get re-authentication guidance instead of a raw runtime failure.
diff --git a/src/agents/path-policy.test.ts b/src/agents/path-policy.test.ts
@@ -36,3 +36,17 @@ describe("toRelativeWorkspacePath (windows semantics)", () => {
     }
   });
 });
+
+describe("toRelativeWorkspacePath", () => {
+  it("accepts dot-dot-prefixed filenames inside the workspace", () => {
+    expect(toRelativeWorkspacePath("/workspace/root", "/workspace/root/..file.txt")).toBe(
+      "..file.txt",
+    );
+  });
+
+  it("rejects parent directory traversal outside the workspace", () => {
+    expect(() => toRelativeWorkspacePath("/workspace/root", "/workspace/root/../file.txt")).toThrow(
+      "Path escapes workspace root",
+    );
+  });
+});
diff --git a/src/agents/path-policy.ts b/src/agents/path-policy.ts
@@ -36,7 +36,12 @@ function validateRelativePathWithinBoundary(params: {
       candidate: params.candidate,
     });
   }
-  if (params.relativePath.startsWith("..") || params.isAbsolutePath(params.relativePath)) {
+  if (
+    params.relativePath === ".." ||
+    params.relativePath.startsWith("../") ||
+    params.relativePath.startsWith("..\\") ||
+    params.isAbsolutePath(params.relativePath)
+  ) {
     throwPathEscapesBoundary({
       options: params.options,
       rootResolved: params.rootResolved,
diff --git a/src/agents/pi-embedded-runner/run/images.test.ts b/src/agents/pi-embedded-runner/run/images.test.ts
@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { describe, expect, it, vi } from "vitest";
 import { createHostSandboxFsBridge } from "../../test-helpers/host-sandbox-fs-bridge.js";
 import { createUnsafeMountedSandbox } from "../../test-helpers/unsafe-mounted-sandbox.js";
@@ -103,8 +104,10 @@ describe("detectImageReferences", () => {
     expect(detectImageReferences("[Image: source: /tmp/second.jpg]")).toStrictEqual([
       { raw: "/tmp/second.jpg", type: "path", resolved: "/tmp/second.jpg" },
     ]);
-    expect(detectImageReferences("See file:///tmp/third.webp")).toStrictEqual([
-      { raw: "file:///tmp/third.webp", type: "path", resolved: "/tmp/third.webp" },
+    const thirdPath = path.join(os.tmpdir(), "third.webp");
+    const thirdUrl = pathToFileURL(thirdPath).href;
+    expect(detectImageReferences(`See ${thirdUrl}`)).toStrictEqual([
+      { raw: thirdUrl, type: "path", resolved: thirdPath },
     ]);
     expect(detectImageReferences("See ./fourth.jpeg")).toStrictEqual([
       { raw: "./fourth.jpeg", type: "path", resolved: "./fourth.jpeg" },
@@ -192,6 +195,18 @@ describe("detectImageReferences", () => {
     });
   });
 
+  it("detects Windows drive image paths in plain prompts", () => {
+    const ref = expectSingleImageReference(
+      String.raw`Look at C:\Users\Ada\Pictures\screenshot.png`,
+    );
+
+    expect(ref).toStrictEqual({
+      raw: String.raw`C:\Users\Ada\Pictures\screenshot.png`,
+      type: "path",
+      resolved: String.raw`C:\Users\Ada\Pictures\screenshot.png`,
+    });
+  });
+
   it("detects [Image: source: ...] format from messaging systems", () => {
     const ref = expectSingleImageReference(`What does this image show?
 [Image: source: /Users/tyleryust/Library/Messages/Attachments/IMG_0043.jpeg]`);
diff --git a/src/agents/pi-embedded-runner/run/images.ts b/src/agents/pi-embedded-runner/run/images.ts
@@ -40,12 +40,15 @@ const MEDIA_ATTACHED_PATH_REGEX_SOURCE =
 const MESSAGE_IMAGE_REGEX_SOURCE =
   "\\[Image:\\s*source:\\s*([^\\]]+\\.(?:" + IMAGE_EXTENSION_PATTERN + "))\\]";
 const FILE_URL_REGEX_SOURCE = "file://[^\\s<>\"'`\\]]+\\.(?:" + IMAGE_EXTENSION_PATTERN + ")";
+const WINDOWS_DRIVE_PATH_REGEX_SOURCE =
+  "(?:^|\\s|[\"'`(])([A-Za-z]:[\\\\/][^\\s\"'`()\\[\\]]*\\.(?:" + IMAGE_EXTENSION_PATTERN + "))";
 const PATH_REGEX_SOURCE =
   "(?:^|\\s|[\"'`(])((\\.\\.?/|[~/])[^\\s\"'`()\\[\\]]*\\.(?:" + IMAGE_EXTENSION_PATTERN + "))";
 const MEDIA_ATTACHED_PATTERN = /\[media attached(?:\s+\d+\/\d+)?:\s*([^\]]+)\]/gi;
 const MEDIA_ATTACHED_PATH_PATTERN = new RegExp(MEDIA_ATTACHED_PATH_REGEX_SOURCE, "i");
 const MESSAGE_IMAGE_PATTERN = new RegExp(MESSAGE_IMAGE_REGEX_SOURCE, "gi");
 const FILE_URL_PATTERN = new RegExp(FILE_URL_REGEX_SOURCE, "gi");
+const WINDOWS_DRIVE_PATH_PATTERN = new RegExp(WINDOWS_DRIVE_PATH_REGEX_SOURCE, "gi");
 const PATH_PATTERN = new RegExp(PATH_REGEX_SOURCE, "gi");
 
 /**
@@ -265,6 +268,7 @@ export function detectImageReferences(prompt: string): DetectedImageRef[] {
   MEDIA_ATTACHED_PATTERN.lastIndex = 0;
   MESSAGE_IMAGE_PATTERN.lastIndex = 0;
   FILE_URL_PATTERN.lastIndex = 0;
+  WINDOWS_DRIVE_PATH_PATTERN.lastIndex = 0;
   PATH_PATTERN.lastIndex = 0;
   let match: RegExpExecArray | null;
   while ((match = MEDIA_ATTACHED_PATTERN.exec(prompt)) !== null) {
@@ -326,6 +330,13 @@ export function detectImageReferences(prompt: string): DetectedImageRef[] {
     }
   }
 
+  // Pattern for Windows drive paths.
+  while ((match = WINDOWS_DRIVE_PATH_PATTERN.exec(prompt)) !== null) {
+    if (match[1]) {
+      addPathRef(match[1]);
+    }
+  }
+
   // Pattern for file paths (absolute, relative, or home)
   // Matches:
   // - /absolute/path/to/file.ext (including paths with special chars like Messages/Attachments)
diff --git a/src/agents/sandbox-paths.test.ts b/src/agents/sandbox-paths.test.ts
@@ -167,6 +167,16 @@ describe("resolveSandboxedMediaSource", () => {
     });
   });
 
+  it("allows dot-dot-prefixed filenames inside the sandbox root", async () => {
+    await withSandboxRoot(async (sandboxDir) => {
+      const result = await resolveSandboxedMediaSource({
+        media: "./..image.png",
+        sandboxRoot: sandboxDir,
+      });
+      expect(result).toBe(path.join(sandboxDir, "..image.png"));
+    });
+  });
+
   it("maps container /workspace absolute paths into sandbox root", async () => {
     await withSandboxRoot(async (sandboxDir) => {
       const result = await resolveSandboxedMediaSource({
diff --git a/src/agents/sandbox-paths.ts b/src/agents/sandbox-paths.ts
@@ -68,7 +68,13 @@ export function resolveSandboxPath(params: { filePath: string; cwd: string; root
   if (!relative || relative === "") {
     return { resolved, relative: "" };
   }
-  if (relative.startsWith("..") || path.isAbsolute(relative) || isWindowsDrivePath(relative)) {
+  if (
+    relative === ".." ||
+    relative.startsWith("../") ||
+    relative.startsWith("..\\") ||
+    path.isAbsolute(relative) ||
+    isWindowsDrivePath(relative)
+  ) {
     throw new Error(`Path escapes sandbox root (${shortPath(rootResolved)}): ${params.filePath}`);
   }
   return { resolved, relative };
diff --git a/src/infra/outbound/message-action-params.test.ts b/src/infra/outbound/message-action-params.test.ts
@@ -375,6 +375,23 @@ describe("message action media helpers", () => {
     expect(fileArgs.filename).toBe("report.pdf");
   });
 
+  it("uses only the leaf filename from Windows-style attachment hints", async () => {
+    const args: Record<string, unknown> = {
+      fileUrl: String.raw`C:\Users\Ada\Downloads\report.pdf`,
+    };
+
+    await hydrateAttachmentParamsForAction({
+      cfg,
+      channel: "workspace",
+      args,
+      action: "sendAttachment",
+      dryRun: true,
+      mediaPolicy: { mode: "host" },
+    });
+
+    expect(args.filename).toBe("report.pdf");
+  });
+
   it("falls back to extension-based attachment names for remote-host file URLs", async () => {
     const args: Record<string, unknown> = {
       media: "file://attacker/share/photo.png",
diff --git a/src/infra/outbound/message-action-params.ts b/src/infra/outbound/message-action-params.ts
@@ -6,6 +6,7 @@ import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { root } from "../../infra/fs-safe.js";
 import { basenameFromMediaSource } from "../../infra/local-file-access.js";
 import { resolveChannelAccountMediaMaxMb } from "../../media/configured-max-bytes.js";
+import { basenameFromAnyPath } from "../../media/file-name.js";
 import {
   buildOutboundMediaLoadOptions,
   resolveOutboundMediaAccess,
@@ -131,8 +132,9 @@ function inferAttachmentFilename(params: {
   const mediaHint = params.mediaHint?.trim();
   if (mediaHint) {
     const base = basenameFromMediaSource(mediaHint);
-    if (base) {
-      return base;
+    const safeBase = base ? basenameFromAnyPath(base) : undefined;
+    if (safeBase) {
+      return safeBase;
     }
   }
   const ext = params.contentType ? extensionForMime(params.contentType) : undefined;
diff --git a/src/media/audio-transcode.test.ts b/src/media/audio-transcode.test.ts
@@ -133,4 +133,26 @@ describe("transcodeAudioBufferToOpus", () => {
     expect(capturedInputPath?.startsWith(tempRoot)).toBe(true);
     expect(capturedOutputPath ? existsSync(capturedOutputPath) : true).toBe(false);
   });
+
+  it("preserves Windows-style output filename leaves on POSIX hosts", async () => {
+    let capturedOutputPath: string | undefined;
+    runFfmpegMock.mockImplementationOnce(async (args: string[]) => {
+      capturedOutputPath = args.at(-1);
+      const outputPath = capturedOutputPath;
+      if (!outputPath) {
+        throw new Error("missing ffmpeg output path");
+      }
+      expect(path.basename(outputPath)).toContain("reply.opus");
+      await import("node:fs/promises").then((fs) =>
+        fs.writeFile(outputPath, Buffer.from("opus-output")),
+      );
+    });
+
+    await transcodeAudioBufferToOpus({
+      audioBuffer: Buffer.from("source"),
+      outputFileName: String.raw`C:\Users\Ada\Downloads\reply.opus`,
+    });
+
+    expect(capturedOutputPath ? existsSync(capturedOutputPath) : true).toBe(false);
+  });
 });
diff --git a/src/media/audio-transcode.ts b/src/media/audio-transcode.ts
@@ -3,6 +3,7 @@ import { writeExternalFileWithinRoot } from "../infra/fs-safe.js";
 import { withTempWorkspace } from "../infra/private-temp-workspace.js";
 import { resolvePreferredOpenClawTmpDir } from "../infra/tmp-openclaw-dir.js";
 import { runFfmpeg } from "./ffmpeg-exec.js";
+import { basenameFromAnyPath } from "./file-name.js";
 
 const DEFAULT_OPUS_SAMPLE_RATE_HZ = 48_000;
 const DEFAULT_OPUS_BITRATE = "64k";
@@ -33,7 +34,7 @@ function normalizeTempPrefix(value?: string): string {
 }
 
 function normalizeOutputFileName(value?: string): string {
-  const baseName = path.basename(value?.trim() || DEFAULT_OUTPUT_FILE_NAME);
+  const baseName = basenameFromAnyPath(value?.trim() || DEFAULT_OUTPUT_FILE_NAME);
   if (/^[a-zA-Z0-9._-]{1,80}$/.test(baseName) && baseName !== "." && baseName !== "..") {
     return baseName;
   }
diff --git a/src/media/fetch.test.ts b/src/media/fetch.test.ts
@@ -601,6 +601,47 @@ describe("readRemoteMediaBuffer", () => {
     await expect(fs.readFile(saved.path)).resolves.toStrictEqual(Buffer.from([1, 2, 3]));
   });
 
+  it("normalizes Windows-style response filenames and caller hints on POSIX hosts", async () => {
+    const fetchImpl = vi.fn(
+      async () =>
+        new Response(makeStream([new Uint8Array([1, 2, 3])]), {
+          status: 200,
+          headers: {
+            "content-disposition": String.raw`attachment; filename="C:\Users\Ada\Downloads\photo.png"`,
+            "content-type": "application/octet-stream",
+          },
+        }),
+    );
+
+    const savedFromHeader = await saveRemoteMedia({
+      url: "https://example.com/download",
+      fetchImpl,
+      lookupFn: makeLookupFn(),
+      maxBytes: 8,
+    });
+
+    expect(savedFromHeader.fileName).toBe("photo.png");
+
+    const savedFromHint = await saveRemoteMedia({
+      url: "https://example.com/download",
+      fetchImpl: vi.fn(
+        async () =>
+          new Response(makeStream([new Uint8Array([1, 2, 3])]), {
+            status: 200,
+            headers: { "content-type": "application/octet-stream" },
+          }),
+      ),
+      lookupFn: makeLookupFn(),
+      filePathHint: String.raw`C:\Users\Ada\Downloads\document.docx`,
+      maxBytes: 8,
+    });
+
+    expect(savedFromHint.fileName).toBe("document.docx");
+    expect(savedFromHint.contentType).toBe(
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+  });
+
   it("does not let filename hints force stored extensions before byte sniffing", async () => {
     const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0x00]);
     const fetchImpl = vi.fn(
diff --git a/src/media/fetch.ts b/src/media/fetch.ts
@@ -1,4 +1,3 @@
-import path from "node:path";
 import { formatErrorMessage } from "../infra/errors.js";
 import {
   fetchWithSsrFGuard,
@@ -10,6 +9,7 @@ import { retryAsync, type RetryOptions } from "../infra/retry.js";
 import { isAbortError, isTransientNetworkError } from "../infra/unhandled-rejections.js";
 import { redactSensitiveText } from "../logging/redact.js";
 import { MAX_DOCUMENT_BYTES } from "./constants.js";
+import { basenameFromAnyPath, extnameFromAnyPath } from "./file-name.js";
 import { detectMime, extensionForMime } from "./mime.js";
 import { readResponseTextSnippet, readResponseWithLimit } from "./read-response-with-limit.js";
 import { saveMediaBuffer, saveMediaStream, type SavedMedia } from "./store.js";
@@ -115,14 +115,14 @@ function parseContentDispositionFileName(header?: string | null): string | undef
     const cleaned = stripQuotes(starMatch[1].trim());
     const encoded = cleaned.split("''").slice(1).join("''") || cleaned;
     try {
-      return path.basename(decodeURIComponent(encoded));
+      return basenameFromAnyPath(decodeURIComponent(encoded));
     } catch {
-      return path.basename(encoded);
+      return basenameFromAnyPath(encoded);
     }
   }
   const match = /filename\s*=\s*([^;]+)/i.exec(header);
   if (match?.[1]) {
-    return path.basename(stripQuotes(match[1].trim()));
+    return basenameFromAnyPath(stripQuotes(match[1].trim()));
   }
   return undefined;
 }
@@ -291,7 +291,7 @@ function resolveRemoteFileName(params: {
   let fileNameFromUrl: string | undefined;
   try {
     const parsed = new URL(params.finalUrl);
-    const base = path.basename(parsed.pathname);
+    const base = basenameFromAnyPath(parsed.pathname);
     fileNameFromUrl = base || undefined;
   } catch {
     // ignore parse errors; leave undefined
@@ -301,7 +301,7 @@ function resolveRemoteFileName(params: {
   );
   return (
     headerFileName ||
-    (params.filePathHint ? path.basename(params.filePathHint) : undefined) ||
+    (params.filePathHint ? basenameFromAnyPath(params.filePathHint) : undefined) ||
     fileNameFromUrl
   );
 }
@@ -615,13 +615,13 @@ async function readRemoteMediaBufferOnce(options: FetchMediaOptions): Promise<Fe
     });
 
     const filePathForMime =
-      fileName && path.extname(fileName) ? fileName : (options.filePathHint ?? finalUrl);
+      fileName && extnameFromAnyPath(fileName) ? fileName : (options.filePathHint ?? finalUrl);
     const contentType = await detectMime({
       buffer,
       headerMime: res.headers.get("content-type"),
       filePath: filePathForMime,
     });
-    if (fileName && !path.extname(fileName) && contentType) {
+    if (fileName && !extnameFromAnyPath(fileName) && contentType) {
       const ext = extensionForMime(contentType);
       if (ext) {
         fileName = `${fileName}${ext}`;
diff --git a/src/media/file-name.ts b/src/media/file-name.ts
@@ -0,0 +1,15 @@
+import path from "node:path";
+
+export function basenameFromAnyPath(value: string): string {
+  return path.win32.basename(path.posix.basename(value));
+}
+
+export function extnameFromAnyPath(value: string): string {
+  return path.extname(basenameFromAnyPath(value));
+}
+
+export function nameFromAnyPath(value: string): string {
+  const base = basenameFromAnyPath(value);
+  const ext = path.extname(base);
+  return path.basename(base, ext);
+}
diff --git a/src/media/media-reference.test.ts b/src/media/media-reference.test.ts
diff --git a/src/media/media-reference.ts b/src/media/media-reference.ts
diff --git a/src/media/store.test.ts b/src/media/store.test.ts
diff --git a/src/media/store.ts b/src/media/store.ts
diff --git a/src/media/web-media.test.ts b/src/media/web-media.test.ts
diff --git a/src/media/web-media.ts b/src/media/web-media.ts
