@yeaft/webchat-agent 1.0.188 → 1.0.189

package/cli.js

@@ -49,6 +49,14 @@ if (command === 'doctor') {
   await handleDoctorCommand();
 } else if (command === 'llm') {
   await handleLlmCommand(subArgs);
+} else if (command === 'local') {
+  try {
+    const { runLocal } = await import('./local-run.js');
+    await runLocal(subArgs);
+  } catch (error) {
+    console.error(`Local run failed: ${error.message}`);
+    process.exit(1);
+  }
 } else if (command === 'upgrade') {
   upgrade();
 } else if (command === '--version' || command === '-v') {
@@ -68,6 +76,7 @@ function printHelp() {
 
   Usage:
     yeaft-agent [options]              Run agent in foreground
+    yeaft-agent local --name <name>    Run local Web UI, server, and agent
     yeaft-agent install [options]      Install as system service
     yeaft-agent uninstall [options]    Remove system service
     yeaft-agent start [options]        Start installed service
@@ -84,6 +93,7 @@ function printHelp() {
     --instance <id>     Deprecated alias for the local service instance id
     --server <url>      WebSocket server URL (default: ws://localhost:3456)
     --name <name>       Agent name and instance id (letters, numbers, ._-)
+    --port <port>       Local server port (local command only; default: 6868)
     --secret <secret>   Agent secret for authentication
     --work-dir <dir>    Default working directory (default: cwd)
     --yeaft-dir <dir>   Yeaft data directory for this instance
@@ -98,6 +108,8 @@ function printHelp() {
     YEAFT_DIR           Yeaft data directory
 
   Examples:
+    yeaft-agent local --name my-worker
+    yeaft-agent local --name my-worker --port 7000
     yeaft-agent --server wss://your-server.com --name my-worker --secret xxx
     yeaft-agent install --server wss://your-server.com --name my-worker --secret xxx
     yeaft-agent install --server wss://your-server.com --name my-worker-2 --secret xxx

package/index.js

@@ -25,6 +25,7 @@ ctx.pkgName = pkg.name;
 
 // 配置文件路径（向后兼容：先查当前目录 .claude-agent.json）
 const LOCAL_CONFIG_FILE = join(process.cwd(), '.claude-agent.json');
+const IS_LOCAL_RUN = process.env.YEAFT_LOCAL_RUN === 'true';
 
 // 加载或创建配置
 function loadConfig() {
@@ -36,6 +37,10 @@ function loadConfig() {
     agentSecret: 'agent-shared-secret'
   };
 
+  // Local run receives its complete connection identity from the launcher and
+  // must not inherit a remote agent's persisted configuration.
+  if (IS_LOCAL_RUN) return defaults;
+
   // Priority 1: Local .claude-agent.json (backward compat)
   if (existsSync(LOCAL_CONFIG_FILE)) {
     try {
@@ -57,6 +62,7 @@ function loadConfig() {
 }
 
 function saveConfig(config) {
+  if (IS_LOCAL_RUN) return;
   writeFileSync(LOCAL_CONFIG_FILE, JSON.stringify(config, null, 2));
 }
 
@@ -336,8 +342,10 @@ process.on('SIGTERM', async () => {
 
 // 启动 - 先确保依赖，再检测能力，预热 models.dev 缓存，再连接
 (async () => {
-  await ensureDependencies();
-  await ensureYeaftSkills();
+  if (process.env.YEAFT_SKIP_STARTUP_INSTALLS !== 'true') {
+    await ensureDependencies();
+    await ensureYeaftSkills();
+  }
   ctx.agentCapabilities = await detectCapabilities();
   // Prime the models.dev community catalog so the Yeaft engine's *synchronous*
   // hot path (engine.js / config.js / cli.js all read context-window inline)

package/local-run.js

@@ -0,0 +1,218 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { createServer } from 'net';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { WebSocket } from 'ws';
+
+const DEFAULT_PORT = 6868;
+const LOCAL_HOST = '127.0.0.1';
+
+export function parseLocalArgs(args) {
+  const options = { name: '', port: DEFAULT_PORT };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const value = args[i + 1];
+    if (arg === '--name') {
+      if (!value || value.startsWith('-')) throw new Error('--name requires a value');
+      options.name = value;
+      i++;
+    } else if (arg === '--port') {
+      if (!value || value.startsWith('-')) throw new Error('--port requires a value');
+      if (!/^\d+$/.test(value)) throw new Error(`Invalid port: ${value}`);
+      options.port = Number(value);
+      if (options.port < 1 || options.port > 65535) throw new Error(`Invalid port: ${value}`);
+      i++;
+    } else {
+      throw new Error(`Unknown local option: ${arg}`);
+    }
+  }
+  if (!options.name) throw new Error('local requires --name <name>');
+  if (!/^[A-Za-z0-9._-]+$/.test(options.name)) {
+    throw new Error('Invalid name: use only letters, numbers, dot, underscore, or hyphen');
+  }
+  return options;
+}
+
+function runtimePaths() {
+  const agentDir = dirname(fileURLToPath(import.meta.url));
+  const packaged = join(agentDir, 'local-runtime');
+  if (existsSync(packaged)) {
+    return {
+      serverEntry: join(packaged, 'server', 'index.js'),
+      webDir: join(packaged, 'web'),
+    };
+  }
+  return {
+    serverEntry: join(agentDir, '..', 'server', 'index.js'),
+    webDir: join(agentDir, '..', 'web'),
+  };
+}
+
+async function assertPortAvailable(port) {
+  const probe = createServer();
+  await new Promise((resolve, reject) => {
+    probe.once('error', reject);
+    probe.listen(port, LOCAL_HOST, resolve);
+  }).catch(error => {
+    if (error.code === 'EADDRINUSE') {
+      throw new Error(`Port ${port} is already in use on ${LOCAL_HOST}`);
+    }
+    throw error;
+  });
+  await new Promise((resolve, reject) => probe.close(error => error ? reject(error) : resolve()));
+}
+
+async function waitForServer(url, server, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null) throw new Error(`Local server exited with code ${server.exitCode}`);
+    try {
+      const response = await fetch(`${url}/api/auth/mode`);
+      if (response.ok) {
+        const mode = await response.json();
+        if (!mode.skipAuth) throw new Error('Local server did not start in no-auth mode');
+        return;
+      }
+    } catch (error) {
+      if (error.message === 'Local server did not start in no-auth mode') throw error;
+      // Server is still starting.
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`Local server did not become ready at ${url}`);
+}
+
+async function waitForAgent(wsUrl, name, agent, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (agent.exitCode !== null) throw new Error(`Local agent exited with code ${agent.exitCode}`);
+    try {
+      const agents = await readAgentList(wsUrl);
+      if (agents.some(item => item.name === name || item.agentName === name)) return;
+    } catch {
+      // Agent is still connecting.
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`Local agent did not register as ${name}`);
+}
+
+function readAgentList(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`${wsUrl}?type=web`);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error('Timed out waiting for agent list'));
+    }, 1000);
+    ws.on('open', () => ws.send(JSON.stringify({ type: 'client_hello', plaintextOk: true })));
+    ws.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        if (message.type !== 'agent_list') return;
+        clearTimeout(timer);
+        ws.close();
+        resolve(message.agents || []);
+      } catch (error) {
+        clearTimeout(timer);
+        ws.terminate();
+        reject(error);
+      }
+    });
+    ws.on('error', error => {
+      clearTimeout(timer);
+      ws.terminate();
+      reject(error);
+    });
+  });
+}
+
+export async function runLocal(args, options = {}) {
+  const config = parseLocalArgs(args);
+  const paths = options.paths || runtimePaths();
+  const dataDir = options.dataDir || join(homedir(), '.yeaft', 'server');
+  const url = `http://${LOCAL_HOST}:${config.port}`;
+  const children = new Set();
+  const signalHandlers = new Map();
+  let stopping = false;
+  let stopPromise = null;
+
+  const stop = (exitCode = 0) => {
+    if (stopPromise) return stopPromise;
+    stopping = true;
+    stopPromise = (async () => {
+      for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+      for (const child of children) {
+        if (child.exitCode === null && !child.killed) child.kill('SIGTERM');
+      }
+      await Promise.all([...children].map(child => new Promise(resolve => {
+        if (child.exitCode !== null) return resolve();
+        const timer = setTimeout(() => {
+          if (child.exitCode === null) child.kill('SIGKILL');
+          resolve();
+        }, 6000);
+        child.once('exit', () => { clearTimeout(timer); resolve(); });
+      })));
+      if (options.exit !== false) process.exit(exitCode);
+    })();
+    return stopPromise;
+  };
+
+  await assertPortAvailable(config.port);
+
+  signalHandlers.set('SIGINT', () => void stop(0));
+  signalHandlers.set('SIGTERM', () => void stop(0));
+  for (const [signal, handler] of signalHandlers) process.once(signal, handler);
+
+  const spawnChild = options.spawn || spawn;
+  try {
+    const server = spawnChild(process.execPath, [paths.serverEntry], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        PORT: String(config.port),
+        SERVER_HOST: LOCAL_HOST,
+        SERVER_DATA_DIR: dataDir,
+        PERF_TRACE_DIR: join(dataDir, 'perf-traces'),
+        SKIP_AUTH: 'true',
+        WEB_DIR: paths.webDir,
+      },
+    });
+    children.add(server);
+
+    await (options.waitForServer || waitForServer)(url, server);
+
+    const agentDir = dirname(fileURLToPath(import.meta.url));
+    const agent = spawnChild(process.execPath, [join(agentDir, 'index.js')], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        SERVER_URL: `ws://${LOCAL_HOST}:${config.port}`,
+        AGENT_NAME: config.name,
+        YEAFT_AGENT_INSTANCE: config.name,
+        AGENT_SECRET: '',
+        YEAFT_LOCAL_RUN: 'true',
+        YEAFT_SKIP_STARTUP_INSTALLS: 'true',
+      },
+    });
+    children.add(agent);
+
+    const fail = childName => code => {
+      if (!stopping) {
+        console.error(`${childName} exited unexpectedly with code ${code}`);
+        void stop(code || 1);
+      }
+    };
+    server.once('exit', fail('Local server'));
+    agent.once('exit', fail('Local agent'));
+
+    await waitForAgent(`ws://${LOCAL_HOST}:${config.port}`, config.name, agent);
+
+    console.log(`Yeaft local is available at ${url}`);
+    return { url, server, agent, stop };
+  } catch (error) {
+    await stop(1);
+    throw error;
+  }
+}

