@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/service-common/protocol/service-event-message.md

@@ -0,0 +1,21 @@
+# ServiceEventMessage
+
+서버가 보내는 이벤트 알림 메시지.
+
+```typescript
+export interface ServiceEventMessage {
+  name: "evt:on";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:on"` | 고정 문자열 discriminant |
+| `body.keys` | `string[]` | 대상 리스너 키 목록 |
+| `body.data` | `unknown` | 이벤트 데이터 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-get-event-listener-infos-message.md

@@ -0,0 +1,19 @@
+# ServiceGetEventListenerInfosMessage
+
+클라이언트가 보내는 이벤트 리스너 정보 목록 요청 메시지.
+
+```typescript
+export interface ServiceGetEventListenerInfosMessage {
+  name: "evt:gets";
+  body: {
+    name: string;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:gets"` | 고정 문자열 discriminant |
+| `body.name` | `string` | 조회할 이벤트 이름 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-message.md

@@ -0,0 +1,52 @@
+# ServiceMessage
+
+모든 서비스 메시지의 유니언 타입. 클라이언트·서버 양방향 메시지를 모두 포함한다.
+
+```typescript
+export type ServiceMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceProgressMessage
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage
+  | ServiceEventMessage;
+```
+
+## Related Types
+
+### `ServiceClientMessage`
+
+클라이언트 → 서버 메시지 유니언.
+
+```typescript
+export type ServiceClientMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage;
+```
+
+### `ServiceServerMessage`
+
+서버 → 클라이언트 메시지 유니언.
+
+```typescript
+export type ServiceServerMessage =
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceEventMessage;
+```
+
+### `ServiceServerRawMessage`
+
+서버가 보내는 모든 메시지 (진행 상태 포함).
+
+```typescript
+export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
+```

package/claude/references/sd-simplysm-v14/service-common/protocol/service-progress-message.md

@@ -0,0 +1,21 @@
+# ServiceProgressMessage
+
+서버가 보내는 청크 수신 진행 상태 알림 메시지.
+
+```typescript
+export interface ServiceProgressMessage {
+  name: "progress";
+  body: {
+    totalSize: number;
+    completedSize: number;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"progress"` | 고정 문자열 discriminant |
+| `body.totalSize` | `number` | 전체 메시지 크기 (바이트) |
+| `body.completedSize` | `number` | 현재까지 수신 완료된 크기 (바이트) |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-remove-event-listener-message.md

@@ -0,0 +1,19 @@
+# ServiceRemoveEventListenerMessage
+
+클라이언트가 보내는 이벤트 리스너 제거 메시지.
+
+```typescript
+export interface ServiceRemoveEventListenerMessage {
+  name: "evt:remove";
+  body: {
+    key: string;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:remove"` | 고정 문자열 discriminant |
+| `body.key` | `string` | 제거할 리스너 키 (UUID) |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-request-message.md

