Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

16.1 KB
Raw Blame
"use client"

import React, { createContext, useContext, useMemo } from "react"

import { apiRequest } from "@/lib/api-wrapper"
import { getApiUrl } from "@/lib/utils"

export type FileAccessRequest = (
  url: string,
  options?: RequestInit,
) => Promise<Response>

export interface FileAccessPolicy {
  previewUrl: (fileId: string) => string
  downloadUrl: (fileId: string) => string
  inlinePreviewUrl: (fileId: string) => string
  inlineDownloadUrl: (fileId: string) => string
  relativePreviewUrl: (fileId: string, relativePath: string) => string
  pdfPreviewUrl?: (fileId: string) => string
  validationUrl?: (fileId: string) => string
  /**
   * Execute under this policy's credential boundary. The built-in default
   * attaches Bearer authorization. The public policy forces same-origin
   * credentials and attaches its guest token as a Bearer header, only for
   * the public file routes. Custom policies must define an equivalent
   * boundary. No policy puts a login or guest token in a URL.
   */
  request: FileAccessRequest
  listFiles?: (query: string) => Promise<Response>
  /**
   * Whether media elements must load managed files through an
   * authenticated fetch into a blob URL. True when previewUrl requires
   * headers a media element cannot send (both built-in policies); false
   * only when the URL is directly loadable as is. Policies that do not
   * declare the capability get the conservative blob path.
   */
  requiresBlobFetch?: boolean
  /**
   * Mint a short-lived, file-scoped ticket and return a URL a media
   * element can load directly, preserving HTTP range requests even under
   * a policy whose previewUrl otherwise requires an Authorization header.
   * When present, this takes priority over requiresBlobFetch; failure
   * (e.g. offline) falls back to that capability instead.
   */
  getStreamingUrl?: (fileId: string) => Promise<string>
  /**
   * Turn a URL from this policy's own builders into one the browser can load
   * without headers (for example an HTML preview's subresources), by adding a
   * short-lived, file-bound ticket. Absent when the builders' URLs already
   * load as is. Rejects for URLs this policy did not build.
   */
  authorizeBrowserUrl?: (url: string) => Promise<string>
}

const encodeFileId = (fileId: string) => encodeURIComponent(fileId)

const buildUrl = (path: string): string => `${getApiUrl()}${path}`

const STREAM_TICKET_MINT_TIMEOUT_MS = 10_000

// Single source of truth for the files router's mount prefix, shared between
// every URL builder below and the mint-response shape check -- otherwise the
// two could drift the way files.py's own prefix derivation was written to
// avoid on the server side.
const FILES_API_PREFIX = "/api/files"

