Function realpathDeepestExisting

src/memdir/teamMemPaths.ts:109–171

* Resolve symlinks for the deepest existing ancestor of a path. * The target file may not exist yet (we may be about to create it), so we * walk up the directory tree until realpath() succeeds, then rejoin the * non-existing tail onto the resolved ancestor. * * SECURITY (PSR M22186): path.resol

(absolutePath: string)

 *
 */
async function realpathDeepestExisting(absolutePath: string): Promise<string> {
  const tail: string[] = []
  let current = absolutePath
  // Walk up until realpath succeeds. ENOENT means this segment doesn't exist
  // yet; pop it onto the tail and try the parent. ENOTDIR means a non-directory
  // component sits in the middle of the path; pop and retry so we can realpath
  // the ancestor to detect symlink escapes.
  // Loop terminates when we reach the filesystem root (dirname('/') === '/').
  for (
    let parent = dirname(current);
    current !== parent;
    parent = dirname(current)
  ) {
    try {
      const realCurrent = await realpath(current)
      // Rejoin the non-existing tail in reverse order (deepest popped first)
      return tail.length === 0
        ? realCurrent
        : join(realCurrent, ...tail.reverse())
    } catch (e: unknown) {
      const code = getErrnoCode(e)
      if (code === 'ENOENT') {
        // Could be truly non-existent (safe to walk up) OR a dangling symlink
        // whose target doesn't exist. Dangling symlinks are an attack vector:
        // writeFile would follow the link and create the target outside teamDir.
        // lstat distinguishes: it succeeds for dangling symlinks (the link entry
        // itself exists), fails with ENOENT for truly non-existent paths.
        try {
          const st = await lstat(current)
          if (st.isSymbolicLink()) {
            throw new PathTraversalError(
              `Dangling symlink detected (target does not exist): "${current}"`,
            )
          }
          // lstat succeeded but isn't a symlink — ENOENT from realpath was
          // caused by a dangling symlink in an ancestor. Walk up to find it.
        } catch (lstatErr: unknown) {
          if (lstatErr instanceof PathTraversalError) {
            throw lstatErr
          }
          // lstat also failed (truly non-existent or inaccessible) — safe to walk up.
        }
      } else if (code === 'ELOOP') {
        // Symlink loop — corrupted or malicious filesystem state.
        throw new PathTraversalError(
          `Symlink loop detected in path: "${current}"`,
        )
      } else if (code !== 'ENOTDIR' && code !== 'ENAMETOOLONG') {
        // EACCES, EIO, etc. — cannot verify containment. Fail closed by wrapping
        // as PathTraversalError so the caller can skip this entry gracefully
        // instead of aborting the entire batch.
        throw new PathTraversalError(
          `Cannot verify path containment (${code}): "${current}"`,
        )
      }
      tail.push(current.slice(parent.length + sep.length))
      current = parent
    }