@uniai-fe/uds-templates 0.6.11 → 0.6.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/cctv/hooks/streamRegistry.ts

@@ -2,6 +2,7 @@
 
 import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
 import {
+  getCctvDebugJwtMetadata,
   getCctvDebugKeyLabel,
   getCctvDebugUrlLabel,
   logCctvDebugEvent,
@@ -31,6 +32,8 @@ interface CctvRtcStreamStartParams {
   video: HTMLVideoElement;
 }
 
+const WHEP_ERROR_BODY_PREVIEW_LIMIT = 1000;
+
 const getEntrySnapshot = (
   entry?: CctvRtcStreamEntry,
 ): CctvRtcStreamSnapshot => ({
@@ -51,6 +54,56 @@ const notifyEntry = (entry: CctvRtcStreamEntry) => {
   entry.listeners.forEach(listener => listener(snapshot));
 };
 
+const getWhepResponseBodyPreview = async (
+  response: Response,
+): Promise<string | null> => {
+  try {
+    const text = await response.clone().text();
+    return text.slice(0, WHEP_ERROR_BODY_PREVIEW_LIMIT);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * WHEP 실패 body를 startWhepStream 외부에서 관찰하기 위한 fetch wrapper.
+ * @desc
+ * 성공 응답은 그대로 통과시키고, 실패 응답에서만 clone body를 읽어 debug log에 남긴다.
+ */
+const createCctvDebugWhepFetcher =
+  ({
+    endpoint,
+    identityKey,
+    streamKey,
+    token,
+  }: {
+    endpoint: string;
+    identityKey: string;
+    streamKey: string;
+    token: string;
+  }): typeof fetch =>
+  async (input, init) => {
+    const response = await fetch(input, init);
+    if (response.ok) return response;
+
+    logCctvDebugEvent({
+      event: "whep:response-error",
+      level: "error",
+      payload: {
+        endpoint: getCctvDebugUrlLabel(endpoint),
+        identityKey: getCctvDebugKeyLabel(identityKey),
+        responseBody: await getWhepResponseBodyPreview(response),
+        status: response.status,
+        statusText: response.statusText,
+        streamKey: getCctvDebugKeyLabel(streamKey),
+        token: getCctvDebugJwtMetadata(token),
+      },
+      source: "streamRegistry",
+    });
+
+    return response;
+  };
+
 const closeEntry = (entry: CctvRtcStreamEntry) => {
   logCctvDebugEvent({
     event: "entry:close",
@@ -188,12 +241,19 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
           endpoint: getCctvDebugUrlLabel(endpoint),
           identityKey: getCctvDebugKeyLabel(identityKey),
           streamKey: getCctvDebugKeyLabel(streamKey),
+          token: getCctvDebugJwtMetadata(token),
         },
         source: "streamRegistry",
       });
 
       startWhepStream({
         endpoint,
+        fetcher: createCctvDebugWhepFetcher({
+          endpoint,
+          identityKey,
+          streamKey,
+          token,
+        }),
         token,
         video,
         signal: controller.signal,

package/src/cctv/utils/debug.ts

@@ -32,6 +32,15 @@ export interface CctvDebugSummary {
   total: number;
 }
 
+export interface CctvDebugJwtMetadata {
+  expiresAt: string | null;
+  expiresInSec: number | null;
+  headerAlg: string | null;
+  headerKid: string | null;
+  tokenLabel: string | null;
+  tokenPartCount: number;
+}
+
 export interface CctvDebugBuffer {
   clear: () => void;
   dump: () => CctvDebugEvent[];
@@ -108,6 +117,13 @@ const getDebugStorageOverride = (keys: readonly string[]): boolean | null => {
   return null;
 };
 
+const getDebugConsoleOverride = (): boolean | null => {
+  const queryOverride = getDebugQueryOverride(DEBUG_CONSOLE_QUERY_KEYS);
+  if (queryOverride !== null) return queryOverride;
+
+  return getDebugStorageOverride(DEBUG_CONSOLE_STORAGE_KEYS);
+};
+
 const isLocalhostDebugDefaultEnabled = (): boolean => {
   const { hostname } = window.location;
   return (
@@ -221,6 +237,57 @@ const summarizeCctvDebugEvents = (
   };
 };
 
+const decodeBase64UrlJson = (value: string): Record<string, unknown> | null => {
+  try {
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const parsed = JSON.parse(atob(padded));
+
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const getJwtStringClaim = (
+  claims: Record<string, unknown> | null,
+  key: string,
+): string | null => {
+  const value = claims?.[key];
+  return typeof value === "string" ? value : null;
+};
+
+const getJwtExpiresAt = (
+  claims: Record<string, unknown> | null,
+): { expiresAt: string | null; expiresInSec: number | null } => {
+  const exp = claims?.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) {
+    return { expiresAt: null, expiresInSec: null };
+  }
+
+  const expiresAtMs = exp * 1000;
+  return {
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    expiresInSec: Math.floor((expiresAtMs - Date.now()) / 1000),
+  };
+};
+
+const stringifyCctvDebugEvent = (entry: CctvDebugEvent): string => {
+  try {
+    return JSON.stringify(entry);
+  } catch {
+    return JSON.stringify({
+      at: entry.at,
+      event: entry.event,
+      level: entry.level,
+      seq: entry.seq,
+      source: entry.source,
+    });
+  }
+};
+
 /**
  * identity/stream key를 원문 대신 추적 가능한 hash label로 바꾼다.
  */
@@ -253,11 +320,37 @@ export const getCctvDebugUrlLabel = (
   }
 };
 
+/**
+ * JWT 원문 대신 헤더/만료시각과 hash label만 기록한다.
+ * @desc
+ * token signature mismatch를 추적하기 위한 메타 정보이며, Bearer token 원문과 payload claim은
+ * debug log에 남기지 않는다.
+ */
+export const getCctvDebugJwtMetadata = (
+  token: string | null | undefined,
+): CctvDebugJwtMetadata | null => {
+  if (!token) return null;
+
+  const [headerPart, payloadPart] = token.split(".");
+  const header = headerPart ? decodeBase64UrlJson(headerPart) : null;
+  const payload = payloadPart ? decodeBase64UrlJson(payloadPart) : null;
+  const { expiresAt, expiresInSec } = getJwtExpiresAt(payload);
+
+  return {
+    expiresAt,
+    expiresInSec,
+    headerAlg: getJwtStringClaim(header, "alg"),
+    headerKid: getJwtStringClaim(header, "kid"),
+    tokenLabel: getCctvDebugKeyLabel(token),
+    tokenPartCount: token.split(".").length,
+  };
+};
+
 /**
  * CCTV debug logging 활성화 여부를 확인한다.
  * @desc
- * production default는 off다. `?udsCctvDebug=1` 또는
- * `localStorage.setItem("uds:cctv:debug", "1")`로 runtime에서 켤 수 있다.
+ * production default는 off, localhost default는 ring buffer on이다.
+ * console 출력은 별도 console flag를 켠 경우에만 활성화한다.
  */
 export const isCctvDebugEnabled = (): boolean => {
   if (!isBrowser()) return false;
@@ -265,6 +358,9 @@ export const isCctvDebugEnabled = (): boolean => {
   const queryOverride = getDebugQueryOverride(DEBUG_QUERY_KEYS);
   if (queryOverride !== null) return queryOverride;
 
+  const consoleOverride = getDebugConsoleOverride();
+  if (consoleOverride === true) return true;
+
   const storageOverride = getDebugStorageOverride(DEBUG_STORAGE_KEYS);
   if (storageOverride !== null) return storageOverride;
 
@@ -274,18 +370,7 @@ export const isCctvDebugEnabled = (): boolean => {
 const isCctvDebugConsoleEnabled = (): boolean => {
   if (!isBrowser()) return false;
 
-  const consoleQueryOverride = getDebugQueryOverride(DEBUG_CONSOLE_QUERY_KEYS);
-  if (consoleQueryOverride !== null) return consoleQueryOverride;
-
-  const consoleStorageOverride = getDebugStorageOverride(
-    DEBUG_CONSOLE_STORAGE_KEYS,
-  );
-  if (consoleStorageOverride !== null) return consoleStorageOverride;
-
-  return (
-    getDebugQueryOverride(DEBUG_QUERY_KEYS) === true ||
-    getDebugStorageOverride(DEBUG_STORAGE_KEYS) === true
-  );
+  return getDebugConsoleOverride() === true;
 };
 
 /**
@@ -372,5 +457,5 @@ export const logCctvDebugEvent = ({
           ? console.info
           : console.debug;
 
-  logger.call(console, "[UDS:CCTV]", entry);
+  logger.call(console, `[UDS:CCTV] ${stringifyCctvDebugEvent(entry)}`);
 };