Summary

• Problem: outbound media filename extracted from HTTP Content-Disposition and URL pathname can carry C0/C1 control, zero-width, and bidi override/isolate formatting characters through src/media/fetch.ts and src/media/web-media.ts to recipient client UI on Telegram / Discord / Matrix / WhatsApp document labels.
• Why it matters: this is defense-in-depth for display labels, not a MIME/content boundary bypass — the PR does not change file bytes, MIME inference, or channel delivery behavior.
• What changed: new helper src/media/outbound-filename.ts stripFilenameControlChars is applied at the 4 sites where filename strings cross the untrusted boundary (3 in fetch.ts, 1 in web-media.ts). Channel adapters in extensions/ are untouched.
• What did NOT change (scope boundary): operator-supplied filename paths (extensions/discord/src/send.shared.ts, extensions/whatsapp/src/inbound/send-api.ts); text body / caption / sender display name / reply quote / embed structured fields; encoding correctness (RFC 5987 charset/lang, mojibake recovery — covered by media: add shared filename decoder #71517).

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related media: add shared filename decoder #71517 (shared filename decoder; same call sites in parseContentDispositionFileName, scope is exclusive — encoding correctness vs character-class strip)
• Related Media: sanitize Content-Disposition filenames from remote fetches #27818 (closed by stale-bot 2026-04-17; same call site, narrower proposal — this PR adds zero-width / bidi formatting coverage)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: parseContentDispositionFileName (src/media/fetch.ts) applies path.basename + decodeURIComponent only; loadWebMediaInternal (src/media/web-media.ts) applies path.basename only. Neither path filters invisible / formatting characters before the value reaches the channel-side document UI label.
• Missing detection / guardrail: no character-class filter at the outbound-media boundary. Existing helpers (sanitizeFilename in src/media/store.ts for local path safety, sanitizeFileName in src/media/file-context.ts for LLM prompt attribute escape, sanitizeAttachmentFilename in src/media/server.ts for HTTP header escape) target other contexts and do not cover this one.
• Contributing context (if known): the 4 channel adapters share media.fileName from the same upstream extraction sites, so a per-channel fix would duplicate logic; the root sites are the natural single integration point.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/media/outbound-filename.test.ts (new, 27 cases) and src/media/fetch.test.ts (new Content-Disposition integration case).
• Scenario the test should lock in: each strip range is removed; preserved characters (U+200E, U+200F, U+202F) round-trip unchanged; the integration path through parseContentDispositionFileName returns a sanitized filename.
• Why this is the smallest reliable guardrail: the helper is a pure function over a closed character set; a unit test per strip range plus boundary preserve cases gives full coverage at low cost. One integration case anchors the fetch-time wiring.
• Existing test that already covers this (if any): none in src/media/.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Outbound media filenames forwarded to channel document UI labels no longer contain C0/C1 control, zero-width, or bidi override/isolate formatting characters. Other characters (including U+200E / U+200F bidi marks and U+202F narrow no-break space) round-trip unchanged. No defaults or config keys change.

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (Ubuntu 24.04)
• Runtime/container: Node 22, pnpm 10.33.0
• Model/provider: N/A (pure helper + fetch path)
• Integration/channel (if any): exercised through src/media/fetch.ts (HTTP Content-Disposition) and src/media/web-media.ts (URL pathname); 4 channel adapters consume the result unchanged.
• Relevant config (redacted): default.

Steps

1. pnpm install
2. pnpm test src/media/outbound-filename.test.ts src/media/fetch.test.ts src/media/web-media.test.ts
3. pnpm check:changed

Expected

• outbound-filename.test.ts: 27/27 pass.
• fetch.test.ts + web-media.test.ts: 42/42 pass (includes the new Content-Disposition integration case).
• check:changed: lanes core, coreTests GREEN (typecheck / lint / conflict-markers / runtime import cycles / pairing guards).

Actual

• outbound-filename.test.ts: 27 passed (114ms).
• fetch.test.ts + web-media.test.ts: 42 passed (843ms).
• check:changed: GREEN, lint 0 warnings 0 errors, 0 runtime cycles, all guards pass.

Evidence

• Failing test/log before + passing after
• Trace/log snippets

pnpm test src/media/outbound-filename.test.ts src/media/fetch.test.ts src/media/web-media.test.ts (worktree at 654cf20737, rebased onto f20a295782):

src/media/outbound-filename.test.ts          Test Files  1 passed (1)  Tests  27 passed (27)
src/media/fetch.test.ts + web-media.test.ts  Test Files  2 passed (2)  Tests  42 passed (42)

pnpm check:changed:

[check:changed] lanes=core, coreTests
[check:changed] typecheck core ... OK
[check:changed] typecheck core tests ... OK
[check:changed] lint core ... Found 0 warnings and 0 errors.
[check:changed] runtime import cycles ... 0 runtime value cycle(s).
[check:changed] webhook body guard ... OK
[check:changed] pairing store/account guards ... OK
EXIT 0

Unrelated full-suite note: a local full-suite precheck on both the rebased branch and the f20a295782 baseline hit one gateway-lane ERR_WORKER_OUT_OF_MEMORY under concurrent Vitest shards. The affected test passes in isolation and does not touch src/media/. Earlier unrelated Windows ACL / unit-fast failures were fixed upstream and are included in the current rebase.

Human Verification (required)

• Verified scenarios: helper unit tests across each strip range; integration through parseContentDispositionFileName; preserved characters (U+200E, U+200F, U+202F) round-trip unchanged; pnpm check:changed GREEN on 654cf20737 (rebased onto f20a295782).
• Edge cases checked: empty input, all-control input, mixed control + printable, characters straddling the strip boundaries (e.g. U+200E LRM kept, U+200B ZWSP stripped), filenames with multibyte characters preserved.
• What I did not verify: live channel send paths (Telegram / Discord / Matrix / WhatsApp); these consume media.fileName unchanged through extensions/ adapters that are untouched by this PR, so the change is transparent to them.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: false-strip of legitimate characters in filenames.
  • Mitigation: strip range is restricted to C0/C1 controls, zero-width characters, and bidi override/isolate formatting characters. A preserve test asserts that U+200E (LRM), U+200F (RLM), and U+202F (NARROW NO-BREAK SPACE) round-trip unchanged, locking in the boundary.
• Risk: overlap with media: add shared filename decoder #71517 (encoding correctness in the same parseContentDispositionFileName).
  • Mitigation: this PR operates on the post-decodeURIComponent value; both PRs touch the same function but functionally exclusive. Whichever lands second takes a small rebase.
• Risk: bidi-affecting directional marks such as LRM (U+200E), RLM (U+200F), and ALM (U+061C) remain in extracted filenames.
  • Mitigation: this is intentional. The PR strips bidi override (U+202A-U+202E) and isolate (U+2066-U+2069) controls, which are the stronger visual-reordering controls relevant to RTLO-style filename deception and Trojan-Source-style visual reordering. LRM/RLM/ALM are directional marks used legitimately in Arabic, Hebrew, and other RTL-script contexts to resolve weak-direction characters such as digits and punctuation in mixed-script filenames. Stripping them would create a concrete multilingual display regression at this filename extraction boundary to mitigate a more theoretical residual surface. If maintainers prefer a stricter policy for all bidi-affecting invisible characters, this strip set can be widened in a follow-up commit.

Real behavior proof

Behavior or issue addressed: With this PR at head 654cf20737, stripFilenameControlChars (src/media/outbound-filename.ts) is invoked at the four documented call sites in src/media/fetch.ts:73,75,80 (Content-Disposition filename* / filename branches) and src/media/web-media.ts:556 (URL pathname basename), removing C0/C1 controls (U+0000–U+001F, U+007F–U+009F), zero-width characters (U+200B–U+200D, U+FEFF), and bidi override + isolate formatting (U+202A–U+202E, U+2066–U+2069) from outbound filename strings before they are surfaced to recipient client UI or used as on-disk filenames. This is defense-in-depth for display labels — file bytes, MIME inference, and channel delivery are unchanged.

Real environment tested: Local Node v22.22.2 with the tsx loader (the same TS-on-Node mechanism the repository uses in its own scripts, e.g. node --import tsx scripts/check-import-cycles.ts). Worktree at HEAD 654cf20737 (this PR's head). The harness imports stripFilenameControlChars from src/media/outbound-filename.ts — the same exported function src/media/fetch.ts:11 and src/media/web-media.ts:31 import — and invokes it with the same stripFilenameControlChars(path.basename(input)) call shape that src/media/fetch.ts:80 uses, against adversarial input strings. The harness does not exercise the surrounding HTTP fetch, channel adapter, or runtime delivery code — only the helper itself, as imported.

Exact steps or command run after this patch:

git checkout 654cf20737
node --import tsx --input-type=module <<'PROOF'
import { stripFilenameControlChars } from "./src/media/outbound-filename.ts";
import path from "node:path";

const RLO  = String.fromCodePoint(0x202e);
const LRI  = String.fromCodePoint(0x2068);
const PDI  = String.fromCodePoint(0x2069);
const ZWSP = String.fromCodePoint(0x200b);
const BOM  = String.fromCodePoint(0xfeff);
const NEL  = String.fromCodePoint(0x0085);

const cases = [
  { name: "baseline ASCII (must passthrough unchanged)", input: "invoice.pdf" },
  { name: "RLO bidi override U+202E in basename",        input: "inv" + RLO + "oice.pdf" },
  { name: "CRLF header-injection vector (U+000D U+000A)", input: "inv\r\nX-Injected: yes\r\n.pdf" },
  { name: "ZWSP U+200B interspersed",                    input: "in" + ZWSP + "voice.pdf" },
  { name: "BOM U+FEFF prefix",                           input: BOM + "invoice.pdf" },
  { name: "C1 control NEL U+0085",                       input: "inv" + NEL + "oice.pdf" },
  { name: "LRI+PDI isolate U+2068 U+2069",               input: LRI + "inv" + PDI + "oice.pdf" },
];
const hex = (s) => Buffer.from(s, "utf8").toString("hex").match(/.{2}/g).join(" ");

console.log("// stripFilenameControlChars roundtrip -- PR 72973 head 654cf20737");
console.log("// helper source: src/media/outbound-filename.ts (exported, imported by fetch.ts:11 and web-media.ts:31)");
console.log("// the harness below applies the same stripFilenameControlChars(path.basename(input)) call shape that fetch.ts:80 uses, against adversarial input strings.");
console.log("// Node version: " + process.version);
console.log("");

let pass = 0;
let fail = 0;
for (const c of cases) {
  const after = stripFilenameControlChars(path.basename(c.input.trim()));
  const inHex = hex(c.input);
  const outHex = hex(after);
  const isBaseline = c.input === "invoice.pdf";
  const ok = isBaseline ? after === "invoice.pdf" : after !== c.input;
  if (ok) { pass += 1; } else { fail += 1; }
  console.log("[case] " + c.name);
  console.log("  in_chars  " + c.input.length + " utf16 / hex utf8: " + inHex);
  console.log("  out_chars " + after.length + " utf16 / hex utf8: " + outHex);
  console.log("  out_repr  " + JSON.stringify(after));
  console.log("  verdict   " + (ok ? "OK (no invisible chars remain)" : "FAIL"));
  console.log("");
}
console.log("// summary: " + pass + "/" + (pass + fail) + " passed");
PROOF

Evidence after fix: Verbatim stdout captured 2026-05-17 from running the command above against worktree HEAD 654cf20737:

// stripFilenameControlChars roundtrip -- PR 72973 head 654cf20737
// helper source: src/media/outbound-filename.ts (exported, imported by fetch.ts:11 and web-media.ts:31)
// the harness below applies the same stripFilenameControlChars(path.basename(input)) call shape that fetch.ts:80 uses, against adversarial input strings.
// Node version: v22.22.2

[case] baseline ASCII (must passthrough unchanged)
  in_chars  11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

[case] RLO bidi override U+202E in basename
  in_chars  12 utf16 / hex utf8: 69 6e 76 e2 80 ae 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

[case] CRLF header-injection vector (U+000D U+000A)
  in_chars  26 utf16 / hex utf8: 69 6e 76 0d 0a 58 2d 49 6e 6a 65 63 74 65 64 3a 20 79 65 73 0d 0a 2e 70 64 66
  out_chars 22 utf16 / hex utf8: 69 6e 76 58 2d 49 6e 6a 65 63 74 65 64 3a 20 79 65 73 2e 70 64 66
  out_repr  "invX-Injected: yes.pdf"
  verdict   OK (no invisible chars remain)

[case] ZWSP U+200B interspersed
  in_chars  12 utf16 / hex utf8: 69 6e e2 80 8b 76 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

[case] BOM U+FEFF prefix
  in_chars  12 utf16 / hex utf8: ef bb bf 69 6e 76 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

[case] C1 control NEL U+0085
  in_chars  12 utf16 / hex utf8: 69 6e 76 c2 85 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

[case] LRI+PDI isolate U+2068 U+2069
  in_chars  13 utf16 / hex utf8: e2 81 a8 69 6e 76 e2 81 a9 6f 69 63 65 2e 70 64 66
  out_chars 11 utf16 / hex utf8: 69 6e 76 6f 69 63 65 2e 70 64 66
  out_repr  "invoice.pdf"
  verdict   OK (no invisible chars remain)

// summary: 7/7 passed

No secrets, tokens, chat identifiers, or user identifiers are involved — the harness operates entirely on hand-constructed adversarial filename strings.

Observed result after fix: For every adversarial input above, the helper's return value contains no invisible/control bytes. Concretely from the hex dumps in the Evidence section: (1) the RLO byte sequence e2 80 ae is removed; (2) the CRLF bytes 0d 0a are removed in both occurrences from the helper's return value (the value its callers in src/media/fetch.ts and src/media/web-media.ts then propagate as media.fileName); (3) the ZWSP / BOM / NEL / LRI+PDI byte sequences are removed; (4) the baseline ASCII filename invoice.pdf is preserved byte-for-byte (11 → 11 bytes, identical hex). The 7/7 passed line in the captured output indicates every reported verdict is OK. This proof exercises only the helper function — it does not observe an HTTP request, a Content-Disposition header on the wire, a runtime delivery, or any channel adapter execution.

What was not tested:

• A full Telegram client → OpenClaw runtime → outbound Content-Disposition round-trip. Reason: it would require switching the local runtime symlink to this PR's worktree and a real-time Telegram client interaction, which would interrupt an unrelated active work item. The PR's extensions/ adapters consume media.fileName unchanged from the extraction sites this PR hardens, so the sanitized value reaches the adapter layer transparently. Happy to add a Telegram capture if a maintainer would like it as an additional artifact.
• LRM / RLM / ALM directional marks (U+200E, U+200F, U+061C). Intentional, per the §Risks discussion on multilingual filename display.
• Operator-supplied filename paths in extensions/discord/src/send.shared.ts and extensions/whatsapp/src/inbound/send-api.ts. Out of scope per §Scope boundary.