@pixelbyte-software/pixcode 1.53.12 → 1.53.14

package/server/index.js

@@ -150,7 +150,7 @@ import {
 import networkRoutes from './routes/network.js';
 import telegramRoutes from './routes/telegram.js';
 import { restoreRequestedTunnel } from './services/external-access.js';
-import { restoreBotFromConfig } from './services/telegram/bot.js';
+import { notifyTelegramTerminalAttached, restoreBotFromConfig } from './services/telegram/bot.js';
 import { ensurePortOpen } from './utils/port-access.js';
 import {
     applyAllStoredCredentialsToEnv,
@@ -1237,6 +1237,7 @@ function appendPtySessionBuffer(session, data) {
         valueBytes = Buffer.byteLength(value, 'utf8');
     }
 
+    session.totalOutputBytes = (session.totalOutputBytes || 0) + valueBytes;
     session.buffer.push(value);
     session.bufferBytes = (session.bufferBytes || 0) + valueBytes;
 
@@ -1247,6 +1248,31 @@ function appendPtySessionBuffer(session, data) {
     if (session.bufferBytes < 0) session.bufferBytes = 0;
 }
 
+function readPtySessionBufferedOutput(session, { maxChars = 12000, sinceCursor = null } = {}) {
+    const rawBuffer = (session?.buffer || []).join('');
+    const bufferBytes = session?.bufferBytes || Buffer.byteLength(rawBuffer, 'utf8');
+    const outputCursor = session?.totalOutputBytes || bufferBytes;
+    const bufferStartCursor = Math.max(0, outputCursor - bufferBytes);
+    let rawOutput = rawBuffer;
+
+    if (Number.isFinite(sinceCursor)) {
+        const skipBytes = Math.max(0, sinceCursor - bufferStartCursor);
+        if (skipBytes > 0) {
+            rawOutput = Buffer.from(rawBuffer, 'utf8').slice(skipBytes).toString('utf8');
+        }
+    }
+
+    if (rawOutput.length > maxChars) {
+        rawOutput = rawOutput.slice(-maxChars);
+    }
+
+    return {
+        rawOutput,
+        outputCursor,
+        bufferStartCursor,
+    };
+}
+
 function normalizeTerminalStartupInput(input) {
     return `\x15${String(input || '').replace(/(?:\r\n|\r|\n)+$/u, '')}\r`;
 }
@@ -1627,6 +1653,8 @@ app.get('/api/shell/sessions/provider-output', authenticateToken, requireProject
         20000,
         Math.max(1000, Number.parseInt(String(req.query.maxChars || '12000'), 10) || 12000)
     );
+    const sinceCursorRaw = Number.parseInt(String(req.query.sinceCursor ?? ''), 10);
+    const sinceCursor = Number.isFinite(sinceCursorRaw) ? Math.max(0, sinceCursorRaw) : null;
 
     if (!SHELL_CLI_PROVIDERS.has(provider)) {
         return res.status(400).json({ error: 'Unsupported provider' });
@@ -1643,6 +1671,8 @@ app.get('/api/shell/sessions/provider-output', authenticateToken, requireProject
                 tabId,
                 sessionId,
                 output: '',
+                outputCursor: 0,
+                bufferStartCursor: 0,
                 message: 'Multiple provider terminal sessions match this target. Pick a specific tab.',
             });
         }
@@ -1653,14 +1683,21 @@ app.get('/api/shell/sessions/provider-output', authenticateToken, requireProject
             tabId,
             sessionId,
             output: '',
+            outputCursor: 0,
+            bufferStartCursor: 0,
             message: 'No active provider terminal session found for this project.',
         });
     }
 
     const matchedSession = match.session;
-    const rawOutput = matchedSession.buffer.join('').slice(-maxChars);
+    const {
+        rawOutput,
+        outputCursor,
+        bufferStartCursor,
+    } = readPtySessionBufferedOutput(matchedSession, { maxChars, sinceCursor });
     const output = stripAnsiSequences(rawOutput);
