Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): describe installed plugins as fully trusted

Yudhi Armyndharis79b6ff15026d
diff --git a/SECURITY.md b/SECURITY.md
index 8d3ab922d..26e5d5d6c 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -64,10 +64,13 @@ new value. The Helm chart does not set `ENABLE_SWAGGER`.
Installing or enabling a plugin is executing third-party code on the host that runs OpenWA.
This is inherent to what a plugin IS here: the sandbox (a `worker_threads` isolate with a
-capped heap, an allowlisted environment, a deny-by-default network manifest, and a
-capability router with per-call timeouts) contains a buggy or runaway plugin — it is NOT a
-security boundary against a malicious one. A worker shares the process's filesystem and
-OS privileges with the API.
+capped heap, an allowlisted environment, a deny-by-default network manifest for
+`ctx.net.fetch`, and a capability router with per-call timeouts) contains a buggy or
+runaway plugin — it is NOT a security boundary against a malicious one. A worker shares
+the process's filesystem and OS privileges with the API, so it can reach anything the API
+container can, including the process environment, the data volume and the `docker-proxy`
+described below. See [docs/30-plugin-sandboxing.md](docs/30-plugin-sandboxing.md) for the
+full list.
The compensating gates on the install path:
@@ -101,14 +104,14 @@ it as one:
bind-mount, which is host-root-equivalent.
Mitigations in place: the proxy is unreachable except from `openwa-api` (dedicated
-`internal: true` network), the orchestration endpoints require an ADMIN-role API key,
-both teardown and start are constrained to the three managed profiles (`postgres`,
-`redis`, `minio`) — non-managed names are dropped before reaching `DockerService` —
-and OpenWA itself never issues deletes (profile teardown is stop-only). If you do not
-use the built-in datastore orchestration (Dashboard → Infrastructure built-in
-toggles), disable the proxy entirely — see the `docker-proxy` comments in
-`docker-compose.yml`; `DockerService` then reports Docker unavailable and
-orchestration degrades gracefully.
+`internal: true` network; any plugin loaded into `openwa-api` shares that reach), the
+orchestration endpoints require an ADMIN-role API key, both teardown and start are
+constrained to the three managed profiles (`postgres`, `redis`, `minio`) — non-managed
+names are dropped before reaching `DockerService` — and OpenWA itself never issues
+deletes (profile teardown is stop-only). If you do not use the built-in datastore
+orchestration (Dashboard → Infrastructure built-in toggles), disable the proxy entirely —
+see the `docker-proxy` comments in `docker-compose.yml`; `DockerService` then reports
+Docker unavailable and orchestration degrades gracefully.
### Session-restricted API keys
diff --git a/docker-compose.yml b/docker-compose.yml
index 71cb28fe9..0aafcf582 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,8 +7,8 @@ services:
image: tecnativa/docker-socket-proxy:v0.4.2
container_name: openwa-docker-proxy
restart: unless-stopped
- # Only on the isolated internal network — reachable solely by openwa-api, NOT the
- # dashboard or any other peer. `internal: true` also denies the proxy
+ # Only on the isolated internal network, reachable solely by openwa-api (including any
+ # plugin loaded into it), NOT the dashboard or any other peer. `internal: true` also denies the proxy
# outbound access; it only needs the locally-mounted docker socket.
networks:
- internal-docker
@@ -544,6 +544,7 @@ networks:
name: openwa-network
# Isolated network for the Docker socket proxy. `internal: true` means no external
# connectivity; only openwa-api joins it, so nothing else can reach docker-proxy:2375.
+ # Plugins run inside openwa-api, so a loaded plugin can reach it too (see SECURITY.md).
internal-docker:
name: openwa-internal-docker
internal: true
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index f98c66b7b..64185d032 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -399,13 +399,14 @@ spec:
labels:
app: openwa
spec:
- # OS-level containment is the second half of the plugin sandbox boundary (see docs/23-plugin-
- # sandboxing.md). Without it a worker_thread plugin that abuses Node built-ins (fs, net) runs with
- # the same privileges as the API and can read host files / open raw sockets outside the capability
- # model. The shipped compose file runs the image read-only + cap_drop:ALL, and the node process
- # runs as the non-root openwa user; the manifest below mirrors that so a k8s deploy is not
- # silently weaker. Do NOT add runAsNonRoot: the entrypoint starts as root to chown /app/data,
- # then drops to openwa via gosu (same as charts/openwa/values.yaml).
+ # OS-level containment is defence in depth for the plugin sandbox (see docs/30-plugin-sandboxing.md):
+ # it limits the privileges the API process holds, not what a plugin inside that process can reach.
+ # Without it the API process, and every plugin loaded into it, keeps whatever the container runtime
+ # grants by default, so a plugin that abuses Node built-ins (fs, net) can read host files / open raw
+ # sockets outside the capability model. The shipped compose file runs the image read-only +
+ # cap_drop:ALL, and the node process runs as the non-root openwa user; the manifest below mirrors
+ # that so a k8s deploy is not silently weaker. Do NOT add runAsNonRoot: the entrypoint starts as
+ # root to chown /app/data, then drops to openwa via gosu (same as charts/openwa/values.yaml).
securityContext:
fsGroup: 1000
containers:
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index f658f3d76..a18e7bb17 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -5,7 +5,7 @@
> **Current Status: ✅ Implemented**
>
> The plugin runtime — loader, hook bus, capability facade, permission enforcement, per-session
-> activation, and a `worker_thread` sandbox for untrusted plugins — is shipped and wired.
+> activation, and a `worker_thread` sandbox for user-installed plugins — is shipped and wired.
| Component | Status | Location |
| ------------------------ | -------------- | ------------------------------------------------------------------ |
@@ -17,15 +17,15 @@
| **Dashboard UI** | ✅ Implemented | `dashboard/src/pages/Plugins.tsx` |
| **REST API** | ✅ Implemented | `src/modules/plugins/plugins.controller.ts` |
-| Component | Status | Notes |
-| ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| **Sandboxed execution** | ✅ Implemented | Untrusted (disk-loaded) plugins run in a `worker_thread`; see [30 — Plugin Sandboxing](./30-plugin-sandboxing.md). No `vm2`. |
-| **Permission enforcement** | ✅ Implemented | Capability permissions enforced at the call boundary via `assertPermission` |
-| **Per-session activation** | ✅ Implemented | A session-scoped plugin runs only for the sessions an operator activated it for |
-| **Per-session config** | ✅ Implemented | Per-session config overrides shallow-merged over the base config at hook time |
-| **Built-in plugins** | ✅ Implemented | The two engine adapters (`whatsapp-web.js`, `baileys`) register as in-process built-ins |
-| **Plugin install / catalog** | ✅ Implemented | Install a `.zip` by upload or URL, or from the remote catalog |
-| **@openwa/plugin-sdk** | 🔜 Planned | NPM package not yet published; plugins implement `IPlugin` directly today |
+| Component | Status | Notes |
+| ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Sandboxed execution** | ✅ Implemented | User-installed (disk-loaded) plugins run in a `worker_thread`; see [30 — Plugin Sandboxing](./30-plugin-sandboxing.md). No `vm2`. |
+| **Permission enforcement** | ✅ Implemented | Capability permissions enforced at the call boundary via `assertPermission` |
+| **Per-session activation** | ✅ Implemented | A session-scoped plugin runs only for the sessions an operator activated it for |
+| **Per-session config** | ✅ Implemented | Per-session config overrides shallow-merged over the base config at hook time |
+| **Built-in plugins** | ✅ Implemented | The two engine adapters (`whatsapp-web.js`, `baileys`) register as in-process built-ins |
+| **Plugin install / catalog** | ✅ Implemented | Install a `.zip` by upload or URL, or from the remote catalog |
+| **@openwa/plugin-sdk** | 🔜 Planned | NPM package not yet published; plugins implement `IPlugin` directly today |
---
@@ -52,9 +52,9 @@ flowchart TB
end
```
-1. **Isolation** - Untrusted plugins (anything loaded from the `plugins/` directory) run in a `worker_thread`, separate from in-process built-ins; capability calls round-trip to the host. First-party built-ins (the engine adapters) run in-process. A `worker_thread` is V8-context isolation in the same OS process, not an OS-level sandbox — see [30 — Plugin Sandboxing](./30-plugin-sandboxing.md) for what it does and does not guarantee, and the OS-containment guidance.
+1. **Isolation** - User-installed plugins (anything loaded from the `plugins/` directory) run in a `worker_thread`, separate from in-process built-ins; capability calls round-trip to the host. First-party built-ins (the engine adapters) run in-process. A `worker_thread` is V8-context isolation in the same OS process, not an OS-level sandbox — see [30 — Plugin Sandboxing](./30-plugin-sandboxing.md) for what it does and does not guarantee, and the OS-containment guidance.
2. **Extensibility** - Easy to add new features
-3. **Safety** - Capability permissions are enforced at the call boundary (`assertPermission` throws `PluginCapabilityError`), session scope is enforced per call, and outbound HTTP is SSRF-guarded.
+3. **Safety** - Capability permissions are enforced at the call boundary (`assertPermission` throws `PluginCapabilityError`), session scope is enforced per call, and `ctx.net.fetch` is SSRF-guarded and host-allowlisted (a direct Node socket opened by the worker is not; see [30 - Plugin Sandboxing](./30-plugin-sandboxing.md)).
4. **Performance** - Lazy loading, minimal overhead
## 19.2 Plugin Types
@@ -564,7 +564,7 @@ double-enable, and engines must match the configured active engine):
- **Built-in (trusted)** → `enableInProcess`: `require()` the `main` module (path-contained to the
plugin dir), instantiate the default-exported class, and run `onLoad` then `onEnable` in-process with
the live capability context.
-- **Untrusted (disk-loaded)** → `enableSandboxed`: spawn a `worker_thread`, load the module there, and
+- **User-installed (disk-loaded)** → `enableSandboxed`: spawn a `worker_thread`, load the module there, and
drive `onLoad`/`onEnable` over the channel. Capability calls and hook dispatches round-trip to the
host, which runs the **same** permission + session-scope checks. Lifecycle calls are bounded by a
30 s timeout and hooks by a 5 s timeout; a failure tears the worker back down. See
@@ -767,7 +767,7 @@ Two further checks apply on top of the permission:
### Sandboxed execution
-Untrusted plugins (anything loaded from the plugins directory) run in a Node `worker_thread`; there is
+User-installed plugins (anything loaded from the plugins directory) run in a Node `worker_thread`; there is
**no `vm2`**. First-party built-ins (the engine adapters) run in-process. The loader routes by trust
tier automatically. Key properties:
@@ -779,11 +779,13 @@ tier automatically. Key properties:
- Lifecycle methods (`load`/`onLoad`/`onEnable`/`onDisable`) and `healthCheck` are bounded by a **30 s**
/ **5 s** timeout respectively, so a wedged plugin can't hang an ADMIN enable/disable or the health endpoint.
- The worker gets a **minimal allowlisted env** (`NODE_ENV`, `NODE_EXTRA_CA_CERTS`, `TZ`) — host secrets
- (master key, DB/Redis vars, …) are withheld.
+ (master key, DB/Redis vars, …) are left out of the worker's `process.env`. That is hygiene, not a
+ boundary: the worker can still read the process environment through `fs`.
This is V8-context isolation in the same OS process, not an OS-level sandbox: a worker can still reach
-Node built-ins (`fs`, `process`, sockets). For genuinely untrusted plugins, combine it with OS
-containment (the shipped Docker image runs read-only rootfs, non-root, `cap_drop: ALL`). See
+Node built-ins (`fs`, `process`, sockets), so it is fault containment and installing a plugin is full
+host trust. The bundled `docker-compose.yml` (not the image) adds read-only rootfs and `cap_drop: ALL`,
+which limit what the process can do to the host but not what a plugin inside it can reach. See
[30 — Plugin Sandboxing](./30-plugin-sandboxing.md) for the full security model and author rules.
---
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index b4f19b95e..6773cac69 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -27,12 +27,12 @@ public contract — Integration SDK v1** — because the contract, not any singl
## 25.2 Design principle: one new primitive, everything else a clone
-The overriding goal is to preserve the untrusted-worker safety invariants _by construction_. OpenWA
-plugins run in a capability-gated worker thread with no ambient host access (see
-[30 - Plugin Sandboxing](./30-plugin-sandboxing.md)). Every host↔worker message is a serializable POJO
-across a `structuredClone` boundary; host-initiated calls fail open on a timeout and drain on a worker
-crash; permissions are manifest-static and cannot be widened by configuration; session scope is enforced
-host-side.
+The overriding goal is to preserve the sandboxed-worker safety invariants _by construction_. OpenWA
+plugins reach the host through a capability-gated worker bridge; the worker is fault containment, not a
+security boundary against a malicious plugin (see [30 - Plugin Sandboxing](./30-plugin-sandboxing.md)).
+Every host↔worker message is a serializable POJO across a `structuredClone` boundary; host-initiated
+calls fail open on a timeout and drain on a worker crash; permissions are manifest-static and cannot be
+widened by configuration; session scope is enforced host-side.
Rather than invent new machinery that would have to re-earn those properties, the Integration Fabric is
**~90% a faithful clone of seams OpenWA already ships**:
@@ -196,8 +196,9 @@ Four tables live on the data connection, each created by a hand-authored dual-di
- **Raw-body content types.** Signature verification observes exact bytes for `application/json` and
`application/x-www-form-urlencoded`. Plain text, XML, octet streams, and non-UTF JSON charsets are not
supported ingress body formats and fail verification/content handling rather than being re-serialized.
-- **Egress.** The only outbound path remains the existing SSRF-guarded `ctx.net.fetch`, scoped to the
- manifest's allowed hosts.
+- **Egress.** The only sanctioned outbound path remains the SSRF-guarded `ctx.net.fetch`, scoped to the
+ manifest's allowed hosts; a direct Node socket opened by the worker is not covered (see [30 - Plugin
+ Sandboxing](./30-plugin-sandboxing.md)).
- **Re-entrancy.** A reply issued _inside_ an ingress handler seeds the in-flight hook set, so an adapter's
own outbound message hook cannot echo-loop the reply back out to the external system.
@@ -245,7 +246,7 @@ dedup rows and re-admit their replays, which is worse than the bounded growth it
## 25.8 The Integration SDK (v1)
-The stable surface untrusted adapters consume. A plugin declares `sdkVersion: "1"` and an `ingress`
+The stable surface sandboxed adapters consume. A plugin declares `sdkVersion: "1"` and an `ingress`
descriptor (the route, which is a single URL path segment such as `chatwoot` and never contains a `/`, its
signature scheme, replay tolerance, dedup header, and an optional verification handshake) in its manifest,
and requests the `webhook:ingress` and `conversation:send` permissions. The host refuses to load an
diff --git a/docs/30-plugin-sandboxing.md b/docs/30-plugin-sandboxing.md
index 73dd54998..882244c0d 100644
--- a/docs/30-plugin-sandboxing.md
+++ b/docs/30-plugin-sandboxing.md
@@ -1,19 +1,22 @@
# 30 — Plugin Sandboxing
-OpenWA runs **untrusted plugins** (anything loaded from the plugins directory) in an isolated worker
-thread, separate from the first-party built-ins (the two engine adapters) which run in-process. This
+OpenWA runs **user-installed plugins** (anything loaded from the plugins directory) in an isolated
+worker thread, separate from the first-party built-ins (the two engine adapters) which run in-process.
+The worker is fault containment for a buggy or runaway plugin, not a security boundary against a
+malicious one: installing a plugin is full host trust (see
+[SECURITY.md](../SECURITY.md#plugins-are-full-host-trust--by-design)). This
page describes the security model honestly — what the sandbox guarantees and, just as important, what
it does not — and what changes for plugin authors.
## Trust tiers
-| Tier | Examples | Runs | Capabilities |
-| ---------------------- | -------------------------------------------------- | -------------------- | ---------------------------------- |
-| **Built-in (trusted)** | the two engine adapters (whatsapp-web.js, baileys) | in-process | direct, full speed |
-| **Untrusted** | anything in the plugins directory | in a `worker_thread` | only via the host-validated bridge |
+| Tier | Examples | Runs | Capabilities |
+| ------------------------------- | -------------------------------------------------- | -------------------- | ---------------------------------- |
+| **Built-in (trusted)** | the two engine adapters (whatsapp-web.js, baileys) | in-process | direct, full speed |
+| **User-installed (full trust)** | anything in the plugins directory | in a `worker_thread` | only via the host-validated bridge |
The loader routes by tier automatically: a plugin registered programmatically is built-in; one loaded
-from disk is untrusted and sandboxed.
+from disk is user-installed and sandboxed.
## What the sandbox guarantees
@@ -30,7 +33,8 @@ from disk is untrusted and sandboxed.
method — and the router validates the string and mapping-key args before they reach a host service
(other positional args are passed through as declared types, not re-checked). `ctx.net.fetch` is
additionally bounded by the host SSRF guard and the manifest `net.allow` host list, so outbound
- HTTP from a worker is neither ambient nor unrestricted.
+ HTTP through `ctx.net.fetch` is neither ambient nor unrestricted; a direct Node socket opened by
+ the worker is not covered (see the limits below).
- **Host-initiated dispatches are mediated too.** Besides hooks, the host drives two other bridges into
the worker over the same request/reply channel: inbound webhooks
(`ctx.registerWebhook`, gated by the `webhook:ingress` permission and dropped for any route the
@@ -61,20 +65,34 @@ from disk is untrusted and sandboxed.
A worker still has access to Node built-ins — `require('fs')`, `process`, network sockets — and runs
as the same uid as OpenWA. The sandbox therefore does **not**, by itself, stop a malicious plugin
-from reading files the OpenWA process can read or making outbound network connections. It protects
-the _integrity_ of the host (no host-object compromise, contained faults, mediated capabilities) — not
-the _confidentiality_ of the host filesystem against deliberate Node-builtin abuse.
+from reading files the OpenWA process can read or making outbound network connections. What it does
+provide is narrower: the worker holds no references to host objects, its faults stay contained, and its
+`ctx.*` calls are mediated. Against a plugin that abuses Node built-ins deliberately, it protects neither
+the integrity nor the confidentiality of the host; see the reach list below.
-For genuinely untrusted, third-party plugins, combine the sandbox with **OS-level containment**:
+The bundled compose stack adds **OS-level containment** as defence in depth. It limits what the OpenWA
+process can do to the host; it does not confine a plugin away from anything that process can reach:
- **Run OpenWA in a container.** The image's entrypoint already drops to the non-root `openwa` user
(via `gosu`, after fixing volume ownership). The rest of the confinement comes from the bundled
`docker-compose.yml`, not from the image: `read_only: true` rootfs with a tmpfs `/tmp`,
`no-new-privileges`, and `cap_drop: ALL` with a minimal re-add
(`CHOWN`/`DAC_OVERRIDE`/`FOWNER`/`SETGID`/`SETUID`) that only the root entrypoint uses — once `gosu`
- setuids, the Node process keeps no effective capabilities. Together these bound what any plugin's
- `fs`/network access can reach; a plain `docker run` of the image gets none of the compose-level
- settings, so replicate them yourself if you deploy that way.
+ setuids, the Node process keeps no effective capabilities. A plain `docker run` of the image gets
+ none of the compose-level settings, so replicate them yourself if you deploy that way.
+- **What a loaded plugin can still reach.** Everything the OpenWA process can, including:
+ - the process environment through `/proc/self/environ` on Linux, with every secret the deployment
+ passes in (`API_MASTER_KEY`, `API_KEY_PEPPER`, `DATABASE_PASSWORD`, `REDIS_PASSWORD`). The worker's
+ allowlisted `process.env` keeps those secrets out of the object the plugin is handed, not out of
+ reach;
+ - the data volume: the SQLite database, session auth state and `data/.env.generated`;
+ - in the bundled compose stack, the `docker-proxy` sidecar at `tcp://docker-proxy:2375`, which can
+ create a container with a host bind-mount (see
+ [SECURITY.md](../SECURITY.md#docker-socket-proxy--scope-and-residual-risk)). If you do not use the
+ built-in datastore orchestration, disable the proxy with the `docker-compose.override.yml` recipe
+ in the `docker-proxy` comments of `docker-compose.yml`. The Helm chart ships no proxy.
+- **Plugins you do not fully trust** do not belong in the OpenWA process: run them in a separate
+ container or VM and reach OpenWA over its API like any other client.
- Until a marketplace exists, the standing guidance remains: **install only plugins you trust.**
A stronger isolation variant (child process with Node's permission model, or an `isolated-vm`) is a
@@ -97,7 +115,7 @@ in-process plugin that calls it fails loud rather than silently never firing —
no class instances with methods, no live references.**
3. **No ambient host access.** `require('fs')`/`process` etc. still exist in the worker but must not
be relied on as a capability — anything the plugin legitimately needs should be a declared
- capability, and OS containment may block direct access.
+ capability.
4. **Declare your permissions.** A capability call is denied unless the manifest declares it:
`messages:send` for `ctx.messages`, `engine:read` for `ctx.engine`, `net:fetch` for `ctx.net.fetch`
(plus a `net.allow` host list), `conversation:send` for `ctx.conversations` / `ctx.handover` /
diff --git a/src/core/plugins/plugin-loader.service.ts b/src/core/plugins/plugin-loader.service.ts
index a5702b5fc..482b4c34f 100644
--- a/src/core/plugins/plugin-loader.service.ts
+++ b/src/core/plugins/plugin-loader.service.ts
@@ -55,13 +55,15 @@ const SANDBOX_CAP_TIMEOUT_MS = 30000;
/**
* Host process.env keys an untrusted plugin worker is allowed to see. Everything else — secrets like
- * API_MASTER_KEY, API_KEY_PEPPER, the DATABASE_/REDIS_ vars, DOCKER_HOST — is withheld. The worker is
- * a thread, so it needs no PATH to start and require() resolves via module paths, not env.
+ * API_MASTER_KEY, API_KEY_PEPPER, the DATABASE_/REDIS_ vars, DOCKER_HOST — is left out of the worker's
+ * process.env object. That keeps secrets from being handed over ambiently; it does not put them out of
+ * reach, since a thread in the same OS process can read /proc/self/environ and the data directory. The
+ * worker is a thread, so it needs no PATH to start and require() resolves via module paths, not env.
*/
const SANDBOX_ENV_ALLOWLIST = ['NODE_ENV', 'NODE_EXTRA_CA_CERTS', 'TZ'] as const;
/**
- * Build the minimal, allowlisted env for an untrusted plugin worker so it never inherits host secrets.
+ * Build the minimal, allowlisted env for a plugin worker so its process.env never carries host secrets.
* Only {@link SANDBOX_ENV_ALLOWLIST} keys are forwarded (unset keys are omitted, not emitted as
* `undefined`), and NODE_ENV defaults to 'production' when the host has none.
*/
diff --git a/src/core/plugins/sandbox/protocol.ts b/src/core/plugins/sandbox/protocol.ts
index 78f82a185..90a573292 100644
--- a/src/core/plugins/sandbox/protocol.ts
+++ b/src/core/plugins/sandbox/protocol.ts
@@ -1,9 +1,10 @@
/**
- * Wire protocol between the host (PluginWorkerHost) and an untrusted plugin worker.
+ * Wire protocol between the host (PluginWorkerHost) and a plugin worker.
*
- * The worker has exactly one channel out — these messages — and no ambient access to the host. The
- * host validates every request before acting on it, so a hostile worker cannot escalate beyond what
- * its manifest declares.
+ * These messages are the worker's channel to the `ctx.*` capabilities, and the host validates every
+ * request against the manifest's permissions before acting on it. They are not the worker's only way
+ * out: the worker is a thread in the host process and can use Node built-ins directly, so this is
+ * fault containment, not a security boundary (see worker-bootstrap.ts and docs/30).
*
* Phase B1 scope: lifecycle only (load + onLoad/onEnable/onDisable/onUnload). The capability bridge
* (B2) and hook bridge (B3) add more message kinds later.
diff --git a/src/core/plugins/sandbox/worker-bootstrap.ts b/src/core/plugins/sandbox/worker-bootstrap.ts
index 30f22cd28..5ee7e3c4f 100644
--- a/src/core/plugins/sandbox/worker-bootstrap.ts
+++ b/src/core/plugins/sandbox/worker-bootstrap.ts
@@ -14,8 +14,10 @@ import { WorkerSearchRegistry, WorkerSearchHandler } from './worker-search-regis
* filesystem, and network credentials. It provides crash / heap-OOM CONTAINMENT, NOT a security
* boundary. Plugin code can `require('fs' | 'net' | 'child_process')` and reach the host's files and
* sockets directly — `parentPort` is NOT the worker's only channel out, and the capability permission
- * model gates only the `ctx.*` verbs, not raw Node access. Load only trusted plugin code, or run
- * OpenWA under an OS-level sandbox (container / seccomp) when untrusted plugins must be supported.
+ * model gates only the `ctx.*` verbs, not raw Node access. Load only plugin code you trust as much as
+ * OpenWA itself. OS-level containment of the OpenWA process limits what the process can do to the host,
+ * not what a plugin inside it can reach; run a plugin you do not fully trust in a separate container or
+ * VM against the API instead (see docs/30).
*/
interface LifecyclePlugin {