// Exported so tests unrelated to streaming-ticket mechanics can spread this
// and override just `getStreamingUrl` (e.g. to undefined), rather than
// depending on an incidental mock-shape quirk (a mocked response missing
// `.json()`) to keep a ticket mint attempt from participating in the test.
export const defaultFileAccessPolicy: FileAccessPolicy = {
  previewUrl: (fileId) => buildUrl(`${FILES_API_PREFIX}/preview/${encodeFileId(fileId)}`),
  downloadUrl: (fileId) => buildUrl(`${FILES_API_PREFIX}/download/${encodeFileId(fileId)}`),
  inlinePreviewUrl: (fileId) =>
    buildUrl(`${FILES_API_PREFIX}/public/preview/${encodeFileId(fileId)}`),
  inlineDownloadUrl: (fileId) =>
    buildUrl(`${FILES_API_PREFIX}/public/download/${encodeFileId(fileId)}`),
  relativePreviewUrl: (fileId, relativePath) => {
    const url = new URL(
      buildUrl(`${FILES_API_PREFIX}/public/preview/${encodeFileId(fileId)}`),
      typeof window === "undefined" ? "http://localhost" : window.location.origin,
    )
    url.searchParams.set("relative_path", relativePath)
    return getApiUrl() ? url.toString() : `${url.pathname}${url.search}${url.hash}`
  },
  pdfPreviewUrl: (fileId) => buildUrl(`${FILES_API_PREFIX}/preview-pdf/${encodeFileId(fileId)}`),
  validationUrl: (fileId) => buildUrl(`${FILES_API_PREFIX}/preview/${encodeFileId(fileId)}?validation_only=true`),
  request: apiRequest,
  listFiles: (query) => {
    const params = new URLSearchParams({ page: "1", size: "20" })
    if (query.trim()) params.set("search", query.trim())
    return apiRequest(buildUrl(`${FILES_API_PREFIX}/list?${params.toString()}`))
  },
  // previewUrl needs the Bearer header apiRequest attaches; media elements
  // cannot send it, so they must go through the blob fetch unless a
  // streaming ticket is available (see getStreamingUrl below).
  requiresBlobFetch: true,
  getStreamingUrl: async (fileId) => {
    // A hung mint request would otherwise leave a media element stuck
    // loading indefinitely, with nothing to time it out -- the caller's own
    // unmount handling (isCancelled checks in useResolvedMediaUrl) ignores
    // a late response but doesn't abort the underlying request.
    const controller = new AbortController()
    const timeout = setTimeout(() => controller.abort(), STREAM_TICKET_MINT_TIMEOUT_MS)
    let response: Response
    try {
      response = await apiRequest(
        buildUrl(`${FILES_API_PREFIX}/stream-tickets/${encodeFileId(fileId)}`),
        { signal: controller.signal },
      )
    } finally {
      clearTimeout(timeout)
    }
    if (!response.ok) {
      throw new Error(`Failed to mint stream ticket: ${response.status}`)
    }
    // The mint endpoint's response shape is a server contract this client
    // doesn't otherwise validate; a malformed/unexpected payload must
    // surface as a caught rejection (so the caller falls back to the blob
    // path) rather than silently becoming a broken `undefined`-based URL.
    // Bound to this exact fileId, not just the generic preview prefix: a
    // prefix-only check would pass a path with extra segments after it
    // (e.g. a dot-segment escaping to a different route) as long as it
    // still started with "/api/files/preview/" -- exploitability is ~nil
    // today (this server is the sole minter, and the ticket's own file_id
    // claim is re-checked at redemption regardless of what path string got
    // us there), but there's no reason to accept a shape looser than what
    // this server actually returns. Decoded and compared, not re-encoded
    // and string-matched: the server encodes file_id with Python's
    // urllib.parse.quote(safe=""), which escapes a different character set
    // than encodeURIComponent does (e.g. "!*'()" round-trip unescaped
    // through encodeURIComponent but ARE escaped by quote) -- re-encoding
    // fileId here and comparing strings would reject a genuinely valid
    // response for any fileId containing one of those characters.
    // decodeURIComponent has no such mismatch: it decodes any valid
    // percent-encoded UTF-8 sequence regardless of which safe-set the
    // encoder chose, so it round-trips correctly against either encoder.
    const previewPrefix = `${FILES_API_PREFIX}/preview/`
    const data: unknown = await response.json()
    const path =
      data && typeof data === "object" ? (data as { path?: unknown }).path : undefined
    if (typeof path !== "string" || !path.startsWith(previewPrefix)) {
      throw new Error("Stream ticket response has an unexpected shape")
    }
    const encodedFileIdAndQuery = path.slice(previewPrefix.length)
    const encodedFileId = encodedFileIdAndQuery.split("?")[0]
    let decodedFileId: string
    try {
      decodedFileId = decodeURIComponent(encodedFileId)
    } catch {
      throw new Error("Stream ticket response has an unexpected shape")
    }
    if (decodedFileId !== fileId) {
      throw new Error("Stream ticket response has an unexpected shape")
    }
    return buildUrl(path)
  },
}

const FileAccessContext = createContext<FileAccessPolicy>(defaultFileAccessPolicy)

export function FileAccessProvider({
  children,
  policy,
}: {
  children: React.ReactNode
  policy?: FileAccessPolicy
}) {
  return (
    <FileAccessContext.Provider value={policy ?? defaultFileAccessPolicy}>
      {children}
    </FileAccessContext.Provider>
  )
}

export function useFileAccess(): FileAccessPolicy {
  return useContext(FileAccessContext)
}

