@sidub-inc/licensing-client 1.5.170 → 1.6.0

package/dist/index.cjs

@@ -2,9 +2,36 @@
 
 var React = require('react');
 
+/**
+ * Parses a Retry-After header value (delta-seconds or HTTP-date) into
+ * milliseconds. Returns undefined when absent or unparseable.
+ */
+function 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;
+}
+function asOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
 /**
  * Error class for licensing-related errors.
  * Thrown when API requests fail, authorization is denied, or network errors occur.
+ *
+ * When the failure came from the licensing service over HTTP, the server's
+ * shared ApiError contract {Code, Message, CorrelationId, Details[]} is parsed
+ * onto the error (MON-334 SR2): branch on {@link code} for machine handling and
+ * quote {@link correlationId} in support requests. Both are undefined only for
+ * failures that never reached the server (network errors, timeouts) or when the
+ * server did not supply them.
  */
 class LicensingError extends Error {
     /**
@@ -19,6 +46,61 @@ class LicensingError extends Error {
         this.response = response;
         this.name = 'LicensingError';
     }
+    /**
+     * Builds a LicensingError from a non-OK HTTP response, parsing the server's
+     * shared ApiError contract {Code, Message, CorrelationId, Details[]} plus the
+     * X-Correlation-Id and Retry-After response headers (MON-334 SR2).
+     *
+     * The machine code and correlation id are never dropped: when the body is not
+     * a parseable ApiError the correlation id still comes from the header, and
+     * the raw body text is always preserved on {@link response}. The message
+     * prefers the server's human-readable ApiError.Message and falls back to the
+     * HTTP status text only when no server message is available.
+     *
+     * @param operation Human-readable operation name used as the message prefix
+     *   (e.g. 'Authorization' → 'Authorization failed: ...').
+     * @param response The non-OK fetch response (or a structural equivalent).
+     * @returns The constructed error, ready to throw.
+     */
+    static async fromHttpResponse(operation, response) {
+        const rawBody = response.text
+            ? await response.text().catch(() => 'Unknown error')
+            : 'Unknown error';
+        let code;
+        let serverMessage;
+        let bodyCorrelationId;
+        let details;
+        try {
+            const parsed = JSON.parse(rawBody);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                code = asOptionalString(parsed.Code ?? parsed.code);
+                serverMessage = asOptionalString(parsed.Message ?? parsed.message);
+                bodyCorrelationId = asOptionalString(parsed.CorrelationId ?? parsed.correlationId);
+                const rawDetails = parsed.Details ?? parsed.details;
+                if (Array.isArray(rawDetails) && rawDetails.length > 0) {
+                    details = rawDetails.map((d) => {
+                        const detail = (d ?? {});
+                        return {
+                            code: asOptionalString(detail.Code ?? detail.code),
+                            message: asOptionalString(detail.Message ?? detail.message),
+                            field: asOptionalString(detail.Field ?? detail.field),
+                            targetId: asOptionalString(detail.TargetId ?? detail.targetId)
+                        };
+                    });
+                }
+            }
+        }
+        catch {
+            // Body is not JSON — the raw text is still preserved on `response`.
+        }
+        const headerCorrelationId = asOptionalString(response.headers?.get?.('X-Correlation-Id') ?? undefined);
+        const error = new LicensingError(`${operation} failed: ${serverMessage ?? response.statusText ?? 'HTTP error'}`, response.status, rawBody);
+        error.code = code;
+        error.correlationId = bodyCorrelationId ?? headerCorrelationId;
+        error.details = details;
+        error.retryAfterMs = parseRetryAfter(response.headers?.get?.('Retry-After'));
+        return error;
+    }
 }
 
 /**
@@ -127,6 +209,16 @@ const CURRENT_VERSION = 1;
  * Encodes a licensing credential to a portable string.
  * This matches the .NET LicensingCredential.ToEncodedString() format.
  *
+ * SECURITY (MON-334 react-08): the encoded string is base64-OBFUSCATED, not
+ * encrypted — it contains the apiAccessKey in recoverable form. Do not store
+ * it anywhere page JavaScript can read (localStorage, sessionStorage,
+ * non-httpOnly cookies): any XSS on the page reads the credential. For
+ * browser apps prefer a backend-held credential with a short-lived token.
+ * The SDK itself never writes this value (or the apiAccessKey) to
+ * localStorage — it persists only authorization payloads and consumption
+ * counters, and the apiAccessKey appears in storage key names only as a
+ * non-reversible hash.
+ *
  * @param credential The credential to encode
  * @returns A portable encoded string prefixed with SIDUB_LIC_
  */
