UCD.js Docs

Path Utils

Architecture notes for @ucdjs/path-utils

@ucdjs/path-utils is the path safety layer that protects storage and HTTP file access.

Role

  • Normalizes path handling across Node, HTTP, and mixed platform environments.
  • Rejects traversal, illegal characters, unsupported UNC paths, and Windows-drive mismatches.
  • Provides the safety boundary reused by fs-backend, client, and store-serving code.

Public Package Docs

User-facing overview of safe path helpers and platform utilities.

FS Backend

Built-in backends rely on these checks before touching files or URLs.

Client

Client file requests use safe path resolution before network fetches.

Store App

The hosted store path shape mirrors the same safety assumptions.

Mental Model

There are two main responsibilities:

  • decode and normalize user-provided paths safely
  • prove that the resolved path still stays inside an allowed base

The core primitive is resolveSafePath(basePath, inputPath). Everything else supports that decision.

Method Flows

resolveSafePath(basePath, inputPath)

isWithinBase()UNC / illegal char guardsdecodePathSafely()resolveSafePath()isWithinBase()UNC / illegal char guardsdecodePathSafely()resolveSafePath()alt[escaped base][inside base]alt[absolute input already inside base][relative or outside-base input]alt[decode fails or max iterations exceeded][decoded path]CallerresolveSafePath(basePath, inputPath)reject empty base + UNC pathsdecode repeatedly until stableerrorFailedToDecodePathErrorreject control chars and null bytesnormalize absolute vs relative inputisWithinBase(base, input)truenormalized absolute pathjoin input to base and normalizeisWithinBase(base, resolved)falsePathTraversalErrortrueresolved pathCaller

decodePathSafely()

decodePathSafely()decodePathSafely()loop[until path stopschanging]alt[iterations exceeded][stabilized]CallerdecodePathSafely(encodedPath)decodeURIComponent()replace %2e, %2f, %5c variantsMaximumDecodingIterationsExceededErrordecoded pathCaller

isWithinBase()

isWithinBase()isWithinBase()CallerisWithinBase(base, resolved)trim + normalize inputsapply leading slashes where neededlower-case on case-insensitive platformscompare exact match or base + separator prefixbooleanCaller

Design Notes

  • URL decoding is iterative because traversal attempts may be double-encoded.
  • Windows behavior is treated explicitly, including drive handling and unsupported UNC paths.
  • isWithinBase() avoids partial prefix mistakes like /root matching /root2.
  • This package does lexical path safety only; the Node backend adds real-path symlink checks on top.

Testing Use

  • repeated encoded traversal attempts
  • Windows drive and case-sensitivity edge cases
  • UNC path rejection
  • control-character and null-byte rejection
  • absolute input that is already valid vs absolute input that escapes base

Lockfile

Architecture notes for @ucdjs/lockfile

UCD Store

Architecture notes for @ucdjs/ucd-store

On this page

RoleRelated DocsMental ModelMethod FlowsresolveSafePath(basePath, inputPath)decodePathSafely()isWithinBase()Design NotesTesting Use