This is a follow-up to my previous security notice regarding @bananacool467/ui-tools.
The previous affected releases were 0.1.0-beta through 0.1.8-beta, where the optional useTerminal functionality exposed a server-side interactive terminal without the intended authentication boundary.
That was a security vulnerability.
It was not an intentionally deployed backdoor or malware payload.
The terminal functionality itself is intentional. @bananacool467/ui-tools is not intended to be a frontend-only component library; it contains various development and UI utilities, including an optional server-side terminal interface.
What happened?
The terminal feature uses a PTY to provide an interactive shell through a WebSocket connection.
In the affected releases, the WebSocket endpoint did not properly require authentication before accepting the connection.
This meant that if the endpoint was reachable by an untrusted user, that user could potentially interact with the server-side PTY without authorization.
The security problem was the missing authentication boundary, not the existence of the terminal functionality itself.
This issue was associated with security reporting such as MAL-2026-13416, which identified the affected package/release behavior as a serious remote command-execution risk.
0.1.9-beta: Authentication Added
In 0.1.9-beta, authentication was added before the WebSocket upgrade.
The server authenticates the request before calling handleUpgrade(). An unauthenticated request receives an HTTP 401 Unauthorized response instead of being upgraded into a WebSocket connection.
The terminal can use the built-in token authentication or an application's own authentication callback.
This addressed the immediate vulnerability.
However, I did not consider simply adding token authentication to be sufficient hardening for a server-side interactive terminal.
That is why 0.2.0-beta adds additional security controls.
0.2.0-beta: Defense in Depth
0.2.0-beta further hardens the terminal functionality with multiple layers of protection.
Authentication
Authentication is required before the WebSocket connection is established.
Applications can either use the configured terminal token or provide their own authentication function.
Custom authentication can also associate an authenticated connection with a user identity.
Session Ownership
Terminal sessions now have an associated user ID.
When a client attempts to reconnect to an existing session, the authenticated user's ID is checked against the session owner.
A user cannot simply provide another user's session ID and take over their terminal session.
Localhost Restriction
restrictToLocalhost can restrict terminal access to localhost connections.
This is enabled by default.
This is particularly useful for development tools where the terminal should never be exposed to the network.
Origin Allowlisting
strictTerminal and allowedOrigins can restrict which origins are permitted to access the terminal endpoint.
This provides another access-control layer for deployments where the terminal needs to be reachable remotely.
HTTPS Requirement
When localhost restriction is disabled, the terminal requires a secure HTTPS connection.
This helps prevent credentials from being transmitted over an unencrypted remote connection.
Message Size Limits
Incoming WebSocket messages are bounded to prevent excessively large messages from being sent to the terminal.
The current maximum message size is 64 KB.
Connection and Session Limits
maxConnections limits the number of simultaneous WebSocket connections.
maxSessions limits the number of active terminal sessions.
These controls reduce the ability of the terminal endpoint to consume unbounded resources.
Session Lifetime
Terminal sessions have a maximum lifetime.
Sessions are automatically terminated after the configured lifetime rather than being allowed to exist indefinitely.
Environment Restrictions
strictEnv and env provide control over which environment variables are passed into the terminal process.
This can be useful when the terminal is intended to run with a deliberately restricted environment instead of inheriting the entire server process environment.
Optional VM Integration
The terminal can also be configured to start a different command through startupShell and startupShellArgs.
This can be used to integrate the terminal with an isolated environment such as a virtual machine.
However, VM isolation should be configured securely by the application using it; simply launching a VM process does not automatically guarantee complete sandboxing.
Why wasn't the terminal removed?
Because the terminal is an intentional feature.
A server-side terminal is inherently powerful because its purpose is to execute commands. The security requirement is therefore to make sure that only authorized users can access it and that the deployment can impose additional restrictions where necessary.
Removing the feature would remove functionality that ui-tools intentionally provides.
Instead, the security model has been strengthened around it.
Version Guidance
- 0.1.0-beta – 0.1.8-beta: Affected by the unauthenticated terminal vulnerability. Upgrade immediately.
- 0.1.9-beta: Adds authentication before the WebSocket upgrade.
- 0.2.0-beta and newer: Includes additional defense-in-depth controls around authentication, authorization, sessions, origins, connections, messages, environment handling, and terminal lifetime.
If you are currently using an affected release, upgrade to a current version rather than continuing to use the unauthenticated implementation.
Final Clarification
The existence of a server-side PTY does not by itself make a package a backdoor.
The terminal functionality was intentionally implemented as a developer feature.
The security issue was that the intended authentication/authorization boundary was missing in the affected releases.
0.1.9-beta addressed that immediate vulnerability, and 0.2.0-beta continues the work with additional security controls because I did not believe a single token check was enough for a feature with this level of privilege.
Security issues happen. What matters is identifying them, documenting them accurately, fixing them, and continuing to improve the security model.
