sonamu 0.10.12 → 0.10.13

package/src/api/websocket-helpers.ts

@@ -6,6 +6,12 @@ import { type FastifyReply } from "fastify";
 import { isSoException } from "../exceptions/so-exceptions";
 import { isPlainObject } from "../utils/utils";
 
+interface WebSocketCloseDescriptor {
+  code: number;
+  reason: string;
+  logLevel: "warn" | "error";
+}
+
 // Fastify websocket route와 Vite HMR websocket이 같은 server socket을 두고 충돌하는 것을 방지하기 위해,
 // WS route가 존재하면 HMR을 별도 포트로 분리해 띄움
 export function resolveIntegratedViteHmrOptions({
@@ -32,9 +38,11 @@ export function resolveWebSocketPluginOptions({
   rawPluginOption: boolean | WebsocketPluginOptions | undefined;
 }): WebsocketPluginOptions | undefined {
   const pluginOptions = rawPluginOption && rawPluginOption !== true ? { ...rawPluginOption } : {};
-  const serverOptions = isPlainObject(pluginOptions.options)
+  const serverOptions: NonNullable<WebsocketPluginOptions["options"]> = isPlainObject(
+    pluginOptions.options,
+  )
     ? { ...pluginOptions.options }
-    : ({} as NonNullable<WebsocketPluginOptions["options"]>);
+    : {};
 
   if (Object.keys(serverOptions).length > 0) {
     pluginOptions.options = serverOptions;
@@ -45,13 +53,9 @@ export function resolveWebSocketPluginOptions({
 
 // handshake/auth/validation 실패를 generic 1011로 뭉개지 않고 1008(policy violation)로 매핑해,
 // close code policy를 한 곳에서 정의함
-export function resolveWebSocketCloseDescriptor(error: unknown): {
-  code: number;
-  reason: string;
-  logLevel: "warn" | "error";
-} {
-  if (isSoException(error)) {
-    if (error.statusCode === 400) {
+export function resolveWebSocketCloseDescriptor(cause: unknown): WebSocketCloseDescriptor {
+  if (isSoException(cause)) {
+    if (cause.statusCode === 400) {
       return {
         code: 1008,
         reason: "Invalid websocket handshake",
@@ -59,7 +63,7 @@ export function resolveWebSocketCloseDescriptor(error: unknown): {
       };
     }
 
-    if (error.statusCode === 401 || error.statusCode === 403) {
+    if (cause.statusCode === 401 || cause.statusCode === 403) {
       return {
         code: 1008,
         reason: "Unauthorized websocket connection",
@@ -67,7 +71,7 @@ export function resolveWebSocketCloseDescriptor(error: unknown): {
       };
     }
 
-    if (error.statusCode >= 400 && error.statusCode < 500) {
+    if (cause.statusCode >= 400 && cause.statusCode < 500) {
       return {
         code: 1008,
         reason: "Rejected websocket connection",
@@ -86,11 +90,14 @@ export function resolveWebSocketCloseDescriptor(error: unknown): {
 // WS 경로에서는 reply가 존재하지 않으므로 접근 시도를 즉시 에러로 surface해 transport misuse를 빨리 드러냄
 // SSE/reply에 의존하는 contextProvider가 있으면 websocketContextProvider를 따로 정의하라는 가이드 역할도 함
 export function createWebSocketReplyStub(): FastifyReply {
-  return new Proxy({} as FastifyReply, {
-    get() {
-      throw new Error(
-        "FastifyReply is not available in websocket context. Define websocketContextProvider if your context setup depends on reply mutation.",
-      );
+  return new Proxy(
+    /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {} as FastifyReply,
+    {
+      get() {
+        throw new Error(
+          "FastifyReply is not available in websocket context. Define websocketContextProvider if your context setup depends on reply mutation.",
+        );
+      },
     },
-  });
+  );
 }

package/src/auth/audit-log/builders.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 
 import {
   type AccountSnapshot,
+  type AuditEventData,
   type AuditLogEvent,
   type Builder,
   type BuilderLocation,
@@ -21,7 +22,7 @@ import {
 // 모든 빌더 공통 필드(triggeredBy/triggerContext, ipAddress/city/country/countryCode)를 합성한다.
 const createEvent = (
   base: { eventKey: string; eventType: string; eventDisplayName?: string },
-  data: Record<string, unknown>,
+  data: AuditEventData,
   trigger: BuilderTrigger,
   location?: BuilderLocation,
 ): AuditLogEvent => ({
@@ -359,7 +360,7 @@ const buildUserEvent = (
   user: UserSnapshot,
   trigger: BuilderTrigger,
   location: BuilderLocation | undefined,
-  extra?: Record<string, unknown>,
+  extra?: AuditEventData,
 ): AuditLogEvent =>
   createEvent(
     { eventKey: user.id, eventType, eventDisplayName },

package/src/auth/audit-log/client-ip.ts

@@ -1,5 +1,7 @@
 import { isIP } from "node:net";
 
+import { isStringValue } from "../../utils/runtime-value";
+
 const CLIENT_IP_HEADERS = [
   "cf-connecting-ip",
   "x-forwarded-for",
@@ -29,8 +31,8 @@ export function replaceClientIpHeaders(
   }
 }
 
-export function getValidClientIp(value: unknown): string | null {
-  if (typeof value !== "string" || value.length > 45 || isIP(value) === 0) {
+export function getValidClientIp<Value>(value: Value): string | null {
+  if (!isStringValue(value) || value.length > 45 || isIP(value) === 0) {
     return null;
   }
 

package/src/auth/audit-log/events.ts

@@ -1,9 +1,23 @@
 /**
  * sonamuAuditLog 플러그인이 audit-log-ingestor로 전달하는 이벤트 body 타입.
  */
+export type AuditEventDataValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | Date
+  | AuditEventDataValue[]
+  | AuditEventData;
+
+export interface AuditEventData {
+  [key: string]: AuditEventDataValue;
+}
+
 export type AuditLogEvent = {
   eventType: string;
-  eventData: Record<string, unknown>;
+  eventData: AuditEventData;
   eventKey: string;
   eventId?: string;
   eventDisplayName?: string;