fix: OpenAPI spec accuracy — hide internal endpoints, mark signup/verify deprecated

- Remove @openapi annotations from /v1/billing/webhook (Stripe-internal)
- Remove @openapi annotations from /v1/billing/success (browser redirect)
- Mark /v1/signup/verify as deprecated (returns 410)
- Add 3 TDD tests in openapi-spec.test.ts
- Update 2 existing tests in app-routes.test.ts
- 530 tests passing (was 527)

dist/routes/billing.js

@@ -15,8 +15,29 @@ function getStripe() {
     return _stripe;
 }
 const router = Router();
-// Track provisioned session IDs to prevent duplicate key creation
-const provisionedSessions = new Set();
+// Track provisioned session IDs with TTL to prevent duplicate key creation and memory leaks
+// Map<sessionId, timestamp> - entries older than 24h are periodically cleaned up
+const provisionedSessions = new Map();
+// TTL Configuration
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // Clean up every 1 hour
+// Cleanup old provisioned session entries
+function cleanupOldSessions() {
+    const now = Date.now();
+    const cutoff = now - SESSION_TTL_MS;
+    let cleanedCount = 0;
+    for (const [sessionId, timestamp] of provisionedSessions.entries()) {
+        if (timestamp < cutoff) {
+            provisionedSessions.delete(sessionId);
+            cleanedCount++;
+        }
+    }
+    if (cleanedCount > 0) {
+        logger.info({ cleanedCount, remainingCount: provisionedSessions.size }, "Cleaned up expired provisioned sessions");
+    }
+}
+// Start periodic cleanup
+setInterval(cleanupOldSessions, CLEANUP_INTERVAL_MS);
 const DOCFAST_PRODUCT_ID = "prod_TygeG8tQPtEAdE";
 // Returns true if the given Stripe subscription contains a DocFast product.
 // Used to filter webhook events — this Stripe account is shared with other projects.
@@ -101,43 +122,15 @@ router.post("/checkout", checkoutLimiter, async (req, res) => {
         res.status(500).json({ error: "Failed to create checkout session" });
     }
 });
