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

package/dist/index.d.cts

@@ -17,6 +17,14 @@ interface IEncryptedPayload {
 }
 type TRawKey = string | CryptoKey | Uint8Array | ArrayBuffer;
 type TKeyProvider = TRawKey | (() => TRawKey | Promise<TRawKey>);
+interface IDecryptErrorInfo {
+    record: any;
+    field: string;
+    value: any;
+    error: Error;
+    index?: number;
+}
+declare const DECRYPT_ERROR_SENTINEL: unique symbol;
 interface IEncryptionContext {
     url?: string;
     method?: string;
@@ -25,12 +33,39 @@ interface IEncryptionContext {
     bindRequestContextAad?: boolean;
     /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
     fields?: string[];
+    /**
+     * Enforces strict encryption validation. When true:
+     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
+     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
+     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
+     */
+    strict?: boolean;
+    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
+    allowedAlgorithms?: string[];
+    /** Whitelist of allowed Key Identifiers (kid). */
+    allowedKids?: string[];
+    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
+    keys?: Record<string, TKeyProvider | IKeyPair>;
+    /** Active key identifier from `keys` to use for all outbound encryption operations */
+    activeKid?: string;
+    /**
+     * Hook invoked whenever decryption fails for an individual field or row.
+     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
+     */
+    onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
     key?: TKeyProvider | IKeyPair;
     /** Optional Key Identifier for multi-role key routing and rotation */
     kid?: string;
     keyId?: string;
-    /** Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping */
-    aad?: string | Uint8Array | ArrayBuffer;
+    /**
+     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
+     * Can be static string/buffer or dynamic callback evaluated per record and field.
+     */
+    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
+    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
+    aadFields?: string[];
+    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
+    baseAad?: string;
     /** Internal flag indicating that key derivation has already been warmed for this batch */
     _warmedKey?: any;
     /** Whether to encrypt/decrypt individual values while preserving JSON keys (default: true) */
@@ -46,12 +81,35 @@ 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;
+    setKeyring?(keys: Record<string, TKeyProvider | IKeyPair>, activeKid?: string): void;
+    getKeyring?(): Record<string, TKeyProvider | IKeyPair> | undefined;
+    setActiveKid?(kid: string): void;
+    getActiveKid?(): string | undefined;
     clearKeys?(): void;
     dispose?(): void;
     [Symbol.dispose]?(): void;
@@ -62,11 +120,22 @@ interface IProviderEncryptionOptions {
     enabled?: boolean;
     /** Secret key, passphrase, CryptoKey, key pair, or async key provider function */
     key?: TKeyProvider | IKeyPair;
+    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
+    keys?: Record<string, TKeyProvider | IKeyPair>;
+    /** Active key identifier from `keys` to use for all outbound encryption operations */
+    activeKid?: string;
     /** Optional Key Identifier for multi-role key routing and key rotation */
     kid?: string;
     keyId?: string;
-    /** Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping */
-    aad?: string | Uint8Array | ArrayBuffer;
+    /**
+     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
+     * Can be static string/buffer or dynamic callback evaluated per record and field.
+     */
+    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
+    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
+    aadFields?: string[];
+    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
+    baseAad?: string;
     /**
      * Whether to bind the request context (HTTP method and URL as `req:${method}:${url}`) into AEAD Authenticated Additional Data (AAD).
      * Defaults to true when URL or method is provided in context, mitigating replay and cross-endpoint confusion attacks (BUG-015).
@@ -85,8 +154,29 @@ interface IProviderEncryptionOptions {
     lazy?: boolean;
     /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
     fields?: string[];
+    /**
+     * Enforces strict encryption validation. When true:
+     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
+     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
+     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
+     */
+    strict?: boolean;
+    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
+    allowedAlgorithms?: string[];
+    /** Whitelist of allowed Key Identifiers (kid). */
+    allowedKids?: string[];
+    /**
+     * Hook invoked whenever decryption fails for an individual field or row.
+     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
+     */
+    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') */
@@ -157,6 +247,56 @@ interface IHKDFFromSecretOptions {
     keyLength?: 128 | 256;
     extractable?: boolean;
 }
+/**
+ * Structured organization access grant for role-based key sharing.
+ */
+interface IAccessGrant {
+    grantId: string;
+    accountId: string;
+    granteeUserId: string;
+    granterUserId: string;
+    wrappedKey: string;
+    expiresAt?: number;
+    permissions?: string[];
+}
+/**
+ * Digitally signed access grant container with granter key fingerprint.
+ */
+interface ISignedGrant {
+    grant: IAccessGrant;
+    signature: string;
+    fingerprint: string;
+}
+/**
+ * Options for verifying access grant validity.
+ */
+interface IVerifyGrantOptions {
+    /** If true, checks whether grant.expiresAt is past the current timestamp */
+    checkExpiry?: boolean;
+    /** Optional reference timestamp for expiration checking (defaults to Date.now()) */
+    now?: number;
+}
+/**
+ * Result container for domain-separated key derivation.
+ */
+interface IDomainDerivedKeys {
+    authKey: CryptoKey;
+    encryptionKey: CryptoKey;
+    salt: string;
+}
+/**
+ * Configuration options for domain-separated key derivation.
+ */
+interface IDeriveAuthAndEncryptionOptions {
+    iterations?: number;
+    hash?: 'SHA-256' | 'SHA-512';
+    authKeyLength?: 128 | 256;
+    encryptionKeyLength?: 128 | 256;
+    authAlgorithm?: 'HMAC' | 'AES-GCM';
+    authInfo?: string;
+    encryptionInfo?: string;
+    extractable?: boolean;
+}
 
 /**
  * types.ts — Framework-agnostic hydration and platform abstraction contracts.
@@ -568,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.
      */
@@ -576,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.
      */
@@ -607,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;
@@ -1544,7 +1699,17 @@ declare function onPlatformReady(cb: () => void): void;
  */
 declare abstract class AEncryptionProvider implements IEncryptionProvider {
     protected defaultKey?: TKeyProvider | IKeyPair;
-    constructor(key?: TKeyProvider | IKeyPair);
+    protected _hmacKey?: TKeyProvider;
+    protected keys?: Record<string, TKeyProvider | IKeyPair>;
+    protected activeKid?: string;
+    protected allowedKids?: string[];
+    constructor(key?: TKeyProvider | IKeyPair, options?: {
+        keys?: Record<string, TKeyProvider | IKeyPair>;
+        activeKid?: string;
+        allowedKids?: string[];
+        hmacKey?: TKeyProvider;
+        [key: string]: any;
+    });
     /**
      * Sets or updates the default secret key, CryptoKey, or async key provider function.
      */
@@ -1553,6 +1718,35 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
      * Retrieves the currently configured default key or key provider callback.
      */
     getDefaultKey(): TKeyProvider | IKeyPair | undefined;
+    /**
+     * Configures a keyring dictionary of keys with an optional active key identifier.
+     */
+    setKeyring(keys: Record<string, TKeyProvider | IKeyPair>, activeKid?: string): void;
+    /**
+     * Retrieves the currently configured keyring dictionary.
+     */
+    getKeyring(): Record<string, TKeyProvider | IKeyPair> | undefined;
+    /**
+     * Sets the active Key Identifier (kid) to use for outbound encryption.
+     */
+    setActiveKid(kid: string): void;
+    /**
+     * 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.
@@ -1593,10 +1787,33 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
      */
     protected _resolveEffectiveAad(options?: IEncryptionContext, isDecrypt?: boolean): string | Uint8Array | ArrayBuffer | undefined;
     /**
-     * Helper to deterministically bind record ID and field name into the AAD
-     * to prevent ciphertext swapping between fields or records.
+     * Helper to deterministically bind record ID, contextual sibling fields (aadFields),
+     * dynamic AAD callbacks, and field name into the AAD to prevent ciphertext swapping
+     * between fields, records, or parent entities.
      */
     protected _bindFieldAad(data: any, field: string, options?: IEncryptionContext): IEncryptionContext;
+    /**
+     * Validates envelope metadata against algorithm whitelists and key identifiers (kid).
+     * In strict mode, allowedAlgorithms defaults to ['AES-GCM'].
+     */
+    protected _validateEnvelopeMetadata(payload: any, options?: IEncryptionContext): Error | undefined;
+    /**
+     * Normalizes encryption options with active keyring parameters:
+     * If `keys` and `activeKid` are configured, selects `key = keys[activeKid]` and sets `kid = activeKid`.
+     */
+    protected _resolveOutboundKeyringOptions(options?: IEncryptionContext): IEncryptionContext;
+    /**
+     * Resolves the appropriate decryption key for a specific payload envelope based on its `kid`
+     * and the configured keyring (`keys`, `activeKid`, or fallback `key`).
+     */
+    protected _resolveDecryptionKeyForEnvelope(payload: any, options?: IEncryptionContext): TKeyProvider | IKeyPair | undefined;
+    /**
+     * Handles a per-field or per-payload decryption error according to configured options:
+     * - Invokes onDecryptError callback if provided
+     * - Attaches error metadata (__decryptErrors) to the record object
+     * - Returns fallback cell placeholder ('[⚠ Decryption Error]') or rethrows
+     */
+    protected _handleDecryptError(err: Error, record: any, field: string, value: any, index: number | undefined, options?: IEncryptionContext): any;
     /**
      * Encrypts a single value (string, object, primitive) into an IEncryptedPayload envelope.
      * Implemented by concrete cryptographic providers.
@@ -1607,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:
@@ -1619,16 +1852,13 @@ declare abstract class AEncryptionProvider implements IEncryptionProvider {
     /**
      * 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.
-     */
-    /**
-     * Top-level polymorphic decryption method.
-     * Automatically performs value-level decryption:
-     * - If payload is an encrypted envelope: decrypts directly via decryptValue.
+     * - If payload is an encrypted envelope: validates metadata and decrypts directly via decryptValue.
      * - If payload is an array of objects: decrypts each row (batched with local memoization).
      * - If payload is an object: decrypts any encrypted value cells across fields.
+     * In strict mode:
+     * - Unencrypted plaintext in configured `fields` triggers a decryption error.
+     * - Envelopes are validated against `allowedAlgorithms` and `allowedKids`.
+     * - Errors are routed through `onDecryptError` or populated into `__decryptErrors`.
      */
     decrypt(payload: any, options?: IEncryptionContext): Promise<any>;
 }
@@ -1701,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.
      */
@@ -1738,6 +1976,26 @@ 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.
+     *
+     * @param wrappedKeyBase64 - The existing ADEK envelope wrapped with current user's public key
+     * @param myPrivateKey - Current user's RSA-OAEP private key
+     * @param recipientPublicKey - New recipient's RSA-OAEP public key
+     * @returns Base64-encoded wrapped key envelope for the recipient
+     */
+    static rewrapAccountKeyForUser(wrappedKeyBase64: string, myPrivateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
     /**
      * Derives a symmetric AES-GCM CryptoKey from a passphrase using PBKDF2 or HKDF.
      * Returns the derived CryptoKey and the base64-encoded salt.
@@ -1751,6 +2009,59 @@ declare class CKeyManager {
      * using HKDF.
      */
     static deriveKeyFromSecret(secretKey: CryptoKey, options?: IHKDFFromSecretOptions): Promise<CryptoKey>;
+    /**
+     * Derives two domain-separated, cryptographically isolated keys from a user password and salt:
+     * 1. `authKey`: For client authentication, SRP, or server challenge proofs.
+     * 2. `encryptionKey`: For AES-GCM local and field-level data encryption.
+     *
+     * Stage 1 (Password Stretching): PBKDF2-HMAC-SHA256 stretches low-entropy password into master secret.
+     * Stage 2 (Domain Expansion): HKDF-Expand derives subkeys using domain-separated context info tags.
+     * Immediate memory zeroization of intermediate master secret buffer is guaranteed.
+     *
+     * @param password - Master user password or passphrase
+     * @param salt - Salt (or omitted to generate a secure random 16-byte salt)
+     * @param options - PBKDF2 and HKDF configuration options
+     */
+    static deriveAuthAndEncryptionKeys(password: string | Uint8Array | ArrayBuffer, salt?: Uint8Array | ArrayBuffer | string, options?: IDeriveAuthAndEncryptionOptions): Promise<IDomainDerivedKeys>;
+    /**
+     * 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>`.
+     */
+    static getKeyFingerprint(publicKey: CryptoKey | Uint8Array | ArrayBuffer | string): Promise<string>;
+    /**
+     * Signs arbitrary data or JSON objects using an ECDSA P-256 private key.
+     * Objects are automatically serialized via canonicalizeJson() before hashing.
+     */
+    static sign(data: any | string | Uint8Array, privateKey: CryptoKey): Promise<string>;
+    /**
+     * 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.
+     */
+    static signGrant(grant: IAccessGrant, granterPrivateKey: CryptoKey, granterPublicKey?: CryptoKey): Promise<ISignedGrant>;
+    /**
+     * Verifies the authenticity and integrity of a signed access grant against granter public key.
+     */
+    static verifyGrant(signedGrant: ISignedGrant, granterPublicKey: CryptoKey, options?: IVerifyGrantOptions): Promise<boolean>;
 }
 
 interface ICWebCryptoOptions {
@@ -1761,6 +2072,10 @@ interface ICWebCryptoOptions {
     info?: string | Uint8Array | ArrayBuffer;
     kid?: string;
     keyId?: string;
+    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).
@@ -1784,6 +2099,7 @@ declare class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     private _cachedKeyId?;
     private _configuredKid?;
     private _decryptSaltCache;
+    private _keyringCache;
     setDefaultKey(key: TKeyProvider): void;
     clearKeys(): void;
     constructor(key?: TKeyProvider | IKeyPair, options?: ICWebCryptoOptions);
@@ -1993,6 +2309,10 @@ interface ICNodeCryptoOptions {
     info?: string | Uint8Array | ArrayBuffer;
     kid?: string;
     keyId?: string;
+    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`.
@@ -2014,6 +2334,8 @@ declare class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     private _cachedHash?;
     private _cachedKeyId?;
     private _configuredKid?;
+    private _keyringCache;
+    private isKeyRetained;
     setDefaultKey(key: TKeyProvider): void;
     clearKeys(): void;
     warmupKey(options?: IEncryptionContext): Promise<void>;
@@ -2115,11 +2437,17 @@ declare function getKeyIdentifier(keyProvider?: any, defaultKey?: any): string;
  * Conforms to W3C Web Cryptography API specification (OperationError) and Node.js crypto error codes.
  */
 declare function isAuthOrDecryptionError(err: any): boolean;
+/**
+ * Serializes a JavaScript value to a deterministic, canonical JSON string conforming to RFC 8785 (JCS).
+ * Guarantees consistent property sorting by UTF-16 code units, omission of undefined/symbol/function values,
+ * standard ECMAScript number formatting (-0 serialized as 0), and detection of circular references.
+ */
+declare function canonicalizeJson(value: any, seen?: Set<any>): string;
 
 /**
  * Universal helper that verifies whether an arbitrary object is a Katlux encrypted payload envelope.
  */
 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, DefaultHydrationAdapter, ECacheStrategy, EDataFilterOperator, EQueueStorage, KatluxIndexedDB, QueueStorageFactory, RequestProvider, RequestProviderRegistry, RequestQueue, SENSITIVE_HEADER_KEYS, applyOperator, buildEncryptionContext, 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, ICNodeCryptoOptions, ICWebCryptoAESCBCOptions, ICWebCryptoOptions, ICacheEntry, ICacheQuotaOptions, ICookieCacheOptions, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IEncryptedPayload, IEncryptionContext, IEncryptionProvider, IFlushOptions, IHKDFFromSecretOptions, IKDFOptions, IKDatatableAction, IKeyPair, IPlatformRouter, IProviderEncryptionOptions, IQueueStorageAdapter, IQueuedOperation, IRequestOptions, ISSRHydrationAdapter, ISearchIndexRowEntry, ISetDataChunkedOptions, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVirtualScrollState, IWrappedKey, KProductItemData, KProductRowAction, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TECDHCurve, TKatluxStore, TKeyProvider, TPageDataHandler, TQueueItemStatus, TRawKey, TTreePageDataHandler, TTreeRow, TUnsubscribe, TreePaginationMode };
+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, 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 };