hermes-agent/apps/desktop/electron/gateway-file-download.ts
Jack Lau 022647f131 fix(desktop): give the gateway save dialog a file type to keep
Both gateway save dialogs opened with no filters. Electron passes filters to
the platform save dialog as its set of file types, so with none supplied the
Windows dialog has exactly one type, "All Files", and no default extension for
the shell to append. The resolved name reaching the dialog is correct and
carries its extension; the dialog is where it goes missing, and a .pptx then
lands as a typeless "File" that Explorer cannot open (#92480).

The image-save dialog in the same file already carries a filter for exactly
this reason, with a comment naming the same platform and the same symptom. The
gateway file path never got the same treatment.

saveDialogFilters offers the download's own type ahead of All Files, so the
dialog names the type and Windows has an extension to keep. All Files stays
last on every branch: a filter list without it turns a save dialog into a
rename requirement.

The extension is whitelisted rather than merely extracted, because the name it
comes from can be server-supplied through Content-Disposition. Anything failing
the test falls back to All Files, which is today's behaviour, so the guard can
only decline to improve a save, never break one.

Both call sites are fixed. A fix that reached only the streaming path would
leave the bug alive on any gateway old enough to 404 that route into the
data-url fallback.
2026-09-29 19:22:42 -05:00

522 lines
18 KiB
TypeScript

// Helpers for saving a gateway-hosted file to the local disk from the Electron
// main process. Extracted from main.ts so the streaming, data-URL decoding, and
// filename derivation are unit-testable without spinning up Electron.
//
// The token / OAuth transports delegate to the shared finalizer here. It
// waits for the save dialog before `pumpStreamToFile` streams the
// response into a sibling temp file with backpressure and renames it onto the
// user-selected destination only once the body has landed in full — so a large
// download never has to be buffered whole in the native process, and a failed
// one never touches a file that was already at the destination.
import crypto from 'node:crypto'
import fs from 'node:fs'
import path from 'node:path'
import { Readable } from 'node:stream'
// Minimal shape of the response objects we consume. Both Node's
// http.IncomingMessage and Electron net's IncomingMessage satisfy it.
export interface ReadableLike {
on(event: 'data', listener: (chunk: Buffer | Uint8Array | string) => void): unknown
on(event: 'end', listener: () => void): unknown
on(event: 'error', listener: (err: Error) => void): unknown
pause?: () => void
resume?: () => void
destroy?: (err?: Error) => void
}
export interface WriteStreamLike {
write(chunk: Buffer): boolean
end(cb: () => void): void
// fs.WriteStream's close() ends the stream and calls back only after the
// descriptor is released. end()'s callback fires on 'finish', while the fd can
// still be open — and Windows refuses to rename a file with an open handle.
close?(cb: (err?: Error | null) => void): void
destroy(err?: Error): void
on(event: 'error', listener: (err: Error) => void): unknown
// 'open' is the ownership signal: only after it fires did THIS pump create
// the temp file, and only then may cleanup unlink it.
once(event: 'close' | 'drain' | 'open', listener: () => void): unknown
}
export interface PumpDeps {
// Must open the temp path exclusively (`flags: 'wx'`): the pump relies on
// creating a brand-new file, never on truncating or following something that
// already sits at that name.
createWriteStream: (tempPath: string) => WriteStreamLike
rename: (fromPath: string, toPath: string) => Promise<unknown>
unlink: (tempPath: string) => Promise<unknown>
// Test seam: pick the temp path deterministically so a regression can seed
// it and prove a pre-open collision leaves the seeded file untouched.
tempPathFor?: (destPath: string) => string
}
// Production deps: exclusive create on the real filesystem. Shared by the
// streaming save and the data-URL fallback in main.ts, and exercised directly
// by the real-filesystem tests so the guarantees are proven against node:fs,
// not only against fakes.
export function fsPumpDeps(): PumpDeps {
return {
createWriteStream: tempPath => fs.createWriteStream(tempPath, { flags: 'wx' }),
rename: (fromPath, toPath) => fs.promises.rename(fromPath, toPath),
unlink: tempPath => fs.promises.unlink(tempPath)
}
}
// How long to wait for a destroyed write stream to emit 'close' before giving
// up and unlinking anyway. fs.WriteStream always emits it; the grace period only
// protects against a stream shape that never does.
const CLOSE_GRACE_MS = 2000
// Resolve once `ws` has released its descriptor. destroy() closes the fd
// asynchronously, and Windows rejects unlink/rename on a path whose handle is
// still open, so cleanup must not run until 'close' has fired.
function awaitClosed(ws: WriteStreamLike): Promise<void> {
return new Promise(resolve => {
const timer = setTimeout(resolve, CLOSE_GRACE_MS)
ws.once('close', () => {
clearTimeout(timer)
resolve()
})
})
}
export interface GatewayFileBackendDeps<T> {
ensureLegacy: (profile: null | string) => Promise<T>
ensureRegistry: (connectionId: string, profile: null | string) => Promise<T>
}
export interface GatewayFileBackendRoute<T> {
connection: T
connectionId: null | string
profile: null | string
}
export interface GatewayFileRequestPaths {
dataUrl: string
download: string
}
export function gatewayFileRequestPaths(
filePath: string,
scopePath: (requestPath: string) => string,
sessionId?: string
): GatewayFileRequestPaths {
const encodedPath = encodeURIComponent(filePath)
const session = sessionId === undefined ? '' : `&session_id=${encodeURIComponent(sessionId)}`
return {
dataUrl: scopePath(`/api/fs/read-data-url?path=${encodedPath}${session}`),
download: scopePath(`/api/fs/download?path=${encodedPath}${session}`)
}
}
/**
* Resolve the backend that owns a renderer-requested gateway file. Registered
* connections must never fall through to the legacy profile pool: that pool
* can point at another machine with another authentication credential.
*/
export async function resolveGatewayFileBackend<T>(
payload: { connectionId?: unknown; profile?: unknown },
deps: GatewayFileBackendDeps<T>
): Promise<GatewayFileBackendRoute<T>> {
const connectionId = String(payload.connectionId ?? '').trim() || null
const profile = String(payload.profile ?? '').trim() || null
const connection = connectionId ? await deps.ensureRegistry(connectionId, profile) : await deps.ensureLegacy(profile)
return { connection, connectionId, profile }
}
// Sibling temp name for an in-flight download. It lives in the destination's own
// directory so the final step is a same-volume rename (and stays inside whatever
// directory the save dialog approved). The name is short and fixed rather than
// derived from the destination's basename so a long user-chosen filename cannot
// push the temp name past the filesystem limit, and the random suffix keeps two
// concurrent saves into the same directory from sharing a temp file. The leading
// dot hides the in-flight file in Finder/ls while it exists.
export function downloadTempPath(destPath: string): string {
return path.join(path.dirname(destPath), `.hermes-download-${crypto.randomBytes(4).toString('hex')}.part`)
}
// Stream `res` to `destPath`, honoring backpressure. Bytes land in a sibling
// temp file first and are renamed onto `destPath` only after the whole body has
// been written and the descriptor released. The destination itself is never
// opened before that point, so a download that fails part-way leaves any file
// already at `destPath` exactly as it was — only the temp file is removed before
// the returned promise rejects. (Opening `destPath` directly truncated it on the
// spot and the error path then unlinked it, destroying a pre-existing file the
// user had chosen to overwrite; #96597.)
export function pumpStreamToFile(res: ReadableLike, destPath: string, deps: PumpDeps): Promise<void> {
return new Promise((resolve, reject) => {
const tempPath = (deps.tempPathFor ?? downloadTempPath)(destPath)
const ws = deps.createWriteStream(tempPath)
let failed = false
// Ownership gate. An exclusive open can fail BEFORE this pump has created
// anything at `tempPath` (EEXIST on a collision, EACCES, a missing parent);
// in that case the path belongs to someone else and cleanup must not touch
// it. fs.WriteStream emits 'open' exactly when the create succeeded.
let owned = false
ws.once('open', () => {
owned = true
})
// `.then(() => dep())` rather than `Promise.resolve(dep())` so a dep that
// throws synchronously still lands on the rejection path instead of escaping
// the stream callback it was invoked from.
const discardTemp = (): Promise<void> => {
if (!owned) {
return Promise.resolve()
}
return Promise.resolve()
.then(() => deps.unlink(tempPath))
.then(
() => {},
() => {} // best effort
)
}
const fail = (err: Error) => {
if (failed) {
return
}
failed = true
try {
res.destroy?.(err)
} catch {
// best effort — the socket may already be closed
}
// Register the 'close' listener BEFORE destroy(): on a stream that is
// already tearing down after its own 'error', 'close' can follow on the
// next tick.
const closed = awaitClosed(ws)
try {
ws.destroy()
} catch {
// best effort
}
closed.then(discardTemp).then(() => reject(err))
}
// Flush and release the temp file, then move it into place. A rename failure
// (destination locked, permissions) must not leave the temp file behind.
const finish = () => {
const onClosed = (err?: Error | null) => {
if (failed) {
return
}
if (err) {
fail(err)
return
}
Promise.resolve()
.then(() => deps.rename(tempPath, destPath))
.then(
() => {
// A failure that raced the rename has already taken the reject
// path; never report success on top of it.
if (!failed) {
resolve()
}
},
(renameErr: Error) => {
if (failed) {
return
}
failed = true
discardTemp().then(() => reject(renameErr))
}
)
}
if (typeof ws.close === 'function') {
ws.close(onClosed)
} else {
ws.end(() => onClosed())
}
}
ws.on('error', fail)
res.on('error', fail)
res.on('data', chunk => {
if (failed) {
return
}
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array)
const ok = ws.write(buffer)
// Backpressure: pause the source until the file stream drains so we never
// accumulate the whole payload in memory.
if (!ok && typeof res.pause === 'function') {
res.pause()
ws.once('drain', () => {
if (!failed) {
res.resume?.()
}
})
}
})
res.on('end', () => {
if (failed) {
return
}
finish()
})
})
}
// Write an in-memory body to `destPath` with the same failure-atomic contract as
// `pumpStreamToFile` (temp file, exclusive create, close, rename). Used by the
// data-URL compatibility fallback, which has the whole body up front; a plain
// `fs.promises.writeFile(destPath, buffer)` would truncate an existing file
// before the write completes and so could destroy it on a mid-write failure.
export function writeBufferToFile(buffer: Buffer, destPath: string, deps: PumpDeps): Promise<void> {
return pumpStreamToFile(Readable.from([buffer]), destPath, deps)
}
// Decode a `data:[<mime>][;base64],<payload>` URL into a Buffer. Used by the
// compatibility fallback that reads through the capped `/api/fs/read-data-url`
// route when the gateway predates `/api/fs/download`.
export function parseDataUrlToBuffer(dataUrl: string): Buffer {
const match = /^data:([^,]*),([\s\S]*)$/.exec(String(dataUrl || ''))
if (!match) {
throw new Error('Malformed data URL')
}
const meta = match[1] || ''
const payload = match[2] || ''
if (/;base64/i.test(meta)) {
return Buffer.from(payload, 'base64')
}
return Buffer.from(decodeURIComponent(payload), 'utf8')
}
// Extract a filename from a Content-Disposition header, preferring the RFC 5987
// `filename*` form. Returns '' when none is present. Always reduced to a
// basename so a malicious header can't redirect the save outside the picked dir.
export function filenameFromContentDisposition(value: unknown): string {
const text = String(value || '')
const encoded = text.match(/filename\*=(?:UTF-8'')?([^;]+)/i)?.[1]
const plain = text.match(/filename="?([^";]+)"?/i)?.[1]
const raw = encoded || plain || ''
if (!raw) {
return ''
}
try {
return path.basename(decodeURIComponent(raw.trim()))
} catch {
return path.basename(raw.trim())
}
}
export interface SaveDialogFilter {
name: string
extensions: string[]
}
const ALL_FILES: SaveDialogFilter = { name: 'All Files', extensions: ['*'] }
// Build the Electron save-dialog `filters` for a resolved download name.
//
// Not cosmetic. Electron hands `filters` to the platform save dialog as its set
// of file types, and on Windows the selected type is also what supplies the
// default extension. Omit it and the dialog has exactly one type, "All Files",
// with no default extension to append — so a name the shell chose to display
// without its extension is then SAVED without it, and a .pptx lands as a
// typeless "File" that Explorer cannot open (#92480). The image-save dialog
// already carries a filter for the same reason.
//
// The extension is whitelisted rather than merely extracted, because the name
// it comes from can be attacker-influenced: `filenameFromContentDisposition`
// reads a server-supplied header. A filter is a poor injection target, but an
// unbounded string from the network has no business reaching a native dialog,
// and anything failing the test still saves — under "All Files", exactly as
// it does today.
export function saveDialogFilters(filename: unknown): SaveDialogFilter[] {
const name = path.basename(String(filename || '').trim())
const ext = path.extname(name).replace(/^\./, '').toLowerCase()
if (!/^[a-z0-9]{1,16}$/.test(ext)) {
return [ALL_FILES]
}
return [{ name: `${ext.toUpperCase()} File`, extensions: [ext] }, ALL_FILES]
}
// Preserve file URIs: only the gateway knows its native drive/UNC semantics.
// Normalize a gateway file path that may arrive as a bare path or a file:// URL.
export function gatewayFilePath(rawPath: unknown): string {
return String(rawPath || '').trim()
}
export interface GatewayFileSaveContext {
fallbackName: string
suggested: string
}
export interface GatewaySaveDialogResult {
canceled: boolean
filePath?: string
}
export interface GatewayFileSaveResult {
canceled?: boolean
path?: string
saved: boolean
}
export interface GatewaySaveDialogOptions {
defaultPath: string
filters?: SaveDialogFilter[]
title: string
}
export interface GatewayFileSaveDeps {
showSaveDialog: (options: GatewaySaveDialogOptions) => Promise<GatewaySaveDialogResult>
pump?: PumpDeps
}
export interface GatewayDownloadResponse extends ReadableLike {
statusCode?: number
headers: { [name: string]: string | string[] | undefined }
}
/** Keep the body unread until the user selects a destination. */
export async function finalizeGatewayDownload(
response: GatewayDownloadResponse,
context: GatewayFileSaveContext,
abort: () => void,
deps: GatewayFileSaveDeps
): Promise<GatewayFileSaveResult> {
const statusCode: number = response.statusCode || 500
if (statusCode >= 400) {
const message: string = await readGatewayErrorText(response)
throw Object.assign(new Error(`${statusCode}: ${message}`), { statusCode })
}
// A socket can fail while the native dialog is open, before the pump listens.
let responseError: Error | null = null
response.on('error', (error: Error): void => {
responseError = error
})
const disposition: string | string[] | undefined =
response.headers['content-disposition'] || response.headers['Content-Disposition']
const filename: string = filenameFromContentDisposition(disposition) || context.suggested || context.fallbackName
try {
const result: GatewaySaveDialogResult = await deps.showSaveDialog({
defaultPath: filename,
filters: saveDialogFilters(filename),
title: 'Save File'
})
if (result.canceled || !result.filePath) {
abort()
return { canceled: true, saved: false }
}
if (responseError) {
throw responseError
}
await pumpStreamToFile(response, result.filePath, deps.pump ?? fsPumpDeps())
return { path: result.filePath, saved: true }
} catch (error) {
abort()
throw error
}
}
function readGatewayErrorText(response: ReadableLike): Promise<string> {
return new Promise((resolve: (message: string) => void): void => {
const chunks: Buffer[] = []
let total: number = 0
response.on('data', (chunk: Buffer | Uint8Array | string): void => {
if (total >= 500) {
return
}
// Normalize text and binary stream chunks before retaining the bounded error prefix.
const bytes: Uint8Array = chunk instanceof Uint8Array ? chunk : Buffer.from(chunk, 'utf8')
const buffer: Buffer = Buffer.from(bytes.subarray(0, 500 - total))
total += buffer.length
chunks.push(buffer)
})
const finish: () => void = (): void => {
resolve(Buffer.concat(chunks).toString('utf8'))
}
response.on('end', finish)
response.on('error', finish)
})
}
export interface GatewayFileDownloadDeps extends GatewayFileSaveDeps {
download: (requestPath: string, context: GatewayFileSaveContext) => Promise<GatewayFileSaveResult>
readDataUrl: (requestPath: string) => Promise<string>
}
/** Only a missing streaming endpoint permits the older, capped data-URL route. */
export async function saveGatewayDownload(
requestPaths: GatewayFileRequestPaths,
context: GatewayFileSaveContext,
deps: GatewayFileDownloadDeps
): Promise<GatewayFileSaveResult> {
try {
return await deps.download(requestPaths.download, context)
} catch (error) {
if (!isNotFoundError(error)) {
throw error
}
}
const buffer: Buffer = parseDataUrlToBuffer(await deps.readDataUrl(requestPaths.dataUrl))
const result: GatewaySaveDialogResult = await deps.showSaveDialog({
defaultPath: context.suggested || context.fallbackName,
filters: saveDialogFilters(context.suggested || context.fallbackName),
title: 'Save File'
})
if (result.canceled || !result.filePath) {
return { canceled: true, saved: false }
}
await writeBufferToFile(buffer, result.filePath, deps.pump ?? fsPumpDeps())
return { path: result.filePath, saved: true }
}
// True when an error thrown by a transport wrapper represents an HTTP 404, used
// to trigger the data-URL compatibility fallback (and nothing else).
export function isNotFoundError(error: unknown): boolean {
return Boolean(error) && (error as { statusCode?: number }).statusCode === 404
}