@sidub-inc/licensing-client 1.5.59 → 1.5.73

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import React, { createContext, useMemo, useEffect, useContext } from 'react';
+import React, { createContext, useMemo, useRef, useEffect, useContext } from 'react';
 
 /**
  * Error class for licensing-related errors.
@@ -407,6 +407,12 @@ class RateLimitAssertion extends LicenseAssertion {
     /**
      * Checks if the feature's consumption is within its rate limit.
      * Prefers local feature state when available, falls back to server currentConsumption.
+     *
+     * The comparison is inclusive (`consumption <= rateLimit`), mirroring the .NET
+     * RateLimitLicenseAssertion exactly: the assertion still passes when consumption
+     * has already reached the limit, so the operation consuming past the final unit
+     * is permitted before the assertion begins failing. The SDKs must agree on this
+     * boundary — do not tighten it here independently of .NET.
      */
     isSatisfied(authorization, featureStates) {
         if (!authorization?.features) {
@@ -550,6 +556,159 @@ class CryptoError extends Error {
  * Signature validator for license authorization entities.
  * Validates that the authorization returned from the server has not been tampered with.
  */
+const SIGNATURE_MEMBER_KEY = '"__sidub_entitySignature"';
+function isJsonWhitespace(c) {
+    return c === ' ' || c === '\t' || c === '\n' || c === '\r';
+}
+/**
+ * Returns the index immediately after the closing quote of the JSON string
+ * starting at `startQuoteIndex`, honoring backslash escapes.
+ */
+function skipJsonString(text, startQuoteIndex) {
+    let i = startQuoteIndex + 1;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === '"') {
+            return i + 1;
+        }
+        i++;
+    }
+    return text.length;
+}
+/**
+ * Returns the index immediately after the JSON value starting at `start`.
+ * Handles strings (with escapes), bracket-matched objects/arrays, and primitives.
+ */
+function skipJsonValue(text, start) {
+    const c = text[start];
+    if (c === '"') {
+        return skipJsonString(text, start);
+    }
+    if (c === '{' || c === '[') {
+        let depth = 0;
+        let i = start;
+        while (i < text.length) {
+            const ch = text[i];
+            if (ch === '"') {
+                i = skipJsonString(text, i);
+                continue;
+            }
+            if (ch === '{' || ch === '[')
+                depth++;
+            else if (ch === '}' || ch === ']') {
+                depth--;
+                if (depth === 0)
+                    return i + 1;
+            }
+            i++;
+        }
+        return text.length;
+    }
+    // Primitive (number, true, false, null) — ends at a structural character.
+    let i = start;
+    while (i < text.length && text[i] !== ',' && text[i] !== '}' && text[i] !== ']' && !isJsonWhitespace(text[i])) {
+        i++;
+    }
+    return i;
+}
+/**
+ * Removes the member spanning [keyStart, valueEnd) together with its structural
+ * comma. The trailing comma is consumed when the member is first or in the middle;
+ * the leading comma when it is last — reconstructing the exact pre-signing bytes
+ * for a member the server appended (or prepended) to compact JSON.
+ */
+function removeMemberSpan(text, keyStart, valueEnd) {
+    let after = valueEnd;
+    while (after < text.length && isJsonWhitespace(text[after]))
+        after++;
+    if (text[after] === ',') {
+        return text.slice(0, keyStart) + text.slice(after + 1);
+    }
+    let before = keyStart - 1;
+    while (before >= 0 && isJsonWhitespace(text[before]))
+        before--;
+    if (before >= 0 && text[before] === ',') {
+        return text.slice(0, before) + text.slice(valueEnd);
+    }
+    return text.slice(0, keyStart) + text.slice(valueEnd);
+}
+/**
+ * Decodes the raw JSON value literal of the signature member into a base64 string.
+ * String values are unescaped via JSON.parse; byte-array values are converted to
+ * base64 (matching the .NET byte[] serialization mode); null/empty yield undefined.
+ */
+function decodeSignatureLiteral(valueLiteral) {
+    try {
+        const parsed = JSON.parse(valueLiteral);
+        if (typeof parsed === 'string') {
+            return parsed.length > 0 ? parsed : undefined;
+        }
+        if (Array.isArray(parsed)) {
+            const bytes = new Uint8Array(parsed);
+            let binary = '';
+            for (let i = 0; i < bytes.length; i++) {
+                binary += String.fromCharCode(bytes[i]);
+            }
+            return btoa(binary);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Textually extracts the `__sidub_entitySignature` member from a raw JSON response.
+ *
+ * The member and its structural comma are removed by string surgery — the response
+ * is never re-serialized, so the remaining text is byte-identical to what the
+ * server signed. Only a member of the top-level object is matched; occurrences of
+ * the key text inside string values cannot match because their quotes are escaped
+ * in raw JSON.
+ *
+ * @param rawText The exact response body text as received from the server.
+ * @returns The stripped text, the decoded signature, and whether the member was found.
+ */
+function extractEntitySignatureMember(rawText) {
+    const n = rawText.length;
+    let depth = 0;
+    let i = 0;
+    while (i < n) {
+        const c = rawText[i];
+        if (c === '"') {
+            if (depth === 1 && rawText.startsWith(SIGNATURE_MEMBER_KEY, i)) {
+                let j = i + SIGNATURE_MEMBER_KEY.length;
+                while (j < n && isJsonWhitespace(rawText[j]))
+                    j++;
+                if (rawText[j] === ':') {
+                    j++;
+                    while (j < n && isJsonWhitespace(rawText[j]))
+                        j++;
+                    const valueEnd = skipJsonValue(rawText, j);
+                    if (valueEnd > j) {
+                        return {
+                            strippedText: removeMemberSpan(rawText, i, valueEnd),
+                            signature: decodeSignatureLiteral(rawText.slice(j, valueEnd)),
+                            found: true
+                        };
+                    }
+                }
+            }
+            i = skipJsonString(rawText, i);
+            continue;
+        }
+        if (c === '{' || c === '[')
+            depth++;
+        else if (c === '}' || c === ']')
+            depth--;
+        i++;
+    }
+    return { strippedText: rawText, signature: undefined, found: false };
+}
 /**
  * Validates license authorization signatures to ensure integrity.
  *
@@ -586,13 +745,20 @@ class SignatureValidator {
         this.initialized = true;
     }
     /**
-     * Validates the signature of a license authorization using the raw server response.
+     * Validates the signature of a license authorization using a PARSED server response.
      *
      * The validation process:
      * 1. Extracts the signature from __sidub_entitySignature
-     * 2. Serializes the raw response data (excluding signature field)
+     * 2. Re-serializes the raw response data (excluding signature field)
      * 3. Verifies the signature using the configured public key
      *
+     * @deprecated Use {@link validateResponseText} instead (MON-205). Step 2 re-serializes an
+     * already-parsed object, and `JSON.stringify` does not round-trip byte-identically —
+     * property order, number formatting and string escaping can each differ from what the
+     * server actually signed, so a genuine authorization can fail verification.
+     * `validateResponseText` verifies the original response bytes and is what
+     * `LicensingClient` now uses; this method is retained only for compatibility.
+     *
      * @param rawResponse The raw server response (before client mapping)
      * @param options Validation options
      * @returns Validation result
@@ -650,6 +816,69 @@ class SignatureValidator {
             return { isValid: false, skipped: false, error: message };
         }
     }
+    /**
+     * Validates the signature of a license authorization against the exact raw
+     * response text (MON-205).
+     *
+     * Unlike {@link validateRawResponse}, which re-serializes a parsed object and is
+     * therefore sensitive to property-order and formatting differences, this method
+     * verifies against the original bytes: the `__sidub_entitySignature` member is
+     * removed textually and the remaining text is what the server actually signed.
+     *
+     * @param rawText The exact response body text as received from the server.
+     * @param options Validation options (same required/throwOnInvalid semantics).
+     * @returns Validation result
+     * @throws {CryptoError} If throwOnInvalid is true and validation fails
+     */
+    async validateResponseText(rawText, options = {}) {
+        const { throwOnInvalid = true, required = this.isConfigured } = options;
+        // If no crypto service configured, skip validation
+        if (!this.cryptoService) {
+            if (required) {
+                const error = 'Signature validation is required but no cryptography configuration was provided.';
+                if (throwOnInvalid) {
+                    throw new CryptoError(error, 'NOT_INITIALIZED');
+                }
+                return { isValid: false, skipped: false, error };
+            }
+            return { isValid: true, skipped: true };
+        }
+        // Ensure initialized
+        await this.initialize();
+        const { strippedText, signature } = extractEntitySignatureMember(rawText);
+        if (!signature) {
+            if (required) {
+                const error = 'Authorization does not contain a signature.';
+                if (throwOnInvalid) {
+                    throw new CryptoError(error, 'INVALID_SIGNATURE');
+                }
+                return { isValid: false, skipped: false, error };
+            }
+            return { isValid: true, skipped: true };
+        }
+        try {
+            const dataBytes = new TextEncoder().encode(strippedText);
+            const isValid = await this.cryptoService.verifySignature(dataBytes.buffer, signature);
+            if (!isValid) {
+                const error = 'Authorization signature verification failed. The authorization may have been tampered with.';
+                if (throwOnInvalid) {
+                    throw new CryptoError(error, 'INVALID_SIGNATURE');
+                }
+                return { isValid: false, skipped: false, error };
+            }
+            return { isValid: true, skipped: false };
+        }
+        catch (error) {
+            if (error instanceof CryptoError) {
+                throw error;
+            }
+            const message = `Signature validation error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+            if (throwOnInvalid) {
+                throw new CryptoError(message, 'VERIFICATION_FAILED');
+            }
+            return { isValid: false, skipped: false, error: message };
+        }
+    }
     /**
      * Serializes the raw server response for signature verification.
      * Removes the __sidub_entitySignature field and serializes to JSON.
@@ -754,11 +983,39 @@ function onStorageChange(prefix, callback) {
     return () => window.removeEventListener('storage', handler);
 }
 
+/** Default freshness TTL when the authorization carries no expiry. */
+const DEFAULT_TTL_MS = 3600000; // 1h
+/** Freshness is capped so revocation cannot stay invisible for the license lifetime. */
+const MAX_FRESH_TTL_MS = 86400000; // 24h
+/** Default stale-serve grace window beyond the freshness deadline. */
+const DEFAULT_GRACE_MS = 86400000; // 24h
+/** Upper bound for a configured grace window. */
+const MAX_GRACE_MS = 7 * 86400000; // 7d
+/**
+ * Non-cryptographic FNV-1a hash. Scoping only — localStorage key names must not
+ * contain raw API keys, and cache keys never need to be reversed.
+ */
+function hashKeyComponent(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
 /**
  * Authorization cache with TTL-based expiry, pseudo-LRU eviction, and localStorage persistence.
- * Cache key format: {licenseId}.{serviceKeyId}
+ * Cache key format: {licenseId}.{serviceKeyId}.{apiKeyHash}
  * One cache instance per LicensingClient — no singletons.
  *
+ * The API key participates in the cache key (hashed — never stored raw in
+ * localStorage key names) so an apiKey override can never read another tenant's
+ * cached authorization.
+ *
+ * Freshness TTL is capped at 24h regardless of license expiry; expired entries are
+ * retained for a bounded grace window and served only via getStale() — flagged, and
+ * only when they carry a validated server signature.
+ *
  * When a storagePrefix is provided, entries are persisted to localStorage and restored
  * on construction, surviving page refreshes. Cross-tab sync is available via onSync().
  */
@@ -767,13 +1024,16 @@ class AuthorizationCache {
      * Creates a new authorization cache.
      * @param maxSize The maximum number of entries to store before evicting the oldest. Defaults to 100.
      * @param storagePrefix Optional localStorage key prefix for persisting entries across page refreshes.
+     * @param graceMs Stale-serve grace window in milliseconds beyond the freshness deadline.
+     *   Defaults to 24h; capped at 7 days.
      */
-    constructor(maxSize = 100, storagePrefix) {
+    constructor(maxSize = 100, storagePrefix, graceMs) {
         this.cache = new Map();
         this.unsubscribe = null;
         this.maxSize = maxSize;
         this.storagePrefix = storagePrefix ?? null;
-        // Restore persisted entries, filtering out expired ones
+        this.graceMs = Math.min(Math.max(graceMs ?? DEFAULT_GRACE_MS, 0), MAX_GRACE_MS);
+        // Restore persisted entries, dropping ones past their stale window
         if (this.storagePrefix) {
             const keys = listKeys(this.storagePrefix);
             for (const fullKey of keys) {
@@ -782,7 +1042,7 @@ class AuthorizationCache {
                 const stored = load(fullKey);
                 if (!stored)
                     continue;
-                if (Date.now() >= stored.expiresAt) {
+                if (Date.now() >= (stored.staleUntil ?? stored.expiresAt)) {
                     remove(fullKey);
                     continue;
                 }
@@ -795,45 +1055,98 @@ class AuthorizationCache {
         }
     }
     /**
-     * Gets a cached authorization if it exists and has not expired.
+     * Builds the composite cache key. The API key is hashed so raw key material
+     * never appears in localStorage key names.
+     */
+    buildKey(licenseId, serviceKeyId, apiKey) {
+        const apiKeySegment = apiKey ? hashKeyComponent(apiKey) : '';
+        return `${licenseId}.${serviceKeyId}.${apiKeySegment}`;
+    }
+    /**
+     * Gets a cached authorization if it exists and is still fresh.
      * On hit, re-inserts the entry to move it to the end (pseudo-LRU freshness).
+     * Entries past freshness but within the grace window are kept (for getStale)
+     * but reported as a miss here.
      *
      * @param licenseId The license identifier.
      * @param serviceKeyId The service key identifier.
-     * @returns The cached authorization, or null if not cached or expired.
+     * @param apiKey The effective API key the authorization was fetched with.
+     * @returns The cached authorization, or null if not cached or no longer fresh.
      */
-    get(licenseId, serviceKeyId) {
-        const key = `${licenseId}.${serviceKeyId}`;
+    get(licenseId, serviceKeyId, apiKey) {
+        const key = this.buildKey(licenseId, serviceKeyId, apiKey);
         const entry = this.cache.get(key);
         if (!entry)
             return null;
-        // Lazy TTL — delete expired entries on access
-        if (Date.now() >= entry.expiresAt) {
+        const now = Date.now();
+        // Past the grace window — drop entirely
+        if (now >= entry.staleUntil) {
             this.cache.delete(key);
             if (this.storagePrefix) {
                 remove(this.storagePrefix + key);
             }
             return null;
         }
+        // Past freshness — retained for stale-serve only
+        if (now >= entry.expiresAt) {
+            return null;
+        }
         // Move to end of Map for pseudo-LRU freshness
         this.cache.delete(key);
         this.cache.set(key, entry);
         return entry.authorization;
     }
+    /**
+     * Gets an expired-but-graced authorization for stale-serve, flagged with isStale.
+     * Only entries whose signature was validated against the server response are
+     * eligible — unverified data must never be served past its freshness deadline.
+     *
+     * @param licenseId The license identifier.
+     * @param serviceKeyId The service key identifier.
+     * @param apiKey The effective API key the authorization was fetched with.
+     * @returns A flagged copy of the stale authorization, or null when none is eligible.
+     */
+    getStale(licenseId, serviceKeyId, apiKey) {
+        const key = this.buildKey(licenseId, serviceKeyId, apiKey);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        const now = Date.now();
+        if (now >= entry.staleUntil) {
+            this.cache.delete(key);
+            if (this.storagePrefix) {
+                remove(this.storagePrefix + key);
+            }
+            return null;
+        }
+        if (entry.authorization.signatureValidated !== true) {
+            return null;
+        }
+        // Still fresh — serve unflagged
+        if (now < entry.expiresAt) {
+            return entry.authorization;
+        }
+        return { ...entry.authorization, isStale: true };
+    }
     /**
      * Stores an authorization in the cache.
      * Evicts the oldest entry if max size is reached.
      *
+     * Freshness is min(license expiry, now + 24h) — default 1h when the
+     * authorization has no expiry. The stale window extends freshness by graceMs
+     * but never past the license's own expiry.
+     *
      * @param licenseId The license identifier.
      * @param serviceKeyId The service key identifier.
      * @param authorization The license authorization to cache.
-     */
-    set(licenseId, serviceKeyId, authorization) {
-        const key = `${licenseId}.${serviceKeyId}`;
-        // Compute expiresAt from authorization, default 1hr if no expiry
-        const expiresAt = authorization.expiresAt
-            ? authorization.expiresAt.getTime()
-            : Date.now() + 3600000;
+     * @param apiKey The effective API key the authorization was fetched with.
+     */
+    set(licenseId, serviceKeyId, authorization, apiKey) {
+        const key = this.buildKey(licenseId, serviceKeyId, apiKey);
+        const now = Date.now();
+        const hardExpiry = authorization.expiresAt ? authorization.expiresAt.getTime() : undefined;
+        const expiresAt = Math.min(hardExpiry ?? (now + DEFAULT_TTL_MS), now + MAX_FRESH_TTL_MS);
+        const staleUntil = Math.min(expiresAt + this.graceMs, hardExpiry ?? Number.MAX_SAFE_INTEGER);
         // If key already exists, delete first (so re-insert goes to end)
         if (this.cache.has(key)) {
             this.cache.delete(key);
@@ -848,9 +1161,10 @@ class AuthorizationCache {
                 }
             }
         }
-        this.cache.set(key, { authorization, expiresAt });
+        const entry = { authorization, expiresAt, staleUntil };
+        this.cache.set(key, entry);
         if (this.storagePrefix) {
-            save(this.storagePrefix + key, this.serializeEntry({ authorization, expiresAt }));
+            save(this.storagePrefix + key, this.serializeEntry(entry));
         }
     }
     /** Removes all cached entries */
@@ -897,7 +1211,7 @@ class AuthorizationCache {
             else {
                 try {
                     const stored = JSON.parse(newValue);
-                    if (Date.now() >= stored.expiresAt) {
+                    if (Date.now() >= (stored.staleUntil ?? stored.expiresAt)) {
                         this.cache.delete(cacheKey);
                         return;
                     }
@@ -933,6 +1247,7 @@ class AuthorizationCache {
     /**
      * Serializes a cache entry for localStorage storage.
      * Converts Date objects to epoch numbers for safe JSON round-tripping.
+     * All authorization fields (including isStale when present) round-trip via spread.
      */
     serializeEntry(entry) {
         const auth = entry.authorization;
@@ -942,11 +1257,13 @@ class AuthorizationCache {
                 issuedAt: auth.issuedAt instanceof Date ? auth.issuedAt.getTime() : auth.issuedAt,
                 expiresAt: auth.expiresAt instanceof Date ? auth.expiresAt.getTime() : auth.expiresAt
             },
-            expiresAt: entry.expiresAt
+            expiresAt: entry.expiresAt,
+            staleUntil: entry.staleUntil
         };
     }
     /**
      * Deserializes a cache entry from localStorage, reconstructing Date objects.
+     * Entries persisted before staleUntil existed get no grace window.
      */
     deserializeEntry(stored) {
         try {
@@ -956,7 +1273,11 @@ class AuthorizationCache {
                 issuedAt: raw.issuedAt ? new Date(raw.issuedAt) : new Date(),
                 expiresAt: raw.expiresAt ? new Date(raw.expiresAt) : undefined
             };
-            return { authorization, expiresAt: stored.expiresAt };
+            return {
+                authorization,
+                expiresAt: stored.expiresAt,
+                staleUntil: stored.staleUntil ?? stored.expiresAt
+            };
         }
         catch {
             return null;
@@ -1091,6 +1412,8 @@ class LicensingClient {
         this.disposables = [];
         this.contextResolved = false;
         this.contextResolutionPromise = null;
+        // MON-203: single-flight authorization fetches keyed on licenseId+serviceKeyId+apiKey.
+        this.inFlightAuthorizations = new Map();
         // Decode credential if provided
         this.credential = config.encodedCredential
             ? decodeCredential(config.encodedCredential)
@@ -1112,7 +1435,7 @@ class LicensingClient {
         // Initialize authorization cache (enabled by default) with localStorage persistence
         this.cacheEnabled = config.cacheEnabled !== false;
         this.authorizationCache = this.cacheEnabled
-            ? new AuthorizationCache(config.cacheMaxSize ?? 100, LicensingClient.AUTH_STORAGE_PREFIX)
+            ? new AuthorizationCache(config.cacheMaxSize ?? 100, LicensingClient.AUTH_STORAGE_PREFIX, config.staleGraceMs)
             : null;
         // Register cross-tab sync for authorization cache
         if (this.authorizationCache) {
@@ -1170,7 +1493,11 @@ class LicensingClient {
     }
     /**
      * Ensures context provider has been resolved before making API calls.
-     * Called once per client lifetime; concurrent callers share the same promise.
+     * Resolved once per client lifetime; concurrent callers share the same promise.
+     *
+     * MON-202: a failed attempt is not memoized — concurrent awaiters of the failed
+     * attempt receive that attempt's rejection, and the next call starts a fresh
+     * attempt. contextResolved only ever becomes true on success.
      */
     async ensureContextResolved() {
         if (this.contextResolved)
@@ -1183,7 +1510,7 @@ class LicensingClient {
             this.contextResolved = true;
             return;
         }
-        this.contextResolutionPromise = (async () => {
+        const resolutionAttempt = (async () => {
             const context = await this.config.contextProvider.resolveContext();
             if (context) {
                 const hadCrypto = !!(this.config.serviceKeyId && this.config.serviceKeyPublicMember);
@@ -1209,7 +1536,17 @@ class LicensingClient {
             }
             this.contextResolved = true;
         })();
-        await this.contextResolutionPromise;
+        this.contextResolutionPromise = resolutionAttempt;
+        try {
+            await resolutionAttempt;
+        }
+        catch (error) {
+            // Identity-guarded: refresh() may have installed a newer attempt already.
+            if (this.contextResolutionPromise === resolutionAttempt) {
+                this.contextResolutionPromise = null;
+            }
+            throw error;
+        }
     }
     /**
      * Builds the cryptography configuration from the resolved config values
@@ -1243,6 +1580,13 @@ class LicensingClient {
      * If cryptographic configuration is provided, the authorization signature will be
      * validated to ensure integrity. This mirrors the .NET LicensingService behavior.
      *
+     * Resilience (MON-203): transient failures (408/429/5xx/network) are retried with
+     * exponential backoff and jitter within the config.timeout budget, honoring
+     * Retry-After. Concurrent calls for the same license/key/apiKey share one
+     * in-flight request. When retries are exhausted on a transient failure, an
+     * expired-but-graced cached authorization is served flagged isStale — only if
+     * its signature was validated; never on 401/403/404 or any denial.
+     *
      * @param licenseId The unique identifier of the license (optional if configured via encodedCredential)
      * @param apiKey Optional API key for authentication (overrides config default)
      * @returns A promise resolving to the license authorization
@@ -1256,14 +1600,113 @@ class LicensingClient {
         if (!effectiveLicenseId) {
             throw new LicensingConfigurationException('License ID is required. Provide it as a parameter or via configuration.');
         }
+        const effectiveApiKey = apiKey || this.config.apiKey;
+        const serviceKeyId = this.config.serviceKeyId ?? '';
         // Check cache first
         if (this.cacheEnabled && this.authorizationCache) {
-            const cached = this.authorizationCache.get(effectiveLicenseId, this.config.serviceKeyId ?? '');
+            const cached = this.authorizationCache.get(effectiveLicenseId, serviceKeyId, effectiveApiKey);
             if (cached)
                 return cached;
         }
+        // In-flight dedup — concurrent callers share one request (and its rejection)
+        const flightKey = `${effectiveLicenseId}.${serviceKeyId}.${effectiveApiKey ?? ''}`;
+        const existing = this.inFlightAuthorizations.get(flightKey);
+        if (existing)
+            return existing;
+        const flight = this.executeAuthorizationFlight(effectiveLicenseId, effectiveApiKey);
+        this.inFlightAuthorizations.set(flightKey, flight);
+        try {
+            return await flight;
+        }
+        finally {
+            if (this.inFlightAuthorizations.get(flightKey) === flight) {
+                this.inFlightAuthorizations.delete(flightKey);
+            }
+        }
+    }
+    /**
+     * Runs the retrying fetch and, when it fails transiently, falls back to a
+     * stale-but-graced cached authorization. Non-transient failures (denials,
+     * signature failures) propagate untouched — they must never be masked.
+     */
+    async executeAuthorizationFlight(effectiveLicenseId, effectiveApiKey) {
+        try {
+            return await this.fetchAuthorizationWithRetry(effectiveLicenseId, effectiveApiKey);
+        }
+        catch (error) {
+            if (LicensingClient.isTransientError(error) && this.cacheEnabled && this.authorizationCache) {
+                const stale = this.authorizationCache.getStale(effectiveLicenseId, this.config.serviceKeyId ?? '', effectiveApiKey);
+                if (stale)
+                    return stale;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Determines whether an authorization/poll error is transient and safe to retry:
+     * network failures (no status), request timeouts (408), throttling (429), and
+     * server errors (5xx). Denials and client errors (401/403/404/4xx) are not.
+     */
+    static isTransientError(error) {
+        if (!(error instanceof LicensingError))
+            return false;
+        const status = error.statusCode;
+        if (status === undefined)
+            return true;
+        return status === 408 || status === 429 || status >= 500;
+    }
+    /**
+     * Parses a Retry-After header value (delta-seconds or HTTP-date) into milliseconds.
+     */
+    static parseRetryAfter(headerValue) {
+        if (!headerValue)
+            return undefined;
+        const seconds = Number(headerValue);
+        if (!Number.isNaN(seconds) && seconds >= 0) {
+            return seconds * 1000;
+        }
+        const date = Date.parse(headerValue);
+        if (!Number.isNaN(date)) {
+            return Math.max(0, date - Date.now());
+        }
+        return undefined;
+    }
+    /**
+     * Retries transient failures with exponential backoff and jitter, honoring
+     * Retry-After when the server supplied one. config.timeout is the overall
+     * budget — a retry whose delay would cross the deadline is not attempted.
+     */
+    async fetchAuthorizationWithRetry(effectiveLicenseId, effectiveApiKey) {
+        const deadline = Date.now() + (this.config.timeout ?? 30000);
+        let lastError;
+        for (let attempt = 0; attempt < LicensingClient.RETRY_MAX_ATTEMPTS; attempt++) {
+            if (attempt > 0) {
+                const retryAfterMs = lastError instanceof LicensingError ? lastError.retryAfterMs : undefined;
+                const backoffCap = Math.min(LicensingClient.RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1), LicensingClient.RETRY_MAX_DELAY_MS);
+                // Full backoff with jitter in [cap/2, cap]; Retry-After overrides the backoff.
+                const delayMs = retryAfterMs ?? Math.floor(backoffCap / 2 + Math.random() * (backoffCap / 2));
+                if (Date.now() + delayMs >= deadline)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+            try {
+                return await this.fetchAuthorization(effectiveLicenseId, effectiveApiKey);
+            }
+            catch (error) {
+                if (!LicensingClient.isTransientError(error)) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Performs a single authorization fetch attempt, validates the response
+     * signature against the exact raw response bytes, maps and caches the result.
+     */
+    async fetchAuthorization(effectiveLicenseId, effectiveApiKey) {
         const url = `${this.config.licenseServiceUri}/GenerateLicenseAuthorization`;
-        const effectiveApiKey = apiKey || this.config.apiKey;
         const headers = {
             'Content-Type': 'application/json',
         };
@@ -1291,16 +1734,21 @@ class LicensingClient {
             clearTimeout(timeoutId);
             if (!response.ok) {
                 const errorText = await response.text().catch(() => 'Unknown error');
-                throw new LicensingError(`Authorization failed: ${response.statusText}`, response.status, errorText);
+                const licensingError = new LicensingError(`Authorization failed: ${response.statusText}`, response.status, errorText);
+                licensingError.retryAfterMs = LicensingClient.parseRetryAfter(response.headers?.get?.('Retry-After'));
+                throw licensingError;
             }
-            const data = await response.json();
-            // Validate signature FIRST using raw server response (before any mapping)
-            // This ensures we verify against the exact bytes the server signed
+            // MON-205: capture the exact raw bytes; parse only after validation.
+            const rawText = await response.text();
+            // Validate signature FIRST against the raw response text with the signature
+            // member textually removed — the exact bytes the server signed. Never a
+            // re-serialization: JSON.stringify does not round-trip byte-identically.
             let signatureValidated = false;
             if (this.validateSignatures) {
-                const validationResult = await this.signatureValidator.validateRawResponse(data, { throwOnInvalid: true, required: this.signatureValidator.isConfigured });
+                const validationResult = await this.signatureValidator.validateResponseText(rawText, { throwOnInvalid: true, required: this.signatureValidator.isConfigured });
                 signatureValidated = validationResult.isValid && !validationResult.skipped;
             }
+            const data = JSON.parse(rawText);
             // Map server response to client model
             // Note: Server uses PascalCase, we convert to camelCase
             // Signature is returned as base64 string in __sidub_entitySignature from .NET
@@ -1331,9 +1779,10 @@ class LicensingClient {
             if (metadataChanged) {
                 this.persistFeatureMetadata();
             }
-            // Store in cache
+            // Store in cache — validation already happened above; the effective apiKey
+            // scopes the entry so an override can never read another tenant's cache.
             if (this.cacheEnabled && this.authorizationCache) {
-                this.authorizationCache.set(effectiveLicenseId, this.config.serviceKeyId ?? '', authorization);
+                this.authorizationCache.set(effectiveLicenseId, this.config.serviceKeyId ?? '', authorization, effectiveApiKey);
             }
             return authorization;
         }
@@ -1536,6 +1985,8 @@ class LicensingClient {
         // Reset context resolution so ensureContextResolved() re-runs with new config
         this.contextResolved = false;
         this.contextResolutionPromise = null;
+        // Pre-refresh in-flight authorization fetches must not satisfy post-refresh calls
+        this.inFlightAuthorizations.clear();
     }
     assertLicense(assertion, authorization) {
         // Auto-inject feature states for RateLimitAssertion
@@ -1601,9 +2052,14 @@ class LicensingClient {
      * Reports license feature consumption/usage to the server.
      * This is used for metering and billing purposes.
      *
+     * Billability is derived from the resolved authorization's license classification:
+     * only Subscription licenses meter billable usage (mirrors .NET
+     * LicensingService.PerformOperation). Each report carries a freshly minted
+     * SubmissionId so the server can deduplicate retried submissions.
+     *
      * @param operation The operation to report
      * @returns A promise that resolves when the operation is reported
-     * @throws {LicensingError} If the request fails
+     * @throws {LicensingError} If the request fails or the authorization cannot be resolved
      */
     async performOperation(operation) {
         await this.ensureContextResolved();
@@ -1611,6 +2067,10 @@ class LicensingClient {
         if (!this.config.consumptionServiceUri) {
             return;
         }
+        // MON-184: billable if and only if the license classification is Subscription —
+        // the authorization is resolved through the cache-aware path (fetch on miss).
+        const authorization = await this.getAuthorization(operation.licenseId);
+        const isBillable = authorization.classification === LicenseClassificationType.Subscription;
         const url = `${this.config.consumptionServiceUri}/messages`;
         const apiKey = this.config.apiKey;
         const headers = {
@@ -1630,9 +2090,11 @@ class LicensingClient {
                 headers,
                 body: JSON.stringify({
                     LicenseId: operation.licenseId,
+                    // MON-187: per-call idempotency key — the server dedups on SubmissionId.
+                    SubmissionId: this.generateRequestId(),
                     BillableResourceId: this.config.billableResourceId ?? '00000000-0000-0000-0000-000000000000',
                     BillablePlanId: this.config.billablePlanId ?? '',
-                    IsBillable: true,
+                    IsBillable: isBillable,
                     LicenseOperation: {
                         LicenseFeature: {
                             FeatureKey: operation.feature.featureId
@@ -1703,6 +2165,8 @@ class LicensingClient {
             : '';
         const body = JSON.stringify({
             LicenseId: effectiveLicenseId,
+            // MON-187: per-call idempotency key — the server dedups on SubmissionId.
+            SubmissionId: this.generateRequestId(),
             BillableResourceId: this.config.billableResourceId ?? '00000000-0000-0000-0000-000000000000',
             BillablePlanId: this.config.billablePlanId ?? '',
             IsBillable: false,
@@ -1892,25 +2356,51 @@ class LicensingClient {
      * Polls for a checkout session result with exponential backoff.
      * Replaces the useCheckout hook pattern with an imperative API.
      *
+     * Resilience (MON-204): transient failures (408/429/5xx/network) inside the loop
+     * are tolerated up to a consecutive-failure budget, with the backoff sleep also
+     * running after failed attempts. Caller cancellation propagates immediately —
+     * an aborted signal wins over a retryable 408, since getCheckoutResult converts
+     * an aborted request into LicensingError('Request timeout', 408). Denials
+     * (401/403/404) fail fast.
+     *
      * @param sessionId The session ID from createCheckoutSession()
      * @param options Optional: apiKey override, AbortSignal for cancellation, maxAttempts (default 60)
      * @returns The completed or failed checkout session result
-     * @throws {LicensingError} If polling times out or the request fails
+     * @throws {LicensingError} If polling times out, is cancelled, or fails non-transiently
      */
     async pollCheckoutResult(sessionId, options) {
         const maxAttempts = options?.maxAttempts ?? 60;
         const signal = options?.signal;
         let delay = 1000;
         const maxDelay = 15000;
+        const consecutiveFailureBudget = 5;
+        let consecutiveFailures = 0;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             if (signal?.aborted) {
                 throw new LicensingError('Checkout polling cancelled');
             }
-            const result = await this.getCheckoutResult(sessionId, options?.apiKey);
-            if (result.status === 'completed' || result.status === 'failed') {
+            let result = null;
+            try {
+                result = await this.getCheckoutResult(sessionId, options?.apiKey);
+                consecutiveFailures = 0;
+            }
+            catch (error) {
+                // Cancellation surfaces as an abort-derived 408 — it must never be retried.
+                if (signal?.aborted) {
+                    throw new LicensingError('Checkout polling cancelled');
+                }
+                if (!LicensingClient.isTransientError(error)) {
+                    throw error;
+                }
+                consecutiveFailures++;
+                if (consecutiveFailures >= consecutiveFailureBudget) {
+                    throw error;
+                }
+            }
+            if (result && (result.status === 'completed' || result.status === 'failed')) {
                 return result;
             }
-            // Wait with exponential backoff
+            // Wait with exponential backoff — after failed attempts too
             await new Promise((resolve) => {
                 const timer = setTimeout(resolve, delay);
                 if (signal) {
@@ -1933,6 +2423,11 @@ class LicensingClient {
 LicensingClient.METADATA_STORAGE_KEY = 'sidub.licensing.metadata';
 LicensingClient.CONSUMPTION_STORAGE_PREFIX = 'sidub.licensing.consumption.';
 LicensingClient.AUTH_STORAGE_PREFIX = 'sidub.licensing.auth.';
+// MON-203: bounded retry policy for transient authorization failures. The overall
+// budget is config.timeout — retries never extend total time past it.
+LicensingClient.RETRY_MAX_ATTEMPTS = 4; // 1 initial + 3 retries
+LicensingClient.RETRY_BASE_DELAY_MS = 500;
+LicensingClient.RETRY_MAX_DELAY_MS = 8000;
 
 /**
  * Assertion that checks if a feature with a specific key exists in the authorization.
@@ -2111,10 +2606,17 @@ const LicensingProvider = ({ config, children }) => {
     // Phase 11 D-11: when the encoded credential changes, invalidate client state and
     // rebuild credential config without remounting the component tree.
     // The `key={credential}` remount idiom is a deprecated fallback.
+    // MON-189: the effect also fires on first mount — the client was just constructed
+    // from this exact credential, so refresh() must only run on an actual change.
+    const observedCredentialRef = useRef(null);
     useEffect(() => {
-        if (config.encodedCredential !== undefined) {
-            void value.client.refresh(config);
-        }
+        const observed = observedCredentialRef.current;
+        observedCredentialRef.current = { credential: config.encodedCredential };
+        if (observed === null)
+            return;
+        if (observed.credential === config.encodedCredential)
+            return;
+        void value.client.refresh(config);
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [config.encodedCredential]);
     return (React.createElement(LicensingContext.Provider, { value: value }, children));
@@ -2253,5 +2755,5 @@ class ConfigurationContextProvider {
     }
 }
 
-export { AuthorizationCache, BillingIntervalUnit, CompositeAssertion, ConfigurationContextProvider, CryptoError, CryptoService, FeatureExistsAssertion, LicenseAssertion, LicenseClassificationType, LicensingClient, LicensingConfigurationException, LicensingError, LicensingProvider, NotAssertion, RateLimitAssertion, RateLimitError, RateLimitFeatureState, ServiceAccessAssertion, ServiceAccessLevel, SignatureValidator, decodeCredential, encodeCredential, findFeatureByKey, getFeatureKey, hasFeature, hasValidCryptoConfig, licensingContextFromEncodedString, licensingContextToEncodedString, listKeys, load, matchesFeatureKey, normalizeBillingIntervalUnit, normalizeLicenseClassificationType, normalizeServiceAccessLevel, onStorageChange, remove, save, tryDecodeCredential, useLicensingContext, useLicensingContextValue };
+export { AuthorizationCache, BillingIntervalUnit, CompositeAssertion, ConfigurationContextProvider, CryptoError, CryptoService, FeatureExistsAssertion, LicenseAssertion, LicenseClassificationType, LicensingClient, LicensingConfigurationException, LicensingError, LicensingProvider, NotAssertion, RateLimitAssertion, RateLimitError, RateLimitFeatureState, ServiceAccessAssertion, ServiceAccessLevel, SignatureValidator, decodeCredential, encodeCredential, extractEntitySignatureMember, findFeatureByKey, getFeatureKey, hasFeature, hasValidCryptoConfig, licensingContextFromEncodedString, licensingContextToEncodedString, listKeys, load, matchesFeatureKey, normalizeBillingIntervalUnit, normalizeLicenseClassificationType, normalizeServiceAccessLevel, onStorageChange, remove, save, tryDecodeCredential, useLicensingContext, useLicensingContextValue };
 //# sourceMappingURL=index.esm.js.map