create-entity-app-server 0.0.3

package/src/app/hooks/post.ts

@@ -0,0 +1,162 @@
+/**
+ * Post 엔티티 훅 예제 — 게시글 작성/조회 시 가공 로직
+ *
+ * Entity Server의 /api/v1/post 요청을 가로채는 훅입니다.
+ * registry.ts 에서 { post: postHook } 으로 등록하면
+ * 클라이언트 → Gateway → Entity Server 흐름에서 before/after 훅이 자동 실행됩니다.
+ *
+ * - beforeSubmit: XSS 방지, 자동 필드
+ * - afterSubmit:  로깅
+ * - afterGet:     본문 미리보기 추가 (find 조회에도 자동 적용)
+ * - beforeDelete: 작성자 본인만 삭제 허용
+ * - beforeList:   기본 페이징/정렬
+ * - afterList:    요약 필드 추가
+ */
+
+import type {
+    EntityHook,
+    UserInfo,
+    SubmitContext,
+    DeleteContext,
+} from "@gateway/api";
+import { logger, ForbiddenError } from "@gateway/api";
+
+/** 간단한 HTML 태그 제거 (XSS 방지 예시) */
+function stripHtml(str: string): string {
+    return str.replace(/<[^>]*>/g, "");
+}
+
+export const postHook: EntityHook = {
+    /**
+     * 게시글 등록/수정 전 데이터 가공
+     *
+     * - ctx.old: 수정 전 데이터 (신규 시 null)
+     * - ctx.new: 클라이언트 요청 데이터
+     * - 제목/본문 HTML 태그 제거 (간이 XSS 방지)
+     * - 신규: 작성자 자동 설정, 슬러그 생성
+     */
+    async beforeSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+        const data = { ...ctx.new };
+
+        // HTML 태그 제거
+        if (data.title) {
+            data.title = stripHtml(data.title as string);
+        }
+        if (data.content) {
+            data.content = stripHtml(data.content as string);
+        }
+
+        if (!ctx.old) {
+            // 신규 게시글
+            data.author_id = user.sub;
+            data.author_name = user.email?.split("@")[0] ?? "unknown";
+            data.created_time = new Date().toISOString();
+
+            // 제목 기반 슬러그 생성
+            if (data.title) {
+                data.slug = (data.title as string)
+                    .toLowerCase()
+                    .replace(/[^a-z0-9가-힣\s-]/g, "")
+                    .replace(/\s+/g, "-")
+                    .slice(0, 80);
+            }
+        }
+
+        // 수정 시 수정일 갱신
+        data.updated_time = new Date().toISOString();
+
+        return data;
+    },
+
+    /**
+     * 게시글 등록/수정 후 로깅
+     *
+     * - ctx.old / ctx.new 로 변경 전후 비교 가능
+     */
+    async afterSubmit(entity: string, ctx: SubmitContext, user: UserInfo) {
+        const action = ctx.old ? "수정" : "작성";
+        logger.info(
+            { seq: ctx.new.seq, title: ctx.new.title, action },
+            `게시글 ${action} 완료`,
+        );
+        return ctx.new;
+    },
+
+    /**
+     * 게시글 단건 조회 후 — 본문 미리보기 추가
+     */
+    async afterGet(entity: string, data: any, user: UserInfo) {
+        if (data.content) {
+            data.preview =
+                data.content.slice(0, 100) +
+                (data.content.length > 100 ? "…" : "");
+        }
+        return data;
+    },
+
+    /**
+     * 게시글 삭제 전 — 작성자 본인 또는 관리자만 삭제 허용
+     *
+     * ctx.data에 삭제 대상 게시글 데이터가 담겨 있으므로
+     * 별도 entityServer.get() 호출 없이 바로 확인 가능
+     */
+    async beforeDelete(entity: string, ctx: DeleteContext, user: UserInfo) {
+        // 관리자는 항상 삭제 가능
+        if (user.role === "admin") return true;
+
+        // 작성자 본인 확인 — ctx.data에서 바로 확인
+        if (ctx.data && ctx.data.author_id !== user.sub) {
+            throw new ForbiddenError(
+                "본인이 작성한 게시글만 삭제할 수 있습니다",
+            );
+        }
+
+        logger.info(
+            { seq: ctx.seq, title: ctx.data?.title, userId: user.sub },
+            "게시글 삭제 요청",
+        );
+        return true;
+    },
+
+    /**
+     * 게시글 목록 전 — 기본 파라미터 설정
+     *
+     * - 기본 정렬: 최신순
+     * - 삭제된 게시글 제외 필터 자동 추가
+     */
+    async beforeList(entity: string, params: any, user: UserInfo) {
+        // 기본 정렬
+        if (!params.orderBy) {
+            params.orderBy = "created_time";
+            params.orderDir = "desc";
+        }
+
+        // 삭제된 게시글 제외 (soft delete)
+        params.conditions = params.conditions || [];
+        params.conditions.push({
+            field: "is_deleted",
+            operator: "eq",
+            value: false,
+        });
+
+        return params;
+    },
+
+    /**
+     * 게시글 목록 후 — 본문 미리보기 추가
+     *
+     * - content → preview (100자 요약)
+     */
+    async afterList(entity: string, result: any, user: UserInfo) {
+        if (result.list) {
+            result.list = result.list.map((post: any) => ({
+                ...post,
+                preview: post.content
+                    ? post.content.slice(0, 100) +
+                      (post.content.length > 100 ? "…" : "")
+                    : "",
+            }));
+        }
+        return result;
+    },
+};

