Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
5.5 KB
Raw Blame
/**
 * Path safety for wfc. All paths arriving from clients are validated against
 * a fixed mount root before any FS call. Mirrors the spec's "Path safety
 * (server-side, mandatory)" section.
 *
 *   1. Reject paths containing `..`, ASCII control characters, or backslash.
 *   2. Normalize via path.posix and resolve against the mount root; reject
 *      anything escaping the mount root.
 *   3. For filesystem sinks, resolve the existing physical path chain from the
 *      mount root and reject symlinked ancestors before kernel path resolution
 *      can leave the mounted tree.
 *   4. Enforce max depth.
 */
import type { Stats } from 'node:fs'
import * as fs from 'node:fs/promises'
import * as path from 'node:path'
import { err } from '../errors'

export interface ResolvePathOptions {
  /** Absolute mount root (e.g. /workspace). */
  mountRoot: string
  /** Max depth (segments) under the mount root. */
  maxDepth: number
}

export type PhysicalPathMode = 'existing-target' | 'existing-parent'

export interface PhysicalPathSafetyOptions extends ResolvePathOptions {
  /**
   * existing-target requires the full target to exist.
   * existing-parent permits a missing target or missing descendants after the
   * deepest safe existing directory, for create-style operations.
   */
  mode: PhysicalPathMode
}

export interface ResolvedPhysicalPath {
  absPath: string
}

const FORBIDDEN_CHARS = /[\\\x00-\x1f\x7f]/

/**
 * Validate + resolve a client-supplied relative path. Returns the absolute
 * on-disk path (still inside `mountRoot`). Throws an HttpError(400, path_invalid)
 * for any rule violation.
 *
 * Empty / "/" / "." map to the mount root itself (useful for listing root).
 */
export function resolveSafePath(rel: string, opts: ResolvePathOptions): string {
  if (typeof rel !== 'string') {
    throw err('path_invalid', 'path must be a string')
  }

  // Normalize the empty / leading-slash root cases up-front.
  const trimmed = rel.replace(/^\/+/, '')
  if (trimmed === '' || trimmed === '.') {
    return opts.mountRoot
  }

  if (FORBIDDEN_CHARS.test(rel)) {
    throw err('path_invalid', 'path contains forbidden characters (\\, ASCII controls)')
  }

  // Reject any segment that is exactly "..".
  const segments = trimmed.split('/').filter(s => s.length > 0)
  if (segments.some(s => s === '..')) {
    throw err('path_invalid', 'path traversal (..) is not allowed')
  }
  if (segments.length > opts.maxDepth) {
    throw err('path_invalid', `path depth exceeds maximum (${opts.maxDepth})`)
  }

  // Normalize and resolve under the mount root. path.posix is used so
  // backslashes are not interpreted as separators on any platform.
  const normalised = path.posix.normalize(segments.join('/'))
  const resolved = path.posix.resolve(opts.mountRoot, normalised)

  // Belt and suspenders: ensure resolved is within mountRoot.
  const rootWithSep = opts.mountRoot.endsWith('/') ? opts.mountRoot : `${opts.mountRoot}/`
  if (resolved !== opts.mountRoot && !resolved.startsWith(rootWithSep)) {
    throw err('path_invalid', 'path escapes mount root')
  }
  return resolved
}

export function isPhysicalSubpath(realPath: string, realRoot: string): boolean {
  const rootWithSep = realRoot.endsWith(path.sep) ? realRoot : `${realRoot}${path.sep}`
  return realPath === realRoot || realPath.startsWith(rootWithSep)
}

async function safeRealpath(candidate: string, realRoot: string): Promise<string> {
  const realCandidate = await fs.realpath(candidate)
  if (!isPhysicalSubpath(realCandidate, realRoot)) {
    throw err('path_invalid', 'path escapes mount root')
  }
  return realCandidate
}

/**
 * Validate lexical containment and the existing physical filesystem chain.
 *
 * This rejects symlinked ancestors centrally before route handlers call
 * readdir, stream, mkdir, rename, unlink, or rm on a client-derived path.
 */
export async function resolveSafePhysicalPath(
  rel: string,
  opts: PhysicalPathSafetyOptions
): Promise<ResolvedPhysicalPath> {
  const absPath = resolveSafePath(rel, opts)
  const realRoot = await fs.realpath(opts.mountRoot)
  const rootStat = await fs.lstat(opts.mountRoot)
  if (rootStat.isSymbolicLink()) {
    throw err('path_invalid', 'symlinks are not allowed')
  }
  const relative = path.posix.relative(opts.mountRoot, absPath)
  const segments = relative === '' ? [] : relative.split(path.posix.sep).filter(Boolean)
  let current = opts.mountRoot

  for (let i = 0; i < segments.length; i += 1) {
    current = path.posix.join(current, segments[i])
    let stat: Stats
    try {
      stat = await fs.lstat(current)
    } catch (e) {
      const fsErr = e as NodeJS.ErrnoException
      if (fsErr.code === 'ENOENT' && opts.mode === 'existing-parent') {
        return { absPath }
      }
      throw e
    }

    if (stat.isSymbolicLink()) {
      throw err('path_invalid', 'symlinks are not allowed')
    }

    // lstat rejects symlink nodes; realpath containment also catches unusual
    // mount/canonicalization cases before a route reaches an FS sink.
    await safeRealpath(current, realRoot)

    const isFinal = i === segments.length - 1
    if (!isFinal && !stat.isDirectory()) {
      throw err('not_a_directory', 'not a directory')
    }
  }

  return { absPath }
}

/** Express-friendly query parser: extracts `path` query param as a string. */
export function pathFromQuery(q: unknown): string {
  if (q === undefined || q === null) return ''
  if (typeof q === 'string') return q
  // Multiple values — reject; clients should send a single path query.
  throw err('path_invalid', 'path query must be a single string')
}