const PUBLIC_FILES_PREFIX = `${FILES_API_PREFIX}/public/`
const PUBLIC_FILE_ROUTE = new RegExp(`^${FILES_API_PREFIX}/public/(?:preview|download)/([^/?#]+)$`)
const TICKET_SHAPE = /^[A-Za-z0-9._~-]{1,8192}$/
// Re-mint this long before the server-side expiry so a URL handed to the
// browser does not expire while its first request is still in flight.
// Clamped to half the ticket's lifetime (see mintTicket), so a deployment
// with a short XAGENT_FILE_STREAM_TICKET_TTL_SECONDS still caches a ticket
// for a while instead of treating every fresh one as already stale.
const TICKET_REFRESH_MARGIN_MS = 30_000

const resolveAgainstPage = (url: string): URL =>
  new URL(url, typeof window === "undefined" ? "http://localhost" : window.location.origin)

/** Whether a URL targets this API's public file routes (the only place the
 * guest token is ever sent). */
const isPublicFileRoute = (url: string): boolean => {
  try {
    const resolved = resolveAgainstPage(url)
    const apiOrigin = resolveAgainstPage(buildUrl("/")).origin
    return resolved.origin === apiOrigin && resolved.pathname.startsWith(PUBLIC_FILES_PREFIX)
  } catch {
    return false
  }
}

/**
 * The public widget/share provider owns this capability. Its access token is
 * captured by the provider instance, never read from browser storage, and is
 * only sent as an Authorization header to the public file routes. Loads that
 * cannot send headers (media streaming, HTML preview subresources) use a
 * short-lived ticket bound to one file, minted with that header; the guest
 * token itself never appears in a URL.
 */
