create-entity-app-server 0.0.3

package/.env.example

@@ -0,0 +1,68 @@
+# Gateway Server
+NODE_ENV=development
+
+# Entity Server 연결
+ENTITY_SERVER_URL=http://127.0.0.1:47200
+ENTITY_API_KEY=your-api-key
+ENTITY_HMAC_SECRET=your-hmac-secret
+
+# JWT (Entity Server와 동일한 secret)
+JWT_SECRET=shared-jwt-secret
+
+# distance-server 프록시용 user HMAC secret
+# 미설정 시 entity-app-server는 ../distance-server/.env 를 fallback 으로 탐색합니다.
+# DISTANCE_HMAC_USER_SECRET=
+
+# DB 직접 접속 (database.json에서 환경변수 치환용)
+# --- development 그룹 ---
+DB_HOST_DEVELOPMENT=127.0.0.1
+DB_PORT_DEVELOPMENT=3306
+DB_NAME_DEVELOPMENT=mydb_dev
+DB_USER_DEVELOPMENT=root
+DB_PASSWORD_DEVELOPMENT=password
+
+# --- production 그룹 ---
+DB_HOST_PRODUCTION=db.yourdomain.com
+DB_PORT_PRODUCTION=3306
+DB_NAME_PRODUCTION=mydb
+DB_USER_PRODUCTION=mydb_user
+DB_PASSWORD_PRODUCTION=your-production-password
+
+# --- production_read 그룹 (읽기 전용 리플리카) ---
+DB_HOST_PRODUCTION_READ=db-read.yourdomain.com
+DB_PORT_PRODUCTION_READ=3306
+DB_NAME_PRODUCTION_READ=mydb
+DB_USER_PRODUCTION_READ=mydb_reader
+DB_PASSWORD_PRODUCTION_READ=your-read-password
+
+# 공휴일 API Key (data.go.kr)
+# HOLIDAY_API_KEY=
+
+# LLM API Keys
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GEMINI_API_KEY=
+
+# 알림톡 API Keys
+# ALIMTALK_API_KEY=
+# ALIMTALK_USER_ID=
+
+# PG Keys
+# TOSS_CLIENT_KEY=
+# TOSS_SECRET_KEY=
+# KAKAO_PAY_CID=
+# KAKAO_PAY_ADMIN_KEY=
+# NICE_CLIENT_KEY=
+# NICE_SECRET_KEY=
+# INICIS_MID=
+# INICIS_SIGN_KEY=
+# INICIS_IV=
+# NAVER_PAY_PARTNER_ID=
+# NAVER_PAY_CLIENT_ID=
+# NAVER_PAY_CLIENT_SECRET=
+# NAVER_PAY_CHAIN_ID=
+# PAYCO_PARTNER_ID=
+# PAYCO_PARTNER_SECRET=
+# PAYLETTER_CLIENT_ID=
+# PAYLETTER_API_KEY=
+# PAYLETTER_API_KEY_SEARCH=

package/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.env
+logs/
+*.log
+.cache/
+*.tgz
+dist.tar.gz

package/LICENSE

