entity-server-client 0.2.5 → 0.2.6

package/src/client/base.ts

@@ -0,0 +1,246 @@
+import type { EntityServerClientOptions } from "../types";
+import { readEnv } from "./utils";
+import { derivePacketKey, parseRequestBody } from "./packet";
+import { entityRequest, type RequestOptions } from "./request";
+
+// mixin 헬퍼 타입
+export type GConstructor<T = object> = new (...args: any[]) => T;
+
+export class EntityServerClientBase {
+    baseUrl: string;
+    token: string;
+    apiKey: string;
+    hmacSecret: string;
+    encryptRequests: boolean;
+    activeTxId: string | null = null;
+
+    // 세션 유지 관련
+    keepSession: boolean;
+    refreshBuffer: number;
+    onTokenRefreshed?: (
+        accessToken: string,
+        expiresIn: number,
+    ) => void;
+    onSessionExpired?: (error: Error) => void;
+    _sessionRefreshToken: string | null = null;
+    _refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+    // ─── 초기화 & 설정 ────────────────────────────────────────────────────────
+
+    /**
+     * EntityServerClient 인스턴스를 생성합니다.
+     *
+     * 기본값:
+     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
+     */
+    constructor(options: EntityServerClientOptions = {}) {
+        const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
+
+        this.baseUrl = (
+            options.baseUrl ??
+            envBaseUrl ??
+            "http://localhost:47200"
+        ).replace(/\/$/, "");
+        this.token = options.token ?? "";
+        this.apiKey = options.apiKey ?? "";
+        this.hmacSecret = options.hmacSecret ?? "";
+        this.encryptRequests = options.encryptRequests ?? false;
+        this.keepSession = options.keepSession ?? false;
+        this.refreshBuffer = options.refreshBuffer ?? 60;
+        this.onTokenRefreshed = options.onTokenRefreshed;
+        this.onSessionExpired = options.onSessionExpired;
+    }
+
+    /** baseUrl, token, encryptRequests 값을 런타임에 갱신합니다. */
+    configure(options: Partial<EntityServerClientOptions>): void {
+        if (options.baseUrl) this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        if (typeof options.token === "string") this.token = options.token;
+        if (typeof options.encryptRequests === "boolean")
+            this.encryptRequests = options.encryptRequests;
+        if (typeof options.apiKey === "string") this.apiKey = options.apiKey;
+        if (typeof options.hmacSecret === "string")
+            this.hmacSecret = options.hmacSecret;
+        if (typeof options.keepSession === "boolean")
+            this.keepSession = options.keepSession;
+        if (typeof options.refreshBuffer === "number")
+            this.refreshBuffer = options.refreshBuffer;
+        if (options.onTokenRefreshed)
+            this.onTokenRefreshed = options.onTokenRefreshed;
+        if (options.onSessionExpired)
+            this.onSessionExpired = options.onSessionExpired;
+    }
+
+    /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
+    setToken(token: string): void {
+        this.token = token;
+    }
+
+    /** HMAC 인증용 API Key를 설정합니다. */
+    setApiKey(apiKey: string): void {
+        this.apiKey = apiKey;
+    }
+
+    /** HMAC 인증용 시크릿을 설정합니다. */
+    setHmacSecret(secret: string): void {
+        this.hmacSecret = secret;
+    }
+
+    /** 암호화 요청 활성화 여부를 설정합니다. */
+    setEncryptRequests(value: boolean): void {
+        this.encryptRequests = value;
+    }
+
+    // ─── 세션 유지 ────────────────────────────────────────────────────────────
+
+    /** @internal 자동 토큰 갱신 타이머를 시작합니다. */
+    _scheduleKeepSession(
+        refreshToken: string,
+        expiresIn: number,
+        refreshFn: (
+            rt: string,
+        ) => Promise<{ access_token: string; expires_in: number }>,
+    ): void {
+        this._clearRefreshTimer();
+        this._sessionRefreshToken = refreshToken;
+        const delayMs = Math.max((expiresIn - this.refreshBuffer) * 1000, 0);
+        this._refreshTimer = setTimeout(async () => {
+            if (!this._sessionRefreshToken) return;
+            try {
+                const result = await refreshFn(this._sessionRefreshToken);
+                this.onTokenRefreshed?.(result.access_token, result.expires_in);
+                this._scheduleKeepSession(
+                    this._sessionRefreshToken,
+                    result.expires_in,
+                    refreshFn,
+                );
+            } catch (err) {
+                this._clearRefreshTimer();
+                this.onSessionExpired?.(
+                    err instanceof Error ? err : new Error(String(err)),
+                );
+            }
+        }, delayMs);
+    }
+
+    /** @internal 자동 갱신 타이머를 정리합니다. */
+    _clearRefreshTimer(): void {
+        if (this._refreshTimer !== null) {
+            clearTimeout(this._refreshTimer);
+            this._refreshTimer = null;
+        }
+    }
+
+    /**
+     * 세션 유지 타이머를 중지합니다.
+     * `logout()` 호출 시 자동으로 중지되며, 직접 호출이 필요한 경우는 드뭅니다.
+     */
+    stopKeepSession(): void {
+        this._clearRefreshTimer();
+        this._sessionRefreshToken = null;
+    }
+
+    // ─── 요청 본문 파싱 ───────────────────────────────────────────────────────
+
+    /**
+     * 요청 바디를 파싱합니다.
+     * `application/octet-stream`이면 XChaCha20-Poly1305 복호화, 그 외는 JSON 파싱합니다.
+     *
+     * @param requireEncrypted `true`이면 암호화된 요청만 허용합니다.
+     */
+    readRequestBody<T = Record<string, unknown>>(
+        body: ArrayBuffer | Uint8Array | string | T | null | undefined,
+        contentType = "application/json",
+        requireEncrypted = false,
+    ): T {
+        const key = derivePacketKey(this.hmacSecret, this.token);
+        return parseRequestBody<T>(body, contentType, requireEncrypted, key);
+    }
+
+    // ─── 내부 헬퍼 ───────────────────────────────────────────────────────────
+
+    get _reqOpts(): RequestOptions {
+        return {
+            baseUrl: this.baseUrl,
+            token: this.token,
+            apiKey: this.apiKey,
+            hmacSecret: this.hmacSecret,
+            encryptRequests: this.encryptRequests,
+        };
+    }
+
+    _request<T>(
+        method: string,
+        path: string,
+        body?: unknown,
+        withAuth = true,
+        extraHeaders?: Record<string, string>,
+    ): Promise<T> {
+        return entityRequest<T>(
+            this._reqOpts,
+            method,
+            path,
+            body,
+            withAuth,
+            extraHeaders,
+        );
+    }
+
+    /** PNG/바이너리 응답을 ArrayBuffer로 반환합니다. (QR, 바코드 등) */
+    async _requestBinary(
+        method: string,
+        path: string,
+        body?: unknown,
+        withAuth = true,
+    ): Promise<ArrayBuffer> {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+        };
+        if (withAuth && this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+
+        const res = await fetch(this.baseUrl + path, {
+            method,
+            headers,
+            ...(body != null ? { body: JSON.stringify(body) } : {}),
+        });
+
+        if (!res.ok) {
+            const text = await res.text();
+            const err = new Error(`HTTP ${res.status}: ${text}`);
+            (err as { status?: number }).status = res.status;
+            throw err;
+        }
+
+        return res.arrayBuffer();
+    }
+
+    /** multipart/form-data 요청을 보냅니다. (파일 업로드 등) */
+    async _requestForm<T>(
+        method: string,
+        path: string,
+        form: FormData,
+        withAuth = true,
+    ): Promise<T> {
+        const headers: Record<string, string> = {};
+        if (withAuth && this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+
+        const res = await fetch(this.baseUrl + path, {
+            method,
+            headers,
+            body: form,
+        });
+
+        const data = await res.json();
+        if (!data.ok) {
+            const err = new Error(
+                data.message ?? `EntityServer error (HTTP ${res.status})`,
+            );
+            (err as { status?: number }).status = res.status;
+            throw err;
+        }
+        return data as T;
+    }
+}

package/src/client/packet.ts

@@ -8,34 +8,25 @@ import { hkdf } from "@noble/hashes/hkdf";
 /**
  * 패킷 암호화 키를 유도합니다.
  * - HMAC 모드 (`hmacSecret` 유효 시): HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
- * - JWT 모드: SHA-256(jwt_token)
+ * - JWT  모드: HKDF-SHA256(jwt_token, "entity-server:packet-encryption")
  */
 export function derivePacketKey(hmacSecret: string, token: string): Uint8Array {
-    if (hmacSecret) {
-        const salt = new TextEncoder().encode("entity-server:hkdf:v1");
-        const info = new TextEncoder().encode(
-            "entity-server:packet-encryption",
-        );
-        return hkdf(
-            sha256,
-            new TextEncoder().encode(hmacSecret),
-            salt,
-            info,
-            32,
-        );
-    }
-    return sha256(new TextEncoder().encode(token));
+    const ikm = hmacSecret || 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(ikm), salt, info, 32);
 }
 
 /**
  * 평문 바이트를 XChaCha20-Poly1305로 암호화합니다.
- * 포맷: [random_magic:magicLen][random_nonce:24][ciphertext+tag]
+ * 포맷: [random_magic:K][random_nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
  */
 export function encryptPacket(
     plaintext: Uint8Array,
     key: Uint8Array,
-    magicLen: number,
 ): Uint8Array {
+    const magicLen = 2 + (key[31] % 14);
     const magic = new Uint8Array(magicLen);
     const nonce = new Uint8Array(24);
     crypto.getRandomValues(magic);
@@ -51,13 +42,11 @@ export function encryptPacket(
 
 /**
  * XChaCha20-Poly1305 패킷을 복호화해 JSON 객체로 변환합니다.
- * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+ * 포맷: [magic:K][nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
  */
-export function decryptPacket<T>(
-    buffer: ArrayBuffer,
-    key: Uint8Array,
-    magicLen: number,
-): T {
+export function decryptPacket<T>(buffer: ArrayBuffer, key: Uint8Array): T {
+    const magicLen = 2 + (key[31] % 14);
     const data = new Uint8Array(buffer);
     if (data.length < magicLen + 24 + 16) {
         throw new Error("Encrypted packet too short");
@@ -79,7 +68,6 @@ export function parseRequestBody<T>(
     contentType: string,
     requireEncrypted: boolean,
     key: Uint8Array,
-    magicLen: number,
 ): T {
     const isEncrypted = contentType
         .toLowerCase()
@@ -93,14 +81,13 @@ export function parseRequestBody<T>(
 
     if (isEncrypted) {
         if (body == null) throw new Error("Encrypted request body is empty");
-        if (body instanceof ArrayBuffer)
-            return decryptPacket<T>(body, key, magicLen);
+        if (body instanceof ArrayBuffer) return decryptPacket<T>(body, key);
         if (body instanceof Uint8Array) {
             const sliced = body.buffer.slice(
                 body.byteOffset,
                 body.byteOffset + body.byteLength,
             );
-            return decryptPacket<T>(sliced as ArrayBuffer, key, magicLen);
+            return decryptPacket<T>(sliced as ArrayBuffer, key);
         }
         throw new Error(
             "Encrypted request body must be ArrayBuffer or Uint8Array",

package/src/client/request.ts

@@ -6,7 +6,6 @@ export interface RequestOptions {
     token: string;
     apiKey: string;
     hmacSecret: string;
-    packetMagicLen: number;
     encryptRequests: boolean;
 }
 
@@ -25,14 +24,7 @@ export async function entityRequest<T>(
     withAuth = true,
     extraHeaders: Record<string, string> = {},
 ): Promise<T> {
-    const {
-        baseUrl,
-        token,
-        apiKey,
-        hmacSecret,
-        packetMagicLen,
-        encryptRequests,
-    } = opts;
+    const { baseUrl, token, apiKey, hmacSecret, encryptRequests } = opts;
     const isHmacMode = withAuth && !!(apiKey && hmacSecret);
 
     const headers: Record<string, string> = {
@@ -57,7 +49,6 @@ export async function entityRequest<T>(
             fetchBody = encryptPacket(
                 new TextEncoder().encode(JSON.stringify(body)),
                 key,
-                packetMagicLen,
             );
             headers["Content-Type"] = "application/octet-stream";
         } else {
@@ -87,7 +78,7 @@ export async function entityRequest<T>(
     const contentType = res.headers.get("Content-Type") ?? "";
     if (contentType.includes("application/octet-stream")) {
         const key = derivePacketKey(hmacSecret, token);
-        return decryptPacket<T>(await res.arrayBuffer(), key, packetMagicLen);
+        return decryptPacket<T>(await res.arrayBuffer(), key);
     }
 
     const data = await res.json();

package/src/client/utils.ts

@@ -1,9 +1,25 @@
-/** Vite 환경변수(`import.meta.env`)에서 값을 읽습니다. */
+/**
+ * 환경변수를 읽습니다.
+ * - 브라우저/Vite: `import.meta.env`
+ * - Node.js: `process.env`
+ */
 export function readEnv(name: string): string | undefined {
+    // Vite / 기타 번들러 (import.meta.env)
     const meta = import.meta as unknown as {
         env?: Record<string, string | undefined>;
     };
-    return meta?.env?.[name];
+    if (meta?.env?.[name] != null) return meta.env[name];
+
+    // Node.js (process.env)
+    if (
+        typeof process !== "undefined" &&
+        process.env &&
+        process.env[name] != null
+    ) {
+        return process.env[name];
+    }
+
+    return undefined;
 }
 
 /** 쿼리 파라미터 객체를 URL 쿼리 문자열로 변환합니다. `orderBy` 키는 `order_by`로 변환됩니다. */

package/src/hooks/useEntityServer.ts

@@ -69,7 +69,6 @@ export function useEntityServer(
         singleton = true,
         tokenResolver,
         baseUrl,
-        packetMagicLen,
         token,
         resumeSession,
     } = options;
@@ -100,10 +99,10 @@ export function useEntityServer(
     const client = useMemo(() => {
         const c = singleton
             ? entityServer
-            : new EntityServerClient({ baseUrl, packetMagicLen, token });
+            : new EntityServerClient({ baseUrl, token });
 
         if (singleton) {
-            c.configure({ baseUrl, packetMagicLen, token });
+            c.configure({ baseUrl, token });
         }
 
         const resolvedToken = tokenResolver?.();
@@ -112,7 +111,7 @@ export function useEntityServer(
         }
 
         return c;
-    }, [singleton, tokenResolver, baseUrl, packetMagicLen, token]);
+    }, [singleton, tokenResolver, baseUrl, token]);
 
     const run = useCallback(async <T>(fn: () => Promise<T>): Promise<T> => {
         if (mountedRef.current) {

package/src/mixins/alimtalk.ts

@@ -0,0 +1,35 @@
+import type { AlimtalkSendRequest, FriendtalkSendRequest } from "../types";
+import type { GConstructor, EntityServerClientBase } from "../client/base";
+
+export function AlimtalkMixin<
+    TBase extends GConstructor<EntityServerClientBase>,
+>(Base: TBase) {
+    return class AlimtalkMixinClass extends Base {
+        // ─── 알림톡 / 친구톡 ─────────────────────────────────────────────────
+
+        /** 알림톡(KakaoTalk 비즈 메시지)을 발송합니다. */
+        alimtalkSend(req: AlimtalkSendRequest): Promise<{ message: string }> {
+            return this._request("POST", "/v1/alimtalk/send", req);
+        }
+
+        /** 알림톡 발송 상태를 조회합니다. */
+        alimtalkStatus(seq: number): Promise<{ ok: boolean; status: string }> {
+            return this._request("GET", `/v1/alimtalk/status/${seq}`);
+        }
+
+        /** 사용 가능한 알림톡 템플릿 목록을 조회합니다. */
+        alimtalkTemplates(): Promise<{
+            templates: Array<{ code: string; name: string; content: string }>;
+            count: number;
+        }> {
+            return this._request("GET", "/v1/alimtalk/templates");
+        }
+
+        /** 친구톡(KakaoTalk 채널 메시지)을 발송합니다. */
+        friendtalkSend(
+            req: FriendtalkSendRequest,
+        ): Promise<{ message: string }> {
+            return this._request("POST", "/v1/friendtalk/send", req);
+        }
+    };
+}