smudgy
dev:manual:scripting:permissions

Table of Contents

Permissions, sandboxing, and trust

Modules are your own unrestricted code. Packages run in separate sandboxes unless you explicitly trust them. A sandboxed package receives only the permissions declared by its manifest and accepted during installation.

Test a local package in its manifest sandbox before publishing. The package detail should describe the same access an installer will be asked to grant.

A local package running against its manifest sandbox with its effective capabilities listed

Permissions from a package and its transitive dependencies are combined. If an update requests additional access, smudgy waits for approval before loading that version.

Runtime resources

These fields control Deno and web-platform APIs:

Manifest field What it allows
net Connections to listed hosts or host:port targets.
read Reading listed files or directory trees. $DATA names the package's private data directory.
write Writing listed files or directory trees. $DATA names the package's private data directory.
env Reading listed environment variables.
sys Reading listed categories of operating-system information, such as hostname, osRelease, cpus, or systemMemoryInfo.
run Starting the listed programs, named by executable name or absolute path. The child process runs with the user's operating-system authority, outside Smudgy's script sandbox.
ffi Loading the listed native libraries. $DATA may be used in a path, but loaded native code executes outside Smudgy's script sandbox.
import none allows only smudgy modules and declared packages; registries also allows npm and JSR; any also allows arbitrary HTTP(S) modules.

Network access and code imports are independent. For example, importing an npm package requires import: "registries"; letting that package call a web service also requires the corresponding net target.

The package manifest System tab with environment, system information, runnable program, and native library permission fields

Recognize grants that escape the sandbox

The permission list limits which Smudgy and Deno operations a package can request. It cannot confine code that runs after one of those operations leaves the script sandbox.

Treat these grants as a decision to trust code with effects elsewhere on the computer:

  • Every run entry: a child process has the user's normal operating-system access, not the package's Smudgy sandbox.
  • Every ffi entry: a native library executes in the Smudgy process and is not contained by the script sandbox.
  • A write path outside the package's own $DATA directory: the package can alter files managed by the user or another application.

The installation review labels such a permission set Effectively full access. A narrowly written entry, such as one executable or library, limits what Smudgy agrees to launch or load; it does not sandbox what that executable or library subsequently does.

A read path outside $DATA receives a caution because it may expose private files. sys can contribute to device fingerprinting, but it does not by itself run native code or grant general file access.

Smudgy capabilities

The permissions.smudgy block uses grouped tokens:

Combine permissions from the same group in one array; the rows below show one token at a time.

Manifest token What it allows
automations: ["aliases"] Create and manage the package's aliases.
automations: ["triggers"] Create and manage the package's triggers.
session: ["send"] Send commands through the user's aliases.
session: ["send-direct"] Send commands directly, bypassing aliases.
session: ["echo"] Write text to the session.
session: ["reach-others"] Enumerate and act on other open sessions.
display: ["change"] Read, hide, restyle, insert, or replace game text.
mapper: ["read"] Read maps, rooms, exits, labels, and shapes.
mapper: ["write"] Change maps; this also grants map reading.
widgets: ["create"] Create and update on-screen widgets.
interop: ["read"] Read or watch shared state and subscribe to events.
interop: ["write"] Publish shared state, emit events, implement procedures, or post procedure calls.
panes: ["create"] Create or close panes, write to them, and route game lines.
gmcp: ["send"] Send GMCP messages and manage GMCP modules.
input: ["access"] Read or rewrite command input, control focus and masking, submit commands, and subscribe to input events.

The legacy events tokens are compatibility aliases for interop in smudgy 0.4 and should not be used in new manifests.

What isolation means

Each sandboxed package has its own JavaScript globals and cannot inspect another package's variables. Communication crosses the sandbox through the explicit shared-state, event, and procedure APIs described in Shared state, events, and procedures.

Trust is an advanced opt-in. A trusted package runs with the same unrestricted access as your modules and ignores its manifest as an enforcement boundary. Scoped run and ffi permissions do not require this mode, but they still permit effects outside the sandbox. Review the package and its dependencies in either case.

smudgy