Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Modules and Permissions

Permissions

Understand Deno's permission model - allow flags for read, write, net, env, run, ffi and sys, scoped values, deny flags, prompts, the Deno.permissions API, and how to grant the least access.

Imagine you run a script you found online. In most runtimes that script can read your home folder, send files to a server and start other programs, and you would never know. Deno takes the opposite stance: a program has no access to the outside world until you grant it. The pure computation always works; anything that touches your files, your network, your environment or other processes needs a permission.

This lesson explains each permission, how to scope it, how to deny access, and how to design programs that need as little as possible. The permission flags are read-only on this site; the runnable examples implement the same matching rules in plain JavaScript so you can see how scopes behave.

The permission model

When code calls a sensitive API, Deno checks whether that capability was granted:

flowchart LR
  A["Code calls Deno.readTextFile"] --> B{"--allow-read covers this path?"}
  B -->|Yes| C["Operation runs"]
  B -->|No| D{"Interactive terminal?"}
  D -->|Yes| E["Prompt: allow / deny"]
  D -->|No| F["Throws NotCapable error"]

Deno checks every sensitive call at the moment it happens.

If you run a program with no flags in a terminal, Deno prompts the first time the code needs something:

TEXT
โ” โš ๏ธ  Deno requests read access to "notes.txt".
โ” โ”€ Requested by `Deno.readTextFile()` API.
โ” โ”€ Run again with --allow-read to bypass this prompt.
โ”— Allow? [y/n/A] (y = yes, allow; n = no, deny; A = allow all read permissions) >

In CI or when the output is piped there is no prompt, so the call throws Deno.errors.NotCapable (older versions use PermissionDenied). Pass --no-prompt to disable prompts everywhere.

The permission flags

Flag Short Grants
--allow-read -R Reading files and directories
--allow-write -W Writing, creating and deleting files
--allow-net -N Network connections and listening on ports
--allow-env -E Reading environment variables
--allow-run Running other programs (Deno.Command)
--allow-ffi Loading native libraries
--allow-sys -S System info such as hostname, OS release, network interfaces
--allow-import -I Downloading code from specific hosts
--allow-all -A Everything (use only for trusted code)

Every flag without a value grants the whole category. Almost all of them accept a list to scope the grant.

Scoping

Terminal
# Only these paths
deno run --allow-read=./data,./config.json main.ts

# Only this host (and port)
deno run --allow-net=api.example.com,localhost:8000 main.ts

# Only these variables
deno run --allow-env=PORT,DATABASE_URL main.ts

# Only these programs
deno run --allow-run=git,deno main.ts

# Only these import hosts
deno run --allow-import=cdn.example.com main.ts

Paths cover the folder and everything inside it. --allow-read=./data allows ./data/users.json but not ./secrets.txt. Network scopes match the host, and a port if you give one: --allow-net=example.com allows any port on that host, while --allow-net=example.com:443 only allows 443. A scoped grant limits the damage if a dependency turns malicious.

The following code applies these same matching rules, so you can test scopes:

Node.js How read and net scopes match

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that .. segments are resolved before comparing. Deno does the same: you cannot escape a scoped folder with ../. Symlinks are a separate concern, so avoid scoping a folder that holds links to somewhere else.

Deny flags

Deny flags win over allow flags. They carve exceptions out of a broad grant:

Terminal
deno run --allow-read --deny-read=./secrets main.ts
deno run --allow-net --deny-net=169.254.169.254 main.ts

The second command lets a program reach the network but not the cloud metadata address often abused in server-side request forgery attacks. Deny rules are checked first, without prompting.

Which permission does an API need?

API Permission
Deno.readTextFile, Deno.readDir, Deno.stat read
Deno.writeTextFile, Deno.mkdir, Deno.remove write
fetch, Deno.serve, WebSocket net
Deno.env.get, Deno.env.toObject env
Deno.Command run
Deno.hostname, Deno.osRelease, Deno.networkInterfaces sys
Deno.dlopen ffi
import("https://...") at runtime import

Some things surprise people: reading the current directory with Deno.cwd() needs read access, and Deno.env.toObject() needs unrestricted --allow-env, since it reads every variable.

Checking permissions in code

The Deno.permissions API lets a program ask what it may do and request more:

TypeScript
const status = await Deno.permissions.query({ name: "read", path: "./data" });
console.log(status.state); // "granted", "prompt" or "denied"

const request = await Deno.permissions.request({ name: "net", host: "api.example.com" });
if (request.state !== "granted") {
  console.log("running in offline mode");
}

await Deno.permissions.revoke({ name: "read", path: "./data" });

revoke is useful for dropping rights once startup is done, so that later code cannot use them. A program that degrades gracefully is friendlier than one that crashes:

Node.js Graceful degradation pattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Designing for least privilege

  • Grant what you need, scoped as narrowly as you can. --allow-read=./data beats --allow-read, which beats -A.
  • Put the flags in a task so everyone runs the same permissions, and they are reviewed with the code:
JSON
{
  "tasks": {
    "start": "deno run --allow-net=0.0.0.0:8000 --allow-read=./public --allow-env=PORT main.ts"
  }
}
  • Read the code before -A. Use -A only for code you trust or in a throwaway sandbox.
  • Review dependency updates: a new version that suddenly needs more permissions is a warning sign.
  • Remember the limits. Permissions are a strong guard against accidents and casual abuse, but they are not a full sandbox for hostile native code. Use containers or VMs when running truly untrusted programs, and never grant --allow-ffi or --allow-run to code you do not trust, since they escape most restrictions.

Permissions in tests and scripts

Tests can declare what they need, per test:

TypeScript
Deno.test({
  name: "reads the fixture",
  permissions: { read: ["./fixtures"] },
  fn: async () => {
    const text = await Deno.readTextFile("./fixtures/a.txt");
    // ...
  },
});

deno test itself accepts the same flags as deno run. A test with its own permissions object runs with exactly those.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens when code needs a permission that was not granted, and there is no interactive terminal?

    Without a prompt, the operation fails with an error such as Deno.errors.NotCapable.
  2. 2. What does --allow-read=./data allow?

    A path scope covers the folder and everything inside it, and nothing outside.
  3. 3. Which wins when both --allow-read and --deny-read cover a path?

    Deny rules take precedence over allow rules.
  4. 4. Which flag is the riskiest to hand to untrusted code?

    Running subprocesses can bypass the scoped restrictions, so --allow-run (and --allow-ffi) should be avoided for untrusted code.
  5. 5. How can a program check whether it has network permission?

    Deno.permissions.query returns a status with state granted, prompt or denied.

Summary

  • A Deno program has no system access until permissions are granted by flag or prompt.
  • The main permissions are read, write, net, env, run, ffi, sys and import; -A grants all.
  • Scope every grant: paths, hosts with optional ports, variable names, program names.
  • Deny flags override allow flags; path scopes resolve .. before matching.
  • Deno.permissions queries, requests and revokes rights at runtime.
  • Put permission flags in tasks and keep them as narrow as the program allows.

Next: The Standard Library