# WASM security (/advanced/wasm-security)

Every Lumis runtime except the Rust crate runs Tree-sitter parsers as
WebAssembly. Two inputs matter: the source code you highlight, and the parser
that reads it.

Highlighting source code you didn't write is safe. A parser is a dependency:
the sandbox limits what its code can do, and Lumis checks the bytes it
downloads.

## Where parsers run

| Runtime | Engine | A parser runs in |
| --- | --- | --- |
| Node with the native addon, Elixir, CLI | [Wasmtime](https://wasmtime.dev) 36, through Tree-sitter's Wasm store | a Wasmtime sandbox with a fixed import list |
| Browsers, Bun, Deno, Node without the addon | `web-tree-sitter` 0.26 (Emscripten) | the JavaScript engine's WebAssembly sandbox |
| Rust | none | your binary. Parsers are C compiled in, like any other C dependency |

`lumis4j` lives in a separate repository and isn't covered here.

## The source you highlight

Lumis assumes it's hostile.

- A parser only decides which byte ranges get which name from Lumis's fixed
  [scope list](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-core/src/highlights.rs#L6).
  The formatter
  [escapes the text](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-core/src/formatter/html.rs#L525),
  so neither the document nor the parser can put markup into HTML output.
- The [budget](/advanced/budget) caps each render with a time limit and a match
  limit. Running out returns the document plain or partly highlighted, never an
  error.
- Elixir renders on
  [dirty CPU schedulers](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/packages/elixir/lumis/native/lumis_nif/src/lib.rs#L668),
  so a slow render doesn't block the BEAM's normal schedulers.

## What the Wasmtime sandbox enforces

Tree-sitter links each parser into a Wasm store it owns, on an engine Lumis
creates with Wasmtime's
[default configuration](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-wasm-runtime/src/runtime.rs#L1064-L1074).

- Imports are an allowlist. A parser can import
  [24 libc functions](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm/stdlib-symbols.txt)
  (`malloc`, `memcpy`, `strcmp`, `towlower` and similar), the lexer callbacks,
  and a few
  [abort and no-op stubs](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L587-L638).
  Any other import
  [fails the load](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1120-L1149).
  Nothing on that list touches files, sockets, clocks or processes.
- Memory is capped. A store's linear memory stops at
  [128 MiB](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L180)
  and a scanner's heap at
  [4 MiB](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/crates/language/wasm/src/stdlib.c#L16).
  Wasmtime bounds-checks every memory access, keeps the call stack out of
  linear memory, and type-checks indirect calls
  ([Wasmtime security](https://docs.wasmtime.dev/security.html)).
- The host checks what crosses the boundary. Since
  [tree-sitter#5569](https://github.com/tree-sitter/tree-sitter/pull/5569),
  every read of language data out of WASM memory is
  [bounds-checked](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L373-L407),
  and a scanner's serialized state
  [can't overrun](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1904-L1907)
  the host buffer.
- A trap only fails the current render. Tree-sitter
  [flags the store](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/wasm_store.c#L1752-L1787)
  and
  [stops the parse](https://github.com/tree-sitter/tree-sitter/blob/v0.26.13/lib/src/parser.c#L1603-L1604),
  and Lumis returns an error for that render.

Wasmtime 36 is a long-term support release and gets security fixes for 24
months ([release policy](https://docs.wasmtime.dev/stability-release.html)).

## Where parser bytes come from

npm and Hex verify an installed parser against your lockfile, so Lumis loads it
as installed. When Lumis downloads parser bytes itself (the CLI, a resolver, a
browser fetching a parser asset), it checks them against the SHA-256 in the
parser's language package
([Rust](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/crates/lumis-wasm-runtime/src/store.rs#L739-L747),
[JavaScript](https://github.com/leandrocp/lumis/blob/462a779f4a1fed892db5167c0e0db976ddc20c3c/packages/javascript/lumis/src/core/languages.ts#L713-L720))
and checks its own cache again on every read. CI builds each parser once and
publishes it to npm with
[provenance](https://docs.npmjs.com/generating-provenance-statements).

## The compiled-module cache

Wasmtime compiles each parser to machine code and caches it under `compiled/`
in the [data directory](/languages#point-every-process-at-one-directory). It
loads those files back as code without checking that it wrote them (the same
caveat as
[`Module::deserialize`](https://docs.rs/wasmtime/36.0.15/wasmtime/struct.Module.html#method.deserialize)),
so anyone who can write that directory can run code in your process. Give it
the permissions you give your application's code.

## Content Security Policy

Lumis works under a policy without `'unsafe-eval'`. It needs
[`'wasm-unsafe-eval'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#wasm-unsafe-eval)
to compile WebAssembly; without it, loading fails at `Parser.init`.

```text
Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'
```

Bundlers warn about two direct `eval` calls in `web-tree-sitter`. Emscripten
uses them only to load JavaScript embedded in a parser, and Tree-sitter parsers
carry none, so the policy can leave `eval` off.