create-entity-server 0.0.9 → 0.0.23

package/template/samples/entities/15_reset_defaults.json

@@ -0,0 +1,94 @@
+{
+    "name": "country",
+    "description": "reset_defaults 예제 — reset-all 실행 시 주요 국가 코드 자동 시딩",
+    "index": {
+        "code": {
+            "comment": "ISO 3166-1 alpha-2 국가 코드 (예: KR, US)",
+            "required": true,
+            "unique": true
+        },
+        "name_ko": {
+            "comment": "국가명 (한국어)"
+        },
+        "name_en": {
+            "comment": "국가명 (영어)"
+        },
+        "region": {
+            "comment": "대륙/지역",
+            "type": [
+                "asia",
+                "europe",
+                "americas",
+                "africa",
+                "oceania",
+                "middle_east"
+            ]
+        },
+        "phone_code": {
+            "comment": "국가 전화 코드 (예: +82)"
+        },
+        "is_active": {
+            "comment": "서비스 지원 여부 (is_* → TINYINT(1) 자동 추론)",
+            "default": true
+        }
+    },
+    "hard_delete": true,
+    "reset_defaults": [
+        {
+            "code": "KR",
+            "name_ko": "대한민국",
+            "name_en": "South Korea",
+            "region": "asia",
+            "phone_code": "+82",
+            "is_active": true
+        },
+        {
+            "code": "US",
+            "name_ko": "미국",
+            "name_en": "United States",
+            "region": "americas",
+            "phone_code": "+1",
+            "is_active": true
+        },
+        {
+            "code": "JP",
+            "name_ko": "일본",
+            "name_en": "Japan",
+            "region": "asia",
+            "phone_code": "+81",
+            "is_active": true
+        },
+        {
+            "code": "CN",
+            "name_ko": "중국",
+            "name_en": "China",
+            "region": "asia",
+            "phone_code": "+86",
+            "is_active": true
+        },
+        {
+            "code": "DE",
+            "name_ko": "독일",
+            "name_en": "Germany",
+            "region": "europe",
+            "phone_code": "+49",
+            "is_active": true
+        },
+        {
+            "code": "GB",
+            "name_ko": "영국",
+            "name_en": "United Kingdom",
+            "region": "europe",
+            "phone_code": "+44",
+            "is_active": true
+        },
+        {
+            "code": "SG",
+            "name_ko": "싱가포르",
+            "name_en": "Singapore",
+            "region": "asia",
+            "phone_code": "+65",
+            "is_active": true
+        }
+    ]
+}

package/template/samples/entities/16_isolated_license.json

@@ -0,0 +1,62 @@
+{
+    "name": "organization",
+    "description": "isolated: license 예제 — 이 엔티티가 테넌트(라이선스) 경계를 정의하는 루트 엔티티. license_seq FK 없이 license_seq 컬럼을 직접 소유",
+    "isolated": "license",
+    "index": {
+        "name": {
+            "comment": "조직명",
+            "required": true,
+            "unique": true
+        },
+        "plan": {
+            "comment": "구독 플랜",
+            "type": ["free", "starter", "pro", "enterprise"],
+            "default": "free"
+        },
+        "max_members": {
+            "comment": "최대 팀원 수",
+            "type": "uint",
+            "default": 5
+        },
+        "owner_seq": {
+            "comment": "소유자 account seq"
+        },
+        "is_active": {
+            "comment": "활성 여부 (is_* → TINYINT(1) 자동 추론)",
+            "default": true
+        },
+        "expires_at": {
+            "comment": "구독 만료일시 (*_at → DATETIME 자동 추론)"
+        }
+    },
+    "fields": {
+        "billing_email": {
+            "type": "varchar(255)",
+            "comment": "청구용 이메일"
+        },
+        "settings": {
+            "comment": "조직 설정 (중첩 fields 그룹)",
+            "fields": {
+                "theme": {
+                    "type": ["light", "dark", "system"],
+                    "comment": "기본 UI 테마",
+                    "default": "system"
+                },
+                "language": {
+                    "type": "varchar(10)",
+                    "comment": "기본 인터페이스 언어",
+                    "default": "ko"
+                },
+                "timezone": {
+                    "type": "varchar(50)",
+                    "comment": "기본 타임존",
+                    "default": "Asia/Seoul"
+                }
+            }
+        }
+    },
+    "cache": {
+        "enabled": true,
+        "ttl_seconds": 300
+    }
+}

