entity-server-client 0.2.4 → 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/hmac.ts

@@ -0,0 +1,41 @@
+// @ts-ignore
+import { sha256 } from "@noble/hashes/sha2";
+// @ts-ignore
+import { hmac } from "@noble/hashes/hmac";
+
+/**
+ * HMAC-SHA256 서명 헤더를 생성합니다.
+ *
+ * 서명 대상: `METHOD|PATH|TIMESTAMP|NONCE|BODY`
+ *
+ * @returns `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature` 헤더 객체
+ */
+export function buildHmacHeaders(
+    method: string,
+    path: string,
+    bodyBytes: Uint8Array,
+    apiKey: string,
+    hmacSecret: string,
+): Record<string, string> {
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = crypto.randomUUID();
+
+    const prefix = new TextEncoder().encode(
+        `${method}|${path}|${timestamp}|${nonce}|`,
+    );
+    const payload = new Uint8Array(prefix.length + bodyBytes.length);
+    payload.set(prefix, 0);
+    payload.set(bodyBytes, prefix.length);
+
+    const sig = hmac(sha256, new TextEncoder().encode(hmacSecret), payload);
+    const signature = [...sig]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+
+    return {
+        "X-API-Key": apiKey,
+        "X-Timestamp": timestamp,
+        "X-Nonce": nonce,
+        "X-Signature": signature,
+    };
+}

package/src/client/packet.ts

@@ -0,0 +1,100 @@
+// @ts-ignore
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+// @ts-ignore
+import { sha256 } from "@noble/hashes/sha2";
+// @ts-ignore
+import { hkdf } from "@noble/hashes/hkdf";
+
+/**
+ * 패킷 암호화 키를 유도합니다.
+ * - HMAC 모드 (`hmacSecret` 유효 시): HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+ * - JWT  모드: HKDF-SHA256(jwt_token, "entity-server:packet-encryption")
+ */
+export function derivePacketKey(hmacSecret: string, token: string): Uint8Array {
+    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:K][random_nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
+ */
+export function encryptPacket(
+    plaintext: Uint8Array,
+    key: Uint8Array,
+): Uint8Array {
+    const magicLen = 2 + (key[31] % 14);
+    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;
+}
+
+/**
+ * XChaCha20-Poly1305 패킷을 복호화해 JSON 객체로 변환합니다.
+ * 포맷: [magic:K][nonce:24][ciphertext+tag]
+ * K = 2 + key[31] % 14 (패킷 키에서 자동 파생)
+ */
+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");
+    }
+    const nonce = data.slice(magicLen, magicLen + 24);
+    const ciphertext = data.slice(magicLen + 24);
+    const cipher = xchacha20poly1305(key, nonce);
+    const plaintext = cipher.decrypt(ciphertext);
+    return JSON.parse(new TextDecoder().decode(plaintext)) as T;
+}
+
+/**
+ * 요청 바디를 파싱합니다. `application/octet-stream`이면 복호화, 그 외는 JSON 파싱합니다.
+ *
+ * @param requireEncrypted `true`이면 암호화된 요청만 허용합니다.
+ */
+export function parseRequestBody<T>(
+    body: ArrayBuffer | Uint8Array | string | T | null | undefined,
+    contentType: string,
+    requireEncrypted: boolean,
+    key: Uint8Array,
+): T {
+    const isEncrypted = contentType
+        .toLowerCase()
+        .includes("application/octet-stream");
+
+    if (requireEncrypted && !isEncrypted) {
+        throw new Error(
+            "Encrypted request required: Content-Type must be application/octet-stream",
+        );
+    }
+
+    if (isEncrypted) {
+        if (body == null) throw new Error("Encrypted request body is empty");
+        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);
+        }
+        throw new Error(
+            "Encrypted request body must be ArrayBuffer or Uint8Array",
+        );
+    }
+
+    if (body == null || body === "") return {} as T;
+    if (typeof body === "string") return JSON.parse(body) as T;
+    return body as T;
+}

package/src/client/request.ts

@@ -0,0 +1,93 @@
+import { derivePacketKey, encryptPacket, decryptPacket } from "./packet";
+import { buildHmacHeaders } from "./hmac";
+
+export interface RequestOptions {
+    baseUrl: string;
+    token: string;
+    apiKey: string;
+    hmacSecret: string;
+    encryptRequests: boolean;
+}
+
+/**
+ * Entity Server에 HTTP 요청을 보냅니다.
+ *
+ * - `encryptRequests` 활성화 시 인증된 POST 바디를 자동 암호화합니다.
+ * - 응답이 `application/octet-stream`이면 자동 복호화합니다.
+ * - JSON 응답의 `ok`가 false이면 에러를 던집니다.
+ */
+export async function entityRequest<T>(
+    opts: RequestOptions,
+    method: string,
+    path: string,
+    body?: unknown,
+    withAuth = true,
+    extraHeaders: Record<string, string> = {},
+): Promise<T> {
+    const { baseUrl, token, apiKey, hmacSecret, encryptRequests } = opts;
+    const isHmacMode = withAuth && !!(apiKey && hmacSecret);
+
+    const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        ...extraHeaders,
+    };
+    if (!isHmacMode && withAuth && token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+
+    let fetchBody: string | Uint8Array | null = null;
+    if (body != null) {
+        const shouldEncrypt =
+            encryptRequests &&
+            withAuth &&
+            (token || isHmacMode) &&
+            method !== "GET" &&
+            method !== "HEAD";
+
+        if (shouldEncrypt) {
+            const key = derivePacketKey(hmacSecret, token);
+            fetchBody = encryptPacket(
+                new TextEncoder().encode(JSON.stringify(body)),
+                key,
+            );
+            headers["Content-Type"] = "application/octet-stream";
+        } else {
+            fetchBody = JSON.stringify(body);
+        }
+    }
+
+    if (isHmacMode) {
+        const bodyBytes =
+            fetchBody instanceof Uint8Array
+                ? fetchBody
+                : typeof fetchBody === "string"
+                  ? new TextEncoder().encode(fetchBody)
+                  : new Uint8Array(0);
+        Object.assign(
+            headers,
+            buildHmacHeaders(method, path, bodyBytes, apiKey, hmacSecret),
+        );
+    }
+
+    const res = await fetch(baseUrl + path, {
+        method,
+        headers,
+        ...(fetchBody != null ? { body: fetchBody as BodyInit } : {}),
+    });
+
+    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);
+    }
+
+    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/utils.ts

@@ -0,0 +1,34 @@
+/**
+ * 환경변수를 읽습니다.
+ * - 브라우저/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>;
+    };
+    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`로 변환됩니다. */
+export function buildQuery(params: Record<string, unknown>): string {
+    return Object.entries(params)
+        .filter(([, value]) => value != null)
+        .map(
+            ([key, value]) =>
+                `${encodeURIComponent(key === "orderBy" ? "order_by" : key)}=${encodeURIComponent(String(value))}`,
+        )
+        .join("&");
+}

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) {