@katlux/providers 0.1.1-alpha.127 → 0.1.1-alpha.128

package/dist/index.d.ts

@@ -81,9 +81,28 @@ interface IEncryptionContext {
     kdfHash?: 'SHA-256' | 'SHA-512';
     info?: string | Uint8Array | ArrayBuffer;
 }
+/**
+ * Context options for single scalar field encryption/decryption with bound AAD.
+ */
+interface IFieldEncryptionContext extends Omit<IEncryptionContext, 'aadFields'> {
+    /** Record identifier to bind into AAD */
+    recordId?: string | number;
+    /** Target field name being encrypted/decrypted */
+    fieldName?: string;
+    /** Sibling record fields (map or array of keys) to deterministically bind into AEAD */
+    aadFields?: Record<string, any> | string[];
+    /** Optional base AAD prefix */
+    baseAad?: string;
+}
 interface IEncryptionProvider {
     encrypt(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload | any>;
     decrypt(payload: IEncryptedPayload | any, options?: IEncryptionContext): Promise<any>;
+    /** Encrypts a single scalar value with contextual AAD binding */
+    encryptField?(value: any, context?: IFieldEncryptionContext): Promise<IEncryptedPayload>;
+    /** Decrypts a single scalar field envelope with contextual AAD */
+    decryptField?(envelope: IEncryptedPayload, context?: IFieldEncryptionContext): Promise<any>;
+    /** Computes deterministic HMAC-SHA256 blind index hash */
+    computeBlindIndex?(value: any, hmacKey?: CryptoKey | TKeyProvider): Promise<string>;
     warmupKey?(options?: IEncryptionContext): Promise<void>;
     isEncrypted?(payload: any): boolean;
     setDefaultKey?(key: TKeyProvider | IKeyPair): void;
@@ -153,6 +172,11 @@ interface IProviderEncryptionOptions {
     onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
     /** Enable HMAC-SHA256 blind indexing and trigram search index on encrypted fields for local DataProviders */
     searchIndex?: boolean;
+    /**
+     * Set to true if API endpoints or data sources return pre-encrypted ciphertext envelopes.
+     * When true, DataProviders decrypt search fields during ingest to populate CSearchIndex.
+     */
+    preEncrypted?: boolean;
     /** Optional dedicated HMAC key for search indexing (defaults to encryption key if omitted) */
     hmacKey?: TKeyProvider;
     /** Cryptographic algorithm identifier (defaults to 'AES-GCM') */
@@ -684,6 +708,11 @@ declare class CSearchIndex {
      * Computes a deterministic HMAC-SHA256 token for a term.
      */
     computeToken(term: any): Promise<string>;
+    /**
+     * Computes a deterministic HMAC-SHA256 blind index hash for a term using the configured HMAC key.
+     * Performs Unicode NFKC normalization, trimming, and lowercasing.
+     */
+    computeBlindIndex(term: any): Promise<string>;
     /**
      * Computes HMAC-SHA256 tokens for all trigrams of a term.
      */
@@ -692,6 +721,11 @@ declare class CSearchIndex {
      * Indexes a single row before its fields are encrypted.
      */
     indexRow(row: any, plaintextFields?: Record<string, any>): Promise<void>;
+    /**
+     * Indexes a row using pre-decrypted plaintext field values.
+     * Allows indexing rows that contain pre-encrypted ciphertext envelopes in allData.
+     */
+    indexRowDecrypted(row: any, decryptedPlaintext: Record<string, any>): Promise<void>;
     /**
      * Indexes an array of rows.
      */
@@ -723,6 +757,11 @@ declare abstract class AEncryptedClientProvider<TRow = TDataRow> extends ADataPr
     clearEncryption(): void;
     protected encryptRows(rows: TRow[]): Promise<TRow[]>;
     protected encryptRowsChunked(rows: TRow[], options?: ISetDataChunkedOptions): Promise<TRow[]>;
+    /**
+     * Indexes pre-encrypted rows by performing a transient in-memory decryption pass
+     * on search fields to populate CSearchIndex without mutating underlying encrypted records in allData.
+     */
+    indexPreEncryptedRows(rows: TRow[]): Promise<void>;
     decryptRows(rows: TRow[]): Promise<{
         rows: TRow[];
         decrypted: boolean;
@@ -1660,6 +1699,7 @@ declare function onPlatformReady(cb: () => void): void;
  */
 declare abstract class AEncryptionProvider implements IEncryptionProvider {
     protected defaultKey?: TKeyProvider | IKeyPair;
+    protected _hmacKey?: TKeyProvider;
     protected keys?: Record<string, TKeyProvider | IKeyPair>;
     protected activeKid?: string;
     protected allowedKids?: string[];
@@ -1667,6 +1707,7 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
         keys?: Record<string, TKeyProvider | IKeyPair>;
         activeKid?: string;
         allowedKids?: string[];
+        hmacKey?: TKeyProvider;
         [key: string]: any;
     });
     /**
@@ -1693,6 +1734,19 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
      * Retrieves the active Key Identifier (kid).
      */
     getActiveKid(): string | undefined;
+    /**
+     * Sets or updates the dedicated HMAC key or key provider callback for blind indexing.
+     */
+    setHmacKey(key: TKeyProvider): void;
+    /**
+     * Retrieves the currently configured HMAC key or key provider callback.
+     */
+    getHmacKey(): TKeyProvider | undefined;
+    /**
+     * Computes a deterministic HMAC-SHA256 blind index hash for an arbitrary term.
+     * If no hmacKey is explicitly provided, uses the provider's configured hmacKey or default key.
+     */
+    computeBlindIndex(value: any, hmacKey?: CryptoKey | TKeyProvider): Promise<string>;
     /**
      * Pre-derives and caches the native CryptoKey for subsequent cryptographic operations.
      * Subclasses should override this with a dedicated, non-side-effecting implementation.
@@ -1770,6 +1824,22 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
      * Implemented by concrete cryptographic providers.
      */
     abstract decryptValue(payload: IEncryptedPayload, options?: IEncryptionContext): Promise<any>;
+    /**
+     * Encrypts a single scalar value with contextual AAD binding into an IEncryptedPayload envelope.
+     * Binds recordId, fieldName, and sibling aadFields deterministically to protect against ciphertext swapping.
+     *
+     * @param value - Scalar value (string, number, boolean, object) to encrypt.
+     * @param context - Field encryption context with recordId, fieldName, and optional sibling aadFields.
+     */
+    encryptField(value: any, context?: IFieldEncryptionContext): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts a single IEncryptedPayload envelope back into its scalar plaintext value using contextual AAD.
+     * Validates recordId, fieldName, and sibling aadFields integrity.
+     *
+     * @param envelope - The IEncryptedPayload envelope to decrypt.
+     * @param context - Field encryption context matching the encryption parameters.
+     */
+    decryptField(envelope: IEncryptedPayload, context?: IFieldEncryptionContext): Promise<any>;
     /**
      * Top-level polymorphic encryption method.
      * Automatically performs value-level encryption:
@@ -1861,11 +1931,19 @@ declare class CKeyManager {
     /**
      * 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>;
+    static importPublicKeyFromPEM(pem: string, algorithm?: 'RSA-OAEP' | 'ECDH' | 'ECDSA', curve?: 'P-256' | 'P-384' | 'P-521', hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    /**
+     * Imports an ECDSA public key from PEM (SPKI) or base64 SPKI string for signature verification.
+     */
+    static importECDSAPublicKeyFromPEM(pem: string, curve?: 'P-256' | 'P-384' | 'P-521'): 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>;
+    static importPrivateKeyFromPEM(pem: string, algorithm?: 'RSA-OAEP' | 'ECDH' | 'ECDSA', curve?: 'P-256' | 'P-384' | 'P-521', hash?: 'SHA-256' | 'SHA-512'): Promise<CryptoKey>;
+    /**
+     * Imports an ECDSA private key from PEM (PKCS#8) or base64 PKCS#8 string for signing.
+     */
+    static importECDSAPrivateKeyFromPEM(pem: string, curve?: 'P-256' | 'P-384' | 'P-521'): Promise<CryptoKey>;
     /**
      * Exports a public CryptoKey to a standard PEM (SPKI) string.
      */
@@ -1898,6 +1976,16 @@ declare class CKeyManager {
      * Returns the restored AES-GCM CryptoKey ready for use in CWebCryptoEncryptionProvider.
      */
     static unwrapAccountKeyForUser(wrappedKeyBase64: string, userPrivateKey: CryptoKey, unwrappedKeyAlgorithm?: any, extractable?: boolean): Promise<CryptoKey>;
+    /**
+     * Wraps an HMAC blind indexing key for a specific recipient user using their RSA-OAEP public key.
+     * Returns a Base64-encoded wrapped key string suitable for storage in role-map / access tables.
+     */
+    static wrapHMACKeyForUser(hmacKey: CryptoKey, userPublicKey: CryptoKey): Promise<string>;
+    /**
+     * Unwraps a Base64-encoded HMAC key using a recipient's RSA-OAEP private key.
+     * Restores the CryptoKey configured for HMAC signing and verification in search indexing.
+     */
+    static unwrapHMACKeyForUser(wrappedKeyBase64: string, userPrivateKey: CryptoKey, hash?: 'SHA-256' | 'SHA-384' | 'SHA-512', extractable?: boolean): Promise<CryptoKey>;
     /**
      * Atomically re-wraps an Account Data Encryption Key (ADEK) for a new recipient
      * without exposing the raw extractable symmetric key to caller application code.
@@ -1939,6 +2027,10 @@ declare class CKeyManager {
      * Generates an ECDSA P-256 signing key pair.
      */
     static generateSigningKeyPair(curve?: 'P-256' | 'P-384' | 'P-521', extractable?: boolean): Promise<IKeyPair>;
+    /**
+     * Generates an ECDSA signing key pair. Alias for generateSigningKeyPair.
+     */
+    static generateECDSAKeyPair(curve?: 'P-256' | 'P-384' | 'P-521', extractable?: boolean): Promise<IKeyPair>;
     /**
      * Generates a deterministic SHA-256 fingerprint for a public key (SPKI or raw).
      * Formatted as `SHA256:<base64url>`.
@@ -1953,6 +2045,15 @@ declare class CKeyManager {
      * Verifies an ECDSA P-256 signature against original data or JSON object.
      */
     static verify(data: any | string | Uint8Array, signature: string, publicKey: CryptoKey): Promise<boolean>;
+    /**
+     * Computes a deterministic HMAC-SHA256 blind index hash for an arbitrary term using the supplied CryptoKey.
+     * Performs Unicode NFKC normalization, trimming, and lowercasing before computing the signature.
+     *
+     * @param value - The input string, number, or object to compute the blind index for.
+     * @param hmacKey - CryptoKey configured for HMAC signing.
+     * @returns Lowercase hexadecimal HMAC-SHA256 blind index hash.
+     */
+    static computeBlindIndex(value: any, hmacKey: CryptoKey): Promise<string>;
     /**
      * Signs a structured access grant, embedding signature and granter key fingerprint.
      */
@@ -1974,6 +2075,7 @@ interface ICWebCryptoOptions {
     keys?: Record<string, TKeyProvider | IKeyPair>;
     activeKid?: string;
     allowedKids?: string[];
+    hmacKey?: TKeyProvider;
 }
 /**
  * Zero-dependency AES-256-GCM cipher provider using native Web Crypto API (crypto.subtle).
@@ -2210,6 +2312,7 @@ interface ICNodeCryptoOptions {
     keys?: Record<string, TKeyProvider | IKeyPair>;
     activeKid?: string;
     allowedKids?: string[];
+    hmacKey?: TKeyProvider;
 }
 /**
  * Server-side synchronous AES-GCM-256 encryption provider using Node.js native `node:crypto`.
@@ -2347,4 +2450,4 @@ declare function canonicalizeJson(value: any, seen?: Set<any>): string;
 declare function isEncrypted(payload: any): boolean;
 
 export { AAPIDataProvider, ADataProvider, AEncryptedClientProvider, AEncryptionProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CBrowserSessionCache, CCookieCache, CECDHEncryptionProvider, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CKeyManager, CLocalStorageCache, CMemoryCache, CNodeCryptoEncryptionProvider, CRSAEncryptionProvider, CSearchIndex, CServerSessionCache, CTreeClientDataProvider, CTreeServerDataProvider, CWebCryptoAESCBCProvider, CWebCryptoEncryptionProvider, CacheProviderFactory, DECRYPT_ERROR_SENTINEL, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, SENSITIVE_HEADER_KEYS, applyOperator, buildEncryptionContext, canonicalizeJson, clearCachedCipherProvider, clearSSRData, compareAnd, compareEqual, compareIn, compareOr, compareValues, createEncryptionProvider, debounce, decryptPageRows, encryptRows, encryptRowsChunked, evaluateFilter, extractTrigrams, fastKeyHash, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getCipherProvider, getHydrationAdapter, getKeyIdentifier, getPlatformApp, getRandomValues, getSSRData, getSSRPayload, getSafeKeyIdentifier, getSubtleCrypto, isAuthOrDecryptionError, isDataEncrypted, isEncrypted, normalizeIndexTerm, onPlatformReady, resolveInfoBytes, safeSetProperty, setHydrationAdapter, sortData, textDecoder, textEncoder, toBase64, useDebounce, useFilterLogic, useSortLogic };
-export type { CacheDriverLoader, IAccessGrant, ICNodeCryptoOptions, ICWebCryptoAESCBCOptions, ICWebCryptoOptions, ICacheEntry, ICacheQuotaOptions, ICookieCacheOptions, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IDecryptErrorInfo, IDeriveAuthAndEncryptionOptions, IDomainDerivedKeys, IEncryptedPayload, IEncryptionContext, IEncryptionProvider, IFlushOptions, IHKDFFromSecretOptions, IKDFOptions, IKDatatableAction, IKeyPair, IPlatformRouter, IProviderEncryptionOptions, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ISearchIndexRowEntry, ISetDataChunkedOptions, ISignedGrant, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVerifyGrantOptions, IVirtualScrollState, IWrappedKey, KProductItemData, KProductRowAction, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TECDHCurve, TKatluxStore, TKeyProvider, TPageDataHandler, TQueueItemStatus, TRawKey, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };
+export type { CacheDriverLoader, IAccessGrant, ICNodeCryptoOptions, ICWebCryptoAESCBCOptions, ICWebCryptoOptions, ICacheEntry, ICacheQuotaOptions, ICookieCacheOptions, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IDecryptErrorInfo, IDeriveAuthAndEncryptionOptions, IDomainDerivedKeys, IEncryptedPayload, IEncryptionContext, IEncryptionProvider, IFieldEncryptionContext, IFlushOptions, IHKDFFromSecretOptions, IKDFOptions, IKDatatableAction, IKeyPair, IPlatformRouter, IProviderEncryptionOptions, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ISearchIndexRowEntry, ISetDataChunkedOptions, ISignedGrant, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVerifyGrantOptions, IVirtualScrollState, IWrappedKey, KProductItemData, KProductRowAction, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TECDHCurve, TKatluxStore, TKeyProvider, TPageDataHandler, TQueueItemStatus, TRawKey, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };