@qodalis/cli-server-node 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -1,5 +1,8 @@
 # Qodalis CLI Server (Node.js)
 
+[![npm @qodalis/cli-server-node](https://img.shields.io/npm/v/@qodalis/cli-server-node?label=%40qodalis%2Fcli-server-node)](https://www.npmjs.com/package/@qodalis/cli-server-node)
+[![npm @qodalis/cli-server-abstractions](https://img.shields.io/npm/v/@qodalis/cli-server-abstractions?label=%40qodalis%2Fcli-server-abstractions)](https://www.npmjs.com/package/@qodalis/cli-server-abstractions)
+
 A Node.js CLI server framework for the [Qodalis CLI](https://github.com/qodalis-solutions/web-cli) ecosystem. Build custom server-side commands that integrate with the Qodalis web terminal.
 
 ## Installation
@@ -303,11 +306,319 @@ The server exposes versioned endpoints:
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/cli/versions` | Version discovery (supported versions, preferred version) |
-| GET | `/api/v1/cli/version` | V1 server version |
-| GET | `/api/v1/cli/commands` | V1 commands (all processors) |
-| POST | `/api/v1/cli/execute` | V1 execute |
-| WS | `/ws/cli/events` | WebSocket events (also `/ws/v1/cli/events`) |
+| GET | `/api/qcli/versions` | Version discovery (supported versions, preferred version) |
+| GET | `/api/v1/qcli/version` | V1 server version |
+| GET | `/api/v1/qcli/commands` | V1 commands (all processors) |
+| POST | `/api/v1/qcli/execute` | V1 execute |
+| POST | `/api/v1/qcli/execute/stream` | V1 SSE streaming execute |
+| POST | `/api/qcli/mcp` | MCP endpoint (when the `mcp` option is on, see [MCP Endpoint](#mcp-endpoint)) |
+| WS | `/ws/qcli/events` | WebSocket events (also `/ws/v1/qcli/events`) |
+| WS | `/ws/v1/qcli/shell` | Interactive PTY shell session |
+
+`GET /capabilities` reports `shell: true|false` and, when the shell is enabled, `shellAuth: 'users' | 'token' | 'custom' | 'anonymous' | 'locked'`.
+
+## MCP Endpoint
+
+The server can expose **the whole system** to AI clients such as Claude Code over the [Model Context Protocol](https://modelcontextprotocol.io): CLI commands, the filesystem API, the data explorer, jobs and tools contributed by plugins, each with the same permissions as a CLI user. It works with or without the users plugin.
+
+### Enabling
+
+MCP is off by default. Enable it with the `mcp` option:
+
+```typescript
+const { app, mcp } = createCliServer({
+    mcp: true,                         // or an options object:
+    // mcp: {
+    //     tools: ['weather_*', 'echo'],  // allow-list (trailing * = prefix); default: every tool
+    //     exclude: ['fs_delete'],        // deny-list, applied after `tools`
+    //     token: process.env.MCP_TOKEN,  // only WITHOUT an auth provider: required bearer token
+    //     instructions: 'Each tool runs one command of this server.', // returned by initialize
+    //     enabled: true,                 // default true when the object is given
+    // },
+    configure: (builder) => builder.addProcessor(new CliEchoCommandProcessor()),
+});
+```
+
+### Route and transport
+
+- `POST /api/qcli/mcp` (`{basePath}/mcp`): MCP *Streamable HTTP*, **stateless** (no `Mcp-Session-Id`) and **JSON responses only** (no SSE). `GET`/`DELETE` → `405` with `Allow: POST`.
+- JSON-RPC 2.0: notifications → `202` with an empty body; malformed JSON → `-32700`, invalid request (including batches) → `-32600`, unknown method → `-32601`, bad params → `-32602` (JSON-RPC errors use HTTP 200).
+- Methods: `initialize` (protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26`; the client's version is echoed when supported, otherwise the newest), `ping`, `tools/list`, `tools/call`.
+- An `Origin` header, when present, must be in `allowedOrigins` or same-origin, otherwise `403` (DNS-rebinding protection; checked before authentication).
+
+### Authentication
+
+| Server | Access |
+|---|---|
+| users plugin mounted (`protectServer`) | a session or an [API token](plugins/users/README.md#api-tokens) (`Authorization: Bearer qcli_pat_…`) holding `commands:execute`; `401`/`403` as plain `{ "error": … }` responses. `tools/list` and `tools/call` only show the tools whose permissions the caller holds. `mcp.token` is ignored. |
+| no auth provider, `mcp.token` set | `Authorization: Bearer <token>` (constant-time compare), else `401` |
+| no auth provider, no token | open, like `/execute` |
+
+### Tools
+
+Tools are collected from **tool providers** on every request, so new registrations, enabled features and the caller's permissions are always current. The `tools`/`exclude` lists apply to every tool.
+
+| Provider | Tools | Permissions | Annotations |
+|---|---|---|---|
+| server | `server_info` (version, capabilities, enabled features, command names) | — | read-only |
+| commands | one tool per command (below) | `commands:execute` + `requiredPermissions` along the chain | — |
+| filesystem (when a file storage provider is configured) | `fs_list {path}`, `fs_stat {path}`, `fs_read {path, maxBytes?=262144}` | `files:read` | read-only |
+| | `fs_write {path, content}`, `fs_mkdir {path}` | `files:write` | — |
+| | `fs_delete {path, recursive?=false}` | `files:write` | destructive |
+| data explorer (when sources are registered) | `data_sources`, `data_schema {source}` | `data:query` | read-only |
+| | `data_query {source, query, parameters?}` | `data:query` | — |
+| jobs (when the jobs plugin is mounted) | `jobs_list`, `jobs_get {id}`, `jobs_history {id, limit?=20}` | `jobs:read` | read-only |
+| | `jobs_trigger`, `jobs_pause`, `jobs_resume`, `jobs_stop`, `jobs_cancel` `{id}` | `jobs:manage` | `jobs_stop`/`jobs_cancel` destructive |
+
+The jobs tools' `id` accepts a job id or a unique job name (exact, then case-insensitive; an ambiguous name is an error).
+
+Feature tools use the same services as the HTTP routes (the storage provider and its path checks, the data explorer executor with its timeouts and row limits, the job scheduler); their errors become `isError: true` results. `fs_read` returns UTF-8 text (binary files → `isError` `binary file, N bytes`). Paths outside the provider's allow-list are rejected exactly as by `/api/qcli/fs` (symlinks are resolved first, so on macOS allow `/private/tmp` rather than `/tmp`).
+
+**Command tools**: every root command and sub-command that has no sub-commands, declares parameters or takes a value (`valueRequired`, or `acceptsValue` for an optional one) becomes a tool named after its path joined with `_` (`weather`, `weather_current`), lower-cased, other characters than `[a-z0-9_-]` replaced by `-`, at most 64 characters. The input schema has one property per parameter (`string`, `number`, `boolean`, `array` of strings; anything else is a string) plus `value` (the positional input) when the command takes one: required with `valueRequired`, optional with `acceptsValue` (set it on processors that read `command.value` without requiring it; the built-in `hash`, `base64 encode|decode`, `http get|post` and the weather commands do). A call builds the same command the CLI would send and runs it through the **same executor as `/execute`**; the outputs are rendered as text (tables as `a | b` rows, lists one item per line, JSON pretty-printed, key-value as `key: value`), `isError` is `exitCode != 0`, and a single JSON-object output is also returned as `structuredContent`. Unknown tools and invalid arguments (wrong type, unknown or missing property) are JSON-RPC `-32602` errors.
+
+Name collisions (a warning is logged): built-in feature tools win, then plugin/host provider tools in registration order, then command tools. The interactive shell is never a tool.
+
+### Adding tools (providers)
+
+```typescript
+import { McpToolProvider, mcpObjectSchema } from '@qodalis/cli-server-node';
+
+const provider: McpToolProvider = {
+    name: 'inventory',
+    getTools: () => [
+        {
+            name: 'inventory_count',
+            description: 'Count the items of a warehouse',
+            inputSchema: mcpObjectSchema({ warehouse: { type: 'string' } }, ['warehouse']),
+            requiredPermissions: ['inventory:read'], // checked for list and call (with an auth provider)
+            annotations: { readOnlyHint: true },
+            call: async (args, { auth, signal }) => ({ text: `42 items in ${args.warehouse}`, isError: false }),
+        },
+    ],
+};
+
+const server = createCliServer({ mcp: true });
+server.mcp.addProvider(provider);            // or builder.addMcpToolProvider(provider) in `configure`
+// plugins can also return `mcpProviders: [provider]` from their build result (picked up by mountPlugin)
+```
+
+Arguments are validated against `inputSchema` before `call` runs. Return `structured` to also send `structuredContent`.
+
+### Using the MCP endpoint from an MCP client
+
+This guide connects [Claude Code](https://docs.claude.com/en/docs/claude-code) to a server. The commands use the demo server (`cd demo && npm start`: port 8047, users plugin, user `root` / password `admin`); replace the URL and credentials with yours.
+
+#### 1. Enable MCP on the server
+
+MCP is enabled with the `mcp` option of `createCliServer` (`mcp: true`, or an options object).
+
+With the users plugin (sessions, permissions, API tokens):
+
+```typescript
+import { createCliServer, CliEchoCommandProcessor } from '@qodalis/cli-server-node';
+import { CliUsersBuilder } from '@qodalis/cli-server-plugin-users';
+
+const { app, eventSocketManager, mountPlugin } = createCliServer({
+    mcp: { instructions: 'Each tool runs one command of this server.' },
+    configure: (builder) => builder.addProcessor(new CliEchoCommandProcessor()),
+});
+
+const usersPlugin = new CliUsersBuilder()
+    .setDefaultAdminPassword('admin')
+    .build((msg) => eventSocketManager.broadcastMessage(msg));
+mountPlugin(usersPlugin);
+
+app.listen(8047);
+```
+
+Without the users plugin, protect the endpoint with a static bearer token (without `token` it is as open as `/execute`):
+
+```typescript
+const { app } = createCliServer({
+    mcp: { token: process.env.QCLI_MCP_TOKEN },
+    configure: (builder) => builder.addProcessor(new CliEchoCommandProcessor()),
+});
+app.listen(8047);
+```
+
+The endpoint is `http://localhost:8047/api/qcli/mcp` (`{basePath}/mcp`).
+
+#### 2. Get a token
+
+With the users plugin, sign in and create an API token with the session token (requires `jq`; otherwise copy the `token` field of each response):
+
+```bash
+SESSION=$(curl -s -X POST http://localhost:8047/api/v1/qcli/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"username":"root","password":"admin"}' | jq -r .token)
+
+TOKEN=$(curl -s -X POST http://localhost:8047/api/v1/qcli/tokens \
+  -H "Authorization: Bearer $SESSION" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"claude","expiresInDays":30}' | jq -r .token)
+
+echo "$TOKEN"
+```
+
+The API token (`qcli_pat_…`) is shown only once. In the web CLI connected to the server, `token create claude` does the same. Add `"permissions": ["commands:execute", "files:read"]` to the body to give the token only part of your permissions; tokens are listed with `GET /api/v1/qcli/tokens` and revoked with `DELETE /api/v1/qcli/tokens/<id>` (see [API tokens](plugins/users/README.md#api-tokens)).
+
+Without the users plugin, the token is the `mcp.token` value.
+
+#### 3. Connect Claude Code
+
+**(a) Directly over HTTP** with the token:
+
+```bash
+claude mcp add --transport http qcli http://localhost:8047/api/qcli/mcp --header "Authorization: Bearer <token>"
+```
+
+**(b) Through the [`@qodalis/mcp-cli`](https://github.com/qodalis-solutions/mcp-cli) bridge**, a local MCP server configured with environment variables:
+
+```bash
+claude mcp add qcli -e QCLI_URL=http://localhost:8047 -e QCLI_TOKEN=<token> -- npx -y @qodalis/mcp-cli
+```
+
+Use `QCLI_USER` / `QCLI_PASSWORD` instead of `QCLI_TOKEN` to sign in with a user, and `QCLI_READ_ONLY=true` to expose only read-only tools.
+
+Check the connection with `claude mcp list` (or `/mcp` inside Claude Code); `qcli` should be listed as connected, with the tools of step 4.
+
+#### 4. Check the endpoint with curl
+
+Every request is one JSON-RPC message sent with `POST`; the server is stateless, so no session header is needed between calls.
+
+```bash
+# initialize
+curl -s http://localhost:8047/api/qcli/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
+
+# list the tools
+curl -s http://localhost:8047/api/qcli/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+
+# call a tool
+curl -s http://localhost:8047/api/qcli/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"value":"hello from MCP"}}}'
+```
+
+Responses (shortened):
+
+```json
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"qodalis-cli-server","version":"1.0.0-beta.7"},"instructions":"…"}}
+{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"server_info","description":"…","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false},"annotations":{"readOnlyHint":true}},{"name":"echo", …}, …]}}
+{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"hello from MCP"}],"isError":false}}
+```
+
+A failed command is a normal result with `"isError": true`; an unknown tool or invalid arguments is a JSON-RPC error (`-32602`).
+
+#### 5. Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `claude mcp list` / `/mcp` shows `qcli` as failed | Run the curl checks of step 4 with the same URL and token to see the HTTP error below. |
+| `401 {"error":"unauthorized"}` or `{"error":"invalid or expired token"}` | No `Authorization: Bearer …` header, or the token is wrong, expired or revoked, or its user is disabled or deleted: create a new token (step 2). Without the users plugin, check `mcp.token`. |
+| `403 {"error":"forbidden: origin not allowed"}` | The request has an `Origin` header that is neither in `allowedOrigins` nor the server's own origin (DNS-rebinding protection). Claude Code sends no `Origin`; for browser-based clients add the origin to `allowedOrigins`. |
+| `403 {"error":"forbidden: missing permission commands:execute"}` | The user, or the token's scope, lacks `commands:execute`, which the endpoint requires. Add it to one of the user's groups, or create a token whose scope includes it. |
+| `403 {"error":"password change required"}` | The user must change their password first. |
+| `404` | MCP is not enabled (`mcp` option) or the URL is not `{basePath}/mcp`. |
+| `405` with `Allow: POST` | The endpoint only accepts `POST` (MCP clients that probe with `GET` handle this). |
+| A tool is missing from `tools/list`, or `-32602 Unknown tool` | The user lacks one of the tool's permissions (`commands:execute` plus the command's `requiredPermissions`, `files:read`/`files:write`, `data:query`, `jobs:read`/`jobs:manage`); the token's scope narrows them further; `mcp.tools` / `mcp.exclude` filter it out; or the feature is not enabled on the server (file storage, data explorer sources, jobs plugin). A command whose parameters all live on its sub-commands appears only as `<command>_<sub>` tools. |
+
+## Remote Shell Security
+
+The PTY shell (`/ws/v1/qcli/shell`, `/ws/qcli/shell`) gives OS-level access to the server. It is **off** unless `enableShell: true`. When enabled, exactly one access mode applies:
+
+| Mode (`shellAuth`) | When | Client must |
+|---|---|---|
+| `users` | the users plugin is mounted | connect with a WS ticket (`?ticket=`) of a session holding `shell:execute` |
+| `token` | no users plugin, `shell.token` set | send `Authorization: Bearer <token>` (header, or the `_header_Authorization` query parameter) |
+| `custom` | no users plugin, `shell.authorize` set | pass the host's `authorize(request, { url, remoteAddress, mode })` check |
+| `anonymous` | no users plugin, `shell.allowAnonymous: true` | nothing (a startup WARNING is logged) |
+| `locked` | none of the above | — every connection is closed with 4401 and a startup ERROR explains the options |
+
+Precedence: users plugin mounted (even with `protectServer: false`) ⇒ `users`; otherwise `token`, then `custom`, then `anonymous`. Whatever the mode, **every configured check among `token` and `authorize` must pass** (so with both set, both are required and `shellAuth` reports `token`); `allowAnonymous` is ignored once either is set. Tokens are compared in constant time (SHA-256 of both, then `timingSafeEqual`) and never logged; an `authorize` that throws or rejects denies.
+
+### With the users plugin
+
+```typescript
+const { mountPlugin, eventSocketManager } = createCliServer({ enableShell: true });
+mountPlugin(new CliUsersBuilder().build((m) => eventSocketManager.broadcastMessage(m)));
+// Grant shell:execute to a group (root/admin has '*'):
+//   PUT /api/v1/qcli/groups/ops  { "permissions": ["commands:execute", "shell:execute"] }
+```
+
+An open shell is bound to the session that opened it: logout, idle/absolute session expiry, admin revoke (kick), user disabled or deleted, or losing `shell:execute` (checked once more right after the shell is registered and before it is spawned, so a logout racing the open is not missed; then immediately on session/user/group changes and every `sessionCheckIntervalMs`, default 30 s, max 60 s), or a password change becoming required closes it with **4401** `session ended` and kills its process tree. Users authenticated by an external auth adapter have no stored session: their shells are re-checked by calling the adapter again with the shell's original upgrade request (see the users plugin README). Re-checks never extend the session by themselves; stdin received since the previous check counts as session activity (at most one touch per 30 s), so an active shell user is not idle-logged-out. Opens and closes are audited as `shell_opened` / `shell_closed` (`userId`, `actorId`, `metadata: { mode: 'interactive' | 'command', sessionId, durationMs, reason, exitCode? }`), never with the command text or stdin. `reason` is one of `exited` (then `exitCode` is set), `closed`, `session ended`, `permission removed`, `shell timed out`, `server shutdown`, `error`.
+
+### Without the users plugin (token mode)
+
+```typescript
+createCliServer({
+    enableShell: true,
+    shell: { token: process.env.QCLI_SHELL_TOKEN },   // long random secret
+});
+```
+
+Browser clients cannot set WebSocket headers: configure the server in web-cli with `headers: { Authorization: 'Bearer <token>' }` and the client forwards it as `?_header_Authorization=Bearer%20<token>`. The standalone server (`src/server.ts`) enables token mode when `QCLI_SHELL_TOKEN` is set. Use HTTPS/WSS so the token is not sent in clear text.
+
+For your own scheme (reverse-proxy identity, IP allow-list, …) use `authorize`:
+
+```typescript
+createCliServer({
+    enableShell: true,
+    shell: { authorize: async (req, { remoteAddress }) => remoteAddress === '127.0.0.1' && req.headers['x-ops'] === 'yes' },
+});
+```
+
+Non-users modes log one info line per open/close (remote address, mode, reason) without the command text.
+
+### Options
+
+```typescript
+shell: {
+    token?: string;                    // token mode (or extra requirement with the users plugin)
+    authorize?: (req, ctx) => boolean | Promise<boolean>;  // custom mode (or extra requirement)
+    allowAnonymous?: boolean;          // open to anyone who can reach the server (not recommended)
+    maxSessionsPerUser?: number;       // per user (users mode) or per remote address (default 3; X-Forwarded-For only with trustProxy)
+    maxSessions?: number;              // total concurrent shells (default 20)
+    idleTimeoutMs?: number;            // close after no stdin (resize does not count; default 15 min, 0 = off)
+    maxDurationMs?: number;            // absolute limit (default none)
+    sessionCheckIntervalMs?: number;   // users-mode re-check (default 30 000, max 60 000)
+    cwd?: string;                      // working directory (default: home directory)
+    shell?: string;                    // shell binary (default: detected)
+    env?: { allow?: string[]; set?: Record<string, string> };
+}
+```
+
+The shell does **not** inherit the server environment: it gets only `PATH`, `HOME`, `USER`, `LANG`, `TERM`, `COLUMNS`, `LINES`, `SHELL` (plus the variables Windows needs to start PowerShell), the names in `env.allow`, and `env.set`. Secrets such as database passwords stay out of the shell.
+
+### Process cleanup
+
+Whenever a shell ends (exit, client close, session ended or permission removed, timeout, server shutdown), the server first collects everything the shell started — its process group, its descendants by parent PID (including background jobs that interactive shells move to their own process groups, and `setsid`/`nohup` children), on Linux every process of its session, and every process tagged with the shell's marker (below) — and then sends SIGHUP, SIGTERM and, after a 1 s grace period, SIGKILL to all of them (re-collecting before the SIGKILL). The server's own process and process group are never targeted. Linux reads `/proc` for everything (no `ps` needed); macOS and other Unixes run `ps`. On Windows only the shell process is killed.
+
+Every shell gets a unique marker in its environment, `QCLI_SHELL_ID=<random 128-bit hex>`, added after the `env.allow`/`env.set` filtering so configuration can neither override nor remove it. Children inherit it, so processes that were re-parented to init *and* left the shell's process group and session — e.g. `setsid sleep 100 &` from an interactive shell, double-forking daemons — are still found: on Linux by reading `/proc/<pid>/environ`, on macOS through `ps -A -E -ww` (which shows the environment of the server user's processes).
+
+Limitations: a process escapes only if it deliberately unsets or changes `QCLI_SHELL_ID` before detaching (`env -u QCLI_SHELL_ID setsid …`), or runs as a different user whose environment the server cannot read (e.g. via `sudo`). On macOS the environment of Apple platform binaries (`/bin/sleep`, `/usr/bin/perl`, …) is hidden from `ps -E`, so such a binary that left the shell's tree and session is not found there either. Run the server in a container or under a service manager (cgroup) if every process must be contained.
+
+### Close codes
+
+Refusals are sent as *accept, then close* so browsers can read them (a foreign `Origin` is still rejected with HTTP 403):
+
+| Code | Reason | When |
+|---|---|---|
+| 4401 | `login required` / `session ended` / `shell access is not configured` | missing ticket or (Bearer) token; session ended (logout, expiry, kick, user disabled/deleted, `shell:execute` removed, password change now required) — shell, events and logs sockets; shell locked |
+| 4403 | `forbidden` | wrong token, `authorize` false or threw, no `shell:execute`, password change required |
+| 4404 | `shell disabled` | `enableShell` is false |
+| 4408 | `shell timed out` | idle timeout or `maxDurationMs` |
+| 4429 | `too many shell sessions` | `maxSessionsPerUser` or `maxSessions` reached |
+| 1001 | `server shutdown` | the server is shutting down |
 
 ## Processor Base Class Reference
 
@@ -322,6 +633,7 @@ The server exposes versioned endpoints:
 | `processors` | `ICliCommandProcessor[]` | `undefined` | Sub-commands |
 | `allowUnlistedCommands` | `boolean` | `undefined` | Accept sub-commands not in `processors` |
 | `valueRequired` | `boolean` | `undefined` | Require a positional value |
+| `acceptsValue` | `boolean` | `undefined` | Reads an optional positional value (`command.value`); MCP exposes it as an optional `value` argument |
 | `version` | `string` | `'1.0.0'` | Processor version string |
 | `author` | `ICliCommandAuthor` | default author | Author metadata (name, email) |
 
@@ -329,12 +641,26 @@ The server exposes versioned endpoints:
 
 ```typescript
 interface CliServerOptions {
-    basePath?: string;                     // API base path (default: '/api/cli')
-    cors?: boolean | cors.CorsOptions;     // CORS config (default: false)
+    basePath?: string;                     // API base path (default: '/api/qcli')
+    cors?: boolean | cors.CorsOptions;     // CORS config (default: only allowedOrigins; off when none)
+    allowedOrigins?: string[];             // CORS + WebSocket Origin allow-list ('http://host:*' = any port)
+    enableShell?: boolean;                 // Interactive shell WebSocket (default: false)
+    shell?: CliShellOptions;               // Shell access mode, limits, timeouts, env (see Remote Shell Security)
+    trustProxy?: boolean | number;         // Trusted proxy hops for X-Forwarded-* (true = 1; default false = none)
+    auth?: ICliServerAuth;                 // Protect the whole server (e.g. usersPlugin.serverAuth)
+    mcp?: boolean | CliMcpOptions;         // MCP endpoint at {basePath}/mcp (default off, see MCP Endpoint)
     configure?: (builder: CliBuilder) => void;  // Processor registration
 }
 ```
 
+CORS is disabled unless `allowedOrigins` (or an explicit `cors` option) is given. The shell socket is off unless `enableShell: true`, and even then it is locked until an access mode applies (see [Remote Shell Security](#remote-shell-security)).
+
+Same-origin requests (e.g. the bundled admin dashboard at `/qcli/admin`) are always allowed by the Origin, CORS and CSRF checks, even when `allowedOrigins` does not list the server's own origin (`X-Forwarded-Proto`/`X-Forwarded-Host` are honoured only with `trustProxy`, and read like `X-Forwarded-For`: the entry at index `len - hops`, the leftmost when the list is shorter, an empty entry ignored).
+
+`trustProxy` is the number of trusted reverse-proxy hops in front of the server (`true` = 1, `false`/`0`/absent = none). With n hops the client IP (Express `req.ip`, the shell's per-address limits) is the `X-Forwarded-For` entry at index `len - n` of the comma-separated list, i.e. with one hop the rightmost entry, appended by your proxy; the leftmost entries are client-controlled and never used unless the list is shorter than n. Without the header (or when the selected entry is empty) the socket address is used. Set it to the exact number of proxies you run, otherwise clients can spoof their IP.
+
+When the users plugin is mounted (`mountPlugin(usersPlugin)`) or passed as `auth`, every `/api/...` route and every WebSocket requires a users session (see [Users Plugin](#users-plugin)); without it the server behaves as before.
+
 `createCliServer()` returns:
 
 ```typescript
@@ -342,7 +668,12 @@ interface CliServerOptions {
     app: Express;                          // Configured Express app
     registry: CliCommandRegistry;          // Processor registry
     builder: CliBuilder;                   // Registration builder
-    eventSocketManager: CliEventSocketManager;  // WebSocket manager
+    executor: CliCommandExecutorService;   // Command executor
+    eventSocketManager: CliEventSocketManager;  // WebSocket event manager
+    logSocketManager: CliLogSocketManager;      // WebSocket log manager
+    mountPlugin(plugin: MountablePlugin): void; // Mount a plugin with its routes (installs plugin.serverAuth)
+    setAuth(auth?: ICliServerAuth): void;       // Install/remove the server auth provider
+    mcp: CliServerMcp;                          // MCP endpoint: { enabled, path, addProvider(provider) }
 }
 ```
 
@@ -391,19 +722,19 @@ import {
 
 ## File Storage
 
-The server includes a pluggable file storage system exposed at `/api/cli/fs/*`. Enable it with `setFileStorageProvider()` and choose a storage backend.
+The server includes a pluggable file storage system exposed at `/api/qcli/fs/*`. Enable it with `setFileStorageProvider()` and choose a storage backend.
 
 ### Filesystem API Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/cli/fs/ls?path=/` | List directory contents |
-| GET | `/api/cli/fs/cat?path=/file.txt` | Read file content |
-| GET | `/api/cli/fs/stat?path=/file.txt` | File/directory metadata |
-| GET | `/api/cli/fs/download?path=/file.txt` | Download file |
-| POST | `/api/cli/fs/upload` | Upload file (multipart) |
-| POST | `/api/cli/fs/mkdir` | Create directory |
-| DELETE | `/api/cli/fs/rm?path=/file.txt` | Delete file or directory |
+| GET | `/api/qcli/fs/ls?path=/` | List directory contents |
+| GET | `/api/qcli/fs/cat?path=/file.txt` | Read file content |
+| GET | `/api/qcli/fs/stat?path=/file.txt` | File/directory metadata |
+| GET | `/api/qcli/fs/download?path=/file.txt` | Download file |
+| POST | `/api/qcli/fs/upload` | Upload file (multipart) |
+| POST | `/api/qcli/fs/mkdir` | Create directory |
+| DELETE | `/api/qcli/fs/rm?path=/file.txt` | Delete file or directory |
 
 ### Storage Providers
 
@@ -615,6 +946,40 @@ All commands support `--region` (`-r`) for region override and `--output` (`-o`)
 
 See [`plugins/aws/README.md`](plugins/aws/README.md) for the full command reference.
 
+### Users Plugin
+
+The users plugin (`@qodalis/cli-server-plugin-users`) adds REST endpoints under `/api/v1/qcli` for authentication, users, groups with permissions, sessions and an audit log, with swappable storage (in-memory by default). It is the server side of the `@qodalis/cli-users` browser plugin's *server mode*.
+
+```typescript
+import { CliUsersBuilder } from '@qodalis/cli-server-plugin-users';
+
+const usersPlugin = new CliUsersBuilder()
+    .build((msg) => eventSocketManager.broadcastMessage(msg));
+mountPlugin(usersPlugin); // protects the whole server (protectServer: true)
+```
+
+Once mounted, every server route and socket requires a users session (login, version discovery and capabilities stay public):
+
+| Surface | Permission |
+|---|---|
+| `GET /commands` | authenticated |
+| `POST /execute`, `/execute/stream` | `commands:execute` + the processor's `requiredPermissions` |
+| `POST /api/qcli/mcp` | `commands:execute` (each tool then checks its own permissions) |
+| fs `ls`/`cat`/`stat`/`download` | `files:read` |
+| fs `upload`/`mkdir`/`rm` | `files:write` |
+| data explorer | `data:query` |
+| jobs read / manage | `jobs:read` / `jobs:manage` |
+| events / logs / shell WebSocket | authenticated / `logs:read` / `shell:execute` (see [Remote Shell Security](#remote-shell-security)) |
+| admin dashboard | `admin:access` |
+
+WebSockets authenticate with a single-use ticket: `POST /api/v1/qcli/sessions/ws-ticket` → `{ ticket, expiresIn: 30 }`, then connect with `?ticket=<ticket>`. Host routes can use `usersPlugin.requireAuth()` / `usersPlugin.requirePermission('perm')`. Processors declare `requiredPermissions: ['deploy:run']` to be enforced server-side.
+
+Events and logs sockets authenticated with a stored session are bound to it: when the session ends (logout, revoke/kick, user disabled or deleted, a password change becoming required, idle/absolute expiry) the socket is closed with **4401** `session ended`; for a revoke the events socket first receives `session-kicked`. Bound sockets are re-checked on every session/user/group change and after each expired-session sweep (`setCleanupInterval`, default 5 minutes). Sockets authenticated by an external auth adapter have no stored session and are not re-checked.
+
+API tokens (`qcli_pat_…`) are long-lived, revocable bearer tokens for MCP clients, CI and scripts; they are accepted wherever a session token is (see [API tokens](plugins/users/README.md#api-tokens)). Sockets opened with a token identity close with 4401 when the token is revoked or expires, or the user is disabled.
+
+See [`plugins/users/README.md`](plugins/users/README.md) for options, endpoints, API tokens, custom storage and external auth adapters.
+
 ## Built-in Processors
 
 These processors ship with the library and are included in the standalone server:
@@ -627,7 +992,6 @@ These processors ship with the library and are included in the standalone server
 | `http` | HTTP request operations |
 | `hash` | Hash computation (MD5, SHA1, SHA256, SHA512) |
 | `base64` | Base64 encode/decode (sub-commands) |
-| `uuid` | UUID generation |
 
 ## Docker
 
@@ -663,10 +1027,22 @@ packages/
       cli-command-parameter-descriptor.ts  # Parameter declaration
       cli-command-author.ts           # Author metadata
 plugins/
+  admin/                              # Admin dashboard plugin (auth, status, config, logs)
+  aws/                                # AWS cloud services (S3, EC2, Lambda, CloudWatch, etc.)
+  data-explorer/                      # Core data explorer abstraction
+  data-explorer-sql/                  # SQL data explorer provider (SQLite)
+  data-explorer-mongo/                # MongoDB data explorer provider
+  data-explorer-postgres/             # PostgreSQL data explorer provider
+  data-explorer-mysql/                # MySQL data explorer provider
+  data-explorer-mssql/                # MS SQL data explorer provider
+  data-explorer-redis/                # Redis data explorer provider
+  data-explorer-elasticsearch/        # Elasticsearch data explorer provider
   filesystem/                         # Core file storage abstraction (IFileStorageProvider, InMemory, OS)
   filesystem-json/                    # JSON file persistence provider
   filesystem-sqlite/                  # SQLite persistence provider (better-sqlite3)
   filesystem-s3/                      # Amazon S3 storage provider (@aws-sdk/client-s3)
+  jobs/                               # Job scheduling plugin
+  users/                              # Users plugin (auth, sessions, groups, audit)
   weather/                            # Weather module (example plugin)
 src/
   abstractions/                       # Re-exports from @qodalis/cli-server-abstractions
@@ -679,9 +1055,11 @@ src/
     cli-command-executor-service.ts   # Command execution pipeline
     cli-response-builder.ts           # Structured output builder
     cli-event-socket-manager.ts       # WebSocket event broadcasting
+    cli-log-socket-manager.ts         # WebSocket log streaming
+    cli-shell-session-manager.ts      # PTY shell session management
   controllers/
-    cli-controller.ts                 # V1 REST API (/api/v1/cli)
-    cli-version-controller.ts         # Version discovery (/api/cli/versions)
+    cli-controller.ts                 # V1 REST API (/api/v1/qcli)
+    cli-version-controller.ts         # Version discovery (/api/qcli/versions)
   extensions/
     cli-builder.ts                    # Fluent registration API (addProcessor, addModule)
   processors/                         # Built-in processors

package/dist/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@qodalis/cli-server-node",
+    "version": "1.0.0-beta.7",
+    "description": "Node.js CLI server for Qodalis CLI ecosystem — use as a library in existing Express apps or run standalone",
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "bin": {
+        "qodalis-cli-server": "dist/src/server.js"
+    },
+    "files": [
+        "dist",
+        "!dist/src/__tests__",
+        "!dist/plugins",
+        "LICENSE",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "start": "tsx src/server.ts",
+        "dev": "tsx watch src/server.ts",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "keywords": [
+        "cli",
+        "qodalis",
+        "terminal",
+        "commands",
+        "cli-server",
+        "command-processor"
+    ],
+    "author": "Nicolae Lupei <nicolae.lupei@qodalis.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/qodalis-solutions/cli-server-node"
+    },
+    "homepage": "https://qodalis.com/",
+    "dependencies": {
+        "@qodalis/cli-server-abstractions": "file:packages/abstractions",
+        "@qodalis/cli-server-plugin-data-explorer": "file:plugins/data-explorer",
+        "@qodalis/cli-server-plugin-filesystem": "file:plugins/filesystem",
+        "@qodalis/cli-server-plugin-jobs": "file:plugins/jobs",
+        "cors": "^2.8.5",
+        "express": "^4.21.0",
+        "multer": "^2.1.0",
+        "node-pty": "^1.1.0",
+        "ws": "^8.18.0"
+    },
+    "optionalDependencies": {
+        "@elastic/elasticsearch": "^8.16.0",
+        "@qodalis/cli-server-plugin-filesystem-json": "file:plugins/filesystem-json",
+        "@qodalis/cli-server-plugin-filesystem-s3": "file:plugins/filesystem-s3",
+        "@qodalis/cli-server-plugin-filesystem-sqlite": "file:plugins/filesystem-sqlite",
+        "better-sqlite3": "^11.10.0",
+        "ioredis": "^5.4.0",
+        "mongodb": "^6.0.0",
+        "mssql": "^11.0.0",
+        "mysql2": "^3.11.0",
+        "pg": "^8.13.0"
+    },
+    "devDependencies": {
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/cors": "^2.8.17",
+        "@types/express": "^4.17.21",
+        "@types/mssql": "^9.1.9",
+        "@types/multer": "^2.0.0",
+        "@types/node": "^22.0.0",
+        "@types/pg": "^8.0.0",
+        "@types/supertest": "^7.2.0",
+        "@types/ws": "^8.5.13",
+        "supertest": "^7.2.2",
+        "tsx": "^4.19.0",
+        "typescript": "^5.6.0",
+        "vitest": "^4.0.18"
+    }
+}

package/dist/src/auth/cli-server-auth-gate.d.ts

@@ -0,0 +1,33 @@
+import { RequestHandler } from 'express';
+import { ICliCommandRegistry } from '../services/cli-command-registry';
+import { CliServerAuthContext, ICliServerAuth } from './cli-server-auth';
+declare global {
+    namespace Express {
+        interface Request {
+            /** Set by the server auth gate when the users plugin protects the server. */
+            qcliServerAuth?: CliServerAuthContext;
+        }
+    }
+}
+/** Normalizes a request path for classification: lower-case, single slashes, no trailing slash. */
+export declare function normalizePath(path: string): string;
+export interface ServerAuthGateOptions {
+    registry: ICliCommandRegistry;
+    /** Prefixes serving the CLI controller (`/api/v1/qcli`, custom basePath). */
+    cliPrefixes: string[];
+    /** Extra public routes as `"METHOD /path"` (e.g. a plugin's own login). */
+    publicRoutes: Set<string>;
+    /** MCP endpoint paths (normalized), requiring `commands:execute`. */
+    mcpPaths?: string[];
+}
+/** Collects `requiredPermissions` along the resolved processor chain. */
+export declare function processorPermissions(registry: ICliCommandRegistry, command: unknown, chain: unknown): string[];
+/** Permissions required for a (protected) server route. */
+export declare function requiredServerPermissions(method: string, path: string, body: any, options: ServerAuthGateOptions): string[];
+/**
+ * Express middleware protecting every `/api/...` route of the CLI server when
+ * an auth provider with `protectServer` is installed. Without a provider it is
+ * a no-op, so servers without the users plugin behave as before.
+ */
+export declare function createServerAuthGate(getAuth: () => ICliServerAuth | undefined, options: ServerAuthGateOptions): RequestHandler;
+//# sourceMappingURL=cli-server-auth-gate.d.ts.map

package/dist/src/auth/cli-server-auth-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-server-auth-gate.d.ts","sourceRoot":"","sources":["../../../src/auth/cli-server-auth-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAA6B,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKpG,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,OAAO,CAAC;QACd,UAAU,OAAO;YACb,6EAA6E;YAC7E,cAAc,CAAC,EAAE,oBAAoB,CAAC;SACzC;KACJ;CACJ;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAgBD,MAAM,WAAW,qBAAqB;IAClC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2EAA2E;IAC3E,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,GACf,MAAM,EAAE,CAkBV;AAED,2DAA2D;AAC3D,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAoB3H;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,MAAM,cAAc,GAAG,SAAS,EACzC,OAAO,EAAE,qBAAqB,GAC/B,cAAc,CAkDhB"}