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

@@ -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

@@ -9,15 +9,19 @@
  * - Contract-compliant API endpoint: POST /api/text-to-speech
  * - Accepts text in body and model as query parameter
  * - Returns binary audio data (application/octet-stream)
- * - Proxies to Vite dev server in development
- * - Serves static frontend in production
+ * - CORS enabled for frontend communication
+ * - JWT session auth with page nonce (production only)
+ * - Pure API server (frontend served separately)
  */
 
 require("dotenv").config();
 
 const { createClient } = require("@deepgram/sdk");
 const cors = require("cors");
+const crypto = require("crypto");
 const express = require("express");
+const fs = require("fs");
+const jwt = require("jsonwebtoken");
 const path = require("path");
 
 // ============================================================================
@@ -39,6 +43,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 - Load Deepgram API key from .env or config.json
 // ============================================================================
@@ -197,6 +300,50 @@ function formatErrorResponse(error, statusCode = 500, errorCode = null) {
   };
 }
 
+// ============================================================================
+// 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 - Define your API endpoints here
 // ============================================================================
@@ -214,8 +361,10 @@ function formatErrorResponse(error, statusCode = 500, errorCode = null) {
  * - Error (4XX): JSON error response matching contract format
  *
  * This endpoint implements the TTS contract specification.
+ *
+ * Protected by JWT session auth (requireSession middleware).
  */
-app.post("/api/text-to-speech", async (req, res) => {
+app.post("/api/text-to-speech", requireSession, async (req, res) => {
   try {
     // Get model from query parameter (contract specifies query param, not body)
     const model = req.query.model || DEFAULT_MODEL;
@@ -289,7 +438,6 @@ app.post("/api/text-to-speech", async (req, res) => {
  */
 app.get("/api/metadata", (req, res) => {
   try {
-    const fs = require("fs");
     const toml = require("toml");
     const tomlPath = path.join(__dirname, "deepgram.toml");
     const tomlContent = fs.readFileSync(tomlPath, "utf-8");
@@ -329,9 +477,9 @@ app.get("/api/metadata", (req, res) => {
 
 app.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(`📡 POST /api/text-to-speech`);
+  console.log(`🚀 Backend API running at http://localhost:${CONFIG.port}`);
+  console.log(`📡 GET  /api/session${REQUIRE_NONCE ? " (nonce required)" : ""}`);
+  console.log(`📡 POST /api/text-to-speech (auth required)`);
   console.log(`📡 GET  /api/metadata`);
   console.log("=".repeat(70) + "\n");
 });