@yeaft/webchat-agent 1.0.188 → 1.0.190

package/local-runtime/server/auth/totp-auth.js

@@ -0,0 +1,133 @@
+import jwt from 'jsonwebtoken';
+import { CONFIG, getUserByUsername, isEmailConfigured, updateUserTotp } from '../config.js';
+import { sendVerificationCode } from '../email.js';
+import { verifyTotpCode } from '../totp.js';
+import { pendingVerifications, pendingTotpVerifications, pendingTotpSetup } from './session-store.js';
+import { completeLogin } from './login.js';
+import { generateVerificationCode, maskEmail } from './utils.js';
+
+/**
+ * Verify TOTP code (for returning users with TOTP enabled)
+ */
+export async function verifyTotpStep(tempToken, totpCode) {
+  const pending = pendingTotpVerifications.get(tempToken);
+
+  if (!pending) {
+    return { success: false, error: 'Invalid or expired TOTP verification token' };
+  }
+
+  if (Date.now() > pending.expiresAt) {
+    pendingTotpVerifications.delete(tempToken);
+    return { success: false, error: 'TOTP verification has expired' };
+  }
+
+  const user = getUserByUsername(pending.username);
+  if (!user || !user.totpSecret) {
+    pendingTotpVerifications.delete(tempToken);
+    return { success: false, error: 'User TOTP configuration not found' };
+  }
+
+  const isValid = verifyTotpCode(totpCode, user.totpSecret);
+  if (!isValid) {
+    return { success: false, error: 'Invalid TOTP code' };
+  }
+
+  pendingTotpVerifications.delete(tempToken);
+
+  // Check if email verification is needed
+  if (isEmailConfigured()) {
+    const code = generateVerificationCode();
+    const newTempToken = jwt.sign({ username: pending.username, type: 'temp' }, CONFIG.jwtSecret, { expiresIn: CONFIG.tempTokenExpiresIn });
+
+    pendingVerifications.set(newTempToken, {
+      username: pending.username,
+      code,
+      email: user.email,
+      sessionKey: pending.sessionKey,
+      role: pending.role,
+      expiresAt: Date.now() + CONFIG.emailCodeExpiresIn
+    });
+
+    try {
+      await sendVerificationCode(user.email, code, pending.username);
+    } catch (err) {
+      console.error('Failed to send verification email:', err.message);
+      pendingVerifications.delete(newTempToken);
+      return { success: false, error: 'Failed to send verification email' };
+    }
+
+    return {
+      success: true,
+      tempToken: newTempToken,
+      needEmailCode: true,
+      emailHint: maskEmail(user.email)
+    };
+  }
+
+  return completeLogin(pending.username, pending.sessionKey, pending.role);
+}
+
+/**
+ * Complete TOTP setup (for first-time TOTP configuration)
+ */
+export async function completeTotpSetup(setupToken, totpCode) {
+  const pending = pendingTotpSetup.get(setupToken);
+
+  if (!pending) {
+    return { success: false, error: 'Invalid or expired TOTP setup token' };
+  }
+
+  if (Date.now() > pending.expiresAt) {
+    pendingTotpSetup.delete(setupToken);
+    return { success: false, error: 'TOTP setup has expired' };
+  }
+
+  const isValid = verifyTotpCode(totpCode, pending.secret);
+  if (!isValid) {
+    return { success: false, error: 'Invalid TOTP code. Please try again.' };
+  }
+
+  const saved = await updateUserTotp(pending.username, {
+    totpSecret: pending.secret,
+    totpEnabled: true
+  });
+
+  if (!saved) {
+    return { success: false, error: 'Failed to save TOTP settings' };
+  }
+
+  pendingTotpSetup.delete(setupToken);
+
+  const user = getUserByUsername(pending.username);
+
+  if (isEmailConfigured() && user) {
+    const code = generateVerificationCode();
+    const tempToken = jwt.sign({ username: pending.username, type: 'temp' }, CONFIG.jwtSecret, { expiresIn: CONFIG.tempTokenExpiresIn });
+
+    pendingVerifications.set(tempToken, {
+      username: pending.username,
+      code,
+      email: user.email,
+      sessionKey: pending.sessionKey,
+      role: pending.role,
+      expiresAt: Date.now() + CONFIG.emailCodeExpiresIn
+    });
+
+    try {
+      await sendVerificationCode(user.email, code, pending.username);
+    } catch (err) {
+      console.error('Failed to send verification email:', err.message);
+      pendingVerifications.delete(tempToken);
+      return { success: false, error: 'Failed to send verification email' };
+    }
+
+    return {
+      success: true,
+      tempToken,
+      needEmailCode: true,
+      emailHint: maskEmail(user.email)
+    };
+  }
+
+  return completeLogin(pending.username, pending.sessionKey, pending.role);
+}

