chore: prepare for PR

docker/coolify-realtime/Dockerfile

@@ -16,6 +16,7 @@ RUN npm i
 RUN npm rebuild node-pty --update-binary
 COPY docker/coolify-realtime/soketi-entrypoint.sh /soketi-entrypoint.sh
 COPY docker/coolify-realtime/terminal-server.js /terminal/terminal-server.js
+COPY docker/coolify-realtime/terminal-utils.js /terminal/terminal-utils.js
 
 # Install Cloudflared based on architecture
 RUN if [ "${TARGETPLATFORM}" = "linux/amd64" ]; then \

docker/coolify-realtime/terminal-server.js

@@ -4,8 +4,33 @@ import pty from 'node-pty';
 import axios from 'axios';
 import cookie from 'cookie';
 import 'dotenv/config';
+import {
+    extractHereDocContent,
+    extractSshArgs,
+    extractTargetHost,
+    extractTimeout,
+    isAuthorizedTargetHost,
+} from './terminal-utils.js';
 
 const userSessions = new Map();
+const terminalDebugEnabled = ['local', 'development'].includes(
+    String(process.env.APP_ENV || process.env.NODE_ENV || '').toLowerCase()
+);
+
+function logTerminal(level, message, context = {}) {
+    if (!terminalDebugEnabled) {
+        return;
+    }
+
+    const formattedMessage = `[TerminalServer] ${message}`;
+
+    if (Object.keys(context).length > 0) {
+        console[level](formattedMessage, context);
+        return;
+    }
+
+    console[level](formattedMessage);
+}
 
 const server = http.createServer((req, res) => {
     if (req.url === '/ready') {
@@ -31,9 +56,19 @@ const getSessionCookie = (req) => {
 
 const verifyClient = async (info, callback) => {
     const { xsrfToken, laravelSession, sessionCookieName } = getSessionCookie(info.req);
+    const requestContext = {
+        remoteAddress: info.req.socket?.remoteAddress,
+        origin: info.origin,
+        sessionCookieName,
+        hasXsrfToken: Boolean(xsrfToken),
+        hasLaravelSession: Boolean(laravelSession),
+    };
+
+    logTerminal('log', 'Verifying websocket client.', requestContext);
 
     // Verify presence of required tokens
     if (!laravelSession || !xsrfToken) {
+        logTerminal('warn', 'Rejecting websocket client because required auth tokens are missing.', requestContext);
         return callback(false, 401, 'Unauthorized: Missing required tokens');
     }
 
@@ -47,13 +82,22 @@ const verifyClient = async (info, callback) => {
         });
 
         if (response.status === 200) {
-            // Authentication successful
+            logTerminal('log', 'Websocket client authentication succeeded.', requestContext);
             callback(true);
         } else {
+            logTerminal('warn', 'Websocket client authentication returned a non-success status.', {
+                ...requestContext,
+                status: response.status,
+            });
             callback(false, 401, 'Unauthorized: Invalid credentials');
         }
     } catch (error) {
-        console.error('Authentication error:', error.message);
+        logTerminal('error', 'Websocket client authentication failed.', {
+            ...requestContext,
+            error: error.message,
+            responseStatus: error.response?.status,
+            responseData: error.response?.data,
+        });
         callback(false, 500, 'Internal Server Error');
     }
 };
@@ -65,28 +109,62 @@ wss.on('connection', async (ws, req) => {
     const userId = generateUserId();
     const userSession = { ws, userId, ptyProcess: null, isActive: false, authorizedIPs: [] };
     const { xsrfToken, laravelSession, sessionCookieName } = getSessionCookie(req);
+    const connectionContext = {
+        userId,
+        remoteAddress: req.socket?.remoteAddress,
+        sessionCookieName,
+        hasXsrfToken: Boolean(xsrfToken),
+        hasLaravelSession: Boolean(laravelSession),
+    };
 
     // Verify presence of required tokens
     if (!laravelSession || !xsrfToken) {
+        logTerminal('warn', 'Closing websocket connection because required auth tokens are missing.', connectionContext);
         ws.close(401, 'Unauthorized: Missing required tokens');
         return;
     }
-    const response = await axios.post(`http://coolify:8080/terminal/auth/ips`, null, {
-        headers: {
-            'Cookie': `${sessionCookieName}=${laravelSession}`,
-            'X-XSRF-TOKEN': xsrfToken
-        },
-    });
-    userSession.authorizedIPs = response.data.ipAddresses || [];
+
+    try {
+        const response = await axios.post(`http://coolify:8080/terminal/auth/ips`, null, {
+            headers: {
+                'Cookie': `${sessionCookieName}=${laravelSession}`,
+                'X-XSRF-TOKEN': xsrfToken
+            },
+        });
+        userSession.authorizedIPs = response.data.ipAddresses || [];
+        logTerminal('log', 'Fetched authorized terminal hosts for websocket session.', {
+            ...connectionContext,
+            authorizedIPs: userSession.authorizedIPs,
+        });
+    } catch (error) {
+        logTerminal('error', 'Failed to fetch authorized terminal hosts.', {
+            ...connectionContext,
+            error: error.message,
+            responseStatus: error.response?.status,
+            responseData: error.response?.data,
+        });
+        ws.close(1011, 'Failed to fetch terminal authorization data');
+        return;
+    }
+
     userSessions.set(userId, userSession);
+    logTerminal('log', 'Terminal websocket connection established.', {
+        ...connectionContext,
+        authorizedHostCount: userSession.authorizedIPs.length,
+    });
 
     ws.on('message', (message) => {
         handleMessage(userSession, message);
-
     });
     ws.on('error', (err) => handleError(err, userId));
-    ws.on('close', () => handleClose(userId));
-
+    ws.on('close', (code, reason) => {
+        logTerminal('log', 'Terminal websocket connection closed.', {
+            userId,
+            code,
+            reason: reason?.toString(),
+        });
+        handleClose(userId);
+    });
 });
 
 const messageHandlers = {
@@ -98,6 +176,7 @@ const messageHandlers = {
     },
     pause: (session) => session.ptyProcess.pause(),
     resume: (session) => session.ptyProcess.resume(),
+    ping: (session) => session.ws.send('pong'),
     checkActive: (session, data) => {
         if (data === 'force' && session.isActive) {
             killPtyProcess(session.userId);
@@ -110,12 +189,34 @@ const messageHandlers = {
 
 function handleMessage(userSession, message) {
     const parsed = parseMessage(message);
-    if (!parsed) return;
+    if (!parsed) {
+        logTerminal('warn', 'Ignoring websocket message because JSON parsing failed.', {
+            userId: userSession.userId,
+            rawMessage: String(message).slice(0, 500),
+        });
+        return;
+    }
+
+    logTerminal('log', 'Received websocket message.', {
+        userId: userSession.userId,
+        keys: Object.keys(parsed),
+        isActive: userSession.isActive,
+    });
 
     Object.entries(parsed).forEach(([key, value]) => {
         const handler = messageHandlers[key];
-        if (handler && (userSession.isActive || key === 'checkActive' || key === 'command')) {
+        if (handler && (userSession.isActive || key === 'checkActive' || key === 'command' || key === 'ping')) {
             handler(userSession, value);
+        } else if (!handler) {
+            logTerminal('warn', 'Ignoring websocket message with unknown handler key.', {
+                userId: userSession.userId,
+                key,
+            });
+        } else {
+            logTerminal('warn', 'Ignoring websocket message because no PTY session is active yet.', {
+                userId: userSession.userId,
+                key,
+            });
         }
     });
 }
@@ -124,7 +225,9 @@ function parseMessage(message) {
     try {
         return JSON.parse(message);
     } catch (e) {
-        console.error('Failed to parse message:', e);
+        logTerminal('error', 'Failed to parse websocket message.', {
+            error: e?.message ?? e,
+        });
         return null;
     }
 }
@@ -134,6 +237,9 @@ async function handleCommand(ws, command, userId) {
     if (userSession && userSession.isActive) {
         const result = await killPtyProcess(userId);
         if (!result) {
+            logTerminal('warn', 'Rejecting new terminal command because the previous PTY could not be terminated.', {
+                userId,
+            });
             // if terminal is still active, even after we tried to kill it, dont continue and show error
             ws.send('unprocessable');
             return;
@@ -147,13 +253,30 @@ async function handleCommand(ws, command, userId) {
 
     // Extract target host from SSH command
     const targetHost = extractTargetHost(sshArgs);
+    logTerminal('log', 'Parsed terminal command metadata.', {
+        userId,
+        targetHost,
+        timeout,
+        sshArgs,
+        authorizedIPs: userSession?.authorizedIPs ?? [],
+    });
+
     if (!targetHost) {
+        logTerminal('warn', 'Rejecting terminal command because no target host could be extracted.', {
+            userId,
+            sshArgs,
+        });
         ws.send('Invalid SSH command: No target host found');
         return;
     }
 
     // Validate target host against authorized IPs
-    if (!userSession.authorizedIPs.includes(targetHost)) {
+    if (!isAuthorizedTargetHost(targetHost, userSession.authorizedIPs)) {
+        logTerminal('warn', 'Rejecting terminal command because target host is not authorized.', {
+            userId,
+            targetHost,
+            authorizedIPs: userSession.authorizedIPs,
+        });
         ws.send(`Unauthorized: Target host ${targetHost} not in authorized list`);
         return;
     }
@@ -169,6 +292,11 @@ async function handleCommand(ws, command, userId) {
     // NOTE: - Initiates a process within the Terminal container
     //         Establishes an SSH connection to root@coolify with RequestTTY enabled
     //         Executes the 'docker exec' command to connect to a specific container
+    logTerminal('log', 'Spawning PTY process for terminal session.', {
+        userId,
+        targetHost,
+        timeout,
+    });
     const ptyProcess = pty.spawn('ssh', sshArgs.concat([hereDocContent]), options);
 
     userSession.ptyProcess = ptyProcess;
@@ -182,7 +310,11 @@ async function handleCommand(ws, command, userId) {
 
     // when parent closes
     ptyProcess.onExit(({ exitCode, signal }) => {
-        console.error(`Process exited with code ${exitCode} and signal ${signal}`);
+        logTerminal(exitCode === 0 ? 'log' : 'error', 'PTY process exited.', {
+            userId,
+            exitCode,
+            signal,
+        });
         ws.send('pty-exited');
         userSession.isActive = false;
     });
@@ -194,28 +326,18 @@ async function handleCommand(ws, command, userId) {
     }
 }
 
-function extractTargetHost(sshArgs) {
-    // Find the argument that matches the pattern user@host
-    const userAtHost = sshArgs.find(arg => {
-        // Skip paths that contain 'storage/app/ssh/keys/'
-        if (arg.includes('storage/app/ssh/keys/')) {
-            return false;
-        }
-        return /^[^@]+@[^@]+$/.test(arg);
-    });
-    if (!userAtHost) return null;
-
-    // Extract host from user@host
-    const host = userAtHost.split('@')[1];
-    return host;
-}
-
 async function handleError(err, userId) {
-    console.error('WebSocket error:', err);
+    logTerminal('error', 'WebSocket error.', {
+        userId,
+        error: err?.message ?? err,
+    });
     await killPtyProcess(userId);
 }
 
 async function handleClose(userId) {
+    logTerminal('log', 'Cleaning up terminal websocket session.', {
+        userId,
+    });
     await killPtyProcess(userId);
     userSessions.delete(userId);
 }
@@ -231,6 +353,11 @@ async function killPtyProcess(userId) {
 
         const attemptKill = () => {
             killAttempts++;
+            logTerminal('log', 'Attempting to terminate PTY process.', {
+                userId,
+                killAttempts,
+                maxAttempts,
+            });
 
             // session.ptyProcess.kill() wont work here because of https://github.com/moby/moby/issues/9098
             // patch with https://github.com/moby/moby/issues/9098#issuecomment-189743947
@@ -238,6 +365,10 @@ async function killPtyProcess(userId) {
 
             setTimeout(() => {
                 if (!session.isActive || !session.ptyProcess) {
+                    logTerminal('log', 'PTY process terminated successfully.', {
+                        userId,
+                        killAttempts,
+                    });
                     resolve(true);
                     return;
                 }
@@ -245,6 +376,10 @@ async function killPtyProcess(userId) {
                 if (killAttempts < maxAttempts) {
                     attemptKill();
                 } else {
+                    logTerminal('warn', 'PTY process still active after maximum termination attempts.', {
+                        userId,
+                        killAttempts,
+                    });
                     resolve(false);
                 }
             }, 500);
@@ -258,76 +393,8 @@ function generateUserId() {
     return Math.random().toString(36).substring(2, 11);
 }
 
-function extractTimeout(commandString) {
-    const timeoutMatch = commandString.match(/timeout (\d+)/);
-    return timeoutMatch ? parseInt(timeoutMatch[1], 10) : null;
-}
-
-function extractSshArgs(commandString) {
-    const sshCommandMatch = commandString.match(/ssh (.+?) 'bash -se'/);
-    if (!sshCommandMatch) return [];
-
-    const argsString = sshCommandMatch[1];
-    let sshArgs = [];
-
-    // Parse shell arguments respecting quotes
-    let current = '';
-    let inQuotes = false;
-    let quoteChar = '';
-    let i = 0;
-
-    while (i < argsString.length) {
-        const char = argsString[i];
-        const nextChar = argsString[i + 1];
-
-        if (!inQuotes && (char === '"' || char === "'")) {
-            // Starting a quoted section
-            inQuotes = true;
-            quoteChar = char;
-            current += char;
-        } else if (inQuotes && char === quoteChar) {
-            // Ending a quoted section
-            inQuotes = false;
-            current += char;
-            quoteChar = '';
-        } else if (!inQuotes && char === ' ') {
-            // Space outside quotes - end of argument
-            if (current.trim()) {
-                sshArgs.push(current.trim());
-                current = '';
-            }
-        } else {
-            // Regular character
-            current += char;
-        }
-        i++;
-    }
-
-    // Add final argument if exists
-    if (current.trim()) {
-        sshArgs.push(current.trim());
-    }
-
-    // Replace RequestTTY=no with RequestTTY=yes
-    sshArgs = sshArgs.map(arg => arg === 'RequestTTY=no' ? 'RequestTTY=yes' : arg);
-
-    // Add RequestTTY=yes if not present
-    if (!sshArgs.includes('RequestTTY=yes') && !sshArgs.some(arg => arg.includes('RequestTTY='))) {
-        sshArgs.push('-o', 'RequestTTY=yes');
-    }
-
-    return sshArgs;
-}
-
-function extractHereDocContent(commandString) {
-    const delimiterMatch = commandString.match(/<< (\S+)/);
-    const delimiter = delimiterMatch ? delimiterMatch[1] : null;
-    const escapedDelimiter = delimiter.slice(1).trim().replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&');
-    const hereDocRegex = new RegExp(`<< \\\\${escapedDelimiter}([\\s\\S\\.]*?)${escapedDelimiter}`);
-    const hereDocMatch = commandString.match(hereDocRegex);
-    return hereDocMatch ? hereDocMatch[1] : '';
-}
-
 server.listen(6002, () => {
-    console.log('Coolify realtime terminal server listening on port 6002. Let the hacking begin!');
+    logTerminal('log', 'Terminal debug logging is enabled.', {
+        terminalDebugEnabled,
+    });
 });

docker/coolify-realtime/terminal-utils.js

@@ -0,0 +1,127 @@
+export function extractTimeout(commandString) {
+    const timeoutMatch = commandString.match(/timeout (\d+)/);
+    return timeoutMatch ? parseInt(timeoutMatch[1], 10) : null;
+}
+
+function normalizeShellArgument(argument) {
+    if (!argument) {
+        return argument;
+    }
+
+    return argument
+        .replace(/'([^']*)'/g, '$1')
+        .replace(/"([^"]*)"/g, '$1');
+}
+
+export function extractSshArgs(commandString) {
+    const sshCommandMatch = commandString.match(/ssh (.+?) 'bash -se'/);
+    if (!sshCommandMatch) return [];
+
+    const argsString = sshCommandMatch[1];
+    let sshArgs = [];
+
+    let current = '';
+    let inQuotes = false;
+    let quoteChar = '';
+    let i = 0;
+
+    while (i < argsString.length) {
+        const char = argsString[i];
+
+        if (!inQuotes && (char === '"' || char === "'")) {
+            inQuotes = true;
+            quoteChar = char;
+            current += char;
+        } else if (inQuotes && char === quoteChar) {
+            inQuotes = false;
+            current += char;
+            quoteChar = '';
+        } else if (!inQuotes && char === ' ') {
+            if (current.trim()) {
+                sshArgs.push(current.trim());
+                current = '';
+            }
+        } else {
+            current += char;
+        }
+        i++;
+    }
+
+    if (current.trim()) {
+        sshArgs.push(current.trim());
+    }
+
+    sshArgs = sshArgs.map((arg) => normalizeShellArgument(arg));
+    sshArgs = sshArgs.map(arg => arg === 'RequestTTY=no' ? 'RequestTTY=yes' : arg);
+
+    if (!sshArgs.includes('RequestTTY=yes') && !sshArgs.some(arg => arg.includes('RequestTTY='))) {
+        sshArgs.push('-o', 'RequestTTY=yes');
+    }
+
+    return sshArgs;
+}
+
+export function extractHereDocContent(commandString) {
+    const delimiterMatch = commandString.match(/<< (\S+)/);
+    const delimiter = delimiterMatch ? delimiterMatch[1] : null;
+    const escapedDelimiter = delimiter?.slice(1).trim().replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&');
+
+    if (!escapedDelimiter) {
+        return '';
+    }
+
+    const hereDocRegex = new RegExp(`<< \\\\${escapedDelimiter}([\\s\\S\\.]*?)${escapedDelimiter}`);
+    const hereDocMatch = commandString.match(hereDocRegex);
+    return hereDocMatch ? hereDocMatch[1] : '';
+}
+
+export function normalizeHostForAuthorization(host) {
+    if (!host) {
+        return null;
+    }
+
+    let normalizedHost = host.trim();
+
+    while (
+        normalizedHost.length >= 2 &&
+        ((normalizedHost.startsWith("'") && normalizedHost.endsWith("'")) ||
+            (normalizedHost.startsWith('"') && normalizedHost.endsWith('"')))
+    ) {
+        normalizedHost = normalizedHost.slice(1, -1).trim();
+    }
+
+    if (normalizedHost.startsWith('[') && normalizedHost.endsWith(']')) {
+        normalizedHost = normalizedHost.slice(1, -1);
+    }
+
+    return normalizedHost.toLowerCase();
+}
+
+export function extractTargetHost(sshArgs) {
+    const userAtHost = sshArgs.find(arg => {
+        if (arg.includes('storage/app/ssh/keys/')) {
+            return false;
+        }
+
+        return /^[^@]+@[^@]+$/.test(arg);
+    });
+
+    if (!userAtHost) {
+        return null;
+    }
+
+    const atIndex = userAtHost.indexOf('@');
+    return normalizeHostForAuthorization(userAtHost.slice(atIndex + 1));
+}
+
+export function isAuthorizedTargetHost(targetHost, authorizedHosts = []) {
+    const normalizedTargetHost = normalizeHostForAuthorization(targetHost);
+
+    if (!normalizedTargetHost) {
+        return false;
+    }
+
+    return authorizedHosts
+        .map(host => normalizeHostForAuthorization(host))
+        .includes(normalizedTargetHost);
+}

docker/coolify-realtime/terminal-utils.test.js

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    extractSshArgs,
+    extractTargetHost,
+    isAuthorizedTargetHost,
+    normalizeHostForAuthorization,
+} from './terminal-utils.js';
+
+test('extractTargetHost normalizes quoted IPv4 hosts from generated ssh commands', () => {
+    const sshArgs = extractSshArgs(
+        "timeout 3600 ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ServerAliveInterval=20 -o ConnectTimeout=10 'root'@'10.0.0.5' 'bash -se' << \\\\$abc\necho hi\nabc"
+    );
+
+    assert.equal(extractTargetHost(sshArgs), '10.0.0.5');
+});
+
+test('extractSshArgs strips shell quotes from port and user host arguments before spawning ssh', () => {
+    const sshArgs = extractSshArgs(
+        "timeout 3600 ssh -p '22' -o StrictHostKeyChecking=no 'root'@'10.0.0.5' 'bash -se' << \\\\$abc\necho hi\nabc"
+    );
+
+    assert.deepEqual(sshArgs.slice(0, 5), ['-p', '22', '-o', 'StrictHostKeyChecking=no', 'root@10.0.0.5']);
+});
+
+test('extractSshArgs preserves proxy command as a single normalized ssh option value', () => {
+    const sshArgs = extractSshArgs(
+        "timeout 3600 ssh -o ProxyCommand='cloudflared access ssh --hostname %h' -o StrictHostKeyChecking=no 'root'@'example.com' 'bash -se' << \\\\$abc\necho hi\nabc"
+    );
+
+    assert.equal(sshArgs[1], 'ProxyCommand=cloudflared access ssh --hostname %h');
+    assert.equal(sshArgs[4], 'root@example.com');
+});
+
+test('isAuthorizedTargetHost matches normalized hosts against plain allowlist values', () => {
+    assert.equal(isAuthorizedTargetHost("'10.0.0.5'", ['10.0.0.5']), true);
+    assert.equal(isAuthorizedTargetHost('"host.docker.internal"', ['host.docker.internal']), true);
+});
+
+test('normalizeHostForAuthorization unwraps bracketed IPv6 hosts', () => {
+    assert.equal(normalizeHostForAuthorization("'[2001:db8::10]'"), '2001:db8::10');
+    assert.equal(isAuthorizedTargetHost("'[2001:db8::10]'", ['2001:db8::10']), true);
+});
+
+test('isAuthorizedTargetHost rejects hosts that are not in the allowlist', () => {
+    assert.equal(isAuthorizedTargetHost("'10.0.0.9'", ['10.0.0.5']), false);
+});