feat: add recovery code functionality and device management

src/handlers/accounts.ts

@@ -5,6 +5,7 @@ import { jsonResponse, errorResponse } from '../utils/response';
 import { generateUUID } from '../utils/uuid';
 import { LIMITS } from '../config/limits';
 import { isTotpEnabled, verifyTotpToken } from '../utils/totp';
+import { createRecoveryCode, recoveryCodeEquals } from '../utils/recovery-code';
 
 function looksLikeEncString(value: string): boolean {
   if (!value) return false;
@@ -20,6 +21,10 @@ function normalizeTotpSecret(input: string): string {
   return input.toUpperCase().replace(/[\s-]/g, '').replace(/=+$/g, '');
 }
 
+function normalizeRecoveryCodeInput(input: string): string {
+  return String(input || '').toUpperCase().replace(/[^A-Z2-7]/g, '');
+}
+
 function jwtSecretUnsafeReason(env: Env): 'missing' | 'default' | 'too_short' | null {
   const secret = (env.JWT_SECRET || '').trim();
   if (!secret) return 'missing';
@@ -132,6 +137,7 @@ export async function handleRegister(request: Request, env: Env): Promise<Respon
     role: 'user',
     status: 'active',
     totpSecret: null,
+    totpRecoveryCode: null,
     createdAt: now,
     updatedAt: now,
   };
@@ -375,10 +381,13 @@ export async function handleSetTotpStatus(request: Request, env: Env, userId: st
       return errorResponse('Invalid TOTP token', 400);
     }
     user.totpSecret = normalizedSecret;
+    if (!user.totpRecoveryCode) {
+      user.totpRecoveryCode = createRecoveryCode();
+    }
     user.updatedAt = new Date().toISOString();
     await storage.saveUser(user);
     await storage.deleteRefreshTokensByUserId(user.id);
-    return jsonResponse({ enabled: true, object: 'twoFactor' });
+    return jsonResponse({ enabled: true, recoveryCode: user.totpRecoveryCode, object: 'twoFactor' });
   }
 
   if (body.enabled === false) {
@@ -398,6 +407,96 @@ export async function handleSetTotpStatus(request: Request, env: Env, userId: st
   return errorResponse('enabled must be true or false', 400);
 }
 
+// POST /api/accounts/totp/recovery-code
+export async function handleGetTotpRecoveryCode(request: Request, env: Env, userId: string): Promise<Response> {
+  const storage = new StorageService(env.DB);
+  const auth = new AuthService(env);
+  const user = await storage.getUserById(userId);
+  if (!user) return errorResponse('User not found', 404);
+
+  let body: Record<string, string | undefined>;
+  try {
+    const contentType = request.headers.get('content-type') || '';
+    if (contentType.includes('application/x-www-form-urlencoded')) {
+      const formData = await request.formData();
+      body = Object.fromEntries(formData.entries()) as Record<string, string>;
+    } else {
+      body = await request.json();
+    }
+  } catch {
+    return errorResponse('Invalid JSON', 400);
+  }
+
+  const currentHash = String(body.masterPasswordHash || body.master_password_hash || body.password || '').trim();
+  if (!currentHash) return errorResponse('masterPasswordHash is required', 400);
+  const valid = await auth.verifyPassword(currentHash, user.masterPasswordHash);
+  if (!valid) return errorResponse('Invalid password', 400);
+
+  if (!user.totpRecoveryCode) {
+    user.totpRecoveryCode = createRecoveryCode();
+    user.updatedAt = new Date().toISOString();
+    await storage.saveUser(user);
+  }
+
+  return jsonResponse({
+    code: user.totpRecoveryCode,
+    object: 'twoFactorRecover',
+  });
+}
+
+// POST /identity/accounts/recover-2fa
+// Disable TOTP by recovery code + password, then rotate recovery code.
+export async function handleRecoverTwoFactor(request: Request, env: Env): Promise<Response> {
+  const storage = new StorageService(env.DB);
+  const auth = new AuthService(env);
+
+  let body: Record<string, string | undefined>;
+  try {
+    const contentType = request.headers.get('content-type') || '';
+    if (contentType.includes('application/x-www-form-urlencoded')) {
+      const formData = await request.formData();
+      body = Object.fromEntries(formData.entries()) as Record<string, string>;
+    } else {
+      body = await request.json();
+    }
+  } catch {
+    return errorResponse('Invalid JSON', 400);
+  }
+
+  const email = String(body.email || body.username || '').trim().toLowerCase();
+  const masterPasswordHash = String(body.masterPasswordHash || body.password || '').trim();
+  const recoveryCode = normalizeRecoveryCodeInput(String(body.recoveryCode || body.twoFactorToken || body.recovery_code || ''));
+
+  if (!email || !masterPasswordHash || !recoveryCode) {
+    return errorResponse('Email, masterPasswordHash and recoveryCode are required', 400);
+  }
+
+  const user = await storage.getUser(email);
+  if (!user) return errorResponse('Invalid credentials', 400);
+  if (user.status !== 'active') return errorResponse('Account is disabled', 403);
+
+  const validPassword = await auth.verifyPassword(masterPasswordHash, user.masterPasswordHash);
+  if (!validPassword) return errorResponse('Invalid credentials', 400);
+
+  if (!recoveryCodeEquals(recoveryCode, user.totpRecoveryCode)) {
+    return errorResponse('Recovery code is incorrect. Try again.', 400);
+  }
+
+  user.totpSecret = null;
+  user.totpRecoveryCode = createRecoveryCode();
+  user.securityStamp = generateUUID();
+  user.updatedAt = new Date().toISOString();
+  await storage.saveUser(user);
+  await storage.deleteRefreshTokensByUserId(user.id);
+
+  return jsonResponse({
+    success: true,
+    twoFactorEnabled: false,
+    newRecoveryCode: user.totpRecoveryCode,
+    object: 'twoFactorRecovery',
+  });
+}
+
 // GET /api/accounts/revision-date
 export async function handleGetRevisionDate(request: Request, env: Env, userId: string): Promise<Response> {
   void request;

src/handlers/devices.ts

@@ -1,6 +1,6 @@
 import { Env } from '../types';
 import { StorageService } from '../services/storage';
-import { jsonResponse } from '../utils/response';
+import { errorResponse, jsonResponse } from '../utils/response';
 import { readKnownDeviceProbe } from '../utils/device';
 
 // GET /api/devices/knowndevice
@@ -40,6 +40,103 @@ export async function handleGetDevices(request: Request, env: Env, userId: strin
   });
 }
 