package/local-runtime/server/auth/utils.js

@@ -0,0 +1,42 @@
+import { randomInt } from 'crypto';
+import bcrypt from 'bcrypt';
+import { CONFIG } from '../config.js';
+import { generateSessionKey, encodeKey } from '../encryption.js';
+
+/**
+ * Generate a random verification code
+ */
+export function generateVerificationCode() {
+  const length = CONFIG.emailCodeLength;
+  let code = '';
+  for (let i = 0; i < length; i++) {
+    code += randomInt(10).toString();
+  }
+  return code;
+}
+
+/**
+ * Mask email for display (e.g., a***@example.com)
+ */
+export function maskEmail(email) {
+  const [local, domain] = email.split('@');
+  if (local.length <= 2) {
+    return `${local[0]}***@${domain}`;
+  }
+  return `${local[0]}${'*'.repeat(Math.min(local.length - 1, 3))}@${domain}`;
+}
+
+/**
+ * Hash a password for storage
+ */
+export async function hashPassword(password) {
+  return bcrypt.hash(password, 10);
+}
+
+/**
+ * Generate session key for skip-auth mode
+ */
+export function generateSkipAuthSession() {
+  const sessionKey = generateSessionKey();
+  return { sessionKey, sessionKeyEncoded: encodeKey(sessionKey) };
+}

package/local-runtime/server/auth.js

@@ -0,0 +1,8 @@
+// Re-export entry point — preserves all existing import paths.
+// Actual implementations are in server/auth/*.js sub-modules.
+export { loginStep1, loginStep2 } from './auth/login.js';
+export { verifyTotpStep, completeTotpSetup } from './auth/totp-auth.js';
+export { verifyToken, logout, maybeRenewToken } from './auth/token.js';
+export { verifyAgent, register } from './auth/register.js';
+export { hashPassword, generateSkipAuthSession } from './auth/utils.js';
+export { loginWithAad } from './auth/aad.js';

package/local-runtime/server/check-node-version.js

