create-entity-app-server 0.0.3

package/src/app/plugins/identity/entity-adapter.ts

@@ -0,0 +1,242 @@
+/**
+ * IdentityQuerier — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 identity_verification, account 엔티티에 접근.
+ * Go의 EntityAdapter를 TypeScript로 포팅.
+ */
+
+import { entityServer } from "@gateway/api";
+import { parseUserAgent } from "../../../system/utils/user-agent.ts";
+import type { VerificationRequest, VerificationResult } from "./types/index.ts";
+
+/** DB 연동 인터페이스 */
+export interface IdentityQuerier {
+    /** pending 상태 인증 요청 레코드를 생성한다 */
+    createRequest(req: VerificationRequest): Promise<number>;
+    /** request_id로 요청을 조회한다 */
+    getRequest(requestId: string): Promise<VerificationRequest | null>;
+    /** 인증 결과를 업데이트한다 */
+    updateResult(
+        requestId: string,
+        result: VerificationResult,
+        ciHash: string,
+    ): Promise<void>;
+    /** 상태만 업데이트한다 */
+    updateStatus(
+        requestId: string,
+        status: string,
+        errorMsg?: string,
+    ): Promise<void>;
+    /** CI 해시로 기존 인증을 조회한다 */
+    findByCIHash(ciHash: string): Promise<Record<string, unknown>[]>;
+    /** CI 해시로 account를 조회한다 */
+    findAccountByCIHash(
+        ciHash: string,
+    ): Promise<Record<string, unknown> | null>;
+    /** account에 CI 해시 및 본인인증 정보를 설정한다 */
+    linkAccountCI(
+        accountSeq: number,
+        ciHash: string,
+        result: VerificationResult,
+    ): Promise<void>;
+}
+
+/** Entity Server 기반 IdentityQuerier 구현 */
+export class IdentityEntityAdapter implements IdentityQuerier {
+    /** IdentityEntityAdapter를 초기화한다 */
+    constructor() {}
+
+    /** pending 상태 인증 요청 레코드를 생성한다 */
+    async createRequest(req: VerificationRequest): Promise<number> {
+        const parsedUserAgent = parseUserAgent(req.userAgent);
+        const data: Record<string, unknown> = {
+            request_id: req.requestId,
+            status: req.status,
+            purpose: req.purpose,
+            provider: req.provider,
+            ip_address: req.ipAddress,
+            user_agent: parsedUserAgent.raw,
+            expires_at: req.expiresAt,
+        };
+        if (parsedUserAgent.platform) {
+            data.user_agent_platform = parsedUserAgent.platform;
+        }
+        if (parsedUserAgent.deviceType) {
+            data.user_agent_device_type = parsedUserAgent.deviceType;
+        }
+        if (parsedUserAgent.browser) {
+            data.user_agent_browser = parsedUserAgent.browser;
+        }
+        if (parsedUserAgent.browserVersion) {
+            data.user_agent_browser_version = parsedUserAgent.browserVersion;
+        }
+        if (req.accountSeq > 0) {
+            data.account_seq = req.accountSeq;
+        }
+
+        const resp = await entityServer.submit("identity_verification", data);
+        return (resp as any).seq ?? 0;
+    }
+
+    /** request_id로 요청을 조회한다 */
+    async getRequest(requestId: string): Promise<VerificationRequest | null> {
+        const resp = await entityServer.list("identity_verification", {
+            conditions: { request_id: requestId },
+            limit: 1,
+        });
+
+        const items = ((resp as any).data?.items ??
+            (resp as any).items ??
+            []) as Record<string, unknown>[];
+        if (items.length === 0) return null;
+
+        return mapToVerificationRequest(items[0]);
+    }
+
+    /** 인증 결과를 업데이트한다 */
+    async updateResult(
+        requestId: string,
+        result: VerificationResult,
+        ciHash: string,
+    ): Promise<void> {
+        const req = await this.getRequest(requestId);
+        if (!req) throw new Error(`identity: request not found: ${requestId}`);
+
+        await entityServer.submit("identity_verification", {
+            seq: req.seq,
+            status: "verified",
+            ci_hash: ciHash,
+            di: result.di,
+            name: result.name,
+            birth_date: result.birthDate,
+            gender: result.gender,
+            carrier: result.carrier,
+            phone: result.phone,
+            nationality: result.nationality,
+            verified_at: new Date().toISOString(),
+        });
+    }
+
+    /** 상태만 업데이트한다 */
+    async updateStatus(
+        requestId: string,
+        status: string,
+        errorMsg?: string,
+    ): Promise<void> {
+        const req = await this.getRequest(requestId);
+        if (!req) throw new Error(`identity: request not found: ${requestId}`);
+
+        const data: Record<string, unknown> = {
+            seq: req.seq,
+            status,
+        };
+        if (errorMsg) data.error_message = errorMsg;
+
+        await entityServer.submit("identity_verification", data);
+    }
+
+    /** CI 해시로 기존 인증을 조회한다 */
+    async findByCIHash(ciHash: string): Promise<Record<string, unknown>[]> {
+        const resp = await entityServer.list("identity_verification", {
+            conditions: { ci_hash: ciHash, status: "verified" },
+            limit: 10,
+            orderBy: "seq",
+            orderDir: "DESC",
+        });
+
+        return ((resp as any).data?.items ??
+            (resp as any).items ??
+            []) as Record<string, unknown>[];
+    }
+
+    /** CI 해시로 account를 조회한다 */
+    async findAccountByCIHash(
+        ciHash: string,
+    ): Promise<Record<string, unknown> | null> {
+        const resp = await entityServer.list("account", {
+            conditions: { ci_hash: ciHash },
+            limit: 1,
+        });
+
+        const items = ((resp as any).data?.items ??
+            (resp as any).items ??
+            []) as Record<string, unknown>[];
+        return items.length > 0 ? items[0] : null;
+    }
+
+    /** account에 CI 해시 및 본인인증 정보를 설정한다 */
+    async linkAccountCI(
+        accountSeq: number,
+        ciHash: string,
+        result: VerificationResult,
+    ): Promise<void> {
+        await entityServer.submit("account", {
+            seq: accountSeq,
+            ci_hash: ciHash,
+            identity_verified: true,
+            identity_name: result.name,
+            identity_birth_date: result.birthDate,
+            identity_gender: result.gender,
+        });
+    }
+}
+
+// ── 헬퍼 함수 ──
+
+/** Entity Server 응답을 VerificationRequest로 변환한다 */
+function mapToVerificationRequest(
+    m: Record<string, unknown>,
+): VerificationRequest {
+    const rawUserAgent = (m.user_agent as string) ?? "";
+    const parsedUserAgent = parseUserAgent(rawUserAgent);
+    return {
+        seq: toNumber(m.seq),
+        requestId: (m.request_id as string) ?? "",
+        status: (m.status as string as any) ?? "pending",
+        purpose: (m.purpose as string) ?? "",
+        provider: (m.provider as string) ?? "",
+        ciHash: (m.ci_hash as string) ?? "",
+        di: (m.di as string) ?? "",
+        name: (m.name as string) ?? "",
+        birthDate: (m.birth_date as string) ?? "",
+        gender: (m.gender as string) ?? "",
+        carrier: (m.carrier as string) ?? "",
+        phone: (m.phone as string) ?? "",
+        nationality: (m.nationality as string) ?? "",
+        accountSeq: toNumber(m.account_seq),
+        ipAddress: (m.ip_address as string) ?? "",
+        userAgent: rawUserAgent,
+        userAgentPlatform:
+            (m.user_agent_platform as string) ?? parsedUserAgent.platform,
+        userAgentDeviceType:
+            (m.user_agent_device_type as string) ?? parsedUserAgent.deviceType,
+        userAgentBrowser:
+            (m.user_agent_browser as string) ?? parsedUserAgent.browser,
+        userAgentBrowserVersion:
+            (m.user_agent_browser_version as string) ??
+            parsedUserAgent.browserVersion,
+        userAgentParsed: {
+            raw: parsedUserAgent.raw,
+            platform:
+                (m.user_agent_platform as string) ?? parsedUserAgent.platform,
+            deviceType:
+                (m.user_agent_device_type as string) ??
+                parsedUserAgent.deviceType,
+            browser:
+                (m.user_agent_browser as string) ?? parsedUserAgent.browser,
+            browserVersion:
+                (m.user_agent_browser_version as string) ??
+                parsedUserAgent.browserVersion,
+        },
+        verifiedAt: (m.verified_at as string) ?? "",
+        expiresAt: (m.expires_at as string) ?? "",
+        errorMessage: (m.error_message as string) ?? "",
+    };
+}
+
+/** 값을 number로 변환한다 */
+function toNumber(v: unknown): number {
+    if (typeof v === "number") return v;
+    if (typeof v === "string") return parseInt(v, 10) || 0;
+    return 0;
+}

