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

Если для выполнения скрипта Node.js вы используете npx, включить модель разрешений можно, передав флаг --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.

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

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

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

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

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