-    const terminalState = resolveProviderTerminalState(matchedSession, provider, output);
+    const fullOutput = readSessionOutputForState(matchedSession);
+    const terminalState = resolveProviderTerminalState(matchedSession, provider, fullOutput);
     res.json({
         active: true,
         provider,
@@ -1671,6 +1708,9 @@ app.get('/api/shell/sessions/provider-output', authenticateToken, requireProject
         matchStatus: match.status,
         ...terminalState,
         output,
+        outputCursor,
+        bufferStartCursor,
+        sinceCursor,
     });
 });
 
@@ -1723,6 +1763,7 @@ app.post('/api/shell/sessions/provider-input', authenticateToken, requireProject
 
     const matchedSession = match.session;
     const data = submit ? normalizeTerminalStartupInput(input) : input;
+    const outputCursorBefore = matchedSession.totalOutputBytes || matchedSession.bufferBytes || 0;
     try {
         writeTerminalInputChunks(matchedSession.pty, data);
         matchedSession.updatedAt = Date.now();
@@ -1736,6 +1777,8 @@ app.post('/api/shell/sessions/provider-input', authenticateToken, requireProject
             submitted: submit,
             bytes: Buffer.byteLength(data),
             matchStatus: match.status,
+            outputCursorBefore,
+            outputCursorAfter: matchedSession.totalOutputBytes || matchedSession.bufferBytes || 0,
         });
     } catch (error) {
         res.status(500).json({
@@ -1764,7 +1807,7 @@ function requireVerifiedTelegramLink(req, res) {
 
 // Bind the paired Telegram chat to an already running provider terminal tab.
 // This route lives next to the PTY registry so it can verify the target is live.
-app.post('/api/telegram/active-terminal', authenticateToken, requireProjectPathAccess('useShell'), (req, res) => {
+app.post('/api/telegram/active-terminal', authenticateToken, requireProjectPathAccess('useShell'), async (req, res) => {
     try {
         const link = requireVerifiedTelegramLink(req, res);
         if (!link) return;
@@ -1824,8 +1867,18 @@ app.post('/api/telegram/active-terminal', authenticateToken, requireProjectPathA
             selectedProjectName: projectName,
             selectedProjectPath: resolvedMatchedProjectPath,
         });
+        notifyTelegramTerminalAttached({
+            userId: req.user.id,
+            terminal: control.activeTerminal,
+        }).then((telegramNotice) => {
+            if (telegramNotice?.ok === false) {
+                console.warn('[telegram] terminal attach notice not delivered:', telegramNotice.reason);
+            }
+        }).catch((error) => {
+            console.warn('[telegram] terminal attach notice failed:', error?.message || error);
+        });
 
-        res.json({ success: true, activeTerminal: control.activeTerminal, control, matchStatus: match.status });
+        res.json({ success: true, activeTerminal: control.activeTerminal, control, matchStatus: match.status, telegramNotice: { queued: true } });
     } catch (error) {
         console.error('telegram/active-terminal failed:', error);
         res.status(500).json({ error: 'Failed to attach Telegram to this terminal.' });
@@ -4142,6 +4195,7 @@ function handleShellConnection(ws, request) {
                         ws: ws,
                         buffer: [],
                         bufferBytes: 0,
+                        totalOutputBytes: 0,
                         droppedOutputBytes: 0,
                         timeoutId: null,
                         userId: ownerUserId,

package/server/routes/auth.js

@@ -6,7 +6,13 @@ import express from 'express';
 import bcrypt from 'bcryptjs';
 
 import { userDb, db } from '../database/db.js';
-import { generateToken, authenticateToken } from '../middleware/auth.js';
+import { generateToken, authenticateToken, requireAdmin } from '../middleware/auth.js';
+import {
+  consumeQrLoginToken,
+  createQrLoginToken,
+  getQrLoginSettings,
+  saveQrLoginSettings,
+} from '../services/qr-login.js';
 import {
   getPublicRemoteConnectionConfig,
   saveRemoteConnectionConfig,
@@ -51,6 +57,46 @@ router.put('/connection-mode', (req, res) => {
   }
 });
 
+router.get('/qr-login/settings', authenticateToken, requireAdmin, (_req, res) => {
+  res.json({ success: true, settings: getQrLoginSettings() });
+});
+
+router.put('/qr-login/settings', authenticateToken, requireAdmin, (req, res) => {
+  try {
+    res.json({ success: true, settings: saveQrLoginSettings(req.body || {}) });
+  } catch (error) {
+    res.status(400).json({ success: false, error: error.message });
+  }
+});
+
+router.post('/qr-login/token', authenticateToken, requireAdmin, (req, res) => {
+  try {
+    const baseUrl = typeof req.body?.baseUrl === 'string' && req.body.baseUrl.trim()
+      ? req.body.baseUrl.trim()
+      : null;
+    res.json({ success: true, ...createQrLoginToken({ userId: req.user.id, baseUrl }) });
+  } catch (error) {
+    const status = error?.code === 'QR_LOGIN_DISABLED' ? 409 : 400;
+    res.status(status).json({ success: false, error: error.message });
+  }
+});
+
+router.post('/qr-login', (req, res) => {
+  try {
+    const user = consumeQrLoginToken(req.body?.token);
+    const token = generateToken(user);
+    userDb.updateLastLogin(user.id);
+    res.json({
+      success: true,
+      user: publicUser(user),
+      token,
+    });
+  } catch (error) {
+    const status = error?.code === 'QR_LOGIN_DISABLED' ? 409 : 401;
+    res.status(status).json({ success: false, error: error.message });
+  }
+});
+
 // User registration (setup) - only allowed if no users exist
 router.post('/register', async (req, res) => {
   try {

package/server/routes/git.js

@@ -46,9 +46,11 @@ router.use((req, res, next) => {
 });
 
 function isNotGitRepositoryMessage(message = '') {
-  return message.includes('Not a git repository')
-    || message.includes('not a git repository')
-    || message.includes('Project directory is not a git repository');
+  const normalized = String(message || '').toLowerCase();
+  return normalized.includes('not a git repository')
+    || normalized.includes('not inside a git work tree')
+    || normalized.includes('does not contain a .git folder')
+    || normalized.includes('project directory is not a git repository');
 }
 
 function isMissingFileError(error) {
@@ -178,6 +180,35 @@ async function buildFilesystemStatus(projectPath) {
   };
 }
 
+async function readFilesystemFileWithDiff(projectPath, filePath) {
+  const projectRoot = path.resolve(projectPath);
+  const resolvedFilePath = path.resolve(projectRoot, String(filePath || ''));
+  const relativePath = path.relative(projectRoot, resolvedFilePath);
+
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    const error = new Error('Invalid file path: path traversal detected');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  const stats = await fs.stat(resolvedFilePath);
+  if (stats.isDirectory()) {
+    const error = new Error('Cannot show diff for directories');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  const currentContent = await fs.readFile(resolvedFilePath, 'utf-8');
+  return {
+    currentContent,
+    oldContent: currentContent,
+    isDeleted: false,
+    isUntracked: false,
+    isGitRepository: false,
+    trackingMode: 'filesystem',
+  };
+}
+
 function spawnAsync(command, args, options = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
@@ -634,6 +665,14 @@ router.get('/diff', async (req, res) => {
 
     res.json({ diff });
   } catch (error) {
+    if (isNotGitRepositoryMessage(getGitErrorDetails(error))) {
+      return res.json({
+        diff: '',
+        isGitRepository: false,
+        trackingMode: 'filesystem',
+      });
+    }
+
     console.error('Git diff error:', error);
     res.json({ error: error.message });
   }
@@ -763,6 +802,34 @@ router.get('/file-with-diff', async (req, res) => {
         isUntracked: false,
       });
     }
+
+    if (isNotGitRepositoryMessage(getGitErrorDetails(error))) {
+      try {
+        return res.json(await readFilesystemFileWithDiff(
+          await getActualProjectPath(project),
+          file,
+        ));
+      } catch (fallbackError) {
+        if (isMissingFileError(fallbackError)) {
+          return res.status(404).json({
+            error: 'File not found',
+            currentContent: '',
+            oldContent: '',
+            isDeleted: true,
+            isUntracked: false,
+            isGitRepository: false,
+            trackingMode: 'filesystem',
+          });
+        }
+
+        return res.status(fallbackError.statusCode || 500).json({
+          error: fallbackError.message || 'Failed to read file',
+          isGitRepository: false,
+          trackingMode: 'filesystem',
+        });
+      }
+    }
+
     console.error('Git file-with-diff error:', error);
     res.json({ error: error.message });
   }

package/server/routes/network.js

@@ -19,6 +19,19 @@ const resolveServerPort = () => {
   return Number.isFinite(port) && port > 0 ? port : 3001;
 };
 
+const PRIVATE_IPV4_REGEX = /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[0-1])\.)/u;
+const VIRTUAL_INTERFACE_REGEX = /(docker|veth|bridge|br-|vmnet|vbox|virtualbox|tailscale|utun|wg|tun|tap|zerotier|zt)/iu;
+
+const classifyEndpoint = (ifaceName, address) => {
+  const isPrivate = PRIVATE_IPV4_REGEX.test(address);
+  const isVirtual = VIRTUAL_INTERFACE_REGEX.test(ifaceName);
+  return {
+    scope: isPrivate ? 'private' : 'public',
+    kind: isVirtual ? 'virtual' : (isPrivate ? 'lan' : 'public'),
+    usableForSameNetwork: isPrivate && !isVirtual,
+  };
+};
+
 // Filter to usable LAN addresses. We skip:
 //  - internal (loopback) addresses, since QR-ing "127.0.0.1" is useless for a phone
 //  - link-local IPv6, since pasting "fe80::…%iface" into a phone browser won't resolve
@@ -32,10 +45,13 @@ const listLanEndpoints = () => {
     for (const addr of addrs) {
       if (addr.internal) continue;
       if (addr.family !== 'IPv4' && addr.family !== 4) continue;
+      const classification = classifyEndpoint(ifaceName, addr.address);
+      if (!classification.usableForSameNetwork) continue;
       endpoints.push({
         host: addr.address,
         label: ifaceName,
         family: 'IPv4',
+        ...classification,
       });
     }
   }
@@ -97,7 +113,8 @@ router.delete('/upnp', (_req, res) => {
 router.post('/tunnel', requireAdmin, async (req, res) => {
   const port = resolveServerPort();
   try {
-    const state = await startTunnel({ port, persistPreference: true });
+    const provider = req.body?.provider === 'ngrok' ? 'ngrok' : 'cloudflare';
+    const state = await startTunnel({ port, provider, persistPreference: true });
     res.json({ success: true, tunnel: state });
   } catch (error) {
     console.error('Tunnel start failed:', error);

package/server/services/external-access.js

@@ -44,6 +44,7 @@ let restoreInFlight = null;
 let tunnelState = {
   running: false,
   binary: null, // 'cloudflared' | 'ngrok'
+  provider: null, // 'cloudflare' | 'ngrok'
   url: null,
   error: null,
   installHint: null,
@@ -55,7 +56,7 @@ let tunnelState = {
 const DEFAULT_TUNNEL_PREFERENCE = Object.freeze({
   desired: false,
   port: null,
-  provider: null,
+  provider: 'cloudflare',
   lastUrl: null,
   lastStartedAt: null,
   lastStoppedAt: null,
@@ -97,8 +98,14 @@ const appendLog = (line) => {
   if (tunnelState.log.length > 200) tunnelState.log.shift();
 };
 
-const detectBinary = async () => {
-  const candidates = ['cloudflared', 'ngrok'];
+const normalizeTunnelProvider = (provider) => (provider === 'ngrok' ? 'ngrok' : 'cloudflare');
+
+const tunnelProviderBinary = (provider) => (normalizeTunnelProvider(provider) === 'ngrok' ? 'ngrok' : 'cloudflared');
+
+const tunnelBinaryProvider = (binary) => (binary === 'ngrok' ? 'ngrok' : 'cloudflare');
+
+const detectBinary = async (provider = null) => {
+  const candidates = provider ? [tunnelProviderBinary(provider)] : ['cloudflared', 'ngrok'];
   for (const name of candidates) {
     try {
       // `which` isn't guaranteed on Windows; we probe with `--version` instead
@@ -116,17 +123,31 @@ const detectBinary = async () => {
   return null;
 };
 
-const createTunnelInstallHint = () => ({
-  title: 'Tunnel binary required',
-  message: 'Install cloudflared or ngrok to create a public mobile URL. Local LAN QR codes still work on the same Wi-Fi/network.',
-  commands: [
-    'macOS: brew install cloudflared',
-    'Windows: winget install Cloudflare.cloudflared',
-    'Linux: install cloudflared from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
-    'Alternative: install and authenticate ngrok from https://ngrok.com/download',
-  ],
-  docsUrl: 'https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
-});
+const createTunnelInstallHint = (provider = 'cloudflare') => {
+  if (normalizeTunnelProvider(provider) === 'ngrok') {
+    return {
+      title: 'ngrok binary required',
+      message: 'Install and authenticate ngrok to create a public mobile URL. Local LAN QR codes still work on the same Wi-Fi/network.',
+      commands: [
+        'macOS: brew install ngrok/ngrok/ngrok',
+        'Windows: winget install ngrok.ngrok',
+        'Linux: install ngrok from https://ngrok.com/download',
+      ],
+      docsUrl: 'https://ngrok.com/download',
+    };
+  }
+
+  return {
+    title: 'Cloudflare Tunnel binary required',
+    message: 'Install cloudflared to create a public Cloudflare URL. Local LAN QR codes still work on the same Wi-Fi/network.',
+    commands: [
+      'macOS: brew install cloudflared',
+      'Windows: winget install Cloudflare.cloudflared',
+      'Linux: install cloudflared from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
+    ],
+    docsUrl: 'https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
+  };
+};
 
 const cloudflareUrlRegex = /https?:\/\/[a-z0-9.-]+trycloudflare\.com/i;
 const ngrokUrlRegex = /https?:\/\/[a-z0-9.-]+\.ngrok(-free)?\.(app|io)/i;
@@ -143,13 +164,14 @@ const extractUrl = (binary, text) => {
   return null;
 };
 
-export const startTunnel = async ({ port, persistPreference = false, restoring = false } = {}) => {
+export const startTunnel = async ({ port, provider: requestedProvider = 'cloudflare', persistPreference = false, restoring = false } = {}) => {
+  const provider = normalizeTunnelProvider(requestedProvider);
   if (tunnelProc) {
     if (persistPreference) {
       await persistTunnelPreference({
         desired: true,
         port,
-        provider: tunnelState.binary,
+        provider: tunnelState.provider || tunnelBinaryProvider(tunnelState.binary),
         lastUrl: tunnelState.url,
       });
       tunnelState = { ...tunnelState, desired: true, restoring: false };
@@ -158,20 +180,21 @@ export const startTunnel = async ({ port, persistPreference = false, restoring =
   }
   suppressNextTunnelRestore = false;
 
-  const binary = await detectBinary();
+  const binary = await detectBinary(provider);
   if (!binary) {
-    const installHint = createTunnelInstallHint();
+    const installHint = createTunnelInstallHint(provider);
     tunnelState = {
       running: false,
       binary: null,
+      provider,
       url: null,
-      error: 'No tunnel binary found',
+      error: provider === 'cloudflare' ? 'cloudflared was not found' : 'ngrok was not found',
       installHint,
       desired: Boolean(persistPreference || restoring),
       restoring,
       log: [],
     };
-    const err = new Error('No tunnel binary found (tried cloudflared, ngrok)');
+    const err = new Error(tunnelState.error);
     err.code = 'ENOENT_TUNNEL';
     err.installHint = installHint;
     throw err;
@@ -183,6 +206,7 @@ export const startTunnel = async ({ port, persistPreference = false, restoring =
   tunnelState = {
     running: true,
     binary,
+    provider,
     url: null,
     error: null,
     installHint: null,
@@ -207,6 +231,7 @@ export const startTunnel = async ({ port, persistPreference = false, restoring =
     tunnelState = {
       running: false,
       binary,
+      provider,
       url: null,
       error: code === 0 ? null : `Tunnel exited with code ${code}`,
       installHint: null,
@@ -242,7 +267,7 @@ export const startTunnel = async ({ port, persistPreference = false, restoring =
         await persistTunnelPreference({
           desired: true,
           port,
-          provider: binary,
+          provider,
           lastUrl: tunnelState.url,
           lastStartedAt: new Date().toISOString(),
         });
@@ -284,6 +309,7 @@ export const stopTunnel = async ({ persistPreference = true } = {}) => {
     tunnelState = {
       running: false,
       binary: null,
+      provider: null,
       url: null,
       error: null,
       installHint: null,
@@ -302,6 +328,7 @@ export const stopTunnel = async ({ persistPreference = true } = {}) => {
   tunnelState = {
     running: false,
     binary: null,
+    provider: null,
     url: null,
     error: null,
     installHint: null,
@@ -341,6 +368,7 @@ export const restoreRequestedTunnel = async ({ port } = {}) => {
     try {
       return await startTunnel({
         port: restorePort,
+        provider: preference.provider || 'cloudflare',
         persistPreference: true,
         restoring: true,
       });

package/server/services/qr-login.js

@@ -0,0 +1,126 @@
+import crypto from 'node:crypto';
+
+import { appConfigDb, userDb } from '../database/db.js';
+
+const CONFIG_KEY = 'qr_login_settings';
+const DEFAULT_SETTINGS = Object.freeze({
+  enabled: false,
+  ttlSeconds: 300,
+});
+const MIN_TTL_SECONDS = 60;
+const MAX_TTL_SECONDS = 15 * 60;
+const qrLoginTokens = new Map();
+
+function clampTtl(value) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  if (!Number.isFinite(parsed)) return DEFAULT_SETTINGS.ttlSeconds;
+  return Math.min(MAX_TTL_SECONDS, Math.max(MIN_TTL_SECONDS, parsed));
+}
+
+function normalizeSettings(value = {}) {
+  const raw = value && typeof value === 'object' ? value : {};
+  return {
+    enabled: raw.enabled === true,
+    ttlSeconds: clampTtl(raw.ttlSeconds),
+  };
+}
+
+function readStoredSettings() {
+  const raw = appConfigDb.get(CONFIG_KEY);
+  if (!raw) return { ...DEFAULT_SETTINGS };
+  try {
+    return normalizeSettings(JSON.parse(raw));
+  } catch {
+    return { ...DEFAULT_SETTINGS };
+  }
+}
+
+function cleanupExpiredTokens() {
+  const now = Date.now();
+  for (const [token, entry] of qrLoginTokens.entries()) {
+    if (!entry || entry.expiresAtMs <= now) {
+      qrLoginTokens.delete(token);
+    }
+  }
+}
+
+function appendQrLoginToken(baseUrl, token) {
+  const url = new URL(baseUrl);
+  url.searchParams.set('qrLoginToken', token);
+  return url.toString();
+}
+
+export function getQrLoginSettings() {
+  return readStoredSettings();
+}
+
+export function saveQrLoginSettings(input = {}) {
+  const settings = normalizeSettings(input);
+  appConfigDb.set(CONFIG_KEY, JSON.stringify(settings));
+  if (!settings.enabled) {
+    qrLoginTokens.clear();
+  }
+  return settings;
+}
+
+export function createQrLoginToken({ userId, baseUrl }) {
+  const settings = readStoredSettings();
+  if (!settings.enabled) {
+    const error = new Error('QR login is disabled.');
+    error.code = 'QR_LOGIN_DISABLED';
+    throw error;
+  }
+  const user = userDb.getUserById(userId);
+  if (!user) {
+    const error = new Error('QR login user was not found.');
+    error.code = 'QR_LOGIN_USER_NOT_FOUND';
+    throw error;
+  }
+
+  cleanupExpiredTokens();
+  const token = crypto.randomBytes(32).toString('base64url');
+  const expiresAtMs = Date.now() + settings.ttlSeconds * 1000;
+  qrLoginTokens.set(token, {
+    userId: user.id,
+    createdAtMs: Date.now(),
+    expiresAtMs,
+  });
+
+  return {
+    token,
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    ttlSeconds: settings.ttlSeconds,
+    qrUrl: baseUrl ? appendQrLoginToken(baseUrl, token) : null,
+  };
+}
+
+export function consumeQrLoginToken(token) {
+  const settings = readStoredSettings();
+  if (!settings.enabled) {
+    const error = new Error('QR login is disabled.');
+    error.code = 'QR_LOGIN_DISABLED';
+    throw error;
+  }
+  if (!token || typeof token !== 'string') {
+    const error = new Error('QR login token is required.');
+    error.code = 'QR_LOGIN_TOKEN_REQUIRED';
+    throw error;
+  }
+
+  cleanupExpiredTokens();
+  const entry = qrLoginTokens.get(token);
+  qrLoginTokens.delete(token);
+  if (!entry) {
+    const error = new Error('QR login token is invalid or expired.');
+    error.code = 'QR_LOGIN_INVALID';
+    throw error;
+  }
+
+  const user = userDb.getUserById(entry.userId);
+  if (!user) {
+    const error = new Error('QR login user was not found.');
+    error.code = 'QR_LOGIN_USER_NOT_FOUND';
+    throw error;
+  }
+  return user;
+}

package/server/services/telegram/bot.js

@@ -7,6 +7,7 @@ import {
   handleTelegramControlCallback,
   handleTelegramControlMessage,
   isTelegramControlCommand,
+  sendActiveTerminalAttachedNotice,
   showMainMenu,
 } from './control-center.js';
 import { t } from './translations.js';
@@ -359,6 +360,20 @@ export const notifyUser = async ({ userId, kind, title, error }) => {
   return sendToUser(userId, text);
 };
 
+export const notifyTelegramTerminalAttached = async ({ userId, terminal }) => {
+  const link = telegramLinksDb.getByUserId(userId);
+  if (!bot) return { ok: false, reason: 'bot_not_running' };
+  if (!link?.chat_id || !link?.verified_at) return { ok: false, reason: 'telegram_not_paired' };
+  if (!terminal) return { ok: false, reason: 'missing_terminal' };
+  try {
+    await sendActiveTerminalAttachedNotice({ bot, chatId: link.chat_id, link, terminal });
+    return { ok: true };
+  } catch (err) {
+    console.warn('[telegram] terminal attach notice failed:', err?.message || err);
+    return { ok: false, reason: err?.message || String(err) };
+  }
+};
+
 // Boot the bot automatically if a token was previously persisted. This runs
 // once during server startup so a restart doesn't silently un-pair everyone.
 export const restoreBotFromConfig = async () => {