package/local-runtime/server/.env.example

@@ -0,0 +1,54 @@
+# WebChat Server Configuration
+
+# Server port
+PORT=3456
+
+# Skip authentication (development mode)
+# Set to "true" to bypass login
+SKIP_AUTH=false
+
+# User configuration (two options)
+#
+# Option 1: Environment variable
+# Format: username:bcryptHash:email:totpSecret:totpEnabled
+# Multiple users separated by comma
+# Generate hash with: node -e "require('bcrypt').hash('password', 10).then(console.log)"
+# AUTH_USERS=admin:$2b$10$xxxxx:admin@example.com::false
+#
+# Option 2: users.json file (recommended)
+# See users.example.json for format
+
+# SMTP configuration for email verification
+# If not configured, email verification will be skipped
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your@gmail.com
+SMTP_PASS=your-app-password
+SMTP_FROM=WebChat <noreply@example.com>
+
+# JWT configuration
+JWT_SECRET=your-random-secret-key-change-this
+JWT_EXPIRES_IN=3d
+# Sliding renew threshold (ms). When a request's token has less than this much
+# life left, the server issues a refreshed token via the X-New-Token response
+# header. Default: 1 day.
+JWT_RENEW_THRESHOLD_MS=86400000
+TEMP_TOKEN_EXPIRES_IN=10m
+
+# Email verification code settings
+EMAIL_CODE_LENGTH=6
+EMAIL_CODE_EXPIRES_IN=300000
+
+# Agent authentication
+# Agents must provide this secret to connect
+AGENT_SECRET=agent-shared-secret
+
+# File upload settings
+MAX_FILE_SIZE=52428800
+FILE_CLEANUP_INTERVAL=600000
+
+# TOTP (Two-Factor Authentication) settings
+TOTP_ENABLED=true
+TOTP_ISSUER=Claude Web Chat
+TOTP_WINDOW=1

