A string prefix check is a poor way to decide whether a file belongs beneath a directory. A sibling named public-old shares the prefix public, and a symlink inside public can point elsewhere. For an existing, trusted static directory tree, resolve filesystem paths first and compare their directory relationship.

This example is a containment inspection helper for a tree that does not change during inspection. It is not a race-safe file-serving security boundary. The program builds its entire fixture beneath the current directory, including the outside-root sibling, and removes it afterward.

Prerequisites

Use Linux with a maintained Node.js installation. The program was executed on Node.js 26.13.0 and uses only built-in modules. Save it as paths.mjs. The current directory must permit temporary directories and symlinks.

Complete example

import {mkdtemp, mkdir, writeFile, symlink, realpath, rm} from 'node:fs/promises';
import path from 'node:path';
import assert from 'node:assert/strict';

async function contained(root, name) {
  if (typeof name !== 'string' || path.isAbsolute(name)) throw new Error('relative path required');
  const base = await realpath(root);
  const target = await realpath(path.resolve(base, name));
  const relative = path.relative(base, target);
  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
    throw new Error('outside root');
  }
  return target;
}
const temp = await mkdtemp(path.join(process.cwd(), 'paths-'));
try {
  const root = path.join(temp, 'public');
  const sibling = path.join(temp, 'public-old');
  await mkdir(root); await mkdir(sibling);
  await writeFile(path.join(root, 'ok.txt'), 'public fixture');
  await writeFile(path.join(sibling, 'other.txt'), 'outside fixture');
  await symlink(sibling, path.join(root, 'shortcut'), 'dir');
  assert.equal(await contained(root, 'ok.txt'), path.join(root, 'ok.txt'));
  await assert.rejects(contained(root, '../public-old/other.txt'), /outside root/);
  await assert.rejects(contained(root, 'shortcut/other.txt'), /outside root/);
  await assert.rejects(contained(root, path.join(root, 'ok.txt')), /relative path/);
  await assert.rejects(contained(root, 'missing.txt'), {code: 'ENOENT'});
  console.log('inside accepted; sibling, symlink, absolute and missing paths rejected');
} finally {
  await rm(temp, {recursive: true, force: true});
}

Run and expected output

node paths.mjs
inside accepted; sibling, symlink, absolute and missing paths rejected

Understand the relationship check

Both the root and candidate are resolved through realpath. The relative path from the resolved root to an ordinary descendant stays within that root. A candidate outside it produces a parent traversal or, on relevant platforms, an absolute relationship that the helper rejects.

Check for the complete parent component rather than rejecting every string beginning with two dots. A legitimate child named ..notes is different from a parent traversal. Similarly, sibling directory names must be compared as path components rather than as text prefixes.

The symlink fixture demonstrates why lexical normalization alone is insufficient. Although shortcut appears inside the root, its resolved target is the sibling directory. The helper rejects the resulting target relationship.

Edge cases and troubleshooting

Realpath requires the candidate to exist. A missing path therefore raises ENOENT, which is asserted in the fixture. Designing a new-file creation policy requires different handling and must account for existing parent directories. The helper also accepts the root itself as contained; add a separate file-type policy if your caller requires a regular file.

A filesystem can change between checking a path and opening it. An attacker who controls directory entries may replace a symlink after this helper returns. Use an appropriate sandbox or descriptor-based operating-system design for hostile mutable trees; returning a checked pathname does not eliminate that race.

This program uses local filesystem paths, not URL paths. Do not add URL decoding casually or assume a web server’s normalization matches Node’s path rules. Windows drive, junction and UNC behavior was not executed here. If symlink creation fails, check filesystem permissions before interpreting it as a containment failure.

References and related tutorials

Consult the official Node.js filesystem documentation and path documentation. Continue with node.js tutorials.