@sayren/store-sdk 0.1.0

package/dist/server.d.mts

@@ -0,0 +1,59 @@
+import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-D6QmPdEJ.mjs";
+//#region src/webhook-signature.d.ts
+interface SignWebhookPayloadOptions {
+  /** 요청 본문 원문. 전송하는 바이트와 정확히 같아야 한다 */
+  payload: string;
+  /** 서명 시크릿. 여러 개면 순서대로 v1을 싣는다(현재 시크릿 먼저) */
+  secret: string | readonly string[];
+  /** 서명 시각 (unix 초). 생략하면 현재 시각 */
+  timestamp?: number;
+}
+/** `Sayren-Signature` 헤더 값을 만든다 */
+export declare function signWebhookPayload(options: SignWebhookPayloadOptions): Promise<string>;
+interface ParsedWebhookSignature {
+  /** 서명 시각 (unix 초) */
+  timestamp: number;
+  /** v1 서명(hex) 목록. 헤더에 실린 순서 그대로 */
+  signatures: string[];
+}
+/**
+ * `Sayren-Signature` 헤더를 파싱한다. `t`가 정확히 1개, `v1`이 1개 이상이어야 하며
+ * 아니면 null. 알 수 없는 스킴(예: 향후 `v2`)은 무시한다.
+ */
+export declare function parseWebhookSignatureHeader(header: string | null | undefined): ParsedWebhookSignature | null;
+type WebhookSignatureFailureReason =
+/** 헤더가 없거나 비어 있음 */
+"MISSING_HEADER" |
+/** 헤더 형식 오류 (`t` 누락·중복·비정수, `v1` 없음) */
+"MALFORMED_HEADER" |
+/** 서명 시각이 허용 오차를 벗어남 (재전송 공격 방지) */
+"TIMESTAMP_OUT_OF_TOLERANCE" |
+/** 어떤 시크릿으로도 일치하는 v1이 없음 (본문 변조·시크릿 불일치) */
+"SIGNATURE_MISMATCH";
+type WebhookSignatureVerification = {
+  ok: true;
+  timestamp: number;
+} | {
+  ok: false;
+  reason: WebhookSignatureFailureReason;
+};
+interface VerifyWebhookSignatureOptions {
+  /** 요청 본문 원문. JSON 파싱 전 바이트 그대로의 문자열이어야 한다 */
+  payload: string;
+  /** `Sayren-Signature` 헤더 값 */
+  header: string | null | undefined;
+  /** 서명 시크릿. 교체 유예 중이면 새·이전 시크릿을 모두 넘긴다. 하나라도 일치하면 통과 */
+  secret: string | readonly string[];
+  /** 타임스탬프 허용 오차(초). 기본 300 */
+  toleranceSec?: number;
+  /** 기준 시각. 생략하면 현재 시각 */
+  now?: Date;
+}
+/**
+ * `Sayren-Signature`를 검증한다. 비교는 `crypto.subtle.verify`(HMAC 상수 시간 비교)로 하며
+ * 헤더의 v1 중 하나가 시크릿 중 하나와 일치하면 통과한다.
+ * 실패해도 예외를 던지지 않고 `{ ok: false, reason }`을 돌려준다.
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<WebhookSignatureVerification>;
+//#endregion
+export { type ParsedWebhookSignature, type SignWebhookPayloadOptions, type VerifyWebhookSignatureOptions, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, type WebhookSignatureFailureReason, type WebhookSignatureVerification };

package/dist/server.mjs

@@ -0,0 +1,125 @@
+import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-ap_exsb9.mjs";
+//#region src/webhook-signature.ts
+/**
+* 웹훅 서명 (`Sayren-Signature`) 생성·파싱·검증.
+*
+* 형식: `t=<unix초>,v1=<hex>[,v1=<hex>]`. v1 = HMAC-SHA256(secret, `${t}.${rawBody}`)의 소문자 hex.
+* 시크릿 교체 유예 중에는 현재·이전 시크릿 서명을 모두 싣는다(현재 먼저).
+*
+* WebCrypto(`crypto.subtle`)만 써서 Node·Workers·Deno 어디서나 동작한다. 키 import는 호출 시점에
+* 하므로 모듈 평가에 부작용·top-level await가 없다(CJS `require(esm)` 소비 조건).
+* 시크릿을 다루므로 서버 엔트리포인트(`@sayren/store-sdk/server`)로만 노출한다.
+*/
+const encoder = new TextEncoder();
+function subtle() {
+	const api = globalThis.crypto?.subtle;
+	if (!api) throw new Error("WebCrypto(crypto.subtle)를 사용할 수 없는 런타임입니다");
+	return api;
+}
+function importHmacKey(secret, usage) {
+	return subtle().importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, [usage]);
+}
+function toHex(buffer) {
+	let hex = "";
+	for (const byte of new Uint8Array(buffer)) hex += byte.toString(16).padStart(2, "0");
+	return hex;
+}
+/** 64자 hex → 32바이트. 형식이 아니면 null */
+function fromHex(hex) {
+	if (!/^[0-9a-fA-F]{64}$/.test(hex)) return null;
+	const bytes = /* @__PURE__ */ new Uint8Array(32);
+	for (let i = 0; i < 32; i++) bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+function signedContent(timestamp, payload) {
+	return encoder.encode(`${timestamp}.${payload}`);
+}
+function toSecretList(secret) {
+	return (typeof secret === "string" ? [secret] : [...secret]).filter((s) => s.length > 0);
+}
+/** `Sayren-Signature` 헤더 값을 만든다 */
+async function signWebhookPayload(options) {
+	const secrets = toSecretList(options.secret);
+	if (secrets.length === 0) throw new Error("서명 시크릿이 비어 있습니다");
+	const timestamp = options.timestamp ?? Math.floor(Date.now() / 1e3);
+	if (!Number.isSafeInteger(timestamp) || timestamp < 0) throw new Error("timestamp는 0 이상의 정수(unix 초)여야 합니다");
+	const content = signedContent(timestamp, options.payload);
+	const parts = [`t=${timestamp}`];
+	for (const secret of secrets) {
+		const key = await importHmacKey(secret, "sign");
+		parts.push(`v1=${toHex(await subtle().sign("HMAC", key, content))}`);
+	}
+	return parts.join(",");
+}
+/**
+* `Sayren-Signature` 헤더를 파싱한다. `t`가 정확히 1개, `v1`이 1개 이상이어야 하며
+* 아니면 null. 알 수 없는 스킴(예: 향후 `v2`)은 무시한다.
+*/
+function parseWebhookSignatureHeader(header) {
+	if (!header) return null;
+	let timestamp = null;
+	const signatures = [];
+	for (const raw of header.split(",")) {
+		const part = raw.trim();
+		const eq = part.indexOf("=");
+		if (eq <= 0) return null;
+		const scheme = part.slice(0, eq);
+		const value = part.slice(eq + 1);
+		if (scheme === "t") {
+			if (timestamp !== null || !/^\d{1,15}$/.test(value)) return null;
+			timestamp = Number(value);
+		} else if (scheme === "v1") {
+			if (!value) return null;
+			signatures.push(value);
+		}
+	}
+	if (timestamp === null || signatures.length === 0) return null;
+	return {
+		timestamp,
+		signatures
+	};
+}
+/**
+* `Sayren-Signature`를 검증한다. 비교는 `crypto.subtle.verify`(HMAC 상수 시간 비교)로 하며
+* 헤더의 v1 중 하나가 시크릿 중 하나와 일치하면 통과한다.
+* 실패해도 예외를 던지지 않고 `{ ok: false, reason }`을 돌려준다.
+*/
+async function verifyWebhookSignature(options) {
+	const secrets = toSecretList(options.secret);
+	if (secrets.length === 0) throw new Error("서명 시크릿이 비어 있습니다");
+	if (!options.header) return {
+		ok: false,
+		reason: "MISSING_HEADER"
+	};
+	const parsed = parseWebhookSignatureHeader(options.header);
+	if (!parsed) return {
+		ok: false,
+		reason: "MALFORMED_HEADER"
+	};
+	const tolerance = options.toleranceSec ?? 300;
+	const nowSec = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	if (Math.abs(nowSec - parsed.timestamp) > tolerance) return {
+		ok: false,
+		reason: "TIMESTAMP_OUT_OF_TOLERANCE"
+	};
+	const candidates = parsed.signatures.map(fromHex).filter((bytes) => bytes !== null);
+	if (candidates.length > 0) {
+		const content = signedContent(parsed.timestamp, options.payload);
+		for (const secret of secrets) {
+			const key = await importHmacKey(secret, "verify");
+			for (const signature of candidates) if (await subtle().verify("HMAC", key, signature, content)) return {
+				ok: true,
+				timestamp: parsed.timestamp
+			};
+		}
+	}
+	return {
+		ok: false,
+		reason: "SIGNATURE_MISMATCH"
+	};
+}
+//#endregion
+export { WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature };

package/dist/webhook-headers-D6QmPdEJ.d.mts

@@ -0,0 +1,22 @@
+//#region src/webhook-headers.d.ts
+/** 웹훅 발송 요청 헤더 상수 (공개 계약). zod 의존 없이 서버 엔트리포인트에서도 가볍게 쓴다 */
+/** 서명 헤더. 형식: `t=<unix초>,v1=<hex>[,v1=<hex>]` */
+declare const WEBHOOK_SIGNATURE_HEADER = "Sayren-Signature";
+/** 이벤트 ID 헤더. 본문 `id`와 같다. 중복 제거 키 */
+declare const WEBHOOK_EVENT_ID_HEADER = "Sayren-Event-Id";
+/** 이벤트 타입 헤더. 본문 `type`과 같다 */
+declare const WEBHOOK_EVENT_TYPE_HEADER = "Sayren-Event-Type";
+/** 전송 기록 ID 헤더. 전송 기록의 `deliveryId`와 같다 */
+declare const WEBHOOK_DELIVERY_ID_HEADER = "Sayren-Delivery-Id";
+/** 발송 요청의 `User-Agent` 값 */
+declare const WEBHOOK_USER_AGENT = "Sayren-Webhooks/1.0";
+/** 수신 측 권장 타임스탬프 허용 오차(초) */
+declare const WEBHOOK_DEFAULT_TOLERANCE_SEC = 300;
+declare const WEBHOOK_HEADERS: {
+  readonly signature: "Sayren-Signature";
+  readonly eventId: "Sayren-Event-Id";
+  readonly eventType: "Sayren-Event-Type";
+  readonly deliveryId: "Sayren-Delivery-Id";
+};
+//#endregion
+export { WEBHOOK_HEADERS as a, WEBHOOK_EVENT_TYPE_HEADER as i, WEBHOOK_DELIVERY_ID_HEADER as n, WEBHOOK_SIGNATURE_HEADER as o, WEBHOOK_EVENT_ID_HEADER as r, WEBHOOK_USER_AGENT as s, WEBHOOK_DEFAULT_TOLERANCE_SEC as t };

package/dist/webhook-headers-ap_exsb9.mjs

@@ -0,0 +1,22 @@
+//#region src/webhook-headers.ts
+/** 웹훅 발송 요청 헤더 상수 (공개 계약). zod 의존 없이 서버 엔트리포인트에서도 가볍게 쓴다 */
+/** 서명 헤더. 형식: `t=<unix초>,v1=<hex>[,v1=<hex>]` */
+const WEBHOOK_SIGNATURE_HEADER = "Sayren-Signature";
+/** 이벤트 ID 헤더. 본문 `id`와 같다. 중복 제거 키 */
+const WEBHOOK_EVENT_ID_HEADER = "Sayren-Event-Id";
+/** 이벤트 타입 헤더. 본문 `type`과 같다 */
+const WEBHOOK_EVENT_TYPE_HEADER = "Sayren-Event-Type";
+/** 전송 기록 ID 헤더. 전송 기록의 `deliveryId`와 같다 */
+const WEBHOOK_DELIVERY_ID_HEADER = "Sayren-Delivery-Id";
+/** 발송 요청의 `User-Agent` 값 */
+const WEBHOOK_USER_AGENT = "Sayren-Webhooks/1.0";
+/** 수신 측 권장 타임스탬프 허용 오차(초) */
+const WEBHOOK_DEFAULT_TOLERANCE_SEC = 300;
+const WEBHOOK_HEADERS = {
+	signature: WEBHOOK_SIGNATURE_HEADER,
+	eventId: WEBHOOK_EVENT_ID_HEADER,
+	eventType: WEBHOOK_EVENT_TYPE_HEADER,
+	deliveryId: WEBHOOK_DELIVERY_ID_HEADER
+};
+//#endregion
+export { WEBHOOK_HEADERS as a, WEBHOOK_EVENT_TYPE_HEADER as i, WEBHOOK_DELIVERY_ID_HEADER as n, WEBHOOK_SIGNATURE_HEADER as o, WEBHOOK_EVENT_ID_HEADER as r, WEBHOOK_USER_AGENT as s, WEBHOOK_DEFAULT_TOLERANCE_SEC as t };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sayren/store-sdk",
+  "version": "0.1.0",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./server": {
+      "development": "./src/server.ts",
+      "types": "./dist/server.d.mts",
+      "default": "./dist/server.mjs"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cochoio/shop.24.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "description": "sayren 관리 API SDK — zod 스키마 + fetch 클라이언트, PKCE 헬퍼",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "biome check --write . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/base64.ts

@@ -0,0 +1,28 @@
+/**
+ * base64 인코딩 헬퍼 — 웹 표준(`btoa` + `TextEncoder`)만 사용한다.
+ *
+ * 이 패키지는 브라우저/서버 공용 entrypoint 하나로 배포되므로 Node 전용 `Buffer`에
+ * 의존하지 않는다. `btoa`는 Latin-1 코드유닛만 받기 때문에 문자열은 반드시
+ * UTF-8 바이트로 먼저 인코딩한 뒤 넘긴다 — 그래야 non-ASCII 입력에서도
+ * `Buffer.from(text, "utf8").toString("base64")`와 동일한 결과가 나온다.
+ */
+
+/** 바이트 배열 → 표준 base64 (패딩 포함) */
+export function base64FromBytes(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** 바이트 배열 → base64url (RFC 4648 §5, 패딩 없음) */
+export function base64UrlFromBytes(bytes: Uint8Array): string {
+  return base64FromBytes(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * 문자열 → UTF-8 base64. `btoa(text)`를 직접 쓰면 Latin-1로 해석돼
+ * non-ASCII에서 잘못된 바이트가 나오거나(예: "café") 예외가 난다(예: "🔑").
+ */
+export function base64Utf8(text: string): string {
+  return base64FromBytes(new TextEncoder().encode(text));
+}