Skip to content

The agent that grows with you

8.2 KB
Raw Blame
import { fileUrlToNativePath } from '../../shared/src/file-url'

import { httpStatusError, readStatusCode } from './api-transport'
import { requestWithOauthFallback } from './oauth-rest-request'

const STREAMABLE_MEDIA_EXTENSIONS = [
  '.avi',
  '.flac',
  '.m4a',
  '.mkv',
  '.mov',
  '.mp3',
  '.mp4',
  '.ogg',
  '.opus',
  '.wav',
  '.webm'
] as const

const FORWARDED_MEDIA_REQUEST_HEADERS = ['accept', 'if-modified-since', 'if-none-match', 'if-range', 'range'] as const

export const MEDIA_PROTOCOL = 'hermes-media'

type MediaProtocolMode = 'remote' | 'stream'

interface MediaProtocolTarget {
  connectionId?: string
  filePath: string
  mode: MediaProtocolMode
  profile?: string
}

export interface MediaRemoteScope {
  connectionId?: string
  profile?: string
}

export interface MediaRemoteConnection {
  authMode?: 'oauth' | 'token'
  baseUrl: string
  headers?: Record<string, string>
  mode?: 'local' | 'remote'
  token?: null | string
  sharedRemote?: boolean
}

type MediaRequestMethod = 'GET' | 'HEAD'

export interface MediaProtocolDependencies {
  ensureRemoteBearer: (baseUrl: string) => Promise<null | string>
  fetchLocal: (resolvedPath: string, headers: Headers, method: MediaRequestMethod) => Promise<Response>
  fetchRemote: (url: string, headers: Headers, method: MediaRequestMethod) => Promise<Response>
  fetchRemoteWithCookies: (url: string, headers: Headers, method: MediaRequestMethod) => Promise<Response>
  resolveLocalFile: (filePath: string) => Promise<string>
  resolveRemoteConnection: (scope: MediaRemoteScope) => Promise<MediaRemoteConnection>
}

function parseMediaProtocolTarget(rawUrl: string): MediaProtocolTarget {
  const url = new URL(rawUrl)
  const mode = url.hostname as MediaProtocolMode

  if (mode !== 'remote' && mode !== 'stream') {
    throw new Error('Unsupported media protocol target')
  }

  const filePath = decodeURIComponent(url.pathname.replace(/^\/+/, ''))

  if (!filePath) {
    throw new Error('Missing media path')
  }

  const connectionId = url.searchParams.get('connectionId')?.trim() || undefined
  const profile = url.searchParams.get('profile')?.trim() || undefined

  return { connectionId, filePath, mode, profile }
}

/**
 * The file name a native save of a `hermes-media://` URL should offer. The
 * media path rides percent-encoded in the URL, so Chromium's own guess flattens
 * the whole path into the name (`C__Users_me_Videos_clip.mp4`). Returns null
 * for any other URL so ordinary downloads keep Chromium's name.
 */
export function mediaProtocolDownloadName(rawUrl: string): null | string {
  let target: MediaProtocolTarget

  try {
    if (new URL(rawUrl).protocol !== `${MEDIA_PROTOCOL}:`) {
      return null
    }

    target = parseMediaProtocolTarget(rawUrl)
  } catch {
    return null
  }

  // Media paths come from the agent's OS: split on both separators.
  return target.filePath.split(/[\\/]/).filter(Boolean).pop() || null
}

/**
 * The native path a media `file:` URL names. Agents write these URLs by hand, and a name may hold a
 * `%` that starts no escape (`100%.mp4`), which the gateway reads as written. That `%` is escaped
 * before the shared parser reads the URL, so the name plays while an encoded separator (`%2f`,
 * `%5c`, or one encoded twice) is still refused.
 */
function mediaFileUrlPath(fileUrl: string): null | string {
  return fileUrlToNativePath(fileUrl.replace(/%(?![0-9a-f]{2})/gi, '%25'))
}

export function isStreamableMediaPath(filePath: string): boolean {
  const mediaPath = /^file:/i.test(filePath) ? mediaFileUrlPath(filePath) : filePath

  if (mediaPath === null) {
    return false
  }

  const lower = mediaPath.toLowerCase()

  return STREAMABLE_MEDIA_EXTENSIONS.some(extension => lower.endsWith(extension))
}

