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

@@ -34,6 +34,7 @@
     "cors": "2.8.5",
     "dotenv": "17.2.3",
     "express": "5.2.1",
+    "jsonwebtoken": "9.0.2",
     "toml": "3.0.0"
   },
   "devDependencies": {

sample.env

@@ -6,3 +6,6 @@ DEEPGRAM_API_KEY=%api_key%
 PORT=8081
 # Server host
 HOST=0.0.0.0
+
+# Session auth (optional - enables nonce validation when set)
+# SESSION_SECRET=%session_secret%

server.js

@@ -9,15 +9,18 @@
  * - Accepts text or URL in JSON body
  * - Supports multiple intelligence features: summarization, topics, sentiment, intents
  * - CORS-enabled for frontend communication
+ * - JWT session auth with page nonce (production only)
  */
 
 require("dotenv").config();
 
-const express = require("express");
 const { createClient } = require("@deepgram/sdk");
 const cors = require("cors");
-const path = require("path");
+const crypto = require("crypto");
+const express = require("express");
 const fs = require("fs");
+const jwt = require("jsonwebtoken");
+const path = require("path");
 const toml = require("toml");
 
 // ============================================================================
@@ -29,6 +32,105 @@ const CONFIG = {
   host: process.env.HOST || '0.0.0.0',
 };
 
+// ============================================================================
+// SESSION AUTH - JWT tokens with page nonce for production security
+// ============================================================================
+
+/**
+ * Session secret for signing JWTs. When set (production/Fly.io), nonce
+ * validation is enforced. When unset (local dev), tokens are issued freely.
+ */
+const SESSION_SECRET =
+  process.env.SESSION_SECRET || crypto.randomBytes(32).toString("hex");
+const REQUIRE_NONCE = !!process.env.SESSION_SECRET;
+
+/** In-memory nonce store: nonce -> expiry timestamp */
+const sessionNonces = new Map();
+
+/** Nonce expiry time (5 minutes) */
+const NONCE_TTL_MS = 5 * 60 * 1000;
+
+/** JWT expiry time (1 hour) */
+const JWT_EXPIRY = "1h";
+
+/**
+ * Generates a single-use nonce and stores it with an expiry
+ * @returns {string} The generated nonce
+ */
+function generateNonce() {
+  const nonce = crypto.randomBytes(16).toString("hex");
+  sessionNonces.set(nonce, Date.now() + NONCE_TTL_MS);
+  return nonce;
+}
+
+/**
+ * Validates and consumes a nonce (single-use)
+ * @param {string} nonce - The nonce to validate
+ * @returns {boolean} True if the nonce was valid and consumed
+ */
+function consumeNonce(nonce) {
+  const expiry = sessionNonces.get(nonce);
+  if (!expiry) return false;
+  sessionNonces.delete(nonce);
+  return Date.now() < expiry;
+}
+
+/** Periodically clean up expired nonces (every 60 seconds) */
+setInterval(() => {
+  const now = Date.now();
+  for (const [nonce, expiry] of sessionNonces) {
+    if (now >= expiry) sessionNonces.delete(nonce);
+  }
+}, 60_000);
+
+/**
+ * Reads frontend/dist/index.html and injects a session nonce meta tag.
+ * Returns null in dev mode (no built frontend).
+ */
+let indexHtmlTemplate = null;
+try {
+  indexHtmlTemplate = fs.readFileSync(
+    path.join(__dirname, "frontend", "dist", "index.html"),
+    "utf-8"
+  );
+} catch {
+  // No built frontend (dev mode) — index.html served by Vite
+}
+
+/**
+ * Express middleware that validates JWT from Authorization header.
+ * Returns 401 with JSON error if token is missing or invalid.
+ */
+function requireSession(req, res, next) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    return res.status(401).json({
+      error: {
+        type: "AuthenticationError",
+        code: "MISSING_TOKEN",
+        message: "Authorization header with Bearer token is required",
+      },
+    });
+  }
+
+  try {
+    const token = authHeader.slice(7);
+    jwt.verify(token, SESSION_SECRET);
+    next();
+  } catch (err) {
+    return res.status(401).json({
+      error: {
+        type: "AuthenticationError",
+        code: "INVALID_TOKEN",
+        message:
+          err.name === "TokenExpiredError"
+            ? "Session expired, please refresh the page"
+            : "Invalid session token",
+      },
+    });
+  }
+}
+
 // ============================================================================
 // API KEY LOADING
 // ============================================================================
@@ -61,6 +163,50 @@ app.use(express.json());
 // Enable CORS (wildcard is safe -- same-origin via Vite proxy / Caddy in production)
 app.use(cors());
 
+// ============================================================================
+// SESSION ROUTES - Auth endpoints (unprotected)
+// ============================================================================
+
+/**
+ * GET / — Serve index.html with injected session nonce (production only).
+ * In dev mode, Vite serves the frontend directly.
+ */
+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 (SESSION_SECRET set),
+ * requires a valid single-use nonce via X-Session-Nonce header.
+ */
+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 });
+});
+
 // ============================================================================
 // API ROUTES
 // ============================================================================
@@ -77,7 +223,7 @@ app.use(cors());
  * - Success (200): JSON with results object containing requested intelligence features
  * - Error (4XX): JSON error response matching contract format
  */
-app.post('/api/text-intelligence', async (req, res) => {
+app.post('/api/text-intelligence', requireSession, async (req, res) => {
   try {
     // Extract text or url from JSON body
     const { text, url } = req.body;
@@ -284,12 +430,10 @@ app.get('/api/metadata', (req, res) => {
 // ============================================================================
 
 app.listen(CONFIG.port, CONFIG.host, () => {
-  console.log('');
-  console.log('======================================================================');
-  console.log(`🚀 Backend API Server running at http://localhost:${CONFIG.port}`);
-  console.log('');
-  console.log(`📡 POST /api/text-intelligence`);
+  console.log("\n" + "=".repeat(70));
+  console.log(`🚀 Backend API running at http://localhost:${CONFIG.port}`);
+  console.log(`📡 GET  /api/session${REQUIRE_NONCE ? " (nonce required)" : ""}`);
+  console.log(`📡 POST /api/text-intelligence (auth required)`);
   console.log(`📡 GET  /api/metadata`);
-  console.log('======================================================================');
-  console.log('');
+  console.log("=".repeat(70) + "\n");
 });