package/template/samples/entities/README.md

@@ -0,0 +1,91 @@
+# 엔티티 설정 예제
+
+`entities/` 디렉토리에 배치하는 `.json` 설정 파일 예제 모음입니다.  
+엔티티 서버의 **모든 주요 기능을 하나씩** 알아볼 수 있도록 주제별로 구성하였습니다.
+
+> **전체 레퍼런스**: [docs/ops/entity-config-guide.md](../../docs/ops/entity-config-guide.md)  
+> **훅 가이드**: [docs/ops/hooks.md](../../docs/ops/hooks.md)
+
+---
+
+## 기능별 샘플 목록
+
+### 기본 필드 & 타입
+
+| 파일                                                     | 엔티티    | 설명                                                                                                                         |
+| -------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| [01_basic_fields.json](01_basic_fields.json)             | `contact` | 필드명 패턴으로 타입이 **자동 추론**되는 모든 케이스 (`_seq`, `_date`, `_at`, `is_*`, `_count`, `_amount`, `email`, `phone`) |
+| [02_types_and_defaults.json](02_types_and_defaults.json) | `product` | 자동 추론이 안 될 때 **`fields` 명시 선언** (`type`, `comment`, `default` 인라인) + `reset_defaults` 시딩                    |
+
+### 제약 & 참조
+
+| 파일                                                               | 엔티티        | 설명                                                                     |
+| ------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
+| [03_hash_and_unique.json](03_hash_and_unique.json)                 | `member`      | **`hash`** (민감 필드 해시 저장) + **단일 `unique`** + **복합 `unique`** |
+| [04_fk_and_composite_unique.json](04_fk_and_composite_unique.json) | `team_member` | **`fk`** 외래키 참조 + **복합 유니크** (`team_seq + user_seq`)           |
+
+### 성능 & 운영
+
+| 파일                                                               | 엔티티        | 설명                                                                      |
+| ------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------- |
+| [05_cache.json](05_cache.json)                                     | `config_item` | **`cache`** 엔티티 레벨 캐시 (`ttl_seconds: 600`)                         |
+| [06_history_and_hard_delete.json](06_history_and_hard_delete.json) | `article`     | **`history_ttl`** 수정 이력 3년 보관 + **`hard_delete: false`** 논리 삭제 |
+| [14_optimistic_lock.json](14_optimistic_lock.json)                 | `inventory`   | **`optimistic_lock`** 동시 수정 충돌 방지 (재고 등 경쟁 조건 있는 데이터) |
+
+### 데이터 격리 & 공유
+
+| 파일                                                 | 엔티티          | 설명                                                                                                              |
+| ---------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [07_license_scope.json](07_license_scope.json)       | `exchange_rate` | **`license_scope: false`** — 전 라이선스 **공용** 기준 데이터 (환율). `license_seq` 컬럼 없이 모든 테넌트가 공유  |
+| [16_isolated_license.json](16_isolated_license.json) | `organization`  | **`isolated: "license"`** — 테넌트 경계를 정의하는 루트 엔티티. `license_seq` FK 없이 직접 소유 (멀티테넌트 루트) |
+
+### 특수 모드
+
+| 파일                                             | 엔티티         | 설명                                                                             |
+| ------------------------------------------------ | -------------- | -------------------------------------------------------------------------------- |
+| [13_read_only.json](13_read_only.json)           | `activity_log` | **`read_only: true`** API로 수정 불가, 서버 내부(훅/SP)에서만 기록되는 감사 로그 |
+| [15_reset_defaults.json](15_reset_defaults.json) | `country`      | **`reset_defaults`** 대량 시딩 — `reset-all` 시 국가 코드 자동 입력              |
+
+### 훅 (Hooks)
+
+| 파일                                                     | 엔티티       | 훅 타입             | 설명                                                                            |
+| -------------------------------------------------------- | ------------ | ------------------- | ------------------------------------------------------------------------------- |
+| [08_hook_sql.json](08_hook_sql.json)                     | `user_point` | `sql`               | 실행형 SQL (포인트 이력 INSERT) + 조회형 SQL (`assign_to`로 결과 주입)          |
+| [09_hook_entity.json](09_hook_entity.json)               | `post`       | `entity`            | `after_get`/`after_list`에서 관련 엔티티 자동 주입 (작성자 프로필, 댓글)        |
+| [10_hook_submit_delete.json](10_hook_submit_delete.json) | `project`    | `submit` / `delete` | 생성 시 연관 엔티티 자동 생성(Upsert 포함), 삭제 시 연관 데이터 자동 정리       |
+| [11_hook_webhook.json](11_hook_webhook.json)             | `payment`    | `webhook`           | 외부 HTTP 통보 — 비동기(결제 생성) + 동기(상태 변경)                            |
+| [12_hook_push.json](12_hook_push.json)                   | `delivery`   | `push`              | 배송 상태 변경 시 고객 푸시 알림 (FCM / APNs 공통, 등록된 모든 디바이스로 전송) |
+
+---
+
+## 훅 타입 한눈에 보기
+
+| 훅 타입   | 핵심 필드                                  | 주요 용도                 | 샘플                         |
+| --------- | ------------------------------------------ | ------------------------- | ---------------------------- |
+| `sql`     | `query`, `params`                          | SQL 실행 또는 결과 주입   | `08_hook_sql.json`           |
+| `entity`  | `entity`, `action`, `assign_to`            | 관련 데이터 자동 로드     | `09_hook_entity.json`        |
+| `submit`  | `entity`, `data`, `match`                  | 다른 엔티티 생성/수정     | `10_hook_submit_delete.json` |
+| `delete`  | `entity`, `match`                          | 다른 엔티티 삭제          | `10_hook_submit_delete.json` |
+| `webhook` | `url`, `body`, `async`                     | 외부 HTTP 호출            | `11_hook_webhook.json`       |
+| `push`    | `target_account_seq`, `title`, `push_body` | FCM / APNs 푸시 알림 전송 | `12_hook_push.json`          |
+
+## 훅 실행 시점
+
+| 시점            | 설명                  | 주로 사용                  |
+| --------------- | --------------------- | -------------------------- |
+| `before_insert` | 데이터 삽입 전        | 유효성 검사, 값 주입       |
+| `after_insert`  | 데이터 삽입 후        | 감사 로그, 알림, 연관 생성 |
+| `before_update` | 데이터 수정 전        | 변경 검증, 권한 확인       |
+| `after_update`  | 데이터 수정 후        | 변경 이력, 상태 알림       |
+| `before_delete` | 데이터 삭제 전        | 참조 무결성 확인           |
+| `after_delete`  | 데이터 삭제 후        | 연관 데이터 정리           |
+| `after_get`     | seq로 단건 조회 후    | 관련 데이터 병합           |
+| `after_find`    | 조건으로 단건 조회 후 | 관련 데이터 병합           |
+| `after_list`    | 목록 조회 후          | 각 항목 추가 정보 주입     |
+
+## 훅 템플릿 변수
+
+| 변수           | 설명                          |
+| -------------- | ----------------------------- |
+| `${new.field}` | 삽입/수정 후 데이터의 필드 값 |
+| `${old.field}` | 수정/삭제 전 데이터의 필드 값 |

