@katlux/providers 0.1.1-alpha.104 → 0.1.1-alpha.105

package/dist/index.d.cts

@@ -1,3 +1,130 @@
+interface IEncryptedPayload {
+    __encrypted: true;
+    ciphertext: string;
+    alg: string;
+    iv?: string;
+    salt?: string;
+    kdf?: string;
+    iter?: number;
+    tag?: string;
+    wrappedKey?: string;
+    sharedKey?: boolean;
+    epk?: JsonWebKey;
+}
+type TRawKey = string | CryptoKey | Uint8Array | ArrayBuffer;
+type TKeyProvider = TRawKey | (() => TRawKey | Promise<TRawKey>);
+interface IEncryptionContext {
+    url?: string;
+    method?: string;
+    isServer?: boolean;
+    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
+    fields?: string[];
+    key?: TKeyProvider | IKeyPair;
+    /** Whether to encrypt/decrypt individual values while preserving JSON keys (default: true) */
+    valueEncryption?: boolean;
+    publicKey?: CryptoKey;
+    privateKey?: CryptoKey;
+    recipientPublicKey?: CryptoKey;
+    recipientPrivateKey?: CryptoKey;
+    curve?: 'P-256' | 'P-384' | 'P-521';
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    kdfIterations?: number;
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    info?: string | Uint8Array | ArrayBuffer;
+}
+interface IEncryptionProvider {
+    encrypt(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload | any>;
+    decrypt(payload: IEncryptedPayload | any, options?: IEncryptionContext): Promise<any>;
+    warmupKey?(options?: IEncryptionContext): Promise<void>;
+    isEncrypted?(payload: any): boolean;
+    setDefaultKey?(key: TKeyProvider | IKeyPair): void;
+    clearKeys?(): void;
+    dispose?(): void;
+    [Symbol.dispose]?(): void;
+    [Symbol.asyncDispose]?(): Promise<void>;
+}
+interface IProviderEncryptionOptions {
+    /** Enable or disable encryption */
+    enabled?: boolean;
+    /** Secret key, passphrase, CryptoKey, key pair, or async key provider function */
+    key?: TKeyProvider | IKeyPair;
+    /**
+     * Whether decryption is permitted during Server-Side Rendering (SSR).
+     * In an End-to-End (E2E) zero-trust model, defaults to false to prevent
+     * plaintext data in server memory or SSR payloads.
+     */
+    decryptOnSSR?: boolean;
+    /** Whether to encrypt/decrypt individual values while preserving JSON object keys (default: true) */
+    valueEncryption?: boolean;
+    /** Whether to defer row/item decryption to active page rendering in DataProviders */
+    lazy?: boolean;
+    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
+    fields?: string[];
+    /** Cryptographic algorithm identifier (defaults to 'AES-GCM') */
+    algorithm?: 'AES-GCM' | string;
+    /** Whether to use synchronous Node.js crypto provider (CNodeCryptoEncryptionProvider) */
+    sync?: boolean;
+    /** Custom encryption provider instance implementing IEncryptionProvider */
+    customProvider?: IEncryptionProvider;
+    /** Key Derivation Function strategy ('none' | 'pbkdf2' | 'hkdf'). Defaults to 'pbkdf2'. */
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    /** Number of PBKDF2 iterations (default: 310,000 per OWASP recommendation) */
+    kdfIterations?: number;
+    /** Hash algorithm for PBKDF2 or HKDF ('SHA-256' | 'SHA-512', default: 'SHA-256') */
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    /** Optional static salt for KDF. If omitted, a cryptographically secure random salt is generated and included in the envelope. */
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    /** Optional public key for asymmetric providers */
+    publicKey?: CryptoKey;
+    /** Optional private key for asymmetric providers */
+    privateKey?: CryptoKey;
+    /** Optional recipient public key for asymmetric/hybrid encryption */
+    recipientPublicKey?: CryptoKey;
+    /** Optional recipient private key for asymmetric/hybrid decryption */
+    recipientPrivateKey?: CryptoKey;
+    /** Elliptic curve name for ECDH ('P-256' | 'P-384' | 'P-521') */
+    curve?: 'P-256' | 'P-384' | 'P-521';
+    /** Optional context/info string or buffer for HKDF key derivation */
+    info?: string | Uint8Array | ArrayBuffer;
+}
+/**
+ * Public and private key pair container for asymmetric / hybrid encryption providers (RSA, ECDH).
+ */
+interface IKeyPair {
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+}
+/**
+ * Represents a key wrapped by a key-encrypting key (KEK) using AES-KW or asymmetric wrapping.
+ */
+interface IWrappedKey {
+    wrappedKey: string;
+    alg: string;
+}
+/**
+ * Options for Key Derivation Functions (PBKDF2 / HKDF) in CKeyManager and encryption providers.
+ */
+interface IKDFOptions {
+    kdf: 'pbkdf2' | 'hkdf';
+    salt?: Uint8Array | ArrayBuffer | string;
+    iterations?: number;
+    hash?: 'SHA-256' | 'SHA-512';
+    info?: string | Uint8Array | ArrayBuffer;
+    keyLength?: 128 | 256;
+    extractable?: boolean;
+}
+/**
+ * Options for deriving a key from an existing CryptoKey secret via HKDF.
+ */
+interface IHKDFFromSecretOptions {
+    salt?: Uint8Array | ArrayBuffer | string;
+    hash?: 'SHA-256' | 'SHA-512';
+    info?: string | Uint8Array | ArrayBuffer;
+    keyLength?: 128 | 256;
+    extractable?: boolean;
+}
+
 /**
  * types.ts — Framework-agnostic hydration and platform abstraction contracts.
  */
@@ -58,6 +185,14 @@ interface ICacheEntry<T> {
     data: T;
     timestamp: number;
     lifetime: number;
+    lastAccessed?: number;
+    accessCount?: number;
+}
+interface ICacheQuotaOptions {
+    maxEntries?: number;
+    maxSizeBytes?: number;
+    quotaThresholdRatio?: number;
+    fallbackToMemory?: boolean;
 }
 interface IRequestOptions {
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
@@ -77,6 +212,9 @@ interface IRequestOptions {
     tags?: string[];
     signal?: AbortSignal;
     _generation?: number;
+    encryption?: IProviderEncryptionOptions;
+    /** If true, returns raw response without decrypting, useful for DataProvider lazy page-level decryption */
+    skipDecryption?: boolean;
 }
 /** Queue persistence backend with automatic fallback: IndexedDB → LocalStorage → Memory */
 declare enum EQueueStorage {
@@ -153,6 +291,7 @@ interface IDataProviderOptions {
     refreshOnMutation?: boolean;
     filterDebounce?: number;
     sortDebounce?: number;
+    encryption?: IProviderEncryptionOptions;
 }
 interface IDataProviderState<TRow = TDataRow> {
     currentPage: number;
@@ -222,6 +361,8 @@ interface ITreeDataProvider<TRow = TDataRow> {
     collapseAll?(): void;
     expandAll?(): void;
     isExpanded?(id: string | number): boolean;
+    allVisibleNodes?: ITreeNode<TRow>[];
+    allVisibleRows?: (TRow & ITreeNode<TRow>)[];
 }
 interface ITreeDataProviderOptions extends IDataProviderOptions {
     parentKey?: string;
@@ -241,6 +382,7 @@ type TTreePageDataHandler<TRow = TDataRow> = (currentPage: number, pageSize: num
     expandedByDefault: boolean;
 }, options?: {
     disableCache?: boolean;
+    signal?: AbortSignal;
 }) => IDataResult<TRow> | Promise<IDataResult<TRow>>;
 interface KProductItemData {
     id: string | number;
@@ -260,7 +402,9 @@ interface KProductRowAction {
 
 declare abstract class ADataProvider<TRow = TDataRow> {
     idKey: string;
-    pageData: TRow[];
+    protected _pageData: TRow[];
+    get pageData(): TRow[];
+    set pageData(val: TRow[]);
     protected _rowCount: number;
     get rowCount(): number;
     set rowCount(val: number);
@@ -388,6 +532,11 @@ declare class RequestProvider {
     setCacheProvider(provider?: ACacheProvider | ECacheStrategy): void;
     setCacheLifetime(lifetime: number): void;
     setDeduplicate(deduplicate: boolean): void;
+    encryption?: IProviderEncryptionOptions;
+    private _cachedCipherProvider?;
+    private _lastEncryptionConfig?;
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     onDataReceived(callback: (data: any, generation?: number) => void): void;
     private invokeDataReceivedCallback;
     hasLastUrl(): boolean;
@@ -398,16 +547,31 @@ declare class RequestProvider {
     registerRequest<T>(url: string, options?: IRequestOptions): Promise<T>;
     static executeAll(): void;
     private isSameOriginUrl;
+    private getCipherProvider;
+    private isDataEncrypted;
+    private buildEncryptionContext;
+    private decryptPayloadIfNeeded;
     request<T>(url: string, options?: IRequestOptions): Promise<T>;
 }
 
+declare function getCipherProvider(encryption?: IProviderEncryptionOptions): IEncryptionProvider | undefined;
+declare function clearCachedCipherProvider(encryption?: IProviderEncryptionOptions): void;
+declare function isDataEncrypted(provider?: IEncryptionProvider, data?: any, visited?: WeakSet<object>): boolean;
+declare function buildEncryptionContext(encryption?: IProviderEncryptionOptions, url?: string, _defaultIdKey?: string): IEncryptionContext;
+declare function decryptPageRows<T = any>(rows: T[], encryption?: IProviderEncryptionOptions, apiUrl?: string, idKey?: string): Promise<{
+    rows: T[];
+    decrypted: boolean;
+}>;
 declare abstract class AAPIDataProvider {
     apiUrl: string;
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     requestProvider: RequestProvider;
     refreshOnMutation: boolean | undefined;
+    encryption?: IProviderEncryptionOptions;
     constructor(options?: IDataProviderOptions);
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     abstract setAPIUrl(url: string): void;
     abstract create(item: any): Promise<void>;
     abstract update(item: any): Promise<void>;
@@ -421,7 +585,10 @@ declare class CAPIFlatClientDataProvider<TRow = TDataRow> extends CFlatClientDat
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    encryption?: IProviderEncryptionOptions;
     constructor(options?: IDataProviderOptions);
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     setContextKey(key: string): void;
     setCacheStrategy(strategy: ECacheStrategy): void;
     setCacheLifetime(lifetime: number): void;
@@ -432,6 +599,7 @@ declare class CAPIFlatClientDataProvider<TRow = TDataRow> extends CFlatClientDat
     create(item: any): Promise<void>;
     update(item: any): Promise<void>;
     delete(items: any[]): Promise<void>;
+    loadPageData(): Promise<void>;
 }
 
 declare class CFlatServerDataProvider<TRow = TDataRow> extends ADataProvider<TRow> {
@@ -447,6 +615,7 @@ declare class CFlatServerDataProvider<TRow = TDataRow> extends ADataProvider<TRo
         signal?: AbortSignal;
     }): Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
+    cancelPending(): void;
 }
 
 declare class CAPIFlatServerDataProvider<TRow = TDataRow> extends CFlatServerDataProvider<TRow> implements AAPIDataProvider {
@@ -455,9 +624,12 @@ declare class CAPIFlatServerDataProvider<TRow = TDataRow> extends CFlatServerDat
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    encryption?: IProviderEncryptionOptions;
     /** Incremented on every new request; stale onDataReceived callbacks are discarded. */
     private _requestGeneration;
     constructor(options?: IDataProviderOptions);
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
         disableCache?: boolean;
@@ -480,18 +652,25 @@ declare class CTreeClientDataProvider<TRow extends TDataRow = TDataRow> extends
     private _filteredNodesCache;
     invalidateStaticCache(): void;
     setFilter(filter: IDataFilter | null, immediate?: boolean): void;
+    protected onFilterUpdated(): void;
     private get _staticNodes();
     private get _nodeMap();
     private get _sortedNodeIds();
     constructor(options?: ITreeDataProviderOptions);
     setData(data: TRow[]): void;
     private buildStaticNodes;
+    protected onSortUpdated(): void;
+    setSortList(sortList: IDataSort[], immediate?: boolean): void;
     private computeSortedIds;
     private isNodeVisible;
     private paginateNodes;
     private updatePageData;
     loadPageData(): Promise<void>;
     get treeNodes(): ITreeNode<TRow>[];
+    get allVisibleNodes(): ITreeNode<TRow>[];
+    get allVisibleRows(): (TRow & ITreeNode<TRow> & {
+        __treeNode: ITreeNode<TRow>;
+    })[];
     get visibleRows(): ITreeNode<TRow>[];
     getAllNodes(): ITreeNode<TRow>[];
     getFlatNodes(): ITreeNode<TRow>[];
@@ -514,7 +693,10 @@ declare class CAPITreeClientDataProvider<TRow extends TDataRow = TDataRow> exten
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    encryption?: IProviderEncryptionOptions;
     constructor(options?: ITreeDataProviderOptions);
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     setContextKey(key: string): void;
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
@@ -525,6 +707,7 @@ declare class CAPITreeClientDataProvider<TRow extends TDataRow = TDataRow> exten
     create(item: any): Promise<void>;
     update(item: any): Promise<void>;
     delete(items: any[]): Promise<void>;
+    loadPageData(): Promise<void>;
 }
 
 /**
@@ -558,6 +741,7 @@ declare class CTreeServerDataProvider<TRow = TDataRow> extends ADataProvider<TRo
         signal?: AbortSignal;
     }): Promise<void>;
     refresh(hardRefresh?: boolean): Promise<void>;
+    cancelPending(): void;
     toggleNode(nodeId: string | number): void;
     expand(nodeId: string | number): void;
     collapse(nodeId: string | number): void;
@@ -579,9 +763,12 @@ declare class CAPITreeServerDataProvider<TRow = TDataRow> extends CTreeServerDat
     cacheStrategy: ECacheStrategy | null;
     cacheLifetime: number;
     refreshOnMutation: boolean | undefined;
+    encryption?: IProviderEncryptionOptions;
     /** Incremented on every new request; stale onDataReceived callbacks are discarded. */
     private _requestGeneration;
     constructor(options?: ITreeDataProviderOptions);
+    setEncryption(encryption?: IProviderEncryptionOptions): void;
+    clearEncryption(): void;
     refresh(hardRefresh?: boolean): Promise<void>;
     refreshData(options?: {
         disableCache?: boolean;
@@ -668,11 +855,14 @@ declare class CServerSessionCache extends ACacheProvider {
     static get storage(): Map<string, Map<string, ICacheEntry<any>>>;
     static getSnapshot(): Map<string, Map<string, ICacheEntry<any>>>;
     static MAX_SERVER_SESSIONS: number;
+    static MAX_ENTRIES_PER_SESSION: number;
+    static CLEANUP_INTERVAL_OPS: number;
+    private static _opCounter;
     /**
-     * Purges expired entries across all server sessions synchronously when the storage
-     * exceeds MAX_SERVER_SESSIONS. Avoids persistent background setInterval timers on Node.js/SSR.
+     * Purges expired entries across server sessions.
+     * Can be run in bounded batches (maxSessionsToCheck) to prevent blocking the event loop.
      */
-    static purgeExpiredServerSessions(): void;
+    static purgeExpiredServerSessions(maxSessionsToCheck?: number): void;
     private sessionIdCache;
     private readonly SESSION_ID_KEY;
     constructor();
@@ -739,8 +929,29 @@ declare class CLocalStorageCache extends ACacheProvider {
     private static instance;
     static getInstance(): CLocalStorageCache;
     type: string;
+    private quotaOptions;
+    configureQuota(options: Partial<ICacheQuotaOptions>): void;
+    getQuotaOptions(): Required<ICacheQuotaOptions>;
     private constructor();
     private _hydrateFromPayload;
+    /**
+     * Estimates current cache storage consumption in bytes and item counts without full JSON.parse overhead.
+     */
+    estimateStorageUsage(): {
+        totalBytes: number;
+        entryCount: number;
+        thresholdBytes: number;
+        isNearQuota: boolean;
+    };
+    /**
+     * Inspects all cache:* items in LocalStorage and returns metadata sorted for LRU analysis.
+     */
+    private _getCacheEntriesMetadata;
+    /**
+     * Evicts least recently used or oldest entries until storage usage drops by targetRatio.
+     * Returns number of evicted items.
+     */
+    evictLRU(targetRatio?: number): number;
     getKeyList(context?: any): Promise<Array<string>>;
     get<T>(key: string, context?: any): Promise<T | null>;
     set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
@@ -754,10 +965,26 @@ declare class CIndexedDBCache extends ACacheProvider {
     private static instance;
     private static instances;
     readonly storeName: string;
+    private quotaOptions;
+    configureQuota(options: Partial<ICacheQuotaOptions>): void;
+    getQuotaOptions(): Required<ICacheQuotaOptions>;
     static getInstance(storeName?: string): CIndexedDBCache;
     constructor(storeName?: string);
     private _hydrateFromPayload;
     private getStore;
+    /**
+     * Checks browser navigator.storage estimate to see if storage usage is near quota.
+     */
+    estimateStorageUsage(): Promise<{
+        quota: number;
+        usage: number;
+        ratio: number;
+        isNearQuota: boolean;
+    }>;
+    /**
+     * Evicts least recently used entries from IndexedDB.
+     */
+    evictLRU(targetRatio?: number): Promise<number>;
     getKeyList(context?: any): Promise<Array<string>>;
     get<T>(key: string, context?: any): Promise<T | null>;
     set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
@@ -926,6 +1153,8 @@ declare class RequestQueue {
     private static _onDeadLetter;
     private static _onFlushComplete;
     private static _onNetworkError;
+    private static _headerProvider;
+    static setHeaderProvider(provider: (() => Record<string, string> | Promise<Record<string, string>>) | null): void;
     /**
      * Load persisted queue from storage into state.
      * Call once at app startup, before any flush or enqueue operations.
@@ -1110,5 +1339,474 @@ declare function getAppRouter(): any;
  */
 declare function onPlatformReady(cb: () => void): void;
 
-export { AAPIDataProvider, ADataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CBrowserSessionCache, CCookieCache, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CLocalStorageCache, CMemoryCache, CServerSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CacheProviderFactory, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, SENSITIVE_HEADER_KEYS, applyOperator, clearSSRData, compareAnd, compareEqual, compareIn, compareOr, compareValues, debounce, evaluateFilter, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getHydrationAdapter, getPlatformApp, getSSRData, getSSRPayload, onPlatformReady, setHydrationAdapter, sortData, useDebounce, useFilterLogic, useSortLogic };
-export type { CacheDriverLoader, ICacheEntry, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IFlushOptions, IKDatatableAction, IPlatformRouter, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVirtualScrollState, KProductItemData, KProductRowAction, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TKatluxStore, TPageDataHandler, TQueueItemStatus, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };
+/**
+ * Foundational abstract base class for all Katlux encryption provider implementations.
+ * Provides key storage, lifecycle management, reusable value-level traversal,
+ * and enforces the isomorphic IEncryptionProvider contract.
+ */
+declare abstract class AEncryptionProvider implements IEncryptionProvider {
+    protected defaultKey?: TKeyProvider | IKeyPair;
+    constructor(key?: TKeyProvider | IKeyPair);
+    /**
+     * Sets or updates the default secret key, CryptoKey, or async key provider function.
+     */
+    setDefaultKey(key: TKeyProvider | IKeyPair): void;
+    /**
+     * Retrieves the currently configured default key or key provider callback.
+     */
+    getDefaultKey(): TKeyProvider | IKeyPair | undefined;
+    /**
+     * Pre-derives and caches the native CryptoKey for subsequent cryptographic operations.
+     * Subclasses should override this with a dedicated, non-side-effecting implementation.
+     */
+    warmupKey(_options?: IEncryptionContext): Promise<void>;
+    /**
+     * Resolves raw key from keyProvider callback or defaultKey.
+     */
+    protected resolveRawKey(keyProvider?: TKeyProvider | IKeyPair | any): Promise<TRawKey>;
+    /**
+     * Checks whether the given payload is an encrypted envelope.
+     */
+    static isEncrypted(payload: any): boolean;
+    /**
+     * Checks whether the given payload is an encrypted envelope.
+     */
+    isEncrypted(payload: any): boolean;
+    /**
+     * Clears configured keys and cached cryptographic material from memory.
+     */
+    clearKeys(): void;
+    /**
+     * Alias for clearKeys() to conform with standard disposal patterns.
+     */
+    dispose(): void;
+    /**
+     * ECMAScript Explicit Resource Management protocol (using / await using declarations).
+     */
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Encrypts a single value (string, object, primitive) into an IEncryptedPayload envelope.
+     * Implemented by concrete cryptographic providers.
+     */
+    abstract encryptValue(value: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts a single IEncryptedPayload envelope back into its original plaintext.
+     * Implemented by concrete cryptographic providers.
+     */
+    abstract decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+    /**
+     * Top-level polymorphic encryption method.
+     * Automatically performs value-level encryption:
+     * - If data is an array of objects: recursively encrypts each row.
+     * - If data is an object: encrypts specified fields (or all values if valueEncryption is true),
+     *   preserving JSON object keys so backend APIs and ORMs can parse keys and perform upserts.
+     * - If data is a primitive or whole-payload envelope: encrypts as a single value.
+     */
+    encrypt(data: any, options?: IEncryptionContext): Promise<any>;
+    /**
+     * Top-level polymorphic decryption method.
+     * Automatically performs value-level decryption:
+     * - If payload is an encrypted envelope: decrypts directly via decryptValue.
+     * - If payload is an array of objects: decrypts each row.
+     * - If payload is an object: decrypts any encrypted value cells across fields.
+     */
+    decrypt(payload: any, options?: IEncryptionContext): Promise<any>;
+}
+
+/**
+ * Static cryptographic key lifecycle management utility.
+ * Provides key generation, JWK import/export, key wrapping (AES-KW / RSA-OAEP),
+ * and standard Key Derivation Functions (PBKDF2 / HKDF).
+ */
+declare class CKeyManager {
+    /**
+     * Generates a cryptographically secure random byte buffer of the specified length.
+     */
+    static randomBytes(length: number): Uint8Array;
+    /**
+     * Converts an ArrayBuffer or Uint8Array into a Base64-encoded string.
+     */
+    static toBase64(buffer: ArrayBuffer | Uint8Array): string;
+    /**
+     * Converts a Base64 or Base64URL-encoded string back into a Uint8Array.
+     * Normalizes URL-safe characters and padding, strictly validating against the Base64 alphabet.
+     */
+    static fromBase64(base64: string): Uint8Array;
+    /**
+     * Deterministically resolves a salt from Uint8Array, ArrayBuffer, Base64/Base64URL string, or raw text string.
+     * Guarantees 100% identical salt byte resolution between Node.js and Browser environments.
+     */
+    static resolveSalt(salt?: Uint8Array | ArrayBuffer | string): Uint8Array;
+    /**
+     * Generates a random AES CryptoKey suitable for AES-GCM or AES-CBC.
+     */
+    static generateAESKey(length?: 128 | 256, algorithm?: 'AES-GCM' | 'AES-CBC' | 'AES-KW', extractable?: boolean): Promise<CryptoKey>;
+    /**
+     * Exports an AES CryptoKey as a raw base64 string.
+     */
+    static exportAESKey(key: CryptoKey): Promise<string>;
+    /**
+     * Imports an AES CryptoKey from a raw base64 string.
+     */
+    static importAESKey(base64: string, algorithm?: 'AES-GCM' | 'AES-CBC' | 'AES-KW', extractable?: boolean): Promise<CryptoKey>;
+    /**
+     * Generates an RSA-OAEP public/private key pair (2048 or 4096 bits).
+     */
+    static generateRSAKeyPair(bits?: 2048 | 4096, hash?: 'SHA-256' | 'SHA-512', extractable?: boolean): Promise<IKeyPair>;
+    /**
+     * Generates an ECDH public/private key pair for elliptic curve Diffie-Hellman.
+     */
+    static generateECDHKeyPair(curve?: 'P-256' | 'P-384' | 'P-521', extractable?: boolean): Promise<IKeyPair>;
+    /**
+     * Exports a public CryptoKey to a portable JsonWebKey (JWK).
+     */
+    static exportPublicKey(key: CryptoKey): Promise<JsonWebKey>;
+    /**
+     * Exports a private CryptoKey to a portable JsonWebKey (JWK).
+     */
+    static exportPrivateKey(key: CryptoKey): Promise<JsonWebKey>;
+    /**
+     * Imports a public key from a JsonWebKey (JWK).
+     */
+    static importPublicKey(jwk: JsonWebKey, algorithm?: string | RsaHashedImportParams | EcKeyImportParams): Promise<CryptoKey>;
+    /**
+     * Imports a private key from a JsonWebKey (JWK).
+     */
+    static importPrivateKey(jwk: JsonWebKey, algorithm?: string | RsaHashedImportParams | EcKeyImportParams): Promise<CryptoKey>;
+    /**
+     * Imports a public key from a PEM (SPKI) or base64 SPKI string.
+     */
+    static importPublicKeyFromPEM(pem: string, algorithm?: 'RSA-OAEP' | 'ECDH', curve?: 'P-256' | 'P-384' | 'P-521', hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    /**
+     * Imports a private key from a PEM (PKCS#8) or base64 PKCS#8 string.
+     */
+    static importPrivateKeyFromPEM(pem: string, algorithm?: 'RSA-OAEP' | 'ECDH', curve?: 'P-256' | 'P-384' | 'P-521', hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    /**
+     * Exports a public CryptoKey to a standard PEM (SPKI) string.
+     */
+    static exportPublicKeyToPEM(key: CryptoKey): Promise<string>;
+    /**
+     * Exports a private CryptoKey to a standard PEM (PKCS#8) string.
+     */
+    static exportPrivateKeyToPEM(key: CryptoKey): Promise<string>;
+    /**
+     * Wraps a target CryptoKey (e.g. an Account Symmetric Key) using a wrapping key
+     * (AES-KW or RSA-OAEP).
+     */
+    static wrapKey(keyToWrap: CryptoKey, wrappingKey: CryptoKey, format?: KeyFormat): Promise<string>;
+    /**
+     * Unwraps a base64-encoded wrapped key using an unwrapping key (AES-KW or RSA-OAEP).
+     */
+    static unwrapKey(wrappedBase64: string, unwrappingKey: CryptoKey, unwrappedKeyAlgorithm?: any, extractable?: boolean, keyUsages?: KeyUsage[], format?: KeyFormat): Promise<CryptoKey>;
+    /**
+     * Generates a high-entropy symmetric AES-GCM Account Data Encryption Key (ADEK).
+     * Designed for multi-user table and field-level encryption.
+     */
+    static generateAccountDataKey(length?: 128 | 192 | 256): Promise<CryptoKey>;
+    /**
+     * Wraps an Account Data Encryption Key (ADEK) for a specific user using the user's public key (RSA-OAEP).
+     * Returns a Base64-encoded wrapped key string suitable for storage in role-map / access tables.
+     */
+    static wrapAccountKeyForUser(adek: CryptoKey, userPublicKey: CryptoKey): Promise<string>;
+    /**
+     * Unwraps a Base64-encoded Account Data Encryption Key (ADEK) using the user's private key (RSA-OAEP).
+     * Returns the restored AES-GCM CryptoKey ready for use in CWebCryptoEncryptionProvider.
+     */
+    static unwrapAccountKeyForUser(wrappedKeyBase64: string, userPrivateKey: CryptoKey, unwrappedKeyAlgorithm?: any): Promise<CryptoKey>;
+    /**
+     * Derives a symmetric AES-GCM CryptoKey from a passphrase using PBKDF2 or HKDF.
+     * Returns the derived CryptoKey and the base64-encoded salt.
+     */
+    static deriveKey(passphrase: string | Uint8Array | ArrayBuffer, options: IKDFOptions): Promise<{
+        key: CryptoKey;
+        salt: string;
+    }>;
+    /**
+     * Derives an AES-GCM CryptoKey from a high-entropy secret (e.g. an ECDH shared secret key)
+     * using HKDF.
+     */
+    static deriveKeyFromSecret(secretKey: CryptoKey, options?: IHKDFFromSecretOptions): Promise<CryptoKey>;
+}
+
+interface ICWebCryptoOptions {
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    kdfIterations?: number;
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    info?: string | Uint8Array | ArrayBuffer;
+}
+declare class CWebCryptoEncryptionProvider extends AEncryptionProvider {
+    private _defaultKdf;
+    private _cachedKey?;
+    private _kdfOptions?;
+    private _cachedSalt?;
+    private _cachedKdf?;
+    private _cachedIter?;
+    private _cachedHash?;
+    private _decryptSaltCache;
+    setDefaultKey(key: TKeyProvider): void;
+    clearKeys(): void;
+    constructor(key?: TKeyProvider | IKeyPair, options?: ICWebCryptoOptions);
+    /**
+     * Derives or returns a CryptoKey for encryption/decryption based on KDF settings.
+     */
+    private resolveCryptoKey;
+    private _resolveCryptoKeyInternal;
+    static isEncrypted(payload: any): boolean;
+    isEncrypted(payload: any): boolean;
+    warmupKey(options?: IEncryptionContext): Promise<void>;
+    /**
+     * Encrypts a single value into an AES-GCM envelope.
+     */
+    encryptValue(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts a single AES-GCM envelope back into its plaintext.
+     */
+    decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+}
+
+interface ICWebCryptoAESCBCOptions {
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    kdfIterations?: number;
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    info?: string | Uint8Array | ArrayBuffer;
+}
+/**
+ * Authenticated AES-CBC-256 provider with Encrypt-then-MAC (HMAC-SHA-256).
+ *
+ * AES-CBC provides confidentiality but no integrity protection by itself.
+ * This provider implements Encrypt-then-MAC: an HMAC-SHA-256 tag is computed
+ * over the (IV || ciphertext) and stored in the envelope's `tag` field.
+ * Upon decryption, the HMAC is strictly verified before CBC decryption to mitigate
+ * padding oracle and bit-flipping attacks.
+ */
+declare class CWebCryptoAESCBCProvider extends AEncryptionProvider {
+    private _defaultKdf;
+    private _cachedEncKey?;
+    private _cachedMacKey?;
+    private _cachedSalt?;
+    private _cachedKdf?;
+    private _cachedIter?;
+    private _cachedHash?;
+    private _kdfOptions?;
+    private _decryptSaltCache;
+    constructor(key?: TKeyProvider | IKeyPair, options?: ICWebCryptoAESCBCOptions);
+    setDefaultKey(key: TKeyProvider | IKeyPair): void;
+    clearKeys(): void;
+    warmupKey(options?: IEncryptionContext): Promise<void>;
+    /**
+     * Derives 64 bytes (512 bits) of key material:
+     * - Bytes 0..31 (256 bits) for AES-CBC encryption key
+     * - Bytes 32..63 (256 bits) for HMAC-SHA-256 authentication key
+     */
+    private resolveCBCKeys;
+    private _deriveCBCKeysInternal;
+    static isEncrypted(payload: any): boolean;
+    isEncrypted(payload: any): boolean;
+    /**
+     * Encrypts a single value into an authenticated AES-CBC-256+HMAC-SHA-256 envelope.
+     */
+    encryptValue(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts a single AES-CBC-256+HMAC-SHA-256 envelope back into its plaintext.
+     */
+    decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+}
+
+/**
+ * Asymmetric / Hybrid encryption provider combining RSA-OAEP (2048/4096-bit) with AES-GCM-256.
+ *
+ * Direct RSA encryption is bounded by key size (RSA-4096 max ~446 bytes).
+ * This provider implements the industry-standard Hybrid Encryption scheme:
+ * 1. A random 256-bit AES-GCM data key is generated per encryption.
+ * 2. Payload is encrypted with the AES-GCM data key (unlimited payload size, authenticated).
+ * 3. The AES-GCM data key is wrapped with the recipient's RSA-OAEP public key.
+ * 4. The envelope packages ciphertext, IV, and wrappedKey.
+ * 5. Only the holder of the matching RSA private key can unwrap the data key and decrypt.
+ */
+declare class CRSAEncryptionProvider extends AEncryptionProvider {
+    private publicKey?;
+    private privateKey?;
+    setDefaultKey(key: TKeyProvider | IKeyPair | Record<string, any>): void;
+    constructor(publicKeyOrPair?: CryptoKey | IKeyPair | {
+        publicKey?: CryptoKey;
+        privateKey?: CryptoKey;
+        recipientPublicKey?: CryptoKey;
+        recipientPrivateKey?: CryptoKey;
+    }, privateKey?: CryptoKey);
+    setPublicKey(key: CryptoKey): void;
+    getPublicKey(): CryptoKey | undefined;
+    setPrivateKey(key: CryptoKey): void;
+    getPrivateKey(): CryptoKey | undefined;
+    clearKeys(): void;
+    static generateKeyPair(bits?: 2048 | 4096): Promise<IKeyPair>;
+    static exportPublicKey(key: CryptoKey): Promise<JsonWebKey>;
+    static exportPrivateKey(key: CryptoKey): Promise<JsonWebKey>;
+    static importPublicKey(jwk: JsonWebKey): Promise<CryptoKey>;
+    static importPrivateKey(jwk: JsonWebKey): Promise<CryptoKey>;
+    static importPublicKeyFromPEM(pem: string, hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    static importPrivateKeyFromPEM(pem: string, hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    static exportPublicKeyToPEM(key: CryptoKey): Promise<string>;
+    static exportPrivateKeyToPEM(key: CryptoKey): Promise<string>;
+    static isEncrypted(payload: any): boolean;
+    isEncrypted(payload: any): boolean;
+    /**
+     * Encrypts a single value into a hybrid RSA-OAEP + AES-GCM envelope.
+     */
+    encryptValue(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts a single hybrid RSA-OAEP + AES-GCM envelope back into its plaintext.
+     */
+    decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+    encrypt(data: any, options?: IEncryptionContext): Promise<any>;
+    decrypt(payload: any, options?: IEncryptionContext): Promise<any>;
+}
+
+type TECDHCurve = 'P-256' | 'P-384' | 'P-521';
+/**
+ * Modern Asymmetric / Hybrid encryption provider using ECDH (Elliptic Curve Diffie-Hellman)
+ * with HKDF key derivation and AES-GCM-256 authenticated encryption.
+ *
+ * Implements forward-secure hybrid encryption:
+ * 1. An ephemeral ECDH keypair is generated per encryption operation.
+ * 2. Key agreement with recipient's ECDH public key produces a high-entropy shared secret.
+ * 3. HKDF derives a 256-bit AES-GCM data key from the shared secret.
+ * 4. Payload is encrypted with AES-GCM.
+ * 5. Ephemeral public key (JWK) is attached to the envelope (`epk`).
+ * 6. Only the recipient with the matching private key can agree with `epk` and decrypt.
+ */
+declare class CECDHEncryptionProvider extends AEncryptionProvider {
+    private recipientPublicKey?;
+    private recipientPrivateKey?;
+    private curve;
+    setDefaultKey(key: TKeyProvider | IKeyPair | Record<string, any>): void;
+    constructor(recipientPublicKeyOrPair?: CryptoKey | IKeyPair | {
+        recipientPublicKey?: CryptoKey;
+        publicKey?: CryptoKey;
+        recipientPrivateKey?: CryptoKey;
+        privateKey?: CryptoKey;
+        curve?: TECDHCurve;
+    }, recipientPrivateKey?: CryptoKey, curve?: TECDHCurve);
+    setRecipientPublicKey(key: CryptoKey): void;
+    getRecipientPublicKey(): CryptoKey | undefined;
+    setRecipientPrivateKey(key: CryptoKey): void;
+    getRecipientPrivateKey(): CryptoKey | undefined;
+    getCurve(): TECDHCurve;
+    clearKeys(): void;
+    static generateKeyPair(curve?: TECDHCurve): Promise<IKeyPair>;
+    static exportPublicKey(key: CryptoKey): Promise<JsonWebKey>;
+    static exportPrivateKey(key: CryptoKey): Promise<JsonWebKey>;
+    static importPublicKey(jwk: JsonWebKey, curve?: TECDHCurve): Promise<CryptoKey>;
+    static importPrivateKey(jwk: JsonWebKey, curve?: TECDHCurve): Promise<CryptoKey>;
+    static importPublicKeyFromPEM(pem: string, curve?: TECDHCurve): Promise<CryptoKey>;
+    static importPrivateKeyFromPEM(pem: string, curve?: TECDHCurve): Promise<CryptoKey>;
+    static exportPublicKeyToPEM(key: CryptoKey): Promise<string>;
+    static exportPrivateKeyToPEM(key: CryptoKey): Promise<string>;
+    static isEncrypted(payload: any): boolean;
+    isEncrypted(payload: any): boolean;
+    /**
+     * Encrypts a single value into an ECDH+HKDF+AES-GCM envelope.
+     */
+    encryptValue(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Encrypts multiple designated fields of a record using a single ephemeral ECDH keypair and shared DEK.
+     */
+    private encryptFieldsWithSharedDEK;
+    /**
+     * Derives the AES-GCM data key for a given ECDH envelope.
+     */
+    private deriveDecryptionKey;
+    /**
+     * Decrypts ciphertext buffer using a derived data key.
+     */
+    private decryptCiphertextWithKey;
+    /**
+     * Decrypts a single ECDH+HKDF+AES-GCM envelope back into its plaintext.
+     */
+    decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+    encrypt(data: any, options?: IEncryptionContext): Promise<any>;
+    decrypt(payload: any, options?: IEncryptionContext): Promise<any>;
+}
+
+interface ICNodeCryptoOptions {
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    kdfIterations?: number;
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    info?: string | Uint8Array | ArrayBuffer;
+}
+/**
+ * Server-side synchronous AES-GCM-256 encryption provider using Node.js native `node:crypto`.
+ *
+ * Fully interoperable with `CWebCryptoEncryptionProvider`:
+ * - Data encrypted by `CNodeCryptoEncryptionProvider` can be decrypted by `CWebCryptoEncryptionProvider`.
+ * - Data encrypted by `CWebCryptoEncryptionProvider` can be decrypted by `CNodeCryptoEncryptionProvider`.
+ *
+ * Provides both synchronous (`encryptSync`, `decryptSync`) and standard Promise-based
+ * (`encrypt`, `decrypt`) methods for Nitro routes, worker threads, and CLI tools.
+ */
+declare class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
+    private _defaultKdf;
+    private _kdfOptions?;
+    private _cachedKey?;
+    private _cachedSalt?;
+    private _cachedKdf?;
+    private _cachedIter?;
+    private _cachedHash?;
+    setDefaultKey(key: TKeyProvider): void;
+    clearKeys(): void;
+    warmupKey(options?: IEncryptionContext): Promise<void>;
+    /**
+     * Synchronously pre-derives and caches the encryption key for subsequent synchronous operations.
+     */
+    warmupKeySync(options?: IEncryptionContext): void;
+    private resolveInfoBuffer;
+    constructor(key?: TKeyProvider | IKeyPair, options?: ICNodeCryptoOptions);
+    private resolveRawKeySync;
+    private resolveRawKeyAsync;
+    private deriveKeySync;
+    private deriveKeyAsync;
+    static isEncrypted(payload: any): boolean;
+    isEncrypted(payload: any): boolean;
+    /**
+     * Synchronously encrypts a single value into an AES-GCM envelope using Node.js crypto.
+     */
+    encryptValueSync(data: any, options?: IEncryptionContext): IEncryptedPayload;
+    private decryptCiphertextWithKey;
+    /**
+     * Synchronously decrypts a single AES-GCM envelope back into its plaintext.
+     */
+    decryptValueSync(payload: IEncryptedPayload, options?: IEncryptionContext): any;
+    encryptSync(data: any, options?: IEncryptionContext): any;
+    decryptSync(payload: any, options?: IEncryptionContext): any;
+    encryptFieldsSync(data: any, fields: string[]): any;
+    decryptFieldsSync(data: any, fields: string[]): any;
+    encryptFields(data: any, fields: string[]): Promise<any>;
+    decryptFields(data: any, fields: string[]): Promise<any>;
+    encryptValue(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload>;
+    decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+    decrypt(payload: any, options?: IEncryptionContext): Promise<any>;
+}
+
+/**
+ * Universal factory function that creates and returns the appropriate IEncryptionProvider
+ * instance according to the configured algorithm and cryptographic options.
+ *
+ * Algorithm dispatch:
+ * - 'AES-GCM' (default): CWebCryptoEncryptionProvider
+ * - 'AES-CBC' | 'AES-CBC-256+HMAC-SHA-256': CWebCryptoAESCBCProvider
+ * - 'RSA-OAEP' | 'RSA-*': CRSAEncryptionProvider
+ * - 'ECDH' | 'ECDH-*': CECDHEncryptionProvider
+ * - 'NODE-CRYPTO' | sync: true: CNodeCryptoEncryptionProvider
+ */
+declare function createEncryptionProvider(options?: IProviderEncryptionOptions): IEncryptionProvider;
+
+/**
+ * Universal helper that verifies whether an arbitrary object is a Katlux encrypted payload envelope.
+ */
+declare function isEncrypted(payload: any): boolean;
+
+export { AAPIDataProvider, ADataProvider, AEncryptionProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CBrowserSessionCache, CCookieCache, CECDHEncryptionProvider, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CKeyManager, CLocalStorageCache, CMemoryCache, CNodeCryptoEncryptionProvider, CRSAEncryptionProvider, CServerSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CWebCryptoAESCBCProvider, CWebCryptoEncryptionProvider, CacheProviderFactory, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, SENSITIVE_HEADER_KEYS, applyOperator, buildEncryptionContext, clearCachedCipherProvider, clearSSRData, compareAnd, compareEqual, compareIn, compareOr, compareValues, createEncryptionProvider, debounce, decryptPageRows, evaluateFilter, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getCipherProvider, getHydrationAdapter, getPlatformApp, getSSRData, getSSRPayload, isDataEncrypted, isEncrypted, onPlatformReady, setHydrationAdapter, sortData, useDebounce, useFilterLogic, useSortLogic };
+export type { CacheDriverLoader, ICNodeCryptoOptions, ICWebCryptoAESCBCOptions, ICWebCryptoOptions, ICacheEntry, ICacheQuotaOptions, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IEncryptedPayload, IEncryptionContext, IEncryptionProvider, IFlushOptions, IHKDFFromSecretOptions, IKDFOptions, IKDatatableAction, IKeyPair, IPlatformRouter, IProviderEncryptionOptions, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVirtualScrollState, IWrappedKey, KProductItemData, KProductRowAction, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TECDHCurve, TKatluxStore, TKeyProvider, TPageDataHandler, TQueueItemStatus, TRawKey, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };