sonamu 0.11.13 → 0.11.15

package/dist/ui-web/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/sonamu-ui/setting.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{projectName}}: Sonamu UI</title>
-    <script type="module" crossorigin src="/sonamu-ui/assets/index-ClxAM2Lk.js"></script>
+    <script type="module" crossorigin src="/sonamu-ui/assets/index-LpE8u19O.js"></script>
     <link rel="stylesheet" crossorigin href="/sonamu-ui/assets/index-BMdIyKXS.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonamu",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "Sonamu — TypeScript Fullstack API Framework",
   "keywords": [
     "framework",

package/src/api/__tests__/sonamu.plugins.test.ts

@@ -0,0 +1,211 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { request } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
+
+import { type FastifyInstance } from "fastify";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { type SonamuFastifyConfig } from "../../types/types";
+import { isNumberValue, isObjectValue } from "../../utils/runtime-value";
+import { type SonamuConfig, type SonamuServerOptions } from "../config";
+import { type Context } from "../context";
+import { type ExtendedApi } from "../decorators";
+import { Sonamu } from "../sonamu";
+
+const LARGE_VALUE = "sonamu-compress-".repeat(1024);
+
+type HttpResponse = {
+  statusCode: number | undefined;
+  headers: import("node:http").IncomingHttpHeaders;
+  body: Buffer;
+};
+
+type SonamuWithBoot = typeof Sonamu & {
+  boot(server: FastifyInstance, options: SonamuServerOptions): Promise<void>;
+};
+
+const sonamuWithBoot =
+  /* SAFETY: 테스트에서 프로세스 시그널을 등록하는 private boot만 격리합니다. */ Sonamu as SonamuWithBoot;
+
+function createApi(methodName: string, options: ExtendedApi["options"] = {}): ExtendedApi {
+  return {
+    modelName: "PayloadModel",
+    methodName,
+    path: `/payload/${methodName}`,
+    options: {
+      httpMethod: "GET",
+      contentType: "application/json",
+      ...options,
+    },
+    typeParameters: [],
+    parameters: [],
+    returnType: "unknown",
+  };
+}
+
+const apis: ExtendedApi[] = [
+  createApi("large"),
+  createApi("largeWithoutCompression", { compress: false }),
+];
+
+const apiConfig: SonamuFastifyConfig = {
+  contextProvider(defaultContext) {
+    return /* SAFETY: 실제 HTTP 요청에서 생성된 기본 컨텍스트를 변경하지 않고 사용합니다. */ defaultContext as Context;
+  },
+  guardHandler() {},
+};
+
+function requestServer(
+  server: FastifyInstance,
+  options: {
+    path: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+): Promise<HttpResponse> {
+  const address = server.server.address();
+  if (!isObjectValue(address) || !("port" in address) || !isNumberValue(address.port)) {
+    throw new Error("테스트 서버의 TCP 주소를 확인할 수 없습니다");
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = request(
+      {
+        host: "127.0.0.1",
+        port: address.port,
+        path: options.path,
+        method: options.method ?? "GET",
+        headers: options.headers,
+      },
+      (response) => {
+        const chunks: Buffer[] = [];
+        response.on("data", (chunk: Buffer) => chunks.push(chunk));
+        response.on("end", () => {
+          resolve({
+            statusCode: response.statusCode,
+            headers: response.headers,
+            body: Buffer.concat(chunks),
+          });
+        });
+      },
+    );
+    req.on("error", reject);
+    if (options.body !== undefined) {
+      req.write(options.body);
+    }
+    req.end();
+  });
+}
+
+describe("Sonamu 서버 플러그인 등록 순서", () => {
+  const originalSnapshot = Sonamu.captureTestingSnapshot();
+  const originalIsInitialized = Sonamu.isInitialized;
+  const originalForTesting = Sonamu.forTesting;
+  const originalServer = Sonamu.server;
+  const originalNodeEnv = process.env.NODE_ENV;
+  const originalHot = process.env.HOT;
+  const servers: FastifyInstance[] = [];
+  const tempRoots: string[] = [];
+  let apiRootPath: string;
+
+  beforeEach(async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.HOT;
+    Sonamu.isInitialized = true;
+    Sonamu.forTesting = false;
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-plugin-registration-"));
+    tempRoots.push(tempRoot);
+    apiRootPath = path.join(tempRoot, "api");
+    Reflect.set(Sonamu, "apiRootPathValue", apiRootPath);
+    Reflect.set(Sonamu, "syncerValue", {
+      apis,
+      models: {
+        PayloadModel: {
+          large: () => ({ value: LARGE_VALUE }),
+          largeWithoutCompression: () => ({ value: LARGE_VALUE }),
+        },
+      },
+      types: {},
+    });
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+  });
+
+  afterEach(async () => {
+    try {
+      await Promise.allSettled(servers.splice(0).map(async (server) => await server.close()));
+    } finally {
+      Sonamu.restoreTestingSnapshot(originalSnapshot);
+      Sonamu.isInitialized = originalIsInitialized;
+      Sonamu.forTesting = originalForTesting;
+      Sonamu.server = originalServer;
+      if (originalNodeEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = originalNodeEnv;
+      }
+      if (originalHot === undefined) {
+        delete process.env.HOT;
+      } else {
+        process.env.HOT = originalHot;
+      }
+      await Promise.all(
+        tempRoots.splice(0).map(async (tempRoot) => {
+          await rm(tempRoot, { recursive: true, force: true });
+        }),
+      );
+      vi.restoreAllMocks();
+    }
+  });
+
+  async function createProductionServer(
+    plugins: SonamuServerOptions["plugins"],
+  ): Promise<FastifyInstance> {
+    const config: SonamuConfig = {
+      api: { dir: "src", route: { prefix: "/api" } },
+      i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+      sync: { targets: [] },
+      validation: { zodCompiler: false },
+      database: {},
+      logging: false,
+      server: {
+        plugins,
+        apiConfig,
+      },
+    };
+    Reflect.set(Sonamu, "configValue", config);
+    vi.spyOn(sonamuWithBoot, "boot").mockResolvedValue(undefined);
+
+    const server = await Sonamu.createServer({ enableSync: false, doSilent: true });
+    servers.push(server);
+    await server.listen({ host: "127.0.0.1", port: 0 });
+    return server;
+  }
+
+  it("운영 서버에서 compress: true이면 JSON 응답을 gzip으로 압축한다", async () => {
+    const server = await createProductionServer({ compress: true });
+
+    const response = await requestServer(server, {
+      path: "/api/payload/large",
+      headers: { "accept-encoding": "gzip" },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.headers["content-encoding"]).toBe("gzip");
+    expect(JSON.parse(gunzipSync(response.body).toString())).toEqual({ value: LARGE_VALUE });
+  });
+
+  it("운영 서버에서 API별 compress: false는 압축하지 않는다", async () => {
+    const server = await createProductionServer({ compress: true });
+
+    const optedOut = await requestServer(server, {
+      path: "/api/payload/largeWithoutCompression",
+      headers: { "accept-encoding": "gzip" },
+    });
+
+    expect(optedOut.headers["content-encoding"]).toBeUndefined();
+    expect(JSON.parse(optedOut.body.toString())).toEqual({ value: LARGE_VALUE });
+  });
+});

package/src/api/sonamu.ts

@@ -1979,6 +1979,7 @@ class SonamuClass {
       return;
     }
 
+    // route() 시점에 실행되는 onRoute 훅이 설치되도록 플러그인 등록 완료를 기다립니다.
     // compress 플러그인은 다른 플러그인보다 먼저 등록되어야 합니다.
     if (plugins.compress) {
       const compressPlugin = (await import("@fastify/compress")).default;
@@ -1992,9 +1993,9 @@ class SonamuClass {
       };
 
       if (plugins.compress === true) {
-        server.register(compressPlugin, defaultOptions);
+        await server.register(compressPlugin, defaultOptions);
       } else {
-        server.register(compressPlugin, {
+        await server.register(compressPlugin, {
           ...defaultOptions,
           ...plugins.compress,
         });
@@ -2018,9 +2019,9 @@ class SonamuClass {
       if (!option) return;
 
       if (option === true) {
-        server.register((await import(pluginName)).default);
+        await server.register((await import(pluginName)).default);
       } else {
-        server.register((await import(pluginName)).default, option);
+        await server.register((await import(pluginName)).default, option);
       }
     };
 

package/src/auth/__tests__/better-auth-request.test.ts

@@ -0,0 +1,210 @@
+import { type FastifyRequest } from "fastify";
+import { describe, expect, test } from "vitest";
+
+import { createBetterAuthRequest } from "../better-auth-request";
+
+// createBetterAuthRequest가 실제로 사용하는 FastifyRequest 필드만 추린 최소 모킹 타입
+type MockableRequestFields = Pick<FastifyRequest, "url" | "method" | "headers" | "body" | "ip">;
+
+function createMockFastifyRequest(overrides: {
+  url?: string;
+  method?: string;
+  headers?: Record<string, string | string[]>;
+  body?: unknown;
+  ip?: string;
+}): FastifyRequest {
+  const mock: MockableRequestFields = {
+    url: overrides.url ?? "/api/auth/callback/apple",
+    method: overrides.method ?? "POST",
+    headers: { host: "localhost:3000", ...overrides.headers },
+    body: overrides.body ?? null,
+    ip: overrides.ip ?? "127.0.0.1",
+  };
+  // SAFETY: 대상 함수는 위 필드만 접근하므로 최소 모킹을 FastifyRequest로 간주해도 안전하다.
+  return mock as FastifyRequest;
+}
+
+describe("createBetterAuthRequest — urlencoded 본문 직렬화 (SON-549)", () => {
+  test("urlencoded POST 콜백 본문을 JSON이 아닌 urlencoded로 직렬화한다", async () => {
+    // Apple Sign-In form_post 콜백 형태의 본문
+    const body = {
+      state: "abc123",
+      code: "authcode-456",
+      user: '{"name":{"firstName":"길동"}}',
+    };
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+    const text = await result.text();
+
+    // JSON 직렬화 결과가 아니어야 한다
+    expect(text).not.toBe(JSON.stringify(body));
+
+    // urlencoded로 재파싱 시 원본 값이 모두 복원되어야 한다
+    const params = new URLSearchParams(text);
+    expect(params.get("state")).toBe("abc123");
+    expect(params.get("code")).toBe("authcode-456");
+    expect(params.get("user")).toBe('{"name":{"firstName":"길동"}}');
+  });
+
+  test("charset 파라미터가 붙은 content-type도 urlencoded로 처리한다", async () => {
+    const body = { state: "abc123", code: "authcode-456" };
+    const request = createMockFastifyRequest({
+      headers: {
+        "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
+      },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+    const params = new URLSearchParams(await result.text());
+
+    expect(params.get("state")).toBe("abc123");
+    expect(params.get("code")).toBe("authcode-456");
+  });
+
+  test("특수문자(=, &, +, 공백, 한글)가 포함된 값이 왕복 보존된다", async () => {
+    const trickyState = "a=b&c+d e한글";
+    const body = { state: trickyState, code: "x" };
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+    const params = new URLSearchParams(await result.text());
+
+    expect(params.get("state")).toBe(trickyState);
+    expect(params.get("code")).toBe("x");
+  });
+
+  test("본문이 이미 urlencoded 문자열이면 값이 그대로 보존된다", async () => {
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: "state=abc&code=def",
+    });
+
+    const result = createBetterAuthRequest(request);
+    const params = new URLSearchParams(await result.text());
+
+    expect(params.get("state")).toBe("abc");
+    expect(params.get("code")).toBe("def");
+  });
+
+  test("배열 값은 반복 키로 직렬화되어 값 손실이 없다", async () => {
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: { tags: ["a", "b"] },
+    });
+
+    const result = createBetterAuthRequest(request);
+    const params = new URLSearchParams(await result.text());
+
+    // "a,b"로 합쳐지지 않고 반복 키(tags=a&tags=b)로 유지되어야 한다
+    expect(params.getAll("tags")).toEqual(["a", "b"]);
+  });
+
+  test("대소문자가 섞인 content-type 값도 urlencoded로 감지한다", async () => {
+    // HTTP 미디어 타입은 대소문자를 구분하지 않으며(RFC 9110 §8.3.1),
+    // Fastify 파서 조회도 소문자화된 타입으로 매칭하므로 브리지도 동일하게 감지해야 한다
+    const body = { state: "mixed-case", code: "authcode-789" };
+    const request = createMockFastifyRequest({
+      headers: {
+        "content-type": "Application/X-WWW-Form-Urlencoded; charset=UTF-8",
+      },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+    const text = await result.text();
+
+    expect(text).not.toBe(JSON.stringify(body));
+
+    const params = new URLSearchParams(text);
+    expect(params.get("state")).toBe("mixed-case");
+    expect(params.get("code")).toBe("authcode-789");
+  });
+
+  test("urlencoded content-type에 중첩 객체 본문이면 JSON 직렬화 폴백을 유지한다", async () => {
+    // qs 계열 파서가 생성하는 중첩 객체는 평탄한 레코드가 아니므로
+    // 본문을 버리거나 예외를 던지지 않고 기존 JSON 직렬화로 보존해야 한다
+    const body = { user: { name: "길동" } };
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+
+    expect(await result.text()).toBe(JSON.stringify(body));
+  });
+});
+
+describe("createBetterAuthRequest — 기존 동작 회귀 보장", () => {
+  test("JSON POST 본문은 JSON.stringify 결과 그대로 전달한다", async () => {
+    const body = { email: "user@example.com", password: "secret" };
+    const request = createMockFastifyRequest({
+      headers: { "content-type": "application/json" },
+      body,
+    });
+
+    const result = createBetterAuthRequest(request);
+
+    expect(await result.text()).toBe(JSON.stringify(body));
+  });
+
+  test("content-type 없는 POST 본문은 JSON.stringify를 유지한다", async () => {
+    const body = { foo: "bar" };
+    const request = createMockFastifyRequest({ body });
+
+    const result = createBetterAuthRequest(request);
+
+    expect(await result.text()).toBe(JSON.stringify(body));
+  });
+
+  test("GET 요청은 본문 없이 메서드와 URL을 보존한다", () => {
+    const request = createMockFastifyRequest({
+      url: "/api/auth/session?foo=bar",
+      method: "GET",
+      body: null,
+    });
+
+    const result = createBetterAuthRequest(request);
+
+    expect(result.body).toBeNull();
+    expect(result.method).toBe("GET");
+    expect(result.url).toBe("http://localhost:3000/api/auth/session?foo=bar");
+  });
+
+  test("urlencoded 경로에서도 클라이언트 IP 치환과 기타 헤더가 유지된다", async () => {
+    const request = createMockFastifyRequest({
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        "x-forwarded-for": "9.9.9.9",
+        "user-agent": "test-agent",
+        cookie: "session=xyz",
+      },
+      body: { state: "abc" },
+      ip: "1.2.3.4",
+    });
+
+    const result = createBetterAuthRequest(request, ["x-custom-ip"]);
+
+    // replaceClientIpHeaders가 신뢰 가능한 request.ip로 치환해야 한다
+    expect(result.headers.get("x-forwarded-for")).toBe("1.2.3.4");
+    expect(result.headers.get("x-real-ip")).toBe("1.2.3.4");
+    expect(result.headers.get("x-custom-ip")).toBe("1.2.3.4");
+
+    // 그 외 헤더는 변경 없이 전달되어야 한다
+    expect(result.headers.get("user-agent")).toBe("test-agent");
+    expect(result.headers.get("cookie")).toBe("session=xyz");
+    expect(result.headers.get("content-type")).toBe("application/x-www-form-urlencoded");
+
+    // urlencoded 본문 직렬화도 함께 보장한다
+    const params = new URLSearchParams(await result.text());
+    expect(params.get("state")).toBe("abc");
+  });
+});

package/src/auth/better-auth-request.ts

@@ -1,8 +1,52 @@
 import { type FastifyRequest } from "fastify";
+import { z } from "zod";
 
 import { convertFastifyHeadersToStandard } from "../utils/utils";
 import { replaceClientIpHeaders } from "./audit-log/client-ip";
 
+/** charset 등 파라미터나 대소문자 변형도 포함해 urlencoded content-type인지 판별한다 (RFC 9110 §8.3.1) */
+function isUrlEncodedContentType(headers: Headers): boolean {
+  return (
+    headers.get("content-type")?.toLowerCase().startsWith("application/x-www-form-urlencoded") ??
+    false
+  );
+}
+
+/** 파서가 본문을 가공하지 않고 넘긴 경우의 원문 urlencoded 문자열 */
+const rawUrlEncodedBodySchema = z.string();
+
+/** Fastify urlencoded 파서가 생성하는 키-값 본문 (반복 키는 배열로 파싱됨) */
+const urlEncodedValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+const urlEncodedRecordSchema = z.record(
+  z.string(),
+  z.union([urlEncodedValueSchema, z.array(urlEncodedValueSchema)]),
+);
+
+/**
+ * Fastify가 파싱한 본문을 원래 content-type에 맞게 재직렬화한다.
+ * urlencoded 본문을 JSON으로 재직렬화하면 better-auth가 폼 콜백(예: Apple form_post)을
+ * 해석하지 못하므로(state_not_found), content-type과 본문 포맷을 일치시킨다.
+ */
+function serializeBody(request: FastifyRequest, headers: Headers): string {
+  if (!isUrlEncodedContentType(headers)) return JSON.stringify(request.body);
+
+  // 이미 urlencoded 문자열이면 그대로 전달해 값 왜곡을 피한다
+  const rawBody = rawUrlEncodedBodySchema.safeParse(request.body);
+  if (rawBody.success) return rawBody.data;
+
+  const recordBody = urlEncodedRecordSchema.safeParse(request.body);
+  // 예상 밖 형태의 본문은 기존 동작(JSON 직렬화)을 유지한다
+  if (!recordBody.success) return JSON.stringify(request.body);
+
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(recordBody.data)) {
+    // 배열은 "a,b"로 합치지 않고 반복 키(tags=a&tags=b)로 직렬화한다
+    const items = Array.isArray(value) ? value : [value];
+    for (const item of items) params.append(key, String(item));
+  }
+  return params.toString();
+}
+
 export function createBetterAuthRequest(
   request: FastifyRequest,
   ipAddressHeaders?: readonly string[],
@@ -16,6 +60,6 @@ export function createBetterAuthRequest(
     method: request.method,
     headers,
   };
-  if (request.body) init.body = JSON.stringify(request.body);
+  if (request.body) init.body = serializeBody(request, headers);
   return new Request(url.toString(), init);
 }