@sayren/store-sdk 0.1.0

package/src/session.ts

@@ -0,0 +1,249 @@
+import { base64UrlFromBytes } from "./base64";
+import { toApiError, unwrapData } from "./http";
+import {
+  buildAuthorizeUrl,
+  createPkcePair,
+  exchangeAuthorizationCode,
+  refreshUserToken,
+} from "./oauth";
+import { type MyAccount, myAccountSchema } from "./schemas/auth";
+
+/**
+ * SDK 세션 매니저 — 콘솔(userToken)의 저장·무음 갱신·회전을 캡슐화한다.
+ *
+ * 저장 매체(쿠키/localStorage/…)와 그 속성(Max-Age·SameSite·Secure·Path)은 **어댑터(앱) 책임**이다.
+ * SDK는 "무엇을 어떤 키로 저장할지"만 알고, "어떻게 저장할지"는 SessionStorage 어댑터에 위임한다.
+ * 쿠키는 동기 read/write라 인터페이스도 동기로 충분하다.
+ */
+export interface SessionStorage {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+}
+
+/**
+ * 세션 키 상수 — SDK가 소유한다. 값은 apps/store의 기존 쿠키 이름(SESSION_COOKIE/REFRESH_COOKIE)과
+ * 동일하게 맞춰, 앱 어댑터·SSR 라우트 가드가 같은 원천을 읽도록 패리티를 보장한다.
+ */
+export const STORE_SESSION_KEYS = {
+  session: "sayren.store.session",
+  refresh: "sayren.store.refresh",
+  /** authorize() → handleCallback() 간 1회용 PKCE 블롭({ verifier, state, redirectUri }) 저장 키 */
+  pkce: "sayren.store.pkce",
+} as const;
+
+/** Web Locks 이름 — 탭 간 refresh 회전 직렬화용 */
+const REFRESH_LOCK = STORE_SESSION_KEYS.refresh;
+
+export interface StoreSessionOptions {
+  /** 예: https://api.example.com/v1 (/oauth2/token이 덧붙는다) */
+  baseUrl: string;
+  /** OAuth public client id (예: avarlabs) */
+  clientId: string;
+  /** 저장 매체 어댑터 (앱 소유) */
+  storage: SessionStorage;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface AuthorizeOptions {
+  /** OAuth 콜백 URI (예: https://store.example.com/auth/callback) */
+  redirectUri: string;
+  /** 생략 시 서버 기본(stores:read). refresh가 필요하면 offline_access 포함 */
+  scope?: string;
+  /** "signup"이면 authorize 대신 호스티드 회원가입 화면으로 진입한다 */
+  screen?: "authorize" | "signup";
+}
+
+export interface StoreSession {
+  /** 현재 userToken (없으면 null) */
+  getToken(): string | null;
+  /** 토큰 저장 + 구독자 통지. refresh_token이 있으면 함께 회전 저장한다(없으면 기존 유지) */
+  setTokens(tokens: { access_token: string; refresh_token?: string }): void;
+  /**
+   * 무음 세션 갱신 — refresh 토큰으로 새 userToken을 받아 회전 저장한다.
+   * - 탭 내부: 동시 다발 호출을 single-flight로 합친다.
+   * - 탭 간: navigator.locks(있으면)로 회전을 직렬화하고, 락 진입 시 다른 탭이 이미
+   *   회전했으면(세션 토큰 변경) 내 refresh 토큰을 소비하지 않고 true를 반환한다.
+   * refresh 토큰이 없으면 false(기존 세션 유지 — access token이 아직 유효할 수 있다).
+   * 회전이 실패(만료·재사용 폐기)하면 세션을 clear하고 false. (401 경로는 onUnauthorized→clear가 별도 처리.)
+   */
+  refresh(): Promise<boolean>;
+  /** 세션/리프레시 키를 지우고 구독자에게 통지한다 */
+  clear(): void;
+  /** 변경 구독(useSyncExternalStore 소비용) — getToken을 스냅샷으로 쓴다. 해지 함수 반환 */
+  subscribe(cb: () => void): () => void;
+  /** 현재 userToken (getToken()과 동일 — 게터 형태 소비용) */
+  readonly accessToken: string | null;
+  /** 현재 저장된 refresh 토큰 (없으면 null) */
+  readonly refreshToken: string | null;
+  /**
+   * 로그인/가입 시작 — PKCE 페어를 생성해 storage에 저장하고 authorize URL을 만든다.
+   * 브라우저(window 존재)에서는 top-level navigation을 수행하고 void를 반환한다.
+   * 그 외(SSR/테스트)에서는 이동하지 않고 URL 문자열을 반환한다.
+   */
+  authorize(options: AuthorizeOptions): Promise<string | undefined>;
+  /**
+   * OAuth 콜백 처리 — 저장된 PKCE 블롭(1회용)을 꺼내 state를 대조하고 code를 토큰으로 교환해 저장한다.
+   * PKCE 블롭이 없거나(만료) state가 불일치하면 던진다.
+   */
+  handleCallback(code: string, state: string): Promise<void>;
+  /** GET /me — accessToken이 없으면 네트워크 없이 null */
+  userinfo(): Promise<MyAccount | null>;
+}
+
+export function createStoreSession(options: StoreSessionOptions): StoreSession {
+  const { baseUrl, clientId, storage } = options;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const listeners = new Set<() => void>();
+
+  function notify(): void {
+    for (const listener of listeners) listener();
+  }
+
+  function getToken(): string | null {
+    return storage.get(STORE_SESSION_KEYS.session);
+  }
+
+  function setTokens(tokens: { access_token: string; refresh_token?: string }): void {
+    storage.set(STORE_SESSION_KEYS.session, tokens.access_token);
+    if (tokens.refresh_token) storage.set(STORE_SESSION_KEYS.refresh, tokens.refresh_token);
+    notify();
+  }
+
+  function clear(): void {
+    storage.remove(STORE_SESSION_KEYS.session);
+    storage.remove(STORE_SESSION_KEYS.refresh);
+    notify();
+  }
+
+  let refreshInFlight: Promise<boolean> | null = null;
+
+  function refresh(): Promise<boolean> {
+    if (!refreshInFlight) {
+      refreshInFlight = doRefresh().finally(() => {
+        refreshInFlight = null;
+      });
+    }
+    return refreshInFlight;
+  }
+
+  async function doRefresh(): Promise<boolean> {
+    // 락을 기다리는 동안 다른 탭이 회전을 끝낼 수 있으므로, 대기 전 세션 토큰을 스냅샷한다.
+    const before = getToken();
+    const locks = typeof navigator !== "undefined" ? navigator.locks : undefined;
+    return locks ? locks.request(REFRESH_LOCK, () => rotate(before)) : rotate(before);
+  }
+
+  async function rotate(before: string | null): Promise<boolean> {
+    // 락 획득 후 세션 토큰이 바뀌었으면 다른 탭이 이미 회전한 것 → 내 refresh 토큰은 소비하지 않는다.
+    if (getToken() !== before) return true;
+    const refreshToken = storage.get(STORE_SESSION_KEYS.refresh);
+    if (!refreshToken) return false;
+    try {
+      const tokens = await refreshUserToken({ baseUrl, clientId, refreshToken, fetch: fetchFn });
+      setTokens({ access_token: tokens.access_token, refresh_token: tokens.refresh_token });
+      return true;
+    } catch {
+      clear(); // refresh 토큰까지 함께 폐기
+      return false;
+    }
+  }
+
+  function subscribe(cb: () => void): () => void {
+    listeners.add(cb);
+    return () => {
+      listeners.delete(cb);
+    };
+  }
+
+  /** crypto.randomUUID가 있으면 그걸, 없으면 무작위 바이트를 base64url로 인코딩해 state를 만든다 */
+  function randomState(): string {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return base64UrlFromBytes(bytes);
+  }
+
+  interface PkceBlob {
+    verifier: string;
+    state: string;
+    redirectUri: string;
+  }
+
+  async function authorize(authorizeOptions: AuthorizeOptions): Promise<string | undefined> {
+    const { verifier, challenge } = await createPkcePair();
+    const state = randomState();
+    const blob: PkceBlob = { verifier, state, redirectUri: authorizeOptions.redirectUri };
+    storage.set(STORE_SESSION_KEYS.pkce, JSON.stringify(blob));
+
+    const url = new URL(
+      buildAuthorizeUrl({
+        baseUrl,
+        clientId,
+        redirectUri: authorizeOptions.redirectUri,
+        state,
+        codeChallenge: challenge,
+        scope: authorizeOptions.scope,
+      }),
+    );
+    if (authorizeOptions.screen === "signup") {
+      url.pathname = url.pathname.replace(/\/oauth2\/authorize$/, "/oauth2/signup");
+    }
+    const finalUrl = url.toString();
+
+    if (typeof window !== "undefined") {
+      window.location.assign(finalUrl);
+      return;
+    }
+    return finalUrl;
+  }
+
+  async function handleCallback(code: string, state: string): Promise<void> {
+    const raw = storage.get(STORE_SESSION_KEYS.pkce);
+    storage.remove(STORE_SESSION_KEYS.pkce); // 1회용
+    if (!raw) throw new Error("로그인 세션이 만료되었습니다. 다시 시도해주세요");
+    const saved = JSON.parse(raw) as PkceBlob;
+    if (saved.state !== state) {
+      throw new Error("state가 일치하지 않습니다. 다시 시도해주세요");
+    }
+    const tokens = await exchangeAuthorizationCode({
+      baseUrl,
+      clientId,
+      redirectUri: saved.redirectUri,
+      code,
+      codeVerifier: saved.verifier,
+      fetch: fetchFn,
+    });
+    setTokens({ access_token: tokens.access_token, refresh_token: tokens.refresh_token });
+  }
+
+  async function userinfo(): Promise<MyAccount | null> {
+    const token = getToken();
+    if (!token) return null;
+    const response = await fetchFn(`${baseUrl}/me`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const json: unknown = await response.json().catch(() => null);
+    if (!response.ok) throw toApiError(response.status, json);
+    return myAccountSchema.parse(unwrapData(json));
+  }
+
+  return {
+    getToken,
+    setTokens,
+    refresh,
+    clear,
+    subscribe,
+    authorize,
+    handleCallback,
+    userinfo,
+    get accessToken(): string | null {
+      return getToken();
+    },
+    get refreshToken(): string | null {
+      return storage.get(STORE_SESSION_KEYS.refresh);
+    },
+  };
+}

package/src/webhook-headers.ts

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

package/src/webhook-signature.ts

@@ -0,0 +1,177 @@
+import { WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers";
+
+/**
+ * 웹훅 서명 (`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(): SubtleCrypto {
+  const api = globalThis.crypto?.subtle;
+  if (!api) throw new Error("WebCrypto(crypto.subtle)를 사용할 수 없는 런타임입니다");
+  return api;
+}
+
+function importHmacKey(secret: string, usage: "sign" | "verify"): Promise<CryptoKey> {
+  return subtle().importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  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: string): Uint8Array<ArrayBuffer> | null {
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) return null;
+  const bytes = 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: number, payload: string): Uint8Array<ArrayBuffer> {
+  return encoder.encode(`${timestamp}.${payload}`);
+}
+
+function toSecretList(secret: string | readonly string[]): string[] {
+  return (typeof secret === "string" ? [secret] : [...secret]).filter((s) => s.length > 0);
+}
+
+export interface SignWebhookPayloadOptions {
+  /** 요청 본문 원문. 전송하는 바이트와 정확히 같아야 한다 */
+  payload: string;
+  /** 서명 시크릿. 여러 개면 순서대로 v1을 싣는다(현재 시크릿 먼저) */
+  secret: string | readonly string[];
+  /** 서명 시각 (unix 초). 생략하면 현재 시각 */
+  timestamp?: number;
+}
+
+/** `Sayren-Signature` 헤더 값을 만든다 */
+export async function signWebhookPayload(options: SignWebhookPayloadOptions): Promise<string> {
+  const secrets = toSecretList(options.secret);
+  if (secrets.length === 0) throw new Error("서명 시크릿이 비어 있습니다");
+  const timestamp = options.timestamp ?? Math.floor(Date.now() / 1000);
+  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(",");
+}
+
+export interface ParsedWebhookSignature {
+  /** 서명 시각 (unix 초) */
+  timestamp: number;
+  /** v1 서명(hex) 목록. 헤더에 실린 순서 그대로 */
+  signatures: string[];
+}
+
+/**
+ * `Sayren-Signature` 헤더를 파싱한다. `t`가 정확히 1개, `v1`이 1개 이상이어야 하며
+ * 아니면 null. 알 수 없는 스킴(예: 향후 `v2`)은 무시한다.
+ */
+export function parseWebhookSignatureHeader(
+  header: string | null | undefined,
+): ParsedWebhookSignature | null {
+  if (!header) return null;
+  let timestamp: number | null = null;
+  const signatures: string[] = [];
+  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 };
+}
+
+export type WebhookSignatureFailureReason =
+  /** 헤더가 없거나 비어 있음 */
+  | "MISSING_HEADER"
+  /** 헤더 형식 오류 (`t` 누락·중복·비정수, `v1` 없음) */
+  | "MALFORMED_HEADER"
+  /** 서명 시각이 허용 오차를 벗어남 (재전송 공격 방지) */
+  | "TIMESTAMP_OUT_OF_TOLERANCE"
+  /** 어떤 시크릿으로도 일치하는 v1이 없음 (본문 변조·시크릿 불일치) */
+  | "SIGNATURE_MISMATCH";
+
+export type WebhookSignatureVerification =
+  | { ok: true; timestamp: number }
+  | { ok: false; reason: WebhookSignatureFailureReason };
+
+export 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 async function verifyWebhookSignature(
+  options: VerifyWebhookSignatureOptions,
+): Promise<WebhookSignatureVerification> {
+  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 ?? WEBHOOK_DEFAULT_TOLERANCE_SEC;
+  const nowSec = Math.floor((options.now ?? new Date()).getTime() / 1000);
+  if (Math.abs(nowSec - parsed.timestamp) > tolerance) {
+    return { ok: false, reason: "TIMESTAMP_OUT_OF_TOLERANCE" };
+  }
+
+  const candidates = parsed.signatures
+    .map(fromHex)
+    .filter((bytes): bytes is Uint8Array<ArrayBuffer> => 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" };
+}