create-entity-app-server 0.0.3

package/docs/plugins/how-to-create.md

@@ -0,0 +1,148 @@
+# 플러그인 추가 가이드
+
+`holidays` 플러그인이 기준 샘플이다. 새 플러그인도 같은 패턴으로 구성한다.
+
+기준 파일: `src/app/plugins/holidays/`
+
+---
+
+## 1) 폴더 구조
+
+`{plugin}`은 새 플러그인 이름(예: `sms`, `push`)이다.
+
+```text
+src/app/plugins/{plugin}/
+├── config.json          — 활성화 여부 + 설정값 (enabled: true/false)
+├── config.example.json  — 설정 예시 (빌드 시 config.json 으로 배포)
+├── config.ts            — config.json 로더 (enabled: false 이면 null 반환)
+├── index.ts             — 플러그인 진입점 (fastify-plugin 래퍼)
+├── routes.ts            — /api/v1/{plugin}/* 라우트 테이블 (선택)
+├── handlers.ts          — 요청/응답 처리 (선택)
+├── service.ts           — 비즈니스 로직
+├── types/
+│   └── index.ts         — 타입 정의 + re-export
+└── providers/           — 외부 서비스 클라이언트 (여러 구현체가 있을 때)
+    ├── index.ts         — 프로바이더 팩토리
+    └── {name}.ts        — 개별 프로바이더 구현
+```
+
+---
+
+## 2) 파일 역할
+
+- `config.json`: `enabled: false` 이면 플러그인이 로드되지 않는다.
+- `config.example.json`: 빌드 시 `config.json`으로 교체되어 배포된다. 실제 `config.json`은 Git에 커밋하지 않는다.
+- `config.ts`: `config.json`을 읽어 타입이 적용된 설정 객체를 반환한다. `enabled: false` 또는 파일 없으면 `null` 반환.
+- `index.ts`: `fastify-plugin`(`fp()`)으로 래핑된 플러그인 진입점. `config.ts`로 설정을 로드하고 `app.decorate()`로 서비스를 등록한다.
+- `routes.ts`: URL 매핑 테이블. `index.ts`에서 `app.register()`로 등록한다. HTTP API가 필요없으면 생략한다.
+- `service.ts`: 외부 API 호출·DB 쿼리 등 실제 비즈니스 로직.
+- `providers/`: 동일 기능의 여러 구현체(예: OpenAI·Claude·Gemini)가 있을 때 분리한다.
+
+---
+
+## 3) `config.ts` 패턴
+
+```ts
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { MyPluginConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+export function loadMyPluginConfig(): MyPluginConfig | null {
+    if (!existsSync(CONFIG_PATH)) return null;
+
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_m, name) => process.env[name] ?? "",
+        );
+        const cfg = JSON.parse(raw) as MyPluginConfig;
+        if (cfg.enabled === false) {
+            logger.info("MyPlugin disabled in config");
+            return null;
+        }
+        return cfg;
+    } catch (err) {
+        logger.error({ err }, "Failed to load MyPlugin config");
+        return null;
+    }
+}
+```
+
+---
+
+## 4) `index.ts` 패턴
+
+```ts
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadMyPluginConfig } from "./config.ts";
+import { MyService } from "./service.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        myService: MyService | null;
+    }
+}
+
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadMyPluginConfig();
+        if (!config) {
+            app.decorate("myService", null);
+            return;
+        }
+
+        const service = new MyService(config);
+        app.decorate("myService", service);
+
+        // HTTP 라우트가 있으면 등록
+        const { default: routes } = await import("./routes.ts");
+        await app.register(routes, { prefix: "/api/v1/my-plugin" });
+    },
+    { name: "my-plugin" },
+);
+```
+
+> `fp()`로 래핑하지 않으면 `app.decorate()`가 자식 스코프에만 적용되어 다른 플러그인에서 접근할 수 없다.
+
+---
+
+## 5) `config.json` / `config.example.json`
+
+`config.json` (실제 설정, Git 제외):
+
+```json
+{
+    "enabled": false,
+    "apiKey": "${MY_PLUGIN_API_KEY}"
+}
+```
+
+`config.example.json` (빌드 배포용):
+
+```json
+{
+    "enabled": false,
+    "apiKey": "${MY_PLUGIN_API_KEY}"
+}
+```
+
+`${ENV_VAR}` 형태로 환경변수를 참조하면 `config.ts`가 런타임에 치환한다.
+
+---
+
+## 6) 자동 로드 조건
+
+`src/app/plugins/{plugin}/index.ts` 파일이 있으면 서버 시작 시 알파벳 순으로 자동 로드된다. 별도 등록 코드가 필요없다.
+
+## 관련 문서
+
+- [라우트 추가 가이드](../routes/how-to-create.md)
+- [설정 파일 가이드](../configs.md)

package/docs/plugins/identity.md

