with.permissions · Execution permissions

Configure the sandboxing permissions for the Module execution.

- https://françois.esquie.app/module:
    api_key: ${Deno.env.get("API_KEY")}
  with:
    # Ensure the api key doesn't get sent somewhere unexpected
    permissions:
      net: api.example.com
      env: API_KEY
      import: jsr.io

CAUTION

Since these restrictions are enforced by the runtime, THEY CANNOT BE BYPASSED.

However it DOES NOT PROTECT AGAINST USERLAND ATTACKS, such as consuming excessive resources or messing up with the expedition progress.

Additionally, subprocesses and dynamic libraries are not subject to the security restrictions imposed by Deno's sandboxing (as explained in their documentation) which means that run and ffi permissions should be used with extreme caution.

Respecting the principle of least privilege greatly reduces the attack surface and the potential impact of a compromised module.

NOTE

Source files from @esquie/core (including built-in modules) are always included within read permissions (or net permissions if Esquie was imported from an URL) even if not explicitly specified. This is to ensure Esquie can run properly.

Supported permissions

Any valid Deno.PermissionOptions descriptor is supported. Refer to the table below for a list of available permissions.

Permission	Description	Flag used
read	File system access (read)	--allow-read
write	File system access (write)	--allow-write
net	Network access	--allow-net
env	Environment variables	--allow-env
sys	System Information	--allow-sys
run	Subprocesses	--allow-run
ffi	FFI (Foreign Function Interface)	--allow-ffi
import	Calls to import()	--allow-import

Permissions inheritance

As explained in the sandboxing rules, a substep cannot request more permissions than their ancestors.

An error will be thrown at runtime if a step attempts to escalate its permissions.

- with:
    permissions:
      read: true
      net: [ example.com, example.org ]
  tasks:
    - _: This will throw an error at runtime
      with:
        permissions:
          read: true            # allowed
          net: [ example.com ]  # allowed (subset)
          write: true           # not allowed

IMPORTANT

The with.permissions is not "deep-merged", which means that when it is overridden, other permissions are implicitly revoked.