create-entity-app-server 0.0.3

package/docs/scripts-guide.md

@@ -0,0 +1,310 @@
+# Gateway 스크립트 사용 가이드
+
+> `packages/entity-app-server/scripts/` 디렉터리의 스크립트 전체 사용법
+
+---
+
+## 목차
+
+| 스크립트                                 | 용도                                  |
+| ---------------------------------------- | ------------------------------------- |
+| [run.sh](#1-runsh)                       | 서버 실행 (개발/프로덕션)             |
+| [build.sh](#2-buildsh)                   | TypeScript 빌드 + dist/ 패키징        |
+| [push.sh](#3-pushsh)                     | 버전 관리 + Git push                  |
+| [release.sh](#4-releasesh)               | 빌드 + 버전업 + push (원스텝)         |
+| [entity.sh](#5-entitysh)                 | Gateway 전용 엔티티 테이블 생성       |
+| [reset-all.sh](#6-reset-allsh)           | Gateway 전용 엔티티 테이블 초기화     |
+| [gen-table-type.sh](#7-gen-table-typesh) | 엔티티 → Kysely 테이블 타입 자동 생성 |
+
+---
+
+## 공통 사항
+
+### dry-run / --apply
+
+엔티티 관련 스크립트는 **기본값이 dry-run** 입니다. 실제로 실행하려면 `--apply`를 붙이세요.
+
+```bash
+./scripts/entity.sh              # 미리보기 (실행 안 함)
+./scripts/entity.sh --apply      # 실제 실행
+```
+
+### HTTP API 의존성
+
+`entity.sh`, `reset-all.sh`는 **entity-server HTTP API**를 직접 호출합니다. `curl` 또는 `wget`이 필요하며, `.env`의 `ENTITY_SERVER_URL` + `ENTITY_API_KEY`를 사용합니다.
+
+---
+
+## 1) run.sh
+
+Gateway 서버를 실행합니다.
+
+```bash
+./scripts/run.sh        # 프로덕션 모드 (dist/system.js)
+./scripts/run.sh dev    # 개발 모드 (tsx watch)
+```
+
+| 모드     | 실행 방법                 | 사전 조건             |
+| -------- | ------------------------- | --------------------- |
+| 프로덕션 | `node dist/system.js`     | `build.sh` 실행 후    |
+| 개발     | `npm run dev` (tsx watch) | `npm install` 완료 후 |
+
+- `.env` 파일이 있으면 자동으로 환경변수를 로드합니다.
+- 프로덕션 모드에서 `dist/system.js`가 없으면 에러를 출력하고 종료합니다.
+
+---
+
+## 2) build.sh
+
+TypeScript를 컴파일하고 배포용 `dist/`를 패키징합니다.
+
+```bash
+./scripts/build.sh           # 프로덕션 빌드 + dist/ 패키징 + dist.tar.gz 생성
+./scripts/build.sh --no-tar  # tar.gz 없이 빌드만
+```
+
+### 단계별 동작
+
+| 단계            | 내용                                                                      |
+| --------------- | ------------------------------------------------------------------------- |
+| [1/4] Build     | `npm run build` → TypeScript 컴파일 → `dist/system.js`, `system-api.js`   |
+| [2/4] Package   | `src/app/` 복사, 플러그인 `config.json` ← `config.example.json` 으로 교체 |
+| [3/4] Resources | `configs/`, `entities/`, `templates/`, `scripts/`, `docs/`, `.env` 복사   |
+| [4/4] Archive   | `dist.tar.gz` 생성 (`--no-tar` 시 생략)                                   |
+
+### dist/ 포함 항목
+
+```
+dist/
+├── system.js         — 난독화 번들 (서버 코어, 수정 불가)
+├── system-api.js     — 공개 API 번들 (ok/fail/logger/entityServer 등)
+├── tsconfig.json     — @gateway/api, @app/* 경로 별칭
+├── app/              — 사용자 편집 가능한 TypeScript 소스
+│   ├── plugins/      — 플러그인 (config.json = config.example.json 내용)
+│   └── routes/       — 비즈니스 라우트 (config.json 원본 유지)
+├── configs/          — 서버·DB·CORS 설정 파일
+├── entities/         — 엔티티 스키마 JSON
+├── templates/        — 확장 템플릿
+├── scripts/          — 운영 스크립트
+├── docs/             — 문서 (design/ 제외)
+└── .env              — .env.example 복사본 (초기값)
+```
+
+---
+
+## 3) push.sh
+
+버전 번호를 올리고 Git push합니다. `package.json`의 `version` 필드를 기준으로 동작합니다.
+
+```bash
+./scripts/push.sh                    # 현재 버전 확인 + 사용법 출력
+./scripts/push.sh version patch      # x.y.Z+1 — 버그 수정
+./scripts/push.sh version minor      # x.Y+1.0 — 기능 추가
+./scripts/push.sh version major      # X+1.0.0 — 호환성 변경
+./scripts/push.sh tag                # 현재 버전으로 git tag만 생성 + push
+```
+
+### 동작 순서 (version)
+
+1. `package.json` 버전 업
+2. `git add package.json && git commit -m "chore: bump version to vX.Y.Z"`
+3. `git tag gateway-vX.Y.Z`
+4. `git push origin <현재 브랜치>`
+5. `git push origin gateway-vX.Y.Z`
+
+> 태그는 `gateway-v` 접두어를 사용합니다 (부모 서버 태그와 구분).
+
+---
+
+## 4) release.sh
+
+빌드 + 버전업 + push를 한 번에 실행합니다.
+
+```bash
+./scripts/release.sh           # patch 릴리즈 (기본값)
+./scripts/release.sh patch     # 버그 수정 릴리즈
+./scripts/release.sh minor     # 기능 추가 릴리즈
+./scripts/release.sh major     # 호환 변경 릴리즈
+```
+
+### 동작 순서
+
+1. `build.sh` 실행 (빌드 + 패키징)
+2. `push.sh version <type>` 실행 (버전업 + push)
+
+> 빠른 배포 사이클에서 사용합니다. 빌드와 push를 개별적으로 제어하려면 `build.sh` → `push.sh`를 따로 실행하세요.
+
+---
+
+## 5) entity.sh
+
+`entities/` 폴더의 JSON 스키마를 entity-server에 등록(테이블 생성)합니다.
+
+```bash
+./scripts/entity.sh                    # 전체 엔티티 dry-run
+./scripts/entity.sh --apply            # 전체 엔티티 생성 실행
+./scripts/entity.sh --entity=llm       # llm 모듈만 dry-run
+./scripts/entity.sh --entity=llm --apply   # llm 모듈만 실행
+./scripts/entity.sh --entity=ocr --apply   # ocr 모듈만
+./scripts/entity.sh --entity=pg --apply    # pg 모듈만
+```
+
+### 옵션
+
+| 옵션              | 설명                                  |
+| ----------------- | ------------------------------------- |
+| `--apply`         | 실제 등록 실행 (생략 시 dry-run)      |
+| `--dry-run`       | 대상 파일 목록만 출력 (기본값)        |
+| `--entity=<이름>` | 특정 모듈 폴더만 대상 (대소문자 무시) |
+
+### 플러그인 enabled 체크
+
+`entities/{plugin}/` 서브폴더는 `src/app/plugins/{plugin}/config.json`의 `enabled` 값과 자동 매핑됩니다.
+
+- `enabled: false` 이면 해당 플러그인의 모든 엔티티를 로그 없이 스킵
+- `config.json` 파일이 없으면 활성화 간주 (항상 등록)
+- dry-run에서는 스킵 대상을 `⏭`로 표시
+- apply 완료 시 성공 / 실패 / 스킵 카운트를 출력
+
+### 동작
+
+1. `entities/` 재귀 탐색 → `.json` 파일 목록 수집
+2. 플러그인 `config.json` `enabled` 확인 → disabled 플러그인 스킵
+3. `POST /v1/admin/{name}/create`로 각 스키마 등록
+4. 성공/실패/스킵 카운트 출력
+
+---
+
+## 6) reset-all.sh
+
+Gateway 전용 엔티티 테이블을 **드롭 후 재생성**합니다.
+
+```bash
+./scripts/reset-all.sh             # dry-run (기본값)
+./scripts/reset-all.sh --apply     # 확인 프롬프트 후 실행
+./scripts/reset-all.sh --force     # 확인 없이 즉시 실행
+```
+
+### 동작 순서
+
+1. `POST /v1/admin/reset-all` → entity-server 전체 초기화 + 새 API 키 발급
+2. `.env`에 `ENTITY_API_KEY` / `ENTITY_HMAC_SECRET` 자동 반영
+3. `entity.sh --apply` 호출 → `entities/` 전체 등록 (`enabled: false` 플러그인 스킵)
+
+### 엔티티 등록 범위
+
+`entities/` 서브폴더와 대응하는 플러그인의 `config.json`이 `enabled: true`인 것만 등록됩니다.
+
+| 모듈 | 엔티티                                          |
+| ---- | ----------------------------------------------- |
+| LLM  | `llm_conversation`, `llm_document`, `llm_usage` |
+| OCR  | `ocr_result`, `ocr_usage`                       |
+| PG   | `pg_order`, `pg_cancel`, `pg_webhook_log`       |
+
+> ⚠️ **주의**: `--apply` / `--force` 실행 시 위 엔티티의 **모든 데이터가 삭제**됩니다.
+
+---
+
+## 자주 쓰는 워크플로
+
+### 첫 설치 후 초기화
+
+```bash
+# 1. 의존성 설치
+npm install
+
+# 2. 환경변수 설정
+cp .env.example .env
+# .env에서 ENTITY_SERVER_URL, ENTITY_API_KEY 등 설정
+
+# 3. Gateway 전용 엔티티 테이블 생성
+./scripts/entity.sh --apply
+
+# 4. 개발 모드 실행
+./scripts/run.sh dev
+```
+
+### 개발 중 배포
+
+```bash
+./scripts/build.sh            # 빌드 확인
+./scripts/release.sh patch    # 빌드 + 버전업 + push
+```
+
+### 엔티티 스키마 변경 후 재적용
+
+```bash
+# 특정 모듈만
+./scripts/entity.sh --entity=llm --dry-run   # 확인
+./scripts/entity.sh --entity=llm --apply     # 적용
+
+# 전체 재생성 (데이터 초기화 포함)
+./scripts/reset-all.sh --apply
+```
+
+---
+
+## 7) gen-table-type.sh
+
+엔티티서버 메타 API를 조회하여 **Kysely 테이블 타입 정의**(TypeScript 인터페이스)를 자동 생성합니다.
+
+```bash
+./scripts/gen-table-type.sh --list                              # 엔티티 목록만 출력
+./scripts/gen-table-type.sh --entity=user                       # user 타입 생성
+./scripts/gen-table-type.sh --entity=user --dry-run             # stdout에만 출력
+./scripts/gen-table-type.sh --entity=user --entity=account      # 복수 지정
+./scripts/gen-table-type.sh --entity=user --force               # 기존 파일 덮어쓰기
+./scripts/gen-table-type.sh --all --dry-run                     # 전체 엔티티 미리보기
+```
+
+### 옵션
+
+| 옵션              | 설명                                          |
+| ----------------- | --------------------------------------------- |
+| `--list`          | 엔티티 목록만 출력 (파일 생성 안 함)          |
+| `--entity=<이름>` | 대상 엔티티 (복수 지정 가능)                  |
+| `--all`           | 전체 엔티티 대상                              |
+| `--dry-run`       | stdout에만 출력 (파일 쓰기 안 함)             |
+| `--force`         | 기존 파일 덮어쓰기 (기본: 파일 있으면 건너뜀) |
+
+### 생성 파일
+
+`src/app/database/tables/{entity}.ts` 에 아래 3개 인터페이스를 생성합니다:
+
+| 인터페이스      | 용도                                         |
+| --------------- | -------------------------------------------- |
+| `{Entity}Table` | Kysely 테이블 정의 (공통 컬럼 + 인덱스 필드) |
+| `{Entity}Data`  | data JSON blob 내 필드 타입                  |
+| `{Entity}Row`   | 전체 행 타입 (API 응답용)                    |
+
+### 필요 환경변수
+
+`.env` 파일에 아래 변수가 설정되어 있어야 합니다:
+
+| 변수                 | 설명                      |
+| -------------------- | ------------------------- |
+| `ENTITY_SERVER_URL`  | 엔티티서버 주소           |
+| `ENTITY_API_KEY`     | 엔티티서버 API 키         |
+| `ENTITY_HMAC_SECRET` | HMAC-SHA256 서명용 시크릿 |
+
+### 인증 방식
+
+엔티티서버의 HMAC 서명 인증을 사용합니다. 요청마다 `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature` 헤더를 자동 생성합니다.
+
+### 사용 예
+
+```bash
+# 1. 엔티티 목록 확인
+./scripts/gen-table-type.sh --list
+
+# 2. 미리보기
+./scripts/gen-table-type.sh --entity=user --dry-run
+
+# 3. 파일 생성
+./scripts/gen-table-type.sh --entity=user --entity=account --force
+
+# 4. 생성된 타입을 Database 인터페이스에 수동 등록
+#    → src/app/database/index.ts 에 import 추가
+```
+
+> 생성된 타입 파일은 `src/app/database/index.ts`의 `Database` 인터페이스에 수동으로 import해야 합니다.

package/docs/security.md

@@ -0,0 +1,221 @@
+# 보안 설정 가이드
+
+CORS, CSRF 방어, 패킷 암호화, 비밀번호 정책 설정 안내입니다.
+
+| 설정 파일       | 섹션                                                                             |
+| --------------- | -------------------------------------------------------------------------------- |
+| `cors.json`     | [CORS](#corsjson)                                                                |
+| `security.json` | [CSRF](#csrf), [패킷 암호화](#packet_encrypt), [비밀번호 정책](#password_policy) |
+
+---
+
+## cors.json
+
+프론트엔드 도메인의 CORS 접근을 제어합니다.  
+파일이 없으면 `http://localhost:5173` 하나만 허용합니다.
+
+### 예시
+
+```json
+{
+    "enabled": true,
+    "origins": ["http://localhost:5173", "https://app.yourdomain.com"],
+    "credentials": true,
+    "allowed_headers": [
+        "Authorization",
+        "Content-Type",
+        "x-request-id",
+        "x-csrf-token"
+    ],
+    "exposed_headers": [
+        "x-request-id",
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset"
+    ],
+    "max_age": 86400
+}
+```
+
+### 설정 항목
+
+| 항목              | 타입     | 기본값                      | 설명                                            |
+| ----------------- | -------- | --------------------------- | ----------------------------------------------- |
+| `enabled`         | boolean  | `true`                      | CORS 활성화 (`false`이면 동일 출처만 허용)      |
+| `origins`         | string[] | `["http://localhost:5173"]` | 허용할 출처 목록 — 정확한 URL 형식              |
+| `credentials`     | boolean  | `true`                      | 쿠키·Authorization 헤더 포함 요청 허용          |
+| `allowed_headers` | string[] | _(기본 CORS 헤더)_          | 클라이언트가 보낼 수 있는 추가 헤더             |
+| `exposed_headers` | string[] | _(없음)_                    | 브라우저 JS에서 읽을 수 있도록 노출할 응답 헤더 |
+| `max_age`         | number   | _(없음)_                    | preflight 캐시 시간(초) — `86400` = 24시간      |
+
+> `origins`에 와일드카드(`*`)는 지원하지 않습니다. `credentials: true`와 함께 사용할 수 없기 때문입니다.
+
+---
+
+## security.json
+
+CSRF 방어, 패킷 암호화, 비밀번호 정책을 한 파일에서 제어합니다.  
+파일이 없으면 모든 기능이 비활성화 상태로 동작합니다.
+
+### 전체 예시
+
+```json
+{
+    "csrf": { ... },
+    "packet_encrypt": { ... },
+    "password_policy": { ... }
+}
+```
+
+---
+
+## csrf
+
+### 예시
+
+```json
+{
+    "csrf": {
+        "enabled": false,
+        "cookie_name": "_csrf",
+        "header_name": "x-csrf-token",
+        "cookie_options": {
+            "http_only": true,
+            "same_site": "strict",
+            "secure": false,
+            "path": "/",
+            "max_age": 86400
+        },
+        "safe_methods": ["GET", "HEAD", "OPTIONS"],
+        "skip_paths": ["/health", "/api/v1/alimtalk/webhook"],
+        "token_length": 32
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                            | 타입     | 기본값           | 설명                                          |
+| ------------------------------- | -------- | ---------------- | --------------------------------------------- |
+| `csrf.enabled`                  | boolean  | `false`          | CSRF 방어 활성화                              |
+| `csrf.cookie_name`              | string   | `"_csrf"`        | CSRF 토큰을 담는 쿠키 이름                    |
+| `csrf.header_name`              | string   | `"x-csrf-token"` | 클라이언트가 토큰을 전달할 요청 헤더          |
+| `csrf.cookie_options.secure`    | boolean  | `false`          | HTTPS 전용 쿠키 — 운영 환경에서는 `true` 권장 |
+| `csrf.cookie_options.same_site` | string   | `"strict"`       | `"strict"` \| `"lax"` \| `"none"`             |
+| `csrf.safe_methods`             | string[] | GET/HEAD/OPTIONS | 토큰 검사를 건너뛸 HTTP 메서드                |
+| `csrf.skip_paths`               | string[] | _(없음)_         | 웹훅 등 CSRF 검사를 건너뛸 경로               |
+| `csrf.token_length`             | number   | `32`             | 생성할 토큰 바이트 길이                       |
+
+---
+
+## packet_encrypt
+
+libsodium 기반 요청/응답 페이로드 암호화입니다.
+
+### 예시
+
+```json
+{
+    "packet_encrypt": {
+        "enabled": false,
+        "skip_paths": ["/health"],
+        "require_encryption": true,
+        "info_label": "entity-server:packet-encryption",
+        "magic_min": 2,
+        "magic_range": 14
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                                | 타입     | 기본값   | 설명                                              |
+| ----------------------------------- | -------- | -------- | ------------------------------------------------- |
+| `packet_encrypt.enabled`            | boolean  | `false`  | 패킷 암호화 활성화                                |
+| `packet_encrypt.skip_paths`         | string[] | _(없음)_ | 암호화 검사를 건너뛸 경로                         |
+| `packet_encrypt.require_encryption` | boolean  | `true`   | 미암호화 요청 거부 여부 (`false`이면 평문도 허용) |
+| `packet_encrypt.info_label`         | string   | _(값)_   | 클라이언트 SDK와 맞춰야 하는 식별 레이블          |
+| `packet_encrypt.magic_min`          | number   | `2`      | 매직 바이트 최솟값 (SDK와 동일하게 유지)          |
+| `packet_encrypt.magic_range`        | number   | `14`     | 매직 바이트 범위 (SDK와 동일하게 유지)            |
+
+---
+
+## password_policy
+
+회원가입·비밀번호 변경 시 공통으로 적용되는 복잡도 규칙입니다.  
+`enabled: false`(기본)이면 길이·복잡도 검증 없이 통과합니다.
+
+앱 코드에서 `validatePassword()`를 호출하여 이 정책을 적용합니다.
+
+```ts
+import { validatePassword } from "@gateway/api";
+
+const err = validatePassword(newPassword, [user.phone, user.birthday]);
+if (err) return reply.code(400).send(fail(err));
+```
+
+### 예시
+
+```json
+{
+    "password_policy": {
+        "enabled": false,
+        "min_length": 8,
+        "max_length": 128,
+        "require_mixed_case": false,
+        "require_number": false,
+        "require_special": false,
+        "history_count": 5,
+        "forbidden_patterns": {
+            "sequential_digits": true,
+            "repeated_chars": true,
+            "keyboard_patterns": false,
+            "sequential_length": 4
+        },
+        "pii_check": {
+            "enabled": false,
+            "entity": "user",
+            "fields": ["phone", "birthday"]
+        }
+    }
+}
+```
+
+### 기본 복잡도 설정
+
+| 항목                 | 타입    | 기본값  | 설명                                              |
+| -------------------- | ------- | ------- | ------------------------------------------------- |
+| `enabled`            | boolean | `false` | 정책 활성화 — `false`이면 모든 복잡도 검사 건너뜀 |
+| `min_length`         | number  | `8`     | 최소 길이                                         |
+| `max_length`         | number  | `128`   | 최대 길이                                         |
+| `require_mixed_case` | boolean | `false` | 대문자 + 소문자 모두 포함 여부                    |
+| `require_number`     | boolean | `false` | 숫자 포함 여부                                    |
+| `require_special`    | boolean | `false` | 특수문자 포함 여부 (`!@#$%^&*` 등)                |
+| `history_count`      | number  | `5`     | 최근 N개 비밀번호 재사용 금지 (0이면 비활성)      |
+
+### forbidden_patterns — 금지 패턴
+
+| 항목                | 타입    | 기본값  | 설명                                       |
+| ------------------- | ------- | ------- | ------------------------------------------ |
+| `sequential_digits` | boolean | `true`  | 연속 숫자 금지 (예: `1234`, `9876`)        |
+| `repeated_chars`    | boolean | `true`  | 반복 문자 금지 (예: `aaaa`, `1111`)        |
+| `keyboard_patterns` | boolean | `false` | 키보드 연속 패턴 금지 (예: `qwer`, `asdf`) |
+| `sequential_length` | number  | `4`     | 위 패턴 적용 최소 연속 길이                |
+
+### pii_check — 개인정보 포함 금지
+
+| 항목      | 타입     | 기본값   | 설명                                           |
+| --------- | -------- | -------- | ---------------------------------------------- |
+| `enabled` | boolean  | `false`  | PII 포함 검사 활성화                           |
+| `entity`  | string   | `"user"` | 개인정보를 조회할 엔티티 이름                  |
+| `fields`  | string[] | —        | 검사할 필드 목록 (예: `["phone", "birthday"]`) |
+
+> `fields`에 지정한 필드값의 숫자 부분이 비밀번호에 4자 이상 포함되면 거부합니다.  
+> 예: 전화번호 `010-1234-5678` → `01012345678` → 비밀번호에 `12345678` 포함 시 거부.
+
+### 비밀번호 이력 재사용 방지
+
+`history_count > 0`이고 `enabled: true`이면, 최근 N개의 해시와 비교하여 재사용을 차단합니다.  
+이력은 `password_history` 엔티티에 저장됩니다.
+
+> `password_history` 엔티티가 없으면 이력 검사를 건너뜁니다.