kiro-mobile-bridge 1.0.21 → 1.0.23

package/README.md

@@ -8,6 +8,7 @@ A lightweight mobile interface that lets you monitor and control Kiro IDE agent
 ## Features
 
 - 📱 Mobile-optimized web interface with tab navigation
+- 🔑 **OTP Authentication** - 6-digit access code generated on server startup
 - 💬 **Chat** - View and send messages to Kiro's agent
 - 📝 **Code** - Browse file explorer and view files with syntax highlighting
 - 📋 **Tasks** - View and navigate Kiro spec task files
@@ -24,11 +25,13 @@ A lightweight mobile interface that lets you monitor and control Kiro IDE agent
 
 Start Kiro with the remote debugging port enabled:
 
-**Run Kiro with debugging port on terminal:**
+**Run Kiro with debugging port on CMD/Terminal:**
 ```bash
 kiro --remote-debugging-port=9000
 ```
 
+**Important:** Your project must be open in Kiro before you close it - the bridge needs an active session to detect and connect to. After that, start Kiro from the terminal with the remote debugging port enabled.
+
 ### 2. Run with npx (Recommended)
 
 Start Server
@@ -53,15 +56,29 @@ Kiro Mobile Bridge
 ─────────────────────
 Local:   http://localhost:3000
 Network: http://192.168.16.106:3000
-Open the Network URL on your phone to monitor Kiro.
+
+🔑 Access Code: 847291
+
+Enter this code on your device to connect.
 ```
 
 ### 3. Open on Your Phone
 
 1. Make sure your phone is on the **same WiFi network** as your computer
 2. Open the **Network URL** (e.g., `http://192.168.1.100:3000`) in your phone's browser
-3. The interface will automatically connect and show your Kiro session
-4. Use the tabs to switch between Chat, Code, and Tasks panels
+3. Enter the **6-digit access code** shown in the terminal
+4. The interface will connect and show your Kiro session
+5. Use the tabs to switch between Chat, Code, and Tasks panels
+
+> **Note:** The access code is single-use — only one device can authenticate per server session. Restart the server to generate a new code.
+
+#### Disable Authentication
+
+For trusted environments where you want the original no-auth experience:
+
+```bash
+npx kiro-mobile-bridge --no-auth
+```
 
 
 #### How It Works
@@ -99,6 +116,23 @@ Open the Network URL on your phone to monitor Kiro.
 - Check your firewall allows connections on port 3000
 - Try the IP address shown in the server output (not `localhost`)
 
+#### Windows: Works on your computer but not on mobile, even on same WiFi.
+
+**Root Cause:** Node.js firewall rule only allows **Public** networks by default. If your network is set to **Private**, mobile devices can't connect.
+
+**Quick Fix - Option 1: Change Network to Public (Easiest)**
+1. Open **Settings** → **Network & Internet**
+2. Click your connection (WiFi or Ethernet)
+3. Under "Network profile type", select **Public network (Recommended)**
+4. Try accessing from mobile again
+
+**Quick Fix - Option 2: Update Firewall Rule (Better for home networks)**
+
+Run this command **as Administrator** (Win + X → Terminal Admin):
+```cmd
+netsh advfirewall firewall set rule name="Node.js JavaScript Runtime" new profile=private,public
+```
+
 #### Linux: Firewall blocking connections
 
 If you're on Linux and can't connect from your phone, your firewall may be blocking port 3000. Allow it with:
@@ -113,13 +147,12 @@ sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
 
 ## Security Notes
 
-#### Only run this on trusted networks.
-**This is designed for local network use only:**
-
-- No authentication
-- No HTTPS
-- Exposes Kiro's chat interface to anyone on your network
-
+#### OTP Authentication
+- A **6-digit access code** is generated on each server startup and displayed in the terminal
+- The code is **single-use** — once a device authenticates, the code is consumed and all other devices are immediately locked out
+- New devices opening the login page during lockout or after the code is consumed will see a locked UI immediately
+- Sessions use **HttpOnly cookies** — tokens are not exposed to client-side JavaScript
+- Use `--no-auth` to disable authentication for fully trusted environments
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-mobile-bridge",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "A simple mobile web interface for monitoring Kiro IDE agent sessions from your phone over LAN",
   "type": "module",
   "main": "src/server.js",

package/src/middleware/auth.js