-/**
- * @openapi
- * /v1/billing/success:
- *   get:
- *     tags: [Billing]
- *     summary: Checkout success page
- *     description: |
- *       Provisions a Pro API key after successful Stripe checkout and displays it in an HTML page.
- *       Called by Stripe redirect after payment completion.
- *     parameters:
- *       - in: query
- *         name: session_id
- *         required: true
- *         schema:
- *           type: string
- *         description: Stripe Checkout session ID
- *     responses:
- *       200:
- *         description: HTML page displaying the new API key
- *         content:
- *           text/html:
- *             schema:
- *               type: string
- *       400:
- *         description: Missing session_id or no customer found
- *       409:
- *         description: Checkout session already used
- *       500:
- *         description: Failed to retrieve session
- */
-// Success page — provision Pro API key after checkout
+// Success page — provision Pro API key after checkout (browser redirect, not a public API)
 router.get("/success", async (req, res) => {
     const sessionId = req.query.session_id;
     if (!sessionId) {
         res.status(400).json({ error: "Missing session_id" });
         return;
     }
+    // Clean up old sessions before checking duplicates
+    cleanupOldSessions();
     // Prevent duplicate provisioning from same session
     if (provisionedSessions.has(sessionId)) {
         res.status(409).json({ error: "This checkout session has already been used to provision a key. If you lost your key, use the key recovery feature." });
@@ -151,10 +144,10 @@ router.get("/success", async (req, res) => {
             res.status(400).json({ error: "No customer found" });
             return;
         }
-        // Check DB for existing key (survives pod restarts, unlike provisionedSessions Set)
+        // Check DB for existing key (survives pod restarts, unlike provisionedSessions Map)
         const existingKey = await findKeyByCustomerId(customerId);
         if (existingKey) {
-            provisionedSessions.add(session.id);
+            provisionedSessions.set(session.id, Date.now());
             res.send(`<!DOCTYPE html>
 <html><head><title>DocFast Pro — Key Already Provisioned</title>
 <style>
@@ -173,7 +166,7 @@ a { color: #4f9; }
             return;
         }
         const keyInfo = await createProKey(email, customerId);
-        provisionedSessions.add(session.id);
+        provisionedSessions.set(session.id, Date.now());
         // Return a nice HTML page instead of raw JSON
         res.send(`<!DOCTYPE html>
 <html><head><title>Welcome to DocFast Pro!</title>
@@ -202,48 +195,7 @@ a { color: #4f9; }
         res.status(500).json({ error: "Failed to retrieve session" });
     }
 });
-/**
- * @openapi
- * /v1/billing/webhook:
- *   post:
- *     tags: [Billing]
- *     summary: Stripe webhook endpoint
- *     description: |
- *       Receives Stripe webhook events for subscription lifecycle management.
- *       Requires the raw request body and a valid Stripe-Signature header for verification.
- *       Handles checkout.session.completed, customer.subscription.updated,
- *       customer.subscription.deleted, and customer.updated events.
- *     parameters:
- *       - in: header
- *         name: Stripe-Signature
- *         required: true
- *         schema:
- *           type: string
- *         description: Stripe webhook signature for payload verification
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             description: Raw Stripe event payload
- *     responses:
- *       200:
- *         description: Webhook received
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 received:
- *                   type: boolean
- *                   example: true
- *       400:
- *         description: Missing Stripe-Signature header or invalid signature
- *       500:
- *         description: Webhook secret not configured
- */
-// Stripe webhook for subscription lifecycle events
+// Stripe webhook for subscription lifecycle events (internal, not in public API docs)
 router.post("/webhook", async (req, res) => {
     const sig = req.headers["stripe-signature"];
     const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
@@ -297,7 +249,7 @@ router.post("/webhook", async (req, res) => {
                 break;
             }
             const keyInfo = await createProKey(email, customerId);
-            provisionedSessions.add(session.id);
+            provisionedSessions.set(session.id, Date.now());
             logger.info({ email, customerId }, "checkout.session.completed: provisioned pro key");
             break;
         }

dist/routes/convert.js

@@ -5,6 +5,7 @@ import dns from "node:dns/promises";
 import logger from "../services/logger.js";
 import { isPrivateIP } from "../utils/network.js";
 import { sanitizeFilename } from "../utils/sanitize.js";
+import { validatePdfOptions } from "../utils/pdf-options.js";
 export const convertRouter = Router();
 /**
  * @openapi
@@ -69,6 +70,12 @@ convertRouter.post("/html", async (req, res) => {
             res.status(400).json({ error: "Missing 'html' field" });
             return;
         }
+        // Validate PDF options
+        const validation = validatePdfOptions(body);
+        if (!validation.valid) {
+            res.status(400).json({ error: validation.error });
+            return;
+        }
         // Acquire concurrency slot
         if (req.acquirePdfSlot) {
             await req.acquirePdfSlot();
@@ -78,23 +85,13 @@ convertRouter.post("/html", async (req, res) => {
         const fullHtml = body.html.includes("<html")
             ? body.html
             : wrapHtml(body.html, body.css);
-        const pdf = await renderPdf(fullHtml, {
-            format: body.format,
-            landscape: body.landscape,
-            margin: body.margin,
-            printBackground: body.printBackground,
-            headerTemplate: body.headerTemplate,
-            footerTemplate: body.footerTemplate,
-            displayHeaderFooter: body.displayHeaderFooter,
-            scale: body.scale,
-            pageRanges: body.pageRanges,
-            preferCSSPageSize: body.preferCSSPageSize,
-            width: body.width,
-            height: body.height,
+        const { pdf, durationMs } = await renderPdf(fullHtml, {
+            ...validation.sanitized,
         });
         const filename = sanitizeFilename(body.filename || "document.pdf");
         res.setHeader("Content-Type", "application/pdf");
         res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
+        res.setHeader("X-Render-Time", String(durationMs));
         res.send(pdf);
     }
     catch (err) {
@@ -173,29 +170,25 @@ convertRouter.post("/markdown", async (req, res) => {
             res.status(400).json({ error: "Missing 'markdown' field" });
             return;
         }
+        // Validate PDF options
+        const validation = validatePdfOptions(body);
+        if (!validation.valid) {
+            res.status(400).json({ error: validation.error });
+            return;
+        }
         // Acquire concurrency slot
         if (req.acquirePdfSlot) {
             await req.acquirePdfSlot();
             slotAcquired = true;
         }
         const html = markdownToHtml(body.markdown, body.css);
-        const pdf = await renderPdf(html, {
-            format: body.format,
-            landscape: body.landscape,
-            margin: body.margin,
-            printBackground: body.printBackground,
-            headerTemplate: body.headerTemplate,
-            footerTemplate: body.footerTemplate,
-            displayHeaderFooter: body.displayHeaderFooter,
-            scale: body.scale,
-            pageRanges: body.pageRanges,
-            preferCSSPageSize: body.preferCSSPageSize,
-            width: body.width,
-            height: body.height,
+        const { pdf, durationMs } = await renderPdf(html, {
+            ...validation.sanitized,
         });
         const filename = sanitizeFilename(body.filename || "document.pdf");
         res.setHeader("Content-Type", "application/pdf");
         res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
+        res.setHeader("X-Render-Time", String(durationMs));
         res.send(pdf);
     }
     catch (err) {
@@ -306,30 +299,25 @@ convertRouter.post("/url", async (req, res) => {
             res.status(400).json({ error: "DNS lookup failed for URL hostname" });
             return;
         }
+        // Validate PDF options
+        const validation = validatePdfOptions(body);
+        if (!validation.valid) {
+            res.status(400).json({ error: validation.error });
+            return;
+        }
         // Acquire concurrency slot
         if (req.acquirePdfSlot) {
             await req.acquirePdfSlot();
             slotAcquired = true;
         }
-        const pdf = await renderUrlPdf(body.url, {
-            format: body.format,
-            landscape: body.landscape,
-            margin: body.margin,
-            printBackground: body.printBackground,
-            headerTemplate: body.headerTemplate,
-            footerTemplate: body.footerTemplate,
-            displayHeaderFooter: body.displayHeaderFooter,
-            scale: body.scale,
-            pageRanges: body.pageRanges,
-            preferCSSPageSize: body.preferCSSPageSize,
-            width: body.width,
-            height: body.height,
-            waitUntil: body.waitUntil,
+        const { pdf, durationMs } = await renderUrlPdf(body.url, {
+            ...validation.sanitized,
             hostResolverRules: `MAP ${parsed.hostname} ${resolvedAddress}`,
         });
         const filename = sanitizeFilename(body.filename || "page.pdf");
         res.setHeader("Content-Type", "application/pdf");
         res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
+        res.setHeader("X-Render-Time", String(durationMs));
         res.send(pdf);
     }
     catch (err) {

dist/routes/email-change.js

@@ -2,70 +2,162 @@ import { Router } from "express";
 import rateLimit from "express-rate-limit";
 import { createPendingVerification, verifyCode } from "../services/verification.js";
 import { sendVerificationEmail } from "../services/email.js";
-import { getAllKeys, updateKeyEmail } from "../services/keys.js";
+import { queryWithRetry } from "../services/db.js";
 import logger from "../services/logger.js";
 const router = Router();
-const changeLimiter = rateLimit({
+const emailChangeLimiter = rateLimit({
     windowMs: 60 * 60 * 1000,
     max: 3,
-    message: { error: "Too many attempts. Please try again in 1 hour." },
+    message: { error: "Too many email change attempts. Please try again in 1 hour." },
     standardHeaders: true,
     legacyHeaders: false,
+    keyGenerator: (req) => req.body?.apiKey || req.ip || "unknown",
 });
-router.post("/", changeLimiter, async (req, res) => {
-    const apiKey = req.headers.authorization?.replace(/^Bearer\s+/i, "") || req.body?.apiKey;
-    const newEmail = req.body?.newEmail;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+async function validateApiKey(apiKey) {
+    const result = await queryWithRetry(`SELECT key, email, tier FROM api_keys WHERE key = $1`, [apiKey]);
+    return result.rows[0] || null;
+}
+/**
+ * @openapi
+ * /v1/email-change:
+ *   post:
+ *     tags: [Account]
+ *     summary: Request email change
+ *     description: |
+ *       Sends a 6-digit verification code to the new email address.
+ *       Rate limited to 3 requests per hour per API key.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [apiKey, newEmail]
+ *             properties:
+ *               apiKey:
+ *                 type: string
+ *               newEmail:
+ *                 type: string
+ *                 format: email
+ *     responses:
+ *       200:
+ *         description: Verification code sent
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: verification_sent
+ *                 message:
+ *                   type: string
+ *       400:
+ *         description: Missing or invalid fields
+ *       403:
+ *         description: Invalid API key
+ *       409:
+ *         description: Email already taken
+ *       429:
+ *         description: Too many attempts
+ */
+router.post("/", emailChangeLimiter, async (req, res) => {
+    const { apiKey, newEmail } = req.body || {};
     if (!apiKey || typeof apiKey !== "string") {
-        res.status(400).json({ error: "API key is required (Authorization header or body)." });
+        res.status(400).json({ error: "apiKey is required." });
         return;
     }
-    if (!newEmail || typeof newEmail !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(newEmail)) {
-        res.status(400).json({ error: "A valid new email address is required." });
+    if (!newEmail || typeof newEmail !== "string") {
+        res.status(400).json({ error: "newEmail is required." });
         return;
     }
     const cleanEmail = newEmail.trim().toLowerCase();
-    const keys = getAllKeys();
-    const userKey = keys.find((k) => k.key === apiKey);
-    if (!userKey) {
-        res.status(401).json({ error: "Invalid API key." });
+    if (!EMAIL_RE.test(cleanEmail)) {
+        res.status(400).json({ error: "Invalid email format." });
         return;
     }
-    const existing = keys.find((k) => k.email === cleanEmail);
-    if (existing) {
+    const keyRow = await validateApiKey(apiKey);
+    if (!keyRow) {
+        res.status(403).json({ error: "Invalid API key." });
+        return;
+    }
+    // Check if email is already taken by another key
+    const existing = await queryWithRetry(`SELECT key FROM api_keys WHERE email = $1 AND key != $2`, [cleanEmail, apiKey]);
+    if (existing.rows.length > 0) {
         res.status(409).json({ error: "This email is already associated with another account." });
         return;
     }
     const pending = await createPendingVerification(cleanEmail);
-    sendVerificationEmail(cleanEmail, pending.code).catch((err) => {
+    sendVerificationEmail(cleanEmail, pending.code).catch(err => {
         logger.error({ err, email: cleanEmail }, "Failed to send email change verification");
     });
-    res.json({ status: "verification_sent", message: "Verification code sent to your new email address." });
+    res.json({ status: "verification_sent", message: "A verification code has been sent to your new email address." });
 });
-router.post("/verify", changeLimiter, async (req, res) => {
-    const apiKey = req.headers.authorization?.replace(/^Bearer\s+/i, "") || req.body?.apiKey;
-    const { newEmail, code } = req.body || {};
+/**
+ * @openapi
+ * /v1/email-change/verify:
+ *   post:
+ *     tags: [Account]
+ *     summary: Verify email change code
+ *     description: Verifies the 6-digit code and updates the account email.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [apiKey, newEmail, code]
+ *             properties:
+ *               apiKey:
+ *                 type: string
+ *               newEmail:
+ *                 type: string
+ *                 format: email
+ *               code:
+ *                 type: string
+ *                 pattern: '^\d{6}$'
+ *     responses:
+ *       200:
+ *         description: Email updated
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: ok
+ *                 newEmail:
+ *                   type: string
+ *       400:
+ *         description: Missing fields or invalid code
+ *       403:
+ *         description: Invalid API key
+ *       410:
+ *         description: Code expired
+ *       429:
+ *         description: Too many failed attempts
+ */
+router.post("/verify", async (req, res) => {
+    const { apiKey, newEmail, code } = req.body || {};
     if (!apiKey || !newEmail || !code) {
-        res.status(400).json({ error: "API key, new email, and code are required." });
+        res.status(400).json({ error: "apiKey, newEmail, and code are required." });
         return;
     }
     const cleanEmail = newEmail.trim().toLowerCase();
     const cleanCode = String(code).trim();
-    const keys = getAllKeys();
-    const userKey = keys.find((k) => k.key === apiKey);
-    if (!userKey) {
-        res.status(401).json({ error: "Invalid API key." });
+    const keyRow = await validateApiKey(apiKey);
+    if (!keyRow) {
+        res.status(403).json({ error: "Invalid API key." });
         return;
     }
     const result = await verifyCode(cleanEmail, cleanCode);
     switch (result.status) {
         case "ok": {
-            const updated = await updateKeyEmail(apiKey, cleanEmail);
-            if (updated) {
-                res.json({ status: "updated", message: "Email address updated successfully.", newEmail: cleanEmail });
-            }
-            else {
-                res.status(500).json({ error: "Failed to update email." });
-            }
+            await queryWithRetry(`UPDATE api_keys SET email = $1 WHERE key = $2`, [cleanEmail, apiKey]);
+            logger.info({ apiKey: apiKey.slice(0, 10) + "...", newEmail: cleanEmail }, "Email changed");
+            res.json({ status: "ok", newEmail: cleanEmail });
             break;
         }
         case "expired":

dist/routes/recover.js

@@ -3,6 +3,7 @@ import rateLimit from "express-rate-limit";
 import { createPendingVerification, verifyCode } from "../services/verification.js";
 import { sendVerificationEmail } from "../services/email.js";
 import { getAllKeys } from "../services/keys.js";
+import { queryWithRetry } from "../services/db.js";
 import logger from "../services/logger.js";
 const router = Router();
 const recoverLimiter = rateLimit({
@@ -129,7 +130,22 @@ router.post("/verify", recoverLimiter, async (req, res) => {
     switch (result.status) {
         case "ok": {
             const keys = getAllKeys();
-            const userKey = keys.find(k => k.email === cleanEmail);
+            let userKey = keys.find(k => k.email === cleanEmail);
+            // DB fallback: cache may be stale in multi-replica setups
+            if (!userKey) {
+                logger.info({ email: cleanEmail }, "recover verify: cache miss, falling back to DB");
+                const dbResult = await queryWithRetry("SELECT key, tier, email, created_at, stripe_customer_id FROM api_keys WHERE email = $1 LIMIT 1", [cleanEmail]);
+                if (dbResult.rows.length > 0) {
+                    const row = dbResult.rows[0];
+                    userKey = {
+                        key: row.key,
+                        tier: row.tier,
+                        email: row.email,
+                        createdAt: row.created_at instanceof Date ? row.created_at.toISOString() : row.created_at,
+                        stripeCustomerId: row.stripe_customer_id || undefined,
+                    };
+                }
+            }
             if (userKey) {
                 res.json({
                     status: "recovered",

dist/routes/signup.js

@@ -56,9 +56,10 @@ router.post("/free", rejectDuplicateEmail, signupLimiter, async (req, res) => {
  * /v1/signup/verify:
  *   post:
  *     tags: [Account]
- *     summary: Verify email and get API key
+ *     summary: Verify email and get API key (discontinued)
+ *     deprecated: true
  *     description: |
- *       Verifies the 6-digit code sent to the user's email and provisions a free API key.
+ *       **Discontinued.** Free accounts are no longer available. Try the demo at POST /v1/demo/html or upgrade to Pro at https://docfast.dev.
  *       Rate limited to 15 attempts per 15 minutes.
  *     requestBody:
  *       required: true

dist/routes/templates.js

@@ -3,6 +3,7 @@ import { renderPdf } from "../services/browser.js";
 import logger from "../services/logger.js";
 import { templates, renderTemplate } from "../services/templates.js";
 import { sanitizeFilename } from "../utils/sanitize.js";
+import { validatePdfOptions } from "../utils/pdf-options.js";
 export const templatesRouter = Router();
 /**
  * @openapi
@@ -146,11 +147,20 @@ templatesRouter.post("/:id/render", async (req, res) => {
             });
             return;
         }
+        // Validate PDF options from underscore-prefixed fields (BUG-103)
+        const pdfOpts = {};
+        if (data._format !== undefined)
+            pdfOpts.format = data._format;
+        if (data._margin !== undefined)
+            pdfOpts.margin = data._margin;
+        const validation = validatePdfOptions(pdfOpts);
+        if (!validation.valid) {
+            res.status(400).json({ error: validation.error });
+            return;
+        }
+        const sanitizedPdf = { format: "A4", ...validation.sanitized };
         const html = renderTemplate(id, data);
-        const pdf = await renderPdf(html, {
-            format: data._format || "A4",
-            margin: data._margin,
-        });
+        const { pdf, durationMs } = await renderPdf(html, sanitizedPdf);
         const filename = sanitizeFilename(data._filename || `${id}.pdf`);
         res.setHeader("Content-Type", "application/pdf");
         res.setHeader("Content-Disposition", `inline; filename="${filename}"`);