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.
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.
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
runentry: a child process has the user's normal operating-system access, not the package's Smudgy sandbox. - Every
ffientry: a native library executes in the Smudgy process and is not contained by the script sandbox. - A
writepath outside the package's own$DATAdirectory: 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.