package/src/app/plugins/2fa/config.example.json

@@ -0,0 +1,15 @@
+{
+    "enabled": true,
+    "issuer": "MyApp",
+    "code_digits": 6,
+    "period_sec": 30,
+    "skew": 1,
+    "recovery_code_count": 10,
+    "setup_token_ttl_sec": 300,
+    "max_verify_attempts": 5,
+    "verify_lockout_sec": 300,
+    "jwt_access_ttl_sec": 3600,
+    "jwt_refresh_ttl_sec": 1209600,
+    "jwt_issuer": "entity-server",
+    "minify": false
+}

package/src/app/plugins/2fa/config.json

@@ -0,0 +1,17 @@
+{
+    "_comment": "2단계 인증(TOTP) 플러그인 — QR코드 기반 OTP 설정/검증, 복구 코드, JWT 발급 설정 포함",
+    "enabled": true,
+    "issuer": "EntityServer",
+    "code_digits": 6,
+    "period_sec": 30,
+    "skew": 1,
+    "recovery_code_count": 10,
+    "setup_token_ttl_sec": 300,
+    "max_verify_attempts": 5,
+    "verify_lockout_sec": 300,
+    "jwt_access_ttl_sec": 3600,
+    "jwt_refresh_ttl_sec": 1209600,
+    "jwt_issuer": "entity-server",
+    "deploy": true,
+    "minify": true
+}

package/src/app/plugins/2fa/config.ts

@@ -0,0 +1,44 @@
+/**
+ * 2FA (TOTP) 설정 로더
+ *
+ * config.json 을 읽어 TwoFactorConfig 를 반환한다.
+ * enabled: false 이면 null 을 반환한다.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { TwoFactorConfig } from "./types.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** config.json 을 읽어 설정을 반환한다. enabled: false 이면 null. */
+export function loadTwoFactorConfig(): TwoFactorConfig | null {
+    const configPath = resolve(__dirname, "config.json");
+    let raw: Record<string, unknown> = {};
+
+    if (existsSync(configPath)) {
+        const text = readFileSync(configPath, "utf-8").replace(
+            /\$\{([^}]+)\}/g,
+            (_m, name: string) => process.env[name] ?? "",
+        );
+        raw = JSON.parse(text) as Record<string, unknown>;
+    }
+
+    if (raw.enabled === false) return null;
+
+    return {
+        enabled: true,
+        issuer: String(raw.issuer ?? "EntityServer"),
+        code_digits: Number(raw.code_digits) || 6,
+        period_sec: Number(raw.period_sec) || 30,
+        skew: Number(raw.skew) ?? 1,
+        recovery_code_count: Number(raw.recovery_code_count) || 10,
+        setup_token_ttl_sec: Number(raw.setup_token_ttl_sec) || 300,
+        max_verify_attempts: Number(raw.max_verify_attempts) || 5,
+        verify_lockout_sec: Number(raw.verify_lockout_sec) || 300,
+        jwt_access_ttl_sec: Number(raw.jwt_access_ttl_sec) || 3600,
+        jwt_refresh_ttl_sec: Number(raw.jwt_refresh_ttl_sec) || 1209600,
+        jwt_issuer: String(raw.jwt_issuer ?? "entity-server"),
+    };
+}