@@ -0,0 +1,515 @@
+/**
+ * OTP Authentication Middleware
+ * Generates a single-use 6-digit OTP on server startup.
+ * After successful verification, issues an HttpOnly session cookie.
+ * Single-device only — no regeneration until server restart.
+ * 
+ * NOTE: crypto.randomInt is used for OTP generation (cryptographically secure).
+ * crypto.randomBytes is used for session tokens (cryptographically secure).
+ */
+import crypto from 'crypto';
+import { OTP_MAX_ATTEMPTS, OTP_LOCKOUT_MS } from '../utils/constants.js';
+
+// =============================================================================
+// State
+// =============================================================================
+
+/** @type {{ otp: string, consumed: boolean, sessionToken: string|null }} */
+const authState = {
+  otp: '',
+  consumed: false,
+  sessionToken: null
+};
+
+/** @type {{ attempts: number, lockedUntil: number }} */
+const rateLimitState = {
+  attempts: 0,
+  lockedUntil: 0
+};
+
+/** @type {boolean} */
+let authEnabled = true;
+
+// =============================================================================
+// OTP Generation & Verification
+// =============================================================================
+
+/**
+ * Generate a new 6-digit OTP (cryptographically random)
+ * Called once on server startup
+ * @returns {string} 6-digit OTP
+ */
+export function generateOTP() {
+  // crypto.randomInt generates a cryptographically secure random integer
+  const code = crypto.randomInt(100000, 999999 + 1);
+  authState.otp = String(code);
+  authState.consumed = false;
+  authState.sessionToken = null;
+  rateLimitState.attempts = 0;
+  rateLimitState.lockedUntil = 0;
+  return authState.otp;
+}
+
+/**
+ * Get the current OTP (for terminal display)
+ * @returns {string}
+ */
+export function getOTP() {
+  return authState.otp;
+}
+
+/**
+ * Set whether auth is enabled
+ * @param {boolean} enabled
+ */
+export function setAuthEnabled(enabled) {
+  authEnabled = enabled;
+}
+
+/**
+ * Check if auth is enabled
+ * @returns {boolean}
+ */
+export function isAuthEnabled() {
+  return authEnabled;
+}
+
+/**
+ * Verify OTP code
+ * Returns session token on success, null on failure.
+ * OTP is single-use — once consumed, further attempts are rejected.
+ * 
+ * @param {string} code - The 6-digit OTP to verify
+ * @returns {{ success: boolean, token?: string, error?: string, retryAfter?: number }}
+ */
+export function verifyOTP(code) {
+  const now = Date.now();
+
+  // Check rate limit lockout
+  if (rateLimitState.lockedUntil > now) {
+    const retryAfter = Math.ceil((rateLimitState.lockedUntil - now) / 1000);
+    return {
+      success: false,
+      error: `Too many attempts. Try again in ${retryAfter}s.`,
+      retryAfter
+    };
+  }
+
+  // Reset attempt counter once lockout period has expired
+  if (rateLimitState.lockedUntil > 0 && rateLimitState.lockedUntil <= now) {
+    rateLimitState.attempts = 0;
+    rateLimitState.lockedUntil = 0;
+  }
+
+  // OTP already consumed — no new sessions allowed
+  // Still enforce rate limiting to prevent brute-force probing
+  if (authState.consumed) {
+    rateLimitState.attempts++;
+    if (rateLimitState.attempts >= OTP_MAX_ATTEMPTS) {
+      rateLimitState.lockedUntil = now + OTP_LOCKOUT_MS;
+      return {
+        success: false,
+        consumed: true,
+        error: `Too many attempts. Try again in ${OTP_LOCKOUT_MS / 1000}s.`,
+        retryAfter: OTP_LOCKOUT_MS / 1000
+      };
+    }
+    return {
+      success: false,
+      consumed: true,
+      error: 'Access code already used. Restart the server for a new code.'
+    };
+  }
+
+  // Validate input format
+  if (!code || typeof code !== 'string' || !/^\d{6}$/.test(code)) {
+    rateLimitState.attempts++;
+    if (rateLimitState.attempts >= OTP_MAX_ATTEMPTS) {
+      rateLimitState.lockedUntil = now + OTP_LOCKOUT_MS;
+      return {
+        success: false,
+        error: `Too many attempts. Try again in ${OTP_LOCKOUT_MS / 1000}s.`,
+        retryAfter: OTP_LOCKOUT_MS / 1000
+      };
+    }
+    return { success: false, error: 'Invalid code format.' };
+  }
+
+  // Timing-safe comparison to prevent timing attacks
+  const codeBuffer = Buffer.from(code);
+  const otpBuffer = Buffer.from(authState.otp);
+  if (codeBuffer.length !== otpBuffer.length || !crypto.timingSafeEqual(codeBuffer, otpBuffer)) {
+    rateLimitState.attempts++;
+    if (rateLimitState.attempts >= OTP_MAX_ATTEMPTS) {
+      rateLimitState.lockedUntil = now + OTP_LOCKOUT_MS;
+      return {
+        success: false,
+        error: `Too many attempts. Try again in ${OTP_LOCKOUT_MS / 1000}s.`,
+        retryAfter: OTP_LOCKOUT_MS / 1000
+      };
+    }
+    return {
+      success: false,
+      error: `Invalid code. ${OTP_MAX_ATTEMPTS - rateLimitState.attempts} attempts remaining.`
+    };
+  }
+
+  // Success — mark consumed, generate session token
+  authState.consumed = true;
+  authState.sessionToken = crypto.randomBytes(32).toString('hex');
+  rateLimitState.attempts = 0;
+
+  return { success: true, token: authState.sessionToken };
+}
+
+/**
+ * Get current rate limit status (for exposing via API)
+ * @returns {{ locked: boolean, retryAfter: number }}
+ */
+export function getRateLimitStatus() {
+  const now = Date.now();
+  if (rateLimitState.lockedUntil > now) {
+    return { locked: true, consumed: authState.consumed, retryAfter: Math.ceil((rateLimitState.lockedUntil - now) / 1000) };
+  }
+  return { locked: false, consumed: authState.consumed, retryAfter: 0 };
+}
+
+/**
+ * Validate a session token
+ * @param {string} token - Session token to validate
+ * @returns {boolean}
+ */
+export function validateSession(token) {
+  if (!token || typeof token !== 'string') return false;
+  if (!authState.sessionToken) return false;
+
+  // Timing-safe comparison
+  const tokenBuffer = Buffer.from(token);
+  const sessionBuffer = Buffer.from(authState.sessionToken);
+  if (tokenBuffer.length !== sessionBuffer.length) return false;
+  return crypto.timingSafeEqual(tokenBuffer, sessionBuffer);
+}
+
+// =============================================================================
+// Cookie Parsing Helper
+// =============================================================================
+
+/**
+ * Parse session token from cookie header
+ * @param {string} cookieHeader - Raw Cookie header value
+ * @returns {string|null}
+ */
+function parseSessionCookie(cookieHeader) {
+  if (!cookieHeader || typeof cookieHeader !== 'string') return null;
+  const match = cookieHeader.match(/(?:^|;\s*)kmb_session=([a-f0-9]{64})(?:;|$)/);
+  return match ? match[1] : null;
+}
+
+// =============================================================================
+// Express Middleware
+// =============================================================================
+
+/** Routes that bypass authentication */
+const PUBLIC_PATHS = new Set(['/auth/login', '/auth/verify', '/auth/status']);
+
+/**
+ * Express authentication middleware
+ * Checks for valid session cookie on all requests except auth routes.
+ * Redirects page requests to login, returns 401 for API/fetch requests.
+ */
+export function authMiddleware(req, res, next) {
+  // Skip auth entirely if disabled (--no-auth flag)
+  if (!authEnabled) return next();
+
+  // Allow public auth routes
+  if (PUBLIC_PATHS.has(req.path)) return next();
+
+  // Parse session token from cookie
+  const token = parseSessionCookie(req.headers.cookie);
+
+  if (token && validateSession(token)) {
+    return next();
+  }
+
+  // Not authenticated — determine response type
+  const wantsJSON = req.headers.accept?.includes('application/json') ||
+    req.headers['content-type']?.includes('application/json') ||
+    req.xhr;
+
+  if (wantsJSON) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  // Redirect browser requests to login page
+  return res.redirect('/auth/login');
+}
+
+// =============================================================================
+// WebSocket Auth
+// =============================================================================
+
+/**
+ * Validate WebSocket connection authentication
+ * Checks session token from the cookie header on the upgrade request.
+ * Browsers automatically send cookies with WebSocket upgrade requests,
+ * so we don't need to pass the token via query string.
+ * 
+ * @param {import('http').IncomingMessage} req - Upgrade request
+ * @returns {boolean}
+ */
+export function validateWSAuth(req) {
+  if (!authEnabled) return true;
+
+  try {
+    const cookie = req.headers.cookie || '';
+    const match = cookie.match(/(?:^|;\s*)kmb_session=([a-f0-9]{64})(?:;|$)/);
+    const token = match ? match[1] : null;
+    return validateSession(token);
+  } catch {
+    return false;
+  }
+}
+
+// =============================================================================
+// Login Page HTML
+// =============================================================================
+
+/**
+ * Generate the self-contained login page HTML
+ * Matches the dark theme of the main interface
+ * @returns {string}
+ */
+export function getLoginPageHTML() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+  <meta name="theme-color" content="#1e1e1e">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <title>Kiro Mobile Bridge — Access Code</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body {
+      height: 100%; overflow: hidden; background: #1e1e1e;
+      font-family: "Segoe WPC", "Segoe UI", -apple-system, BlinkMacSystemFont, system-ui, Ubuntu, sans-serif;
+      color: #cccccc;
+    }
+    .login-container {
+      display: flex; flex-direction: column; align-items: center; justify-content: center;
+      height: 100%; height: 100dvh; padding: 24px; text-align: center;
+    }
+    .logo { font-size: 28px; font-weight: 600; color: #ffffff; margin-bottom: 8px; }
+    .subtitle { font-size: 13px; color: #888; margin-bottom: 40px; }
+    .otp-label { font-size: 14px; color: #cccccc; margin-bottom: 16px; }
+    .otp-inputs {
+      display: flex; gap: 8px; margin-bottom: 24px; justify-content: center;
+    }
+    .otp-inputs input {
+      width: 48px; height: 56px; text-align: center; font-size: 24px; font-weight: 600;
+      background: #2d2d2d; border: 2px solid #3c3c3c; border-radius: 8px; color: #ffffff;
+      outline: none; caret-color: #0078d4; transition: border-color 0.15s;
+      -webkit-appearance: none; appearance: none;
+    }
+    .otp-inputs input:focus { border-color: #0078d4; }
+    .otp-inputs input.error { border-color: #f44336; animation: shake 0.4s; }
+    .otp-inputs input.success { border-color: #4caf50; }
+    .error-message {
+      color: #f44336; font-size: 13px; min-height: 20px; margin-bottom: 16px;
+      transition: opacity 0.2s;
+    }
+    .status-message {
+      color: #4caf50; font-size: 13px; min-height: 20px; margin-bottom: 16px;
+    }
+    .hint {
+      font-size: 12px; color: #666; max-width: 280px; line-height: 1.5;
+    }
+    @keyframes shake {
+      0%, 100% { transform: translateX(0); }
+      25% { transform: translateX(-6px); }
+      50% { transform: translateX(6px); }
+      75% { transform: translateX(-4px); }
+    }
+    @keyframes fadeIn {
+      from { opacity: 0; transform: translateY(10px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    .login-container { animation: fadeIn 0.3s ease-out; }
+  </style>
+</head>
+<body>
+  <div class="login-container">
+    <div class="logo">Kiro Mobile Bridge</div>
+    <div class="subtitle">Remote IDE Monitor</div>
+    <div class="otp-label">Enter Access Code</div>
+    <div class="otp-inputs" id="otpInputs">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="one-time-code" aria-label="Digit 1">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="off" aria-label="Digit 2">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="off" aria-label="Digit 3">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="off" aria-label="Digit 4">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="off" aria-label="Digit 5">
+      <input type="tel" inputmode="numeric" pattern="[0-9]*" maxlength="1" autocomplete="off" aria-label="Digit 6">
+    </div>
+    <div id="errorMsg" class="error-message"></div>
+    <div class="hint">Check the terminal where you started the server for the 6-digit access code.</div>
+  </div>
+  <script>
+    const inputs = document.querySelectorAll('#otpInputs input');
+    const errorMsg = document.getElementById('errorMsg');
+    let submitting = false;
+
+    // Check lockout status on page load (covers new devices opening during lockout)
+    (async () => {
+      try {
+        const res = await fetch('/auth/status');
+        const data = await res.json();
+        if (data.consumed) {
+          // OTP already used by another device
+          showError('Access code already used. Restart the server for a new code.');
+          inputs.forEach(i => { i.disabled = true; });
+        } else if (data.locked && data.retryAfter > 0) {
+          startLockoutCountdown(data.retryAfter);
+        } else {
+          inputs[0].focus();
+        }
+      } catch {
+        inputs[0].focus();
+      }
+    })();
+
+    inputs.forEach((input, index) => {
+      input.addEventListener('input', (e) => {
+        const value = e.target.value.replace(/\\D/g, '');
+        e.target.value = value.slice(-1); // Keep only last digit
+
+        clearErrors();
+
+        if (value && index < inputs.length - 1) {
+          inputs[index + 1].focus();
+        }
+
+        // Auto-submit when all 6 digits entered
+        if (getCode().length === 6) {
+          submitOTP();
+        }
+      });
+
+      input.addEventListener('keydown', (e) => {
+        if (e.key === 'Backspace') {
+          if (!e.target.value && index > 0) {
+            inputs[index - 1].focus();
+            inputs[index - 1].value = '';
+          }
+        } else if (e.key === 'ArrowLeft' && index > 0) {
+          inputs[index - 1].focus();
+        } else if (e.key === 'ArrowRight' && index < inputs.length - 1) {
+          inputs[index + 1].focus();
+        }
+      });
+
+      // Handle paste (e.g., pasting full 6-digit code)
+      input.addEventListener('paste', (e) => {
+        e.preventDefault();
+        const pasted = (e.clipboardData.getData('text') || '').replace(/\\D/g, '').slice(0, 6);
+        if (pasted.length > 0) {
+          for (let i = 0; i < inputs.length; i++) {
+            inputs[i].value = pasted[i] || '';
+          }
+          const focusIndex = Math.min(pasted.length, inputs.length - 1);
+          inputs[focusIndex].focus();
+          if (pasted.length === 6) submitOTP();
+        }
+      });
+    });
+
+    function getCode() {
+      return Array.from(inputs).map(i => i.value).join('');
+    }
+
+    function clearErrors() {
+      errorMsg.textContent = '';
+      errorMsg.className = 'error-message';
+      inputs.forEach(i => i.classList.remove('error', 'success'));
+    }
+
+    function showError(msg) {
+      errorMsg.textContent = msg;
+      errorMsg.className = 'error-message';
+      inputs.forEach(i => i.classList.add('error'));
+    }
+
+    function showSuccess() {
+      errorMsg.textContent = 'Access granted!';
+      errorMsg.className = 'status-message';
+      inputs.forEach(i => {
+        i.classList.remove('error');
+        i.classList.add('success');
+        i.disabled = true;
+      });
+    }
+
+    let lockoutTimer = null;
+
+    function startLockoutCountdown(seconds) {
+      // Disable all inputs during lockout
+      inputs.forEach(i => { i.disabled = true; i.value = ''; });
+      let remaining = seconds;
+      showError('Too many attempts. Try again in ' + remaining + 's.');
+
+      if (lockoutTimer) clearInterval(lockoutTimer);
+      lockoutTimer = setInterval(() => {
+        remaining--;
+        if (remaining <= 0) {
+          clearInterval(lockoutTimer);
+          lockoutTimer = null;
+          clearErrors();
+          inputs.forEach(i => { i.disabled = false; });
+          inputs[0].focus();
+        } else {
+          showError('Too many attempts. Try again in ' + remaining + 's.');
+        }
+      }, 1000);
+    }
+
+    async function submitOTP() {
+      if (submitting || lockoutTimer) return;
+      submitting = true;
+
+      const code = getCode();
+      try {
+        const res = await fetch('/auth/verify', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ otp: code })
+        });
+        const data = await res.json();
+
+        if (data.success) {
+          showSuccess();
+          // Redirect to main app after brief success indication
+          setTimeout(() => { window.location.href = '/'; }, 600);
+        } else if (data.consumed) {
+          // OTP already used by another device — permanently lock
+          showError(data.error || 'Access code already used. Restart the server for a new code.');
+          inputs.forEach(i => { i.disabled = true; i.value = ''; });
+          if (data.retryAfter) startLockoutCountdown(data.retryAfter);
+        } else if (data.retryAfter) {
+          // Rate limited — start countdown
+          startLockoutCountdown(data.retryAfter);
+        } else {
+          showError(data.error || 'Invalid code.');
+          // Clear inputs on failure for retry
+          inputs.forEach(i => i.value = '');
+          inputs[0].focus();
+        }
+      } catch (err) {
+        showError('Connection error. Please try again.');
+      } finally {
+        submitting = false;
+      }
+    }
+  </script>
+</body>
+</html>`;
+}

package/src/public/index.html

@@ -1000,6 +1000,25 @@
     // State
     // =============================================================================
     let ws = null, reconnectAttempts = 0, reconnectTimeout = null;
+
+    // Handle 401 responses — redirect to login page
+    function handleAuthError(response) {
+      if (response && response.status === 401) {
+        window.location.href = '/auth/login';
+        return true;
+      }
+      return false;
+    }
+
+    // Wrap native fetch to auto-handle 401 auth errors
+    const _originalFetch = window.fetch;
+    window.fetch = async function (...args) {
+      const response = await _originalFetch.apply(this, args);
+      if (response.status === 401) {
+        window.location.href = '/auth/login';
+      }
+      return response;
+    };
     let cascades = [], selectedCascadeId = null, currentStyles = null;
     let isTypingInKiroInput = false, activePanel = 'chat';
     let lastSuccessfulSnapshot = null, navigationPending = false;
@@ -1085,6 +1104,7 @@
     // =============================================================================
     function connect() {
       const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      // Session cookie is automatically sent with the WebSocket upgrade request
       ws = new WebSocket(`${protocol}//${window.location.host}`);
 
       ws.onopen = () => { setStatus('connected'); reconnectAttempts = 0; };

package/src/server.js

@@ -27,6 +27,20 @@ import {
   SNAPSHOT_IDLE_THRESHOLD
 } from './utils/constants.js';
 
+// Auth
+import {
+  generateOTP,
+  getOTP,
+  setAuthEnabled,
+  isAuthEnabled,
+  authMiddleware,
+  validateWSAuth,
+  validateSession,
+  getLoginPageHTML,
+  verifyOTP,
+  getRateLimitStatus
+} from './middleware/auth.js';
+
 // Routes
 import { createApiRouter } from './routes/api.js';
 
@@ -38,6 +52,13 @@ const __dirname = dirname(__filename);
 // =============================================================================
 
 const PORT = process.env.PORT || 3000;
+const NO_AUTH = process.argv.includes('--no-auth');
+
+// Configure authentication
+setAuthEnabled(!NO_AUTH);
+if (!NO_AUTH) {
+  generateOTP();
+}
 
 // =============================================================================
 // State Management
@@ -66,24 +87,24 @@ async function discoverTargets() {
   const foundCascadeIds = new Set();
   let foundMainWindow = false;
   let stateChanged = false;
-  
+
   const portResults = await Promise.allSettled(
     CDP_PORTS.map(port => fetchCDPTargets(port).then(targets => ({ port, targets })))
   );
-  
+
   for (const result of portResults) {
     if (result.status !== 'fulfilled') continue;
     const { port, targets } = result.value;
-    
+
     try {
       // Find main VS Code window
       const mainWindowTarget = targets.find(target => {
         const url = (target.url || '').toLowerCase();
-        return target.type === 'page' && 
-               (url.startsWith('vscode-file://') || url.includes('workbench')) &&
-               target.webSocketDebuggerUrl;
+        return target.type === 'page' &&
+          (url.startsWith('vscode-file://') || url.includes('workbench')) &&
+          target.webSocketDebuggerUrl;
       });
-      
+
       if (mainWindowTarget && !mainWindowCDP.connection) {
         console.log(`[Discovery] Found main VS Code window: ${mainWindowTarget.title}`);
         try {
@@ -92,7 +113,7 @@ async function discoverTargets() {
           mainWindowCDP.id = generateId(mainWindowTarget.webSocketDebuggerUrl);
           foundMainWindow = true;
           stateChanged = true;
-          
+
           cdp.ws.on('close', () => {
             console.log(`[Discovery] Main window disconnected`);
             mainWindowCDP.connection = null;
@@ -105,25 +126,25 @@ async function discoverTargets() {
       } else if (mainWindowTarget) {
         foundMainWindow = true;
       }
-      
+
       // Find Kiro Agent webviews
       const kiroAgentTargets = targets.filter(target => {
         const url = (target.url || '').toLowerCase();
-        return (url.includes('kiroagent') || url.includes('vscode-webview')) && 
-               target.webSocketDebuggerUrl && target.type !== 'page';
+        return (url.includes('kiroagent') || url.includes('vscode-webview')) &&
+          target.webSocketDebuggerUrl && target.type !== 'page';
       });
-      
+
       for (const target of kiroAgentTargets) {
         const wsUrl = target.webSocketDebuggerUrl;
         const cascadeId = generateId(wsUrl);
         foundCascadeIds.add(cascadeId);
-        
+
         if (!cascades.has(cascadeId)) {
           stateChanged = true;
-          
+
           try {
             const cdp = await connectToCDP(wsUrl);
-            
+
             cascades.set(cascadeId, {
               id: cascadeId,
               cdp,
@@ -134,14 +155,14 @@ async function discoverTargets() {
               editor: null,
               editorHash: null
             });
-            
+
             cdp.ws.on('close', () => {
               console.log(`[Discovery] Cascade disconnected: ${cascadeId}`);
               cascades.delete(cascadeId);
               broadcastCascadeList();
               adjustDiscoveryInterval(true);
             });
-            
+
             broadcastCascadeList();
           } catch (err) {
             console.error(`[Discovery] Failed to connect to ${cascadeId}: ${err.message}`);
@@ -155,14 +176,14 @@ async function discoverTargets() {
       console.debug(`[Discovery] Error scanning port ${port}: ${err.message}`);
     }
   }
-  
+
   // Clean up disconnected targets
   for (const [cascadeId, cascade] of cascades) {
     if (!foundCascadeIds.has(cascadeId)) {
       console.log(`[Discovery] Target no longer available: ${cascadeId}`);
       stateChanged = true;
-      try { 
-        cascade.cdp.close(); 
+      try {
+        cascade.cdp.close();
       } catch (e) {
         console.debug(`[Discovery] Error closing cascade ${cascadeId}: ${e.message}`);
       }
@@ -170,10 +191,10 @@ async function discoverTargets() {
       broadcastCascadeList();
     }
   }
-  
+
   const mainWindowChanged = foundMainWindow !== pollingState.lastMainWindowConnected;
   const cascadeCountChanged = cascades.size !== pollingState.lastCascadeCount;
-  
+
   if (stateChanged || mainWindowChanged || cascadeCountChanged) {
     console.log(`[Discovery] Active cascades: ${cascades.size}${foundMainWindow ? ' (main window connected)' : ''}`);
     pollingState.lastCascadeCount = cascades.size;
@@ -190,21 +211,21 @@ async function discoverTargets() {
 
 async function pollSnapshots() {
   let anyChanges = false;
-  
+
   for (const [cascadeId, cascade] of cascades) {
     try {
       const cdp = cascade.cdp;
-      
+
       // Capture CSS once
       if (cascade.css === null) {
         cascade.css = await captureCSS(cdp);
       }
-      
+
       // Capture metadata
       const metadata = await captureMetadata(cdp);
       cascade.metadata.chatTitle = metadata.chatTitle || cascade.metadata.chatTitle;
       cascade.metadata.isActive = metadata.isActive;
-      
+
       // Capture chat snapshot
       const snapshot = await captureSnapshot(cdp);
       if (snapshot) {
@@ -216,7 +237,7 @@ async function pollSnapshots() {
           anyChanges = true;
         }
       }
-      
+
       // Capture editor from main window
       // Store rootContextId locally to avoid race conditions during async operations
       const mainCDP = mainWindowCDP.connection;
@@ -242,7 +263,7 @@ async function pollSnapshots() {
       console.error(`[Snapshot] Error polling cascade ${cascadeId}:`, err.message);
     }
   }
-  
+
   adjustSnapshotInterval(anyChanges);
 }
 
@@ -316,7 +337,7 @@ function broadcastCascadeList() {
     window: c.metadata?.windowTitle || 'Unknown',
     active: c.metadata?.isActive || false
   }));
-  
+
   const message = JSON.stringify({ type: 'cascade_list', cascades: cascadeList });
   for (const client of wss.clients) {
     if (client.readyState === WebSocket.OPEN) client.send(message);
@@ -338,6 +359,51 @@ app.use((req, res, next) => {
   next();
 });
 
+// Auth routes — must be before authMiddleware
+app.get('/auth/login', (req, res) => {
+  res.type('html').send(getLoginPageHTML());
+});
+
+app.post('/auth/verify', (req, res) => {
+  const { otp } = req.body;
+  const result = verifyOTP(otp);
+
+  if (result.success) {
+    // Set HttpOnly session cookie (no Secure flag — this is HTTP-only LAN tool)
+    res.cookie('kmb_session', result.token, {
+      httpOnly: true,
+      sameSite: 'strict',
+      path: '/'
+    });
+    console.log(`[Auth] Device authenticated successfully`);
+    res.json({ success: true });
+  } else {
+    console.log(`[Auth] Failed attempt: ${result.error}`);
+    res.status(401).json({
+      success: false,
+      error: result.error,
+      retryAfter: result.retryAfter || null
+    });
+  }
+});
+
+app.get('/auth/status', (req, res) => {
+  const cookie = req.headers.cookie || '';
+  const match = cookie.match(/(?:^|;\s*)kmb_session=([a-f0-9]{64})(?:;|$)/);
+  const token = match ? match[1] : null;
+  const rateLimit = getRateLimitStatus();
+  res.json({
+    authenticated: token ? validateSession(token) : false,
+    authEnabled: isAuthEnabled(),
+    locked: rateLimit.locked,
+    consumed: rateLimit.consumed,
+    retryAfter: rateLimit.retryAfter
+  });
+});
+
+// Authentication gate — all routes below require valid session
+app.use(authMiddleware);
+
 app.use(express.static(join(__dirname, 'public')));
 
 // Mount API routes
@@ -353,8 +419,16 @@ wss = new WebSocketServer({ server: httpServer });
 
 wss.on('connection', (ws, req) => {
   const clientIP = req.socket.remoteAddress || 'unknown';
+
+  // Validate WebSocket authentication
+  if (!validateWSAuth(req)) {
+    console.log(`[WebSocket] Unauthorized connection from ${clientIP}`);
+    ws.close(4401, 'Unauthorized');
+    return;
+  }
+
   console.log(`[WebSocket] Client connected from ${clientIP}`);
-  
+
   // Send cascade list on connect
   const cascadeList = Array.from(cascades.values()).map(c => ({
     id: c.id,
@@ -362,9 +436,9 @@ wss.on('connection', (ws, req) => {
     window: c.metadata?.windowTitle || 'Unknown',
     active: c.metadata?.isActive || false
   }));
-  
+
   ws.send(JSON.stringify({ type: 'cascade_list', cascades: cascadeList }));
-  
+
   ws.on('close', () => console.log(`[WebSocket] Client disconnected from ${clientIP}`));
   ws.on('error', (err) => console.error(`[WebSocket] Error from ${clientIP}:`, err.message));
 });
@@ -377,9 +451,15 @@ httpServer.listen(PORT, '0.0.0.0', () => {
   console.log(`Local:   http://localhost:${PORT}`);
   console.log(`Network: http://${localIP}:${PORT}`);
   console.log('');
-  console.log('Open the Network URL on your phone to monitor Kiro.');
+  if (isAuthEnabled()) {
+    console.log(`\x1b[33m\x1b[1m🔑 Access Code: ${getOTP()}\x1b[0m`);
+    console.log('');
+    console.log('Enter this code on your device to connect.');
+  } else {
+    console.log('Auth disabled (--no-auth). Open the Network URL on your phone.');
+  }
   console.log('');
-  
+
   // Start discovery and polling
   discoverTargets();
   pollingState.discoveryInterval = setInterval(discoverTargets, pollingState.discoveryIntervalMs);

package/src/utils/constants.js

@@ -103,6 +103,12 @@ export const SNAPSHOT_INTERVAL_ACTIVE = 200;     // 200ms when active (very fast
 export const SNAPSHOT_INTERVAL_IDLE = 800;       // 800ms when idle
 export const SNAPSHOT_IDLE_THRESHOLD = 3000;     // 3 seconds before considered idle
 
+/**
+ * OTP authentication settings
+ */
+export const OTP_MAX_ATTEMPTS = 5;       // Max failed attempts before lockout
+export const OTP_LOCKOUT_MS = 60000;      // 60 second lockout after max attempts
+
 /**
  * Maximum depth for recursive file search
  * @type {number}