The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* external-open.ts
*
* The single route every external URL open in the desktop app flows through.
* Electron-free: every side effect (shell.openExternal, spawn, the file
* opener, the failure channel) is injected, so the "open failed → notify"
* behavior is unit-tested without loading electron — the same shape as
* native-oauth-login.ts and connection-config.ts. main.ts wires the real deps.
*
* A URL is opened exactly once. An open failure is logged and reported
* through notifyFailure (the renderer shows a fallback modal with the URL);
* the caller reads the result to decide whether an open-failure must also
* abort its own flow (the native-OAuth path fails fast, link paths don't).
*/
import type { ChildProcess, SpawnOptions } from 'node:child_process'
import { externalUrlTarget } from '../../shared/src/external-url'
import { absolutizeProtocolRelativeUrl, looksLikeLocalFilesystemPath } from './local-filesystem-path'
export type ExternalOpenResult =
{ ok: true } | { ok: false; reason: 'invalid' } | { ok: false; reason: 'failed'; message: string }
export interface FileOpenGuardDeps {
log: (line: string) => void
reportMissing: (rawUrl: string, message: string) => void
}
/**
* Decide what a pre-open stat failure means for a file open (#122027). Lives
* here, not inline in main.ts, so the classification is unit-tested without
* loading electron — same injected-deps shape as the rest of the module.
*
* Returns true when the failure was a MISS: it has been reported through
* reportMissing and the caller must NOT hand the path to the OS (a reveal of
* a non-existent path is silently a no-op on macOS; an open of one reads as
* "No application found" on LaunchServices). Returns false for every other
* stat failure (EACCES on a locked volume, ELOOP, Windows EPERM): those are
* logged and the caller still proceeds to the OS, so an existing-but-locked
* file keeps its real error and a stat failure never fabricates a miss.
*/
export function reportPreOpenStatFailure(error: unknown, rawUrl: string, deps: FileOpenGuardDeps): boolean {
if (error && typeof error === 'object' && (error as { code?: string }).code === 'missing-file') {
deps.reportMissing(rawUrl, externalOpenErrorMessage(error))
return true
}
deps.log(`[file] pre-open stat failed: ${externalOpenErrorMessage(error)}`)
return false
}
export interface ExternalOpenDeps {
isWsl: boolean
spawn: (cmd: string, args: readonly string[], opts: SpawnOptions) => ChildProcess
openExternal: (url: string) => Promise<void>
openFile: (rawUrl: string) => Promise<void>
/**
* Open a BARE local filesystem path (POSIX `/…`, `~/…`, Windows drive/UNC)
* that is not a URL. The impl resolves it through the same audited
* `resolveRequestedPathForIpc` the `file:` route uses, then `shell.openPath`,
* with the same reveal-in-folder fallback and missing-file reporting as the
* file route. Resolves false when the path could not be resolved at all
* (rejected syntax, blocked device path) so the caller logs and reports it.
*/
openLocalPath: (rawPath: string) => Promise<boolean>
notifyFailure: (url: string, message: string) => void
log: (line: string) => void
}
export function externalOpenErrorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error)
}
/**
* Open a URL in the system browser. Resolves `invalid` for a URL the route
* does not open (empty, malformed, unsupported scheme). NEVER rejects: an open
* failure is logged + reported through notifyFailure and resolves `failed`,
* so fire-and-forget callers can `void` the result safely.
*/
export async function openExternalUrl(rawUrl: string, deps: ExternalOpenDeps): Promise<ExternalOpenResult> {
const raw = absolutizeProtocolRelativeUrl(String(rawUrl || '').trim())
if (!raw) {
return { ok: false, reason: 'invalid' }
}
// Bare local paths (POSIX `/…`, `~/…`, Windows drive/UNC) are not valid
// absolute URLs: `new URL()` either throws (POSIX, `~`, UNC) or mis-parses a
// drive letter as a bogus `c:` scheme, which the web allowlist below would
// reject as "Invalid external URL". Route them through the audited file
// resolver instead (hermes-agent 80946, 84361).
if (looksLikeLocalFilesystemPath(raw)) {
let opened: boolean
try {
opened = await deps.openLocalPath(raw)
} catch (error) {
return failOpen(deps, raw, error)
}
if (!opened) {
deps.log(`[file] openPath resolve rejected: path=${raw}`)
return { ok: false, reason: 'invalid' }
}
return { ok: true }
}
const target = externalUrlTarget(raw)
if (!target) {
return { ok: false, reason: 'invalid' }
}
if (target.kind === 'file') {
try {
await deps.openFile(target.url)
} catch {
// main's openFile handles its own fallback; never surfaced here
}
return { ok: true }
}
const { url } = target
if (deps.isWsl) {
return openViaWsl(url, deps)
}
try {
await deps.openExternal(url)
return { ok: true }
} catch (error) {
return failOpen(deps, url, error)
}
}
async function openViaWsl(url: string, deps: ExternalOpenDeps): Promise<ExternalOpenResult> {
deps.log(`[link] opening via WSL→Windows: ${url}`)
const proc = deps.spawn('cmd.exe', ['/c', 'start', '""', url], {
detached: true,
stdio: 'ignore',
windowsHide: true
})
// 'error' only fires when the process could not be spawned. In that case
// fall back to xdg-open; if that also fails, surface it. The handler runs
// asynchronously after this function has already resolved.
proc.on('error', error => {
deps.log(`[link] cmd.exe start failed: ${error.message}; falling back to xdg-open`)
deps.openExternal(url).catch(openError => {
failOpen(deps, url, openError)
})
})
try {
proc.unref()
} catch {
// unref can throw on an already-closed handle in some node versions
}
return { ok: true }
}
function failOpen(deps: ExternalOpenDeps, url: string, error: unknown): ExternalOpenResult {
const message = externalOpenErrorMessage(error)
deps.log(`[link] openExternal failed: ${message}`)
deps.notifyFailure(url, message)
return { ok: false, reason: 'failed', message }
}