@@ -221,7 +313,8 @@ function hasValidCryptoConfig(credential) {
 
 /**
  * Gets the normalized feature key from a feature object.
- * Handles both client-side (featureId) and server-side (FeatureKey) naming conventions.
+ * Handles both the SDK model (featureKey) and raw server (FeatureKey) naming.
+ * The legacy `featureId` alias was removed in 2.0 (MON-334 SR4).
  *
  * @param feature The feature object to extract the key from
  * @returns The feature key, or empty string if not found
@@ -230,12 +323,12 @@ function getFeatureKey(feature) {
     if (!feature) {
         return '';
     }
-    // Check both camelCase (client) and PascalCase (server) conventions
-    return feature.featureId || feature.FeatureKey || '';
+    // Check both camelCase (SDK model) and PascalCase (raw server) conventions
+    return feature.featureKey || feature.FeatureKey || '';
 }
 /**
  * Checks if a feature matches the specified feature key.
- * Handles both client-side (featureId) and server-side (FeatureKey) naming conventions.
+ * Handles both the SDK model (featureKey) and raw server (FeatureKey) naming.
  *
  * @param feature The feature to check
  * @param featureKey The key to match against
@@ -403,7 +496,7 @@ class RateLimitAssertion extends LicenseAssertion {
             this.featureKey = featureKeyOrFeature;
         }
         else {
-            this.featureKey = featureKeyOrFeature.featureId;
+            this.featureKey = featureKeyOrFeature.featureKey;
         }
     }
     /**
@@ -746,86 +839,17 @@ class SignatureValidator {
         await this.cryptoService.initialize();
         this.initialized = true;
     }
-    /**
-     * Validates the signature of a license authorization using a PARSED server response.
-     *
-     * The validation process:
-     * 1. Extracts the signature from __sidub_entitySignature
-     * 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
-     * @throws {CryptoError} If throwOnInvalid is true and validation fails
-     */
-    async validateRawResponse(rawResponse, 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();
-        // Check if response has a signature
-        const signature = rawResponse.__sidub_entitySignature;
-        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 {
-            // Serialize the raw response data for verification (excluding signature)
-            const dataToVerify = this.serializeRawForVerification(rawResponse);
-            const dataBytes = new TextEncoder().encode(dataToVerify);
-            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 };
-        }
-    }
     /**
      * 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.
+     * This is the ONLY validation entry point. The deprecated
+     * `validateRawResponse` — which re-serialized a parsed object and was
+     * therefore sensitive to property-order and formatting differences, letting
+     * genuine authorizations fail verification — was removed in 2.0 (MON-334
+     * react-10). 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).
@@ -881,16 +905,6 @@ class SignatureValidator {
             return { isValid: false, skipped: false, error: message };
         }
     }
-    /**
-     * Serializes the raw server response for signature verification.
-     * Removes the __sidub_entitySignature field and serializes to JSON.
-     */
-    serializeRawForVerification(rawResponse) {
-        // Create a copy without the signature field
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { __sidub_entitySignature, ...dataWithoutSignature } = rawResponse;
-        return JSON.stringify(dataWithoutSignature);
-    }
 }
 
 /**
@@ -1028,13 +1042,18 @@ class AuthorizationCache {
      * @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.
+     * @param freshTtlMs Upper bound in milliseconds on how long an entry stays fresh
+     *   before revalidation (MON-334 react-09). Defaults to 24h (the historical cap);
+     *   lower values tighten the revocation window at the cost of more server calls.
+     *   Capped at 24h; 0 means every read revalidates.
      */
