feat: key recovery via email verification (BUG-014)

- POST /v1/recover: request recovery code
- POST /v1/recover/verify: verify code, receive key via email
- Key sent via email only (not in API response) for security
- Rate limited to 3 attempts per hour
- Non-enumerable: same response whether email exists or not
- DKIM-signed emails via postfix/opendkim

src/routes/recover.ts

@@ -0,0 +1,90 @@
+import { Router, Request, Response } from "express";
+import rateLimit from "express-rate-limit";
+import { createPendingVerification, verifyCode } from "../services/verification.js";
+import { sendRecoveryEmail, sendVerificationEmail } from "../services/email.js";
+import { getAllKeys } from "../services/keys.js";
+
+const router = Router();
+
+const recoverLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000,
+  max: 3,
+  message: { error: "Too many recovery attempts. Please try again in 1 hour." },
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+// Step 1: Request recovery — sends verification code
+router.post("/", recoverLimiter, async (req: Request, res: Response) => {
+  const { email } = req.body || {};
+
+  if (!email || typeof email !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    res.status(400).json({ error: "A valid email address is required." });
+    return;
+  }
+
+  const cleanEmail = email.trim().toLowerCase();
+
+  // Check if this email has any keys
+  const keys = getAllKeys();
+  const userKey = keys.find(k => k.email === cleanEmail);
+  
+  // Always return success to prevent email enumeration
+  if (!userKey) {
+    res.json({ status: "recovery_sent", message: "If an account exists for this email, a verification code has been sent." });
+    return;
+  }
+
+  const pending = createPendingVerification(cleanEmail);
+
+  sendVerificationEmail(cleanEmail, pending.code).catch(err => {
+    console.error(`Failed to send recovery email to ${cleanEmail}:`, err);
+  });
+
+  res.json({ status: "recovery_sent", message: "If an account exists for this email, a verification code has been sent." });
+});
+
+// Step 2: Verify code — sends API key via email (NOT in response)
+router.post("/verify", recoverLimiter, async (req: Request, res: Response) => {
+  const { email, code } = req.body || {};
+
+  if (!email || !code) {
+    res.status(400).json({ error: "Email and code are required." });
+    return;
+  }
+
+  const cleanEmail = email.trim().toLowerCase();
+  const cleanCode = String(code).trim();
+
+  const result = verifyCode(cleanEmail, cleanCode);
+
+  switch (result.status) {
+    case "ok": {
+      const keys = getAllKeys();
+      const userKey = keys.find(k => k.email === cleanEmail);
+      
+      if (userKey) {
+        sendRecoveryEmail(cleanEmail, userKey.key).catch(err => {
+          console.error(`Failed to send recovery key to ${cleanEmail}:`, err);
+        });
+      }
+
+      res.json({
+        status: "recovered",
+        message: "Your API key has been sent to your email address.",
+      });
+      break;
+    }
+    case "expired":
+      res.status(410).json({ error: "Verification code has expired. Please request a new one." });
+      break;
+    case "max_attempts":
+      res.status(429).json({ error: "Too many failed attempts. Please request a new code." });
+      break;
+    case "invalid":
+      res.status(400).json({ error: "Invalid verification code." });
+      break;
+  }
+});
+
+export { router as recoverRouter };