@@ -0,0 +1,223 @@
+# 본인인증(Identity Verification) 가이드
+
+NICE, KMC, 다날 중계사를 통한 본인인증 가이드입니다.
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.
+실제 라우트표, 호출 예제, 응답 예제는 [Identity Routes](../routes/identity-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [프로바이더 비교](#프로바이더-비교)
+- [인증 흐름](#인증-흐름)
+- [설정](#설정)
+- [파일 구조](#파일-구조)
+- [보안 고려사항](#보안-고려사항)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+Gateway의 Identity 플러그인은 주민등록번호 기반 휴대폰 본인인증을 단일 API로 추상화합니다.
+
+- NICE / KMC / 다날 중계사 지원 (플러그가능 어댑터 패턴)
+- OAuth2 + AES/3DES 암호화, HMAC 무결성 검증
+- CI(연계정보) 기반 중복 가입 확인
+- 인증 결과 자동 마스킹 (이름, 생년월일, 전화번호)
+- 요청별 TTL 관리 및 만 시각 자동 만료
+- NICE PASS 앱 인증(`authtype: "P"`) 지원
+
+---
+
+## 프로바이더 비교
+
+| provider | driver  | 암호화 방식               | 특징                                                |
+| -------- | ------- | ------------------------- | --------------------------------------------------- |
+| NICE     | `nice`  | AES-128-CBC + HMAC-SHA256 | OAuth2 v2 API, token_val 키 유도, PASS 앱 인증 지원 |
+| KMC      | `kmc`   | 3DES-CBC                  | CP코드/URL코드 기반, 간단한 설정                    |
+| 다날     | `danal` | AES-256-CBC               | client_id/secret 기반 키 유도                       |
+
+---
+
+## 인증 흐름
+
+### NICE (기본 프로바이더)
+
+```mermaid
+sequenceDiagram
+    participant C as 클라이언트
+    participant G as Gateway
+    participant N as NICE API
+
+    C->>G: POST /api/v1/identity/request
+    G->>N: OAuth2 access_token 발급
+    N-->>G: access_token
+    G->>N: crypto token 발급
+    N-->>G: token_val, site_code, token_version_id
+    Note over G: AES-128-CBC 암호화 + HMAC-SHA256 무결성
+    G-->>C: popup_url, enc_data, token_version_id, integrity_value
+
+    C->>N: 팝업 열기 (CheckPlusSafeModel/service.cb)
+    Note over N: 사용자 본인인증 수행
+    N->>G: POST /api/v1/identity/callback (enc_data)
+    Note over G: token_val 기반 AES-128-CBC 복호화
+    G-->>C: postMessage (verified / failed)
+
+    C->>G: GET /api/v1/identity/result/:request_id
+    G-->>C: 마스킹된 인증 결과
+```
+
+### KMC / 다날
+
+기본 흐름은 동일하나, 별도 OAuth 토큰 없이 직접 암호화→팝업→콜백→복호화 과정을 거칩니다.
+
+---
+
+## 설정
+
+`configs/plugins/identity.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "nice",
+    "return_url": "/api/v1/identity/callback",
+    "success_redirect_url": "",
+    "failure_redirect_url": "",
+    "duplicate_ci_check": true,
+    "request_ttl_sec": 300,
+    "result_ttl_sec": 600,
+    "providers": {
+        "nice": {
+            "driver": "nice",
+            "site_code": "${NICE_SITE_CODE}",
+            "site_password": "${NICE_SITE_PASSWORD}",
+            "client_id": "${NICE_CLIENT_ID}",
+            "client_secret": "${NICE_CLIENT_SECRET}",
+            "product_id": "2101979031",
+            "api_url": "https://nice.checkplus.co.kr",
+            "token_url": "https://svc.niceapi.co.kr:22001/digital/niceid/oauth/oauth/token",
+            "crypto_url": "https://svc.niceapi.co.kr:22001/digital/niceid/api/v1.0/common/crypto/token"
+        },
+        "kmc": {
+            "driver": "kmc",
+            "site_code": "${KMC_SITE_CODE}",
+            "site_password": "${KMC_SITE_PASSWORD}",
+            "api_url": "https://www.kmcert.com"
+        },
+        "danal": {
+            "driver": "danal",
+            "cp_cd": "${DANAL_CP_CD}",
+            "url_cd": "${DANAL_URL_CD}",
+            "cert_key": "${DANAL_CERT_KEY}",
+            "api_url": "https://cert.danal.co.kr"
+        }
+    },
+    "rate_limit": {
+        "per_ip_per_hour": 10,
+        "per_account_per_day": 5
+    }
+}
+```
+
+### 설정 항목
+
+| 키                     | 타입    | 기본값 | 설명                                       |
+| ---------------------- | ------- | ------ | ------------------------------------------ |
+| `enabled`              | boolean | false  | 플러그인 활성화 여부                       |
+| `default`              | string  | —      | 기본 프로바이더 (`nice` / `kmc` / `danal`) |
+| `return_url`           | string  | —      | 중계사 콜백 수신 URL                       |
+| `success_redirect_url` | string  | `""`   | 인증 성공 시 리다이렉트 URL (팝업 내)      |
+| `failure_redirect_url` | string  | `""`   | 인증 실패 시 리다이렉트 URL (팝업 내)      |
+| `duplicate_ci_check`   | boolean | true   | CI 해시 기반 중복 가입 확인 활성화         |
+| `request_ttl_sec`      | number  | 300    | 인증 요청 유효 시간 (초)                   |
+| `result_ttl_sec`       | number  | 600    | 인증 결과 조회 가능 시간 (초)              |
+| `rate_limit`           | object  | —      | 요청 제한 설정                             |
+
+### NICE 프로바이더 설정
+
+| 키              | 설명                                                       |
+| --------------- | ---------------------------------------------------------- |
+| `client_id`     | NICE API OAuth2 client ID                                  |
+| `client_secret` | NICE API OAuth2 client secret                              |
+| `product_id`    | NICE 상품코드 (NICE에서 발급)                              |
+| `site_code`     | (선택) 기본 사이트코드 — 실제로는 crypto API 응답에서 사용 |
+| `api_url`       | NICE 팝업 베이스 URL                                       |
+| `token_url`     | OAuth2 토큰 발급 URL                                       |
+| `crypto_url`    | 크립토 토큰 발급 URL                                       |
+
+### KMC 프로바이더 설정
+
+| 키         | 설명                         |
+| ---------- | ---------------------------- |
+| `cp_cd`    | KMC CP 코드                  |
+| `url_cd`   | KMC URL 코드                 |
+| `cert_key` | KMC 인증서 키 (3DES 키 유도) |
+| `api_url`  | KMC 팝업 베이스 URL          |
+
+### 다날 프로바이더 설정
+
+| 키              | 설명                             |
+| --------------- | -------------------------------- |
+| `client_id`     | 다날 CP ID (AES IV 유도)         |
+| `client_secret` | 다날 client secret (AES 키 유도) |
+| `api_url`       | 다날 팝업 베이스 URL             |
+
+---
+
+## 파일 구조
+
+```
+src/app/plugins/identity/
+  index.ts          — Fastify 플러그인 등록
+  config.ts         — configs/plugins/identity.json 로더 + 환경변수 치환
+  types.ts          — 타입 정의 (상태, 목적, 입출력, 설정)
+  client.ts         — IdentityClient 인터페이스 정의
+  client-nice.ts    — NICE CheckPlus v2 어댑터
+  client-kmc.ts     — KMC 한국모바일인증 어댑터
+  client-danal.ts   — 다날 본인인증 어댑터
+  crypto.ts         — 프로바이더별 키 유도 + @system/crypto/cipher.ts re-export
+  service.ts        — 비즈니스 로직 (요청 생성, 콜백 처리, CI 중복검사, 마스킹)
+  entity-adapter.ts — Entity Server DB 연동 (인증 요청 CRUD)
+  routes.ts         — 라우트 테이블
+  handlers.ts       — API 핸들러
+```
+
+---
+
+## 보안 고려사항
+
+### 암호화 키 유도
+
+- **NICE**: `sha256(token_val)` → 앞 16B: AES key, 뒤 16B: IV
+    - HMAC 키: `sha256(token_val + "HMAC")` (32B)
+- **KMC**: `sha256(cert_key)` → 앞 24B: 3DES key, 뒤 8B: IV
+- **다날**: AES key = `sha256(client_secret)`, IV = `sha256(client_id)[:16]`
+
+### 민감 정보 처리
+
+- CI(연계정보)는 SHA-256 해시로만 저장 (`ci_hash`)
+- 클라이언트 응답 시 이름/생년월일/전화번호 자동 마스킹
+- 원문 CI는 서버 메모리에서만 처리 후 폐기
+
+### 요청 보호
+
+- IP당 시간당 / 계정당 일일 요청 제한 (rate_limit)
+- 요청 ID는 `crypto.randomBytes(32).toString("hex")` (64자 hex)
+- TTL 만료 후 자동 `expired` 처리
+
+### 환경변수
+
+모든 민감 설정값은 `${ENV_VAR}` 패턴으로 환경변수에서 주입합니다.
+
+---
+
+## 운영 팁
+
+1. **NICE PASS 인증**: `method: "pass"` 로 요청하면 `authtype: "P"` 가 자동 추가됩니다.
+2. **콜백 URL**: `return_url`은 외부에서 접근 가능한 URL이어야 합니다.
+3. **팝업 닫기**: 콜백 핸들러는 `window.opener.postMessage`로 결과를 전달한 후 자동으로 팝업을 닫습니다.
+4. **CI 중복검사**: `duplicate_ci_check: true` 시 동일 CI로 가입된 계정이 있으면 `is_duplicate: true` 가 반환됩니다.
+5. **토큰 캐시**: NICE의 `token_val`은 서비스 레이어에서 `tokenVersionId`를 키로 캐시하며, 콜백 복호화 후 자동 삭제됩니다 (일회용).