fix: enforce symlink-aware filesystem roots

Author: antfubot

packages/devframe/src/utils/serve-static.test.ts

@@ -1,9 +1,10 @@
 import type { AddressInfo } from 'node:net'
 import type { ServeStaticOptions } from './serve-static'
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from 'node:fs'
 import { createServer } from 'node:http'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import process from 'node:process'
 import { H3, toNodeHandler } from 'h3'
 import { afterEach, describe, expect, it } from 'vitest'
 import { mountStaticHandler, serveStaticHandler, serveStaticNodeMiddleware } from './serve-static'
@@ -216,6 +217,66 @@ describe('mountStaticHandler', () => {
   })
 })
 
+// Symlinks require privileges on Windows that hosted CI runners lack, so
+// gate the symlink-containment suite off that platform.
+describe.skipIf(process.platform === 'win32')('serveStaticHandler symlink containment', () => {
+  let fx: Fixture | undefined
+
+  afterEach(async () => {
+    await fx?.close()
+    fx = undefined
+  })
+
+  it('returns 404 for a file symlink escaping the served root', async () => {
+    const dir = makeTmp('devframe-serve-link-')
+    const outside = makeTmp('devframe-serve-outside-')
+    writeFileSync(join(outside, 'secret.txt'), 'top secret', 'utf-8')
+    symlinkSync(join(outside, 'secret.txt'), join(dir, 'leak.txt'))
+    writeFileSync(join(dir, 'ok.txt'), 'in root', 'utf-8')
+    fx = await startH3(dir, { single: false })
+
+    const leak = await fetch(`${fx.baseUrl}/leak.txt`)
+    expect(leak.status).toBe(404)
+    // Ordinary in-root files still serve.
+    const ok = await fetch(`${fx.baseUrl}/ok.txt`)
+    expect(ok.status).toBe(200)
+    expect(await ok.text()).toBe('in root')
+  })
+
+  it('returns 404 for a file reached through an escaping directory symlink', async () => {
+    const dir = makeTmp('devframe-serve-link-')
+    const outside = makeTmp('devframe-serve-outside-')
+    writeFileSync(join(outside, 'secret.txt'), 'top secret', 'utf-8')
+    symlinkSync(outside, join(dir, 'escape'))
+    fx = await startH3(dir, { single: false })
+
+    const res = await fetch(`${fx.baseUrl}/escape/secret.txt`)
+    expect(res.status).toBe(404)
+  })
+
+  it('serves a symlink whose canonical target stays inside the served root', async () => {
+    const dir = makeTmp('devframe-serve-link-')
+    writeFileSync(join(dir, 'real.txt'), 'contained', 'utf-8')
+    symlinkSync(join(dir, 'real.txt'), join(dir, 'alias.txt'))
+    fx = await startH3(dir, { single: false })
+
+    const res = await fetch(`${fx.baseUrl}/alias.txt`)
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('contained')
+  })
+
+  it('returns 404 through the Node middleware for an escaping symlink', async () => {
+    const dir = makeTmp('devframe-serve-link-')
+    const outside = makeTmp('devframe-serve-outside-')
+    writeFileSync(join(outside, 'secret.txt'), 'top secret', 'utf-8')
+    symlinkSync(join(outside, 'secret.txt'), join(dir, 'leak.txt'))
+    fx = await startMw(dir, { single: false })
+
+    const res = await fetch(`${fx.baseUrl}/leak.txt`)
+    expect(res.status).toBe(404)
+  })
+})
+
 describe('serveStaticNodeMiddleware', () => {
   let fx: Fixture | undefined
 

packages/devframe/src/utils/serve-static.ts

@@ -3,7 +3,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ReadableStream as NodeWebReadableStream } from 'node:stream/web'
 import type { RemoteAssetsErrorMessage, RemoteAssetsStore } from '../types/remote-assets'
 import { createReadStream } from 'node:fs'
-import { stat } from 'node:fs/promises'
+import { realpath, stat } from 'node:fs/promises'
 import { Readable } from 'node:stream'
 import { defineHandler, H3 } from 'h3'
 import { lookup } from 'mrmime'
@@ -31,11 +31,39 @@ interface ResolvedFile {
 
 const HTML_EXTENSIONS = ['.html', '.htm']
 
-async function statFile(abs: string): Promise<ResolvedFile | null> {
+/** `child === root` or a path nested beneath it, using pathe's `/` separator. */
+function isWithin(child: string, root: string): boolean {
+  return child === root || child.startsWith(root + sep)
+}
+
+/**
+ * The canonical (symlink-resolved) served root. Falls back to the lexical
+ * path when the directory does not exist yet so an empty deployment simply
+ * serves nothing rather than throwing.
+ */
+async function canonicalRoot(absDir: string): Promise<string> {
+  try {
+    return normalize(await realpath(absDir))
+  }
+  catch {
+    return absDir
+  }
+}
+
+/**
+ * Stat a candidate file and confirm its canonical target stays inside the
+ * canonical served root, so a symlink inside the root can only resolve to a
+ * file that is still within the root. A symlink escaping the root reads as a
+ * miss (`null`), not a leak.
+ */
+async function statFile(abs: string, realRoot: string): Promise<ResolvedFile | null> {
   try {
     const s = await stat(abs)
     if (!s.isFile())
       return null
+    const real = normalize(await realpath(abs))
+    if (!isWithin(real, realRoot))
+      return null
     return { abs, size: s.size, mtime: s.mtime }
   }
   catch {
@@ -45,6 +73,7 @@ async function statFile(abs: string): Promise<ResolvedFile | null> {
 
 async function resolveTarget(
   absDir: string,
+  realRoot: string,
   urlPath: string,
   indexNames: string[],
   single: boolean,
@@ -67,15 +96,15 @@ async function resolveTarget(
   if (abs !== absDir && !abs.startsWith(absDir + sep))
     return null
 
-  const direct = await statFile(abs)
+  const direct = await statFile(abs, realRoot)
   if (direct)
     return direct
 
   try {
     const s = await stat(abs)
     if (s.isDirectory()) {
       for (const name of indexNames) {
-        const candidate = await statFile(join(abs, name))
+        const candidate = await statFile(join(abs, name), realRoot)
         if (candidate)
           return candidate
       }
@@ -90,15 +119,15 @@ async function resolveTarget(
   // fallback so pretty-URL deployments resolve to the right page.
   if (!extname(cleaned)) {
     for (const ext of HTML_EXTENSIONS) {
-      const candidate = await statFile(abs + ext)
+      const candidate = await statFile(abs + ext, realRoot)
       if (candidate)
         return candidate
     }
   }
 
   const fallbackIndex = indexNames[0]
   if (single && fallbackIndex && !/\.[a-z0-9]+$/i.test(cleaned)) {
-    const indexFile = await statFile(join(absDir, fallbackIndex))
+    const indexFile = await statFile(join(absDir, fallbackIndex), realRoot)
     if (indexFile)
       return indexFile
   }
@@ -199,14 +228,18 @@ export function serveStaticHandler(
     return serveRemoteAssetsHandler(source)
   const absDir = resolve(source)
   const opts = normalizeOptions(options)
+  // Canonicalize the served root once and reuse it — the containment check
+  // compares every candidate's canonical path against this.
+  let realRootPromise: Promise<string> | undefined
+  const getRealRoot = (): Promise<string> => (realRootPromise ??= canonicalRoot(absDir))
   return defineHandler(async (event) => {
     const method = event.req.method
     if (method !== 'GET' && method !== 'HEAD') {
       event.res.status = 405
       event.res.headers.set('Allow', 'GET, HEAD')
       return ''
     }
-    const file = await resolveTarget(absDir, event.url.pathname, opts.indexNames, opts.single)
+    const file = await resolveTarget(absDir, await getRealRoot(), event.url.pathname, opts.indexNames, opts.single)
     if (!file) {
       event.res.status = 404
       return ''
@@ -250,6 +283,8 @@ export function serveStaticNodeMiddleware(
 ): (req: IncomingMessage, res: ServerResponse, next?: (err?: Error) => void) => void {
   const absDir = typeof source === 'string' ? resolve(source) : undefined
   const opts = normalizeOptions(options)
+  let realRootPromise: Promise<string> | undefined
+  const getRealRoot = (dir: string): Promise<string> => (realRootPromise ??= canonicalRoot(dir))
   return (req, res, next) => {
     void (async () => {
       const method = req.method
@@ -282,7 +317,7 @@ export function serveStaticNodeMiddleware(
         return
       }
 
-      const file = await resolveTarget(absDir, url, opts.indexNames, opts.single)
+      const file = await resolveTarget(absDir, await getRealRoot(absDir), url, opts.indexNames, opts.single)
       if (!file) {
         if (next) {
           next()

plans/README.md

@@ -12,7 +12,7 @@ Generated by the improve skill on 2026-09-01 at commit `2d978f84`. Execute in th
 | 004 | Contain remote asset materialization | P1 | S | - | TODO |
 | 005 | Block Data Inspector prototype-chain writes | P1 | S | - | TODO |
 | 006 | Validate request-derived authentication-link origins | P1 | M | - | TODO |
-| 007 | Reject pre-existing symlink escapes from filesystem roots | P2 | M | - | TODO |
+| 007 | Reject pre-existing symlink escapes from filesystem roots | P2 | M | - | DONE |
 
 Status values: TODO | IN PROGRESS | DONE | BLOCKED (with reason) | REJECTED (with rationale)
 

plugins/assets/src/node/context.ts

@@ -1,5 +1,5 @@
 import type { DevframeNodeContext, RpcStreamingChannel } from 'devframe'
-import { resolveAssetPath } from './paths'
+import { assertAssetMutationPath, resolveAssetPath, resolveAssetReadPath } from './paths'
 
 export interface AssetsConfig {
   /** Directory this devframe manages. */
@@ -19,8 +19,19 @@ export interface AssetsConfig {
 }
 
 export interface AssetsContext extends AssetsConfig {
-  /** Resolve a root-relative path to an absolute one, rejecting escapes. */
+  /** Resolve a root-relative path to an absolute one, rejecting lexical escapes. */
   resolvePath: (relativePath: string) => string
+  /**
+   * Resolve a path for a read, allowing an in-root symlink only when its
+   * canonical target stays inside the managed root.
+   */
+  resolveReadPath: (relativePath: string) => Promise<string>
+  /**
+   * Resolve a path for a mutation, rejecting every pre-existing symlink
+   * component. Call again after creating directories and right before the
+   * mutating I/O.
+   */
+  assertMutationPath: (relativePath: string) => Promise<string>
 }
 
 const configs = new WeakMap<DevframeNodeContext, AssetsConfig>()
@@ -54,6 +65,8 @@ export function getAssetsContext(ctx: DevframeNodeContext): AssetsContext {
     baseURL: config?.baseURL ?? '/',
     uploadChannel: config?.uploadChannel,
     resolvePath: (relativePath: string) => resolveAssetPath(dir, relativePath),
+    resolveReadPath: (relativePath: string) => resolveAssetReadPath(dir, relativePath),
+    assertMutationPath: (relativePath: string) => assertAssetMutationPath(dir, relativePath),
   }
   contexts.set(ctx, built)
   return built

plugins/assets/src/node/paths.ts

@@ -1,11 +1,17 @@
-import { resolve } from 'pathe'
+import fsp from 'node:fs/promises'
+import { dirname, normalize, resolve } from 'pathe'
 import { diagnostics } from '../diagnostics'
 
 /**
  * Resolve a client-supplied, root-relative path against the managed
  * directory, rejecting anything that would escape it (`..` traversal, a
- * rogue absolute path, etc.). Every RPC handler that touches the
- * filesystem goes through this — never trust a path from the wire.
+ * rogue absolute path, etc.). This is the lexical guard every RPC handler
+ * that touches the filesystem goes through first — never trust a path from
+ * the wire.
+ *
+ * Lexical checks alone cannot see symlinks: use {@link resolveAssetReadPath}
+ * (reads) or {@link assertAssetMutationPath} (mutations) to also close
+ * pre-existing symlink escapes.
  */
 export function resolveAssetPath(root: string, relativePath: string): string {
   const cleaned = relativePath.replace(/^[/\\]+/, '')
@@ -15,3 +21,94 @@ export function resolveAssetPath(root: string, relativePath: string): string {
     throw diagnostics.DP_ASSETS_0001({ path: relativePath })
   return absolute
 }
+
+/** `child === root` or a path nested beneath it, using pathe's `/` separator. */
+function isWithin(child: string, root: string): boolean {
+  return child === root || child.startsWith(`${root}/`)
+}
+
+/**
+ * The canonical (symlink-resolved) managed root. Falls back to the lexical
+ * path when the directory does not exist yet.
+ */
+async function canonicalRoot(root: string): Promise<string> {
+  const normalizedRoot = resolve(root)
+  try {
+    return normalize(await fsp.realpath(normalizedRoot))
+  }
+  catch {
+    return normalizedRoot
+  }
+}
+
+/**
+ * Canonical path of the nearest existing ancestor of `absolute` (the target
+ * itself when it exists), with every symlink along the way resolved.
+ */
+async function nearestExistingCanonical(absolute: string): Promise<string> {
+  let current = absolute
+  for (;;) {
+    try {
+      return normalize(await fsp.realpath(current))
+    }
+    catch {
+      const parent = dirname(current)
+      if (parent === current)
+        return current
+      current = parent
+    }
+  }
+}
+
+/**
+ * Resolve a path for a **read**, allowing a symlink only when its canonical
+ * target stays inside the canonical managed root. Lexical escapes and
+ * symlinks whose canonical target leaves the root both throw
+ * `DP_ASSETS_0001`.
+ */
+export async function resolveAssetReadPath(root: string, relativePath: string): Promise<string> {
+  const absolute = resolveAssetPath(root, relativePath)
+  const canonRoot = await canonicalRoot(root)
+  const nearest = await nearestExistingCanonical(absolute)
+  if (!isWithin(nearest, canonRoot))
+    throw diagnostics.DP_ASSETS_0001({ path: relativePath })
+  return absolute
+}
+
+/**
+ * Resolve a path for a **mutation**, rejecting every pre-existing symlink
+ * among the path components from the managed root down to the target —
+ * including in-root symlinks — so a mutation can never follow a symlink out
+ * of (or around) the root. Walks only components that already exist, so it
+ * is safe for not-yet-created upload/mkdir targets; call it again after
+ * creating directories and immediately before the mutating I/O to re-check
+ * the freshly materialized components.
+ *
+ * This closes deterministic, pre-existing symlink escapes; it does not
+ * defeat a concurrent local process swapping a component between this check
+ * and the I/O.
+ */
+export async function assertAssetMutationPath(root: string, relativePath: string): Promise<string> {
+  const absolute = resolveAssetPath(root, relativePath)
+  const canonRoot = await canonicalRoot(root)
+  const lexicalRoot = resolve(root)
+  const rel = absolute === lexicalRoot ? '' : absolute.slice(lexicalRoot.length + 1)
+  const segments = rel ? rel.split('/') : []
+
+  let current = canonRoot
+  for (const segment of segments) {
+    current = `${current}/${segment}`
+    let stat
+    try {
+      stat = await fsp.lstat(current)
+    }
+    catch {
+      // This component does not exist yet — nothing deeper can either, so
+      // there is no pre-existing symlink left to reject.
+      break
+    }
+    if (stat.isSymbolicLink())
+      throw diagnostics.DP_ASSETS_0001({ path: relativePath })
+  }
+  return absolute
+}

plugins/assets/src/node/scanner.ts

@@ -50,11 +50,17 @@ export function statToAssetInfo(dir: string, baseURL: string, relPath: string, s
 
 /** Recursively lists every file under `dir`, sorted alphabetically by path. */
 export async function scanAssets(dir: string, baseURL: string, includeFsPath = false): Promise<AssetInfo[]> {
-  const files = await glob(['**/*'], { cwd: dir, onlyFiles: true, dot: false })
+  // Never traverse into or across symlinks — a symlink inside the managed
+  // directory must not expose files (or whole trees) that live outside it.
+  const files = await glob(['**/*'], { cwd: dir, onlyFiles: true, dot: false, followSymbolicLinks: false })
 
   const infos = await Promise.all(files.map(async (relPath): Promise<AssetInfo | undefined> => {
     try {
       const stat = await fsp.lstat(join(dir, relPath))
+      // `lstat` describes the link itself; drop any symlink entry so the
+      // listing only ever names real files contained in the root.
+      if (stat.isSymbolicLink())
+        return undefined
       return statToAssetInfo(dir, baseURL, relPath, stat, includeFsPath)
     }
     catch {