create-entity-app-server 0.0.3

package/src/app/plugins/2fa/handlers/regenerate.ts

@@ -0,0 +1,99 @@
+/**
+ * POST /api/v1/account/2fa/recovery/regenerate
+ *
+ * 복구 코드 재생성: JWT 인증 + TOTP 코드 확인
+ *
+ * Go `HandleRegenerateRecovery` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, sendEmail, logger } from "@gateway/api";
+import type { TwoFactorConfig, RegenerateRecoveryBody } from "../types.ts";
+import {
+    getAccountSeqFromJwt,
+    getAccountBySeq,
+    updateAccount,
+    nowIsoString,
+    TEMPLATES_DIR,
+} from "./utils.ts";
+import { validateTOTP, generateRecoveryCodes } from "../totp-utils.ts";
+
+export function createRegenerateHandler(cfg: TwoFactorConfig) {
+    return async function handleRegenerate(
+        req: FastifyRequest<{ Body: RegenerateRecoveryBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq) {
+            reply.code(401).send(fail("Not authenticated"));
+            return;
+        }
+
+        const body = req.body ?? {};
+        const code = (body.code ?? "").trim();
+        if (!code) {
+            reply.code(400).send(fail("code (TOTP) is required"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(500).send(fail("Internal server error"));
+            return;
+        }
+
+        if (!account.totp_enabled) {
+            reply.code(400).send(fail("2FA is not enabled"));
+            return;
+        }
+
+        // TOTP 코드 검증
+        const secret = account.totp_secret ?? "";
+        const valid = validateTOTP(
+            secret,
+            code,
+            cfg.skew,
+            cfg.code_digits,
+            cfg.period_sec,
+        );
+        if (!valid) {
+            reply.code(401).send(fail("Invalid TOTP code"));
+            return;
+        }
+
+        // 새 복구 코드 생성
+        const { plainCodes, hashes } = generateRecoveryCodes(
+            cfg.recovery_code_count,
+        );
+
+        await updateAccount(accountSeq, {
+            totp_recovery_codes: JSON.stringify(hashes),
+        });
+
+        // 새 복구 코드 이메일 발송
+        sendEmail({
+            to: [account.email],
+            subject: "2단계 인증 복구 코드 재생성",
+            templateDir: TEMPLATES_DIR,
+            templateName: "auth/2fa_recovery_regenerated",
+            templateData: {
+                email: account.email,
+                recovery_codes: plainCodes.join("\n"),
+                recovery_count: String(plainCodes.length),
+                regenerated_time: nowIsoString(),
+            },
+        }).catch((err: unknown) =>
+            logger.warn(
+                { err },
+                "2FA regenerate: failed to send recovery codes email",
+            ),
+        );
+
+        reply.code(200).send(
+            ok({
+                recovery_codes: plainCodes,
+                message: "기존 복구 코드가 모두 폐기되고 새로 생성되었습니다.",
+            }),
+        );
+    };
+}

package/src/app/plugins/2fa/handlers/setup-verify.ts

@@ -0,0 +1,121 @@
+/**
+ * POST /api/v1/account/2fa/setup/verify
+ *
+ * 2FA 설정 확인: TOTP 코드 검증 → 2FA 활성화 + 복구 코드 생성
+ * JWT 또는 setup_token 인증
+ *
+ * Go `HandleSetupVerify` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, sendEmail, logger } from "@gateway/api";
+import type { TwoFactorConfig, SetupVerifyBody } from "../types.ts";
+import {
+    getAccountSeqFromJwt,
+    getAccountSeqFromTwoFactorToken,
+    getAccountBySeq,
+    updateAccount,
+    nowIsoString,
+    TEMPLATES_DIR,
+} from "./utils.ts";
+import { validateTOTP, generateRecoveryCodes } from "../totp-utils.ts";
+
+export function createSetupVerifyHandler(cfg: TwoFactorConfig) {
+    return async function handleSetupVerify(
+        req: FastifyRequest<{ Body: SetupVerifyBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const body = req.body ?? {};
+        const code = (body.code ?? "").trim();
+        if (!code) {
+            reply.code(400).send(fail("code is required"));
+            return;
+        }
+
+        // 인증: JWT 또는 setup_token
+        let accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq && body.setup_token) {
+            accountSeq = getAccountSeqFromTwoFactorToken(
+                body.setup_token,
+                "2fa_setup",
+            );
+        }
+        if (!accountSeq) {
+            reply.code(401).send(fail("Not authenticated"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(500).send(fail("Internal server error"));
+            return;
+        }
+
+        const secret = account.totp_secret ?? "";
+        if (!secret || secret === "<nil>") {
+            reply
+                .code(400)
+                .send(
+                    fail(
+                        "2FA setup not initiated. Call POST /api/v1/account/2fa/setup first.",
+                    ),
+                );
+            return;
+        }
+
+        // TOTP 코드 검증
+        const valid = validateTOTP(
+            secret,
+            code,
+            cfg.skew,
+            cfg.code_digits,
+            cfg.period_sec,
+        );
+        if (!valid) {
+            reply.code(401).send(fail("Invalid TOTP code"));
+            return;
+        }
+
+        // 복구 코드 생성
+        const { plainCodes, hashes } = generateRecoveryCodes(
+            cfg.recovery_code_count,
+        );
+        const enabledTime = nowIsoString();
+
+        // 2FA 활성화
+        await updateAccount(accountSeq, {
+            totp_enabled: true,
+            totp_enabled_time: enabledTime,
+            totp_recovery_codes: JSON.stringify(hashes),
+            totp_failed_attempts: 0,
+            totp_locked_until: null,
+        });
+
+        // 복구 코드 이메일 발송
+        sendEmail({
+            to: [account.email],
+            subject: "2단계 인증 복구 코드",
+            templateDir: TEMPLATES_DIR,
+            templateName: "auth/2fa_setup_complete",
+            templateData: {
+                email: account.email,
+                recovery_codes: plainCodes.join("\n"),
+                recovery_count: String(plainCodes.length),
+                enabled_time: enabledTime,
+            },
+        }).catch((err: unknown) =>
+            logger.warn(
+                { err },
+                "2FA setup: failed to send recovery codes email",
+            ),
+        );
+
+        reply.code(200).send(
+            ok({
+                recovery_codes: plainCodes,
+                message:
+                    "복구 코드를 안전한 곳에 저장하세요. 이 코드는 다시 표시되지 않습니다.",
+            }),
+        );
+    };
+}

package/src/app/plugins/2fa/handlers/setup.ts

@@ -0,0 +1,92 @@
+/**
+ * POST /api/v1/account/2fa/setup
+ *
+ * 2FA 설정 시작: 비밀 키 + QR코드 생성 → setup_token 발급
+ * JWT 인증 필요
+ *
+ * Go `HandleSetup` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { TwoFactorConfig } from "../types.ts";
+import {
+    getAccountSeqFromJwt,
+    getAccountBySeq,
+    updateAccount,
+    generateSetupToken,
+} from "./utils.ts";
+import {
+    generateSecret,
+    generateOTPAuthURL,
+    generateSetupQR,
+} from "../totp-utils.ts";
+
+export function createSetupHandler(cfg: TwoFactorConfig) {
+    return async function handleSetup(
+        req: FastifyRequest,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq) {
+            reply.code(401).send(fail("Not authenticated"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(500).send(fail("Internal server error"));
+            return;
+        }
+
+        if (account.totp_enabled) {
+            reply
+                .code(409)
+                .send(
+                    fail(
+                        "2FA is already enabled. Disable first to reconfigure.",
+                    ),
+                );
+            return;
+        }
+
+        // 비밀 키 생성
+        const secret = generateSecret();
+
+        // otpauth URL 생성
+        const otpauthURL = generateOTPAuthURL(
+            secret,
+            account.email,
+            cfg.issuer,
+            cfg.code_digits,
+            cfg.period_sec,
+        );
+
+        // QR코드 생성
+        let qrDataURI: string;
+        try {
+            qrDataURI = await generateSetupQR(otpauthURL, 256);
+        } catch {
+            reply.code(500).send(fail("Failed to generate QR code"));
+            return;
+        }
+
+        // 비밀 키를 account에 임시 저장 (totp_enabled=false 상태)
+        await updateAccount(accountSeq, { totp_secret: secret });
+
+        // setup_token 발급
+        const setupToken = generateSetupToken(
+            accountSeq,
+            cfg.setup_token_ttl_sec,
+        );
+
+        reply.code(200).send(
+            ok({
+                secret,
+                qr_code: qrDataURI,
+                otpauth_url: otpauthURL,
+                setup_token: setupToken,
+            }),
+        );
+    };
+}

package/src/app/plugins/2fa/handlers/status.ts

@@ -0,0 +1,47 @@
+/**
+ * GET /api/v1/account/2fa/status
+ *
+ * 현재 계정의 2FA 활성화 상태 조회
+ * JWT 인증 필요
+ *
+ * Go `HandleStatus` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { TwoFactorConfig } from "../types.ts";
+import {
+    getAccountSeqFromJwt,
+    getAccountBySeq,
+    parseRecoveryHashes,
+} from "./utils.ts";
+
+export function createStatusHandler(cfg: TwoFactorConfig) {
+    return async function handleStatus(
+        req: FastifyRequest,
+        reply: FastifyReply,
+    ): Promise<void> {
+        void cfg;
+        const accountSeq = getAccountSeqFromJwt(req);
+        if (!accountSeq) {
+            reply.code(401).send(fail("Not authenticated"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(500).send(fail("Internal server error"));
+            return;
+        }
+
+        const hashes = parseRecoveryHashes(account);
+
+        reply.code(200).send(
+            ok({
+                enabled: Boolean(account.totp_enabled),
+                enabled_time: account.totp_enabled_time ?? "",
+                remaining_recovery_codes: hashes.length,
+            }),
+        );
+    };
+}

package/src/app/plugins/2fa/handlers/utils.ts

@@ -0,0 +1,222 @@
+/**
+ * 2FA 공통 유틸리티
+ *
+ * - JWT 파싱/검증/발급 (two_factor_token, setup_token, token pair)
+ * - account 엔티티 조회
+ * - 잠금 상태 확인 / 실패 횟수 관리
+ * - 복구 코드 해시 파싱
+ */
+
+import type { FastifyRequest } from "fastify";
+import jwt from "jsonwebtoken";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { entityServer, logger } from "@gateway/api";
+import { env } from "@gateway/api";
+import type {
+    TwoFactorConfig,
+    AccountTotpFields,
+    TwoFactorTokenClaims,
+} from "../types.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = join(__dirname, "..", "templates");
+
+/* ──────────── account_seq 추출 ──────────── */
+
+/** req.user(프록시 미들웨어)에서 account_seq 추출 */
+export function getAccountSeqFromJwt(req: FastifyRequest): number | null {
+    const user = (req as unknown as Record<string, unknown>).user as
+        | Record<string, unknown>
+        | undefined;
+    if (!user) return null;
+    return Number(user.account_seq ?? user.seq ?? 0) || null;
+}
+
+/**
+ * two_factor_token / setup_token 검증 → account_seq 반환
+ * purpose가 일치하지 않으면 null
+ */
+export function getAccountSeqFromTwoFactorToken(
+    token: string,
+    expectedPurpose: "2fa_verify" | "2fa_setup",
+): number | null {
+    try {
+        const claims = jwt.verify(
+            token,
+            env.JWT_SECRET,
+        ) as TwoFactorTokenClaims;
+        if (claims.purpose !== expectedPurpose) return null;
+        const seq = Number(claims.sub);
+        return isFinite(seq) && seq > 0 ? seq : null;
+    } catch {
+        return null;
+    }
+}
+
+/** two_factor_token 발급 */
+export function generateTwoFactorToken(
+    accountSeq: number,
+    purpose: "2fa_verify" | "2fa_setup",
+    ttlSec: number,
+): string {
+    return jwt.sign({ purpose }, env.JWT_SECRET, {
+        subject: String(accountSeq),
+        expiresIn: ttlSec,
+    });
+}
+
+/** setup_token 발급 */
+export function generateSetupToken(accountSeq: number, ttlSec: number): string {
+    return generateTwoFactorToken(accountSeq, "2fa_setup", ttlSec);
+}
+
+/* ──────────── Access/Refresh 토큰 발급 ──────────── */
+
+/** JTI 생성 (refresh token용) */
+function generateJTI(): string {
+    return randomBytes(16).toString("hex");
+}
+
+export interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+
+/** Go GenerateTokenPair과 동일한 방식으로 JWT 토큰 쌍 발급 */
+export function issueTokenPair(
+    account: AccountTotpFields,
+    cfg: TwoFactorConfig,
+): TokenPair {
+    const now = Math.floor(Date.now() / 1000);
+
+    const accessPayload = {
+        email: account.email ?? "",
+        name: account.name ?? account.email ?? "",
+        rbac_role: account.rbac_role ?? "",
+        license_seq: account.license_seq ?? 0,
+        iss: cfg.jwt_issuer,
+        iat: now,
+        exp: now + cfg.jwt_access_ttl_sec,
+    };
+
+    const accessToken = jwt.sign(accessPayload, env.JWT_SECRET, {
+        subject: String(account.seq),
+        algorithm: "HS256",
+    });
+
+    const refreshPayload = {
+        jti: generateJTI(),
+        iss: cfg.jwt_issuer,
+        iat: now,
+        exp: now + cfg.jwt_refresh_ttl_sec,
+    };
+
+    const refreshToken = jwt.sign(refreshPayload, env.JWT_SECRET, {
+        subject: String(account.seq),
+        algorithm: "HS256",
+    });
+
+    return {
+        access_token: accessToken,
+        refresh_token: refreshToken,
+        expires_in: cfg.jwt_access_ttl_sec,
+    };
+}
+
+/* ──────────── account 엔티티 조회 ──────────── */
+
+export async function getAccountBySeq(
+    seq: number,
+): Promise<AccountTotpFields | null> {
+    try {
+        const res = await entityServer.get<AccountTotpFields>("account", seq);
+        return res?.data ?? null;
+    } catch (err) {
+        logger.error({ err, seq }, "2FA: getAccountBySeq failed");
+        return null;
+    }
+}
+
+/* ──────────── 잠금 처리 ──────────── */
+
+/** 잠금 상태 확인. 잠겨 있으면 에러 메시지 반환 */
+export function checkLockout(account: AccountTotpFields): string | null {
+    if (!account.totp_locked_until) return null;
+    const lockedUntil = new Date(account.totp_locked_until).getTime();
+    const remaining = Math.ceil((lockedUntil - Date.now()) / 1000);
+    if (remaining > 0) {
+        return `Too many failed attempts. Try again in ${remaining} seconds.`;
+    }
+    return null;
+}
+
+/** 실패 횟수 증가 + 임계치 초과 시 잠금 */
+export async function incrementFailedAttempts(
+    accountSeq: number,
+    account: AccountTotpFields,
+    cfg: TwoFactorConfig,
+): Promise<void> {
+    const failed = (Number(account.totp_failed_attempts) || 0) + 1;
+    const update: Record<string, unknown> = { totp_failed_attempts: failed };
+
+    if (failed >= cfg.max_verify_attempts) {
+        const lockUntil = new Date(Date.now() + cfg.verify_lockout_sec * 1000)
+            .toISOString()
+            .replace("T", " ")
+            .replace("Z", "")
+            .slice(0, 19);
+        update.totp_locked_until = lockUntil;
+        logger.warn(
+            { accountSeq, failed },
+            "2FA: account locked due to failed attempts",
+        );
+    }
+
+    await updateAccount(accountSeq, update);
+}
+
+/** 실패 횟수 리셋 */
+export async function resetFailedAttempts(accountSeq: number): Promise<void> {
+    await updateAccount(accountSeq, {
+        totp_failed_attempts: 0,
+        totp_locked_until: null,
+    });
+}
+
+/* ──────────── account 업데이트 ──────────── */
+
+export async function updateAccount(
+    seq: number,
+    data: Record<string, unknown>,
+): Promise<void> {
+    try {
+        await entityServer.submit("account", { seq, ...data });
+    } catch (err) {
+        logger.error({ err, seq }, "2FA: updateAccount failed");
+    }
+}
+
+/* ──────────── 복구 코드 해시 파싱 ──────────── */
+
+export function parseRecoveryHashes(account: AccountTotpFields): string[] {
+    const raw = account.totp_recovery_codes ?? "";
+    if (!raw || raw === "<nil>") return [];
+    try {
+        return JSON.parse(raw) as string[];
+    } catch {
+        return [];
+    }
+}
+
+/* ──────────── 공통 유틸 ──────────── */
+
+export function nowIsoString(): string {
+    return new Date()
+        .toISOString()
+        .replace("T", " ")
+        .replace("Z", "")
+        .slice(0, 19);
+}