@@ -0,0 +1,17 @@
+# ServiceRequestMessage
+
+클라이언트가 보내는 서비스 메서드 요청 메시지.
+
+```typescript
+export interface ServiceRequestMessage {
+  name: `${string}.${string}`;
+  body: unknown[];
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `` `${string}.${string}` `` | 서비스명.메서드명 형식 (예: `"OrmService.connect"`) |
+| `body` | `unknown[]` | 메서드 매개변수 배열 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-response-message.md

@@ -0,0 +1,17 @@
+# ServiceResponseMessage
+
+서버가 보내는 서비스 메서드 응답 메시지.
+
+```typescript
+export interface ServiceResponseMessage {
+  name: "response";
+  body?: unknown;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"response"` | 고정 문자열 discriminant |
+| `body` | `unknown?` | 메서드 실행 결과 (없으면 void) |

package/claude/references/sd-simplysm-v14/service-common/service-types/app-structure-service.md

@@ -0,0 +1,15 @@
+# AppStructureService
+
+서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 서비스 인터페이스.
+
+```typescript
+export interface AppStructureService {
+  getItems(): Record<string, AppStructureItem[]>;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getItems` | 없음 | `Record<string, AppStructureItem[]>` | 클라이언트명을 키로, 해당 클라이언트의 앱 구조 항목 배열을 값으로 하는 맵 반환 |

package/claude/references/sd-simplysm-v14/service-common/service-types/auto-update-service.md

@@ -0,0 +1,20 @@
+# AutoUpdateService
+
+클라이언트 애플리케이션의 최신 버전 정보를 조회하는 서비스 인터페이스.
+
+```typescript
+export interface AutoUpdateService {
+  getLastVersion(platform: string): Promise<
+    | { version: string; downloadPath: string }
+    | undefined
+  >;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | 지정된 플랫폼의 최신 버전 정보 조회. 버전이 없으면 `undefined` |
+
+`platform` 예시: `"win32"`, `"darwin"`, `"linux"`

package/claude/references/sd-simplysm-v14/service-common/service-types/orm-service.md

@@ -0,0 +1,61 @@
+# OrmService
+
+데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공하는 서비스 인터페이스. MySQL, MSSQL, PostgreSQL을 지원한다. 이 패키지에는 구현체가 없으며, 서버(`service-server`)와 클라이언트(`service-client`)가 공유하는 타입 계약이다.
+
+```typescript
+export interface OrmService {
+  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
+    dialect: Dialect;
+    database?: string;
+    schema?: string;
+  }>;
+  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
+  close(connId: number): Promise<void>;
+  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(connId: number): Promise<void>;
+  rollbackTransaction(connId: number): Promise<void>;
+  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
+  executeDefs(
+    connId: number,
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<unknown[][]>;
+  bulkInsert(
+    connId: number,
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | DB 연결 정보 조회 |
+| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | DB 연결을 생성하고 연결 ID 반환 |
+| `close` | `connId: number` | `Promise<void>` | 연결 종료 |
+| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | 트랜잭션 시작 |
+| `commitTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 커밋 |
+| `rollbackTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 롤백 |
+| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | 파라미터 바인딩 쿼리 실행 |
+| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | QueryDef 배열로 쿼리 실행 |
+| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | 대량 삽입 |
+
+사용 순서: `connect()` → `beginTransaction()` → `executeDefs()`/`executeParametrized()` → `commitTransaction()`/`rollbackTransaction()` → `close()`
+
+## Related Types
+
+### `DbConnOptions`
+
+데이터베이스 연결 옵션.
+
+```typescript
+export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `configName` | `string?` | 서버에 등록된 DB 설정 이름 |
+| `config` | `Record<string, unknown>?` | 직접 지정하는 DB 연결 설정 |

package/claude/references/sd-simplysm-v14/service-common/types/service-upload-result.md

@@ -0,0 +1,19 @@
+# ServiceUploadResult
+
+파일 업로드 결과. 서버에 업로드된 파일의 정보를 포함한다.
+
+```typescript
+export interface ServiceUploadResult {
+  path: string;
+  filename: string;
+  size: number;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | `string` | 서버 내 저장 경로 |
+| `filename` | `string` | 원본 파일명 |
+| `size` | `number` | 파일 크기 (바이트) |

package/claude/references/sd-simplysm-v14/service-server/README.md

@@ -0,0 +1,162 @@
+# @simplysm/service-server
+
+> Fastify 기반 서비스 서버. WebSocket/HTTP 이중 전송, JWT 인증, ORM 브리지, 자동 업데이트를 제공한다.
+> Node.js 런타임 전용. `@simplysm/service-common`과 `@simplysm/core-common`에 의존한다.
+
+## Installation
+
+```bash
+npm install @simplysm/service-server
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 서버 생성 및 시작 | [`ServiceServer`](./main/service-server.md) |
+| 서비스 정의 | [`defineService`](./core/define-service.md) |
+| 인증 적용 | [`auth`](./core/auth.md) |
+| JWT 토큰 발급/검증 | [`signJwt`](./auth/sign-jwt.md), [`verifyJwt`](./auth/verify-jwt.md) |
+| 이벤트 브로드캐스트 | [`ServiceServer`](./main/service-server.md) (`getEvent` / `emitEvent`) |
+| ORM 서비스 등록 | [`OrmService`](./services/orm-service.md) |
+| 자동 업데이트 서비스 등록 | [`AutoUpdateService`](./services/auto-update-service.md) |
+| 파일 업로드 처리 | [`handleUpload`](./transport-http/handle-upload.md) |
+| 설정 파일 읽기 | [`getConfig`](./utils/get-config.md) |
+
+## API Overview
+
+### Main
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServiceServer`](./main/service-server.md) | class | 서버를 생성하고 시작할 때. WebSocket/HTTP 라우팅, JWT 인증, 이벤트 브로드캐스트, graceful shutdown을 처리한다 |
+| [`ServerEventProxy`](./main/service-server.md#servereventproxy) | interface | `getEvent()`의 반환 타입을 참조할 때 |
+| [`createServiceServer`](./main/create-service-server.md) | function | `new ServiceServer()` 대신 팩토리 함수로 서버를 생성할 때 |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServiceServerOptions`](./types/service-server-options.md) | interface | 서버 생성 옵션을 구성할 때 (rootPath, port, ssl, auth, services) |
+
+### Auth
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`AuthTokenPayload`](./auth/auth-token-payload.md) | interface | JWT 페이로드 타입을 참조할 때 |
+| [`signJwt`](./auth/sign-jwt.md) | function | 서버 외부에서 직접 JWT 토큰을 서명할 때. 일반적으로는 `server.signAuthToken()` 사용을 권장 |
+| [`verifyJwt`](./auth/verify-jwt.md) | function | 서버 외부에서 직접 JWT 토큰을 검증할 때. 일반적으로는 `server.verifyAuthToken()` 사용을 권장 |
+| [`decodeJwt`](./auth/verify-jwt.md#decodejwt) | function | 검증 없이 토큰 내용을 확인할 때 (디버깅 등) |
+
+### Core
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`defineService`](./core/define-service.md) | function | 서비스를 정의할 때. 이름과 팩토리 함수로 구성한다 |
+| [`ServiceDefinition`](./core/define-service.md#servicedefinition) | interface | 서비스 정의 타입을 참조할 때 |
+| [`ServiceMethods`](./core/define-service.md#servicemethods) | type | 클라이언트 측 타입 공유를 위해 서비스 메서드 시그니처를 추출할 때 |
+| [`auth`](./core/auth.md) | function | 서비스 또는 메서드에 인증을 요구할 때 |
+| [`getServiceAuthPermissions`](./core/auth.md#getserviceauthpermissions) | function | `auth()`로 래핑된 함수의 권한 배열을 프로그래밍적으로 읽을 때 |
+| [`ServiceContext`](./core/service-context.md) | interface | 서비스 팩토리에서 컨텍스트 타입을 참조할 때 |
+| [`createServiceContext`](./core/service-context.md#createservicecontext) | function | 테스트 등에서 `ServiceContext`를 직접 생성할 때 |
+| [`executeServiceMethod`](./core/execute-service-method.md) | function | 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때 |
+
+### Transport - Socket
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`WebSocketHandler`](./transport-socket/websocket-handler.md) | interface | WebSocket 메시지 라우팅 및 이벤트 브로드캐스트 동작을 이해할 때 |
+| [`createWebSocketHandler`](./transport-socket/websocket-handler.md#createwebsockethandler) | function | 커스텀 WebSocket 핸들러를 생성할 때 |
+| [`ServiceSocket`](./transport-socket/service-socket.md) | interface | WebSocket 연결 추상화를 참조할 때. `ServiceContext.socket`의 타입이다 |
+| [`createServiceSocket`](./transport-socket/service-socket.md#createservicesocket) | function | 테스트 등에서 `ServiceSocket`을 직접 생성할 때 |
+
+### Transport - HTTP
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`handleHttpRequest`](./transport-http/handle-http-request.md) | function | HTTP API 요청 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
+| [`handleUpload`](./transport-http/handle-upload.md) | function | 파일 업로드 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
+| [`handleStaticFile`](./transport-http/handle-static-file.md) | function | 정적 파일 서빙 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
+
+### Protocol
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServerProtocolWrapper`](./protocol/server-protocol-wrapper.md) | interface | 프로토콜 인코딩/디코딩 래퍼의 동작을 이해할 때. worker 스레드 자동 위임 기준을 확인할 때 |
+| [`createServerProtocolWrapper`](./protocol/server-protocol-wrapper.md#createserverprotocolwrapper) | function | 커스텀 프로토콜 래퍼를 생성할 때 |
+
+### Services
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`OrmService`](./services/orm-service.md) | const | DB 연결을 서비스 계층에서 제공할 때. WebSocket 전용, 인증 필수 |
+| [`OrmServiceType`](./services/orm-service.md#ormservicetype) | type | 클라이언트에서 ORM 서비스 타입을 참조할 때 |
+| [`AutoUpdateService`](./services/auto-update-service.md) | const | 클라이언트 앱 자동 업데이트를 제공할 때 |
+| [`AutoUpdateServiceType`](./services/auto-update-service.md#autoupdateservicetype) | type | 클라이언트에서 자동 업데이트 서비스 타입을 참조할 때 |
+| [`AppStructureService`](./services/app-structure-service.md) | function | 앱 구조 정보를 클라이언트에 제공할 때 |
+| [`AppStructureServiceType`](./services/app-structure-service.md#appstructureservicetype) | type | 클라이언트에서 앱 구조 서비스 타입을 참조할 때 |
+
+### Utils
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`getConfig`](./utils/get-config.md) | function | `.config.json` 파일을 캐싱 및 자동 리로드로 읽을 때 |
+
+### Legacy
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`handleV1Connection`](./legacy/handle-v1-connection.md) | function | V1 WebSocket 프로토콜 호환이 필요할 때. 자동 업데이트만 지원한다 |
+
+## Usage Examples
+
+### 서버 생성 및 시작
+
+```typescript
+import { createServiceServer, defineService, auth } from "@simplysm/service-server";
+
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+})));
+
+const server = createServiceServer<{ userId: string }>({
+  rootPath: "/app",
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [HealthService, UserService],
+});
+
+await server.listen();
+```
+
+### JWT 토큰 발급 및 검증
+
+```typescript
+const token = await server.signAuthToken({
+  roles: ["admin"],
+  data: { userId: "123" },
+});
+
+const payload = await server.verifyAuthToken(token);
+// payload.data.userId === "123"
+```
+
+### 이벤트 브로드캐스트
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+export const UserUpdatedEvent = defineEvent<{ userId: string }, { name: string }>("UserUpdated");
+
+const userUpdatedEvt = server.getEvent<typeof UserUpdatedEvent>("UserUpdated");
+await userUpdatedEvt.emit((info) => info.userId === "123", { name: "새 이름" });
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 브라우저 환경에서 서버에 연결 → `@simplysm/service-client`
+- 서버-클라이언트 공유 타입/프로토콜 정의 → `@simplysm/service-common`

package/claude/references/sd-simplysm-v14/service-server/auth/auth-token-payload.md

@@ -0,0 +1,18 @@
+# AuthTokenPayload
+
+JWT 페이로드 인터페이스. `jose` 라이브러리의 `JWTPayload`를 확장한다.
+
+```typescript
+interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+  roles: string[];
+  data: TAuthInfo;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `roles` | `string[]` | 사용자 역할 배열. `auth(["admin"], ...)` 등에서 역할 검사에 사용된다 |
+| `data` | `TAuthInfo` | 사용자 정의 인증 데이터. `ServiceContext.authInfo`로 접근 가능하다 |
+| (JWTPayload 상속) | — | `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti` 등 표준 JWT 클레임 |

package/claude/references/sd-simplysm-v14/service-server/auth/sign-jwt.md

@@ -0,0 +1,30 @@
+# signJwt
+
+HS256 알고리즘과 12시간 유효기간으로 JWT 토큰을 서명한다.
+
+```typescript
+async function signJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  payload: AuthTokenPayload<TAuthInfo>,
+): Promise<string>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `jwtSecret` | `string` | HMAC 서명 시크릿 |
+| `payload` | [`AuthTokenPayload<TAuthInfo>`](./auth-token-payload.md) | JWT 페이로드 |
+
+## Returns
+
+`Promise<string>` — 서명된 JWT 토큰 문자열.
+
+## Usage
+
+```typescript
+const token = await signJwt("my-secret", {
+  roles: ["admin"],
+  data: { userId: "123" },
+});
+```

package/claude/references/sd-simplysm-v14/service-server/auth/verify-jwt.md

@@ -0,0 +1,35 @@
+# verifyJwt
+
+JWT 토큰을 검증하고 페이로드를 반환한다. 만료된 토큰은 "토큰이 만료되었습니다." 에러를, 그 외 유효하지 않은 토큰은 "유효하지 않은 토큰입니다." 에러를 던진다.
+
+```typescript
+async function verifyJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  token: string,
+): Promise<AuthTokenPayload<TAuthInfo>>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `jwtSecret` | `string` | HMAC 서명 시크릿 |
+| `token` | `string` | 검증할 JWT 토큰 문자열 |
+
+## Returns
+
+`Promise<AuthTokenPayload<TAuthInfo>>` — 검증된 JWT 페이로드.
+
+## Related Types
+
+### `decodeJwt`
+
+JWT 토큰을 검증 없이 디코딩한다. 서명 검증이나 만료 확인을 수행하지 않는다.
+
+```typescript
+function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `token` | `string` | 디코딩할 JWT 토큰 문자열 |

package/claude/references/sd-simplysm-v14/service-server/core/auth.md

@@ -0,0 +1,64 @@
+# auth
+
+서비스 팩토리 또는 메서드에 인증을 요구하는 래퍼 함수. 래핑된 함수에 `AUTH_PERMISSIONS` 심볼로 권한 배열을 부착한다.
+
+## When to use
+
+- ✅ 서비스 전체 또는 특정 메서드에 로그인을 요구할 때
+- ✅ 특정 역할만 접근 가능한 메서드를 만들 때
+- ❌ 인증이 불필요한 공개 메서드에는 사용하지 않는다
+
+```typescript
+function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+function auth<TFunction extends (...args: any[]) => any>(
+  permissions: string[],
+  fn: TFunction,
+): TFunction;
+```
+
+## Overloads
+
+| Overload | Description |
+|----------|-------------|
+| `auth(fn)` | 로그인만 요구 (역할 검사 없음). 권한 배열은 `[]` |
+| `auth(permissions, fn)` | 지정된 역할 중 하나를 가진 사용자만 허용 |
+
+사용 위치:
+- 서비스 수준: `defineService("Name", auth((ctx) => ({ ... })))` — 모든 메서드에 인증 적용
+- 메서드 수준: `{ methodName: auth(() => result) }` — 해당 메서드만 인증 적용
+- 메서드 수준 권한이 서비스 수준 권한보다 우선한다
+
+## Related Types
+
+### `getServiceAuthPermissions`
+
+`auth()`로 래핑된 함수에서 인증 권한 배열을 읽는다. 래핑되지 않은 함수는 `undefined`를 반환한다.
+
+```typescript
+function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `fn` | `Function` | 검사할 함수 |
+
+## Usage
+
+```typescript
+// 서비스 수준: 모든 메서드에 로그인 필요
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+})));
+
+// 역할 지정
+const AdminService = defineService("Admin", auth(["admin"], (ctx) => ({
+  deleteAll: () => { /* ... */ },
+})));
+
+// 메서드 수준
+const MixedService = defineService("Mixed", (ctx) => ({
+  publicMethod: () => "ok",
+  privateMethod: auth(() => ctx.authInfo),
+  adminMethod: auth(["admin"], () => "admin only"),
+}));
+```