sendFile(directory="/abs/path") cannot serve files outside the web root on Adobe CF, and hijacks any path containing "/wheels" on all engines

[bpamiri]

Summary

sendFile() documents (docblock + file-uploads guide line 198): "Directory outside of the web root where the file exists. Must be a full path." The path-resolution block in vendor/wheels/controller/miscellaneous.cfc (~lines 254-290) breaks that contract two ways, same root cause: it post-processes an already-absolute directory argument instead of using it verbatim.

Repro (guide-behavioral-audit harness, develop post-4.0.3)

Defect 1 — Adobe CF: absolute directory gets webroot-prefixed. When fullPath doesn't contain the web root, the #873 branch calls ExpandPath(local.fullPath). Lucee's ExpandPath() returns existing absolute paths unchanged, so it happens to work there; Adobe's always resolves against the web root.

// container: /tmp/dlprobe/secret.txt exists; FileExists() = true
sendFile(file="secret.txt", directory="/tmp/dlprobe");

• Lucee 7.0.1+100: 200, file served, Content-Disposition: attachment.
• Adobe 2023.0.11: Wheels.FileNotFound — looked in /wheels-test-suite/public/tmp/dlprobe (probe confirmed ExpandPath("/tmp/dlprobe") webroot-prefixes on Adobe). The documented serve-from-outside-the-webroot feature does not work at all on Adobe CF.

Defect 2 — all engines: /wheels substring hijack. Before the ExpandPath fallback, the resolver does findNoCase("/wheels", local.fullPath) to support the /wheels mapping — and substring-matches ANY directory containing /wheels:

sendFile(file="secret.txt", directory="/tmp/wheels-dl"); // Lucee 7
// → Wheels.FileNotFound: looked in /wheels-test-suite/public/wheels-dl

Real-world installs under /var/www/wheels/uploads or /srv/wheelsapp/files get their paths silently rewritten.

Root cause

vendor/wheels/controller/miscellaneous.cfc ~254-290: the #873 "DOES NOT CONTAIN root → ExpandPath" branch plus the findNoCase("/wheels", fullPath) substring match, both applied to caller-supplied absolute paths.

Proposed direction

When arguments.directory is supplied and is an absolute path (e.g. DirectoryExists() or starts with / / drive letter), build fullPath = directory & "/" & file and skip both the /wheels mapping rewrite and the ExpandPath() fallback. Keep existing behavior for relative filePath-based resolution. The existing ..-traversal guard runs before this block and still applies.

Acceptance

• sendFile(file=..., directory="/abs/outside/webroot") serves the file on Lucee AND Adobe.
• A directory containing /wheels as a substring is not rewritten.
• Specs cover both shapes; docs caution in file-uploads-and-downloads.mdx line 198 removed once fixed.

Reported by the guide-behavioral-audit P1 batch 2 (work item p1-8-uploads, claim C14; live on wheels-test-lucee7:v1.0.0 + wheels-test-adobe2023:v1.0.1).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior with a clear what-happened/what-expected: sendFile(file="secret.txt", directory="/tmp/dlprobe") throws Wheels.FileNotFound on Adobe CF (path webroot-prefixed) and any directory containing the /wheels substring (e.g. /tmp/wheels-dl) is silently rewritten on all engines — both contradicting the documented "Must be a full path … outside of the web root" contract.

Suspected layer

controller — see .ai/wheels/controllers/ for canonical patterns.

Fix sketch

The defect lives in the sendFile() path-resolution block in vendor/wheels/controller/miscellaneous.cfc (~lines 254-292). Two sites post-process an already-absolute caller-supplied directory: the local.fullPath CONTAINS "/wheels" substring branch (~line 271) and the ExpandPath(local.fullPath) fallback (~line 287). The fix shape, per the reporter proposed direction: when arguments.directory is supplied and absolute (e.g. DirectoryExists() / starts with / or a drive letter), build fullPath = directory & "/" & file verbatim and skip both the /wheels mapping rewrite and the ExpandPath() fallback, leaving the relative filePath-based path and the existing ..-traversal guard untouched. The doc caution at file-uploads-and-downloads.mdx line 198 can be removed once fixed.

Confidence: medium

The report is clear and points at the exact file/lines, but the fix sits on engine-divergent ExpandPath() behavior (Lucee returns absolute paths unchanged; Adobe resolves against the web root) — the cross-engine auto-downgrade rule caps this at medium, and the path-resolution change has security-adjacent traversal implications worth a careful spec.

<!-- wheels-bot:triage:3077 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3101

Spec: vendor/wheels/tests/specs/controller/miscellaneousSpec.cfc — two new sendFile specs (absolute-directory serve + /wheels-substring no-rewrite), failing → passing.
Implementation: vendor/wheels/controller/miscellaneous.cfc — absolute directory arguments are now used verbatim, skipping the /wheels mapping rewrite and the ExpandPath() web-root fallback.

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.