Session Roles

Role Model

Each frontend connection is assigned a role. Five built-in roles:

Role	Description
`admin`	Full access. Config, other sessions, audit log.
`user`	Standard interactive use. Own processes, plugins, jobs.
`script`	(default) Like `user` without job control, plugins, or admin.
`ci`	Restricted spawn via allowlist. Full redirect and env.
`restricted`	Minimal. No arbitrary processes, no redirects, no env mutation.

Capabilities

Capability	Description
`spawnAny`	Allow spawning any process from PATH.
`spawnAllowlist`	Comma-separated permitted commands (when `spawnAny` is false).
`fileRedirect`	Allow `>`, `>>` file writes.
`fileSandbox`	Restrict writes to a directory. Uses textual path normalization only.
`envMutation`	Allow modifying env vars.
`envSafelist`	Comma-separated env vars that can be modified.
`pluginAccess`	Allow calling plugin methods.
`pluginAllowlist`	Comma-separated permitted plugins.
`configModify`	Allow modifying config at runtime.
`sessionManage`	Allow managing other sessions (list, kill).
`jobControlOwn`	Allow `fg`/`bg`/`jobs` for own jobs.
`jobControlOthers`	Allow managing other sessions’ jobs.
`auditAccess`	Allow audit commands and log access.

Custom Roles

Defined in ~/.lash/roles.conf:

[role:ci]
spawnAny = false
spawnAllowlist = make, cmake, ninja, gcc, g++, clang, git, cargo, dub
fileRedirect = true
fileSandbox = /home/ci/builds
envMutation = true
envSafelist = PATH, HOME, CC, CXX
pluginAccess = false

[role:monitoring]
spawnAny = false
spawnAllowlist = ps, top, df, free, uptime
fileRedirect = false
auditAccess = true

Custom roles override built-in defaults of the same name.

Role Switching

role                  # prints current role
role user             # switch to user role
role admin            # requires audit password

Switching to a role with auditAccess requires entering the audit password. The password is verified against the stored verification hash in ~/.lash/audit.key.

Denied Actions

When a role denies an action, the shell returns a Problem/Suggestion error:

Problem: This session (role: restricted) cannot run 'curl'.
Suggestion: 'curl' is not in the allowlist. Switch to a 'user' session.

Default Role

Set the default role in ~/.lash/config:

[settings]
role.default = script