Permissions and security
Status: Partly implemented. The sandbox (folder rule, WebAssembly container, Lua sandbox), memory and time limits, the capability store with the Permissions screen, and command permissions. API 1.20: capability checks and requests from code (
cl_cap_granted,cl_cap_request,mod.permission_changed), the file API and HTTP behindnet.http:<host>. Permission nodes for servers, the OS APIs behind the other capabilities and package signatures are Planned.
Concepts: Capabilities and permissions. Internals: Security, the sandbox and capabilities.
Command permissions (server)
| C | Lua | C++ |
|---|---|---|
cl_cmd_requires_level(node, 2) |
node:requires_permission(2) |
node.requires_level(2) |
cl_cmd_requires_permission(node, CL_STR("my_mod.admin")) |
node:requires_permission("my_mod.admin") |
node.requires_permission("my_mod.admin") |
cl_cmd_desc.permission_level |
clight::cmd::add(name, fn, level) |
|
cl_cmd_ctx_permission_level(ctx) |
ctx:permission_level() |
c.permission_level() |
A named permission means operators (level 2) until a permissions plugin can answer it. See Commands.
Sandbox limits
| Limit | Default | Manifest |
|---|---|---|
| Memory (WASM linear memory, Lua allocator) | 256 MB (at most 4096, WASM and Lua) | limits.memory_mb |
| Time per callback (Lua) | 50 ms | |
| Time per call (WASM) | a deadline per call (epoch interruption) | |
| Errors before the mod is turned off | Lua: 10 within a minute. WASM: 10 traps, or one call past its deadline |
A mod that hits a limit gets an error (Lua) or a trap (WASM) in that call; the game keeps running. When the mod is turned off for the session (see the table), the Mods screen shows why.
Files
Every mod reads its own folder and writes only mods/<id>/data/ through the file API (cl_fs_*, Lua cl.fs, API 1.20; at most 256 MiB, executables refused); a WebAssembly mod also sees its folder read-only as / and data/ read/write as /data through WASI (Filesystem and HTTP). Packages may not contain native code; the loader and the website refuse it (Packaging a .clmod).
Capabilities
Declared in permissions / optional_permissions, decided by the player on the Permissions screen, stored in config/clight/permissions.json. The list: Capability list. From code (API 1.20): cl_cap_granted(cap) (Lua cl.permission(cap)) and cl_cap_request(cap) (Lua cl.request_permission(cap)), which opens the Permissions screen for an undecided capability; the answer fires mod.permission_changed.
Planned
Permission nodes with defaults and checks anywhere (has_permission), a permissions service other mods can provide, the OS APIs behind their capabilities, and signed packages (Signing and trust).