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

package/dist/src/services/cli-shell-options.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShellCloseCodes = exports.SHELL_DEFAULTS = void 0;
+exports.resolveShellAuthMode = resolveShellAuthMode;
+exports.tokensEqual = tokensEqual;
+exports.readBearerToken = readBearerToken;
+exports.buildShellEnv = buildShellEnv;
+const os = __importStar(require("os"));
+const crypto_1 = require("crypto");
+exports.SHELL_DEFAULTS = {
+    maxSessionsPerUser: 3,
+    maxSessions: 20,
+    idleTimeoutMs: 15 * 60 * 1000,
+    sessionCheckIntervalMs: 30 * 1000,
+    maxSessionCheckIntervalMs: 60 * 1000,
+    /** stdin touches the users session at most this often. */
+    touchIntervalMs: 30 * 1000,
+};
+/** WebSocket close codes used by the shell socket (accept, then close). */
+exports.ShellCloseCodes = {
+    LoginRequired: 4401,
+    Forbidden: 4403,
+    Disabled: 4404,
+    TimedOut: 4408,
+    TooMany: 4429,
+};
+/**
+ * Resolves the access mode (`shellAuth`). Users plugin mounted ⇒ `users`; otherwise
+ * `token` before `custom`, then `anonymous`; otherwise `locked`. Every configured
+ * check among token/authorize must pass whatever the reported mode.
+ */
+function resolveShellAuthMode(options, usersMounted) {
+    if (usersMounted)
+        return 'users';
+    if (options?.token)
+        return 'token';
+    if (options?.authorize)
+        return 'custom';
+    if (options?.allowAnonymous)
+        return 'anonymous';
+    return 'locked';
+}
+/** Constant-time comparison of a presented token with the configured secret. */
+function tokensEqual(presented, expected) {
+    const a = (0, crypto_1.createHash)('sha256').update(presented, 'utf8').digest();
+    const b = (0, crypto_1.createHash)('sha256').update(expected, 'utf8').digest();
+    return (0, crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * Bearer token from the `Authorization` header or, for browser clients that
+ * cannot set WebSocket headers, the `_header_Authorization` query parameter.
+ */
+function readBearerToken(request, url) {
+    let value = request.headers.authorization;
+    if (!value) {
+        for (const [key, v] of url.searchParams) {
+            if (key.toLowerCase() === '_header_authorization') {
+                value = v;
+                break;
+            }
+        }
+    }
+    if (!value)
+        return undefined;
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return match ? match[1].trim() : undefined;
+}
+const BASE_ENV = ['PATH', 'HOME', 'USER', 'LANG', 'TERM', 'COLUMNS', 'LINES', 'SHELL'];
+/** Variables Windows needs to start PowerShell at all. */
+const WINDOWS_BASE_ENV = ['SystemRoot', 'SystemDrive', 'WINDIR', 'ComSpec', 'PATHEXT', 'USERPROFILE', 'USERNAME', 'TEMP', 'TMP'];
+/**
+ * Builds the minimal shell environment: `PATH`, `HOME`, `USER`, `LANG`, `TERM`,
+ * `COLUMNS`, `LINES`, `SHELL` (plus the Windows essentials on win32), then the
+ * `allow`-listed server variables, then the fixed `set` values.
+ */
+function buildShellEnv(options, info, source = process.env) {
+    const env = {};
+    const names = os.platform() === 'win32' ? [...BASE_ENV, ...WINDOWS_BASE_ENV] : BASE_ENV;
+    for (const name of [...names, ...(options?.allow ?? [])]) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    env.TERM = 'xterm-256color';
+    env.COLUMNS = String(info.cols);
+    env.LINES = String(info.rows);
+    env.SHELL = info.shell;
+    if (!env.HOME)
+        env.HOME = os.homedir();
+    if (!env.USER) {
+        try {
+            env.USER = os.userInfo().username;
+        }
+        catch {
+            // no passwd entry (containers with arbitrary uids)
+        }
+    }
+    if (!env.PATH && os.platform() !== 'win32') {
+        env.PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+    }
+    for (const [k, v] of Object.entries(options?.set ?? {})) {
+        env[k] = String(v);
+    }
+    return env;
+}
+//# sourceMappingURL=cli-shell-options.js.map

package/dist/src/services/cli-shell-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-shell-options.js","sourceRoot":"","sources":["../../../src/services/cli-shell-options.ts"],"names":[],"mappings":"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"}

package/dist/src/services/cli-shell-session-manager.d.ts

@@ -1,18 +1,91 @@
 import { WebSocket } from 'ws';
-/** Manages interactive PTY shell sessions over WebSocket connections. */
+import type { IncomingMessage } from 'http';
+import { ICliServerAuth } from '../auth/cli-server-auth';
+import { CliShellAuthMode, CliShellOptions } from './cli-shell-options';
+/** Public view of an open shell session. */
+export interface CliShellSessionInfo {
+    id: string;
+    authMode: CliShellAuthMode;
+    mode: 'interactive' | 'command';
+    remoteAddress: string;
+    userId?: string;
+    userName?: string;
+    sessionId?: string;
+    startedAt: string;
+}
+/**
+ * Manages interactive PTY shell sessions over WebSocket connections and
+ * enforces Appendix C: access mode, session binding, limits, timeouts,
+ * minimal environment and audit.
+ */
 export declare class CliShellSessionManager {
+    private _options;
+    private _enabled;
+    private _auth?;
+    private _unsubscribe?;
+    private readonly _sessions;
+    private _nextId;
+    private _checkTimer?;
+    private _trustProxy;
+    constructor(options?: {
+        enabled?: boolean;
+        shell?: CliShellOptions;
+        trustProxy?: boolean | number;
+    });
+    /**
+     * Trusted reverse-proxy hops (`true` = 1): the remote address is the
+     * `X-Forwarded-For` entry at index `len - hops` (`false`/0: the socket address).
+     */
+    setTrustProxy(trust: boolean | number): void;
+    get enabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    get options(): CliShellOptions;
+    setOptions(options: CliShellOptions): void;
+    /** Current access mode (`undefined` while the shell is disabled). */
+    get authMode(): CliShellAuthMode | undefined;
+    /** Installs the auth provider (users plugin); subscribes to its session events. */
+    setAuth(auth: ICliServerAuth | undefined): void;
+    /** Logs the startup state: ERROR when locked, WARNING when anonymous. */
+    logStartupState(): void;
+    /** Open sessions. */
+    getSessions(): CliShellSessionInfo[];
+    /**
+     * Takes over an accepted shell WebSocket: authorizes it (closing with
+     * 4401/4403/4404/4429 when refused), then bridges it to a PTY.
+     */
+    accept(ws: WebSocket, request: IncomingMessage, url: URL): Promise<void>;
+    /** Decides access for the given mode. */
+    private authorize;
+    private spawn;
+    /** Idle (no stdin) and absolute duration timers ⇒ 4408. */
+    private armTimers;
+    private onSessionEvent;
+    private ensureCheckTimer;
+    private stopCheckTimerIfIdle;
+    /**
+     * 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).
+     */
+    recheck(userId?: string): Promise<void>;
+    /** One re-check of a users-mode shell; ends it when the session ended or lost `shell:execute`. */
+    private revalidateSession;
+    private onOpened;
     /**
-     * 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.
+     * 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.
      */
-    handleSession(ws: WebSocket, cols: number, rows: number, command?: string): Promise<void>;
-    /** Determines the shell binary and arguments based on the platform and optional command. */
+    private end;
+    private audit;
+    /** Closes every open shell (server shutdown). */
+    dispose(): void;
+    private remoteAddressOf;
+    /** Determines the shell binary and arguments based on options, platform and optional command. */
     private getShellInfo;
-    /** Detects the best available shell on Unix systems by checking $SHELL and common paths. */
-    private detectShell;
     /** Sends a JSON message to the WebSocket if the connection is open. */
     private send;
 }

package/dist/src/services/cli-shell-session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-shell-session-manager.d.ts","sourceRoot":"","sources":["../../../src/services/cli-shell-session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAuC/B,yEAAyE;AACzE,qBAAa,sBAAsB;IAC/B;;;;;;OAMG;IACG,aAAa,CACf,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IA4FhB,4FAA4F;IAC5F,OAAO,CAAC,YAAY;IAcpB,4FAA4F;IAC5F,OAAO,CAAC,WAAW;IAwBnB,uEAAuE;IACvE,OAAO,CAAC,IAAI;CAKf"}
+{"version":3,"file":"cli-shell-session-manager.d.ts","sourceRoot":"","sources":["../../../src/services/cli-shell-session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAK5C,OAAO,EAIH,cAAc,EAEjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,gBAAgB,EAChB,eAAe,EAOlB,MAAM,qBAAqB,CAAC;AAwC7B,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACrB;AAiCD;;;;GAIG;AACH,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAiB;IAC/B,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,WAAW,CAAC,CAAiB;IAErC,OAAO,CAAC,WAAW,CAAmB;gBAE1B,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,eAAe,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;KAAO;IAMvG;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAI5C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,IAAI,OAAO,IAAI,eAAe,CAE7B;IAED,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAI1C,qEAAqE;IACrE,IAAI,QAAQ,IAAI,gBAAgB,GAAG,SAAS,CAE3C;IAED,mFAAmF;IACnF,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI;IAU/C,yEAAyE;IACzE,eAAe,IAAI,IAAI;IAevB,qBAAqB;IACrB,WAAW,IAAI,mBAAmB,EAAE;IAapC;;;OAGG;IACG,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAkE9E,yCAAyC;YAC3B,SAAS;IA0DvB,OAAO,CAAC,KAAK;IA4Eb,2DAA2D;IAC3D,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,oBAAoB;IAO5B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,kGAAkG;YACpF,iBAAiB;IA0B/B,OAAO,CAAC,QAAQ;IAQhB;;;;OAIG;IACH,OAAO,CAAC,GAAG;IA2BX,OAAO,CAAC,KAAK;IAqBb,iDAAiD;IACjD,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,eAAe;IAIvB,iGAAiG;IACjG,OAAO,CAAC,YAAY;IASpB,uEAAuE;IACvE,OAAO,CAAC,IAAI;CAKf"}