export function mediaRequestHeaders(source: Headers): Headers {
  const forwarded = new Headers()

  for (const name of FORWARDED_MEDIA_REQUEST_HEADERS) {
    const value = source.get(name)

    if (value) {
      forwarded.set(name, value)
    }
  }

  return forwarded
}

export function remoteMediaEndpoint(baseUrl: string, filePath: string, profile?: string): string {
  const normalizedBase = baseUrl.replace(/\/+$/, '')
  const url = new URL(`${normalizedBase}/api/files/stream`)

  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
    throw new Error(`Unsupported Hermes backend URL protocol: ${url.protocol}`)
  }

  if (/^file:/i.test(filePath)) {
    const nativePath = mediaFileUrlPath(filePath)

    if (nativePath === null) {
      throw new Error('Invalid media file URL')
    }

    // Older gateways accept native POSIX paths, not file URIs. Keep that
    // lossless contract, but leave drive letters and UNC hosts (a native path
    // not starting with `/`) to the gateway.
    if (nativePath.startsWith('/')) {
      filePath = nativePath
    }
  }

  url.searchParams.set('path', filePath)

  if (profile) {
    url.searchParams.set('profile', profile)
  }

  return url.toString()
}

export function createMediaProtocolHandler(dependencies: MediaProtocolDependencies) {
  return async (request: Pick<Request, 'headers' | 'method' | 'url'>): Promise<Response> => {
    if (request.method !== 'GET' && request.method !== 'HEAD') {
      return new Response('Method not allowed', {
        headers: { allow: 'GET, HEAD' },
        status: 405
      })
    }

    const method: MediaRequestMethod = request.method
    let target: MediaProtocolTarget

    try {
      target = parseMediaProtocolTarget(request.url)
    } catch {
      return new Response('Media not found', { status: 404 })
    }

    if (!isStreamableMediaPath(target.filePath)) {
      return new Response('Unsupported media type', { status: 415 })
    }

    const headers = mediaRequestHeaders(request.headers)

    if (target.mode === 'stream') {
      try {
        const resolvedPath = await dependencies.resolveLocalFile(target.filePath)

        if (!isStreamableMediaPath(resolvedPath)) {
          return new Response('Unsupported media type', { status: 415 })
        }

        return await dependencies.fetchLocal(resolvedPath, headers, method)
      } catch {
        return new Response('Media not found', { status: 404 })
      }
    }

    try {
      const connection = await dependencies.resolveRemoteConnection({
        connectionId: target.connectionId,
        profile: target.profile
      })

      if (connection.mode !== 'remote') {
        return new Response('Remote media backend unavailable', { status: 404 })
      }

      const endpoint = remoteMediaEndpoint(
        connection.baseUrl,
        target.filePath,
        connection.sharedRemote ? target.profile : undefined
      )

      // The gateway's configured extra headers (access-proxy gates) travel on
      // every remote request; forwarded range/cache negotiation headers win.
      for (const [name, value] of Object.entries(connection.headers ?? {})) {
        if (!headers.has(name)) {
          headers.set(name, value)
        }
      }

      if (connection.authMode === 'oauth') {
        return await requestWithOauthFallback(connection.baseUrl, {
          ensureNativeAccessToken: dependencies.ensureRemoteBearer,
          requestWithBearer: bearer => {
            headers.set('authorization', `Bearer ${bearer}`)

            return dependencies.fetchRemote(endpoint, headers, method)
          },
          requestWithCookie: async () => {
            const response = await dependencies.fetchRemoteWithCookies(endpoint, headers, method)

            // Fetch resolves HTTP errors; translate only the auth verdict so
            // the shared fallback can preserve a failed native refresh.
            if (response.status === 401 || response.status === 403) {
              await response.body?.cancel()
              throw httpStatusError(response.status, 'Remote media authentication unavailable')
            }

            return response
          }
        })
      }

      if (!connection.token) {
        return new Response('Remote media authentication unavailable', { status: 401 })
      }

      headers.set('x-hermes-session-token', connection.token)

      return await dependencies.fetchRemote(endpoint, headers, method)
    } catch (error) {
      const status = readStatusCode(error)

      return new Response('Remote media unavailable', { status: status === 401 || status === 403 ? status : 502 })
    }
  }
}