+// GET /api/devices/authorized
+// Returns known devices together with active 2FA remember-token expiry.
+export async function handleGetAuthorizedDevices(request: Request, env: Env, userId: string): Promise<Response> {
+  void request;
+  const storage = new StorageService(env.DB);
+  const [devices, trusted] = await Promise.all([
+    storage.getDevicesByUserId(userId),
+    storage.getTrustedDeviceTokenSummariesByUserId(userId),
+  ]);
+
+  const trustedByIdentifier = new Map<string, { expiresAt: number; tokenCount: number }>();
+  for (const row of trusted) {
+    trustedByIdentifier.set(row.deviceIdentifier, { expiresAt: row.expiresAt, tokenCount: row.tokenCount });
+  }
+
+  const knownIdentifiers = new Set<string>();
+  const data = devices.map(device => {
+    knownIdentifiers.add(device.deviceIdentifier);
+    const trustedInfo = trustedByIdentifier.get(device.deviceIdentifier);
+    return {
+      id: device.deviceIdentifier,
+      name: device.name,
+      identifier: device.deviceIdentifier,
+      type: device.type,
+      creationDate: device.createdAt,
+      revisionDate: device.updatedAt,
+      trusted: !!trustedInfo,
+      trustedTokenCount: trustedInfo?.tokenCount || 0,
+      trustedUntil: trustedInfo?.expiresAt ? new Date(trustedInfo.expiresAt).toISOString() : null,
+      object: 'device',
+    };
+  });
+
+  for (const row of trusted) {
+    if (knownIdentifiers.has(row.deviceIdentifier)) continue;
+    data.push({
+      id: row.deviceIdentifier,
+      name: 'Unknown device',
+      identifier: row.deviceIdentifier,
+      type: 14,
+      creationDate: '',
+      revisionDate: '',
+      trusted: true,
+      trustedTokenCount: row.tokenCount,
+      trustedUntil: row.expiresAt ? new Date(row.expiresAt).toISOString() : null,
+      object: 'device',
+    });
+  }
+
+  return jsonResponse({
+    data,
+    object: 'list',
+    continuationToken: null,
+  });
+}
+
+// DELETE /api/devices/authorized
+export async function handleRevokeAllTrustedDevices(request: Request, env: Env, userId: string): Promise<Response> {
+  void request;
+  const storage = new StorageService(env.DB);
+  const removed = await storage.deleteTrustedTwoFactorTokensByUserId(userId);
+  return jsonResponse({ success: true, removed });
+}
+
+// DELETE /api/devices/authorized/:deviceIdentifier
+export async function handleRevokeTrustedDevice(
+  request: Request,
+  env: Env,
+  userId: string,
+  deviceIdentifier: string
+): Promise<Response> {
+  void request;
+  const normalized = String(deviceIdentifier || '').trim();
+  if (!normalized) return errorResponse('Invalid device identifier', 400);
+
+  const storage = new StorageService(env.DB);
+  const removed = await storage.deleteTrustedTwoFactorTokensByDevice(userId, normalized);
+  return jsonResponse({ success: true, removed });
+}
+
+// DELETE /api/devices/:deviceIdentifier
+export async function handleDeleteDevice(
+  request: Request,
+  env: Env,
+  userId: string,
+  deviceIdentifier: string
+): Promise<Response> {
+  void request;
+  const normalized = String(deviceIdentifier || '').trim();
+  if (!normalized) return errorResponse('Invalid device identifier', 400);
+
+  const storage = new StorageService(env.DB);
+  await storage.deleteTrustedTwoFactorTokensByDevice(userId, normalized);
+  const deleted = await storage.deleteDevice(userId, normalized);
+  return jsonResponse({ success: deleted });
+}
+
 // PUT /api/devices/identifier/{deviceIdentifier}/token
 // Bitwarden mobile reports push token updates to this endpoint.
 // NodeWarden does not implement push notifications, so accept and no-op.

