two-factor.service.ts

two-factor.service.tsapps/api/src/modules/org/two-factor.service.tsraw ← org5,696 B← Back to the app
1/**
2 * TASK-0133 — 2FA enrollment/verification for the org `require2FA` policy.
3 *
4 * The seed lives on `User.twoFactorSecret` as an AES-256-GCM base64
5 * envelope (same scheme/key as SSO + webhook secrets — `MASTER_ENCRYPTION_
6 * KEY` via `lib/crypto.ts`); the base32 string is revealed EXACTLY ONCE in
7 * the enrollment response (QR data `otpauth://totp/…`) — it is never read
8 * back. A missing `MASTER_ENCRYPTION_KEY` is a 500 (fail-closed).
9 *
10 * Verification at LOGIN (the enforcement point): a user in ANY org with
11 * `require2FA: true` (see `resolveUserPolicy`) must present a valid `totp`
12 * code — `login()` returns `202 { reason: "2fa_required", verificationId }`
13 * and `POST /auth/2fa/verify` completes the login (issues the session). The
14 * pending 2FA step is a short-lived (5 min, single-use) Redis token, so a
15 * wrong password never learns anything about a user's TOTP state.
16 */
17import { Inject, Injectable } from "@nestjs/common";
18import type { Request } from "express";
19import { aes256gcmDecrypt, aes256gcmEncrypt } from "../../lib/crypto.js";
20import { ApiError } from "../../common/errors.js";
21import { PrismaService } from "../../common/prisma.service.js";
22import { RedisService } from "../../common/redis.service.js";
23import { AuditService } from "../../common/audit.service.js";
24import { loadEnv } from "../../config/env.js";
25import { generateTotpSeed, totpVerify } from "./totp.js";
26 
27export const TWO_FA_PENDING_TTL_SEC = 300; // 5 min, single-use
28const pendingKey = (id: string) => `auth:2fa:pending:${id}`;
29 
30@Injectable()
31export class TwoFactorService {
32  constructor(
33    @Inject(PrismaService) private readonly prisma: PrismaService,
34    @Inject(RedisService) private readonly redis: RedisService,
35    @Inject(AuditService) private readonly audit: AuditService
36  ) {}
37 
38  private key(): string {
39    const k = loadEnv().MASTER_ENCRYPTION_KEY;
40    if (!k) {
41      throw new ApiError(
42        "INTERNAL_ERROR",
43        500,
44        "MASTER_ENCRYPTION_KEY is not configured — 2FA secrets cannot be stored."
45      );
46    }
47    return k;
48  }
49 
50  /** The decrypted TOTP seed (null when not enrolled). */
51  async getSeed(userId: string): Promise<Buffer | null> {
52    const row = await this.prisma.user.findUnique({
53      where: { id: userId },
54      select: { twoFactorSecret: true }
55    });
56    if (!row?.twoFactorSecret) return null;
57    try {
58      return Buffer.from(aes256gcmDecrypt(row.twoFactorSecret, this.key()), "base64");
59    } catch {
60      // A corrupt envelope must not 500 login — treat as enrolled-with-
61      // broken-seed: fail closed (require re-enrollment) but report 500
62      // honestly (the admin can reset it).
63      throw new ApiError("INTERNAL_ERROR", 500, "Stored 2FA secret is unreadable; reset 2FA enrollment.");
64    }
65  }
66 
67  /** Enrollment: returns the revealed-once secret + otpauth URI. */
68  async enroll(userId: string, req?: Request): Promise<{ secret: string; otpauthUri: string; confirmed: false }> {
69    const { seed, secret } = generateTotpSeed();
70    const envelope = aes256gcmEncrypt(seed.toString("base64"), this.key());
71    await this.prisma.user.update({ where: { id: userId }, data: { twoFactorSecret: envelope } });
72    const user = await this.prisma.user.findUnique({ where: { id: userId }, select: { email: true } });
73    const host = new URL(loadEnv().WEB_ORIGIN).host;
74    const otpauthUri = `otpauth://totp/${encodeURIComponent(host)}:${encodeURIComponent(
75      user?.email ?? userId
76    )}?secret=${secret}&issuer=${encodeURIComponent(host)}&algorithm=SHA1&digits=6&period=30`;
77    await this.audit.audit(req, req?.auth, {
78      action: "user.2fa_enrolled",
79      resourceType: "user",
80      resourceId: userId,
81      metadata: { method: "totp" }
82    });
83    return { secret, otpauthUri, confirmed: false };
84  }
85 
86  /** Disenroll (self or org-admin reset). */
87  async disable(userId: string, req?: Request): Promise<void> {
88    await this.prisma.user.update({
89      where: { id: userId },
90      data: { twoFactorSecret: null }
91    });
92    await this.audit.audit(req, req?.auth, {
93      action: "user.2fa_disabled",
94      resourceType: "user",
95      resourceId: userId,
96      metadata: {}
97    });
98  }
99 
100  async isEnrolled(userId: string): Promise<boolean> {
101    const row = await this.prisma.user.findUnique({
102      where: { id: userId },
103      select: { twoFactorSecret: true }
104    });
105    return row?.twoFactorSecret != null;
106  }
107 
108  /**
109   * Create a pending 2FA step for a user who passed the password (login
110   * returned 202). Returns the `verificationId` (random 32 bytes, b64url).
111   */
112  async createPending(userId: string): Promise<string> {
113    const id = Buffer.from(generateTotpSeed().seed).toString("base64url");
114    await this.redis.getRedis().set(pendingKey(id), userId, "EX", TWO_FA_PENDING_TTL_SEC);
115    return id;
116  }
117 
118  /**
119   * Verify + consume a pending step. Returns the userId on success.
120   * Consumes atomically (GETDEL) so the step is single-use.
121   */
122  async verifyPending(verificationId: string, code: string): Promise<string> {
123    const r = this.redis.getRedis();
124    // GETDEL is atomic (Redis ≥ 6.2; we run 7) — ioredis's typings predate it,
125    // hence the cast. A GET-then-DEL race would allow a replay window.
126    const stored = await (r as unknown as { getDel(k: string): Promise<string | null> }).getDel(
127      pendingKey(verificationId)
128    );
129    if (!stored) throw ApiError.unauthorized("2FA verification expired.", [{ reason: "2fa_pending_expired" }]);
130    const seed = await this.getSeed(stored);
131    if (!seed || !totpVerify(seed, code)) {
132      throw ApiError.unauthorized("Invalid 2FA code.", [{ reason: "2fa_code_invalid" }]);
133    }
134    return stored;
135  }
136}
137