@rscc/common-core 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @rscc/common-core
 
-RSCC 공통 코어 — `CommonResponse` 봉투 타입과 API 클라이언트(traceId·재시도·멱등성 키), SSE 파서,
+RSCC 공통 코어 — `CommonResponse` 봉투 타입과 API 클라이언트(traceId·재시도·멱등성 키·쿠키 인증/CSRF), SSE 파서,
 회복탄력성 유틸(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안 유틸(마스킹·로그 리댁션·
 웹훅 서명·JWT 디코드), 와이어 계약 헬퍼(날짜·목록 쿼리·벌크·업로드·피처 플래그), 한국 도메인 유틸.
 **프레임워크 무관, 런타임 의존성 0.** 같은 라이브러리의 Java·Python 구현과 동일한 와이어 계약·공유
@@ -12,7 +12,7 @@ RSCC 공통 코어 — `CommonResponse` 봉투 타입과 API 클라이언트(tra
 npm i @rscc/common-core
 ```
 
-- **Node >= 18** 또는 모던 브라우저 (전역 `fetch` / `Headers` / `ReadableStream` / `crypto.subtle` 전제)
+- **Node >= 20** 또는 모던 브라우저 (전역 `fetch` / `Headers` / `ReadableStream` / `crypto.subtle` 전제)
 - ESM + CJS 듀얼 빌드, 타입 선언(`.d.ts` / `.d.cts`) 동봉, `sideEffects: false`
 - 메인 엔트리 `@rscc/common-core` 는 브라우저 안전. Node 전용 기능은 서브패스 `@rscc/common-core/crypto` 로만 제공
 
@@ -21,7 +21,8 @@ npm i @rscc/common-core
 | 모듈 | 공개 API | 설명 |
 |---|---|---|
 | 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`/관측 훅 |
+| 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` · `maskName` · `maskPhone` · `maskEmail` · `maskCardNumber` | 시크릿(앞4+뒤4)·이름·휴대폰·이메일·카드번호 마스킹 |
@@ -95,6 +96,58 @@ const { data, traceId, response } = await api.requestWithMeta<UserInfo>("/api/v1
 - `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
@@ -146,10 +199,16 @@ const dec = decryptAesGcm(enc, key);      // 키 상이·변조 시 CryptoError
   (못 읽으면 발신 값을 노출 — 서버가 수신 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` 는 모든 모드에서 해석된다).
 
 ## 관련 패키지
 

package/dist/index.cjs

@@ -23,6 +23,8 @@ __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,
@@ -42,6 +44,7 @@ __export(index_exports, {
   createFeatureFlags: () => createFeatureFlags,
   createTokenBucket: () => createTokenBucket,
   createTtlCache: () => createTtlCache,
+  csrfHeaderFor: () => csrfHeaderFor,
   decodeJwtPayload: () => decodeJwtPayload,
   decomposeHangul: () => decomposeHangul,
   formatPhoneNumber: () => formatPhoneNumber,
@@ -52,6 +55,7 @@ __export(index_exports, {
   isForeignerRrn: () => isForeignerRrn,
   isRetryableStatus: () => isRetryableStatus,
   isTokenExpired: () => isTokenExpired,
+  isUnsafeMethod: () => isUnsafeMethod,
   isValidBusinessNumber: () => isValidBusinessNumber,
   isValidCorporateNumber: () => isValidCorporateNumber,
   isValidRrn: () => isValidRrn,
@@ -71,6 +75,7 @@ __export(index_exports, {
   parseSseFrame: () => parseSseFrame,
   parseWireDateTime: () => parseWireDateTime,
   pickJosa: () => pickJosa,
+  readCookie: () => readCookie,
   readSseStream: () => readSseStream,
   retry: () => retry,
   rrnBirthDate: () => rrnBirthDate,
@@ -112,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() {
@@ -255,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 () => {
@@ -270,8 +364,16 @@ function createApiClient(config) {
         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 {
@@ -1779,6 +1881,8 @@ function matchesHangul(query, target) {
   ApiError,
   BulkheadFullError,
   CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1798,6 +1902,7 @@ function matchesHangul(query, target) {
   createFeatureFlags,
   createTokenBucket,
   createTtlCache,
+  csrfHeaderFor,
   decodeJwtPayload,
   decomposeHangul,
   formatPhoneNumber,
@@ -1808,6 +1913,7 @@ function matchesHangul(query, target) {
   isForeignerRrn,
   isRetryableStatus,
   isTokenExpired,
+  isUnsafeMethod,
   isValidBusinessNumber,
   isValidCorporateNumber,
   isValidRrn,
@@ -1827,6 +1933,7 @@ function matchesHangul(query, target) {
   parseSseFrame,
   parseWireDateTime,
   pickJosa,
+  readCookie,
   readSseStream,
   retry,
   rrnBirthDate,

package/dist/index.d.cts

@@ -75,6 +75,79 @@ declare const ResultCode: {
 /** ResultCode 코드 값의 유니온 타입 ("200" | "400" | ...). */
 type ResultCode = (typeof ResultCode)[keyof typeof ResultCode];
 
+/**
+ * CSRF double-submit 클라이언트 헬퍼 — contracts/session-auth.md §4·§5 (수동 동기화).
+ *
+ * 쿠키 운반 인증 모드(`jwt-cookie` / `session`)에서 서버는 CSRF 토큰을 HttpOnly 가 아닌 쿠키
+ * (`XSRF-TOKEN`)로 발급하고, 클라이언트는 **비안전 메서드** 요청마다 그 값을 헤더(`X-XSRF-TOKEN`)에
+ * 되돌려 보낸다. 서버는 쿠키 값과 헤더 값의 동등성만 확인한다.
+ *
+ * 부착 규칙 (골든 벡터 XC-01~08):
+ * - 비안전 메서드(GET·HEAD·OPTIONS·TRACE 외)일 때만.
+ * - CSRF 쿠키가 있고 값이 비어 있지 않을 때만 (없으면 부착 안 함 — 오류 없음).
+ * - 요청 URL 이 **같은 출처**(상대 URL 포함)이거나 명시한 `allowedOrigins` 에 속할 때만 —
+ *   교차 출처로는 보내지 않는다(토큰 유출 방지).
+ * - `document` 가 없는 환경(SSR·Node)에서는 `readCookie` 주입이 없으면 아무것도 붙이지 않는다.
+ *
+ * SSR 안전: 모듈 로드 시점에 `document`/`location` 에 접근하지 않는다 (호출 시점에만 존재 확인).
+ */
+/** CSRF 토큰 쿠키 기본 이름 (contracts/session-auth.md §2.1). */
+declare const DEFAULT_CSRF_COOKIE_NAME = "XSRF-TOKEN";
+/** CSRF 요청 헤더 기본 이름 — Spring `CookieCsrfTokenRepository` 관례 (contracts/session-auth.md §2.1). */
+declare const DEFAULT_CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+/** CSRF 헤더 자동 부착 옵션 (apiClient `csrf` / useSse `csrf`). */
+interface CsrfOptions {
+    /** CSRF 토큰 쿠키 이름. 기본 {@link DEFAULT_CSRF_COOKIE_NAME} (`"XSRF-TOKEN"`) — 서버 설정과 일치시킬 것. */
+    cookieName?: string;
+    /** CSRF 요청 헤더 이름. 기본 {@link DEFAULT_CSRF_HEADER_NAME} (`"X-XSRF-TOKEN"`). */
+    headerName?: string;
+    /**
+     * 같은 출처 외에 헤더를 보내도 되는 **오리진** 목록 (예: `["https://api.example.com"]`) —
+     * 같은 사이트 서브도메인 토폴로지(`app.example.com` → `api.example.com`, contracts §8)용.
+     * 항목은 `scheme://host[:port]` 로 정규화해 비교한다(경로·끝 슬래시·대소문자·기본 포트 무관).
+     * 와일드카드는 지원하지 않는다. 기본: 없음 (같은 출처만).
+     */
+    allowedOrigins?: readonly string[];
+    /**
+     * **원시 쿠키 문자열**(`"a=1; XSRF-TOKEN=abc"` 형태) 공급자 — `document.cookie` 대신 쓴다
+     * (React Native·테스트 등 `document` 가 없는 환경). null/undefined 반환은 쿠키 없음.
+     * 기본: `document` 가 있으면 `document.cookie`, 없으면 쿠키 없음.
+     */
+    readCookie?: () => string | null | undefined;
+}
+/**
+ * 원시 쿠키 문자열에서 `name` 쿠키 값을 읽는다 (contracts/session-auth.md §2.3).
+ *
+ * - `;` 로 나누고 각 조각의 앞뒤 공백을 제거한 뒤 **첫 `=`** 기준으로 이름·값을 가른다.
+ * - 이름은 **대소문자 구분 정확 일치**, 같은 이름이 여럿이면 **첫 값**(XC-08).
+ * - 값은 디코딩하지 않는다(`decodeURIComponent` 미적용). 빈 값(`name=`)은 `""` 를 반환한다.
+ * - `cookieString` 생략 시 `document` 가 있으면 `document.cookie` 를 쓰고, 없으면(SSR·Node) null.
+ *   `document.cookie` 접근 자체가 실패하는 환경(샌드박스 iframe 등)도 null.
+ *
+ * @returns 쿠키 값, 해당 쿠키가 없으면 null.
+ */
+declare function readCookie(name: string, cookieString?: string): string | null;
+/**
+ * 비안전 메서드 여부 — GET·HEAD·OPTIONS·TRACE 외 전부 true (대소문자 무관).
+ * `method` 생략(또는 빈 문자열)은 fetch 기본값 GET 으로 보아 false.
+ */
+declare function isUnsafeMethod(method?: string): boolean;
+/**
+ * 요청 하나에 붙일 CSRF 헤더를 계산한다 — 붙여야 하면 `[헤더명, 쿠키값]`, 아니면 null.
+ *
+ * 판정 순서: 비안전 메서드? → CSRF 쿠키 있음(빈 값 제외)? → 같은 출처(상대 URL, 또는 `location` 이
+ * 있을 때 그 오리진과 같은 절대 URL) 또는 `allowedOrigins` 소속? → 부착 (골든 벡터 XC-01~05·07·08).
+ * 호출자가 이미 같은 헤더를 실었는지(XC-06)는 호출 측(apiClient·useSse)이 확인한다.
+ *
+ * 오류를 던지지 않는다 — `document`·`readCookie` 가 모두 없으면(SSR) null. URL 을 해석할 수 없으면
+ * 교차 출처로 간주해 null (토큰 유출 방지 쪽으로 실패).
+ *
+ * @param url 요청 URL (상대/절대). 상대 URL 은 같은 출처로 본다.
+ * @param method HTTP 메서드. 생략 시 GET.
+ * @param options `true` 또는 생략 = 기본값, 객체 = {@link CsrfOptions}.
+ */
+declare function csrfHeaderFor(url: string, method: string | undefined, options?: true | CsrfOptions): [name: string, value: string] | null;
+
 /**
  * 아웃바운드 회복탄력성 — 지수 백오프 + full jitter 재시도. 런타임 의존성 0(native 만).
  *
@@ -229,8 +302,34 @@ interface ApiClientConfig {
      * 상대 baseUrl("/api")도 지원.
      */
     baseUrl: string;
-    /** 토큰 공급자. 지정 시 반환값이 truthy 면 `Authorization: Bearer <token>` 부착. */
+    /**
+     * 토큰 공급자 (`bearer` 모드). 지정 시 반환값이 truthy 면 `Authorization: Bearer <token>` 부착
+     * (호출자가 Authorization 을 이미 실었으면 덮어쓰지 않음). 쿠키 모드(`jwt-cookie`/`session`)의
+     * 웹 클라이언트는 쓰지 않는다 — `credentials`·`csrf` 참조.
+     */
     getToken?: () => string | null | undefined;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 같은 출처 API 는 `"same-origin"`(fetch 기본값과 같음), 서브도메인 등 교차 출처 API 는 `"include"`.
+     *
+     * - 미지정 = fetch 에 `credentials` 속성 자체를 넘기지 않는다 (현행 동작 — fetch 기본값 `"same-origin"`).
+     * - 호출별 `init.credentials` 가 있으면 그 값이 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (contracts/session-auth.md §4·§5, 골든 벡터 XC-01~08).
+     * `true` = 기본값(쿠키 `XSRF-TOKEN` → 헤더 `X-XSRF-TOKEN`, 같은 출처만), 객체 = {@link CsrfOptions}
+     * (쿠키·헤더 이름, 서브도메인 API 용 `allowedOrigins`, `document` 없는 환경용 `readCookie`).
+     * 미지정/false = 부착 안 함 (현행 동작).
+     *
+     * - **비안전 메서드**(GET·HEAD·OPTIONS·TRACE 외)이고 CSRF 쿠키가 있으며 요청 URL(baseUrl 조인 후)이
+     *   같은 출처(상대 URL 포함)이거나 `allowedOrigins` 에 속할 때만 붙인다 — 교차 출처로는 보내지 않는다.
+     * - 호출자가 이미 같은 이름의 헤더를 실었으면 덮어쓰지 않는다 (호출자 우선, XC-06).
+     * - 쿠키는 **시도마다 다시 읽는다** — 재시도 사이에 서버가 토큰을 회전해도 새 값을 싣는다.
+     * - `document` 가 없는 환경(SSR·Node)에서는 `readCookie` 주입이 없으면 아무것도 붙이지 않는다(오류 없음).
+     * - `getToken`(bearer)과 독립적으로 동작한다.
+     */
+    csrf?: boolean | CsrfOptions;
     /** 401 수신 시 throw 직전에 호출되는 콜백 (로그아웃/리다이렉트 등 소비자 정책 주입). */
     onUnauthorized?: (error: ApiError) => void;
     /** fetch 구현체 주입 (테스트용). 기본 globalThis.fetch. */
@@ -324,10 +423,13 @@ interface ApiClient {
  *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
  * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
  * - 401 은 throw 직전에 onUnauthorized 콜백을 호출한다.
+ * - 인증 운반 (contracts/session-auth.md): `bearer` = `getToken` 으로 Authorization 헤더,
+ *   `jwt-cookie`/`session` = `credentials` + `csrf` (쿠키는 브라우저가 싣고 CSRF 헤더만 자동 부착).
  * - retry 지정 시 요청을 core retry() 로 감싼다 ({@link ApiClientRetryOptions} —
  *   멱등 메서드 기본, Retry-After 하한, 시도 간 동일 traceId).
  *
- * 저장소 접근·경로·이벤트명 하드코딩 없음 — 전부 config 주입.
+ * 저장소 접근·경로·이벤트명 하드코딩 없음 — 전부 config 주입 (opt-in `csrf` 의 CSRF 쿠키 읽기만 예외 —
+ * 기본 `document.cookie`, `readCookie` 로 교체 가능).
  */
 declare function createApiClient(config: ApiClientConfig): ApiClient;
 
@@ -847,7 +949,7 @@ declare function generateIdempotencyKey(): string;
  * 시맨틱(입력→판정)은 3언어 동일하며 반환 형태만 다르다."
  *
  * Node 전용 API(`timingSafeEqual` 등) 미사용 — 브라우저/Node 공용
- * (`globalThis.crypto.subtle`, Node 18+ / 모던 브라우저).
+ * (`globalThis.crypto.subtle`, Node 20+ / 모던 브라우저).
  */
 /** 웹훅 서명 헤더명 기본값 (contracts/webhook-signature.md). */
 declare const WEBHOOK_SIGNATURE_HEADER = "X-Rscc-Signature";
@@ -1347,4 +1449,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, csrfHeaderFor, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isUnsafeMethod, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.d.ts

@@ -75,6 +75,79 @@ declare const ResultCode: {
 /** ResultCode 코드 값의 유니온 타입 ("200" | "400" | ...). */
 type ResultCode = (typeof ResultCode)[keyof typeof ResultCode];
 
+/**
+ * CSRF double-submit 클라이언트 헬퍼 — contracts/session-auth.md §4·§5 (수동 동기화).
+ *
+ * 쿠키 운반 인증 모드(`jwt-cookie` / `session`)에서 서버는 CSRF 토큰을 HttpOnly 가 아닌 쿠키
+ * (`XSRF-TOKEN`)로 발급하고, 클라이언트는 **비안전 메서드** 요청마다 그 값을 헤더(`X-XSRF-TOKEN`)에
+ * 되돌려 보낸다. 서버는 쿠키 값과 헤더 값의 동등성만 확인한다.
+ *
+ * 부착 규칙 (골든 벡터 XC-01~08):
+ * - 비안전 메서드(GET·HEAD·OPTIONS·TRACE 외)일 때만.
+ * - CSRF 쿠키가 있고 값이 비어 있지 않을 때만 (없으면 부착 안 함 — 오류 없음).
+ * - 요청 URL 이 **같은 출처**(상대 URL 포함)이거나 명시한 `allowedOrigins` 에 속할 때만 —
+ *   교차 출처로는 보내지 않는다(토큰 유출 방지).
+ * - `document` 가 없는 환경(SSR·Node)에서는 `readCookie` 주입이 없으면 아무것도 붙이지 않는다.
+ *
+ * SSR 안전: 모듈 로드 시점에 `document`/`location` 에 접근하지 않는다 (호출 시점에만 존재 확인).
+ */
+/** CSRF 토큰 쿠키 기본 이름 (contracts/session-auth.md §2.1). */
+declare const DEFAULT_CSRF_COOKIE_NAME = "XSRF-TOKEN";
+/** CSRF 요청 헤더 기본 이름 — Spring `CookieCsrfTokenRepository` 관례 (contracts/session-auth.md §2.1). */
+declare const DEFAULT_CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+/** CSRF 헤더 자동 부착 옵션 (apiClient `csrf` / useSse `csrf`). */
+interface CsrfOptions {
+    /** CSRF 토큰 쿠키 이름. 기본 {@link DEFAULT_CSRF_COOKIE_NAME} (`"XSRF-TOKEN"`) — 서버 설정과 일치시킬 것. */
+    cookieName?: string;
+    /** CSRF 요청 헤더 이름. 기본 {@link DEFAULT_CSRF_HEADER_NAME} (`"X-XSRF-TOKEN"`). */
+    headerName?: string;
+    /**
+     * 같은 출처 외에 헤더를 보내도 되는 **오리진** 목록 (예: `["https://api.example.com"]`) —
+     * 같은 사이트 서브도메인 토폴로지(`app.example.com` → `api.example.com`, contracts §8)용.
+     * 항목은 `scheme://host[:port]` 로 정규화해 비교한다(경로·끝 슬래시·대소문자·기본 포트 무관).
+     * 와일드카드는 지원하지 않는다. 기본: 없음 (같은 출처만).
+     */
+    allowedOrigins?: readonly string[];
+    /**
+     * **원시 쿠키 문자열**(`"a=1; XSRF-TOKEN=abc"` 형태) 공급자 — `document.cookie` 대신 쓴다
+     * (React Native·테스트 등 `document` 가 없는 환경). null/undefined 반환은 쿠키 없음.
+     * 기본: `document` 가 있으면 `document.cookie`, 없으면 쿠키 없음.
+     */
+    readCookie?: () => string | null | undefined;
+}
+/**
+ * 원시 쿠키 문자열에서 `name` 쿠키 값을 읽는다 (contracts/session-auth.md §2.3).
+ *
+ * - `;` 로 나누고 각 조각의 앞뒤 공백을 제거한 뒤 **첫 `=`** 기준으로 이름·값을 가른다.
+ * - 이름은 **대소문자 구분 정확 일치**, 같은 이름이 여럿이면 **첫 값**(XC-08).
+ * - 값은 디코딩하지 않는다(`decodeURIComponent` 미적용). 빈 값(`name=`)은 `""` 를 반환한다.
+ * - `cookieString` 생략 시 `document` 가 있으면 `document.cookie` 를 쓰고, 없으면(SSR·Node) null.
+ *   `document.cookie` 접근 자체가 실패하는 환경(샌드박스 iframe 등)도 null.
+ *
+ * @returns 쿠키 값, 해당 쿠키가 없으면 null.
+ */
+declare function readCookie(name: string, cookieString?: string): string | null;
+/**
+ * 비안전 메서드 여부 — GET·HEAD·OPTIONS·TRACE 외 전부 true (대소문자 무관).
+ * `method` 생략(또는 빈 문자열)은 fetch 기본값 GET 으로 보아 false.
+ */
+declare function isUnsafeMethod(method?: string): boolean;
+/**
+ * 요청 하나에 붙일 CSRF 헤더를 계산한다 — 붙여야 하면 `[헤더명, 쿠키값]`, 아니면 null.
+ *
+ * 판정 순서: 비안전 메서드? → CSRF 쿠키 있음(빈 값 제외)? → 같은 출처(상대 URL, 또는 `location` 이
+ * 있을 때 그 오리진과 같은 절대 URL) 또는 `allowedOrigins` 소속? → 부착 (골든 벡터 XC-01~05·07·08).
+ * 호출자가 이미 같은 헤더를 실었는지(XC-06)는 호출 측(apiClient·useSse)이 확인한다.
+ *
+ * 오류를 던지지 않는다 — `document`·`readCookie` 가 모두 없으면(SSR) null. URL 을 해석할 수 없으면
+ * 교차 출처로 간주해 null (토큰 유출 방지 쪽으로 실패).
+ *
+ * @param url 요청 URL (상대/절대). 상대 URL 은 같은 출처로 본다.
+ * @param method HTTP 메서드. 생략 시 GET.
+ * @param options `true` 또는 생략 = 기본값, 객체 = {@link CsrfOptions}.
+ */
+declare function csrfHeaderFor(url: string, method: string | undefined, options?: true | CsrfOptions): [name: string, value: string] | null;
+
 /**
  * 아웃바운드 회복탄력성 — 지수 백오프 + full jitter 재시도. 런타임 의존성 0(native 만).
  *
@@ -229,8 +302,34 @@ interface ApiClientConfig {
      * 상대 baseUrl("/api")도 지원.
      */
     baseUrl: string;
-    /** 토큰 공급자. 지정 시 반환값이 truthy 면 `Authorization: Bearer <token>` 부착. */
+    /**
+     * 토큰 공급자 (`bearer` 모드). 지정 시 반환값이 truthy 면 `Authorization: Bearer <token>` 부착
+     * (호출자가 Authorization 을 이미 실었으면 덮어쓰지 않음). 쿠키 모드(`jwt-cookie`/`session`)의
+     * 웹 클라이언트는 쓰지 않는다 — `credentials`·`csrf` 참조.
+     */
     getToken?: () => string | null | undefined;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 같은 출처 API 는 `"same-origin"`(fetch 기본값과 같음), 서브도메인 등 교차 출처 API 는 `"include"`.
+     *
+     * - 미지정 = fetch 에 `credentials` 속성 자체를 넘기지 않는다 (현행 동작 — fetch 기본값 `"same-origin"`).
+     * - 호출별 `init.credentials` 가 있으면 그 값이 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (contracts/session-auth.md §4·§5, 골든 벡터 XC-01~08).
+     * `true` = 기본값(쿠키 `XSRF-TOKEN` → 헤더 `X-XSRF-TOKEN`, 같은 출처만), 객체 = {@link CsrfOptions}
+     * (쿠키·헤더 이름, 서브도메인 API 용 `allowedOrigins`, `document` 없는 환경용 `readCookie`).
+     * 미지정/false = 부착 안 함 (현행 동작).
+     *
+     * - **비안전 메서드**(GET·HEAD·OPTIONS·TRACE 외)이고 CSRF 쿠키가 있으며 요청 URL(baseUrl 조인 후)이
+     *   같은 출처(상대 URL 포함)이거나 `allowedOrigins` 에 속할 때만 붙인다 — 교차 출처로는 보내지 않는다.
+     * - 호출자가 이미 같은 이름의 헤더를 실었으면 덮어쓰지 않는다 (호출자 우선, XC-06).
+     * - 쿠키는 **시도마다 다시 읽는다** — 재시도 사이에 서버가 토큰을 회전해도 새 값을 싣는다.
+     * - `document` 가 없는 환경(SSR·Node)에서는 `readCookie` 주입이 없으면 아무것도 붙이지 않는다(오류 없음).
+     * - `getToken`(bearer)과 독립적으로 동작한다.
+     */
+    csrf?: boolean | CsrfOptions;
     /** 401 수신 시 throw 직전에 호출되는 콜백 (로그아웃/리다이렉트 등 소비자 정책 주입). */
     onUnauthorized?: (error: ApiError) => void;
     /** fetch 구현체 주입 (테스트용). 기본 globalThis.fetch. */
@@ -324,10 +423,13 @@ interface ApiClient {
  *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
  * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
  * - 401 은 throw 직전에 onUnauthorized 콜백을 호출한다.
+ * - 인증 운반 (contracts/session-auth.md): `bearer` = `getToken` 으로 Authorization 헤더,
+ *   `jwt-cookie`/`session` = `credentials` + `csrf` (쿠키는 브라우저가 싣고 CSRF 헤더만 자동 부착).
  * - retry 지정 시 요청을 core retry() 로 감싼다 ({@link ApiClientRetryOptions} —
  *   멱등 메서드 기본, Retry-After 하한, 시도 간 동일 traceId).
  *
- * 저장소 접근·경로·이벤트명 하드코딩 없음 — 전부 config 주입.
+ * 저장소 접근·경로·이벤트명 하드코딩 없음 — 전부 config 주입 (opt-in `csrf` 의 CSRF 쿠키 읽기만 예외 —
+ * 기본 `document.cookie`, `readCookie` 로 교체 가능).
  */
 declare function createApiClient(config: ApiClientConfig): ApiClient;
 
@@ -847,7 +949,7 @@ declare function generateIdempotencyKey(): string;
  * 시맨틱(입력→판정)은 3언어 동일하며 반환 형태만 다르다."
  *
  * Node 전용 API(`timingSafeEqual` 등) 미사용 — 브라우저/Node 공용
- * (`globalThis.crypto.subtle`, Node 18+ / 모던 브라우저).
+ * (`globalThis.crypto.subtle`, Node 20+ / 모던 브라우저).
  */
 /** 웹훅 서명 헤더명 기본값 (contracts/webhook-signature.md). */
 declare const WEBHOOK_SIGNATURE_HEADER = "X-Rscc-Signature";
@@ -1347,4 +1449,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type CsrfOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_HEADER_NAME, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, csrfHeaderFor, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isUnsafeMethod, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readCookie, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.js

@@ -20,6 +20,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() {
@@ -163,6 +250,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 () => {
@@ -178,8 +267,16 @@ function createApiClient(config) {
         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 {
@@ -1686,6 +1783,8 @@ export {
   ApiError,
   BulkheadFullError,
   CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1705,6 +1804,7 @@ export {
   createFeatureFlags,
   createTokenBucket,
   createTtlCache,
+  csrfHeaderFor,
   decodeJwtPayload,
   decomposeHangul,
   formatPhoneNumber,
@@ -1715,6 +1815,7 @@ export {
   isForeignerRrn,
   isRetryableStatus,
   isTokenExpired,
+  isUnsafeMethod,
   isValidBusinessNumber,
   isValidCorporateNumber,
   isValidRrn,
@@ -1734,6 +1835,7 @@ export {
   parseSseFrame,
   parseWireDateTime,
   pickJosa,
+  readCookie,
   readSseStream,
   retry,
   rrnBirthDate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rscc/common-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "RSCC 공통 코어 — CommonResponse 타입·apiClient(traceId·재시도·멱등성 키), SSE 파서, 회복탄력성(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안(마스킹·로그 리댁션·웹훅 서명·JWT 디코드·AES-GCM 서브패스), 와이어 계약 헬퍼, 한국 도메인 유틸. 프레임워크 무관, 런타임 의존성 0.",
   "keywords": [
     "rscc",
@@ -24,7 +24,7 @@
     "url": "https://github.com/Jeonghyeon-Ryu/r-common/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"