entity-server-client 0.2.5 → 0.3.0

package/src/client/base.ts

@@ -0,0 +1,305 @@
+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;
+    anonymousPacketToken: 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` 또는 상대 경로(`""`)
+     */
+    constructor(options: EntityServerClientOptions = {}) {
+        const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
+
+        this.baseUrl = (options.baseUrl ?? envBaseUrl ?? "").replace(/\/$/, "");
+        this.token = options.token ?? "";
+        this.anonymousPacketToken = options.anonymousPacketToken ?? "";
+        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 (typeof options.baseUrl === "string") {
+            this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        }
+        if (typeof options.token === "string") this.token = options.token;
+        if (typeof options.anonymousPacketToken === "string") {
+            this.anonymousPacketToken = options.anonymousPacketToken;
+        }
+        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;
+    }
+
+    /** 익명 패킷 암호화용 토큰을 설정합니다. */
+    setAnonymousPacketToken(token: string): void {
+        this.anonymousPacketToken = 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 || this.anonymousPacketToken,
+        );
+        return parseRequestBody<T>(body, contentType, requireEncrypted, key);
+    }
+
+    // ─── 내부 헬퍼 ───────────────────────────────────────────────────────────
+
+    get _reqOpts(): RequestOptions {
+        return {
+            baseUrl: this.baseUrl,
+            token: this.token,
+            anonymousPacketToken: this.anonymousPacketToken,
+            apiKey: this.apiKey,
+            hmacSecret: this.hmacSecret,
+            encryptRequests: this.encryptRequests,
+        };
+    }
+
+    requestJson<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,
+            false,
+        );
+    }
+
+    _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,
+            true,
+        );
+    }
+
+    /** 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) } : {}),
+            credentials: "include",
+        });
+
+        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,
+            credentials: "include",
+        });
+
+        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;
+    }
+
+    /** multipart/form-data 요청을 보내고 바이너리(ArrayBuffer)를 반환합니다. */
+    async _requestFormBinary(
+        method: string,
+        path: string,
+        form: FormData,
+        withAuth = true,
+    ): Promise<ArrayBuffer> {
+        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,
+            credentials: "include",
+        });
+
+        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();
+    }
+}

package/src/client/packet.ts

@@ -1,71 +1,37 @@
-// @ts-ignore
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-// @ts-ignore
-import { sha256 } from "@noble/hashes/sha2";
-// @ts-ignore
-import { hkdf } from "@noble/hashes/hkdf";
+import {
+    derivePacketKey as derivePacketKeyCore,
+    encryptPacket as encryptPacketCore,
+    decryptPacket as decryptPacketCore,
+} from "../packet";
 
 /**
  * 패킷 암호화 키를 유도합니다.
  * - 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));
+    return derivePacketKeyCore(hmacSecret || token);
 }
 
 /**
  * 평문 바이트를 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 magic = new Uint8Array(magicLen);
-    const nonce = new Uint8Array(24);
-    crypto.getRandomValues(magic);
-    crypto.getRandomValues(nonce);
-    const cipher = xchacha20poly1305(key, nonce);
-    const ciphertext = cipher.encrypt(plaintext);
-    const result = new Uint8Array(magicLen + 24 + ciphertext.length);
-    result.set(magic, 0);
-    result.set(nonce, magicLen);
-    result.set(ciphertext, magicLen + 24);
-    return result;
+    return encryptPacketCore(plaintext, key);
 }
 
 /**
  * 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 {
-    const data = new Uint8Array(buffer);
-    if (data.length < magicLen + 24 + 16) {
-        throw new Error("Encrypted packet too short");
-    }
-    const nonce = data.slice(magicLen, magicLen + 24);
-    const ciphertext = data.slice(magicLen + 24);
-    const cipher = xchacha20poly1305(key, nonce);
-    const plaintext = cipher.decrypt(ciphertext);
+export function decryptPacket<T>(buffer: ArrayBuffer, key: Uint8Array): T {
+    const plaintext = decryptPacketCore(buffer, key);
     return JSON.parse(new TextDecoder().decode(plaintext)) as T;
 }
 
@@ -79,7 +45,6 @@ export function parseRequestBody<T>(
     contentType: string,
     requireEncrypted: boolean,
     key: Uint8Array,
-    magicLen: number,
 ): T {
     const isEncrypted = contentType
         .toLowerCase()
@@ -93,14 +58,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

@@ -4,12 +4,31 @@ import { buildHmacHeaders } from "./hmac";
 export interface RequestOptions {
     baseUrl: string;
     token: string;
+    anonymousPacketToken: string;
     apiKey: string;
     hmacSecret: string;
-    packetMagicLen: number;
     encryptRequests: boolean;
 }
 
+function resolvePacketSource(opts: RequestOptions): string {
+    return opts.hmacSecret || opts.token || opts.anonymousPacketToken;
+}
+
+async function readErrorMessage(res: Response): Promise<string> {
+    const contentType = res.headers.get("Content-Type") ?? "";
+    if (contentType.includes("application/json")) {
+        const data = (await res.json().catch(() => null)) as {
+            error?: string;
+            message?: string;
+        } | null;
+        if (data?.error) return data.error;
+        if (data?.message) return data.message;
+    }
+
+    const text = await res.text().catch(() => "");
+    return text || `HTTP ${res.status}`;
+}
+
 /**
  * Entity Server에 HTTP 요청을 보냅니다.
  *
@@ -24,16 +43,18 @@ export async function entityRequest<T>(
     body?: unknown,
     withAuth = true,
     extraHeaders: Record<string, string> = {},
+    requireOkShape = true,
 ): Promise<T> {
     const {
         baseUrl,
         token,
         apiKey,
         hmacSecret,
-        packetMagicLen,
         encryptRequests,
+        anonymousPacketToken,
     } = opts;
     const isHmacMode = withAuth && !!(apiKey && hmacSecret);
+    const packetSource = resolvePacketSource(opts);
 
     const headers: Record<string, string> = {
         "Content-Type": "application/json",
@@ -47,19 +68,23 @@ export async function entityRequest<T>(
     if (body != null) {
         const shouldEncrypt =
             encryptRequests &&
-            withAuth &&
-            (token || isHmacMode) &&
+            !!packetSource &&
             method !== "GET" &&
             method !== "HEAD";
 
         if (shouldEncrypt) {
-            const key = derivePacketKey(hmacSecret, token);
+            const key = derivePacketKey(
+                hmacSecret,
+                token || anonymousPacketToken,
+            );
             fetchBody = encryptPacket(
                 new TextEncoder().encode(JSON.stringify(body)),
                 key,
-                packetMagicLen,
             );
             headers["Content-Type"] = "application/octet-stream";
+            if (!token && !isHmacMode && anonymousPacketToken) {
+                headers["X-Packet-Token"] = anonymousPacketToken;
+            }
         } else {
             fetchBody = JSON.stringify(body);
         }
@@ -82,21 +107,33 @@ export async function entityRequest<T>(
         method,
         headers,
         ...(fetchBody != null ? { body: fetchBody as BodyInit } : {}),
+        credentials: "include",
     });
 
+    if (!res.ok) {
+        const err = new Error(await readErrorMessage(res));
+        (err as { status?: number }).status = res.status;
+        throw err;
+    }
+
     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);
+        const key = derivePacketKey(hmacSecret, token || anonymousPacketToken);
+        return decryptPacket<T>(await res.arrayBuffer(), key);
+    }
+
+    if (!contentType.includes("application/json")) {
+        return (await res.text()) as T;
     }
 
     const data = await res.json();
-    if (!data.ok) {
+    if (requireOkShape && !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/utils.ts

@@ -1,9 +1,24 @@
-/** 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)
+    const _proc = (
+        globalThis as { process?: { env?: Record<string, string | undefined> } }
+    ).process;
+    if (_proc?.env?.[name] != null) {
+        return _proc.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) {