create-entity-server 0.0.15 → 0.0.23

package/template/samples/node/src/EntityServerClient.js

@@ -6,9 +6,9 @@
  *
  * 환경변수:
  *   ENTITY_SERVER_URL          http://localhost:47200
- *   ENTITY_SERVER_API_KEY      your-api-key
- *   ENTITY_SERVER_HMAC_SECRET  your-hmac-secret
- *   ENTITY_SERVER_MAGIC_LEN    4  (서버 packet_magic_len 과 동일하게)
+ *   ENTITY_SERVER_API_KEY      your-api-key        (HMAC 모드)
+ *   ENTITY_SERVER_HMAC_SECRET  your-hmac-secret    (HMAC 모드)
+ *   ENTITY_SERVER_TOKEN        your-jwt-token      (JWT 모드)
  *
  * 사용 예:
  *   const es = new EntityServerClient();
@@ -27,27 +27,59 @@
  *   }
  */
 
-import { createHmac, randomUUID } from "crypto";
+import { createHmac, randomFillSync, randomUUID } from "crypto";
 import { xchacha20_poly1305 } from "@noble/ciphers/chacha";
 import { sha256 } from "@noble/hashes/sha2";
+import { hkdf } from "@noble/hashes/hkdf";
 
 export class EntityServerClient {
     #baseUrl;
     #apiKey;
     #hmacSecret;
-    #magicLen;
+    #token;
+    #encryptRequests;
+    #packetEncryption = false;
     #activeTxId = null;
 
+    /**
+     * @param {Object} [opts]
+     * @param {string}  [opts.baseUrl]         ENTITY_SERVER_URL 환경변수 또는 기본값
+     * @param {string}  [opts.apiKey]          X-API-Key 헤더값 (HMAC 모드)
+     * @param {string}  [opts.hmacSecret]      HMAC 서명 시크릿 (HMAC 모드)
+     * @param {string}  [opts.token]           JWT Bearer 토큰 (JWT 모드)
+     * @param {boolean} [opts.encryptRequests] true 이면 POST 요청 바디를 XChaCha20-Poly1305로 암호화
+     */
     constructor({
         baseUrl = process.env.ENTITY_SERVER_URL ?? "http://localhost:47200",
         apiKey = process.env.ENTITY_SERVER_API_KEY ?? "",
         hmacSecret = process.env.ENTITY_SERVER_HMAC_SECRET ?? "",
-        magicLen = Number(process.env.ENTITY_SERVER_MAGIC_LEN ?? "4"),
+        token = process.env.ENTITY_SERVER_TOKEN ?? "",
+        encryptRequests = false,
     } = {}) {
         this.#baseUrl = baseUrl.replace(/\/$/, "");
         this.#apiKey = apiKey;
         this.#hmacSecret = hmacSecret;
-        this.#magicLen = magicLen > 0 ? magicLen : 4;
+        this.#token = token;
+        this.#encryptRequests = encryptRequests;
+    }
+
+    /** JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용합니다. */
+    setToken(token) {
+        this.#token = token;
+    }
+
+    /**
+     * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+     * 서버가 packet_encryption: true 를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
+     * @returns {Promise<{ok: boolean, packet_encryption?: boolean}>}
+     */
+    async checkHealth() {
+        const res = await fetch(this.#baseUrl + "/v1/health");
+        const data = await res.json();
+        if (data.packet_encryption) {
+            this.#packetEncryption = true;
+        }
+        return data;
     }
 
     // ─── 트랜잭션 ─────────────────────────────────────────────────────────────
@@ -89,38 +121,91 @@ export class EntityServerClient {
 
     // ─── CRUD ────────────────────────────────────────────────────────────────
 
-    /** 단건 조회 */
-    get(entity, seq) {
-        return this.#request("GET", `/v1/entity/${entity}/${seq}`);
+    /**
+     * 단건 조회
+     * @param {Object} [opts]
+     * @param {boolean} [opts.skipHooks]  true 이면 after_get 훅 미실행
+     */
+    get(entity, seq, { skipHooks = false } = {}) {
+        const q = skipHooks ? "?skipHooks=true" : "";
+        return this.#request("GET", `/v1/entity/${entity}/${seq}${q}`);
     }
 
-    /** 목록 조회 */
-    list(entity, { page = 1, limit = 20, orderBy } = {}) {
-        const q = new URLSearchParams({
-            page,
-            limit,
-            ...(orderBy && { order_by: orderBy }),
-        });
-        return this.#request("GET", `/v1/entity/${entity}/list?${q}`);
+    /**
+     * 조건으로 단건 조회 (POST + conditions body)
+     *
+     * @param {string} entity      엔티티 이름
+     * @param {Object} conditions  필터 조건. index/hash/unique 필드만 사용 가능
+     * @param {Object} [opts]
+     * @param {boolean} [opts.skipHooks]  after_find 훅 미실행 여부 (기본 false)
+     */
+    find(entity, conditions, { skipHooks = false } = {}) {
+        const q = skipHooks ? "?skipHooks=true" : "";
+        return this.#request(
+            "POST",
+            `/v1/entity/${entity}/find${q}`,
+            conditions ?? {},
+        );
     }
 
-    /** 건수 조회 */
-    count(entity) {
-        return this.#request("GET", `/v1/entity/${entity}/count`);
+    /**
+     * 목록 조회 (POST + conditions body)
+     *
+     * @param {Object} [opts]
+     * @param {number}   [opts.page]        페이지 번호 (기본 1)
+     * @param {number}   [opts.limit]       페이지당 건수 (기본 20, 최대 1000)
+     * @param {string}   [opts.orderBy]     정렬 기준 필드명 (- 접두사로 내림차순)
+     * @param {string}   [opts.orderDir]    정렬 방향 ('ASC'|'DESC')
+     * @param {string[]} [opts.fields]      반환 필드 목록. 미지정 시 인덱스 필드만 반환 (기본, 가장 빠름). '*' 지정 시 전체 필드 반환
+     * @param {Object}   [opts.conditions]  필터 조건. index/hash/unique 필드만 사용 가능
+     */
+    list(
+        entity,
+        { page = 1, limit = 20, orderBy, orderDir, fields, conditions } = {},
+    ) {
+        const qParams = { page, limit };
+        if (orderBy)
+            qParams.order_by = orderDir === "DESC" ? `-${orderBy}` : orderBy;
+        if (fields?.length) qParams.fields = fields.join(",");
+        const q = new URLSearchParams(qParams);
+        return this.#request(
+            "POST",
+            `/v1/entity/${entity}/list?${q}`,
+            conditions ?? {},
+        );
     }
 
     /**
-     * 필터 검색
-     * @param {Array}  filter  예: [{ field: 'status', op: 'eq', value: 'active' }]
-     * @param {Object} params  예: { page: 1, limit: 20, orderBy: 'name' }
+     * 건수 조회
+     * @param {Object} [conditions]  필터 조건 (list() 와 동일 규칙)
      */
-    query(entity, filter = [], { page = 1, limit = 20, orderBy } = {}) {
-        const q = new URLSearchParams({
-            page,
-            limit,
-            ...(orderBy && { order_by: orderBy }),
-        });
-        return this.#request("POST", `/v1/entity/${entity}/query?${q}`, filter);
+    count(entity, conditions) {
+        return this.#request(
+            "POST",
+            `/v1/entity/${entity}/count`,
+            conditions ?? {},
+        );
+    }
+
+    /**
+     * 커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+     *
+     * @param {Object}   req
+     * @param {string}   req.sql      SELECT SQL문. 사용자 입력은 반드시 params 로 바인딩 (SQL Injection 방지)
+     * @param {Array}    [req.params] ? 플레이스홀더 바인딩 값
+     * @param {number}   [req.limit]  최대 반환 건수 (최대 1000)
+     *
+     * @example
+     * es.query('order', {
+     *   sql: 'SELECT o.seq, u.name FROM order o JOIN account u ON u.data_seq = o.account_seq WHERE o.status = ?',
+     *   params: ['pending'],
+     *   limit: 100,
+     * });
+     */
+    query(entity, { sql, params = [], limit } = {}) {
+        const body = { sql, params };
+        if (limit != null) body.limit = limit;
+        return this.#request("POST", `/v1/entity/${entity}/query`, body);
     }
 
     /**
@@ -131,12 +216,13 @@ export class EntityServerClient {
      * @param {Object} [opts]
      * @param {string} [opts.transactionId]  transStart() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
      */
-    submit(entity, data, { transactionId } = {}) {
+    submit(entity, data, { transactionId, skipHooks = false } = {}) {
         const txId = transactionId ?? this.#activeTxId;
         const extra = txId ? { "X-Transaction-ID": txId } : {};
+        const q = skipHooks ? "?skipHooks=true" : "";
         return this.#request(
             "POST",
-            `/v1/entity/${entity}/submit`,
+            `/v1/entity/${entity}/submit${q}`,
             data,
             extra,
         );
@@ -150,12 +236,19 @@ export class EntityServerClient {
      * @param {string} [opts.transactionId]  transStart() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
      * @param {boolean} [opts.hard]           하드 삭제 여부 (기본 false)
      */
-    delete(entity, seq, { transactionId, hard = false } = {}) {
-        const q = hard ? "?hard=true" : "";
+    delete(
+        entity,
+        seq,
+        { transactionId, hard = false, skipHooks = false } = {},
+    ) {
+        const params = new URLSearchParams();
+        if (hard) params.set("hard", "true");
+        if (skipHooks) params.set("skipHooks", "true");
+        const q = params.size ? `?${params}` : "";
         const txId = transactionId ?? this.#activeTxId;
         const extra = txId ? { "X-Transaction-ID": txId } : {};
         return this.#request(
-            "DELETE",
+            "POST",
             `/v1/entity/${entity}/delete/${seq}${q}`,
             null,
             extra,
@@ -297,24 +390,51 @@ export class EntityServerClient {
     // ─── 내부 ─────────────────────────────────────────────────────────────────
 
     async #request(method, path, body, extraHeaders = {}) {
-        const bodyStr = body != null ? JSON.stringify(body) : "";
-        const timestamp = String(Math.floor(Date.now() / 1000));
-        const nonce = randomUUID();
-        const signature = this.#sign(method, path, timestamp, nonce, bodyStr);
-
-        const headers = {
-            "Content-Type": "application/json",
-            "X-API-Key": this.#apiKey,
-            "X-Timestamp": timestamp,
-            "X-Nonce": nonce,
-            "X-Signature": signature,
-            ...extraHeaders,
-        };
+        // 요청 바디 결정: encryptRequests 시 POST 바디를 암호화합니다.
+        let bodyData = null; // string | Buffer | null
+        if (body != null) {
+            if (this.#encryptRequests || this.#packetEncryption) {
+                const plaintext = Buffer.from(JSON.stringify(body));
+                bodyData = this.#encryptPacket(plaintext); // Buffer
+            } else {
+                bodyData = JSON.stringify(body);
+            }
+        }
+
+        const isHmacMode = !!(this.#apiKey && this.#hmacSecret);
+
+        const contentType =
+            (this.#encryptRequests || this.#packetEncryption) &&
+            bodyData instanceof Buffer
+                ? "application/octet-stream"
+                : "application/json";
+
+        const headers = { "Content-Type": contentType };
+
+        if (isHmacMode) {
+            const timestamp = String(Math.floor(Date.now() / 1000));
+            const nonce = randomUUID();
+            const signature = this.#sign(
+                method,
+                path,
+                timestamp,
+                nonce,
+                bodyData ?? "",
+            );
+            headers["X-API-Key"] = this.#apiKey;
+            headers["X-Timestamp"] = timestamp;
+            headers["X-Nonce"] = nonce;
+            headers["X-Signature"] = signature;
+        } else if (this.#token) {
+            headers["Authorization"] = `Bearer ${this.#token}`;
+        }
+
+        Object.assign(headers, extraHeaders);
 
         const res = await fetch(this.#baseUrl + path, {
             method,
             headers,
-            ...(bodyStr ? { body: bodyStr } : {}),
+            ...(bodyData != null ? { body: bodyData } : {}),
         });
 
         const contentType = res.headers.get("Content-Type") ?? "";
@@ -335,27 +455,80 @@ export class EntityServerClient {
         return data;
     }
 
+    /**
+     * 패킷 암호화 키를 유도합니다.
+     * - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+     * - JWT  모드: SHA256(token)
+     */
+    #derivePacketKey() {
+        if (this.#token && !this.#hmacSecret) {
+            return sha256(new TextEncoder().encode(this.#token));
+        }
+        const salt = new TextEncoder().encode("entity-server:hkdf:v1");
+        const info = new TextEncoder().encode(
+            "entity-server:packet-encryption",
+        );
+        return hkdf(
+            sha256,
+            new TextEncoder().encode(this.#hmacSecret),
+            salt,
+            info,
+            32,
+        );
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 암호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     * magicLen: 패킷 키의 마지막 바이트에서 파생 (2 + key[31] % 14)
+     * @param {Buffer} plaintext
+     * @returns {Buffer}
+     */
+    #encryptPacket(plaintext) {
+        const key = this.#derivePacketKey();
+        const magicLen = 2 + (key[31] % 14);
+        const magic = Buffer.allocUnsafe(magicLen);
+        const nonce = Buffer.allocUnsafe(24);
+        randomFillSync(magic);
+        randomFillSync(nonce);
+        const cipher = xchacha20_poly1305(key, nonce);
+        const ciphertext = cipher.encrypt(
+            plaintext instanceof Uint8Array
+                ? plaintext
+                : new Uint8Array(plaintext),
+        );
+        return Buffer.concat([magic, nonce, Buffer.from(ciphertext)]);
+    }
+
     /**
      * XChaCha20-Poly1305 패킷 복호화
      * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
-     * 키: sha256(hmac_secret)
+     * 키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
      */
     #decryptPacket(buffer) {
-        const key = sha256(new TextEncoder().encode(this.#hmacSecret));
+        const key = this.#derivePacketKey();
+        const magicLen = 2 + (key[31] % 14);
         const data = new Uint8Array(buffer);
-        const nonce = data.slice(this.#magicLen, this.#magicLen + 24);
-        const ciphertext = data.slice(this.#magicLen + 24);
+        const nonce = data.slice(magicLen, magicLen + 24);
+        const ciphertext = data.slice(magicLen + 24);
         const cipher = xchacha20_poly1305(key, nonce);
         const plaintext = cipher.decrypt(ciphertext);
         return JSON.parse(new TextDecoder().decode(plaintext));
     }
 
-    /** HMAC-SHA256 서명 */
+    /**
+     * HMAC-SHA256 서명
+     * body 는 문자열(JSON) 또는 Buffer(암호화된 바디) 모두 지원합니다.
+     */
     #sign(method, path, timestamp, nonce, body) {
-        const payload = [method, path, timestamp, nonce, body].join("|");
-        return createHmac("sha256", this.#hmacSecret)
-            .update(payload)
-            .digest("hex");
+        const mac = createHmac("sha256", this.#hmacSecret);
+        const prefix = `${method}|${path}|${timestamp}|${nonce}|`;
+        mac.update(prefix);
+        if (body != null && body !== "") {
+            // Buffer(binary) 또는 string 모두 처리 — Go 서버의 string(c.Body()) 와 동일한 바이트
+            mac.update(typeof body === "string" ? body : Buffer.from(body));
+        }
+        return mac.digest("hex");
     }
 }
 

package/template/samples/node/src/example.js

@@ -8,7 +8,7 @@ const es = new EntityServerClient({
 
 // 목록 조회
 const list = await es.list("product", { page: 1, limit: 10 });
-console.log("List:", list.data?.length, "items");
+console.log("List:", list.data?.total, "items");
 
 // 생성
 const created = await es.submit("product", {
@@ -22,17 +22,17 @@ console.log("Created seq:", created.seq);
 await es.submit("product", { seq: created.seq, price: 79000 });
 console.log("Updated");
 
-// 필터 검색
-const results = await es.query(
-    "product",
-    [{ field: "category", op: "eq", value: "peripherals" }],
-    { page: 1, limit: 5 },
-);
-console.log("Query results:", results.data?.length);
+// 커스텀 SQL 검색
+const results = await es.query("product", {
+    sql: "SELECT seq, name, category FROM product WHERE category = ?",
+    params: ["peripherals"],
+    limit: 5,
+});
+console.log("Query results:", results.data?.items?.length);
 
 // 이력 조회
 const hist = await es.history("product", created.seq);
-console.log("History count:", hist.data?.length);
+console.log("History count:", hist.data?.items?.length);
 
 // 삭제
 await es.delete("product", created.seq);

package/template/samples/php/ci4/Config/EntityServer.php

@@ -10,6 +10,5 @@ class EntityServer extends BaseConfig
     public string $apiKey = '';
     public string $hmacSecret = '';
     public int $timeout = 10;
-    public int $magicLen = 4;
     public bool $requireEncryptedRequest = true;
 }