@@ -0,0 +1,66 @@
+Entity Server Gateway — Source Available License
+Copyright (c) 2026 KIM YOUNG JIN (ehfuse@gmail.com)
+
+────────────────────────────────────────────────────────────────
+DEFINITIONS
+────────────────────────────────────────────────────────────────
+
+"Software" means Entity Server Gateway, including all source files,
+compiled binaries (system.js, system-api.js), configuration templates,
+documentation, and scripts distributed with this repository.
+
+"Commercial Use" means any use of the Software, directly or indirectly,
+that generates revenue, including but not limited to: SaaS products,
+subscription services, consulting projects, internal business systems,
+or any deployment where the operator derives monetary benefit.
+
+"Non-Commercial Use" means personal projects, academic research,
+educational purposes, and evaluation only, with no revenue generated.
+
+────────────────────────────────────────────────────────────────
+FREE USE (Non-Commercial)
+────────────────────────────────────────────────────────────────
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this Software for Non-Commercial Use only, to:
+
+- use, copy, modify, and run the Software for personal or educational
+  purposes;
+- submit contributions back to the original repository.
+
+────────────────────────────────────────────────────────────────
+COMMERCIAL LICENSE REQUIRED
+────────────────────────────────────────────────────────────────
+
+Any Commercial Use of this Software requires a separate written
+commercial license agreement obtained from the copyright holder.
+
+To obtain a commercial license, contact: ehfuse@gmail.com
+
+Unauthorized Commercial Use is strictly prohibited.
+
+────────────────────────────────────────────────────────────────
+RESTRICTIONS (ALL USERS)
+────────────────────────────────────────────────────────────────
+
+Regardless of license type, you may NOT:
+
+- Sell, sublicense, or redistribute the Software or substantial
+  portions of it as a standalone product;
+- Remove or alter copyright notices or this license.
+
+────────────────────────────────────────────────────────────────
+PROPRIETARY COMPONENTS
+────────────────────────────────────────────────────────────────
+
+The compiled core bundles (system.js, system-api.js) are proprietary
+and distributed in binary form only. Reverse engineering, decompiling,
+or disassembling these files is prohibited.
+
+────────────────────────────────────────────────────────────────
+DISCLAIMER
+────────────────────────────────────────────────────────────────
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY DAMAGES ARISING
+FROM THE USE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# Entity Server Gateway
+
+**Entity Server** 위에서 동작하는 Fastify 기반 게이트웨이 서버입니다.  
+인증·엔티티 CRUD·파일 스토리지 등 서버 코어는 숨겨진 번들(`system.js`)로 제공되며,  
+비즈니스 로직(라우트·훅·확장모듈)은 TypeScript 소스로 직접 수정할 수 있습니다.
+
+```
+system.js       — 서버 코어
+system-api.js   — 공개 API (ok / fail / logger / entityServer)
+app/            — 여기를 자유롭게 수정하세요
+  extensions/   — 결제·LLM·알림 등 확장모듈
+  routes/       — 커스텀 API 엔드포인트
+  hooks/        — 엔티티 이벤트 훅
+configs/        — JSON 설정 파일
+```
+
+## 시작하기
+
+```bash
+npm create entity-app-server@latest my-app
+cd my-app
+npm install
+cp .env.example .env
+npm run dev
+```
+
+→ [docs/getting-started.md](docs/getting-started.md)
+
+## 문서
+
+| 문서                                          | 설명                |
+| --------------------------------------------- | ------------------- |
+| [getting-started.md](docs/getting-started.md) | 설치 및 첫 실행     |
+| [docs/README.md](docs/README.md)              | 커스터마이징 가이드 |
+| [docs/extensions/](docs/extensions/)          | 확장모듈 상세       |
+| [docs/api-routes/](docs/api-routes/)          | API 라우트 레퍼런스 |

