API среды выполнения

При включении модели разрешений с помощью флага --permission в объект process добавляется новое свойство permission. Это свойство содержит одну функцию:

process.permission.has('fs.write'); // true
process.permission.has('fs.write', '/home/rafaelgss/protected-folder'); // true

process.permission.has('fs.read'); // true
process.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false copy

Разрешения файловой системы

По умолчанию модель разрешений ограничивает доступ к файловой системе через модуль node:fs. Она не гарантирует, что пользователи не смогут получить доступ к файловой системе другими способами, например через модуль node:sqlite.

Чтобы разрешить доступ к файловой системе, используйте флаги --allow-fs-read и --allow-fs-write:

$ node --permission --allow-fs-read=* --allow-fs-write=* index.js
Hello world! copy

По умолчанию точки входа вашего приложения включаются в список разрешённых путей для чтения файловой системы. Например:

$ node --permission index.js copy

• index.js будет включён в список разрешённых путей для чтения файловой системы

$ node -r /path/to/custom-require.js --permission index.js. copy

• /path/to/custom-require.js будет включён в список разрешённых путей для чтения файловой системы.
• index.js будет включён в список разрешённых путей для чтения файловой системы.

Допустимые аргументы для обоих флагов:

• * — чтобы разрешить все операции FileSystemRead или FileSystemWrite соответственно.
• Относительные пути к текущему рабочему каталогу.
• Абсолютные пути.

Пример:

• --allow-fs-read=* — разрешит все операции FileSystemRead.
• --allow-fs-write=* — разрешит все операции FileSystemWrite.
• --allow-fs-write=/tmp/ — разрешит доступ FileSystemWrite к папке /tmp/.
• --allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore — разрешит доступ FileSystemRead к папке /tmp/ и пути /home/.gitignore.

Также поддерживаются подстановочные знаки:

• --allow-fs-read=/home/test* разрешит чтение всего, что соответствует подстановочному знаку. Например: /home/test/file1 или /home/test2

После символа подстановки (*) все последующие символы будут игнорироваться. Например, /home/*.js будет работать аналогично /home/*.

При инициализации модели разрешений к указанному каталогу автоматически добавляется подстановочный знак (*), если каталог существует. Например, если существует /home/test/files, он будет обрабатываться как /home/test/files/*. Однако если каталог не существует, подстановочный знак добавлен не будет, а доступ будет ограничен /home/test/files. Если вы хотите разрешить доступ к каталогу, который ещё не существует, обязательно укажите подстановочный знак явно: /my-path/folder-do-not-exist/*.

Использование модели разрешений с npx

Если вы используете npx для запуска скрипта Node.js, модель разрешений можно включить, передав флаг --node-options. Например:

npx --node-options="--permission" package-name copy

При этом переменная среды NODE_OPTIONS задаётся для всех процессов Node.js, запускаемых npx, без влияния на сам процесс npx.

Ошибка FileSystemRead при использовании npx

Приведённая выше команда, вероятно, вызовет ошибку недопустимого доступа FileSystemRead, поскольку Node.js требуется доступ на чтение файловой системы, чтобы найти и выполнить пакет. Чтобы избежать этого:

1. Использование глобально установленного пакета Предоставьте доступ на чтение к глобальному каталогу node_modules, выполнив команду:

   npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name copy

2. Использование кэша npx Если вы временно устанавливаете пакет или используете кэш npx, предоставьте доступ на чтение к каталогу кэша npm:

   npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name copy

Любые аргументы, которые обычно передаются в node (например, флаги --allow-*), также можно передать через флаг --node-options. Эта гибкость позволяет легко настраивать разрешения по мере необходимости при использовании npx.

Ограничения модели разрешений

Перед использованием этой системы необходимо учитывать следующие ограничения:

• Модель не распространяется на рабочие потоки.
• При использовании модели разрешений будут ограничены следующие возможности:
  • Нативные модули
  • Дочерние процессы
  • Рабочие потоки
  • Протокол инспектора
  • Доступ к файловой системе
  • WASI
• Модель разрешений инициализируется после настройки среды Node.js. Однако некоторые флаги, например --env-file или --openssl-config, предназначены для чтения файлов до инициализации среды. Поэтому на такие флаги не распространяются правила модели разрешений. То же относится к флагам V8, которые можно задать во время выполнения через v8.setFlagsFromString.
• При включённой модели разрешений запросить движки OpenSSL во время выполнения нельзя, что влияет на встроенные модули crypto, https и tls.
• При включённой модели разрешений нельзя загружать расширения, загружаемые во время выполнения, что влияет на модуль sqlite.
• Использование существующих файловых дескрипторов через модуль node:fs обходит модель разрешений.

Ограничения и известные проблемы

• Символические ссылки будут обрабатываться, даже если они указывают на расположения за пределами путей, доступ к которым разрешён. Относительные символические ссылки могут предоставить доступ к произвольным файлам и каталогам. При запуске приложений с включённой моделью разрешений необходимо убедиться, что в путях, доступ к которым разрешён, нет относительных символических ссылок.