fix: require OTP verification for recovery unlock

src/controllers/recoveryController.ts

@@ -1,18 +1,26 @@
 import { Response, NextFunction } from "express";
 import { z } from "zod";
 import { Request } from "express";
-import { unlockApp } from "../services/recovery/recoveryService";
+import {
+  unlockApp,
+  verifyRecoveryOtp,
+} from "../services/recovery/recoveryService";
 import { AppError } from "../middleware/errorHandler";
 
 const unlockAppSchema = z.object({
-  identifier: z.string().min(1, "identifier is required"), // email or E.164 phone
+  identifier: z.string().min(1, "identifier is required"),
   passcode: z.string().min(1, "passcode is required"),
 });
 
+const verifyRecoveryOtpSchema = z.object({
+  challenge_token: z.string().min(1, "challenge_token is required"),
+  code: z.string().min(1, "code is required"),
+});
+
 /**
  * POST /recovery/unlock
  * Body: { identifier: string (email or E.164 phone), passcode: string }
- * On success returns { api_key, user_id }. No auth header required (user is recovering access).
+ * Returns { challenge_token, channel }.
  */
 export async function postUnlock(
   req: Request,
@@ -26,8 +34,8 @@ export async function postUnlock(
       passcode: body.passcode,
     });
     res.status(200).json({
-      api_key: result.api_key,
-      user_id: result.user_id,
+      challenge_token: result.challenge_token,
+      channel: result.channel,
     });
   } catch (e) {
     if (e instanceof z.ZodError) {
@@ -41,6 +49,48 @@ export async function postUnlock(
         return next(new AppError(e.message, 401));
       if (e.message.includes("identifier"))
         return next(new AppError(e.message, 400));
+      if (e.message === "Recovery channel not configured")
+        return next(new AppError(e.message, 400));
+      if (e.message === "OTP delivery unavailable")
+        return next(new AppError(e.message, 503));
+    }
+    next(e);
+  }
+}
+
+/**
+ * POST /recovery/unlock/verify
+ * Body: { challenge_token: string, code: string }
+ * Returns { api_key, user_id }.
+ */
+export async function postUnlockVerify(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> {
+  try {
+    const body = verifyRecoveryOtpSchema.parse(req.body);
+    const result = await verifyRecoveryOtp({
+      challenge_token: body.challenge_token,
+      code: body.code,
+    });
+    res.status(200).json({
+      api_key: result.api_key,
+      user_id: result.user_id,
+    });
+  } catch (e) {
+    if (e instanceof z.ZodError) {
+      const msg = e.errors.map((x) => x.message).join("; ");
+      return next(new AppError(msg, 400));
+    }
+    if (e instanceof Error) {
+      if (
+        e.message === "Invalid or expired code" ||
+        e.message === "Invalid code"
+      )
+        return next(new AppError(e.message, 401));
+      if (e.message === "Invalid or expired challenge")
+        return next(new AppError(e.message, 401));
     }
     next(e);
   }

src/routes/recoveryRoutes.ts

@@ -1,11 +1,15 @@
 import { Router } from "express";
-import { postUnlock } from "../controllers/recoveryController";
+import {
+  postUnlock,
+  postUnlockVerify,
+} from "../controllers/recoveryController";
 import { standardRateLimiter } from "../middleware/rateLimiter";
 
 const router: ReturnType<typeof Router> = Router();
 
 router.use(standardRateLimiter);
 
 router.post("/unlock", postUnlock);
+router.post("/unlock/verify", postUnlockVerify);
 
 export default router;

src/services/recovery/recoveryService.ts

@@ -1,25 +1,62 @@
 /**
- * Recovery Tier 1: unlock app via email/phone + passcode.
- * On success, issues a new API key and returns it. Does not touch Stellar keys.
+ * Recovery Tier 1: unlock app via email/phone + passcode + OTP.
+ * Two-step flow: 1) verify passcode, send OTP; 2) verify OTP, issue API key.
  */
 import bcrypt from "bcryptjs";
 import { prisma } from "../../config/database";
 import { generateApiKey } from "../../middleware/auth";
 import { logger } from "../../config/logger";
+import { signChallengeToken, verifyChallengeToken } from "../../utils/jwt";
+import { getRabbitMQChannel, QUEUES } from "../../config/rabbitmq";
+
+const OTP_EXPIRY_MINUTES = 10;
 
 export interface UnlockAppParams {
   identifier: string; // email or E.164 phone
   passcode: string;
 }
 
 export interface UnlockAppResult {
+  challenge_token: string;
+  channel: "email" | "sms";
+}
+
+export interface VerifyRecoveryOtpParams {
+  challenge_token: string;
+  code: string;
+}
+
+export interface VerifyRecoveryOtpResult {
   api_key: string;
   user_id: string;
 }
 
+function generateOtpCode(): string {
+  return String(Math.floor(100000 + Math.random() * 900000));
+}
+
+async function publishOtpToQueue(payload: {
+  channel: string;
+  to: string;
+  code: string;
+}): Promise<void> {
+  try {
+    const ch = getRabbitMQChannel();
+    await ch.assertQueue(QUEUES.OTP_SEND, { durable: true });
+    ch.sendToQueue(QUEUES.OTP_SEND, Buffer.from(JSON.stringify(payload)), {
+      persistent: true,
+    });
+    logger.debug("Recovery OTP published to queue", {
+      channel: payload.channel,
+    });
+  } catch (e) {
+    logger.error("Failed to publish recovery OTP to RabbitMQ", e);
+    throw new Error("OTP delivery unavailable");
+  }
+}
+
 /**
- * Unlock app: verify identifier + passcode, then issue and return a new API key.
- * identifier is email or phone_e164 (E.164).
+ * Step 1: Verify identifier + passcode, generate OTP, return challenge token.
  */
 export async function unlockApp(
   params: UnlockAppParams,
@@ -40,7 +77,12 @@ export async function unlockApp(
 
   const user = await prisma.user.findFirst({
     where,
-    select: { id: true, passcodeHash: true },
+    select: {
+      id: true,
+      passcodeHash: true,
+      email: true,
+      phoneE164: true,
+    },
   });
   if (!user || !user.passcodeHash) {
     logger.warn("Recovery: user not found or no passcode set", {
@@ -55,10 +97,75 @@ export async function unlockApp(
     throw new Error("Invalid passcode");
   }
 
-  const apiKey = await generateApiKey(user.id, []);
-  logger.info("Recovery: app unlocked, new key issued", { userId: user.id });
+  const channel = isEmail ? "email" : "sms";
+  const to = isEmail ? user.email : user.phoneE164;
+  if (!to) {
+    throw new Error("Recovery channel not configured");
+  }
+
+  const code = generateOtpCode();
+  const codeHash = await bcrypt.hash(code, 10);
+  await prisma.otpChallenge.create({
+    data: {
+      userId: user.id,
+      codeHash,
+      channel,
+      expiresAt: new Date(Date.now() + OTP_EXPIRY_MINUTES * 60 * 1000),
+    },
+  });
+
+  await publishOtpToQueue({ channel, to, code });
+
+  const challenge_token = signChallengeToken(user.id);
+  logger.info("Recovery: passcode verified, OTP sent", {
+    userId: user.id,
+    channel,
+  });
+
+  return { challenge_token, channel };
+}
+
+/**
+ * Step 2: Verify challenge token + OTP code, issue API key.
+ */
+export async function verifyRecoveryOtp(
+  params: VerifyRecoveryOtpParams,
+): Promise<VerifyRecoveryOtpResult> {
+  const { challenge_token, code } = params;
+  const payload = verifyChallengeToken(challenge_token);
+
+  const now = new Date();
+  const challenge = await prisma.otpChallenge.findFirst({
+    where: {
+      userId: payload.userId,
+      expiresAt: { gt: now },
+      usedAt: null,
+    },
+    orderBy: { createdAt: "desc" },
+  });
+
+  if (!challenge) {
+    throw new Error("Invalid or expired code");
+  }
+
+  const match = await bcrypt.compare(code, challenge.codeHash);
+  if (!match) {
+    logger.warn("Recovery: invalid OTP", { userId: payload.userId });
+    throw new Error("Invalid code");
+  }
+
+  await prisma.otpChallenge.update({
+    where: { id: challenge.id },
+    data: { usedAt: now },
+  });
+
+  const apiKey = await generateApiKey(payload.userId, []);
+  logger.info("Recovery: OTP verified, new key issued", {
+    userId: payload.userId,
+  });
+
   return {
     api_key: apiKey,
-    user_id: user.id,
+    user_id: payload.userId,
   };
 }