@rscc/common-core 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,10 @@
 # @rscc/common-core
 
-RSCC 공통 코어 — `CommonResponse` 봉투 타입, API 클라이언트 팩토리(traceId 발신/에코), SSE 프레임 파서, JWT 디코더, 시크릿 마스킹 유틸. **프레임워크 무관, 런타임 의존성 0.**
+RSCC 공통 코어 — `CommonResponse` 봉투 타입과 API 클라이언트(traceId·재시도·멱등성 키·쿠키 인증/CSRF), SSE 파서,
+회복탄력성 유틸(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안 유틸(마스킹·로그 리댁션·
+웹훅 서명·JWT 디코드), 와이어 계약 헬퍼(날짜·목록 쿼리·벌크·업로드·피처 플래그), 한국 도메인 유틸.
+**프레임워크 무관, 런타임 의존성 0.** 같은 라이브러리의 Java·Python 구현과 동일한 와이어 계약·공유
+테스트 벡터로 시맨틱을 맞춘다.
 
 ## 설치
 
@@ -8,43 +12,160 @@ RSCC 공통 코어 — `CommonResponse` 봉투 타입, API 클라이언트 팩
 npm i @rscc/common-core
 ```
 
-- **Node >= 18** (전역 `fetch` / `Headers` / `ReadableStream` 전제)
+- **Node >= 20** 또는 모던 브라우저 (전역 `fetch` / `Headers` / `ReadableStream` / `crypto.subtle` 전제)
 - ESM + CJS 듀얼 빌드, 타입 선언(`.d.ts` / `.d.cts`) 동봉, `sideEffects: false`
+- 메인 엔트리 `@rscc/common-core` 는 브라우저 안전. Node 전용 기능은 서브패스 `@rscc/common-core/crypto` 로만 제공
 
-## 공개 API
+## 모듈 한눈에
 
 | 모듈 | 공개 API | 설명 |
 |---|---|---|
-| types | `CommonResponse<T>` · `PageResponse<T>` · `ResultCode` | 응답 봉투·페이지네이션(page 0 시작)·결과 코드(값은 문자열) |
-| apiClient | `createApiClient(config)` · `ApiError` · `ApiClient` · `ApiClientConfig` · `ApiResult<T>` | 봉투 언랩 · 401 콜백 · `X-Trace-Id` 발신/에코 |
-| sse | `parseSseFrame` · `readSseStream` · `SseFrameEvent` · `SseSource` · `SseCallbacks` | SSE 프레임 파싱 — 청크/멀티바이트 경계 안전, 모르는 키는 skip |
+| types | `CommonResponse<T>` · `PageResponse<T>` · `ResultCode` · `FieldErrorDetail` · `ValidationErrorData` · `isValidationErrorData` | 응답 봉투 · 페이지(page 0 시작) · 결과 코드(값은 문자열) · 검증 오류 봉투 타입 가드 |
+| apiClient | `createApiClient` · `ApiError` · `ApiClient` · `ApiClientConfig` · `ApiClientRetryOptions` · `ApiResult<T>` · `ApiRequestInfo` / `ApiResponseInfo` / `ApiErrorInfo` | 봉투 언랩 · 401 콜백 · `X-Trace-Id` 발신/에코 · opt-in 재시도/멱등성 키/`strictJson`/관측 훅 · 인증 모드(`getToken` bearer / `credentials`+`csrf` 쿠키) |
+| csrf | `csrfHeaderFor` · `readCookie` · `isUnsafeMethod` · `DEFAULT_CSRF_COOKIE_NAME` · `DEFAULT_CSRF_HEADER_NAME` · `CsrfOptions` | CSRF double-submit 헤더 계산 — 비안전 메서드 + 쿠키 존재 + 같은 출처/`allowedOrigins` 일 때만. SSR 안전 |
+| sse | `parseSseFrame` · `readSseStream` · `SseFrameEvent` · `SseSource` · `SseCallbacks` | SSE 프레임 파싱 — 청크·멀티바이트 경계 안전, 모르는 키는 skip |
 | jwt | `decodeJwtPayload` · `getTokenExpiry` · `isTokenExpired` | base64url 디코드만 — **서명 미검증**, 만료 판단은 fail-closed |
-| masking | `maskSecret` | 앞4+뒤4 노출, 8자 이하 전량 마스킹 (java `MaskingUtils` 와 동일 규칙) |
+| masking | `maskSecret` · `maskName` · `maskPhone` · `maskEmail` · `maskCardNumber` | 시크릿(앞4+뒤4)·이름·휴대폰·이메일·카드번호 마스킹 |
+| datetime | `toWireDateTime` · `toWireDate` · `parseWireDateTime` · `stripZone` | 오프셋 없는 LocalDateTime 와이어 형식 — `toISOString()`(Z) 의 9시간 스큐 차단 |
+| chosung | `toChosung` · `isChosungQuery` | 한글 초성 변환·초성 질의 판별 (자동완성) |
+| retry | `retry` · `isRetryableStatus` · `parseRetryAfterMs` · `RetryOptions` | 지수 백오프 + full jitter, 시간 예산, `Retry-After` 파싱 |
+| cache | `createTtlCache` · `TtlCache<K,V>` · `TtlCacheOptions` | TTL 캐시 + single-flight(동일 키 로더 1회 공유), lazy expiry |
+| circuitBreaker | `createCircuitBreaker` · `CircuitOpenError` · `CircuitBreaker` · `CircuitBreakerOptions` · `CircuitState` | 연속 실패 서킷 브레이커 — `execute(fn)` 권장, 취소는 무집계(`onIgnore`) |
+| tokenBucket | `createTokenBucket` · `TokenBucket` · `TokenBucketOptions` | 토큰버킷 레이트리미터 (연속 리필, 대기 없이 즉시 판정) |
+| bulkhead | `createBulkhead` · `BulkheadFullError` · `Bulkhead` · `BulkheadOptions` | 동시 실행 + 대기 슬롯 격벽, 만석 즉시 거부 |
+| logSanitize | `sanitizeLogValue` | 로그 인젝션 방지 — 제어 문자 공백 치환 + 길이 절단 |
+| bizno | `normalizeBusinessNumber` · `isValidBusinessNumber` · `isValidCorporateNumber` | 사업자(10)·법인(13)번호 체크섬 검증 |
+| idempotency | `generateIdempotencyKey` | 멱등성 키 생성 (apiClient `idempotency` 옵션으로 자동 부착 가능) |
+| webhook | `signWebhook` · `verifyWebhook` · `WEBHOOK_SIGNATURE_HEADER` | HMAC-SHA256 웹훅 서명/검증 (WebCrypto — async), 시크릿 로테이션 |
+| bulk | `isBulkResult` · `bulkFailures` · `createBulkResultBuilder` · `BulkResult` · `BulkResultItem` · `BulkResultBuilder` | 벌크/부분 실패 봉투 판별·생성 |
+| upload | `sniffFile` · `kindsForExtension` · `validateUpload` · `FileKind` · `UploadValidationResult` | 업로드 프리검증 — 크기·확장자·매직바이트 대조 |
+| query | `buildListQuery` · `ListQueryOptions` · `SortParam` | 목록 조회 쿼리(page/size/sort/필터) 빌더 |
+| featureFlags | `parseFlag` · `createFeatureFlags` · `FeatureFlagReader` | 피처 플래그 파싱 (참 집합 `true`/`1`/`on`/`yes`) |
+| rrn | `normalizeRrn` · `isValidRrn` · `isForeignerRrn` · `rrnChecksumOkLegacy` · `rrnBirthDate` | 주민등록번호 형식·생년월일 검증 (기본 검증은 **체크섬 미포함**) |
+| josa | `pickJosa` · `attachJosa` · `JosaPair` | 은/는·이/가 등 조사 자동 선택 |
+| age | `ageMan` · `ageByYear` · `ageInsurance` | 만 나이·연 나이·보험 나이 (입력 `"YYYY-MM-DD"` 문자열) |
+| phone | `normalizePhoneNumber` · `classifyPhoneNumber` · `formatPhoneNumber` · `toE164` · `PhoneType` | 전화번호 정규화·분류·포맷·E.164 변환 |
+| money | `toKoreanWords` · `toFormalNotation` · `abbreviateAmount` | 금액 한글 수사 · 공문서 표기(`금…원整`) · UI 약식(`1.2억`) |
+| businessDays | `createBusinessDays` · `BusinessDays` · `BusinessDaysOptions` | 영업일 계산 (공휴일 주입형 — 내장 공휴일 없음) |
+| jamo | `decomposeHangul` · `composeHangul` · `matchesHangul` | 두벌식 자모 분해·조합·혼합 질의 매칭 |
+| **crypto (서브패스)** | `encryptAesGcm` · `decryptAesGcm` · `CryptoError` — `@rscc/common-core/crypto` | AES-256/GCM (Java/Python 와이어 호환). **Node 전용** (`node:crypto`) |
 
 ## 사용 예시
 
 ### createApiClient — CommonResponse 언랩 + traceId
 
 ```ts
-import { createApiClient, ApiError } from "@rscc/common-core";
+import { createApiClient, ApiError, isValidationErrorData } from "@rscc/common-core";
 
 const api = createApiClient({
-  baseUrl: "https://api.example.com",              // 끝 슬래시 없이
-  getToken: () => localStorage.getItem("token"),  // 선택 — Authorization: Bearer 부착
+  baseUrl: "https://api.example.com",             // 끝 슬래시 유무 무관 — 경계 슬래시 자동 단일화
+  getToken: () => sessionStorage.getItem("token"), // 선택 — Authorization: Bearer 부착
   onUnauthorized: () => { /* 로그아웃/리다이렉트 정책은 소비자가 결정 */ },
+  // 선택: retry: { retries: 3 }, idempotency: {}, strictJson: true, onRequest/onResponse/onError
 });
 
-// 성공 봉투 → data 언랩
+// 성공 봉투 → data 언랩 (비봉투 JSON 은 그대로)
 const user = await api.request<UserInfo>("/api/v1/users/me");
 
-// 실패 봉투/HTTP 에러 → ApiError { code, message, status, traceId }
+// 문자열 body → Content-Type: application/json 자동 부착
+await api.request("/api/v1/items", { method: "POST", body: JSON.stringify(item) });
+
+// 실패 봉투/HTTP 에러 → ApiError { code, message, status, traceId, data, retryAfterMs }
 try {
   await api.request("/api/v1/things/999");
 } catch (e) {
-  if (e instanceof ApiError) console.error(`[${e.traceId}] ${e.code}: ${e.message}`);
+  if (e instanceof ApiError) {
+    console.error(`[${e.traceId}] ${e.code}: ${e.message}`);
+    if (isValidationErrorData(e.data)) { /* e.data.errors — 필드별 검증 오류 */ }
+  }
 }
+
+// traceId·status·원본 Response 가 필요하면
+const { data, traceId, response } = await api.requestWithMeta<UserInfo>("/api/v1/users/me");
+```
+
+- **Content-Type**: 호출자가 지정하지 않았고 body 가 **문자열**일 때만 `application/json` 을 붙인다.
+  body 없는 요청(GET 등)엔 붙이지 않으므로 교차 출처 GET 이 CORS preflight 를 유발하지 않는다.
+  `URLSearchParams`/`Blob`/`FormData`/`ArrayBuffer`/`ReadableStream` 은 fetch 기본값을 따른다.
+- **traceId**: 논리 호출당 1회 생성해 `X-Trace-Id` 로 부착(재시도 전 시도 동일), 응답 에코를 우선 노출.
+- **retry** (opt-in): 멱등 메서드(GET/HEAD/OPTIONS/PUT/DELETE)만 기본 재시도, 408/429/5xx 일부·네트워크
+  오류 대상, `Retry-After` 를 대기 하한으로 존중. POST/PATCH 는 `methods` 로 명시 옵트인.
+- **idempotency** (opt-in): POST/PATCH 에 `Idempotency-Key` 를 논리 호출당 1회 생성해 부착(호출자 헤더 우선).
+- **strictJson** (opt-in): 2xx 의 비-JSON 본문을 null 대신 `INVALID_JSON` ApiError 로 실패(`rawText` 앞 2048자
+  보존). 빈 본문(204 등)은 계속 null.
+- `requestWithMeta` 의 `response` 는 **본문 미소비 원본** — 파싱은 `clone()` 사본으로 하므로 `text()`/`json()`
+  재호출이 가능하다.
+
+### 인증 모드 — bearer vs 쿠키(jwt-cookie / session) + CSRF
+
+서버가 인증 자격을 어디로 받는지(서버 설정의 인증 모드)에 맞춰 클라이언트 설정을 고른다.
+
+| 서버 모드 | 자격 운반 | 클라이언트 설정 |
+|---|---|---|
+| `bearer` (기본) | `Authorization: Bearer <JWT>` | `getToken` |
+| `jwt-cookie` | HttpOnly 쿠키 (JS 가 토큰을 못 봄) | `credentials` + `csrf` |
+| `session` | 서버 세션 쿠키 | `credentials` + `csrf` |
+
+```ts
+// bearer — 토큰을 앱이 보관하고 헤더로 싣는다 (앱·서버 간 호출, 모바일 등)
+const bearerApi = createApiClient({ baseUrl: "https://api.example.com", getToken: () => tokenStore.get() });
+
+// jwt-cookie / session — 같은 출처(리버스 프록시로 프론트와 API 를 한 오리진에, 권장)
+const api = createApiClient({ baseUrl: "/api", credentials: "same-origin", csrf: true });
+
+// jwt-cookie / session — 같은 사이트 서브도메인 (app.example.com → api.example.com)
+const subdomainApi = createApiClient({
+  baseUrl: "https://api.example.com",
+  credentials: "include",                                   // 교차 출처로 쿠키 전송
+  csrf: { allowedOrigins: ["https://api.example.com"] },    // 이 오리진에만 CSRF 헤더 허용
+});
+
+// 로그인 상태 확인은 토큰 만료 계산(isTokenExpired) 대신 서버 엔드포인트로
+const me = await api.request<UserInfo>("/api/v1/users/me").catch(() => null);
+```
+
+- **`credentials`**: fetch `credentials` 기본값. 미지정이면 속성 자체를 넘기지 않는다(fetch 기본 `"same-origin"`).
+  호출별 `init.credentials` 가 우선한다.
+- **`csrf`** (double-submit): 서버가 내려준 HttpOnly 아닌 쿠키 `XSRF-TOKEN` 값을 `X-XSRF-TOKEN` 헤더로 되돌려 보낸다.
+  **비안전 메서드**(GET·HEAD·OPTIONS·TRACE 외)이고 쿠키가 있으며 요청 URL 이 **같은 출처**(상대 URL 포함)이거나
+  `allowedOrigins` 에 속할 때만 붙인다 — 교차 출처로는 보내지 않는다(토큰 유출 방지). 호출자가 이미 실은 헤더는
+  덮어쓰지 않고, 재시도마다 쿠키를 다시 읽는다(토큰 회전 대응).
+- `CsrfOptions`: `cookieName`(기본 `XSRF-TOKEN`) · `headerName`(기본 `X-XSRF-TOKEN`) · `allowedOrigins`(오리진 정규화 비교,
+  와일드카드 없음) · `readCookie`(원시 쿠키 문자열 공급자 — `document` 가 없는 React Native·테스트용).
+- `document` 가 없는 환경(SSR·Node)에서는 `readCookie` 주입이 없으면 아무것도 붙이지 않고 오류도 내지 않는다.
+  모듈 로드 시점에 `document`/`location` 에 접근하지 않는다.
+- 쿠키 모드의 웹 클라이언트는 **토큰을 localStorage/sessionStorage 에 저장하지 않는다** — 웹이 다시 헤더 토큰을 쓰면
+  HttpOnly 쿠키로 막은 XSS 토큰 탈취 경로가 되살아난다(`getToken` 은 앱·서버 간 호출용).
+- 서브도메인 토폴로지는 서버 쪽도 맞춰야 한다 — CSRF 쿠키 `Domain` 을 상위 도메인으로(프론트 JS 가 읽도록), CORS 가
+  자격 허용(`Access-Control-Allow-Credentials: true` + 명시 오리진)과 `X-XSRF-TOKEN` 요청 헤더를 허용.
+
+헬퍼를 직접 쓸 수도 있다 (axios 인터셉터 등 다른 HTTP 클라이언트 — 서버는 CSRF 토큰을 헤더로만 받는다):
+
+```ts
+import { csrfHeaderFor, readCookie } from "@rscc/common-core";
+
+csrfHeaderFor("/api/v1/items", "POST", true);  // ["X-XSRF-TOKEN", "<쿠키 값>"] | null
+readCookie("XSRF-TOKEN");                      // document.cookie 에서 첫 값 (디코딩 안 함) | null
 ```
 
+### 서킷 브레이커 — execute 권장
+
+```ts
+import { createCircuitBreaker, CircuitOpenError, retry } from "@rscc/common-core";
+
+const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+
+// 게이트 → 실행 → 결과 보고를 정확히 1회 보장. OPEN 이면 fn 미호출 + CircuitOpenError
+await retry(() => cb.execute(() => api.request("/api/v1/downstream")), {
+  shouldRetry: (e) => !(e instanceof CircuitOpenError), // OPEN 차단은 즉시 실패
+});
+```
+
+- resolve → 성공, `name === "AbortError"` → 무집계(`onIgnore`), 그 외 throw → 실패로 집계 후 **같은 오류를 그대로** rethrow.
+- 수동 게이트(`allowRequest()` + `onSuccess`/`onFailure`/`onIgnore` 중 정확히 1회)도 지원한다.
+- 보고가 끝내 오지 않은 그랜트는 OPEN 진입 후 `2 × openDurationMs` 에 유실로 용서되어 OPEN 영구 고착을 막는다.
+  HALF_OPEN 프로브도 `openDurationMs` 동안 미보고면 유실로 간주해 새 프로브를 넘긴다(HALF_OPEN 고착 방지).
+
 ### SSE 스트림 소비
 
 ```ts
@@ -52,24 +173,44 @@ import { readSseStream } from "@rscc/common-core";
 
 const res = await fetch(streamUrl, { method: "POST", body, signal });
 await readSseStream(res, {
-  onDelta: (chunk) => { /* 텍스트 증분 */ },
+  onConversationId: (id) => { /* 첫 프레임 */ },
   onSources: (sources) => { /* RAG 근거 */ },
+  onDelta: (chunk) => { /* 텍스트 증분 */ },
   onError: (message) => { /* in-band 오류 */ },
   onDone: () => { /* data: [DONE] */ },
 });
 ```
 
-## 알려진 제약
+### AES-256/GCM — Node 전용 서브패스
 
-- SSE 파서는 프레임 구분자 **LF(`\n\n`) 고정** — CRLF 로 정규화하는 프록시 뒤에서는 프레임이 분리되지 않는다.
-- `baseUrl` 은 **끝 슬래시 없이** 지정할 것 — path 와 단순 연결하며 정규화하지 않는다.
-- `requestWithMeta` 의 `ApiResult.response` 는 body 가 이미 소비된 상태 — headers/status 조회용.
-- 2xx 응답인데 본문이 JSON 이 아니면 `data` 는 조용히 null 이 된다.
-- JWT 디코더는 **서명을 검증하지 않는다** — 표시·만료 판단 전용. 인가 판단은 반드시 서버에서.
+```ts
+import { encryptAesGcm, decryptAesGcm, CryptoError } from "@rscc/common-core/crypto";
 
-## 문서 / 저장소
+const enc = encryptAesGcm("민감값", key); // Base64(IV(12B)∥암호문∥태그(16B)) — 매번 다름
+const dec = decryptAesGcm(enc, key);      // 키 상이·변조 시 CryptoError
+```
+
+## 알려진 제약
 
-- 상세 문서: [js/README.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/js/README.md)
-- 와이어 계약(단일 소스): [contracts/](https://github.com/Jeonghyeon-Ryu/r-common/tree/master/contracts)
-- React 훅: [@rscc/common-react](https://www.npmjs.com/package/@rscc/common-react)
-- 저장소: [Jeonghyeon-Ryu/r-common](https://github.com/Jeonghyeon-Ryu/r-common) · MIT
+- **SSE 파서는 프레임 구분자 LF(`\n\n`) 고정** — 개행을 CRLF 로 정규화하는 프록시 뒤에서는 프레임이 분리되지 않는다.
+- 2xx 응답인데 본문이 JSON 이 아니면 `data` 는 기본적으로 조용히 null 이 된다 — 명시 실패가 필요하면 `strictJson: true`.
+- 문자열 body 는 `application/json` 으로 간주된다 — JSON 이 아닌 문자열 본문은 Content-Type 을 직접 지정할 것.
+- 교차 출처에서 traceId 에코를 읽으려면 서버가 `Access-Control-Expose-Headers: X-Trace-Id` 를 내려야 한다
+  (못 읽으면 발신 값을 노출 — 서버가 수신 traceId 를 재사용하므로 동일 값).
+- 1회성 body(`ReadableStream`/`FormData`)는 재전송이 불가해 `retry` 를 지정해도 1회만 실행된다.
+- JWT 디코더는 **서명을 검증하지 않는다** — 표시·만료 판단 전용. 인가 판단은 반드시 서버에서.
+  쿠키 인증 모드(HttpOnly 쿠키)에서는 JS 가 토큰을 볼 수 없으므로 `/me` 같은 서버 엔드포인트로 상태를 확인할 것.
+- `csrf` 는 교차 출처 요청에 헤더를 붙이지 않는다 — 서브도메인 API 는 `allowedOrigins` 에 명시해야 한다.
+  CSRF 쿠키를 읽으려면 그 쿠키가 프론트 페이지 도메인에서 보여야 한다(서버 `Domain` 설정).
+- `isValidRrn` 은 체크섬을 포함하지 않는다(2020-10 이후 발급분은 체크섬 불성립) — `rrnChecksumOkLegacy` 는 레거시 정합 검사 전용.
+- `signWebhook`/`verifyWebhook` 은 WebCrypto 기반이라 **async** 다 (Java/Python 은 동기).
+- 서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시는 **인스턴스(프로세스) 로컬** 상태다 — 분산 공유되지 않는다.
+- `@rscc/common-core/crypto` 는 `node:crypto` 를 쓰는 **Node 전용** 서브패스 — 브라우저 번들에 포함하지 말 것.
+- 서브패스는 `exports` 맵으로만 노출된다 — TypeScript `moduleResolution` 이 레거시 `node`(`node10`)면
+  `@rscc/common-core/crypto` 의 타입을 찾지 못한다. `node16` / `nodenext` / `bundler` 를 사용할 것
+  (메인 엔트리 `@rscc/common-core` 는 모든 모드에서 해석된다).
+
+## 관련 패키지
+
+- React 훅(`useDebounce`, `useSse`): [@rscc/common-react](https://www.npmjs.com/package/@rscc/common-react)
+- 라이선스: MIT

package/dist/index.cjs

@@ -22,6 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   ApiError: () => ApiError,
   BulkheadFullError: () => BulkheadFullError,
+  CircuitOpenError: () => CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME: () => DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME: () => DEFAULT_CSRF_HEADER_NAME,
   ResultCode: () => ResultCode,
   WEBHOOK_SIGNATURE_HEADER: () => WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount: () => abbreviateAmount,
@@ -41,6 +44,7 @@ __export(index_exports, {
   createFeatureFlags: () => createFeatureFlags,
   createTokenBucket: () => createTokenBucket,
   createTtlCache: () => createTtlCache,
+  csrfHeaderFor: () => csrfHeaderFor,
   decodeJwtPayload: () => decodeJwtPayload,
   decomposeHangul: () => decomposeHangul,
   formatPhoneNumber: () => formatPhoneNumber,
@@ -51,6 +55,7 @@ __export(index_exports, {
   isForeignerRrn: () => isForeignerRrn,
   isRetryableStatus: () => isRetryableStatus,
   isTokenExpired: () => isTokenExpired,
+  isUnsafeMethod: () => isUnsafeMethod,
   isValidBusinessNumber: () => isValidBusinessNumber,
   isValidCorporateNumber: () => isValidCorporateNumber,
   isValidRrn: () => isValidRrn,
@@ -70,6 +75,7 @@ __export(index_exports, {
   parseSseFrame: () => parseSseFrame,
   parseWireDateTime: () => parseWireDateTime,
   pickJosa: () => pickJosa,
+  readCookie: () => readCookie,
   readSseStream: () => readSseStream,
   retry: () => retry,
   rrnBirthDate: () => rrnBirthDate,
@@ -111,6 +117,93 @@ var ResultCode = {
   INTERNAL_SERVER_ERROR: "500"
 };
 
+// src/csrf.ts
+var DEFAULT_CSRF_COOKIE_NAME = "XSRF-TOKEN";
+var DEFAULT_CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+var SENTINEL_ORIGIN = "http://rscc-csrf.invalid";
+var ABSOLUTE_URL = /^([a-zA-Z][a-zA-Z\d+.-]*):\/\/([^/?#\\]*)/;
+var HAS_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+var PROTOCOL_RELATIVE = /^[\\/]{2}/;
+var DEFAULT_PORTS = { http: "80", https: "443", ws: "80", wss: "443" };
+function readCookie(name, cookieString) {
+  const source = cookieString ?? documentCookie();
+  if (!source) return null;
+  for (const part of source.split(";")) {
+    const pair = part.trim();
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    if (pair.slice(0, eq) === name) return pair.slice(eq + 1);
+  }
+  return null;
+}
+function isUnsafeMethod(method) {
+  return !SAFE_METHODS.has((method || "GET").toUpperCase());
+}
+function csrfHeaderFor(url, method, options) {
+  if (!isUnsafeMethod(method)) return null;
+  const opts = options === true || options === void 0 ? {} : options;
+  const cookieString = opts.readCookie ? opts.readCookie() : documentCookie();
+  if (!cookieString) return null;
+  const token = readCookie(opts.cookieName ?? DEFAULT_CSRF_COOKIE_NAME, cookieString);
+  if (!token) return null;
+  if (!isAllowedTarget(url, opts.allowedOrigins)) return null;
+  return [opts.headerName ?? DEFAULT_CSRF_HEADER_NAME, token];
+}
+function documentCookie() {
+  if (typeof document === "undefined") return null;
+  try {
+    return typeof document.cookie === "string" ? document.cookie : null;
+  } catch {
+    return null;
+  }
+}
+function currentLocation() {
+  if (typeof location === "undefined") return null;
+  try {
+    const { href, origin } = location;
+    return typeof href === "string" && typeof origin === "string" ? { href, origin } : null;
+  } catch {
+    return null;
+  }
+}
+function isAllowedTarget(url, allowedOrigins) {
+  const loc = currentLocation();
+  const base = loc ? loc.href : SENTINEL_ORIGIN;
+  const selfOrigin = loc ? loc.origin : SENTINEL_ORIGIN;
+  const target = originOf(url, base, selfOrigin);
+  if (target === null || target === "null") return false;
+  if (selfOrigin !== "null" && target === selfOrigin) return true;
+  if (!allowedOrigins || allowedOrigins.length === 0) return false;
+  return allowedOrigins.some((entry) => originOf(entry, base, selfOrigin) === target);
+}
+function originOf(url, base, baseOrigin) {
+  try {
+    if (typeof URL === "function") {
+      const origin = new URL(url, base).origin;
+      if (typeof origin === "string") return origin;
+    }
+  } catch {
+  }
+  return looseOriginOf(url, baseOrigin);
+}
+function looseOriginOf(url, baseOrigin) {
+  const trimmed = url.trim();
+  const m = ABSOLUTE_URL.exec(trimmed);
+  if (m) {
+    const scheme = m[1].toLowerCase();
+    const authority = m[2];
+    const hostPort = authority.slice(authority.lastIndexOf("@") + 1).toLowerCase();
+    const hp = /^(.*?)(?::(\d*))?$/.exec(hostPort);
+    const host = hp?.[1] ?? "";
+    const port = hp?.[2] ?? "";
+    if (!host) return null;
+    return port === "" || port === DEFAULT_PORTS[scheme] ? `${scheme}://${host}` : `${scheme}://${host}:${port}`;
+  }
+  if (PROTOCOL_RELATIVE.test(trimmed) || HAS_SCHEME.test(trimmed)) return null;
+  return baseOrigin;
+}
+
 // src/idempotency.ts
 var FALLBACK_GROUPS = [8, 4, 4, 4, 12];
 function generateIdempotencyKey() {
@@ -254,6 +347,8 @@ function createApiClient(config) {
   async function requestWithMeta(path, init = {}) {
     const sentTraceId = generateTraceId();
     const method = (init.method ?? "GET").toUpperCase();
+    const url = joinUrl(config.baseUrl, path);
+    const credentials = init.credentials ?? config.credentials;
     const idempotencyHeader = config.idempotency?.header ?? "Idempotency-Key";
     const idempotencyKey = config.idempotency && (config.idempotency.methods ?? DEFAULT_IDEMPOTENCY_METHODS).includes(method) ? generateIdempotencyKey() : null;
     const attemptOnce = async () => {
@@ -262,16 +357,23 @@ function createApiClient(config) {
       if (idempotencyKey !== null && !headers.has(idempotencyHeader)) {
         headers.set(idempotencyHeader, idempotencyKey);
       }
-      const isFormData = typeof FormData !== "undefined" && init.body instanceof FormData;
-      if (!headers.has("Content-Type") && !isFormData) {
+      if (!headers.has("Content-Type") && typeof init.body === "string") {
         headers.set("Content-Type", "application/json");
       }
       if (config.getToken && !headers.has("Authorization")) {
         const token = config.getToken();
         if (token) headers.set("Authorization", `Bearer ${token}`);
       }
+      if (config.csrf) {
+        const csrfHeader = csrfHeaderFor(url, method, config.csrf);
+        if (csrfHeader && !headers.has(csrfHeader[0])) headers.set(csrfHeader[0], csrfHeader[1]);
+      }
       const fetchFn = config.fetchImpl ?? globalThis.fetch;
-      const response = await fetchFn(joinUrl(config.baseUrl, path), { ...init, headers });
+      const response = await fetchFn(url, {
+        ...init,
+        ...credentials !== void 0 ? { credentials } : {},
+        headers
+      });
       const traceId = response.headers.get(traceIdHeader) ?? sentTraceId;
       let raw = null;
       try {
@@ -685,6 +787,12 @@ function createTtlCache(options) {
 }
 
 // src/circuitBreaker.ts
+var CircuitOpenError = class extends Error {
+  constructor(message = "\uC11C\uD0B7 OPEN \u2014 \uC694\uCCAD \uCC28\uB2E8") {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+};
 function createCircuitBreaker(options) {
   const { failureThreshold, openDurationMs, now = Date.now } = options;
   if (!Number.isInteger(failureThreshold) || failureThreshold <= 0) {
@@ -697,6 +805,7 @@ function createCircuitBreaker(options) {
   let consecutiveFailures = 0;
   let openedAtMs = 0;
   let probeInFlight = false;
+  let probeStartedAtMs = 0;
   let inFlightGrants = 0;
   function allowRequest() {
     if (state === "CLOSED") {
@@ -704,18 +813,24 @@ function createCircuitBreaker(options) {
       return true;
     }
     if (state === "OPEN") {
-      if (now() - openedAtMs >= openDurationMs) {
-        if (inFlightGrants > 0) {
+      const nowMs2 = now();
+      const elapsedMs = nowMs2 - openedAtMs;
+      if (elapsedMs < openDurationMs) return false;
+      if (inFlightGrants > 0) {
+        if (elapsedMs < 2 * openDurationMs) {
           return false;
         }
-        state = "HALF_OPEN";
-        probeInFlight = true;
-        return true;
+        inFlightGrants = 0;
       }
-      return false;
+      state = "HALF_OPEN";
+      probeInFlight = true;
+      probeStartedAtMs = nowMs2;
+      return true;
     }
-    if (probeInFlight) return false;
+    const nowMs = now();
+    if (probeInFlight && nowMs - probeStartedAtMs < openDurationMs) return false;
     probeInFlight = true;
+    probeStartedAtMs = nowMs;
     return true;
   }
   function onSuccess() {
@@ -750,13 +865,40 @@ function createCircuitBreaker(options) {
     }
     inFlightGrants = Math.max(0, inFlightGrants - 1);
   }
+  function onIgnore() {
+    if (state === "HALF_OPEN") {
+      probeInFlight = false;
+      return;
+    }
+    inFlightGrants = Math.max(0, inFlightGrants - 1);
+  }
+  async function execute(fn) {
+    if (!allowRequest()) {
+      throw new CircuitOpenError();
+    }
+    let result;
+    try {
+      result = await fn();
+    } catch (error) {
+      if (isAbortError(error)) onIgnore();
+      else onFailure();
+      throw error;
+    }
+    onSuccess();
+    return result;
+  }
   return {
     allowRequest,
     onSuccess,
     onFailure,
+    onIgnore,
+    execute,
     state: () => state
   };
 }
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
 
 // src/tokenBucket.ts
 function createTokenBucket(options) {
@@ -1738,6 +1880,9 @@ function matchesHangul(query, target) {
 0 && (module.exports = {
   ApiError,
   BulkheadFullError,
+  CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1757,6 +1902,7 @@ function matchesHangul(query, target) {
   createFeatureFlags,
   createTokenBucket,
   createTtlCache,
+  csrfHeaderFor,
   decodeJwtPayload,
   decomposeHangul,
   formatPhoneNumber,
@@ -1767,6 +1913,7 @@ function matchesHangul(query, target) {
   isForeignerRrn,
   isRetryableStatus,
   isTokenExpired,
+  isUnsafeMethod,
   isValidBusinessNumber,
   isValidCorporateNumber,
   isValidRrn,
@@ -1786,6 +1933,7 @@ function matchesHangul(query, target) {
   parseSseFrame,
   parseWireDateTime,
   pickJosa,
+  readCookie,
   readSseStream,
   retry,
   rrnBirthDate,