@root/path

A secure-by-default path module (wrapper around node's path).

npm install --save @root/path

var Path = require("@root/path");

// throws error when path resolves to ../...
Path.join("foo", "../bar"); // throws error
Path.resolve("/foo", "/bar"); // throws error
Path.relative("/foo/bar", "/foo"); // throws error

// unsafe is an alias to require('path'), for convenience;
Path.unsafe.join("foo", "../bar"); // does NOT throw error

Use with Promises, if you prefer:
(not actually async, but makes error handling easier via .catch()):

var Path = require("@root/path").promises;

Path.join("foo", "../bar").catch(function (e) {
  // give empty string rather than throwing error
  return "";
});

await Path.unsafe.join("foo", "../bar");

Note: v1.x does not check fs.realpath to resolve symbolic links. You probably know if you're using symbolic links, so if you're using potentially dangerous symbolic links, you need to check fs.realpath yourself.

API

Same as the built-in path, but throws an error when a joined, resolved, or relative path is not a child of the root, base, or from path.

{
  "message": "'x' [may] resolve[s] to a different parent than 'y'",
  "code": "E_PARENT_PATH",
  "path": "x"
}

Path.join(root, child1, ...)

Throw an error if the new path is not a child of root:

// Good
Path.join("/foo", "/bar"); //=> /foo/bar
Path.join("/foo", "./bar"); //=> /foo/bar
Path.join("/foo", "bar"); //=> /foo/bar
Path.join("foo", "bar"); //=> foo/bar

// Bad
Path.join("../foo", "bar"); //X ../foo/bar
Path.join("foo", "../bar"); //X ./bar

Path.resolve(base, path1, ...)

Throw an error if the new path is is not a child of base:

// Good
Path.resolve("/foo", "./bar"); //=> /foo/bar
Path.resolve("/foo", "bar"); //=> /foo/bar
Path.resolve("foo", "bar"); //=> /Users/me/foo/bar
Path.resolve("../foo", "bar"); // /Users/foo/bar

// Bad
Path.resolve("/foo", "/bar"); //X /bar
Path.resolve("foo", "../bar"); //X /Users/me/bar

Path.relative(from, to)

Throw an error if to resolves outside of from (i.e. the path starts with ..):

// Good
Path.relative("/foo/bar", "/foo/bar/baz"); //=> bar
Path.relative("/foo", "/foo/bar/baz"); //=> bar/baz
Path.relative("foo", "foo/bar"); //=> bar

// Bad
Path.relative("foo", "bar"); //X ../bar
Path.relative("/foo", "bar"); //X ../Users/me/bar
Path.relative("/foo/bar", "/foo"); //X ..
Path.relative("../foo", "bar"); // //X ../me/bar

Extra

The rest of path's properties are provided for convenience, but their behavior is left unchanged.

See https://nodejs.org/api/path.html

• Path.basename(path[, ext])
• Path.delimiter
• Path.dirname(path)
• Path.extname(path)
• Path.format(pathObject)
• Path.isAbsolute(path)
• Path.join([...paths]) (see above)
• Path.normalize(path)
• Path.parse(path)
• Path.posix
• Path.relative(from, to) (see above)
• Path.resolve([...paths]) (see above)
• Path.sep
• Path.toNamespacedPath(path)
• Path.win32
• Path.unsafe = require('path');

The non-wrapped methods and properties are generated automatically, so this module will mirror the built-in path without being republished.