package/template/samples/flutter/lib/entity_server_client.dart

@@ -12,7 +12,6 @@
 ///   baseUrl:    'http://your-server:47200',
 ///   apiKey:     'your-api-key',
 ///   hmacSecret: 'your-hmac-secret',
-///   magicLen:   4,   // 서버 packet_magic_len 과 동일
 /// );
 /// final result = await client.list('product');
 /// ```
@@ -31,6 +30,7 @@
 /// ```
 
 import 'dart:convert';
+import 'dart:math';
 import 'dart:typed_data';
 
 import 'package:cryptography/cryptography.dart';
@@ -41,37 +41,94 @@ class EntityServerClient {
   final String baseUrl;
   final String apiKey;
   final String hmacSecret;
+  String token;
   final int magicLen;
+  /// true 이면 POST 요청 바디를 XChaCha20-Poly1305로 암호화합니다.
+  final bool encryptRequests;
 
   final _uuid = const Uuid();
   String? _activeTxId;
+  bool _packetEncryption = false;
 
   EntityServerClient({
     this.baseUrl = 'http://localhost:47200',
     this.apiKey = '',
     this.hmacSecret = '',
-    this.magicLen = 4,
+    this.token = '',
+    this.encryptRequests = false,
   });
 
-  // ─── CRUD ─────────────────────────────────────────────────────────
+  /// JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용합니다.
+  void setToken(String newToken) => token = newToken;
+
+  // ─── Health Check ──────────────────────────────────────────────
 
-  Future<Map<String, dynamic>> get(String entity, int seq) =>
-      _request('GET', '/v1/entity/$entity/$seq');
+  /// 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+  /// 서버가 packet_encryption: true 를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
+  Future<Map<String, dynamic>> checkHealth() async {
+    final uri = Uri.parse('${baseUrl.replaceAll(RegExp(r'/$'), '')}/v1/health');
+    final res = await http.get(uri);
+    final data = jsonDecode(res.body) as Map<String, dynamic>;
+    if (data['packet_encryption'] == true) {
+      _packetEncryption = true;
+    }
+    return data;
+  }
 
-  Future<Map<String, dynamic>> list(String entity, {int page = 1, int limit = 20}) =>
-      _request('GET', '/v1/entity/$entity/list?page=$page&limit=$limit');
+  // ─── CRUD ─────────────────────────────────────────────────────────
 
-  Future<Map<String, dynamic>> count(String entity) =>
-      _request('GET', '/v1/entity/$entity/count');
+  Future<Map<String, dynamic>> get(String entity, int seq, {bool skipHooks = false}) =>
+      _request('GET', '/v1/entity/$entity/$seq${skipHooks ? "?skipHooks=true" : ""}');
 
-  Future<Map<String, dynamic>> query(
+  /// 조건으로 단건 조회 (POST + conditions body)
+  ///
+  /// [conditions] 는 index/hash/unique 필드에만 사용 가능합니다.
+  /// 조건에 맞는 행이 없으면 예외가 발생합니다 (404).
+  Future<Map<String, dynamic>> find(
     String entity,
-    List<Map<String, dynamic>> filter, {
+    Map<String, dynamic> conditions, {
+    bool skipHooks = false,
+  }) =>
+      _request('POST', '/v1/entity/$entity/find${skipHooks ? "?skipHooks=true" : ""}',
+          body: conditions);
+
+  /// 목록 조회 (POST + conditions body)
+  ///
+  /// [fields] 를 미지정하면 기본적으로 인덱스 필드만 반환합니다 (가장 빠름).
+  /// 전체 필드 반환이 필요하면 `['*']` 를 지정하세요.
+  /// [conditions] 는 index/hash/unique 필드에만 사용 가능합니다.
+  Future<Map<String, dynamic>> list(
+    String entity, {
     int page = 1,
     int limit = 20,
-  }) =>
-      _request('POST', '/v1/entity/$entity/query?page=$page&limit=$limit',
-          body: filter);
+    String? orderBy,
+    List<String>? fields,
+    Map<String, dynamic>? conditions,
+  }) {
+    final qParts = <String>['page=$page', 'limit=$limit'];
+    if (orderBy != null) qParts.add('order_by=$orderBy');
+    if (fields != null && fields.isNotEmpty) qParts.add('fields=${fields.join(",")}');
+    return _request('POST', '/v1/entity/$entity/list?${qParts.join("&")}',
+        body: conditions ?? {});
+  }
+
+  /// 건수 조회
+  Future<Map<String, dynamic>> count(String entity, {Map<String, dynamic>? conditions}) =>
+      _request('POST', '/v1/entity/$entity/count', body: conditions ?? {});
+
+  /// 커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+  ///
+  /// [sql] 은 SELECT 쿼리만 허용합니다. 사용자 입력은 반드시 [params] 로 바인딩하세요.
+  Future<Map<String, dynamic>> query(
+    String entity,
+    String sql, {
+    List<dynamic>? params,
+    int? limit,
+  }) {
+    final body = <String, dynamic>{'sql': sql, 'params': params ?? []};
+    if (limit != null) body['limit'] = limit;
+    return _request('POST', '/v1/entity/$entity/query', body: body);
+  }
 
   /// 트랜잭션 시작 — 서버에 트랜잭션 큐를 등록하고 transaction_id 를 반환합니다.
   /// 이후 submit / delete 가 서버 큐에 쌓이고 transCommit() 시 일괄 처리됩니다.
@@ -103,18 +160,24 @@ class EntityServerClient {
     String entity,
     Map<String, dynamic> data, {
     String? transactionId,
+    bool skipHooks = false,
   }) {
     final txId = transactionId ?? _activeTxId;
-    return _request('POST', '/v1/entity/$entity/submit',
+    final q = skipHooks ? '?skipHooks=true' : '';
+    return _request('POST', '/v1/entity/$entity/submit$q',
         body: data,
         extraHeaders: txId != null ? {'X-Transaction-ID': txId} : null);
   }
 
+  /// 삭제. 서버는 POST /delete/:seq 로만 처리합니다.
   Future<Map<String, dynamic>> delete(String entity, int seq,
-      {String? transactionId, bool hard = false}) {
-    final q = hard ? '?hard=true' : '';
+      {String? transactionId, bool hard = false, bool skipHooks = false}) {
+    final qParts = <String>[];
+    if (hard) qParts.add('hard=true');
+    if (skipHooks) qParts.add('skipHooks=true');
+    final q = qParts.isNotEmpty ? '?${qParts.join("&")}' : '';
     final txId = transactionId ?? _activeTxId;
-    return _request('DELETE', '/v1/entity/$entity/delete/$seq$q',
+    return _request('POST', '/v1/entity/$entity/delete/$seq$q',
         extraHeaders: txId != null ? {'X-Transaction-ID': txId} : null);
   }
 
@@ -125,6 +188,97 @@ class EntityServerClient {
   Future<Map<String, dynamic>> rollback(String entity, int historySeq) =>
       _request('POST', '/v1/entity/$entity/rollback/$historySeq');
 
+  /// 푸시 발송 트리거 엔티티에 submit합니다.
+  Future<Map<String, dynamic>> push(
+    String pushEntity,
+    Map<String, dynamic> payload, {
+    String? transactionId,
+  }) =>
+      submit(pushEntity, payload, transactionId: transactionId);
+
+  /// push_log 목록 조회 헬퍼
+  Future<Map<String, dynamic>> pushLogList({int page = 1, int limit = 20}) =>
+      list('push_log', page: page, limit: limit);
+
+  /// account_device 디바이스 등록/갱신 헬퍼 (push_token 단일 필드)
+  Future<Map<String, dynamic>> registerPushDevice(
+    int accountSeq,
+    String deviceId,
+    String pushToken, {
+    String? platform,
+    String? deviceType,
+    String? browser,
+    String? browserVersion,
+    bool pushEnabled = true,
+    String? transactionId,
+  }) {
+    final payload = <String, dynamic>{
+      'id': deviceId,
+      'account_seq': accountSeq,
+      'push_token': pushToken,
+      'push_enabled': pushEnabled,
+      if (platform != null && platform.isNotEmpty) 'platform': platform,
+      if (deviceType != null && deviceType.isNotEmpty)
+        'device_type': deviceType,
+      if (browser != null && browser.isNotEmpty) 'browser': browser,
+      if (browserVersion != null && browserVersion.isNotEmpty)
+        'browser_version': browserVersion,
+    };
+    return submit('account_device', payload, transactionId: transactionId);
+  }
+
+  /// account_device.seq 기준 push_token 갱신 헬퍼
+  Future<Map<String, dynamic>> updatePushDeviceToken(
+    int deviceSeq,
+    String pushToken, {
+    bool pushEnabled = true,
+    String? transactionId,
+  }) {
+    return submit('account_device', {
+      'seq': deviceSeq,
+      'push_token': pushToken,
+      'push_enabled': pushEnabled,
+    }, transactionId: transactionId);
+  }
+
+  /// account_device.seq 기준 푸시 수신 비활성화 헬퍼
+  Future<Map<String, dynamic>> disablePushDevice(
+    int deviceSeq, {
+    String? transactionId,
+  }) {
+    return submit('account_device', {
+      'seq': deviceSeq,
+      'push_enabled': false,
+    }, transactionId: transactionId);
+  }
+
+  /// 요청 본문을 읽어 JSON으로 반환합니다.
+  /// - application/octet-stream: 암호 패킷 복호화
+  /// - 그 외: 평문 JSON 파싱
+  Future<Map<String, dynamic>> readRequestBody(
+    Uint8List rawBody, {
+    String contentType = 'application/json',
+    bool requireEncrypted = false,
+  }) async {
+    final lowered = contentType.toLowerCase();
+    final isEncrypted = lowered.contains('application/octet-stream');
+
+    if (requireEncrypted && !isEncrypted) {
+      throw Exception(
+          'Encrypted request required: Content-Type must be application/octet-stream');
+    }
+
+    if (isEncrypted) {
+      if (rawBody.isEmpty) {
+        throw Exception('Encrypted request body is empty');
+      }
+      return await _decryptPacket(rawBody);
+    }
+
+    if (rawBody.isEmpty) return {};
+    return jsonDecode(utf8.decode(rawBody)) as Map<String, dynamic>;
+  }
+
   // ─── 내부 ─────────────────────────────────────────────────────────
 
   Future<Map<String, dynamic>> _request(
@@ -133,21 +287,37 @@ class EntityServerClient {
     Object? body,
     Map<String, String>? extraHeaders,
   }) async {
-    final bodyStr = body != null ? jsonEncode(body) : '';
-    final timestamp =
-        (DateTime.now().millisecondsSinceEpoch ~/ 1000).toString();
-    final nonce = _uuid.v4();
-    final signature = await _sign(method, path, timestamp, nonce, bodyStr);
+    // 요청 바디 결정: encryptRequests 시 POST 바디를 암호화
+    Uint8List? bodyBytes;
+    String contentType = 'application/json';
+    if (body != null) {
+      final jsonBytes = Uint8List.fromList(utf8.encode(jsonEncode(body)));
+      if (encryptRequests || _packetEncryption) {
+        bodyBytes   = await _encryptPacket(jsonBytes);
+        contentType = 'application/octet-stream';
+      } else {
+        bodyBytes = jsonBytes;
+      }
+    }
+
+    final isHmacMode = apiKey.isNotEmpty && hmacSecret.isNotEmpty;
 
     final uri = Uri.parse('${baseUrl.replaceAll(RegExp(r'/$'), '')}$path');
-    final headers = <String, String>{
-      'Content-Type': 'application/json',
-      'X-API-Key': apiKey,
-      'X-Timestamp': timestamp,
-      'X-Nonce': nonce,
-      'X-Signature': signature,
-      if (extraHeaders != null) ...extraHeaders,
-    };
+    final headers = <String, String>{'Content-Type': contentType};
+
+    if (isHmacMode) {
+      final timestamp =
+          (DateTime.now().millisecondsSinceEpoch ~/ 1000).toString();
+      final nonce = _uuid.v4();
+      final signature = await _sign(method, path, timestamp, nonce, bodyBytes ?? Uint8List(0));
+      headers['X-API-Key']   = apiKey;
+      headers['X-Timestamp'] = timestamp;
+      headers['X-Nonce']     = nonce;
+      headers['X-Signature'] = signature;
+    } else if (token.isNotEmpty) {
+      headers['Authorization'] = 'Bearer $token';
+    }
+    if (extraHeaders != null) headers.addAll(extraHeaders);
 
     final http.Response res;
     switch (method.toUpperCase()) {
@@ -156,38 +326,78 @@ class EntityServerClient {
         break;
       case 'DELETE':
         res = await http.delete(uri, headers: headers,
-            body: bodyStr.isNotEmpty ? bodyStr : null);
+            body: bodyBytes != null && bodyBytes.isNotEmpty ? bodyBytes : null);
         break;
       default:
         res = await http.post(uri, headers: headers,
-            body: bodyStr.isNotEmpty ? bodyStr : null);
+            body: bodyBytes != null && bodyBytes.isNotEmpty ? bodyBytes : null);
     }
 
-    final contentType = res.headers['content-type'] ?? '';
+    final ct = res.headers['content-type'] ?? '';
 
     // 패킷 암호화 응답: application/octet-stream → 복호화
-    if (contentType.contains('application/octet-stream')) {
+    if (ct.contains('application/octet-stream')) {
       return await _decryptPacket(res.bodyBytes);
     }
 
     final data = jsonDecode(res.body) as Map<String, dynamic>;
     if (data['ok'] != true) {
-      throw Exception('EntityServer error: ${data['message']} (HTTP ${res.statusCode})');
+      throw Exception('EntityServer error: \${data['message']} (HTTP \${res.statusCode})');
     }
     return data;
   }
 
+  /// 패킷 암호화 키를 유도합니다.
+  /// - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+  /// - JWT  모드: SHA256(token)
+  Future<Uint8List> _derivePacketKey() async {
+    if (token.isNotEmpty && hmacSecret.isEmpty) {
+      final sha = Sha256();
+      final hash = await sha.hash(utf8.encode(token));
+      return Uint8List.fromList(hash.bytes);
+    }
+    final hkdf = Hkdf(hmac: Hmac.sha256(), outputLength: 32);
+    final output = await hkdf.deriveKey(
+      secretKey: SecretKey(utf8.encode(hmacSecret)),
+      nonce: utf8.encode('entity-server:hkdf:v1'),
+      info: utf8.encode('entity-server:packet-encryption'),
+    );
+    return Uint8List.fromList(await output.extractBytes());
+  }
+
+  static Uint8List _randomBytes(int count) {
+    final rng = Random.secure();
+    return Uint8List.fromList(List.generate(count, (_) => rng.nextInt(256)));
+  }
+
+  /// XChaCha20-Poly1305 패킷 암호화
+  /// 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+  /// magicLen: 2 + keyBytes[31] % 14
+  Future<Uint8List> _encryptPacket(Uint8List plaintext) async {
+    final keyBytes = await _derivePacketKey();
+    final key   = SecretKey(keyBytes);
+    final magicLen = 2 + keyBytes[31] % 14;
+    final magic = _randomBytes(magicLen);
+    final nonce = _randomBytes(24);
+
+    final algorithm = Xchacha20.poly1305Aead();
+    final secretBox = await algorithm.encrypt(plaintext, secretKey: key, nonce: nonce);
+    // 포맷: ciphertext + mac(16)
+    final cipherBytes = Uint8List.fromList([
+      ...secretBox.cipherText,
+      ...secretBox.mac.bytes,
+    ]);
+    return Uint8List.fromList([...magic, ...nonce, ...cipherBytes]);
+  }
+
   /// XChaCha20-Poly1305 패킷 복호화
   /// 포맷: [magic:magicLen][nonce:24][ciphertext+tag:...]
-  /// 키: sha256(hmac_secret)
+  /// 키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
   Future<Map<String, dynamic>> _decryptPacket(Uint8List data) async {
-    // 키 유도: sha256(hmac_secret)
-    final sha256 = Sha256();
-    final keyHash = await sha256.hash(utf8.encode(hmacSecret));
-    final key = SecretKey(keyHash.bytes);
-
+    final keyBytes = await _derivePacketKey();
+    final key = SecretKey(keyBytes);
+    final magicLen = 2 + keyBytes[31] % 14;
     final nonce = data.sublist(magicLen, magicLen + 24);
-    // ciphertext 마지막 16바이트가 Poly1305 MAC
     final ciphertextWithMac = data.sublist(magicLen + 24);
 
     final algorithm = Xchacha20.poly1305Aead();
@@ -201,18 +411,21 @@ class EntityServerClient {
     return jsonDecode(utf8.decode(plaintext)) as Map<String, dynamic>;
   }
 
-  /// HMAC-SHA256 서명
+  /// HMAC-SHA256 서명. bodyBytes 는 JSON 또는 암호화된 바이너리 모두 지원합니다.
   Future<String> _sign(
     String method,
     String path,
     String timestamp,
     String nonce,
-    String body,
+    Uint8List bodyBytes,
   ) async {
-    final payload = [method, path, timestamp, nonce, body].join('|');
     final algorithm = Hmac.sha256();
-    final key = SecretKey(utf8.encode(hmacSecret));
-    final mac = await algorithm.calculateMac(utf8.encode(payload), secretKey: key);
+    final secretKey = SecretKey(utf8.encode(hmacSecret));
+    final prefix    = utf8.encode('\$method|\$path|\$timestamp|\$nonce|');
+    final mac = await algorithm.calculateMac(
+      Uint8List.fromList([...prefix, ...bodyBytes]),
+      secretKey: secretKey,
+    );
     return mac.bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
   }
 }