package/src/app/plugins/2fa/handlers/verify.ts

@@ -0,0 +1,92 @@
+/**
+ * POST /api/v1/account/2fa/verify
+ *
+ * 로그인 2단계: two_factor_token + TOTP 코드 검증 → JWT 토큰 쌍 발급
+ * 인증 불필요 (two_factor_token 사용)
+ *
+ * Go `HandleVerify` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { TwoFactorConfig, TwoFactorVerifyBody } from "../types.ts";
+import {
+    getAccountSeqFromTwoFactorToken,
+    getAccountBySeq,
+    checkLockout,
+    incrementFailedAttempts,
+    resetFailedAttempts,
+    issueTokenPair,
+} from "./utils.ts";
+import { validateTOTP } from "../totp-utils.ts";
+
+export function createVerifyHandler(cfg: TwoFactorConfig) {
+    return async function handleVerify(
+        req: FastifyRequest<{ Body: TwoFactorVerifyBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const body = req.body ?? {};
+        const code = (body.code ?? "").trim();
+
+        if (!body.two_factor_token || !code) {
+            reply
+                .code(400)
+                .send(fail("two_factor_token and code are required"));
+            return;
+        }
+
+        const accountSeq = getAccountSeqFromTwoFactorToken(
+            body.two_factor_token,
+            "2fa_verify",
+        );
+        if (!accountSeq) {
+            reply.code(401).send(fail("Invalid or expired two-factor token"));
+            return;
+        }
+
+        const account = await getAccountBySeq(accountSeq);
+        if (!account) {
+            reply.code(500).send(fail("Internal server error"));
+            return;
+        }
+
+        // 잠금 상태 확인
+        const lockMsg = checkLockout(account);
+        if (lockMsg) {
+            reply.code(429).send(fail(lockMsg));
+            return;
+        }
+
+        const secret = account.totp_secret ?? "";
+        if (!secret || secret === "<nil>") {
+            reply
+                .code(400)
+                .send(fail("2FA is not configured for this account"));
+            return;
+        }
+
+        // TOTP 코드 검증
+        const valid = validateTOTP(
+            secret,
+            code,
+            cfg.skew,
+            cfg.code_digits,
+            cfg.period_sec,
+        );
+        if (!valid) {
+            await incrementFailedAttempts(accountSeq, account, cfg);
+            reply.code(401).send(fail("Invalid TOTP code"));
+            return;
+        }
+
+        // 성공 → 실패 횟수 리셋 + JWT 발급
+        await resetFailedAttempts(accountSeq);
+        const tokenPair = issueTokenPair(account, cfg);
+
+        reply
+            .header("X-Access-Token", tokenPair.access_token)
+            .header("X-Refresh-Token", tokenPair.refresh_token)
+            .code(200)
+            .send(ok(tokenPair));
+    };
+}