package/bin/create.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * create-entity-app-server
+ *
+ * CRA / create-vite 와 유사한 UX 로 Entity App Server 프로젝트를 초기화합니다.
+ * Entity Server 연동, 프록시, 훅 시스템이 포함된 프로젝트가 생성됩니다.
+ *
+ * 사용법:
+ *   npx create-entity-app-server               → ./entity-app-server/ 생성
+ *   npx create-entity-app-server my-app        → ./my-app/ 생성
+ *   npm create entity-app-server my-app        → 동일
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ─── 버전 / 설정 ──────────────────────────────────────────────────────────────
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkg = JSON.parse(
+    fs.readFileSync(path.resolve(__dirname, "../package.json"), "utf8"),
+);
+const VERSION = pkg.version;
+
+const TEMPLATE_ENTRIES = [
+    "src",
+    "configs",
+    "docs",
+    "scripts",
+    ".env.example",
+    ".gitignore",
+    "README.md",
+    "tsconfig.json",
+    "tsconfig.app.json",
+];
+
+// ─── 도움말 ───────────────────────────────────────────────────────────────────
+
+function printHelp() {
+    console.log(`
+create-entity-app-server v${VERSION}
+
+Fastify + Entity Server 연동 Entity App Server 프로젝트를 생성합니다.
+스캐폴딩된 프로젝트에 비즈니스 로직(라우트, 훅)만 추가하면 됩니다.
+
+사용법:
+  npx create-entity-app-server [폴더명]
+  npm create entity-app-server [폴더명]
+
+예시:
+  npx create-entity-app-server                 # → ./entity-app-server/
+  npx create-entity-app-server my-app          # → ./my-app/
+  npx create-entity-app-server ./projects/app
+
+옵션:
+  --help, -h       이 도움말 출력
+`);
+}
+
+// ─── 헬퍼 ─────────────────────────────────────────────────────────────────────
+
+function copyDir(src, dest) {
+    if (!fs.existsSync(src)) return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory()) copyDir(s, d);
+        else fs.copyFileSync(s, d);
+    }
+}
+
+function countFiles(dir) {
+    let count = 0;
+    if (!fs.existsSync(dir)) return 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            count += countFiles(path.join(dir, entry.name));
+        } else {
+            count++;
+        }
+    }
+    return count;
+}
+
+function copyEntry(srcRoot, destRoot, entryName) {
+    const src = path.join(srcRoot, entryName);
+    const dest = path.join(destRoot, entryName);
+    if (!fs.existsSync(src)) return;
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) copyDir(src, dest);
+    else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+}
+
+function toPackageName(dirName) {
+    const normalized = path.basename(dirName).toLowerCase();
+    const sanitized = normalized
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized || "entity-app-server";
+}
+
+function buildAppPackageJson(projectName) {
+    return {
+        name: projectName,
+        version: "0.1.0",
+        private: true,
+        type: pkg.type,
+        description:
+            "Fastify app server for Entity Server — proxy, hooks, and business route scaffolding.",
+        keywords: [
+            "entity-server",
+            "entity-app-server",
+            "proxy",
+            "api-server",
+            "rest-api",
+        ],
+        homepage: "https://github.com/ehfuse/entity-app-server",
+        bugs: {
+            url: "https://github.com/ehfuse/entity-app-server/issues",
+        },
+        repository: {
+            type: "git",
+            url: "https://github.com/ehfuse/entity-app-server.git",
+        },
+        license: pkg.license,
+        scripts: pkg.scripts,
+        dependencies: pkg.dependencies,
+        optionalDependencies: pkg.optionalDependencies,
+        devDependencies: pkg.devDependencies,
+        engines: pkg.engines,
+        os: pkg.os,
+        cpu: pkg.cpu,
+    };
+}
+
+// ─── 메인 ─────────────────────────────────────────────────────────────────────
+
+function run() {
+    const argv = process.argv.slice(2);
+    const filtered = argv.filter((a) => !a.startsWith("-"));
+
+    if (argv.includes("--help") || argv.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+
+    // 대상 폴더 결정
+    const dirName = filtered[0] ?? "entity-app-server";
+    const targetDir = path.resolve(process.cwd(), dirName);
+
+    // 이미 비어있지 않은 폴더면 중단
+    if (fs.existsSync(targetDir)) {
+        const entries = fs.readdirSync(targetDir);
+        if (entries.length > 0) {
+            console.error(
+                `\n오류: '${dirName}' 폴더가 이미 존재하고 비어있지 않습니다.`,
+            );
+            console.error(`다른 이름을 사용하거나 빈 폴더를 지정하세요.\n`);
+            process.exit(1);
+        }
+    }
+
+    const packageRoot = path.resolve(__dirname, "..");
+
+    console.log(`\n  create-entity-app-server v${VERSION}`);
+    console.log(`  폴더 생성 중: ${targetDir}\n`);
+
+    // ── 템플릿 파일 복사 ───────────────────────────────────────────────────────
+
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const entryName of TEMPLATE_ENTRIES) {
+        copyEntry(packageRoot, targetDir, entryName);
+    }
+    fs.writeFileSync(
+        path.join(targetDir, "package.json"),
+        `${JSON.stringify(buildAppPackageJson(toPackageName(dirName)), null, 2)}\n`,
+        "utf8",
+    );
+
+    const fileCount = countFiles(targetDir);
+    console.log(`  ✓ ${fileCount}개 파일 복사 완료`);
+
+    // ── 완료 안내 ─────────────────────────────────────────────────────────────
+
+    const relDir = path.relative(process.cwd(), targetDir) || dirName;
+    const cdCmd = relDir !== "." ? `cd ${relDir}` : "";
+
+    console.log(`
+  ✔ Created entity-app-server in ${relDir}
+
+  ${relDir}/
+    ├── src/system/          ← 게이트웨이 코어
+    ├── src/app/             ← 비즈니스 라우트/훅/플러그인
+    ├── configs/             ← JSON 설정 파일
+    ├── scripts/             ← build/run/release 스크립트
+    ├── .env.example         ← .env 로 복사 후 설정
+    ├── package.json         ← 프로젝트별 메타데이터 생성됨
+    └── tsconfig.json
+
+  다음 단계:
+${cdCmd ? `    ${cdCmd}` : ""}
+    cp .env.example .env      # 환경변수 설정
+    vim .env                  # Entity Server URL, API Key 등 입력
+    npm install               # 의존성 설치
+    npm run dev               # 개발 서버 시작 (http://localhost:3000)
+
+  비즈니스 라우트 추가:
+    mkdir src/routes/order
+    # route.ts, service.ts, schema.ts 작성
+    # → 자동으로 /v1/api/order/* 에 등록됨
+
+  문서: https://github.com/ehfuse/entity-app-server#readme
+`);
+}
+
+run();

