feat(auth): add JWT session auth with page nonce

Author: lukeocodes

deploy/Caddyfile

@@ -1,11 +1,22 @@
 :8080 {
+	# HTML page served by backend (injects session nonce)
+	@htmlpage {
+		path /
+		path /index.html
+	}
+	handle @htmlpage {
+		reverse_proxy localhost:{$BACKEND_PORT:8081}
+	}
+
+	# API endpoints proxied to backend
 	handle /api/* {
 		reverse_proxy localhost:{$BACKEND_PORT:8081}
 	}
 
+	# Static assets served by Caddy
 	handle {
 		root * /app/frontend/dist
-		try_files {path} /index.html
 		file_server
 	}
 }
+

package.json

@@ -28,6 +28,7 @@
     "cors": "2.8.5",
     "dotenv": "17.2.3",
     "express": "5.2.1",
+    "jsonwebtoken": "9.0.2",
     "toml": "3.0.0",
     "ws": "8.18.0"
   },

sample.env

@@ -5,4 +5,5 @@ DEEPGRAM_API_KEY=%api_key%
 # Backend API server port
 PORT=8081
 # Server host
-HOST=0.0.0.0
+HOST=0.0.0.0
+# SESSION_SECRET=%session_secret%

server.js

@@ -5,19 +5,28 @@
  * Forwards all messages (JSON and binary) bidirectionally between client and Deepgram.
  *
  * Routes:
- *   WS  /api/voice-agent  - WebSocket proxy to Deepgram Agent API
- *   GET /api/metadata      - Project metadata from deepgram.toml
+ *   GET  /api/session       - Issue JWT session token
+ *   GET  /api/metadata      - Project metadata from deepgram.toml
+ *   WS   /api/voice-agent   - WebSocket proxy to Deepgram Agent API (auth required)
  */
 
 const { WebSocketServer, WebSocket } = require('ws');
 const express = require('express');
 const { createServer } = require('http');
 const cors = require('cors');
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
 require('dotenv').config();
 const path = require('path');
 const fs = require('fs');
 const toml = require('toml');
-// Native __dirname support in CommonJS
+
+// Validate required environment variables
+if (!process.env.DEEPGRAM_API_KEY) {
+  console.error('ERROR: DEEPGRAM_API_KEY environment variable is required');
+  console.error('Please copy sample.env to .env and add your API key');
+  process.exit(1);
+}
 
 // Configuration
 const CONFIG = {
@@ -27,24 +36,130 @@ const CONFIG = {
   host: process.env.HOST || '0.0.0.0',
 };
 
-// Validate required environment variables
-if (!CONFIG.deepgramApiKey) {
-  console.error('Error: DEEPGRAM_API_KEY not found in environment variables');
-  process.exit(1);
+// ============================================================================
+// SESSION AUTH - JWT tokens with page nonce for production security
+// ============================================================================
+
+const SESSION_SECRET =
+  process.env.SESSION_SECRET || crypto.randomBytes(32).toString('hex');
+const REQUIRE_NONCE = !!process.env.SESSION_SECRET;
+
+const sessionNonces = new Map();
+const NONCE_TTL_MS = 5 * 60 * 1000;
+const JWT_EXPIRY = '1h';
+
+function generateNonce() {
+  const nonce = crypto.randomBytes(16).toString('hex');
+  sessionNonces.set(nonce, Date.now() + NONCE_TTL_MS);
+  return nonce;
+}
+
+function consumeNonce(nonce) {
+  const expiry = sessionNonces.get(nonce);
+  if (!expiry) return false;
+  sessionNonces.delete(nonce);
+  return Date.now() < expiry;
+}
+
+setInterval(() => {
+  const now = Date.now();
+  for (const [nonce, expiry] of sessionNonces) {
+    if (now >= expiry) sessionNonces.delete(nonce);
+  }
+}, 60_000);
+
+let indexHtmlTemplate = null;
+try {
+  indexHtmlTemplate = fs.readFileSync(
+    path.join(__dirname, 'frontend', 'dist', 'index.html'),
+    'utf-8'
+  );
+} catch {
+  // No built frontend (dev mode)
+}
+
+/**
+ * Validates JWT from WebSocket subprotocol: access_token.<jwt>
+ * Returns the token string if valid, null if invalid.
+ */
+function validateWsToken(protocols) {
+  if (!protocols) return null;
+  const list = Array.isArray(protocols) ? protocols : protocols.split(',').map(s => s.trim());
+  const tokenProto = list.find(p => p.startsWith('access_token.'));
+  if (!tokenProto) return null;
+  const token = tokenProto.slice('access_token.'.length);
+  try {
+    jwt.verify(token, SESSION_SECRET);
+    return tokenProto;
+  } catch {
+    return null;
+  }
 }
 
-// Initialize Express
 const app = express();
-app.use(express.json());
+const server = createServer(app);
+const wss = new WebSocketServer({
+  noServer: true,
+  handleProtocols: (protocols) => {
+    // Accept the access_token.* subprotocol so the client sees it echoed back
+    for (const proto of protocols) {
+      if (proto.startsWith('access_token.')) return proto;
+    }
+    return false;
+  },
+});
+
+// Track all active WebSocket connections for graceful shutdown
+const activeConnections = new Set();
 
-// Enable CORS (wildcard is safe -- same-origin via Vite proxy / Caddy in production)
+// Enable CORS
 app.use(cors());
 
 // ============================================================================
-// API ROUTES
+// SESSION ROUTES - Auth endpoints (unprotected)
 // ============================================================================
 
-// Metadata endpoint - required for standardization compliance
+/**
+ * GET / — Serve index.html with injected session nonce (production only)
+ */
+app.get('/', (req, res) => {
+  if (!indexHtmlTemplate) {
+    return res.status(404).send('Frontend not built. Run make build first.');
+  }
+  const nonce = generateNonce();
+  const html = indexHtmlTemplate.replace(
+    '</head>',
+    `<meta name="session-nonce" content="${nonce}">\n</head>`
+  );
+  res.type('html').send(html);
+});
+
+/**
+ * GET /api/session — Issues a JWT. In production, requires valid nonce.
+ */
+app.get('/api/session', (req, res) => {
+  if (REQUIRE_NONCE) {
+    const nonce = req.headers['x-session-nonce'];
+    if (!nonce || !consumeNonce(nonce)) {
+      return res.status(403).json({
+        error: {
+          type: 'AuthenticationError',
+          code: 'INVALID_NONCE',
+          message: 'Valid session nonce required. Please refresh the page.',
+        },
+      });
+    }
+  }
+
+  const token = jwt.sign({ iat: Math.floor(Date.now() / 1000) }, SESSION_SECRET, {
+    expiresIn: JWT_EXPIRY,
+  });
+  res.json({ token });
+});
+
+/**
+ * Metadata endpoint - required for standardization compliance
+ */
 app.get('/api/metadata', (req, res) => {
   try {
     const tomlPath = path.join(__dirname, 'deepgram.toml');
@@ -68,40 +183,20 @@ app.get('/api/metadata', (req, res) => {
   }
 });
 
-// Create HTTP server
-const server = createServer(app);
-
-// Create WebSocket server for agent endpoint
-const wss = new WebSocketServer({
-  server,
-  path: '/api/voice-agent'
-});
-
-// Handle WebSocket connections - simple pass-through proxy
+/**
+ * WebSocket proxy handler
+ * Forwards all messages bidirectionally between client and Deepgram Agent API
+ */
 wss.on('connection', async (clientWs, request) => {
   console.log('Client connected to /api/voice-agent');
+  activeConnections.add(clientWs);
 
   try {
-    // Extract API key from Sec-WebSocket-Protocol header or use server's key
-    const protocol = request.headers['sec-websocket-protocol'];
-    const apiKey = protocol || CONFIG.deepgramApiKey;
-
-    if (!apiKey) {
-      clientWs.send(JSON.stringify({
-        type: 'Error',
-        description: 'Missing API key',
-        code: 'MISSING_API_KEY'
-      }));
-      clientWs.close();
-      return;
-    }
-
-    // Create raw WebSocket connection to Deepgram Agent API
-    // Send API key via Authorization header
+    // Always use server-side API key for Deepgram connection
     console.log('Initiating Deepgram connection...');
     const deepgramWs = new WebSocket(CONFIG.deepgramAgentUrl, {
       headers: {
-        'Authorization': `Token ${apiKey}`
+        'Authorization': `Token ${CONFIG.deepgramApiKey}`
       }
     });
 
@@ -152,6 +247,7 @@ wss.on('connection', async (clientWs, request) => {
       if (deepgramWs.readyState === WebSocket.OPEN) {
         deepgramWs.close();
       }
+      activeConnections.delete(clientWs);
     });
 
     // Handle client errors
@@ -175,44 +271,95 @@ wss.on('connection', async (clientWs, request) => {
   }
 });
 
-// Start the server
-server.listen(CONFIG.port, CONFIG.host, () => {
-  console.log('');
-  console.log('======================================================================');
-  console.log(`🚀 Backend API Server running at http://localhost:${CONFIG.port}`);
-  console.log(`📡 WS   /api/voice-agent`);
-  console.log(`📡 GET  /api/metadata`);
-  console.log('======================================================================');
-  console.log('');
-});
+/**
+ * Handle WebSocket upgrade requests for /api/voice-agent.
+ * Validates JWT from access_token.<jwt> subprotocol before upgrading.
+ */
+server.on('upgrade', (request, socket, head) => {
+  const pathname = new URL(request.url, 'http://localhost').pathname;
 
-// Graceful shutdown
-function shutdown() {
-  console.log('\nShutting down server...');
+  console.log(`WebSocket upgrade request for: ${pathname}`);
 
-  wss.clients.forEach((client) => {
-    try {
-      client.close();
-    } catch (err) {
-      console.error('Error closing client:', err);
+  if (pathname === '/api/voice-agent') {
+    // Validate JWT from subprotocol
+    const protocols = request.headers['sec-websocket-protocol'];
+    const validProto = validateWsToken(protocols);
+    if (!validProto) {
+      console.log('WebSocket auth failed: invalid or missing token');
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+      return;
     }
-  });
 
+    console.log('Backend handling /api/voice-agent WebSocket (authenticated)');
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      wss.emit('connection', ws, request);
+    });
+    return;
+  }
+
+  // Unknown WebSocket path - reject
+  console.log(`Unknown WebSocket path: ${pathname}`);
+  socket.destroy();
+});
+
+/**
+ * Graceful shutdown handler
+ */
+function gracefulShutdown(signal) {
+  console.log(`\n${signal} signal received: starting graceful shutdown...`);
+
+  // Stop accepting new connections
   wss.close(() => {
-    console.log('WebSocket server closed');
+    console.log('WebSocket server closed to new connections');
+  });
+
+  // Close all active WebSocket connections
+  console.log(`Closing ${activeConnections.size} active WebSocket connection(s)...`);
+  activeConnections.forEach((ws) => {
+    try {
+      ws.close(1001, 'Server shutting down');
+    } catch (error) {
+      console.error('Error closing WebSocket:', error);
+    }
   });
 
+  // Close the HTTP server
   server.close(() => {
     console.log('HTTP server closed');
+    console.log('Shutdown complete');
     process.exit(0);
   });
 
-  // Force exit after 5 seconds
+  // Force shutdown after 10 seconds if graceful shutdown fails
   setTimeout(() => {
-    console.error('Force closing');
+    console.error('Could not close connections in time, forcefully shutting down');
     process.exit(1);
-  }, 5000);
+  }, 10000);
 }
 
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);
+// Handle shutdown signals
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+// Handle uncaught errors
+process.on('uncaughtException', (error) => {
+  console.error('Uncaught Exception:', error);
+  gracefulShutdown('UNCAUGHT_EXCEPTION');
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  gracefulShutdown('UNHANDLED_REJECTION');
+});
+
+// Start server
+server.listen(CONFIG.port, CONFIG.host, () => {
+  console.log("\n" + "=".repeat(70));
+  console.log(`🚀 Backend API Server running at http://localhost:${CONFIG.port}`);
+  console.log("");
+  console.log(`📡 GET  /api/session${REQUIRE_NONCE ? ' (nonce required)' : ''}`);
+  console.log(`📡 WS   /api/voice-agent (auth required)`);
+  console.log(`📡 GET  /api/metadata`);
+  console.log("=".repeat(70) + "\n");
+});