Search documentation of Plushie

# Plushie.RendererEnv (Plushie v0.7.2)

Copy Markdown View Source

Builds a safe, whitelisted environment for the renderer binary.

The renderer is spawned as a child process via `Port.open/2`. Erlang ports inherit the parent's full environment by default, which can leak sensitive variables (API keys, database credentials, tokens) to the renderer.

This module builds an explicit environment from a whitelist. Variables not on the whitelist are actively unset (set to `false` in Erlang port terms) so the child process receives only what it needs.

## Usage

    env = Plushie.RendererEnv.build(rust_log: "plushie=error")
    Port.open({:spawn_executable, path}, [{:env, env} | other_opts])

## How it works

Erlang's `{:env, list}` option extends the parent environment rather than replacing it. To enforce a whitelist, `build/1` emits `{name, false}` entries for every parent variable that is NOT whitelisted. This causes Erlang to unset those variables in the child process.

## Whitelist

The whitelist covers:

- Display - `DISPLAY`, `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, `WINIT_UNIX_BACKEND`, `XDG_RUNTIME_DIR`
- Rendering - `WGPU_BACKEND`, `MESA_*`, `LIBGL_*`, `__GLX_*`, `VK_*`, `GALLIUM_*`
- Library loading - `PATH`, `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `DYLD_FALLBACK_LIBRARY_PATH`
- Locale - `LANG`, `LANGUAGE`, `LC_*`
- Accessibility - `DBUS_SESSION_BUS_ADDRESS`, `AT_SPI_*`, `GTK_MODULES`, `NO_AT_BRIDGE`
- Font - `FONTCONFIG_*`, `XDG_DATA_DIRS`, `XDG_DATA_HOME`
- Renderer - `RUST_LOG`, `RUST_BACKTRACE`
- Home - `HOME`, `USER`
- Plushie toggles - any variable starting with `PLUSHIE_` (debug and diagnostic toggles read by the renderer itself, e.g. `PLUSHIE_NO_CATCH_UNWIND`). The prefix is plushie-reserved; no legitimate secret should use it.

## Summary

### Types

env_entry()

A single entry for the `:env` option of `Port.open/2`.

### Functions

build(opts \\ [])

Builds a whitelisted environment for the renderer Port.

whitelisted?(name)

Returns `true` if `name` is on the whitelist.

## Types

# env_entry()

    @type env_entry() :: {charlist(), charlist()} | {charlist(), false}

A single entry for the `:env` option of `Port.open/2`.

## Functions

# build(opts \\ [])

    @spec build(keyword()) :: [env_entry()]

Builds a whitelisted environment for the renderer Port.

Returns a list of `{charlist_name, charlist_value | false}` tuples suitable for the `:env` option of `Port.open/2`. Non-whitelisted variables from the parent environment are explicitly unset (`false`).

## Options

- `:rust_log` - sets `RUST_LOG`. When provided, overrides any inherited value. When `nil`, the parent's `RUST_LOG` is forwarded if present.

- `:extra` - additional `{charlist_name, charlist_value | false}` pairs to merge (e.g. for tests that need to unset specific variables).

# whitelisted?(name)

    @spec whitelisted?(String.t()) :: boolean()

Returns `true` if `name` is on the whitelist.