@simplysm/sd-claude 14.0.91 → 14.0.92

package/claude/references/sd-simplysm14/apis/service-server/transport-internals.md

@@ -19,9 +19,9 @@ function executeServiceMethod(
 
 요청 1건을 실제 서비스 메서드로 라우팅·실행하는 핵심 게이트키퍼. WebSocket/HTTP 핸들러가 모두 이 함수로 수렴한다.
 
-- `serviceName`/`methodName` — `server.options.services` 에서 `names` 매칭으로 서비스를, 그 팩토리 산출 객체에서 메서드를 찾음. 없으면 throw.
+- `serviceName` / `methodName` — `server.options.services` 의 `names` 매칭으로 서비스를, 그 팩토리 산출 객체에서 메서드를 찾음. 없으면 throw.
 - `params: unknown[]` — 메서드 인자 배열. 스프레드되어 메서드에 전달.
-- `socket?` / `http?` — 둘 중 하나로 요청 출처 전달. `clientName` 에 `..`·슬래시가 있으면 보안 차단 throw.
+- `socket?` / `http?` — 둘 중 하나로 요청 출처 전달. `clientName` 에 `..`·슬래시(`/`,`\`)가 있으면 보안 차단 throw.
 - 동작: 컨텍스트 생성 → 팩토리 호출 → 메서드 조회 → 인증/권한 검사(`auth` 래핑 권한 기준) → 실행 후 반환값 반환. `auth: false` 면 인증 스킵, `auth` 미설정인데 권한 요구 메서드면 설정 오류 throw.
 
 ## createServiceContext
@@ -32,20 +32,30 @@ function createServiceContext<TAuthInfo>(
 ): ServiceContext<TAuthInfo>
 ```
 
-`ServiceContext`(인증·클라이언트·설정 접근자) 인스턴스를 만든다. 인자 `socket`/`http`/`legacy` 중 들어온 것으로 `authInfo`·`clientName` 출처가 결정된다. 컨텍스트 필드 의미는 [service-authoring.md](./service-authoring.md) 의 ServiceContext 절 참조. 테스트에서 컨텍스트를 직접 만들어 서비스 메서드를 단위 호출할 때 유용.
+`ServiceContext`(인증·클라이언트·설정 접근자) 인스턴스를 만든다.
+
+- `server` — 서버 인스턴스(필수).
+- `socket?: ServiceSocket` — 들어오면 `authInfo`·`clientName` 출처가 소켓 우선.
+- `http?: { clientName; authTokenPayload? }` — HTTP 요청 출처.
+- `legacy?: { clientName? }` — V1 레거시 출처(`clientName` 만).
+
+컨텍스트 필드 의미는 [service-authoring.md](./service-authoring.md) 의 ServiceContext 절 참조. 테스트에서 컨텍스트를 직접 만들어 서비스 메서드를 단위 호출할 때 유용.
 
 ## ServiceSocket / createServiceSocket
 
 단일 WebSocket 연결을 감싸 프로토콜 인코딩·ping/pong 연결 유지·이벤트 리스너 추적을 담당하는 인터페이스. `createServiceSocket(socket, clientId, clientName, connReq)` 로 생성.
 
-- `connectedAtDateTime: DateTime` / `clientName: string` / `connReq: FastifyRequest` — 연결 시각·클라이언트 이름·원본 요청.
-- `authTokenPayload?: AuthTokenPayload` — 소켓 `auth` 메시지로 검증된 토큰. 이후 그 소켓 요청의 `ctx.authInfo` 출처.
-- `close()` — 소켓 즉시 종료(terminate).
-- `send(uuid, msg): Promise<number>` — 서버 메시지를 프로토콜로 인코딩해 전송, 보낸 바이트 수 반환.
-- `addListener(key, eventName, info)` / `removeListener(key)` — 이벤트 구독 등록·해제. `key` 는 구독 식별자, `info` 는 selector 매칭용 메타.
-- `getEventListeners(eventName)` — 해당 이벤트의 구독 `{ key, info }[]` 조회.
-- `filterEventTargetKeys(targetKeys)` — 주어진 키 중 이 소켓에 존재하는 것만 반환.
-- `on("error" | "close" | "message", handler)` — 소켓 이벤트 후킹. 5초 주기 ping, pong 미수신 시 자동 terminate.
+- `readonly connectedAtDateTime: DateTime` — 연결 성립 시각.
+- `readonly clientName: string` — 연결 시 받은 클라이언트 이름.
+- `readonly connReq: FastifyRequest` — 원본 연결 요청(원격 주소 등).
+- `authTokenPayload?: AuthTokenPayload` — 소켓 `auth` 메시지로 검증된 토큰. 이후 그 소켓 요청의 `ctx.authInfo` 출처(set 으로 갱신).
+- `close(): void` — 소켓 즉시 종료(terminate).
+- `send(uuid, msg): Promise<number>` — 서버 메시지를 프로토콜로 인코딩해 전송, 보낸 바이트 수 반환(소켓 미개방이면 `0`).
+- `addListener(key, eventName, info): void` — 이벤트 구독 등록. `key` = 구독 식별자, `info` = selector 매칭용 메타.
+- `removeListener(key): void` — `key` 로 구독 1건 해제.
+- `getEventListeners(eventName): { key, info }[]` — 해당 이벤트의 구독 목록 조회.
+- `filterEventTargetKeys(targetKeys): string[]` — 주어진 키 중 이 소켓에 존재하는 것만 반환.
+- `on("error" | "close" | "message", handler): void` — 소켓 이벤트 후킹. 5초 주기 ping, pong 미수신 시 자동 terminate.
 
 ## WebSocketHandler / createWebSocketHandler
 
@@ -58,26 +68,26 @@ function createWebSocketHandler(
 
 여러 `ServiceSocket` 을 `clientId` 로 관리하고, 클라이언트 메시지를 `runMethod`(보통 `executeServiceMethod` 바인딩)로 라우팅하며, 이벤트를 브로드캐스트한다.
 
-- `addSocket(socket, clientId, clientName, connReq)` — 연결 등록. 같은 `clientId` 의 기존 연결은 닫고 교체.
-- `closeAll()` — 모든 연결 종료(서버 `close()` 시 호출).
+- `addSocket(socket, clientId, clientName, connReq): void` — 연결 등록. 같은 `clientId` 의 기존 연결은 닫고 교체. 생성 중 예외 시 소켓 terminate.
+- `closeAll(): void` — 모든 연결 종료(서버 `close()` 시 호출).
 - `emit<TEventDef>(eventName, infoSelector, data): Promise<void>` — 전 소켓의 해당 이벤트 구독 중 `infoSelector(info)` 가 `true` 인 키에게만 `evt:on` 메시지 전송. `ServiceServer.emitEvent` 의 실제 구현.
-- 처리하는 클라이언트 메시지 종류: `"<service>.<method>"`(RPC 호출), `evt:add`/`evt:remove`/`evt:gets`/`evt:emit`(이벤트 구독·조회·발생), `auth`(소켓 토큰 검증). 그 외는 `BAD_MESSAGE` 에러 응답. `DEV` 환경에서만 에러 스택 포함.
+- 처리하는 클라이언트 메시지 종류: `"<service>.<method>"`(RPC 호출), `evt:add`/`evt:remove`/`evt:gets`/`evt:emit`(이벤트 구독·해제·조회·발생), `auth`(소켓 토큰 검증). 그 외는 `BAD_MESSAGE` 에러 응답. 처리 중 예외는 `INTERNAL_ERROR` 응답이며, `DEV` 환경에서만 에러 스택 포함.
 
 ## HTTP / 정적 / 업로드 핸들러
 
 `fastify` 라우트에 직접 물리는 저수준 함수들. 커스텀 라우트를 짤 때만 직접 사용.
 
-- `handleHttpRequest(req, reply, jwtSecret, runMethod)` — `/api/:service/:method` 처리. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <token>` 검증(실패 시 401), GET 은 `?json=` 쿼리, POST 는 배열 본문에서 파라미터를 받아 `runMethod` 실행. 그 외 메서드는 405.
-- `handleUpload(req, reply, rootPath, jwtSecret)` — `/upload` multipart 처리. 인증 토큰 필수(없거나 무효면 401). 파일을 `rootPath/www/uploads/<uuid><ext>` 로 저장하고 `ServiceUploadResult[]`(`{ path, filename, size }`) 반환. 도중 실패 시 그 요청에서 저장한 파일을 모두 롤백 삭제 후 500.
-- `handleStaticFile(req, reply, rootPath, urlPath)` — `rootPath/www` 하위 정적 파일 전송. `www` 밖 경로는 차단(throw), 디렉터리면 슬래시 리다이렉트 후 `index.html`, `.` 으로 시작하는 숨김 파일은 403, 미존재는 404 HTML 응답.
+- `handleHttpRequest(req, reply, jwtSecret, runMethod)` — `/api/:service/:method` 처리. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <token>` 검증(실패 시 401). GET 은 `?json=` 쿼리, POST 는 배열 본문에서 파라미터를 받아 `runMethod` 실행. 본문이 배열이 아니면 400, 그 외 HTTP 메서드는 405.
+- `handleUpload(req, reply, rootPath, jwtSecret)` — `/upload` multipart 처리. multipart 아니면 400, 인증 토큰 필수(없거나 무효면 401). 파일을 `rootPath/www/uploads/<uuid><ext>` 로 저장하고 `ServiceUploadResult[]`(`{ path, filename, size }`) 반환. 도중 실패 시 그 요청에서 저장한 파일을 모두 롤백 삭제 후 500.
+- `handleStaticFile(req, reply, rootPath, urlPath)` — `rootPath/www` 하위 정적 파일 전송. `www` 밖 경로는 차단(throw), 디렉터리면 슬래시 리다이렉트 후 `index.html`, `.` 으로 시작하는 숨김 파일은 403, 미존재는 404, 그 외 전송 실패는 500 HTML 응답.
 
 ## ServerProtocolWrapper / createServerProtocolWrapper
 
-메시지 인코딩/디코딩을 크기·내용에 따라 worker 스레드와 메인 스레드로 자동 분배하는 래퍼. `createServerProtocolWrapper()` 로 생성(worker 는 지연 싱글턴).
+메시지 인코딩/디코딩을 크기·내용에 따라 worker 스레드와 메인 스레드로 자동 분배하는 래퍼. `createServerProtocolWrapper()` 로 생성(worker 는 지연 싱글턴, 소켓 간 공유).
 
-- `encode(uuid, message): Promise<{ chunks: Bytes[]; totalSize: number }>` — `body` 에 `Uint8Array` 가 있으면 worker, 아니면 메인 스레드에서 인코딩.
-- `decode(bytes): Promise<ServiceMessageDecodeResult>` — 청크 재조립(stateful)은 항상 메인 스레드 단일 누적기에서, 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 worker 위임. 진행 중이면 `{ type: "progress" }`, 완료면 `{ type: "complete", uuid, message }`.
-- `dispose()` — 프로토콜 리소스 해제.
+- `encode(uuid, message): Promise<{ chunks: Bytes[]; totalSize: number }>` — `body` 에 `Uint8Array` 가 있으면(단일 또는 배열 요소 중 하나라도) worker, 아니면 메인 스레드에서 인코딩.
+- `decode(bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>` — 청크 재조립(stateful)은 항상 메인 스레드 단일 누적기에서, 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 worker 위임. 진행 중이면 `{ type: "progress" }`, 완료면 `{ type: "complete", uuid, message }`.
+- `dispose(): void` — 프로토콜 리소스 해제.
 
 ## getConfig
 

package/claude/references/sd-simplysm14/apis/service-server/v1-legacy.md

@@ -1,6 +1,6 @@
 # @simplysm/service-server — V1 레거시 지원
 
-`ver !== "2"`(구버전) WebSocket 클라이언트를 받기 위한 레거시 핸들러. 주로 구버전 앱의 자동업데이트(`SdAutoUpdateService.getLastVersion`) 요청을 처리한다. `ServiceServer` 는 ver=2 가 아닌 연결을 자동으로 이 핸들러로 넘긴다(`AutoUpdate` 서비스나 `legacyV1Handlers` 가 있을 때만, 둘 다 없으면 연결 거부). `ServiceServerOptions.legacyV1Handlers` 로 커스텀 핸들러를 끼울 때만 직접 다룬다.
+`ver !== "2"`(구버전) WebSocket 클라이언트를 받기 위한 레거시 핸들러. 주로 구버전 앱의 자동업데이트(`SdAutoUpdateService.getLastVersion`) 요청을 처리한다. `ServiceServer` 는 ver=2 가 아닌 연결을 자동으로 이 핸들러로 넘긴다(`AutoUpdate` 서비스나 `legacyV1Handlers` 가 있을 때만, 둘 다 없으면 코드 1008 로 연결 거부). `ServiceServerOptions.legacyV1Handlers` 로 커스텀 핸들러를 끼울 때만 직접 다룬다.
 
 ## handleV1Connection
 
@@ -9,10 +9,10 @@ function handleV1Connection(socket, autoUpdateMethods: V1AutoUpdateMethods, clie
 function handleV1Connection(socket, options: V1ConnectionOptions): void;
 ```
 
-V1 WebSocket 연결 1건을 받아 연결 알림(`{ name: "connected" }`) 전송 후 메시지를 처리한다. 처리 순서: 커스텀 핸들러들 → (미처리 시) `SdAutoUpdateService.getLastVersion` fallback → 그래도 미처리면 `UPGRADE_REQUIRED` 에러 응답. 메시지 파싱·처리 중 예외는 잡아 warn 로그만 남기고 응답하지 않음.
+V1 WebSocket 연결 1건을 받아 연결 알림(`{ name: "connected" }`) 전송 후 메시지를 처리한다. 처리 순서: 커스텀 핸들러들 → (미처리 시) `SdAutoUpdateService.getLastVersion` fallback → 그래도 미처리면 `UPGRADE_REQUIRED` 에러 응답. 메시지 파싱·처리 중 예외는 잡아 warn 로그만 남기고 응답하지 않는다.
 
 - `socket: WebSocket` — `ws` 의 원시 소켓.
-- 2번째 인자: `V1AutoUpdateMethods` 객체(자동업데이트만 응대)이거나 `V1ConnectionOptions`(핸들러·팩토리 포함). `"getLastVersion" in arg` 로 분기.
+- 2번째 인자 — `V1AutoUpdateMethods` 객체(자동업데이트만 응대)이거나 `V1ConnectionOptions`(핸들러·팩토리 포함). `"getLastVersion" in arg` 로 분기.
 - `clientNameSetter?` — 첫 시그니처에서만. 요청의 `clientName` 을 외부에 통지하는 콜백.
 
 ## V1ConnectionOptions
@@ -21,15 +21,15 @@ V1 WebSocket 연결 1건을 받아 연결 알림(`{ name: "connected" }`) 전송
 - `serviceContextFactory?: (request: V1Request) => ServiceContext` — 요청마다 컨텍스트를 새로 만들 때. `serviceContext` 보다 우선.
 - `handlers?: V1RequestHandler[]` — 커스텀 요청 핸들러 목록. 앞에서부터 호출되며 첫 `handled: true` 에서 멈춤. 핸들러가 있는데 컨텍스트가 없으면 throw.
 - `autoUpdateMethods?: V1AutoUpdateMethods` — 자동업데이트 fallback 구현(고정).
-- `autoUpdateMethodsFactory?: (ctx: V1RequestHandlerContext) => V1AutoUpdateMethods` — 요청마다 fallback 구현 생성. 지정 시 `autoUpdateMethods` 대신 사용.
+- `autoUpdateMethodsFactory?: (ctx: V1RequestHandlerContext) => V1AutoUpdateMethods` — 요청마다 fallback 구현 생성. 지정 시 `autoUpdateMethods` 대신 사용(컨텍스트 없으면 throw).
 - `clientNameSetter?: (clientName: string | undefined) => void` — 매 요청 `clientName` 통지 콜백.
 
 ## V1RequestHandler 와 관련 타입
 
-- `V1Request` — `{ uuid: string; command: string; params: unknown[]; clientName?: string }`. 구버전 클라이언트가 보내는 요청 형태.
-- `V1Response` — `{ name: "response"; reqUuid: string; state: "success" | "error"; body: unknown }`. 서버가 돌려보내는 응답 형태(`state` 로 성공/에러 구분).
+- `V1Request` — `{ uuid: string; command: string; params: unknown[]; clientName?: string }`. 구버전 클라이언트가 보내는 요청 형태. `command` 는 `"<service>.<method>"` 형태의 명령 키.
+- `V1Response` — `{ name: "response"; reqUuid: string; state: "success" | "error"; body: unknown }`. 서버가 돌려보내는 응답 형태. `state` = 응답 상태로 `"success"`(정상)·`"error"`(오류) 구분.
 - `V1RequestHandlerContext` — `{ request: V1Request; serviceContext: ServiceContext }`. 핸들러가 받는 인자.
-- `V1RequestHandlerResult` — `{ handled: true; state?: "success"|"error"; body: unknown } | { handled: false }`. `handled: false` 면 다음 핸들러·fallback 으로 넘어감, `true` 면 그 `state`(기본 `"success"`)·`body` 로 즉시 응답.
+- `V1RequestHandlerResult` — `{ handled: true; state?: "success" | "error"; body: unknown } | { handled: false }`. `handled` = 이 핸들러가 요청을 처리했는지. `false` 면 다음 핸들러·fallback 으로 넘어가고, `true` 면 그 `state`(기본 `"success"`)·`body` 로 즉시 응답.
 - `V1RequestHandler` — `(ctx: V1RequestHandlerContext) => V1RequestHandlerResult | Promise<V1RequestHandlerResult>`. 동기·비동기 모두 가능.
 - `V1AutoUpdateMethods` — `{ getLastVersion: (platform: string) => Promise<unknown> | unknown }`. `SdAutoUpdateService.getLastVersion` 명령의 fallback 인터페이스.
 
@@ -46,4 +46,4 @@ const server = createServiceServer({
 });
 ```
 
-주의: `legacyV1Handlers` 도 없고 `AutoUpdate`(`SdAutoUpdateService`) 서비스도 등록 안 됐으면 ver=2 가 아닌 연결은 코드 1008 로 즉시 거부된다.
+주의: `legacyV1Handlers` 도 없고 `AutoUpdate`(`SdAutoUpdateService`) 서비스도 등록 안 됐으면 ver≠2 연결은 코드 1008 로 즉시 거부된다.

package/claude/references/sd-simplysm14/apis/storage/README.md

@@ -1,40 +1,17 @@
 # @simplysm/storage
 
-FTP / FTPS / SFTP 원격 스토리지에 연결해 파일·디렉토리를 업로드·다운로드·조회·삭제하는 Node 전용 클라이언트. 프로토콜별 구현을 동일 인터페이스(`StorageClient`)로 통일하고, 팩토리(`StorageFactory.connect`)로 연결/종료를 자동 관리.
+Node.js 환경에서 FTP/FTPS/SFTP 원격 스토리지에 접속해 파일·디렉토리를 업로드·다운로드·조회·삭제하는 라이브러리. 프로토콜별 구현을 동일 인터페이스(`StorageClient`)로 통일하고, `StorageFactory.connect` 콜백 패턴으로 연결/종료를 자동 관리한다. 전 구현이 Node 전용(`basic-ftp`·`ssh2-sftp-client`·`fs`/`os`/`path`/`stream` 의존)이라 브라우저에서 사용 불가.
 
 ## 사용 트리거 인덱스
 
-- **StorageFactory** — 원격 스토리지에 접속해 파일 작업을 한 뒤 자동으로 연결을 닫고 싶을 때. 권장 진입점.
-- **StorageClient** — `connect` 콜백 안에서 받는 파일 조작 인터페이스. mkdir/list/readFile/put/remove 등 호출 시 참조.
-- **StorageConnConfig** — 접속 호스트/계정/비밀번호를 구성할 때.
-- **StorageProtocol** — 프로토콜 종류(`ftp`/`ftps`/`sftp`)를 지정할 때.
-- **FileInfo** — `list()` 가 돌려주는 항목 구조(이름·파일여부)를 확인할 때.
-- **FtpStorageClient / SftpStorageClient** — 팩토리 없이 클라이언트를 직접 인스턴스화·재연결 제어해야 할 때(비권장).
+- **StorageFactory.connect** — 프로토콜·접속정보로 연결을 열고 콜백 안에서 파일 작업 후 자동 종료할 때. 직접 클라이언트 인스턴스화보다 권장되는 진입점.
+- **StorageClient** — connect 콜백이 받는 파일 작업 인터페이스(mkdir/list/put/readFile/exists/remove/rename/uploadDir 등). 어떤 메서드를 호출할 수 있는지 확인할 때.
+- **StorageConnConfig / StorageProtocol / FileInfo** — connect 인자 형태, 지원 프로토콜 리터럴, list 반환 항목 형태를 확인할 때.
+- **FtpStorageClient / SftpStorageClient** — 팩토리 없이 연결을 직접 잡거나(수명·재연결 직접 제어), 프로토콜별 인증·동작 차이를 확인할 때. 비권장.
 
-## StorageProtocol
+## StorageFactory (진입점)
 
-```ts
-type StorageProtocol = "ftp" | "ftps" | "sftp";
-```
-
-- `"ftp"` — 평문 FTP. 보안 채널 없이 접속(`FtpStorageClient` 를 `secure=false` 로 생성). 내부망·테스트 환경에서만 권장.
-- `"ftps"` — TLS 로 암호화된 FTP(`FtpStorageClient` 를 `secure=true` 로 생성). 외부망 FTP 접속 시.
-- `"sftp"` — SSH 기반 SFTP(`SftpStorageClient`). password 미지정 시 `~/.ssh/id_ed25519` 키 + SSH agent 로 인증. 가장 일반적인 보안 전송.
-
-## StorageConnConfig
-
-```ts
-interface StorageConnConfig { host: string; port?: number; user?: string; password?: string; }
-```
-
-- `host: string` — 접속 대상 서버 호스트명 또는 IP. 필수.
-- `port?: number` — 접속 포트. 미지정 시 각 라이브러리 기본값(FTP 21, SFTP 22) 사용. 비표준 포트면 명시.
-- `user?: string` — 로그인 사용자명. 미지정 시 익명/기본 사용자.
-- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 `null`/미지정이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키와 SSH agent(`SSH_AUTH_SOCK` 환경변수가 설정된 경우 `agent` 옵션) 로 인증 시도하고, 키 파싱 실패(암호화 키 등) 시 agent 단독으로 재시도. FTP/FTPS 에서는 미지정 시 라이브러리 기본(익명) 처리. 키 인증을 쓰려면 password 를 넘기지 말 것.
-
-## StorageFactory
-
-스토리지 접속 진입점. 연결 생성 → 콜백 실행 → 자동 종료를 묶어 처리한다. 인스턴스를 직접 만들 필요 없이 정적 `connect` 만 사용.
+스토리지 접속 진입점. 인스턴스를 만들 필요 없이 정적 `connect` 만 사용한다. 연결 생성 → 콜백 실행 → 자동 종료를 한 번에 묶어 처리한다.
 
 ```ts
 class StorageFactory {
@@ -46,10 +23,10 @@ class StorageFactory {
 }
 ```
 
-- `type: StorageProtocol` — 사용할 프로토콜. `"sftp"` → `SftpStorageClient`, `"ftps"` → `FtpStorageClient(secure=true)`, `"ftp"` → `FtpStorageClient(secure=false)` 를 내부 생성. 보안 전송이 필요하면 `"ftps"` 또는 `"sftp"`.
-- `config: StorageConnConfig` — 접속 설정. 위 StorageConnConfig 참조.
+- `type: StorageProtocol` — 사용할 프로토콜. 내부에서 `"sftp"` → `SftpStorageClient`, `"ftps"` → `FtpStorageClient(secure=true)`, `"ftp"` → `FtpStorageClient(secure=false)` 를 생성. 보안 전송이 필요하면 `"ftps"`/`"sftp"`.
+- `config: StorageConnConfig` — 접속 설정(host/port/user/password). 아래 StorageConnConfig 참조.
 - `fn: (storage: StorageClient) => R | Promise<R>` — 연결된 `StorageClient` 를 받아 파일 작업을 수행하는 콜백. 반환값이 그대로 `connect` 의 결과(`Promise<R>`) 가 됨. 동기·비동기 모두 허용.
-- 동작: `client.connect()` 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 오류는 무시(이미 종료된 경우 대비). 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨. 직접 클라이언트를 다루는 것보다 권장.
+- 동작: `client.connect(config)` 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 중 오류는 무시(이미 종료된 경우 대비). 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨.
 
 ```ts
 const names = await StorageFactory.connect("sftp", { host: "10.0.0.1", user: "u", password: "p" }, async (s) => {
@@ -59,9 +36,47 @@ const names = await StorageFactory.connect("sftp", { host: "10.0.0.1", user: "u"
 });
 ```
 
-## StorageClient
+주의: 콜백 밖으로 `storage` 를 유출해 나중에 호출하면 이미 닫힌 연결이므로 실패한다.
+
+## 연결·작업 타입
+
+### StorageConnConfig
+
+원격 서버 접속 정보.
+
+```ts
+interface StorageConnConfig { host: string; port?: number; user?: string; password?: string; }
+```
+
+- `host: string` — 접속 대상 서버 호스트명 또는 IP. 필수.
+- `port?: number` — 접속 포트. 미지정 시 각 라이브러리 기본값(FTP 21, SFTP 22) 사용. 비표준 포트면 명시.
+- `user?: string` — 로그인 사용자명. 미지정 시 익명/기본 사용자.
+- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 미지정이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키 + SSH agent(`SSH_AUTH_SOCK` 환경변수가 있으면 `agent` 옵션)로 인증을 시도하고, 키 파싱 실패(암호화 키 등) 시 agent 단독 재시도. FTP/FTPS 에서는 미지정 시 라이브러리 기본(익명) 처리. SFTP 키 인증을 쓰려면 password 를 넘기지 말 것.
+
+### StorageProtocol
+
+```ts
+type StorageProtocol = "ftp" | "ftps" | "sftp";
+```
+
+- `"ftp"` — 평문 FTP. 보안 채널 없음(`FtpStorageClient` 를 `secure=false` 로 생성). 내부망·테스트에서만 권장.
+- `"ftps"` — TLS 로 암호화된 FTP(`FtpStorageClient` 를 `secure=true` 로 생성). 외부망 FTP 접속 시.
+- `"sftp"` — SSH 기반 SFTP(`SftpStorageClient`). 가장 일반적인 보안 전송.
+
+### FileInfo
 
-`connect` 콜백 안에서 받는 파일 조작 인터페이스. `FtpStorageClient`·`SftpStorageClient` 가 구현한다. 모든 메서드는 `Promise` 반환. 경로는 원격 기준 경로 문자열.
+`list()` 가 반환하는 항목.
+
+```ts
+interface FileInfo { name: string; isFile: boolean; }
+```
+
+- `name: string` — 항목 이름(파일명 또는 디렉토리명, 경로 아님).
+- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. 디렉토리 탐색 시 파일만 골라 처리하는 분기 기준으로 사용. FTP 는 라이브러리의 `isFile`, SFTP 는 항목 type 이 `"-"`(일반 파일)인 경우만 `true`(디렉토리·심볼릭 링크는 `false`).
+
+### StorageClient
+
+`connect` 콜백 안에서 받는 파일 작업 인터페이스. `FtpStorageClient`·`SftpStorageClient` 가 구현. 모든 메서드는 `Promise` 반환. 경로는 원격 기준 경로 문자열.
 
 ```ts
 interface StorageClient {
@@ -83,33 +98,24 @@ interface StorageClient {
 - `rename(fromPath, toPath)` — 파일/디렉토리 경로 이동·이름 변경. `toPath` 로 옮기거나 새 이름을 부여할 때.
 - `list(dirPath)` — 디렉토리 내 항목을 `FileInfo[]` 로 반환. 목록을 파일/폴더로 갈라 처리할 때.
 - `readFile(filePath)` — 원격 파일 전체를 `Bytes`(Uint8Array) 로 메모리에 다운로드(스트리밍 아님 — 큰 파일은 메모리 부담). 텍스트가 필요하면 호출 측에서 디코딩. SFTP 는 응답이 예상 타입(Buffer/string) 이 아니면 `SdError` throw.
-- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 없음·권한·네트워크 오류 포함) 에 대해 `false` 반환** — true/false 외 throw 없음. 따라서 `true` 만 "확실히 존재"로 신뢰한다. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록으로 디렉토리 확인(슬래시 없는 경로는 루트 `/` 기준이라 항목 많은 디렉토리에서는 느려질 수 있음). SFTP 는 `exists()` 결과가 문자열(`'d'`/`'-'`/`'l'`)이면 존재로 판정. 작업 전 분기 확인에 사용.
-- `put(localPathOrBuffer, storageFilePath)` — 단일 파일 업로드. 첫 인자가 `string` 이면 로컬 파일 경로에서, `Bytes` 면 메모리 바이트에서 업로드. 생성된 콘텐츠를 바로 올릴 땐 `Bytes` 로 전달.
-- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 전체를 원격 디렉토리로 재귀 업로드. 빌드 산출물 폴더 통째로 배포할 때.
+- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 없음·권한·네트워크 오류 포함) 에 대해 `false` 반환** — throw 없음이므로 `true` 만 "확실히 존재"로 신뢰한다. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록으로 디렉토리 확인(슬래시 없는 경로는 루트 `/` 기준이라 항목 많은 디렉토리에서는 느려질 수 있음). SFTP 는 `exists()` 결과가 문자열(`'d'`/`'-'`/`'l'`)이면 존재로 판정. 작업 전 분기 확인에 사용.
+- `put(localPathOrBuffer, storageFilePath)` — 단일 파일 업로드. 첫 인자가 `string` 이면 로컬 파일 경로에서, `Bytes` 면 메모리 바이트에서 업로드. 생성한 콘텐츠를 바로 올릴 땐 `Bytes` 로 전달.
+- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 전체를 원격 디렉토리로 재귀 업로드. 빌드 산출물 폴더를 통째로 배포할 때.
 - `remove(filePath)` — 원격 파일 삭제.
 - `close()` — 연결 종료. 이미 종료/미연결 상태에서 호출해도 오류 없음. 종료 후 같은 인스턴스에서 `connect()` 로 재연결 가능. `StorageFactory.connect` 사용 시 직접 호출 불필요.
 
 미연결 상태에서 작업 메서드를 호출하면 모든 구현체가 `SdError`("연결되어 있지 않습니다") throw.
 
-## FileInfo
-
-```ts
-interface FileInfo { name: string; isFile: boolean; }
-```
-
-- `name: string` — 항목 이름(파일명 또는 디렉토리명, 경로 아님).
-- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. 디렉토리 탐색 시 파일만 골라 처리하는 분기 기준으로 사용. SFTP 는 항목 type 이 `"-"` 인 경우만 `true`(디렉토리·심볼릭 링크는 `false`).
-
 ## FtpStorageClient / SftpStorageClient (직접 사용, 비권장)
 
-`StorageClient` 직접 구현체. 보통은 `StorageFactory.connect` 로 충분하며, 연결 수명을 콜백 밖에서 수동으로 다뤄야 할 때만 직접 생성한다. 두 구현체 모두 Node 전용(`basic-ftp`, `ssh2-sftp-client`, `fs`/`os`/`path`/`stream` 의존)이라 브라우저에서 사용 불가.
+`StorageClient` 직접 구현체. 보통은 `StorageFactory.connect` 로 충분하며, 연결 수명을 콜백 밖에서 수동으로 다뤄야 할 때만 직접 생성한다.
 
 ```ts
 new FtpStorageClient(secure?: boolean)  // secure=true → FTPS, 생략/false → 평문 FTP
 new SftpStorageClient()
 ```
 
-- `FtpStorageClient` 의 `secure` 생성자 인자 — `true` 면 TLS(FTPS), 생략/`false` 면 평문 FTP. 팩토리는 `ftps`→`true`, `ftp`→`false` 로 매핑.
+- `FtpStorageClient` 의 `secure` 생성자 인자 — `true` 면 TLS(FTPS), 생략/`false`(기본) 면 평문 FTP. 팩토리는 `"ftps"`→`true`, `"ftp"`→`false` 로 매핑.
 - `SftpStorageClient` 는 생성자 인자 없음. password 미지정 시 키/agent 인증 경로를 탄다(StorageConnConfig 의 `password` 풀이 참조).
 - 직접 사용 시 `connect()` → 작업 → `close()` 순으로 호출하고, 예외 발생 시에도 `close()` 가 호출되도록 `try/finally` 로 감쌀 것. 동일 인스턴스에서 `close()` 없이 `connect()` 를 재호출하면 연결 누수로 throw.