package/src/app/plugins/2fa/docs/README.md

@@ -0,0 +1,139 @@
+# 2단계 인증 플러그인 (2FA)
+
+TOTP(Time-based One-Time Password) 기반 2단계 인증을 제공합니다. QR코드로 인증 앱을 연결하고, 로그인 시 OTP를 추가 검증합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [API](#api)
+- [인증 흐름](#인증-흐름)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목       | 내용                                   |
+| ---------- | -------------------------------------- |
+| 인증 방식  | TOTP (RFC 6238)                        |
+| OTP 자리수 | 6자리                                  |
+| 유효 시간  | 30초 주기 (skew ±1 허용)               |
+| 복구코드   | 10개 (1회용, 전화기 분실 시 사용)      |
+| 계정 연동  | 기존 `account` 엔티티에 TOTP 필드 추가 |
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": true,
+    "issuer": "EntityServer",
+    "code_digits": 6,
+    "period_sec": 30,
+    "skew": 1,
+    "recovery_code_count": 10,
+    "setup_token_ttl_sec": 300,
+    "max_verify_attempts": 5,
+    "verify_lockout_sec": 300,
+    "jwt_access_ttl_sec": 3600,
+    "jwt_refresh_ttl_sec": 1209600,
+    "jwt_issuer": "entity-server"
+}
+```
+
+### 설정 항목
+
+| 항목                  | 기본값         | 설명                                 |
+| --------------------- | -------------- | ------------------------------------ |
+| `enabled`             | `true`         | 플러그인 활성화                      |
+| `issuer`              | `EntityServer` | 인증 앱에 표시될 서비스명            |
+| `code_digits`         | `6`            | OTP 자리수                           |
+| `period_sec`          | `30`           | OTP 유효 시간(초)                    |
+| `skew`                | `1`            | 시간 오차 허용 범위 (±1 주기)        |
+| `recovery_code_count` | `10`           | 복구코드 발급 개수                   |
+| `setup_token_ttl_sec` | `300`          | 2FA 설정 토큰 유효 시간(초)          |
+| `max_verify_attempts` | `5`            | 연속 실패 허용 횟수                  |
+| `verify_lockout_sec`  | `300`          | 잠금 해제까지 대기 시간(초)          |
+| `jwt_access_ttl_sec`  | `3600`         | 2FA 완료 후 발급되는 액세스 토큰 TTL |
+| `jwt_refresh_ttl_sec` | `1209600`      | 리프레시 토큰 TTL (14일)             |
+
+---
+
+## API
+
+기본 경로: `/api/v1/account/2fa`
+
+| 메서드   | 경로                   | 인증             | 설명                                  |
+| -------- | ---------------------- | ---------------- | ------------------------------------- |
+| `POST`   | `/setup`               | JWT 필요         | 2FA 설정 시작 — QR코드 및 secret 반환 |
+| `POST`   | `/setup/verify`        | setup 토큰       | OTP 입력으로 2FA 활성화 확인          |
+| `DELETE` | `/`                    | JWT 필요         | 2FA 비활성화                          |
+| `GET`    | `/status`              | JWT 필요         | 2FA 활성화 여부 조회                  |
+| `POST`   | `/recovery/regenerate` | JWT 필요         | 복구코드 재생성 (기존 코드 무효화)    |
+| `POST`   | `/verify`              | two_factor_token | 로그인 중 OTP 검증 — 최종 JWT 발급    |
+| `POST`   | `/recovery`            | two_factor_token | 복구코드로 인증 — 최종 JWT 발급       |
+
+### POST /setup 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "setup_token": "...",
+        "qr_url": "otpauth://totp/EntityServer:user@example.com?secret=...&issuer=EntityServer",
+        "secret": "JBSWY3DPEHPK3PXP"
+    }
+}
+```
+
+### POST /verify 요청 바디
+
+```json
+{
+    "two_factor_token": "eyJ...",
+    "code": "123456"
+}
+```
+
+---
+
+## 인증 흐름
+
+### 2FA 설정
+
+```
+1. POST /account/login         → { two_factor_required: false, access_token: "..." }
+   (또는 2FA 미설정 계정 정상 로그인)
+2. POST /account/2fa/setup     → { setup_token, qr_url, secret }
+3. 인증 앱으로 QR 스캔
+4. POST /account/2fa/setup/verify  body: { setup_token, code }  → 2FA 활성화
+```
+
+### 2FA 활성화 계정 로그인
+
+```
+1. POST /account/login         → { two_factor_required: true, two_factor_token: "..." }
+2. POST /account/2fa/verify    body: { two_factor_token, code }  → { access_token, refresh_token }
+```
+
+### 복구코드 로그인 (기기 분실 시)
+
+```
+POST /account/2fa/recovery    body: { two_factor_token, recovery_code: "xxxx-xxxx" }
+→ { access_token, refresh_token }
+```
+
+---
+
+## 운영 팁
+
+- `issuer`는 인증 앱 목록에 표시될 서비스 이름 — 배포 전 변경할 것
+- 복구코드는 발급 시 일회성으로 보여주며 DB에 해시로 저장됨 — 사용자에게 안전하게 보관하도록 안내
+- `skew: 1` 설정으로 ±30초 오차를 허용하므로, 서버 시간 동기화(NTP) 필요
+- `max_verify_attempts` 초과 시 `verify_lockout_sec`만큼 잠김 — 운영 환경에 맞게 조정

package/src/app/plugins/2fa/entities/account.json

@@ -0,0 +1,30 @@
+{
+    "name": "account",
+    "description": "2FA(TOTP) 활성화 시 account 엔티티에 추가되는 필드 정의. enabled=true 시 앱서버 시작 때 entity 서버에 additive-sync 됩니다.",
+    "fields": {
+        "totp_secret": {
+            "type": "varchar(64)",
+            "comment": "TOTP 비밀 키 (Base32, 암호화 저장)"
+        },
+        "totp_enabled": {
+            "type": "bool",
+            "default": false,
+            "comment": "2FA 활성화 여부"
+        },
+        "totp_enabled_time": {
+            "comment": "2FA 활성화 시각"
+        },
+        "totp_recovery_codes": {
+            "type": "varchar(500)",
+            "comment": "복구 코드 JSON 배열 (SHA-256 해시, 암호화 저장)"
+        },
+        "totp_failed_attempts": {
+            "type": "uint",
+            "default": 0,
+            "comment": "연속 TOTP 실패 횟수"
+        },
+        "totp_locked_until": {
+            "comment": "TOTP 잠금 해제 시각"
+        }
+    }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * DELETE /api/v1/account/2fa
+ *
+ * 2FA 비활성화: JWT 인증 + 비밀번호(선택) + TOTP 코드 확인
+ *
+ * Go `HandleDisable` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, sendEmail, logger } from "@gateway/api";
+import type { TwoFactorConfig, TwoFactorDisableBody } from "../types.ts";
+import {
+    getAccountSeqFromJwt,
+    getAccountBySeq,
+    updateAccount,
+    nowIsoString,
+    TEMPLATES_DIR,
+} from "./utils.ts";
+import { verifyPassword } from "../../../routes/password-reset/password-utils.ts";
+import { validateTOTP } from "../totp-utils.ts";
+
+export function createDisableHandler(cfg: TwoFactorConfig) {
+    return async function handleDisable(
+        req: FastifyRequest<{ Body: TwoFactorDisableBody }>,
+        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;
+        }
+
+        // 비밀번호 확인 (비밀번호가 있는 계정만)
+        const hasPassword = Boolean(account.has_password);
+        if (hasPassword) {
+            const passwd = (body.passwd ?? "").trim();
+            if (!passwd) {
+                reply
+                    .code(400)
+                    .send(
+                        fail("passwd is required for password-based accounts"),
+                    );
+                return;
+            }
+            const storedPasswd = account.passwd ?? "";
+            if (!verifyPassword(passwd, storedPasswd)) {
+                reply.code(401).send(fail("Invalid password"));
+                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;
+        }
+
+        // 2FA 비활성화
+        await updateAccount(accountSeq, {
+            totp_secret: null,
+            totp_enabled: false,
+            totp_enabled_time: null,
+            totp_recovery_codes: null,
+            totp_failed_attempts: 0,
+            totp_locked_until: null,
+        });
+
+        // 비활성화 알림 이메일
+        sendEmail({
+            to: [account.email],
+            subject: "2단계 인증 비활성화 알림",
+            templateDir: TEMPLATES_DIR,
+            templateName: "auth/2fa_disabled",
+            templateData: {
+                email: account.email,
+                disabled_time: nowIsoString(),
+                disabled_by: "본인 요청",
+            },
+        }).catch((err: unknown) =>
+            logger.warn(
+                { err },
+                "2FA disable: failed to send notification email",
+            ),
+        );
+
+        reply.code(200).send(ok({ message: "2FA가 비활성화되었습니다." }));
+    };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 2FA 핸들러 배럴 re-export
+ */
+
+export { createSetupHandler } from "./setup.ts";
+export { createSetupVerifyHandler } from "./setup-verify.ts";
+export { createVerifyHandler } from "./verify.ts";
+export { createRecoveryHandler } from "./recovery.ts";
+export { createDisableHandler } from "./disable.ts";
+export { createStatusHandler } from "./status.ts";
+export { createRegenerateHandler } from "./regenerate.ts";

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

@@ -0,0 +1,98 @@
+/**
+ * POST /api/v1/account/2fa/recovery
+ *
+ * 복구 코드로 로그인: two_factor_token + 복구 코드 검증 → JWT 토큰 쌍 발급
+ * 인증 불필요 (two_factor_token 사용)
+ *
+ * Go `HandleRecovery` 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { TwoFactorConfig, TwoFactorRecoveryBody } from "../types.ts";
+import {
+    getAccountSeqFromTwoFactorToken,
+    getAccountBySeq,
+    checkLockout,
+    incrementFailedAttempts,
+    updateAccount,
+    parseRecoveryHashes,
+    issueTokenPair,
+} from "./utils.ts";
+import { verifyRecoveryCode } from "../totp-utils.ts";
+
+export function createRecoveryHandler(cfg: TwoFactorConfig) {
+    return async function handleRecovery(
+        req: FastifyRequest<{ Body: TwoFactorRecoveryBody }>,
+        reply: FastifyReply,
+    ): Promise<void> {
+        const body = req.body ?? {};
+        const recoveryCode = (body.recovery_code ?? "").trim();
+
+        if (!body.two_factor_token || !recoveryCode) {
+            reply
+                .code(400)
+                .send(fail("two_factor_token and recovery_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 hashes = parseRecoveryHashes(account);
+        if (hashes.length === 0) {
+            reply.code(400).send(fail("No recovery codes available"));
+            return;
+        }
+
+        // 복구 코드 검증
+        const { valid, remaining } = verifyRecoveryCode(recoveryCode, hashes);
+        if (!valid) {
+            await incrementFailedAttempts(accountSeq, account, cfg);
+            reply.code(401).send(fail("Invalid recovery code"));
+            return;
+        }
+
+        // 사용된 코드 제거 + 실패 횟수 리셋
+        await updateAccount(accountSeq, {
+            totp_recovery_codes: JSON.stringify(remaining),
+            totp_failed_attempts: 0,
+            totp_locked_until: null,
+        });
+
+        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,
+                    remaining_recovery_codes: remaining.length,
+                    message:
+                        "복구 코드로 로그인했습니다. 새 복구 코드 생성을 권장합니다.",
+                }),
+            );
+    };
+}