package/src/app/plugins/identity/handlers.ts

@@ -0,0 +1,239 @@
+/**
+ * 본인인증 API 핸들러
+ *
+ * POST   /request            → 인증 요청 생성
+ * POST   /callback           → 중계사 콜백 수신
+ * GET    /result/:request_id → 인증 결과 조회
+ * POST   /verify-ci          → CI 기반 중복 확인
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+
+/** identityService가 활성화되어 있는지 확인한다 */
+const ensureSvc = (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.server.identityService) {
+        reply.status(503).send(fail("Identity plugin not enabled"));
+        return null;
+    }
+    return req.server.identityService;
+};
+
+// ── 인증 요청 생성 ──
+
+/** 본인인증 요청을 생성한다 */
+export async function handleRequest(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const body = (request.body ?? {}) as Record<string, string>;
+    const { purpose, method, provider } = body;
+
+    if (!purpose) {
+        return reply.status(400).send(fail("purpose is required"));
+    }
+
+    // JWT가 있으면 account_seq 추출 (선택적)
+    let accountSeq = 0;
+    if (request.user) {
+        accountSeq = (request.user as any).seq ?? 0;
+    }
+
+    try {
+        const result = await svc.createRequest(
+            purpose,
+            method ?? "",
+            provider ?? "",
+            request.ip,
+            request.headers["user-agent"] ?? "",
+            accountSeq,
+        );
+        return ok(result);
+    } catch (err) {
+        console.warn("identity: create request failed:", err);
+        return reply
+            .status(500)
+            .send(fail("failed to create identity verification request"));
+    }
+}
+
+// ── 콜백 처리 ──
+
+/** 중계사 콜백을 수신한다 */
+export async function handleCallback(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const cfg = svc.config();
+    const contentType = request.headers["content-type"] ?? "";
+    let encData = "";
+    let tokenVersionId = "";
+    let provider = "";
+
+    if (
+        contentType.includes("application/x-www-form-urlencoded") ||
+        contentType.includes("multipart/form-data")
+    ) {
+        // form-urlencoded 방식 (NICE, KMC)
+        const body = request.body as Record<string, string>;
+        encData = body.enc_data ?? "";
+        tokenVersionId = body.token_version_id ?? "";
+        // KMC는 rec_cert 파라미터 사용
+        if (!encData) encData = body.rec_cert ?? "";
+    } else {
+        // JSON 방식
+        const body = (request.body ?? {}) as Record<string, string>;
+        encData = body.enc_data ?? "";
+        tokenVersionId = body.token_version_id ?? "";
+        provider = body.provider ?? "";
+    }
+
+    if (!encData) {
+        return reply.status(400).send(fail("enc_data is required"));
+    }
+
+    // 프로바이더 추론
+    if (!provider) {
+        provider =
+            (request.query as Record<string, string>).provider ?? cfg.default;
+    }
+
+    try {
+        const result = await svc.handleCallback(
+            provider,
+            encData,
+            tokenVersionId || undefined,
+        );
+
+        // 성공: 팝업 닫기 + postMessage 전송
+        const requestId = result.requestId;
+        const redirectUrl = cfg.successRedirectUrl
+            ? `${cfg.successRedirectUrl}?request_id=${requestId}`
+            : "";
+
+        reply.type("text/html");
+        return callbackHTML("verified", requestId, redirectUrl);
+    } catch (err) {
+        console.warn("identity: callback failed:", err);
+
+        // 실패 시 리다이렉트 또는 에러 페이지
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const redirectUrl = cfg.failureRedirectUrl
+            ? `${cfg.failureRedirectUrl}?error=${encodeURIComponent(errMsg)}`
+            : "";
+
+        reply.type("text/html");
+        return callbackHTML("failed", "", redirectUrl);
+    }
+}
+
+// ── 결과 조회 ──
+
+/** 인증 결과를 조회한다 */
+export async function handleResult(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { request_id } = request.params as { request_id: string };
+    if (!request_id) {
+        return reply.status(400).send(fail("request_id is required"));
+    }
+
+    // 길이 검증 (64자 hex)
+    if (request_id.length !== 64) {
+        return reply.status(400).send(fail("invalid request_id format"));
+    }
+
+    try {
+        const result = await svc.getResult(request_id);
+        if (!result) {
+            return reply.status(404).send(fail("request not found"));
+        }
+        return ok(result);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("not found")) {
+            return reply.status(404).send(fail("request not found"));
+        }
+        return reply.status(500).send(fail("failed to get result"));
+    }
+}
+
+// ── CI 중복 확인 ──
+
+/** CI 해시로 중복 가입 여부를 확인한다 */
+export async function handleVerifyCI(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const body = (request.body ?? {}) as Record<string, string>;
+    const ciHash = body.ci_hash ?? "";
+
+    if (!ciHash) {
+        return reply.status(400).send(fail("ci_hash is required"));
+    }
+
+    try {
+        const { exists, accountSeq } = await svc.checkCIDuplicate(ciHash);
+        const data: Record<string, unknown> = { exists };
+        if (exists) data.account_seq = accountSeq;
+        return ok(data);
+    } catch {
+        return reply.status(500).send(fail("CI check failed"));
+    }
+}
+
+// ── 콜백 HTML 헬퍼 ──
+
+/** 콜백 결과를 프론트엔드에 전달하는 HTML을 생성한다 */
+function callbackHTML(
+    status: string,
+    requestId: string,
+    redirectUrl: string,
+): string {
+    const redirectScript = redirectUrl
+        ? `
+                setTimeout(function() {
+                    if (window.opener) {
+                        window.opener.location.href = ${JSON.stringify(redirectUrl)};
+                    }
+                }, 100);`
+        : "";
+
+    return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>본인인증 결과</title></head>
+<body>
+<script>
+(function() {
+    try {
+        if (window.opener && window.opener.postMessage) {
+            window.opener.postMessage({
+                type: "identity_verification",
+                request_id: ${JSON.stringify(requestId)},
+                status: ${JSON.stringify(status)}
+            }, "*");
+        }
+        ${redirectScript}
+    } catch(e) {
+        console.error("identity callback error:", e);
+    }
+    setTimeout(function() { window.close(); }, 300);
+})();
+</script>
+<p>인증이 완료되었습니다. 이 창은 자동으로 닫힙니다.</p>
+</body>
+</html>`;
+}

package/src/app/plugins/identity/index.ts

@@ -0,0 +1,80 @@
+/**
+ * 본인인증 플러그인 Fastify 플러그인
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadIdentityConfig } from "./config.ts";
+import { IdentityService } from "./service.ts";
+import { IdentityEntityAdapter } from "./entity-adapter.ts";
+import { createClient, type IdentityClient } from "./providers/index.ts";
+import { ensurePluginEntities } from "@gateway/api";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+declare module "fastify" {
+    interface FastifyInstance {
+        /** 본인인증 서비스 인스턴스 (disabled 시 null) */
+        identityService: IdentityService | null;
+    }
+}
+
+/** 본인인증 플러그인을 등록한다 */
+export default fp(async (app: FastifyInstance) => {
+    const cfg = loadIdentityConfig();
+    if (!cfg) {
+        app.decorate("identityService", null);
+        return;
+    }
+
+    // entities/account.json 의 identity 필드를 account 엔티티에 additive-sync
+    await ensurePluginEntities(__dirname).catch((err) =>
+        app.log.warn({ err }, "Identity: entity setup failed, continuing"),
+    );
+
+    // 프로바이더 클라이언트 생성
+    const clients = new Map<string, IdentityClient>();
+    let defaultClient: IdentityClient | null = null;
+
+    for (const [name, providerCfg] of Object.entries(cfg.providers)) {
+        const client = createClient(providerCfg);
+        clients.set(name, client);
+        if (name === cfg.default) {
+            defaultClient = client;
+        }
+    }
+
+    if (!defaultClient) {
+        throw new Error(
+            `identity: default provider '${cfg.default}' not found`,
+        );
+    }
+
+    // 서비스 생성
+    const service = new IdentityService(cfg, clients, defaultClient);
+
+    // Entity Server 어댑터 연결
+    const entityAdapter = new IdentityEntityAdapter();
+    service.setQuerier(entityAdapter);
+
+    app.decorate("identityService", service);
+
+    // 만료 토큰 캐시 정리 (5분 주기)
+    const cleanupInterval = setInterval(
+        () => {
+            service.cleanExpiredTokens();
+        },
+        5 * 60 * 1000,
+    );
+
+    app.addHook("onClose", async () => {
+        clearInterval(cleanupInterval);
+        console.log("Identity plugin stopped");
+    });
+
+    console.log(
+        `Identity plugin enabled — default: ${cfg.default}, providers: ${Object.keys(cfg.providers).join(", ")}`,
+    );
+});