create-entity-app-server 0.0.3

package/src/app/plugins/identity/config.example.json

@@ -0,0 +1,43 @@
+{
+    "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",
+            "_comment": "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",
+            "_comment": "KMC 본인인증",
+            "site_code": "${KMC_SITE_CODE}",
+            "site_password": "${KMC_SITE_PASSWORD}",
+            "api_url": "https://www.kmcert.com"
+        },
+        "danal": {
+            "driver": "danal",
+            "_comment": "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
+    }
+}

package/src/app/plugins/identity/config.json

@@ -0,0 +1,30 @@
+{
+    "_comment": "본인인증 플러그인 — NICE 등 주민번호 없는 휴대폰 본인인증 연동. CI 중복 체크 및 결과 콜백 지원",
+    "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"
+        }
+    },
+    "rate_limit": {
+        "per_ip_per_hour": 10,
+        "per_account_per_day": 5
+    },
+    "deploy": true,
+    "minify": false
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 본인인증 설정 로더
+ * 플러그인 디렉토리의 config.json 로드 + 환경변수 치환
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { IdentityConfig, IdentityProviderConfig } from "./types/index.ts";
+
+/** 기본 설정값 */
+const DEFAULTS: Omit<IdentityConfig, "providers" | "default"> = {
+    enabled: false,
+    requestTtlSec: 300,
+    resultTtlSec: 600,
+    returnUrl: "",
+    duplicateCiCheck: true,
+    rateLimit: { perIpPerHour: 10, perAccountPerDay: 5 },
+};
+
+/** 유효한 드라이버 목록 */
+const VALID_DRIVERS = new Set(["nice", "kmc", "danal"]);
+
+/** 문자열 내 ${ENV} 패턴을 환경변수 값으로 치환한다 */
+function expandEnv(val: string | undefined): string {
+    if (!val) return "";
+    return val.replace(/\$\{([^}]+)\}/g, (_, key) => process.env[key] ?? "");
+}
+
+/** 프로바이더 설정의 모든 환경변수를 치환한다 */
+function expandProviderEnv(p: IdentityProviderConfig): IdentityProviderConfig {
+    return {
+        ...p,
+        siteCode: expandEnv(p.siteCode),
+        sitePassword: expandEnv(p.sitePassword),
+        clientId: expandEnv(p.clientId),
+        clientSecret: expandEnv(p.clientSecret),
+        productId: expandEnv(p.productId),
+        cpCd: expandEnv(p.cpCd),
+        urlCd: expandEnv(p.urlCd),
+        certKey: expandEnv(p.certKey),
+        apiUrl: expandEnv(p.apiUrl),
+        tokenUrl: expandEnv(p.tokenUrl),
+        cryptoUrl: expandEnv(p.cryptoUrl),
+    };
+}
+
+/** 설정 유효성을 검증한다 */
+function validate(cfg: IdentityConfig): void {
+    if (Object.keys(cfg.providers).length === 0) {
+        throw new Error("identity: at least one provider is required");
+    }
+    for (const [, p] of Object.entries(cfg.providers)) {
+        if (!VALID_DRIVERS.has(p.driver)) {
+            throw new Error(`identity: unsupported driver: ${p.driver}`);
+        }
+    }
+    const found = cfg.default in cfg.providers;
+    if (!found) {
+        throw new Error(
+            `identity: default provider '${cfg.default}' not found in providers list`,
+        );
+    }
+}
+
+/**
+ * 플러그인 디렉토리의 config.json을 로드한다.
+ * 파일이 없거나 enabled=false이면 null을 반환한다.
+ */
+export function loadIdentityConfig(): IdentityConfig | null {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const filePath = join(__dirname, "config.json");
+
+    if (!existsSync(filePath)) return null;
+
+    let raw: Record<string, any>;
+    try {
+        raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    } catch {
+        throw new Error(`identity: failed to parse ${filePath}`);
+    }
+
+    // enabled 확인
+    if (raw.enabled === false) return null;
+
+    const cfg: IdentityConfig = {
+        enabled: raw.enabled ?? true,
+        default: raw.default ?? "",
+        requestTtlSec: raw.request_ttl_sec ?? DEFAULTS.requestTtlSec,
+        resultTtlSec: raw.result_ttl_sec ?? DEFAULTS.resultTtlSec,
+        returnUrl: raw.return_url ?? DEFAULTS.returnUrl,
+        successRedirectUrl: raw.success_redirect_url,
+        failureRedirectUrl: raw.failure_redirect_url,
+        duplicateCiCheck: raw.duplicate_ci_check ?? DEFAULTS.duplicateCiCheck,
+        providers: Object.fromEntries(
+            Object.entries(raw.providers ?? {}).map(([name, p]) => {
+                const pRaw = p as Record<string, any>;
+                return [
+                    name,
+                    expandProviderEnv({
+                        driver: pRaw.driver ?? name,
+                        siteCode: pRaw.site_code,
+                        sitePassword: pRaw.site_password,
+                        clientId: pRaw.client_id,
+                        clientSecret: pRaw.client_secret,
+                        productId: pRaw.product_id,
+                        cpCd: pRaw.cp_cd,
+                        urlCd: pRaw.url_cd,
+                        certKey: pRaw.cert_key,
+                        apiUrl: pRaw.api_url,
+                        tokenUrl: pRaw.token_url,
+                        cryptoUrl: pRaw.crypto_url,
+                    }),
+                ];
+            }),
+        ),
+        rateLimit: {
+            perIpPerHour:
+                raw.rate_limit?.per_ip_per_hour ??
+                DEFAULTS.rateLimit.perIpPerHour,
+            perAccountPerDay:
+                raw.rate_limit?.per_account_per_day ??
+                DEFAULTS.rateLimit.perAccountPerDay,
+        },
+    };
+
+    // 기본 프로바이더 자동 설정
+    if (!cfg.default && Object.keys(cfg.providers).length > 0) {
+        cfg.default = Object.keys(cfg.providers)[0];
+    }
+    if (cfg.requestTtlSec <= 0) cfg.requestTtlSec = 300;
+    if (cfg.resultTtlSec <= 0) cfg.resultTtlSec = 600;
+    if (cfg.rateLimit.perIpPerHour <= 0) cfg.rateLimit.perIpPerHour = 10;
+    if (cfg.rateLimit.perAccountPerDay <= 0) cfg.rateLimit.perAccountPerDay = 5;
+
+    validate(cfg);
+    return cfg;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 본인인증 키 유도 유틸리티
+ *
+ * 범용 암복호화 함수는 @system/crypto/cipher.ts 를 사용한다.
+ * 여기에는 프로바이더별 키 유도 로직만 둔다.
+ */
+
+import { sha256, sha256Hex } from "@gateway/api";
+
+// system/crypto/cipher.ts 의 함수들을 re-export (기존 import 호환)
+export {
+    encryptAesCbc,
+    decryptAesCbc,
+    encrypt3DesCbc,
+    decrypt3DesCbc,
+    hmacSha256,
+} from "@gateway/api";
+
+// ── 키 유도 ──
+
+/** NICE 토큰 값에서 AES-128 키(16B)와 IV(16B)를 유도한다 */
+export function deriveNiceKeyIV(tokenVal: string): { key: Buffer; iv: Buffer } {
+    const hash = sha256(tokenVal);
+    return { key: hash.subarray(0, 16), iv: hash.subarray(16) };
+}
+
+/** KMC cert_key에서 3DES 키(24B)와 IV(8B)를 유도한다 */
+export function deriveKmcKey(certKey: string): { key: Buffer; iv: Buffer } {
+    const hash = sha256(certKey);
+    return { key: hash.subarray(0, 24), iv: hash.subarray(24, 32) };
+}
+
+/** Danal client_secret/client_id에서 AES-256 키(32B)와 IV(16B)를 유도한다 */
+export function deriveDanalKey(
+    clientSecret: string,
+    clientId: string,
+): { key: Buffer; iv: Buffer } {
+    const keyHash = sha256(clientSecret);
+    const ivHash = sha256(clientId);
+    return { key: keyHash, iv: ivHash.subarray(0, 16) };
+}
+
+/** NICE HMAC-SHA256 무결성 키를 유도한다 (sha256(tokenVal + "HMAC"), 32B) */
+export function deriveNiceHmacKey(tokenVal: string): Buffer {
+    return sha256(tokenVal + "HMAC");
+}
+
+/** CI 값을 SHA-256으로 해시한다 */
+export function hashCI(ci: string): string {
+    return sha256Hex(ci);
+}

package/src/app/plugins/identity/docs/README.md

@@ -0,0 +1,164 @@
+# 본인인증 플러그인 (Identity)
+
+NICE 휴대폰 본인인증 서비스를 연동합니다. 주민번호 없이 휴대폰 번호와 통신사 인증만으로 CI/DI를 발급받습니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [인증 흐름](#인증-흐름)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목           | 내용                                              |
+| -------------- | ------------------------------------------------- |
+| 프로바이더     | NICE 인증 (NICEid / CheckPlus)                    |
+| 인증 방식      | 팝업/리다이렉트 방식 (중계사 콜백)                |
+| CI             | 연계정보 — 개인 식별자 (서비스 간 공유 불가)      |
+| DI             | 중복가입 확인 정보                                |
+| 중복 가입 방지 | `duplicate_ci_check: true` 시 동일 CI 재가입 차단 |
+
+> 기본 비활성화(`enabled: false`) 상태입니다. NICE 계약 및 사이트코드 발급 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.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}"
+        }
+    },
+    "rate_limit": {
+        "per_ip_per_hour": 10,
+        "per_account_per_day": 5
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                             | 기본값  | 설명                                   |
+| -------------------------------- | ------- | -------------------------------------- |
+| `enabled`                        | `false` | 플러그인 활성화                        |
+| `default`                        | `nice`  | 사용할 프로바이더 키                   |
+| `return_url`                     | —       | NICE 콜백 수신 URL (서버 내부)         |
+| `success_redirect_url`           | —       | 인증 성공 후 클라이언트 리다이렉트 URL |
+| `failure_redirect_url`           | —       | 인증 실패 후 클라이언트 리다이렉트 URL |
+| `duplicate_ci_check`             | `true`  | CI 중복 가입 차단 여부                 |
+| `request_ttl_sec`                | `300`   | 인증 요청 유효 시간(초)                |
+| `result_ttl_sec`                 | `600`   | 인증 결과 보관 시간(초)                |
+| `rate_limit.per_ip_per_hour`     | `10`    | IP당 시간별 최대 요청 수               |
+| `rate_limit.per_account_per_day` | `5`     | 계정당 일별 최대 요청 수               |
+
+---
+
+## 환경변수
+
+```env
+NICE_SITE_CODE=NICE_사이트코드
+NICE_SITE_PASSWORD=NICE_사이트패스워드
+NICE_CLIENT_ID=NICE_클라이언트ID
+NICE_CLIENT_SECRET=NICE_클라이언트시크릿
+```
+
+NICE 계약 후 [NICE 개발자센터](https://developer.nicelabs.co.kr)에서 발급받습니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/identity`
+
+| 메서드 | 경로                  | 인증     | 설명                                            |
+| ------ | --------------------- | -------- | ----------------------------------------------- |
+| `POST` | `/request`            | JWT 선택 | 인증 요청 생성 — NICE 팝업용 암호화 데이터 반환 |
+| `POST` | `/callback`           |          | NICE 중계사 콜백 수신 (서버 내부용)             |
+| `GET`  | `/result/:request_id` | JWT 선택 | 인증 결과 조회                                  |
+| `POST` | `/verify-ci`          |          | CI 값으로 중복 가입 여부 확인                   |
+
+### POST /request 요청 바디
+
+```json
+{
+    "purpose": "signup"
+}
+```
+
+`purpose` 유효값: `signup`, `account_recovery`, `adult_verification`
+
+### POST /request 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "request_id": "uuid-v4",
+        "enc_data": "암호화된_요청_데이터",
+        "token_version_id": "...",
+        "integrity_value": "...",
+        "url": "https://nice.checkplus.co.kr/CheckPlusSafeModel/service.cb"
+    }
+}
+```
+
+### GET /result/:request_id 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "name": "홍길동",
+        "birth": "19900101",
+        "gender": "M",
+        "mobile": "01012345678",
+        "ci": "...",
+        "di": "..."
+    }
+}
+```
+
+---
+
+## 인증 흐름
+
+```
+1. POST /identity/request          → { enc_data, url, ... }
+2. 클라이언트에서 NICE 팝업 열기   (enc_data를 팝업 URL에 전달)
+3. 사용자 휴대폰 인증 완료
+4. NICE → POST /identity/callback  (서버로 결과 전달)
+5. GET  /identity/result/:request_id → { name, birth, ci, di, ... }
+6. 서비스 로직에서 결과 활용 (회원가입 완료, 계정 복구 등)
+```
+
+---
+
+## 운영 팁
+
+- `success_redirect_url`, `failure_redirect_url`은 실제 서비스 URL로 설정할 것
+- 결과는 `result_ttl_sec`(기본 10분) 후 자동 삭제 → 조회는 즉시 처리
+- CI는 서비스 간 공유 불가 — 동일 사용자라도 서비스별로 다른 CI 발급
+- 테스트 환경에서는 NICE 제공 테스트 사이트코드 사용

