@rscc/common-core 0.2.0 → 0.4.0

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 () => {
@@ -171,16 +260,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 {
@@ -594,6 +690,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) {
@@ -606,6 +708,7 @@ function createCircuitBreaker(options) {
   let consecutiveFailures = 0;
   let openedAtMs = 0;
   let probeInFlight = false;
+  let probeStartedAtMs = 0;
   let inFlightGrants = 0;
   function allowRequest() {
     if (state === "CLOSED") {
@@ -613,18 +716,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() {
@@ -659,13 +768,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) {
@@ -1646,6 +1782,9 @@ function matchesHangul(query, target) {
 export {
   ApiError,
   BulkheadFullError,
+  CircuitOpenError,
+  DEFAULT_CSRF_COOKIE_NAME,
+  DEFAULT_CSRF_HEADER_NAME,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,
@@ -1665,6 +1804,7 @@ export {
   createFeatureFlags,
   createTokenBucket,
   createTtlCache,
+  csrfHeaderFor,
   decodeJwtPayload,
   decomposeHangul,
   formatPhoneNumber,
@@ -1675,6 +1815,7 @@ export {
   isForeignerRrn,
   isRetryableStatus,
   isTokenExpired,
+  isUnsafeMethod,
   isValidBusinessNumber,
   isValidCorporateNumber,
   isValidRrn,
@@ -1694,6 +1835,7 @@ export {
   parseSseFrame,
   parseWireDateTime,
   pickJosa,
+  readCookie,
   readSseStream,
   retry,
   rrnBirthDate,

package/package.json

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