src/handlers/identity.ts

@@ -7,11 +7,13 @@ import { LIMITS } from '../config/limits';
 import { isTotpEnabled, verifyTotpToken } from '../utils/totp';
 import { createRefreshToken } from '../utils/jwt';
 import { readAuthRequestDeviceInfo } from '../utils/device';
+import { createRecoveryCode, recoveryCodeEquals } from '../utils/recovery-code';
 import { issueSendAccessToken } from './sends';
 
 const TWO_FACTOR_REMEMBER_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const TWO_FACTOR_PROVIDER_AUTHENTICATOR = 0;
 const TWO_FACTOR_PROVIDER_REMEMBER = 5;
+const TWO_FACTOR_PROVIDER_RECOVERY_CODE = 8;
 
 function resolveTotpSecret(userSecret: string | null, envSecret: string | undefined): string | null {
   if (userSecret && isTotpEnabled(userSecret)) {
@@ -23,16 +25,20 @@ function resolveTotpSecret(userSecret: string | null, envSecret: string | undefi
   return null;
 }
 
-function twoFactorRequiredResponse(message: string = 'Two factor required.'): Response {
+function twoFactorRequiredResponse(message: string = 'Two factor required.', includeRecoveryCode: boolean = false): Response {
+  const providers = includeRecoveryCode
+    ? [String(TWO_FACTOR_PROVIDER_AUTHENTICATOR), String(TWO_FACTOR_PROVIDER_RECOVERY_CODE)]
+    : [String(TWO_FACTOR_PROVIDER_AUTHENTICATOR)];
+  const providers2: Record<string, null> = {};
+  for (const provider of providers) providers2[provider] = null;
+
   // Bitwarden clients rely on these fields to trigger the 2FA UI flow.
   return jsonResponse(
     {
       error: 'invalid_grant',
       error_description: message,
-      TwoFactorProviders: [String(TWO_FACTOR_PROVIDER_AUTHENTICATOR)],
-      TwoFactorProviders2: {
-        [String(TWO_FACTOR_PROVIDER_AUTHENTICATOR)]: null,
-      },
+      TwoFactorProviders: providers,
+      TwoFactorProviders2: providers2,
       // Required by current Android parser (nullable value is acceptable).
       SsoEmail2faSessionToken: null,
       // Keep payload shape close to upstream implementations.
@@ -148,21 +154,22 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     let trustedTwoFactorTokenToReturn: string | undefined;
     const effectiveTotpSecret = resolveTotpSecret(user.totpSecret, env.TOTP_SECRET);
     if (effectiveTotpSecret) {
+      const canUseRecoveryCode = !!user.totpRecoveryCode;
       const normalizedTwoFactorProvider = String(twoFactorProvider ?? '').trim();
       const normalizedTwoFactorToken = String(twoFactorToken ?? '').trim();
-      const rememberRequested = ['1', 'true', 'True', 'TRUE', 'on', 'yes', 'Yes', 'YES'].includes(String(twoFactorRemember || '').trim());
+      let rememberRequested = ['1', 'true', 'True', 'TRUE', 'on', 'yes', 'Yes', 'YES'].includes(String(twoFactorRemember || '').trim());
       const hasProvider = normalizedTwoFactorProvider.length > 0;
       const hasToken = normalizedTwoFactorToken.length > 0;
 
       // Upstream-compatible behavior: if 2FA is required and either provider or token is missing,
       // respond with a 2FA challenge payload.
       if (!hasProvider || !hasToken) {
-        return twoFactorRequiredResponse();
+        return twoFactorRequiredResponse('Two factor required.', canUseRecoveryCode);
       }
 
       const parsedProvider = Number.parseInt(normalizedTwoFactorProvider, 10);
       if (!Number.isFinite(parsedProvider)) {
-        return twoFactorRequiredResponse();
+        return twoFactorRequiredResponse('Two factor required.', canUseRecoveryCode);
       }
 
       let passedByRememberToken = false;
@@ -177,13 +184,23 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
 
         // Remember token missing/invalid/expired should re-enter the 2FA challenge flow.
         if (!passedByRememberToken) {
-          return twoFactorRequiredResponse();
+          return twoFactorRequiredResponse('Two factor required.', canUseRecoveryCode);
         }
       } else if (parsedProvider === TWO_FACTOR_PROVIDER_AUTHENTICATOR) {
         const totpOk = await verifyTotpToken(effectiveTotpSecret, normalizedTwoFactorToken);
         if (!totpOk) {
           return recordFailedTwoFactorAndBuildResponse(rateLimit, loginIdentifier);
         }
+      } else if (parsedProvider === TWO_FACTOR_PROVIDER_RECOVERY_CODE) {
+        if (!recoveryCodeEquals(normalizedTwoFactorToken, user.totpRecoveryCode)) {
+          return recordFailedTwoFactorAndBuildResponse(rateLimit, loginIdentifier);
+        }
+        user.totpSecret = null;
+        user.totpRecoveryCode = createRecoveryCode();
+        user.updatedAt = new Date().toISOString();
+        await storage.saveUser(user);
+        await storage.deleteRefreshTokensByUserId(user.id);
+        rememberRequested = false;
       } else {
         // Unsupported provider for this server profile behaves as an invalid 2FA attempt.
         return recordFailedTwoFactorAndBuildResponse(rateLimit, loginIdentifier);