create-entity-server 0.0.15 → 0.0.25

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;
 
-  Future<Map<String, dynamic>> get(String entity, int seq) =>
-      _request('GET', '/v1/entity/$entity/$seq');
+  // ─── Health Check ──────────────────────────────────────────────
 
-  Future<Map<String, dynamic>> list(String entity, {int page = 1, int limit = 20}) =>
-      _request('GET', '/v1/entity/$entity/list?page=$page&limit=$limit');
+  /// 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+  /// 서버가 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>> count(String entity) =>
-      _request('GET', '/v1/entity/$entity/count');
+  // ─── CRUD ─────────────────────────────────────────────────────────
 
-  Future<Map<String, dynamic>> query(
+  Future<Map<String, dynamic>> get(String entity, int seq, {bool skipHooks = false}) =>
+      _request('GET', '/v1/entity/$entity/$seq${skipHooks ? "?skipHooks=true" : ""}');
+
+  /// 조건으로 단건 조회 (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);
   }
 
@@ -224,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()) {
@@ -247,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();
@@ -292,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();
   }
 }