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

package/dist/src/services/cli-shell-session-manager.js

@@ -35,10 +35,16 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CliShellSessionManager = void 0;
 const ws_1 = require("ws");
+const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const logger_1 = require("../utils/logger");
+const cli_server_auth_1 = require("../auth/cli-server-auth");
+const cli_shell_options_1 = require("./cli-shell-options");
+const process_tree_1 = require("./process-tree");
 const logger = (0, logger_1.createLogger)('ShellSession');
+/** Longest delay `setTimeout` supports (~24.8 days); longer ones fire immediately. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
 /**
  * Lazy-loads node-pty to avoid import failures when the native add-on is unavailable.
  * @throws {Error} If node-pty cannot be loaded.
@@ -56,16 +62,210 @@ function getPty() {
     }
     return _pty;
 }
-/** Manages interactive PTY shell sessions over WebSocket connections. */
+/**
+ * Manages interactive PTY shell sessions over WebSocket connections and
+ * enforces Appendix C: access mode, session binding, limits, timeouts,
+ * minimal environment and audit.
+ */
 class CliShellSessionManager {
+    _options;
+    _enabled;
+    _auth;
+    _unsubscribe;
+    _sessions = new Set();
+    _nextId = 1;
+    _checkTimer;
+    _trustProxy;
+    constructor(options = {}) {
+        this._enabled = options.enabled ?? false;
+        this._options = options.shell ?? {};
+        this._trustProxy = options.trustProxy ?? false;
+    }
     /**
-     * Creates a PTY shell session bridged to the given WebSocket.
-     * @param ws - WebSocket connection for the shell session.
-     * @param cols - Initial terminal width in columns.
-     * @param rows - Initial terminal height in rows.
-     * @param command - Optional command to execute instead of an interactive shell.
+     * Trusted reverse-proxy hops (`true` = 1): the remote address is the
+     * `X-Forwarded-For` entry at index `len - hops` (`false`/0: the socket address).
      */
-    async handleSession(ws, cols, rows, command) {
+    setTrustProxy(trust) {
+        this._trustProxy = trust;
+    }
+    get enabled() {
+        return this._enabled;
+    }
+    setEnabled(enabled) {
+        this._enabled = enabled;
+    }
+    get options() {
+        return this._options;
+    }
+    setOptions(options) {
+        this._options = options ?? {};
+    }
+    /** Current access mode (`undefined` while the shell is disabled). */
+    get authMode() {
+        return this._enabled ? (0, cli_shell_options_1.resolveShellAuthMode)(this._options, !!this._auth) : undefined;
+    }
+    /** Installs the auth provider (users plugin); subscribes to its session events. */
+    setAuth(auth) {
+        if (auth === this._auth)
+            return;
+        this._unsubscribe?.();
+        this._unsubscribe = undefined;
+        this._auth = auth;
+        if (auth?.onSessionEvent) {
+            this._unsubscribe = auth.onSessionEvent((event) => this.onSessionEvent(event));
+        }
+    }
+    /** Logs the startup state: ERROR when locked, WARNING when anonymous. */
+    logStartupState() {
+        const mode = this.authMode;
+        if (mode === 'locked') {
+            logger.error('Shell is enabled but no access mode is configured, so it is LOCKED (every connection is refused). ' +
+                'Mount the users plugin (shell:execute permission), or set shell.token, shell.authorize, ' +
+                'or shell.allowAnonymous (not recommended).');
+        }
+        else if (mode === 'anonymous') {
+            logger.warn('WARNING: shell is enabled without authentication (shell.allowAnonymous). Anyone who can reach this server gets a shell.');
+        }
+        else if (mode) {
+            logger.info('Shell enabled (auth=%s)', mode);
+        }
+    }
+    /** Open sessions. */
+    getSessions() {
+        return [...this._sessions].map((s) => ({
+            id: s.id,
+            authMode: s.authMode,
+            mode: s.mode,
+            remoteAddress: s.remoteAddress,
+            userId: s.ctx?.userId,
+            userName: s.ctx?.userName,
+            sessionId: s.ctx?.sessionId,
+            startedAt: new Date(s.startedAt).toISOString(),
+        }));
+    }
+    /**
+     * Takes over an accepted shell WebSocket: authorizes it (closing with
+     * 4401/4403/4404/4429 when refused), then bridges it to a PTY.
+     */
+    async accept(ws, request, url) {
+        if (!this._enabled) {
+            ws.close(cli_shell_options_1.ShellCloseCodes.Disabled, 'shell disabled');
+            return;
+        }
+        const cols = clampDim(url.searchParams.get('cols'), 80);
+        const rows = clampDim(url.searchParams.get('rows'), 24);
+        const command = url.searchParams.get('cmd') || undefined;
+        const mode = command ? 'command' : 'interactive';
+        const remoteAddress = this.remoteAddressOf(request);
+        const authMode = (0, cli_shell_options_1.resolveShellAuthMode)(this._options, !!this._auth);
+        let decision;
+        try {
+            decision = await this.authorize(authMode, request, url, remoteAddress, mode);
+        }
+        catch {
+            decision = { ok: false, code: cli_shell_options_1.ShellCloseCodes.Forbidden, reason: 'forbidden' };
+        }
+        if (!decision.ok) {
+            closeWs(ws, decision.code, decision.reason);
+            return;
+        }
+        if (ws.readyState !== ws_1.WebSocket.OPEN)
+            return;
+        const limitKey = authMode === 'users' ? `user:${decision.ctx.userId}` : `addr:${remoteAddress}`;
+        const perUser = this._options.maxSessionsPerUser ?? cli_shell_options_1.SHELL_DEFAULTS.maxSessionsPerUser;
+        const total = this._options.maxSessions ?? cli_shell_options_1.SHELL_DEFAULTS.maxSessions;
+        let sameKey = 0;
+        for (const s of this._sessions)
+            if (s.limitKey === limitKey)
+                sameKey++;
+        if (sameKey >= perUser || this._sessions.size >= total) {
+            closeWs(ws, cli_shell_options_1.ShellCloseCodes.TooMany, 'too many shell sessions');
+            return;
+        }
+        const now = Date.now();
+        const session = {
+            id: `sh-${this._nextId++}`,
+            ws,
+            authMode,
+            mode,
+            remoteAddress,
+            limitKey,
+            ctx: decision.ctx,
+            request,
+            startedAt: now,
+            lastInput: now,
+            inputSinceCheck: false,
+            lastTouch: 0,
+            closed: false,
+        };
+        this._sessions.add(session);
+        this.ensureCheckTimer();
+        if (session.ctx) {
+            // A logout/revoke/permission change between ticket consumption (or a slow
+            // `authorize`) and the registration above emitted its event before this
+            // shell could hear it: revalidate once now, before anything is spawned.
+            await this.revalidateSession(session);
+            if (session.closed)
+                return;
+            if (ws.readyState !== ws_1.WebSocket.OPEN) {
+                this.end(session, undefined, undefined, 'closed');
+                return;
+            }
+        }
+        this.spawn(session, cols, rows, command);
+    }
+    /** Decides access for the given mode. */
+    async authorize(authMode, request, url, remoteAddress, mode) {
+        const o = this._options;
+        if (authMode === 'locked') {
+            return { ok: false, code: cli_shell_options_1.ShellCloseCodes.LoginRequired, reason: 'shell access is not configured' };
+        }
+        let ctx;
+        if (authMode === 'users') {
+            const ticket = url.searchParams.get('ticket');
+            try {
+                ctx = ticket ? await this._auth.consumeTicket(ticket) : undefined;
+            }
+            catch (err) {
+                if (err?.status === 403) {
+                    return { ok: false, code: cli_shell_options_1.ShellCloseCodes.Forbidden, reason: 'forbidden' };
+                }
+                ctx = undefined;
+            }
+            if (!ctx) {
+                return { ok: false, code: cli_shell_options_1.ShellCloseCodes.LoginRequired, reason: 'login required' };
+            }
+            if (!this._auth.hasPermission(ctx, cli_server_auth_1.CliServerPermissions.ShellExecute)) {
+                return { ok: false, code: cli_shell_options_1.ShellCloseCodes.Forbidden, reason: 'forbidden' };
+            }
+        }
+        // Every configured check among token/authorize must pass, whatever the mode.
+        if (o.token) {
+            const presented = (0, cli_shell_options_1.readBearerToken)(request, url);
+            if (!presented) {
+                return { ok: false, code: cli_shell_options_1.ShellCloseCodes.LoginRequired, reason: 'login required' };
+            }
+            if (!(0, cli_shell_options_1.tokensEqual)(presented, o.token)) {
+                return { ok: false, code: cli_shell_options_1.ShellCloseCodes.Forbidden, reason: 'forbidden' };
+            }
+        }
+        if (o.authorize) {
+            let allowed = false;
+            try {
+                allowed = (await o.authorize(request, { url, remoteAddress, mode })) === true;
+            }
+            catch (err) {
+                logger.warn('Shell authorize callback threw; denying (%s)', err?.message ?? 'error');
+                allowed = false;
+            }
+            if (!allowed) {
+                return { ok: false, code: cli_shell_options_1.ShellCloseCodes.Forbidden, reason: 'forbidden' };
+            }
+        }
+        return { ok: true, ctx };
+    }
+    spawn(session, cols, rows, command) {
+        const { ws } = session;
         const { shell, args } = this.getShellInfo(command);
         let nodePty;
         try {
@@ -73,120 +273,261 @@ class CliShellSessionManager {
         }
         catch (err) {
             logger.error('node-pty unavailable: %s', err.message ?? err);
-            this.send(ws, { type: 'error', message: err.message });
-            ws.close();
+            this.send(ws, { type: 'error', message: 'shell is not available on this server' });
+            this.end(session, 1011, 'shell unavailable', 'error');
             return;
         }
-        let ptyProcess;
+        // Set after the allow/set filtering: configuration can neither override nor drop it.
+        session.shellId = (0, process_tree_1.newShellId)();
         try {
-            ptyProcess = nodePty.spawn(shell, args, {
+            session.pty = nodePty.spawn(shell, args, {
                 name: 'xterm-256color',
                 cols,
                 rows,
-                cwd: os.homedir(),
-                env: { ...process.env, TERM: 'xterm-256color' },
+                cwd: this._options.cwd ?? os.homedir(),
+                env: { ...(0, cli_shell_options_1.buildShellEnv)(this._options.env, { shell, cols, rows }), [process_tree_1.SHELL_ID_ENV]: session.shellId },
             });
         }
         catch (err) {
-            logger.error('Shell session error: %s', err.message ?? err);
-            this.send(ws, { type: 'error', message: err.message });
-            ws.close();
+            logger.error('Shell spawn failed: %s', err.message ?? err);
+            this.send(ws, { type: 'error', message: 'failed to start shell' });
+            this.end(session, 1011, 'shell failed', 'error');
             return;
         }
-        logger.info('Shell session started (shell=%s, cols=%d, rows=%d)', shell, cols, rows);
-        const detectedOs = os.platform() === 'win32'
-            ? 'win32'
-            : os.platform() === 'darwin'
-                ? 'darwin'
-                : 'linux';
+        this.onOpened(session);
         this.send(ws, {
             type: 'ready',
             shell: path.basename(shell),
-            os: detectedOs,
-        });
-        ptyProcess.onData((data) => {
-            this.send(ws, { type: 'stdout', data });
+            os: os.platform() === 'win32' ? 'win32' : os.platform() === 'darwin' ? 'darwin' : 'linux',
         });
-        ptyProcess.onExit(({ exitCode }) => {
-            logger.info('Shell session ended');
+        session.pty.onData((data) => this.send(ws, { type: 'stdout', data }));
+        session.pty.onExit(({ exitCode }) => {
+            if (session.closed)
+                return;
             this.send(ws, { type: 'exit', code: exitCode });
-            if (ws.readyState === ws_1.WebSocket.OPEN) {
-                ws.close();
-            }
+            this.end(session, 1000, 'exit', 'exited', exitCode);
         });
         ws.on('message', (raw) => {
+            let msg;
             try {
-                const msg = JSON.parse(raw.toString());
-                switch (msg.type) {
-                    case 'stdin':
-                        ptyProcess.write(msg.data);
-                        break;
-                    case 'resize':
-                        ptyProcess.resize(msg.cols, msg.rows);
-                        break;
-                }
+                msg = JSON.parse(raw.toString());
             }
             catch {
-                // Ignore malformed messages
                 logger.debug('Ignoring malformed WebSocket message');
+                return;
             }
-        });
-        ws.on('close', () => {
             try {
-                ptyProcess.kill();
+                if (msg.type === 'stdin' && typeof msg.data === 'string') {
+                    session.lastInput = Date.now();
+                    session.inputSinceCheck = true;
+                    session.pty?.write(msg.data);
+                }
+                else if (msg.type === 'resize') {
+                    session.pty?.resize(clampDim(String(msg.cols), cols), clampDim(String(msg.rows), rows));
+                }
             }
             catch {
-                // Already exited
-                logger.debug('Process already exited, cleanup skipped');
+                logger.debug('Ignoring shell message after exit');
             }
         });
+        ws.on('close', () => this.end(session, undefined, undefined, 'closed'));
         ws.on('error', (error) => {
-            logger.error('Shell session error: %s', error.message ?? error);
-            try {
-                ptyProcess.kill();
-            }
-            catch {
-                // Already exited
-                logger.debug('Process already exited, cleanup skipped');
-            }
+            logger.error('Shell socket error: %s', error.message ?? error);
+            this.end(session, undefined, undefined, 'error');
         });
+        this.armTimers(session);
     }
-    /** Determines the shell binary and arguments based on the platform and optional command. */
-    getShellInfo(command) {
-        if (os.platform() === 'win32') {
-            const shell = 'powershell.exe';
-            return command
-                ? { shell, args: ['-Command', command] }
-                : { shell, args: [] };
-        }
-        const shell = this.detectShell();
-        return command
-            ? { shell, args: ['-c', command] }
-            : { shell, args: [] };
-    }
-    /** Detects the best available shell on Unix systems by checking $SHELL and common paths. */
-    detectShell() {
-        const envShell = process.env.SHELL;
-        if (envShell) {
-            try {
-                require('fs').accessSync(envShell, require('fs').constants.X_OK);
-                return envShell;
-            }
-            catch {
-                // $SHELL binary not accessible; try common paths
-            }
+    /** Idle (no stdin) and absolute duration timers ⇒ 4408. */
+    armTimers(session) {
+        const idle = this._options.idleTimeoutMs ?? cli_shell_options_1.SHELL_DEFAULTS.idleTimeoutMs;
+        if (idle > 0) {
+            const check = () => {
+                if (session.closed)
+                    return;
+                const remaining = session.lastInput + idle - Date.now();
+                if (remaining <= 0) {
+                    this.end(session, cli_shell_options_1.ShellCloseCodes.TimedOut, 'shell timed out', 'shell timed out');
+                }
+                else {
+                    session.idleTimer = setTimeout(check, Math.min(remaining, MAX_TIMEOUT_MS));
+                    session.idleTimer.unref?.();
+                }
+            };
+            session.idleTimer = setTimeout(check, Math.min(idle, MAX_TIMEOUT_MS));
+            session.idleTimer.unref?.();
         }
-        const candidates = ['/bin/bash', '/usr/bin/bash', '/bin/sh'];
-        for (const candidate of candidates) {
-            try {
-                require('fs').accessSync(candidate, require('fs').constants.X_OK);
-                return candidate;
+        const max = this._options.maxDurationMs;
+        if (max && max > 0) {
+            const deadline = Date.now() + max;
+            const expire = () => {
+                if (session.closed)
+                    return;
+                const remaining = deadline - Date.now();
+                if (remaining <= 0) {
+                    this.end(session, cli_shell_options_1.ShellCloseCodes.TimedOut, 'shell timed out', 'shell timed out');
+                }
+                else {
+                    session.durationTimer = setTimeout(expire, Math.min(remaining, MAX_TIMEOUT_MS));
+                    session.durationTimer.unref?.();
+                }
+            };
+            session.durationTimer = setTimeout(expire, Math.min(max, MAX_TIMEOUT_MS));
+            session.durationTimer.unref?.();
+        }
+    }
+    // ----------------------------------------------------- session binding
+    onSessionEvent(event) {
+        if (event.type === 'session-ended') {
+            for (const s of [...this._sessions]) {
+                if (s.ctx?.sessionId && s.ctx.sessionId === event.sessionId) {
+                    this.end(s, cli_shell_options_1.ShellCloseCodes.LoginRequired, 'session ended', 'session ended');
+                }
             }
-            catch {
+        }
+        else {
+            void this.recheck(event.userId);
+        }
+    }
+    ensureCheckTimer() {
+        if (this._checkTimer || !this._auth)
+            return;
+        const interval = Math.min(Math.max(this._options.sessionCheckIntervalMs ?? cli_shell_options_1.SHELL_DEFAULTS.sessionCheckIntervalMs, 10), cli_shell_options_1.SHELL_DEFAULTS.maxSessionCheckIntervalMs);
+        this._checkTimer = setInterval(() => void this.recheck(), interval);
+        this._checkTimer.unref?.();
+    }
+    stopCheckTimerIfIdle() {
+        if (this._checkTimer && ![...this._sessions].some((s) => s.ctx)) {
+            clearInterval(this._checkTimer);
+            this._checkTimer = undefined;
+        }
+    }
+    /**
+     * Re-validates users-mode shells: session alive, user enabled, still holding
+     * `shell:execute` (identities from a host auth adapter are re-authenticated
+     * from the original upgrade request). Otherwise the shell is closed with 4401
+     * `session ended` (audit reason `session ended` or `permission removed`).
+     * The check itself never extends the session; stdin received since the
+     * previous check touches it first (at most once per 30 s).
+     */
+    async recheck(userId) {
+        for (const s of [...this._sessions]) {
+            if (s.closed || !s.ctx || (userId && s.ctx.userId !== userId))
                 continue;
+            await this.revalidateSession(s);
+        }
+    }
+    /** One re-check of a users-mode shell; ends it when the session ended or lost `shell:execute`. */
+    async revalidateSession(s) {
+        const auth = this._auth;
+        if (s.closed || !s.ctx)
+            return;
+        let fresh = s.ctx;
+        const now = Date.now();
+        const typed = s.inputSinceCheck;
+        s.inputSinceCheck = false;
+        try {
+            if (typed && auth?.touch && now - s.lastTouch >= cli_shell_options_1.SHELL_DEFAULTS.touchIntervalMs) {
+                s.lastTouch = now;
+                await auth.touch(s.ctx);
             }
+            fresh = auth?.revalidate ? await auth.revalidate(s.ctx, s.request) : s.ctx;
+        }
+        catch {
+            fresh = undefined;
+        }
+        if (s.closed)
+            return;
+        if (!fresh || !auth || !auth.hasPermission(fresh, cli_server_auth_1.CliServerPermissions.ShellExecute)) {
+            this.end(s, cli_shell_options_1.ShellCloseCodes.LoginRequired, 'session ended', fresh ? 'permission removed' : 'session ended');
+        }
+        else {
+            s.ctx = { ...s.ctx, permissions: fresh.permissions };
+        }
+    }
+    // ------------------------------------------------------------ lifecycle
+    onOpened(session) {
+        if (session.authMode === 'users' && session.ctx) {
+            this.audit(session, 'shell_opened', {});
+        }
+        else {
+            logger.info('Shell opened (id=%s, auth=%s, mode=%s, remote=%s)', session.id, session.authMode, session.mode, session.remoteAddress);
+        }
+    }
+    /**
+     * Ends a session once (`why` is the audit reason: exited | closed | session ended |
+     * permission removed | shell timed out | server shutdown | error): kills the process tree, closes the socket with the
+     * given code (when still open) and audits/logs the close.
+     */
+    end(session, code, reason, why, exitCode) {
+        if (session.closed)
+            return;
+        session.closed = true;
+        this._sessions.delete(session);
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        if (session.durationTimer)
+            clearTimeout(session.durationTimer);
+        this.stopCheckTimerIfIdle();
+        if (session.pty) {
+            killTree(session.pty, session.shellId);
+        }
+        if (code !== undefined) {
+            closeWs(session.ws, code, reason ?? '');
+        }
+        if (!session.pty)
+            return; // never opened
+        const durationMs = Date.now() - session.startedAt;
+        if (session.authMode === 'users' && session.ctx) {
+            this.audit(session, 'shell_closed', { durationMs, reason: why, ...(why === 'exited' ? { exitCode } : {}) });
+        }
+        else {
+            logger.info('Shell closed (id=%s, auth=%s, mode=%s, remote=%s, reason=%s, durationMs=%d)', session.id, session.authMode, session.mode, session.remoteAddress, why, durationMs);
+        }
+    }
+    audit(session, event, extra) {
+        const ctx = session.ctx;
+        const audit = this._auth?.audit;
+        if (!audit)
+            return;
+        audit
+            .call(this._auth, {
+            event,
+            userId: ctx.userId,
+            userName: ctx.userName,
+            actorId: ctx.userId,
+            actorName: ctx.userName,
+            metadata: {
+                mode: session.mode,
+                sessionId: ctx.sessionId,
+                remoteAddress: session.remoteAddress,
+                ...extra,
+            },
+        })
+            .catch((err) => logger.error('Shell audit failed: %s', err?.message ?? err));
+    }
+    /** Closes every open shell (server shutdown). */
+    dispose() {
+        for (const s of [...this._sessions]) {
+            this.end(s, 1001, 'server shutdown', 'server shutdown');
+        }
+        if (this._checkTimer)
+            clearInterval(this._checkTimer);
+        this._checkTimer = undefined;
+        this._unsubscribe?.();
+        this._unsubscribe = undefined;
+    }
+    // -------------------------------------------------------------- helpers
+    remoteAddressOf(request) {
+        return (0, cli_server_auth_1.clientAddress)(request, this._trustProxy);
+    }
+    /** Determines the shell binary and arguments based on options, platform and optional command. */
+    getShellInfo(command) {
+        if (os.platform() === 'win32') {
+            const shell = this._options.shell ?? 'powershell.exe';
+            return command ? { shell, args: ['-Command', command] } : { shell, args: [] };
         }
-        return '/bin/sh';
+        const shell = this._options.shell ?? detectShell();
+        return command ? { shell, args: ['-c', command] } : { shell, args: [] };
     }
     /** Sends a JSON message to the WebSocket if the connection is open. */
     send(ws, msg) {
@@ -196,4 +537,52 @@ class CliShellSessionManager {
     }
 }
 exports.CliShellSessionManager = CliShellSessionManager;
+/** Detects the best available shell on Unix systems by checking $SHELL and common paths. */
+function detectShell() {
+    const candidates = [process.env.SHELL, '/bin/bash', '/usr/bin/bash', '/bin/sh'].filter(Boolean);
+    for (const candidate of candidates) {
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return '/bin/sh';
+}
+function clampDim(value, fallback) {
+    const n = parseInt(value ?? '', 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(n, 1000);
+}
+function closeWs(ws, code, reason) {
+    if (ws.readyState === ws_1.WebSocket.OPEN || ws.readyState === ws_1.WebSocket.CONNECTING) {
+        try {
+            ws.close(code, reason);
+        }
+        catch {
+            ws.terminate();
+        }
+    }
+}
+/**
+ * Kills the shell and everything it started. Unix: the descendant tree and every
+ * process carrying the shell's `QCLI_SHELL_ID` marker are collected before
+ * signalling (background jobs in their own process groups, `setsid`/`nohup`
+ * children, re-parented daemons), then HUP → TERM → (grace) → KILL.
+ */
+function killTree(pty, shellId) {
+    if (os.platform() !== 'win32') {
+        (0, process_tree_1.terminateProcessTree)(pty.pid, undefined, shellId);
+        return;
+    }
+    try {
+        pty.kill();
+    }
+    catch {
+        // already exited
+    }
+}
 //# sourceMappingURL=cli-shell-session-manager.js.map