export function createPublicFileAccessPolicy(accessToken: string): FileAccessPolicy {
  const inlinePreviewUrl = (fileId: string) =>
    buildUrl(`${FILES_API_PREFIX}/public/preview/${encodeFileId(fileId)}`)
  const inlineDownloadUrl = (fileId: string) =>
    buildUrl(`${FILES_API_PREFIX}/public/download/${encodeFileId(fileId)}`)

  const request: FileAccessRequest = (url, options = {}) => {
    const headers = new Headers(options.headers)
    headers.delete("Authorization")
    if (accessToken && isPublicFileRoute(url)) {
      headers.set("Authorization", `Bearer ${accessToken}`)
    }
    // Same-origin requests carry ambient cookies, including the edge's
    // selected_region routing cookie. Cookies are not an authorization input.
    // Task-bound files validate the guest token header (or a file ticket);
    // taskless and legacy paths use their file ID or path capability.
    return fetch(url, { ...options, headers, credentials: "same-origin" })
  }

  type TicketEntry = { ticket: string; refreshAt: number }
  // One cache per policy instance (so per guest token): pending and settled
  // mints by fileId. A failed or timed-out mint is evicted, so the next load
  // retries instead of re-throwing a cached rejection.
  const tickets = new Map<string, Promise<TicketEntry>>()
  // When each settled mint stops being reused, keyed by its cache promise.
  // Pending mints have no entry, so pruning never drops a per-file
  // single-flight promise.
  const settledRefreshAt = new WeakMap<Promise<TicketEntry>, number>()
  // Without this, a file that is never requested again would keep its stale
  // entry for the life of the policy, so the cache would grow with every
  // file visited.
  const pruneStaleTickets = () => {
    const now = Date.now()
    for (const [fileId, cached] of tickets) {
      const refreshAt = settledRefreshAt.get(cached)
      if (refreshAt !== undefined && refreshAt <= now) tickets.delete(fileId)
    }
  }

  const readTicket = async (fileId: string, signal: AbortSignal): Promise<TicketEntry> => {
    const response = await request(
      buildUrl(`${FILES_API_PREFIX}/public/tickets/${encodeFileId(fileId)}`),
      { method: "POST", signal },
    )
    if (!response.ok) {
      throw new Error(`Failed to mint file ticket: ${response.status}`)
    }
    const data: unknown = await response.json()
    const record = data && typeof data === "object" ? data as Record<string, unknown> : {}
    const ticket = record.ticket
    const expiresIn = record.expires_in
    if (typeof ticket !== "string" || !TICKET_SHAPE.test(ticket)
      || typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0) {
      throw new Error("File ticket response has an unexpected shape")
    }
    const lifetimeMs = expiresIn * 1000
    const marginMs = Math.min(TICKET_REFRESH_MARGIN_MS, lifetimeMs / 2)
    return { ticket, refreshAt: Date.now() + lifetimeMs - marginMs }
  }

  const fetchTicket = async (fileId: string): Promise<TicketEntry> => {
    // A hung mint would otherwise stall every media/HTML-preview load for
    // this file behind the cached pending promise. The deadline covers the
    // whole mint -- headers, body and validation -- not just the request:
    // aborting cancels a real fetch's body read too, and the race settles
    // even when the body stream ignores the signal.
    const controller = new AbortController()
    let timeout: ReturnType<typeof setTimeout> | undefined
    const deadline = new Promise<never>((_, reject) => {
      timeout = setTimeout(() => {
        reject(new Error("File ticket mint timed out"))
        controller.abort()
      }, STREAM_TICKET_MINT_TIMEOUT_MS)
    })
    try {
      return await Promise.race([readTicket(fileId, controller.signal), deadline])
    } finally {
      clearTimeout(timeout)
    }
  }

  const mintTicket = async (fileId: string): Promise<string> => {
    pruneStaleTickets()
    const cached = tickets.get(fileId)
    if (cached) {
      const entry = await cached.catch(() => null)
      if (entry && entry.refreshAt > Date.now()) return entry.ticket
      const current = tickets.get(fileId)
      if (current === cached) {
        tickets.delete(fileId)
      } else if (current) {
        // A concurrent caller already replaced this stale entry with its own
        // mint: share that one (without re-checking it) instead of minting
        // a second ticket.
        return (await current).ticket
      }
    }
    const pending = fetchTicket(fileId)
    tickets.set(fileId, pending)
    try {
      // A just-minted ticket is returned as is, never re-checked against
      // refreshAt: that check is only for reuse, so no TTL can make this loop.
      const entry = await pending
      settledRefreshAt.set(pending, entry.refreshAt)
      return entry.ticket
    } catch (error) {
      if (tickets.get(fileId) === pending) tickets.delete(fileId)
      throw error
    }
  }

  const authorizeBrowserUrl = async (url: string): Promise<string> => {
    const resolved = resolveAgainstPage(url)
    const match = isPublicFileRoute(url) ? PUBLIC_FILE_ROUTE.exec(resolved.pathname) : null
    if (!match) throw new Error("Not a public file URL")
    const ticket = await mintTicket(decodeURIComponent(match[1]))
    resolved.searchParams.set("ticket", ticket)
    return /^[A-Za-z][A-Za-z0-9+.-]*:/.test(url)
      ? resolved.toString()
      : `${resolved.pathname}${resolved.search}${resolved.hash}`
  }

  return {
    previewUrl: inlinePreviewUrl,
    downloadUrl: inlineDownloadUrl,
    inlinePreviewUrl,
    inlineDownloadUrl,
    validationUrl: (fileId) => `${inlinePreviewUrl(fileId)}?validation_only=true`,
    relativePreviewUrl: (fileId, relativePath) => {
      const url = resolveAgainstPage(inlinePreviewUrl(fileId))
      url.searchParams.set("relative_path", relativePath)
      return getApiUrl() ? url.toString() : `${url.pathname}${url.search}${url.hash}`
    },
    // Public file routes deliberately do not expose the authenticated PDF
    // conversion endpoint. PPTX falls back to the scoped public byte route.
    request,
    // previewUrl needs the guest Bearer header, which media elements cannot
    // send: they load through a blob fetch, or a file ticket when streaming.
    requiresBlobFetch: true,
    getStreamingUrl: (fileId) => authorizeBrowserUrl(inlinePreviewUrl(fileId)),
    authorizeBrowserUrl,
  }
}

/** Keep a stable policy instance when a caller derives it from a public token. */
export function usePublicFileAccessPolicy(accessToken: string): FileAccessPolicy {
  return useMemo(() => createPublicFileAccessPolicy(accessToken), [accessToken])
}