doc: clarify path.isAbsolute is not enough for mitigating path traversals

[ericfortis]

Since path.isAbsolute() it’s likely used for mitigating path traversals, I’m documentating that it doesn’t resolve paths.

I didn’t test its usages but for example it looks that it’s used for that here: https://github.com/nodejs/node/blob/47ae886e43537365ccc54beff0b1ac08a5a5aa19/lib/fs.js#L1803C3-L1815C4

[aduh95]

I don't really understand why you would call path.isAbsolute at all.

Suggested change

	The `path.isAbsolute()` method determines if the literal (non-resolved) `path` is an
	absolute path. Therefore, it’s likely that you want to run it through `path.normalize()`
	if your plan is to use it as a subpath in order to mitigate path traversals. For example:
	```js
	// Normalizing the subpath mitigates traversing above the mount directory.
	const mySubpath = path.normalize('/foo/../..');
	if (path.isAbsolute(mySubpath)) {
	const myPath = path.join(MOUNT_DIR, mySubpath)
	}
	The `path.isAbsolute()` method determines if `path` is an absolute path. Being an
	absolute path doesn't not guarentee it would be safe to treat as a subpath:
	```js
	const MOUNT_DIR = '/home/example/';
	const userProvidedPath = '/foo/../../../etc/passwd';
	console.log(path.isAbsolute(userProvidedPath)); // true
	console.log(path.join(MOUNT_DIR, userProvidedPath)); // /etc/passwd
	// Instead, call `path.normalize`:
	console.log(path.join(MOUNT_DIR, path.normalize(`/${userProvidedPath}`))); // /home/example/etc/passwd

[ericfortis]

Flow control, e.g.

const mySubpath = path.normalize('/foo/../..')
if (!path.isAbsolute(mySubpath))
  throw 'FORBIDDEN'
const myPath = path.join(MOUNT_DIR, mySubpath)

I agree it‘s not needed.

[ericfortis]

Perhaps, instead of documenting the behavior, a better approach could be adding path.isAbsoluteSubpath(). That way, when autocompleting, users can tell there's something not obvious about path.isAbsolute().

Something like,

function isAbsoluteSubpath(path) {
  const dpath = decodeURIComponent(path)
  if (!dpath.startsWith('/'))
    return false
  let nOutside = 0
  for (const part of dpath.split('/')) {
    if (part === '')
      continue
    if (part === '..')
      nOutside++
    else
      nOutside--
    if (nOutside > 0)
      return false
  }
  return true
}

function is(path, expected) {
  console.assert(expected === isAbsoluteSubpath(path), path)
}

;[
  '.',
  './',
  '..',
  '/..',
  '../',
  '/home//../../..',
  '/home/user/../../..'
].forEach(p => {
  is(p, false)
  is(encodeURIComponent(p), false)
})

;[
  '/',
  '/home/user/docs',
  '/home/user/./docs',
  '/home/user//docs'
].forEach(p => {
  is(p, true)
  is(encodeURIComponent(p), true)
})

[aduh95]

If the current behavior is confusing, let's update the doc to make them less confusing. Having clearer docs doesn't mean we can't add another API, that'd be a false dichotomy to think we can do one and not the other.

Would you like to take my suggestion so this PR can move forward?

[aduh95]

Landed in 97cbefa