-    constructor(maxSize = 100, storagePrefix, graceMs) {
+    constructor(maxSize = 100, storagePrefix, graceMs, freshTtlMs) {
         this.cache = new Map();
         this.unsubscribe = null;
         this.maxSize = maxSize;
         this.storagePrefix = storagePrefix ?? null;
         this.graceMs = Math.min(Math.max(graceMs ?? DEFAULT_GRACE_MS, 0), MAX_GRACE_MS);
+        this.freshTtlMs = Math.min(Math.max(freshTtlMs ?? MAX_FRESH_TTL_MS, 0), MAX_FRESH_TTL_MS);
         // Restore persisted entries, dropping ones past their stale window
         if (this.storagePrefix) {
             const keys = listKeys(this.storagePrefix);
@@ -1134,10 +1153,16 @@ class AuthorizationCache {
      * 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
+     * Freshness is min(license expiry, now + freshTtlMs) — default 1h when the
      * authorization has no expiry. The stale window extends freshness by graceMs
      * but never past the license's own expiry.
      *
+     * Revocation trade-off (MON-334 react-09): a revoked/denied license keeps
+     * authorizing from cache until its freshness deadline — up to freshTtlMs
+     * (default 24h) — plus, on transient outages only, the stale-serve grace.
+     * Tighten freshTtlMs to shrink that window; denials (401/403/404) are never
+     * stale-served.
+     *
      * @param licenseId The license identifier.
      * @param serviceKeyId The service key identifier.
      * @param authorization The license authorization to cache.
@@ -1147,7 +1172,8 @@ class AuthorizationCache {
         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 noExpiryTtl = Math.min(DEFAULT_TTL_MS, this.freshTtlMs);
+        const expiresAt = Math.min(hardExpiry ?? (now + noExpiryTtl), now + this.freshTtlMs);
         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)) {
@@ -1414,6 +1440,8 @@ class LicensingClient {
         this.disposables = [];
         this.contextResolved = false;
         this.contextResolutionPromise = null;
+        // MON-334 react-03: the unsigned-mode warning fires at most once per client.
+        this.signaturePostureWarned = false;
         // MON-203: single-flight authorization fetches keyed on licenseId+serviceKeyId+apiKey.
         this.inFlightAuthorizations = new Map();
         // Decode credential if provided
@@ -1437,7 +1465,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, config.staleGraceMs)
+            ? new AuthorizationCache(config.cacheMaxSize ?? 100, LicensingClient.AUTH_STORAGE_PREFIX, config.staleGraceMs, config.cacheFreshTtlMs)
             : null;
         // Register cross-tab sync for authorization cache
         if (this.authorizationCache) {
@@ -1550,6 +1578,25 @@ class LicensingClient {
             throw error;
         }
     }
+    /**
+     * Applies the gateway credential headers to an outgoing request. Mirrors the
+     * .NET SDK's GatewayAuthHeaders/GatewayAuthHeaderNames exactly: the ApiAccessKey
+     * is sent as the branded `dub-apiKey` header (the gateway's configured
+     * subscription-key name) and additionally as the platform-default
+     * `Ocp-Apim-Subscription-Key` header, so the SDK keeps authenticating against a
+     * gateway provisioned with the Azure default name (the MON-42 → MON-52
+     * regression class). The gateway strips the redundant copy before forwarding.
+     *
+     * Header-only by design (MON-66 parity, MON-334 SR3): the key is never placed
+     * in the URL query string, where it would leak into browser history, Referer
+     * headers on redirects, and CDN/proxy/gateway access logs.
+     */
+    static applyAuthHeaders(headers, apiKey) {
+        if (!apiKey)
+            return;
+        headers['dub-apiKey'] = apiKey;
+        headers['Ocp-Apim-Subscription-Key'] = apiKey;
+    }
     /**
      * Builds the cryptography configuration from the resolved config values
      */
@@ -1569,6 +1616,38 @@ class LicensingClient {
     get isSignatureValidationEnabled() {
         return this.validateSignatures && this.signatureValidator.isConfigured;
     }
+    /**
+     * Makes the signature-validation posture explicit (MON-334 react-03).
+     * Runs after context resolution, before any authorization is accepted:
+     *
+     * - `validateSignatures: true` with no verification key is a contradiction —
+     *   the integrator demanded validation that cannot happen. Previously this
+     *   silently skipped; it now throws {@link LicensingConfigurationException}.
+     * - Validation silently OFF (no keys configured, `validateSignatures` unset)
+     *   emits one prominent console warning per client. Setting
+     *   `validateSignatures: false` explicitly acknowledges unsigned mode and
+     *   suppresses the warning.
+     *
+     * Check {@link isSignatureValidationEnabled} at runtime to observe the
+     * effective posture.
+     */
+    assertSignaturePosture() {
+        if (this.validateSignatures && !this.signatureValidator.isConfigured) {
+            throw new LicensingConfigurationException('Signature validation was requested (validateSignatures: true) but no verification key is configured. ' +
+                'Provide serviceKeyId and serviceKeyPublicMember (or an encodedCredential that carries them), ' +
+                'or set validateSignatures: false explicitly to accept unsigned authorizations.');
+        }
+        if (!this.validateSignatures &&
+            this.config.validateSignatures === undefined &&
+            !this.signaturePostureWarned) {
+            this.signaturePostureWarned = true;
+            console.warn('[Sidub.Licensing] Signature validation is DISABLED: no serviceKeyId/serviceKeyPublicMember is configured, ' +
+                'so license authorizations are accepted without cryptographic verification. ' +
+                'Configure an encodedCredential (which carries the verification key) to enable validation, ' +
+                'or set validateSignatures: false explicitly to acknowledge unsigned mode and silence this warning. ' +
+                'Inspect client.isSignatureValidationEnabled to observe the effective posture.');
+        }
+    }
     /**
      * Gets the configured license ID (from credential or explicit config)
      */
@@ -1597,6 +1676,9 @@ class LicensingClient {
      */
     async getAuthorization(licenseId, apiKey) {
         await this.ensureContextResolved();
+        // react-03: surface the signature posture before any authorization —
+        // cached or fetched — is accepted.
+        this.assertSignaturePosture();
         // Use provided licenseId or fall back to configured value
         const effectiveLicenseId = licenseId || this.config.licenseId;
         if (!effectiveLicenseId) {
@@ -1657,22 +1739,6 @@ class LicensingClient {
             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
@@ -1712,22 +1778,17 @@ class LicensingClient {
         const headers = {
             'Content-Type': 'application/json',
         };
-        // Add authentication headers if API key is provided
-        if (effectiveApiKey) {
-            headers['dub-issuerKey'] = effectiveApiKey;
-        }
+        // Credential travels header-only (dub-apiKey + Ocp-Apim-Subscription-Key) —
+        // never in the URL. The dead dub-issuerKey header was removed in 2.0 (MON-334).
+        LicensingClient.applyAuthHeaders(headers, effectiveApiKey);
         const parameters = {
             RequestId: this.generateRequestId(),
             LicenseId: effectiveLicenseId
         };
-        // Add query parameters for API key if provided
-        const queryParams = effectiveApiKey
-            ? `?subscription-key=${encodeURIComponent(effectiveApiKey)}`
-            : '';
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(`${url}${queryParams}`, {
+            const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(parameters),
@@ -1735,10 +1796,9 @@ class LicensingClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                const errorText = await response.text().catch(() => 'Unknown error');
-                const licensingError = new LicensingError(`Authorization failed: ${response.statusText}`, response.status, errorText);
-                licensingError.retryAfterMs = LicensingClient.parseRetryAfter(response.headers?.get?.('Retry-After'));
-                throw licensingError;
+                // SR2: parse the shared ApiError body + X-Correlation-Id header —
+                // the machine code and correlation id must never be dropped.
+                throw await LicensingError.fromHttpResponse('Authorization', response);
             }
             // MON-205: capture the exact raw bytes; parse only after validation.
             const rawText = await response.text();
@@ -1774,7 +1834,7 @@ class LicensingClient {
                 const rf = f;
                 const ss = rf.sampleSeconds ?? rf.SampleSeconds;
                 if (ss !== undefined && typeof ss === 'number') {
-                    this.featureMetadata.set(`${authorization.licenseId}.${f.featureId}`, ss);
+                    this.featureMetadata.set(`${authorization.licenseId}.${f.featureKey}`, ss);
                     metadataChanged = true;
                 }
             }
@@ -1816,10 +1876,12 @@ class LicensingClient {
         }
         return serverFeatures.map((f) => {
             const sf = f;
-            // Normalize featureId from PascalCase server response
-            const featureId = String(sf.FeatureKey ?? sf.featureKey ?? sf.featureId ?? '');
+            // Normalize featureKey from the PascalCase server wire field (SR4:
+            // wire names frozen — the server sends FeatureKey; the SDK model
+            // exposes camelCase featureKey).
+            const featureKey = String(sf.FeatureKey ?? sf.featureKey ?? '');
             // Build normalized feature with camelCase properties only
-            const feature = { featureId };
+            const feature = { featureKey };
             // ServiceAccessLevel (ServiceAccessLicenseFeature)
             const rawAccess = sf.ServiceAccessLevel ?? sf.serviceAccessLevel;
             if (rawAccess !== undefined) {
@@ -1899,14 +1961,14 @@ class LicensingClient {
         }
         const features = auth.features.map((f) => {
             const sf = f;
-            const featureKey = String(sf.featureId ?? '');
+            const featureKey = String(sf.featureKey ?? '');
             const displayName = String(sf.displayName ?? sf.featureName ?? featureKey);
             return { featureKey, displayName };
         });
         const consumption = [];
         for (const f of auth.features) {
             const sf = f;
-            const featureKey = String(sf.featureId ?? '');
+            const featureKey = String(sf.featureKey ?? '');
             const rateLimit = sf.rateLimit;
             const sampleSeconds = sf.sampleSeconds;
             if (rateLimit === undefined || sampleSeconds === undefined)
@@ -1987,6 +2049,8 @@ class LicensingClient {
         // Reset context resolution so ensureContextResolved() re-runs with new config
         this.contextResolved = false;
         this.contextResolutionPromise = null;
+        // New credential epoch — the signature posture may have changed (react-03)
+        this.signaturePostureWarned = false;
         // Pre-refresh in-flight authorization fetches must not satisfy post-refresh calls
         this.inFlightAuthorizations.clear();
     }
@@ -2078,16 +2142,11 @@ class LicensingClient {
         const headers = {
             'Content-Type': 'application/json',
         };
-        if (apiKey) {
-            headers['dub-apiKey'] = apiKey;
-        }
-        const queryParams = apiKey
-            ? `?subscription-key=${encodeURIComponent(apiKey)}`
-            : '';
+        LicensingClient.applyAuthHeaders(headers, apiKey);
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(`${url}${queryParams}`, {
+            const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({
@@ -2099,7 +2158,7 @@ class LicensingClient {
                     IsBillable: isBillable,
                     LicenseOperation: {
                         LicenseFeature: {
-                            FeatureKey: operation.feature.featureId
+                            FeatureKey: operation.feature.featureKey
                         },
                         Amount: operation.quantity ?? 1
                     }
@@ -2108,11 +2167,10 @@ class LicensingClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                const errorText = await response.text().catch(() => 'Unknown error');
-                throw new LicensingError(`Consumption report failed: ${response.statusText}`, response.status, errorText);
+                throw await LicensingError.fromHttpResponse('Consumption report', response);
             }
             // Update local feature state after successful server report (auto-create if needed)
-            const stateKey = `${operation.licenseId}.${operation.feature.featureId}`;
+            const stateKey = `${operation.licenseId}.${operation.feature.featureKey}`;
             let state = this.featureStates.get(stateKey);
             if (!state) {
                 const sampleSeconds = this.featureMetadata.get(stateKey) ?? 3600;
@@ -2159,12 +2217,7 @@ class LicensingClient {
         const headers = {
             'Content-Type': 'application/json',
         };
-        if (effectiveApiKey) {
-            headers['dub-apiKey'] = effectiveApiKey;
-        }
-        const queryParams = effectiveApiKey
-            ? `?subscription-key=${encodeURIComponent(effectiveApiKey)}`
-            : '';
+        LicensingClient.applyAuthHeaders(headers, effectiveApiKey);
         const body = JSON.stringify({
             LicenseId: effectiveLicenseId,
             // MON-187: per-call idempotency key — the server dedups on SubmissionId.
@@ -2182,7 +2235,7 @@ class LicensingClient {
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(`${url}${queryParams}`, {
+            const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body,
@@ -2190,8 +2243,7 @@ class LicensingClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                const errorText = await response.text().catch(() => 'Unknown error');
-                throw new LicensingError(`Access check report failed: ${response.statusText}`, response.status, errorText);
+                throw await LicensingError.fromHttpResponse('Access check report', response);
             }
         }
         catch (error) {
@@ -2224,12 +2276,7 @@ class LicensingClient {
         const headers = {
             'Content-Type': 'application/json',
         };
-        if (effectiveApiKey) {
-            headers['dub-apiKey'] = effectiveApiKey;
-        }
-        const queryParams = effectiveApiKey
-            ? `?subscription-key=${encodeURIComponent(effectiveApiKey)}`
-            : '';
+        LicensingClient.applyAuthHeaders(headers, effectiveApiKey);
         // Send PascalCase body matching CreateCheckoutSessionParameters.cs
         const body = JSON.stringify({
             RequestId: this.generateRequestId(),
@@ -2243,7 +2290,7 @@ class LicensingClient {
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(`${url}${queryParams}`, {
+            const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body,
@@ -2251,8 +2298,7 @@ class LicensingClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                const errorText = await response.text().catch(() => 'Unknown error');
-                throw new LicensingError(`Checkout session creation failed: ${response.statusText}`, response.status, errorText);
+                throw await LicensingError.fromHttpResponse('Checkout session creation', response);
             }
             const data = await response.json();
             // Map PascalCase server response to camelCase DTO
@@ -2291,12 +2337,7 @@ class LicensingClient {
         const headers = {
             'Content-Type': 'application/json',
         };
-        if (effectiveApiKey) {
-            headers['dub-apiKey'] = effectiveApiKey;
-        }
-        const queryParams = effectiveApiKey
-            ? `?subscription-key=${encodeURIComponent(effectiveApiKey)}`
-            : '';
+        LicensingClient.applyAuthHeaders(headers, effectiveApiKey);
         // Send PascalCase body matching GetCheckoutSessionResultParameters.cs
         const body = JSON.stringify({
             SessionId: sessionId
@@ -2304,7 +2345,7 @@ class LicensingClient {
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(`${url}${queryParams}`, {
+            const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body,
@@ -2312,8 +2353,7 @@ class LicensingClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                const errorText = await response.text().catch(() => 'Unknown error');
-                throw new LicensingError(`Checkout result retrieval failed: ${response.statusText}`, response.status, errorText);
+                throw await LicensingError.fromHttpResponse('Checkout result retrieval', response);
             }
             const data = await response.json();
             // Map PascalCase server response to camelCase DTO
@@ -2783,15 +2823,10 @@ exports.hasFeature = hasFeature;
 exports.hasValidCryptoConfig = hasValidCryptoConfig;
 exports.licensingContextFromEncodedString = licensingContextFromEncodedString;
 exports.licensingContextToEncodedString = licensingContextToEncodedString;
-exports.listKeys = listKeys;
-exports.load = load;
 exports.matchesFeatureKey = matchesFeatureKey;
 exports.normalizeBillingIntervalUnit = normalizeBillingIntervalUnit;
 exports.normalizeLicenseClassificationType = normalizeLicenseClassificationType;
 exports.normalizeServiceAccessLevel = normalizeServiceAccessLevel;
-exports.onStorageChange = onStorageChange;
-exports.remove = remove;
-exports.save = save;
 exports.tryDecodeCredential = tryDecodeCredential;
 exports.useLicensingContext = useLicensingContext;
 exports.useLicensingContextValue = useLicensingContextValue;