package/configs/cache.json

@@ -0,0 +1,7 @@
+{
+    "driver": "memory",
+    "default_ttl_seconds": 3600,
+    "memory": {
+        "max_entries": 10000
+    }
+}

package/configs/cors.json

@@ -0,0 +1,24 @@
+{
+    "enabled": true,
+    "allow_localhost": true,
+    "origins": ["http://118.217.181.36:48200"],
+    "credentials": true,
+    "allowed_headers": [
+        "Authorization",
+        "Content-Type",
+        "X-API-Key",
+        "X-Nonce",
+        "X-Packet-Token",
+        "X-Signature",
+        "X-Timestamp",
+        "x-request-id",
+        "x-csrf-token"
+    ],
+    "exposed_headers": [
+        "x-request-id",
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset"
+    ],
+    "max_age": 86400
+}

package/configs/database.json

@@ -0,0 +1,30 @@
+{
+    "default": "distance_dev",
+    "tableReadOnly": ["entity_*"],
+    "groups": {
+        "distance_dev": {
+            "driver": "mysql",
+            "host": "${DB_HOST_DISTANCE_DEV}",
+            "port": "${DB_PORT_DISTANCE_DEV}",
+            "database": "${DB_NAME_DISTANCE_DEV}",
+            "user": "${DB_USER_DISTANCE_DEV}",
+            "password": "${DB_PASSWORD_DISTANCE_DEV}",
+            "maxConnections": 10,
+            "idleTimeout": 60000,
+            "connectionTimeout": 10000,
+            "readOnly": false
+        },
+        "development": {
+            "driver": "mysql",
+            "host": "${DB_HOST_DEVELOPMENT}",
+            "port": "${DB_PORT_DEVELOPMENT}",
+            "database": "${DB_NAME_DEVELOPMENT}",
+            "user": "${DB_USER_DEVELOPMENT}",
+            "password": "${DB_PASSWORD_DEVELOPMENT}",
+            "maxConnections": 10,
+            "idleTimeout": 60000,
+            "connectionTimeout": 10000,
+            "readOnly": false
+        }
+    }
+}

package/configs/security.json

@@ -0,0 +1,45 @@
+{
+    "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", "/v1/api/alimtalk/webhook"],
+        "token_length": 32
+    },
+    "packet_encrypt": {
+        "enabled": true,
+        "skip_paths": ["/health"],
+        "require_encryption": true,
+        "info_label": "entity-server:packet-encryption",
+        "magic_min": 2,
+        "magic_range": 14
+    },
+    "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"]
+        }
+    }
+}

package/configs/server.json

@@ -0,0 +1,31 @@
+{
+    "namespace": "entity-app-server",
+    "port": 48200,
+    "host": "0.0.0.0",
+    "baseUrl": "http://localhost:48200",
+    "logging": {
+        "level": "info",
+        "logDir": "./logs",
+        "access": {
+            "enabled": true,
+            "filename": "access",
+            "frequency": "daily",
+            "maxFiles": 14,
+            "maxSize": "100m"
+        },
+        "error": {
+            "enabled": true,
+            "filename": "error",
+            "frequency": "daily",
+            "maxFiles": 30,
+            "maxSize": "50m"
+        },
+        "app": {
+            "enabled": true,
+            "filename": "app",
+            "frequency": "daily",
+            "maxFiles": 14,
+            "maxSize": "100m"
+        }
+    }
+}