@@ -0,0 +1,74 @@
+/**
+ * check-node-version.js — Runtime guard for Node.js minimum version.
+ *
+ * The agent and server use `node:sqlite` (DatabaseSync) which is built-in
+ * to Node ≥ 22.5.0. On older Node the import fails with the cryptic
+ * `No such built-in module: node:sqlite`. We replace that with a clear
+ * actionable message and exit early.
+ *
+ * Why this exists even though `package.json` has `"engines": { "node": ">=22.5.0" }`:
+ *   - npm only WARNS on engines mismatch by default (not strict).
+ *   - `nvm use 22` selects whichever 22.x is already installed; if the
+ *     user has 22.0–22.4, they pass the major check but fail node:sqlite.
+ *   - Globally-installed CLIs (`@yeaft/webchat-agent`) bypass package.json
+ *     engines entirely on the user's system.
+ *
+ * Call `assertNodeVersion()` at the very top of every entry point (before
+ * any import that transitively touches `node:sqlite`).
+ */
+
+const MIN_MAJOR = 22;
+const MIN_MINOR = 5;
+
+/**
+ * Parse `process.version` ("v22.5.1") into [major, minor, patch].
+ * Returns null on unrecognized input rather than throwing — we never
+ * want this guard to break startup itself.
+ */
+function parseNodeVersion(v) {
+  if (typeof v !== 'string') return null;
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * @returns {boolean} true if current Node satisfies the minimum.
+ */
+export function isSupportedNodeVersion(versionString = process.version) {
+  const parsed = parseNodeVersion(versionString);
+  if (!parsed) return true; // unknown — don't block
+  const [major, minor] = parsed;
+  if (major > MIN_MAJOR) return true;
+  if (major < MIN_MAJOR) return false;
+  return minor >= MIN_MINOR;
+}
+
+/**
+ * Print a clear error and exit(1) if Node is too old.
+ *
+ * @param {{ component?: string }} [opts]
+ */
+export function assertNodeVersion(opts = {}) {
+  if (isSupportedNodeVersion()) return;
+  const component = opts.component || 'yeaft';
+  const required = `${MIN_MAJOR}.${MIN_MINOR}.0`;
+  const lines = [
+    '',
+    `✖  ${component} requires Node.js ≥ ${required}`,
+    `   Current: ${process.version}`,
+    '',
+    '   This project uses the built-in `node:sqlite` module which was',
+    `   added in Node ${required}.`,
+    '',
+    '   Fix:',
+    '     # if you use nvm:',
+    '     nvm install 22       # installs the latest 22.x (currently > 22.5)',
+    '     nvm use 22',
+    '',
+    '     # or upgrade Node from https://nodejs.org/',
+    '',
+  ];
+  process.stderr.write(lines.join('\n'));
+  process.exit(1);
+}

package/local-runtime/server/config.js

@@ -0,0 +1,298 @@
+import 'dotenv/config';
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { userDb } from './database.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Load users from environment variable or users.json file
+ * Format for AUTH_USERS: username:passwordHash:email
+ * TOTP settings are loaded from SQLite database
+ *
+ * On startup, users are migrated into SQLite with role='admin'.
+ * After migration, all runtime queries go through the database.
+ */
+function loadUsers() {
+  const users = [];
+
+  // Try loading from environment variable first
+  if (process.env.AUTH_USERS) {
+    const userEntries = process.env.AUTH_USERS.split(',');
+    for (const entry of userEntries) {
+      const parts = entry.split(':');
+      const [username, passwordHash, email] = parts;
+      if (username && passwordHash && email) {
+        const trimmedUsername = username.trim();
+        // Load TOTP settings from database
+        const totpData = userDb.getTotp(trimmedUsername);
+        users.push({
+          username: trimmedUsername,
+          passwordHash: passwordHash.trim(),
+          email: email.trim(),
+          totpSecret: totpData?.totpSecret || null,
+          totpEnabled: totpData?.totpEnabled || false
+        });
+      }
+    }
+  }
+
+  // Try loading from users.json file (fallback for backward compatibility)
+  const usersFile = join(__dirname, 'users.json');
+  if (existsSync(usersFile)) {
+    try {
+      const fileContent = JSON.parse(readFileSync(usersFile, 'utf-8'));
+      if (Array.isArray(fileContent.users)) {
+        for (const u of fileContent.users) {
+          // Skip if user already loaded from env
+          if (users.find(existing => existing.username === u.username)) continue;
+          // Load TOTP settings from database
+          const totpData = userDb.getTotp(u.username);
+          users.push({
+            ...u,
+            totpSecret: totpData?.totpSecret || u.totpSecret || null,
+            totpEnabled: totpData?.totpEnabled || u.totpEnabled || false
+          });
+        }
+      }
+    } catch (err) {
+      console.error('Failed to load users.json:', err.message);
+    }
+  }
+
+  // Migrate all loaded users into SQLite (idempotent)
+  let migrated = 0;
+  for (const u of users) {
+    const result = userDb.migrateUser(u.username, u.passwordHash, u.email, 'admin');
+    if (result) migrated++;
+  }
+  if (migrated > 0) {
+    console.log(`[Migration] Synced ${migrated} users from AUTH_USERS/users.json to database`);
+  }
+
+  return users;
+}
+
+// Default secrets - these MUST be changed in production
+const DEFAULT_JWT_SECRET = 'default-secret-change-in-production';
+const DEFAULT_AGENT_SECRET = 'agent-shared-secret';
+
+export const CONFIG = {
+  // Server settings
+  port: parseInt(process.env.PORT, 10) || 3456,
+  host: process.env.SERVER_HOST || undefined,
+
+  // Authentication
+  skipAuth: process.env.SKIP_AUTH === 'true',
+  users: loadUsers(),
+
+  // JWT settings
+  jwtSecret: process.env.JWT_SECRET || DEFAULT_JWT_SECRET,
+  jwtExpiresIn: process.env.JWT_EXPIRES_IN || '3d',
+  // Sliding renew: when an inbound request's token has less than this many ms
+  // remaining, requireAuth issues a fresh token via the X-New-Token response
+  // header. 1 day means an active user never sees an unexpected logout.
+  jwtRenewThresholdMs: parseInt(process.env.JWT_RENEW_THRESHOLD_MS, 10) || 24 * 60 * 60 * 1000,
+  tempTokenExpiresIn: process.env.TEMP_TOKEN_EXPIRES_IN || '10m',
+
+  // Email verification
+  emailCodeLength: parseInt(process.env.EMAIL_CODE_LENGTH, 10) || 6,
+  emailCodeExpiresIn: parseInt(process.env.EMAIL_CODE_EXPIRES_IN, 10) || 300000, // 5 minutes in ms
+
+  // SMTP settings
+  smtp: {
+    host: process.env.SMTP_HOST || '',
+    port: parseInt(process.env.SMTP_PORT, 10) || 587,
+    secure: process.env.SMTP_SECURE === 'true',
+    user: process.env.SMTP_USER || '',
+    pass: process.env.SMTP_PASS || '',
+    from: process.env.SMTP_FROM || 'WebChat <noreply@example.com>'
+  },
+
+  // Agent authentication (global fallback — per-user agent_secret is preferred)
+  agentSecret: process.env.AGENT_SECRET || DEFAULT_AGENT_SECRET,
+
+  // File upload settings
+  maxFileSize: parseInt(process.env.MAX_FILE_SIZE, 10) || 50 * 1024 * 1024, // 50MB
+  fileCleanupInterval: parseInt(process.env.FILE_CLEANUP_INTERVAL, 10) || 600000, // 10 minutes
+
+  // TOTP (Two-Factor Authentication) settings
+  totp: {
+    enabled: process.env.TOTP_ENABLED !== 'false', // Enable by default
+    issuer: process.env.TOTP_ISSUER || 'Claude Web Chat',
+    window: parseInt(process.env.TOTP_WINDOW, 10) || 1 // Allow 1 step before/after
+  },
+
+  // Azure AD (Microsoft Entra ID) SSO settings
+  aad: {
+    enabled: process.env.AAD_ENABLED === 'true',
+    clientId: process.env.AAD_CLIENT_ID || '',
+    tenantId: process.env.AAD_TENANT_ID || '',
+    autoCreateUser: process.env.AAD_AUTO_CREATE_USER !== 'false', // Auto-create local user on first AAD login
+    defaultRole: process.env.AAD_DEFAULT_ROLE || 'pro' // Default role for auto-created AAD users
+  },
+
+  // Multi-provider SSO settings (server-driven OAuth code flow)
+  // Each provider follows the same shape: { enabled, clientId/secret, callbackUrl, autoCreateUser, defaultRole }
+  // Microsoft re-uses the existing aad.* block above and is included here for the unified UI listing only.
+  sso: {
+    github: {
+      enabled: process.env.SSO_GITHUB_ENABLED === 'true',
+      clientId: process.env.SSO_GITHUB_CLIENT_ID || '',
+      clientSecret: process.env.SSO_GITHUB_CLIENT_SECRET || '',
+      callbackUrl: process.env.SSO_GITHUB_CALLBACK_URL || '',
+      autoCreateUser: process.env.SSO_GITHUB_AUTO_CREATE_USER !== 'false',
+      defaultRole: process.env.SSO_GITHUB_DEFAULT_ROLE || 'pro'
+    },
+    google: {
+      enabled: process.env.SSO_GOOGLE_ENABLED === 'true',
+      clientId: process.env.SSO_GOOGLE_CLIENT_ID || '',
+      clientSecret: process.env.SSO_GOOGLE_CLIENT_SECRET || '',
+      callbackUrl: process.env.SSO_GOOGLE_CALLBACK_URL || '',
+      autoCreateUser: process.env.SSO_GOOGLE_AUTO_CREATE_USER !== 'false',
+      defaultRole: process.env.SSO_GOOGLE_DEFAULT_ROLE || 'pro'
+    },
+    wechat: {
+      // PC web 扫码 (Open Platform 网页扫码) — open.weixin.qq.com/connect/qrconnect
+      enabled: process.env.SSO_WECHAT_ENABLED === 'true',
+      appId: process.env.SSO_WECHAT_APP_ID || '',
+      appSecret: process.env.SSO_WECHAT_APP_SECRET || '',
+      callbackUrl: process.env.SSO_WECHAT_CALLBACK_URL || '',
+      autoCreateUser: process.env.SSO_WECHAT_AUTO_CREATE_USER !== 'false',
+      defaultRole: process.env.SSO_WECHAT_DEFAULT_ROLE || 'pro'
+    },
+    alipay: {
+      // 支付宝网页授权 — oauth2/publicAppAuthorize.htm (RSA2 signing)
+      enabled: process.env.SSO_ALIPAY_ENABLED === 'true',
+      appId: process.env.SSO_ALIPAY_APP_ID || '',
+      privateKey: process.env.SSO_ALIPAY_PRIVATE_KEY || '',
+      alipayPublicKey: process.env.SSO_ALIPAY_PUBLIC_KEY || '',
+      callbackUrl: process.env.SSO_ALIPAY_CALLBACK_URL || '',
+      autoCreateUser: process.env.SSO_ALIPAY_AUTO_CREATE_USER !== 'false',
+      defaultRole: process.env.SSO_ALIPAY_DEFAULT_ROLE || 'pro'
+    }
+  }
+};
+
+/**
+ * Check if email is configured
+ */
+export function isEmailConfigured() {
+  return !!(CONFIG.smtp.host && CONFIG.smtp.user && CONFIG.smtp.pass);
+}
+
+/**
+ * Get user by username — queries database first, falls back to CONFIG.users
+ * @param {string} username
+ * @returns {object|null} Normalized user object with { username, passwordHash, email, totpSecret, totpEnabled, role, id }
+ */
+export function getUserByUsername(username) {
+  // Query database first (includes migrated, registered, and SSO-only users).
+  const dbUser = userDb.getByUsername(username);
+  if (dbUser) {
+    return {
+      username: dbUser.username,
+      passwordHash: dbUser.password_hash || null,
+      email: dbUser.email,
+      totpSecret: dbUser.totp_secret,
+      totpEnabled: !!dbUser.totp_enabled,
+      role: dbUser.role === 'admin' ? 'admin' : 'pro',
+      id: dbUser.id
+    };
+  }
+  // Fallback to CONFIG.users (only relevant before first migration)
+  return CONFIG.users.find(u => u.username === username) || null;
+}
+
+/**
+ * Update user TOTP settings in SQLite database
+ * @param {string} username
+ * @param {{totpSecret: string, totpEnabled: boolean}} data
+ * @returns {Promise<boolean>}
+ */
+export async function updateUserTotp(username, data) {
+  try {
+    userDb.updateTotp(username, data.totpSecret, data.totpEnabled);
+
+    // Update in-memory user data (CONFIG.users) for backward compat
+    const user = CONFIG.users.find(u => u.username === username);
+    if (user) {
+      user.totpSecret = data.totpSecret;
+      user.totpEnabled = data.totpEnabled;
+    }
+
+    console.log(`TOTP settings saved to database for user: ${username}`);
+    return true;
+  } catch (err) {
+    console.error('Failed to save TOTP settings:', err.message);
+    return false;
+  }
+}
+
+/**
+ * Check if TOTP is globally enabled
+ * @returns {boolean}
+ */
+export function isTotpEnabled() {
+  return CONFIG.totp?.enabled !== false;
+}
+
+/**
+ * Validate that required secrets are configured in production mode
+ * Throws an error if default secrets are used in production
+ */
+export function validateProductionConfig() {
+  if (CONFIG.skipAuth) {
+    // Development mode - skip validation
+    return { valid: true };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  // Check JWT_SECRET
+  if (CONFIG.jwtSecret === DEFAULT_JWT_SECRET) {
+    errors.push('JWT_SECRET must be set to a secure value in production mode');
+  }
+
+  // Check that at least one user with a password exists (in DB or config)
+  // Only warn (don't block startup) — allows first-time setup via create-user.js
+  const dbUsers = userDb.getAll();
+  const hasUserWithPassword = dbUsers.some(u => u.password_hash) || CONFIG.users.length > 0;
+  if (!hasUserWithPassword) {
+    warnings.push('No users configured. Create one with: node server/create-user.js <username> <password> [email]');
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, warnings: warnings.length > 0 ? warnings : undefined };
+}
+
+/**
+ * Check if Azure AD SSO is configured
+ * @returns {boolean}
+ */
+export function isAadEnabled() {
+  return CONFIG.aad?.enabled && !!CONFIG.aad.clientId && !!CONFIG.aad.tenantId;
+}
+
+/**
+ * Return the set of enabled SSO providers (excluding Microsoft, which is exposed via aadEnabled).
+ * Used by /api/auth/mode to drive the LoginPage button list.
+ * @returns {{ github: boolean, google: boolean, wechat: boolean, alipay: boolean }}
+ */
+export function getEnabledSsoProviders() {
+  const sso = CONFIG.sso || {};
+  return {
+    github: !!(sso.github?.enabled && sso.github.clientId && sso.github.clientSecret && sso.github.callbackUrl),
+    google: !!(sso.google?.enabled && sso.google.clientId && sso.google.clientSecret && sso.google.callbackUrl),
+    wechat: !!(sso.wechat?.enabled && sso.wechat.appId && sso.wechat.appSecret && sso.wechat.callbackUrl),
+    alipay: !!(sso.alipay?.enabled && sso.alipay.appId && sso.alipay.privateKey && sso.alipay.callbackUrl)
+  };
+}
+
+export default CONFIG;

package/local-runtime/server/context.js

@@ -0,0 +1,140 @@
+import { WebSocket } from 'ws';
+
+// 存储所有连接的 agents
+// agentId -> { ws, name, workDir, conversations: Map<convId, {workDir, claudeSessionId}>, sessionKey, isAlive, capabilities }
+export const agents = new Map();
+
+// 存储所有 web 客户端
+// clientId -> { ws, authenticated, currentAgent, currentConversation, sessionKey, isAlive }
+export const webClients = new Map();
+
+// 临时文件存储: fileId -> { name, mimeType, buffer, uploadedAt, userId }
+export const pendingFiles = new Map();
+
+// Port proxy
+export const pendingProxyRequests = new Map(); // requestId → { res, timeout, streaming }
+export const proxyWsConnections = new Map(); // proxyWsId → { browserWs, agentId }
+
+// Store pending agent connections (waiting for auth message)
+// tempId -> { ws, agentId, agentName, workDir, timeout }
+export const pendingAgentConnections = new Map();
+
+// ★ Phase 3: Server-side message queues
+// conversationId → [{id, prompt, workDir, userId, clientId, queuedAt, files}]
+export const serverMessageQueues = new Map();
+
+// ★ Phase 4: Directory listing cache
+// key: `${agentId}:${normalizedDirPath}` → { entries, timestamp }
+export const directoryCache = new Map();
+export const DIR_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+export const DIR_CACHE_MAX_SIZE = 500;
+
+// ★ Phase 5: File Tab state storage
+// key: `${userId}:${agentId}` → { files: [{path}], activeIndex, timestamp }
+export const userFileTabs = new Map();
+
+// Preview file cache for binary file preview (Office/PDF/Image)
+// fileId → { buffer, mimeType, filename, createdAt, token }
+export const previewFiles = new Map();
+
+// Admin dashboard usage stats.
+// userId → { requests, bytesSent, bytesReceived, messages, sessions }
+// `messages` is user turn count. bytesSent/bytesReceived are message traffic
+// only; heartbeat/control frames are deliberately excluded.
+export const userStatsDeltas = new Map();
+
+const HEARTBEAT_MESSAGE_TYPES = new Set([
+  'ping',
+  'pong',
+  'ping_session',
+  'pong_session',
+  'client_hello'
+]);
+
+const OUTBOUND_MESSAGE_TRAFFIC_TYPES = new Set([
+  'claude_output',
+  'yeaft_output',
+  'btw_stream',
+  'btw_done',
+  'btw_error',
+  'context_usage',
+  'ask_user_question'
+]);
+
+/**
+ * Get or initialize a stats delta entry for a user.
+ */
+function getOrCreateDelta(userId) {
+  let delta = userStatsDeltas.get(userId);
+  if (!delta) {
+    delta = {
+      requests: 0,
+      bytesSent: 0,
+      bytesReceived: 0,
+      messages: 0,
+      sessions: 0,
+    };
+    userStatsDeltas.set(userId, delta);
+  }
+  return delta;
+}
+
+export function isHeartbeatMessageType(type) {
+  return HEARTBEAT_MESSAGE_TYPES.has(type);
+}
+
+export function isOutboundMessageTraffic(type) {
+  return OUTBOUND_MESSAGE_TRAFFIC_TYPES.has(type);
+}
+
+/**
+ * Record a non-heartbeat WS request received from a user. This is kept for
+ * operator diagnostics; dashboard traffic comes from user-turn/message bytes.
+ */
+export function trackRequest(userId, bytesReceived, messageType = '') {
+  if (!userId || isHeartbeatMessageType(messageType)) return;
+  const delta = getOrCreateDelta(userId);
+  delta.requests++;
+}
+
+/**
+ * Record outbound message bytes sent to a user via WS.
+ */
+export function trackMessageBytesSent(userId, bytesSent, messageType = '') {
+  if (!userId || !bytesSent || !isOutboundMessageTraffic(messageType)) return;
+  const delta = getOrCreateDelta(userId);
+  delta.bytesSent += bytesSent;
+}
+
+/**
+ * Backward-compatible alias. Only message output frames are counted.
+ */
+export function trackBytesSent(userId, bytesSent, messageType = '') {
+  trackMessageBytesSent(userId, bytesSent, messageType);
+}
+
+/**
+ * Record a user turn and the inbound message payload bytes for it.
+ */
+export function trackUserTurn(userId, bytesReceived = 0) {
+  if (!userId) return;
+  const delta = getOrCreateDelta(userId);
+  delta.messages++;
+  delta.bytesReceived += Math.max(0, Number(bytesReceived) || 0);
+}
+
+/**
+ * Legacy name: a tracked "message" is now a user turn.
+ */
+export function trackMessage(userId, bytesReceived = 0) {
+  trackUserTurn(userId, bytesReceived);
+}
+
+/**
+ * Record a new session created by a user.
+ */
+export function trackSession(userId) {
+  if (!userId) return;
+  const delta = getOrCreateDelta(userId);
+  delta.sessions++;
+}