@codenkay/video-nsgplayer-core 3.0.0 → 3.0.1

package/dist/index.d.cts

@@ -151,6 +151,12 @@ type StreamingConfig = {
      * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
      */
     getKeyAccessToken?: () => string | null | undefined;
+    /**
+     * Max same-origin key-proxy failures before the session permanently switches
+     * to browser Bearer / signed-query (default 2). Prevents hls.js from hammering
+     * a Cloudflare-blocked BFF (9–10× 502s).
+     */
+    keyProxyMaxFailures?: number;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -198,6 +204,7 @@ type PlayerConfig = Required<{
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
         getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+        keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -279,7 +286,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "2.0.1";
+declare const PACKAGE_VERSION = "3.0.1";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -312,6 +319,7 @@ type PlayerConfigPartial = Partial<{
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
         getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
+        keyProxyMaxFailures?: PlayerConfig["streaming"]["keyProxyMaxFailures"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -431,6 +439,7 @@ type HlsEngineOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -646,15 +655,21 @@ declare class RefreshManager {
 
 type HlsLoaderInstance = {
     stats: LoaderStats;
+    context: LoaderContext | null;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
-    abort?: () => void;
+    abort(): void;
 };
-type HlsLoader = new (config: object) => HlsLoaderInstance;
+/** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
+type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Max same-origin BFF key attempts before the session circuit opens. */
+declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    /** Override max BFF key failures before permanent browser fallback (default 2). */
+    keyProxyMaxFailures?: number;
 };
 declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
 /**
@@ -664,26 +679,24 @@ declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolea
  * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
  * stack (`InternalError: too much recursion`).
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
  *
  * AES `enc.key` handling (enterprise priority order):
  * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
  * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
- *    params — same auth model as segments on Appextech CDN hosts
  * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
  * hls.js loader that:
  * - Re-applies signed auth query params on every media request
- * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
- *
- * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
- * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
+ * - Loads AES `enc.key` via controlled BFF (≤2) → Bearer → query XHR
+ *   with a **session circuit breaker** so a dead Cloudflare BFF is not
+ *   hammered by hls.js retries (which previously caused 9–10× 502s).
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -692,4 +705,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.d.ts

@@ -151,6 +151,12 @@ type StreamingConfig = {
      * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
      */
     getKeyAccessToken?: () => string | null | undefined;
+    /**
+     * Max same-origin key-proxy failures before the session permanently switches
+     * to browser Bearer / signed-query (default 2). Prevents hls.js from hammering
+     * a Cloudflare-blocked BFF (9–10× 502s).
+     */
+    keyProxyMaxFailures?: number;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -198,6 +204,7 @@ type PlayerConfig = Required<{
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
         getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+        keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -279,7 +286,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "2.0.1";
+declare const PACKAGE_VERSION = "3.0.1";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -312,6 +319,7 @@ type PlayerConfigPartial = Partial<{
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
         getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
+        keyProxyMaxFailures?: PlayerConfig["streaming"]["keyProxyMaxFailures"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -431,6 +439,7 @@ type HlsEngineOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -646,15 +655,21 @@ declare class RefreshManager {
 
 type HlsLoaderInstance = {
     stats: LoaderStats;
+    context: LoaderContext | null;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
-    abort?: () => void;
+    abort(): void;
 };
-type HlsLoader = new (config: object) => HlsLoaderInstance;
+/** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
+type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Max same-origin BFF key attempts before the session circuit opens. */
+declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    /** Override max BFF key failures before permanent browser fallback (default 2). */
+    keyProxyMaxFailures?: number;
 };
 declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
 /**
@@ -664,26 +679,24 @@ declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolea
  * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
  * stack (`InternalError: too much recursion`).
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
  *
  * AES `enc.key` handling (enterprise priority order):
  * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
  * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
- *    params — same auth model as segments on Appextech CDN hosts
  * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
  * hls.js loader that:
  * - Re-applies signed auth query params on every media request
- * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
- *
- * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
- * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
+ * - Loads AES `enc.key` via controlled BFF (≤2) → Bearer → query XHR
+ *   with a **session circuit breaker** so a dead Cloudflare BFF is not
+ *   hammered by hls.js retries (which previously caused 9–10× 502s).
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -692,4 +705,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.js

@@ -146,7 +146,7 @@ var AuthManager = class {
 
 // src/config/defaults.ts
 var PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2];
-var PACKAGE_VERSION = "2.0.1";
+var PACKAGE_VERSION = "3.0.1";
 var DEFAULT_PLAYER_BEHAVIOR = {
   autoplay: true,
   startMuted: true,
@@ -325,7 +325,8 @@ function mergePlayerConfig(partial) {
         ...partial?.streaming?.hls
       },
       keyProxyUrlBuilder: partial?.streaming?.keyProxyUrlBuilder,
-      getKeyAccessToken: partial?.streaming?.getKeyAccessToken
+      getKeyAccessToken: partial?.streaming?.getKeyAccessToken,
+      keyProxyMaxFailures: partial?.streaming?.keyProxyMaxFailures
     },
     logging: { ...DEFAULT_PLAYER_CONFIG.logging, ...partial?.logging },
     debug: { ...DEFAULT_PLAYER_CONFIG.debug, ...partial?.debug },
@@ -768,6 +769,7 @@ function seekToLiveEdge(media, options) {
 import { XhrLoader as BuiltinXhrLoader } from "hls.js";
 var ENC_KEY_PATH_RE = /enc\.key$/i;
 var BUILTIN_LOADER_NAMES = /* @__PURE__ */ new Set(["XhrLoader", "FetchLoader"]);
+var KEY_PROXY_MAX_FAILURES = 2;
 function isEncryptionKeyUrl(rawUrl, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
   try {
     return ENC_KEY_PATH_RE.test(new URL(rawUrl, baseOrigin).pathname);
@@ -828,6 +830,20 @@ function createLoaderStats() {
     buffering: { start: 0, first: 0, end: 0 }
   };
 }
+function isProxyUpstreamBlocked(status, contentType, bodyHead, errorText) {
+  if (status === 0 || status === 502 || status === 503 || status === 504) {
+    return true;
+  }
+  if (status === 403 || status === 401) return true;
+  if (contentType?.includes("text/html")) return true;
+  if (/<!DOCTYPE|<html|Just a moment|Cloudflare|blocked/i.test(bodyHead)) {
+    return true;
+  }
+  if (errorText && /Cloudflare|HTML|DOCTYPE|blocked|502/i.test(errorText)) {
+    return true;
+  }
+  return false;
+}
 async function loadEncryptionKeyWithFetch(context, callbacks, accessToken, signal) {
   const stats = createLoaderStats();
   stats.loading.first = performance.now();
@@ -886,10 +902,122 @@ async function loadEncryptionKeyWithFetch(context, callbacks, accessToken, signa
     response
   );
 }
+async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, state) {
+  const stats = createLoaderStats();
+  stats.loading.first = performance.now();
+  const canTryProxy = Boolean(plan.proxyUrl) && !state.circuitOpen && state.proxyFailures < plan.maxProxyFailures;
+  if (canTryProxy && plan.proxyUrl) {
+    while (!state.circuitOpen && state.proxyFailures < plan.maxProxyFailures && !signal.aborted) {
+      state.proxyFailures += 1;
+      try {
+        const response = await fetch(plan.proxyUrl, {
+          method: "GET",
+          headers: { Accept: "*/*" },
+          credentials: "same-origin",
+          cache: "no-store",
+          signal
+        });
+        const contentType = response.headers.get("content-type");
+        const data = await response.arrayBuffer();
+        const head = new TextDecoder().decode(data.slice(0, 64));
+        if (response.ok && !isProxyUpstreamBlocked(response.status, contentType, head)) {
+          const end = performance.now();
+          stats.loading.end = end;
+          stats.loaded = data.byteLength;
+          stats.total = data.byteLength;
+          callbacks.onSuccess(
+            {
+              url: response.url || plan.proxyUrl,
+              data,
+              code: response.status
+            },
+            stats,
+            { ...context, url: plan.proxyUrl },
+            response
+          );
+          return "ok";
+        }
+        if (isProxyUpstreamBlocked(
+          response.status,
+          contentType,
+          head,
+          response.statusText
+        )) {
+          if (response.status === 502 || contentType?.includes("text/html") || /Cloudflare|DOCTYPE|blocked/i.test(head)) {
+            state.circuitOpen = true;
+            break;
+          }
+          continue;
+        }
+        callbacks.onError(
+          {
+            code: response.status,
+            text: `enc.key proxy HTTP ${response.status}`
+          },
+          { ...context, url: plan.proxyUrl },
+          response,
+          stats
+        );
+        return "ok";
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+          callbacks.onError(
+            { code: 0, text: "enc.key proxy aborted/timeout" },
+            context,
+            null,
+            stats
+          );
+          return "ok";
+        }
+        state.circuitOpen = true;
+        break;
+      }
+    }
+    state.circuitOpen = true;
+  }
+  if (plan.accessToken) {
+    try {
+      await loadEncryptionKeyWithFetch(
+        { ...context, url: plan.signedKeyUrl },
+        callbacks,
+        plan.accessToken,
+        signal
+      );
+      return "ok";
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        callbacks.onError(
+          { code: 0, text: "enc.key fetch aborted/timeout" },
+          { ...context, url: plan.signedKeyUrl },
+          null,
+          stats
+        );
+        return "ok";
+      }
+      if (error instanceof TypeError || error instanceof Error && /Failed to fetch|NetworkError|CORS/i.test(error.message)) {
+        return "try_xhr";
+      }
+      callbacks.onError(
+        {
+          code: 0,
+          text: error instanceof Error ? error.message : "enc.key Bearer fetch failed"
+        },
+        { ...context, url: plan.signedKeyUrl },
+        null,
+        stats
+      );
+      return "ok";
+    }
+  }
+  return "try_xhr";
+}
 function createAuthParamsLoader(HlsClass, store, options = {}) {
   const BaseLoader = resolveBuiltinHlsLoader(HlsClass);
+  const maxProxyFailures = typeof options.keyProxyMaxFailures === "number" && options.keyProxyMaxFailures >= 0 ? options.keyProxyMaxFailures : KEY_PROXY_MAX_FAILURES;
+  const keyProxyState = { proxyFailures: 0, circuitOpen: false };
   return class AuthParamsLoader {
     constructor(config) {
+      this.context = null;
       this.keyAbort = null;
       this.inner = new BaseLoader(config);
       this.stats = this.inner.stats;
@@ -897,14 +1025,16 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
     abort() {
       this.keyAbort?.abort();
       this.keyAbort = null;
-      this.inner.abort?.();
+      this.inner.abort();
     }
     destroy() {
       this.keyAbort?.abort();
       this.keyAbort = null;
+      this.context = null;
       this.inner.destroy();
     }
     load(context, config, callbacks) {
+      this.context = context;
       if (!context.url) {
         this.inner.load(context, config, callbacks);
         return;
@@ -912,87 +1042,59 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
       try {
         const originalUrl = context.url;
         const isKey = isEncryptionKeyUrl(originalUrl);
-        const usingKeyProxy = Boolean(
-          isKey && options.keyProxyUrlBuilder && options.videoId
-        );
-        const signedKeyUrl = isKey ? rewriteHlsRequestUrl(originalUrl, store, {
-          ...options,
-          keyProxyUrlBuilder: void 0
-        }) : context.url;
-        context.url = rewriteHlsRequestUrl(originalUrl, store, options);
-        if (usingKeyProxy) {
-          const accessToken = options.getKeyAccessToken?.() ?? null;
-          if (!accessToken) {
-            this.inner.load(context, config, callbacks);
-            return;
+        if (!isKey) {
+          if (store.hasParams()) {
+            context.url = rewriteHlsRequestUrl(originalUrl, store, {
+              ...options,
+              keyProxyUrlBuilder: void 0
+            });
           }
-          const proxyCallbacks = {
-            ...callbacks,
-            onError: (error, errContext, networkDetails, stats) => {
-              const code = error?.code;
-              const retryable = code === 0 || code === 502 || code === 403 || code === 401 || /Cloudflare|HTML|DOCTYPE|blocked/i.test(error?.text ?? "");
-              if (!retryable) {
-                callbacks.onError(error, errContext, networkDetails, stats);
-                return;
-              }
-              this.keyAbort?.abort();
-              this.keyAbort = new AbortController();
-              const bearerContext = { ...context, url: signedKeyUrl };
-              void loadEncryptionKeyWithFetch(
-                bearerContext,
-                callbacks,
-                accessToken,
-                this.keyAbort.signal
-              ).catch((fetchError) => {
-                callbacks.onError(
-                  {
-                    code: 0,
-                    text: fetchError instanceof Error ? fetchError.message : error.text || "enc.key proxy and Bearer fetch failed"
-                  },
-                  bearerContext,
-                  null,
-                  stats
-                );
-              });
-            }
-          };
-          this.inner.load(context, config, proxyCallbacks);
+          this.inner.load(context, config, callbacks);
           return;
         }
-        if (isKey && typeof options.getKeyAccessToken === "function") {
-          const accessToken = options.getKeyAccessToken() ?? null;
-          if (accessToken) {
-            this.keyAbort?.abort();
-            this.keyAbort = new AbortController();
-            const timeoutMs = typeof config?.timeout === "number" && config.timeout > 0 ? config.timeout : 2e4;
-            const timer = setTimeout(() => this.keyAbort?.abort(), timeoutMs);
-            void loadEncryptionKeyWithFetch(
-              context,
-              callbacks,
-              accessToken,
-              this.keyAbort.signal
-            ).catch((error) => {
-              const stats = createLoaderStats();
-              const aborted = error instanceof DOMException && error.name === "AbortError";
-              if (!aborted && (error instanceof TypeError || error instanceof Error && /Failed to fetch|NetworkError|CORS/i.test(error.message))) {
-                this.inner.load(context, config, callbacks);
-                return;
-              }
-              callbacks.onError(
-                {
-                  code: 0,
-                  text: aborted ? "enc.key fetch aborted/timeout" : error instanceof Error ? error.message : "enc.key fetch failed"
-                },
-                context,
-                null,
-                stats
-              );
-            }).finally(() => {
-              clearTimeout(timer);
-            });
-            return;
+        const signedKeyUrl = rewriteHlsRequestUrl(originalUrl, store, {
+          ...options,
+          keyProxyUrlBuilder: void 0
+        });
+        const proxyConfigured = Boolean(
+          options.keyProxyUrlBuilder && options.videoId
+        );
+        const proxyUrl = proxyConfigured && !keyProxyState.circuitOpen ? rewriteHlsRequestUrl(originalUrl, store, options) : null;
+        const accessToken = options.getKeyAccessToken?.() ?? null;
+        this.keyAbort?.abort();
+        this.keyAbort = new AbortController();
+        const timeoutMs = typeof config?.timeout === "number" && config.timeout > 0 ? config.timeout : 2e4;
+        const timer = setTimeout(() => this.keyAbort?.abort(), timeoutMs);
+        void loadEncryptionKeyEnterprise(
+          context,
+          callbacks,
+          {
+            proxyUrl,
+            signedKeyUrl,
+            accessToken,
+            maxProxyFailures
+          },
+          this.keyAbort.signal,
+          keyProxyState
+        ).then((result) => {
+          if (result === "try_xhr") {
+            context.url = signedKeyUrl;
+            this.inner.load(context, config, callbacks);
           }
-        }
+        }).catch((error) => {
+          callbacks.onError(
+            {
+              code: 0,
+              text: error instanceof Error ? error.message : "enc.key load failed"
+            },
+            context,
+            null,
+            createLoaderStats()
+          );
+        }).finally(() => {
+          clearTimeout(timer);
+        });
+        return;
       } catch {
       }
       this.inner.load(context, config, callbacks);
@@ -1062,7 +1164,8 @@ var HlsEngine = class {
     const loader = createAuthParamsLoader(Hls, authParams, {
       videoId,
       keyProxyUrlBuilder,
-      getKeyAccessToken
+      getKeyAccessToken,
+      keyProxyMaxFailures: this.options.keyProxyMaxFailures
     });
     this.hls = new Hls({
       enableWorker: hlsConfig.enableWorker,
@@ -1487,10 +1590,11 @@ function createVideoPlayer(options) {
         videoId: options.videoId,
         keyProxyUrlBuilder: config.streaming.keyProxyUrlBuilder,
         // Enterprise AES key auth:
-        // 1) keyProxyUrlBuilder (same-origin BFF) when configured
+        // 1) keyProxyUrlBuilder (same-origin BFF) when configured — max 2 failures
         // 2) else getKeyAccessToken / AuthManager Bearer via browser fetch
         // 3) else signed query + XHR (CDN hosts)
         getKeyAccessToken: config.streaming.getKeyAccessToken ?? (() => authManager.getAccessToken()),
+        keyProxyMaxFailures: config.streaming.keyProxyMaxFailures,
         hlsConfig: config.streaming.hls,
         logger,
         callbacks: {
@@ -1808,7 +1912,8 @@ function createVideoPlayer(options) {
           engine: "hls",
           hls: { ...config.streaming.hls, ...partial?.streaming?.hls },
           keyProxyUrlBuilder: partial?.streaming?.keyProxyUrlBuilder ?? config.streaming.keyProxyUrlBuilder,
-          getKeyAccessToken: partial?.streaming?.getKeyAccessToken ?? config.streaming.getKeyAccessToken ?? (() => authManager.getAccessToken())
+          getKeyAccessToken: partial?.streaming?.getKeyAccessToken ?? config.streaming.getKeyAccessToken ?? (() => authManager.getAccessToken()),
+          keyProxyMaxFailures: partial?.streaming?.keyProxyMaxFailures ?? config.streaming.keyProxyMaxFailures
         },
         logging: { ...config.logging, ...partial?.logging },
         debug: { ...config.debug, ...partial?.debug },
@@ -1839,6 +1944,7 @@ export {
   DEFAULT_THEME,
   DEFAULT_WATERMARK,
   EventEmitter,
+  KEY_PROXY_MAX_FAILURES,
   PACKAGE_VERSION,
   PLAYBACK_RATES,
   PlaybackSourceManager,