package/local-runtime/server/api.js

@@ -0,0 +1,111 @@
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { CONFIG } from './config.js';
+import { verifyToken, maybeRenewToken } from './auth.js';
+import { registerAuthRoutes } from './routes/auth-routes.js';
+import { registerInvitationRoutes } from './routes/invitation-routes.js';
+import { registerUserRoutes } from './routes/user-routes.js';
+import { registerSessionRoutes } from './routes/session-routes.js';
+import { registerUploadRoutes } from './routes/upload-routes.js';
+import { registerAdminRoutes } from './routes/admin-routes.js';
+import { registerExpertRoutes } from './routes/expert-routes.js';
+
+// 登录速率限制: IP -> { attempts, resetAt }
+const loginAttempts = new Map();
+const LOGIN_MAX_ATTEMPTS = 30;
+const LOGIN_WINDOW_MS = 5 * 60 * 1000; // 5 分钟窗口
+
+function checkRateLimit(ip) {
+  const now = Date.now();
+  const record = loginAttempts.get(ip);
+  if (!record || now > record.resetAt) {
+    loginAttempts.set(ip, { attempts: 1, resetAt: now + LOGIN_WINDOW_MS });
+    return true;
+  }
+  record.attempts++;
+  return record.attempts <= LOGIN_MAX_ATTEMPTS;
+}
+
+// 定期清理过期的速率限制记录
+setInterval(() => {
+  const now = Date.now();
+  for (const [ip, record] of loginAttempts) {
+    if (now > record.resetAt) loginAttempts.delete(ip);
+  }
+}, 5 * 60 * 1000);
+
+/**
+ * Middleware to verify JWT token for protected API routes
+ */
+function requireAuth(req, res, next) {
+  if (CONFIG.skipAuth) {
+    req.user = { username: 'dev-user', role: 'admin' };
+    return next();
+  }
+
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  const token = authHeader.replace('Bearer ', '');
+  const result = verifyToken(token);
+
+  if (!result.valid) {
+    return res.status(401).json({ error: 'Invalid or expired token' });
+  }
+
+  // Sliding renewal: if the token is in the last `jwtRenewThresholdMs` of its
+  // life, mint a fresh one and surface it to the client via X-New-Token. The
+  // browser fetch wrapper picks this up and swaps localStorage transparently.
+  // Skip renewal for non-session tokens (temp/totp/totp-setup) — those have
+  // their own short-lived semantics and must not be promoted to full sessions.
+  if (!result.type) {
+    const fresh = maybeRenewToken(token, result.exp, result.username);
+    if (fresh) {
+      res.setHeader('X-New-Token', fresh);
+    }
+  }
+
+  req.user = { username: result.username, role: result.role === 'admin' ? 'admin' : 'pro' };
+  next();
+}
+
+/**
+ * Middleware to require admin role
+ */
+function requireAdmin(req, res, next) {
+  if (CONFIG.skipAuth) return next();
+  if (req.user.role !== 'admin') {
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+  next();
+}
+
+// Read version from version.json (injected at Docker build time)
+const __apiDirname = dirname(fileURLToPath(import.meta.url));
+let serverVersion = 'dev';
+try {
+  const versionFile = JSON.parse(readFileSync(join(__apiDirname, '../version.json'), 'utf-8'));
+  serverVersion = versionFile.version || 'dev';
+} catch {}
+
+// Shared middleware/helpers passed to sub-route modules
+const shared = { requireAuth, requireAdmin, checkRateLimit };
+
+export function registerApiRoutes(app) {
+  // Version API
+  app.get('/api/version', (req, res) => {
+    res.json({ version: serverVersion });
+  });
+
+  // Delegate to sub-route modules
+  registerAuthRoutes(app, shared);
+  registerInvitationRoutes(app, shared);
+  registerUserRoutes(app, shared);
+  registerSessionRoutes(app, shared);
+  registerUploadRoutes(app, shared);
+  registerAdminRoutes(app, shared);
+  registerExpertRoutes(app, shared);
+}

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

@@ -0,0 +1,235 @@
+import jwt from 'jsonwebtoken';
+import { CONFIG, isAadEnabled, getUserByUsername } from '../config.js';
+import { generateSessionKey, encodeKey } from '../encryption.js';
+import { userDb, identityDb } from '../database.js';
+import { completeLogin } from './login.js';
+
+/**
+ * Microsoft OIDC public keys cache
+ * Keys are fetched from Microsoft's JWKS endpoint and cached.
+ */
+let _jwksCache = null;
+let _jwksCacheExpiry = 0;
+const JWKS_CACHE_TTL = 3600000; // 1 hour
+
+/**
+ * Fetch Microsoft's OIDC public signing keys (JWKS)
+ * @returns {Promise<Array>} Array of JWK key objects
+ */
+async function getSigningKeys() {
+  const now = Date.now();
+  if (_jwksCache && now < _jwksCacheExpiry) {
+    return _jwksCache;
+  }
+
+  const tenantId = CONFIG.aad.tenantId;
+  const jwksUrl = `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`;
+
+  const response = await fetch(jwksUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch JWKS: ${response.status}`);
+  }
+
+  const data = await response.json();
+  _jwksCache = data.keys;
+  _jwksCacheExpiry = now + JWKS_CACHE_TTL;
+  return _jwksCache;
+}
+
+/**
+ * Convert a JWK RSA key to PEM format for jwt.verify()
+ * @param {Object} jwk - JWK key object with n (modulus) and e (exponent)
+ * @returns {string} PEM-formatted public key
+ */
+function jwkToPem(jwk) {
+  // Base64url decode
+  const base64UrlToBuffer = (str) => {
+    let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) base64 += '=';
+    return Buffer.from(base64, 'base64');
+  };
+
+  const n = base64UrlToBuffer(jwk.n);
+  const e = base64UrlToBuffer(jwk.e);
+
+  // DER encode RSA public key
+  const encodeDerLength = (length) => {
+    if (length < 0x80) return Buffer.from([length]);
+    if (length < 0x100) return Buffer.from([0x81, length]);
+    return Buffer.from([0x82, (length >> 8) & 0xff, length & 0xff]);
+  };
+
+  const encodeDerInteger = (buf) => {
+    // Prepend 0x00 if high bit set (to ensure positive integer)
+    const needsPad = buf[0] & 0x80;
+    const content = needsPad ? Buffer.concat([Buffer.from([0x00]), buf]) : buf;
+    return Buffer.concat([Buffer.from([0x02]), encodeDerLength(content.length), content]);
+  };
+
+  const nDer = encodeDerInteger(n);
+  const eDer = encodeDerInteger(e);
+
+  // SEQUENCE { n INTEGER, e INTEGER }
+  const rsaKeyBody = Buffer.concat([nDer, eDer]);
+  const rsaKeySeq = Buffer.concat([Buffer.from([0x30]), encodeDerLength(rsaKeyBody.length), rsaKeyBody]);
+
+  // BIT STRING wrapper
+  const bitString = Buffer.concat([Buffer.from([0x03]), encodeDerLength(rsaKeySeq.length + 1), Buffer.from([0x00]), rsaKeySeq]);
+
+  // AlgorithmIdentifier: OID 1.2.840.113549.1.1.1 (rsaEncryption) + NULL
+  const algorithmId = Buffer.from([
+    0x30, 0x0d,
+    0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01,
+    0x05, 0x00
+  ]);
+
+  // SubjectPublicKeyInfo SEQUENCE
+  const spkiBody = Buffer.concat([algorithmId, bitString]);
+  const spki = Buffer.concat([Buffer.from([0x30]), encodeDerLength(spkiBody.length), spkiBody]);
+
+  // PEM encode
+  const base64 = spki.toString('base64');
+  const lines = base64.match(/.{1,64}/g).join('\n');
+  return `-----BEGIN PUBLIC KEY-----\n${lines}\n-----END PUBLIC KEY-----`;
+}
+
+/**
+ * Verify a Microsoft id_token
+ * @param {string} idToken - The id_token from MSAL.js
+ * @returns {Promise<Object>} Decoded token payload with user info
+ */
+async function verifyIdToken(idToken) {
+  // Decode header to get kid (key ID)
+  const headerB64 = idToken.split('.')[0];
+  const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString());
+
+  if (!header.kid) {
+    throw new Error('Token missing kid header');
+  }
+
+  // Find matching signing key
+  const keys = await getSigningKeys();
+  const signingKey = keys.find(k => k.kid === header.kid);
+  if (!signingKey) {
+    // Invalidate cache and retry once
+    _jwksCache = null;
+    const freshKeys = await getSigningKeys();
+    const freshKey = freshKeys.find(k => k.kid === header.kid);
+    if (!freshKey) {
+      throw new Error('No matching signing key found');
+    }
+    return verifyWithKey(idToken, freshKey);
+  }
+
+  return verifyWithKey(idToken, signingKey);
+}
+
+/**
+ * Verify token with a specific JWK key
+ */
+function verifyWithKey(idToken, jwk) {
+  const pem = jwkToPem(jwk);
+  const tenantId = CONFIG.aad.tenantId;
+
+  const decoded = jwt.verify(idToken, pem, {
+    algorithms: ['RS256'],
+    audience: CONFIG.aad.clientId,
+    issuer: `https://login.microsoftonline.com/${tenantId}/v2.0`
+  });
+
+  return decoded;
+}
+
+/**
+ * Handle AAD login: verify id_token, find or create user, return JWT
+ * @param {string} idToken - Microsoft id_token from frontend MSAL.js
+ * @returns {Promise<Object>} Login result with token, sessionKey, role
+ */
+export async function loginWithAad(idToken) {
+  if (!isAadEnabled()) {
+    return { success: false, error: 'Azure AD login is not enabled' };
+  }
+
+  if (!idToken) {
+    return { success: false, error: 'id_token is required' };
+  }
+
+  let decoded;
+  try {
+    decoded = await verifyIdToken(idToken);
+  } catch (err) {
+    console.error('[AAD] Token verification failed:', err.message);
+    return { success: false, error: 'Invalid Microsoft token' };
+  }
+
+  // Extract user info from id_token
+  const aadOid = decoded.oid || decoded.sub; // Object ID (unique per user per tenant)
+  const email = decoded.preferred_username || decoded.email || decoded.upn;
+  const name = decoded.name || email?.split('@')[0] || 'aad-user';
+
+  if (!aadOid) {
+    return { success: false, error: 'Token missing user identifier (oid)' };
+  }
+
+  // 1. Try to find existing user by AAD OID
+  let user = userDb.getByAadOid(aadOid);
+
+  // 2. If not found by OID, try to match by email/username (link existing account)
+  if (!user && email) {
+    const existingByEmail = userDb.getByUsername(email.split('@')[0]);
+    if (existingByEmail && existingByEmail.email === email) {
+      // Link existing user to AAD
+      userDb.updateAadOid(existingByEmail.id, aadOid);
+      user = existingByEmail;
+      console.log(`[AAD] Linked existing user '${existingByEmail.username}' to AAD OID ${aadOid}`);
+    }
+  }
+
+  // 3. Auto-create user if configured
+  if (!user) {
+    if (!CONFIG.aad.autoCreateUser) {
+      return { success: false, error: 'No matching local account found. Contact your admin.' };
+    }
+
+    // Generate unique username from email or name
+    let username = email ? email.split('@')[0] : name;
+    // Sanitize username: only allow letters, numbers, hyphens, underscores
+    username = username.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+    // Ensure uniqueness
+    let candidate = username;
+    let suffix = 1;
+    while (userDb.getByUsername(candidate)) {
+      candidate = `${username}_${suffix++}`;
+    }
+
+    const role = CONFIG.aad.defaultRole || 'pro';
+    user = userDb.createFromAad(candidate, email, aadOid, role);
+    console.log(`[AAD] Auto-created user '${candidate}' (email: ${email}, role: ${role})`);
+  }
+
+  // 4. Complete login (same as password login)
+  const sessionKey = generateSessionKey();
+  const role = user.role === 'admin' ? 'admin' : 'pro';
+
+  // Update last login
+  if (user.id) {
+    userDb.updateLogin(user.id);
+  }
+
+  // Mirror this AAD login into the unified user_identities table so the
+  // multi-provider binding view works for legacy AAD users too.
+  try {
+    identityDb.upsert({
+      userId: user.id,
+      provider: 'microsoft',
+      subject: aadOid,
+      email,
+      displayName: name
+    });
+  } catch (e) {
+    console.warn('[AAD] failed to upsert user_identities row:', e.message);
+  }
+
+  return completeLogin(user.username, sessionKey, role);
+}