package/src/app/plugins/identity/entities/account.json

@@ -0,0 +1,27 @@
+{
+    "name": "account",
+    "description": "본인인증(identity) 플러그인 활성화 시 account 엔티티에 추가되는 필드 정의. enabled=true 시 앱서버 시작 때 entity 서버에 additive-sync 됩니다.",
+    "fields": {
+        "ci_hash": {
+            "type": "string",
+            "comment": "본인인증 CI 해시 (SHA-256, 중복가입 방지)"
+        },
+        "identity_verified": {
+            "type": "bool",
+            "default": false,
+            "comment": "본인인증 완료 여부"
+        },
+        "identity_name": {
+            "type": "string",
+            "comment": "인증된 실명"
+        },
+        "identity_birth_date": {
+            "type": "string",
+            "comment": "인증된 생년월일 (YYYYMMDD)"
+        },
+        "identity_gender": {
+            "type": "string",
+            "comment": "인증된 성별 (M/F)"
+        }
+    }
+}

package/src/app/plugins/identity/entities/identity_verification.json

@@ -0,0 +1,113 @@
+{
+    "name": "identity_verification",
+    "description": "휴대폰 본인인증 요청 및 결과 저장. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "hard_delete": false,
+    "compress": true,
+    "fields": {
+        "request_id": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "unique": true,
+            "comment": "인증 요청 고유 ID (32바이트 hex)"
+        },
+        "status": {
+            "index": true,
+            "type": ["pending", "verified", "failed", "expired"],
+            "default": "pending"
+        },
+        "purpose": {
+            "index": true,
+            "type": [
+                "signup",
+                "find_account",
+                "password_reset",
+                "adult_verify",
+                "identity_change"
+            ],
+            "required": true
+        },
+        "provider": {
+            "index": true,
+            "type": ["nice", "kmc", "danal"],
+            "required": true
+        },
+        "ci_hash": {
+            "type": "string",
+            "comment": "CI의 SHA-256 해시 (중복 조회용)"
+        },
+        "di": {
+            "type": "string",
+            "comment": "DI 원문 (암호화 저장)"
+        },
+        "name": {
+            "type": "string",
+            "comment": "인증된 실명"
+        },
+        "birth_date": {
+            "type": "string",
+            "comment": "생년월일 (YYYYMMDD)"
+        },
+        "gender": {
+            "type": "string",
+            "comment": "성별 (M/F)"
+        },
+        "carrier": {
+            "type": "string",
+            "comment": "통신사 코드"
+        },
+        "phone": {
+            "type": "string",
+            "comment": "인증 휴대폰 번호"
+        },
+        "nationality": {
+            "type": "string",
+            "comment": "내/외국인 (local/foreign)"
+        },
+        "account_seq": {
+            "type": "int",
+            "comment": "연결된 계정 seq (인증 완료 후 설정)"
+        },
+        "ip_address": {
+            "type": "string",
+            "comment": "요청 IP 주소"
+        },
+        "user_agent": {
+            "type": "string",
+            "comment": "요청 User-Agent"
+        },
+        "user_agent_platform": {
+            "type": "string",
+            "comment": "요청 User-Agent 기반 플랫폼"
+        },
+        "user_agent_device_type": {
+            "type": "string",
+            "comment": "요청 User-Agent 기반 기기 유형"
+        },
+        "user_agent_browser": {
+            "type": "string",
+            "comment": "요청 User-Agent 기반 브라우저"
+        },
+        "user_agent_browser_version": {
+            "type": "string",
+            "comment": "요청 User-Agent 기반 브라우저 버전"
+        },
+        "verified_at": {
+            "type": "string",
+            "comment": "인증 완료 시각 (RFC3339)"
+        },
+        "expires_at": {
+            "type": "string",
+            "comment": "요청 만료 시각 (RFC3339)"
+        },
+        "error_message": {
+            "type": "string",
+            "comment": "실패 시 에러 메시지"
+        },
+        "raw_response": {
+            "type": "json",
+            "comment": "중계사 원본 응답 (디버깅용, 암호화)"
+        }
+    }
+}