@rushstack/node-core-library - npm Package Compare versions

Comparing version 3.40.1 to 3.40.2

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "3.40.2",
+      "tag": "@rushstack/node-core-library_v3.40.2",
+      "date": "Tue, 14 Sep 2021 01:17:04 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Improve documentation to clarify usage for FileSystem APIs related to symbolic links"
+          }
+        ]
+      }
+    },
+    {
       "version": "3.40.1",
@@ -7,0 +19,0 @@ "tag": "@rushstack/node-core-library_v3.40.1",

CHANGELOG.md

 # Change Log - @rushstack/node-core-library
 
-This log was last generated on Mon, 13 Sep 2021 15:07:05 GMT and should not be manually modified.
+This log was last generated on Tue, 14 Sep 2021 01:17:04 GMT and should not be manually modified.
 
+## 3.40.2
+Tue, 14 Sep 2021 01:17:04 GMT
+
+### Patches
+
+- Improve documentation to clarify usage for FileSystem APIs related to symbolic links
+
 ## 3.40.1
@@ -6,0 +13,0 @@ Mon, 13 Sep 2021 15:07:05 GMT

lib/FileSystem.d.ts

@@ -517,4 +517,17 @@ /// <reference types="node" />
     /**
-     * Creates a Windows "directory junction". Behaves like `createSymbolicLinkToFile()` on other platforms.
+     * Creates an NTFS "directory junction" on Windows operating systems; for other operating systems, it
+     * creates a regular symbolic link.  The link target must be a folder, not a file.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * For security reasons, Windows operating systems by default require administrator elevation to create
+     * symbolic links.  As a result, on Windows it's generally recommended for Node.js tools to use hard links
+     * (for files) or NTFS directory junctions (for folders), since regular users are allowed to create them.
+     * Hard links and junctions are less vulnerable to symlink attacks because they cannot reference a network share,
+     * and their target must exist at the time of link creation.  Non-Windows operating systems generally don't
+     * restrict symlink creation, and as such are more vulnerable to symlink attacks.  Note that Windows can be
+     * configured to permit regular users to create symlinks, for example by enabling Windows 10 "developer mode."
+     *
+     * A directory junction requires the link source and target to both be located on local disk volumes;
+     * if not, use a symbolic link instead.
      */
@@ -527,4 +540,13 @@ static createSymbolicLinkJunction(options: IFileSystemCreateLinkOptions): void;
     /**
-     * Creates a symbolic link to a file (on Windows this requires elevated permissionsBits).
+     * Creates a symbolic link to a file.  On Windows operating systems, this may require administrator elevation.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * To avoid administrator elevation on Windows, use {@link FileSystem.createHardLink} instead.
+     *
+     * On Windows operating systems, the NTFS file system distinguishes file symlinks versus directory symlinks:
+     * If the target is not the correct type, the symlink will be created successfully, but will fail to resolve.
+     * Other operating systems do not make this distinction, in which case {@link FileSystem.createSymbolicLinkFile}
+     * and {@link FileSystem.createSymbolicLinkFolder} can be used interchangeably, but doing so will make your
+     * tool incompatible with Windows.
      */
@@ -537,4 +559,13 @@ static createSymbolicLinkFile(options: IFileSystemCreateLinkOptions): void;
     /**
-     * Creates a symbolic link to a folder (on Windows this requires elevated permissionsBits).
+     * Creates a symbolic link to a folder.  On Windows operating systems, this may require administrator elevation.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * To avoid administrator elevation on Windows, use {@link FileSystem.createSymbolicLinkJunction} instead.
+     *
+     * On Windows operating systems, the NTFS file system distinguishes file symlinks versus directory symlinks:
+     * If the target is not the correct type, the symlink will be created successfully, but will fail to resolve.
+     * Other operating systems do not make this distinction, in which case {@link FileSystem.createSymbolicLinkFile}
+     * and {@link FileSystem.createSymbolicLinkFolder} can be used interchangeably, but doing so will make your
+     * tool incompatible with Windows.
      */
@@ -547,4 +578,16 @@ static createSymbolicLinkFolder(options: IFileSystemCreateLinkOptions): void;
     /**
-     * Creates a hard link.
+     * Creates a hard link.  The link target must be a file, not a folder.
      * Behind the scenes it uses `fs.linkSync()`.
+     *
+     * @remarks
+     * For security reasons, Windows operating systems by default require administrator elevation to create
+     * symbolic links.  As a result, on Windows it's generally recommended for Node.js tools to use hard links
+     * (for files) or NTFS directory junctions (for folders), since regular users are allowed to create them.
+     * Hard links and junctions are less vulnerable to symlink attacks because they cannot reference a network share,
+     * and their target must exist at the time of link creation.  Non-Windows operating systems generally don't
+     * restrict symlink creation, and as such are more vulnerable to symlink attacks.  Note that Windows can be
+     * configured to permit regular users to create symlinks, for example by enabling Windows 10 "developer mode."
+     *
+     * A hard link requires the link source and target to both be located on same disk volume;
+     * if not, use a symbolic link instead.
      */
@@ -551,0 +594,0 @@ static createHardLink(options: IFileSystemCreateLinkOptions): void;

lib/FileSystem.js

@@ -677,4 +677,17 @@ "use strict";
     /**
-     * Creates a Windows "directory junction". Behaves like `createSymbolicLinkToFile()` on other platforms.
+     * Creates an NTFS "directory junction" on Windows operating systems; for other operating systems, it
+     * creates a regular symbolic link.  The link target must be a folder, not a file.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * For security reasons, Windows operating systems by default require administrator elevation to create
+     * symbolic links.  As a result, on Windows it's generally recommended for Node.js tools to use hard links
+     * (for files) or NTFS directory junctions (for folders), since regular users are allowed to create them.
+     * Hard links and junctions are less vulnerable to symlink attacks because they cannot reference a network share,
+     * and their target must exist at the time of link creation.  Non-Windows operating systems generally don't
+     * restrict symlink creation, and as such are more vulnerable to symlink attacks.  Note that Windows can be
+     * configured to permit regular users to create symlinks, for example by enabling Windows 10 "developer mode."
+     *
+     * A directory junction requires the link source and target to both be located on local disk volumes;
+     * if not, use a symbolic link instead.
      */
@@ -701,4 +714,13 @@ static createSymbolicLinkJunction(options) {
     /**
-     * Creates a symbolic link to a file (on Windows this requires elevated permissionsBits).
+     * Creates a symbolic link to a file.  On Windows operating systems, this may require administrator elevation.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * To avoid administrator elevation on Windows, use {@link FileSystem.createHardLink} instead.
+     *
+     * On Windows operating systems, the NTFS file system distinguishes file symlinks versus directory symlinks:
+     * If the target is not the correct type, the symlink will be created successfully, but will fail to resolve.
+     * Other operating systems do not make this distinction, in which case {@link FileSystem.createSymbolicLinkFile}
+     * and {@link FileSystem.createSymbolicLinkFolder} can be used interchangeably, but doing so will make your
+     * tool incompatible with Windows.
      */
@@ -723,4 +745,13 @@ static createSymbolicLinkFile(options) {
     /**
-     * Creates a symbolic link to a folder (on Windows this requires elevated permissionsBits).
+     * Creates a symbolic link to a folder.  On Windows operating systems, this may require administrator elevation.
      * Behind the scenes it uses `fs.symlinkSync()`.
+     *
+     * @remarks
+     * To avoid administrator elevation on Windows, use {@link FileSystem.createSymbolicLinkJunction} instead.
+     *
+     * On Windows operating systems, the NTFS file system distinguishes file symlinks versus directory symlinks:
+     * If the target is not the correct type, the symlink will be created successfully, but will fail to resolve.
+     * Other operating systems do not make this distinction, in which case {@link FileSystem.createSymbolicLinkFile}
+     * and {@link FileSystem.createSymbolicLinkFolder} can be used interchangeably, but doing so will make your
+     * tool incompatible with Windows.
      */
@@ -745,4 +776,16 @@ static createSymbolicLinkFolder(options) {
     /**
-     * Creates a hard link.
+     * Creates a hard link.  The link target must be a file, not a folder.
      * Behind the scenes it uses `fs.linkSync()`.
+     *
+     * @remarks
+     * For security reasons, Windows operating systems by default require administrator elevation to create
+     * symbolic links.  As a result, on Windows it's generally recommended for Node.js tools to use hard links
+     * (for files) or NTFS directory junctions (for folders), since regular users are allowed to create them.
+     * Hard links and junctions are less vulnerable to symlink attacks because they cannot reference a network share,
+     * and their target must exist at the time of link creation.  Non-Windows operating systems generally don't
+     * restrict symlink creation, and as such are more vulnerable to symlink attacks.  Note that Windows can be
+     * configured to permit regular users to create symlinks, for example by enabling Windows 10 "developer mode."
+     *
+     * A hard link requires the link source and target to both be located on same disk volume;
+     * if not, use a symbolic link instead.
      */
@@ -749,0 +792,0 @@ static createHardLink(options) {

package.json

 {
 	"name": "@rushstack/node-core-library",
-	"version": "3.40.1",
+	"version": "3.40.2",
 	"description": "Core libraries that every NodeJS toolchain project should use",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

995046

increased by1.44%

Lines of code

13839

increased by1.03%

No dependency changes