@sidub-inc/licensing-client 1.5.85 → 1.6.0

package/dist/index.d.ts

@@ -1,8 +1,42 @@
 import React, { ReactNode } from 'react';
 
+/**
+ * A single structured detail entry from the server's shared ApiError contract.
+ * Mirrors the .NET ApiErrorDetail entity {Code, Message, Field, TargetId}.
+ */
+interface ApiErrorDetail {
+    /** Machine-readable detail code. */
+    code?: string;
+    /** Human-readable detail message. */
+    message?: string;
+    /** The request field the detail refers to, when applicable. */
+    field?: string;
+    /** The identifier of the entity the detail refers to, when applicable. */
+    targetId?: string;
+}
+/**
+ * Minimal structural view of a fetch Response used for error construction.
+ * Kept structural (rather than the DOM Response type) so Node callers and
+ * tests can supply plain objects.
+ */
+interface HttpErrorResponseLike {
+    status?: number;
+    statusText?: string;
+    text?: () => Promise<string>;
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+}
 /**
  * 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.
  */
 declare class LicensingError extends Error {
     statusCode?: number | undefined;
@@ -13,6 +47,21 @@ declare class LicensingError extends Error {
      * retry policy; undefined when the server did not supply one.
      */
     retryAfterMs?: number;
+    /**
+     * Machine-readable error code from the server's ApiError body (e.g.
+     * 'ApiKeyMissing', 'AuthorizationDenied', 'NotFound', 'ValidationError',
+     * 'ServerError'). Undefined when the response body was not a parseable
+     * ApiError or the failure never reached the server.
+     */
+    code?: string;
+    /**
+     * The request correlation id, from the ApiError body or the X-Correlation-Id
+     * response header. Quote this value in support requests — it stitches the
+     * client failure to the server-side logs.
+     */
+    correlationId?: string;
+    /** Structured per-field details from the ApiError body, when supplied. */
+    details?: ApiErrorDetail[];
     /**
      * Creates a new licensing error.
      * @param message A description of the error.
@@ -20,6 +69,23 @@ declare class LicensingError extends Error {
      * @param response The raw response body from the server, if available.
      */
     constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+    /**
+     * 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 fromHttpResponse(operation: string, response: HttpErrorResponseLike): Promise<LicensingError>;
 }
 
 /**
@@ -87,11 +153,15 @@ declare enum BillingIntervalUnit {
 declare function normalizeBillingIntervalUnit(value: number | string | null | undefined): BillingIntervalUnit | undefined;
 
 /**
- * Base interface for license features
+ * Base interface for license features.
+ *
+ * The identifier is `featureKey`, matching the wire vocabulary (the server
+ * serializes `FeatureKey`) and the rest of the SDK (assertions, consumption,
+ * state views). Renamed from `featureId` in 2.0 (MON-334 SR4).
  */
 interface ILicenseFeature {
-    /** Unique identifier for the feature type */
-    featureId: string;
+    /** Unique key identifying the feature (wire field: FeatureKey). */
+    featureKey: string;
 }
 /**
  * Rate agreement for subscription-based licenses
@@ -216,8 +286,25 @@ interface LicensingConfig {
      * authorizations remain eligible to be served (flagged isStale) for this long
      * when the licensing service is transiently unreachable. Default 24h; capped
      * at 7 days. Set to 0 to disable stale-serve.
+     *
+     * Revocation trade-off: stale-serve only ever triggers on transient failures
+     * (network/408/429/5xx) and only for signature-validated entries — a denial
+     * (401/403/404) is never masked. But during an outage a revoked license can
+     * keep authorizing for up to this window past its freshness deadline.
      */
     staleGraceMs?: number;
+    /**
+     * Optional: Upper bound in milliseconds on how long a cached authorization
+     * stays fresh before the SDK revalidates against the server (MON-334
+     * react-09). Default 24h (capped there); the no-expiry default remains 1h.
+     *
+     * Revocation trade-off: a revoked or downgraded license keeps authorizing
+     * from cache until its freshness deadline — revocation latency is
+     * min(cacheFreshTtlMs, remaining license window). Tighten this value for
+     * faster revocation pickup at the cost of more authorization calls; 0 makes
+     * every getAuthorization revalidate.
+     */
+    cacheFreshTtlMs?: number;
     /** Optional: Custom context provider for multi-tenant credential resolution */
     contextProvider?: {
         resolveContext(): Promise<{
@@ -300,6 +387,16 @@ interface LicensingCredential {
  * 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_
  */
@@ -330,7 +427,7 @@ declare function hasValidCryptoConfig(credential: LicensingCredential | null | u
 
 /**
  * Extended feature interface that accounts for server response casing variations.
- * The server may return features with PascalCase (FeatureKey) or camelCase (featureId).
+ * The server serializes PascalCase (FeatureKey); the SDK model uses camelCase (featureKey).
  */
 interface ServerFeature extends ILicenseFeature {
     /** Server-side PascalCase feature key */
@@ -356,7 +453,8 @@ interface ServerFeature extends ILicenseFeature {
 }
 /**
  * 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
@@ -364,7 +462,7 @@ interface ServerFeature extends ILicenseFeature {
 declare function getFeatureKey(feature: ILicenseFeature | ServerFeature): string;
 /**
  * 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
@@ -390,6 +488,15 @@ declare function hasFeature(features: ILicenseFeature[] | undefined | null, feat
 
 /**
  * Status of a checkout session.
+ *
+ * Exactly three values travel the wire. The server holds a fourth internal
+ * state, PaymentPending (async bank-debit settlement, MON-191), which it
+ * DELIBERATELY surfaces as 'pending' — so 'pending' covers both "session just
+ * created, poll again in seconds" and "payment is settling, which can take
+ * days". A completed credential may therefore arrive up to 14 days after
+ * checkout; keep polling (or re-poll later) rather than treating a prolonged
+ * 'pending' as failure. Verified against CheckoutResultService (MON-334
+ * align-naming-shape-02).
  */
 type CheckoutSessionStatus = 'pending' | 'completed' | 'failed';
 /**
@@ -429,7 +536,14 @@ interface CheckoutSessionResult {
     status: CheckoutSessionStatus;
     /** Correlation ID from the original request */
     correlationId?: string;
-    /** Encoded licensing credential (SIDUB_LIC_...) — present when status is 'completed' */
+    /**
+     * Encoded licensing credential (SIDUB_LIC_...) — present when status is 'completed'.
+     *
+     * SECURITY (MON-334 react-08): this value is base64-obfuscated, NOT encrypted —
+     * it contains the tenant's apiAccessKey. Hand it to your backend for storage;
+     * do not persist it in localStorage or anywhere page JavaScript (and therefore
+     * any XSS) can read it.
+     */
     encodedCredential?: string;
     /** License ID provisioned by checkout — present when status is 'completed' */
     licenseId?: string;
@@ -498,8 +612,8 @@ declare function normalizeServiceAccessLevel(value: number | string | null | und
  * Extends the base feature with service type and access level metadata.
  */
 interface ServiceAccessLicenseFeature extends ILicenseFeature {
-    /** Unique identifier for the feature. */
-    featureId: string;
+    /** Unique key identifying the feature (wire field: FeatureKey). */
+    featureKey: string;
     /** Optional service type identifier for finer-grained access control. */
     serviceType?: string;
     /** The access level granted for this feature (Allowed or Denied). */
@@ -589,8 +703,8 @@ declare class RateLimitFeatureState {
  * Extends the base feature with rate limiting metadata and usage counters.
  */
 interface RateLimitLicenseFeature extends ILicenseFeature {
-    /** Unique identifier for the feature. */
-    featureId: string;
+    /** Unique key identifying the feature (wire field: FeatureKey). */
+    featureKey: string;
     /** Sliding window duration in seconds for rate limit evaluation. */
     sampleSeconds?: number;
     /** Maximum allowed consumption within the sample window. */
@@ -765,6 +879,7 @@ declare class LicensingClient {
     private readonly disposables;
     private contextResolved;
     private contextResolutionPromise;
+    private signaturePostureWarned;
     private readonly inFlightAuthorizations;
     private static readonly METADATA_STORAGE_KEY;
     private static readonly CONSUMPTION_STORAGE_PREFIX;
@@ -794,6 +909,20 @@ declare class LicensingClient {
      * attempt. contextResolved only ever becomes true on success.
      */
     private ensureContextResolved;
+    /**
+     * 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.
+     */
+    private static applyAuthHeaders;
     /**
      * Builds the cryptography configuration from the resolved config values
      */
@@ -802,6 +931,22 @@ declare class LicensingClient {
      * Gets whether cryptographic signature validation is enabled
      */
     get isSignatureValidationEnabled(): boolean;
+    /**
+     * 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.
+     */
+    private assertSignaturePosture;
     /**
      * Gets the configured license ID (from credential or explicit config)
      */
@@ -839,10 +984,6 @@ declare class LicensingClient {
      * server errors (5xx). Denials and client errors (401/403/404/4xx) are not.
      */
     private static isTransientError;
-    /**
-     * Parses a Retry-After header value (delta-seconds or HTTP-date) into milliseconds.
-     */
-    private static parseRetryAfter;
     /**
      * Retries transient failures with exponential backoff and jitter, honoring
      * Retry-After when the server supplied one. config.timeout is the overall
@@ -1107,20 +1248,6 @@ interface SignatureValidationResult {
     /** Error message if validation failed */
     error?: string;
 }
-/**
- * Raw server response for authorization (before client mapping).
- * Uses PascalCase property names matching the .NET server response.
- */
-interface RawAuthorizationResponse {
-    AuthorizationId: string;
-    LicenseId: string;
-    LicenseClassification: string | number;
-    IssueDate: string;
-    ExpiryDate?: string;
-    Features: unknown[];
-    __sidub_entitySignature?: string;
-    [key: string]: unknown;
-}
 /**
  * Result of textually extracting the entity signature member from a raw JSON response.
  */
@@ -1171,35 +1298,17 @@ declare class SignatureValidator {
      * Initializes the validator. Must be called before validating signatures.
      */
     initialize(): Promise<void>;
-    /**
-     * 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
-     */
-    validateRawResponse(rawResponse: RawAuthorizationResponse, options?: SignatureValidationOptions): Promise<SignatureValidationResult>;
     /**
      * 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).
@@ -1207,11 +1316,6 @@ declare class SignatureValidator {
      * @throws {CryptoError} If throwOnInvalid is true and validation fails
      */
     validateResponseText(rawText: string, options?: SignatureValidationOptions): Promise<SignatureValidationResult>;
-    /**
-     * Serializes the raw server response for signature verification.
-     * Removes the __sidub_entitySignature field and serializes to JSON.
-     */
-    private serializeRawForVerification;
 }
 
 /**
@@ -1235,6 +1339,7 @@ declare class AuthorizationCache {
     private maxSize;
     private storagePrefix;
     private graceMs;
+    private freshTtlMs;
     private unsubscribe;
     /**
      * Creates a new authorization cache.
@@ -1242,8 +1347,12 @@ declare 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?: number, storagePrefix?: string, graceMs?: number);
+    constructor(maxSize?: number, storagePrefix?: string, graceMs?: number, freshTtlMs?: number);
     /**
      * Builds the composite cache key. The API key is hashed so raw key material
      * never appears in localStorage key names.
@@ -1276,10 +1385,16 @@ declare 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.
@@ -1318,41 +1433,6 @@ declare class AuthorizationCache {
     private deserializeEntry;
 }
 
-/**
- * Thin localStorage abstraction for persisting SDK state across page refreshes.
- * All methods are SSR-safe — they no-op when `window`/`localStorage` is unavailable.
- *
- * Used by RateLimitFeatureState and AuthorizationCache for transparent persistence.
- */
-/**
- * Serializes and stores a value under the given key.
- * No-op in SSR/Node environments.
- */
-declare function save<T>(key: string, data: T): void;
-/**
- * Loads and deserializes a value from the given key.
- * Returns null if the key is missing, the value cannot be parsed, or in SSR.
- */
-declare function load<T>(key: string): T | null;
-/**
- * Removes a value from localStorage.
- * No-op in SSR/Node environments.
- */
-declare function remove(key: string): void;
-/**
- * Returns all localStorage keys that start with the given prefix.
- * Returns an empty array in SSR/Node environments.
- */
-declare function listKeys(prefix: string): string[];
-/**
- * Registers a listener for localStorage changes from OTHER tabs.
- * Filters events by key prefix and calls the callback with the full key and new value.
- *
- * Returns an unsubscribe function that removes the listener.
- * Returns a no-op in SSR/Node environments.
- */
-declare function onStorageChange(prefix: string, callback: (key: string, newValue: string | null) => void): () => void;
-
 /**
  * Context for providing the LicensingClient to React components
  */
@@ -1508,5 +1588,5 @@ declare class ConfigurationContextProvider implements ILicensingContextProvider
     resolveContext(): Promise<LicensingContextType | null>;
 }
 
-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 };
-export type { CheckoutRequest, CheckoutSession, CheckoutSessionResult, CheckoutSessionStatus, ClientLicenseConfiguration, ConsumptionView, CryptoConfig, FeatureView, GenerateLicenseAuthorizationParameters, ILicenseAssertion, ILicenseFeature, ILicensingContextProvider, License, LicenseAuthorization, LicenseFeatureStateOperation, LicenseStateView, LicensingConfig, LicensingContextType, LicensingCredential, LicensingProviderProps, RateAgreement, RateLimitLicenseFeature, RawAuthorizationResponse, ServerFeature, ServiceAccessLicenseFeature, SignatureMemberExtraction, SignatureValidationOptions, SignatureValidationResult };
+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, matchesFeatureKey, normalizeBillingIntervalUnit, normalizeLicenseClassificationType, normalizeServiceAccessLevel, tryDecodeCredential, useLicensingContext, useLicensingContextValue };
+export type { ApiErrorDetail, CheckoutRequest, CheckoutSession, CheckoutSessionResult, CheckoutSessionStatus, ClientLicenseConfiguration, ConsumptionView, CryptoConfig, FeatureView, GenerateLicenseAuthorizationParameters, ILicenseAssertion, ILicenseFeature, ILicensingContextProvider, License, LicenseAuthorization, LicenseFeatureStateOperation, LicenseStateView, LicensingConfig, LicensingContextType, LicensingCredential, LicensingProviderProps, RateAgreement, RateLimitLicenseFeature, ServerFeature, ServiceAccessLicenseFeature, SignatureMemberExtraction, SignatureValidationOptions, SignatureValidationResult };